If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/clauderic/dnd-kit shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 3d ago
• 6 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 91% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live clauderic/dnd-kit repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/clauderic/dnd-kit.

What it runs against: a local clone of clauderic/dnd-kit — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in clauderic/dnd-kit | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 33 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of clauderic/dnd-kit. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/clauderic/dnd-kit.git
#   cd dnd-kit
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of clauderic/dnd-kit and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "clauderic/dnd-kit(\\.git)?\\b" \\
  && ok "origin remote is clauderic/dnd-kit" \\
  || miss "origin remote is not clauderic/dnd-kit (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "packages/core/src/index.ts" \\
  && ok "packages/core/src/index.ts" \\
  || miss "missing critical file: packages/core/src/index.ts"
test -f "packages/dom/src/index.ts" \\
  && ok "packages/dom/src/index.ts" \\
  || miss "missing critical file: packages/dom/src/index.ts"
test -f "packages/react/src/index.ts" \\
  && ok "packages/react/src/index.ts" \\
  || miss "missing critical file: packages/react/src/index.ts"
test -f "packages/sortable/src/index.ts" \\
  && ok "packages/sortable/src/index.ts" \\
  || miss "missing critical file: packages/sortable/src/index.ts"
test -f "apps/docs/astro.config.mjs" \\
  && ok "apps/docs/astro.config.mjs" \\
  || miss "missing critical file: apps/docs/astro.config.mjs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 33 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~3d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/clauderic/dnd-kit"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

@dnd-kit is a framework-agnostic drag-and-drop toolkit that provides a layered architecture: a DOM-agnostic core (@dnd-kit/abstract), a DOM implementation (@dnd-kit/dom), and framework adapters (React, Vue, Svelte, Solid). It solves the problem of building accessible, performant, and customizable drag-and-drop interfaces without vendor lock-in or heavy dependencies, supporting lists, grids, nested contexts, virtualized lists, and variable-sized items out of the box. Monorepo structure with a layered architecture: packages/core contains @dnd-kit/abstract (framework-agnostic logic), packages/dom contains @dnd-kit/dom (DOM bindings), packages/react/vue/svelte/solid contain framework adapters, and apps/docs is an Astro-based documentation site. Documentation lives in MDX (apps/docs/docs/concepts, apps/docs/docs/extend) with interactive examples powered by CodeSandbox integration.

Frontend developers (React, Vue, Svelte, Solid) who need to build drag-and-drop interfaces with accessibility and performance requirements. Specifically: UI component library maintainers, SaaS dashboard builders, sortable list implementers, and game developers building 2D browser games with drag mechanics.

Production-ready and actively maintained. The codebase shows sophisticated TypeScript patterns, comprehensive CI/CD (Chromatic, Playwright tests, automated releases via Changeset), and a well-organized monorepo structure. Recent activity visible in .changeset/ with bug fixes for draggable sensors, drag overlay flicker, and Solid children evaluation—indicating active development and responsiveness to issues.

Low risk for core functionality; the layered architecture isolates framework-specific code. Moderate dependency surface across multiple framework adapters (React 19.2.0, Vue, Svelte, Solid), but the abstract core limits breakage exposure. No obvious single-maintainer risk signals in the file structure, and the Changeset-based release process suggests governance. Main risk: tight coupling between DOM implementation and sensor logic could impact extensibility if collision detection or pointer handling APIs shift.

Recent fixes target draggable sensor deep equality checks, drag overlay flicker reduction, Solid framework children double-evaluation, and sourcemap file inclusion in builds (visible in .changeset/ entries). The Changeset entries suggest a 6-8 week release cycle, and Chromatic workflow indicates visual regression testing is active.

Clone the repo, install with npm: git clone https://github.com/clauderic/dnd-kit.git && cd dnd-kit && npm install. Start the documentation dev server (primary entry point for learning): cd apps/docs && npm run dev --port 3000. To work on core packages: npm run build at the root, then modify files in packages/ and run package-specific tests with npm test (inferred from standard monorepo pattern).

Daily commands: Development: cd apps/docs && npm run dev launches Astro dev server on port 3000 with hot reload. Production build: npm run build (runs OG image generation via scripts/generate-og-image.mjs, then Astro build). Preview production build: npm run preview. Linting: npm run lint or npm run lint:fix.

