@vgai/engine 0.5.0 → 0.5.2

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

@@ -1,110 +0,0 @@
-/**
- * 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.
- *
- * 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
- * bundles/tests completely untouched — `render-control.ts` itself is not
- * modified by this unit.
- *
- * ## Why `renderAudio` takes `(start, end)` and `compose` is a FACTORY
- *
- * `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").
- *
- * ## Wire format — why WAV bytes cross as base64, not a raw sample array
- *
- * `page.evaluate`'s return value is JSON-serialized; a `Float32Array`/
- * typed-array result would either fail to serialize or be coerced into a
- * verbose `{ "0": ..., "1": ... }` object, and a plain JS number array of
- * (potentially) hundreds of thousands of floats is slow to serialize and
- * bloats the IPC payload. Encoding the FULL WAV file (header + 16-bit PCM
- * data, `audio/wav-encode.ts`) to a single base64 string in-page keeps the
- * Node-side capture driver (`render-cinematic.ts`) to one
- * `Buffer.from(wavBase64, 'base64')` + one `writeFile` — no PCM assembly
- * logic duplicated on the Node side at all.
- */
-import { type ToneOfflineComposeFn } from '../audio/tone-offline-render';
-/** 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;
-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;
-    /** 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`. */
-    readonly location?: {
-        readonly search: string;
-    };
-}
-/** One offline audio render, encoded as a complete WAV file — the exact
- *  shape `render-cinematic.ts`'s capture driver reads back via `page.evaluate`. */
-export interface RenderAudioResult {
-    /** Base64 of a complete little-endian 16-bit-PCM RIFF/WAVE file (see
-     *  `audio/wav-encode.ts`) — decode with `Buffer.from(wavBase64, 'base64')`. */
-    readonly wavBase64: string;
-    readonly sampleRate: number;
-    readonly channels: number;
-    readonly durationSeconds: number;
-    /** RMS/peak over the raw PCM, BEFORE 16-bit quantization — lets a caller
-     *  assert "genuinely non-silent audio, not a muxed-in silent track"
-     *  without re-decoding the WAV it just received. */
-    readonly rms: number;
-    readonly peak: number;
-}
-/** 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-
- *  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). */
-    renderAudio(start: number, end: number): Promise<RenderAudioResult>;
-}
-/**
- * Build (and, when render mode is actually requested, publish) the
- * `window.__vgaiRenderAudio` harness — same AC-4-shaped production
- * protection as `installRenderControlHarness`: even called unconditionally
- * on every boot, this only ever constructs/attaches the harness when
- * `isRenderModeRequested(location)` is true, so a normal production gameplay
- * page never gets `window.__vgaiRenderAudio` (and normal play never
- * re-renders its music through an offline context — that would be a
- * separate, much stranger bug).
- */
-export declare function installRenderAudioHarness(opts: RenderAudioControlOptions): VgaiRenderAudioHarness | undefined;
-//# sourceMappingURL=render-audio-control.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"render-audio-control.d.ts","sourceRoot":"","sources":["../../src/runtime/render-audio-control.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,OAAO,EAAqB,KAAK,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAI5F;;0DAE0D;AAC1D,MAAM,MAAM,yBAAyB,GAAG,CAAC,UAAU,EAAE,MAAM,KAAK,oBAAoB,CAAC;AAErF,MAAM,WAAW,yBAAyB;IACxC,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,yBAAyB,CAAC;IAC5C,2FAA2F;IAC3F,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,oFAAoF;IACpF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,6FAA6F;IAC7F,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CACjD;AAED;mFACmF;AACnF,MAAM,WAAW,iBAAiB;IAChC;mFAC+E;IAC/E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC;;wDAEoD;IACpD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;oEAGoE;AACpE,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IACxB;;;;;;gDAM4C;IAC5C,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CACrE;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,yBAAyB,GAC9B,sBAAsB,GAAG,SAAS,CAoCpC"}

package/dist/runtime/render-audio-control.js

