@vgai/engine 0.2.0 → 0.3.0

package/src/audio/index.ts

@@ -1,7 +1,39 @@
-export { hum, nature, rain, wind } from './ambient';
-export { bounce, crash, explosion, hit } from './impacts';
-export { footstep, jump, whoosh } from './movement';
-export { arpeggio, bassPulse, stinger } from './musical';
-export { uiClick, uiError, uiHover, uiSuccess } from './ui-sounds';
-export { brakeSqueal, engineDrone, tireSkid } from './vehicle';
-export { chargeUp, gunshot, laser } from './weapons';
+// Engine-core audio surface (spec §13 workstream G).
+//
+// G3 ("Replace or Relocate Procedural Audio Helpers") removed the former
+// `musical.ts`/`weapons.ts`/`impacts.ts`/`vehicle.ts`/`ambient.ts`/
+// `movement.ts`/`ui-sounds.ts` — raw-`AudioContext`/`Math.random`-driven
+// oscillator and noise-buffer SFX generators that were engine-owned but
+// non-spatial (they never touched `THREE.PositionalAudio`, so the "spatial
+// one-shot helper" exception in the G3 acceptance criteria does not apply to
+// them). Each was either relocated verbatim into the example project that
+// used it (`examples/{third-person,fps,third-person-arena,rts,vehicle}/src/
+// procedural-audio.ts`) or deleted as dead code with no shipped consumer
+// (`bassPulse`/`arpeggio`/`gunshot`/`laser`/`bounce`/`crash`/`explosion`/
+// `tireSkid`/`wind`/`rain`/`hum`/`nature`/`uiHover`/`uiError`). The canonical
+// replacements — a procedural-music example built directly on Tone's own API
+// and a spatial-audio example built directly on `THREE.PositionalAudio` — are
+// `examples/audio-showcase`.
+//
+// What remains here is the genuine engine-core audio capability: the G1/G2
+// Tone↔Three context bridge and offline render (`wav-encode.ts`, the G4
+// PCM->WAV encoder, is consumed by its own module path, not this barrel — see
+// `packages/engine/src/runtime/render-audio-control.ts`).
+export {
+  bindClockToTone,
+  type ToneClockBinding,
+  type ToneClockBindingOptions,
+  type ToneTransportLike,
+} from './tone-clock-binding';
+export {
+  bridgeToneToThreeAudio,
+  connectToneBusToMasterGain,
+  resumeSharedAudio,
+  type ToneAudioBridge,
+} from './tone-context';
+export {
+  renderToneOffline,
+  type ToneOfflineComposeFn,
+  type ToneOfflineRenderRequest,
+  type ToneOfflineRenderResult,
+} from './tone-offline-render';

package/src/audio/tone-clock-binding.ts

