@vgai/engine 0.5.22 → 0.5.24

package/src/manifest/filename.ts

@@ -1,17 +1,13 @@
 // The project manifest's FILENAME. There is exactly ONE.
 //
-// The manifest is `vgai.project.json`. It used to be `vgai.game.json`, and for
-// a while both names were read — WO-9 #62 recorded that dual-read as
-// permanent, on the presumption of an EXTERNAL constituency of projects
-// already on disk. The owner reversed that on 2026-08-02 (the legacy-removal
-// doctrine, `docs/ARCHITECTURE-CORE.md` §Vocabulary): this is pre-release
-// software, no such constituency exists, and a second way to spell the
-// manifest is the defect — two accepted names meant both kept being written,
-// and copies of the "try both" probe grew in five modules that agreed with the
-// real resolver only by coincidence.
+// The manifest is `vgai.project.json`, and NOTHING reads a second spelling
+// (the legacy-removal doctrine, `docs/ARCHITECTURE-CORE.md` §Vocabulary). Two
+// accepted names is the defect, not the convenience: both get written, and
+// copies of the "try both" probe spread into modules that agree with the real
+// resolver only by coincidence.
 //
-// So the old name is REMOVED, and removed means it REJECTS LOUDLY naming the
-// exact one-line fix — never silently ignored, never redirected. A directory
+// The removed name REJECTS LOUDLY, naming the exact one-line fix — never
+// silently ignored, never redirected. A directory
 // carrying only `vgai.game.json` is an error with a `git mv` in the message,
 // not a project that quietly fails to open.
 //
