Promote develop to main

.claude/settings.local.json

@@ -1,3 +1,6 @@
 {
-  "enabledMcpjsonServers": ["threenative-assets", "threenative-sculpt", "threenative-engine"]
+  "enabledMcpjsonServers": ["threenative-assets", "threenative-sculpt", "threenative-engine"],
+  "permissions": {
+    "allow": ["Bash(cd *)"]
+  }
 }

.claude/skills/build-on-sandbox/SKILL.md

@@ -95,6 +95,9 @@ preference; it is the difference between the two outcomes.
    result matches, and the committed ledger path. The comparison and the friction record
    are the point of the exercise.
 
+For performance work, use the existing stress scene instead of a new game:
+[stress-scene.md](stress-scene.md) says where it is, what it loads, and how to measure it.
+
 ## Rules
 
 - **Work only inside your game folder.** `../sandbox/<name>/` is yours; the sandbox root and

.claude/skills/build-on-sandbox/stress-scene.md

@@ -0,0 +1,56 @@
+# The stress scene (performance loop)
+
+The stress lab is a sandbox game whose second scene loads the engine to its limit with a realistic
+open-world mix. It is not a game to play. It is the fixed bench for the inspect, fix, measure loop.
+
+## Where it is
+
+- Game folder: `../sandbox/stress-lab/`, a starter-kit sandbox game. The sandbox folder is its own git
+  repository: commit scene changes there.
+- Scene: `src/scenes/Stress.ts`. Report: `src/stressReport.ts`. Look: `src/render/stress.ts`.
+- Open it with `main.html?stress` (natively: `TN_DEBUG_STRESS=1`). Without `?stress` the starter course
+  opens, so the kit's own playtests still prove it.
+
+## What it loads
+
+The `real` preset: 4000 trees, 6000 rocks, 120 houses, 600 props, 120 animated rigs, 300 physics
+bodies, 12 fires of 1500 particles, 16 lights, virtual shadow maps, and the engine's default look.
+The camera orbits the town (radius 70 m, one turn in 40 s).
+
+| URL flag | Effect |
+| --- | --- |
+| `&max` | the `max` preset (2.5 to 3 times the `real` counts) |
+| `&noTrees`, `&noRocks`, `&noHouses`, `&noProps`, `&noCrowd`, `&noBodies`, `&noFires`, `&noLights` | removes one layer, to price it |
+| `&plainShadow` | regular shadow maps instead of virtual shadow maps |
+| `&adaptive` | the adaptive quality tier instead of `high` |
+| `&still` | stops the orbit and the walkers |
+| `&closeup` | frames a sunlit walker, for shadow judging |
+| `&freezeAt=<s>` | holds the orbit at second `<s>` after a real pan |
+
+## Put the latest engine in it
+
+1. Build the packages you changed (`pnpm --filter <package> build`).
+2. Copy the built files into `node_modules/` of the game folder, or make a fresh sandbox with
+   `pnpm sandbox --genre <genre> --name <name>` and copy `src/` across.
+3. Move `node_modules/.vite` aside and restart Vite, or the browser keeps the old prebundle.
+
+## Measure
+
+1. Open `main.html?stress` in real Chrome through the Chrome DevTools MCP, with the cache ignored.
+   Read `adapter.info`: `swiftshader` means the numbers are not GPU numbers.
+2. Wait 75 s. Startup, shader compiles and the world build are not stress.
+3. Read `globalThis.__TN_STRESS__`: fps, frame, render, update and GPU p50, frame p95, presented p95,
+   JS-Wasm crossings and long tasks.
+4. Record every run: `pnpm stress:loop record <report.json> --label "<change>" --decision keep|reject`.
+   The dashboard's Stress lab tab draws `docs/stress-loop/ledger.json`.
+
+## Compare two engines
+
+- Alternate the arms in one quiet window (A, B, B, A) with two or more runs per arm. Noise is about
+  ±7% between sessions and ±3% inside one. Compare render p50 and frame p95, not fps from different
+  sessions.
+- Keep a change only on a paired gain. A count that falls (draws, crossings) is not a gain until frame
+  time falls with it.
+- A change that can move pixels needs the visual judge from the repo's `AGENTS.md`. Capture the same
+  orbit time on both arms.
+- Fix the engine in `packages/`, never the scene: the gain must reach every game.

