@vgai/engine 0.5.22 → 0.5.24

package/dist/manifest/schema.js

@@ -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'`)
@@ -53,7 +48,7 @@ export const GAME_MANIFEST_VERSION = 2;
 // 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
@@ -75,8 +70,8 @@ const REMOVED_BARE_ADAPTER_SPELLING = {
 };
 function removedSpellingMessage(bad, where) {
     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 ' +
+    return (`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}".`);
 }
@@ -194,28 +189,6 @@ export const RootAdapterSchema = z
                 .describe("How long the host waits for this game's first captured frame before the mount " +
                 '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('Ingest adapter configuration for an unmodified game (a repo-vendored game or your ' +
@@ -257,6 +230,33 @@ export const AdapterRootSchema = z
         "mounts the root's DOM in (`@scope`; packages/editor/server/scoped-game-css.ts), so " +
         "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()
@@ -350,6 +350,7 @@ export const GameManifestSchema = z
             .describe('Exact @vgai/engine semver this game was scaffolded/last upgraded against — an ' +
             'identity pin, not a range'),
     })
+        .strict()
         .describe('Engine version pin'),
     roots: z
         .array(AdapterRootSchema)
@@ -422,20 +423,24 @@ export const GameManifestSchema = z
                 .optional()
                 .describe('Optional editor labels keyed by adapter-root id'),
             groups: z
-                .array(z.object({
+                .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'),
-            }))
+            })
+                .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
@@ -469,6 +474,7 @@ export const GameManifestSchema = z
             .optional()
             .describe('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
@@ -476,6 +482,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
@@ -504,6 +511,7 @@ export const GameManifestSchema = z
             'production builds. Default false: the bridge only installs in dev builds. The ' +
             'runtime reader is the debug-bridge installer (D18).'),
     })
+        .strict()
         .optional()
         .describe('Debug-bridge production gating (D18) — governs whether ?vgai-debug=1 installs ' +
         'window.__vgai outside dev builds.'),
@@ -530,6 +538,7 @@ export const GameManifestSchema = z
             'even higher-precedence explicit config value a host passes directly. Optional — ' +
             "omit to fall back to the runtime's own fixed default seed."),
     })
