V11 working

.codesandbox/ci.json

@@ -1,5 +1,5 @@
 {
   "sandboxes": ["4nc1u", "bfplr", "1wh6f"],
   "packages": ["dist"],
-  "node": "20"
+  "node": "22"
 }

.cursor/plans/jsdoc_from_clean_docs_60011536.plan.md

@@ -0,0 +1,106 @@
+---
+name: JSDoc from Clean Docs
+overview: Process all components to extract documentation from `docs-original/`, write JSDoc to source files, and create `.docs.mdx` templates for rich content that can't be expressed in JSDoc.
+todos:
+  - id: batch-1
+    content: Process Abstractions category (~15 components)
+    status: completed
+  - id: batch-2
+    content: Process Controls category (~15 components)
+    status: completed
+    dependencies:
+      - batch-1
+  - id: batch-3
+    content: Process Cameras category (~5 components)
+    status: completed
+    dependencies:
+      - batch-2
+  - id: batch-4
+    content: Process Geometry category (~15 components)
+    status: completed
+    dependencies:
+      - batch-3
+  - id: batch-5
+    content: Process Staging category (~20 components)
+    status: in_progress
+    dependencies:
+      - batch-4
+  - id: batch-6
+    content: Process Loaders category (~15 components)
+    status: pending
+    dependencies:
+      - batch-5
+  - id: batch-7
+    content: Process Misc categories (~20 components)
+    status: pending
+    dependencies:
+      - batch-6
+  - id: validate
+    content: Run docs:generate and compare output with docs-original
+    status: pending
+    dependencies:
+      - batch-7
+---
+
+# Regener
+
+ate JSDoc from Clean Documentation Source
+
+## Strategy
+
+For each component with docs in `docs-original/`:
+
+1. **Extract from original docs:**
+
+- Description text
+- Code examples
+- Prop documentation (if inline in docs)
+
+2. **Write to source `.tsx` file:**
+
+- Component JSDoc with description and `@example` blocks
+- Prop JSDoc comments on the Props type
+
+3. **Create `.docs.mdx` template** (only if rich content exists):
+
+- Use `{/* AUTO:badges */}`, `{/* AUTO:description */}`, `{/* AUTO:example */}` for auto-generated parts
+- Preserve Codesandbox embeds, Grid layouts, and custom hand-written sections
+
+```javascript
+docs-original/clone.mdx          (read)
+        │
+        ├──► src/.../Clone.tsx   (write JSDoc)
+        │
+        └──► src/.../Clone.docs.mdx  (create template if rich content)
+```
+
+## Implementation Batches
+
+Process components by category to maintain focus:| Batch | Category | Est. Components ||-------|----------|-----------------|| 1 | Abstractions | ~15 || 2 | Controls | ~15 || 3 | Cameras | ~5 || 4 | Geometry (Gizmos, Shapes) | ~15 || 5 | Staging | ~20 || 6 | Loaders | ~15 || 7 | Misc (Helpers, Shaders, Performance) | ~20 |
+
+## Key Files
+
+- **Source docs:** `docs-original/` (preserved backup)
+- **Source files:** `src/core/*/` and `src/external/*/`
+- **Config:** [scripts/docs-config.ts](scripts/docs-config.ts)
+- **Generator:** [scripts/generate-docs.ts](scripts/generate-docs.ts)
+- **Reference:** [docs/development/DOCS_GENERATION.md](docs/development/DOCS_GENERATION.md)
+
+## Workflow Per Component
+
+1. Read `docs-original/{category}/{component}.mdx`
+2. Parse content:
+
+- Extract description (first paragraph after frontmatter)
+- Extract code blocks as examples
+- Identify rich content (Codesandbox, Grid, custom sections)
+
+3. Update `src/{tier}/{Category}/{Component}/{Component}.tsx`:
+
+- Add/update JSDoc above export
+- Add/update prop comments on Props type
+
+4. If rich content exists, create `{Component}.docs.mdx` template with injection tags
+5. Run `yarn docs:generate` after each batch to verify
+
+## Validation

.github/PULL_REQUEST_TEMPLATE.md

@@ -25,7 +25,7 @@ To check an item, place an "x" in the box like so: "- [x] Documentation"
 Remove items that are irrelevant to your changes.
 -->
 
