EPIC: Strata terrain hardening

.github/workflows/ci.yml

@@ -659,6 +659,46 @@ jobs:
       - uses: ./.github/actions/playwright-chromium
       - run: pnpm test:playtest:ci
 
+  strata:
+    needs: [scope, build-artifacts]
+    if: ${{ needs.scope.outputs.selection == 'full' && fromJSON(needs.scope.outputs.plan).jobs.strata.required }}
+    runs-on: ${{ (github.event.pull_request.head.repo.fork || !vars.TN_RUNNER) && 'ubuntu-24.04' || vars.TN_RUNNER }}
+    timeout-minutes: 60
+    env:
+      TN_CI_SHA: ${{ needs.scope.outputs.candidate_sha }}
+    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
+      - uses: ./.github/actions/workspace-dist
+        with:
+          shared-artifact: workspace-packages
+          save-bundles: "false"
+      - uses: ./.github/actions/playwright-chromium
+      - name: Generate the terrain example's ignored world source
+        run: pnpm --filter strata-terrain-preview bake
+      - name: Run strata web playtest
+        run: sh scripts/xvfb.sh pnpm --filter strata-terrain-preview test:terrain:web
+      - name: Run strata consumer verification
+        run: pnpm --filter strata-terrain-preview test:consumer
+      - name: Run strata editor verification
+        run: sh scripts/xvfb.sh pnpm --filter strata-terrain-preview test:terrain:editor
+      - name: Run strata authored-world reproduction
+        run: sh scripts/xvfb.sh pnpm --filter strata-terrain-preview test:terrain:authored
+      - name: Run strata custom-art swap
+        run: sh scripts/xvfb.sh pnpm --filter strata-terrain-preview test:terrain:custom
+      - name: Run strata static-world export
+        run: sh scripts/xvfb.sh pnpm --filter strata-terrain-preview test:terrain:export
+
   golden-path-template:
     needs: [scope, build-artifacts]
     if: ${{ (needs.scope.outputs.selection == 'full' || needs.scope.outputs.selection == 'template') }}
@@ -1008,6 +1048,12 @@ jobs:
           node-version: 20
           cache: pnpm
       - run: pnpm install --frozen-lockfile
+      # Check before restoring or publishing workspace builds, including the develop warm lane.
+      # The pinned upstream archive is downloaded fresh; cache: pnpm does not cache its npm build.
+      # Bash time reports the download + own-build wall cost and preserves failures (PRD-593 AC-2).
+      - name: Verify the generated Three.js patch has not drifted
+        shell: bash
+        run: time pnpm --filter @threenative/core patch:generate --check
       - uses: ./.github/actions/workspace-dist
       - run: pnpm --filter abyss-framework build
       - name: Enforce entity registry boundaries
@@ -1241,7 +1287,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, 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, typecheck, lint, test, test-unit, test-native, test-browser, test-playtest, strata, golden-path-template, template-nonvisual, 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 }}
     timeout-minutes: 5
@@ -1295,6 +1341,7 @@ jobs:
       - test-native
       - test-browser
       - test-playtest
+      - strata
       - golden-path-template
       - template-nonvisual
       - golden-path

.gitignore

@@ -201,10 +201,15 @@ examples/auto-lod/public/
 
 # Generated by prepack from packages/core/patches (the only tracked copy).
 packages/create-threenative/template-assets/patches/
+# scripts/stage-terrain-kits.mjs writes these kits from packages/terrain/starter, the only tracked copy.
+/packages/create-threenative/template-assets/terrain/
 
 # Licensed (non-redistributable) local art for review; never committed
 examples/strata-terrain-preview/local-assets/
 examples/native-css-hud/corpus/out/
 examples/native-css-hud/corpus/out-interaction/
 examples/native-css-hud/corpus/out-desktop/
 examples/native-css-hud/bench/out/
+
+# Forest kit headless bake output (authored recipe and assets remain tracked).
+/packages/terrain/starter/forest/world/