+        .strict()
         .optional()
         .describe('Seeded-RNG determinism contract (D15) — governs ' +
         'whether ctx.random is boot-seeded from a reproducible seed and whether the ' +
@@ -576,6 +585,7 @@ export const GameManifestSchema = z
             "(the profiler's per-frame render.triangles, from renderer.info). Exact and " +
             '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, ' +
             'maxEntities, maxDrawCalls, maxTriangles) — an empty budget block gates nothing ' +

package/dist/physics/collider-dimensions.d.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
@@ -33,8 +29,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/dist/physics/collider-dimensions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"collider-dimensions.d.ts","sourceRoot":"","sources":["../../src/physics/collider-dimensions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAMpE,MAAM,WAAW,uBAAuB;IACtC,+DAA+D;IAC/D,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,kBAAkB,EAC5B,UAAU,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAC7C,WAAW,EAAE,MAAM,GAClB,uBAAuB,CA4CzB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,EACrD,UAAU,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAC5C,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAItC"}
+{"version":3,"file":"collider-dimensions.d.ts","sourceRoot":"","sources":["../../src/physics/collider-dimensions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAMpE,MAAM,WAAW,uBAAuB;IACtC,+DAA+D;IAC/D,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,kBAAkB,EAC5B,UAAU,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAC7C,WAAW,EAAE,MAAM,GAClB,uBAAuB,CA4CzB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,EACrD,UAAU,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAC5C,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAItC"}

package/dist/physics/collider-dimensions.js

@@ -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
@@ -27,8 +23,8 @@ import { DEFAULTS } from '../defaults';
 const UNIFORM_SCALE_EPSILON = 1e-4;
 /**
  * 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/dist/pixi/scene-capture.d.ts

@@ -17,20 +17,18 @@
  * instance, so it is trapped; a game bundling its own pixi cannot be captured at
  * all, and its mount fails by name.
  */
-import { type VisibilityClock, type VisibleCaptureWindow } from '../adapter/ingest/visible-capture-window';
+import { type CaptureWaitOptions } 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 {
     /** The game's root stage Container. */
@@ -59,7 +57,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;

package/dist/pixi/scene-capture.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scene-capture.d.ts","sourceRoot":"","sources":["../../src/pixi/scene-capture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,oBAAoB,EAC1B,MAAM,0CAA0C,CAAC;AAElD;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,oEAAoE;IACpE,UAAU,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;IACzC,sEAAsE;IACtE,MAAM,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,oBAAoB,GAAG,IAAI,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CACpE;AAED,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IAChC,uCAAuC;IACvC,KAAK,EAAE,OAAO,CAAC;IACf,kCAAkC;IAClC,QAAQ,EAAE,OAAO,CAAC;IAClB,wEAAwE;IACxE,GAAG,EAAE,OAAO,CAAC;CACd;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC5C;;;;;;;;;;;;;;;;OAgBG;IACH,cAAc,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,oBAAoB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACpF,YAAY,IAAI,MAAM,CAAC;IACvB,sEAAsE;IACtE,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC,SAAS,IAAI,IAAI,CAAC;CACnB;AAMD,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,GAAG,SAAS,CAAC;CAChE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,OAAO,EACtB,OAAO,GAAE,qBAA0B,GAClC,oBAAoB,CAmFtB"}
+{"version":3,"file":"scene-capture.d.ts","sourceRoot":"","sources":["../../src/pixi/scene-capture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACL,KAAK,kBAAkB,EAGxB,MAAM,0CAA0C,CAAC;AAElD;;;;;;;;;GASG;AACH,YAAY,EAAE,kBAAkB,EAAE,CAAC;AAEnC,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IAChC,uCAAuC;IACvC,KAAK,EAAE,OAAO,CAAC;IACf,kCAAkC;IAClC,QAAQ,EAAE,OAAO,CAAC;IAClB,wEAAwE;IACxE,GAAG,EAAE,OAAO,CAAC;CACd;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC5C;;;;;;;;;;;;;;;;OAgBG;IACH,cAAc,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAClF,YAAY,IAAI,MAAM,CAAC;IACvB,sEAAsE;IACtE,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC,SAAS,IAAI,IAAI,CAAC;CACnB;AAMD,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,GAAG,SAAS,CAAC;CAChE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,OAAO,EACtB,OAAO,GAAE,qBAA0B,GAClC,oBAAoB,CAmFtB"}

package/dist/react/world-state.d.ts

@@ -18,9 +18,9 @@
 import { type PropsWithChildren } from 'react';
 import type { z } from 'zod';
 import type { RootStateObserver } from '../adapter';
+import type { DebugCommandArgs } from '../runtime/debug-registry';
 import { 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`). */
 export { shallow };

package/dist/react/world-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"world-state.d.ts","sourceRoot":"","sources":["../../src/react/world-state.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAEL,KAAK,iBAAiB,EAMvB,MAAM,OAAO,CAAC;AACf,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,OAAO,EAA4B,KAAK,MAAM,EAAE,OAAO,EAAE,MAAM,iCAAiC,CAAC;AACjG,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD;6EAC6E;AAC7E,OAAO,EAAE,OAAO,EAAE,CAAC;AAInB;;;;;;;;;;;;;;oFAcoF;AACpF,wBAAgB,aAAa,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,iBAAiB,CAAC;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,CAAC,+BAElF;AAED;;mDAEmD;AACnD,wBAAgB,OAAO,IAAI,IAAI,CAQ9B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,IAAI,IAAI,GAAG,IAAI,CAE7C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,CAAC,EAAE,MAAM,GAAE,MAAM,CAAC,CAAC,CAAa,GAAG,CAAC,CAW9F;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,iBAAiB,CAiBlF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,CAAC,EAClC,MAAM,GAAE,MAAM,CAAC,CAAC,CAAa,GAC5B,CAAC,CAoBH;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,OAAO,EACjB,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,YAAY,GAAG,UAAU,CAAA;CAAE,GAC1C,IAAI,CAaN;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,CAAC,CAAC,QAAQ,GAAG,SAAS,GAAG,SAAS,EAC1E,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAA;CAAE,EACrE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAAC,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,GAC/D,IAAI,CAeN;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,KAAK,IAAI,CASxE"}
+{"version":3,"file":"world-state.d.ts","sourceRoot":"","sources":["../../src/react/world-state.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAEL,KAAK,iBAAiB,EAMvB,MAAM,OAAO,CAAC;AACf,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAElE,OAAO,EAA4B,KAAK,MAAM,EAAE,OAAO,EAAE,MAAM,iCAAiC,CAAC;AACjG,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAE5C;6EAC6E;AAC7E,OAAO,EAAE,OAAO,EAAE,CAAC;AAInB;;;;;;;;;;;;;;oFAcoF;AACpF,wBAAgB,aAAa,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,iBAAiB,CAAC;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,CAAC,+BAElF;AAED;;mDAEmD;AACnD,wBAAgB,OAAO,IAAI,IAAI,CAQ9B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,IAAI,IAAI,GAAG,IAAI,CAE7C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,CAAC,EAAE,MAAM,GAAE,MAAM,CAAC,CAAC,CAAa,GAAG,CAAC,CAW9F;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,iBAAiB,CAiBlF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,CAAC,EAClC,MAAM,GAAE,MAAM,CAAC,CAAC,CAAa,GAC5B,CAAC,CAoBH;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,OAAO,EACjB,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,YAAY,GAAG,UAAU,CAAA;CAAE,GAC1C,IAAI,CAaN;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,CAAC,CAAC,QAAQ,GAAG,SAAS,GAAG,SAAS,EAC1E,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAA;CAAE,EACrE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAAC,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,GAC/D,IAAI,CAeN;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,KAAK,IAAI,CASxE"}

package/dist/render/light-camera-factory.d.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

package/dist/render/light-camera-factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"light-camera-factory.d.ts","sourceRoot":"","sources":["../../src/render/light-camera-factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAY/B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAK9D,kEAAkE;AAClE,wBAAgB,WAAW,CAAC,GAAG,EAAE,eAAe,GAAG,KAAK,CAAC,KAAK,CA8C7D;AAED,oEAAoE;AACpE,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,GAAG,KAAK,CAAC,MAAM,CAoBhE"}
+{"version":3,"file":"light-camera-factory.d.ts","sourceRoot":"","sources":["../../src/render/light-camera-factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAW/B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAK9D,kEAAkE;AAClE,wBAAgB,WAAW,CAAC,GAAG,EAAE,eAAe,GAAG,KAAK,CAAC,KAAK,CA8C7D;AAED,oEAAoE;AACpE,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,GAAG,KAAK,CAAC,MAAM,CAoBhE"}

package/dist/render/light-camera-factory.js

@@ -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
@@ -21,10 +19,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 { DEFAULTS } from '../defaults';
 let rectAreaLightUniformsInitialized = false;

package/dist/render/material-factory.js

@@ -54,7 +54,7 @@ export function createMaterial(mat) {
     // 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/dist/render/render-batch-system.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render-batch-system.d.ts","sourceRoot":"","sources":["../../src/render/render-batch-system.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AA6FhE,qBAAa,iBAAiB;IAU1B,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,QAAQ;IAVlB,OAAO,CAAC,IAAI,CAAqB;IACjC,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,aAAa,CAAe;IAEpC,OAAO,CAAC,QAAQ,CAA6C;IAE7D,OAAO,CAAC,SAAS,CAAoD;gBAG3D,KAAK,EAAE,KAAK,CAAC,KAAK,EAClB,QAAQ,EAAE,sBAAsB;IAM1C,wEAAwE;IACxE,KAAK,IAAI,IAAI;IA0Bb,OAAO,CAAC,SAAS;IAyCjB;;;;;OAKG;IACH,MAAM,IAAI,IAAI;IAyBd;;;OAGG;IACH,OAAO,CAAC,SAAS,EAAE,KAAK,CAAC,SAAS,GAAG,KAAK,CAAC,IAAI,GAAG,IAAI;IAStD,kEAAkE;IAClE,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,4DAA4D;IAC5D,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,QAAQ,IAAI,IAAI;CAiBjB"}
+{"version":3,"file":"render-batch-system.d.ts","sourceRoot":"","sources":["../../src/render/render-batch-system.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAqGhE,qBAAa,iBAAiB;IAU1B,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,QAAQ;IAVlB,OAAO,CAAC,IAAI,CAAqB;IACjC,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,aAAa,CAAe;IAEpC,OAAO,CAAC,QAAQ,CAA6C;IAE7D,OAAO,CAAC,SAAS,CAAoD;gBAG3D,KAAK,EAAE,KAAK,CAAC,KAAK,EAClB,QAAQ,EAAE,sBAAsB;IAM1C,wEAAwE;IACxE,KAAK,IAAI,IAAI;IA0Bb,OAAO,CAAC,SAAS;IAyCjB;;;;;OAKG;IACH,MAAM,IAAI,IAAI;IAyBd;;;OAGG;IACH,OAAO,CAAC,SAAS,EAAE,KAAK,CAAC,SAAS,GAAG,KAAK,CAAC,IAAI,GAAG,IAAI;IAStD,kEAAkE;IAClE,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,4DAA4D;IAC5D,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,QAAQ,IAAI,IAAI;CAiBjB"}

package/dist/render/render-features.d.ts

@@ -1,12 +1,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;
 export interface RenderFeature {

package/dist/render/render-features.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render-features.d.ts","sourceRoot":"","sources":["../../src/render/render-features.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;GAQG;AAEH,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAE3D,MAAM,WAAW,aAAa;IAC5B,kDAAkD;IAClD,GAAG,EAAE,MAAM,CAAC;IACZ,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;IACpB,qBAAqB;IACrB,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;IACnC,uDAAuD;IACvD,OAAO,EAAE,kBAAkB,CAAC;IAC5B;;;OAGG;IACH,KAAK,EAAE,MAAM,GAAG,QAAQ,CAAC;IACzB,oFAAoF;IACpF,SAAS,EAAE,OAAO,CAAC;IACnB,sCAAsC;IACtC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,oCAAoC;IACpC,KAAK,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED,eAAO,MAAM,eAAe,EAAE,SAAS,aAAa,EA6EnD,CAAC;AAEF,kCAAkC;AAClC,eAAO,MAAM,qBAAqB,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAEpE,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,GAAE;IAAE,aAAa,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,CAAC,CAAC,UAAU,CAiBtF"}
+{"version":3,"file":"render-features.d.ts","sourceRoot":"","sources":["../../src/render/render-features.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAE3D,MAAM,WAAW,aAAa;IAC5B,kDAAkD;IAClD,GAAG,EAAE,MAAM,CAAC;IACZ,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;IACpB,qBAAqB;IACrB,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;IACnC,uDAAuD;IACvD,OAAO,EAAE,kBAAkB,CAAC;IAC5B;;;OAGG;IACH,KAAK,EAAE,MAAM,GAAG,QAAQ,CAAC;IACzB,oFAAoF;IACpF,SAAS,EAAE,OAAO,CAAC;IACnB,sCAAsC;IACtC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,oCAAoC;IACpC,KAAK,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED,eAAO,MAAM,eAAe,EAAE,SAAS,aAAa,EAgDnD,CAAC;AAEF,kCAAkC;AAClC,eAAO,MAAM,qBAAqB,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAEpE,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,GAAE;IAAE,aAAa,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,CAAC,CAAC,UAAU,CAiBtF"}

package/dist/render/render-features.js

@@ -1,14 +1,5 @@
 import { z } from 'zod';
 export const RENDER_FEATURES = [
-    {
-        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',
@@ -18,15 +9,6 @@ export const RENDER_FEATURES = [
         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',
@@ -64,16 +46,6 @@ export const RENDER_FEATURES = [
         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. */
 export const RENDER_FEATURE_BY_KEY = new Map(RENDER_FEATURES.map((f) => [f.key, f]));

package/dist/runtime/create-runtime.d.ts

@@ -1,16 +1,27 @@
+import { type RootDeclaration } from '../adapter/binding';
 import type { DomHostContext } from '../adapter/host-context';
 import type { MountedPixiRoot, MountedReactRoot, MountedThreeRoot, RootAdapter } from '../adapter/root-adapter';
 import { type Game, type GameInternal, type RootInstance } from './game';
-import type { PlaytestContext } from './types';
+import type { PlaytestContext } from './playtest';
 /**
  * Register a three world onto the Game shell. `opts.id` defaults to
  * `'main'`; multi-root callers pass an explicit id. This is the one
  * registration path for a three world, whatever its id.
  */
-export declare function registerThreeRoot(game: GameInternal, adapter: RootAdapter, mounted: MountedThreeRoot, opts?: {
-    id?: string | undefined;
-    pausable?: boolean | undefined;
-}): RootInstance;
+export declare function registerThreeRoot(game: GameInternal, adapter: RootAdapter, mounted: MountedThreeRoot, opts?: RegisterRootOptions): RootInstance;
+/** What every `register<Surface>Root` takes beyond the mount itself. */
+export interface RegisterRootOptions {
+    readonly id?: string | undefined;
+    readonly pausable?: boolean | undefined;
+    /**
+     * The DECLARATION half of this root's binding, from the resolver that
+     * produced `adapter` (`adapter/binding.ts`). Absent for a bare harness
+     * registration or a `mountManifestRoots` caller who supplied an
+     * already-constructed adapter — see `RootInstance.binding` for why that
+     * legitimately yields `null` rather than a fabricated binding.
+     */
+    readonly declaration?: RootDeclaration | undefined;
+}
 /**
  * Register a canvas world onto the Game shell — the pixi analog of
  * {@link registerThreeRoot}. `adapter` is the seam's own
@@ -18,10 +29,7 @@ export declare function registerThreeRoot(game: GameInternal, adapter: RootAdapt
  * (`AdapterHandle`, `runtime/game.ts`), so this passes through with zero cast.
  * `stage` is the one field every `MountedPixiRoot` actually carries.
  */
-export declare function registerPixiRoot(game: GameInternal, adapter: RootAdapter<'canvas'>, mounted: MountedPixiRoot, opts?: {
-    id?: string | undefined;
-    pausable?: boolean | undefined;
-}): RootInstance;
+export declare function registerPixiRoot(game: GameInternal, adapter: RootAdapter<'canvas'>, mounted: MountedPixiRoot, opts?: RegisterRootOptions): RootInstance;
 /**
  * Register a React world onto the Game shell — the DOM
  * analog of {@link registerThreeRoot}/{@link registerPixiRoot}. A react
@@ -33,10 +41,7 @@ export declare function registerPixiRoot(game: GameInternal, adapter: RootAdapte
  * `registerPixiRoot`'s doc comment above) — `RootInstance.adapter` only
  * needs `.id`, so this passes through with zero cast.
  */
-export declare function registerReactRoot(game: GameInternal, adapter: RootAdapter<'dom'>, mounted: MountedReactRoot, container: HTMLElement, opts?: {
-    id?: string | undefined;
-    pausable?: boolean | undefined;
-}): RootInstance;
+export declare function registerReactRoot(game: GameInternal, adapter: RootAdapter<'dom'>, mounted: MountedReactRoot, container: HTMLElement, opts?: RegisterRootOptions): RootInstance;
 /**
  * One world to mount in the universal host — the host-facing mirror of
  * `manifest/load.ts`'s `ResolvedAdapterRoot` (same identity and presentation
@@ -63,6 +68,14 @@ export interface RootMountSpecBase {
      * `input-router.ts`'s `resolveClaimingRoot`.
      */
     readonly hitTest?: ((x: number, y: number) => boolean) | undefined;
+    /**
+     * The DECLARATION half of this root's binding, from whoever resolved
+     * `adapter` — see `adapter/binding.ts`'s {@link RootDeclaration}. Carried on
+     * the spec because the resolver knows it and the host is the only one who
+     * can complete the binding (it needs `mounted`, which does not exist until
+     * this spec is mounted).
+     */
+    readonly declaration?: RootDeclaration | undefined;
 }
 export interface ThreeRootMountSpec extends RootMountSpecBase {
     readonly kind: 'three';
@@ -89,9 +102,8 @@ export interface PixiRootMountSpec extends RootMountSpecBase {
  * opaque mount with nothing to tick).
  *
  * Deliberately carries NO `firstParty: true` brand: that brand specifically
- * means "has a `.ctx: GameContext`" (`isFirstPartyMounted`,
- * `runtime/game.ts`) — a react world has no Rapier/ComponentManager/
- * GameContext at all, so branding it first-party would be a type lie.
+ * a react world has no physics or component runtime at all, so branding it
+ * first-party would be a type lie.
  * `Game.registerRoot`'s "no state bridge" console warning explicitly exempts
  * `kind: 'dom'` (§7.1-15): a react world has no `observe` BY DESIGN — that
  * hook is scoped to `useRootObservation` (the ingested/foreign-world case),
@@ -125,7 +137,7 @@ export interface ReactRootAdapter extends RootAdapter<'dom'> {
     readonly id: string;
     mount(host: DomHostContext): Promise<MountedReactGame>;
 }
-/** WO-34, same reasoning as {@link PixiRootMountSpec} above: the seam's
+/** Same reasoning as {@link PixiRootMountSpec} above: the seam's
  *  `RootAdapter<'dom'>` is what a DOM root actually guarantees. */
 export interface ReactRootMountSpec extends RootMountSpecBase {
     readonly kind: 'dom';
@@ -149,9 +161,8 @@ export interface RootsRuntimeConfig {
     /**
      * Mirrors `ThreeHostContext.headless` (Node conformance tests — no GPU): skips
      * real `WebGLRenderer` construction for every three world in this
-     * session (a stand-in renderer is used instead, exactly as
-     * `SetupThreeRootAdapter.mount` already special-cases `host.headless`
-     * internally). Pixijs roots are unaffected — Pixi already falls back to
+     * session (a stand-in renderer is used instead; adapters special-case
+     * `host.headless` themselves). Pixijs roots are unaffected — Pixi already falls back to
      * a 2D canvas renderer with no GPU. Never set `true` in a real host.
      */
     headless?: boolean | undefined;
@@ -200,11 +211,9 @@ export interface RootsRuntimeConfig {
 /**
  * Handle returned by createGameRuntime() for controlling the running game.
  *
- * This is the GENERIC host handle — it has no first-party concepts (no
- * `GameContext`, no `GameSetupFn`). First-party features (the live `GameContext`,
- * warm-restart hot reload) are reached through `game.defaultRoot.mounted`
- * and narrowed to `MountedSetupThreeRoot`
- * (the editor does this for HMR/physics-sync — those are inherently first-party).
+ * This is the GENERIC host handle — it has no first-party concepts. A
+ * root's own surface is reached through `game.defaultRoot.mounted`, typed
+ * as the mounted-root contract (`MountedRoot`).
  *
  * Root access is explicit through `game.roots`, `game.world(id)`, and
  * `game.defaultRoot`; the session does not project a surface-specific alias.