@vgai/engine 0.2.0 → 0.3.0

package/src/runtime/render-control.ts

@@ -0,0 +1,522 @@
+/**
+ * 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).
+ *
+ * This module does NOT reuse `PlayState.step()` (`Game.play.step()`) — that
+ * surface only advances the currently-FROZEN (paused) set of worlds 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.worlds` directly and calls each world's own
+ * `WorldFrameHooks.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
+ * publishes `window.__vgaiRender` when the page's URL opts in via
+ * `?vgai-render=1` (AC 4: unavailable/protected in normal production
+ * gameplay unless explicitly enabled). See `render-seed.ts` for the
+ * matching `Math.random` determinism hardening, which must run BEFORE this
+ * module (or any other game module) is even imported.
+ *
+ * I5 (`--simulate` render, §15 I5) is implemented HERE, alongside `renderOnce`:
+ * {@link VgaiRenderHarness.simulateSubsteps} drives `game.runFrame(fixedDt)` a
+ * fixed integer number of times — the FULL fixed-step gameplay frame (every
+ * phase in `PHASE_ORDER`, including `physics`/`gameLogic`/`animation`), unlike
+ * `renderOnce`'s deliberately gameplay-free `preRender`+`render`-only pass.
+ * A caller that never invokes `simulateSubsteps` (the default, sequence-
+ * controlled render — I4) gets byte-identical behavior to before this method
+ * existed: `renderOnce`/`seek`/`seekFrame`/`advanceFrame` are untouched by
+ * this addition.
+ */
+
+import { SystemPhase } from '../core/types';
+import type { Game, GameInternal, WorldFrameHooks } from './game';
+import { RENDER_MODE_QUERY_PARAM } from './render-seed';
+
+/** Per-subsystem readiness verdict (I2 AC: "Runtime reports asset, shader,
+ *  font, Theatre, Tone, and scene readiness"). `not-applicable` is the
+ *  correct answer for any subsystem genuinely absent from a given fixture
+ *  (spec note: "If a subsystem isn't present in the fixture, report it as
+ *  not-applicable rather than failing") — never coerced to `ready`. */
+export type ReadinessStatus = 'ready' | 'not-applicable' | 'error';
+
+export interface ReadinessEntry {
+  readonly status: ReadinessStatus;
+  readonly detail?: string;
+}
+
+/** The full readiness report `ready()` resolves. One entry per subsystem
+ *  named in the I2 AC, always present (never a sparse/optional object) so a
+ *  caller can read every key unconditionally. */
+export interface ReadinessReport {
+  readonly assets: ReadinessEntry;
+  readonly shaders: ReadinessEntry;
+  readonly fonts: ReadinessEntry;
+  readonly theatre: ReadinessEntry;
+  readonly tone: ReadinessEntry;
+  readonly scene: ReadinessEntry;
+}
+
+/**
+ * Caller-supplied per-subsystem readiness checks. Each hook is optional:
+ * absence means that subsystem genuinely does not exist in this fixture/game
+ * (reported `not-applicable`), NOT that it's assumed ready. A hook that
+ * resolves is `ready`; one that throws/rejects is `error` with the message
+ * captured (never silently swallowed, never escalated to fail the whole
+ * `ready()` call — one subsystem's failure must not hide the others' status).
+ * `fonts` has no hook slot: it is always checked directly against
+ * `document.fonts.ready` (universally meaningful in a browser render page),
+ * matching the AC's explicit `document.fonts.ready` callout.
+ */
+export interface RenderReadinessHooks {
+  assets?(): Promise<void> | void;
+  shaders?(): Promise<void> | void;
+  theatre?(): Promise<void> | void;
+  tone?(): Promise<void> | void;
+  scene?(): Promise<void> | void;
+}
+
+/** The minimal clock surface this seam drives — `AnimationClock`'s `seek`/
+ *  `seekFrame` (`animation/animation-clock.ts`). Typed narrowly (not
+ *  imported as a value) so this module never depends on the clock's full
+ *  surface, just the two methods the render seam actually calls. */
+export interface SeekableClock {
+  seek(t: number): unknown;
+  seekFrame(n: number, fps: number): unknown;
+}
+
+/**
+ * I8 render-integration seam: a per-frame, fixed-`dt` advance hook — exactly
+ * the engine's `SystemFn` shape (`core/types.ts`) — for a
+ * cinematic-participating system whose live-gameplay driver `renderOnce()`
+ * deliberately bypasses. The motivating case is `bindXStateAnimation`'s
+ * `tick` (`animation/xstate-animation-binding.ts`, E2): in live play it
+ * rides the fixed-step `'animation'` phase
+ * (`ctx.systems.add(SystemPhase.ANIMATION, binding.tick)`), but
+ * `renderOnce()` (I2) runs ONLY `preRender`+`render` — the `'animation'`
+ * phase, along with every other gameplay phase, is never touched by design
+ * (see this module's top doc comment). Without a distinct advance hook, an
+ * `AnimationMixer` driven this way would sit frozen for the entire render:
+ * nothing would ever call `mixer.update(dt)`. `advanceFrame` (below) is that
+ * hook — a small, explicit registry of `FrameAdvancer`s a render-mode page
+ * opts into via {@link RenderControlHarnessOptions.frameAdvancers}, invoked
+ * in registration order.
+ */
+export type FrameAdvancer = (dt: number) => void;
+
+/** The `window.__vgaiRender` surface (I2 AC, extended by I8's `advanceFrame`).
+ *  Every method here is synchronous except the two that genuinely need to
+ *  wait on the browser (composited render completion, async readiness
+ *  probes). */
+export interface VgaiRenderHarness {
+  /** Evaluate Theatre/registered-GSAP/cinematic-participating evaluators at
+   *  exact time `t` (seconds) via `clock.seek(t)` — never advances gameplay
+   *  substeps. Synchronous: the clock's subscribed evaluators run inline,
+   *  before this call returns. */
+  seek(t: number): void;
+  /** Exact-frame variant — `clock.seekFrame(n, fps)`, i.e. `start + n/fps`,
+   *  bit-exact and drift-free across repeated calls. Same no-substep
+   *  semantics as {@link seek}. */
+  seekFrame(n: number, fps: number): void;
+  /**
+   * I8 render-integration seam: advance every registered
+   * {@link FrameAdvancer} (e.g. an XState/`AnimationMixer` binding's `tick`)
+   * by exactly `dt` seconds, in registration order. A render-mode capture
+   * loop calls this ONCE per OUTPUT frame, with `dt = 1 / fps`, BEFORE
+   * `seekFrame`/`renderOnce` for that frame — see
+   * `packages/vgai-sdk/src/render/render-cinematic.ts`'s `captureFrames`, which
+   * drives exactly this sequence. `advanceFrame` is a genuinely
+   * FORWARD-ONLY, INCREMENTAL tick (it has no notion of "time" to seek
+   * to — it only knows "advance by `dt` more") — unlike {@link seek}/
+   * {@link seekFrame}, which are absolute and idempotent, calling
+   * `advanceFrame` twice never undoes or re-derives a prior call, it always
+   * accumulates. This composes correctly with I4's default sequence-
+   * controlled render (and I8's reference cinematic) specifically BECAUSE
+   * that capture loop only ever walks output frames monotonically forward
+   * (`n = 0, 1, 2, ...`); it is NOT safe to call from a scrubber/editor
+   * preview that seeks backward or re-visits a frame — a caller that needs
+   * that (a future `--simulate`/preview seam) must not reuse this hook as-is.
+   * A no-op when no advancers are registered (the default), so this method
+   * is always present and always safe to call even for a fixture with
+   * nothing to advance (e.g. the I0 `render-cinematic` fixture).
+   */
+  advanceFrame(dt: number): void;
+  /** Runs exactly one `preRender`+`render` phase pass across every
+   *  host-driven world on the `Game` (z-order is a DOM/canvas-stacking
+   *  concern already handled by `create-runtime.ts`'s surface stack — this
+   *  call does not need to reorder anything to composite correctly), then
+   *  resolves after a double-`requestAnimationFrame` composition fence. */
+  renderOnce(): Promise<void>;
+  /** Resolves once every declared subsystem has reported in (see
+   *  {@link ReadinessReport}). */
+  ready(): Promise<ReadinessReport>;
+  /**
+   * I5 `--simulate` seam: advance the FULL fixed-step gameplay frame
+   * (`game.runFrame(fixedDt)` — every phase in `PHASE_ORDER`: input,
+   * prePhysics, physics, postPhysics, gameLogic, animation, preRender,
+   * render) exactly `steps` times, synchronously, in a tight loop. This is
+   * what makes physics/gameplay/AI/particles/participating-audio evolve
+   * BETWEEN captured output frames under `--simulate` — every real gameplay
+   * phase runs, unlike {@link renderOnce} (which runs ONLY `preRender`+
+   * `render`, by design, for the I4 sequence-controlled default) or
+   * {@link advanceFrame} (which ticks only registered {@link FrameAdvancer}s,
+   * never a gameplay phase).
+   *
+   * `fixedDt` is fixed for the lifetime of this harness (see
+   * {@link RenderControlHarnessOptions.simulateFixedDt}, default `1/60` —
+   * the same fixed timestep every real host's `createGameLoop` config
+   * uses) — callers choose HOW MANY substeps to run per captured frame
+   * (`steps`), not the substep's own `dt`, matching the I5 AC's "a fixed
+   * integer number of times per output frame" wording exactly.
+   *
+   * A capture loop that wants BOTH a warmup period (I5 AC: "simulation
+   * state can warm up before the capture range") and per-frame substeps
+   * calls this twice: once with the warmup step count before frame 0, then
+   * once per captured frame with the per-frame step count — there is no
+   * separate "warmup" method, because warmup is just simulateSubsteps called
+   * before the capture loop starts (see `render-cinematic.ts`'s
+   * `captureFrames`, which drives exactly this sequence for `--simulate`
+   * requests).
+   */
+  simulateSubsteps(steps: number): void;
+  /**
+   * I5 AC 5 ("the render report names every subsystem excluded from
+   * deterministic participation"): every subsystem NOT participating in
+   * deterministic capture, computed fresh on every call from two sources —
+   * (1) `RenderControlHarnessOptions.excludedFromDeterminism`, a static,
+   * 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
+   * rather than merely warned about once to the console). Declared entries
+   * come first, in declaration order; world-exclusion entries follow, in
+   * `game.worlds` declaration order.
+   */
+  excludedFromDeterminism(): string[];
+  /**
+   * I7 fold-in (I5 nit): the ACTUAL fixed substep `dt` (seconds) this
+   * harness passes to every `game.runFrame(fixedDt)` call inside
+   * {@link simulateSubsteps} — i.e. `RenderControlHarnessOptions.simulateFixedDt`,
+   * resolved with its own `1/60` default already applied. Exists so the
+   * render pipeline (`render-cinematic.ts`'s `RenderManifestSimulate
+   * .fixedTimestep`) can report the REAL value a fixture is using instead of
+   * assuming every fixture matches the harness's own default — a fixture
+   * that configures a different `simulateFixedDt` (a different Rapier/
+   * physics substep) now shows up correctly in the render manifest rather
+   * than a silently wrong hardcoded `1/60`.
+   */
+  simulateFixedDt(): number;
+}
+
+export interface RenderControlHarnessOptions {
+  /**
+   * `GameInternal` (not just the game-facing `Game`) — this harness is
+   * itself a host (the render/capture driver), and I5's
+   * {@link VgaiRenderHarness.simulateSubsteps} needs the host-only
+   * `runFrame` surface (`runtime/game.ts`'s `GameInternal.runFrame` doc
+   * comment: "the host loop ... and `GameSession.step()` are the only
+   * callers"). Every real call site already holds a `GameInternal` (the
+   * direct return of `createGame(...)`), so this is not a new construction
+   * requirement, just a narrower declared type than before I5.
+   */
+  readonly game: GameInternal;
+  readonly clock: SeekableClock;
+  readonly readiness?: RenderReadinessHooks;
+  /** Where to publish the harness. Defaults to the real `window` — override
+   *  in a unit test to avoid touching the global object. */
+  readonly target?: Record<string, unknown>;
+  /** Where to read `?vgai-render=1` from. Defaults to `window.location`. */
+  readonly location?: { readonly search: string };
+  /** I8 render-integration seam — see {@link VgaiRenderHarness.advanceFrame}.
+   *  Zero or more `FrameAdvancer`s invoked, in array order, on every
+   *  `harness.advanceFrame(dt)` call. Default `[]` (no-op), which is exactly
+   *  what a fixture with nothing gameplay-phase-driven (e.g. I0's fixture)
+   *  needs — `advanceFrame` is still present on the harness, it just has
+   *  nothing to do. */
+  readonly frameAdvancers?: readonly FrameAdvancer[];
+  /**
+   * I5 `--simulate` seam: the fixed substep `dt` (seconds)
+   * {@link VgaiRenderHarness.simulateSubsteps} passes to every
+   * `game.runFrame(fixedDt)` call. Default `1/60` — the same fixed timestep
+   * every real host's `createGameLoop` config uses (`create-runtime.ts`), so
+   * a `--simulate` fixture's Rapier world (whose own `integrationParameters.dt`
+   * defaults to `1/60`) stays in lockstep with the gameplay substep unless a
+   * fixture deliberately configures both to a different, still-matching,
+   * value.
+   */
+  readonly simulateFixedDt?: number;
+  /**
+   * I5 AC 5 — see {@link VgaiRenderHarness.excludedFromDeterminism}. A
+   * static, page-declared list of subsystems this fixture/game has that do
+   * NOT participate in deterministic capture (e.g. live networking,
+   * non-seeded ambient audio) — named here as an explicit, reviewable
+   * policy rather than silently dropped. Default `[]` (nothing to declare —
+   * correct for a fixture with no such subsystem).
+   */
+  readonly excludedFromDeterminism?: readonly string[];
+}
+
+/** Shared by {@link installRenderControlHarness} and any caller that wants
+ *  to check the opt-in flag before doing render-mode-only setup work (e.g.
+ *  `render-seed.ts`'s own gate uses the same query param name). */
+export function isRenderModeRequested(location: { readonly search: string }): boolean {
+  return new URLSearchParams(location.search).get(RENDER_MODE_QUERY_PARAM) === '1';
+}
+
+const RENDER_ONLY_PHASES = [SystemPhase.PRE_RENDER, SystemPhase.RENDER] as const;
+
+/**
+ * Run exactly one `preRender`+`render` phase pass across every host-driven
+ * (`!drivesOwnLoop`) world on `game`, then await the GPU/DOM composition
+ * fence. This is the ENTIRE frame this call drives — no `input`,
+ * `prePhysics`, `physics`, `postPhysics`, `gameLogic`, or `animation` phase
+ * is ever touched, which is what makes this safe to call from a paused-or-
+ * stopped clock without silently ticking gameplay. Phases are run as global
+ * barriers across worlds (mirroring `GameInternal.runFrame`'s own phase-then-
+ * world nesting in `runtime/game.ts`): every world's `preRender` runs before
+ * any world's `render`, in `game.worlds` declaration order.
+ *
+ * Ordering within a phase mirrors `GameInternal.runFrame` EXACTLY (see its
+ * doc comment in `runtime/game.ts`): the game-scoped `SystemRunner`
+ * (`game.systems`) runs FIRST, before any world's frame hooks. `game.systems`
+ * is empty for every game today (nothing registers against it yet), so this
+ * is a no-op in practice — but a later slice that registers a Game-scoped
+ * `preRender`/`render` system (e.g. a cinematic camera crossfade that must
+ * paint once per captured frame) would otherwise be silently MISSED by
+ * capture while running fine in live playback, since live playback goes
+ * through `runFrame`. Running it here keeps the seam a faithful subset of
+ * `runFrame`'s phase pass, not a divergent one.
+ *
+ * A `drivesOwnLoop` world (self-driven, raw-rAF) has no phase hooks this
+ * seam can drive — it is skipped with a loud, once-per-call warning rather
+ * 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
+ * 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 worlds = renderableWorlds(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.
+    game.systems.runPhase(phase, 0);
+    for (const world of worlds) {
+      world.frame.runPhase(phase, 0);
+    }
+  }
+  await compositionFence();
+}
+
+interface RenderableWorld {
+  readonly id: string;
+  readonly frame: WorldFrameHooks;
+}
+
+/** Filter `game.worlds` down to the ones {@link renderOnce} can actually
+ *  drive (host-driven, with real `WorldFrameHooks`) — 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[] = [];
+  for (const world of game.worlds) {
+    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)',
+      );
+      continue;
+    }
+    if (!world.frame) {
+      warnUnrenderable(
+        world.id,
+        `(kind: ${world.kind}) has no phase hooks — renderOnce() cannot drive it (opaque/foreign ` +
+          'mount with no frame-gated entry point)',
+      );
+      continue;
+    }
+    result.push({ id: world.id, frame: world.frame });
+  }
+  return result;
+}
+
+function warnUnrenderable(worldLabel: string, reason: string): void {
+  // biome-ignore lint/suspicious/noConsole: structured, greppable — mirrors runtime/game.ts's own direct console.warn idiom for "cannot gate this world" capability shortfalls.
+  console.warn(`[render-control] world "${worldLabel}" ${reason}.`);
+}
+
+/**
+ * I5 AC 5 policy text for the two conditions {@link renderableWorlds} skips —
+ * shared so {@link VgaiRenderHarness.excludedFromDeterminism} names the SAME
+ * worlds `renderOnce()` warns about, in the SAME words, rather than
+ * maintaining a second, driftable description of the same two checks.
+ */
+function computeWorldExclusionReasons(game: Game): string[] {
+  const reasons: string[] = [];
+  for (const world of game.worlds) {
+    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).',
+      );
+      continue;
+    }
+    if (!world.frame) {
+      reasons.push(
+        `world "${world.id}" (kind: ${world.kind}) has no phase hooks — an opaque/foreign mount ` +
+          'with no frame-gated entry point cannot participate in deterministic capture.',
+      );
+    }
+  }
+  return reasons;
+}
+
+function nextAnimationFrame(): Promise<void> {
+  return new Promise((resolve) => {
+    requestAnimationFrame(() => resolve());
+  });
+}
+
+/**
+ * GPU/DOM composition fence (I2 AC: "waits for GPU/DOM composition
+ * (double-rAF fence ... ) rather than an arbitrary sleep"). Two nested
+ * `requestAnimationFrame` callbacks: the first fires once the browser has
+ * scheduled a new frame after our `render()` calls above; the second fires
+ * once THAT frame has itself been produced and composited — by the time the
+ * second callback runs, the compositor has committed the frame our render
+ * calls painted, so a screenshot taken immediately after this resolves
+ * reflects the seeked state, not a stale one. (The CDP screenshot
+ * compositor-commit wait itself is the capture host's job — I0/I3 — this
+ * fence is the runtime-side half.)
+ */
+async function compositionFence(): Promise<void> {
+  await nextAnimationFrame();
+  await nextAnimationFrame();
+}
+
+async function resolveHook(
+  hook: (() => Promise<void> | void) | undefined,
+): Promise<ReadinessEntry> {
+  if (!hook) return { status: 'not-applicable' };
+  try {
+    await hook();
+    return { status: 'ready' };
+  } catch (err) {
+    return { status: 'error', detail: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+async function checkFontsReady(): Promise<ReadinessEntry> {
+  if (typeof document === 'undefined' || !document.fonts) return { status: 'not-applicable' };
+  try {
+    await document.fonts.ready;
+    return { status: 'ready' };
+  } catch (err) {
+    return { status: 'error', detail: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+async function buildReadinessReport(hooks: RenderReadinessHooks): Promise<ReadinessReport> {
+  const [assets, shaders, fonts, theatre, tone, scene] = await Promise.all([
+    resolveHook(hooks.assets),
+    resolveHook(hooks.shaders),
+    checkFontsReady(),
+    resolveHook(hooks.theatre),
+    resolveHook(hooks.tone),
+    resolveHook(hooks.scene),
+  ]);
+  return { assets, shaders, fonts, theatre, tone, scene };
+}
+
+/**
+ * Build (and, when render mode is actually requested, publish) the
+ * `window.__vgaiRender` harness. AC 4 — production protection — lives HERE,
+ * not just at the call site: even if a host application calls this
+ * unconditionally on every boot, the harness is only ever constructed *and*
+ * attached to `target` when `isRenderModeRequested(location)` is true;
+ * otherwise this is a no-op that returns `undefined`. A normal production
+ * gameplay page therefore never gets `window.__vgaiRender` no matter how
+ * this function is wired into its entry point.
+ */
+export function installRenderControlHarness(
+  opts: RenderControlHarnessOptions,
+): VgaiRenderHarness | undefined {
+  const location = opts.location ?? window.location;
+  if (!isRenderModeRequested(location)) return undefined;
+
+  const { game, clock, readiness = {} } = opts;
+  const target = opts.target ?? (window as unknown as Record<string, unknown>);
+  const frameAdvancers = opts.frameAdvancers ?? [];
+  const simulateFixedDt = opts.simulateFixedDt ?? 1 / 60;
+  const declaredExclusions = opts.excludedFromDeterminism ?? [];
+
+  const harness: VgaiRenderHarness = {
+    seek(t: number): void {
+      clock.seek(t);
+    },
+    seekFrame(n: number, fps: number): void {
+      clock.seekFrame(n, fps);
+    },
+    advanceFrame(dt: number): void {
+      for (const advancer of frameAdvancers) advancer(dt);
+    },
+    renderOnce(): Promise<void> {
+      return renderOnce(game);
+    },
+    ready(): Promise<ReadinessReport> {
+      return buildReadinessReport(readiness);
+    },
+    simulateSubsteps(steps: number): void {
+      for (let i = 0; i < steps; i++) {
+        game.runFrame(simulateFixedDt);
+      }
+    },
+    excludedFromDeterminism(): string[] {
+      return [...declaredExclusions, ...computeWorldExclusionReasons(game)];
+    },
+    simulateFixedDt(): number {
+      return simulateFixedDt;
+    },
+  };
+
+  target['__vgaiRender'] = harness;
+  return harness;
+}
+
+/**
+ * Defensive assertion for the I2 AC "Pixi worlds 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 worlds 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
+ * engine did not construct itself, to assert the invariant against the
+ * live mounted renderer rather than merely trusting it. Duck-typed against
+ * pixi.js v8's numeric `RendererType` (`WEBGL = 1`, `WEBGPU = 2`,
+ * `CANVAS = 4`) so this file never value-imports `pixi.js` (the same
+ * type-only-pixi rule `runtime/game.ts`/`create-runtime.ts` document for
+ * themselves).
+ */
+export function assertPixiWorldIsWebGL(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).',
+    );
+  }
+}

package/src/runtime/render-seed.ts

@@ -0,0 +1,79 @@
+/**
+ * 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").
+ *
+ * Deliberately a ZERO-IMPORT module (no `three`, no other engine file) so
+ * its own evaluation is instantaneous — a render-mode entry page loads this
+ * as its FIRST `<script type="module">` tag, before the tag that pulls in
+ * the actual game/runtime modules. Per the HTML module-script ordering
+ * rules, sibling `<script type="module">` tags without `async` execute in
+ * document order, and each one's own dependency graph (here, empty) is
+ * fully evaluated before the browser moves to the next tag — so calling
+ * {@link maybeInstallRenderModeRandom} from this module's importer, in a
+ * script tag placed before the game's own entry tag, guarantees every
+ * subsequent module's top-level code (and everything it does at runtime)
+ * observes the seeded generator, never the platform's real
+ * cryptographically-random `Math.random`.
+ *
+ * This module does not decide WHETHER to seed on its own (importing it has
+ * no side effect) — the caller decides, by calling
+ * {@link maybeInstallRenderModeRandom} (query-param gated) or
+ * {@link installDeterministicRandom} (unconditional) from a tiny bootstrap
+ * entry. See `packages/engine/e2e/fixture/render-seed-entry.ts` for the
+ * worked bootstrap this module is designed to be loaded from.
+ */
+
+/**
+ * mulberry32 — a small, fast, deterministic 32-bit PRNG. Not cryptographic;
+ * this is explicitly a determinism tool (reproducible capture), not a
+ * security primitive. Returns a function with the same call signature as
+ * `Math.random` (no arguments, `[0, 1)` float).
+ */
+export function createMulberry32(seed: number): () => number {
+  let state = seed >>> 0;
+  return function mulberry32(): number {
+    state = (state + 0x6d2b79f5) | 0;
+    let t = state;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/**
+ * Replace the global `Math.random` with a seeded, deterministic generator.
+ * Idempotent to call more than once (each call re-seeds from scratch — the
+ * last call wins), which matters for HMR-style re-execution the same way
+ * `main.ts`'s `registerWorldKind` guard does elsewhere in this runtime.
+ */
+export function installDeterministicRandom(seed: number): void {
+  Math.random = createMulberry32(seed);
+}
+
+/** Query-param name that opts a page into render-control mode (I2 AC 4: the
+ *  mode must be unavailable/protected in normal production gameplay unless
+ *  explicitly enabled). Shared with `render-control.ts`'s own production
+ *  guard so both checks agree on the same flag. */
+export const RENDER_MODE_QUERY_PARAM = 'vgai-render';
+/** Optional query param to pin a specific seed (default below when absent). */
+export const RENDER_SEED_QUERY_PARAM = 'vgai-seed';
+const DEFAULT_RENDER_SEED = 0x9e3779b9; // golden-ratio constant — an arbitrary but fixed default
+
+/**
+ * Seed `Math.random` iff the page's URL opts into render mode
+ * (`?vgai-render=1`), reading an optional `?vgai-seed=<int>` override.
+ * Returns whether it seeded, purely for the caller's own diagnostics/log —
+ * the bootstrap entry doesn't need to branch on it.
+ */
+export function maybeInstallRenderModeRandom(
+  location: { search: string } = window.location,
+): boolean {
+  const params = new URLSearchParams(location.search);
+  if (params.get(RENDER_MODE_QUERY_PARAM) !== '1') return false;
+  const seedParam = params.get(RENDER_SEED_QUERY_PARAM);
+  const seed = seedParam !== null && seedParam !== '' ? Number(seedParam) : DEFAULT_RENDER_SEED;
+  installDeterministicRandom(Number.isFinite(seed) ? seed : DEFAULT_RENDER_SEED);
+  return true;
+}

package/src/runtime/types.ts

@@ -2,7 +2,6 @@ import type RAPIER from '@dimforge/rapier3d-compat';
 import type { EffectComposer } from 'postprocessing';
 import type * as THREE from 'three';
 import type { SystemAdapters } from '../adapter/system-adapter';
-import type { AnimGraph } from '../animation/anim-graph';
 import type { AssetCache } from '../assets';
 import type { createSystemRunner } from '../core/system-runner';
 import type { createDebugDraw } from '../dev/debug-draw';
@@ -75,10 +74,6 @@ export interface GameContext {
    *  automatically per frame. Dev-only visualization — not for shipped
    *  visuals. */
   debugDraw: ReturnType<typeof createDebugDraw>;
-  /** Active animation graphs, keyed by their `Object3D`; ticked in the
-   *  `animation` phase. Look up an entity's `AnimGraph` to set params/triggers.
-   *  GLTF/scene-defined graphs register here automatically. */
-  animGraphs: Map<THREE.Object3D, AnimGraph>;
   /** Shared GLTF/texture cache. Use `assets.loadGLTF(...)` etc. to load+cache
    *  models at runtime so repeated loads reuse geometry/material. */
   assets: AssetCache;