@@ -0,0 +1,98 @@
+import type { AnimationClock, ClockEvaluatorHandle } from '../animation/animation-clock';
+import type { SystemPhaseName } from '../core/types';
+
+/**
+ * G2 — Integrate Tone with the Canonical Clock, preview/real-time half
+ * (spec §13 G2, §10 D1). Mirrors `animation/theatre-clock-binding.ts`'s D2
+ * pattern exactly, on purpose: the canonical `AnimationClock` is the single
+ * source of truth for "what time is it", and every participating system
+ * (Theatre's sequence position, a registered GSAP timeline, and — here — a
+ * Tone transport) is seeked to match it on every clock crossing. Tone must
+ * never be left to free-run its own real-time clock while participating in
+ * a cinematic, for the exact same reason Theatre isn't: deterministic
+ * export, offline scrubbing, and no wall-clock dependency
+ * (`animation-clock.ts`'s module doc explains why in full).
+ *
+ * ## Why setting `transport.seconds` is enough
+ *
+ * Setting `Tone.getTransport().seconds` repositions the transport's
+ * playhead synchronously; it does not itself start real-time ticking (that
+ * still requires an explicit `transport.start()`, which this binding
+ * deliberately never calls — see the module doc on `animation-clock.ts` for
+ * why nothing in this codebase is allowed to drive its own
+ * `requestAnimationFrame`/wall-clock loop). A clock-seeked Tone transport is
+ * a pure function of `clock.time`, exactly like a Theatre sequence's
+ * `position` setter.
+ *
+ * ## Structural (not nominal) transport typing
+ *
+ * `ToneTransportLike` intentionally types only the ONE property this
+ * binding touches (`seconds`), the same narrowing discipline
+ * `runtime/render-control.ts`'s `SeekableClock` uses for the canonical
+ * clock. `Tone.getTransport()`'s real `TransportClass` satisfies this
+ * structurally with no adapter — pass it directly at the real call site.
+ * The narrow type is also what makes this binding's own unit tests real
+ * (not mocked-away): `packages/engine/test/audio/tone-clock-binding.test.ts`
+ * exercises the FULL seek/pause/loop/time-scale matrix against a real
+ * `AnimationClock` and a plain `{ seconds: number }` object — no Tone
+ * import, no `AudioContext`, and it still proves the exact behavior a real
+ * `Tone.Transport` will see, because `TransportClass` IS a
+ * `ToneTransportLike` at the type level.
+ */
+
+export interface ToneTransportLike {
+  seconds: number;
+}
+
+export interface ToneClockBindingOptions {
+  /**
+   * Which `AnimationClock` phase to seek the transport in. Defaults to
+   * `'animation'` — the same phase `theatre-clock-binding.ts` uses by
+   * default, so a Theatre sequence and a Tone transport bound to the same
+   * clock stay in lockstep with each other (`PHASE_ORDER`-then-registration-
+   * order — see `animation-clock.ts`'s `subscribe` doc comment).
+   */
+  phase?: SystemPhaseName;
+}
+
+export interface ToneClockBinding {
+  /** Removes the clock evaluator. No further `transport.seconds` writes
+   *  occur after this — the transport is left at whatever position it was
+   *  last seeked to (matches `TheatreClockBinding.dispose`'s contract). */
+  dispose(): void;
+}
+
+/**
+ * Subscribe `transport.seconds = clock.time` to every crossing of `clock`
+ * in the given phase (default `'animation'`). Returns a disposer; call it
+ * to stop driving the transport (e.g. on `GameCleanup.dispose()`, or before
+ * rebinding on hot reload — this is what keeps HMR from accumulating
+ * duplicate listeners).
+ *
+ * Only call this for a Tone composition that PARTICIPATES in a cinematic
+ * (spec G2 AC). Ordinary, non-cinematic game music should drive Tone's own
+ * real-time transport directly (`transport.start()`, `Tone.Transport.bpm`,
+ * etc. — see `tone-context.ts`'s "escape hatch" section) and must NEVER be
+ * bound here, since a bound transport's position is entirely clock-driven
+ * and `start()`/`stop()` calls on it would fight this binding's writes.
+ */
+export function bindClockToTone(
+  clock: AnimationClock,
+  transport: ToneTransportLike,
+  options: ToneClockBindingOptions = {},
+): ToneClockBinding {
+  const phase = options.phase ?? 'animation';
+
+  const handle: ClockEvaluatorHandle = clock.subscribe(phase, (crossing) => {
+    transport.seconds = crossing.currentTime;
+  });
+
+  let disposed = false;
+  return {
+    dispose(): void {
+      if (disposed) return;
+      disposed = true;
+      handle.dispose();
+    },
+  };
+}

package/src/audio/tone-context.ts

