@vgai/engine 0.5.2 → 0.5.4

package/src/adapter/ingest/overlay-report.ts

@@ -1,176 +0,0 @@
-/**
- * Overlay apply report — D9 (docs/DECISIONS-PENDING.md §D9): decide + surface
- * what happens when a saved ingest overlay is reapplied onto a scene that may
- * have moved on since the overlay was authored (a vendored game bump, or a
- * dynamic subtree that never respawned). Two independent signals, either of
- * which is worth a loud (never silent) structured warning:
- *   - a GAME-VERSION mismatch: the overlay's `authoredAgainst.gameVersion`
- *     (`./overlay-file.ts`'s envelope, stamped from the manifest's `version`
- *     at save time) disagrees with the currently-mounted game's version;
- *   - ORPHANED ids: structural-path ids in the overlay that resolved to
- *     nothing on the current scene walk (`./overlay-apply.ts`'s
- *     `applyOverlayToObjects`).
- *
- * Neither condition blocks mounting — the overlay still applies everything it
- * CAN; this module only decides whether/how to report what it couldn't.
- *
- * This is the SEAM T3.8 (the runtime overlay applier, i.e. reapplying an
- * ingest overlay against a shipped/played build rather than the editor)
- * reuses: `./overlay-applier.ts`'s `applyVgaiOverlay` builds + logs this EXACT
- * report shape, same as the editor does. Moved here from the editor-only
- * module that used to own it (`packages/editor/src/authoring/overlay-report.ts`,
- * which now re-exports everything below unchanged plus the editor-only
- * "active report" banner slot) — kept dependency-free (no `editor-console`/
- * `window` import) so it stays importable from a headless runtime context —
- * same discipline as `../achieved-tier.ts`.
- *
- * R5 (docs/MASTER-ARCHITECTURE-REVIEW.md §4(c)/§7.1 item 9) adds a THIRD
- * independent signal alongside version-mismatch/orphans: an UPSTREAM-PIN
- * mismatch. `gameVersion` alone cannot catch a same-slot substitution after a
- * re-vendor (structural ids are position+type+name; a re-vendor that keeps a
- * slot's shape reapplies the overlay onto a semantically different object
- * with `applied:1, orphanedIds:[]`, and every vendored game's manifest
- * `version` is hand-set and need not change on a re-vendor). The upstream pin
- * (`./upstream-pin.ts`, read from the vendored game's `UPSTREAM.md`) is bound
- * to the thing that actually changes. Like the other two signals, a mismatch
- * never blocks application — it's a report, not a block (matching orphan
- * semantics) — so a re-vendor surfaces as an explicit "authored against pin
- * X, applying onto pin Y" instead of silent success.
- */
-
-/** One mount's version + orphan findings — the D9 acceptance-criteria shape. */
-export interface OverlayApplyReport {
-  gameId: string;
-  /** `authoredAgainst.gameVersion` from the loaded overlay envelope, or `null` if never stamped. */
-  authoredAgainst: string | null;
-  /** The currently-mounted game's manifest `version`, or `null` if unknown at this call site. */
-  currentVersion: string | null;
-  /** Both sides known AND different — never true if either side is `null` (anti-shim: no guessing). */
-  versionMismatch: boolean;
-  applied: number;
-  /** Structural-path ids present in the overlay that resolved to nothing on this scene walk. */
-  orphanedIds: string[];
-  /**
-   * R5 — upstream-pin identity check (see this module's header). Distinct
-   * from `versionMismatch`/`orphanedIds`: it catches a same-slot
-   * SUBSTITUTION (id persists, meaning changed) that those two cannot.
-   */
-  upstreamPin: {
-    /** The pin the overlay was authored against, or `null` if never recorded/discoverable. */
-    authored: string | null;
-    /** The currently-mounted game's own discoverable pin, or `null` if undiscoverable here
-     * (e.g. the runtime ship-path applier, which has no `UPSTREAM.md` access at all — a
-     * documented no-op there — or an externally-authored, non-vendored project). */
-    current: string | null;
-    /**
-     * Whether the SAVED overlay envelope recorded the upstream-pin concept at
-     * all (i.e. `authoredAgainst.upstreamPin` was a present key, even if its
-     * value was `null`). `false` means a legacy overlay — saved by pre-R5
-     * code (or the pre-D9 flat-file shape) — for which the pin check is
-     * skipped entirely, not silently treated as a match. This is the
-     * "explicit legacy indication" the report surfaces so a legacy overlay's
-     * clean apply doesn't read as "verified" when it was never checked.
-     */
-    recorded: boolean;
-    /** `recorded` AND both sides known AND different — never true otherwise (anti-shim). */
-    mismatch: boolean;
-  };
-}
-
-/** Greppable prefix shared by every overlay-related log line (mirrors `achieved-tier.ts`'s `TIER_SHORTFALL_PREFIX`). */
-export const OVERLAY_REPORT_PREFIX = 'overlay-report';
-
-/** Build the report from a mount's raw findings — pure, no logging. */
-export function buildOverlayApplyReport(args: {
-  gameId: string;
-  authoredAgainst: string | null;
-  currentVersion: string | null;
-  applied: number;
-  orphanedIds: string[];
-  /**
-   * R5: the loaded overlay's `authoredAgainst.upstreamPin`. Pass `undefined`
-   * (or omit) when the saved envelope never had the key at all (legacy
-   * overlay — `upstreamPin.recorded` becomes `false`); pass `null` when the
-   * envelope DID have the key but its value was `null` (R5-aware code
-   * looked, found nothing — `recorded` is `true`, `authored` is `null`); pass
-   * the pin string otherwise.
-   */
-  authoredUpstreamPin?: string | null | undefined;
-  /**
-   * R5: the currently-mounted game's own discoverable pin, or `null`/omitted
-   * when undiscoverable at this call site (anti-shim: never fabricated).
-   */
-  currentUpstreamPin?: string | null | undefined;
-}): OverlayApplyReport {
-  const versionMismatch =
-    args.authoredAgainst !== null &&
-    args.currentVersion !== null &&
-    args.authoredAgainst !== args.currentVersion;
-  const recorded = args.authoredUpstreamPin !== undefined;
-  const authoredPin = args.authoredUpstreamPin ?? null;
-  const currentPin = args.currentUpstreamPin ?? null;
-  const upstreamPinMismatch =
-    recorded && authoredPin !== null && currentPin !== null && authoredPin !== currentPin;
-  return {
-    gameId: args.gameId,
-    authoredAgainst: args.authoredAgainst,
-    currentVersion: args.currentVersion,
-    applied: args.applied,
-    orphanedIds: args.orphanedIds,
-    versionMismatch,
-    upstreamPin: {
-      authored: authoredPin,
-      current: currentPin,
-      recorded,
-      mismatch: upstreamPinMismatch,
-    },
-  };
-}
-
-/** Whether this report is worth surfacing (mismatch OR any orphan) — pure, no logging. */
-export function overlayReportWarrants(report: OverlayApplyReport): boolean {
-  return report.versionMismatch || report.orphanedIds.length > 0 || report.upstreamPin.mismatch;
-}
-
-/** The one shared message shape — greppable on the prefix, JSON-parseable on the trailing payload. */
-export function formatOverlayApplyReportMessage(report: OverlayApplyReport): string {
-  const parts: string[] = [];
-  if (report.versionMismatch) {
-    parts.push(
-      `overlay authored against v${report.authoredAgainst}, game is v${report.currentVersion}`,
-    );
-  }
-  if (report.upstreamPin.mismatch) {
-    parts.push(
-      `overlay authored against upstream pin ${report.upstreamPin.authored}, ` +
-        `game is vendored at pin ${report.upstreamPin.current}`,
-    );
-  }
-  if (report.orphanedIds.length > 0) {
-    parts.push(
-      `${report.orphanedIds.length} orphaned overlay entr${report.orphanedIds.length === 1 ? 'y' : 'ies'}`,
-    );
-  }
-  return (
-    `${OVERLAY_REPORT_PREFIX} game "${report.gameId}": ${parts.join('; ')} ` +
-    `(D9, docs/DECISIONS-PENDING.md §D9; upstream-pin check R5, ` +
-    `docs/MASTER-ARCHITECTURE-REVIEW.md §4(c)). ${OVERLAY_REPORT_PREFIX} ${JSON.stringify(report)}`
-  );
-}
-
-/**
- * Emit the ONE structured `console.warn` this report warrants (mirroring the
- * tier-shortfall pattern), or do nothing when neither signal fires. Returns
- * whether it warned (callers that also want the panel-visible `editorConsole`
- * echo, or the inline banner, use the return value / the report itself).
- */
-export function logOverlayApplyReport(report: OverlayApplyReport): boolean {
-  if (!overlayReportWarrants(report)) return false;
-  // The D9 AC requires this EXACT native console.warn (spied on directly in
-  // overlay-versioning.test.ts) — other deliberate native console.warn call sites in
-  // this codebase (e.g. editor-store.ts) are unsuppressed and already counted in the
-  // lint baseline; this one is suppressed to keep this task's diff at zero NEW warnings.
-  // biome-ignore lint/suspicious/noConsole: see comment above
-  console.warn(formatOverlayApplyReportMessage(report));
-  return true;
-}

