@vgai/engine 0.2.0 → 0.4.0-canary.20260715.0

package/src/runtime/mount-manifest.ts

@@ -2,25 +2,25 @@
 // helper: an ENGINE-side generalization of `examples/tri-world/src/main.ts`'s
 // hand-built `WorldMountSpec[]`.
 //
-// `resolveAllWorlds`/`resolveWorldAdapter` (`packages/editor/src/
+// `resolveAllWorlds`/`resolveRootAdapter` (`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
+// resolved whatever module graph the manifest's roots 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
+// `ReactRootAdapter` 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`/
+// a hand-rolled `ReactRootAdapter` 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`
@@ -28,21 +28,25 @@
 // weight — only pixi/react are avoided.
 
 import { fromSetup, VgaiSceneGameAdapter } from '../adapter';
+import { assertNever } from '../adapter/adapter-surface';
 import type { GameAdapter } from '../adapter/game-adapter';
-import { assertNever } from '../adapter/world-kind';
 import {
   loadGameManifest,
+  type ResolvedAdapterRoot,
   type ResolvedGameManifest,
-  type ResolvedWorldEntry,
 } from '../manifest/load';
 import type { ComponentRegistry } from '../scene/component-registry';
 import {
   createGameRuntime,
   type GameSession,
   type Pixi2DGameAdapter,
-  type ReactWorldAdapter,
+  type ReactRootAdapter,
   type WorldMountSpec,
 } from './create-runtime';
+import { type DebugBridgeWindowTarget, maybeInstallDebugBridge } from './debug-bridge';
+import { getDebugRegistry } from './debug-registry';
+import { getGameplayRngTrapControl } from './gameplay-rng-trap';
+import { RENDER_SEED_QUERY_PARAM } from './render-seed';
 import type { GameSetupFn } from './types';
 
 // ---------------------------------------------------------------------------
