@vgai/engine 0.5.2 → 0.5.4

package/src/audio/index.ts

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

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

@@ -1,175 +0,0 @@
-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);
-  bridgedContexts.add(context);
-  return {
-    context,
-    isBridged: () => Tone.getContext().rawContext === context,
-  };
-}
-
-// --- W3c introspection bookkeeping (read-only debugger seam) ----------------
-//
-// The registries below record what already flows through THIS module's two
-// seams — nothing new is wrapped; Tone stays used through its own API. They
-// exist so the first-party `AudioAdapter` introspection
-// (`audio-introspection.ts`) can answer "is Tone bridged onto this world's
-// context?" and "which Tone nodes feed this world's master bus?" TRUTHFULLY,
-// without ever instantiating a Tone global context of its own (calling
-// `Tone.getContext()` on a page whose game never used Tone would fabricate
-// one just by asking).
-
-const bridgedContexts = new WeakSet<AudioContext>();
-
-/** `true` iff {@link bridgeToneToThreeAudio} has run for this exact native
- *  context. A cheap pre-check: callers still confirm the bridge is CURRENT
- *  via `Tone.getContext().rawContext === context` (a later re-bridge to a
- *  different context leaves stale entries here) — but only after this
- *  returns `true`, so the confirmation never forces Tone to create a
- *  context that didn't already exist. */
-export function hasToneBridge(context: AudioContext): boolean {
-  return bridgedContexts.has(context);
-}
-
-interface ToneMasterRoute {
-  node: ToneAudioNode;
-  masterGain: GainNode;
-}
-
-const toneMasterRoutes: ToneMasterRoute[] = [];
-
-/** The still-alive Tone nodes routed into `masterGain` via
- *  {@link connectToneBusToMasterGain}. Disposed nodes (Tone's own
- *  `.disposed` flag) are pruned on every call, so a game that cleans up
- *  after itself leaves nothing behind here. Filtered by `masterGain`
- *  IDENTITY: one world's snapshot never shows another world's routes. */
-export function getToneMasterGainRoutes(masterGain: GainNode): ToneAudioNode[] {
-  for (let i = toneMasterRoutes.length - 1; i >= 0; i--) {
-    if (toneMasterRoutes[i]?.node.disposed) toneMasterRoutes.splice(i, 1);
-  }
-  return toneMasterRoutes.filter((r) => r.masterGain === masterGain).map((r) => r.node);
-}
-
-/**
- * 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);
-  // W3c: record the route so the Audio debugger's graph snapshot can show it
-  // (see the introspection-bookkeeping section below).
-  toneMasterRoutes.push({ node: toneNode, 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

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