refactor(untangle): one owner per value — PRD-832 lands, PRD-833..842 follow

.gitattributes

@@ -5,3 +5,6 @@ packages/three-native/tests/compatibility/goldens/** linguist-generated
 packages/three-native/tests/compatibility/fixtures/** linguist-generated
 packages/three-native/api/*.json linguist-generated
 packages/three-native/generated/** linguist-generated
+
+# A CRLF checkout breaks Vite's shebang strip (`/^#!.*\n/`), so a shebang module fails to import on Windows.
+*.mjs text eol=lf

.github/workflows/ci.yml

@@ -208,6 +208,9 @@ jobs:
         run: |
           set -euo pipefail
           pnpm lint
+          # PRD-836: the capability reference and the context skill are build output, not tracked
+          # files, and `check:docs` resolves links against the working tree.
+          pnpm capabilities:sync
           pnpm check:docs
           pnpm exec vitest run \
             scripts/__tests__/check-doc-links.spec.ts \
@@ -1451,6 +1454,9 @@ jobs:
           shared-artifact: workspace-packages
           save-bundles: "false"
           pack-archives: "false"
+      # The capability reference is build output (PRD-836): `budgets --check`s it, so a clean
+      # checkout generates it first, exactly as the docs lane does.
+      - run: pnpm capabilities:sync
       - run: pnpm budgets
       - run: pnpm quality
       - run: pnpm sync:agents --check

.github/workflows/native-platforms.yml

@@ -1513,6 +1513,14 @@ jobs:
           pnpm --filter @threenative/runtime-native native:build
       - if: runner.os != 'Windows'
         run: pnpm --filter @threenative/runtime-native native:build
+      - name: Install the Linux display probe's tools
+        if: runner.os == 'Linux'
+        run: |
+          # `host-window.test.mjs` reads the window the X server reports. The hosted image ships
+          # Xvfb, xwininfo and xprop but no xdotool, so the verify lane below failed on the
+          # prerequisite instead of running the probe. Installed here, not trusted to the image.
+          sh scripts/retry-download.sh sudo apt-get update
+          sh scripts/retry-download.sh sudo apt-get install -y xdotool xvfb x11-utils
       - name: Report the compiler cache hit rate
         if: always() && env.CCACHE_UNAVAILABLE != '1'
         shell: bash

.github/workflows/native-release.yml

@@ -258,6 +258,7 @@ jobs:
           libxcursor-dev libxi-dev libxfixes-dev libxss-dev libxkbcommon-dev
           libgtk-3-dev libwebkit2gtk-4.1-dev libxcomposite-dev xcompmgr
           libvulkan1 mesa-vulkan-drivers vulkan-tools zlib1g-dev
+          xdotool xvfb x11-utils
       - name: Install Windows HTTP build dependencies
         if: runner.os == 'Windows'
         run: >-
@@ -551,11 +552,15 @@ jobs:
           name: runtime-ios-simulator-arm64
           path: release/threenative-ios-simulator-arm64.zip
           if-no-files-found: error
+      # Runs when the proof above fails, which is the only time anyone reads these logs: a failed
+      # launch writes `variant-<label>.log` and the step that uploads them came after the throw, so
+      # the run that needed the log was the one run that never kept it (PRD-842, web-ui variant).
       - uses: actions/upload-artifact@v7
+        if: ${{ !cancelled() }}
         with:
           name: evidence-ios-simulator-arm64
           path: packages/runtime-native/artifacts/ios/
-          if-no-files-found: error
+          if-no-files-found: warn
 
   publish:
     needs: [validate-tag, gates, build, build-android, build-ios-simulator]

.gitignore

@@ -202,8 +202,10 @@ __pycache__/
 # authored `assets/hull.glb` source is tracked.
 examples/auto-lod/public/
 
-# Generated by prepack from packages/core/patches (the only tracked copy).
-packages/create-threenative/template-assets/patches/
+# Generated by prepack from packages/core/patches (the only tracked copy). The manifest is not
+# generated: it is the list prepack reads, so a clean checkout with no manifest cannot pack at all.
+packages/create-threenative/template-assets/patches/*
+!packages/create-threenative/template-assets/patches/manifest.json
 # scripts/stage-terrain-kits.mjs writes these kits from packages/terrain/starter, the only tracked copy.
 /packages/create-threenative/template-assets/terrain/
 
@@ -228,3 +230,9 @@ tools/unreal-reference/gi/**/__pycache__/
 examples/strata-terrain-preview/dist-engine/
 
 dist-one-spell/