.github/actions/playwright-chromium/action.yml

@@ -24,12 +24,13 @@ runs:
           [ ! -f "$source" ] || sudo sed -i 's|http://azure.archive.ubuntu.com/ubuntu|https://archive.ubuntu.com/ubuntu|g; s|https://azure.archive.ubuntu.com/ubuntu|https://archive.ubuntu.com/ubuntu|g' "$source"
         done
     # The browser binary caches; its shared libraries are apt packages that do not, so
-    # `--with-deps` still runs. On a cache hit that is the only work left.
+    # `install-deps` still runs. On a cache hit that is the only work left.
+    # It takes 11-114 s; a mirror that trickles held it 29 minutes (run 41249368283), so each
+    # attempt is cut at 240 s and retried. Root runs the timeout, so it can kill apt's fetchers.
     - name: Install Chromium and its system dependencies
       shell: bash
       run: |
-        if [ "${{ steps.cache.outputs.cache-hit }}" = "true" ]; then
-          pnpm exec playwright install-deps chromium
-        else
-          pnpm exec playwright install --with-deps chromium
+        if [ "${{ steps.cache.outputs.cache-hit }}" != "true" ]; then
+          pnpm exec playwright install chromium
         fi
+        sh scripts/retry-download.sh sudo timeout --kill-after=15 240 env "PATH=$PATH" node_modules/.bin/playwright install-deps chromium

.github/actions/scaffold-from-tarballs/action.yml

@@ -42,7 +42,6 @@ runs:
           case "$package_name" in
             create-threenative) package_flag="--cli-package" ;;
             threenative-animation-mcp) package_flag="--animation-mcp-package" ;;
