@vgai/engine 0.5.5 → 0.5.6

package/dist/runtime/presentation.d.ts

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

package/dist/runtime/presentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presentation.d.ts","sourceRoot":"","sources":["../../src/runtime/presentation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,qEAAqE;AACrE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,oFAAoF;AACpF,MAAM,WAAW,gBAAgB;IAC/B,qEAAqE;IACrE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+FAA+F;IAC/F,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,gBAAgB,EAC3B,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE;IAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CAAO,GAChD,gBAAgB,CAmBlB;AAED,6FAA6F;AAC7F,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,+EAA+E;AAC/E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,gGAAgG;IAChG,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,UAAU,CAAC;IACvC,8FAA8F;IAC9F,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;CAChC;AAED,MAAM,MAAM,aAAa,GAAG,gBAAgB,GAAG,mBAAmB,CAAC;AAEnE,eAAO,MAAM,iBAAiB,EAAE,gBAAmC,CAAC;AAEpE;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EACzE,QAAQ,CAAC,EAAE,gBAAgB,GAAG,SAAS,GACtC,aAAa,CAwBf"}

package/dist/runtime/presentation.js

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

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

@@ -0,0 +1,126 @@
+/**
+ * Render-mode AUDIO control seam (I6, "Encode and Mux" + the audio-capture
+ * half of §13 G4). This is `render-control.ts`'s sibling for the audio side:
+ * where that module publishes `window.__vgaiRender` (exact-time seeks +
+ * composited frame passes), THIS module publishes `window.__vgaiRenderAudio` —
+ * an OPT-IN surface a render-mode page installs only when it declares a score,
+ * so `vgai render-cinematic` (`packages/vgai-cli/src/render-cinematic.ts`) can
+ * detect "this cinematic has a deterministic audio track" with a single
+ * property check (`__vgaiRenderAudio?.hasAudio === true`) rather than needing
+ * a schema field threaded through every fixture.
+ *
+ * Deliberately a SEPARATE global from `__vgaiRender`/`VgaiRenderHarness`
+ * (`render-control.ts`), not an extra method bolted onto that interface:
+ * every existing render-mode page (I0's `render-cinematic` fixture, I8's
+ * `reference-cinematic`) has no score at all, and this keeps their
+ * bundles/tests completely untouched — `render-control.ts` itself is not
+ * modified by this unit.
+ *
+ * ## What this module is, and what it deliberately is not
+ *
+ * `window.__vgaiRenderAudio` is a PROTOCOL — the surface the Node-side capture
+ * driver reads through `page.evaluate`, the audio counterpart to a debug
+ * adapter. That is why it stays in the engine. Producing the samples is not a
+ * protocol, so it does not: {@link RenderAudioControlOptions.render} is
+ * supplied by the caller and hands back a native `AudioBuffer`. This module
+ * owns the render-mode gate, the WAV encoding, and the base64 wire format.
+ *
+ * It used to call `renderToneOffline` itself, which put `tone` in the engine's
+ * dependency list for a page that merely wanted to publish a global. The
+ * offline renderer moved to the `music` capability (`src/lib/music/
+ * tone-offline-render.ts`); a fixture composes the two in one line, and a page
+ * scoring with anything else — a pre-rendered WAV decoded into an
+ * `AudioBuffer`, a WebAudio `OfflineAudioContext` graph, another library —
+ * satisfies the same contract without touching Tone at all.
+ *
+ * ## Why `renderAudio` takes `(start, end)` — the offset trap
+ *
+ * An offline render of `[10, 10.72)` schedules its first event at LOCAL time
+ * 0, not absolute time 10. A render-mode page authors its score in
+ * ABSOLUTE/canonical time (e.g. "a note at the same t=1.2s the video's
+ * Director cut happens"), so whatever the caller's `render` does internally
+ * must subtract the requested range's `start` from every scheduled event time.
+ * With Tone that means building the `Tone.Offline` callback per call, closed
+ * over `start` — see `renderToneOffline`'s own doc. This was the G12 review
+ * follow-up named in the unit's build brief ("renderToneOffline gives the
+ * composition LOCAL time 0 at `start`, so your composition must close over the
+ * range/offset"); it is now the caller's to honour, and the capability's
+ * fixture shows it.
+ *
+ * ## Wire format — why WAV bytes cross as base64, not a raw sample array
+ *
+ * `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.
+ */
+/** What a caller's renderer hands back: real PCM in a native `AudioBuffer`.
+ *  `AudioBuffer` — not a vgai type — is the point: any offline audio path in
+ *  the platform already produces one. */
+export interface RenderedAudio {
+    readonly buffer: AudioBuffer;
+    readonly durationSeconds: number;
+}
+/** Render `[start, end)` (absolute/canonical seconds) offline and
+ *  deterministically. The offset trap in the module doc is the renderer's to
+ *  honour: identical `(start, end)` on an unchanged score must produce
+ *  identical samples, since the capture driver relies on it. */
+export type OfflineAudioRenderer = (start: number, end: number) => Promise<RenderedAudio>;
+export interface RenderAudioControlOptions {
+    /** See {@link OfflineAudioRenderer}. With the `music` capability this is one
+     *  line over `renderToneOffline`; nothing here knows or cares that it is. */
+    readonly render: OfflineAudioRenderer;
+    /** Where to publish the harness. Defaults to the real `window` — override in a unit test. */
+    readonly target?: Record<string, unknown>;
+    /** Where to read `?vgai-render=1` from. Defaults to `window.location`. */
+    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 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), returning a complete
+     *  WAV file. Deterministic: identical `(start, end)` on an unchanged score
+     *  produces byte-identical `wavBase64` every call — this module adds no
+     *  source of nondeterminism, so the property is exactly whatever the
+     *  supplied {@link OfflineAudioRenderer} guarantees (with the `music`
+     *  capability, the `Tone.Offline` determinism G2 already proves). */
+    renderAudio(start: number, end: number): Promise<RenderAudioResult>;
+}
+/**
+ * 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAKH;;yCAEyC;AACzC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED;;;gEAGgE;AAChE,MAAM,MAAM,oBAAoB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;AAE1F,MAAM,WAAW,yBAAyB;IACxC;iFAC6E;IAC7E,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,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;;;;;;yEAMqE;IACrE,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,CA8BpC"}

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

@@ -0,0 +1,116 @@
+/**
+ * Render-mode AUDIO control seam (I6, "Encode and Mux" + the audio-capture
+ * half of §13 G4). This is `render-control.ts`'s sibling for the audio side:
+ * where that module publishes `window.__vgaiRender` (exact-time seeks +
+ * composited frame passes), THIS module publishes `window.__vgaiRenderAudio` —
+ * an OPT-IN surface a render-mode page installs only when it declares a score,
+ * so `vgai render-cinematic` (`packages/vgai-cli/src/render-cinematic.ts`) can
+ * detect "this cinematic has a deterministic audio track" with a single
+ * property check (`__vgaiRenderAudio?.hasAudio === true`) rather than needing
+ * a schema field threaded through every fixture.
+ *
+ * Deliberately a SEPARATE global from `__vgaiRender`/`VgaiRenderHarness`
+ * (`render-control.ts`), not an extra method bolted onto that interface:
+ * every existing render-mode page (I0's `render-cinematic` fixture, I8's
+ * `reference-cinematic`) has no score at all, and this keeps their
+ * bundles/tests completely untouched — `render-control.ts` itself is not
+ * modified by this unit.
+ *
+ * ## What this module is, and what it deliberately is not
+ *
+ * `window.__vgaiRenderAudio` is a PROTOCOL — the surface the Node-side capture
+ * driver reads through `page.evaluate`, the audio counterpart to a debug
+ * adapter. That is why it stays in the engine. Producing the samples is not a
+ * protocol, so it does not: {@link RenderAudioControlOptions.render} is
+ * supplied by the caller and hands back a native `AudioBuffer`. This module
+ * owns the render-mode gate, the WAV encoding, and the base64 wire format.
+ *
+ * It used to call `renderToneOffline` itself, which put `tone` in the engine's
+ * dependency list for a page that merely wanted to publish a global. The
+ * offline renderer moved to the `music` capability (`src/lib/music/
+ * tone-offline-render.ts`); a fixture composes the two in one line, and a page
+ * scoring with anything else — a pre-rendered WAV decoded into an
+ * `AudioBuffer`, a WebAudio `OfflineAudioContext` graph, another library —
+ * satisfies the same contract without touching Tone at all.
+ *
+ * ## Why `renderAudio` takes `(start, end)` — the offset trap
+ *
+ * An offline render of `[10, 10.72)` schedules its first event at LOCAL time
+ * 0, not absolute time 10. A render-mode page authors its score in
+ * ABSOLUTE/canonical time (e.g. "a note at the same t=1.2s the video's
+ * Director cut happens"), so whatever the caller's `render` does internally
+ * must subtract the requested range's `start` from every scheduled event time.
+ * With Tone that means building the `Tone.Offline` callback per call, closed
+ * over `start` — see `renderToneOffline`'s own doc. This was the G12 review
+ * follow-up named in the unit's build brief ("renderToneOffline gives the
+ * composition LOCAL time 0 at `start`, so your composition must close over the
+ * range/offset"); it is now the caller's to honour, and the capability's
+ * fixture shows it.
+ *
+ * ## Wire format — why WAV bytes cross as base64, not a raw sample array
+ *
+ * `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 { 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 { render } = opts;
+    const harness = {
+        hasAudio: true,
+        async renderAudio(start, end) {
+            const rendered = await render(start, end);
+            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);
+}