@volter/editor-game 0.5.66 → 0.5.68

package/src/runtime/adapter/native-debug-module.ts

@@ -0,0 +1,498 @@
+/**
+ * The ordinary module surface a native game may expose to its own debugger.
+ *
+ * A root entry re-exports one `debug` object from the project's command module:
+ *
+ *   export { debug } from './commands';
+ *
+ * The command module imports no vgai API. Its functions are the application's
+ * own functions over its own stores; the native adapter merely projects that
+ * existing registry onto the session debug/input doors after the root mounts.
+ * Loading through the root entry is load-bearing: the functions close over the
+ * exact module graph the mounted application uses, never a separately evaluated
+ * copy of its stores.
+ */
+
+import type { VgaiGameSystemAdapters } from '@volter/editor-project/adapter/ingest/game-contract';
+import type {
+  NativeCommandEntry,
+  NativeDebugBinding,
+  NativeDebugModule,
+  NativeInputValue,
+  NativeInputValueType,
+  NativeSystemsBinding,
+  NativeTable,
+} from '@volter/editor-project/adapter/native-entry-surface';
+import { NATIVE_INPUT_VALUE_TYPES } from '@volter/editor-project/adapter/native-entry-surface';
+import {
+  DebugError,
+  type DebugRegistry,
+  type DebugVirtualInputTarget,
+  getDebugRegistry,
+} from '../debug-registry';
+import type { Game } from '../game';
+import {
+  CONTRACT_SYSTEM_SLOTS,
+  type ContractSurface,
+  projectContractSystemAdapters,
+} from './ingest/contract-system-adapters';
+
+export type {
+  NativeCommandEntry,
+  NativeDebugBinding,
+  NativeDebugModule,
+  NativeInputValue,
+  NativeInputValueType,
+  NativeSystemsBinding,
+  NativeTable,
+} from '@volter/editor-project/adapter/native-entry-surface';
+export { NATIVE_INPUT_VALUE_TYPES } from '@volter/editor-project/adapter/native-entry-surface';
+
+type NativeInputBinding = NonNullable<NativeDebugModule['input']>;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function rejectUnknownKeys(value: Record<string, unknown>, allowed: readonly string[], at: string) {
+  const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (unknown.length > 0) {
+    throw new Error(
+      `${at} has unknown ${unknown.length === 1 ? 'key' : 'keys'}: ${unknown.join(', ')}`,
+    );
+  }
+}
+
+function functionRecord(
+  value: unknown,
+  at: string,
+): Record<string, (...args: unknown[]) => unknown> {
+  if (!isRecord(value)) throw new Error(`${at} must be an object of named functions.`);
+  const out: Record<string, (...args: unknown[]) => unknown> = {};
+  for (const [name, candidate] of Object.entries(value)) {
+    if (!name) throw new Error(`${at} contains an empty name.`);
+    if (typeof candidate !== 'function') throw new Error(`${at}.${name} must be a function.`);
+    out[name] = candidate as (...args: unknown[]) => unknown;
+  }
+  return out;
+}
+
+function parseActions(value: unknown): Record<string, NativeInputValueType> {
+  if (!isRecord(value)) {
+    throw new Error('debug.input.actions must be an object mapping action names to value types.');
+  }
+  const actions: Record<string, NativeInputValueType> = {};
+  for (const [name, valueType] of Object.entries(value)) {
+    if (!name) throw new Error('debug.input.actions contains an empty action name.');
+    if (!NATIVE_INPUT_VALUE_TYPES.includes(valueType as NativeInputValueType)) {
+      throw new Error(
+        `debug.input.actions.${name} must be one of ${NATIVE_INPUT_VALUE_TYPES.join(', ')}.`,
+      );
+    }
+    actions[name] = valueType as NativeInputValueType;
+  }
+  return actions;
+}
+
+function parseInput(value: unknown): NativeInputBinding {
+  if (!isRecord(value)) throw new Error('debug.input must be an object.');
+  rejectUnknownKeys(value, ['actions', 'set', 'clear', 'tap', 'scheduleAtTick'], 'debug.input');
+  if (typeof value['actions'] === 'function') {
+    // A live table: validated per read (requireAction/the actions source), not
+    // here — the whole point is that its content changes after install.
+    const set = value['set'];
+    const clear = value['clear'];
+    if (typeof set !== 'function') throw new Error('debug.input.set must be a function.');
+    if (typeof clear !== 'function') throw new Error('debug.input.clear must be a function.');
+    return value as unknown as NativeInputBinding;
+  }
+  const set = value['set'];
+  const clear = value['clear'];
+  const tap = value['tap'];
+  const scheduleAtTick = value['scheduleAtTick'];
+  if (typeof set !== 'function') throw new Error('debug.input.set must be a function.');
+  if (typeof clear !== 'function') throw new Error('debug.input.clear must be a function.');
+  if (tap !== undefined && typeof tap !== 'function') {
+    throw new Error('debug.input.tap must be a function when provided.');
+  }
+  if (scheduleAtTick !== undefined && typeof scheduleAtTick !== 'function') {
+    throw new Error('debug.input.scheduleAtTick must be a function when provided.');
+  }
+  return {
+    actions: parseActions(value['actions']),
+    set: set as NativeInputBinding['set'],
+    clear: clear as NativeInputBinding['clear'],
+    ...(typeof tap === 'function' ? { tap: tap as NonNullable<NativeInputBinding['tap']> } : {}),
+    ...(typeof scheduleAtTick === 'function'
+      ? {
+          scheduleAtTick: scheduleAtTick as NonNullable<NativeInputBinding['scheduleAtTick']>,
+        }
+      : {}),
+  };
+}
+
+/** Read the single native `debug` export from an already-loaded root module. */
+export function nativeDebugBindingFromEntryModule(
+  rootId: string,
+  entryModule: unknown,
+): NativeDebugBinding | null {
+  if (!isRecord(entryModule) || entryModule['debug'] === undefined) return null;
+  if (!isRecord(entryModule['debug'])) {
+    throw new Error(`Root "${rootId}" exports \`debug\`, but it is not an object.`);
+  }
+  const raw = entryModule['debug'];
+  rejectUnknownKeys(
+    raw,
+    ['commands', 'state', 'input', 'events', 'settled'],
+    `Root "${rootId}" debug export`,
+  );
+
+  // A thunk table defers to install time (see {@link NativeTable}); a plain
+  // record validates here, where the error can still name the export.
+  const parseTable = (value: unknown, at: string) => {
+    if (value === undefined) return undefined;
+    if (typeof value === 'function') return value as () => Readonly<Record<string, never>>;
+    return functionRecord(value, at);
+  };
+  // Commands allow the `{ description?, run }` entry shape; full validation
+  // happens at install (`resolveCommandTable`), where thunks resolve too.
+  const parseCommands = (value: unknown, at: string) => {
+    if (value === undefined) return undefined;
+    if (typeof value === 'function') return value as () => Readonly<Record<string, never>>;
+    if (!isRecord(value)) throw new Error(`${at} must be an object of named commands.`);
+    return value as Readonly<Record<string, NativeCommandEntry>>;
+  };
+  const commands = parseCommands(raw['commands'], 'debug.commands');
+  const state = parseTable(raw['state'], 'debug.state');
+  const input = raw['input'] === undefined ? undefined : parseInput(raw['input']);
+  const events = raw['events'] === undefined ? undefined : parseEvents(raw['events']);
+  const settled = raw['settled'];
+  if (settled !== undefined && typeof settled !== 'function') {
+    throw new Error('debug.settled must be a function returning a boolean.');
+  }
+  if (!commands && !state && !input && !events && !settled) {
+    throw new Error(`Root "${rootId}" exports an empty \`debug\` object.`);
+  }
+  return {
+    rootId,
+    debug: {
+      ...(commands ? { commands } : {}),
+      ...(state ? { state } : {}),
+      ...(input ? { input } : {}),
+      ...(events ? { events } : {}),
+      ...(settled ? { settled: settled as () => boolean } : {}),
+    },
+  };
+}
+
+function parseEvents(value: unknown): NonNullable<NativeDebugModule['events']> {
+  if (!isRecord(value) || typeof value['subscribe'] !== 'function') {
+    throw new Error('debug.events must be an object with a subscribe(listener) function.');
+  }
+  return value as unknown as NonNullable<NativeDebugModule['events']>;
+}
+
+/** Resolve a possibly-thunk COMMAND table, validating each entry's shape. */
+function resolveCommandTable(
+  table: NativeTable<NativeCommandEntry> | undefined,
+  at: string,
+): Readonly<Record<string, NativeCommandEntry>> {
+  if (table === undefined) return {};
+  const raw = typeof table === 'function' ? table() : table;
+  if (!isRecord(raw)) throw new Error(`${at} must be an object of named commands.`);
+  for (const [name, entry] of Object.entries(raw)) {
+    if (!name) throw new Error(`${at} contains an empty name.`);
+    const ok =
+      typeof entry === 'function' ||
+      (isRecord(entry) && typeof (entry as { run?: unknown }).run === 'function');
+    if (!ok) throw new Error(`${at}.${name} must be a function or { description?, run }.`);
+  }
+  return raw as Readonly<Record<string, NativeCommandEntry>>;
+}
+
+/** Resolve a possibly-thunk table at install time, validating the result. */
+function resolveTable<T>(
+  table: NativeTable<T> | undefined,
+  at: string,
+): Readonly<Record<string, T>> {
+  if (table === undefined) return {};
+  if (typeof table === 'function') {
+    return functionRecord(table(), at) as Readonly<Record<string, T>>;
+  }
+  return table;
+}
+
+function valueMatches(type: NativeInputValueType, value: NativeInputValue): boolean {
+  if (type === 'digital') return typeof value === 'boolean';
+  if (type === 'scalar') return typeof value === 'number' && Number.isFinite(value);
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof value.x === 'number' &&
+    Number.isFinite(value.x) &&
+    typeof value.y === 'number' &&
+    Number.isFinite(value.y)
+  );
+}
+
+function installInput(
+  game: Game,
+  registry: DebugRegistry,
+  binding: NativeDebugBinding,
+  input: NativeInputBinding,
+): void {
+  const trace: Array<{ tick: number; action: string; value: NativeInputValue }> = [];
+  let recording = false;
+
+  // LIVE read on every use — see the `actions` field's own comment.
+  const liveActions = (): Readonly<Record<string, NativeInputValueType>> =>
+    typeof input.actions === 'function' ? input.actions() : input.actions;
+
+  const requireAction = (action: string, value: NativeInputValue): NativeInputValueType => {
+    const actions = liveActions();
+    const type = actions[action];
+    if (!type) {
+      throw new DebugError(
+        'INPUT_ACTION_NOT_FOUND',
+        `Native input has no action named "${action}".`,
+        {
+          registered: Object.keys(actions),
+        },
+      );
+    }
+    if (!valueMatches(type, value)) {
+      throw new DebugError(
+        'INPUT_ACTION_VALUE_TYPE',
+        `Native input action "${action}" expects ${type}, not ${typeof value}.`,
+        { action, expected: type },
+      );
+    }
+    return type;
+  };
+
+  const apply = (action: string, value: NativeInputValue, tick: number): void => {
+    requireAction(action, value);
+    input.set(action, value);
+    if (recording) trace.push({ tick, action, value });
+  };
+
+  const unsupportedSource = (method: string): never => {
+    throw new DebugError(
+      'NATIVE_INPUT_SOURCE_UNSUPPORTED',
+      `${method} addresses an engine test source, but this game exposes an app-owned action store. Drive it by action name instead.`,
+    );
+  };
+  const target: DebugVirtualInputTarget = {
+    setVirtualAction(action, value) {
+      apply(action, value, registry.getGameTick());
+      return { delivered: true };
+    },
+    tapVirtualAction(action) {
+      if (!input.tap) {
+        throw new DebugError(
+          'NATIVE_INPUT_TAP_UNSUPPORTED',
+          `Native input for root "${binding.rootId}" does not export tap(); use setVirtualAction through the app-owned store.`,
+        );
+      }
+      requireAction(action, true);
+      input.tap(action);
+      return { delivered: true };
+    },
+    clearVirtualActions() {
+      input.clear();
+    },
+    scheduleActionAtTick(tick, action, value) {
+      const currentTick = registry.getGameTick();
+      if (!Number.isInteger(tick) || tick < currentTick) {
+        throw new DebugError(
+          'TICK_ALREADY_PASSED',
+          `Cannot schedule native input for tick ${tick}; current tick is ${currentTick}.`,
+          { tick, currentTick },
+        );
+      }
+      requireAction(action, value);
+      if (!input.scheduleAtTick) {
+        throw new DebugError(
+          'NATIVE_INPUT_SCHEDULE_UNSUPPORTED',
+          `Native input for root "${binding.rootId}" does not export scheduleAtTick(); the adapter will not create a host scheduler for it.`,
+        );
+      }
+      input.scheduleAtTick(tick, action, value);
+    },
+    startInputRecording() {
+      trace.length = 0;
+      recording = true;
+    },
+    stopInputRecording() {
+      recording = false;
+    },
+    isInputRecording() {
+      return recording;
+    },
+    injectAxis() {
+      unsupportedSource('injectAxis');
+    },
+    injectVector2() {
+      unsupportedSource('injectVector2');
+    },
+    injectPointerDelta() {
+      unsupportedSource('injectPointerDelta');
+    },
+    injectPointerPosition() {
+      unsupportedSource('injectPointerPosition');
+    },
+  };
+
+  registry.setInputActionsSource(binding.rootId, () =>
+    Object.entries(liveActions()).map(([name, valueType]) => ({ name, valueType })),
+  );
+  registry.setInputTraceSource(binding.rootId, () => ({
+    version: 1,
+    seed: null,
+    fixedDt: game.loop.fixedDt,
+    ticks: [...trace],
+  }));
+  registry.setVirtualInputTarget(binding.rootId, target);
+}
+
+/** Project native registries onto the existing session debugger after mount. */
+export function installNativeDebugBindings(
+  game: Game,
+  bindings: readonly NativeDebugBinding[],
+): void {
+  if (bindings.length === 0) return;
+  const registry = getDebugRegistry(game);
+  if (!registry)
+    throw new Error('Cannot install native debug bindings: mounted Game has no debug registry.');
+  for (const binding of bindings) {
+    if (!game.world(binding.rootId)) {
+      throw new Error(`Native debug binding names unmounted root "${binding.rootId}".`);
+    }
+    const root = registry.forRoot(binding.rootId);
+    const state = resolveTable(binding.debug.state, `Root "${binding.rootId}" debug.state`);
+    for (const [name, read] of Object.entries(state)) {
+      root.registerStateProvider(name, read, { tier: 'assisted' });
+    }
+    const commands = resolveCommandTable(
+      binding.debug.commands,
+      `Root "${binding.rootId}" debug.commands`,
+    );
+    for (const [name, entry] of Object.entries(commands)) {
+      const run = typeof entry === 'function' ? entry : entry.run;
+      const description = typeof entry === 'function' ? undefined : entry.description;
+      root.registerCommand(
+        name,
+        { locus: 'client', ...(description === undefined ? {} : { description }) },
+        run,
+      );
+    }
+    if (binding.debug.input) installInput(game, registry, binding, binding.debug.input);
+    // The app's emitter → the session's tick-stamped event log. The
+    // subscription's disposer is deliberately dropped: it lives exactly as
+    // long as this Game's registry does.
+    binding.debug.events?.subscribe((event, detail) => root.emit(event, detail));
+    // The app's own between-worlds truth → the session's tick gate
+    // (`runTicksWhenSettled`). Same lifetime rule as the event subscription.
+    if (binding.debug.settled) registry.registerWorldSettledProbe(binding.debug.settled);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// The native `systems` export — the first-party door onto `SystemAdapters`
+// ---------------------------------------------------------------------------
+//
+// The sibling of `debug` on the SAME module surface: a root entry re-exports
+// one `systems` object beside it —
+//
+//   export { debug, systems } from './commands';
+//
+// — whose slots are the ONE declarable carrier both realms share,
+// `VgaiGameSystemAdapters` (`ingest/game-contract.ts`; the native engine is
+// the premade 100% implementation of that contract). Validation is the SAME
+// projection the ingest realm uses (`ingest/contract-system-adapters.ts`), so
+// there is one shape law, not two. This door is what retires
+// `ctx.registerSystemAdapter` from component code (ARCHITECTURE-CORE §System
+// adapters: "a project's `vgai.adapter.ts` binds app-owned systems through
+// declared native exports … Components never call `registerSystemAdapter`").
+//
+// Native-realm difference from ingest: a malformed slot THROWS (this is our
+// own code failing its own contract — fail fast), where the ingest projection
+// files a verdict for the coverage report. A `{ present: false, evidence }`
+// slot is accepted as the positive absence it is and binds nothing.
+
+/**
+ * Read the single native `systems` export from an already-loaded root module.
+ * `surface` is the root's own mount surface when the caller knows it — it
+ * feeds the physics keying check (`PHYSICS_KEYING_BY_SURFACE`).
+ */
+export function nativeSystemsBindingFromEntryModule(
+  rootId: string,
+  entryModule: unknown,
+  surface?: ContractSurface | undefined,
+): NativeSystemsBinding | null {
+  if (!isRecord(entryModule) || entryModule['systems'] === undefined) return null;
+  const raw = entryModule['systems'];
+  if (!isRecord(raw)) {
+    throw new Error(`Root "${rootId}" exports \`systems\`, but it is not an object.`);
+  }
+  rejectUnknownKeys(raw, CONTRACT_SYSTEM_SLOTS, `Root "${rootId}" systems export`);
+  const projection = projectContractSystemAdapters(
+    { systemAdapters: raw as VgaiGameSystemAdapters },
+    surface,
+  );
+  if (projection.malformed.length > 0) {
+    throw new Error(
+      `Root "${rootId}" systems export is malformed: ` +
+        projection.malformed.map((slot) => `${slot.slot} — ${slot.reason}`).join('; '),
+    );
+  }
+  if (Object.keys(projection.bound).length === 0 && projection.empty.length === 0) {
+    throw new Error(`Root "${rootId}" exports an empty \`systems\` object.`);
+  }
+  return { rootId, slots: projection.bound, absent: projection.empty };
+}
+
+/**
+ * Install every declared binding onto the mounted Game's game-scoped slot
+ * table (`Game.installDeclaredSystemAdapters`), where the ordinary
+ * `game.systemAdapters` merge picks them up ahead of any lingering component
+ * registration for the same root.
+ *
+ * A root's ABSENCES travel the same call and install NOTHING — they are
+ * recorded, never bound, because the whole point of `absent()` is that no
+ * adapter exists to bind (see its comment: a marker, never a stub). They are
+ * recorded HERE rather than left on the binding alone so the answer is
+ * game-scoped, matching the registry every editor panel already reads: a
+ * `SystemAdapters` slot is filled by whichever root builds it, so "does this
+ * GAME have physics" cannot be answered one root at a time.
+ *
+ * A root that declares only absences therefore still calls through — skipping
+ * it on an empty `slots` map is what would drop exactly the games whose whole
+ * declaration is "I have none of these".
+ */
+export function installNativeSystemsBindings(
+  game: Game,
+  bindings: readonly NativeSystemsBinding[],
+): void {
+  if (bindings.length === 0) return;
+  const install = game.installDeclaredSystemAdapters;
+  if (!install) {
+    throw new Error(
+      'Cannot install native systems bindings: this Game does not implement ' +
+        'installDeclaredSystemAdapters.',
+    );
+  }
+  for (const binding of bindings) {
+    if (Object.keys(binding.slots).length === 0 && binding.absent.length === 0) continue;
+    install.call(
+      game,
+      binding.rootId,
+      binding.slots,
+      binding.absent.map((slot) => ({
+        rootId: binding.rootId,
+        slot: slot.slot,
+        reason: slot.evidence,
+      })),
+    );
+  }
+}

package/src/runtime/audio/bus-mixer.ts

@@ -0,0 +1,161 @@
+/**
+ * A named-bus mixer over Web Audio: buses created on demand, routed into each
+ * other by name, and set in DECIBELS.
+ *
+ * Every mixer a game reaches for is this shape — Unity's `AudioMixerGroup`,
+ * Godot's bus layout, FMOD's VCAs, and the `music`/`sfx`/`voice` trio
+ * `setup/setup-audio.ts` hands a first-party three world. What they share is
+ * not the protocol (that part is genuinely per-ecosystem and stays with the
+ * lane that speaks it) but the machinery underneath: a `GainNode` per bus, a
+ * name → node map, a parent to route into, and the one conversion below. This
+ * file owns exactly that, and nothing that names an ecosystem.
+ *
+ * ## dB is not a gain, and the mistake is silent
+ *
+ * `GainNode.gain` is a LINEAR amplitude multiplier; every mixer's authored
+ * volume is logarithmic dB, where 0 dB is unity and −80 dB is silence. Writing
+ * the dB number straight onto `gain.value` gives you a gain of −80 (a phase
+ * inversion at 80x) where the author asked for silence, and it does not throw,
+ * warn, or look wrong in a debugger — it is just loud. {@link dbToLinear} is
+ * the one conversion, `10^(dB/20)`, which is both Godot's `db_to_linear`
+ * (`core/math/math_funcs.h`: `exp(db * 0.11512925464970228…)`, the same
+ * function written in base e) and Unity's mixer volume curve.
+ *
+ * It deliberately does NOT clamp. A mixer's RANGE is protocol — Unity's
+ * exposed parameters saturate at its slider's ends, Godot's `volume_db` does
+ * not — so the lane that knows the range applies it before calling here, and
+ * this file cannot silently mute or silently boost anyone's authored value.
+ *
+ * ## Create-on-demand, and why it is the contract rather than a convenience
+ *
+ * {@link AudioBusMixer.bus} MINTS a bus the first time it is named and returns
+ * the SAME node forever after. The identity is the contract, not the minting:
+ * a source connects to a bus long before anything sets that bus's volume, and
+ * a parent is usually named by its child before anyone asks for it directly
+ * (`bus('music', 'master')` builds `master` too, and the later `bus('master')`
+ * must be that same node). A `bus()` that minted per call would hand the
+ * volume control a SECOND node — the sources would keep feeding the first one,
+ * every later write would land on a node nothing plays through, and nothing
+ * would throw or look wrong. So the map is authoritative, and the only way a
+ * name stops resolving to its node is {@link AudioBusMixer.remove} or
+ * {@link AudioBusMixer.disconnect}.
+ *
+ * A re-ask that names a DIFFERENT parent throws by name. Routing is decided at
+ * creation (the node is already connected by then), so honouring the second
+ * parent would mean silently re-routing live audio and ignoring it would mean
+ * silently keeping the first — a loud error is the only reading that is not a
+ * lie.
+ *
+ * ## RESOURCE OWNERSHIP
+ *
+ * No module-scoped state: {@link createAudioBusMixer} is a factory and the
+ * OWNER of an instance is whoever called it (a `setupAudio` graph, one
+ * translated port's mixer store). What an instance ALLOCATES is one `GainNode`
+ * per named bus, and disconnecting those is the whole of its teardown
+ * obligation — {@link AudioBusMixer.disconnect}, called once by that same
+ * owner. The `context` and the `destination` node are NOT its own: they are
+ * passed in, shared with everything else hanging off the same graph, and this
+ * file never creates, closes, suspends or disconnects either one.
+ */
+
+/**
+ * The graph an {@link AudioBusMixer} hangs off, as the two members it touches.
+ *
+ * Narrow on purpose: `createGain` is all it needs from the context, so a real
+ * `AudioContext`, an `OfflineAudioContext` and a headless stand-in are all
+ * acceptable without a cast.
+ */
+export interface AudioBusMixerOptions {
+  readonly context: { createGain(): GainNode };
+  /** The node every parentless bus feeds. Usually a master gain or the context's destination. */
+  readonly destination: AudioNode;
+}
+
+export interface AudioBusMixer {
+  /**
+   * The bus named `name`, created on the first ask and connected to `parent`
+   * (itself created on demand) or to the destination.
+   *
+   * The returned node is the real `GainNode` — set `gain.value`, schedule
+   * automation on `gain`, connect sources to it. Nothing here stands between a
+   * caller and Web Audio's own API.
+   */
+  bus(name: string, parent?: string): GainNode;
+  /** The bus named `name` if it EXISTS, else null. Never mints one. */
+  find(name: string): GainNode | null;
+  /** Set this bus's gain from decibels, creating it if absent. Clamp before calling — see the header. */
+  setDb(name: string, db: number, parent?: string): void;
+  /**
+   * Disconnect one bus and forget its name, so a later {@link bus} mints a
+   * fresh node. Buses that named it as their parent are NOT re-routed — they
+   * keep feeding the removed node, which now reaches nothing.
+   */
+  remove(name: string): void;
+  /** Disconnect every bus and forget them all. The owner's ONE teardown. */
+  disconnect(): void;
+}
+
+/** dB → linear amplitude: `10^(dB/20)`. 0 dB is 1, −6 dB is ~0.5, −80 dB is ~0.0001. Never clamps. */
+export function dbToLinear(db: number): number {
+  return 10 ** (db / 20);
+}
+
+interface BusRecord {
+  readonly node: GainNode;
+  readonly parent: string | undefined;
+}
+
+function safeDisconnect(node: GainNode): void {
+  try {
+    node.disconnect();
+  } catch {
+    // already disconnected
+  }
+}
+
+/** Create one named-bus mixer. See the header for what owns the instance and what it allocates. */
+export function createAudioBusMixer(options: AudioBusMixerOptions): AudioBusMixer {
+  const { context, destination } = options;
+  const buses = new Map<string, BusRecord>();
+
+  function bus(name: string, parent?: string): GainNode {
+    const existing = buses.get(name);
+    if (existing !== undefined) {
+      if (parent !== undefined && parent !== existing.parent) {
+        throw new Error(
+          `audio bus ${JSON.stringify(name)} already routes into ` +
+            `${existing.parent === undefined ? 'the destination' : JSON.stringify(existing.parent)}` +
+            `; it cannot also route into ${JSON.stringify(parent)}. Routing is decided when a bus ` +
+            'is created (see packages/editor-game/src/runtime/audio/bus-mixer.ts).',
+        );
+      }
+      return existing.node;
+    }
+    // The parent is resolved (and minted, recursively) before this bus is
+    // seated, so a conflicting-parent throw upstream leaves nothing half-built.
+    const into = parent === undefined ? destination : bus(parent);
+    const node = context.createGain();
+    node.gain.value = 1;
+    node.connect(into);
+    buses.set(name, { node, parent });
+    return node;
+  }
+
+  return {
+    bus,
+    find: (name) => buses.get(name)?.node ?? null,
+    setDb: (name, db, parent) => {
+      bus(name, parent).gain.value = dbToLinear(db);
+    },
+    remove: (name) => {
+      const record = buses.get(name);
+      if (record === undefined) return;
+      buses.delete(name);
+      safeDisconnect(record.node);
+    },
+    disconnect: () => {
+      for (const record of buses.values()) safeDisconnect(record.node);
+      buses.clear();
+    },
+  };
+}