@vgai/engine 0.2.0 → 0.3.0

package/dist/runtime/render-control.d.ts

@@ -0,0 +1,291 @@
+/**
+ * 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 type { GameInternal } from './game';
+/** 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 declare function isRenderModeRequested(location: {
+    readonly search: string;
+}): boolean;
+/**
+ * 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 declare function installRenderControlHarness(opts: RenderControlHarnessOptions): VgaiRenderHarness | undefined;
+/**
+ * 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 declare function assertPixiWorldIsWebGL(rendererType: unknown, worldId: string): void;
+//# sourceMappingURL=render-control.d.ts.map

package/dist/runtime/render-control.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-control.d.ts","sourceRoot":"","sources":["../../src/runtime/render-control.ts"],"names":[],"mappings":"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"}

package/dist/runtime/render-control.js

@@ -0,0 +1,264 @@
+/**
+ * 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 { RENDER_MODE_QUERY_PARAM } from './render-seed';
+/** 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) {
+    return new URLSearchParams(location.search).get(RENDER_MODE_QUERY_PARAM) === '1';
+}
+const RENDER_ONLY_PHASES = [SystemPhase.PRE_RENDER, SystemPhase.RENDER];
+/**
+ * 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) {
+    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();
+}
+/** 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) {
+    const result = [];
+    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, reason) {
+    // 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) {
+    const reasons = [];
+    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() {
+    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() {
+    await nextAnimationFrame();
+    await nextAnimationFrame();
+}
+async function resolveHook(hook) {
+    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() {
+    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) {
+    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) {
+    const location = opts.location ?? window.location;
+    if (!isRenderModeRequested(location))
+        return undefined;
+    const { game, clock, readiness = {} } = opts;
+    const target = opts.target ?? window;
+    const frameAdvancers = opts.frameAdvancers ?? [];
+    const simulateFixedDt = opts.simulateFixedDt ?? 1 / 60;
+    const declaredExclusions = opts.excludedFromDeterminism ?? [];
+    const harness = {
+        seek(t) {
+            clock.seek(t);
+        },
+        seekFrame(n, fps) {
+            clock.seekFrame(n, fps);
+        },
+        advanceFrame(dt) {
+            for (const advancer of frameAdvancers)
+                advancer(dt);
+        },
+        renderOnce() {
+            return renderOnce(game);
+        },
+        ready() {
+            return buildReadinessReport(readiness);
+        },
+        simulateSubsteps(steps) {
+            for (let i = 0; i < steps; i++) {
+                game.runFrame(simulateFixedDt);
+            }
+        },
+        excludedFromDeterminism() {
+            return [...declaredExclusions, ...computeWorldExclusionReasons(game)];
+        },
+        simulateFixedDt() {
+            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, worldId) {
+    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/dist/runtime/render-seed.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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 declare function createMulberry32(seed: number): () => number;
+/**
+ * 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 declare function installDeterministicRandom(seed: number): void;
+/** 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 declare const RENDER_MODE_QUERY_PARAM = "vgai-render";
+/** Optional query param to pin a specific seed (default below when absent). */
+export declare const RENDER_SEED_QUERY_PARAM = "vgai-seed";
+/**
+ * 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 declare function maybeInstallRenderModeRandom(location?: {
+    search: string;
+}): boolean;
+//# sourceMappingURL=render-seed.d.ts.map

package/dist/runtime/render-seed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-seed.d.ts","sourceRoot":"","sources":["../../src/runtime/render-seed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,MAAM,CAS3D;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAE7D;AAED;;;mDAGmD;AACnD,eAAO,MAAM,uBAAuB,gBAAgB,CAAC;AACrD,+EAA+E;AAC/E,eAAO,MAAM,uBAAuB,cAAc,CAAC;AAGnD;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,GAAE;IAAE,MAAM,EAAE,MAAM,CAAA;CAAoB,GAC7C,OAAO,CAOT"}