-            threenative-blender-mcp) package_flag="--blender-mcp-package" ;;
             threenative-engine-mcp) package_flag="--engine-mcp-package" ;;
             @threenative/*) package_flag="--threenative-${package_name#@threenative/}-package" ;;
             *) echo "unsupported workspace package $package_name"; exit 1 ;;

.github/workflows/ci.yml

@@ -929,8 +929,7 @@ jobs:
           # in, or this lane would quietly stop covering 21 scenarios it has always covered.
           extras="$GITHUB_WORKSPACE/packages/create-threenative/template-playtests/${{ matrix.template }}"
           if [ -d "$extras" ]; then cp -r "$extras/." "$target/playtests/"; fi
-          # PRD-748: the engine-cost contract row runs on every PR, for every kit that does not opt out.
-          pnpm exec tsx scripts/kit-contract-row.ts engine-cost "${{ matrix.template }}" "$target/playtests"
+          # The PRD-748 engine-cost row runs in `template-engine-cost`, beside this leg.
           scenario_list=$(node "$GITHUB_WORKSPACE/scripts/non-visual-scenarios.mjs" "$target")
           mapfile -t scenarios <<< "$scenario_list"
           test "${#scenarios[@]}" -gt 0
@@ -971,6 +970,72 @@ jobs:
           pnpm --dir "$target" exec threenative build --target web
           test -s "$target/dist/index.html"
 
+  # PRD-748's engine-cost contract row, every PR, per kit. It draws all 1260 ticks one by one for
+  # its four counter windows, and on hosted SwiftShader that alone took 14m51s (run 41170629638,
+  # adventure): inside a kit's 30-minute `template-nonvisual` leg it cancelled adventure and
+  # collectathon. It runs here in parallel, with the same scenario, bounds and ticks. A kit that
+  # opts out prints its reason and passes; `ci-required` gates this job like any other.
+  template-engine-cost:
+    needs: [scope, build-artifacts]
+    if: ${{ (needs.scope.outputs.selection == 'full' || needs.scope.outputs.selection == 'template') }}
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJSON(needs.scope.outputs.plan).templateMatrix }}
+    runs-on: ${{ (github.event.pull_request.head.repo.fork || !vars.TN_RUNNER || !contains(fromJSON(needs.scope.outputs.runner_admission || '[]'), format('ci:template-engine-cost:{0}', matrix.template))) && 'ubuntu-24.04' || vars.TN_RUNNER }}
+    # 45, owner-approved for this job only (2026-10-31): on 813c0166a the row step alone ran
+    # 964-1775+ s on hosted SwiftShader (VM speed spread 1.75x, 99% raster hostGap), and rain,
+    # adventure (twice) and shooter hit 30. Ticks, windows, bounds and every threshold are unchanged.
+    timeout-minutes: 45
+    env:
+      TN_CI_SHA: ${{ needs.scope.outputs.candidate_sha }}
+      TN_PLAYTEST_ALLOW_SOFTWARE: "1"
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ needs.scope.outputs.candidate_sha || github.sha }}
+      - uses: ./.github/actions/pnpm
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 20
+          cache: pnpm
+          cache-dependency-path: |
+            pnpm-lock.yaml
+            packages/create-threenative/templates/*/package.json
+      - run: pnpm install --frozen-lockfile
+      # Before the row: its writer imports create-threenative, which needs this artifact's packages/*/dist.
+      - name: Take the packed workspace from build
+        uses: actions/download-artifact@v4
+        with:
+          name: workspace-packages
+      - name: Write the kit's engine-cost row
+        id: row
+        run: |
+          set -euo pipefail
+          mkdir -p "$RUNNER_TEMP/engine-cost-row"
+          pnpm exec tsx scripts/kit-contract-row.ts engine-cost "${{ matrix.template }}" "$RUNNER_TEMP/engine-cost-row"
+          if [ -f "$RUNNER_TEMP/engine-cost-row/contract-engine-cost.playtest.json" ]; then echo "applies=true" >> "$GITHUB_OUTPUT"; fi
+      - name: Scaffold the template from local tarballs
+        if: steps.row.outputs.applies == 'true'
+        uses: ./.github/actions/scaffold-from-tarballs
+        with:
+          archives-directory: ${{ github.workspace }}/artifacts/workspace-packages
+          specs-file: ${{ github.workspace }}/artifacts/workspace-packages/specs
+          target: ${{ runner.temp }}/threenative-${{ matrix.template }}
+          template: ${{ matrix.template }}
+      - uses: ./.github/actions/playwright-chromium
+        if: steps.row.outputs.applies == 'true'
+      - name: Run the engine-cost row
+        if: steps.row.outputs.applies == 'true'
+        run: |
+          set -euo pipefail
+          target="$RUNNER_TEMP/threenative-${{ matrix.template }}"
+          pnpm --dir "$target" install
+          cp "$RUNNER_TEMP/engine-cost-row/contract-engine-cost.playtest.json" "$target/playtests/"
+          # `--server-timeout` as in template-nonvisual: the first asset cook holds the dev port.
+          pnpm --dir "$target" exec threenative-playtest --scenario playtests/contract-engine-cost.playtest.json \
+            --browser-recipe webgpu --headed --no-screenshots --server-timeout 120000 \
+            --server-command "pnpm dev --host 127.0.0.1 --port \$PORT --strictPort"
+
   # `golden-path` is a required status check in the `main protection` ruleset, and required checks
   # match the reported context by exact string. A matrix job does not report its own name — it
   # reports `golden-path (starter)` and `golden-path (platformer)` — so the moment this lane became
@@ -1491,7 +1556,7 @@ jobs:
   # The only required context after protected-develop cutover. Explicit exemptions are not passes.
   # Legacy main contexts stay in place until the owner changes protection after full qualification.
   ci-required:
-    needs: [scope, integration, native-platforms, native-engine, typecheck, lint, test, test-unit, test-native, test-browser, test-playtest, golden-path-template, template-nonvisual, golden-path, benchmark, build, build-artifacts, budgets, performance-contracts, supply-chain]
+    needs: [scope, integration, native-platforms, native-engine, typecheck, lint, test, test-unit, test-native, test-browser, test-playtest, golden-path-template, template-nonvisual, template-engine-cost, golden-path, benchmark, build, build-artifacts, budgets, performance-contracts, supply-chain]
     if: ${{ always() && !github.event.pull_request.draft }}
     runs-on: ${{ (github.event.pull_request.head.repo.fork || !vars.TN_RUNNER_LIGHT) && 'ubuntu-24.04' || vars.TN_RUNNER_LIGHT }}
     # 15, not 5: `fetch-depth: 0` pulls every branch and tag, which takes over five minutes on a