@@ -0,0 +1,129 @@
+import type { ToneAudioNode } from 'tone';
+import * as Tone from 'tone';
+
+/**
+ * G1 — Establish Audio Ownership (spec §13 G1, §3.6, §4).
+ *
+ * ## The boundary
+ *
+ * Two independent, native-vocabulary audio systems coexist in every VGAI
+ * game, each with a genuinely different job. This module does not wrap
+ * either one — it only decides who owns which native `AudioContext` and how
+ * the two graphs meet:
+ *
+ *  - **Three/Web Audio** (`setup/setup-audio.ts`) remains authoritative for
+ *    SPATIAL audio: `THREE.AudioListener` (attached to the active camera)
+ *    and `THREE.Audio`/`THREE.PositionalAudio` sources. (G3, a later unit,
+ *    has since removed the non-spatial engine-owned one-shot procedural
+ *    helpers this comment used to name here — `audio/impacts.ts`,
+ *    `audio/weapons.ts`, `audio/ambient.ts`, and their siblings — relocating
+ *    each into the example project that used it, or deleting it as dead code;
+ *    see `packages/engine/src/audio/index.ts`'s header comment and
+ *    `examples/audio-showcase` for the canonical native-Tone/native-Three
+ *    replacements. This module's own boundary/bridge is unchanged by that
+ *    unit.)
+ *  - **Tone.js** owns musical transport, tempo, scheduling, synthesis, and
+ *    procedural composition — imported and used with its OWN native API
+ *    (`new Tone.Synth()`, `Tone.getTransport()`, `Tone.Offline(...)`,
+ *    `Tone.getContext()`), never through a VGAI-renamed wrapper (spec §1's
+ *    native-library rule). See `packages/engine/test/audio/tone-context.test.ts`
+ *    for a direct, unwrapped usage example.
+ *
+ * ## Why they must share one native `AudioContext`
+ *
+ * Both systems ultimately talk to exactly one hardware output. If Tone ran
+ * its own independently-created `AudioContext` alongside
+ * `THREE.AudioListener`'s, they would: fight over autoplay-policy resume
+ * state (two contexts, two `state`s, two places a "click to start audio"
+ * gesture would need to unlock); produce TWO separate graphs that a single
+ * mute/volume control cannot coherently silence; and — fatally for G4/I6 —
+ * make deterministic offline capture impossible to align with the video's
+ * frame-addressed render range, since there would be no single graph whose
+ * lifecycle (suspend/resume/close) the render/capture harness can reason
+ * about.
+ *
+ * `bridgeToneToThreeAudio` fixes this: it points Tone's global context
+ * (`Tone.setContext`) at the SAME native `AudioContext` instance
+ * `THREE.AudioListener` already created (`setupAudio(camera).listener.context`,
+ * `setup/setup-audio.ts`). After bridging,
+ * `Tone.getContext().rawContext === threeListener.context` — there is
+ * exactly one native context. One `.resume()`/`.suspend()` call (or
+ * `Tone.start()`, which does both) affects both systems, and routing a Tone
+ * bus into `setupAudio()`'s `masterGain` (see `connectToneBusToMasterGain`
+ * below) puts Tone's output under the SAME mute/master-volume control as
+ * every `THREE.Audio` source.
+ *
+ * ## What this module does NOT do
+ *
+ * It does not create an `AudioContext` (that remains `setupAudio`'s job —
+ * call `bridgeToneToThreeAudio` AFTER `setupAudio(camera)`, before
+ * constructing any Tone node: Tone nodes built against the PREVIOUS global
+ * context are not retroactively migrated — Tone's own `setContext` contract,
+ * not a VGAI limitation). It does not wrap any Tone class, and it does not
+ * touch THREE's audio path at all. G3 (a later unit) is where engine-owned
+ * procedural helpers get rewritten directly on Tone or relocated to game
+ * code — this module only owns the context boundary + bridge.
+ *
+ * ## Escape hatch — ordinary (non-cinematic) game music
+ *
+ * None of the above requires participating in a cinematic. Once bridged,
+ * ordinary game music can drive Tone's REAL real-time transport exactly as
+ * Tone's own docs describe — `Tone.getTransport().bpm.value = 128`,
+ * `Tone.getTransport().start()`, `new Tone.Sequence(...).start(0)`, etc. —
+ * with no VGAI involvement at all. `tone-clock-binding.ts` (G2) is opt-in,
+ * only for the case where a Tone composition must stay in lockstep with the
+ * canonical `AnimationClock` because it participates in a cinematic.
+ */
+
+/** Result of {@link bridgeToneToThreeAudio} — the shared native context plus
+ *  a re-checkable assertion, so a caller/test doesn't need to re-derive the
+ *  bridging logic to confirm it still holds later. */
+export interface ToneAudioBridge {
+  /** The native `AudioContext` Tone and `THREE.AudioListener` now share. */
+  readonly context: AudioContext;
+  /** True iff `Tone.getContext().rawContext` is still exactly `context`
+   *  (identity, not equality — proves ONE shared native context, not two
+   *  compatible-looking ones). */
+  isBridged(): boolean;
+}
+
+/**
+ * Point Tone's global context at `context` (typically
+ * `setupAudio(camera).listener.context` from `setup/setup-audio.ts`). Call
+ * this once per game boot, after `setupAudio(camera)`, before constructing
+ * any Tone node.
+ */
+export function bridgeToneToThreeAudio(context: AudioContext): ToneAudioBridge {
+  Tone.setContext(context);
+  return {
+    context,
+    isBridged: () => Tone.getContext().rawContext === context,
+  };
+}
+
+/**
+ * Route a Tone output node (a bus, `Tone.getDestination()`, or any
+ * `Tone.Gain` used as a submix) into the SAME `masterGain`
+ * `setupAudio()` created, so Tone output is silenced/attenuated by the
+ * identical mute/volume control as every `THREE.Audio`/`THREE.PositionalAudio`
+ * source. `toneNode` is Tone's own `ToneAudioNode` type (no VGAI wrapper);
+ * `masterGain` is the plain native `GainNode` `setupAudio()` already
+ * returns — Tone's `.connect()` natively accepts a raw `AudioNode` as its
+ * destination, so no adapter node is needed on either side.
+ */
+export function connectToneBusToMasterGain(toneNode: ToneAudioNode, masterGain: GainNode): void {
+  toneNode.connect(masterGain);
+}
+
+/**
+ * Resume the shared context after a user gesture. Because
+ * {@link bridgeToneToThreeAudio} guarantees Tone and THREE share the
+ * identical native context, calling `Tone.start()` — which both resumes the
+ * context AND runs Tone's own autoplay-unlock bookkeeping (a silent-buffer
+ * trick required on some browsers) — is sufficient to unstick BOTH systems;
+ * a separate `context.resume()` call on the THREE side is redundant once
+ * bridged, not required.
+ */
+export async function resumeSharedAudio(): Promise<void> {
+  await Tone.start();
+}

