Skip to content

Write HTML. Render video. Built for agents.

82.4 KB
Raw Blame
// fallow-ignore-file code-duplication
import { describe, it, expect, vi, afterEach } from "vitest";
import {
  evictMediaSyncState,
  hasMediaSyncStateForTest,
  readElementPlaybackRate,
  readElementPlaybackStart,
  refreshRuntimeMediaCache,
  resolveRuntimeMediaClipDuration,
  syncRuntimeMedia as syncRuntimeMediaWithDuration,
} from "./media";
import type { RuntimeMediaClip } from "./media";
import { resolveNaturalMediaTimelineDuration } from "./playbackRate";
import { resetSeekDispatchState, waitForSeekCompletion } from "./adapters/seek-dispatch";
import { sourceTimeAt } from "../speedRamp";
import type { HfAutomationLane } from "../audioAutomation";

// Most cases predate the terminal rule and run with no composition end to hold at.
const syncRuntimeMedia = (
  params: Omit<Parameters<typeof syncRuntimeMediaWithDuration>[0], "getCompositionDuration"> &
    Partial<Pick<Parameters<typeof syncRuntimeMediaWithDuration>[0], "getCompositionDuration">>,
) => syncRuntimeMediaWithDuration({ getCompositionDuration: () => 0, ...params });

function createVideo(attrs: Record<string, string>): HTMLVideoElement {
  const el = document.createElement("video");
  for (const [key, value] of Object.entries(attrs)) {
    el.setAttribute(key, value);
  }
  // jsdom doesn't compute media duration, so we stub it
  Object.defineProperty(el, "duration", { value: NaN, writable: true, configurable: true });
  document.body.appendChild(el);
  return el;
}

function createAudio(attrs: Record<string, string>): HTMLAudioElement {
  const el = document.createElement("audio");
  for (const [key, value] of Object.entries(attrs)) {
    el.setAttribute(key, value);
  }
  Object.defineProperty(el, "duration", { value: NaN, writable: true, configurable: true });
  document.body.appendChild(el);
  return el;
}

describe("readElementPlaybackRate", () => {
  it("reads defaultPlaybackRate from element", () => {
    const el = document.createElement("video");
    Object.defineProperty(el, "defaultPlaybackRate", { value: 0.5, writable: true });
    expect(readElementPlaybackRate(el)).toBe(0.5);
  });

  it("defaults to 1 when not set", () => {
    const el = document.createElement("video");
    expect(readElementPlaybackRate(el)).toBe(1);
  });

  it("clamps to [0.1, 10]", () => {
    const el = document.createElement("video");
    Object.defineProperty(el, "defaultPlaybackRate", { value: 0.01, writable: true });
    expect(readElementPlaybackRate(el)).toBe(0.1);
    Object.defineProperty(el, "defaultPlaybackRate", { value: 20, writable: true });
    expect(readElementPlaybackRate(el)).toBe(10);
  });

  it("defaults to 1 for NaN/negative/zero", () => {
    const el = document.createElement("video");
    Object.defineProperty(el, "defaultPlaybackRate", { value: NaN, writable: true });
    expect(readElementPlaybackRate(el)).toBe(1);
    Object.defineProperty(el, "defaultPlaybackRate", { value: -1, writable: true });
    expect(readElementPlaybackRate(el)).toBe(1);
    Object.defineProperty(el, "defaultPlaybackRate", { value: 0, writable: true });
    expect(readElementPlaybackRate(el)).toBe(1);
  });
});

describe("readElementPlaybackStart fallback", () => {
  it.each([
    ["", "1.5", 1.5],
    ["   ", "1.5", 1.5],
    ["later", "1.5", 1.5],
    ["-1", "1.5", 1.5],
    [null, "-1", 0],
    ["0", "1.5", 0],
    ["2.25", "1.5", 2.25],
  ])("uses non-negative finite playback-start -> media-start -> 0", (playback, media, expected) => {
    const el = document.createElement("audio");
    if (playback !== null) el.setAttribute("data-playback-start", playback);
    el.setAttribute("data-media-start", media);
    expect(readElementPlaybackStart(el)).toBe(expected);
  });
});

describe("refreshRuntimeMediaCache", () => {
  afterEach(() => {
    document.body.innerHTML = "";
  });

  it("finds video elements with data-start", () => {
    createVideo({ "data-start": "0", "data-duration": "5" });
    const result = refreshRuntimeMediaCache();
    expect(result.timedMediaEls).toHaveLength(1);
    expect(result.mediaClips).toHaveLength(1);
    expect(result.videoClips).toHaveLength(1);
  });

  it("finds audio elements with data-start", () => {
    createAudio({ "data-start": "2", "data-duration": "3" });
    const result = refreshRuntimeMediaCache();
    expect(result.timedMediaEls).toHaveLength(1);
    expect(result.mediaClips).toHaveLength(1);
    expect(result.videoClips).toHaveLength(0);
  });

  it("ignores media without data-start", () => {
    document.body.appendChild(document.createElement("video"));
    const result = refreshRuntimeMediaCache();
    expect(result.timedMediaEls).toHaveLength(0);
  });

  it("calculates clip end from start + duration", () => {
    createVideo({ "data-start": "2", "data-duration": "3" });
    const result = refreshRuntimeMediaCache();
    const clip = result.mediaClips[0];
    expect(clip.start).toBe(2);
    expect(clip.duration).toBe(3);
    expect(clip.end).toBe(5);
  });

  it("uses media-start offset", () => {
    createVideo({ "data-start": "0", "data-duration": "5", "data-media-start": "10" });
    const result = refreshRuntimeMediaCache();
    expect(result.mediaClips[0].mediaStart).toBe(10);
  });

  it("parses volume attribute", () => {
    createVideo({ "data-start": "0", "data-duration": "5", "data-volume": "0.5" });
    const result = refreshRuntimeMediaCache();
    expect(result.mediaClips[0].volume).toBe(0.5);
  });

  it("handles missing volume gracefully", () => {
    createVideo({ "data-start": "0", "data-duration": "5" });
    const result = refreshRuntimeMediaCache();
    expect(result.mediaClips[0].volume).toBeNull();
  });

  it("maxMediaEnd tracks highest clip end", () => {
    createVideo({ "data-start": "0", "data-duration": "5" });
    createVideo({ "data-start": "3", "data-duration": "10" });
    const result = refreshRuntimeMediaCache();
    expect(result.maxMediaEnd).toBe(13);
  });

  it("uses custom resolveStartSeconds", () => {
    createVideo({ "data-start": "0", "data-duration": "5" });
    const result = refreshRuntimeMediaCache({ resolveStartSeconds: () => 10 });
    expect(result.mediaClips[0].start).toBe(10);
  });

  it("falls back to element.duration when data-duration missing", () => {
    const el = createVideo({ "data-start": "0" });
    Object.defineProperty(el, "duration", { value: 8, writable: true });
    const result = refreshRuntimeMediaCache();
    expect(result.mediaClips[0].duration).toBe(8);
  });

  it("reads defaultPlaybackRate from element", () => {
    const el = createVideo({ "data-start": "0", "data-duration": "10" });
    Object.defineProperty(el, "defaultPlaybackRate", { value: 0.5, writable: true });
    const result = refreshRuntimeMediaCache();
    expect(result.mediaClips[0].playbackRate).toBe(0.5);
  });

  it("defaults playback rate to 1", () => {
    createVideo({ "data-start": "0", "data-duration": "5" });
    const result = refreshRuntimeMediaCache();
    expect(result.mediaClips[0].playbackRate).toBe(1);
  });

  it("clamps playback rate to [0.1, 10]", () => {
    const el1 = createVideo({ "data-start": "0", "data-duration": "5" });
    Object.defineProperty(el1, "defaultPlaybackRate", { value: 0.01, writable: true });
    const r1 = refreshRuntimeMediaCache();
    expect(r1.mediaClips[0].playbackRate).toBe(0.1);
    document.body.innerHTML = "";
    const el2 = createVideo({ "data-start": "0", "data-duration": "5" });
    Object.defineProperty(el2, "defaultPlaybackRate", { value: 20, writable: true });
    const r2 = refreshRuntimeMediaCache();
    expect(r2.mediaClips[0].playbackRate).toBe(10);
  });

  it("adjusts fallback duration by playback rate", () => {
    const el = createVideo({ "data-start": "0" });
    Object.defineProperty(el, "defaultPlaybackRate", { value: 0.5, writable: true });
    Object.defineProperty(el, "duration", { value: 10, writable: true });
    const result = refreshRuntimeMediaCache();
    // 10s source at 0.5x = 20s on timeline
    expect(result.mediaClips[0].duration).toBe(20);
  });

  it("resolveDurationSeconds must account for playbackRate (regression: clip clipped early)", () => {
    const el = createVideo({ "data-start": "0", "data-duration": "10" });
    Object.defineProperty(el, "defaultPlaybackRate", { value: 0.5, writable: true });
    Object.defineProperty(el, "duration", { value: 5, writable: true });
    const result = refreshRuntimeMediaCache({
      resolveDurationSeconds: (element) => {
        const mediaStart =
          Number.parseFloat(element.dataset.playbackStart ?? element.dataset.mediaStart ?? "0") ||
          0;
        const playbackRate = readElementPlaybackRate(element);
        return Number.isFinite(element.duration) && element.duration > mediaStart
          ? Math.max(0, (element.duration - mediaStart) / playbackRate)
          : null;
      },
    });
    // 5s source at 0.5x = 10s effective; should NOT be capped to 5s
    expect(result.mediaClips[0].duration).toBe(10);
    expect(result.mediaClips[0].end).toBe(10);
  });

  it.each([10, 11])(
    "preserves an authoritative zero duration at or past EOF (start=%s)",
    (mediaStart) => {
      const el = createVideo({ "data-start": "3", "data-media-start": String(mediaStart) });
      Object.defineProperty(el, "duration", { value: 10, writable: true });
      const result = refreshRuntimeMediaCache({
        resolveDurationSeconds: (element) =>
          resolveNaturalMediaTimelineDuration(element, element.duration),
      });

      expect(result.mediaClips[0].duration).toBe(0);
      expect(result.mediaClips[0].end).toBe(3);
      expect(result.maxMediaEnd).toBe(3);
    },
  );

  it("distinguishes an authoritative zero duration from an unknown duration", () => {
    createVideo({ "data-start": "3" });
    const knownZero = refreshRuntimeMediaCache({ resolveDurationSeconds: () => 0 });
    const unknown = refreshRuntimeMediaCache({ resolveDurationSeconds: () => null });

    expect(knownZero.mediaClips[0]).toMatchObject({ duration: 0, end: 3 });
    expect(unknown.mediaClips[0]).toMatchObject({ duration: Infinity, end: Infinity });
  });

  it("reads native loop attribute", () => {
    createVideo({ "data-start": "0", "data-duration": "15", loop: "" });
    const result = refreshRuntimeMediaCache();
    expect(result.mediaClips[0].loop).toBe(true);
  });

  it("defaults loop to false", () => {
    createVideo({ "data-start": "0", "data-duration": "5" });
    const result = refreshRuntimeMediaCache();
    expect(result.mediaClips[0].loop).toBe(false);
  });
});