• packages/core/src/index.ts — Entry point for the framework-agnostic drag-and-drop core—all higher-level packages depend on these abstractions
• packages/dom/src/index.ts — DOM implementation layer that bridges the abstract core to real browser APIs; essential for understanding how events flow
• packages/react/src/index.ts — React adapter providing hooks like useDraggable, useDroppable, and useSortable—primary interface for React users
• packages/sortable/src/index.ts — Sortable list abstraction built on top of core; heavily used pattern showing how to compose the toolkit
• apps/docs/astro.config.mjs — Documentation build configuration and site structure; defines how examples and API docs are generated
• .changeset/config.json — Release and versioning strategy configuration; critical for understanding how packages are published
• packages/core/src/manager/DragDropManager.ts — Central state machine and event coordinator for all drag-drop interactions; the choreographer of the entire system

Create a Custom Collision Detection Algorithm

1. Create a new file in packages/core/src/collisionDetection/ (e.g. customCollisionDetection.ts) (packages/core/src/collisionDetection.ts)
2. Export the function from packages/core/src/index.ts (packages/core/src/index.ts)
3. Pass it to DndContext's collisionDetection prop in your React app (packages/react/src/index.ts)
4. Document with example in apps/docs/docs/extend/plugins.mdx (apps/docs/docs/extend/plugins.mdx)

Build a Custom Input Sensor

1. Create a sensor class in packages/core/src/sensors/YourSensor.ts implementing the Sensor interface (packages/core/src/sensors/PointerSensor.ts)
2. Export from packages/core/src/index.ts (packages/core/src/index.ts)
3. Pass to DndContext's sensors prop (packages/react/src/index.ts)
4. Add documentation in apps/docs/docs/extend/sensors.mdx with code example (apps/docs/docs/extend/sensors.mdx)

Add a New Framework Adapter

1. Create packages/framework-name/src/index.ts exposing equivalent hooks (e.g., useDraggable, useDroppable) (packages/react/src/index.ts)
2. Implement context provider and lifecycle hooks using the framework's API (packages/react/src/hooks/useDraggable.ts)
3. Import and wrap the core DragDropManager from packages/core (packages/core/src/manager/DragDropManager.ts)
4. Create package.json with dependencies on @dnd-kit/core and @dnd-kit/dom (packages/react/src/index.ts)

Add a New Example to Documentation

1. Create a React component in apps/docs (inferred from structure) with useDraggable/useDroppable hooks (packages/react/src/index.ts)
2. Create a new .mdx file in apps/docs/docs/concepts/ or apps/docs/docs/extend/ (apps/docs/docs/concepts/drag-drop-manager.mdx)
3. Embed the component via CodeSandbox integration or inline code blocks (apps/docs/astro.config.mjs)

• TypeScript — Enables type-safe abstractions across framework boundaries and prevents runtime errors in complex drag-drop state
• Layered architecture (abstract → DOM → framework) — Allows core logic to be framework-agnostic while supporting multiple frameworks (React, Svelte, Solid, Vue) with minimal duplication
• Sensor pattern for input handling — Decouples drag initiation logic from specific input methods, making it easy to add custom sensors without modifying core
• Monorepo (pnpm workspaces inferred) — Simplifies dependency management across tightly-coupled packages (@dnd-kit/core, @dnd-kit/dom, @dnd-kit/react, etc.)
• Astro for documentation — Zero-JS-by-default static site with React island support for interactive examples; fast docs, minimal overhead
• Collision detection algorithms as pluggable functions — Enables use-case-specific drop detection (e.g., closest-center for lists, shape-intersection for spatial layouts)

• Framework-agnostic core + thin adapters vs. direct React library

  • Why: Maximizes code reuse and enables Svelte/Solid/Vue support; increases initial complexity
  • Consequence: Developers must understand 2–3 layers; more files to trace, but eliminates framework lock-in

• Client-side only; no server-side state synchronization

  • Why: Simplifies architecture for UI-centric use cases; reduces latency on drag feedback
  • Consequence: Real-time collaboration requires external sync; unsuitable for multi-user live editing without custom backend

• Pluggable collision detection rather than one built-in algorithm

  • Why: Supports diverse layouts (lists, grids, 2D games, Kanban); one algorithm cannot fit all shapes
  • Consequence: Developers must choose/implement collision logic; more decisions upfront

• CSS-based transforms for animations rather than requestAnimationFrame loop

  • Why: Leverages GPU acceleration; browser paint optimizations; minimal JS blocking
  • Consequence: Limited control over sub-frame animation timing; cannot easily hook into frame-by

