@vgai/engine 0.5.2 → 0.5.3

package/src/runtime/presentation.ts

@@ -0,0 +1,141 @@
+/**
+ * runtime/presentation.ts — how a game with a DECLARED resolution is presented in a host panel.
+ *
+ * `vgai.project.json`'s `resolution` is the game's own LOGICAL size: the coordinate space its
+ * cameras frame, its DOM overlay lays out in, and its 2D worlds author positions against. A host
+ * panel is whatever size the user dragged it to, and the two are not the same number.
+ *
+ * The rule, and it is the whole module:
+ *
+ *   **A declared resolution is rendered AT that resolution, and the RESULT is scaled uniformly to
+ *   fit the panel, centered, letterboxed.**
+ *
+ * That is presentation scaling — an OS scaling a game window — and deliberately NOT a stretch mode.
+ * Nothing here reflows the game, changes a camera's aspect, or re-anchors a HUD: the game renders
+ * one shape and the host draws that shape smaller or larger. Every presented root of one project
+ * (a three canvas, a pixi canvas, a dom overlay) therefore shares ONE scaled rect, which is what
+ * keeps a HUD registered over the world beneath it.
+ *
+ * A project that declares no `resolution` is unchanged: the game fills the panel and its cameras
+ * follow the panel's aspect ({@link PRESENTATION_FILL}).
+ *
+ * The math is here, alone and pure, because it had already been written twice inline (the Game
+ * panel's device-preview branch and the story preview's artboard) and a third copy would have been
+ * the one that drifted.
+ */
+
+/** A width/height pair in whatever unit the caller is working in. */
+export interface PresentationSize {
+  readonly width: number;
+  readonly height: number;
+}
+
+/** Where a logical rect lands inside a container, scaled uniformly and centered. */
+export interface PresentationRect {
+  /** Uniform logical→container scale factor. Always finite and > 0. */
+  readonly scale: number;
+  /** The scaled rect's size in container units. */
+  readonly width: number;
+  readonly height: number;
+  /** The letterbox margins — how far in from the container's top-left the scaled rect starts. */
+  readonly offsetX: number;
+  readonly offsetY: number;
+}
+
+function positiveOrZero(value: number): number {
+  return Number.isFinite(value) && value > 0 ? value : 0;
+}
+
+/**
+ * Fit `logical` inside `container`, preserving aspect and centering the result.
+ *
+ * `allowUpscale` is the difference between the two callers this replaces and it is not cosmetic.
+ * A DEVICE PREVIEW must never upscale — the point is to see the device's own pixels, so a phone
+ * frame in a big panel stays phone-sized. A game's DECLARED resolution must upscale, or a 720x540
+ * game sits as a postage stamp in the middle of a maximized panel and the feature reads as broken.
+ *
+ * A degenerate input (zero, negative, NaN — a panel mid-collapse, a manifest with a 0) yields
+ * `scale: 1` and a zero-offset rect rather than an Infinity that would propagate into a CSS
+ * transform.
+ */
+export function fitPresentation(
+  container: PresentationSize,
+  logical: PresentationSize,
+  options: { readonly allowUpscale?: boolean } = {},
+): PresentationRect {
+  const cw = positiveOrZero(container.width);
+  const ch = positiveOrZero(container.height);
+  const lw = positiveOrZero(logical.width);
+  const lh = positiveOrZero(logical.height);
+  if (cw === 0 || ch === 0 || lw === 0 || lh === 0) {
+    return { scale: 1, width: lw, height: lh, offsetX: 0, offsetY: 0 };
+  }
+  const raw = Math.min(cw / lw, ch / lh);
+  const scale = options.allowUpscale === true ? raw : Math.min(raw, 1);
+  const width = lw * scale;
+  const height = lh * scale;
+  return {
+    scale,
+    width,
+    height,
+    offsetX: (cw - width) / 2,
+    offsetY: (ch - height) / 2,
+  };
+}
+
+/** The game fills its panel: no declared resolution, no device preset, today's behaviour. */
+export interface PresentationFill {
+  readonly kind: 'fill';
+}
+
+/** The game renders at a fixed logical size and the host scales the result. */
+export interface PresentationLogical {
+  readonly kind: 'logical';
+  readonly width: number;
+  readonly height: number;
+  /** `device` — a preview preset the user picked; `manifest` — the project's own `resolution`. */
+  readonly source: 'device' | 'manifest';
+  /** Device previews never upscale; a declared resolution does. See {@link fitPresentation}. */
+  readonly allowUpscale: boolean;
+}
+
+export type PresentedSize = PresentationFill | PresentationLogical;
+
+export const PRESENTATION_FILL: PresentationFill = { kind: 'fill' };
+
+/**
+ * Decide what size a game is presented at, from the two things that can ask for one.
+ *
+ * PRECEDENCE: an explicitly PICKED device resolution wins over the manifest's declared one. The
+ * pick is a live act by whoever is looking at the panel ("show me this on a phone"), and a project
+ * setting must not silently override it — otherwise every declared-resolution project would make
+ * the device-preview picker do nothing.
+ */
+export function resolvePresentedSize(
+  picked: { readonly width: number | null; readonly height: number | null },
+  declared?: PresentationSize | undefined,
+): PresentedSize {
+  if (picked.width !== null && picked.height !== null) {
+    return {
+      kind: 'logical',
+      width: picked.width,
+      height: picked.height,
+      source: 'device',
+      allowUpscale: false,
+    };
+  }
+  if (
+    declared !== undefined &&
+    positiveOrZero(declared.width) > 0 &&
+    positiveOrZero(declared.height) > 0
+  ) {
+    return {
+      kind: 'logical',
+      width: declared.width,
+      height: declared.height,
+      source: 'manifest',
+      allowUpscale: true,
+    };
+  }
+  return PRESENTATION_FILL;
+}