@@ -1,111 +0,0 @@
-/**
- * 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.
- *
- * 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
- * bundles/tests completely untouched — `render-control.ts` itself is not
- * modified by this unit.
- *
- * ## Why `renderAudio` takes `(start, end)` and `compose` is a FACTORY
- *
- * `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").
- *
- * ## Wire format — why WAV bytes cross as base64, not a raw sample array
- *
- * `page.evaluate`'s return value is JSON-serialized; a `Float32Array`/
- * typed-array result would either fail to serialize or be coerced into a
- * verbose `{ "0": ..., "1": ... }` object, and a plain JS number array of
- * (potentially) hundreds of thousands of floats is slow to serialize and
- * bloats the IPC payload. Encoding the FULL WAV file (header + 16-bit PCM
- * data, `audio/wav-encode.ts`) to a single base64 string in-page keeps the
- * Node-side capture driver (`render-cinematic.ts`) to one
- * `Buffer.from(wavBase64, 'base64')` + one `writeFile` — no PCM assembly
- * logic duplicated on the Node side at all.
- */
-import { renderToneOffline } from '../audio/tone-offline-render';
-import { encodeWav16, pcmStats } from '../audio/wav-encode';
-import { isRenderModeRequested } from './render-control';
-/**
- * Build (and, when render mode is actually requested, publish) the
- * `window.__vgaiRenderAudio` harness — same AC-4-shaped production
- * protection as `installRenderControlHarness`: even called unconditionally
- * on every boot, this only ever constructs/attaches the harness when
- * `isRenderModeRequested(location)` is true, so a normal production gameplay
- * page never gets `window.__vgaiRenderAudio` (and normal play never
- * re-renders its music through an offline context — that would be a
- * separate, much stranger bug).
- */
-export function installRenderAudioHarness(opts) {
-    const location = opts.location ?? window.location;
-    if (!isRenderModeRequested(location))
-        return undefined;
-    const target = opts.target ?? window;
-    const { compose, channels, sampleRate } = opts;
-    const harness = {
-        hasAudio: true,
-        async renderAudio(start, end) {
-            const rendered = await renderToneOffline({
-                start,
-                end,
-                ...(channels !== undefined ? { channels } : {}),
-                ...(sampleRate !== undefined ? { sampleRate } : {}),
-                compose: compose(start),
-            });
-            const channelData = [];
-            for (let ch = 0; ch < rendered.buffer.numberOfChannels; ch++) {
-                channelData.push(rendered.buffer.getChannelData(ch));
-            }
-            const wavBytes = encodeWav16({ channelData, sampleRate: rendered.buffer.sampleRate });
-            const stats = pcmStats(channelData);
-            return {
-                wavBase64: uint8ArrayToBase64(wavBytes),
-                sampleRate: rendered.buffer.sampleRate,
-                channels: rendered.buffer.numberOfChannels,
-                durationSeconds: rendered.durationSeconds,
-                rms: stats.rms,
-                peak: stats.peak,
-            };
-        },
-    };
-    target['__vgaiRenderAudio'] = harness;
-    return harness;
-}
-/** Browser-native base64 encode (`btoa`) over a `Uint8Array`, chunked so a
- *  multi-second stereo WAV doesn't blow `String.fromCharCode`'s argument-count
- *  limit in one call. Node has no `btoa` for arbitrary bytes reliably across
- *  versions, but this module only ever runs in the browser (render-mode
- *  pages), matching `tone-offline-render.ts`'s own "browser-only" contract. */
-function uint8ArrayToBase64(bytes) {
-    const CHUNK_SIZE = 0x8000;
-    let binary = '';
-    for (let i = 0; i < bytes.length; i += CHUNK_SIZE) {
-        const chunk = bytes.subarray(i, i + CHUNK_SIZE);
-        binary += String.fromCharCode(...chunk);
-    }
-    return btoa(binary);
-}

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

@@ -1,291 +0,0 @@
-/**
- * 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 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.
- *
- * 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.roots` 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 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
- * 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

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