Skip to content

Write HTML. Render video. Built for agents.

67.3 KB
Raw Blame
// fallow-ignore-file code-duplication complexity
import { beforeEach, describe, it, expect, vi } from "vitest";
import { MAX_AUDIO_GAIN } from "../audioGain.js";
import { WebAudioTransport } from "./webAudioTransport";

function createMockAudioContext(currentTime = 100) {
  const startFn = vi.fn();
  const endedListeners: (() => void)[] = [];
  const sourceNode = {
    buffer: null as AudioBuffer | null,
    playbackRate: { value: 1 },
    start: startFn,
    stop: vi.fn(),
    disconnect: vi.fn(),
    connect: vi.fn(),
    addEventListener: vi.fn((event: string, cb: () => void) => {
      if (event === "ended") endedListeners.push(cb);
    }),
    _fireEnded: () => endedListeners.forEach((cb) => cb()),
  };
  const gainNode = {
    gain: { value: 1 },
    connect: vi.fn(),
    disconnect: vi.fn(),
  };
  const mediaElementSourceNode = {
    connect: vi.fn(),
    disconnect: vi.fn(),
  };
  const masterGain = {
    gain: { value: 1 },
    connect: vi.fn(),
  };
  const monitorGain = {
    gain: { value: 1 },
    connect: vi.fn(),
  };
  const ctx = {
    currentTime,
    state: "running",
    resume: vi.fn(),
    suspend: vi.fn(() => Promise.resolve()),
    createBufferSource: vi.fn(() => sourceNode),
    createMediaElementSource: vi.fn(() => mediaElementSourceNode),
    // The element gain is the first one a schedule creates; its lane and clip gains get their own.
    createGain: vi.fn(() =>
      ctx.createGain.mock.calls.length === 1
        ? gainNode
        : { gain: { value: 1 }, connect: vi.fn(), disconnect: vi.fn() },
    ),
    destination: {},
    close: vi.fn(),
  };
  return { ctx, sourceNode, mediaElementSourceNode, gainNode, masterGain, monitorGain, startFn };
}

function setupTransport(currentTime = 100) {
  const transport = new WebAudioTransport();
  const mock = createMockAudioContext(currentTime);
  (transport as unknown as { _ctx: unknown })._ctx = mock.ctx;
  (transport as unknown as { _masterGain: unknown })._masterGain = mock.masterGain;
  (transport as unknown as { _monitorGain: unknown })._monitorGain = mock.monitorGain;
  const gen = transport.startGeneration();
  return { transport, mock, gen };
}

const mockBuffer = {} as AudioBuffer;
const mockEl = {
  muted: false,
  volume: 0.4,
  paused: true,
  addEventListener: () => {},
  getAttribute: (name: string) => (name === "data-playback-rate" ? "1" : null),
} as unknown as HTMLMediaElement;

describe("WebAudioTransport author gain vs user volume", () => {
  it("carries a static above-unity author gain onto the element gain node", () => {
    // The regression this ceiling exists to prevent: a static `data-volume`
    // above unity was capped at 1 here while the render honoured it, so preview
    // and render disagreed on every boosted clip. Automation lanes hid it —
    // they schedule ramps onto the param directly and never pass through here.
    const { transport, mock } = setupTransport();
    const el = { muted: false } as HTMLMediaElement;
    transport["_activeSources"] = [
      { el, gainNode: mock.gainNode, clipGainNode: { gain: { value: 1 } }, sourceKind: "buffer" },
    ] as never;

    transport.setElementVolume(el, 1.949845);

    expect(mock.gainNode.gain.value).toBeCloseTo(1.949845, 6);
  });

  it("still refuses a gain beyond the shared ceiling", () => {
    const { transport, mock } = setupTransport();
    const el = { muted: false } as HTMLMediaElement;
    transport["_activeSources"] = [
      { el, gainNode: mock.gainNode, clipGainNode: { gain: { value: 1 } }, sourceKind: "buffer" },
    ] as never;

    transport.setElementVolume(el, 99);

    expect(mock.gainNode.gain.value).toBeCloseTo(MAX_AUDIO_GAIN, 6);
  });

  it("keeps the user's master volume spec-clamped — it is a fader, not a gain", () => {
    const transport = new WebAudioTransport();
    const monitor = { gain: { value: 1 }, connect: vi.fn() };
    (transport as unknown as { _monitorGain: unknown })._monitorGain = monitor;

    transport.setVolume(99);

    expect(monitor.gain.value).toBe(1);
  });
});