@@ -40,7 +36,7 @@ export function isManifestFilename(name: string): boolean {
 export function removedManifestFilenameMessage(where: string): string {
   return (
     `${where}: found \`${REMOVED_MANIFEST_FILENAME}\` and no \`${MANIFEST_FILENAME}\`. ` +
-    `\`${REMOVED_MANIFEST_FILENAME}\` was REMOVED (WO-LR1; the legacy-removal doctrine, ` +
+    `\`${REMOVED_MANIFEST_FILENAME}\` was REMOVED (the legacy-removal doctrine, ` +
     'docs/ARCHITECTURE-CORE.md §Vocabulary) — nothing reads it any more, and it is ' +
     'deliberately NOT read as a fallback, because a second accepted name is the defect.\n' +
     `Fix: rename it — \`git mv ${REMOVED_MANIFEST_FILENAME} ${MANIFEST_FILENAME}\`. ` +

package/src/manifest/load.ts

@@ -62,13 +62,6 @@ export type ResolvedAdapter =
       readonly assets: Record<string, string> | undefined;
       readonly domStubs: string[] | undefined;
       readonly captureTimeoutMs: number | undefined;
-      /**
-       * The component this root'''s WORLD is, in the game'''s own source (see the
-       * field'''s schema description). Present ⇒ Edit mounts THAT component
-       * alone as a still design-time document and Play mounts the game
-       * through `entry`; absent ⇒ `entry` is what both modes mount.
-       */
-      readonly world?: { readonly entry: string; readonly export?: string | undefined } | undefined;
     };
 
 export interface ResolvedAdapterRoot {
@@ -77,6 +70,13 @@ export interface ResolvedAdapterRoot {
   readonly description: string | undefined;
   readonly adapter: ResolvedAdapter;
   readonly entry: string | undefined;
+  /**
+   * The component this root's WORLD is, in the game's own source (see the
+   * field's schema description). Present ⇒ Edit mounts THAT component alone as
+   * its design-time document and Play mounts the game through `entry`;
+   * absent ⇒ `entry` is what both modes mount.
+   */
+  readonly world?: { readonly entry: string; readonly export: string | undefined } | undefined;
   readonly zOrder: number;
   readonly pausable: boolean;
   readonly loop: 'gated' | 'self-driven';
@@ -231,7 +231,6 @@ function resolveAdapter(root: AdapterRoot): ResolvedAdapter {
     assets: ingest.assets,
     domStubs: ingest.domStubs,
     captureTimeoutMs: ingest.captureTimeoutMs,
-    world: ingest.world,
   };
 }
 
@@ -251,11 +250,14 @@ function checkEngineVersionPin(version: string): void {
  * `id` drives uniqueness; `adapter` (incl. its surface and
  * `module`/`ingest.*` sub-fields) drives adapter identity
  * resolution; `entry` drives the entry cross-field rule and is
- * carried through; `zOrder` drives the final sort; `pausable`/`loop` are
+ * carried through; `world` is carried through for the ONE reader that mounts a
+ * design-time document (the editor's design session) and is deliberately not
+ * cross-checked against `entry` — the two name different modules on purpose;
+ * `zOrder` drives the final sort; `pausable`/`loop` are
  * carried through as-is (their consumers are the runtime/CLI, T3.2/T3.3);
  * `description` (T3.3
  * slice 3) is carried through as-is — its consumer today is
- * `resolveIngestDescriptor` (packages/editor/src/adapter-resolver.ts), which
+ * `resolveIngestDescriptor` (packages/editor/src/ingest/resolve-three.ts), which
  * threads an ingest-three root's description into `IngestGame.description`.
  */
 function resolveRoot(root: AdapterRoot): ResolvedAdapterRoot {
@@ -268,6 +270,8 @@ function resolveRoot(root: AdapterRoot): ResolvedAdapterRoot {
     description: root.description,
     adapter,
     entry: root.entry,
+    world:
+      root.world === undefined ? undefined : { entry: root.world.entry, export: root.world.export },
     zOrder: root.zOrder,
     pausable: root.pausable,
     loop: root.loop,
@@ -285,9 +289,9 @@ function resolveRoot(root: AdapterRoot): ResolvedAdapterRoot {
  * any Zod validation failure or cross-field rule violation.
  */
 export function loadGameManifest(raw: unknown): ResolvedGameManifest {
-  // Removed-format guard FIRST, on the raw value: a legacy `.vscn.json` root
-  // would otherwise fail Zod's `roots` discriminated union with a confusing
-  // shape error instead of a migration message (WO-8).
+  // Removed-format guard FIRST, on the raw value: a root declaring a removed
+  // content field would otherwise fail Zod's `roots` discriminated union with
+  // a confusing shape error instead of the named migration message.
   const parsed = GameManifestSchema.safeParse(raw);
   if (!parsed.success) {
     // D-V6: the `roots` `superRefine`'s composition issues — a duplicate root

package/src/manifest/schema.ts

@@ -7,14 +7,9 @@
 // has a `.describe()` (repo policy — powers `scripts/generate-schema.ts` and
 // the T4.1 schema-walk coverage test).
 //
-// Naming: this file follows the repo's `XxxSchema` (Zod schema) / `Xxx`
-// (inferred type) convention used throughout `scene/schema/` — the design
-// doc's §3 sketch names the bare consts (`AdapterRoot`) without the
-// `Schema` suffix; that sketch is explicitly a
-// "Zod sketch" the doc tells implementers to adapt to real code style
-// ("mirror the style in scene/schema/scene-file.ts" per CLAUDE.md), so the
-// schema consts here are suffixed and the bare names are reserved for the
-// inferred types, matching every other schema file in the repo.
+// Naming: `XxxSchema` is the Zod schema, `Xxx` the inferred type. Every schema
+// file in this repo reads that way, so the bare names stay reserved for the
+// types.
 //
 // Adapter surface values mirror `AdapterSurface` in
 // `packages/engine/src/runtime/game.ts` (`'three' | 'canvas' | 'dom'`)
@@ -56,7 +51,7 @@ export const GAME_MANIFEST_VERSION = 2 as const;
 // which is exactly why react is a `dom` root rather than its own kind.
 //
 // The pre-rename spellings `threejs`/`pixijs`/`react` are REMOVED, not
-// normalized (WO-LR1 item 2, the legacy-removal doctrine at
+// normalized (the legacy-removal doctrine at
 // ARCHITECTURE-CORE §Vocabulary). Normalization was a second way to say the
 // same thing: two spellings both parsed, so both kept being written, and
 // SECOND readers grew (the dev server's surface probe, the hosted-editor
@@ -83,8 +78,8 @@ function removedSpellingMessage(bad: string, where: 'adapter' | 'adapter.surface
   const canonical =
     where === 'adapter' ? REMOVED_BARE_ADAPTER_SPELLING[bad] : REMOVED_SURFACE_SPELLING[bad];
   return (
-    `Game manifest: \`${where}\`: "${bad}" — that spelling was REMOVED (WO-LR1; ` +
-    'ARCHITECTURE-CORE §Vocabulary). The surface vocabulary is ' +
+    `Game manifest: \`${where}\`: "${bad}" — that spelling was REMOVED ` +
+    '(ARCHITECTURE-CORE §Vocabulary). The surface vocabulary is ' +
     "'three' | 'canvas' | 'dom' — what the HOST HANDS the root, never which " +
     `library it uses.\nFix: change \`${where}\` to "${canonical}".`
   );
@@ -219,34 +214,6 @@ export const RootAdapterSchema = z
                     'FAILS by name. A game that needs a long boot (streamed world assets, a menu ' +
                     'the player must clear) raises it; the default is 10s.',
                 ),
-              world: z
-                .object({
-                  entry: z
-                    .string()
-                    .describe(
-                      "Project-relative path to the game's OWN module exporting that component",
-                    ),
-                  export: z
-                    .string()
-                    .optional()
-                    .describe(
-                      'Named export to read from that module; omit when the module default-exports it',
-                    ),
-                })
-                .strict()
-                .optional()
-                .describe(
-                  "The component this root's WORLD is, in the game's own source — a three root " +
-                    'whose scene is a React/R3F component tree names it here. Two readers, and ' +
-                    'they mount different things: the editor mounts THIS component alone as the ' +
-                    "root's design-time document (a still scene — its frameloop runs ONE bounded " +
-                    'settle at mount, so physics-owned bodies rest at their authored spawn, and ' +
-                    'is then frozen forever; nothing moves in Edit), while `entry` ' +
-                    'above stays what PLAY mounts (the whole game, its own composition, its own ' +
-                    'HUD and loop). Declaring it is what lets a scene be a scene in Edit rather ' +
-                    "than the running game's mount surfaces. A game whose world is not a " +
-                    'component omits it and keeps mounting through `entry` in both modes.',
-                ),
             })
             .strict()
             .describe(
@@ -306,6 +273,37 @@ export const AdapterRootSchema = z
           "the HUD is styled on the UI board's story cards and on the game surface without the " +
           'editor seeing a single one of those rules. The files themselves are never modified.',
       ),
+    world: z
+      .object({
+        entry: z
+          .string()
+          .describe("Project-relative path to the game's OWN module exporting that component"),
+        export: z
+          .string()
+          .optional()
+          .describe(
+            'Named export to read from that module; omit when the module default-exports it',
+          ),
+      })
+      .strict()
+      .optional()
+      .describe(
+        "The component this root's WORLD is, in the game's own source. Two readers, and they " +
+          "mount different things: the EDITOR mounts THIS component alone as the root's " +
+          'design-time document, while `entry` above stays what PLAY mounts (the whole game — ' +
+          'its own composition, its own HUD, its own loop). It sits on the ROOT rather than ' +
+          'inside any one adapter because the split it names is not about ingest: a game whose ' +
+          'runtime entry is a SHELL over the thing an author actually edits has this shape ' +
+          'whether the source is vendored or first-party. Two shipped cases, one field: an ' +
+          'ingested game whose `entry` mounts game+HUD+loop while the named export is the world ' +
+          'alone; and a translated Unity/Godot port, whose `entry` is a scene HOST that mounts ' +
+          'the scene the built player starts on (`EditorBuildSettings` index 0 — routinely a ' +
+          'menu with no 3D content at all) while the named export opens the scene an author ' +
+          "edits. That is Unity's own split: build settings say where the PLAYER starts; the " +
+          'Scene view opens a scene, and Unity keeps that fact somewhere else entirely. A game ' +
+          'whose world is not a separate component omits this and keeps mounting through ' +
+          '`entry` in both modes.',
+      ),
     zOrder: z
       .number()
       .int()
@@ -424,6 +422,7 @@ export const GameManifestSchema = z
               'identity pin, not a range',
           ),
       })
+      .strict()
       .describe('Engine version pin'),
     roots: z
       .array(AdapterRootSchema)
@@ -498,21 +497,25 @@ export const GameManifestSchema = z
               .describe('Optional editor labels keyed by adapter-root id'),
             groups: z
               .array(
-                z.object({
-                  id: z.string().describe('Unique editor-only group id'),
-                  label: z.string().describe('Editor-only group label'),
-                  roots: z
-                    .array(z.string())
-                    .min(1)
-                    .describe('Adapter-root ids shown under this editor-only group'),
-                }),
+                z
+                  .object({
+                    id: z.string().describe('Unique editor-only group id'),
+                    label: z.string().describe('Editor-only group label'),
+                    roots: z
+                      .array(z.string())
+                      .min(1)
+                      .describe('Adapter-root ids shown under this editor-only group'),
+                  })
+                  .strict(),
               )
               .optional()
               .describe('Optional editor-only hierarchy groups'),
           })
+          .strict()
           .optional()
           .describe('Editor projection for native adapter roots'),
       })
+      .strict()
       .optional()
       .describe('Editor-only authoring metadata; never runtime ownership'),
     server: z
@@ -558,6 +561,7 @@ export const GameManifestSchema = z
             'Deploy-baked managed-relay credentials. NEVER hand-authored in source — written only into the staged manifest by `vgai deploy` and fetched at runtime by the standalone client',
           ),
       })