@@ -96,7 +100,7 @@ export interface PixiMountEntry {
 
 /**
  * A caller-supplied entry for a `kind: 'react'` world — ALWAYS a
- * fully-constructed {@link ReactWorldAdapter} (the caller's own module graph
+ * fully-constructed {@link ReactRootAdapter} (the caller's own module graph
  * calls `createRoot(host.container).render(<GameProvider game={host.game}>
  * <Entry/></GameProvider>)` itself, exactly like `tri-world`'s original
  * hand-mount did). A standalone build has ONE module graph, so there is no
@@ -109,7 +113,7 @@ export interface PixiMountEntry {
  */
 export interface ReactMountEntry {
   readonly kind: 'react';
-  readonly adapter: ReactWorldAdapter;
+  readonly adapter: ReactRootAdapter;
 }
 
 export type MountEntry = ThreeMountEntry | PixiMountEntry | ReactMountEntry;
@@ -143,6 +147,71 @@ export interface MountManifestOptions {
   /** Forwarded to `createGameRuntime` — Node/headless test harnesses only,
    *  never a real host. See `WorldsRuntimeConfig.headless`. */
   readonly headless?: boolean | undefined;
+  /**
+   * Task 2.1 (`docs/ACCEPTANCE-DRIVER-BUILD-PLAN.md`,
+   * `docs/SYNTHETIC-PLAYER-SPEC.md` §3.4): overrides for the `?vgai-debug=1`
+   * bridge `mountManifestWorlds` installs at the tail of every mount — the
+   * engine-owned install point so every standalone project gets it with zero
+   * template edits. Omit both in a real host (defaults to `window.location`/
+   * `window`); a headless test supplies fakes here instead of touching the
+   * global object, mirroring `render-control.ts`'s own `location`/`target`
+   * override precedent.
+   */
+  readonly debugBridge?:
+    | {
+        readonly url?: { readonly search: string } | undefined;
+        readonly window?: DebugBridgeWindowTarget | undefined;
+      }
+    | undefined;
+  /**
+   * D15 (T-D15.1) — the "explicit config" leg of the boot-time seed
+   * precedence (`manifest.determinism.defaultSeed` → `?vgai-seed=` → this),
+   * highest-precedence, for a caller that already knows the exact seed it
+   * wants (a future CLI `--seed`/probe fixture `seed` option, T-D15.6).
+   * Ignored entirely unless the manifest declares
+   * `determinism.seededRandom` — see `resolveDeterminismSeed` below.
+   */
+  readonly seed?: number | undefined;
+  /** Where to read `?vgai-seed=` from for the boot-time seed reader. Same
+   *  override precedent as `debugBridge.url` (defaults to `window.location`
+   *  when a real `window` exists; a headless caller with no override gets no
+   *  query-param seed, same as `maybeInstallDebugBridge`'s own url default). */
+  readonly seedUrl?: { readonly search: string } | undefined;
+}
+
+/**
+ * D15 (T-D15.1) boot-time seed reader — resolves the root seed
+ * `mountManifestWorlds` threads into `createGameRuntime` (and therefore
+ * `createGame`, BEFORE any world's `mount()`/`setup()` runs). Returns
+ * `undefined` when the manifest doesn't declare `determinism.seededRandom`
+ * at all — `?vgai-seed=` and `defaultSeed` are both ignored in that case
+ * (§2.a: "the mount path seeds ctx.random ... iff declared"; an undeclared
+ * project's `ctx.random` still exists, just boots from `createGame`'s own
+ * fixed default, unaffected by the manifest or the URL).
+ *
+ * Precedence when declared (highest wins): `explicitSeed` (a caller-supplied
+ * config value) → `?vgai-seed=<int>` on `url` → `manifest.determinism
+ * .defaultSeed`.
+ */
+export function resolveDeterminismSeed(opts: {
+  readonly determinism: ResolvedGameManifest['determinism'];
+  readonly explicitSeed: number | undefined;
+  readonly url: { readonly search: string } | undefined;
+}): number | undefined {
+  if (opts.determinism?.seededRandom !== true) return undefined;
+  const querySeed = opts.url ? readSeedQueryParam(opts.url) : undefined;
+  return opts.explicitSeed ?? querySeed ?? opts.determinism.defaultSeed;
+}
+
+function readSeedQueryParam(url: { readonly search: string }): number | undefined {
+  const raw = new URLSearchParams(url.search).get(RENDER_SEED_QUERY_PARAM);
+  if (raw === null || raw === '') return undefined;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+function hasRealWindow(): boolean {
+  return typeof window !== 'undefined';
 }
 
 // `mountManifestWorlds` returns the SAME `GameSession` shape
@@ -159,24 +228,24 @@ export type MountedManifestSession = GameSession;
 /**
  * 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`
+ * exactly one load-bearing way for this check: a `ResolvedAdapterRoot.adapter`
  * is `{ type: 'default' | 'module' | 'ingest', identity, ... }`, while a raw
- * `WorldEntry.adapter` is the literal string `'default'` or a bare `{module}`/
+ * `AdapterRoot.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"
+ * `RootAdapterSchema`). An empty `roots` 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: unknown): value is ResolvedGameManifest {
   if (typeof value !== 'object' || value === null) return false;
-  const worlds = (value as { worlds?: unknown }).worlds;
-  if (!Array.isArray(worlds) || worlds.length === 0) return false;
-  return worlds.every((world) => {
+  const roots = (value as { roots?: unknown }).roots;
+  if (!Array.isArray(roots) || roots.length === 0) return false;
+  return roots.every((world) => {
     if (typeof world !== 'object' || world === null) return false;
     const adapter = (world as { adapter?: unknown }).adapter;
     if (typeof adapter !== 'object' || adapter === null) return false;
     const type = (adapter as { type?: unknown }).type;
-    return type === 'default' || type === 'module' || type === 'ingest';
+    return type === 'builtin' || type === 'module' || type === 'ingest';
   });
 }
 
@@ -192,12 +261,12 @@ export function resolveManifest(raw: unknown): ResolvedGameManifest {
 }
 
 // ---------------------------------------------------------------------------
-// Per-kind entry -> adapter resolution (mirrors `resolveWorldAdapter`'s
+// Per-kind entry -> adapter resolution (mirrors `resolveRootAdapter`'s
 // per-identity dispatch, `packages/editor/src/adapter-resolver.ts`)
 // ---------------------------------------------------------------------------
 
 function resolveThreeAdapter(
-  world: ResolvedWorldEntry,
+  world: ResolvedAdapterRoot,
   entry: ThreeMountEntry | undefined,
 ): GameAdapter {
   if (entry?.adapter) return entry.adapter;
@@ -213,7 +282,7 @@ function resolveThreeAdapter(
   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 " +
+        "ingest roots 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).',
@@ -249,7 +318,7 @@ function resolveThreeAdapter(
 }
 
 function resolvePixiAdapter(
-  world: ResolvedWorldEntry,
+  world: ResolvedAdapterRoot,
   entry: PixiMountEntry | undefined,
 ): Pixi2DGameAdapter {
   if (entry?.adapter) return entry.adapter;
@@ -263,13 +332,13 @@ function resolvePixiAdapter(
 }
 
 function resolveReactAdapter(
-  world: ResolvedWorldEntry,
+  world: ResolvedAdapterRoot,
   entry: ReactMountEntry | undefined,
-): ReactWorldAdapter {
+): ReactRootAdapter {
   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` ' +
+      'world always needs a caller-supplied, already-constructed `ReactRootAdapter` ' +
       `(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; " +
@@ -278,13 +347,13 @@ function resolveReactAdapter(
 }
 
 function buildWorldMountSpec(
-  world: ResolvedWorldEntry,
+  world: ResolvedAdapterRoot,
   entry: MountEntry | undefined,
 ): WorldMountSpec {
-  if (entry !== undefined && entry.kind !== world.kind) {
+  if (entry !== undefined && entry.kind !== world.surface) {
     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's root "${world.id}" uses surface "${world.surface}" — fix the entries key (or the ` +
         'manifest) so the two agree.',
     );
   }
@@ -300,23 +369,23 @@ function buildWorldMountSpec(
   // 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') {
+  if (world.surface === 'threejs') {
     const threeEntry = entry as ThreeMountEntry | undefined;
     return { ...base, kind: 'threejs', adapter: resolveThreeAdapter(world, threeEntry) };
   }
-  if (world.kind === 'pixijs') {
+  if (world.surface === 'pixijs') {
     const pixiEntry = entry as PixiMountEntry | undefined;
     return { ...base, kind: 'pixijs', adapter: resolvePixiAdapter(world, pixiEntry) };
   }
-  if (world.kind === 'react') {
+  if (world.surface === 'react') {
     const reactEntry = entry as ReactMountEntry | undefined;
     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
+  // dispatch loop): `world.kind` is the closed `AdapterRoot['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');
+  return assertNever(world.surface, 'mountManifestWorlds');
 }
 
 // ---------------------------------------------------------------------------
@@ -328,7 +397,7 @@ function buildWorldMountSpec(
  * 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
+ * + `createGameRuntime({ roots })` 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
@@ -342,20 +411,83 @@ function buildWorldMountSpec(
  */
 export async function mountManifestWorlds(opts: MountManifestOptions): Promise<GameSession> {
   const manifest = resolveManifest(opts.manifest);
-  if (manifest.worlds.length === 0) {
-    throw new Error('mountManifestWorlds: manifest declares no worlds — nothing to mount.');
+  if (manifest.roots.length === 0) {
+    throw new Error('mountManifestWorlds: manifest declares no roots — nothing to mount.');
   }
   const entries = opts.entries ?? {};
 
-  const worlds: WorldMountSpec[] = manifest.worlds.map((world) =>
+  const roots: WorldMountSpec[] = manifest.roots.map((world) =>
     buildWorldMountSpec(world, entries[world.id]),
   );
 
-  return createGameRuntime({
+  // D15 (T-D15.1) — resolved BEFORE `createGameRuntime` (which constructs the
+  // Game, and therefore `ctx.random`, before any world's `mount()`/`setup()`
+  // runs — see `createGame`'s own doc comment): the seed must be baked in at
+  // construction time, not patched in afterward, or a world's `setup()`
+  // would already have drawn from the wrong (default) sequence before any
+  // post-hoc reseed could take effect.
+  const seedUrl = opts.seedUrl ?? (hasRealWindow() ? window.location : undefined);
+  const resolvedSeed = resolveDeterminismSeed({
+    determinism: manifest.determinism,
+    explicitSeed: opts.seed,
+    url: seedUrl,
+  });
+
+  const session = await createGameRuntime({
     container: opts.container,
-    worlds,
+    roots,
     width: opts.width ?? manifest.resolution?.width,
     height: opts.height ?? manifest.resolution?.height,
     headless: opts.headless,
+    seed: resolvedSeed,
   });
+
+  // D15 (T-D15.3) — the dev-mode Math.random phase trap: only while the
+  // manifest declares the contract AND this is a dev build (mirrors D18's
+  // debug-bridge gate — `import.meta.env.DEV`, never a production build
+  // unless something ELSE explicitly opts in, which this trap has no
+  // opt-in for at all: it is dev-only, full stop). `getGameplayRngTrapControl`
+  // returns `null` only for a bare `Game`-shaped test stand-in predating
+  // T7.1 — real mounts always have one (same precedent as `getDebugRegistry`
+  // just below).
+  if (manifest.determinism?.seededRandom === true && Boolean(import.meta.env?.DEV)) {
+    getGameplayRngTrapControl(session.game)?.setEnabled(true);
+  }
+
+  // Task 2.1 — install the `?vgai-debug=1` bridge at the TAIL of every
+  // manifest mount (engine-owned, so a standalone project gets it with zero
+  // template edits). `getDebugRegistry` returns `null` only for a bare
+  // `Game`-shaped test stand-in predating T7.1 — real mounts always have one.
+  const debugRegistry = getDebugRegistry(session.game);
+  if (debugRegistry) {
+    // Defect 3 fix: `setRoomDeclared` (the locus-required rule — a project
+    // with a Colyseus room must declare `locus: 'client' | 'server'` on every
+    // debug command, docs/SYNTHETIC-PLAYER-SPEC.md §3.1) was never actually
+    // called from a real mount path — this is that wiring. `manifest.server`
+    // (`ResolvedGameManifest.server`, `manifest/load.ts`) is `{ room, module }
+    // | undefined`; its mere presence is the "this project declares a room"
+    // signal, independent of whether/when the game actually joins it.
+    if (manifest.server) {
+      debugRegistry.setRoomDeclared(true);
+    }
+    // Defect 5 fix: `maybeInstallDebugBridge` adds `window` listeners and
+    // publishes `window.__vgai` with no way to undo either — wire its
+    // `uninstall()` into THIS session's own `stop()` so a caller that tears
+    // this mount down doesn't leave the bridge (and its listeners) live.
+    const bridgeHandle = maybeInstallDebugBridge({
+      registry: debugRegistry,
+      manifest,
+      url: opts.debugBridge?.url,
+      window: opts.debugBridge?.window,
+    });
+    if (bridgeHandle) {
+      const stopSession = session.stop;
+      session.stop = () => {
+        bridgeHandle.uninstall();
+        stopSession();
+      };
+    }
+  }
+
+  return session;
 }

package/src/runtime/render-audio-control.ts

@@ -0,0 +1,168 @@
+/**
+ * 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, type ToneOfflineComposeFn } from '../audio/tone-offline-render';
+import { encodeWav16, pcmStats } from '../audio/wav-encode';
+import { isRenderModeRequested } from './render-control';
+
+/** 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 function installRenderAudioHarness(
+  opts: RenderAudioControlOptions,
+): VgaiRenderAudioHarness | undefined {
+  const location = opts.location ?? window.location;
+  if (!isRenderModeRequested(location)) return undefined;
+
+  const target = opts.target ?? (window as unknown as Record<string, unknown>);
+  const { compose, channels, sampleRate } = opts;
+
+  const harness: VgaiRenderAudioHarness = {
+    hasAudio: true,
+    async renderAudio(start: number, end: number): Promise<RenderAudioResult> {
+      const rendered = await renderToneOffline({
+        start,
+        end,
+        ...(channels !== undefined ? { channels } : {}),
+        ...(sampleRate !== undefined ? { sampleRate } : {}),
+        compose: compose(start),
+      });
+      const channelData: Float32Array[] = [];
+      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: Uint8Array): string {
+  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);
+}