package/src/audio/tone-offline-render.ts

@@ -0,0 +1,167 @@
+import { Offline } from 'tone';
+
+/**
+ * G2 — Integrate Tone with the Canonical Clock, OFFLINE-render half (spec
+ * §13 G2, and the G4/I6 seam it is deliberately shaped for). This module
+ * renders a Tone composition over an exact `[start, end)` time range to a
+ * real `AudioBuffer` via `Tone.Offline` — i.e. `OfflineAudioContext`, NOT a
+ * live real-time `AudioContext` — such that identical inputs produce
+ * bit-identical output samples on every call. This is what makes offline
+ * Tone audio safe to mux into a deterministically-rendered video (G4/I6):
+ * the video side already re-renders frame-by-frame from an exact clock
+ * position, and this is the audio side's equivalent — an exact re-render
+ * from an exact time range, not a live capture of whatever happened to play.
+ *
+ * ## Why this can't run in plain Node (documented, not assumed)
+ *
+ * `Tone.Offline` ultimately constructs a real `OfflineAudioContext`
+ * (via `standardized-audio-context`, Tone's own dependency). Node has no
+ * native Web Audio implementation, so `standardized-audio-context` throws
+ * `"Missing the native OfflineAudioContext constructor."` the moment
+ * `Tone.Offline(...)` is actually invoked — confirmed empirically against
+ * this repo's installed `tone@15.1.22` before writing this module (plain
+ * `import * as Tone from 'tone'` succeeds; calling `Tone.Offline(...)` in a
+ * Node process throws immediately). There is no lightweight polyfill in this
+ * repo's dependency tree, and installing a native Node Web Audio addon is
+ * out of scope for this unit (build-box constraints). The determinism proof
+ * for this module therefore runs in a REAL headless-Chromium page via
+ * Playwright — see `packages/engine/e2e/tests/tone-audio-g1-g2.spec.ts`
+ * — mirroring how I0 proved video-frame determinism. This module's own
+ * `packages/engine/test/audio/tone-offline-render.test.ts` covers everything
+ * that does NOT require a real `OfflineAudioContext` (range validation,
+ * synchronous pre-render cancellation) directly in Node.
+ *
+ * ## Composition contract
+ *
+ * `compose` is called by `Tone.Offline` itself, inside the offline context —
+ * build the SAME graph you would in real-time Tone code
+ * (`new Tone.Synth().toDestination()`, `context.transport.schedule(...)`,
+ * etc; see Tone's own `Offline` docs). Nothing about this wrapper changes
+ * Tone's native API surface — `compose`'s parameter is `Tone.Offline`'s own
+ * callback type, re-derived structurally (`Parameters<typeof Offline>[0]`)
+ * rather than duplicated, so this module can never drift from Tone's actual
+ * signature.
+ *
+ * ## Cancellation — cooperative, not a true mid-render abort
+ *
+ * The Web Audio spec gives `OfflineAudioContext` no `.close()`/cancel API
+ * once `startRendering()` is in flight, and neither does Tone. `signal`
+ * therefore provides COOPERATIVE cancellation only: if `signal` is already
+ * aborted before this function calls `Tone.Offline`, the render never
+ * starts at all (checked synchronously, before any `OfflineAudioContext` is
+ * created). If `signal` aborts WHILE a render is in flight, this function's
+ * returned promise rejects immediately with an `AbortError` — so a caller
+ * (e.g. a render-cancellation UI action) sees the render "stop" from its own
+ * perspective and never receives/uses the resulting buffer — even though
+ * the underlying browser-native render may keep running in the background
+ * until it would have finished anyway. This is an honest, documented
+ * limitation, not a gap: no browser API makes a stronger guarantee possible.
+ */
+
+/** Tone's own `Offline` callback signature, re-derived (not re-typed) so
+ *  this module can never drift from the real function it wraps. */
+export type ToneOfflineComposeFn = Parameters<typeof Offline>[0];
+
+export interface ToneOfflineRenderRequest {
+  /** Canonical/Theatre-time range start, in seconds. */
+  readonly start: number;
+  /** Canonical/Theatre-time range end, in seconds. Must be `> start`. */
+  readonly end: number;
+  /** Output sample rate. Default 44100 (CD-quality, FFmpeg's usual default). */
+  readonly sampleRate?: number;
+  /** Output channel count. Default 2 (stereo). */
+  readonly channels?: number;
+  /** Builds the Tone graph inside the offline context — Tone's native
+   *  `Offline` callback, unmodified. Receives local time `0` at `start`. */
+  readonly compose: ToneOfflineComposeFn;
+  /** Optional cooperative-cancellation signal — see module doc above. */
+  readonly signal?: AbortSignal;
+}
+
+export interface ToneOfflineRenderResult {
+  /** The rendered PCM, as a real (native) `AudioBuffer` — `.getChannelData(n)`
+   *  gives the Float32 samples for channel `n`, ready for a digest/RMS
+   *  computation or (eventually, G4/I6) FFmpeg muxing. */
+  readonly buffer: AudioBuffer;
+  readonly durationSeconds: number;
+  readonly sampleRate: number;
+  readonly channels: number;
+}
+
+const DEFAULT_SAMPLE_RATE = 44100;
+const DEFAULT_CHANNELS = 2;
+
+/** Render `request.compose`'s Tone graph offline over `[start, end)`,
+ *  producing a deterministic `AudioBuffer`. See module doc for the
+ *  determinism/cancellation contract. */
+export async function renderToneOffline(
+  request: ToneOfflineRenderRequest,
+): Promise<ToneOfflineRenderResult> {
+  const {
+    start,
+    end,
+    sampleRate = DEFAULT_SAMPLE_RATE,
+    channels = DEFAULT_CHANNELS,
+    compose,
+    signal,
+  } = request;
+
+  if (!Number.isFinite(start) || !Number.isFinite(end) || end <= start) {
+    throw new Error(
+      `[tone-offline-render] invalid range [${start}, ${end}) — end must be a finite number > start`,
+    );
+  }
+  if (!Number.isFinite(sampleRate) || sampleRate <= 0) {
+    throw new Error(
+      `[tone-offline-render] sampleRate must be a finite number > 0, got ${sampleRate}`,
+    );
+  }
+  if (!Number.isInteger(channels) || channels <= 0) {
+    throw new Error(`[tone-offline-render] channels must be a positive integer, got ${channels}`);
+  }
+  // Cooperative cancellation, checked BEFORE ever constructing an
+  // OfflineAudioContext — an already-aborted signal must never start a
+  // render at all (see module doc).
+  if (signal?.aborted) {
+    throw createAbortError();
+  }
+
+  const durationSeconds = end - start;
+  const renderPromise = Offline(compose, durationSeconds, channels, sampleRate);
+  const toneBuffer = signal ? await raceAbort(renderPromise, signal) : await renderPromise;
+  const buffer = toneBuffer.get();
+  if (!buffer) {
+    throw new Error('[tone-offline-render] Tone.Offline resolved without a decoded AudioBuffer');
+  }
+
+  return {
+    buffer,
+    durationSeconds,
+    sampleRate: buffer.sampleRate,
+    channels: buffer.numberOfChannels,
+  };
+}
+
+function createAbortError(): DOMException {
+  return new DOMException('[tone-offline-render] render canceled', 'AbortError');
+}
+
+/** Race `promise` against `signal` firing — resolves/rejects with whichever
+ *  happens first, without altering the underlying Web Audio render (see
+ *  module doc's "cooperative, not a true mid-render abort" section). */
+function raceAbort<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = () => reject(createAbortError());
+    signal.addEventListener('abort', onAbort, { once: true });
+    promise.then(
+      (value) => {
+        signal.removeEventListener('abort', onAbort);
+        resolve(value);
+      },
+      (err: unknown) => {
+        signal.removeEventListener('abort', onAbort);
+        reject(err);
+      },
+    );
+  });
+}