-- [ ] Documentation updated ([example](https://github.com/pmndrs/drei/blob/master/docs/misc/example.mdx?plain=1))
+- [ ] Documentation updated ([example](https://github.com/pmndrs/drei/blob/master/docs/helpers/example.mdx?plain=1))
 - [ ] Storybook entry added ([example](https://github.com/pmndrs/drei/blob/master/.storybook/stories/Example.stories.tsx))
 - [ ] Ready to be merged
 

.github/workflows/docs.yml

@@ -1,37 +1,110 @@
 name: Build documentation and deploy to GitHub Pages
+
 on:
   push:
     branches: ['master']
   workflow_dispatch:
 
-# Cancel previous run (see: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#concurrency)
+# Cancel previous run
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
 jobs:
   build:
-    uses: pmndrs/docs/.github/workflows/build.yml@v2
-    with:
-      mdx: 'docs'
-      libname: 'Drei'
-      libname_short: 'drei'
-      home_redirect: '/getting-started/introduction'
-      icon: '🥉'
-      logo: '/logo.jpg'
-      github: 'https://github.com/pmndrs/drei'
-      discord: 'https://discord.com/channels/740090768164651008/741751532592038022'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      #* Generate docs from TSDoc ==============================
+      - run: corepack enable
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.node-version'
+          cache: 'yarn'
+      - run: yarn install
+      - name: Generate documentation from TSDoc
+        run: yarn docs:generate --no-backup
+
+      #* Build docs site (replicated from pmndrs/docs workflow) ==============================
+      - id: configurepages
+        uses: actions/configure-pages@v5
+        with:
+          enablement: true
+
+      - id: set-base-path
+        run: echo "BASE_PATH=${{ steps.configurepages.outputs.base_path }}" >> "$GITHUB_OUTPUT"
+
+      - name: Build docs site
+        run: |
+          set -ex
+          docker run --rm --init \
+            -v "./docs":/app/docs \
+            -e BASE_PATH \
+            -e DIST_DIR="docs/out$BASE_PATH" \
+            -e MDX \
+            -e NEXT_PUBLIC_LIBNAME \
+            -e NEXT_PUBLIC_LIBNAME_SHORT \
+            -e NEXT_PUBLIC_LIBNAME_DOTSUFFIX_LABEL \
+            -e NEXT_PUBLIC_LIBNAME_DOTSUFFIX_HREF \
+            -e OUTPUT=export \
+            -e HOME_REDIRECT \
+            -e MDX_BASEURL \
+            -e SOURCECODE_BASEURL \
+            -e EDIT_BASEURL \
+            -e NEXT_PUBLIC_URL \
+            -e ICON \
+            -e LOGO \
+            -e GITHUB \
+            -e DISCORD \
+            -e THEME_PRIMARY \
+            -e THEME_SCHEME \
+            -e THEME_CONTRAST \
+            -e THEME_NOTE \
+            -e THEME_TIP \
+            -e THEME_IMPORTANT \
+            -e THEME_WARNING \
+            -e THEME_CAUTION \
+            -e CONTRIBUTORS_PAT \
+            ghcr.io/pmndrs/docs:2 npm run build
+        env:
+          BASE_PATH: ${{ steps.set-base-path.outputs.BASE_PATH }}
+          MDX: docs
+          NEXT_PUBLIC_LIBNAME: Drei
+          NEXT_PUBLIC_LIBNAME_SHORT: drei
+          NEXT_PUBLIC_LIBNAME_DOTSUFFIX_LABEL: docs
+          NEXT_PUBLIC_LIBNAME_DOTSUFFIX_HREF: https://docs.pmnd.rs
+          HOME_REDIRECT: /getting-started/introduction
+          MDX_BASEURL: 'https://github.com/${{ github.repository }}/raw/${{ github.ref_name }}/docs'
+          SOURCECODE_BASEURL: 'https://github.com/${{ github.repository }}/tree/${{ github.ref_name }}'
+          EDIT_BASEURL: 'https://github.com/${{ github.repository }}/edit/${{ github.ref_name }}/docs'
+          NEXT_PUBLIC_URL: ${{ steps.configurepages.outputs.base_url }}
+          ICON: '🥉'
+          LOGO: '/logo.jpg'
+          GITHUB: 'https://github.com/pmndrs/drei'
+          DISCORD: 'https://discord.com/channels/740090768164651008/741751532592038022'
+          THEME_PRIMARY: '#323e48'
+          THEME_SCHEME: tonalSpot
+          THEME_CONTRAST: '0'
+          THEME_NOTE: '#1f6feb'
+          THEME_TIP: '#238636'
+          THEME_IMPORTANT: '#8957e5'
+          THEME_WARNING: '#d29922'
+          THEME_CAUTION: '#da3633'
+          CONTRIBUTORS_PAT: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/out${{ steps.set-base-path.outputs.BASE_PATH }}
 
   deploy:
     needs: build
     runs-on: ubuntu-latest
 
-    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
     permissions:
-      pages: write # to deploy to Pages
-      id-token: write # to verify the deployment originates from an appropriate source
+      pages: write
+      id-token: write
 
-    # Deploy to the github-pages environment
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}

.github/workflows/release.yml

@@ -9,52 +9,98 @@ on:
       - 'rc'
   pull_request: {}
 
+permissions:
+  contents: write
+  id-token: write
+
 # Cancel any previous run (see: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#concurrency)
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
 jobs:
+  #* Static Analysis ==============================
+  # Lint, typecheck, formatting - fast checks that don't need build
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: corepack enable
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.node-version'
+          cache: 'yarn'
+      - run: yarn install
+      - run: yarn test:lint
+
+  #* Build & Test ==============================
+  # Build the package and run all tests
   test:
     runs-on: ubuntu-latest
-    container:
-      image: ghcr.io/pmndrs/playwright:drei
-      credentials:
-        username: ${{ github.actor }}
-        password: ${{ secrets.GITHUB_TOKEN }}
+    steps:
+      - uses: actions/checkout@v4
+      - run: corepack enable
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.node-version'
+          cache: 'yarn'
+      - run: yarn install
+      - run: yarn build
+
+      # Bundle verification - ensures THREE imports are correct per entry point
+      - name: Verify bundle structure
+        run: yarn test:bundles
 
-    # 0.159.0 is mandatory; others are informational
-    strategy:
-      fail-fast: false
-      matrix:
-        three-version: ['0.159.0', '0.180.0', 'latest']
-    continue-on-error: ${{ matrix.three-version != '0.159.0' }}
-    name: test (w/ three@${{ matrix['three-version'] }})
+      # Canary tests - verifies exports are importable
+      - name: Canary import tests
+        run: yarn test:canary
 
+  #* Build Storybook & Parity Tests ==============================
+  storybook:
+    needs: [lint, test]
+    runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - run: corepack enable
       - uses: actions/setup-node@v4
         with:
+          node-version-file: '.node-version'
           cache: 'yarn'
       - run: yarn install
       - run: yarn build
-      - run: yarn eslint:ci
-      - run: yarn typecheck
-      - run: yarn prettier
-      - run: (cd test/e2e; ./e2e.sh ${{ matrix.three-version }})
-      - name: Upload Playwright screenshots
-        if: always()
+      - run: yarn build-storybook
+
+      # Install Playwright browsers for parity tests
+      - name: Install Playwright browsers
+        run: npx playwright install chromium
+
+      # Platform parity tests - compare Legacy vs WebGPU renders
+      - name: Run parity tests
+        id: parity
+        run: yarn test:parity
+        continue-on-error: true
+
+      # Upload diff images on failure for debugging
+      - name: Upload parity diff images
+        if: steps.parity.outcome == 'failure'
+        uses: actions/upload-artifact@v4
+        with:
+          name: parity-diffs
+          path: test-results/parity/
+          retention-days: 7
+
+      # Upload Playwright HTML report for interactive viewing
+      - name: Upload Playwright report
+        if: steps.parity.outcome == 'failure'
         uses: actions/upload-artifact@v4
         with:
-          name: playwright-screenshots-${{ matrix.three-version }}
-          path: |
-            test-results/**
-          if-no-files-found: ignore
+          name: parity-report
+          path: playwright-report/
           retention-days: 7
 
-  build-and-release:
-    needs: test
+  #* Release ==============================
+  release:
+    needs: [lint, test, storybook]
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -65,8 +111,8 @@ jobs:
           cache: 'yarn'
       - run: yarn install
       - run: yarn build
-      - run: yarn build-storybook
-      # semantic-release skips not configured branches(see: release.config.js) or pull-requests
+
+      # semantic-release skips not configured branches (see: release.config.js) or pull-requests
       - run: yarn release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}