Skip to content

Write HTML. Render video. Built for agents.

36.8 KB
Raw Blame
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { initSandboxRuntimeModular } from "./init";
import { WebAudioTransport } from "./webAudioTransport";
import { STUDIO_MANUAL_EDIT_GESTURE_ATTR } from "../editing/draftMarkers";
import type { RuntimeTimelineLike } from "./types";

// The readiness gate's 8s timeout is a one-shot timer these transport tests must not count.
vi.mock("../compositionReadiness", async (importOriginal) => {
  const actual = await importOriginal<typeof import("../compositionReadiness")>();
  return {
    ...actual,
    settleCompositionReadiness: vi.fn(),
    settleFirstFrameCompositionReadiness: vi.fn(),
  };
});

/**
 * The transport parks itself when the editor is paused and settled. Everything
 * it used to discover by looking again on the next frame has to arrive by some
 * other route, and each of those routes gets a test here — one per row of the
 * enumeration in the PR body. A loop that stops noticing one of them is a
 * correctness regression no performance test would catch.
 */

const PARK_HEARTBEAT_MS = 80; // state.bridgeMaxPostIntervalMs

function createManualRaf() {
  let now = 0;
  let nextId = 0;
  const callbacks = new Map<number, FrameRequestCallback>();
  return {
    requestAnimationFrame: (callback: FrameRequestCallback) => {
      nextId += 1;
      callbacks.set(nextId, callback);
      return nextId;
    },
    cancelAnimationFrame: (id: number) => {
      callbacks.delete(id);
    },
    pending: () => callbacks.size,
    step: (milliseconds = 16) => {
      now += milliseconds;
      const batch = Array.from(callbacks.entries());
      callbacks.clear();
      for (const [, callback] of batch) callback(now);
    },
    now: () => now,
  };
}

function createMockTimeline(duration: number): RuntimeTimelineLike {
  const state = { time: 0, paused: true, duration };
  return {
    play: () => {
      state.paused = false;
    },
    pause: () => {
      state.paused = true;
    },
    seek: (time?: number) => {
      if (time !== undefined) state.time = time;
      return state.time;
    },
    totalTime: (time?: number) => {
      if (time !== undefined) state.time = time;
      return state.time;
    },
    time: () => state.time,
    duration: () => state.duration,
    add: () => {},
    paused: (value?: boolean) => {
      if (typeof value === "boolean") state.paused = value;
      return state.paused;
    },
    timeScale: () => {},
    set: () => {},
    getChildren: () => [],
  };
}

/** jsdom implements neither play() nor pause(), and `paused` is the only state the
 *  runtime reads. Returns a handle driving it the way a browser does, so a test can
 *  start the element and watch whether the transport stops it. */
function stubMediaPlayback(
  el: HTMLMediaElement,
  durationSeconds: number,
): { start: () => void; isPaused: () => boolean } {
  let paused = true;
  Object.defineProperty(el, "duration", { value: durationSeconds, configurable: true });
  Object.defineProperty(el, "paused", { configurable: true, get: () => paused });
  el.pause = () => {
    paused = true;
  };
  el.play = () => {
    paused = false;
    // A real browser fires this, and firing it is what makes the defect deterministic.
    el.dispatchEvent(new Event("play"));
    return Promise.resolve();
  };
  return { start: () => void el.play(), isPaused: () => paused };
}

/** MutationObserver records land in a microtask; nothing observes them sooner. */
const flushObservers = () => new Promise<void>((resolve) => queueMicrotask(() => resolve()));