+
+# PRD-836: the one committed capability manifest is core's; this copy and the reference it
+# generates are build output. The context skill is not: its prose is hand-written and one region of
+# it is generated, so it stays tracked or a clean checkout loses the words.
+/packages/create-threenative/capabilities.json
+/packages/create-threenative/agent-docs/references/capability-reference.md

AGENTS.md

@@ -10,7 +10,7 @@ One source, two runtimes: browser WebGPU and an owned C++ host for desktop/Andro
 
 ## How you work
 
-1. **Search the manifest before you write — by rule, not judgement.** Run `engine_search_capabilities` and read every row — it carries the import path, signature, example, constraints, overrides and deprecations; call `engine_capability_detail` only for a symbol the search did not return — before any new file under `src/` or `packages/`, any helper longer than a screen, and any render stage you toggle. Skipping it has shipped 446 hand-written lines of an installed system at 9 FPS. **Search the symptom too, before you debug it** (owner, 2026-10-24: "why this capability research wasnt done BEFORE having these issues"): a slow frame, limbs out of step with motion, a blurred or wrong image. Before you report a game done, play it from the spawn and read `TN_FRAME_BUDGET`, `TN_SCENE_WARNING` and `TN_RENDER_PROJECTION`. The manifest (`packages/create-threenative/capabilities.json`, rebuilt by `pnpm build`) is the only complete public surface, including subpath exports like `@threenative/physics/navigation`. Both tools ship in `threenative-engine-mcp`, wired by the `.mcp.json` that installing `@threenative/core` writes; launch from the game-project root or the server is missing.
+1. **Search the manifest before you write — by rule, not judgement.** Run `engine_search_capabilities` and read every row — it carries the import path, signature, example, constraints, overrides and deprecations; call `engine_capability_detail` only for a symbol the search did not return — before any new file under `src/` or `packages/`, any helper longer than a screen, and any render stage you toggle. Skipping it has shipped 446 hand-written lines of an installed system at 9 FPS. **Search the symptom too, before you debug it** (owner, 2026-10-24: "why this capability research wasnt done BEFORE having these issues"): a slow frame, limbs out of step with motion, a blurred or wrong image. Before you report a game done, play it from the spawn and read `TN_FRAME_BUDGET`, `TN_SCENE_WARNING` and `TN_RENDER_PROJECTION`. The manifest (`packages/core/capabilities.json`, rebuilt by `pnpm build`) is the only complete public surface, including subpath exports like `@threenative/physics/navigation`. Both tools ship in `threenative-engine-mcp`, wired by the `.mcp.json` that installing `@threenative/core` writes; launch from the game-project root or the server is missing.
    For game behavior references, use `engine_search_references`, then `engine_reference_detail` for pinned source; `engine_save_reference` saves a local reference and returns a contribution command; `engine_watch_reference` returns a contact sheet of real gameplay footage.
    Then be lazy (the `ponytail` skill, re-injected by the project hooks; `PONYTAIL=off` opts out): YAGNI, installed system, stdlib/platform, one line. Never simplify away validation, error handling, security, accessibility or requested behaviour.
 2. **Name the layer before fixing a bug**: engine (`packages/`) or game (example/template), and why. An engine bug fixed in game code leaves every other game broken.

CHANGELOG.md