package/src/animation/gsap-registration.ts

@@ -1,184 +0,0 @@
-import gsap from 'gsap';
-import type { SystemPhaseName } from '../core/types';
-import type { AnimationClock, ClockEvaluatorHandle } from './animation-clock';
-
-/**
- * D7 — register a native, paused GSAP timeline on the canonical
- * `AnimationClock` (spec §10 D7, §5.5 GSAP Contract, §3.2).
- *
- * Mirrors `theatre-clock-binding.ts` (D2)'s shape: VGAI's entire GSAP
- * integration is "who drives time". Games build GSAP timelines with GSAP's
- * own native, un-renamed API (`gsap.timeline()`, `.to()`, `.from()`, …,
- * spec §5.5) — this module never wraps or renames the tween-building API. It
- * only stores the native `gsap.core.Timeline` and seeks it every time the
- * clock moves, exactly like the Theatre sequence binding seeks
- * `sequence.position`.
- *
- * ## Unregistered GSAP is unaffected (§5.5 contract)
- *
- * `gsap.to(enemy.position, { … })` called anywhere in game code — without
- * ever touching this module — keeps running on GSAP's own real-time,
- * `requestAnimationFrame`-driven global ticker exactly as GSAP ships it. This
- * module does not touch `gsap.ticker`, `gsap.globalTimeline`, or any other
- * global GSAP state, precisely so it cannot perturb that ordinary real-time
- * code path. Only a timeline explicitly passed to `registerGsap` — and
- * created paused — participates in deterministic scrub/export.
- *
- * ## Why a PAUSED timeline seeked with `.time()` is deterministic
- *
- * GSAP's global ticker only auto-advances animations that are actually
- * playing; a timeline created with `{ paused: true }` (and never resumed) is
- * never touched by the ticker's rAF-driven `dt` accumulation, so wall-clock
- * elapsed time, dropped frames, and GSAP's lag-smoothing heuristics (which
- * exist purely to compensate a *playing* animation for an irregular ticker
- * `dt`) cannot affect it. The only thing that ever moves a registered
- * timeline's playhead is this module's own `timeline.time(clock.time)` call,
- * driven synchronously off the clock — same story as `theatre-clock-binding`
- * driving `sequence.position` off the clock instead of Theatre's own raf
- * loop. This is proven directly against the real `gsap` runtime in
- * `packages/engine/test/gsap-registration.test.ts` (including a real
- * wall-clock `setTimeout` wait between two `clock.seek()` calls to the same
- * time, asserting the sampled value is bit-for-bit identical — nothing
- * "polished" the value while real time passed). `timeline.time(value)` (not
- * `.seek(value)`) is used because it takes only a numeric offset in the
- * clock's own second-denominated domain — `.seek()`'s label-string overload
- * is irrelevant here and would only widen the accepted input past what a
- * clock time actually is. Neither call resumes playback; both simply
- * position an already-paused timeline, which is why this module never calls
- * `.play()`/`.resume()`.
- *
- * ## Phase choice
- *
- * Registered by default at the `'animation'` phase — the same phase
- * `bindClockToTheatreSequence` (D2) uses, and the same phase
- * XState-bound `AnimationMixer` playback ticks in (see `ARCHITECTURE.md`'s
- * phase table). A registered GSAP timeline commonly targets the same
- * Object3D/material properties a Theatre-driven object binding also writes,
- * so keeping both in the `'animation'` phase (ahead of `'preRender'`, where
- * camera/material reads happen) avoids ordering surprises.
- */
-
-export interface GsapRegistrationOptions {
-  /** Which `AnimationClock` phase to seek the timeline in. Defaults to `'animation'`. */
-  phase?: SystemPhaseName;
-}
-
-export interface GsapRegistration {
-  /**
-   * Removes the clock evaluator and stops driving the timeline (no further
-   * `timeline.time(...)` calls occur after this). Also frees this
-   * clock+timeline pair for re-registration (see `GsapRegistrationError`'s
-   * `'duplicate'` case below).
-   */
-  dispose(): void;
-}
-
-/**
- * Thrown by `registerGsap` when the input does not satisfy the D7 contract.
- * `code` distinguishes the three rejection reasons so a caller can branch on
- * it programmatically instead of string-matching `message`:
- *
- *  - `'not-a-timeline'` — the second argument is not a real
- *    `gsap.core.Timeline` instance (e.g. a plain object, a single GSAP
- *    `Tween`, or `undefined`). Checked with `instanceof gsap.core.Timeline`
- *    against the actual installed GSAP runtime, not duck-typing, so a
- *    same-shaped fake cannot slip through.
- *  - `'not-paused'` — the timeline exists but was not created with
- *    `{ paused: true }` (or was later resumed) at registration time. This
- *    module deliberately REJECTS rather than silently force-pausing: a
- *    caller who already relies on the timeline advancing in real time (e.g.
- *    a UI polish tween that happens to also get registered by mistake) would
- *    otherwise have its behavior silently changed. Rejecting makes the fix
- *    (`gsap.timeline({ paused: true })`) obvious at the call site instead of
- *    producing a hard-to-notice runtime pause.
- *  - `'duplicate'` — this exact timeline is already registered against this
- *    exact clock. Detected per `(clock, timeline)` pair (not globally), so
- *    the same timeline may legitimately be registered against two
- *    independent clocks/cinematic contexts — mirroring D2's "multiple
- *    projects/sheets coexist" allowance — while registering it twice on the
- *    SAME clock (almost always a bug: a duplicate `useEffect` run, a missed
- *    disposer, …) is caught immediately instead of silently doubling the
- *    number of `.time()` writes per crossing.
- */
-export class GsapRegistrationError extends Error {
-  constructor(
-    message: string,
-    readonly code: 'not-a-timeline' | 'not-paused' | 'duplicate',
-  ) {
-    super(message);
-    this.name = 'GsapRegistrationError';
-  }
-}
-
-// Per-clock membership of already-registered timelines. A WeakMap keyed by
-// clock (not a field on AnimationClock itself — D1 owns no knowledge of
-// GSAP) holding a WeakSet keyed by timeline, so neither the clock nor a
-// disposed/dropped timeline is kept alive by this module.
-const registeredByClock = new WeakMap<AnimationClock, WeakSet<gsap.core.Timeline>>();
-
-/**
- * Register a native, paused `gsap.core.Timeline` on `clock`: from now on,
- * every clock crossing (`seek`, `advance`, idempotent re-seeks, `setRange`
- * clamps — anything that fires a `ClockEvaluator`, per `animation-clock.ts`)
- * positions the timeline at `clock.time` via `timeline.time(clock.time)`.
- * The timeline is never played/resumed — it stays paused and is driven
- * exclusively by the clock, both in live preview and in offline
- * frame-by-frame export (whatever calls `clock.seek`/`clock.seekFrame`).
- *
- * Throws `GsapRegistrationError` if `timeline` is not a real
- * `gsap.core.Timeline`, is not paused, or is already registered against this
- * `clock` — see that class's doc comment for the exact policy on each case.
- *
- * Returns a `GsapRegistration` whose `dispose()` removes the clock evaluator
- * (mirrors `bindClockToTheatreSequence`'s `TheatreClockBinding`).
- */
-export function registerGsap(
-  clock: AnimationClock,
-  timeline: gsap.core.Timeline,
-  options: GsapRegistrationOptions = {},
-): GsapRegistration {
-  if (!(timeline instanceof gsap.core.Timeline)) {
-    throw new GsapRegistrationError(
-      '[registerGsap] expected a native gsap.core.Timeline (e.g. gsap.timeline({ paused: true })), ' +
-        `got ${timeline === null ? 'null' : typeof timeline}`,
-      'not-a-timeline',
-    );
-  }
-  if (!timeline.paused()) {
-    throw new GsapRegistrationError(
-      '[registerGsap] timeline must be created paused — gsap.timeline({ paused: true }) — before ' +
-        'registration; a registered timeline is driven exclusively by the clock and must never also ' +
-        'be advancing under its own real-time playback',
-      'not-paused',
-    );
-  }
-
-  let seenForClock = registeredByClock.get(clock);
-  if (!seenForClock) {
-    seenForClock = new WeakSet();
-    registeredByClock.set(clock, seenForClock);
-  }
-  if (seenForClock.has(timeline)) {
-    throw new GsapRegistrationError(
-      '[registerGsap] this timeline is already registered against this clock — dispose() the prior ' +
-        'registration before registering it again',
-      'duplicate',
-    );
-  }
-  seenForClock.add(timeline);
-
-  const phase = options.phase ?? 'animation';
-  const handle: ClockEvaluatorHandle = clock.subscribe(phase, () => {
-    timeline.time(clock.time);
-  });
-
-  let disposed = false;
-  return {
-    dispose(): void {
-      if (disposed) return;
-      disposed = true;
-      handle.dispose();
-      seenForClock!.delete(timeline);
-    },
-  };
-}