package/src/runtime/render-audio-control.ts

@@ -1,39 +1,51 @@
 /**
- * Render-mode AUDIO control seam (I6, `docs/AI-NATIVE-AUTHORING-
- * IMPLEMENTATION-SPEC.md` §15 I6 "Encode and Mux" + the audio-capture half of
- * §13 G4). This is `render-control.ts`'s sibling for the audio side: where
- * that module publishes `window.__vgaiRender` (exact-time seeks + composited
- * frame passes), THIS module publishes `window.__vgaiRenderAudio` — an
- * OPT-IN surface a render-mode page installs only when it declares a Tone
- * score, so `vgai render-cinematic` (`packages/vgai-cli/src/render-
- * cinematic.ts`) can detect "this cinematic has a deterministic audio track"
- * with a single property check (`__vgaiRenderAudio?.hasAudio === true`)
- * rather than needing a schema field threaded through every fixture.
+ * Render-mode AUDIO control seam (I6, "Encode and Mux" + the audio-capture
+ * half of §13 G4). This is `render-control.ts`'s sibling for the audio side:
+ * where that module publishes `window.__vgaiRender` (exact-time seeks +
+ * composited frame passes), THIS module publishes `window.__vgaiRenderAudio` —
+ * an OPT-IN surface a render-mode page installs only when it declares a score,
+ * so `vgai render-cinematic` (`packages/vgai-cli/src/render-cinematic.ts`) can
+ * detect "this cinematic has a deterministic audio track" with a single
+ * property check (`__vgaiRenderAudio?.hasAudio === true`) rather than needing
+ * a schema field threaded through every fixture.
  *
  * Deliberately a SEPARATE global from `__vgaiRender`/`VgaiRenderHarness`
  * (`render-control.ts`), not an extra method bolted onto that interface:
  * every existing render-mode page (I0's `render-cinematic` fixture, I8's
- * `reference-cinematic`) has no Tone score at all, and this keeps their
+ * `reference-cinematic`) has no score at all, and this keeps their
  * bundles/tests completely untouched — `render-control.ts` itself is not
  * modified by this unit.
  *
- * ## Why `renderAudio` takes `(start, end)` and `compose` is a FACTORY
+ * ## What this module is, and what it deliberately is not
  *
- * `Tone.Offline` (via `audio/tone-offline-render.ts`) gives the composition
- * callback LOCAL time 0 at whatever `start` was requested — an offline
- * render of `[10, 10.72)` schedules its first event at LOCAL time 0, not
- * absolute time 10 (see that module's own doc comment). A render-mode page
- * authors its score in ABSOLUTE/canonical time (e.g. "a note at the same
- * t=1.2s the video's Director cut happens"), so the actual Tone-native
- * compose callback passed to `renderToneOffline` must subtract the
- * requested range's `start` from every scheduled event time. Rather than
- * have every fixture re-derive that subtraction inline, this module's
- * {@link RenderAudioControlOptions.compose} is a FACTORY: called once per
- * `renderAudio(start, end)` invocation with `start`, returning the actual
- * `Tone.Offline`-native callback closed over that offset. This is the
- * concrete fix for the G12 review follow-up named in this unit's build
- * brief ("renderToneOffline gives the composition LOCAL time 0 at `start`,
- * so your composition must close over the range/offset").
+ * `window.__vgaiRenderAudio` is a PROTOCOL — the surface the Node-side capture
+ * driver reads through `page.evaluate`, the audio counterpart to a debug
+ * adapter. That is why it stays in the engine. Producing the samples is not a
+ * protocol, so it does not: {@link RenderAudioControlOptions.render} is
+ * supplied by the caller and hands back a native `AudioBuffer`. This module
+ * owns the render-mode gate, the WAV encoding, and the base64 wire format.
+ *
+ * It used to call `renderToneOffline` itself, which put `tone` in the engine's
+ * dependency list for a page that merely wanted to publish a global. The
+ * offline renderer moved to the `music` capability (`src/lib/music/
+ * tone-offline-render.ts`); a fixture composes the two in one line, and a page
+ * scoring with anything else — a pre-rendered WAV decoded into an
+ * `AudioBuffer`, a WebAudio `OfflineAudioContext` graph, another library —
+ * satisfies the same contract without touching Tone at all.
+ *
+ * ## Why `renderAudio` takes `(start, end)` — the offset trap
+ *
+ * An offline render of `[10, 10.72)` schedules its first event at LOCAL time
+ * 0, not absolute time 10. A render-mode page authors its score in
+ * ABSOLUTE/canonical time (e.g. "a note at the same t=1.2s the video's
+ * Director cut happens"), so whatever the caller's `render` does internally
+ * must subtract the requested range's `start` from every scheduled event time.
+ * With Tone that means building the `Tone.Offline` callback per call, closed
+ * over `start` — see `renderToneOffline`'s own doc. This was the G12 review
+ * follow-up named in the unit's build brief ("renderToneOffline gives the
+ * composition LOCAL time 0 at `start`, so your composition must close over the
+ * range/offset"); it is now the caller's to honour, and the capability's
+ * fixture shows it.
  *
  * ## Wire format — why WAV bytes cross as base64, not a raw sample array
  *
@@ -48,22 +60,27 @@
  * logic duplicated on the Node side at all.
  */
 
