@vgai/engine 0.2.0 → 0.4.0-canary.20260715.0

package/src/animation/xstate-animation-meta.ts

@@ -0,0 +1,319 @@
+import { z } from 'zod';
+
+/**
+ * E1 — Zod/TypeScript metadata attached to XState state `meta.animation`
+ * (spec §11 E1, §5.6, §3.3).
+ *
+ * This module defines ONLY animation data: which clip(s) a state plays, how
+ * they loop/blend/crossfade, and (for locomotion-style states) how a 1D/2D/
+ * direct blend tree distributes weight across several clips from a live
+ * parameter. It intentionally contains **no transition vocabulary** — no
+ * `on`/`target`/`guard`/`always`/`after`/`entry`/`exit`. XState alone owns
+ * states, transitions, events, and guards (§3.3); this metadata is read-only
+ * data a binding (`xstate-animation-binding.ts`, E2) consumes to drive a
+ * `THREE.AnimationMixer` when XState enters/exits a state. Every schema below
+ * is `.strict()` specifically so that smuggling a transition-shaped key into
+ * `meta.animation` is a loud Zod "unrecognized key" error, not a silently
+ * ignored field (E1 AC: "Metadata contains no transition language").
+ *
+ * ## Native layered composition
+ *
+ * Parallel XState regions may drive independent named layers. Each layer can
+ * filter a clip to selected bone subtrees, scale its weight, and use normal
+ * override or Three's native additive blend mode. XState still owns all
+ * state/transition semantics; these fields only describe how the active
+ * state's native `AnimationAction`s are composed by the binding.
+ *
+ * ## Blend tree shape
+ *
+ * Deliberately structurally IDENTICAL to `anim-graph-types.ts`'s
+ * `BlendTreeDef` (same `type`/`parameter`/`parameterY`/`children[].clip`/
+ * `.threshold`/`.thresholdY`/`.weight` fields) so the binding can hand a
+ * parsed `AnimationBlendTree` straight to the existing, already-tested
+ * `evaluateBlendTree` (`blend-node.ts`) with zero conversion — E2 reuses that
+ * function verbatim rather than re-implementing 1D/2D/direct blend math.
+ */
+
+// ---------------------------------------------------------------------------
+// Blend tree children
+// ---------------------------------------------------------------------------
+
+const AnimationBlendChildSchema = z
+  .object({
+    clip: z.string().min(1).describe('Animation clip name this child plays'),
+    threshold: z.number().describe('1D/2D blend position on the primary parameter axis'),
+    thresholdY: z
+      .number()
+      .optional()
+      .describe('2D blend position on the secondary parameter axis (2D blend trees only)'),
+    weight: z
+      .number()
+      .min(0)
+      .optional()
+      .describe('Explicit weight for "direct" blend trees (ignored by 1D/2D)'),
+  })
+  .strict();
+
+export type AnimationBlendChild = z.infer<typeof AnimationBlendChildSchema>;
+
+const AnimationBlendTree1DSchema = z
+  .object({
+    type: z.literal('1D').describe('Interpolates linearly between sorted children by threshold'),
+    parameter: z.string().min(1).describe('Context/selector value driving the blend'),
+    children: z
+      .array(AnimationBlendChildSchema)
+      .min(2, '1D blend tree needs at least 2 children to interpolate between'),
+  })
+  .strict();
+
+const AnimationBlendTree2DSchema = z
+  .object({
+    type: z
+      .literal('2D')
+      .describe('Inverse-distance-weights children by (parameter, parameterY) position'),
+    parameter: z.string().min(1).describe('Primary axis context/selector value'),
+    parameterY: z.string().min(1).describe('Secondary axis context/selector value'),
+    children: z
+      .array(AnimationBlendChildSchema.extend({ thresholdY: z.number() }))
+      .min(1, '2D blend tree needs at least 1 child'),
+  })
+  .strict();
+
+const AnimationBlendTreeDirectSchema = z
+  .object({
+    type: z.literal('direct').describe('Each child has an explicit weight, normalized to sum to 1'),
+    // `parameter` is unused by direct blending (evaluateBlendTree never reads
+    // it for `type: 'direct'`) but kept required+defaulted so the parsed
+    // value stays structurally assignable to `BlendTreeDef`
+    // (`anim-graph-types.ts`), which declares `parameter: string` for every
+    // blend mode — the same convention that type already uses.
+    parameter: z.string().default(''),
+    children: z
+      .array(AnimationBlendChildSchema.extend({ weight: z.number().min(0) }))
+      .min(1, 'direct blend tree needs at least 1 child'),
+  })
+  .strict();
+
+export const AnimationBlendTreeSchema = z.discriminatedUnion('type', [
+  AnimationBlendTree1DSchema,
+  AnimationBlendTree2DSchema,
+  AnimationBlendTreeDirectSchema,
+]);
+
+export type AnimationBlendTree = z.infer<typeof AnimationBlendTreeSchema>;
+
+// ---------------------------------------------------------------------------
+// Crossfade / blend-in-out metadata (shared by clip and blend-tree states)
+// ---------------------------------------------------------------------------
+
+const AnimationCrossfadeMetaSchema = z
+  .object({
+    duration: z
+      .number()
+      .min(0)
+      .default(0)
+      .describe(
+        'Seconds to blend from the previously active clip into this state on entry, applied via ' +
+          'native `AnimationAction.crossFadeTo`/`fadeIn` (E2). 0 = instant activation, no fade.',
+      ),
+    warp: z
+      .boolean()
+      .default(false)
+      .describe(
+        "Passed through to AnimationAction.crossFadeTo's `warp` param — linearly warps timeScale " +
+          'across the two clips during the blend so differing clip lengths line up. Default false.',
+      ),
+  })
+  .strict()
+  .describe('Blend-in/out/crossfade timing for entering this state');
+
+export type AnimationCrossfadeMeta = z.infer<typeof AnimationCrossfadeMetaSchema>;
+
+const AnimationBoneMaskSchema = z
+  .object({
+    include: z
+      .array(z.string().min(1))
+      .min(1)
+      .optional()
+      .describe('Bone/object names whose complete descendant subtrees are retained'),
+    exclude: z
+      .array(z.string().min(1))
+      .min(1)
+      .optional()
+      .describe('Bone/object names whose complete descendant subtrees are removed'),
+  })
+  .strict()
+  .refine((mask) => Boolean(mask.include?.length || mask.exclude?.length), {
+    message: 'boneMask needs at least one include or exclude bone name',
+  })
+  .describe('Filters animation tracks by named Object3D/Bone subtrees');
+
+export type AnimationBoneMask = z.infer<typeof AnimationBoneMaskSchema>;
+
+const AnimationLayerFields = {
+  layer: z
+    .string()
+    .min(1)
+    .optional()
+    .describe('Composition layer name; omitted means the single base layer'),
+  weight: z
+    .number()
+    .min(0)
+    .max(1)
+    .optional()
+    .describe('Layer weight multiplier from 0 to 1; defaults to 1'),
+  blendMode: z
+    .enum(['override', 'additive'])
+    .optional()
+    .describe('Native Three normal/override or additive action blending; defaults to override'),
+  boneMask: AnimationBoneMaskSchema.optional().describe(
+    'Optional include/exclude filter applied to every clip track in this state',
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// Per-state animation metadata: single clip OR blend tree, plus crossfade
+// ---------------------------------------------------------------------------
+
+const ClipAnimationMetaSchema = z
+  .object({
+    clip: z.string().min(1).describe('Single clip to play while this XState state is active'),
+    loop: z
+      .boolean()
+      .default(true)
+      .describe(
+        'Loop the clip (THREE.LoopRepeat) vs play once (THREE.LoopOnce, clamped on last frame)',
+      ),
+    speed: z
+      .number()
+      .positive()
+      .default(1)
+      .describe('Playback speed multiplier (AnimationAction.timeScale)'),
+    crossfade: AnimationCrossfadeMetaSchema.optional(),
+    ...AnimationLayerFields,
+  })
+  .strict();
+
+export type ClipAnimationMeta = z.infer<typeof ClipAnimationMetaSchema>;
+
+const BlendTreeAnimationMetaSchema = z
+  .object({
+    blendTree: AnimationBlendTreeSchema.describe(
+      'Multiple clips blended by a live context/selector-driven parameter',
+    ),
+    crossfade: AnimationCrossfadeMetaSchema.optional(),
+    ...AnimationLayerFields,
+  })
+  .strict();
+
+export type BlendTreeAnimationMeta = z.infer<typeof BlendTreeAnimationMetaSchema>;
+
+/**
+ * The full shape of `state.meta.animation` for one XState state (spec §5.6):
+ * exactly one of a single clip or a blend tree, plus optional crossfade
+ * timing. `.strict()` on both branches is what makes authoring a transition
+ * keyword (`on`, `target`, `guard`, …) inside `meta.animation` a validation
+ * error instead of a silently-accepted second transition dialect.
+ */
+export const StateAnimationMetaSchema = z.union([
+  ClipAnimationMetaSchema,
+  BlendTreeAnimationMetaSchema,
+]);
+
+export type StateAnimationMeta = z.infer<typeof StateAnimationMetaSchema>;
+
+/** True iff a validated meta declares a single clip rather than a blend tree. */
+export function isClipAnimationMeta(meta: StateAnimationMeta): meta is ClipAnimationMeta {
+  return 'clip' in meta;
+}
+
+/** True iff a validated meta declares a blend tree rather than a single clip. */
+export function isBlendTreeAnimationMeta(meta: StateAnimationMeta): meta is BlendTreeAnimationMeta {
+  return 'blendTree' in meta;
+}
+
+// ---------------------------------------------------------------------------
+// Validation entry point
+// ---------------------------------------------------------------------------
+
+/** Thrown by `parseStateAnimationMeta` — always names the offending state id. */
+export class AnimationMetaValidationError extends Error {
+  constructor(
+    message: string,
+    readonly stateId: string,
+    readonly issues: z.ZodIssue[],
+  ) {
+    super(message);
+    this.name = 'AnimationMetaValidationError';
+  }
+}
+
+/**
+ * Validate one state's `meta.animation` value. Called by the E2 binding for
+ * every state a machine declares (both at bind time, up front, and — for
+ * belt-and-suspenders — again whenever a state is entered).
+ *
+ * @throws {AnimationMetaValidationError} naming the state id and every Zod
+ *   issue (path + message) — e.g. an unrecognized `on`/`target` key, a
+ *   missing `clip`, or a 1D blend tree with only one child.
+ */
+export function parseStateAnimationMeta(stateId: string, raw: unknown): StateAnimationMeta {
+  const result = StateAnimationMetaSchema.safeParse(raw);
+  if (!result.success) {
+    const detail = result.error.issues
+      .map((issue) => `${issue.path.length ? issue.path.join('.') : '(root)'}: ${issue.message}`)
+      .join('; ');
+    throw new AnimationMetaValidationError(
+      `[xstate-animation] invalid meta.animation for state "${stateId}": ${detail}`,
+      stateId,
+      result.error.issues,
+    );
+  }
+  return result.data;
+}
+
+// ---------------------------------------------------------------------------
+// Machine-wide collection (used by E2 to validate + resolve clips up front)
+// ---------------------------------------------------------------------------
+
+/** The minimal shape of an XState `StateNode` this module needs to walk. */
+export interface AnimationMetaStateNodeLike {
+  id: string;
+  meta?: { animation?: unknown } & Record<string, unknown>;
+  states?: Record<string, AnimationMetaStateNodeLike>;
+}
+
+export interface MachineAnimationMetaEntry {
+  stateId: string;
+  meta: StateAnimationMeta;
+}
+
+/**
+ * Walk every state node in a machine (from its root `StateNode`, e.g.
+ * `actor.logic.root`) and validate every `meta.animation` value found.
+ * States with no `meta.animation` are skipped (not every XState state needs
+ * to drive animation). Returns one entry per animated state, in document
+ * order.
+ *
+ * @throws {AnimationMetaValidationError} on the FIRST invalid meta found —
+ *   naming the specific state id, so an agent authoring a machine gets an
+ *   actionable pointer straight to the bad state instead of a generic error.
+ */
+export function collectMachineAnimationMeta(
+  root: AnimationMetaStateNodeLike,
+): MachineAnimationMetaEntry[] {
+  const out: MachineAnimationMetaEntry[] = [];
+  const visit = (node: AnimationMetaStateNodeLike): void => {
+    if (node.meta && 'animation' in node.meta && node.meta.animation !== undefined) {
+      out.push({ stateId: node.id, meta: parseStateAnimationMeta(node.id, node.meta.animation) });
+    }
+    for (const child of Object.values(node.states ?? {})) visit(child);
+  };
+  visit(root);
+  return out;
+}
+
+/** Every clip name referenced anywhere in a validated meta (1 for clip states, N for blend trees). */
+export function clipNamesOf(meta: StateAnimationMeta): string[] {
+  return isClipAnimationMeta(meta) ? [meta.clip] : meta.blendTree.children.map((c) => c.clip);
+}

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();
+}