@@ -9,8 +9,24 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
-Nothing yet. Add the next change here. A removed or changed public symbol needs a `### Breaking`
-entry that names it (`pnpm api:surface:check`).
+### Added
+
+- `@threenative/core/render/environment` is the one home of the environment measure-and-sample
+  mechanism that twelve templates used to copy byte-for-byte: `measureEnvironment`,
+  `sampleEnvironment` and its cache, `captureEnvironmentSnapshot`, `reportEnvironmentContribution`,
+  `sampledRadiance`, the sampling-source check, and the gate that decides which renderer may run the
+  material lane (`IMaterialLightingEnvironment`, `materialLightingEnabled`, `isWebGLFallbackRenderer`).
+
+### Breaking
+
+- `@threenative/core`'s `devGlobal` and `publishDevGlobal` take their `scope` argument explicitly
+  rather than defaulting to `globalThis`: a default made an explicit `undefined` read the page's
+  global, which is exactly the worker case a caller asks about. Both were new in this branch.
+
+- `@threenative/core/render/environment` does not export `backlightMaterial`, `resolveKey` or
+  `validateControls`: the backlight's shader constants decide how a surface looks, so those files
+  stay in each game's `src/render/`. A game that imported them from the subpath — only this branch
+  ever did — keeps the identical copies its kit already ships.
 
 ## [0.3.11] - 2026-11-03
 

CLAUDE.md

@@ -12,7 +12,7 @@ One source, two runtimes: browser WebGPU and an owned C++ host for desktop/Andro
 
 ## How you work
 
-1. **Search the manifest before you write — by rule, not judgement.** Run `engine_search_capabilities` and read every row — it carries the import path, signature, example, constraints, overrides and deprecations; call `engine_capability_detail` only for a symbol the search did not return — before any new file under `src/` or `packages/`, any helper longer than a screen, and any render stage you toggle. Skipping it has shipped 446 hand-written lines of an installed system at 9 FPS. **Search the symptom too, before you debug it** (owner, 2026-10-24: "why this capability research wasnt done BEFORE having these issues"): a slow frame, limbs out of step with motion, a blurred or wrong image. Before you report a game done, play it from the spawn and read `TN_FRAME_BUDGET`, `TN_SCENE_WARNING` and `TN_RENDER_PROJECTION`. The manifest (`packages/create-threenative/capabilities.json`, rebuilt by `pnpm build`) is the only complete public surface, including subpath exports like `@threenative/physics/navigation`. Both tools ship in `threenative-engine-mcp`, wired by the `.mcp.json` that installing `@threenative/core` writes; launch from the game-project root or the server is missing.
+1. **Search the manifest before you write — by rule, not judgement.** Run `engine_search_capabilities` and read every row — it carries the import path, signature, example, constraints, overrides and deprecations; call `engine_capability_detail` only for a symbol the search did not return — before any new file under `src/` or `packages/`, any helper longer than a screen, and any render stage you toggle. Skipping it has shipped 446 hand-written lines of an installed system at 9 FPS. **Search the symptom too, before you debug it** (owner, 2026-10-24: "why this capability research wasnt done BEFORE having these issues"): a slow frame, limbs out of step with motion, a blurred or wrong image. Before you report a game done, play it from the spawn and read `TN_FRAME_BUDGET`, `TN_SCENE_WARNING` and `TN_RENDER_PROJECTION`. The manifest (`packages/core/capabilities.json`, rebuilt by `pnpm build`) is the only complete public surface, including subpath exports like `@threenative/physics/navigation`. Both tools ship in `threenative-engine-mcp`, wired by the `.mcp.json` that installing `@threenative/core` writes; launch from the game-project root or the server is missing.
    For game behavior references, use `engine_search_references`, then `engine_reference_detail` for pinned source; `engine_save_reference` saves a local reference and returns a contribution command; `engine_watch_reference` returns a contact sheet of real gameplay footage.
    Then be lazy (the `ponytail` skill, re-injected by the project hooks; `PONYTAIL=off` opts out): YAGNI, installed system, stdlib/platform, one line. Never simplify away validation, error handling, security, accessibility or requested behaviour.
 2. **Name the layer before fixing a bug**: engine (`packages/`) or game (example/template), and why. An engine bug fixed in game code leaves every other game broken.

README.md

@@ -77,7 +77,7 @@ const game = defineGame<GameState, IPhysicsContext>({
     },
   },
   plugins: [rapier(), playtest()],
-  render: config.renderer,
+  renderer: config.renderer,
   scenes: { play: Play },
   start: "play",
 });

biome.json

@@ -253,6 +253,10 @@
           }
         }
       }
+    },
+    {
+      "include": ["packages/runtime-native/src/runtime-scripts/frame-op-stream.js"],
+      "linter": { "rules": { "style": { "useNamingConvention": "off" } } }
     }
   ]
 }