-import { renderToneOffline, type ToneOfflineComposeFn } from '../audio/tone-offline-render';
 import { encodeWav16, pcmStats } from '../audio/wav-encode';
 import { isRenderModeRequested } from './render-control';
 
-/** Builds the actual `Tone.Offline`-native compose callback for a render
- *  starting at `rangeStart` (absolute/canonical seconds) — see the module
- *  doc's "closes over the range/offset" section above. */
-export type RenderAudioComposeFactory = (rangeStart: number) => ToneOfflineComposeFn;
+/** What a caller's renderer hands back: real PCM in a native `AudioBuffer`.
+ *  `AudioBuffer` — not a vgai type — is the point: any offline audio path in
+ *  the platform already produces one. */
+export interface RenderedAudio {
+  readonly buffer: AudioBuffer;
+  readonly durationSeconds: number;
+}
+
+/** Render `[start, end)` (absolute/canonical seconds) offline and
+ *  deterministically. The offset trap in the module doc is the renderer's to
+ *  honour: identical `(start, end)` on an unchanged score must produce
+ *  identical samples, since the capture driver relies on it. */
+export type OfflineAudioRenderer = (start: number, end: number) => Promise<RenderedAudio>;
 
 export interface RenderAudioControlOptions {
-  /** See {@link RenderAudioComposeFactory}. */
-  readonly compose: RenderAudioComposeFactory;
-  /** Output channel count. Default 2 (stereo) — same default as `tone-offline-render.ts`. */
-  readonly channels?: number;
-  /** Output sample rate. Default 44100 — same default as `tone-offline-render.ts`. */
-  readonly sampleRate?: number;
+  /** See {@link OfflineAudioRenderer}. With the `music` capability this is one
+   *  line over `renderToneOffline`; nothing here knows or cares that it is. */
+  readonly render: OfflineAudioRenderer;
   /** Where to publish the harness. Defaults to the real `window` — override in a unit test. */
   readonly target?: Record<string, unknown>;
   /** Where to read `?vgai-render=1` from. Defaults to `window.location`. */
@@ -88,17 +105,17 @@ export interface RenderAudioResult {
 
 /** The `window.__vgaiRenderAudio` surface. Presence of this global (guarded
  *  by `hasAudio: true`, never a bare `undefined`/`false` value on a present
- *  object) IS the "this cinematic declares a Tone score" signal `render-
+ *  object) IS the "this cinematic declares a score" signal `render-
  *  cinematic.ts` checks — see this module's own top doc comment. */
 export interface VgaiRenderAudioHarness {
   readonly hasAudio: true;
   /** Render `[start, end)` (absolute/canonical seconds, exactly the same
-   *  range `window.__vgaiRender`'s frame walk covers) offline via
-   *  `Tone.Offline`, returning a complete WAV file. Deterministic: identical
-   *  `(start, end)` on an unchanged score produces byte-identical
-   *  `wavBase64` every call (the same `Tone.Offline` determinism
-   *  `tone-offline-render.ts`/G2 already proves — this module adds no
-   *  additional source of nondeterminism). */
+   *  range `window.__vgaiRender`'s frame walk covers), returning a complete
+   *  WAV file. Deterministic: identical `(start, end)` on an unchanged score
+   *  produces byte-identical `wavBase64` every call — this module adds no
+   *  source of nondeterminism, so the property is exactly whatever the
+   *  supplied {@link OfflineAudioRenderer} guarantees (with the `music`
+   *  capability, the `Tone.Offline` determinism G2 already proves). */
   renderAudio(start: number, end: number): Promise<RenderAudioResult>;
 }
 
@@ -119,18 +136,12 @@ export function installRenderAudioHarness(
   if (!isRenderModeRequested(location)) return undefined;
 
   const target = opts.target ?? (window as unknown as Record<string, unknown>);
-  const { compose, channels, sampleRate } = opts;
+  const { render } = opts;
 
   const harness: VgaiRenderAudioHarness = {
     hasAudio: true,
     async renderAudio(start: number, end: number): Promise<RenderAudioResult> {
-      const rendered = await renderToneOffline({
-        start,
-        end,
-        ...(channels !== undefined ? { channels } : {}),
-        ...(sampleRate !== undefined ? { sampleRate } : {}),
-        compose: compose(start),
-      });
+      const rendered = await render(start, end);
       const channelData: Float32Array[] = [];
       for (let ch = 0; ch < rendered.buffer.numberOfChannels; ch++) {
         channelData.push(rendered.buffer.getChannelData(ch));

package/src/runtime/render-control.ts

@@ -1,20 +1,19 @@
 /**
- * Render-control runtime seam (I2, `docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md`
- * §15 I2). This is the harness a deterministic-capture host (Playwright/CDP,
- * I0/I3/I4) drives: exact-time seeks against the canonical
- * `AnimationClock` (`animation/animation-clock.ts`), and single
- * `preRender`+`render` phase passes across every world on a `Game`
- * (`runtime/game.ts`) — WITHOUT ever advancing gameplay fixed-step substeps
- * (`input`/`prePhysics`/`physics`/`postPhysics`/`gameLogic`/`animation` are
- * never invoked by this seam; `--simulate` (I5) is a different, later, path
- * that deliberately drives `game.runFrame(fixedDt)` instead).
+ * Render-control runtime seam (I2). This is the harness a deterministic-capture host
+ * (Playwright/CDP, I0/I3/I4) drives: exact-time seeks against the canonical
+ * `AnimationClock` (`animation/animation-clock.ts`), and single `preRender`+`render`
+ * phase passes across every world on a `Game` (`runtime/game.ts`) — WITHOUT ever
+ * advancing gameplay fixed-step substeps
+ * (`input`/`prePhysics`/`physics`/`postPhysics`/`gameLogic`/`animation` are never
+ * invoked by this seam; `--simulate` (I5) is a different, later, path that
+ * deliberately drives `game.runFrame(fixedDt)` instead).
  *
  * This module does NOT reuse `PlayState.step()` (`Game.play.step()`) — that
  * surface only advances the currently-FROZEN (paused) set of roots and is a
  * whole-call no-op while unpaused (see its doc comment in `runtime/game.ts`);
  * the spec review explicitly flagged it as the wrong seam. `renderOnce`
  * instead walks `game.roots` directly and calls each world's own
- * `WorldFrameHooks.runPhase` for exactly two phases.
+ * `RootFrameHooks.runPhase` for exactly two phases.
  *
  * Also does NOT install anything by default — a caller must explicitly call
  * {@link installRenderControlHarness}, and even then it only actually
@@ -36,7 +35,7 @@
  */
 
 import { SystemPhase } from '../core/types';
-import type { Game, GameInternal, WorldFrameHooks } from './game';
+import type { Game, GameInternal, RootFrameHooks } from './game';
 import { RENDER_MODE_QUERY_PARAM } from './render-seed';
 
 /** Per-subsystem readiness verdict (I2 AC: "Runtime reports asset, shader,
@@ -193,8 +192,8 @@ export interface VgaiRenderHarness {
    * page-declared list (e.g. "live Colyseus networking", "non-seeded ambient
    * audio") this fixture/game names about itself, and (2) any world this
    * seam itself could not frame-gate (a `drivesOwnLoop` world, or a
-   * host-driven world with no `WorldFrameHooks` — the SAME two conditions
-   * {@link renderOnce}'s `renderableWorlds` skips, described here as policy
+   * host-driven world with no `RootFrameHooks` — the SAME two conditions
+   * {@link renderOnce}'s `renderableRoots` skips, described here as policy
    * rather than merely warned about once to the console). Declared entries
    * come first, in declaration order; world-exclusion entries follow, in
    * `game.roots` declaration order.
@@ -222,7 +221,7 @@ export interface VgaiRenderHarness {
    * `PerformanceProfiler` (`dev/performance-profiler.ts`) enabled, sampling
    * it after every frame, then restores the profiler's prior enabled state.
    * Returns per-frame CPU/phase timings + render counters, plus a
-   * structural node/entity count of every threejs/pixijs world's live scene
+   * structural node/entity count of every three/canvas world's live scene
    * graph. NOT a parallel instrumentation layer: every number here comes
    * from the existing profiler (timings, render counters) or the live world
    * roots themselves (counts).
@@ -257,7 +256,7 @@ export interface PerfFrameSample {
 }
 
 /** Per-world structural counts from {@link VgaiRenderHarness.perfSample}. */
-export interface PerfWorldCount {
+export interface PerfRootCount {
   readonly id: string;
   readonly kind: string;
   /** Total scene-graph descendants of the world root (exclusive of the root
@@ -271,9 +270,9 @@ export interface PerfWorldCount {
 
 export interface PerfSampleReport {
   readonly frames: readonly PerfFrameSample[];
-  /** threejs/pixijs worlds only — a react/DOM world has no scene-graph node
+  /** three/canvas worlds only — a react/DOM world has no scene-graph node
    *  count; it is omitted rather than fabricated. */
-  readonly worlds: readonly PerfWorldCount[];
+  readonly worlds: readonly PerfRootCount[];
 }
 
 export interface RenderControlHarnessOptions {
@@ -360,12 +359,12 @@ const RENDER_ONLY_PHASES = [SystemPhase.PRE_RENDER, SystemPhase.RENDER] as const
  * than silently omitted, mirroring this file's "fail loudly, never a silent
  * no-op" convention. A host-driven world with no `frame` (an opaque/foreign
  * mount) is skipped the same way — there is no phase hook to call. Both
- * checks happen ONCE, up front (see {@link renderableWorlds}), not per
+ * checks happen ONCE, up front (see {@link renderableRoots}), not per
  * phase — a world unrenderable in `preRender` is unrenderable in `render`
  * too, so warning twice would just be noise.
  */
 async function renderOnce(game: Game): Promise<void> {
-  const roots = renderableWorlds(game);
+  const roots = renderableRoots(game);
   for (const phase of RENDER_ONLY_PHASES) {
     // Game-scoped systems first, then per-world frame hooks — the SAME order
     // GameInternal.runFrame uses (runtime/game.ts). See doc comment above.
@@ -377,24 +376,20 @@ async function renderOnce(game: Game): Promise<void> {
   await compositionFence();
 }
 
-interface RenderableWorld {
+interface RenderableRoot {
   readonly id: string;
-  readonly frame: WorldFrameHooks;
+  readonly frame: RootFrameHooks;
 }
 
 /** Filter `game.roots` down to the ones {@link renderOnce} can actually
- *  drive (host-driven, with real `WorldFrameHooks`) — see that function's
+ *  drive (host-driven, with real `RootFrameHooks`) — see that function's
  *  doc comment for why an excluded world is warned about loudly, not
  *  silently dropped. */
-function renderableWorlds(game: Game): RenderableWorld[] {
-  const result: RenderableWorld[] = [];
+function renderableRoots(game: Game): RenderableRoot[] {
+  const result: RenderableRoot[] = [];
   for (const world of game.roots) {
     if (world.mounted.drivesOwnLoop) {
-      warnUnrenderable(
-        world.id,
-        'drives its own loop — renderOnce() cannot frame-gate it ' +
-          '(docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §15 I5 names this policy)',
-      );
+      warnUnrenderable(world.id, 'drives its own loop — renderOnce() cannot frame-gate it');
       continue;
     }
     if (!world.frame) {
@@ -416,19 +411,19 @@ function warnUnrenderable(worldLabel: string, reason: string): void {
 }
 
 /**
- * I5 AC 5 policy text for the two conditions {@link renderableWorlds} skips —
+ * I5 AC 5 policy text for the two conditions {@link renderableRoots} skips —
  * shared so {@link VgaiRenderHarness.excludedFromDeterminism} names the SAME
  * roots `renderOnce()` warns about, in the SAME words, rather than
  * maintaining a second, driftable description of the same two checks.
  */
-function computeWorldExclusionReasons(game: Game): string[] {
+function computeRootExclusionReasons(game: Game): string[] {
   const reasons: string[] = [];
   for (const world of game.roots) {
     if (world.mounted.drivesOwnLoop) {
       reasons.push(
         `world "${world.id}" drives its own loop — cannot be frame-gated for deterministic ` +
-          'capture (docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §15 I5 names this policy: ' +
-          'FAIL LOUDLY or be excluded only by an explicit declared policy).',
+          'capture (the policy is to FAIL LOUDLY, or be excluded only by an explicit declared ' +
+          'policy).',
       );
       continue;
     }
@@ -442,11 +437,11 @@ function computeWorldExclusionReasons(game: Game): string[] {
   return reasons;
 }
 
-/** Structural scene-graph walk shared by threejs (`Object3D`) and pixijs
- *  (`Container`) roots — both expose a `children` array, and threejs nodes
+/** Structural scene-graph walk shared by three (`Object3D`) and canvas
+ *  (`Container`) roots — both expose a `children` array, and three nodes
  *  additionally carry `userData` (where the loader/editor entity tag lives).
  *  Deliberately duck-typed so this file keeps its type-only three/pixi rule. */
-function countWorldGraph(root: { readonly children?: readonly unknown[] }): {
+function countRootGraph(root: { readonly children?: readonly unknown[] }): {
   nodes: number;
   entities: number;
 } {
@@ -465,16 +460,16 @@ function countWorldGraph(root: { readonly children?: readonly unknown[] }): {
   return { nodes, entities };
 }
 
-/** See {@link PerfSampleReport.worlds} — threejs/pixijs worlds only; a
+/** See {@link PerfSampleReport.worlds} — three/canvas worlds only; a
  *  react/DOM world has no scene-graph node count and is omitted, never
  *  fabricated. */
-function countWorlds(game: Game): PerfWorldCount[] {
-  const counts: PerfWorldCount[] = [];
+function countRoots(game: Game): PerfRootCount[] {
+  const counts: PerfRootCount[] = [];
   for (const world of game.roots) {
-    if (world.kind === 'threejs') {
-      counts.push({ id: world.id, kind: world.kind, ...countWorldGraph(world.threeRoot()) });
-    } else if (world.kind === 'pixijs') {
-      counts.push({ id: world.id, kind: world.kind, ...countWorldGraph(world.pixiRoot()) });
+    if (world.kind === 'three') {
+      counts.push({ id: world.id, kind: world.kind, ...countRootGraph(world.threeScene()) });
+    } else if (world.kind === 'canvas') {
+      counts.push({ id: world.id, kind: world.kind, ...countRootGraph(world.pixiStage()) });
     }
   }
   return counts;
@@ -581,7 +576,7 @@ export function installRenderControlHarness(
       }
     },
     excludedFromDeterminism(): string[] {
-      return [...declaredExclusions, ...computeWorldExclusionReasons(game)];
+      return [...declaredExclusions, ...computeRootExclusionReasons(game)];
     },
     simulateFixedDt(): number {
       return simulateFixedDt;
@@ -606,7 +601,7 @@ export function installRenderControlHarness(
       } finally {
         profiler.enabled = wasEnabled;
       }
-      return { frames, worlds: countWorlds(game) };
+      return { frames, worlds: countRoots(game) };
     },
   };
 
@@ -617,10 +612,9 @@ export function installRenderControlHarness(
 /**
  * Defensive assertion for the I2 AC "Pixi roots are pinned to the WebGL
  * renderer (not WebGPU) in render mode". In THIS engine that invariant
- * already holds unconditionally — `world2d/pixi-surface.ts`'s
- * `createPixiSurface` hardcodes `preference: 'webgl'` on every
- * `Application.init()` call it makes, and `setup/setup-renderer.ts` never
- * constructs a `WebGPURenderer` for threejs roots either — so there is no
+ * already holds unconditionally — no in-repo mount constructs a Pixi
+ * `Application` with a WebGPU preference, and `setup/setup-renderer.ts` never
+ * constructs a `WebGPURenderer` for three roots either — so there is no
  * live WebGPU code path for a first-party render-mode page to disable.
  * This helper exists for a render-mode installer that mounts a CUSTOM/
  * foreign pixi adapter (`create-runtime.ts`'s `{ module }` pixi path) this
@@ -631,13 +625,13 @@ export function installRenderControlHarness(
  * type-only-pixi rule `runtime/game.ts`/`create-runtime.ts` document for
  * themselves).
  */
-export function assertPixiWorldIsWebGL(rendererType: unknown, worldId: string): void {
+export function assertPixiRootIsWebGL(rendererType: unknown, worldId: string): void {
   const isWebGPU =
     rendererType === 2 || (typeof rendererType === 'string' && /webgpu/i.test(rendererType));
   if (isWebGPU) {
     throw new Error(
       `[render-control] world "${worldId}": Pixi renderer is WebGPU in render mode — ` +
-        'render-control requires WebGL (docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §15 I2).',
+        'render-control requires WebGL.',
     );
   }
 }

package/src/runtime/render-seed.ts

@@ -1,8 +1,7 @@
 /**
- * Deterministic `Math.random` seeding for render-control mode (I2 AC,
- * `docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md` §15 I2: "`Math.random`
- * is deterministically seeded/stubbed page-wide before any game module
- * executes").
+ * Deterministic `Math.random` seeding for render-control mode (I2 AC:
+ * "`Math.random` is deterministically seeded/stubbed page-wide before any
+ * game module executes").
  *
  * Deliberately a ZERO-IMPORT module (no `three`, no other engine file) so
  * its own evaluation is instantaneous — a render-mode entry page loads this

package/src/runtime/state-bridge.ts

@@ -1,36 +1,35 @@
 /**
- * Frame-versioned game state bridge (T7.4 slice 1 — `docs/REACT-STATE-BRIDGE.md`
- * §2, the D7 remainder). Components mutate state on `this` freely during
- * ticks — there is no proxy, no dirty tracking, no event per mutation (Track
- * A: no mirror, no sync layer). So the unit of change a subscriber can
- * observe is the FRAME: `GameInternal.runFrame` bumps `frameVersion` and
- * notifies subscribers at most once, at its tail, AFTER every phase of every
- * world and every world's `endFrame` hook has run (see the wiring in
- * `runtime/game.ts`) — mirroring the D7 "from `gameLogic` onward, every
- * world's post-step state is readable" guarantee, extended to "after the
+ * Frame-versioned game state bridge (T7.4 slice 1, the D7 remainder). Components
+ * mutate state on `this` freely during ticks — there is no proxy, no dirty
+ * tracking, no event per mutation (Track A: no mirror, no sync layer). So the
+ * unit of change a subscriber can observe is the FRAME: `GameInternal.runFrame`
+ * bumps `frameVersion` and notifies subscribers at most once, at its tail, AFTER
+ * every phase of every world and every world's `endFrame` hook has run (see the
+ * wiring in `runtime/game.ts`) — mirroring the D7 "from `gameLogic` onward,
+ * every world's post-step state is readable" guarantee, extended to "after the
  * frame, ALL state is readable".
  *
  * This file is plain, react-free TypeScript any consumer could use — no
  * react import here, or anywhere under `runtime/` (the react-facing
- * `useGameState` hook, which DOES import React, lives at
- * `packages/engine/src/react/game-state.tsx`).
+ * `useWorldState` hook, which DOES import React, lives at
+ * `packages/engine/src/react/world-state.tsx`).
  *
- * SECOND trigger for `bump()` (`Game.registerWorld`, `runtime/game.ts`): the
- * `roots` list is also state a `useGameState` selector can read
+ * SECOND trigger for `bump()` (`Game.registerRoot`, `runtime/game.ts`): the
+ * `roots` list is also state a `useWorldState` selector can read
  * (`g.roots.map(...)`, the T6.2 two-world-compose gate), and it changes
- * OUTSIDE the frame loop — `registerWorld` is called as each world finishes
+ * OUTSIDE the frame loop — `registerRoot` is called as each world finishes
  * mounting, which can happen well before the host's loop has ticked even
  * once. Without an immediate notification here, a selector that first reads
  * `g.roots` before every world has registered stays stuck on that stale
  * snapshot until the next completed frame — which, on a slow/contended host
- * or a backgrounded tab, may be arbitrarily delayed. See `registerWorld`'s
+ * or a backgrounded tab, may be arbitrarily delayed. See `registerRoot`'s
  * own doc comment for the concrete CI failure this closes.
  */
 
-/** Frame-versioned, react-free subscription surface — `docs/REACT-STATE-BRIDGE.md` §2. */
+/** Frame-versioned, react-free subscription surface. */
 export interface GameStateBridge {
   /** Monotonic; bumped once per completed `runFrame`, AND once per
-   *  `Game.registerWorld` call (world-list changes are observable state too
+   *  `Game.registerRoot` call (world-list changes are observable state too
    *  — see this file's module doc comment). Starts at 0 before the first of
    *  either has happened. Never treat this as a literal frame COUNT — only
    *  "did it change" is a contract any consumer may rely on. */
@@ -41,7 +40,7 @@ export interface GameStateBridge {
 }
 
 /** Host-internal extension of {@link GameStateBridge}: adds `bump`, called
- *  both by `GameInternal.runFrame` at its tail AND by `Game.registerWorld`
+ *  both by `GameInternal.runFrame` at its tail AND by `Game.registerRoot`
  *  when the world list changes (see this file's module doc comment). NOT
  *  part of the game-facing `Game.state` surface (typed as the narrower
  *  `GameStateBridge` there) — games/components/hooks never call `bump`