No obvious environment variable requirements in .changeset or package.json, but apps/docs/.env.example suggests optional config (check it for secrets/API keys if builds fail). The OG image generation script (scripts/generate-og-image.mjs) requires @resvg/resvg-js and runs during build—if you're on M1 Mac or uncommon OS, this may fail; use npm run astro build to skip it and test docs-only builds. Node version pinned in .nvmrc—use the exact version to avoid install mismatches. Prettier config is shared across root and apps/ (check .prettierrc and apps/docs/.prettierrc for conflicts if formatting behaves oddly).

• Sensor Pattern — Sensors (pointer, keyboard, touch) are the input abstraction layer in dnd-kit; understanding how they detect and emit drag events is essential to extending or customizing input handling
• Collision Detection Algorithms — dnd-kit supports pluggable collision detection (rectangle, closest corners, center, etc.); choosing or implementing the right algorithm determines drop target accuracy for complex layouts
• Modifiers (Transform Pipeline) — Modifiers allow declarative transformation of drag coordinates before rendering (snap to grid, restrict to axis, etc.); they compose to create complex drag behaviors without branching logic
• Layered Architecture (Abstract → DOM → Framework) — dnd-kit's core innovation: separating framework-agnostic logic (@dnd-kit/abstract) from DOM bindings (@dnd-kit/dom) from framework adapters (React/Vue/Svelte/Solid) allows reuse and reduces duplication
• Drag Overlay Pattern — The DragOverlay component renders dragged items outside normal flow to avoid layout thrashing; understanding portal rendering and transform-based positioning is critical for performance
• Live Regions and ARIA — dnd-kit bakes in accessibility (aria-roledescription, live regions for screen readers); this is non-obvious in drag-drop UX and critical for inclusive design
• Virtual Scrolling with Drag-Drop — Virtualized lists (rendering only visible items) conflict with drag detection; dnd-kit handles this via observer patterns and scroll-aware collision detection

• atlassian/react-beautiful-dnd — Predecessor and alternative React drag-and-drop library; dnd-kit was built to address its limitations (performance, bundle size, accessibility)
• SortableJS/Sortable — Vanilla JS sortable library covering lists and grids; dnd-kit is a modern, typed, multi-framework alternative with better extensibility
• solid-dnd/solid-dnd — Solid-specific drag-and-drop library; dnd-kit's Solid adapter provides framework-agnostic equivalent with more features
• angular/material — Angular Material's CDK drag-drop module; competitors in the same space for Angular developers seeking batteries-included solutions
• reduxjs/redux — Related as dnd-kit examples often pair with Redux for state management; Zustand (used in docs site) is a lighter alternative

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add end-to-end tests for Astro documentation build and deployment

The repo has a Playwright workflow (.github/workflows/playwright.yml) but the docs app (apps/docs) uses Astro with complex dependencies (@mintlify/astro, @codesandbox/sandpack-react, AI SDK integration). There are no E2E tests verifying the docs site builds correctly, interactive components render properly, and the OG image generation script (scripts/generate-og-image.mjs) succeeds. This is critical since the docs are the primary user touchpoint.

• [ ] Add new test file apps/docs/tests/build.spec.ts to verify astro build completes without errors
• [ ] Add test for OG image generation script execution and output validation
• [ ] Add test for Sandpack code examples rendering and sandboxing functionality
• [ ] Extend .github/workflows/playwright.yml to run these build/E2E tests on PR
• [ ] Document test setup in apps/docs/README.md if it exists

Add unit tests for docs-specific utilities and helper scripts

The docs app has scripts/generate-og-image.mjs and scripts/diff-screenshots.mjs but there are no tests verifying these work correctly. Given the complexity of image generation (using satori and @resvg/resvg-js), failures in production could break the build. Contributors should add unit tests to prevent regressions.

• [ ] Create apps/docs/tests/scripts/generate-og-image.test.mjs with test cases for valid/invalid frontmatter, image dimensions, and file output
• [ ] Create apps/docs/tests/scripts/diff-screenshots.test.mjs with test cases for image comparison logic
• [ ] Add test fixtures (sample markdown files with frontmatter, sample images) to apps/docs/tests/fixtures/
• [ ] Update package.json scripts to include 'test' command running these tests
• [ ] Document script behavior and test coverage in apps/docs/scripts/README.md

Document and test the AI-powered features in the docs (Mintlify + AI SDK integration)

The docs package includes @ai-sdk/react and ai dependencies, suggesting AI-powered search or assistance features exist, but there's no documentation in apps/docs/docs/ explaining how to use these features or configure them. This leaves contributors unable to understand, maintain, or extend AI functionality. Clear documentation with example usage patterns would be valuable.