describe("parked transport loop", () => {
  const originalRaf = window.requestAnimationFrame;
  const originalCancelRaf = window.cancelAnimationFrame;
  let raf: ReturnType<typeof createManualRaf>;
  let posted: Array<Record<string, unknown>>;

  const mount = (bodyHtml = "") => {
    document.body.innerHTML = `<div id="root" data-composition-id="main" data-root="true" data-start="0" data-duration="5">${bodyHtml}</div>`;
    window.__timelines = { main: createMockTimeline(5) };
  };

  /** Run frames until nothing asks for another one. */
  const settle = (maxFrames = 200): number => {
    let frames = 0;
    while (raf.pending() > 0 && frames < maxFrames) {
      raf.step();
      frames += 1;
    }
    return frames;
  };

  /** One frame at 120 Hz: the clock and the animation frame advance together. */
  const frame120Hz = () => {
    vi.advanceTimersByTime(8);
    raf.step(8);
  };

  /**
   * Park the transport AND drain init's own one-shot timers, several of which
   * post state and would otherwise be mistaken for a heartbeat. Leaves exactly
   * one timer pending: the parked heartbeat.
   */
  const quiesce = (): void => {
    settle();
    // Up to ~400 ms of 1 ms steps: the transport holds a deferred manifest
    // post for one cadence interval before it may park.
    for (let i = 0; i < 400; i += 1) {
      if (raf.pending() === 0 && vi.getTimerCount() <= 1) return;
      vi.advanceTimersByTime(1);
      settle();
    }
    throw new Error(
      `transport never quiesced (raf ${raf.pending()}, timers ${vi.getTimerCount()})`,
    );
  };

  beforeEach(() => {
    vi.useFakeTimers({
      toFake: ["setTimeout", "clearTimeout", "setInterval", "clearInterval", "Date"],
    });
    document.body.innerHTML = "";
    (globalThis as typeof globalThis & { CSS?: { escape?: (v: string) => string } }).CSS ??= {};
    globalThis.CSS.escape ??= (value: string) => value;
    raf = createManualRaf();
    window.requestAnimationFrame = raf.requestAnimationFrame as typeof window.requestAnimationFrame;
    window.cancelAnimationFrame = raf.cancelAnimationFrame as typeof window.cancelAnimationFrame;
    posted = [];
    vi.spyOn(window.parent, "postMessage").mockImplementation((message: unknown) => {
      posted.push(message as Record<string, unknown>);
    });
    window.__timelines = {};
  });

  afterEach(() => {
    window.__hfRuntimeTeardown?.();
    delete (document as { visibilityState?: DocumentVisibilityState }).visibilityState;
    document.body.innerHTML = "";
    window.__timelines = {} as Record<string, RuntimeTimelineLike>;
    delete window.__player;
    delete window.__playerReady;
    delete window.__HF_EXPORT_RENDER_SEEK_CONFIG;
    delete (window as { __hfLottie?: unknown }).__hfLottie;
    vi.restoreAllMocks();
    vi.useRealTimers();
    window.requestAnimationFrame = originalRaf;
    window.cancelAnimationFrame = originalCancelRaf;
  });

  it("stops asking for animation frames once paused and settled", () => {
    mount();
    initSandboxRuntimeModular();
    quiesce();
    expect(raf.pending()).toBe(0);
    // Exactly one thing still scheduled: the parked heartbeat.
    expect(vi.getTimerCount()).toBe(1);
  });

  it("reports the end in the state it posts when the film finishes", () => {
    let nowMs = 1000;
    vi.spyOn(performance, "now").mockImplementation(() => nowMs);
    document.body.innerHTML = `<div id="root" data-composition-id="main" data-root="true" data-start="0" data-duration="4.97"><div id="clip" data-start="0.48" data-duration="4.49"></div></div>`;
    window.__timelines = { main: createMockTimeline(4.97) };
    initSandboxRuntimeModular();
    quiesce();

    window.__player!.play();
    for (let step = 0; step < 120 && window.__player!.isPlaying(); step += 1) {
      nowMs += 50;
      raf.step(50);
    }

    const states = posted.filter((m) => m["type"] === "state");
    expect(states.at(-1)).toMatchObject({ isPlaying: false, ended: true, frame: 149 });
  });

  const setPlayRange = (startSeconds: number | null, endSeconds: number | null) =>
    window.dispatchEvent(
      new MessageEvent("message", {
        source: window.parent,
        data: {
          source: "hf-parent",
          type: "control",
          action: "set-play-range",
          startSeconds,
          endSeconds,
        },
      }),
    );
  const stateMessages = () => posted.filter((m) => m["type"] === "state");

  /** Mounts a 5 s film with clips a [0, 3) and b [3, 5), driven by a mocked clock. */
  const mountRangeFilm = () => {
    let nowMs = 1000;
    vi.spyOn(performance, "now").mockImplementation(() => nowMs);
    mount(
      `<div id="a" data-start="0" data-duration="3"></div><div id="b" data-start="3" data-duration="2"></div>`,
    );
    const timeline = window.__timelines!.main!;
    initSandboxRuntimeModular();
    quiesce();
    const frames: Array<{ time: number; b: string }> = [];
    const step = () => {
      nowMs += 7;
      raf.step(7);
      frames.push({ time: timeline.time(), b: document.getElementById("b")!.style.visibility });
    };
    const playOut = () => {
      window.__player!.play();
      for (let n = 0; n < 1000 && window.__player!.isPlaying(); n += 1) step();
    };
    return { timeline, frames, step, playOut };
  };

  it("stops on a play range's last frame, says it ended, and restarts at the range start only while it is set", () => {
    const { timeline, frames, playOut } = mountRangeFilm();

    setPlayRange(2, 3);
    window.__player!.seek(2);
    for (let wrap = 0; wrap < 3; wrap += 1) playOut();
    expect(stateMessages().at(-1)).toMatchObject({ isPlaying: false, ended: true, frame: 89 });
    expect(stateMessages().at(-1)?.["currentTime"]).toBeCloseTo(89 / 30, 9);
    expect(timeline.time()).toBeCloseTo(89 / 30, 9);
    expect(Math.max(...frames.map((f) => f.time))).toBeLessThan(3);
    expect(frames.every((f) => f.b === "hidden")).toBe(true);
    expect(document.getElementById("a")!.style.visibility).not.toBe("hidden");
    expect(window.__player!.getDuration()).toBe(5);

    const before = stateMessages().length;
    window.__player!.play();
    expect(stateMessages()[before]).toMatchObject({ isPlaying: true, frame: 60 });
    window.__player!.pause();

    setPlayRange(null, null);
    playOut();
    expect(stateMessages().at(-1)).toMatchObject({ isPlaying: false, ended: true, frame: 150 });
    const atFilmEnd = stateMessages().length;
    window.__player!.play();
    expect(stateMessages()[atFilmEnd]).toMatchObject({ isPlaying: true, frame: 0 });
  });

  it("jumps to the range start and keeps playing when a new range leaves the playhead outside", () => {
    const { step } = mountRangeFilm();
    setPlayRange(2, 3);
    window.__player!.seek(2.5);
    window.__player!.play();
    step();
    const before = stateMessages().length;

    setPlayRange(2, 2.4);

    const after = stateMessages().slice(before);
    expect(after.some((m) => m["ended"] === true)).toBe(false);
    expect(after.at(-1)).toMatchObject({ isPlaying: true, currentTime: 2 });
    expect(after.at(-1)?.["capabilities"]).toContain("play-range");
    expect(window.__player!.isPlaying()).toBe(true);
  });

  // The render stops at the root's declared length too; a longer animation is cut off.
  it.each([
    ["3 s, shorter than its animation", "3", 90],
    ["under a second", "0.2", 6],
    ["one 60 fps frame", String(1 / 60), 1],
  ])("stops a film declared %s at that length, and says so", (_label, declared, frame) => {
    const seconds = Number(declared);
    let nowMs = 1000;
    vi.spyOn(performance, "now").mockImplementation(() => nowMs);
    document.body.innerHTML = `<div id="root" data-composition-id="main" data-root="true" data-start="0" data-duration="${declared}"></div>`;
    window.__timelines = { main: createMockTimeline(5) };
    initSandboxRuntimeModular();
    quiesce();

    window.__player!.play();
    for (let step = 0; step < 400 && window.__player!.isPlaying(); step += 1) {
      nowMs += 10;
      raf.step(10);
    }

    const states = posted.filter((m) => m["type"] === "state");
    expect(states.at(-1)).toMatchObject({ isPlaying: false, ended: true, frame });
    expect(window.__player!.getDuration()).toBeCloseTo(seconds, 9);
    const timeline = posted.filter((m) => m["type"] === "timeline").at(-1);
    expect(timeline?.["durationSeconds"]).toBeCloseTo(seconds, 9);
  });

  it("keeps asking for animation frames while playing", () => {
    mount();
    initSandboxRuntimeModular();
    quiesce();
    window.__player!.play();
    // Every frame during playback re-arms: the loop must never park mid-play.
    for (let i = 0; i < 10; i += 1) {
      expect(raf.pending()).toBeGreaterThan(0);
      raf.step();
    }
    expect(raf.pending()).toBeGreaterThan(0);
  });

  /** The host's per-frame tick, as the player posts it on the runtime-bridge path. */
  const hostTick = () =>
    window.dispatchEvent(
      new MessageEvent("message", {
        source: window.parent,
        data: { source: "hf-parent", type: "control", action: "tick" },
      }),
    );

  const countSeeks = () => {
    const timeline = window.__timelines!["main"] as RuntimeTimelineLike;
    const seeks: number[] = [];
    const originalTotalTime = timeline.totalTime!.bind(timeline);
    timeline.totalTime = (time?: number, suppress?: boolean) => {
      if (time !== undefined) seeks.push(time);
      return originalTotalTime(time, suppress);
    };
    return seeks;
  };

  it("does not seek a timeline time already rendered by its frame loop", () => {
    vi.spyOn(performance, "now").mockReturnValue(1000);
    mount();
    initSandboxRuntimeModular();
    quiesce();
    window.__player!.play();
    frame120Hz();
    const seeks = countSeeks();

    frame120Hz();
    const perFrame = seeks.length;
    hostTick();

    expect(perFrame).toBeGreaterThan(0);
    expect(seeks.length).toBe(perFrame);
  });

  it("renders a newer host time after its own frame rendered an earlier time", () => {
    let nowMs = 1000;
    vi.spyOn(performance, "now").mockImplementation(() => nowMs);
    mount();
    initSandboxRuntimeModular();
    quiesce();
    window.__player!.play();
    nowMs = 1008;
    frame120Hz();
    const seeks = countSeeks();

    nowMs = 1024;
    hostTick();

    expect(seeks).toContain(0.024);
  });

  it("reapplies an explicit seek even when that timeline time was already rendered", () => {
    vi.spyOn(performance, "now").mockReturnValue(1000);
    mount();
    initSandboxRuntimeModular();
    quiesce();
    window.__player!.play();
    frame120Hz();
    const timeline = window.__timelines!["main"]!;
    timeline.totalTime!(1);
    const seeks = countSeeks();

    window.__player!.seek(0);

    expect(seeks).toContain(0);
    expect(timeline.totalTime!()).toBe(0);
  });

  it("refreshes the WebAudio snapshot on host ticks without iframe frames", () => {
    let audioTime = 0;
    mount();
    initSandboxRuntimeModular();
    quiesce();
    window.__player!.play();
    vi.spyOn(WebAudioTransport.prototype, "ownsClock").mockReturnValue(true);
    vi.spyOn(WebAudioTransport.prototype, "context", "get").mockReturnValue({} as AudioContext);
    vi.spyOn(WebAudioTransport.prototype, "getTime").mockImplementation(() => audioTime);
    frame120Hz();
    const seeks = countSeeks();

    audioTime = 0.024;
    hostTick();
    const firstSeekCount = seeks.length;
    hostTick();
    expect(seeks.length).toBe(firstSeekCount);
    audioTime = 0.048;
    hostTick();

    expect(seeks).toContain(0.024);
    expect(seeks.at(-1)).toBe(0.048);
    expect(window.__player!.getTime()).toBe(0.048);
  });

  it.each([false, true])(
    "renders the first host tick after play with prior playback %s",
    (resume) => {
      let nowMs = 1000;
      vi.spyOn(performance, "now").mockImplementation(() => nowMs);
      mount();
      initSandboxRuntimeModular();
      quiesce();
      if (resume) {
        window.__player!.play();
        frame120Hz();
        window.__player!.pause();
        quiesce();
      }
      window.__player!.play();
      const seeks = countSeeks();
      nowMs += 8;
      vi.advanceTimersByTime(8);
      hostTick();
      expect(seeks.length).toBeGreaterThan(0);
    },
  );

  it("advances on the host's ticks while its own animation frames are throttled", () => {
    let nowMs = 1000;
    vi.spyOn(performance, "now").mockImplementation(() => nowMs);
    mount();
    initSandboxRuntimeModular();
    quiesce();
    window.__player!.play();
    frame120Hz();
    hostTick();
    const seeks = countSeeks();

    for (let i = 0; i < 3; i += 1) {
      nowMs += 8;
      vi.advanceTimersByTime(8);
      hostTick();
    }

    expect(seeks).toContain(0.008);
    expect(seeks).toContain(0.016);
    expect(seeks.at(-1)).toBe(0.024);
  });

  it("posts the paused bridge heartbeat on its documented interval while parked", () => {
    mount();
    initSandboxRuntimeModular();
    quiesce();
    const before = posted.filter((m) => m["type"] === "state").length;
    for (let beat = 0; beat < 3; beat += 1) vi.advanceTimersByTime(PARK_HEARTBEAT_MS);
    const after = posted.filter((m) => m["type"] === "state").length;
    expect(after - before).toBe(3);
    // Still parked: the heartbeat is a timer, not a frame.
    expect(raf.pending()).toBe(0);
  });

  const setIdleHeartbeat = (slow: boolean) =>
    window.dispatchEvent(
      new MessageEvent("message", {
        source: window.parent,
        data: { source: "hf-parent", type: "control", action: "set-idle-heartbeat", slow },
      }),
    );
  const states = () => posted.filter((m) => m["type"] === "state").length;

  it("slows the parked heartbeat to once a second when the host asks, and back when it stops", () => {
    mount();
    initSandboxRuntimeModular();
    quiesce();

    setIdleHeartbeat(true);
    quiesce();
    const slow = states();
    vi.advanceTimersByTime(3000);
    expect(states() - slow).toBe(3);
    expect(raf.pending()).toBe(0);

    // Turned off mid-interval, the 80 ms beat resumes without waiting out the second.
    vi.advanceTimersByTime(500);
    setIdleHeartbeat(false);
    settle();
    const resumed = states();
    for (let beat = 0; beat < 3; beat += 1) vi.advanceTimersByTime(PARK_HEARTBEAT_MS);
    expect(states() - resumed).toBe(3);
  });

  it("keeps the fast heartbeat under a slow request until a timeline is bound", () => {
    mount();
    window.__timelines = {};
    initSandboxRuntimeModular();
    document.getElementById("root")!.removeAttribute("data-duration");
    setIdleHeartbeat(true);
    quiesce();

    // A composition that registers its timeline late (after fonts load) must still be seen at once.
    window.__timelines!["main"] = createMockTimeline(12);
    vi.advanceTimersByTime(PARK_HEARTBEAT_MS);
    settle();
    expect(window.__player!.getDuration()).toBeCloseTo(12, 3);
  });

  it("keeps the fast heartbeat under a slow request while a sub-composition is unbound", () => {
    mount('<div data-composition-id="child"></div>');
    initSandboxRuntimeModular();
    setIdleHeartbeat(true);
    quiesce();

    const before = states();
    for (let beat = 0; beat < 3; beat += 1) vi.advanceTimersByTime(PARK_HEARTBEAT_MS);
    expect(states() - before).toBe(3);
  });

  it("delivers a live data-duration edit while parked", async () => {
    mount();
    initSandboxRuntimeModular();
    quiesce();

    window.__timelines!["main"] = createMockTimeline(9);
    document.getElementById("root")!.setAttribute("data-duration", "9");
    await flushObservers();

    settle();
    expect(window.__player!.getDuration()).toBeCloseTo(9, 3);
  });

  it("delivers a timeline registered into window.__timelines, which no observer can see", () => {
    mount();
    window.__timelines = {};
    initSandboxRuntimeModular();
    document.getElementById("root")!.removeAttribute("data-duration");
    quiesce();
    expect(window.__player!.getDuration()).not.toBeCloseTo(12, 3);

    // No DOM mutation and no event: the registry is a plain object. Only the
    // parked heartbeat's signature re-read can find this.
    window.__timelines!["main"] = createMockTimeline(12);
    vi.advanceTimersByTime(PARK_HEARTBEAT_MS);
    settle();
    expect(window.__player!.getDuration()).toBeCloseTo(12, 3);
  });

  it("delivers a timed element mounted after the loop parked", async () => {
    mount();
    initSandboxRuntimeModular();
    quiesce();
    const manifestBefore = window.__clipManifest?.clips.length ?? 0;

    const late = document.createElement("div");
    late.id = "late-clip";
    late.setAttribute("data-start", "1");
    late.setAttribute("data-duration", "2");
    document.getElementById("root")!.appendChild(late);
    await flushObservers();

    settle();
    expect(window.__clipManifest!.clips.length).toBeGreaterThan(manifestBefore);
    expect(window.__clipManifest!.clips.some((clip) => clip.id === "late-clip")).toBe(true);
  });

  it("delivers media metadata that arrives after the loop parked", async () => {
    mount(`<video id="v" data-start="0" src="a.mp4"></video>`);
    // A declared length would hold the film at 5 s; only an inferred one can grow.
    document.getElementById("root")!.removeAttribute("data-duration");
    initSandboxRuntimeModular();
    quiesce();

    const video = document.getElementById("v") as HTMLVideoElement;
    Object.defineProperty(video, "duration", { value: 30, configurable: true });
    // `durationchange` is an event, not a DOM mutation: this is the only route.
    video.dispatchEvent(new Event("durationchange"));
    await flushObservers();

    settle();
    expect(window.__player!.getDuration()).toBeGreaterThanOrEqual(30);
  });

  it("delivers the start of a Studio manual-edit gesture while parked", async () => {
    mount(`<div id="c" data-start="0" data-duration="2"></div>`);
    initSandboxRuntimeModular();
    quiesce();
    expect(raf.pending()).toBe(0);

    document.getElementById("c")!.setAttribute(STUDIO_MANUAL_EDIT_GESTURE_ATTR, "token-1");
    await flushObservers();
    expect(raf.pending()).toBeGreaterThan(0);
  });

  it("runs the reconciling seek the frame a manual-edit gesture ends", async () => {
    mount(`<div id="c" data-start="0" data-duration="2"></div>`);
    initSandboxRuntimeModular();
    quiesce();

    const target = document.getElementById("c")!;
    target.setAttribute(STUDIO_MANUAL_EDIT_GESTURE_ATTR, "token-1");
    await flushObservers();
    raf.step();
    // A gesture owns the paused frame: the loop defers the seek and parks until the marker clears.
    expect(raf.pending()).toBe(0);

    const timeline = window.__timelines!["main"] as RuntimeTimelineLike;
    const seeks: number[] = [];
    const originalTotalTime = timeline.totalTime!.bind(timeline);
    timeline.totalTime = (time?: number, suppress?: boolean) => {
      if (time !== undefined) seeks.push(time);
      return originalTotalTime(time, suppress);
    };

    target.removeAttribute(STUDIO_MANUAL_EDIT_GESTURE_ATTR);
    await flushObservers();
    raf.step();
    expect(seeks.length).toBeGreaterThan(0);
  });

  it("wakes on an explicit seek from the control surface", () => {
    mount();
    initSandboxRuntimeModular();
    quiesce();
    expect(raf.pending()).toBe(0);

    window.__player!.seek(1);
    expect(raf.pending()).toBeGreaterThan(0);
    settle();
    expect(window.__player!.getTime()).toBeCloseTo(1, 3);
  });

  it("never parks while an export render is driving frames", () => {
    window.__HF_EXPORT_RENDER_SEEK_CONFIG = { mode: "seek" };
    mount();
    initSandboxRuntimeModular();
    quiesce();

    window.__player!.renderSeek(1);
    // The render path must keep the exact scheduling it had before: a frame is
    // always in flight, whatever the playhead is doing.
    for (let i = 0; i < 10; i += 1) {
      expect(raf.pending()).toBeGreaterThan(0);
      raf.step();
    }
  });

  it("still parks after Studio's own renderSeek fallback, which is not a render", () => {
    // `playbackAdapter` drives an overhanging-timeline preview through
    // renderSeek. Latching on that alone would leave the loop unparked for the
    // whole session — the export config is what separates the two.
    expect(window.__HF_EXPORT_RENDER_SEEK_CONFIG).toBeUndefined();
    mount();
    initSandboxRuntimeModular();
    quiesce();

    window.__player!.renderSeek(1);
    quiesce();
    expect(raf.pending()).toBe(0);
    expect(window.__player!.getTime()).toBeCloseTo(1, 3);
  });

  it("stops both the frame loop and the parked timer on teardown", () => {
    mount();
    initSandboxRuntimeModular();
    quiesce();

    window.__hfRuntimeTeardown?.();
    posted.length = 0;
    // The count, not just the silence: a heartbeat that is still armed but
    // returns early on `tornDown` posts nothing either, so counting posts
    // alone passes with the clearTimeout deleted.
    expect(vi.getTimerCount()).toBe(0);
    vi.advanceTimersByTime(PARK_HEARTBEAT_MS * 5);
    expect(raf.pending()).toBe(0);
    expect(posted.filter((m) => m["type"] === "state")).toHaveLength(0);
  });

  it("rate-limits the manifest while playing, whatever the DOM does", () => {
    mount();
    initSandboxRuntimeModular();
    quiesce();
    window.__player!.play();
    // Two seconds in, so the rebind policy's play hold is not what is doing
    // the work — this has to hold for the rest of playback too.
    for (let i = 0; i < 130; i += 1) raf.step();

    const root = document.getElementById("root")!;
    const before = posted.filter((m) => m["type"] === "timeline").length;
    for (let frame = 0; frame < 30; frame += 1) {
      // A composition that appends a node every frame. The manifest is a full
      // document walk; posting it per frame is the regression this guards.
      const node = document.createElement("div");
      node.setAttribute("data-start", String(frame));
      node.setAttribute("data-duration", "1");
      root.appendChild(node);
      raf.step();
    }
    const posts = posted.filter((m) => m["type"] === "timeline").length - before;
    // Main's cadence over 30 frames is one post per 20 frames, so at most two.
    expect(posts).toBeLessThanOrEqual(2);
  });

  it("does not re-post the manifest while playing a film that is not changing", () => {
    mount();
    initSandboxRuntimeModular();
    quiesce();
    window.__player!.play();
    // Past the rebind policy's play hold, at 120 Hz.
    for (let i = 0; i < 300; i += 1) frame120Hz();
    const before = posted.filter((m) => m["type"] === "timeline").length;
    for (let i = 0; i < 250; i += 1) frame120Hz();
    expect(posted.filter((m) => m["type"] === "timeline").length - before).toBe(0);
  });

  it("posts a playing clip's new track, label and z-index once playback stops", async () => {
    mount(
      '<div id="clip" data-start="0" data-duration="5" data-track-index="0" data-timeline-label="Before" style="z-index: 1"></div>',
    );
    initSandboxRuntimeModular();
    quiesce();
    window.__player!.play();
    for (let i = 0; i < 300; i += 1) frame120Hz();
    const clip = document.getElementById("clip")!;
    clip.setAttribute("data-track-index", "7");
    clip.setAttribute("data-timeline-label", "After");
    clip.style.zIndex = "9";
    await flushObservers();
    posted.length = 0;
    for (let i = 0; i < 130; i += 1) frame120Hz();
    expect(posted.filter((m) => m["type"] === "timeline")).toHaveLength(0);
    window.__player!.pause();
    for (let i = 0; i < 10; i += 1) frame120Hz();
    const clips = (posted.filter((m) => m["type"] === "timeline").at(-1)?.["clips"] ?? []) as Array<
      Record<string, unknown>
    >;
    const clip_ = clips.find((c) => c["id"] === "clip");
    expect([clip_?.["track"], clip_?.["timelineLabel"], clip_?.["zIndex"]]).toEqual([
      7,
      "After",
      9,
    ]);
  });

  it("posts a label edited while playing and paused before the next poll", async () => {
    mount('<div id="clip" data-start="0" data-duration="5" data-timeline-label="Before"></div>');
    initSandboxRuntimeModular();
    quiesce();
    window.__player!.play();
    for (let i = 0; i < 300; i += 1) frame120Hz();
    document.getElementById("clip")!.setAttribute("data-timeline-label", "After");
    await flushObservers();
    for (let i = 0; i < 12; i += 1) frame120Hz();
    window.__player!.pause();
    for (let i = 0; i < 300; i += 1) frame120Hz();
    const clips = (posted.filter((m) => m["type"] === "timeline").at(-1)?.["clips"] ?? []) as Array<
      Record<string, unknown>
    >;
    expect(clips.find((c) => c["id"] === "clip")?.["timelineLabel"]).toBe("After");
  });

  it("applies a data-width change while playing", async () => {
    mount();
    initSandboxRuntimeModular();
    quiesce();
    window.__player!.play();
    for (let i = 0; i < 300; i += 1) frame120Hz();
    const root = document.getElementById("root")!;
    root.setAttribute("data-width", "640");
    await flushObservers();
    for (let i = 0; i < 60; i += 1) frame120Hz();
    expect(root.style.width).toBe("640px");
  });

  it("applies a data-height change while parked", async () => {
    mount();
    initSandboxRuntimeModular();
    quiesce();
    const root = document.getElementById("root")!;
    root.setAttribute("data-height", "360");
    await flushObservers();
    vi.advanceTimersByTime(PARK_HEARTBEAT_MS);
    settle();
    expect(root.style.height).toBe("360px");
  });

  it("does not park when the manifest post throws with a change still pending", async () => {
    mount();
    initSandboxRuntimeModular();
    quiesce();

    // postTimeline walks author DOM, which can throw. Fail it exactly once.
    const NODE_SELECTOR =
      "[data-start], [data-track-index], [data-composition-id], video, audio, img";
    const realQueryAll = Document.prototype.querySelectorAll;
    let failuresLeft = 1;
    vi.spyOn(Document.prototype, "querySelectorAll").mockImplementation(function (
      this: Document,
      selector: string,
    ) {
      if (selector === NODE_SELECTOR && failuresLeft > 0) {
        failuresLeft -= 1;
        throw new Error("author DOM blew up");
      }
      return realQueryAll.call(this, selector);
    } as typeof Document.prototype.querySelectorAll);

    const late = document.createElement("div");
    late.id = "late-after-throw";
    late.setAttribute("data-start", "1");
    late.setAttribute("data-duration", "2");
    document.getElementById("root")!.appendChild(late);
    await flushObservers();

    // Run frames until the manifest post is attempted and throws. The post is
    // rate-limited, so it lands on the frame counter's boundary, not the first
    // woken frame.
    let thrown: unknown = null;
    for (let frame = 0; frame < 60 && thrown == null; frame += 1) {
      if (raf.pending() === 0) break;
      try {
        raf.step();
      } catch (error) {
        thrown = error;
      }
    }
    expect(String(thrown)).toContain("author DOM blew up");
    // The change is still owed, so the loop must not have parked on it.
    expect(raf.pending()).toBeGreaterThan(0);

    settle();
    expect(window.__clipManifest!.clips.some((clip) => clip.id === "late-after-throw")).toBe(true);
  });

  it("delivers an adapter duration that grows while parked, with no DOM mutation and no event", () => {
    mount();
    document.getElementById("root")!.removeAttribute("data-duration");
    initSandboxRuntimeModular();
    quiesce();
    const before = window.__player!.getDuration();

    // A Lottie instance lengthening is a live animation object changing. No
    // observer and no event can see it; only the parked poll can.
    window.__hfLottie = [{ goToAndStop: () => {}, totalFrames: 600, frameRate: 30 }] as never;
    vi.advanceTimersByTime(PARK_HEARTBEAT_MS);
    settle();

    expect(before).toBeLessThan(20);
    expect(window.__player!.getDuration()).toBeCloseTo(20, 3);
  });

  it("stops a media element that starts playing while parked and the clock is paused", () => {
    // Nothing may run while the clock is paused. `play` does not bubble, so the
    // wake comes from a capture-phase listener; without it the enforcement is
    // unreachable exactly when it is needed, because a parked loop runs no ticks.
    mount(`<video id="rogue" data-start="0" data-duration="5"></video>`);
    const media = stubMediaPlayback(document.getElementById("rogue") as HTMLVideoElement, 5);
    initSandboxRuntimeModular();
    quiesce();
    expect(window.__player!.isPlaying()).toBe(false);
    expect(raf.pending()).toBe(0);

    // Autoplay, a composition script, a restored bfcache state.
    media.start();
    settle();

    expect(media.isPaused()).toBe(true);
  });

  it("stops hosted media with no data-start of its own, which the transport also drives", () => {
    // A clip inside a composition inherits its timing from the host. It is the
    // transport's to play, so it is the transport's to stop; a probe keyed on
    // data-start alone could not see it.
    mount(`
      <div data-composition-id="host" data-start="0" data-duration="10">
        <video id="hosted" data-duration="5"></video>
      </div>`);
    const media = stubMediaPlayback(document.getElementById("hosted") as HTMLVideoElement, 5);
    initSandboxRuntimeModular();
    quiesce();

    media.start();
    settle();

    expect(media.isPaused()).toBe(true);
  });

  it("leaves a LEASED element alone while paused, and stops it once released", () => {
    // The colour-grading preview and the Studio's scrub audition both play media
    // on purpose with the clock stopped. They borrow the element first; the
    // enforcement is for anything that plays without borrowing.
    mount(`<video id="grade" data-start="0" data-duration="5"></video>`);
    const video = document.getElementById("grade") as HTMLVideoElement;
    const media = stubMediaPlayback(video, 5);
    initSandboxRuntimeModular();
    quiesce();

    window.__hf!.leasePausedMedia!(video);
    media.start();
    settle();
    // Several more ticks: a lease must survive more than the frame it was taken on.
    for (let i = 0; i < 5; i += 1) {
      window.__player!.seek(window.__player!.getTime());
      settle();
    }
    expect(media.isPaused()).toBe(false);

    window.__hf!.releasePausedMedia!(video);
    settle();
    expect(media.isPaused()).toBe(true);
  });

  it("does not stop the colour-grading preview, which plays on purpose while paused", () => {
    // The end-to-end wiring, not the lease in isolation: init constructs the
    // grading runtime with the lease, so startPreviewPlayback borrows before the
    // play() whose own event wakes the transport that would otherwise stop it.
    mount(`<video id="graded" data-start="0" data-duration="5"></video>`);
    const video = document.getElementById("graded") as HTMLVideoElement;
    const media = stubMediaPlayback(video, 5);
    let currentTime = 0;
    Object.defineProperty(video, "currentTime", {
      configurable: true,
      get: () => currentTime,
      set: (next: number) => {
        currentTime = next;
      },
    });
    initSandboxRuntimeModular();
    quiesce();

    const stop = window.__hf!.colorGrading!.startPreviewPlayback("graded");
    expect(typeof stop).toBe("function");
    settle();
    for (let beat = 0; beat < 5; beat += 1) {
      vi.advanceTimersByTime(PARK_HEARTBEAT_MS);
      settle();
    }
    expect(media.isPaused()).toBe(false);

    stop!();
    expect(media.isPaused()).toBe(true);
    // The stop closure must RELEASE, not just pause: a restart after it is an
    // unleased play while paused, and the transport has to stop it.
    media.start();
    settle();
    expect(media.isPaused()).toBe(true);
  });

  it("reclaims a leased element the moment the transport plays", () => {
    // A lease is an exemption from the PAUSED-side enforcement only. Once the
    // clock runs the transport owns every element again, so a leased clip that is
    // outside the playhead's window is stopped like any other.
    mount(`<video id="late" data-start="10" data-duration="5"></video>`);
    const video = document.getElementById("late") as HTMLVideoElement;
    const media = stubMediaPlayback(video, 5);
    initSandboxRuntimeModular();
    quiesce();

    window.__hf!.leasePausedMedia!(video);
    media.start();
    settle();
    expect(media.isPaused()).toBe(false);

    window.__player!.play();
    settle();
    expect(window.__player!.isPlaying()).toBe(true);
    expect(media.isPaused()).toBe(true);
  });

  const setVisibility = (state: DocumentVisibilityState) => {
    Object.defineProperty(document, "visibilityState", { configurable: true, get: () => state });
    document.dispatchEvent(new Event("visibilitychange"));
  };

  it("keeps the transport ticking on a timer while the document is hidden", () => {
    // A hidden document runs no animation frames but its media keeps playing, so a
    // transport driven by frames alone never ends a clip at the end of its window.
    let nowMs = 1000;
    vi.spyOn(performance, "now").mockImplementation(() => nowMs);
    mount(`<audio id="a1" data-start="0" data-duration="1"></audio>`);
    const media = stubMediaPlayback(document.getElementById("a1") as HTMLAudioElement, 10);
    initSandboxRuntimeModular();
    quiesce();

    window.__player!.play();
    settle();
    expect(media.isPaused()).toBe(false);

    setVisibility("hidden");
    for (let i = 0; i < 100; i += 1) {
      nowMs += 16;
      vi.advanceTimersByTime(16);
    }

    expect(window.__player!.getTime()).toBeGreaterThan(1);
    expect(media.isPaused()).toBe(true);
  });

  it("moves a pending tick between animation frames and a timer as visibility changes", () => {
    mount();
    initSandboxRuntimeModular();
    quiesce();
    window.__player!.play();
    expect(raf.pending()).toBe(1);

    setVisibility("hidden");
    expect(raf.pending()).toBe(0);
    vi.advanceTimersByTime(16);
    expect(raf.pending()).toBe(0);
    expect(window.__player!.isPlaying()).toBe(true);

    setVisibility("visible");
    expect(raf.pending()).toBe(1);
  });
});