package/src/audio/audio-introspection.ts

@@ -1,290 +0,0 @@
-/**
- * W3c — first-party `AudioAdapter` INTROSPECTION over the engine's own audio
- * stack (the engine is its own first adapter). `attachAudioIntrospection`
- * augments the mute-only adapter `createAudioSystemAdapter` built with the
- * optional read-only debugger capabilities the editor's Audio tab consumes:
- *
- *  - `graphSnapshot()` — the engine bus hierarchy (`setup-audio.ts`'s
- *    music/sfx/voice → master → destination, plus the THREE listener tap)
- *    and every Tone node a game routed through `connectToneBusToMasterGain`
- *    (recorded at that seam — see `tone-context.ts`). Tone-INTERNAL wiring
- *    (a game's private synth chains) is not visible from here and is not
- *    fabricated; a game wanting richer graphs registers its own adapter.
- *  - `transportState()` — Tone's real transport (`Tone.getTransport()`),
- *    reported ONLY when the game bridged Tone onto this world's context
- *    (`hasToneBridge`); otherwise an honest `null` ("no musical transport"),
- *    and Tone's global context is never instantiated just by asking.
- *  - `acquireMeters()` — per-bus linear-RMS levels via native `AnalyserNode`
- *    taps (the "Tone.Meter or equivalent": analysers work identically
- *    whether or not Tone is bridged, and disposal is a plain disconnect).
- *    Returns `null` on a headless world (no real `createAnalyser`).
- *  - `audioEvents()` — bounded seq-fenced ring fed by REAL observation
- *    points only: Tone transport start/stop/pause emitter events (attached
- *    lazily once a bridge exists), native context `statechange`, and the
- *    adapter's own mute/unmute calls.
- *
- * SQ-4 boundary: this module is the READ-ONLY debugger seam. The full mixer
- * (sends/effects/per-bus gain EDITING, FMOD-class adaptive-audio authoring)
- * waits on SQ-4 and is deliberately absent here.
- *
- * Uses Tone directly (no wrapper). The EDITOR never imports this module or
- * Tone — it consumes only `SystemAdapters.audio` (mirror of the networking
- * rule). Wired by `vgai-scene-game-adapter.ts` via dynamic import so `tone`
- * stays out of the mount-critical chunk, with the returned disposer called
- * from `disposeGame` (no leaked transport listeners across mounts — the
- * Tone transport is a singleton that outlives any one world).
- */
-
-import * as Tone from 'tone';
-import type {
-  AudioAdapter,
-  AudioDebugEvent,
-  AudioGraphNode,
-  AudioMeterFrame,
-  AudioMeterHandle,
-  AudioTransportState,
-} from '../adapter/system-adapter';
-import type { AudioContext as GameAudio } from '../setup/setup-audio';
-import { getToneMasterGainRoutes, hasToneBridge } from './tone-context';
-
-/** Ring capacity — mirrors the debug-event ring's bounded-drop-oldest idiom. */
-const EVENT_RING_CAP = 200;
-
-function now(): number {
-  return typeof performance !== 'undefined' ? performance.now() : Date.now();
-}
-
-function ctorName(value: object): string {
-  const name = (value as { constructor?: { name?: string } }).constructor?.name;
-  return name && name !== 'Object' ? name : 'AudioNode';
-}
-
-/**
- * Attach the W3c introspection capabilities to `adapter` (mutating it — the
- * same object stays registered on `SystemAdapters.audio`) and return a
- * disposer that detaches every listener and releases any meter handle still
- * alive. Idempotent per adapter object is NOT required: call once per mount.
- */
-export function attachAudioIntrospection(adapter: AudioAdapter, audio: GameAudio): () => void {
-  // --- event ring -----------------------------------------------------------
-  const ring: AudioDebugEvent[] = [];
-  let nextSeq = 1;
-  const record = (kind: AudioDebugEvent['kind'], detail?: string): void => {
-    const event: AudioDebugEvent = { seq: nextSeq++, time: now(), kind };
-    if (detail !== undefined) event.detail = detail;
-    ring.push(event);
-    if (ring.length > EVENT_RING_CAP) ring.splice(0, ring.length - EVENT_RING_CAP);
-  };
-
-  // The native context, when this world has a real one (headless worlds use
-  // a plain stand-in whose `listener.context` may be absent).
-  const nativeContext = (): (BaseAudioContext & Partial<AudioContext>) | null => {
-    const context = (audio.listener as { context?: BaseAudioContext } | undefined)?.context;
-    return context && typeof context.state === 'string'
-      ? (context as BaseAudioContext & Partial<AudioContext>)
-      : null;
-  };
-
-  /** Tone is CURRENTLY bridged onto this world's context. `hasToneBridge`
-   *  gates first so `Tone.getContext()` is only consulted when a Tone global
-   *  context already exists (never fabricating one — see tone-context.ts). */
-  const isBridged = (): boolean => {
-    const context = nativeContext();
-    if (!context || !hasToneBridge(context as AudioContext)) return false;
-    try {
-      return Tone.getContext().rawContext === context;
-    } catch {
-      return false; // no constructible Tone context in this environment (Node)
-    }
-  };
-
-  // --- mute/unmute events: wrap the adapter's OWN entry point ---------------
-  const baseSetMuted = adapter.setMuted.bind(adapter);
-  adapter.setMuted = (muted: boolean): void => {
-    baseSetMuted(muted);
-    record(muted ? 'mute' : 'unmute');
-  };
-
-  // --- context statechange --------------------------------------------------
-  const context = nativeContext();
-  const onStateChange = (): void => {
-    record('context-statechange', nativeContext()?.state ?? 'unknown');
-  };
-  if (context && typeof context.addEventListener === 'function') {
-    context.addEventListener('statechange', onStateChange);
-  }
-
-  // --- transport events (lazy: the game bridges Tone DURING its setup, after
-  //     this adapter is seeded — so hooks attach on the first capability read
-  //     that finds a live bridge) ------------------------------------------
-  let transportHooked = false;
-  const onTransportStart = (): void => record('transport-start');
-  const onTransportStop = (): void => record('transport-stop');
-  const onTransportPause = (): void => record('transport-pause');
-  const ensureTransportHooks = (): void => {
-    if (transportHooked || !isBridged()) return;
-    transportHooked = true;
-    const transport = Tone.getTransport();
-    transport.on('start', onTransportStart);
-    transport.on('stop', onTransportStop);
-    transport.on('pause', onTransportPause);
-    // A game typically bridges Tone and starts its transport DURING setup(),
-    // before anything polls this adapter — that start predates the listeners
-    // above. If the transport is already running at hook time, record that
-    // truthful observation (marked as such) so the log's first entry isn't a
-    // hole where the session's defining event happened.
-    if (transport.state === 'started') {
-      record('transport-start', 'already running when observed');
-    }
-  };
-
-  // --- capabilities ---------------------------------------------------------
-
-  adapter.graphSnapshot = (): AudioGraphNode[] => {
-    const nodes: AudioGraphNode[] = [];
-    const contextState = nativeContext()?.state;
-    const destination: AudioGraphNode = {
-      id: 'destination',
-      type: 'AudioDestinationNode',
-      label: 'Output',
-      outputs: [],
-    };
-    if (contextState !== undefined) destination.state = contextState;
-    nodes.push(destination);
-    nodes.push({
-      id: 'master',
-      type: ctorName(audio.masterGain),
-      label: 'Master',
-      outputs: ['destination'],
-    });
-    nodes.push({
-      id: 'bus-music',
-      type: ctorName(audio.buses.music),
-      label: 'Music bus',
-      outputs: ['master'],
-    });
-    nodes.push({
-      id: 'bus-sfx',
-      type: ctorName(audio.buses.sfx),
-      label: 'SFX bus',
-      outputs: ['master'],
-    });
-    nodes.push({
-      id: 'bus-voice',
-      type: ctorName(audio.buses.voice),
-      label: 'Voice bus',
-      outputs: ['master'],
-    });
-    if (audio.listener) {
-      nodes.push({
-        id: 'listener',
-        type: ctorName(audio.listener),
-        label: '3D listener (THREE)',
-        outputs: ['master'],
-      });
-    }
-    // Tone nodes routed into THIS world's master bus (seam-recorded; disposed
-    // nodes are pruned by the registry itself).
-    getToneMasterGainRoutes(audio.masterGain).forEach((toneNode, index) => {
-      nodes.push({
-        id: `tone-${index}`,
-        // Tone nodes carry their own class name (`'Gain'`, `'Volume'`…).
-        type: (toneNode as { name?: string }).name ?? ctorName(toneNode),
-        label: `Tone route ${index + 1}`,
-        outputs: ['master'],
-      });
-    });
-    return nodes;
-  };
-
-  adapter.transportState = (): AudioTransportState | null => {
-    ensureTransportHooks();
-    if (!isBridged()) return null; // honest: no musical transport in this world
-    const transport = Tone.getTransport();
-    return {
-      state: transport.state,
-      seconds: transport.seconds,
-      bpm: transport.bpm.value,
-      position: String(transport.position),
-    };
-  };
-
-  const liveMeterHandles = new Set<AudioMeterHandle>();
-  adapter.acquireMeters = (): AudioMeterHandle | null => {
-    const meterContext = nativeContext();
-    if (!meterContext || typeof meterContext.createAnalyser !== 'function') {
-      return null; // headless world — metering is impossible, and says so
-    }
-    const taps = (
-      [
-        ['master', 'Master', audio.masterGain],
-        ['bus-music', 'Music', audio.buses.music],
-        ['bus-sfx', 'SFX', audio.buses.sfx],
-        ['bus-voice', 'Voice', audio.buses.voice],
-      ] as const
-    ).map(([id, label, gain]) => {
-      const analyser = meterContext.createAnalyser();
-      analyser.fftSize = 1024;
-      gain.connect(analyser); // a TAP (analyser is a sink), not an insert
-      return { id, label, gain, analyser, buffer: new Float32Array(analyser.fftSize) };
-    });
-    let disposed = false;
-    const handle: AudioMeterHandle = {
-      read: (): AudioMeterFrame[] =>
-        taps.map(({ id, label, analyser, buffer }) => {
-          analyser.getFloatTimeDomainData(buffer);
-          let sum = 0;
-          for (let i = 0; i < buffer.length; i++) {
-            const sample = buffer[i] as number;
-            sum += sample * sample;
-          }
-          return { id, label, level: Math.sqrt(sum / buffer.length) };
-        }),
-      dispose: (): void => {
-        if (disposed) return;
-        disposed = true;
-        for (const tap of taps) {
-          try {
-            tap.gain.disconnect(tap.analyser);
-          } catch {
-            // already torn down with the context — nothing to release
-          }
-        }
-        liveMeterHandles.delete(handle);
-      },
-    };
-    liveMeterHandles.add(handle);
-    return handle;
-  };
-
-  adapter.audioEvents = (sinceSeq?: number): AudioDebugEvent[] => {
-    ensureTransportHooks();
-    return sinceSeq !== undefined ? ring.filter((e) => e.seq > sinceSeq) : [...ring];
-  };
-
-  // --- teardown -------------------------------------------------------------
-  return (): void => {
-    if (transportHooked) {
-      try {
-        const transport = Tone.getTransport();
-        transport.off('start', onTransportStart);
-        transport.off('stop', onTransportStop);
-        transport.off('pause', onTransportPause);
-      } catch {
-        // Tone context already closed — the listeners died with it
-      }
-      transportHooked = false;
-    }
-    if (context && typeof context.removeEventListener === 'function') {
-      context.removeEventListener('statechange', onStateChange);
-    }
-    // Safety net: a consumer should dispose its own handle, but Stop must
-    // never leak analyser taps regardless.
-    for (const handle of [...liveMeterHandles]) handle.dispose();
-    adapter.setMuted = baseSetMuted;
-    delete adapter.graphSnapshot;
-    delete adapter.transportState;
-    delete adapter.acquireMeters;
-    delete adapter.audioEvents;
-  };
-}