describe("WebAudioTransport", () => {
  beforeEach(() => {
    mockEl.muted = false;
    mockEl.volume = 0.4;
  });

  describe("pitch-preserving media-element source route", () => {
    it("routes native media through WebAudio without decoding, resampling, or muting it", async () => {
      const { transport, mock, gen } = setupTransport(100);

      const scheduled = await transport.scheduleMediaElementPlayback(mockEl, 0, 0, 0, 0.8, gen, 2);

      expect(scheduled).not.toBeNull();
      expect(mock.ctx.createMediaElementSource).toHaveBeenCalledWith(mockEl);
      expect(mock.ctx.createBufferSource).not.toHaveBeenCalled();
      expect(mock.mediaElementSourceNode.connect).toHaveBeenCalled();
      expect(mock.gainNode.connect).toHaveBeenCalledWith(mock.masterGain);
      expect(mockEl.muted).toBe(false);
      expect(mockEl.volume).toBe(1);
      expect(mock.gainNode.gain.value).toBe(0.8);
      expect(transport.ownsElement(mockEl)).toBe(false);
      expect(transport.routesElement(mockEl)).toBe(true);
    });

    it("leaves the clock to a routed element, which keeps its own time", async () => {
      const { transport, gen } = setupTransport(100);

      await transport.scheduleMediaElementPlayback(mockEl, 0, 0, 0, 1, gen, 1);

      expect(transport.routesElement(mockEl)).toBe(true);
      expect(transport.ownsClock()).toBe(false);
    });

    it("drops a schedule still waiting on resume() when stopAll comes first", async () => {
      const { transport, mock, gen } = setupTransport(100);
      let resume!: () => void;
      mock.ctx.state = "suspended";
      mock.ctx.resume = vi.fn(() => new Promise<void>((r) => (resume = r)));

      const pending = transport.scheduleMediaElementPlayback(mockEl, 0, 0, 0, 1, gen, 1);
      transport.stopAll();
      resume();

      expect(await pending).toBeNull();
      expect(transport.routesElement(mockEl)).toBe(false);
    });

    it("creates one MediaElementAudioSourceNode per element and context", async () => {
      const { transport, mock } = setupTransport(100);

      let gen = transport.startGeneration();
      await transport.scheduleMediaElementPlayback(mockEl, 0, 0, 0, 1, gen, 1);
      transport.stopAll();
      gen = transport.startGeneration();
      await transport.scheduleMediaElementPlayback(mockEl, 0, 0, 0, 1, gen, 2);

      expect(mock.ctx.createMediaElementSource).toHaveBeenCalledTimes(1);
    });

    it("re-aims FX automation on a global-rate change without resampling the native source", async () => {
      const { transport, mock, gen } = setupTransport(100);
      await transport.scheduleMediaElementPlayback(mockEl, 0, 0, 0, 1, gen, 1);
      const active = (transport as unknown as { _activeSources: { fx?: unknown }[] })
        ._activeSources;
      const setRate = vi.fn();
      active[0]!.fx = { dispose: vi.fn(), setRate };

      transport.setRate(2);

      expect(setRate).toHaveBeenCalledWith(2);
      expect(mock.ctx.createBufferSource).not.toHaveBeenCalled();
    });

    it("disconnects the transient graph on stop but keeps the cached native source reusable", async () => {
      const { transport, mock, gen } = setupTransport(100);
      await transport.scheduleMediaElementPlayback(mockEl, 0, 0, 0, 1, gen, 2);

      transport.stopAll();

      expect(mock.mediaElementSourceNode.disconnect).toHaveBeenCalled();
      expect(mockEl.muted).toBe(false);
      expect(mockEl.volume).toBe(0.4);
      expect(transport.ownsClock()).toBe(false);
    });

    // #3458. `createMediaElementSource` over a CORS-cross-origin resource does
    // not throw — the Web Audio spec asks the node for SILENCE — so the
    // `try/catch` around it never fires and the composition plays through
    // perfectly with no sound. The node also permanently steals the element's
    // native output, so the only possible defence is to not build it.
    it("never builds a source node over cross-origin media with no CORS opt-in", async () => {
      const { transport, mock, gen } = setupTransport(100);
      const el = document.createElement("audio");
      el.setAttribute("src", "https://cdn.example.com/track.mp3");
      vi.spyOn(console, "info").mockImplementation(() => {});

      const scheduled = await transport.scheduleMediaElementPlayback(el, 0, 0, 0, 1, gen, 1);

      expect(scheduled).toBeNull();
      expect(mock.ctx.createMediaElementSource).not.toHaveBeenCalled();
      // Untouched: the caller falls back, and a muted or re-levelled element
      // would take the fallback's audio down with it.
      expect(el.muted).toBe(false);
      expect(transport.routesElement(el)).toBe(false);
    });

    it("still routes cross-origin media that carries the crossorigin opt-in", async () => {
      const { transport, mock, gen } = setupTransport(100);
      const el = document.createElement("audio");
      el.setAttribute("src", "https://cdn.example.com/track.mp3");
      el.setAttribute("crossorigin", "anonymous");

      const scheduled = await transport.scheduleMediaElementPlayback(el, 0, 0, 0, 1, gen, 1);

      expect(scheduled).not.toBeNull();
      expect(mock.ctx.createMediaElementSource).toHaveBeenCalledWith(el);
    });

    it("still routes same-origin media", async () => {
      const { transport, mock, gen } = setupTransport(100);
      const el = document.createElement("audio");
      el.setAttribute("src", "/assets/vo.mp3");

      const scheduled = await transport.scheduleMediaElementPlayback(el, 0, 0, 0, 1, gen, 1);

      expect(scheduled).not.toBeNull();
      expect(mock.ctx.createMediaElementSource).toHaveBeenCalledWith(el);
    });

    // R2 finding: `_mediaElementSources` is keyed by element identity, not by
    // asset. A cache hit alone said nothing about the element's CURRENT
    // resource, so a pooled element reused for a new clip kept handing back
    // the OLD (same-origin) node — and its stale `web-audio` verdict — after
    // `src` moved to a cross-origin asset with no `crossorigin` opt-in. Only
    // `destroy()` ever cleared the cache, so this silenced the element for the
    // rest of the session.
    it("stops returning the cached node once the same element's src moves cross-origin", async () => {
      const { transport, mock, gen: gen1 } = setupTransport(100);
      vi.spyOn(console, "info").mockImplementation(() => {});
      const el = document.createElement("audio");
      el.setAttribute("src", "/assets/vo.mp3");

      const first = await transport.scheduleMediaElementPlayback(el, 0, 0, 0, 1, gen1, 1);
      expect(first).not.toBeNull();
      expect(mock.ctx.createMediaElementSource).toHaveBeenCalledTimes(1);

      transport.stopAll();
      // `stopAll()` itself disconnects the transient graph (see "disconnects
      // the transient graph on stop but keeps the cached native source
      // reusable" above) without evicting the cache — clear the spy so the
      // assertion below is about the FIX's own eviction, not that call.
      mock.mediaElementSourceNode.disconnect.mockClear();
      el.setAttribute("src", "https://cdn.example.com/reused-clip.mp3");
      const gen2 = transport.startGeneration();
      const second = await transport.scheduleMediaElementPlayback(el, 0, 0, 0, 1, gen2, 1);

      expect(second).toBeNull();
      // The one-way door means a fresh node can't be built either — the
      // fix's job is to stop HANDING BACK the stale one, not to conjure a
      // new node over a src that was never eligible.
      expect(mock.ctx.createMediaElementSource).toHaveBeenCalledTimes(1);
      expect(mock.mediaElementSourceNode.disconnect).toHaveBeenCalledTimes(1);
    });

    it("keeps returning the cached node when a reused element's src stays eligible", async () => {
      const { transport, mock, gen: gen1 } = setupTransport(100);
      const el = document.createElement("audio");
      el.setAttribute("src", "/assets/vo.mp3");

      await transport.scheduleMediaElementPlayback(el, 0, 0, 0, 1, gen1, 1);
      transport.stopAll();
      el.setAttribute("src", "/assets/other-same-origin-clip.mp3");
      const gen2 = transport.startGeneration();
      const second = await transport.scheduleMediaElementPlayback(el, 0, 0, 0, 1, gen2, 1);

      expect(second).not.toBeNull();
      expect(mock.ctx.createMediaElementSource).toHaveBeenCalledTimes(1);
    });
  });

  it("tracks play generation for async race prevention", () => {
    const transport = new WebAudioTransport();
    expect(transport.currentGeneration()).toBe(0);
    const gen1 = transport.startGeneration();
    expect(gen1).toBe(1);
    const gen2 = transport.startGeneration();
    expect(gen2).toBe(2);
    expect(transport.currentGeneration()).toBe(2);
  });

  it("getTime returns -1 when paused", () => {
    const transport = new WebAudioTransport();
    expect(transport.getTime()).toBe(-1);
  });

  it("ownsClock returns false initially", () => {
    const transport = new WebAudioTransport();
    expect(transport.ownsClock()).toBe(false);
  });

  it("stopAll restores el.muted to prior value", () => {
    const transport = new WebAudioTransport();
    const mockEl = { muted: false } as HTMLMediaElement;
    const mockSource = {
      el: mockEl,
      sourceKind: "buffer" as const,
      sourceNode: { stop: vi.fn(), disconnect: vi.fn() } as unknown as AudioBufferSourceNode,
      gainNode: { disconnect: vi.fn() } as unknown as GainNode,
      compositionStart: 0,
      mediaStart: 0,
      scheduledAt: 0,
      priorMuted: false,
    };
    // Simulate WebAudio taking over: el.muted was set to true
    mockEl.muted = true;
    (transport as unknown as { _activeSources: (typeof mockSource)[] })._activeSources = [
      mockSource,
    ];
    (transport as unknown as { _paused: boolean })._paused = false;

    expect(transport.ownsClock()).toBe(true);
    transport.stopAll();
    expect(mockEl.muted).toBe(false);
    expect(transport.ownsClock()).toBe(false);
  });

  it("stopAll restores el.muted=true when element was already muted", () => {
    const transport = new WebAudioTransport();
    const mockEl = { muted: true } as HTMLMediaElement;
    const mockSource = {
      el: mockEl,
      sourceKind: "buffer" as const,
      sourceNode: { stop: vi.fn(), disconnect: vi.fn() } as unknown as AudioBufferSourceNode,
      gainNode: { disconnect: vi.fn() } as unknown as GainNode,
      compositionStart: 0,
      mediaStart: 0,
      scheduledAt: 0,
      priorMuted: true,
    };
    (transport as unknown as { _activeSources: (typeof mockSource)[] })._activeSources = [
      mockSource,
    ];

    transport.stopAll();
    expect(mockEl.muted).toBe(true);
  });

  it("stopAll called multiple times is safe (idempotent)", () => {
    const transport = new WebAudioTransport();
    transport.stopAll();
    transport.stopAll();
    expect(transport.ownsClock()).toBe(false);
  });

  it("destroy clears buffer cache and nulls context", () => {
    const transport = new WebAudioTransport();
    transport.destroy();
    expect(transport.context).toBeNull();
    expect(transport.ownsClock()).toBe(false);
  });

  it("restores the configured master volume after user mute then unmute", () => {
    const { transport, mock } = setupTransport();
    transport.setVolume(0.4);
    transport.setMuted(true);
    expect(mock.monitorGain.gain.value).toBe(0);
    expect(mock.masterGain.gain.value).toBe(1);

    transport.setMuted(false);

    expect(mock.monitorGain.gain.value).toBe(0.4);
    expect(mock.masterGain.gain.value).toBe(1);
  });

  it("applies author and user volume once in separate gain layers", async () => {
    const { transport, mock, gen } = setupTransport();
    await transport.scheduleMediaElementPlayback(mockEl, 0, 0, 0, 0.8, gen, 1);
    transport.setVolume(0.5);

    expect(mock.gainNode.gain.value).toBe(0.8);
    expect(mock.masterGain.gain.value).toBe(1);
    expect(mock.monitorGain.gain.value).toBe(0.5);
    expect(
      mock.gainNode.gain.value * mock.masterGain.gain.value * mock.monitorGain.gain.value,
    ).toBeCloseTo(0.4);
  });

  describe("ownsElement (per-element mute gate)", () => {
    function withSource(el: HTMLMediaElement) {
      const transport = new WebAudioTransport();
      const source = {
        el,
        sourceKind: "buffer" as const,
        sourceNode: { stop: vi.fn(), disconnect: vi.fn() } as unknown as AudioBufferSourceNode,
        gainNode: { disconnect: vi.fn() } as unknown as GainNode,
        compositionStart: 0,
        mediaStart: 0,
        scheduledAt: 0,
        priorMuted: false,
      };
      (transport as unknown as { _activeSources: (typeof source)[] })._activeSources = [source];
      (transport as unknown as { _paused: boolean })._paused = false;
      return transport;
    }

    it("returns true for an element the transport plays", () => {
      const el = {
        muted: false,
        getAttribute: (name: string) => (name === "data-playback-rate" ? "1" : null),
      } as unknown as HTMLMediaElement;
      expect(withSource(el).ownsElement(el)).toBe(true);
    });

    it("returns false for an element the transport does not play", () => {
      const el = {
        muted: false,
        getAttribute: (name: string) => (name === "data-playback-rate" ? "1" : null),
      } as unknown as HTMLMediaElement;
      const other = { muted: false } as HTMLMediaElement;
      expect(withSource(el).ownsElement(other)).toBe(false);
    });

    it("returns false after stopAll releases the element", () => {
      const el = { muted: false } as HTMLMediaElement;
      const transport = withSource(el);
      transport.stopAll();
      expect(transport.ownsElement(el)).toBe(false);
    });
  });

  describe("schedulePlayback timing", () => {
    it("keeps author boost above unity on the per-element gain node", async () => {
      const { transport, mock, gen } = setupTransport(100);

      await transport.schedulePlayback(mockEl, mockBuffer, 0, 0, () => 0, 1, gen);
      transport.setElementVolume(mockEl, 3.98);

      expect(mock.gainNode.gain.value).toBeCloseTo(3.98, 5);
    });

    it("starts in-progress clips immediately with correct buffer offset", async () => {
      const { transport, mock, gen } = setupTransport(100);

      await transport.schedulePlayback(mockEl, mockBuffer, 5, 0, () => 8, 1, gen);

      expect(mock.startFn).toHaveBeenCalledWith(0, 3);
    });

    it("starts in-progress clips with mediaStart offset", async () => {
      const { transport, mock, gen } = setupTransport(100);

      await transport.schedulePlayback(mockEl, mockBuffer, 5, 2, () => 8, 1, gen);

      expect(mock.startFn).toHaveBeenCalledWith(0, 5);
    });

    it("schedules future clips with delay instead of playing immediately", async () => {
      const { transport, mock, gen } = setupTransport(100);

      await transport.schedulePlayback(mockEl, mockBuffer, 10, 0, () => 2, 1, gen);

      expect(mock.startFn).toHaveBeenCalledWith(108, 0);
    });

    it("schedules future clips with correct mediaStart", async () => {
      const { transport, mock, gen } = setupTransport(100);

      await transport.schedulePlayback(mockEl, mockBuffer, 10, 1.5, () => 2, 1, gen);

      expect(mock.startFn).toHaveBeenCalledWith(108, 1.5);
    });

    it("starts clips at exact composition start time immediately", async () => {
      const { transport, mock, gen } = setupTransport(100);

      await transport.schedulePlayback(mockEl, mockBuffer, 5, 0, () => 5, 1, gen);

      expect(mock.startFn).toHaveBeenCalledWith(0, 0);
    });
  });

  describe("clip duration bound (trim)", () => {
    it("bounds an in-progress clip to its remaining authored window", async () => {
      const { transport, mock, gen } = setupTransport(100);
      // compStart=5, mediaStart=0, compTime=8 → elapsed=3; clipDuration=10 → 7 left
      await transport.schedulePlayback(mockEl, mockBuffer, 5, 0, () => 8, 1, gen, 1, 10);
      expect(mock.startFn).toHaveBeenCalledWith(0, 3, 7);
    });

    it("bounds a future clip to its full authored window", async () => {
      const { transport, mock, gen } = setupTransport(100);
      // compStart=10, mediaStart=1.5, compTime=2 → elapsed=-8 → delay 8; clipDuration=4
      await transport.schedulePlayback(mockEl, mockBuffer, 10, 1.5, () => 2, 1, gen, 1, 4);
      expect(mock.startFn).toHaveBeenCalledWith(108, 1.5, 4);
    });

    it("holds a clip whose head an in-point cut until its window opens, at that point's source", async () => {
      const { transport, mock, gen } = setupTransport(100);
      // The clip's own t=0 is 1, its window opens at 2 and ends at 5: from comp time 0, wait 2 s, then
      // play source 1 to 4; from comp time 1.5, the same.
      await transport.schedulePlayback(mockEl, mockBuffer, 1, 0, () => 0, 1, gen, 1, 4, 2);
      expect(mock.startFn).toHaveBeenLastCalledWith(102, 1, 3);
      await transport.schedulePlayback(mockEl, mockBuffer, 1, 0, () => 1.5, 1, gen, 1, 4, 2);
      expect(mock.startFn).toHaveBeenLastCalledWith(100.5, 1, 3);
    });

    it("does not schedule a clip whose window has already elapsed", async () => {
      const { transport, mock, gen } = setupTransport(100);
      // elapsed=15 > clipDuration=10 → nothing to play
      const result = await transport.schedulePlayback(
        mockEl,
        mockBuffer,
        5,
        0,
        () => 20,
        1,
        gen,
        1,
        10,
      );
      expect(result).toBeNull();
      expect(mock.startFn).not.toHaveBeenCalled();
    });

    it("keeps source bounds in authored media time when global rate changes", async () => {
      const { transport, mock, gen } = setupTransport(100);
      // Global rate=2 changes wallclock speed, not source-time span.
      await transport.schedulePlayback(mockEl, mockBuffer, 5, 0, () => 8, 1, gen, 2, 10);
      expect(mock.startFn).toHaveBeenCalledWith(0, 3, 7);
    });

    it("plays unbounded when clipDuration is omitted (legacy behavior)", async () => {
      const { transport, mock, gen } = setupTransport(100);
      await transport.schedulePlayback(mockEl, mockBuffer, 5, 0, () => 8, 1, gen);
      expect(mock.startFn).toHaveBeenCalledWith(0, 3);
    });
  });

  describe("playback rate", () => {
    it("combines authored media rate with global rate without corrupting source seek or clock", async () => {
      const { transport, mock, gen } = setupTransport(100);
      const el = {
        muted: false,
        getAttribute: (name: string) => (name === "data-playback-rate" ? "2" : null),
      } as unknown as HTMLMediaElement;

      // At composition t=0.5 with mediaStart=1, authored 2x has consumed one
      // source second. Global 0.5x makes the source node's wallclock rate 1x,
      // but the composition clock must still advance at global 0.5x.
      await transport.schedulePlayback(el, mockBuffer, 0, 1, () => 0.5, 1, gen, 0.5, 2);

      expect(mock.sourceNode.playbackRate.value).toBe(1);
      expect(mock.startFn).toHaveBeenCalledWith(0, 2, 3);
      mock.ctx.currentTime = 101;
      expect(transport.getTime()).toBe(1);

      transport.setRate(1);
      expect(mock.sourceNode.playbackRate.value).toBe(2);
    });

    it("sets sourceNode.playbackRate.value when rate is provided", async () => {
      const { transport, mock, gen } = setupTransport(100);

      await transport.schedulePlayback(mockEl, mockBuffer, 5, 0, () => 8, 1, gen, 2);

      expect(mock.sourceNode.playbackRate.value).toBe(2);
    });

    it("defaults rate to 1 when not provided", async () => {
      const { transport, mock, gen } = setupTransport(100);

      await transport.schedulePlayback(mockEl, mockBuffer, 5, 0, () => 8, 1, gen);

      expect(mock.sourceNode.playbackRate.value).toBe(1);
    });

    it("scales delay by rate for future clips so they fire at the right wallclock", async () => {
      const { transport, mock, gen } = setupTransport(100);

      // compStart=10, compositionTime=2, rate=2 → 8s of comp time = 4s wallclock
      await transport.schedulePlayback(mockEl, mockBuffer, 10, 0, () => 2, 1, gen, 2);

      expect(mock.startFn).toHaveBeenCalledWith(104, 0);
    });

    it("keeps in-progress buffer offset at elapsed + mediaStart regardless of rate", async () => {
      const { transport, mock, gen } = setupTransport(100);

      await transport.schedulePlayback(mockEl, mockBuffer, 5, 0, () => 8, 1, gen, 2);

      expect(mock.startFn).toHaveBeenCalledWith(0, 3);
    });

    it("setRate updates active sources in place", async () => {
      const { transport, mock, gen } = setupTransport(100);

      await transport.schedulePlayback(mockEl, mockBuffer, 5, 0, () => 8, 1, gen, 1);
      expect(mock.sourceNode.playbackRate.value).toBe(1);

      transport.setRate(2);

      expect(mock.sourceNode.playbackRate.value).toBe(2);
    });

    it("setRate re-aims each source's FX automation, not just its playback rate", async () => {
      // The lanes are committed to absolute context times when the source is
      // scheduled, so bumping playbackRate alone left every automated parameter
      // running its original plan over audio moving at a different speed.
      const { transport, mock, gen } = setupTransport(100);
      await transport.schedulePlayback(mockEl, mockBuffer, 5, 0, () => 8, 1, gen, 1);
      const active = (transport as unknown as { _activeSources: { fx?: unknown }[] })
        ._activeSources;
      const setRate = vi.fn();
      active[0]!.fx = { dispose: vi.fn(), setRate };

      transport.setRate(2);

      expect(setRate).toHaveBeenCalledWith(2);
      expect(mock.sourceNode.playbackRate.value).toBe(2);
    });

    it("setRate before any sources are scheduled does not throw", () => {
      const transport = new WebAudioTransport();
      expect(() => transport.setRate(2)).not.toThrow();
    });

    it("setRate is a no-op when the rate is unchanged", async () => {
      const { transport, mock, gen } = setupTransport(100);
      await transport.schedulePlayback(mockEl, mockBuffer, 5, 0, () => 8, 1, gen, 2);

      mock.ctx.currentTime = 100.5;
      const timeBefore = transport.getTime();
      transport.setRate(2);
      const timeAfter = transport.getTime();

      expect(timeAfter).toBe(timeBefore);
      // No re-anchor, so the next 0.5s of wallclock still maps to 1s of comp time.
      mock.ctx.currentTime = 101;
      expect(transport.getTime()).toBeCloseTo(10, 10);
    });

    it("setRate clamps non-finite or non-positive values to 1", async () => {
      const { transport, mock, gen } = setupTransport(100);
      await transport.schedulePlayback(mockEl, mockBuffer, 5, 0, () => 8, 1, gen, 2);
      expect(mock.sourceNode.playbackRate.value).toBe(2);

      transport.setRate(Number.NaN);
      expect(mock.sourceNode.playbackRate.value).toBe(1);

      transport.setRate(2);
      transport.setRate(0);
      expect(mock.sourceNode.playbackRate.value).toBe(1);

      transport.setRate(2);
      transport.setRate(-1);
      expect(mock.sourceNode.playbackRate.value).toBe(1);
    });

    it("getTime advances at the configured rate", async () => {
      const { transport, mock, gen } = setupTransport(100);

      await transport.schedulePlayback(mockEl, mockBuffer, 5, 0, () => 8, 1, gen, 2);

      // At schedule time, ctx.currentTime=100, compositionTime=8.
      expect(transport.getTime()).toBeCloseTo(8, 10);

      // Advance the audio-context clock by 0.5 wallclock seconds; at rate=2,
      // composition time should have advanced 1s.
      mock.ctx.currentTime = 100.5;
      expect(transport.getTime()).toBeCloseTo(9, 10);
    });

    it("getTime tracks composition time after a mid-playback setRate", async () => {
      const { transport, mock, gen } = setupTransport(100);

      await transport.schedulePlayback(mockEl, mockBuffer, 5, 0, () => 8, 1, gen, 1);
      expect(transport.getTime()).toBeCloseTo(8, 10);

      // 0.5s passes at rate=1 → composition time = 8.5
      mock.ctx.currentTime = 100.5;
      expect(transport.getTime()).toBeCloseTo(8.5, 10);

      // Bump rate to 2 — composition time should NOT jump.
      transport.setRate(2);
      expect(transport.getTime()).toBeCloseTo(8.5, 10);

      // Another 0.5s wallclock at rate=2 → composition time = 9.5
      mock.ctx.currentTime = 101;
      expect(transport.getTime()).toBeCloseTo(9.5, 10);
    });
  });

  describe("onended cleanup (audio dropout fix)", () => {
    it("cleans up _activeSources when AudioBufferSourceNode ends naturally", async () => {
      const { transport, mock, gen } = setupTransport(100);
      const el = {
        muted: false,
        getAttribute: (name: string) => (name === "data-playback-rate" ? "1" : null),
      } as unknown as HTMLMediaElement;

      await transport.schedulePlayback(el, mockBuffer, 0, 0, () => 0, 1, gen);
      expect(transport.ownsClock()).toBe(true);
      expect(el.muted).toBe(true);

      mock.sourceNode._fireEnded();

      expect(transport.ownsClock()).toBe(false);
      expect(el.muted).toBe(false);
    });

    it("restores priorMuted=true when element was already muted", async () => {
      const { transport, mock, gen } = setupTransport(100);
      const el = {
        muted: true,
        getAttribute: (name: string) => (name === "data-playback-rate" ? "1" : null),
      } as unknown as HTMLMediaElement;

      await transport.schedulePlayback(el, mockBuffer, 0, 0, () => 0, 1, gen);
      expect(el.muted).toBe(true);

      mock.sourceNode._fireEnded();

      expect(el.muted).toBe(true);
      expect(transport.ownsClock()).toBe(false);
    });

    it("disposes the FX graph when a clip ends naturally", async () => {
      // stopAll() disposes by walking _activeSources, and the splice above had
      // already removed this entry — so the handle, its MutationObserver and any
      // running LFO survived the clip for the rest of the session.
      const { transport, mock, gen } = setupTransport(100);
      await transport.schedulePlayback(mockEl, mockBuffer, 0, 0, () => 0, 1, gen);

      mock.sourceNode._fireEnded();

      expect(mock.sourceNode.disconnect).toHaveBeenCalled();
      expect(mock.gainNode.disconnect).toHaveBeenCalled();
    });

    it("registers onended listener on the sourceNode", async () => {
      const { transport, mock, gen } = setupTransport(100);

      await transport.schedulePlayback(mockEl, mockBuffer, 0, 0, () => 0, 1, gen);

      expect(mock.sourceNode.addEventListener).toHaveBeenCalledWith("ended", expect.any(Function));
    });

    it("onended after stopAll is a no-op — does not clobber restored state", async () => {
      const { transport, mock, gen } = setupTransport(100);
      const el = {
        muted: false,
        getAttribute: (name: string) => (name === "data-playback-rate" ? "1" : null),
      } as unknown as HTMLMediaElement;

      await transport.schedulePlayback(el, mockBuffer, 0, 0, () => 0, 1, gen);
      expect(el.muted).toBe(true);

      transport.stopAll();
      expect(el.muted).toBe(false);
      expect(transport.ownsClock()).toBe(false);

      el.muted = true;

      mock.sourceNode._fireEnded();

      expect(el.muted).toBe(true);
      expect(transport.ownsClock()).toBe(false);
    });
  });

  describe("group routing (preview)", () => {
    // Real jsdom elements — `groupInput` looks the group up via
    // `el.ownerDocument.getElementById`, and `audioGroupOf` reads `tagName` /
    // `getAttribute`, neither of which the plain-object mocks above implement.
    function createGroupMockAudioContext(currentTime = 100) {
      const gainNodes: {
        gain: { value: number };
        connect: ReturnType<typeof vi.fn>;
        disconnect: ReturnType<typeof vi.fn>;
      }[] = [];
      const analysers: {
        fftSize: number;
        connect: ReturnType<typeof vi.fn>;
        disconnect: ReturnType<typeof vi.fn>;
        getFloatTimeDomainData: ReturnType<typeof vi.fn>;
      }[] = [];
      const masterGain = { gain: { value: 1 }, connect: vi.fn(), disconnect: vi.fn() };
      const monitorGain = { gain: { value: 1 }, connect: vi.fn(), disconnect: vi.fn() };
      const mediaElementSource = { connect: vi.fn(), disconnect: vi.fn() };
      const ctx = {
        currentTime,
        state: "running",
        resume: vi.fn(),
        suspend: vi.fn(() => Promise.resolve()),
        createBufferSource: vi.fn(() => ({
          buffer: null as AudioBuffer | null,
          playbackRate: { value: 1 },
          start: vi.fn(),
          stop: vi.fn(),
          disconnect: vi.fn(),
          connect: vi.fn(),
          addEventListener: vi.fn(),
        })),
        createGain: vi.fn(() => {
          // The AudioParam scheduling surface is part of the contract the group
          // bus uses (`clearParamLane` cancels before re-seeding a reused bus).
          // A bare `{ value }` made any such call throw, and `schedulePlayback`
          // swallows throws into `return null` — so the mock's own gap read as
          // "the member did not play" rather than as a missing stub.
          const node = {
            gain: {
              value: 1,
              cancelScheduledValues: vi.fn(),
              cancelAndHoldAtTime: vi.fn(),
              setValueAtTime: vi.fn(),
              linearRampToValueAtTime: vi.fn(),
              exponentialRampToValueAtTime: vi.fn(),
              setValueCurveAtTime: vi.fn(),
            },
            connect: vi.fn(),
            disconnect: vi.fn(),
          };
          gainNodes.push(node);
          return node;
        }),
        createAnalyser: vi.fn(() => {
          const node = {
            fftSize: 2048,
            connect: vi.fn(),
            disconnect: vi.fn(),
            getFloatTimeDomainData: vi.fn(),
          };
          analysers.push(node);
          return node;
        }),
        createChannelSplitter: vi.fn(() => ({ connect: vi.fn(), disconnect: vi.fn() })),
        // The media-element route needs this as much as the decoded one: without
        // it `scheduleMediaElementPlayback` throws and its catch returns null,
        // which reads as "the member did not play" rather than a missing stub.
        createMediaElementSource: vi.fn(() => mediaElementSource),
        destination: {},
        close: vi.fn(),
      };
      return { ctx, gainNodes, analysers, masterGain, monitorGain, mediaElementSource };
    }

    function setupGroupTransport(currentTime = 100) {
      const transport = new WebAudioTransport();
      const mock = createGroupMockAudioContext(currentTime);
      (transport as unknown as { _ctx: unknown })._ctx = mock.ctx;
      (transport as unknown as { _masterGain: unknown })._masterGain = mock.masterGain;
      (transport as unknown as { _monitorGain: unknown })._monitorGain = mock.monitorGain;
      const gen = transport.startGeneration();
      return { transport, mock, gen };
    }

    function groupedAudioEl(id: string, groupId?: string): HTMLMediaElement {
      const el = document.createElement("audio");
      el.id = id;
      if (groupId) el.setAttribute("data-audio-group", groupId);
      document.body.appendChild(el);
      return el as unknown as HTMLMediaElement;
    }

    /** Create a grouped member and schedule it in one step — the shape every
     *  test below needs, differing only in id/group/generation. */
    async function scheduleGrouped(
      transport: WebAudioTransport,
      gen: number,
      id: string,
      groupId?: string,
    ): Promise<HTMLMediaElement> {
      const el = groupedAudioEl(id, groupId);
      await transport.schedulePlayback(el, mockBuffer, 0, 0, () => 0, 1, gen);
      return el;
    }

    /** The group's own input gain is built lazily on the first member — index
     *  1 in creation order (that member's own gain is 0). */
    const firstGroupInput = (mock: ReturnType<typeof createGroupMockAudioContext>) =>
      mock.gainNodes[1]!;

    beforeEach(() => {
      document.body.innerHTML = "";
    });

    it.each([
      [
        "decoded",
        (t: WebAudioTransport, el: HTMLMediaElement, gen: number) =>
          t.schedulePlayback(el, mockBuffer, 0, 0, () => 0, 1, gen),
      ],
      [
        "media-element",
        (t: WebAudioTransport, el: HTMLMediaElement, gen: number) =>
          t.scheduleMediaElementPlayback(el, 0, 0, 0, 1, gen),
      ],
    ])(
      "keeps a %s clip's volume lane off the gain each tick rewrites",
      async (_route, schedule) => {
        const { transport, mock, gen } = setupGroupTransport();
        const el = groupedAudioEl("voice");
        const points = [
          { t: 0, v: 0 },
          { t: 3, v: 1 },
          { t: 6, v: 0 },
        ];
        el.setAttribute(
          "data-automation",
          JSON.stringify({ version: 1, lanes: [{ target: "volume", points }] }),
        );

        expect(await schedule(transport, el, gen)).not.toBeNull();
        type Ramps = { linearRampToValueAtTime: ReturnType<typeof vi.fn> };
        const laneGains = mock.gainNodes.filter(
          (node) => (node.gain as unknown as Ramps).linearRampToValueAtTime.mock.calls.length > 0,
        );
        expect(laneGains).toHaveLength(1);
        const laneValue = laneGains[0]!.gain.value;

        transport.setElementVolume(el, 0.5);

        expect(laneGains[0]!.gain.value).toBe(laneValue);
        expect(mock.gainNodes.filter((node) => node.gain.value === 0.5)).toHaveLength(1);
      },
    );

    describe("volume lanes follow the transport mid-play", () => {
      const lane = (points: { t: number; v: number }[]) =>
        JSON.stringify({ version: 1, lanes: [{ target: "volume", points }] });
      const FADE = lane([
        { t: 0, v: 0 },
        { t: 3, v: 1 },
        { t: 6, v: 0 },
      ]);
      type Param = Record<
        "linearRampToValueAtTime" | "cancelScheduledValues",
        ReturnType<typeof vi.fn>
      >;
      const param = (node: { gain: unknown }) => node.gain as Param;
      const rampsAfter = (node: { gain: unknown }, from: number) =>
        param(node).linearRampToValueAtTime.mock.calls.slice(from);
      /** Let the MutationObserver's microtask run. */
      const settle = () => new Promise((r) => setTimeout(r, 0));

      // An unbounded media-element clip: the runtime does not stopAll and reschedule it on a rate change.
      async function playBed(automation?: string, volume?: string) {
        const setup = setupGroupTransport();
        const el = groupedAudioEl("bed");
        if (automation) el.setAttribute("data-automation", automation);
        if (volume) el.setAttribute("data-volume", volume);
        await setup.transport.scheduleMediaElementPlayback(el, 0, 0, 0, 1, setup.gen);
        expect(setup.transport.hasBoundedActiveSources()).toBe(false);
        return { ...setup, el, laneGain: setup.mock.gainNodes[1]! };
      }

      // Gain 2 times a 0 -> 3 ramp crosses the ceiling at 6.635 s; the product holds there after.
      const CROSSING = lane([
        { t: 0, v: 0 },
        { t: 10, v: 3 },
      ]);
      const crossAt = 100 + (MAX_AUDIO_GAIN / 2 / 3) * 10;

      it("caps the routed graph's product when gain 2 and a constant lane 3 would make 6", async () => {
        const { transport, el, mock, laneGain } = await playBed(lane([{ t: 0, v: 3 }]), "2");
        transport.setElementVolume(el, 1, 2);
        const booked = (laneGain.gain as unknown as { setValueAtTime: ReturnType<typeof vi.fn> })
          .setValueAtTime.mock.calls;
        expect(mock.gainNodes[2]!.gain.value * booked[0]![0]).toBeCloseTo(MAX_AUDIO_GAIN, 9);
      });

      it("holds a clip's gain times its lane under the ceiling, with data-volume played ahead", async () => {
        const { laneGain } = await playBed(CROSSING, "2");
        expect(rampsAfter(laneGain, 0)).toContainEqual([
          expect.closeTo(MAX_AUDIO_GAIN / 2, 6),
          expect.closeTo(crossAt, 6),
        ]);
        expect(rampsAfter(laneGain, 0)).toContainEqual([
          expect.closeTo(MAX_AUDIO_GAIN / 2, 6),
          110,
        ]);
      });

      it("re-books a clip's lane when its data-volume changes", async () => {
        const { el, laneGain } = await playBed(CROSSING, "2");
        const before = param(laneGain).linearRampToValueAtTime.mock.calls.length;

        el.setAttribute("data-volume", "1");
        await settle();

        expect(rampsAfter(laneGain, before)).toContainEqual([3, 110]);
      });

      it("restores unity after a playing clip's volume lane is removed", async () => {
        const { el, laneGain, transport, mock } = await playBed(lane([{ t: 0, v: 0.25 }]), "2");
        transport.setElementVolume(el, 1, 2);

        el.removeAttribute("data-automation");
        await Promise.resolve();

        const booked = (laneGain.gain as unknown as { setValueAtTime: ReturnType<typeof vi.fn> })
          .setValueAtTime.mock.calls;
        expect(booked.at(-1)).toEqual([1, 100]);
        expect(mock.gainNodes[2]!.gain.value * booked.at(-1)![0]).toBe(2);
      });

      it("restores the static group gain after its playing volume lane is removed", async () => {
        document.body.innerHTML = `<hf-audio-group id="vo" data-volume="2"></hf-audio-group>`;
        const group = document.getElementById("vo")!;
        group.setAttribute("data-automation", lane([{ t: 0, v: 0.25 }]));
        const { transport, mock, gen } = setupGroupTransport();
        await scheduleGrouped(transport, gen, "a", "vo");
        const fader = mock.gainNodes[4]!;

        group.removeAttribute("data-automation");
        await Promise.resolve();

        const booked = (fader.gain as unknown as { setValueAtTime: ReturnType<typeof vi.fn> })
          .setValueAtTime.mock.calls;
        expect(booked.at(-1)).toEqual([2, 100]);
      });

      it("holds a group's gain times its lane under the ceiling, through a ramp", async () => {
        document.body.innerHTML = `<hf-audio-group id="vo" data-volume="2"></hf-audio-group>`;
        document.getElementById("vo")!.setAttribute("data-automation", CROSSING);
        const { transport, mock, gen } = setupGroupTransport();
        await scheduleGrouped(transport, gen, "a", "vo");
        const fader = mock.gainNodes[4]!;
        expect(rampsAfter(fader, 0)).toContainEqual([
          expect.closeTo(MAX_AUDIO_GAIN, 6),
          expect.closeTo(crossAt, 6),
        ]);
      });

      it("re-aims a clip's lane at a new rate", async () => {
        const { transport, laneGain } = await playBed(FADE);
        expect(rampsAfter(laneGain, 0)).toContainEqual([1, 103]);
        const before = param(laneGain).linearRampToValueAtTime.mock.calls.length;

        transport.setRate(2);

        expect(rampsAfter(laneGain, before)).toContainEqual([1, 101.5]);
      });

      it("re-books a clip's lane when it is edited", async () => {
        const { el, laneGain } = await playBed(FADE);
        const before = param(laneGain).linearRampToValueAtTime.mock.calls.length;

        el.setAttribute(
          "data-automation",
          lane([
            { t: 0, v: 0 },
            { t: 2, v: 0.5 },
          ]),
        );
        await settle();

        expect(rampsAfter(laneGain, before)).toContainEqual([0.5, 102]);
      });

      it("clears a clip's lane when it is removed", async () => {
        const { el, laneGain } = await playBed(FADE);
        const ramps = param(laneGain).linearRampToValueAtTime.mock.calls.length;
        const cancels = param(laneGain).cancelScheduledValues.mock.calls.length;

        el.removeAttribute("data-automation");
        await settle();

        expect(param(laneGain).cancelScheduledValues.mock.calls.slice(cancels)).toContainEqual([0]);
        expect(rampsAfter(laneGain, ramps)).toEqual([]);
      });

      it("books a lane added to a playing clip", async () => {
        const { el, laneGain } = await playBed();
        expect(laneGain).toBeDefined();

        el.setAttribute("data-automation", FADE);
        await settle();

        expect(rampsAfter(laneGain, 0)).toContainEqual([1, 103]);
      });

      it("books a group's lane times its data-volume, at a new rate and on an edit", async () => {
        document.body.innerHTML = `<hf-audio-group id="vo" data-volume="0.5"></hf-audio-group>`;
        document.getElementById("vo")!.setAttribute("data-automation", FADE);
        const { transport, mock, gen } = setupGroupTransport();
        await scheduleGrouped(transport, gen, "a", "vo");
        const fader = mock.gainNodes[4]!;
        expect(rampsAfter(fader, 0)).toContainEqual([0.5, 103]);

        let before = param(fader).linearRampToValueAtTime.mock.calls.length;
        transport.setRate(2);
        expect(rampsAfter(fader, before)).toContainEqual([0.5, 101.5]);

        before = param(fader).linearRampToValueAtTime.mock.calls.length;
        document.getElementById("vo")!.setAttribute(
          "data-automation",
          lane([
            { t: 0, v: 0 },
            { t: 4, v: 0.5 },
          ]),
        );
        await settle();
        expect(rampsAfter(fader, before)).toContainEqual([0.25, 102]);
      });
    });

    it("routes an ungrouped clip straight to master through its own gain", async () => {
      const { transport, mock, gen } = setupGroupTransport();

      await scheduleGrouped(transport, gen, "lone");

      // Clip gain (data-volume, ahead of the FX), then the lane, then the per-tick gain to master.
      expect(mock.gainNodes).toHaveLength(3);
      const [gain, laneGain, clipGain] = mock.gainNodes;
      expect(gain!.connect).toHaveBeenCalledWith(mock.masterGain);
      expect(laneGain!.connect).toHaveBeenCalledWith(gain);
      expect(clipGain!.connect).toHaveBeenCalledWith(laneGain);
    });

    // The media-element transport is the PRIMARY path for audio — the runtime
    // tries it first and only falls back to a decoded buffer. It has to reach
    // the same bus, or grouping silently applies to nothing that actually plays.
    // The render clamps a track volume with `clampAudioGain` (ceiling ~3.98),
    // so an over-unity bus previewed at 1.0 exported up to 12 dB louder than
    // it auditioned.
    it("previews an over-unity bus fader at the render's ceiling, not unity", async () => {
      const { transport, mock, gen } = setupGroupTransport();
      document.body.innerHTML = `<hf-audio-group id="vo" data-volume="10"></hf-audio-group>`;
      await scheduleGrouped(transport, gen, "a", "vo");

      // Creation order: a-gain(0), groupInput(1), groupOutput(2), muteGain(3), fader(4).
      expect(mock.gainNodes[4]!.gain.value).toBeCloseTo(3.9811, 3);
    });

    it("still floors a negative bus fader at zero", async () => {
      const { transport, mock, gen } = setupGroupTransport();
      document.body.innerHTML = `<hf-audio-group id="vo" data-volume="-1"></hf-audio-group>`;
      await scheduleGrouped(transport, gen, "a", "vo");

      expect(mock.gainNodes[4]!.gain.value).toBe(0);
    });

    // A bare getElementById read a member's own fader and chain as the bus's.
    it("ignores a non-<hf-audio-group> element sharing the group id", async () => {
      const { transport, mock, gen } = setupGroupTransport();
      document.body.innerHTML = `<div id="vo" data-volume="0.25" data-hidden></div>`;
      await scheduleGrouped(transport, gen, "a", "vo");

      // Flat bus: unity fader, unmuted — the documented "group with no element"
      // degradation, not the stranger's settings.
      expect(mock.gainNodes[4]!.gain.value).toBe(1);
      expect(mock.gainNodes[3]!.gain.value).toBe(1);
    });

    it("routes a grouped clip's MEDIA-ELEMENT playback to the group bus, not master", async () => {
      const { transport, mock, gen } = setupGroupTransport();
      const el = groupedAudioEl("vo-1", "vo");

      await transport.scheduleMediaElementPlayback(el, 0, 0, 0, 1, gen, 1);

      const clipGain = mock.gainNodes[0]!;
      expect(clipGain.connect).toHaveBeenCalledWith(firstGroupInput(mock));
      expect(clipGain.connect).not.toHaveBeenCalledWith(mock.masterGain);
    });

    it("plays a routed clip's data-volume on its clip gain, ahead of its effects", async () => {
      const { transport, mock, gen } = setupGroupTransport();
      const el = groupedAudioEl("lone");
      await transport.scheduleMediaElementPlayback(el, 0, 0, 0, 1, gen, 1);

      transport.setElementVolume(el, 0.8, 0.5);

      const [gain, , clipGain] = mock.gainNodes;
      expect(clipGain!.gain.value).toBe(0.5);
      expect(gain!.gain.value).toBe(0.8);
    });

    it("routes an UNGROUPED clip's media-element playback straight to master", async () => {
      const { transport, mock, gen } = setupGroupTransport();
      const el = groupedAudioEl("lone");

      await transport.scheduleMediaElementPlayback(el, 0, 0, 0, 1, gen, 1);

      expect(mock.gainNodes).toHaveLength(3);
      expect(mock.gainNodes[0]!.connect).toHaveBeenCalledWith(mock.masterGain);
      expect(mock.gainNodes[1]!.connect).toHaveBeenCalledWith(mock.gainNodes[0]);
      expect(mock.gainNodes[2]!.connect).toHaveBeenCalledWith(mock.gainNodes[1]);
    });

    it("two members of the same group land on ONE shared group gain, not master directly", async () => {
      const { transport, mock, gen } = setupGroupTransport();

      await scheduleGrouped(transport, gen, "a", "vo");
      await scheduleGrouped(transport, gen, "b", "vo");

      // Creation order for a: a-gain(0), groupInput(1), groupOutput(2),
      // muteGain(3), fader(4) — the group bus is built lazily inside a's
      // schedule call — then a's lane(5) and clip gain(6). Then b: b-gain(7), lane(8), clip gain(9).
      expect(mock.gainNodes.length).toBeGreaterThanOrEqual(10);
      const aGain = mock.gainNodes[0]!;
      const groupInput = firstGroupInput(mock);
      const groupOutput = mock.gainNodes[2]!;
      const muteGain = mock.gainNodes[3]!;
      const fader = mock.gainNodes[4]!;
      const bGain = mock.gainNodes[7]!;

      // Both members feed the shared bus — neither connects straight to master.
      expect(aGain.connect).toHaveBeenCalledWith(groupInput);
      expect(bGain.connect).toHaveBeenCalledWith(groupInput);
      expect(aGain.connect).not.toHaveBeenCalledWith(mock.masterGain);
      expect(bGain.connect).not.toHaveBeenCalledWith(mock.masterGain);

      // The bus's input never reaches master directly. It runs through the
      // chain (dry here — neither member's group has a chain-bearing
      // `<hf-audio-group>`) onto the FADER, then the mute gain (B5), then the
      // output gain, then master. The fader sits POST-FX because that is where
      // the render bakes group volume in.
      expect(groupInput.connect).not.toHaveBeenCalledWith(mock.masterGain);
      expect(groupInput.connect).toHaveBeenCalledWith(fader);
      expect(fader.connect).toHaveBeenCalledWith(muteGain);
      expect(muteGain.connect).toHaveBeenCalledWith(groupOutput);
      expect(groupOutput.connect).toHaveBeenCalledWith(mock.masterGain);
    });

    it("a second member of an already-open group does not rebuild the group bus", async () => {
      const { transport, mock, gen } = setupGroupTransport();

      await scheduleGrouped(transport, gen, "a", "vo");
      const gainCountAfterFirst = mock.gainNodes.length; // a's gains + group input/output/mute/fader
      await scheduleGrouped(transport, gen, "b", "vo");

      // Only b's own gain, lane and clip gain are new — no second group bus minted.
      expect(mock.gainNodes.length).toBe(gainCountAfterFirst + 3);
    });

    it("a group id with no matching <hf-audio-group> element still gets a flat bus", async () => {
      const { transport, mock, gen } = setupGroupTransport();

      await scheduleGrouped(transport, gen, "a", "orphan-group"); // no matching element

      const muteGain = mock.gainNodes[3]!;
      const groupOutput = mock.gainNodes[2]!;
      const fader = mock.gainNodes[4]!;
      expect(firstGroupInput(mock).connect).toHaveBeenCalledWith(fader);
      expect(fader.connect).toHaveBeenCalledWith(muteGain);
      expect(muteGain.connect).toHaveBeenCalledWith(groupOutput);
      expect(groupOutput.connect).toHaveBeenCalledWith(mock.masterGain);
      // No element to read, so the fader sits at unity.
      expect(fader.gain.value).toBe(1);
    });

    // The old assertion here was `resolves.not.toBeNull()` — it was named for
    // group volume and checked only that scheduling did not throw, so the bus
    // sitting at unity while the render applied data-volume went unseen. The
    // export was ~8 dB quieter than what had been auditioned.
    it("puts the group's own data-volume on the bus fader", async () => {
      document.body.innerHTML = `<hf-audio-group id="vo" data-label="Voiceover" data-volume="0.4"></hf-audio-group>`;
      const { transport, mock, gen } = setupGroupTransport();

      await expect(scheduleGrouped(transport, gen, "a", "vo")).resolves.not.toBeNull();

      expect(mock.gainNodes[4]!.gain.value).toBeCloseTo(0.4, 6);
    });

    it("leaves the fader at unity when the group carries no data-volume", async () => {
      document.body.innerHTML = `<hf-audio-group id="vo" data-label="Voiceover"></hf-audio-group>`;
      const { transport, mock, gen } = setupGroupTransport();

      // No throw wiring the group's automation reader against a real
      // <hf-audio-group> element that carries no fx/automation attrs.
      await expect(scheduleGrouped(transport, gen, "a", "vo")).resolves.not.toBeNull();
      expect(mock.gainNodes[4]!.gain.value).toBe(1);
    });

    it("destroy() disposes every group bus", async () => {
      const { transport, mock, gen } = setupGroupTransport();
      await scheduleGrouped(transport, gen, "a", "vo");
      const groupInput = firstGroupInput(mock);

      transport.destroy();

      expect(groupInput.disconnect).toHaveBeenCalled();
    });

    it("stopAll() does NOT dispose group buses — replaying the group does not rebuild it", async () => {
      const { transport, mock, gen } = setupGroupTransport();
      await scheduleGrouped(transport, gen, "a", "vo");
      const groupInput = firstGroupInput(mock);

      transport.stopAll();
      expect(groupInput.disconnect).not.toHaveBeenCalled();

      const gen2 = transport.startGeneration();
      await scheduleGrouped(transport, gen2, "a", "vo");
      // Still only one group-input gain ever created for "vo".
      expect(mock.gainNodes.filter((n) => n === groupInput)).toHaveLength(1);
    });

    // Surviving stopAll() is the point of the bus — and the trap. Its envelopes
    // were booked against the FIRST pass's absolute context times, so a replay
    // or a seek left the fader holding that pass's last value: 0 after a
    // fade-out, i.e. silent for the rest of the session.
    it("re-anchors the reused bus once per play generation, and only once", async () => {
      document.body.innerHTML = `<hf-audio-group id="vo" data-volume="0.5"></hf-audio-group>`;
      const { transport, mock, gen } = setupGroupTransport();
      await scheduleGrouped(transport, gen, "a", "vo");
      const fader = mock.gainNodes[4]!;

      // Something moved the fader mid-pass (a ramp reaching its last point).
      fader.gain.value = 0;
      transport.stopAll();

      const gen2 = transport.startGeneration();
      await scheduleGrouped(transport, gen2, "a", "vo");
      expect(fader.gain.value).toBeCloseTo(0.5, 6);

      // A second member in the SAME pass must not re-book on top of the first.
      fader.gain.value = 0;
      await scheduleGrouped(transport, gen2, "b", "vo");
      expect(fader.gain.value).toBe(0);
    });

    // reanchor runs inside schedulePlayback, whose catch turns any throw into
    // `return null` — so a bus that fails to re-anchor would silently take the
    // MEMBER out of the pass, and a generation stamped before the attempt would
    // stop every later member retrying.
    it("keeps the member playing when re-anchoring the bus throws", async () => {
      document.body.innerHTML = `<hf-audio-group id="vo" data-volume="0.5"></hf-audio-group>`;
      const { transport, mock, gen } = setupGroupTransport();
      await scheduleGrouped(transport, gen, "a", "vo");
      const fader = mock.gainNodes[4]!;
      fader.gain.cancelScheduledValues = vi.fn(() => {
        throw new Error("param is not schedulable");
      });

      transport.stopAll();
      const gen2 = transport.startGeneration();

      await expect(scheduleGrouped(transport, gen2, "a", "vo")).resolves.not.toBeNull();
      // Generation not consumed by the failed attempt, so a sibling still tries.
      fader.gain.cancelScheduledValues = vi.fn();
      await scheduleGrouped(transport, gen2, "b", "vo");
      expect(fader.gain.value).toBeCloseTo(0.5, 6);
    });

    describe("master bus", () => {
      const GAIN_CHAIN = JSON.stringify({
        version: 1,
        nodes: [{ type: "gain", id: "g", params: { gain: -6 } }],
      });

      function withBusOut(setup: ReturnType<typeof setupGroupTransport>) {
        const busOut = { gain: { value: 1 }, connect: vi.fn(), disconnect: vi.fn() };
        (setup.transport as unknown as { _busOut: unknown })._busOut = busOut;
        return busOut;
      }

      it("splices the root's chain between the sum and the monitor", async () => {
        document.body.innerHTML = `<div id="root" data-composition-id="main"></div>`;
        document.getElementById("root")!.setAttribute("data-fx-chain", GAIN_CHAIN);
        const setup = setupGroupTransport();
        const busOut = withBusOut(setup);

        await scheduleGrouped(setup.transport, setup.gen, "a");

        const { masterGain } = setup.mock;
        expect(masterGain.disconnect).toHaveBeenCalledWith(busOut);
        // Wired into the chain's input, not straight to the bus output.
        expect(masterGain.connect).toHaveBeenCalledTimes(1);
        expect(masterGain.connect).not.toHaveBeenCalledWith(busOut);
      });

      it("feeds grouped members through the same master bus", async () => {
        document.body.innerHTML = `<div id="root" data-composition-id="main" data-fx-chain='${GAIN_CHAIN}'></div>`;
        const setup = setupGroupTransport();
        const busOut = withBusOut(setup);

        await scheduleGrouped(setup.transport, setup.gen, "a", "vo");

        expect(setup.mock.masterGain.disconnect).toHaveBeenCalledWith(busOut);
        expect(setup.mock.masterGain.connect).not.toHaveBeenCalledWith(busOut);
      });

      it("limits a plain video at unity played from its media element", async () => {
        document.body.innerHTML = `<div id="root" data-composition-id="main" data-fx-chain='${GAIN_CHAIN}'><video id="talk" data-has-audio="true"></video></div>`;
        const setup = setupGroupTransport();
        const busOut = withBusOut(setup);
        const video = document.getElementById("talk") as unknown as HTMLMediaElement;

        await setup.transport.scheduleMediaElementPlayback(video, 0, 0, 0, 1, setup.gen, 1);

        expect(setup.mock.gainNodes[0]!.connect).toHaveBeenCalledWith(setup.mock.masterGain);
        expect(setup.mock.masterGain.disconnect).toHaveBeenCalledWith(busOut);
        expect(setup.mock.masterGain.connect).not.toHaveBeenCalledWith(busOut);
      });

      it("leaves the sum wired straight through when the root has no chain", async () => {
        document.body.innerHTML = `<div id="root" data-composition-id="main"></div>`;
        const setup = setupGroupTransport();
        const busOut = withBusOut(setup);

        await scheduleGrouped(setup.transport, setup.gen, "a");

        expect(setup.mock.masterGain.connect).toHaveBeenLastCalledWith(busOut);
      });

      it("ignores a chain on a sub-composition's root", async () => {
        document.body.innerHTML = `<div id="root" data-composition-id="main"><div data-composition-id="inner" data-fx-chain='${GAIN_CHAIN}'></div></div>`;
        const setup = setupGroupTransport();
        const busOut = withBusOut(setup);

        await scheduleGrouped(setup.transport, setup.gen, "a");

        expect(setup.mock.masterGain.connect).toHaveBeenLastCalledWith(busOut);
      });

      it("is built once for the session, not once per member", async () => {
        document.body.innerHTML = `<div id="root" data-composition-id="main" data-fx-chain='${GAIN_CHAIN}'></div>`;
        const setup = setupGroupTransport();
        withBusOut(setup);

        await scheduleGrouped(setup.transport, setup.gen, "a");
        const nodesAfterFirst = setup.mock.gainNodes.length;
        await scheduleGrouped(setup.transport, setup.gen, "b");

        // The second member adds its own element gain, lane and clip gain, and nothing else.
        expect(setup.mock.gainNodes.length).toBe(nodesAfterFirst + 3);
        expect(setup.mock.masterGain.disconnect).toHaveBeenCalledTimes(1);
      });
    });

    describe("group mute (B5)", () => {
      it("a group created with data-hidden already set starts muted (mute gain at 0)", async () => {
        document.body.innerHTML = `<hf-audio-group id="vo" data-hidden></hf-audio-group>`;
        const { transport, mock, gen } = setupGroupTransport();

        await scheduleGrouped(transport, gen, "a", "vo");

        const muteGain = mock.gainNodes[3]!;
        expect(muteGain.gain.value).toBe(0);
      });

      it("setGroupMuted toggles the mute gain on an active group bus", async () => {
        const { transport, mock, gen } = setupGroupTransport();
        await scheduleGrouped(transport, gen, "a", "vo");
        const muteGain = mock.gainNodes[3]!;
        expect(muteGain.gain.value).toBe(1);

        transport.setGroupMuted("vo", true);
        expect(muteGain.gain.value).toBe(0);

        transport.setGroupMuted("vo", false);
        expect(muteGain.gain.value).toBe(1);
      });

      it("setGroupMuted on a group with no active member is a no-op, not a throw", () => {
        const { transport } = setupGroupTransport();
        expect(() => transport.setGroupMuted("never-played", true)).not.toThrow();
      });
    });

    describe("level metering", () => {
      const addGroup = (id: string) => {
        document.body.insertAdjacentHTML(
          "beforeend",
          `<hf-audio-group id="${id}"></hf-audio-group>`,
        );
      };
      const setLevel = (analyser: { getFloatTimeDomainData: unknown }, peak: number) => {
        (analyser.getFloatTimeDomainData as ReturnType<typeof vi.fn>).mockImplementation(
          (buf: Float32Array) => buf.fill(0).fill(-peak, 3, 4),
        );
      };

      it("creates nothing until startMetering", async () => {
        addGroup("vo");
        const { transport, mock, gen } = setupGroupTransport();
        await scheduleGrouped(transport, gen, "a", "vo");
        expect(mock.ctx.createAnalyser).not.toHaveBeenCalled();
        expect(transport.readLevels()).toEqual({ master: { l: 0, r: 0 }, groups: {} });
      });

      it("attaches the master tap once init() lands, even when startMetering ran while the context was still warming up", async () => {
        const mock = createGroupMockAudioContext();
        class MockAudioContext {
          constructor() {
            return mock.ctx as unknown as MockAudioContext;
          }
        }
        vi.stubGlobal("AudioContext", MockAudioContext);
        const transport = new WebAudioTransport();

        transport.startMetering();
        expect(mock.ctx.createAnalyser).not.toHaveBeenCalled();
        expect(transport.readLevels()).toEqual({ master: { l: 0, r: 0 }, groups: {} });

        const ok = await transport.init();

        expect(ok).toBe(true);
        expect(mock.ctx.createAnalyser).toHaveBeenCalled();
        expect(transport.readLevels()).toEqual({ master: { l: 0, r: 0 }, groups: {} });
        vi.unstubAllGlobals();
      });

      it("taps master and each group as side branches, once however often it starts", async () => {
        addGroup("vo");
        const { transport, mock, gen } = setupGroupTransport();
        await scheduleGrouped(transport, gen, "a", "vo");
        const groupOutput = mock.gainNodes[2]!;
        const connectsBefore = groupOutput.connect.mock.calls.length;

        transport.startMetering();
        transport.startMetering();

        expect(mock.analysers).toHaveLength(4);
        expect(groupOutput.connect).toHaveBeenCalledTimes(connectsBefore + 1);
        expect(groupOutput.connect).toHaveBeenCalledWith(mock.masterGain);
        expect(mock.masterGain.connect).toHaveBeenCalledTimes(1);
        expect(mock.monitorGain.connect).not.toHaveBeenCalled();
      });

      it("keeps program taps off the monitor fader", async () => {
        addGroup("vo");
        const { transport, mock, gen } = setupGroupTransport();
        await scheduleGrouped(transport, gen, "a", "vo");
        transport.startMetering();
        transport.setVolume(0.5);
        transport.setMuted(true);
        const groupOutput = mock.gainNodes.find((n) =>
          n.connect.mock.calls.some((call) => call[0] === mock.masterGain),
        );
        expect(mock.masterGain.gain.value).toBe(1);
        expect(groupOutput?.gain.value).toBe(1);
        expect(mock.monitorGain.gain.value).toBe(0);
      });

      it("reads the peak per channel and stops cleanly", async () => {
        addGroup("vo");
        const { transport, mock, gen } = setupGroupTransport();
        await scheduleGrouped(transport, gen, "a", "vo");
        transport.startMetering();
        const [masterL, , groupL, groupR] = mock.analysers;
        setLevel(masterL!, 0.5);
        setLevel(groupL!, 0.25);
        setLevel(groupR!, 0.125);

        const levels = transport.readLevels();
        expect(levels.master).toEqual({ l: 0.5, r: 0 });
        expect(levels.groups.vo).toEqual({ l: 0.25, r: 0.125 });

        transport.stopMetering();
        expect(transport.readLevels()).toEqual({ master: { l: 0, r: 0 }, groups: {} });
        expect(mock.gainNodes[2]!.disconnect).toHaveBeenCalled();
      });

      it("a group built after start is metered, and one removed from the document leaves the read", async () => {
        const { transport, mock, gen } = setupGroupTransport();
        transport.startMetering();
        addGroup("late");
        await scheduleGrouped(transport, gen, "a", "late");
        expect(Object.keys(transport.readLevels().groups)).toEqual(["late"]);

        document.querySelector("hf-audio-group")!.remove();
        expect(transport.readLevels().groups).toEqual({});
        expect(mock.analysers).toHaveLength(4);
      });
    });
  });

  describe("decodeAudioElement retry policy (late-asset self-heal)", () => {
    function transportWithDecode(decodeImpl: () => Promise<AudioBuffer>) {
      const transport = new WebAudioTransport();
      const ctx = { state: "running", decodeAudioData: vi.fn(decodeImpl) };
      (transport as unknown as { _ctx: unknown })._ctx = ctx;
      return transport;
    }
    const el = (src: string) =>
      ({
        getAttribute: (name: string) => (name === "src" ? src : null),
        currentSrc: "",
      }) as unknown as HTMLMediaElement;
    const failedSrcs = (t: WebAudioTransport) =>
      (t as unknown as { _failedSrcs: Set<string> })._failedSrcs;

    it("does NOT blacklist a transient fetch failure — a later play retries and succeeds", async () => {
      const transport = transportWithDecode(async () => ({}) as AudioBuffer);
      const fetchMock = vi
        .fn()
        .mockResolvedValueOnce({ ok: false, status: 404 }) // asset not uploaded yet
        .mockResolvedValueOnce({ ok: true, arrayBuffer: async () => new ArrayBuffer(8) });
      vi.stubGlobal("fetch", fetchMock);

      const first = await transport.decodeAudioElement(el("tts.wav"));
      expect(first).toBeNull();
      expect(failedSrcs(transport).has("tts.wav")).toBe(false); // not permanently silenced

      const second = await transport.decodeAudioElement(el("tts.wav"));
      expect(second).not.toBeNull(); // self-heals once the asset is available
      expect(fetchMock).toHaveBeenCalledTimes(2);
      vi.unstubAllGlobals();
    });

    it("DOES blacklist genuinely undecodable bytes — not retried", async () => {
      const transport = transportWithDecode(async () => {
        throw new Error("unsupported codec");
      });
      const fetchMock = vi
        .fn()
        .mockResolvedValue({ ok: true, arrayBuffer: async () => new ArrayBuffer(8) });
      vi.stubGlobal("fetch", fetchMock);

      const first = await transport.decodeAudioElement(el("corrupt.wav"));
      expect(first).toBeNull();
      expect(failedSrcs(transport).has("corrupt.wav")).toBe(true); // bad data is permanent

      const second = await transport.decodeAudioElement(el("corrupt.wav"));
      expect(second).toBeNull();
      expect(fetchMock).toHaveBeenCalledTimes(1); // short-circuited, no re-fetch
      vi.unstubAllGlobals();
    });
  });
});