+      .strict()
       .optional()
       .describe('Multiplayer server config (Colyseus), if this game registers a room'),
     resolution: z
@@ -565,6 +569,7 @@ export const GameManifestSchema = z
         width: z.number().describe('Canvas width in pixels'),
         height: z.number().describe('Canvas height in pixels'),
       })
+      .strict()
       .optional()
       .describe('Canvas resolution'),
     rendering: z
@@ -599,6 +604,7 @@ export const GameManifestSchema = z
               'runtime reader is the debug-bridge installer (D18).',
           ),
       })
+      .strict()
       .optional()
       .describe(
         'Debug-bridge production gating (D18) — governs whether ?vgai-debug=1 installs ' +
@@ -631,6 +637,7 @@ export const GameManifestSchema = z
               "omit to fall back to the runtime's own fixed default seed.",
           ),
       })
+      .strict()
       .optional()
       .describe(
         'Seeded-RNG determinism contract (D15) — governs ' +
@@ -689,6 +696,7 @@ export const GameManifestSchema = z
               'deterministic under a seed.',
           ),
       })
+      .strict()
       .refine((budget) => Object.values(budget).some((value) => value !== undefined), {
         message:
           'Game manifest: `budget` must set at least one metric (frameCpuMsP95, physicsMsP95, ' +

package/src/physics/collider-dimensions.ts

@@ -5,17 +5,13 @@
  * shape is defined in absolute world units at creation time. Three.js meshes,
  * by contrast, scale visually for free via the normal Object3D hierarchy. To
  * keep the physical collider matching what's on screen, the LOADER must bake
- * the entity's composed WORLD scale (self × every transformed ancestor — see
- * T1.1's world-transform composition) into the collider's dimensions at
- * creation time.
+ * the entity's composed WORLD scale (self × every transformed ancestor) into
+ * the collider's dimensions at creation time.
  *
- * This is the ONE place that does that math, so both the runtime loader
- * (scene-loader.ts `createPhysicsBody`) and the editor's collider gizmo
- * (gizmo-registry.ts) agree on exactly the same numbers — previously the
- * editor gizmo only rendered the entity's own live Object3D scale (via normal
- * Three.js parenting) while the Rapier body ignored scale entirely, so the
- * two silently agreed by coincidence for uniform scale and disagreed for
- * everything else.
+ * This is the ONE place that does that math, so every caller — the physics
+ * body creation path and the editor's collider gizmo alike — agrees on
+ * exactly the same numbers. Two copies silently agree by coincidence for
+ * uniform scale and disagree for everything else.
  *
  * Round colliders (ball/capsule) can only represent a uniform radius — Rapier
  * has no ellipsoid/elliptical-capsule shape. A non-uniform world scale on a
@@ -40,8 +36,8 @@ export interface ColliderWorldDimensions {
 
 /**
  * Compute a collider's WORLD-space dimensions given the entity's composed
- * world scale (self × ancestors, per-axis, in the entity's own local frame —
- * X/Y/Z order matches `SceneEntity.transform.scale`).
+ * world scale (self × ancestors, per-axis, in the entity's own local frame,
+ * in X/Y/Z order).
  *
  * @param collider - the entity's authored (unscaled) collider definition.
  * @param worldScale - composed world scale `[x, y, z]`.

package/src/pixi/scene-capture.ts

@@ -19,25 +19,22 @@
  */
 
 import {
+  type CaptureWaitOptions,
   documentVisibilityClock,
   startVisibleCaptureWindow,
-  type VisibilityClock,
-  type VisibleCaptureWindow,
 } from '../adapter/ingest/visible-capture-window';
 
 /**
- * Options for {@link SceneCapture2DHandle.waitForCapture} — the same shape the
- * three lane's `CaptureWaitOptions` has, because it is the same wait. Passing a
- * bare number is `{ timeoutMs }`, which is what every existing caller does.
+ * Options for {@link SceneCapture2DHandle.waitForCapture} — the WAIT's options,
+ * not this lane's, so they carry no `2D` suffix and are not declared here.
+ * They configure `visible-capture-window.ts`'s window, which both surfaces
+ * share; this lane used to restate them field-for-field under a `2D` name.
+ * The suffix marks what a surface genuinely owns
+ * ({@link CapturedRuntime2D} is a Pixi stage/renderer/app, and stays), and a
+ * budget of visible milliseconds is not that. Passing a bare number is
+ * `{ timeoutMs }`, which is what every existing caller does.
  */
-export interface CaptureWait2DOptions {
-  /** The capture window, in VISIBLE milliseconds (default 10s). */
-  timeoutMs?: number | undefined;
-  /** Injected in tests; defaults to the document's own visibility. */
-  visibility?: VisibilityClock | undefined;
-  /** Live view of the wait while it runs, `null` the moment it ends. */
-  onWait?: ((wait: VisibleCaptureWindow | null) => void) | undefined;
-}
+export type { CaptureWaitOptions };
 
 /** A live Pixi runtime captured from an external PixiJS game. */
 export interface CapturedRuntime2D {
@@ -68,7 +65,7 @@ export interface SceneCapture2DHandle {
    * frame the tab draws after it comes forward is trapped exactly as it would
    * have been at boot. Rejects only when the window is spent while VISIBLE.
    */
-  waitForCapture(options?: number | CaptureWait2DOptions): Promise<CapturedRuntime2D>;
+  waitForCapture(options?: number | CaptureWaitOptions): Promise<CapturedRuntime2D>;
   getDrawCount(): number;
   /** Pause/resume the captured game's own ticker (loop-host gating). */
   setPaused(paused: boolean): void;
@@ -138,7 +135,7 @@ export function installSceneCapture2D(
       else app.ticker.start();
     },
     waitForCapture(options) {
-      const opts: CaptureWait2DOptions =
+      const opts: CaptureWaitOptions =
         typeof options === 'number' ? { timeoutMs: options } : (options ?? {});
       const timeoutMs = opts.timeoutMs ?? 10_000;
       if (captured) return Promise.resolve(captured);

package/src/react/world-state.tsx

@@ -27,10 +27,10 @@ import {
 } from 'react';
 import type { z } from 'zod';
 import type { RootStateObserver } from '../adapter';
+import type { DebugCommandArgs } from '../runtime/debug-registry';
 import { getDebugRegistry } from '../runtime/debug-registry';
 import { createFrameSelectorCache, type Equals, shallow } from '../runtime/frame-selector-cache';
 import type { Game } from '../runtime/game';
-import type { DebugCommandArgs } from '../runtime/types';
 
 /** Re-exported for convenience — the opt-in equality for selectors that
  *  return a fresh object/array/tuple every call (default is `Object.is`). */

package/src/render/light-camera-factory.ts

@@ -1,12 +1,10 @@
 /**
- * Shared light + camera factory (T1.13 — DEFAULTS truth).
+ * Shared light + camera factory — the ONE place light/camera fallbacks are
+ * decided, and it decides them by READING `DEFAULTS.light`/`DEFAULTS.camera`.
  *
- * `createLight`/`createCamera` used to be duplicated verbatim between the
- * runtime loader (`scene-loader.ts`) and the editor preview
- * (`entity-factory.ts`) — both hardcoded the same fallback literals (color
- * '#ffffff', fov 60, near 0.1, far 1000, etc.) that happened to agree with
- * `DEFAULTS.light`/`DEFAULTS.camera` by luck rather than by reading them. Any
- * edit to one copy (or to `DEFAULTS`) could silently diverge from the other.
+ * A second copy hardcoding the same literals (color '#ffffff', fov 60, near
+ * 0.1, far 1000) would agree by luck rather than by construction, and any
+ * edit to either copy — or to `DEFAULTS` — would silently diverge.
  *
  * This module is now the ONE place that builds a `THREE.Light`/`THREE.Camera`
  * from a `LightDescriptor`/`CameraDescriptor` descriptor, reading its fallbacks from
@@ -22,10 +20,9 @@ import * as THREE from 'three';
 // `three/addons/*` alias (package.json `exports`: `"./addons/*":
 // "./examples/jsm/*"` — the identical file as
 // `three/examples/jsm/lights/RectAreaLightUniformsLib.js`) because a literal
-// `/examples/` specifier trips `engine-host-no-game-imports.test.ts`'s
-// game/editor-example guard (a same-substring false positive against this
-// repo's OWN `packages/editor/template/src/examples/` convention, unrelated
-// to three.js's addon folder naming).
+// `/examples/` specifier trips this repo's game/editor-example import guard —
+// a same-substring false positive against our own `src/examples/` convention,
+// unrelated to three.js's addon folder naming.
 import { RectAreaLightUniformsLib } from 'three/addons/lights/RectAreaLightUniformsLib.js';
 import type { CameraDescriptor } from '../asset-formats/camera';
 import type { LightDescriptor } from '../asset-formats/light';

package/src/render/material-factory.ts

@@ -65,7 +65,7 @@ export function createMaterial(mat?: MaterialDescriptor): THREE.Material {
   // R1c — every fallback below reads DEFAULTS.material.* instead of
   // duplicating its value as a bare literal, so DEFAULTS stays the single
   // source of truth for what an omitted field renders as (see
-  // defaults-out-of-scope-consistency.test.ts / material-factory.test.ts's
+  // `material-factory.test.ts`'s
   // "omitted-field" locks, which fail if either copy drifts from the other).
   const dMat = DEFAULTS.material;
   const sideValue = mat.side ?? dMat.side;

package/src/render/render-batch-system.ts

@@ -13,21 +13,29 @@ import { staticBatchSignature } from './structural-signature';
  * N logical objects → 1 draw call, ~0 CPU/frame. This is the classic "static
  * batching" technique (cf. Unity/PlayCanvas static batch groups).
  *
- * Strategy 1 (keep identity, don't merge). Moving entities (boids-style, all-frame churn) are a separate
- * concern — see render/auto-batcher.ts (dynamic).
+ * Strategy 1 (keep identity, don't merge). Moving entities (boids-style,
+ * all-frame churn) are a separate concern, and the engine does not answer it:
+ * a game's production answer is the `static-batch` capability's `<Frozen>`
+ * (see the scope note below).
  *
  * Eligibility (anything failing stays an ordinary draw — degrade, don't break):
  *   - plain THREE.Mesh (not Instanced/Skinned/Batched)
  *   - single, opaque material (transparency needs per-object sorting)
  *   - group of ≥2 sharing (geometry, material, shadow flags)
- *   - not explicitly opted out (`entity.render.autoBatch === false`)
+ *   - (there is no per-entity opt-out setting: this docblock used to name
+ *     `entity.render.autoBatch === false`, a render-feature field NO CODE HERE
+ *     OR ANYWHERE EVER READ. The field was deleted with R-2's coverage fix;
+ *     opting a subtree out is the `static-batch` capability's `<Frozen>`
+ *     declaration, per the scope note below.)
  *   - STATIC members (no physics/components/animation) → detached; MOVING members →
  *     kept in-graph hidden + dirty-synced each frame. A bucket may split into both.
  *
  * Scope / limitations (v1):
- *   - NOT WIRED: nothing in the engine calls build() — the rendering-scale
- *     example's render lab is the only driver (via the hosted-module map), and
- *     no adapter batches automatically. That is settled, not pending: a game's
+ *   - NOT WIRED: nothing in the engine calls build(), and nothing constructs
+ *     this class. The only remaining reference is the hosted editor's
+ *     project-script module map (`editor/src/browser-project-scripts.ts`),
+ *     which loads the module so a project script MAY drive it; the example
+ *     that used to is gone. That is settled, not pending: a game's
  *     production answer is the `static-batch` capability's `<Frozen>`, a
  *     DECLARED mount-static subtree in the game's own TSX, and `dev/static-
  *     batch-advisor.ts` is what routes an author to it by measurement. Full-

package/src/render/render-features.ts

@@ -2,12 +2,23 @@ import { z } from 'zod';
 
 /**
  * The render-feature registry — single source of truth for every togglable render
- * setting. The scene schema (`SceneEnvironment.rendering`, `SceneEntity.render`),
- * the cascade resolver (`resolveRenderSettings`), the editor UI, and the stats
- * overlay are all derived from this list, so "everything togglable" stays
- * consistent by construction (same posture as the component/material/instancer
- * registries). Adding a feature here gives it a schema field + cascade entry for
- * free..
+ * setting. The render-env schema (`asset-formats/render-env.ts`) and the cascade
+ * resolver (`resolveRenderSettings`) are both derived from this list, so
+ * "everything togglable" stays consistent by construction (same posture as the
+ * component/material/instancer registries).
+ *
+ * EVERY ENTRY HERE MUST HAVE A RUNTIME READER of its resolved value, and that is
+ * now enforced: `schema-reader-coverage.test.ts` derives its walk from this
+ * array, so adding a feature adds a described schema path that fails coverage
+ * until `schema-consumption-map.ts` names the file that reads it.
+ *
+ * Three entries were deleted when that enforcement first ran, having reached it
+ * with no reader at all: `autoBatch` (its only mention was a COMMENT in
+ * `render-batch-system.ts`, a class whose own header says nothing calls it),
+ * `lod`, and `backend` (which offered a `webgpu` option while
+ * `setup-renderer.ts` unconditionally constructs a `THREE.WebGLRenderer`). A
+ * toggle that changes nothing is worse than a missing one — it tells an author
+ * the engine has a dial it does not have.
  */
 
 export type RenderFeatureValue = boolean | number | string;
@@ -37,16 +48,6 @@ export interface RenderFeature {
 }
 
 export const RENDER_FEATURES: readonly RenderFeature[] = [
-  {
-    key: 'autoBatch',
-    label: 'Auto-batching',
-    description:
-      'Automatically batch entities sharing geometry+material into one draw call (InstancedMesh/BatchedMesh) while keeping each Object3D as the handle. The headline perf win; opt out per-entity for custom-shader/skinned meshes.',
-    kind: 'toggle',
-    default: true,
-    apply: 'live',
-    perEntity: true,
-  },
   {
     key: 'frustumCulling',
     label: 'Frustum culling',
@@ -56,15 +57,6 @@ export const RENDER_FEATURES: readonly RenderFeature[] = [
     apply: 'live',
     perEntity: true,
   },
-  {
-    key: 'lod',
-    label: 'Level of detail',
-    description: 'Distance-based geometry swap (LOD) for eligible entities.',
-    kind: 'toggle',
-    default: true,
-    apply: 'live',
-    perEntity: true,
-  },
   {
     key: 'shadows',
     label: 'Shadows',
@@ -103,16 +95,6 @@ export const RENDER_FEATURES: readonly RenderFeature[] = [
     apply: 'reload',
     perEntity: false,
   },
-  {
-    key: 'backend',
-    label: 'Renderer backend',
-    description: 'GPU backend: auto picks WebGPU when available, else WebGL2. Applies on reload.',
-    kind: 'enum',
-    default: 'auto',
-    apply: 'reload',
-    perEntity: false,
-    options: ['auto', 'webgl', 'webgpu'],
-  },
 ];
 
 /** Map for O(1) lookup by key. */