• [ ] Create apps/docs/docs/features/ai-assistance.mdx documenting the AI-powered features (search, Q&A, etc.)
• [ ] Document required environment variables (check .env.example for clues) and configuration in the MDX file
• [ ] Create example React component in apps/docs/src/components/AIAssistance.tsx showing how to integrate AI features
• [ ] Add tests in apps/docs/tests/components/AIAssistance.test.tsx for the component
• [ ] Update CONTRIBUTING.md with instructions for setting up AI features locally for development

• Add unit tests for sensor deep equality check (mentioned in .changeset/fix-draggable-sensors-deep-equal.md)—find the sensor comparison logic in packages/dom/src and write tests to cover the regression case.
• Expand keyboard accessibility docs in apps/docs/docs/extend/sensors/keyboard-sensor.mdx—currently sparse; add concrete examples of custom key bindings and screen reader behavior with real code snippets.
• Create a 'Troubleshooting' page under apps/docs/docs/ to document the drag overlay flicker issue (.changeset/fix-dragoverlay-flicker.md) and other known gotchas—help users debug common DX issues.

• High · AI SDK Integration Without Input Validation — apps/docs/package.json - @ai-sdk/react, ai dependencies. The codebase includes @ai-sdk/react and ai packages for AI functionality. Without visible input validation and sanitization mechanisms in the file structure, there is a risk of prompt injection attacks where user inputs could be sent directly to LLM endpoints, potentially causing unauthorized actions or information leakage. Fix: Implement strict input validation and sanitization for all user inputs before sending to AI services. Use parameterized prompts, implement rate limiting, and add content security policies. Add monitoring for suspicious AI API usage patterns.
• High · Code Sandbox Integration Without Isolation — apps/docs/package.json - @codesandbox/sandpack-react dependency. The @codesandbox/sandpack-react dependency enables code execution in the documentation. This presents a significant XSS and arbitrary code execution risk if user-provided code snippets are not properly sandboxed and validated. Fix: Ensure sandpack-react is configured with proper iframe sandboxing attributes (sandbox attribute with minimal permissions). Validate and sanitize all code snippets before rendering. Implement Content Security Policy (CSP) headers to restrict script execution.
• High · React Markdown Without XSS Protection — apps/docs/package.json - react-markdown dependency. The react-markdown library is used without visible configuration. If markdown content comes from untrusted sources or user input, it could contain malicious HTML/JavaScript leading to XSS attacks. Fix: Configure react-markdown with allowedElements/disallowedElements to only allow safe markdown elements. Use rehype-sanitize or similar to sanitize HTML. Never render user-generated markdown content without sanitization.
• Medium · Missing Environment Variable Validation — apps/docs/.env.example. The .env.example file exists but there is no visible validation mechanism for required environment variables in the codebase. This could lead to misconfiguration in production if critical variables are missing or improperly set. Fix: Implement environment variable validation on application startup. Create a schema (using zod, joi, or similar) that validates all required and optional environment variables with their expected types and formats.
• Medium · Potential Information Disclosure via Satori/OG Image Generation — apps/docs/package.json - @resvg/resvg-js, satori dependencies; apps/docs/scripts/generate-og-image.mjs. The @resvg/resvg-js and satori packages are used for OG image generation. If user-controlled data is included in generated images without sanitization, it could leak sensitive information or be used for phishing. Fix: Sanitize all user-controlled data before including in OG image generation. Limit what metadata/content can be included in dynamically generated images. Implement input validation and length limits.
• Medium · Build Script Security — apps/docs/scripts/generate-og-image.mjs, apps/docs/scripts/diff-screenshots.mjs. The build script runs node scripts that generate OG images and perform screenshot comparisons. These scripts could be injection vectors if they process untrusted data or use unsanitized shell commands. Fix: Review scripts for command injection vulnerabilities. Use safe APIs (child_process.execFile instead of shell=true). Validate all inputs to these scripts. Consider removing screenshot diff functionality from production builds.
• Low · Outdated or Unverified Dependencies — apps/docs/package.json - all dependencies. Several dependencies lack pinned versions (^, ~) or have not been verified for known vulnerabilities. Regular security audits are not evident in the configuration. Fix: Run npm audit regularly and address findings. Consider using npm audit automation in CI/CD. Pin critical security-sensitive dependencies to exact versions. Add dependency scanning tools like Snyk or Dependabot.
• Low · Missing Security Headers Configuration — apps/docs/astro.config.mjs. No visible security header configuration (CSP, X-Frame-Options, X-Content-Type-Options, etc.) in the provided Astro configuration or files. Fix: Add security headers to astro.config.mjs. Implement Content Security Policy, X-Frame-Options: DENY, X-

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.