package/src/audio/wav-encode.ts

@@ -0,0 +1,119 @@
+/**
+ * Pure PCM -> 16-bit WAV encoder (spec §15 I6 "Encode and Mux", audio half —
+ * `docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md`). This module takes
+ * already-rendered Float32 channel data (e.g. `AudioBuffer.getChannelData(n)`
+ * from a `Tone.Offline` render, `audio/tone-offline-render.ts`) and produces
+ * a standard little-endian, 16-bit-PCM, interleaved RIFF/WAVE file as raw
+ * bytes — no `AudioBuffer`/`AudioContext` dependency, so this runs equally in
+ * a browser render-mode page (`runtime/render-audio-control.ts`) and in
+ * plain Node (this module's own `packages/engine/test/audio/wav-encode.test.ts`,
+ * no Playwright needed).
+ *
+ * 16-bit PCM (not 32-bit float) is the deliberate choice named by the I6 AC
+ * ("16-bit PCM WAV is fine") — it is universally decodable by every FFmpeg
+ * build without an extra format flag, keeping the video-mux step's ffmpeg
+ * invocation ordinary and portable.
+ */
+
+export interface PcmToWavInput {
+  /** One `Float32Array` per channel, each sample in `[-1, 1]` (values outside
+   *  that range are clamped, not thrown on — real synthesis can transiently
+   *  clip). All channels must have equal length. */
+  readonly channelData: readonly Float32Array[];
+  readonly sampleRate: number;
+}
+
+const BYTES_PER_SAMPLE = 2; // 16-bit PCM
+const WAV_HEADER_BYTES = 44;
+
+function clamp(value: number, lo: number, hi: number): number {
+  return Math.min(hi, Math.max(lo, value));
+}
+
+function writeAsciiString(view: DataView, offset: number, text: string): void {
+  for (let i = 0; i < text.length; i++) {
+    view.setUint8(offset + i, text.charCodeAt(i));
+  }
+}
+
+/** Encode `input` as a complete little-endian, 16-bit-PCM, interleaved
+ *  RIFF/WAVE file (44-byte canonical header + data chunk). Throws on an
+ *  empty/mismatched channel set rather than silently producing a malformed
+ *  file — this module's own contribution to the "fail loudly, never a
+ *  silent no-op" convention `runtime/render-control.ts` documents. */
+export function encodeWav16(input: PcmToWavInput): Uint8Array {
+  const { channelData, sampleRate } = input;
+  const numChannels = channelData.length;
+  if (numChannels === 0) {
+    throw new Error('[wav-encode] channelData must contain at least one channel');
+  }
+  if (!Number.isFinite(sampleRate) || sampleRate <= 0) {
+    throw new Error(`[wav-encode] sampleRate must be a finite number > 0, got ${sampleRate}`);
+  }
+  const numFrames = channelData[0]?.length ?? 0;
+  for (let ch = 0; ch < numChannels; ch++) {
+    const len = channelData[ch]?.length ?? -1;
+    if (len !== numFrames) {
+      throw new Error(
+        `[wav-encode] channel ${ch} has length ${len}, expected ${numFrames} (all channels must match)`,
+      );
+    }
+  }
+
+  const blockAlign = numChannels * BYTES_PER_SAMPLE;
+  const byteRate = sampleRate * blockAlign;
+  const dataSize = numFrames * blockAlign;
+
+  const buffer = new ArrayBuffer(WAV_HEADER_BYTES + dataSize);
+  const view = new DataView(buffer);
+
+  // RIFF chunk descriptor
+  writeAsciiString(view, 0, 'RIFF');
+  view.setUint32(4, 36 + dataSize, true);
+  writeAsciiString(view, 8, 'WAVE');
+
+  // fmt subchunk (PCM)
+  writeAsciiString(view, 12, 'fmt ');
+  view.setUint32(16, 16, true); // subchunk size for PCM
+  view.setUint16(20, 1, true); // audio format 1 = PCM
+  view.setUint16(22, numChannels, true);
+  view.setUint32(24, sampleRate, true);
+  view.setUint32(28, byteRate, true);
+  view.setUint16(32, blockAlign, true);
+  view.setUint16(34, BYTES_PER_SAMPLE * 8, true); // bits per sample
+
+  // data subchunk
+  writeAsciiString(view, 36, 'data');
+  view.setUint32(40, dataSize, true);
+
+  let offset = WAV_HEADER_BYTES;
+  for (let i = 0; i < numFrames; i++) {
+    for (let ch = 0; ch < numChannels; ch++) {
+      const sample = clamp(channelData[ch]?.[i] ?? 0, -1, 1);
+      const intSample = Math.round(sample < 0 ? sample * 0x8000 : sample * 0x7fff);
+      view.setInt16(offset, intSample, true);
+      offset += BYTES_PER_SAMPLE;
+    }
+  }
+
+  return new Uint8Array(buffer);
+}
+
+/** RMS + peak over all channels/samples — the same "non-trivial audio, not
+ *  an all-zero buffer" sanity check `tone-audio-main.ts`'s fixture computes,
+ *  factored out here so both that fixture and the render-audio harness can
+ *  share one implementation instead of drifting copies. */
+export function pcmStats(channelData: readonly Float32Array[]): { rms: number; peak: number } {
+  let sumSquares = 0;
+  let peak = 0;
+  let count = 0;
+  for (const data of channelData) {
+    for (let i = 0; i < data.length; i++) {
+      const v = data[i] ?? 0;
+      sumSquares += v * v;
+      peak = Math.max(peak, Math.abs(v));
+      count++;
+    }
+  }
+  return { rms: count > 0 ? Math.sqrt(sumSquares / count) : 0, peak };
+}