@@ -1561,6 +1626,7 @@ jobs:
       - test-playtest
       - golden-path-template
       - template-nonvisual
+      - template-engine-cost
       - golden-path
       - benchmark
       - build

.github/workflows/native-platforms.yml

@@ -2624,7 +2624,8 @@ jobs:
           missing=()
           for config in packages/*/tsup.config.ts; do
             directory="${config%/tsup.config.ts}"
-            [ -f "$directory/dist/index.js" ] || missing+=("$directory/dist/index.js")
+            output="$directory/$(node -p "require('./$directory/package.json').main.replace(/^\\.\\//, '')")"
+            [ -f "$output" ] || missing+=("$output")
           done
           if [ "${#missing[@]}" -gt 0 ]; then
             echo "TN_IOS_PACKAGE_OUTPUTS_MISSING: ${missing[*]}" >&2

.github/workflows/npm-release.yml

@@ -101,33 +101,6 @@ jobs:
         run: |
           sudo apt-get update
           sudo apt-get install -y libvulkan1 mesa-vulkan-drivers
-      - name: Install the pinned Blender used by the registry verifier
-        env:
-          BLENDER_VERSION: 5.2.0
-        run: |
-          archive="${RUNNER_TEMP}/blender-${BLENDER_VERSION}-linux-x64.tar.xz"
-          checksums="${RUNNER_TEMP}/blender-${BLENDER_VERSION}.sha256"
-          install_root="${RUNNER_TEMP}/blender-${BLENDER_VERSION}-linux-x64"
-          curl --fail --location --retry 3 --retry-delay 2 \
-            "https://download.blender.org/release/Blender5.2/blender-${BLENDER_VERSION}-linux-x64.tar.xz" \
-            --output "$archive"
-          curl --fail --location --retry 3 --retry-delay 2 \
-            "https://download.blender.org/release/Blender5.2/blender-${BLENDER_VERSION}.sha256" \
-            --output "$checksums"
-          test -s "$archive"
-          (
-            cd "$RUNNER_TEMP"
-            sha256sum --ignore-missing --check "$(basename "$checksums")"
-          )
-          tar -xJf "$archive" -C "$RUNNER_TEMP"
-          blender="${install_root}/blender"
-          test -x "$blender"
-          actual_version="$("$blender" --version | awk 'NR == 1 { print $2 }')"
-          test "$actual_version" = "$BLENDER_VERSION" || {
-            echo "Expected Blender ${BLENDER_VERSION}, received ${actual_version}." >&2
-            exit 1
-          }
-          echo "THREENATIVE_BLENDER_PATH=${blender}" >> "$GITHUB_ENV"
       # The publish set, named one package per line so `pnpm publish:check` can assert that no
       # publishable package is missing from it. A package that exists, is not private, and is
       # absent here would be omitted from the release.
@@ -148,6 +121,7 @@ jobs:
           pnpm tsx scripts/verify-native-release-commit.ts "$native_tag"
       # BEGIN GENERATED WORKSPACE PUBLISH SET
       #   @threenative/assets
+      #   @threenative/blender-bridge
       #   @threenative/core
       #   @threenative/metahuman
       #   @threenative/physics
@@ -161,7 +135,6 @@ jobs:
       #   @threenative/ui
       #   create-threenative
       #   threenative-animation-mcp
-      #   threenative-blender-mcp
       #   threenative-engine-mcp
       # END GENERATED WORKSPACE PUBLISH SET
       - name: Run the single guarded release path
@@ -228,33 +201,6 @@ jobs:
         run: |
           sudo apt-get update
           sudo apt-get install -y libvulkan1 mesa-vulkan-drivers libwebkit2gtk-4.1-0
-      - name: Install the pinned Blender used by the MCP conversion proof
-        env:
-          BLENDER_VERSION: 5.2.0
-        run: |
-          archive="${RUNNER_TEMP}/blender-${BLENDER_VERSION}-linux-x64.tar.xz"
-          checksums="${RUNNER_TEMP}/blender-${BLENDER_VERSION}.sha256"
-          install_root="${RUNNER_TEMP}/blender-${BLENDER_VERSION}-linux-x64"
-          curl --fail --location --retry 3 --retry-delay 2 \
-            "https://download.blender.org/release/Blender5.2/blender-${BLENDER_VERSION}-linux-x64.tar.xz" \
-            --output "$archive"
-          curl --fail --location --retry 3 --retry-delay 2 \
-            "https://download.blender.org/release/Blender5.2/blender-${BLENDER_VERSION}.sha256" \
-            --output "$checksums"
-          test -s "$archive"
-          (
-            cd "$RUNNER_TEMP"
-            sha256sum --ignore-missing --check "$(basename "$checksums")"
-          )
-          tar -xJf "$archive" -C "$RUNNER_TEMP"
-          blender="${install_root}/blender"
-          test -x "$blender"
-          actual_version="$("$blender" --version | awk 'NR == 1 { print $2 }')"
-          test "$actual_version" = "$BLENDER_VERSION" || {
-            echo "Expected Blender ${BLENDER_VERSION}, received ${actual_version}." >&2
-            exit 1
-          }
-          echo "THREENATIVE_BLENDER_PATH=${blender}" >> "$GITHUB_ENV"
       # Proves the registry path, which no other gate in this repository exercises: the sandbox,
       # the sweeps and verify-golden-path all resolve `file:` tarballs by design.
       - name: Install from the registry in a directory with no workspace above it

.gitignore

@@ -184,7 +184,7 @@ screenshot-*.png
 # scaffold the way a stranger's machine would; three of them were committed by accident in #37.
 *.tgz
 
-# Python bytecode caches. `packages/blender-mcp/gpl/recipes` is executed by Blender, which
+# Python bytecode caches. `packages/blender-bridge/gpl` is executed by Blender, which
 # writes a `__pycache__` beside the recipes on every run; one .pyc was committed by accident.
 __pycache__/
 *.pyc

AGENTS.md

@@ -26,12 +26,13 @@ One source, two runtimes: browser WebGPU and an owned C++ host for desktop/Andro
 ## Pull requests
 
 - **Small changes skip the PR**: a tiny fix, a docs-only edit, a mirror regeneration — anything with no PRD — commits directly to local `develop` after its relevant checks pass.
+- **Open a PR only when a PRD or the owner asks for one** (owner, 2026-10-28: "stop opening fucking PRs all the time"). Fix a red on an open PR by pushing to that PR's branch. Fix a red on `develop` by committing to the PR already in flight, or ask. A second PR for one release or one red is the failure, even when it looks small.
 - **One PR per PRD**, opened as a draft at the first commit — never one per phase, never several PRDs in one PR. Label it with the `prd:25/50/75/100` that `pnpm prd:progress` prints and update the label as phases land.
 - Branch from `origin/develop` (not a local branch that may be ahead of it), target `develop`, squash-merge. Set `git config threenative.integrationBranch develop` per checkout.
 - The commit that finishes a PRD also `git mv`s it to `docs/PRDs/done/`.
 - `main` takes only the ordinary full-checked `develop -> main` PR, merged with a merge commit, never squash or rebase.
 - **Push once per run**: while your PR's CI runs, commit locally; push to fix that run or after it finishes. A PRD tick rides with the next code push, never alone.
-- **Short CI fix cycles.** Start a full CI run only when it is necessary: a release-candidate head or a required gate. A full run costs about an hour. Start the fix when the first red appears, and do not wait for the run to end. Prove the fix on the nearest lane (CI image, same software adapter, cold cache) before you push. Push all fixes for a run as one commit set and cancel the superseded run. `gh run rerun --failed` retries only a flake on the same commit. It cannot test a fix, and a partial rerun breaks the Integration receipts. Never trim the board or call a partial run green.
+- **Short CI fix cycles.** Start a full CI run only when it is necessary: a release-candidate head or a required gate. A full run costs about an hour. Start the fix when the first red appears, and do not wait for the run to end. Prove the fix on the nearest lane (CI image, same software adapter, cold cache) before you push. Push all fixes for a run as one commit set and cancel the superseded run. `gh run rerun --failed` retries only a flake on the same commit. It cannot test a fix. Its green joins keep the receipts of the attempt that ran them, so it can turn `ci-required` green. Never trim the board or call a partial run green.
 - **No workflow file per feature**: add its CI proof as a job in an existing workflow.
 - Before retargeting, inventory `gh pr list` and `pnpm worktree:status`; retarget in-flight PRs one at a time and never rewrite another worktree.