AGENTS.md

@@ -35,6 +35,7 @@ One source, two runtimes: browser WebGPU and an owned C++ host for desktop/Andro
 | --- | --- |
 | Anything that **decides how it looks** — materials, shaders, TSL, lights, tonemapping, post, framing — and any preset or default picking one | `templates/*/src/render/`, as generated user source |
 | The **mechanism** that puts it on screen — pooling, lifetime, billboarding, instancing, dispatch, culling — with every appearance parameter from the game; plumbing every game repeats | `packages/core/src/` |
+| Optional terrain authoring and terrain-only editor companions, within the CHARTER allowance | `packages/terrain/`; appearance remains generated game source |
 | Physics or navigation (WASM dep) · React HUD/menu bindings · C++ host, platform bring-up, native systems · scenario harness and assertions | `packages/physics/` · `ui/` · `runtime-native/` · `playtest/` |
 | Gameplay, never in a package · proof that any of it works | an example or template · `<package>/__tests__/*.spec.ts` **and** a playtest scenario |
 

CHANGELOG.md

@@ -30,6 +30,18 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Breaking
 
+- `@threenative/terrain/export` removes `exportWorldGLB`. Prepare the browser scene with
+  `prepareWorldGLTF`, then encode it in Node with `cookTerrainWorld({ preparedWorld: prepared.json })`
+  from `@threenative/assets`; the editor already uses this shared cook.
+
+- `@threenative/assets`'s `cookTerrainWorld` declaration adds a prepared-world JSON overload
+  for the terrain editor's portable GLB export. Existing state/species/out calls remain valid;
+  the new overload embeds the game's frozen scene without instancing or filesystem output.
+
+- `@threenative/terrain`'s `makeExport` declaration adds a `"project"` overload accepting
+  a null terrain state, so recipes can be exported before the first evaluation. Existing
+  calls remain valid; non-project exports still require an evaluated state.
+
 - The unreleased terrain editor's `mountTerrainEditor` view factory receives
   `(host, controller)`. Its `IEditorView` implements `setDocument(document, revision)`
   so metadata edits can update the scene without dispatching terrain evaluation;

CLAUDE.md

@@ -37,6 +37,7 @@ One source, two runtimes: browser WebGPU and an owned C++ host for desktop/Andro
 | --- | --- |
 | Anything that **decides how it looks** — materials, shaders, TSL, lights, tonemapping, post, framing — and any preset or default picking one | `templates/*/src/render/`, as generated user source |
 | The **mechanism** that puts it on screen — pooling, lifetime, billboarding, instancing, dispatch, culling — with every appearance parameter from the game; plumbing every game repeats | `packages/core/src/` |
+| Optional terrain authoring and terrain-only editor companions, within the CHARTER allowance | `packages/terrain/`; appearance remains generated game source |
 | Physics or navigation (WASM dep) · React HUD/menu bindings · C++ host, platform bring-up, native systems · scenario harness and assertions | `packages/physics/` · `ui/` · `runtime-native/` · `playtest/` |
 | Gameplay, never in a package · proof that any of it works | an example or template · `<package>/__tests__/*.spec.ts` **and** a playtest scenario |
 

biome.json

@@ -11,6 +11,7 @@
       "packages/metahuman/wasm/**",
       "artifacts/**",
       "examples/strata-terrain-preview/src/world/*.json",
+      "examples/strata-terrain-preview/assets/world/*.json",
       "examples/strata-terrain-preview/local-assets/**",
       "build/**",
       "release-native/**",
@@ -89,6 +90,10 @@
     }
   },
   "overrides": [
+    {
+      "include": ["examples/procedural-animals/src/render/donor/core/motion/quadruped.js"],
+      "javascript": { "formatter": { "quoteProperties": "preserve" } }
+    },
     {
       "include": ["**/*.ts", "**/*.tsx"],
       "linter": { "rules": { "style": { "useNamingConvention": "off" } } }