describe("resolveRuntimeMediaClipDuration", () => {
  it("preserves an explicit video slot beyond the source", () => {
    expect(
      resolveRuntimeMediaClipDuration({
        isVideo: true,
        sourceDuration: 1,
        hostRemaining: 8,
        explicitDuration: 5,
      }),
    ).toBe(5);
  });

  it("honors an explicit slot for a looping video instead of truncating it to one loop", () => {
    // Loop wrapping happens later in syncRuntimeMedia. Duration resolution must
    // preserve the authored window that the loop fills.
    expect(
      resolveRuntimeMediaClipDuration({
        isVideo: true,
        sourceDuration: 1,
        hostRemaining: null,
        explicitDuration: 10,
      }),
    ).toBe(10);
  });

  it("keeps audio bounded by its playable source", () => {
    expect(
      resolveRuntimeMediaClipDuration({
        isVideo: false,
        sourceDuration: 1,
        hostRemaining: 8,
        explicitDuration: 5,
      }),
    ).toBe(1);
  });

  it("uses natural duration for a video without an explicit slot", () => {
    expect(
      resolveRuntimeMediaClipDuration({
        isVideo: true,
        sourceDuration: 1,
        hostRemaining: 8,
        explicitDuration: null,
      }),
    ).toBe(1);
  });

  it("uses natural source duration when a video has no slot or host window", () => {
    expect(
      resolveRuntimeMediaClipDuration({
        isVideo: true,
        sourceDuration: 1,
        hostRemaining: null,
        explicitDuration: null,
      }),
    ).toBe(1);
  });

  it("preserves a known zero natural span instead of falling back to the host window", () => {
    expect(
      resolveRuntimeMediaClipDuration({
        isVideo: true,
        sourceDuration: 0,
        hostRemaining: 8,
        explicitDuration: null,
      }),
    ).toBe(0);
  });
});

