@vgai/engine 0.2.0 → 0.3.0

package/dist/runtime/mount-manifest.js

@@ -0,0 +1,204 @@
+// D-Z2 (docs/WAVE3-ADAPTER-PLUMBING-DESIGN.md) — the standalone manifest-mount
+// helper: an ENGINE-side generalization of `examples/tri-world/src/main.ts`'s
+// hand-built `WorldMountSpec[]`.
+//
+// `resolveAllWorlds`/`resolveWorldAdapter` (`packages/editor/src/
+// adapter-resolver.ts`) already do this translation for the EDITOR, but they
+// are Vite-coupled by construction (`/@fs/` dynamic imports of project files
+// through the dev server, §0.1/§0.5 of the design doc) — unusable from a
+// plain static build. This module mirrors their per-kind dispatch
+// (`default-three`/`default-pixi`/`default-react`, `{ module }`, `{ ingest }`)
+// but never imports a project file itself: the caller's OWN bundler already
+// resolved whatever module graph the manifest's worlds need, and hands the
+// already-built pieces in via `entries` (keyed by world id) — no `/@fs/`, no
+// dev server, no editor import.
+//
+// Engine-core react/pixi-free discipline (§0.6, mirrored from
+// `create-runtime.ts`'s own documented rule for its `Pixi2DGameAdapter`/
+// `ReactWorldAdapter` type-only imports): this file never value-imports
+// `pixi.js`, `world2d/pixi-game-adapter.ts`, `react`, or `react-dom` — a
+// pixijs or react world's adapter is ALWAYS supplied already-constructed via
+// `entries[id].adapter` (the caller's own module graph built it, exactly like
+// `tri-world`'s original hand-mount built `new PixiSceneGameAdapter(...)` and
+// a hand-rolled `ReactWorldAdapter` itself). Threejs is different: `three`/
+// `VgaiSceneGameAdapter` are already unconditional dependencies of every
+// caller of `createGameRuntime`'s legacy path (this same file's sibling,
+// immediately below in this directory), so building a `VgaiSceneGameAdapter`
+// here for the common scene-driven/`setup`-driven cases adds no NEW bundle
+// weight — only pixi/react are avoided.
+import { fromSetup, VgaiSceneGameAdapter } from '../adapter';
+import { assertNever } from '../adapter/world-kind';
+import { loadGameManifest, } from '../manifest/load';
+import { createGameRuntime, } from './create-runtime';
+// ---------------------------------------------------------------------------
+// Raw-vs-resolved manifest detection
+// ---------------------------------------------------------------------------
+/**
+ * Distinguish an already-`loadGameManifest`d {@link ResolvedGameManifest}
+ * from a raw (pre-Zod-parse) manifest value. The two shapes differ in
+ * exactly one load-bearing way for this check: a `ResolvedWorldEntry.adapter`
+ * is `{ type: 'default' | 'module' | 'ingest', identity, ... }`, while a raw
+ * `WorldEntry.adapter` is the literal string `'default'` or a bare `{module}`/
+ * `{ingest}` object with NO `type`/`identity` fields (`schema.ts`'s
+ * `WorldAdapterSchema`). An empty `worlds` array is treated as "not resolved"
+ * (falls through to `loadGameManifest`, whose own Zod validation reports the
+ * empty-array error, if any, more precisely than a guess here could).
+ */
+function looksAlreadyResolved(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const worlds = value.worlds;
+    if (!Array.isArray(worlds) || worlds.length === 0)
+        return false;
+    return worlds.every((world) => {
+        if (typeof world !== 'object' || world === null)
+            return false;
+        const adapter = world.adapter;
+        if (typeof adapter !== 'object' || adapter === null)
+            return false;
+        const type = adapter.type;
+        return type === 'default' || type === 'module' || type === 'ingest';
+    });
+}
+/**
+ * Exported (E4, docs/unified-world-editor/27-visual-react-editing.md §7) so
+ * `mount-game.ts`'s `mountGameFromManifest` composer can share this exact
+ * raw-vs-resolved detection instead of re-implementing it — the two modules
+ * must always agree on what "already resolved" means.
+ */
+export function resolveManifest(raw) {
+    if (looksAlreadyResolved(raw))
+        return raw;
+    return loadGameManifest(raw);
+}
+// ---------------------------------------------------------------------------
+// Per-kind entry -> adapter resolution (mirrors `resolveWorldAdapter`'s
+// per-identity dispatch, `packages/editor/src/adapter-resolver.ts`)
+// ---------------------------------------------------------------------------
+function resolveThreeAdapter(world, entry) {
+    if (entry?.adapter)
+        return entry.adapter;
+    if (world.adapter.type === 'module') {
+        throw new Error(`mountManifestWorlds: world "${world.id}" (threejs) declares a { module } adapter ` +
+            `("${world.adapter.module}") — mountManifestWorlds never imports an arbitrary module ` +
+            'path itself (no `/@fs/`, no dev server). Import the module yourself and supply the ' +
+            `constructed adapter via entries["${world.id}"] = { kind: 'threejs', adapter }.`);
+    }
+    if (world.adapter.type === 'ingest') {
+        throw new Error(`mountManifestWorlds: world "${world.id}" (threejs) declares an { ingest } adapter — ` +
+            "ingest worlds require the editor's dev-server-backed mount machinery (an EditorStore " +
+            "plus iframe/DOM capture, see adapter-resolver.ts's resolveIngestThreeAdapter) and are " +
+            'not supported by mountManifestWorlds (docs/WAVE3-ADAPTER-PLUMBING-DESIGN.md D-Z7 — no ' +
+            'porting aids, no hosted ingest routes).');
+    }
+    // type === 'default'
+    if (world.entry !== undefined) {
+        if (!entry?.setup) {
+            throw new Error(`mountManifestWorlds: world "${world.id}" (threejs) declares \`entry\` "${world.entry}" ` +
+                `— supply entries["${world.id}"] = { kind: 'threejs', setup } (the entry module's ` +
+                "exported `setup` function) or { kind: 'threejs', adapter } for full control. Got " +
+                `${entry === undefined ? 'no entry at all' : 'an entry with neither `setup` nor `adapter`'}.`);
+        }
+        return fromSetup(world.id, entry.setup);
+    }
+    if (world.scene !== undefined) {
+        return new VgaiSceneGameAdapter({
+            id: world.id,
+            scenePath: world.scene,
+            componentRegistry: entry?.componentRegistry,
+        });
+    }
+    // Unreachable in practice: `load.ts`'s `checkAdapterSceneEntryRules`
+    // requires `scene` or `entry` for every 'default' adapter world at
+    // manifest-load time — see `resolveDefaultThreeAdapter`'s identical guard.
+    throw new Error(`mountManifestWorlds: world "${world.id}" is default-three with neither \`scene\` nor ` +
+        '`entry` — this should have been rejected by manifest validation.');
+}
+function resolvePixiAdapter(world, entry) {
+    if (entry?.adapter)
+        return entry.adapter;
+    throw new Error(`mountManifestWorlds: world "${world.id}" (pixijs) has no entries["${world.id}"] — a pixijs ` +
+        'world always needs a caller-supplied, already-constructed adapter ' +
+        `(entries["${world.id}"] = { kind: 'pixijs', adapter }, e.g. \`new PixiSceneGameAdapter(...)\` ` +
+        "built from your own already-imported '@engine/world2d') — mountManifestWorlds never " +
+        "value-imports pixi.js (mirrors create-runtime.ts's own pixi-free-core discipline).");
+}
+function resolveReactAdapter(world, entry) {
+    if (entry?.adapter)
+        return entry.adapter;
+    throw new Error(`mountManifestWorlds: world "${world.id}" (react) has no entries["${world.id}"] — a react ` +
+        'world always needs a caller-supplied, already-constructed `ReactWorldAdapter` ' +
+        `(entries["${world.id}"] = { kind: 'react', adapter }, mounting via your own already-imported ` +
+        'react-dom `createRoot` + your own `<GameProvider>`) — mountManifestWorlds never ' +
+        "value-imports react/react-dom (mirrors create-runtime.ts's own react-free-core discipline; " +
+        'see docs/REACT-STATE-BRIDGE.md §2-3).');
+}
+function buildWorldMountSpec(world, entry) {
+    if (entry !== undefined && entry.kind !== world.kind) {
+        throw new Error(`mountManifestWorlds: entries["${world.id}"] declares kind "${entry.kind}" but the ` +
+            `manifest's world "${world.id}" is kind "${world.kind}" — fix the entries key (or the ` +
+            'manifest) so the two agree.');
+    }
+    const base = {
+        id: world.id,
+        zOrder: world.zOrder,
+        pausable: world.pausable,
+        loop: world.loop,
+    };
+    // `entry`'s `kind` is guaranteed to agree with `world.kind` past the guard
+    // above (or `entry` is `undefined`) — TS can't narrow a `Record` lookup
+    // through that runtime check, so each branch casts to its own entry shape;
+    // the actual safety comes from the mismatch guard, not from the cast.
+    if (world.kind === 'threejs') {
+        const threeEntry = entry;
+        return { ...base, kind: 'threejs', adapter: resolveThreeAdapter(world, threeEntry) };
+    }
+    if (world.kind === 'pixijs') {
+        const pixiEntry = entry;
+        return { ...base, kind: 'pixijs', adapter: resolvePixiAdapter(world, pixiEntry) };
+    }
+    if (world.kind === 'react') {
+        const reactEntry = entry;
+        return { ...base, kind: 'react', adapter: resolveReactAdapter(world, reactEntry) };
+    }
+    // Exhaustiveness guard (§7.4-2, same idiom as `resolveAllWorlds`'s own
+    // dispatch loop): `world.kind` is the closed `WorldEntry['kind']` union
+    // (`z.enum(['threejs','pixijs','react'])`), so a hypothetical 4th kind
+    // must fail to compile here, not silently fall through.
+    return assertNever(world.kind, 'mountManifestWorlds');
+}
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+/**
+ * Mount every world declared by a `vgai.game.json` manifest onto `container`,
+ * standalone — no editor, no dev server. The generalization of
+ * `examples/tri-world/src/main.ts`'s hand-built `WorldMountSpec[]` (D-Z2,
+ * docs/WAVE3-ADAPTER-PLUMBING-DESIGN.md). Reuses the pure `loadGameManifest`
+ * + `createGameRuntime({ worlds })` and mirrors `resolveAllWorlds`'s per-kind
+ * dispatch — but every entry the manifest needs beyond what a `default`-
+ * adapter scene/entry can express on its own comes from the caller's OWN
+ * already-imported module graph (`opts.entries`), never a dynamic import
+ * this file performs itself.
+ *
+ * Degrades loudly (docs/WAVE3-ADAPTER-PLUMBING-DESIGN.md D-Z2): a missing
+ * entry, a kind/shape mismatch, a `{ module }`/`{ ingest }` adapter with no
+ * caller-supplied adapter, or an empty manifest all throw a named `Error`
+ * identifying the world id, its kind, and what was expected — never a silent
+ * skip or a partially-mounted session.
+ */
+export async function mountManifestWorlds(opts) {
+    const manifest = resolveManifest(opts.manifest);
+    if (manifest.worlds.length === 0) {
+        throw new Error('mountManifestWorlds: manifest declares no worlds — nothing to mount.');
+    }
+    const entries = opts.entries ?? {};
+    const worlds = manifest.worlds.map((world) => buildWorldMountSpec(world, entries[world.id]));
+    return createGameRuntime({
+        container: opts.container,
+        worlds,
+        width: opts.width ?? manifest.resolution?.width,
+        height: opts.height ?? manifest.resolution?.height,
+        headless: opts.headless,
+    });
+}

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

@@ -0,0 +1,110 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,111 @@
+/**
+ * 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);
+}