package/src/core/game-loop.ts

@@ -18,6 +18,13 @@ export function createGameLoop(config: GameLoopConfig) {
   const maxSubSteps = config.maxSubSteps ?? 8;
   // Also the accumulator's hard ceiling (see the spiral-of-death guard below).
   const maxAccumulator = fixedDt * maxSubSteps;
+  // I2 (render-control runtime mode, see `GameLoopConfig.externalDrive`'s
+  // doc comment): in this mode `start()` below deliberately skips both the
+  // `requestAnimationFrame` arm AND the `visibilitychange` listener install —
+  // no wall-clock timing source ever exists for this loop instance, so
+  // `config.update` can only ever be invoked by an external driver calling
+  // into the render-control seam, never by this file's own `frame()`.
+  const externalDrive = config.externalDrive ?? false;
 
   let accumulator = 0;
   let lastTime = 0;
@@ -87,6 +94,16 @@ export function createGameLoop(config: GameLoopConfig) {
       hiddenPaused = false;
       lastTime = performance.now();
       accumulator = 0;
+
+      // External-drive mode (I2): never arm rAF and never install the
+      // visibilitychange auto-stop handler. `running` still flips `true`
+      // above (so `isRunning`/`stop()` behave normally for a caller that
+      // treats this loop as "started"), but nothing will ever call
+      // `frame()` — a headless/backgrounded capture page cannot have this
+      // loop silently killed by `document.hidden`, because there is no
+      // listener to fire in the first place.
+      if (externalDrive) return;
+
       rafId = requestAnimationFrame(frame);
 
       if (!visibilityListenerAttached && typeof document !== 'undefined') {

package/src/core/types.ts

@@ -55,4 +55,17 @@ export interface GameLoopConfig {
    * produces zero substeps calls `update` zero times and renders zero times.
    */
   update: (dt: number) => void;
+  /**
+   * External-drive mode (I2, `docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md`
+   * §15 I2): when `true`, `start()` never arms a `requestAnimationFrame`
+   * chain and never installs the `visibilitychange`/`document.hidden`
+   * auto-stop handler — so a headless/backgrounded capture page cannot have
+   * its loop silently killed by the tab-hidden guard, and `config.update`
+   * is never invoked by wall-clock/RAF timing at all. The caller (a render
+   * harness) drives frames itself instead — see `runtime/render-control.ts`,
+   * which calls a world's phase hooks directly rather than going through
+   * this loop's `update` callback. Default `false` (normal wall-clock RAF
+   * playback, unchanged).
+   */
+  externalDrive?: boolean;
 }