describe("syncRuntimeMedia", () => {
  function fakePlayedRanges(el: HTMLMediaElement, ranges: Array<[number, number]>): void {
    Object.defineProperty(el, "played", {
      configurable: true,
      get: () => ({
        length: ranges.length,
        start: (i: number) => ranges[i][0],
        end: (i: number) => ranges[i][1],
      }),
    });
  }

  function createMockClip(
    overrides?: Partial<RuntimeMediaClip>,
    mediaType: "audio" | "video" = "video",
  ): RuntimeMediaClip {
    const el = document.createElement(mediaType);
    document.body.appendChild(el);
    Object.defineProperty(el, "paused", { value: true, writable: true, configurable: true });
    el.play = vi.fn(() => Promise.resolve());
    el.pause = vi.fn();
    Object.defineProperty(el, "currentTime", { value: 0, writable: true, configurable: true });
    Object.defineProperty(el, "playbackRate", { value: 1, writable: true, configurable: true });
    // Default: audio has been playing — so drift-seek forward is allowed.
    // Tests that exercise the "cold first play" guard call fakePlayedRanges(el, []).
    fakePlayedRanges(el, [[0, 1]]);
    // Mirror bindMediaMetadataListeners: pre-set el.volume to data-volume so the
    // first-tick path in syncRuntimeMedia sees the correct baseline (not the browser
    // default of 1) and GSAP-change detection works correctly from the first tick.
    const dataVolume = overrides?.volume;
    if (dataVolume != null && Number.isFinite(dataVolume)) {
      el.volume = Math.max(0, Math.min(1, dataVolume));
    }
    return {
      el,
      start: 0,
      mediaStart: 0,
      duration: 10,
      end: 10,
      volume: null,
      playbackRate: 1,
      loop: false,
      sourceDuration: null,
      ...overrides,
    };
  }

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

  it("seeks a clip whose start is a float sum to its first frame, never before it", () => {
    const clip = createMockClip({ start: 19.8 + 0.1, end: 25 });
    Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
    clip.el.currentTime = 3;
    syncRuntimeMedia({ clips: [clip], timeSeconds: 19.9, playing: false, playbackRate: 1 });
    expect(clip.el.currentTime).toBe(0);
  });

  describe("speed ramp", () => {
    it("seeks to the integrated source time and plays at the instantaneous rate", () => {
      const rate = {
        target: "rate",
        points: [
          { t: 0, v: 1 },
          { t: 2, v: 3 },
        ],
      };
      const clip = createMockClip({ start: 1, end: 5, rate });
      Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
      syncRuntimeMedia({ clips: [clip], timeSeconds: 3, playing: false, playbackRate: 1 });
      expect(clip.el.currentTime).toBeCloseTo(3.641, 2);
      syncRuntimeMedia({ clips: [clip], timeSeconds: 3, playing: true, playbackRate: 1 });
      expect(clip.el.playbackRate).toBeCloseTo(3, 5);
    });
  });

  describe("volume automation lane", () => {
    const DUCK = JSON.stringify({
      version: 1,
      lanes: [
        {
          target: "volume",
          points: [
            { t: 0, v: 0.8 },
            { t: 2, v: 0.8 },
            { t: 3, v: 0.1 },
            { t: 8, v: 0.1 },
          ],
        },
      ],
    });

    /**
     * The runtime rewrites the transport's gain every tick. Before the lane fed
     * this path it was scheduled onto the AudioParam instead and erased within a
     * frame, so the envelope was inaudible in preview while being correct in the
     * render.
     */
    function volumesAt(times: number[], automation?: string, volume = 0.55) {
      const clip = createMockClip({ start: 0, end: 10, volume });
      Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
      if (automation) clip.el.setAttribute("data-automation", automation);
      const seen: number[] = [];
      for (const t of times) {
        syncRuntimeMedia({
          clips: [clip],
          timeSeconds: t,
          playing: true,
          playbackRate: 1,
          onElementVolume: (_el, v) => seen.push(v),
        });
      }
      return seen;
    }

    it("drives the transport gain from the lane times data-volume", () => {
      const [held, ducked] = volumesAt([1, 5], DUCK);
      expect(held).toBeCloseTo(0.8 * 0.55, 5);
      expect(ducked).toBeCloseTo(0.1 * 0.55, 5);
    });

    it("keeps automation author-only while user volume remains a separate layer", () => {
      const clip = createMockClip({ start: 0, end: 10, volume: 0.55 });
      clip.el.setAttribute("data-automation", DUCK);
      const onElementVolume = vi.fn();
      syncRuntimeMedia({
        clips: [clip],
        timeSeconds: 1,
        playing: true,
        playbackRate: 1,
        userVolume: 0.5,
        onElementVolume,
      });

      expect(onElementVolume).toHaveBeenLastCalledWith(
        clip.el,
        expect.closeTo(0.22, 5),
        expect.closeTo(0.44, 5),
        1,
      );
    });

    it("leaves a routed clip's lane to the transport, sending data-volume as clip gain", () => {
      const clip = createMockClip({ start: 0, end: 10, volume: 0.55 });
      clip.el.setAttribute("data-automation", DUCK);
      const onElementVolume = vi.fn();
      syncRuntimeMedia({
        clips: [clip],
        timeSeconds: 5,
        playing: true,
        playbackRate: 1,
        onElementVolume,
        isWebAudioRouted: () => true,
      });

      expect(onElementVolume).toHaveBeenLastCalledWith(clip.el, 1, 1, 0.55);
    });

    it("ramps between points across ticks", () => {
      const [a, b, c] = volumesAt([2, 2.5, 3], DUCK);
      expect(a).toBeCloseTo(0.8 * 0.55, 5);
      expect(b).toBeGreaterThan(0.1 * 0.55);
      expect(b).toBeLessThan(0.8 * 0.55);
      expect(c).toBeCloseTo(0.1 * 0.55, 5);
    });

    it("falls back to data-volume when there is no lane", () => {
      const [only] = volumesAt([5], undefined, 0.55);
      expect(only).toBeCloseTo(0.55, 5);
    });

    it("applies data-fade-in / data-fade-out on top of data-volume, anchored to the clip edges", () => {
      const at = (t: number) => {
        const clip = createMockClip({ start: 2, end: 12, duration: 10, volume: 0.8 });
        Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
        clip.el.setAttribute("data-fade-in", "2");
        clip.el.setAttribute("data-fade-out", "1");
        clip.fades = { fadeIn: 2, fadeOut: 1 };
        let authored = -1;
        syncRuntimeMedia({
          clips: [clip],
          timeSeconds: t,
          playing: true,
          playbackRate: 1,
          onElementVolume: (_el, _effective, authorVolume) => {
            authored = authorVolume;
          },
        });
        return authored;
      };
      expect(at(2.5)).toBeCloseTo(0.2, 5); // a quarter into the 2 s fade-in
      expect(at(3)).toBeCloseTo(0.4, 5); // halfway through the fade-in
      expect(at(6)).toBeCloseTo(0.8, 5); // body of the clip: data-volume alone
      expect(at(11.5)).toBeCloseTo(0.4, 5); // halfway through the 1 s fade-out
      expect(at(11.9)).toBeCloseTo(0.08, 5); // almost at the clip's end
    });

    it("never writes NaN or a negative volume for 0, negative, NaN, or longer-than-clip fades", () => {
      const cases: Array<{ fadeIn: number; fadeOut: number }> = [
        { fadeIn: 0, fadeOut: 0 },
        { fadeIn: -2, fadeOut: -1 },
        { fadeIn: Number.NaN, fadeOut: Number.NaN },
        { fadeIn: 40, fadeOut: 40 },
      ];
      for (const fades of cases) {
        const clip = createMockClip({ start: 0, end: 10, duration: 10, volume: 0.5, fades });
        Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
        for (const t of [0, 5, 10, 12]) {
          syncRuntimeMedia({
            clips: [clip],
            timeSeconds: t,
            playing: true,
            playbackRate: 1,
          });
          expect(Number.isFinite(clip.el.volume)).toBe(true);
          expect(clip.el.volume).toBeGreaterThanOrEqual(0);
          expect(clip.el.volume).toBeLessThanOrEqual(1);
        }
      }
    });

    it("sends boosted author gain to Web Audio while keeping the native element legal", () => {
      const clip = createMockClip({ start: 0, end: 10, volume: 3.98 });
      Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
      let transportGain = -1;

      syncRuntimeMedia({
        clips: [clip],
        timeSeconds: 1,
        playing: true,
        playbackRate: 1,
        // Third arg is the authored gain, which is the one the transport wants;
        // the second is the element's, which the spec pins to [0,1].
        onElementVolume: (_el, _effectiveVolume, authorVolume) => {
          transportGain = authorVolume;
        },
      });

      expect(transportGain).toBeCloseTo(3.98, 5);
      expect(clip.el.volume).toBe(1);
    });

    /**
     * The render bakes the lane at CLIP-LOCAL time: prepareAudioTrack already
     * cut the wav with `-ss mediaStart`, so its t=0 is the clip's start, and
     * normaliseEnvelope subtracts trackStart. Preview used to sample at MEDIA
     * time — mediaStart included, scaled by playbackRate, wrapped on a loop — so
     * the same envelope played somewhere else than it rendered.
     */
    it("samples the lane at clip-local time, the way the render bakes it", () => {
      const trimmed = (t: number) => {
        const clip = createMockClip({ start: 0, end: 10, volume: 0.55, mediaStart: 30 });
        Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
        clip.el.setAttribute("data-automation", DUCK);
        let seen = -1;
        syncRuntimeMedia({
          clips: [clip],
          timeSeconds: t,
          playing: true,
          playbackRate: 1,
          onElementVolume: (_el, v) => {
            seen = v;
          },
        });
        return seen;
      };
      // `data-media-start="30"` on a clip whose lane holds 0.8 until t=2 then
      // ducks to 0.1 by t=3. At media time the playhead is already 30 s past the
      // last point, so preview held 0.1 from the first frame and never ducked.
      expect(trimmed(1)).toBeCloseTo(0.8 * 0.55, 5);
      expect(trimmed(5)).toBeCloseTo(0.1 * 0.55, 5);
    });

    it("supersedes keyframes probed from the timeline", () => {
      // Both present: the lane is the explicit one, and `lint` warns about it.
      const clip = createMockClip({ start: 0, end: 10, volume: 0.55 });
      Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
      clip.el.setAttribute("data-automation", DUCK);
      clip.volumeKeyframes = [
        { time: 0, volume: 1 },
        { time: 10, volume: 1 },
      ];
      let seen = -1;
      syncRuntimeMedia({
        clips: [clip],
        timeSeconds: 5,
        playing: true,
        playbackRate: 1,
        onElementVolume: (_el, v) => {
          seen = v;
        },
      });
      expect(seen).toBeCloseTo(0.1 * 0.55, 5);
    });
  });

  it("hands the transport an above-unity author gain, uncapped", () => {
    // The preview terminus. `el.volume` is spec-bound to [0,1] and always will
    // be, so the boost can only reach the ear through the Web Audio gain node —
    // which means the author gain handed to the transport must NOT be capped on
    // the way out, even though the native write beside it is.
    const clip = createMockClip({ start: 0, end: 10, volume: 1.949845 });
    const onElementVolume = vi.fn();

    syncRuntimeMedia({
      clips: [clip],
      timeSeconds: 1,
      playing: false,
      playbackRate: 1,
      onElementVolume,
    });

    const [, , authorVolume] = onElementVolume.mock.calls.at(-1) as [unknown, number, number];
    expect(authorVolume).toBeCloseTo(1.949845, 6);
    expect(clip.el.volume).toBe(1);
  });

  it("plays active clip when playing and buffered", () => {
    const clip = createMockClip({ start: 0, end: 10 });
    Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
    syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: true, playbackRate: 1 });
    expect(clip.el.play).toHaveBeenCalled();
  });

  it("uses a half-open interval around a clip's end boundary", () => {
    const clip = createMockClip({ start: 0, end: 2.5 });
    Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });

    syncRuntimeMedia({
      clips: [clip],
      timeSeconds: 2.5 - 1e-9,
      playing: true,
      playbackRate: 1,
    });
    expect(clip.el.play).toHaveBeenCalledTimes(1);

    syncRuntimeMedia({ clips: [clip], timeSeconds: 2.5, playing: true, playbackRate: 1 });
    syncRuntimeMedia({
      clips: [clip],
      timeSeconds: 2.5 + 1e-9,
      playing: true,
      playbackRate: 1,
    });
    expect(clip.el.play).toHaveBeenCalledTimes(1);
  });

  it("plays synchronously even when media is unbuffered (preserves user gesture)", () => {
    // Calling play() synchronously inside the user-gesture call chain lets the
    // browser queue playback until data buffers, while consuming the transient
    // user activation. Deferring to an async canplay handler would let the
    // activation expire and the autoplay policy silently reject — producing
    // the "silent first play, audio only after second click" bug.
    const clip = createMockClip({ start: 0, end: 10 });
    Object.defineProperty(clip.el, "readyState", { value: 0, writable: true });
    syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: true, playbackRate: 1 });
    expect(clip.el.play).toHaveBeenCalled();
  });

  describe("data-hidden silences preview volume", () => {
    const hiddenClip = () => {
      const clip = createMockClip({ start: 0, end: 10, volume: 0.8 });
      Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
      const hiddenAncestor = document.createElement("div");
      hiddenAncestor.setAttribute("data-hidden", "");
      document.body.appendChild(hiddenAncestor);
      hiddenAncestor.appendChild(clip.el);
      return clip;
    };
    const volumeSeen = (clip: ReturnType<typeof hiddenClip>) => {
      let seen = -1;
      syncRuntimeMedia({
        clips: [clip],
        timeSeconds: 1,
        playing: true,
        playbackRate: 1,
        onElementVolume: (_el, v) => {
          seen = v;
        },
      });
      return seen;
    };

    it("zeroes effective volume for a clip under a data-hidden ancestor", () => {
      expect(volumeSeen(hiddenClip())).toBe(0);
    });

    // A visible clip is the control: the zero above has to come from the
    // ancestor, not from the fixture reading 0 for some other reason.
    it("leaves a visible clip at its authored volume", () => {
      const clip = createMockClip({ start: 0, end: 10, volume: 0.8 });
      Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
      document.body.appendChild(clip.el);
      expect(volumeSeen(clip)).toBe(0.8);
    });

    it("does not touch el.muted when silencing a hidden clip (RULES trap: transport owns el.muted)", () => {
      const clip = hiddenClip();
      clip.el.muted = false;

      syncRuntimeMedia({
        clips: [clip],
        timeSeconds: 1,
        playing: true,
        playbackRate: 1,
      });

      expect(clip.el.muted).toBe(false);
    });
  });

  describe("video seek completion", () => {
    afterEach(() => resetSeekDispatchState());

    function seekColdVideo(): RuntimeMediaClip {
      const clip = createMockClip({ start: 7.1, end: 18.24 });
      Object.defineProperty(clip.el, "seeking", { value: true, configurable: true });
      syncRuntimeMedia({ clips: [clip], timeSeconds: 12, playing: false, playbackRate: 1 });
      return clip;
    }

    async function barrierSettled(barrier: Promise<void>): Promise<boolean> {
      let settled = false;
      void barrier.then(() => (settled = true));
      await new Promise((resolve) => setTimeout(resolve, 0));
      return settled;
    }

    it("holds the seek-completion barrier until a seeking video lands its frame", async () => {
      const clip = seekColdVideo();
      expect(clip.el.currentTime).toBeCloseTo(4.9);
      const barrier = waitForSeekCompletion();
      expect(await barrierSettled(barrier)).toBe(false);
      clip.el.dispatchEvent(new Event("seeked"));
      expect(await barrierSettled(barrier)).toBe(true);
    });

    it("does not hold a geometry read for a seeking video's frame", async () => {
      seekColdVideo();
      expect(await barrierSettled(waitForSeekCompletion({ videoFrames: false }))).toBe(true);
      expect(await barrierSettled(waitForSeekCompletion())).toBe(false);
    });

    function seekLoadingVideo(): RuntimeMediaClip {
      const clip = createMockClip({ start: 7.1, end: 18.24 });
      Object.defineProperty(clip.el, "readyState", { value: 0, configurable: true });
      Object.defineProperty(clip.el, "networkState", { value: 2, configurable: true });
      syncRuntimeMedia({ clips: [clip], timeSeconds: 12, playing: false, playbackRate: 1 });
      return clip;
    }

    it("holds the barrier until a video still loading its first data has it", async () => {
      const clip = seekLoadingVideo();
      expect(clip.el.seeking).toBe(false);
      const barrier = waitForSeekCompletion();
      expect(await barrierSettled(barrier)).toBe(false);
      Object.defineProperty(clip.el, "seeking", { value: true, configurable: true });
      clip.el.dispatchEvent(new Event("loadeddata"));
      expect(await barrierSettled(barrier)).toBe(false);
      clip.el.dispatchEvent(new Event("seeked"));
      expect(await barrierSettled(barrier)).toBe(true);
    });

    it("holds a loading video that is already parked on the frame's time", async () => {
      const clip = createMockClip({ start: 7.1, end: 18.24 });
      Object.defineProperty(clip.el, "readyState", { value: 0, configurable: true });
      Object.defineProperty(clip.el, "networkState", { value: 2, configurable: true });
      clip.el.currentTime = 4.9;
      syncRuntimeMedia({ clips: [clip], timeSeconds: 12, playing: false, playbackRate: 1 });
      expect(await barrierSettled(waitForSeekCompletion())).toBe(false);
    });

    it("does not hold a video that is not fetching", async () => {
      const clip = createMockClip({ start: 7.1, end: 18.24 });
      Object.defineProperty(clip.el, "readyState", { value: 0, configurable: true });
      Object.defineProperty(clip.el, "networkState", { value: 1, configurable: true });
      syncRuntimeMedia({ clips: [clip], timeSeconds: 12, playing: false, playbackRate: 1 });
      expect(await barrierSettled(waitForSeekCompletion())).toBe(true);
    });

    it("releases a loading video when its <source> child fails", async () => {
      const clip = seekLoadingVideo();
      const source = document.createElement("source");
      clip.el.appendChild(source);
      const barrier = waitForSeekCompletion();
      source.dispatchEvent(new Event("error"));
      expect(await barrierSettled(barrier)).toBe(true);
    });

    it("gives a later seek its own full wait", async () => {
      vi.useFakeTimers();
      try {
        const clip = seekLoadingVideo();
        await vi.advanceTimersByTimeAsync(4000);
        syncRuntimeMedia({ clips: [clip], timeSeconds: 13, playing: false, playbackRate: 1 });
        let settled = false;
        void waitForSeekCompletion().then(() => (settled = true));
        await vi.advanceTimersByTimeAsync(4999);
        expect(settled).toBe(false);
        await vi.advanceTimersByTimeAsync(1);
        expect(settled).toBe(true);
      } finally {
        vi.useRealTimers();
      }
    });

    it("does not hold a loading video while playing without a seek", async () => {
      const clip = createMockClip({ start: 7.1, end: 18.24 });
      Object.defineProperty(clip.el, "readyState", { value: 0, configurable: true });
      Object.defineProperty(clip.el, "networkState", { value: 2, configurable: true });
      syncRuntimeMedia({ clips: [clip], timeSeconds: 12, playing: true, playbackRate: 1 });
      resetSeekDispatchState();
      syncRuntimeMedia({ clips: [clip], timeSeconds: 12, playing: true, playbackRate: 1 });
      expect(await barrierSettled(waitForSeekCompletion())).toBe(true);
    });

    it("releases a video that never loads after the cap", async () => {
      vi.useFakeTimers();
      try {
        seekLoadingVideo();
        let settled = false;
        void waitForSeekCompletion().then(() => (settled = true));
        await vi.advanceTimersByTimeAsync(4999);
        expect(settled).toBe(false);
        await vi.advanceTimersByTimeAsync(1);
        expect(settled).toBe(true);
      } finally {
        vi.useRealTimers();
      }
    });

    it("keeps holding a loading video through a suspend between range requests", async () => {
      const clip = seekLoadingVideo();
      const barrier = waitForSeekCompletion();
      clip.el.dispatchEvent(new Event("suspend"));
      expect(await barrierSettled(barrier)).toBe(false);
      Object.defineProperty(clip.el, "seeking", { value: true, configurable: true });
      clip.el.dispatchEvent(new Event("loadedmetadata"));
      clip.el.dispatchEvent(new Event("seeking"));
      expect(await barrierSettled(barrier)).toBe(false);
      Object.defineProperty(clip.el, "seeking", { value: false, configurable: true });
      clip.el.dispatchEvent(new Event("seeked"));
      expect(await barrierSettled(barrier)).toBe(true);
    });

    it("does not hold a render for a video still loading", async () => {
      const renderWindow = window as { __HF_EXPORT_RENDER_SEEK_CONFIG?: unknown };
      renderWindow.__HF_EXPORT_RENDER_SEEK_CONFIG = { mode: "seek" };
      try {
        seekLoadingVideo();
        expect(await barrierSettled(waitForSeekCompletion())).toBe(true);
      } finally {
        delete renderWindow.__HF_EXPORT_RENDER_SEEK_CONFIG;
      }
    });

    it.each(["error", "emptied", "abort"])(
      "releases the barrier when the seek ends in %s",
      async (type) => {
        const clip = seekColdVideo();
        const barrier = waitForSeekCompletion();
        clip.el.dispatchEvent(new Event(type));
        expect(await barrierSettled(barrier)).toBe(true);
      },
    );
  });

  describe("play() storm guard (unplayable elements)", () => {
    it("does not play() an element with a media error", () => {
      const clip = createMockClip({ start: 0, end: 10 });
      Object.defineProperty(clip.el, "error", { value: { code: 4 }, configurable: true });
      syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: true, playbackRate: 1 });
      expect(clip.el.play).not.toHaveBeenCalled();
    });

    it("starts an audio clip due within the next tick, from its first sample", () => {
      const clip = createMockClip({ start: 5, end: 6, mediaStart: 2 }, "audio");
      syncRuntimeMedia({
        clips: [clip],
        timeSeconds: 4.99,
        playing: true,
        playbackRate: 1,
        cueAheadSeconds: 0.017,
      });
      expect(clip.el.play).toHaveBeenCalledTimes(1);
      expect(clip.el.currentTime).toBe(2);
    });

    it("does not start an audio clip further away than the next tick", () => {
      const clip = createMockClip({ start: 5, end: 6 }, "audio");
      syncRuntimeMedia({
        clips: [clip],
        timeSeconds: 4.95,
        playing: true,
        playbackRate: 1,
        cueAheadSeconds: 0.017,
      });
      expect(clip.el.play).not.toHaveBeenCalled();
    });

    it("does not start a sped-up clip so early that its window opens it past strict sync", () => {
      const clip = createMockClip({ start: 5, end: 6, rate: 3 }, "audio");
      syncRuntimeMedia({
        clips: [clip],
        timeSeconds: 4.98,
        playing: true,
        playbackRate: 1,
        cueAheadSeconds: 0.034,
      });
      expect(clip.el.play).not.toHaveBeenCalled();
    });

    it("judges a head-cut clip's cue-ahead by its rate at the cut, not at its own start", () => {
      // The clip's own t=0 is 2 and an in-point cuts it to start at 5, where the ramp has reached 3x.
      const rate: HfAutomationLane = {
        target: "rate",
        points: [
          { t: 0, v: 1 },
          { t: 3, v: 3 },
        ],
      };
      const clip = createMockClip({ start: 5, origin: 2, end: 6, rate }, "audio");
      syncRuntimeMedia({
        clips: [clip],
        timeSeconds: 4.98,
        playing: true,
        playbackRate: 1,
        cueAheadSeconds: 0.034,
      });
      expect(clip.el.play).not.toHaveBeenCalled();
    });

    it("keeps a clip it started early playing when the next tick is shorter", () => {
      const clip = createMockClip({ start: 5, end: 6 }, "audio");
      syncRuntimeMedia({
        clips: [clip],
        timeSeconds: 4.97,
        playing: true,
        playbackRate: 1,
        cueAheadSeconds: 0.034,
      });
      Object.defineProperty(clip.el, "paused", {
        value: false,
        writable: true,
        configurable: true,
      });
      syncRuntimeMedia({
        clips: [clip],
        timeSeconds: 4.98,
        playing: true,
        playbackRate: 1,
        cueAheadSeconds: 0.01,
      });
      expect(clip.el.pause).not.toHaveBeenCalled();
    });

    it("does not start a clip again once the playhead is past it", () => {
      const clip = createMockClip({ start: 5, end: 6 }, "audio");
      syncRuntimeMedia({
        clips: [clip],
        timeSeconds: 6.01,
        playing: true,
        playbackRate: 1,
        cueAheadSeconds: 0.017,
      });
      expect(clip.el.play).not.toHaveBeenCalled();
    });

    it("starts nothing early while paused, and never a video", () => {
      const audio = createMockClip({ start: 5, end: 6 }, "audio");
      syncRuntimeMedia({
        clips: [audio],
        timeSeconds: 4.99,
        playing: false,
        playbackRate: 1,
        cueAheadSeconds: 0.017,
      });
      const video = createMockClip({ start: 5, end: 6 }, "video");
      syncRuntimeMedia({
        clips: [video],
        timeSeconds: 4.99,
        playing: true,
        playbackRate: 1,
        cueAheadSeconds: 0.017,
      });
      expect(audio.el.play).not.toHaveBeenCalled();
      expect(video.el.play).not.toHaveBeenCalled();
    });

    it("does not play() an element whose networkState is NO_SOURCE", () => {
      const clip = createMockClip({ start: 0, end: 10 });
      Object.defineProperty(clip.el, "networkState", { value: 3, configurable: true });
      syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: true, playbackRate: 1 });
      expect(clip.el.play).not.toHaveBeenCalled();
    });

    it("does not re-play() across ticks while the element stays errored", () => {
      const clip = createMockClip({ start: 0, end: 10 });
      Object.defineProperty(clip.el, "error", { value: { code: 4 }, configurable: true });
      for (const t of [5, 5.1, 5.2, 5.3]) {
        syncRuntimeMedia({ clips: [clip], timeSeconds: t, playing: true, playbackRate: 1 });
      }
      expect(clip.el.play).not.toHaveBeenCalled();
    });

    it("plays again once the element recovers (error clears)", () => {
      const clip = createMockClip({ start: 0, end: 10 });
      Object.defineProperty(clip.el, "error", { value: { code: 4 }, configurable: true });
      syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: true, playbackRate: 1 });
      expect(clip.el.play).not.toHaveBeenCalled();
      Object.defineProperty(clip.el, "error", { value: null, configurable: true });
      syncRuntimeMedia({ clips: [clip], timeSeconds: 5.1, playing: true, playbackRate: 1 });
      expect(clip.el.play).toHaveBeenCalled();
    });
  });

  it("forces preload=auto on every active element, not just during play", () => {
    // Streaming formats (MP3) may arrive with preload="metadata", which only
    // buffers the first few seconds. Setting preload="auto" on every active
    // tick catches elements whose preload was overridden after init.ts set it
    // — and ensures it happens even when paused (e.g. during a seek).
    const clip = createMockClip({ start: 0, end: 10 });
    Object.defineProperty(clip.el, "preload", { value: "metadata", writable: true });
    syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: false, playbackRate: 1 });
    expect(clip.el.preload).toBe("auto");
  });

  it("does not re-fire play() while a previous play() is in flight", () => {
    // Without a play-request dedup, the 50ms runtime poll would fire 20–40
    // spurious play() calls per element during the 1–2s initial buffer, each
    // with a catch() that would swallow any real AbortError / NotAllowedError
    // the developer needs to see.
    const clip = createMockClip({ start: 0, end: 10 });
    Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
    syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: true, playbackRate: 1 });
    syncRuntimeMedia({ clips: [clip], timeSeconds: 5.02, playing: true, playbackRate: 1 });
    syncRuntimeMedia({ clips: [clip], timeSeconds: 5.04, playing: true, playbackRate: 1 });
    expect(clip.el.play).toHaveBeenCalledTimes(1);
  });

  it("re-issues play() after a hard seek clears the in-flight guard", () => {
    // A scrub during playback triggers a hard seek (offset jump > 0.5s).
    // The fix clears the playRequested guard so the very next sync tick can
    // re-issue play() instead of waiting 50-150ms for the guard to clear
    // naturally — closing the audible desync gap on timeline scrub.
    const clip = createMockClip({ start: 0, end: 20, mediaStart: 0 });
    Object.defineProperty(clip.el, "currentTime", { value: 2, writable: true });
    // Steady-state playback at t=2
    syncRuntimeMedia({ clips: [clip], timeSeconds: 2, playing: true, playbackRate: 1 });
    expect(clip.el.play).toHaveBeenCalledTimes(1);
    // Scrub to t=15 — hard seek fires, guard should be cleared
    syncRuntimeMedia({ clips: [clip], timeSeconds: 15, playing: true, playbackRate: 1 });
    // Next tick: play() should fire again (guard was cleared by the seek)
    syncRuntimeMedia({ clips: [clip], timeSeconds: 15.02, playing: true, playbackRate: 1 });
    expect(clip.el.play).toHaveBeenCalledTimes(2);
  });

  it("calls load() once when a seek fails past the buffered range (MP3 partial buffer)", () => {
    // Streaming MP3 with preload="metadata" only buffers the first ~15s.
    // When the user seeks to 20s, el.currentTime = 20 silently fails —
    // currentTime stays at 0. The fix detects this and calls load() once
    // to trigger a full network fetch.
    const clip = createMockClip({ start: 0, end: 30, mediaStart: 0 });
    // Simulate: currentTime is writable but the setter is intercepted
    // to stay at 0 (simulating failed seek past buffer).
    let internalTime = 0;
    Object.defineProperty(clip.el, "currentTime", {
      get: () => internalTime,
      set: () => {
        // Seek silently fails — stays at 0 (MP3 past buffer)
      },
      configurable: true,
    });
    clip.el.load = vi.fn();
    // First tick at t=20 — hard seek fires, fails, should call load()
    syncRuntimeMedia({ clips: [clip], timeSeconds: 20, playing: true, playbackRate: 1 });
    expect(clip.el.load).toHaveBeenCalledTimes(1);
    // Second tick — load() should NOT be called again (one-shot guard)
    syncRuntimeMedia({ clips: [clip], timeSeconds: 20.05, playing: true, playbackRate: 1 });
    expect(clip.el.load).toHaveBeenCalledTimes(1);
  });

  it("does not call load() when the seek succeeds", () => {
    const clip = createMockClip({ start: 0, end: 30, mediaStart: 0 });
    Object.defineProperty(clip.el, "currentTime", { value: 0, writable: true });
    clip.el.load = vi.fn();
    // Seek to 20 — succeeds (currentTime updates)
    syncRuntimeMedia({ clips: [clip], timeSeconds: 20, playing: true, playbackRate: 1 });
    expect(clip.el.currentTime).toBe(20);
    expect(clip.el.load).not.toHaveBeenCalled();
  });

  it("clears the load-retry guard when clip deactivates and reactivates", () => {
    const clip = createMockClip({ start: 0, end: 10, mediaStart: 0 });
    let internalTime = 0;
    Object.defineProperty(clip.el, "currentTime", {
      get: () => internalTime,
      set: () => {},
      configurable: true,
    });
    clip.el.load = vi.fn();
    // First activation — seek fails, load() called
    syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: true, playbackRate: 1 });
    expect(clip.el.load).toHaveBeenCalledTimes(1);
    // Deactivate
    syncRuntimeMedia({ clips: [clip], timeSeconds: 11, playing: true, playbackRate: 1 });
    // Reactivate — guard was cleared, so load() can fire again
    syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: true, playbackRate: 1 });
    expect(clip.el.load).toHaveBeenCalledTimes(2);
  });

  it("pauses active clip when not playing", () => {
    const clip = createMockClip({ start: 0, end: 10 });
    Object.defineProperty(clip.el, "paused", { value: false, writable: true });
    syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: false, playbackRate: 1 });
    expect(clip.el.pause).toHaveBeenCalled();
  });

  it("pauses inactive clip", () => {
    const clip = createMockClip({ start: 5, end: 10 });
    Object.defineProperty(clip.el, "paused", { value: false, writable: true });
    syncRuntimeMedia({ clips: [clip], timeSeconds: 2, playing: true, playbackRate: 1 });
    expect(clip.el.pause).toHaveBeenCalled();
  });

  it("does not restart a non-loop clip that has naturally ended before the clip's end time", () => {
    // Reproduces: bg-music WAV is 60s but data-duration="68.6" (composition duration).
    // At t=62 the file has ended; without this guard the runtime calls el.play() every
    // rAF tick, resetting currentTime to 0 and causing audible stutter for 8.6s.
    const clip = createMockClip({ start: 0, end: 68.6, loop: false });
    Object.defineProperty(clip.el, "paused", { value: true, writable: true });
    Object.defineProperty(clip.el, "ended", { value: true, writable: true, configurable: true });
    syncRuntimeMedia({ clips: [clip], timeSeconds: 62, playing: true, playbackRate: 1 });
    expect(clip.el.play).not.toHaveBeenCalled();
  });

  it("seeks a non-looping video to its final frame when entering an authored hold tail", () => {
    const clip = createMockClip({ start: 0, end: 5, duration: 5, sourceDuration: 0.25 });
    syncRuntimeMedia({ clips: [clip], timeSeconds: 4, playing: true, playbackRate: 1 });
    expect(clip.el.currentTime).toBe(0.25);
    expect(clip.el.play).not.toHaveBeenCalled();
  });

  it("holds a video that runs to the composition end on its last frame at the terminal time", () => {
    const clip = createMockClip({ start: 2.5, end: 5, duration: 2.5, sourceDuration: 10 });
    const seek = {
      clips: [clip],
      playing: false,
      playbackRate: 1,
      getCompositionDuration: () => 5,
    };
    syncRuntimeMedia({ ...seek, timeSeconds: 5 });
    expect(clip.el.currentTime).toBe(2.5);
    expect(clip.el.play).not.toHaveBeenCalled();
  });

  it("holds a video ending on a float sum at the composition end on its last frame", () => {
    const clip = createMockClip({
      start: 19.8,
      end: 19.8 + 6.4,
      duration: 6.4,
      sourceDuration: 10,
    });
    syncRuntimeMedia({
      clips: [clip],
      timeSeconds: 26.2,
      playing: false,
      playbackRate: 1,
      getCompositionDuration: () => 26.2,
    });
    expect(clip.el.currentTime).toBeCloseTo(6.4, 9);
  });

  it("holds a speed-ramped video that runs to the composition end at the source time of its own end", () => {
    const lane: HfAutomationLane = {
      target: "rate",
      points: [
        { t: 0, v: 1 },
        { t: 5, v: 2 },
      ],
    };
    const clip = createMockClip({ start: 0, end: 5, duration: 5, sourceDuration: 100, rate: lane });
    syncRuntimeMedia({
      clips: [clip],
      timeSeconds: 6,
      playing: false,
      playbackRate: 1,
      getCompositionDuration: () => 5,
    });
    expect(clip.el.currentTime).toBeCloseTo(sourceTimeAt(lane, 5), 5);
    expect(clip.el.currentTime).toBeLessThan(sourceTimeAt(lane, 6));
    expect(clip.el.play).not.toHaveBeenCalled();
  });

  it("clamps a terminal video hold to a shorter source tail", () => {
    const clip = createMockClip({ start: 0, end: 5, duration: 5, sourceDuration: 0.25 });
    syncRuntimeMedia({
      clips: [clip],
      timeSeconds: 5,
      playing: true,
      playbackRate: 1,
      getCompositionDuration: () => 5,
    });
    expect(clip.el.currentTime).toBe(0.25);
    expect(clip.el.play).not.toHaveBeenCalled();
  });

  it("does not hold a video that ended before the composition did", () => {
    const clip = createMockClip({ start: 0, end: 2.5, duration: 2.5, sourceDuration: 10 });
    syncRuntimeMedia({
      clips: [clip],
      timeSeconds: 5,
      playing: false,
      playbackRate: 1,
      getCompositionDuration: () => 5,
    });
    expect(clip.el.currentTime).toBe(0);
  });

  it("seeks an ended video backward into its playable source", () => {
    const clip = createMockClip({ start: 0, end: 5, duration: 5, sourceDuration: 1 });
    Object.defineProperty(clip.el, "currentTime", { value: 1, writable: true, configurable: true });
    Object.defineProperty(clip.el, "ended", { value: true, writable: true, configurable: true });
    syncRuntimeMedia({ clips: [clip], timeSeconds: 0.9, playing: true, playbackRate: 1 });
    expect(clip.el.currentTime).toBe(0.9);
    expect(clip.el.play).toHaveBeenCalledTimes(1);
  });

  it("seeks an ended audio clip backward into its playable source", () => {
    const clip = createMockClip(
      { start: 3.12, end: 3.67, duration: 0.55, sourceDuration: 0.55 },
      "audio",
    );
    Object.defineProperty(clip.el, "currentTime", {
      value: 0.55,
      writable: true,
      configurable: true,
    });
    Object.defineProperty(clip.el, "ended", { value: true, writable: true, configurable: true });

    syncRuntimeMedia({ clips: [clip], timeSeconds: 3.12, playing: true, playbackRate: 1 });

    expect(clip.el.currentTime).toBe(0);
    expect(clip.el.play).toHaveBeenCalledTimes(1);
  });

  it("does not restart ended audio past its source duration", () => {
    const clip = createMockClip(
      { start: 3.12, end: 4.12, duration: 1, sourceDuration: 0.55 },
      "audio",
    );
    Object.defineProperty(clip.el, "currentTime", {
      value: 0.55,
      writable: true,
      configurable: true,
    });
    Object.defineProperty(clip.el, "ended", { value: true, writable: true, configurable: true });

    syncRuntimeMedia({ clips: [clip], timeSeconds: 3.8, playing: true, playbackRate: 1 });

    expect(clip.el.currentTime).toBe(0.55);
    expect(clip.el.play).not.toHaveBeenCalled();
  });

  it("does not replay an audio tail when native EOF leads the runtime clock", () => {
    const clip = createMockClip(
      { start: 3.12, end: 3.67, duration: 0.55, sourceDuration: 0.55 },
      "audio",
    );
    Object.defineProperty(clip.el, "paused", { value: false, writable: true });
    Object.defineProperty(clip.el, "currentTime", { value: 0.53, writable: true });
    syncRuntimeMedia({ clips: [clip], timeSeconds: 3.65, playing: true, playbackRate: 1 });

    clip.el.currentTime = 0.55;
    Object.defineProperty(clip.el, "paused", { value: true, writable: true });
    Object.defineProperty(clip.el, "ended", { value: true, writable: true, configurable: true });
    syncRuntimeMedia({
      clips: [clip],
      timeSeconds: 3.66,
      playing: true,
      playbackRate: 1,
      forceSync: true,
    });
    syncRuntimeMedia({
      clips: [clip],
      timeSeconds: 3.665,
      playing: true,
      playbackRate: 1,
      forceSync: true,
    });

    expect(clip.el.currentTime).toBe(0.55);
    expect(clip.el.play).not.toHaveBeenCalled();
  });

  it("rewinds ended audio after a backward seek within the active clip", () => {
    const clip = createMockClip(
      { start: 3.12, end: 3.67, duration: 0.55, sourceDuration: 0.55 },
      "audio",
    );
    Object.defineProperty(clip.el, "currentTime", { value: 0.5, writable: true });
    syncRuntimeMedia({ clips: [clip], timeSeconds: 3.62, playing: true, playbackRate: 1 });
    vi.mocked(clip.el.play).mockClear();

    clip.el.currentTime = 0.55;
    Object.defineProperty(clip.el, "paused", { value: true, writable: true });
    Object.defineProperty(clip.el, "ended", { value: true, writable: true, configurable: true });
    syncRuntimeMedia({
      clips: [clip],
      timeSeconds: 3.12,
      playing: true,
      playbackRate: 1,
      forceSync: true,
    });

    expect(clip.el.currentTime).toBe(0);
    expect(clip.el.play).toHaveBeenCalledTimes(1);
  });

  it("does restart a loop clip that has naturally ended while still within its active window", () => {
    const clip = createMockClip({ start: 0, end: 68.6, loop: true, sourceDuration: 60 });
    Object.defineProperty(clip.el, "paused", { value: true, writable: true });
    Object.defineProperty(clip.el, "ended", { value: true, writable: true, configurable: true });
    syncRuntimeMedia({ clips: [clip], timeSeconds: 62, playing: true, playbackRate: 1 });
    expect(clip.el.play).toHaveBeenCalled();
  });

  it("resumes a previously-ended non-loop clip after a backward seek resets el.ended", () => {
    // el.ended resets to false when the browser processes a seek (per WHATWG spec).
    // This test pins the contract: silent at t=62 (ended), playable again at t=30 (seeked back).
    const clip = createMockClip({ start: 0, end: 68.6, loop: false });
    Object.defineProperty(clip.el, "paused", { value: true, writable: true });
    Object.defineProperty(clip.el, "ended", { value: true, writable: true, configurable: true });
    syncRuntimeMedia({ clips: [clip], timeSeconds: 62, playing: true, playbackRate: 1 });
    expect(clip.el.play).not.toHaveBeenCalled();
    // Simulate backward seek: browser resets ended to false before committing new currentTime
    Object.defineProperty(clip.el, "ended", { value: false, writable: true, configurable: true });
    syncRuntimeMedia({ clips: [clip], timeSeconds: 30, playing: true, playbackRate: 1 });
    expect(clip.el.play).toHaveBeenCalledTimes(1);
  });

  it("sets volume when clip has volume", () => {
    const clip = createMockClip({ start: 0, end: 10, volume: 0.7 });
    syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: false, playbackRate: 1 });
    expect(clip.el.volume).toBe(0.7);
  });

  it("applies userVolume as a multiplier on clip volume", () => {
    const clip = createMockClip({ start: 0, end: 10, volume: 0.8 });
    syncRuntimeMedia({
      clips: [clip],
      timeSeconds: 5,
      playing: false,
      playbackRate: 1,
      userVolume: 0.5,
    });
    expect(clip.el.volume).toBeCloseTo(0.4);
  });

  it("applies userVolume to clips without explicit volume (default 1)", () => {
    const clip = createMockClip({ start: 0, end: 10 });
    syncRuntimeMedia({
      clips: [clip],
      timeSeconds: 5,
      playing: false,
      playbackRate: 1,
      userVolume: 0.3,
    });
    expect(clip.el.volume).toBeCloseTo(0.3);
  });

  it("preserves authored volume changes made between sync ticks", () => {
    const clip = createMockClip({ start: 0, end: 10, volume: 0 });
    syncRuntimeMedia({ clips: [clip], timeSeconds: 0, playing: false, playbackRate: 1 });
    expect(clip.el.volume).toBe(0);

    clip.el.volume = 0.5;
    syncRuntimeMedia({ clips: [clip], timeSeconds: 0.5, playing: false, playbackRate: 1 });

    expect(clip.el.volume).toBe(0.5);
  });

  it("writes volume and muted only when they change, not on every tick", () => {
    const clip = createMockClip({ start: 0, end: 10, volume: 0.7 });
    const writes = { volume: 0, muted: 0 };
    for (const prop of ["volume", "muted"] as const) {
      const native = Object.getOwnPropertyDescriptor(HTMLMediaElement.prototype, prop)!;
      Object.defineProperty(clip.el, prop, {
        configurable: true,
        get() {
          return native.get!.call(this);
        },
        set(value) {
          writes[prop]++;
          native.set!.call(this, value);
        },
      });
    }
    for (const timeSeconds of [1, 1.04, 1.08, 1.12]) {
      syncRuntimeMedia({
        clips: [clip],
        timeSeconds,
        playing: false,
        playbackRate: 1,
        outputMuted: true,
      });
    }
    expect(clip.el.volume).toBe(0.7);
    expect(clip.el.muted).toBe(true);
    expect(writes).toEqual({ volume: 0, muted: 1 });

    clip.el.muted = false;
    syncRuntimeMedia({
      clips: [clip],
      timeSeconds: 1.16,
      playing: false,
      playbackRate: 1,
      outputMuted: true,
    });
    expect(clip.el.muted).toBe(true);
  });

  it("reports effective and author-only volume to external audio transports", () => {
    const clip = createMockClip({ start: 0, end: 10, volume: 0 });
    const onElementVolume = vi.fn();
    syncRuntimeMedia({
      clips: [clip],
      timeSeconds: 0,
      playing: false,
      playbackRate: 1,
      onElementVolume,
    });
    clip.el.volume = 0.75;
    syncRuntimeMedia({
      clips: [clip],
      timeSeconds: 1,
      playing: false,
      playbackRate: 1,
      userVolume: 0.5,
      onElementVolume,
    });

    expect(clip.el.volume).toBeCloseTo(0.375);
    expect(onElementVolume).toHaveBeenLastCalledWith(clip.el, 0.375, 0.75, 1);
  });

  it("preserves author volume through user zero then restore", () => {
    const clip = createMockClip({ start: 0, end: 10, volume: 0.8 });
    const onElementVolume = vi.fn();
    syncRuntimeMedia({
      clips: [clip],
      timeSeconds: 1,
      playing: false,
      playbackRate: 1,
      userVolume: 0,
      onElementVolume,
    });
    syncRuntimeMedia({
      clips: [clip],
      timeSeconds: 2,
      playing: false,
      playbackRate: 1,
      userVolume: 0.5,
      onElementVolume,
    });

    expect(onElementVolume.mock.calls.at(-2)).toEqual([clip.el, 0, 0.8, 1]);
    expect(onElementVolume.mock.calls.at(-1)).toEqual([clip.el, 0.4, 0.8, 1]);
  });

  it("does not mistake routed upstream unity for an authored volume change", () => {
    const clip = createMockClip({ start: 0, end: 10, volume: 0.8 });
    clip.el.volume = 1;
    const onElementVolume = vi.fn();
    syncRuntimeMedia({
      clips: [clip],
      timeSeconds: 1,
      playing: true,
      playbackRate: 1,
      userVolume: 0.5,
      isWebAudioRouted: (el) => el === clip.el,
      onElementVolume,
    });

    expect(onElementVolume).toHaveBeenLastCalledWith(clip.el, 0.5, 1, 0.8);
  });

  describe("per-element mute (Web Audio ownership)", () => {
    it("mutes a clip whose element the transport owns", () => {
      const clip = createMockClip({ start: 0, end: 10 });
      syncRuntimeMedia({
        clips: [clip],
        timeSeconds: 5,
        playing: true,
        playbackRate: 1,
        isWebAudioOwned: (el) => el === clip.el,
      });
      expect(clip.el.muted).toBe(true);
    });

    it("leaves an un-owned clip audible while another track is on Web Audio", () => {
      // Regression: the un-owned track used to be muted by the global gate the
      // moment any source was active → silent while the owned track played.
      const owned = createMockClip({ start: 0, end: 10 });
      const unowned = createMockClip({ start: 0, end: 10 });
      syncRuntimeMedia({
        clips: [owned, unowned],
        timeSeconds: 5,
        playing: true,
        playbackRate: 1,
        isWebAudioOwned: (el) => el === owned.el,
      });
      expect(owned.el.muted).toBe(true);
      expect(unowned.el.muted).toBe(false);
    });

    it("force-mutes every element when outputMuted (parent proxy owns all audio)", () => {
      const clip = createMockClip({ start: 0, end: 10 });
      syncRuntimeMedia({
        clips: [clip],
        timeSeconds: 5,
        playing: true,
        playbackRate: 1,
        outputMuted: true,
        isWebAudioOwned: () => false,
      });
      expect(clip.el.muted).toBe(true);
    });

    it("force-mutes every element when userMuted", () => {
      const clip = createMockClip({ start: 0, end: 10 });
      syncRuntimeMedia({
        clips: [clip],
        timeSeconds: 5,
        playing: true,
        playbackRate: 1,
        userMuted: true,
        isWebAudioOwned: () => false,
      });
      expect(clip.el.muted).toBe(true);
    });

    it("mutes only once the transport takes the element over", () => {
      const clip = createMockClip({ start: 0, end: 10 });
      let owned = false;
      syncRuntimeMedia({
        clips: [clip],
        timeSeconds: 5,
        playing: true,
        playbackRate: 1,
        isWebAudioOwned: () => owned,
      });
      expect(clip.el.muted).toBe(false); // decoding — audible via HTMLMedia fallback
      owned = true;
      syncRuntimeMedia({
        clips: [clip],
        timeSeconds: 5.1,
        playing: true,
        playbackRate: 1,
        isWebAudioOwned: () => owned,
      });
      expect(clip.el.muted).toBe(true);
    });
  });

  it("hard-syncs on the first active tick (sub-composition activation, mediaStart offsets)", () => {
    const clip = createMockClip({ start: 0, end: 10, mediaStart: 0 });
    Object.defineProperty(clip.el, "currentTime", { value: 0, writable: true });
    syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: false, playbackRate: 1 });
    expect(clip.el.currentTime).toBe(5);
  });

  it("does not seek on sub-0.5s drift in steady-state — avoids pause/play hiccups", () => {
    const clip = createMockClip({ start: 0, end: 10, mediaStart: 0 });
    Object.defineProperty(clip.el, "currentTime", { value: 5.4, writable: true });
    // Establish a baseline offset of 0 with a steady-state tick first.
    syncRuntimeMedia({ clips: [clip], timeSeconds: 5.4, playing: true, playbackRate: 1 });
    // Now a small transient drift: timeline backs up 0.4s (typical of
    // pause/play ordering). Below the 0.5s threshold — don't seek.
    syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: true, playbackRate: 1 });
    expect(clip.el.currentTime).toBe(5.4);
  });

  it("does not force audio forward while it's still buffering (gradual drift growth)", () => {
    // Cold-play: audio stuck buffering at 0, timeline advances ~16ms per tick.
    // The offset grows gradually; no single tick jumps by 0.5s, so the
    // drift-correction seek must NOT fire. Without this guard the runtime
    // would force-seek audio forward and the user would miss the opening
    // words of the narration.
    const clip = createMockClip({ start: 0, end: 10, mediaStart: 0 });
    Object.defineProperty(clip.el, "currentTime", { value: 0, writable: true });
    // First tick: timeline at 0, audio at 0, no drift — first-tick hard-sync is a no-op.
    syncRuntimeMedia({ clips: [clip], timeSeconds: 0, playing: true, playbackRate: 1 });
    // Subsequent ticks: timeline advances, audio stays buffering at 0.
    for (let t = 0.016; t < 0.7; t += 0.016) {
      syncRuntimeMedia({ clips: [clip], timeSeconds: t, playing: true, playbackRate: 1 });
    }
    expect(clip.el.currentTime).toBe(0);
  });

  it("re-syncs on a scrub — offset jumps in one tick", () => {
    const clip = createMockClip({ start: 0, end: 20, mediaStart: 0 });
    Object.defineProperty(clip.el, "currentTime", { value: 2, writable: true });
    // Steady-state.
    syncRuntimeMedia({ clips: [clip], timeSeconds: 2, playing: true, playbackRate: 1 });
    syncRuntimeMedia({ clips: [clip], timeSeconds: 2.02, playing: true, playbackRate: 1 });
    // User scrubs forward to 15 — offset jumps from ~0 to ~13 in one tick.
    syncRuntimeMedia({ clips: [clip], timeSeconds: 15, playing: true, playbackRate: 1 });
    expect(clip.el.currentTime).toBe(15);
  });

  it("catastrophic-drift safety valve eventually resyncs a stuck element", () => {
    const clip = createMockClip({ start: 0, end: 100, mediaStart: 0 });
    Object.defineProperty(clip.el, "currentTime", { value: 0, writable: true });
    // Establish baseline at t=0.
    syncRuntimeMedia({ clips: [clip], timeSeconds: 0, playing: true, playbackRate: 1 });
    // Gradually advance timeline by 0.3s per tick without audio moving.
    // Each tick's offset delta is 0.3 (< 0.5s jump threshold), so only the
    // >3s catastrophic-drift safety valve can trigger the resync.
    for (let t = 0.3; t <= 4; t += 0.3) {
      syncRuntimeMedia({ clips: [clip], timeSeconds: t, playing: true, playbackRate: 1 });
    }
    expect(clip.el.currentTime).toBeGreaterThan(3);
  });

  it("clears offset baseline when clip deactivates — re-entry hard-syncs", () => {
    const clip = createMockClip({ start: 0, end: 5, mediaStart: 0 });
    Object.defineProperty(clip.el, "currentTime", { value: 0, writable: true });
    // Active pass: establish baseline at t=2.
    syncRuntimeMedia({ clips: [clip], timeSeconds: 2, playing: true, playbackRate: 1 });
    // Deactivate: timeline moves past the clip window.
    syncRuntimeMedia({ clips: [clip], timeSeconds: 6, playing: true, playbackRate: 1 });
    // Re-activate at t=3 — first-tick hard-sync should fire despite having
    // a previous baseline, because the clip was inactive in between.
    Object.defineProperty(clip.el, "currentTime", { value: 0, writable: true });
    syncRuntimeMedia({ clips: [clip], timeSeconds: 3, playing: true, playbackRate: 1 });
    expect(clip.el.currentTime).toBe(3);
  });

  it("rewinds stale short audio on its first tick after re-entry", () => {
    const clip = createMockClip(
      { start: 3.12, end: 3.67, duration: 0.55, sourceDuration: 0.55 },
      "audio",
    );
    Object.defineProperty(clip.el, "currentTime", { value: 0.49, writable: true });

    syncRuntimeMedia({ clips: [clip], timeSeconds: 3.12, playing: true, playbackRate: 1 });

    expect(clip.el.currentTime).toBe(0);
  });

  it("does not force cold audio forward on its first active tick", () => {
    const clip = createMockClip(
      { start: 3.12, end: 3.67, duration: 0.55, sourceDuration: 0.55 },
      "audio",
    );
    Object.defineProperty(clip.el, "currentTime", { value: 0, writable: true });

    syncRuntimeMedia({ clips: [clip], timeSeconds: 3.61, playing: true, playbackRate: 1 });

    expect(clip.el.currentTime).toBe(0);
  });

  it("sets per-element playbackRate × global rate", () => {
    const clip = createMockClip({ start: 0, end: 10, playbackRate: 0.5 });
    syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: true, playbackRate: 2 });
    expect(clip.el.playbackRate).toBe(1); // 0.5 × 2 = 1
  });

  it("computes relTime with per-element playback rate", () => {
    const clip = createMockClip({ start: 0, end: 20, playbackRate: 0.5, mediaStart: 0 });
    Object.defineProperty(clip.el, "currentTime", { value: 0, writable: true });
    syncRuntimeMedia({ clips: [clip], timeSeconds: 10, playing: false, playbackRate: 1 });
    // At timeline t=10, with 0.5x rate: relTime = 10 * 0.5 + 0 = 5s into the media
    expect(clip.el.currentTime).toBe(5);
  });

  it("wraps relTime when loop is true and media has ended", () => {
    // 3s source at 1x, looped over 10s clip
    const clip = createMockClip({
      start: 0,
      end: 10,
      mediaStart: 0,
      loop: true,
      sourceDuration: 3,
    });
    Object.defineProperty(clip.el, "currentTime", { value: 0, writable: true });
    // At t=7, relTime = 7, wraps to 7 % 3 = 1
    syncRuntimeMedia({ clips: [clip], timeSeconds: 7, playing: false, playbackRate: 1 });
    expect(clip.el.currentTime).toBe(1);
  });

  it("wraps loop with mediaStart offset", () => {
    // Source is 10s, mediaStart=5, so loop length is 5s (5-10)
    const clip = createMockClip({
      start: 0,
      end: 15,
      mediaStart: 5,
      loop: true,
      sourceDuration: 10,
    });
    Object.defineProperty(clip.el, "currentTime", { value: 0, writable: true });
    // At t=7: relTime = 7*1 + 5 = 12, wraps: 5 + ((12-5) % 5) = 5 + (7%5) = 5+2 = 7
    syncRuntimeMedia({ clips: [clip], timeSeconds: 7, playing: false, playbackRate: 1 });
    expect(clip.el.currentTime).toBe(7);
  });

  it("holds the final frame instead of looping a non-looping video", () => {
    const clip = createMockClip({
      start: 0,
      end: 10,
      mediaStart: 0,
      loop: false,
      sourceDuration: 3,
    });
    Object.defineProperty(clip.el, "currentTime", { value: 0, writable: true });
    // At t=7 the source is exhausted, so the final frame remains visible.
    syncRuntimeMedia({ clips: [clip], timeSeconds: 7, playing: false, playbackRate: 1 });
    expect(clip.el.currentTime).toBe(3);
  });

  it("asserts muted=true every tick while outputMuted is set", () => {
    // Parent ownership has taken over audible playback via parent-frame
    // proxies. The iframe runtime must silence every active media element
    // per tick so new sub-composition media inherits the mute as soon as
    // it appears in the DOM — otherwise a late <audio> insertion would
    // briefly play audibly and double-voice the viewer.
    const clip = createMockClip({ start: 0, end: 10, volume: 1 });
    Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
    Object.defineProperty(clip.el, "muted", { value: false, writable: true });
    syncRuntimeMedia({
      clips: [clip],
      timeSeconds: 5,
      playing: true,
      playbackRate: 1,
      outputMuted: true,
    });
    expect(clip.el.muted).toBe(true);
    // A second tick re-asserts — captures the sticky behavior, since
    // the bridge handler only runs on flip transitions.
    Object.defineProperty(clip.el, "muted", { value: false, writable: true });
    syncRuntimeMedia({
      clips: [clip],
      timeSeconds: 5.02,
      playing: true,
      playbackRate: 1,
      outputMuted: true,
    });
    expect(clip.el.muted).toBe(true);
  });

  it("does not touch muted when outputMuted is absent", () => {
    // The un-mute decision belongs to author intent (`<audio muted>`) and
    // user preference (`onSetMuted`) — syncRuntimeMedia must not race them.
    const clip = createMockClip({ start: 0, end: 10 });
    Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
    Object.defineProperty(clip.el, "muted", { value: true, writable: true });
    syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: true, playbackRate: 1 });
    expect(clip.el.muted).toBe(true);
  });

  it("fires onAutoplayBlocked when play() rejects with NotAllowedError", async () => {
    const clip = createMockClip({ start: 0, end: 10 });
    Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
    const rejection = Object.assign(new Error("blocked"), { name: "NotAllowedError" });
    clip.el.play = vi.fn(() => Promise.reject(rejection));
    const onAutoplayBlocked = vi.fn();
    syncRuntimeMedia({
      clips: [clip],
      timeSeconds: 5,
      playing: true,
      playbackRate: 1,
      onAutoplayBlocked,
    });
    // The rejection is delivered on a microtask — flush it.
    await Promise.resolve();
    await Promise.resolve();
    expect(onAutoplayBlocked).toHaveBeenCalledTimes(1);
  });

  it("does not fire onAutoplayBlocked for non-autoplay rejections", async () => {
    const clip = createMockClip({ start: 0, end: 10 });
    Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
    const rejection = Object.assign(new Error("aborted"), { name: "AbortError" });
    clip.el.play = vi.fn(() => Promise.reject(rejection));
    const onAutoplayBlocked = vi.fn();
    syncRuntimeMedia({
      clips: [clip],
      timeSeconds: 5,
      playing: true,
      playbackRate: 1,
      onAutoplayBlocked,
    });
    await Promise.resolve();
    await Promise.resolve();
    expect(onAutoplayBlocked).not.toHaveBeenCalled();
  });

  it("asserts muted=true every tick while userMuted is set", () => {
    // Mirror of the `outputMuted` test — user preference must be sticky
    // too. A sub-composition that activates after the user mutes should
    // inherit the silence, not briefly play at author volume before the
    // next bridge message lands.
    const clip = createMockClip({ start: 0, end: 10, volume: 1 });
    Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
    Object.defineProperty(clip.el, "muted", { value: false, writable: true });
    syncRuntimeMedia({
      clips: [clip],
      timeSeconds: 5,
      playing: true,
      playbackRate: 1,
      userMuted: true,
    });
    expect(clip.el.muted).toBe(true);
  });

  it("fires onAutoplayBlocked for every rejected play (caller owns the latch)", async () => {
    // media.ts is intentionally memoryless — each NotAllowedError rejection
    // invokes the callback. The init.ts caller wraps with
    // `mediaAutoplayBlockedPosted` so the outbound message is posted at most
    // once per session. This test pins down the contract (fires always) so
    // a future refactor can't quietly add deduplication here and break the
    // caller's latching logic.
    const clip = createMockClip({ start: 0, end: 10 });
    Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
    const rejection = Object.assign(new Error("blocked"), { name: "NotAllowedError" });
    clip.el.play = vi.fn(() => Promise.reject(rejection));
    const onAutoplayBlocked = vi.fn();

    // Simulate two ticks — between them `playRequested` clears so play() runs
    // again and rejects again.
    syncRuntimeMedia({
      clips: [clip],
      timeSeconds: 5,
      playing: true,
      playbackRate: 1,
      onAutoplayBlocked,
    });
    await Promise.resolve();
    await Promise.resolve();
    syncRuntimeMedia({
      clips: [clip],
      timeSeconds: 5.05,
      playing: true,
      playbackRate: 1,
      onAutoplayBlocked,
    });
    await Promise.resolve();
    await Promise.resolve();

    // No latch inside media.ts — two rejections, two callback invocations.
    // The caller's latch is what prevents a second outbound message.
    expect(onAutoplayBlocked).toHaveBeenCalledTimes(2);
  });

  it("caller-side latch pattern posts once across many rejections", async () => {
    // Mirrors what init.ts does: the onAutoplayBlocked wrapper checks and
    // sets a boolean flag so the outbound post fires exactly once even if
    // the raw callback fires many times. Regression guard for the latch
    // wiring in the init.ts handler.
    const clip = createMockClip({ start: 0, end: 10 });
    Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
    const rejection = Object.assign(new Error("blocked"), { name: "NotAllowedError" });
    clip.el.play = vi.fn(() => Promise.reject(rejection));

    let posted = 0;
    const state = { latched: false };
    const wrapped = () => {
      if (state.latched) return;
      state.latched = true;
      posted += 1;
    };

    for (let i = 0; i < 5; i++) {
      syncRuntimeMedia({
        clips: [clip],
        timeSeconds: 5 + i * 0.05,
        playing: true,
        playbackRate: 1,
        onAutoplayBlocked: wrapped,
      });
      await Promise.resolve();
      await Promise.resolve();
    }

    expect(posted).toBe(1);
  });

  it("corrects stable sub-0.5s drift after consecutive over-threshold ticks", () => {
    const clip = createMockClip({ start: 0, end: 10, mediaStart: 0 });
    Object.defineProperty(clip.el, "currentTime", { value: 5.4, writable: true });
    syncRuntimeMedia({ clips: [clip], timeSeconds: 5.4, playing: true, playbackRate: 1 });
    syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: true, playbackRate: 1 });
    expect(clip.el.currentTime).toBe(5.4);
    syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: true, playbackRate: 1 });
    expect(clip.el.currentTime).toBe(5.4);
    syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: true, playbackRate: 1 });
    expect(clip.el.currentTime).toBe(5);
  });

  it("does not force audio forward while it's still buffering (gradual drift growth)", () => {
    const clip = createMockClip({ start: 0, end: 10, mediaStart: 0 });
    Object.defineProperty(clip.el, "currentTime", { value: 0, writable: true });
    syncRuntimeMedia({ clips: [clip], timeSeconds: 0, playing: true, playbackRate: 1 });
    for (let t = 0.016; t < 0.7; t += 0.016) {
      syncRuntimeMedia({ clips: [clip], timeSeconds: t, playing: true, playbackRate: 1 });
    }
    expect(clip.el.currentTime).toBe(0);
  });

  it("forceSync corrects any drift above 20ms immediately", () => {
    const clip = createMockClip({ start: 0, end: 10, mediaStart: 0 });
    Object.defineProperty(clip.el, "currentTime", { value: 5.1, writable: true });
    syncRuntimeMedia({ clips: [clip], timeSeconds: 5.1, playing: true, playbackRate: 1 });
    syncRuntimeMedia({
      clips: [clip],
      timeSeconds: 5,
      playing: true,
      playbackRate: 1,
      forceSync: true,
    });
    expect(clip.el.currentTime).toBe(5);
  });

  describe("playing video drift", () => {
    function playingVideoAt(currentTime: number, playbackRate = 1) {
      const clip = createMockClip({ start: 0, end: 20, duration: 20 });
      Object.defineProperty(clip.el, "paused", { value: false, writable: true });
      Object.defineProperty(clip.el, "currentTime", { value: currentTime, writable: true });
      clip.el.playbackRate = playbackRate;
      return clip;
    }
    const tick = (clip: RuntimeMediaClip, timeSeconds: number, playbackRate = 1) =>
      syncRuntimeMedia({
        clips: [clip],
        timeSeconds,
        playing: true,
        playbackRate,
        getCompositionDuration: () => 20,
      });

    it("runs a video lagging past the sync tolerance 3% fast instead of seeking it", () => {
      const clip = playingVideoAt(4.908);
      tick(clip, 5);
      tick(clip, 5);
      expect(clip.el.playbackRate).toBeCloseTo(1.03, 9);
      expect(clip.el.currentTime).toBe(4.908);
    });

    it("runs a video that is ahead 3% slow", () => {
      const clip = playingVideoAt(5.3);
      tick(clip, 5);
      tick(clip, 5);
      expect(clip.el.playbackRate).toBeCloseTo(0.97, 9);
    });

    it("keeps steering until the video is nearly back, then returns to the authored rate", () => {
      const clip = playingVideoAt(4.9);
      tick(clip, 5);
      tick(clip, 5);
      clip.el.currentTime = 4.98;
      tick(clip, 5);
      expect(clip.el.playbackRate).toBeCloseTo(1.03, 9);
      clip.el.currentTime = 4.995;
      tick(clip, 5);
      expect(clip.el.playbackRate).toBe(1);
    });

    it("keeps steering through a speed ramp, whose base rate moves every tick", () => {
      const clip = playingVideoAt(4.9);
      tick(clip, 5, 1);
      tick(clip, 5, 1);
      clip.el.currentTime = 4.98;
      tick(clip, 5, 1.2);
      expect(clip.el.playbackRate).toBeCloseTo(1.2 * 1.03, 9);
    });

    it("plays a hard-synced video at its authored rate on the tick it is seeked", () => {
      const clip = playingVideoAt(4.9);
      tick(clip, 5);
      tick(clip, 5);
      expect(clip.el.playbackRate).toBeCloseTo(1.03, 9);
      tick(clip, 9); // a jump past the hard-sync threshold
      expect(clip.el.currentTime).toBe(9);
      expect(clip.el.playbackRate).toBe(1);
    });

    it("does not start steering inside the sync tolerance", () => {
      const clip = playingVideoAt(4.97, 2);
      tick(clip, 5, 2);
      tick(clip, 5, 2);
      expect(clip.el.playbackRate).toBe(2);
    });

    it("returns a steered video to its authored rate when the transport pauses", () => {
      const clip = playingVideoAt(4.9);
      tick(clip, 5);
      tick(clip, 5);
      syncRuntimeMedia({
        clips: [clip],
        timeSeconds: 5,
        playing: false,
        playbackRate: 1,
        getCompositionDuration: () => 20,
      });
      clip.el.currentTime = 4.98; // inside the tolerance: must not resume steering
      tick(clip, 5);
      expect(clip.el.playbackRate).toBe(1);
    });

    it("forgets the steering when the element's sync state is evicted", () => {
      const clip = playingVideoAt(4.9);
      tick(clip, 5);
      tick(clip, 5);
      evictMediaSyncState(clip.el);
      expect(hasMediaSyncStateForTest(clip.el)).toBe(false);
    });

    it("does not rewrite a steered rate that reads back at lower precision", () => {
      const clip = playingVideoAt(4.9);
      let stored = 1;
      let writes = 0;
      Object.defineProperty(clip.el, "playbackRate", {
        configurable: true,
        get: () => stored,
        set: (v: number) => {
          writes += 1;
          stored = Math.fround(v);
        },
      });
      for (let i = 0; i < 5; i++) tick(clip, 5);
      expect(writes).toBe(1);
    });

    it("scales the steer with the transport rate", () => {
      const clip = playingVideoAt(4.908, 2);
      tick(clip, 5, 2);
      tick(clip, 5, 2);
      expect(clip.el.playbackRate).toBeCloseTo(2.06, 9);
    });
  });

  it.each([
    [60, 0.25],
    [10, 0.5],
  ])(
    "keeps a video slower than the browser can play on the playhead at %i fps, preview speed %f",
    (fps, speed) => {
      // A 0.1x clip at 0.25x or 0.5x preview speed is below Chromium's 1/16 rate floor.
      const clip = createMockClip({ start: 0, end: 30, duration: 30, playbackRate: 0.1 });
      const el = clip.el;
      let rate = speed;
      let paused = true;
      Object.defineProperty(el, "playbackRate", {
        configurable: true,
        get: () => rate,
        set: (v: number) => {
          if (v < 0.0625) throw new DOMException("unsupported rate", "NotSupportedError");
          rate = v;
        },
      });
      Object.defineProperty(el, "paused", { configurable: true, get: () => paused });
      el.play = vi.fn(() => ((paused = false), Promise.resolve()));
      el.pause = vi.fn(() => void (paused = true));
      const dt = 1 / fps;
      let timeline = 0;
      for (let i = 0; i < fps * 4; i++) {
        timeline += speed * dt;
        if (!paused) el.currentTime += rate * dt;
        syncRuntimeMedia({
          clips: [clip],
          timeSeconds: timeline,
          playing: true,
          playbackRate: speed,
        });
      }
      expect(Math.abs(el.currentTime - 0.1 * timeline)).toBeLessThan(0.05);
    },
  );

  // A seek while playing pauses and syncs in one pass, before the video element has paused.
  it("a seek that pauses mid-playback lands a lagging playing video on the new time", () => {
    const clip = createMockClip({ start: 3.85, end: 5.6, duration: 1.75 });
    Object.defineProperty(clip.el, "paused", { value: false, writable: true });
    Object.defineProperty(clip.el, "currentTime", { value: 0.031, writable: true });
    syncRuntimeMedia({ clips: [clip], timeSeconds: 4.109, playing: true, playbackRate: 1 });
    expect(clip.el.currentTime).toBe(0.031);

    syncRuntimeMedia({
      clips: [clip],
      timeSeconds: 4.4,
      playing: false,
      playbackRate: 1,
      forceSync: true,
    });
    expect(clip.el.currentTime).toBeCloseTo(0.55, 5);
    expect(clip.el.pause).toHaveBeenCalled();
  });

  it("mutes when either outputMuted OR userMuted is true (OR invariant)", () => {
    // Explicit validation of the combined-flag contract: setting one to
    // false while the other is true must keep the element muted.
    const clip = createMockClip({ start: 0, end: 10, volume: 1 });
    Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
    Object.defineProperty(clip.el, "muted", { value: false, writable: true });
    syncRuntimeMedia({
      clips: [clip],
      timeSeconds: 5,
      playing: true,
      playbackRate: 1,
      outputMuted: false,
      userMuted: true,
    });
    expect(clip.el.muted).toBe(true);
    Object.defineProperty(clip.el, "muted", { value: false, writable: true });
    syncRuntimeMedia({
      clips: [clip],
      timeSeconds: 5,
      playing: true,
      playbackRate: 1,
      outputMuted: true,
      userMuted: false,
    });
    expect(clip.el.muted).toBe(true);
  });
});