Skip to content

Write HTML. Render video. Built for agents.

159 KB
Raw Blame
import { describe, it, expect, vi, beforeEach, afterEach, type MockInstance } from "vitest";
import { formatTime, formatSpeed, SPEED_PRESETS } from "./controls.js";

// Install a stubbed contentDocument getter on the given iframe element. The
// new stopMedia / muted tests repeat this `Object.defineProperty(... { get })`
// shape; routing through a named helper keeps the per-test bodies focused on
// the actual assertion.
function stubIframeContentDocument(iframe: HTMLIFrameElement, doc: Document | null): void {
  Object.defineProperty(iframe, "contentDocument", {
    configurable: true,
    get: () => doc,
  });
}

// Bare test docs never run a runtime, so only paintAndIdleReadinessInput
// is ever pending — drain real rAF frames past its quiet-frame minimum
// on the given window (the iframe's own, not the test's global one).
async function awaitPaintAndIdle(win: Window = window): Promise<void> {
  for (let i = 0; i < 6; i++) {
    await new Promise<void>((resolve) => win.requestAnimationFrame(() => resolve()));
  }
}

function createForeignFrameMediaDocument(): {
  doc: Document;
  video: HTMLMediaElement & { pause: ReturnType<typeof vi.fn> };
  audio: HTMLMediaElement & { pause: ReturnType<typeof vi.fn> };
} {
  class FrameElement {
    readonly tagName: string;
    ownerDocument: {
      defaultView: { Element: typeof FrameElement; HTMLMediaElement: typeof FrameElement };
    } | null = null;

    constructor(tagName: string) {
      this.tagName = tagName;
    }
  }

  class FrameMedia extends FrameElement {
    muted = false;
    defaultMuted = false;
    pause = vi.fn();
  }

  const video = new FrameMedia("VIDEO");
  const audio = new FrameMedia("AUDIO");
  const fakeDoc = {
    defaultView: { Element: FrameElement, HTMLMediaElement: FrameMedia },
    querySelectorAll: () => [video, audio],
  };
  video.ownerDocument = fakeDoc;
  audio.ownerDocument = fakeDoc;

  return {
    doc: fakeDoc as unknown as Document,
    video: video as unknown as HTMLMediaElement & { pause: ReturnType<typeof vi.fn> },
    audio: audio as unknown as HTMLMediaElement & { pause: ReturnType<typeof vi.fn> },
  };
}

// ── Controls unit tests ──

describe("SPEED_PRESETS", () => {
  it("contains logarithmic speed steps", () => {
    expect(SPEED_PRESETS).toEqual([0.25, 0.5, 1, 1.5, 2, 4]);
  });

  it("includes 1x as default speed", () => {
    expect(SPEED_PRESETS).toContain(1);
  });
});

describe("formatSpeed", () => {
  it("formats integer speeds", () => {
    expect(formatSpeed(1)).toBe("1x");
    expect(formatSpeed(2)).toBe("2x");
    expect(formatSpeed(4)).toBe("4x");
  });

  it("formats fractional speeds", () => {
    expect(formatSpeed(0.25)).toBe("0.25x");
    expect(formatSpeed(0.5)).toBe("0.5x");
    expect(formatSpeed(1.5)).toBe("1.5x");
  });
});

describe("formatTime", () => {
  it("formats 0 seconds", () => {
    expect(formatTime(0)).toBe("0:00");
  });

  it("formats seconds under a minute", () => {
    expect(formatTime(45)).toBe("0:45");
  });

  it("formats exact minutes", () => {
    expect(formatTime(120)).toBe("2:00");
  });

  it("formats minutes and seconds", () => {
    expect(formatTime(95)).toBe("1:35");
  });

  it("pads seconds with leading zero", () => {
    expect(formatTime(61)).toBe("1:01");
  });

  it("floors fractional seconds", () => {
    expect(formatTime(3.7)).toBe("0:03");
  });

  it("handles negative input", () => {
    expect(formatTime(-5)).toBe("0:00");
  });
});

// ── Parent-frame audio proxies (ownership-based) ──
//
// Parent-frame audio/video copies are preloaded mirror proxies of the iframe's
// timed media. They exist as a fallback for environments that block iframe
// `.play()`. Under the default `runtime` audio ownership, the iframe drives
// audible playback and the proxies stay paused. Ownership flips to `parent`
// only when the runtime posts `media-autoplay-blocked` — then the proxies
// become the audible source and the iframe is silenced via bridge.

describe("HyperframesPlayer parent-frame media", () => {
  type PlayerElement = HTMLElement & {
    play: () => void;
    pause: () => void;
    seek: (t: number) => void;
    _audioOwner?: "runtime" | "parent";
    _promoteToParentProxy?: () => void;
    _ready?: boolean;
    _assetsReady?: boolean;
    _parentTickRaf?: number | null;
  };

  let player: PlayerElement;
  let mockAudio: {
    src: string;
    preload: string;
    muted: boolean;
    playbackRate: number;
    currentTime: number;
    paused: boolean;
    play: ReturnType<typeof vi.fn>;
    pause: ReturnType<typeof vi.fn>;
    load: ReturnType<typeof vi.fn>;
  };

  beforeEach(async () => {
    await import("./hyperframes-player.js");

    mockAudio = {
      src: "",
      preload: "",
      muted: false,
      playbackRate: 1,
      currentTime: 0,
      paused: true,
      play: vi.fn().mockResolvedValue(undefined),
      pause: vi.fn(),
      load: vi.fn(),
    };

    vi.spyOn(globalThis, "Audio").mockImplementation(function () {
      return mockAudio as unknown as HTMLAudioElement;
    });

    player = document.createElement("hyperframes-player") as PlayerElement;
  });

  afterEach(() => {
    player.remove();
    vi.restoreAllMocks();
  });

  it("includes audio-src in observedAttributes", () => {
    const Ctor = player.constructor as typeof HTMLElement & {
      observedAttributes: string[];
    };
    expect(Ctor.observedAttributes).toContain("audio-src");
  });

  it("creates Audio and starts preloading when audio-src is set", () => {
    player.setAttribute("audio-src", "https://cdn.example.com/narration.mp3");
    document.body.appendChild(player);

    expect(globalThis.Audio).toHaveBeenCalled();
    expect(mockAudio.preload).toBe("auto");
    expect(mockAudio.src).toBe("https://cdn.example.com/narration.mp3");
    expect(mockAudio.load).toHaveBeenCalled();
  });

  it("syncs muted attribute to parent media", () => {
    player.setAttribute("muted", "");
    player.setAttribute("audio-src", "https://cdn.example.com/narration.mp3");
    document.body.appendChild(player);

    expect(mockAudio.muted).toBe(true);
  });

  it("syncs playback-rate to parent media", () => {
    player.setAttribute("playback-rate", "1.5");
    player.setAttribute("audio-src", "https://cdn.example.com/narration.mp3");
    document.body.appendChild(player);

    expect(mockAudio.playbackRate).toBe(1.5);
  });

  it("play() does NOT start parent-proxy under runtime ownership", () => {
    // Default ownership is `runtime` — the iframe drives audible playback.
    // If we also started parent proxies here, both would play and the user
    // would hear doubled, slightly-offset audio (the original bug).
    player.setAttribute("audio-src", "https://cdn.example.com/narration.mp3");
    document.body.appendChild(player);

    player.play();
    expect(mockAudio.play).not.toHaveBeenCalled();
    expect(player._audioOwner).toBe("runtime");
  });

  it("pause() does NOT touch parent-proxy under runtime ownership", () => {
    player.setAttribute("audio-src", "https://cdn.example.com/narration.mp3");
    document.body.appendChild(player);

    player.pause();
    expect(mockAudio.pause).not.toHaveBeenCalled();
  });

  it("seek() does NOT update parent currentTime under runtime ownership", () => {
    // Under runtime ownership the iframe is authoritative for time; touching
    // the proxy's currentTime would just trigger a re-buffer for no gain.
    player.setAttribute("audio-src", "https://cdn.example.com/narration.mp3");
    document.body.appendChild(player);

    player.seek(12.5);
    expect(mockAudio.currentTime).toBe(0);
  });

  it("after promotion to parent ownership: play/pause/seek drive parent proxy", () => {
    // Simulates the runtime having posted `media-autoplay-blocked`. Post
    // promotion: the web component owns audible output and fully drives
    // the parent proxy.
    player.setAttribute("audio-src", "https://cdn.example.com/narration.mp3");
    document.body.appendChild(player);

    player._promoteToParentProxy?.();
    expect(player._audioOwner).toBe("parent");

    player.play();
    expect(mockAudio.play).toHaveBeenCalled();

    player.seek(12.5);
    expect(mockAudio.currentTime).toBe(12.5);

    player.pause();
    expect(mockAudio.pause).toHaveBeenCalled();
  });

  it("hands audio back to the iframe and pauses the proxy as soon as the source changes", () => {
    player.setAttribute("audio-src", "https://cdn.example.com/narration.mp3");
    document.body.appendChild(player);
    player._promoteToParentProxy?.();
    player._ready = true;
    player._assetsReady = true;
    player.play();
    expect(player._parentTickRaf).not.toBeNull();
    mockAudio.pause.mockClear();

    player.setAttribute("src", "next-composition.html");

    expect(player._audioOwner).toBe("runtime");
    expect(mockAudio.pause).toHaveBeenCalled();
    expect(player._parentTickRaf).toBeNull();
  });

  function dispatchAutoplayBlockedFromPlayerFrame(player: HTMLElement): HTMLMediaElement {
    const iframe = player.shadowRoot?.querySelector("iframe");
    if (!(iframe instanceof HTMLIFrameElement)) throw new Error("expected player iframe");
    const iframeDoc = iframe.contentDocument;
    if (!iframeDoc) throw new Error("expected player iframe document");
    const video = iframeDoc.createElement("video");
    video.setAttribute("data-start", "0");
    video.setAttribute("data-duration", "10");
    video.muted = false;
    iframeDoc.body.appendChild(video);

    window.dispatchEvent(
      new MessageEvent("message", {
        source: iframe.contentWindow,
        data: { source: "hf-preview", type: "media-autoplay-blocked" },
      }),
    );

    return video;
  }

  it("does not mute iframe media on autoplay fallback inside presenter slideshow", () => {
    const slideshow = document.createElement("hyperframes-slideshow");
    slideshow.appendChild(player);
    document.body.appendChild(slideshow);

    const video = dispatchAutoplayBlockedFromPlayerFrame(player);

    expect(video.muted).toBe(false);
    expect(player._audioOwner).toBe("runtime");
    slideshow.remove();
  });

  it("does not promote autoplay fallback inside audience slideshow", () => {
    const slideshow = document.createElement("hyperframes-slideshow");
    slideshow.setAttribute("mode", "audience");
    slideshow.appendChild(player);
    document.body.appendChild(slideshow);

    const video = dispatchAutoplayBlockedFromPlayerFrame(player);

    expect(video.muted).toBe(false);
    expect(player._audioOwner).toBe("runtime");
    slideshow.remove();
  });

  it("seek() while playing pauses parent proxy (prevents mirrorTime stutter loop)", () => {
    // Regression: previously `seek()` only called `seekAll()`, leaving the
    // proxy playing. With the timeline frozen at the new seek target, the
    // parent's `mirrorTime` drift-correction would yank `currentTime` back
    // every ~80ms of accumulated drift, producing an audible audio stutter
    // loop while the video frame stayed frozen. `seek()` must be symmetric
    // with `pause()` for the parent-owned audio path.
    player.setAttribute("audio-src", "https://cdn.example.com/narration.mp3");
    document.body.appendChild(player);

    player._promoteToParentProxy?.();
    player.play();
    expect(mockAudio.play).toHaveBeenCalled();
    mockAudio.pause.mockClear();

    player.seek(12.5);
    expect(mockAudio.pause).toHaveBeenCalled();
    expect(mockAudio.currentTime).toBe(12.5);
  });

  it("promotion is idempotent", () => {
    player.setAttribute("audio-src", "https://cdn.example.com/narration.mp3");
    document.body.appendChild(player);

    player._promoteToParentProxy?.();
    player._promoteToParentProxy?.();
    player._promoteToParentProxy?.();
    // Only one play() attempt is triggered by promotion itself (gated on
    // `!this._paused`, which is true by default so it doesn't trigger at all).
    // The test's meaning is: ownership stays `parent`, no thrash, no errors.
    expect(player._audioOwner).toBe("parent");
  });

  it("dispatches audioownershipchange on promotion", () => {
    player.setAttribute("audio-src", "https://cdn.example.com/narration.mp3");
    document.body.appendChild(player);

    const events: Array<{ owner: string; reason: string }> = [];
    player.addEventListener("audioownershipchange", (e: Event) => {
      const detail = (e as CustomEvent<{ owner: string; reason: string }>).detail;
      events.push(detail);
    });

    player._promoteToParentProxy?.();
    expect(events).toEqual([{ owner: "parent", reason: "autoplay-blocked" }]);

    // Second promote is idempotent — no duplicate event.
    player._promoteToParentProxy?.();
    expect(events).toHaveLength(1);
  });

  it("promotion mid-playback plays parent proxy immediately", () => {
    // Previously-missing coverage: if the user is already playing when
    // the runtime reports autoplay-blocked, the proxy must start audible
    // right away — not wait for the user to hit pause/play again.
    player.setAttribute("audio-src", "https://cdn.example.com/narration.mp3");
    document.body.appendChild(player);

    player.play(); // `_paused = false`, owner still `runtime` → no parent play yet
    expect(mockAudio.play).not.toHaveBeenCalled();

    player._promoteToParentProxy?.();
    expect(mockAudio.play).toHaveBeenCalled();
  });

  it("surfaces playbackerror when parent proxy play() rejects", async () => {
    player.setAttribute("audio-src", "https://cdn.example.com/narration.mp3");
    document.body.appendChild(player);

    const rejection = Object.assign(new Error("blocked"), { name: "NotAllowedError" });
    mockAudio.play = vi.fn().mockRejectedValueOnce(rejection);

    const errors: unknown[] = [];
    player.addEventListener("playbackerror", (e: Event) => {
      errors.push((e as CustomEvent).detail);
    });

    player._promoteToParentProxy?.();
    player.play();
    // Promise rejection delivered on a microtask — flush.
    await Promise.resolve();
    await Promise.resolve();

    expect(errors.length).toBeGreaterThan(0);
    expect((errors[0] as { source: string }).source).toBe("parent-proxy");
  });

  it("playbackerror dedup: fires at most once per parent-ownership session", async () => {
    // Under parent ownership with parent-also-blocked, every iframe
    // paused→playing transition in the state loop re-invokes `_playParentMedia`.
    // Without a latch, each rejection would re-fire `playbackerror`, spamming
    // subscribers. Mirrors the runtime's `mediaAutoplayBlockedPosted` latch.
    player.setAttribute("audio-src", "https://cdn.example.com/narration.mp3");
    document.body.appendChild(player);

    const rejection = Object.assign(new Error("blocked"), { name: "NotAllowedError" });
    mockAudio.play = vi.fn().mockRejectedValue(rejection);

    const errors: unknown[] = [];
    player.addEventListener("playbackerror", (e: Event) => {
      errors.push((e as CustomEvent).detail);
    });

    player._promoteToParentProxy?.();
    player.play();
    player.pause();
    player.play();
    player.pause();
    player.play();
    await Promise.resolve();
    await Promise.resolve();
    await Promise.resolve();

    expect(errors).toHaveLength(1);
  });

  it("cleans up parent media on disconnect", () => {
    player.setAttribute("audio-src", "https://cdn.example.com/narration.mp3");
    document.body.appendChild(player);

    player.remove();
    expect(mockAudio.pause).toHaveBeenCalled();
    expect(mockAudio.src).toBe("");
  });

  it("owns exactly one controls, media, and listener set across ten reconnects", () => {
    const reconnectingPlayer = player as PlayerElement & {
      readonly iframeElement: HTMLIFrameElement;
      readonly paused: boolean;
      readonly _parentMedia: unknown[];
      shadowRoot: ShadowRoot;
    };
    reconnectingPlayer.setAttribute("controls", "");
    reconnectingPlayer.setAttribute("audio-src", "https://cdn.example.com/narration.mp3");

    const windowAdd = vi.spyOn(window, "addEventListener");
    const windowRemove = vi.spyOn(window, "removeEventListener");
    const iframeAdd = vi.spyOn(reconnectingPlayer.iframeElement, "addEventListener");
    const iframeRemove = vi.spyOn(reconnectingPlayer.iframeElement, "removeEventListener");

    for (let cycle = 0; cycle < 10; cycle++) {
      document.body.appendChild(reconnectingPlayer);
      expect(reconnectingPlayer.shadowRoot.querySelectorAll(".hfp-controls")).toHaveLength(1);
      expect(reconnectingPlayer._parentMedia).toHaveLength(1);

      reconnectingPlayer.remove();
      expect(reconnectingPlayer.shadowRoot.querySelectorAll(".hfp-controls")).toHaveLength(0);
      expect(reconnectingPlayer._parentMedia).toHaveLength(0);
      expect(reconnectingPlayer.paused).toBe(true);
    }

    document.body.appendChild(reconnectingPlayer);

    expect(reconnectingPlayer.shadowRoot.querySelectorAll(".hfp-controls")).toHaveLength(1);
    expect(reconnectingPlayer._parentMedia).toHaveLength(1);
    expect(
      windowAdd.mock.calls.filter(([eventName]) => eventName === "message").length -
        windowRemove.mock.calls.filter(([eventName]) => eventName === "message").length,
    ).toBe(1);
    // The one load listener is added in the constructor, before these spies.
    expect(
      iframeAdd.mock.calls.filter(([eventName]) => eventName === "load").length -
        iframeRemove.mock.calls.filter(([eventName]) => eventName === "load").length,
    ).toBe(0);
  });

  it("returns parent-media ownership to the runtime after reconnect", () => {
    player.setAttribute("audio-src", "https://cdn.example.com/narration.mp3");
    document.body.appendChild(player);
    player._promoteToParentProxy?.();
    expect(player._audioOwner).toBe("parent");

    player.remove();
    document.body.appendChild(player);

    expect(player._audioOwner).toBe("runtime");
  });

  it("updates parent media when playback-rate changes after setup", () => {
    player.setAttribute("audio-src", "https://cdn.example.com/narration.mp3");
    document.body.appendChild(player);

    player.setAttribute("playback-rate", "2");
    expect(mockAudio.playbackRate).toBe(2);
  });

  it("updates parent media when muted toggles after setup", () => {
    player.setAttribute("audio-src", "https://cdn.example.com/narration.mp3");
    document.body.appendChild(player);

    player.setAttribute("muted", "");
    expect(mockAudio.muted).toBe(true);

    player.removeAttribute("muted");
    expect(mockAudio.muted).toBe(false);
  });
});

// ── Shader transition preview controls ──
//
// Shader transition capture scale and loading UI ownership are player-level
// preview concerns. The player forwards those options into the iframe before
// the composition runs, then renders transition-prep progress from runtime
// messages when `shader-loading="player"` is enabled.

describe("HyperframesPlayer shader transition options", () => {
  type PlayerWithIframe = HTMLElement & {
    iframeElement: HTMLIFrameElement;
  };

  beforeEach(async () => {
    await import("./hyperframes-player.js");
  });

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

  it("observes shader capture scale and loading attributes", () => {
    const player = document.createElement("hyperframes-player");
    const Ctor = player.constructor as typeof HTMLElement & {
      observedAttributes: string[];
    };

    expect(Ctor.observedAttributes).toContain("shader-capture-scale");
    expect(Ctor.observedAttributes).toContain("shader-loading");
  });

  it("passes shader options through src query parameters", () => {
    const player = document.createElement("hyperframes-player") as PlayerWithIframe;
    player.setAttribute("shader-capture-scale", "0.5");
    player.setAttribute("shader-loading", "player");
    document.body.appendChild(player);
    player.setAttribute("src", "/api/projects/demo/preview?x=1#stage");

    const url = new URL(player.iframeElement.src);
    expect(url.pathname).toBe("/api/projects/demo/preview");
    expect(url.searchParams.get("x")).toBe("1");
    expect(url.searchParams.get("__hf_shader_capture_scale")).toBe("0.5");
    expect(url.searchParams.get("__hf_shader_loading")).toBe("player");
    expect(url.hash).toBe("#stage");
  });

  it("injects shader options into srcdoc before composition scripts run", () => {
    const player = document.createElement("hyperframes-player") as PlayerWithIframe;
    player.setAttribute("shader-capture-scale", "0.5");
    player.setAttribute("shader-loading", "player");
    document.body.appendChild(player);
    player.setAttribute(
      "srcdoc",
      '<!doctype html><html><head><script src="composition.js"></script></head><body></body></html>',
    );

    const srcdoc = player.iframeElement.srcdoc;
    expect(srcdoc).toContain('window.__HF_SHADER_CAPTURE_SCALE="0.5";');
    expect(srcdoc).toContain('window.__HF_SHADER_LOADING="player";');
    expect(srcdoc.indexOf("data-hyperframes-player-shader-options")).toBeLessThan(
      srcdoc.indexOf("composition.js"),
    );
  });

  it("shows and hides the player-owned shader loader from transition state messages", () => {
    vi.useFakeTimers();
    const player = document.createElement("hyperframes-player") as PlayerWithIframe;
    player.setAttribute("shader-loading", "player");
    document.body.appendChild(player);

    const iframeWindow = player.iframeElement.contentWindow;
    expect(iframeWindow).toBeTruthy();
    window.dispatchEvent(
      new MessageEvent("message", {
        source: iframeWindow,
        data: {
          source: "hf-preview",
          type: "shader-transition-state",
          compositionId: "main",
          state: {
            loading: true,
            progress: 3,
            total: 10,
            currentTransition: 1,
            transitionTotal: 2,
            transitionFrame: 3,
            transitionFrames: 5,
            phase: "capturing",
          },
        },
      }),
    );

    const loader = player.shadowRoot?.querySelector(".hfp-shader-loader");
    expect(loader?.classList.contains("hfp-visible")).toBe(true);
    expect(loader?.textContent).toContain("1/2");
    expect(loader?.textContent).toContain("3/5");

    const playEvents: Event[] = [];
    player.addEventListener("play", (event) => playEvents.push(event));
    loader?.dispatchEvent(new MouseEvent("click", { bubbles: true, composed: true }));
    expect(playEvents).toHaveLength(0);

    window.dispatchEvent(
      new MessageEvent("message", {
        source: iframeWindow,
        data: {
          source: "hf-preview",
          type: "shader-transition-state",
          compositionId: "main",
          state: { loading: false, ready: true },
        },
      }),
    );
    window.dispatchEvent(
      new MessageEvent("message", {
        source: iframeWindow,
        data: {
          source: "hf-preview",
          type: "shader-transition-state",
          compositionId: "main",
          state: { loading: false, ready: true },
        },
      }),
    );
    expect(loader?.classList.contains("hfp-visible")).toBe(false);
    expect(loader?.classList.contains("hfp-hiding")).toBe(true);
    vi.advanceTimersByTime(420);
    expect(loader?.classList.contains("hfp-hiding")).toBe(false);
    vi.useRealTimers();
  });
});

// ── Shared stylesheet (adoptedStyleSheets) ──
//
// Every player constructed in the same document should adopt the *same*
// CSSStyleSheet instance instead of getting its own <style> element. This is
// the studio thumbnail-grid win — N players, one parsed sheet.

describe("HyperframesPlayer adoptedStyleSheets", () => {
  type AdoptingShadowRoot = ShadowRoot & { adoptedStyleSheets: CSSStyleSheet[] };
  type PlayerWithShadow = HTMLElement & { shadowRoot: AdoptingShadowRoot | null };

  beforeEach(async () => {
    await import("./hyperframes-player.js");
  });

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

  it("shares a single CSSStyleSheet across multiple player instances", () => {
    const a = document.createElement("hyperframes-player") as PlayerWithShadow;
    const b = document.createElement("hyperframes-player") as PlayerWithShadow;
    document.body.appendChild(a);
    document.body.appendChild(b);

    const sheetsA = a.shadowRoot?.adoptedStyleSheets ?? [];
    const sheetsB = b.shadowRoot?.adoptedStyleSheets ?? [];

    expect(sheetsA.length).toBeGreaterThan(0);
    expect(sheetsB.length).toBeGreaterThan(0);
    expect(sheetsA.at(-1)).toBe(sheetsB.at(-1));
  });

  it("does not inject a per-instance <style> when adoption succeeds", () => {
    const player = document.createElement("hyperframes-player") as PlayerWithShadow;
    document.body.appendChild(player);

    expect(player.shadowRoot?.querySelector("style")).toBeNull();
  });
});

// ── Media MutationObserver scoping ──
//
// The observer that catches late-attached `<audio data-start>` from
// sub-composition activation used to watch `iframe.contentDocument.body`
// wholesale. That fired on every body-level mutation — analytics scripts,
// runtime telemetry markers, dev-only overlays — even though only
// composition-tree changes can introduce new timed media. The fix is to
// scope per top-level composition host (see `selectMediaObserverTargets`);
// these tests verify the player honors that scoping.

describe("HyperframesPlayer media MutationObserver scoping", () => {
  type PlayerInternal = HTMLElement & {
    _observeDynamicMedia?: (doc: Document) => void;
  };

  beforeEach(async () => {
    await import("./hyperframes-player.js");
  });

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

  it("attaches the observer to each top-level composition host (not the body)", () => {
    const observeSpy = vi.spyOn(MutationObserver.prototype, "observe");

    const player = document.createElement("hyperframes-player") as PlayerInternal;
    document.body.appendChild(player);
    // The constructor doesn't install an observer — only `_observeDynamicMedia`
    // does — so the spy starts clean for the call we care about.
    observeSpy.mockClear();

    // Simulates the iframe document the runtime hands the player after mount.
    // Bypassing the iframe lifecycle keeps the test deterministic; the
    // selection logic itself is exercised in `mediaObserverScope.test.ts`.
    const fakeDoc = document.implementation.createHTMLDocument("test");
    fakeDoc.body.innerHTML = `
      <div data-composition-id="root-a"></div>
      <div data-composition-id="root-b"></div>
      <script>// runtime telemetry — body-level, must NOT be observed</script>
    `;

    player._observeDynamicMedia?.(fakeDoc);

    expect(observeSpy).toHaveBeenCalledTimes(2);
    const observedTargets = observeSpy.mock.calls.map((call) => call[0]);
    expect(observedTargets.map((t) => (t as Element).getAttribute("data-composition-id"))).toEqual([
      "root-a",
      "root-b",
    ]);
    expect(observedTargets).not.toContain(fakeDoc.body);
    // Subtree is still required — sub-composition media can be deeply nested
    // inside the host (e.g. wrapper div around the `<audio>`).
    // Attribute observation on "preload" and "src" is required so the player creates
    // parent proxies when the preloader promotes a clip, and follows a re-pointed one.
    for (const call of observeSpy.mock.calls) {
      expect(call[1]).toEqual({
        childList: true,
        subtree: true,
        attributes: true,
        attributeFilter: ["preload", "src"],
      });
    }
  });

  it("falls back to observing the document body when no composition hosts exist", () => {
    // Preserves the legacy behavior for documents that haven't bootstrapped
    // a composition tree yet (e.g. a blank iframe between src changes).
    const observeSpy = vi.spyOn(MutationObserver.prototype, "observe");

    const player = document.createElement("hyperframes-player") as PlayerInternal;
    document.body.appendChild(player);
    observeSpy.mockClear();

    const fakeDoc = document.implementation.createHTMLDocument("test");
    fakeDoc.body.innerHTML = `<div class="not-a-composition"></div>`;

    player._observeDynamicMedia?.(fakeDoc);

    expect(observeSpy).toHaveBeenCalledTimes(1);
    expect(observeSpy.mock.calls[0]?.[0]).toBe(fakeDoc.body);
  });
});

// ── Parent-proxy time-mirror coalescing ──
//
// `_mirrorParentMediaTime` is the steady-state correction loop that nudges
// every parent-frame audio/video proxy back onto the iframe's timeline. The
// post-`P1-4` contract: a single over-threshold sample (one slow bridge tick,
// one tab-throttled rAF, one GC pause) is absorbed by a per-proxy counter and
// does NOT cost a `currentTime` write. Only a *trending* drift — two
// consecutive samples above the 50 ms threshold — triggers a seek. Forced
// callers (audio-ownership promotion, brand-new proxy initialization) bypass
// the gate so the listener never hears a misaligned sample on cut-over.

describe("HyperframesPlayer parent-proxy time-mirror coalescing", () => {
  type DriftEntry = {
    el: { currentTime: number; src: string; pause: () => void };
    start: number;
    duration: number;
    driftSamples: number;
  };
  type PlayerInternal = HTMLElement & {
    _parentMedia: DriftEntry[];
    _mirrorParentMediaTime: (timelineSeconds: number, options?: { force?: boolean }) => void;
    _promoteToParentProxy?: () => void;
  };

  let player: PlayerInternal;

  beforeEach(async () => {
    await import("./hyperframes-player.js");
    player = document.createElement("hyperframes-player") as PlayerInternal;
    document.body.appendChild(player);
    // No audio-src was set, so `_parentMedia` is empty. Tests push synthetic
    // POJO entries — `_mirrorParentMediaTime` only reads/writes
    // `el.currentTime`, so a plain object stands in fine for HTMLMediaElement.
  });

  afterEach(() => {
    player.remove();
    vi.restoreAllMocks();
  });

  function makeEntry(
    opts: {
      currentTime?: number;
      start?: number;
      duration?: number;
      driftSamples?: number;
    } = {},
  ): DriftEntry {
    // Include `pause`/`src` so `disconnectedCallback`'s teardown loop
    // (`m.el.pause(); m.el.src = ""`) doesn't blow up when the player is
    // removed at the end of the test — `_mirrorParentMediaTime` itself only
    // touches `currentTime`.
    const entry: DriftEntry = {
      el: {
        currentTime: opts.currentTime ?? 0,
        src: "",
        pause: vi.fn(),
      },
      start: opts.start ?? 0,
      duration: opts.duration ?? 100,
      driftSamples: opts.driftSamples ?? 0,
    };
    player._parentMedia.push(entry);
    return entry;
  }

  it("initializes new parent-media entries with driftSamples=0", () => {
    // Mock Audio just for this test so the audio-src bootstrap path produces
    // a real entry rather than throwing on construction.
    const mockAudio = {
      src: "",
      preload: "",
      muted: false,
      playbackRate: 1,
      currentTime: 0,
      paused: true,
      play: vi.fn().mockResolvedValue(undefined),
      pause: vi.fn(),
      load: vi.fn(),
    };
    vi.spyOn(globalThis, "Audio").mockImplementation(function () {
      return mockAudio as unknown as HTMLAudioElement;
    });

    const fresh = document.createElement("hyperframes-player") as PlayerInternal;
    fresh.setAttribute("audio-src", "https://cdn.example.com/narration.mp3");
    document.body.appendChild(fresh);

    expect(fresh._parentMedia).toHaveLength(1);
    expect(fresh._parentMedia[0]?.driftSamples).toBe(0);
    fresh.remove();
  });

  it("does nothing when drift is within the 50 ms threshold", () => {
    const m = makeEntry({ currentTime: 5 });
    player._mirrorParentMediaTime(5.04);
    expect(m.el.currentTime).toBe(5);
    expect(m.driftSamples).toBe(0);
  });

  it("absorbs a single over-threshold spike without writing currentTime", () => {
    const m = makeEntry({ currentTime: 5 });
    player._mirrorParentMediaTime(5.5);
    expect(m.el.currentTime).toBe(5);
    expect(m.driftSamples).toBe(1);
  });

  it("issues a seek on the second consecutive over-threshold sample", () => {
    const m = makeEntry({ currentTime: 5 });
    player._mirrorParentMediaTime(5.5);
    expect(m.el.currentTime).toBe(5);
    expect(m.driftSamples).toBe(1);
    // Second sample with the same drift: the gate trips, the write fires,
    // and the counter resets so the proxy doesn't re-seek every later tick.
    player._mirrorParentMediaTime(5.5);
    expect(m.el.currentTime).toBe(5.5);
    expect(m.driftSamples).toBe(0);
  });

  it("resets the counter when a sample comes back within threshold", () => {
    const m = makeEntry({ currentTime: 5 });
    player._mirrorParentMediaTime(5.5);
    expect(m.driftSamples).toBe(1);
    // Recovery — counter must clear so a later isolated spike doesn't
    // accidentally satisfy the 2-sample gate by piggy-backing on stale state.
    player._mirrorParentMediaTime(5.02);
    expect(m.driftSamples).toBe(0);
    expect(m.el.currentTime).toBe(5);
    player._mirrorParentMediaTime(5.5);
    expect(m.driftSamples).toBe(1);
    expect(m.el.currentTime).toBe(5);
  });

  it("force: true writes immediately on the first over-threshold sample", () => {
    const m = makeEntry({ currentTime: 5 });
    player._mirrorParentMediaTime(5.5, { force: true });
    expect(m.el.currentTime).toBe(5.5);
    expect(m.driftSamples).toBe(0);
  });

  it("force: true clears any pre-existing drift counter", () => {
    const m = makeEntry({ currentTime: 5, driftSamples: 1 });
    player._mirrorParentMediaTime(5.5, { force: true });
    expect(m.el.currentTime).toBe(5.5);
    expect(m.driftSamples).toBe(0);
  });

  it("does not seek out-of-range entries and resets their counters", () => {
    // Active window [10, 15). currentTime=99 is a sentinel — if the function
    // ever writes inside an out-of-range branch the test catches it because
    // relTime would be 5 (or 15), not 99.
    const m = makeEntry({
      currentTime: 99,
      start: 10,
      duration: 5,
      driftSamples: 5,
    });
    player._mirrorParentMediaTime(5);
    expect(m.el.currentTime).toBe(99);
    expect(m.driftSamples).toBe(0);
    // Boundary: relTime === duration → still out of range (the loop uses `>=`).
    m.driftSamples = 7;
    player._mirrorParentMediaTime(15);
    expect(m.el.currentTime).toBe(99);
    expect(m.driftSamples).toBe(0);
  });

  it("tracks drift independently across multiple proxies", () => {
    // a is drifted; b is aligned. A single tick must increment a's counter
    // and reset b's — proving the per-entry state is genuinely per-entry.
    const a = makeEntry({ currentTime: 5 });
    const b = makeEntry({ currentTime: 7.01, driftSamples: 1 });
    player._mirrorParentMediaTime(7);
    expect(a.el.currentTime).toBe(5);
    expect(a.driftSamples).toBe(1);
    expect(b.el.currentTime).toBe(7.01);
    expect(b.driftSamples).toBe(0);
  });

  it("force: true bypasses the gate for every proxy in a single sweep", () => {
    const a = makeEntry({ currentTime: 5 });
    const b = makeEntry({ currentTime: 8 });
    player._mirrorParentMediaTime(7, { force: true });
    expect(a.el.currentTime).toBe(7);
    expect(b.el.currentTime).toBe(7);
    expect(a.driftSamples).toBe(0);
    expect(b.driftSamples).toBe(0);
  });

  it("_promoteToParentProxy invokes _mirrorParentMediaTime with force: true", () => {
    // Integration check of the promotion call site — we cannot tolerate even
    // ~80 ms of audible drift across an ownership flip, so the call site
    // must opt out of the jitter gate.
    const spy = vi.spyOn(player, "_mirrorParentMediaTime");
    player._promoteToParentProxy?.();
    const forcedCall = spy.mock.calls.find(([, opts]) => opts?.force === true);
    expect(forcedCall).toBeDefined();
  });
});

// ── Synchronous seek() with same-origin detection ──
//
// Studio has long reached past the postMessage bridge and called the runtime's
// `__player.seek` directly (`useTimelinePlayer.ts:233`) — that's the only way
// to land a scrubbed frame in the same task as the input event so the user
// sees no perceived lag. P3-1 promotes that pattern to a public API: the
// player element's own `seek()` now tries the same shortcut first, and only
// falls back to the async postMessage bridge when the iframe is genuinely
// cross-origin (or the runtime hasn't installed `__player` yet). The tests
// here stub `iframe.contentWindow` so we can exercise the branch matrix
// without booting an actual runtime.

describe("HyperframesPlayer seek() sync path", () => {
  type SyncPlayerStub = {
    seek?: (t: number) => void;
    play?: () => void;
    pause?: () => void;
  };
  type TimelineStub = {
    duration: () => number;
    time: () => number;
    seek: (t: number) => void;
    play: () => void;
    pause: () => void;
  };
  type FakeContentWindow = {
    __player?: SyncPlayerStub;
    __timelines?: Record<string, TimelineStub>;
    postMessage?: ReturnType<typeof vi.fn>;
  };
  type PlayerInternal = HTMLElement & {
    seek: (t: number) => void;
    play: () => void;
    pause: () => void;
    stopMedia: () => void;
    iframe: HTMLIFrameElement;
    _currentTime: number;
    duration: number;
    _parentMedia: Array<{
      el: { pause: ReturnType<typeof vi.fn>; src: string };
      start: number;
      duration: number;
      driftSamples: number;
      source?: HTMLMediaElement | null;
    }>;
  };

  let player: PlayerInternal;

  beforeEach(async () => {
    await import("./hyperframes-player.js");
    player = document.createElement("hyperframes-player") as PlayerInternal;
    document.body.appendChild(player);
  });

  afterEach(() => {
    player.remove();
    vi.restoreAllMocks();
  });

  // Replace the iframe's `contentWindow` getter so the test controls what the
  // sync path sees. Passing `"throw"` simulates the cross-origin SecurityError
  // a real browser raises when reading `contentWindow.<anything>`.
  function stubContentWindow(stub: FakeContentWindow | "throw") {
    Object.defineProperty(player.iframe, "contentWindow", {
      configurable: true,
      get() {
        if (stub === "throw") throw new Error("SecurityError");
        return stub;
      },
    });
  }

  it("calls __player.seek directly on the same-origin path", () => {
    // The whole point of P3-1: when the runtime is reachable, scrubs land in
    // the same task as the input. `postMessage` must NOT also fire — that
    // would cause a duplicate, async re-seek a tick later.
    const sync = vi.fn();
    const post = vi.fn();
    stubContentWindow({ __player: { seek: sync }, postMessage: post });

    player.seek(12.5);

    expect(sync).toHaveBeenCalledTimes(1);
    expect(sync).toHaveBeenCalledWith(12.5);
    expect(post).not.toHaveBeenCalled();
  });

  it("passes the raw time-in-seconds through, not a rounded frame number", () => {
    // The postMessage bridge has to round to a frame at the wire boundary,
    // but the in-process call accepts seconds directly — preserving the
    // caller's precision for fractional scrubs.
    const sync = vi.fn();
    stubContentWindow({ __player: { seek: sync } });

    player.seek(7.3333);

    expect(sync).toHaveBeenCalledWith(7.3333);
  });

  it("falls back to postMessage when __player has not been installed yet", () => {
    // Before the runtime bootstraps, `contentWindow` exists but `__player` is
    // undefined. The fallback queues the seek via postMessage, which the
    // runtime drains once `installRuntimeControlBridge` runs.
    const post = vi.fn();
    stubContentWindow({ postMessage: post });

    player.seek(12.5);

    expect(post).toHaveBeenCalledTimes(1);
    expect(post).toHaveBeenCalledWith(
      expect.objectContaining({
        source: "hf-parent",
        type: "control",
        action: "seek",
        timeSeconds: 12.5,
        frame: 375,
        protocolVersion: 1,
      }),
      "*",
    );
  });

  it("carries a frame fallback for accepted legacy cross-origin runtimes", () => {
    // An older runtime ignores protocol-v1 metadata and reads only `frame`.
    // Omitting it makes that bridge default every seek to frame zero.
    const post = vi.fn();
    stubContentWindow({ postMessage: post });

    player.seek(7.5);

    expect(post).toHaveBeenCalledWith(
      expect.objectContaining({
        action: "seek",
        timeSeconds: 7.5,
        frame: 225,
      }),
      "*",
    );
  });

  it("seeks same-origin __timelines when no runtime bridge exists", () => {
    const timeline: TimelineStub = {
      duration: vi.fn(() => 5),
      time: vi.fn(() => 0),
      seek: vi.fn(),
      play: vi.fn(),
      pause: vi.fn(),
    };
    const post = vi.fn();
    stubContentWindow({ __timelines: { main: timeline }, postMessage: post });

    player.seek(2);

    expect(timeline.seek).toHaveBeenCalledTimes(1);
    // suppressEvents=false so onUpdate fires (imperative-visibility compositions repaint).
    expect(timeline.seek).toHaveBeenCalledWith(2, false);
    expect(post).not.toHaveBeenCalled();
  });

  it("rebinds when a same-origin composition replaces its registered timeline", () => {
    const first: TimelineStub = {
      duration: vi.fn(() => 5),
      time: vi.fn(() => 0),
      seek: vi.fn(),
      play: vi.fn(),
      pause: vi.fn(),
    };
    const second: TimelineStub = {
      duration: vi.fn(() => 8),
      time: vi.fn(() => 0),
      seek: vi.fn(),
      play: vi.fn(),
      pause: vi.fn(),
    };
    const timelines = { main: first };
    const post = vi.fn();
    stubContentWindow({ __timelines: timelines, postMessage: post });

    player.seek(1);
    timelines.main = second;
    player.seek(6);

    expect(first.seek).toHaveBeenCalledTimes(1);
    expect(second.seek).toHaveBeenCalledWith(6, false);
    expect(player.duration).toBe(8);
    expect(post).not.toHaveBeenCalled();
  });

  it("fires durationchange when a ready composition replaces its timeline", () => {
    const makeTimeline = (duration: number): TimelineStub => ({
      duration: vi.fn(() => duration),
      time: vi.fn(() => 0),
      seek: vi.fn(),
      play: vi.fn(),
      pause: vi.fn(),
    });
    const timelines = { main: makeTimeline(5) };
    stubContentWindow({ __timelines: timelines, postMessage: vi.fn() });
    const durations: number[] = [];
    player.addEventListener("durationchange", (event) => {
      durations.push((event as CustomEvent<{ duration: number }>).detail.duration);
    });

    player.seek(1);
    (player as unknown as { _ready: boolean })._ready = true;
    timelines.main = makeTimeline(8);
    player.seek(6);

    expect(durations).toEqual([8]);
  });

  it("plays and pauses same-origin __timelines when no runtime bridge exists", () => {
    const timeline: TimelineStub = {
      duration: vi.fn(() => 5),
      time: vi.fn(() => 0),
      seek: vi.fn(),
      play: vi.fn(),
      pause: vi.fn(),
    };
    const post = vi.fn();
    stubContentWindow({ __timelines: { main: timeline }, postMessage: post });

    player.play();
    player.pause();

    expect(timeline.play).toHaveBeenCalledTimes(1);
    expect(timeline.pause).toHaveBeenCalledTimes(1);
    expect(post).not.toHaveBeenCalled();
  });

  it("pauses same-origin __timelines after seek while playing", () => {
    const pause = vi.fn();
    const timeline: TimelineStub = {
      duration: vi.fn(() => 5),
      time: vi.fn(() => 0),
      seek: vi.fn(),
      play: vi.fn(),
      pause,
    };
    const post = vi.fn();
    stubContentWindow({ __timelines: { main: timeline }, postMessage: post });

    player.play();
    pause.mockClear();
    player.seek(2);

    expect(timeline.seek).toHaveBeenCalledWith(2, false);
    expect(pause).toHaveBeenCalledTimes(1);
    expect(post).not.toHaveBeenCalled();
  });

  it("stopMedia pauses slide media without stopping global audio-src proxies", () => {
    const post = vi.fn();
    const doc = document.implementation.createHTMLDocument("composition");
    const iframeVideo = doc.createElement("video");
    const iframeAudio = doc.createElement("audio");
    const iframeVideoPause = vi.fn();
    const iframeAudioPause = vi.fn();
    Object.defineProperty(iframeVideo, "pause", { configurable: true, value: iframeVideoPause });
    Object.defineProperty(iframeAudio, "pause", { configurable: true, value: iframeAudioPause });
    doc.body.append(iframeVideo, iframeAudio);
    stubIframeContentDocument(player.iframe, doc);
    stubContentWindow({ postMessage: post });

    const slideProxyPause = vi.fn();
    const globalProxyPause = vi.fn();
    player._parentMedia.push(
      {
        el: { pause: slideProxyPause, src: "https://cdn.example.com/slide.mp4" },
        start: 0,
        duration: 5,
        driftSamples: 0,
        source: iframeVideo,
      },
      {
        el: { pause: globalProxyPause, src: "https://cdn.example.com/background.mp3" },
        start: 0,
        duration: Infinity,
        driftSamples: 0,
        source: null,
      },
    );

    player.stopMedia();

    expect(post).toHaveBeenCalledWith(expect.objectContaining({ action: "stop-media" }), "*");
    expect(iframeVideoPause).toHaveBeenCalledOnce();
    expect(iframeAudioPause).toHaveBeenCalledOnce();
    expect(slideProxyPause).toHaveBeenCalledOnce();
    expect(globalProxyPause).not.toHaveBeenCalled();
  });

  it("stopMedia pauses iframe-realm media elements", () => {
    const post = vi.fn();
    const { doc, video, audio } = createForeignFrameMediaDocument();
    stubIframeContentDocument(player.iframe, doc);
    stubContentWindow({ postMessage: post });

    player.stopMedia();

    expect(post).toHaveBeenCalledWith(expect.objectContaining({ action: "stop-media" }), "*");
    expect(video.pause).toHaveBeenCalledOnce();
    expect(audio.pause).toHaveBeenCalledOnce();
  });

  it("does not bypass an installed runtime bridge for direct __timelines playback", () => {
    const timeline: TimelineStub = {
      duration: vi.fn(() => 5),
      time: vi.fn(() => 0),
      seek: vi.fn(),
      play: vi.fn(),
      pause: vi.fn(),
    };
    const post = vi.fn();
    stubContentWindow({
      __player: { play: vi.fn(), pause: vi.fn() },
      __timelines: { main: timeline },
      postMessage: post,
    });

    player.play();
    player.pause();

    expect(timeline.play).not.toHaveBeenCalled();
    expect(timeline.pause).not.toHaveBeenCalled();
    expect(post).toHaveBeenCalledWith(expect.objectContaining({ action: "play" }), "*");
    expect(post).toHaveBeenCalledWith(expect.objectContaining({ action: "pause" }), "*");
  });

  it("falls back to postMessage when __player exists but lacks seek()", () => {
    // Defensive: a partial `__player` (e.g. older runtime, mocked stub) must
    // not be assumed callable. `typeof seek !== "function"` guards this.
    const post = vi.fn();
    stubContentWindow({
      __player: { play: vi.fn(), pause: vi.fn() },
      postMessage: post,
    });

    player.seek(7);

    expect(post).toHaveBeenCalledWith(
      expect.objectContaining({
        action: "seek",
        timeSeconds: 7,
        frame: 210,
        protocolVersion: 1,
      }),
      "*",
    );
  });

  it("does not throw when contentWindow access raises (cross-origin embed)", () => {
    // Reading `iframe.contentWindow` on a true cross-origin iframe throws a
    // DOMException. Both `_trySyncSeek` AND the postMessage fallback hit the
    // same getter, so both swallow the error — the public seek() must remain
    // a clean no-op surface for the caller.
    stubContentWindow("throw");

    expect(() => player.seek(12.5)).not.toThrow();
  });

  it("falls back to postMessage when __player.seek throws at runtime", () => {
    // If the runtime's seek implementation panics, we catch in `_trySyncSeek`
    // and degrade to the bridge. The postMessage path runs in a separate
    // task — it may succeed where the sync call failed, and at worst the
    // failure mode is identical.
    const sync = vi.fn(() => {
      throw new Error("runtime panic");
    });
    const post = vi.fn();
    stubContentWindow({ __player: { seek: sync }, postMessage: post });

    expect(() => player.seek(12.5)).not.toThrow();
    expect(post).toHaveBeenCalledWith(expect.objectContaining({ action: "seek" }), "*");
  });

  it("updates _currentTime regardless of which path is taken", () => {
    // `_currentTime` is the parent-side cache that drives controls and parent
    // proxy mirroring. It must update unconditionally — otherwise scrubs on a
    // cross-origin embed leave the controls UI showing stale time.
    const sync = vi.fn();
    stubContentWindow({ __player: { seek: sync } });
    player.seek(8.25);
    expect(player._currentTime).toBe(8.25);

    // Reset and verify the fallback path produces the same caching behavior.
    stubContentWindow({ postMessage: vi.fn() });
    player.seek(11);
    expect(player._currentTime).toBe(11);
  });
});

describe("HyperframesPlayer loop end-state handling", () => {
  type PlayerInternal = HTMLElement & {
    iframe: HTMLIFrameElement;
    play: () => void;
    pause: () => void;
    seek: (timeInSeconds: number) => void;
    loop: boolean;
    _duration: number;
    _currentTime: number;
    _paused: boolean;
    _ready: boolean;
    _assetsReady: boolean;
    _onMessage: (event: MessageEvent) => void;
  };

  let player: PlayerInternal;
  let frameWindow: Window;

  beforeEach(async () => {
    await import("./hyperframes-player.js");
    player = document.createElement("hyperframes-player") as PlayerInternal;
    frameWindow = window;
    vi.spyOn(frameWindow, "postMessage").mockImplementation(() => undefined);
    Object.defineProperty(player.iframe, "contentWindow", {
      configurable: true,
      get: () => frameWindow,
    });
    document.body.appendChild(player);
  });

  afterEach(() => {
    player.remove();
    vi.restoreAllMocks();
  });

  it("wraps and keeps playing when a looping composition posts its final paused state", () => {
    const seek = vi.spyOn(player, "seek");
    const play = vi.spyOn(player, "play");
    player.loop = true;
    player._duration = 4;
    player._paused = false;

    player._onMessage(
      new MessageEvent("message", {
        source: frameWindow,
        data: {
          source: "hf-preview",
          type: "state",
          frame: 120,
          isPlaying: false,
        },
      }),
    );

    expect(seek).toHaveBeenCalledWith(0);
    expect(play).toHaveBeenCalled();
    expect(player._paused).toBe(false);
    expect(player._currentTime).toBe(0);
  });

  it("fires ended and stays paused when a non-looping composition posts its final paused state", () => {
    const seek = vi.spyOn(player, "seek");
    const play = vi.spyOn(player, "play");
    const ended = vi.fn();
    player.addEventListener("ended", ended);
    player.loop = false;
    player._duration = 4;
    player._paused = false;

    player._onMessage(
      new MessageEvent("message", {
        source: frameWindow,
        data: {
          source: "hf-preview",
          type: "state",
          frame: 120,
          isPlaying: false,
        },
      }),
    );

    expect(seek).not.toHaveBeenCalled();
    expect(play).not.toHaveBeenCalled();
    expect(ended).toHaveBeenCalledTimes(1);
    expect(player._paused).toBe(true);
  });

  function postState(frame: number, isPlaying: boolean, currentTime?: number, ended = false) {
    player._onMessage(
      new MessageEvent("message", {
        source: frameWindow,
        data: { source: "hf-preview", type: "state", frame, currentTime, ended, isPlaying },
      }),
    );
  }

  // 4.97 s at 30 fps is 149.1 frames: the runtime posts frame 149 both at its end and
  // on a pause just before it. Its `ended` flag tells the two apart, and the player's
  // length can sit a float step past the runtime's end (0.48 + 4.49 here).
  it("ends a film when the runtime reports its end, even a float step short of the length", () => {
    const ended = vi.fn();
    player.addEventListener("ended", ended);
    player.loop = false;
    player._duration = 0.48 + 4.49;
    player._paused = false;

    postState(149, true, 4.96);
    expect(ended).not.toHaveBeenCalled();

    postState(149, false, 4.97, true);
    expect(ended).toHaveBeenCalledTimes(1);
    expect(player._currentTime).toBe(player._duration);
  });

  it("takes a length under a second from the runtime and ends there", () => {
    const ended = vi.fn();
    player.addEventListener("ended", ended);
    player.loop = false;
    player._onMessage(
      new MessageEvent("message", {
        source: frameWindow,
        data: { source: "hf-preview", type: "timeline", durationSeconds: 0.2, durationInFrames: 6 },
      }),
    );
    expect(player._duration).toBe(0.2);
    player._paused = false;

    postState(6, false, 0.2, true);

    expect(ended).toHaveBeenCalledTimes(1);
    expect(player._currentTime).toBe(0.2);
  });

  it("loops a film whose length falls between two frames", () => {
    const seek = vi.spyOn(player, "seek");
    player.loop = true;
    player._duration = 4.97;
    player._paused = false;

    postState(149, false, 4.97, true);

    expect(seek).toHaveBeenCalledWith(0);
    expect(player._paused).toBe(false);
  });

  it("keeps a pause the runtime marks as not ended, even at exactly the length", () => {
    const ended = vi.fn();
    const seek = vi.spyOn(player, "seek");
    player.addEventListener("ended", ended);
    player._duration = 4.97;

    for (const loop of [false, true]) {
      player.loop = loop;
      player._paused = false;
      postState(149, false, 4.97, false);

      expect(ended).not.toHaveBeenCalled();
      expect(seek).not.toHaveBeenCalled();
      expect(player._paused).toBe(true);
    }
  });

  it("ends or loops a film the runtime plays past the length without ever reporting its end", () => {
    const ended = vi.fn();
    const seek = vi.spyOn(player, "seek");
    player.addEventListener("ended", ended);
    player._duration = 1;

    player.loop = true;
    player._paused = false;
    postState(31, true, 1.02, false);
    expect(seek).toHaveBeenCalledWith(0);

    player.loop = false;
    player._paused = false;
    postState(31, true, 1.02, false);
    expect(ended).toHaveBeenCalledTimes(1);
  });

  it("leaves a film paused at its end alone when the runtime keeps reporting the end", () => {
    const ended = vi.fn();
    const seek = vi.spyOn(player, "seek");
    player.addEventListener("ended", ended);
    player.loop = true;
    player._duration = 4.97;
    player._paused = true;

    postState(149, false, 4.97, true);

    expect(ended).not.toHaveBeenCalled();
    expect(seek).not.toHaveBeenCalled();
    expect(player._paused).toBe(true);
  });

  it("keeps a pause from inside the composition on the last frame", () => {
    const ended = vi.fn();
    const seek = vi.spyOn(player, "seek");
    player.addEventListener("ended", ended);
    player.loop = true;
    player._duration = 4.97;
    player._paused = false;

    postState(149, false, 4.95);

    expect(ended).not.toHaveBeenCalled();
    expect(seek).not.toHaveBeenCalled();
    expect(player._paused).toBe(true);
    expect(player._currentTime).toBe(4.95);
  });

  it("resumes where a host pause on the last frame left it", () => {
    player._duration = 4.97;
    player._paused = false;
    player.pause();
    postState(149, false, 4.95);
    const seek = vi.spyOn(player, "seek");

    player.play();

    expect(seek).not.toHaveBeenCalled();
    expect(player._currentTime).toBe(4.95);
  });

  it("play() seeks to 0 and replays when called after the video has ended", () => {
    const seek = vi.spyOn(player, "seek");
    player.loop = false;
    player._duration = 4;
    player._paused = false;

    player._onMessage(
      new MessageEvent("message", {
        source: frameWindow,
        data: {
          source: "hf-preview",
          type: "state",
          frame: 120,
          isPlaying: false,
        },
      }),
    );

    expect(player._paused).toBe(true);
    seek.mockClear();

    player.play();

    expect(seek).toHaveBeenCalledWith(0);
    expect(player._paused).toBe(false);
  });

  it("play() does not seek to 0 when called mid-playback", () => {
    const seek = vi.spyOn(player, "seek");
    player._duration = 4;
    player._paused = true;
    // Simulate mid-video position (frame 60 = 2s into a 4s video)
    player._onMessage(
      new MessageEvent("message", {
        source: frameWindow,
        data: {
          source: "hf-preview",
          type: "state",
          frame: 60,
          isPlaying: false,
        },
      }),
    );

    player.play();

    expect(seek).not.toHaveBeenCalled();
    expect(player._paused).toBe(false);
  });

  it("rewinds and keeps playing when an ended listener calls play", () => {
    const seek = vi.spyOn(player, "seek");
    player._ready = true;
    player._assetsReady = true;
    player._duration = 4;
    player._paused = false;
    player.addEventListener("ended", () => player.play(), { once: true });

    player._onMessage(
      new MessageEvent("message", {
        source: frameWindow,
        data: { source: "hf-preview", type: "state", frame: 120, isPlaying: false },
      }),
    );

    expect(seek).toHaveBeenCalledWith(0);
    expect(player._currentTime).toBe(0);
    expect(player._paused).toBe(false);
  });

  it("clamps _currentTime to _duration when a state message reports a frame past the end", () => {
    // Regression test: the postMessage state path previously set _currentTime
    // without clamping, while the direct timeline path already clamped. A frame
    // count slightly past the end (common on final-frame messages) would set
    // _currentTime > _duration, causing the progress bar to overflow the
    // scrubber track and the time display to show e.g. "0:05 / 0:04".
    player._duration = 4; // 4s = 120 frames at 30fps
    player._paused = false;

    player._onMessage(
      new MessageEvent("message", {
        source: frameWindow,
        data: {
          source: "hf-preview",
          type: "state",
          frame: 150, // 5s — past the 4s duration
          isPlaying: false,
        },
      }),
    );

    expect(player._currentTime).toBe(4);
  });
});

describe("HyperframesPlayer srcdoc attribute", () => {
  type PlayerInternal = HTMLElement & {
    iframe: HTMLIFrameElement;
    _ready: boolean;
  };

  beforeEach(async () => {
    await import("./hyperframes-player.js");
  });

  it("includes srcdoc in observedAttributes", () => {
    // `attributeChangedCallback` only fires for observed attributes. Without
    // this, runtime srcdoc swaps from studio would silently drop on the floor.
    const ctor = customElements.get("hyperframes-player") as
      | (typeof HTMLElement & { observedAttributes: string[] })
      | undefined;
    expect(ctor).toBeDefined();
    expect(ctor!.observedAttributes).toContain("srcdoc");
    expect(ctor!.observedAttributes).toContain("runtime-src");
  });

  it("uses a configured runtime source for loopback srcdoc", () => {
    const player = document.createElement("hyperframes-player") as PlayerInternal;
    player.setAttribute("srcdoc", "<!doctype html><html><head></head><body></body></html>");
    player.setAttribute("runtime-src", "http://127.0.0.1:8900/hyperframe.runtime.iife.js");

    expect(player.iframe.hasAttribute("srcdoc")).toBe(false);

    document.body.appendChild(player);

    expect(player.iframe.getAttribute("srcdoc")).toContain(
      '<script src="http://127.0.0.1:8900/hyperframe.runtime.iife.js"></script>',
    );

    player.remove();
  });

  it("falls back to the pinned runtime for a foreign-origin runtime source", () => {
    // A srcdoc frame inherits the embedder's origin under the default `allow-same-origin`,
    // so an attacker-controlled host would be script execution in the embedding page.
    const player = document.createElement("hyperframes-player") as PlayerInternal;
    player.setAttribute("runtime-src", "https://evil.example.com/hyperframe.runtime.iife.js");
    player.setAttribute("srcdoc", "<!doctype html><html><head></head><body></body></html>");
    document.body.appendChild(player);

    const srcdoc = player.iframe.getAttribute("srcdoc") ?? "";
    expect(srcdoc).not.toContain("evil.example.com");
    expect(srcdoc).toContain("hyperframe.runtime.iife.js");

    player.remove();
  });

  it("falls back to the pinned runtime for an unsafe runtime source", () => {
    const player = document.createElement("hyperframes-player") as PlayerInternal;
    player.setAttribute("runtime-src", 'javascript:alert("no")');
    player.setAttribute("srcdoc", "<!doctype html><html><head></head><body></body></html>");
    document.body.appendChild(player);

    const srcdoc = player.iframe.getAttribute("srcdoc") ?? "";
    expect(srcdoc).not.toContain("javascript:");
    expect(srcdoc).toContain("hyperframe.runtime.iife.js");

    player.remove();
  });

  it("forwards an initial srcdoc attribute to the iframe on connect", () => {
    // Studio's primary use case: render the player with composition HTML
    // already in hand, no network round-trip. Setting the attribute before
    // the element is connected must still apply on connect.
    const player = document.createElement("hyperframes-player") as PlayerInternal;
    const html = "<!doctype html><html><body>hello</body></html>";
    player.setAttribute("srcdoc", html);
    document.body.appendChild(player);

    // Not byte-identical: srcdoc now also carries the runtime, injected ahead
    // of body scripts so a pasted component can read its variables during
    // parse. The composition itself must still arrive intact.
    expect(player.iframe.getAttribute("srcdoc")).toContain("<body>hello</body>");
    expect(player.iframe.getAttribute("srcdoc")).toContain("hyperframe.runtime.iife.js");

    player.remove();
  });

  it("does not navigate initial srcdoc before the runtime listener is connected", () => {
    // React assigns custom-element attributes before inserting the element. If the observed
    // attribute callback navigates the child iframe immediately, a fast srcdoc runtime can post
    // its one-shot `ready` message before connectedCallback subscribes to `window.message`.
    // Retained runtime data then waits forever and a caption style appears stuck on its bootstrap
    // frame. The connect path owns the first navigation; attributeChangedCallback owns only
    // subsequent swaps.
    const player = document.createElement("hyperframes-player") as PlayerInternal;
    player.setAttribute("srcdoc", "<!doctype html><html><body>deferred</body></html>");

    expect(player.iframe.hasAttribute("srcdoc")).toBe(false);

    document.body.appendChild(player);
    expect(player.iframe.getAttribute("srcdoc")).toContain("<body>deferred</body>");

    player.remove();
  });

  it("does not navigate initial src before the runtime listener is connected", () => {
    const player = document.createElement("hyperframes-player") as PlayerInternal;
    player.setAttribute("src", "/api/projects/deferred/preview");

    expect(player.iframe.hasAttribute("src")).toBe(false);

    document.body.appendChild(player);
    expect(player.iframe.getAttribute("src")).toBe("/api/projects/deferred/preview");

    player.remove();
  });

  it("forwards a srcdoc attribute set after connect to the iframe", () => {
    // The composition-switching flow: same player element, new HTML.
    // Without `attributeChangedCallback` wiring this would no-op.
    const player = document.createElement("hyperframes-player") as PlayerInternal;
    document.body.appendChild(player);

    const html = "<!doctype html><html><body>after connect</body></html>";
    player.setAttribute("srcdoc", html);

    expect(player.iframe.getAttribute("srcdoc")).toContain("<body>after connect</body>");
    expect(player.iframe.getAttribute("srcdoc")).toContain("hyperframe.runtime.iife.js");

    player.remove();
  });

  it("resets _ready when srcdoc changes so onIframeLoad replays setup", () => {
    // The ready flag gates probe intervals, controls hookup, and poster
    // tear-down. Switching documents must invalidate it so the next `load`
    // event re-runs that setup against the fresh window.
    const player = document.createElement("hyperframes-player") as PlayerInternal;
    document.body.appendChild(player);
    player._ready = true;

    player.setAttribute("srcdoc", "<!doctype html><html></html>");

    expect(player._ready).toBe(false);

    player.remove();
  });

  it("removes iframe.srcdoc when the attribute is removed so src can take over", () => {
    // Per HTML spec, iframe.srcdoc beats iframe.src whenever both are
    // present. Studio's fetch-fail fallback path needs srcdoc cleared so
    // setting src afterwards actually navigates to that URL.
    const player = document.createElement("hyperframes-player") as PlayerInternal;
    player.setAttribute("srcdoc", "<!doctype html><html></html>");
    document.body.appendChild(player);
    expect(player.iframe.hasAttribute("srcdoc")).toBe(true);

    player.removeAttribute("srcdoc");

    expect(player.iframe.hasAttribute("srcdoc")).toBe(false);

    player.remove();
  });

  it("treats an empty-string srcdoc as a deliberate empty document, not removal", () => {
    // `setAttribute("srcdoc", "")` and `removeAttribute("srcdoc")` send
    // different signals from the caller — empty string means "load a blank
    // doc," removal means "fall back to src." We have to distinguish them.
    const player = document.createElement("hyperframes-player") as PlayerInternal;
    document.body.appendChild(player);

    player.setAttribute("srcdoc", "");

    expect(player.iframe.hasAttribute("srcdoc")).toBe(true);
    expect(player.iframe.getAttribute("srcdoc")).toBe("");

    player.remove();
  });

  it("forwards both src and srcdoc to the iframe and lets the browser arbitrate", () => {
    // We deliberately don't strip src when srcdoc is set: the HTML spec
    // already says srcdoc wins, and keeping both lets the browser fall back
    // to src automatically if the embed re-renders without srcdoc.
    const player = document.createElement("hyperframes-player") as PlayerInternal;
    player.setAttribute("src", "/api/projects/foo/preview");
    player.setAttribute("srcdoc", "<!doctype html><html></html>");
    document.body.appendChild(player);

    expect(player.iframe.getAttribute("src")).toBe("/api/projects/foo/preview");
    // srcdoc carries the runtime now; what matters here is that both
    // attributes are present so the browser can arbitrate.
    expect(player.iframe.getAttribute("srcdoc")).toContain("<html>");

    player.remove();
  });
});

// ── Volume / Mute controls ──

describe("HyperframesPlayer volume and mute", () => {
  let player: HTMLElement & {
    muted: boolean;
    volume: number;
    iframeElement: HTMLIFrameElement;
  };
  let mockAudio: {
    preload: string;
    src: string;
    muted: boolean;
    volume: number;
    playbackRate: number;
    currentTime: number;
    load: ReturnType<typeof vi.fn>;
    play: ReturnType<typeof vi.fn>;
    pause: ReturnType<typeof vi.fn>;
  };

  beforeEach(async () => {
    await import("./hyperframes-player.js");

    mockAudio = {
      preload: "",
      src: "",
      muted: false,
      volume: 1,
      playbackRate: 1,
      currentTime: 0,
      load: vi.fn(),
      play: vi.fn().mockResolvedValue(undefined),
      pause: vi.fn(),
    };
    vi.spyOn(globalThis, "Audio").mockImplementation(function () {
      return mockAudio as unknown as HTMLAudioElement;
    });

    player = document.createElement("hyperframes-player") as typeof player;
  });

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

  it("defaults volume to 1", () => {
    document.body.appendChild(player);
    expect(player.volume).toBe(1);
  });

  it("sets volume on parent media when audio-src is configured", () => {
    player.setAttribute("volume", "0.5");
    player.setAttribute("audio-src", "https://cdn.example.com/narration.mp3");
    document.body.appendChild(player);

    expect(mockAudio.volume).toBe(0.5);
  });

  it("updates parent media volume when volume attribute changes", () => {
    player.setAttribute("audio-src", "https://cdn.example.com/narration.mp3");
    document.body.appendChild(player);

    player.setAttribute("volume", "0.3");
    expect(mockAudio.volume).toBe(0.3);
  });

  it("clamps volume to [0, 1]", () => {
    document.body.appendChild(player);

    player.volume = 1.5;
    expect(player.volume).toBe(1);

    player.volume = -0.5;
    expect(player.volume).toBe(0);
  });

  it("dispatches volumechange event when volume changes", () => {
    document.body.appendChild(player);

    const handler = vi.fn();
    player.addEventListener("volumechange", handler);

    player.setAttribute("volume", "0.7");
    expect(handler).toHaveBeenCalledTimes(1);
  });

  it("muted property toggles the muted attribute", () => {
    document.body.appendChild(player);

    player.muted = true;
    expect(player.hasAttribute("muted")).toBe(true);

    player.muted = false;
    expect(player.hasAttribute("muted")).toBe(false);
  });

  it("muted property directly mutes same-origin iframe media", () => {
    document.body.appendChild(player);
    const doc = document.implementation.createHTMLDocument("composition");
    const video = doc.createElement("video");
    const authoredMuted = doc.createElement("audio");
    authoredMuted.defaultMuted = true;
    doc.body.append(video, authoredMuted);
    stubIframeContentDocument(player.iframeElement, doc);

    player.muted = true;
    expect(video.muted).toBe(true);
    expect(authoredMuted.muted).toBe(true);

    player.muted = false;
    expect(video.muted).toBe(false);
    expect(authoredMuted.muted).toBe(true);
  });

  it("muted property mutes iframe-realm media elements", () => {
    document.body.appendChild(player);
    const { doc, video, audio } = createForeignFrameMediaDocument();
    audio.defaultMuted = true;
    stubIframeContentDocument(player.iframeElement, doc);

    player.muted = true;
    expect(video.muted).toBe(true);
    expect(audio.muted).toBe(true);

    player.muted = false;
    expect(video.muted).toBe(false);
    expect(audio.muted).toBe(true);
  });

  it("sends set-volume control to iframe", () => {
    document.body.appendChild(player);

    const postMessageSpy = vi.fn();
    Object.defineProperty(player.iframeElement, "contentWindow", {
      value: { postMessage: postMessageSpy },
      configurable: true,
    });

    player.setAttribute("volume", "0.6");
    expect(postMessageSpy).toHaveBeenCalledWith(
      expect.objectContaining({
        source: "hf-parent",
        type: "control",
        action: "set-volume",
        volume: 0.6,
      }),
      "*",
    );
  });

  it("controls bar shows mute button when controls are enabled", () => {
    player.setAttribute("controls", "");
    document.body.appendChild(player);

    const shadow = player.shadowRoot!;
    const muteBtn = shadow.querySelector(".hfp-mute-btn");
    expect(muteBtn).toBeTruthy();
    expect(muteBtn?.getAttribute("aria-label")).toBe("Mute");
  });

  it("controls bar shows volume slider when controls are enabled", () => {
    player.setAttribute("controls", "");
    document.body.appendChild(player);

    const shadow = player.shadowRoot!;
    const slider = shadow.querySelector(".hfp-volume-slider");
    expect(slider).toBeTruthy();
  });

  it("volume slider has ARIA slider attributes", () => {
    player.setAttribute("controls", "");
    document.body.appendChild(player);

    const shadow = player.shadowRoot!;
    const slider = shadow.querySelector(".hfp-volume-slider")!;
    expect(slider.getAttribute("role")).toBe("slider");
    expect(slider.getAttribute("aria-label")).toBe("Volume");
    expect(slider.getAttribute("aria-valuemin")).toBe("0");
    expect(slider.getAttribute("aria-valuemax")).toBe("100");
    expect(slider.getAttribute("aria-valuenow")).toBe("100");
    expect(slider.getAttribute("tabindex")).toBe("0");
  });

  it("removes and recreates one controls bar when the controls attribute toggles", () => {
    document.body.appendChild(player);

    player.setAttribute("controls", "");
    expect(player.shadowRoot!.querySelectorAll(".hfp-controls")).toHaveLength(1);

    player.removeAttribute("controls");
    expect(player.shadowRoot!.querySelectorAll(".hfp-controls")).toHaveLength(0);

    player.setAttribute("controls", "");
    expect(player.shadowRoot!.querySelectorAll(".hfp-controls")).toHaveLength(1);
  });

  it("dispatches volumechange when muted toggles (HTML5 spec)", () => {
    document.body.appendChild(player);

    const handler = vi.fn();
    player.addEventListener("volumechange", handler);

    player.muted = true;
    expect(handler).toHaveBeenCalledTimes(1);

    player.muted = false;
    expect(handler).toHaveBeenCalledTimes(2);
  });

  it("muted icon differs from volume=0 unmuted icon", () => {
    player.setAttribute("controls", "");
    document.body.appendChild(player);

    const shadow = player.shadowRoot!;
    const muteBtn = shadow.querySelector(".hfp-mute-btn")!;

    player.setAttribute("volume", "0");
    const zeroVolumeHtml = muteBtn.innerHTML;

    player.muted = true;
    const mutedHtml = muteBtn.innerHTML;

    expect(zeroVolumeHtml).not.toBe(mutedHtml);
  });
});

// ── Audio lock ──

describe("HyperframesPlayer audio lock", () => {
  let player: HTMLElement & { muted: boolean; audioLocked: boolean };

  beforeEach(async () => {
    await import("./hyperframes-player.js");
    player = document.createElement("hyperframes-player") as typeof player;
  });

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

  it("audioLocked property toggles the audio-locked attribute", () => {
    document.body.appendChild(player);

    player.audioLocked = true;
    expect(player.hasAttribute("audio-locked")).toBe(true);

    player.audioLocked = false;
    expect(player.hasAttribute("audio-locked")).toBe(false);
  });

  it("forces muted when audio-locked is set", () => {
    document.body.appendChild(player);
    expect(player.hasAttribute("muted")).toBe(false);

    player.setAttribute("audio-locked", "");
    expect(player.muted).toBe(true);
    expect(player.hasAttribute("muted")).toBe(true);
  });

  it("re-asserts mute when something tries to unmute while locked", () => {
    document.body.appendChild(player);
    player.setAttribute("audio-locked", "");

    // Direct property unmute
    player.muted = false;
    expect(player.hasAttribute("muted")).toBe(true);

    // Raw attribute removal
    player.removeAttribute("muted");
    expect(player.hasAttribute("muted")).toBe(true);
  });

  it("allows unmute again once unlocked", () => {
    document.body.appendChild(player);
    player.setAttribute("audio-locked", "");
    expect(player.muted).toBe(true);

    // Unlock does NOT auto-unmute — it only lifts the restriction.
    player.removeAttribute("audio-locked");
    expect(player.muted).toBe(true);

    // Now the viewer/host can unmute.
    player.muted = false;
    expect(player.hasAttribute("muted")).toBe(false);
  });

  it("hides the volume controls when locked after controls exist", () => {
    player.setAttribute("controls", "");
    document.body.appendChild(player);

    const volumeWrap = player.shadowRoot!.querySelector(".hfp-volume-wrap") as HTMLElement;
    expect(volumeWrap.style.display).not.toBe("none");

    player.setAttribute("audio-locked", "");
    expect(volumeWrap.style.display).toBe("none");
  });

  it("hides the volume controls when controls are created while already locked", () => {
    player.setAttribute("audio-locked", "");
    player.setAttribute("controls", "");
    document.body.appendChild(player);

    const volumeWrap = player.shadowRoot!.querySelector(".hfp-volume-wrap") as HTMLElement;
    expect(volumeWrap.style.display).toBe("none");
  });

  it("restores the volume controls when unlocked", () => {
    player.setAttribute("controls", "");
    player.setAttribute("audio-locked", "");
    document.body.appendChild(player);

    const volumeWrap = player.shadowRoot!.querySelector(".hfp-volume-wrap") as HTMLElement;
    expect(volumeWrap.style.display).toBe("none");

    player.removeAttribute("audio-locked");
    expect(volumeWrap.style.display).not.toBe("none");
  });
});

describe("HyperframesPlayer runtime ready handshake", () => {
  // When the iframe runtime announces `{type: "ready"}` the player replays
  // current bridge state (muted, volume, playback rate) so any control message
  // that arrived before the iframe runtime registered its listener isn't lost.
  // This fixes a deterministic race on warm-cache reloads of claude.ai and
  // inside the Claude desktop Electron client where the iframe finishes
  // loading after the player has already set audio-locked.
  interface PlayerInternal extends HTMLElement {
    muted: boolean;
    volume: number;
    audioLocked: boolean;
    playbackRate: number;
    ready: boolean;
    duration: number;
    paused: boolean;
    compositionWidth: number;
    compositionHeight: number;
    scenes: Array<{ id: string; start: number; duration: number }>;
    iframe: HTMLIFrameElement;
    play: () => void;
    pause: () => void;
    seek: (t: number) => void;
    _onMessage: (event: MessageEvent) => void;
    _onProbeReady: (r: {
      duration: number;
      adapter: { kind: string; getDuration: () => number };
      compositionSize: { width: number; height: number } | null;
    }) => void;
    _onIframeLoad: () => void;
    _runtimeBridgeReady: boolean;
  }

  let player: PlayerInternal;
  let frameWindow: Window;
  let postSpy: MockInstance<typeof window.postMessage>;

  function readyMessage() {
    return new MessageEvent("message", {
      source: frameWindow,
      data: { source: "hf-preview", type: "ready" },
    });
  }

  function timelineMessage(durationInFrames = 120, extra: Record<string, unknown> = {}) {
    return new MessageEvent("message", {
      source: frameWindow,
      data: {
        source: "hf-preview",
        type: "timeline",
        durationInFrames,
        scenes: [],
        ...extra,
      },
    });
  }

  function stageSizeMessage(width: number, height: number) {
    return new MessageEvent("message", {
      source: frameWindow,
      data: { source: "hf-preview", type: "stage-size", width, height },
    });
  }

  function findControlCalls(action: string) {
    return postSpy.mock.calls.filter((call) => {
      const data = call[0] as { type?: string; action?: string };
      return data?.type === "control" && data?.action === action;
    });
  }

  beforeEach(async () => {
    await import("./hyperframes-player.js");
    player = document.createElement("hyperframes-player") as PlayerInternal;
    frameWindow = window;
    postSpy = vi.spyOn(frameWindow, "postMessage").mockImplementation(() => undefined);
    Object.defineProperty(player.iframe, "contentWindow", {
      configurable: true,
      get: () => frameWindow,
    });
    document.body.appendChild(player);
  });

  afterEach(() => {
    player.remove();
    vi.restoreAllMocks();
  });

  it("replays current muted state when runtime emits ready", () => {
    player.muted = true;
    postSpy.mockClear();

    player._onMessage(readyMessage());

    const muteCalls = findControlCalls("set-muted");
    expect(muteCalls).toHaveLength(1);
    expect(muteCalls[0]?.[0]).toMatchObject({
      source: "hf-parent",
      type: "control",
      action: "set-muted",
      muted: true,
    });
  });

  it("replays volume and playback-rate alongside muted", () => {
    player.volume = 0.5;
    player.playbackRate = 1.25;
    postSpy.mockClear();

    player._onMessage(readyMessage());

    expect(findControlCalls("set-muted")).toHaveLength(1);
    expect(findControlCalls("set-volume")[0]?.[0]).toMatchObject({
      action: "set-volume",
      volume: 0.5,
    });
    expect(findControlCalls("set-playback-rate")[0]?.[0]).toMatchObject({
      action: "set-playback-rate",
      playbackRate: 1.25,
    });
  });

  it("replays low-power-idle as a slow idle heartbeat, and a normal one without it", () => {
    postSpy.mockClear();
    player._onMessage(readyMessage());
    expect(findControlCalls("set-idle-heartbeat")[0]?.[0]).toMatchObject({ slow: false });

    player.setAttribute("low-power-idle", "");
    postSpy.mockClear();
    player._onMessage(readyMessage());
    expect(findControlCalls("set-idle-heartbeat")[0]?.[0]).toMatchObject({
      action: "set-idle-heartbeat",
      slow: true,
    });
  });

  it("sends low-power-idle to a ready runtime as soon as it changes", () => {
    player._onMessage(readyMessage());
    postSpy.mockClear();
    player.setAttribute("low-power-idle", "");
    expect(findControlCalls("set-idle-heartbeat")[0]?.[0]).toMatchObject({ slow: true });

    postSpy.mockClear();
    player.removeAttribute("low-power-idle");
    expect(findControlCalls("set-idle-heartbeat")[0]?.[0]).toMatchObject({ slow: false });
  });

  it("tells the runtime how large the frame shows, on fit and again on play", () => {
    Object.defineProperty(player, "offsetWidth", { configurable: true, value: 540 });
    Object.defineProperty(player, "offsetHeight", { configurable: true, value: 960 });
    // The frame's on-screen box, after the fit and any zoom the page puts around the player,
    // over its layout width, which a default size can hold before the stage size arrives.
    let shownWidth = 540;
    player.iframe.getBoundingClientRect = () => ({ width: shownWidth }) as DOMRect;
    Object.defineProperty(player.iframe, "offsetWidth", { configurable: true, value: 1080 });
    postSpy.mockClear();

    player._onMessage(stageSizeMessage(1080, 1920));
    expect(findControlCalls("set-display-scale").at(-1)?.[0]).toMatchObject({ scale: 0.5 });

    shownWidth = 1080;
    postSpy.mockClear();
    player.play();
    expect(findControlCalls("set-display-scale")[0]?.[0]).toMatchObject({ scale: 1 });
  });

  it("keeps runtime WebAudio media enabled outside slideshow embeds", () => {
    postSpy.mockClear();

    player._onMessage(readyMessage());

    expect(findControlCalls("set-native-media-sync-disabled")[0]?.[0]).toMatchObject({
      action: "set-native-media-sync-disabled",
      disabled: false,
    });
    expect(findControlCalls("set-web-audio-media-disabled")[0]?.[0]).toMatchObject({
      action: "set-web-audio-media-disabled",
      disabled: false,
    });
  });

  it("disables runtime WebAudio media inside slideshow embeds", () => {
    const slideshow = document.createElement("hyperframes-slideshow");
    slideshow.appendChild(player);
    document.body.appendChild(slideshow);
    postSpy.mockClear();

    player._onMessage(readyMessage());

    expect(findControlCalls("set-native-media-sync-disabled")[0]?.[0]).toMatchObject({
      action: "set-native-media-sync-disabled",
      disabled: true,
    });
    expect(findControlCalls("set-web-audio-media-disabled")[0]?.[0]).toMatchObject({
      action: "set-web-audio-media-disabled",
      disabled: true,
    });
    slideshow.remove();
  });

  it("replays the muted state forced by audio-locked", () => {
    // The audio-locked attribute is the original motivating case for this
    // handshake — its `muted = true` side effect must survive an iframe race.
    player.setAttribute("audio-locked", "");
    expect(player.muted).toBe(true);
    postSpy.mockClear();

    player._onMessage(readyMessage());

    const muteCalls = findControlCalls("set-muted");
    expect(muteCalls).toHaveLength(1);
    expect(muteCalls[0]?.[0]).toMatchObject({ action: "set-muted", muted: true });
  });

  it("replays again on a second ready (idempotent — iframe reloads emit again)", () => {
    player.muted = true;
    postSpy.mockClear();

    player._onMessage(readyMessage());
    player._onMessage(readyMessage());

    expect(findControlCalls("set-muted")).toHaveLength(2);
  });

  it("does not erase a DOMContentLoaded runtime handshake when iframe load follows it", () => {
    player._onMessage(readyMessage());
    expect(player._runtimeBridgeReady).toBe(true);

    player._onIframeLoad();

    expect(player._runtimeBridgeReady).toBe(true);
  });

  it("drops the runtime handshake when a shader-option change navigates the frame", () => {
    // The navigating sandbox path already clears readiness. This path navigates too, so a
    // delivery issued afterwards must not be posted into the document being replaced.
    player._onMessage(readyMessage());
    expect(player._runtimeBridgeReady).toBe(true);

    player.setAttribute("shader-capture-scale", "0.5");

    expect(player._runtimeBridgeReady).toBe(false);
  });

  it("ignores ready events from a different window", () => {
    postSpy.mockClear();
    const otherSource = {} as Window;

    player._onMessage(
      new MessageEvent("message", {
        source: otherSource,
        data: { source: "hf-preview", type: "ready" },
      }),
    );

    expect(findControlCalls("set-muted")).toHaveLength(0);
  });

  it("treats a cross-origin runtime timeline message as player ready", () => {
    const readyEvents: unknown[] = [];
    player.addEventListener("ready", (event) => {
      readyEvents.push((event as CustomEvent).detail);
    });

    player._onMessage(timelineMessage(120));

    expect(player.ready).toBe(true);
    expect(player.duration).toBe(4);
    expect(readyEvents).toEqual([{ duration: 4, compositionWidth: 1920, compositionHeight: 1080 }]);
  });

  it("reports the picture size in ready and as public properties", () => {
    const readyEvents: unknown[] = [];
    player.addEventListener("ready", (event) => {
      readyEvents.push((event as CustomEvent).detail);
    });

    player._onMessage(timelineMessage(120, { compositionWidth: 1080, compositionHeight: 1920 }));

    expect(readyEvents).toEqual([{ duration: 4, compositionWidth: 1080, compositionHeight: 1920 }]);
    expect(player.compositionWidth).toBe(1080);
    expect(player.compositionHeight).toBe(1920);
  });

  it("reports the picture size in ready on the same-origin probe path", () => {
    const readyEvents: unknown[] = [];
    player.addEventListener("ready", (event) => {
      readyEvents.push((event as CustomEvent).detail);
    });

    player._onProbeReady({
      duration: 5,
      adapter: { kind: "runtime", getDuration: () => 5 },
      compositionSize: { width: 1080, height: 1350 },
    });

    expect(readyEvents).toEqual([{ duration: 5, compositionWidth: 1080, compositionHeight: 1350 }]);
  });

  it("fires a timeline message's events only after the whole message is applied", () => {
    const seen: string[] = [];
    const state = () =>
      `ready=${player.ready} d=${player.duration} ` +
      `${player.compositionWidth}x${player.compositionHeight} scenes=${player.scenes.length}`;
    for (const type of ["resize", "scenes", "durationchange", "ready"]) {
      player.addEventListener(type, () => seen.push(`${type}: ${state()}`));
    }

    player._onMessage(
      timelineMessage(120, {
        compositionWidth: 1080,
        compositionHeight: 1920,
        scenes: [{ id: "a", start: 0, duration: 4 }],
      }),
    );
    seen.push("--");
    player._onMessage(
      timelineMessage(180, {
        compositionWidth: 1280,
        compositionHeight: 720,
        scenes: [
          { id: "a", start: 0, duration: 4 },
          { id: "b", start: 4, duration: 2 },
        ],
      }),
    );

    expect(seen).toEqual([
      "resize: ready=true d=4 1080x1920 scenes=1",
      "ready: ready=true d=4 1080x1920 scenes=1",
      "scenes: ready=true d=4 1080x1920 scenes=1",
      "--",
      "resize: ready=true d=6 1280x720 scenes=2",
      "durationchange: ready=true d=6 1280x720 scenes=2",
      "scenes: ready=true d=6 1280x720 scenes=2",
    ]);
  });

  it("keeps ready ahead of the events it causes on an opaque-origin timeline", () => {
    stubIframeContentDocument(player.iframe, null);
    player.setAttribute("autoplay", "");
    const seen: string[] = [];
    for (const type of ["ready", "assetsready", "play"]) {
      player.addEventListener(type, () => seen.push(type));
    }

    player._onMessage(timelineMessage(120));

    expect(seen).toEqual(["ready", "assetsready", "play"]);
  });

  it("fires an event a ready listener raises after the rest of the update", () => {
    stubIframeContentDocument(player.iframe, null);
    player.setAttribute("autoplay", "");
    const seen: string[] = [];
    for (const type of ["ready", "assetsready", "play", "pause"]) {
      player.addEventListener(type, () => seen.push(type));
    }
    player.addEventListener("ready", () => player.pause(), { once: true });

    player._onMessage(timelineMessage(120));

    // Autoplay is decided after `ready`'s listeners.
    expect(seen).toEqual(["ready", "assetsready", "pause", "play"]);
    expect(player.paused).toBe(false);
  });

  it("keeps autoplay when a ready listener seeks", () => {
    stubIframeContentDocument(player.iframe, null);
    player.setAttribute("autoplay", "");
    player.addEventListener("ready", () => player.seek(1), { once: true });

    player._onMessage(timelineMessage(120));

    expect(player.paused).toBe(false);
    expect(findControlCalls("play")).toHaveLength(1);
  });

  it("applies a message a listener delivers inside the update after the first one's events", () => {
    const seen: string[] = [];
    for (const type of ["ready", "durationchange", "scenes"]) {
      player.addEventListener(type, () => seen.push(`${type} d=${player.duration}`));
    }
    player.addEventListener("ready", () => player._onMessage(timelineMessage(180)), { once: true });

    player._onMessage(timelineMessage(120));

    expect(seen).toEqual(["ready d=4", "scenes d=6", "durationchange d=6", "scenes d=6"]);
  });

  it("runs the rest of an update's events when a listener throws", () => {
    stubIframeContentDocument(player.iframe, null);
    const seen: string[] = [];
    player.addEventListener("ready", () => {
      throw new Error("listener failed");
    });
    player.addEventListener("assetsready", () => seen.push("assetsready"));

    expect(() => player._onMessage(timelineMessage(120))).toThrow("listener failed");
    expect(seen).toEqual(["assetsready"]);
  });

  it("keeps raising events after an action throws inside an update", () => {
    stubIframeContentDocument(player.iframe, null);
    player.setAttribute("autoplay", "");
    vi.spyOn(player, "play").mockImplementationOnce(() => {
      throw new Error("play failed");
    });
    expect(() => player._onMessage(timelineMessage(120))).toThrow("play failed");
    const durations: number[] = [];
    player.addEventListener("durationchange", (event) => {
      durations.push((event as CustomEvent<{ duration: number }>).detail.duration);
    });

    player._onMessage(timelineMessage(180));

    expect(durations).toEqual([6]);
  });

  it("fires the probe path's resize only once ready is set", () => {
    const seen: string[] = [];
    player.addEventListener("resize", () => seen.push(`resize ready=${player.ready}`));

    player._onProbeReady({
      duration: 5,
      adapter: { kind: "runtime", getDuration: () => 5 },
      compositionSize: { width: 1080, height: 1350 },
    });

    expect(seen).toEqual(["resize ready=true"]);
  });

  it("warns when the same-origin probe readies a zero-size player", () => {
    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => undefined);

    player._onProbeReady({
      duration: 5,
      adapter: { kind: "runtime", getDuration: () => 5 },
      compositionSize: { width: 1080, height: 1920 },
    });

    const rescaleWarnings = warnSpy.mock.calls.filter((call) =>
      String(call[0]).includes("rescale no-op after ready"),
    );
    expect(rescaleWarnings).toHaveLength(1);
  });

  it("fires resize only when the picture size changes", () => {
    const sizes: unknown[] = [];
    player.addEventListener("resize", (event) => {
      sizes.push((event as unknown as CustomEvent).detail);
    });

    player._onMessage(timelineMessage(120, { compositionWidth: 1080, compositionHeight: 1920 }));
    player._onMessage(stageSizeMessage(1080, 1920));
    player._onMessage(stageSizeMessage(1280, 720));

    expect(sizes).toEqual([
      { compositionWidth: 1080, compositionHeight: 1920 },
      { compositionWidth: 1280, compositionHeight: 720 },
    ]);
  });

  it("fires durationchange when the duration changes after ready, not at ready", () => {
    const durations: number[] = [];
    player.addEventListener("durationchange", (event) => {
      durations.push((event as CustomEvent<{ duration: number }>).detail.duration);
    });

    player._onMessage(timelineMessage(120));
    player._onMessage(timelineMessage(120));
    player._onMessage(timelineMessage(180));

    expect(durations).toEqual([6]);
    expect(player.duration).toBe(6);
  });

  it("honors autoplay after cross-origin runtime timeline readiness", async () => {
    // A bare iframe fires its own async `load` a few ms after append, which
    // resets pending-play state (see createConnectedPlayer's comment below) —
    // await it first so it can't land mid-test during the readiness wait.
    await new Promise<void>((resolve) => {
      player.iframe.addEventListener("load", () => resolve(), { once: true });
    });
    player.setAttribute("autoplay", "");
    postSpy.mockClear();

    player._onMessage(timelineMessage(120));
    // The same-origin doc under test has no pending media, but play() is now
    // gated on paint-and-idle too — it queues until that settles. The gate
    // polls the real (unstubbed) iframe document's own window, not the
    // stubbed contentWindow used for postMessage.
    await awaitPaintAndIdle(player.iframe.contentDocument!.defaultView!);

    expect(player.paused).toBe(false);
    expect(findControlCalls("play")).toHaveLength(1);
  });

  it("rescales the iframe on cross-origin timeline readiness even without a stage-size message", () => {
    // Regression: the runtime's postTimeline() only sends `stage-size` when it
    // can resolve the root's data-width/data-height at that instant — a race
    // that can lose on first paint. onRuntimeTimelineReady must not depend on
    // stage-size having arrived, or the iframe is left unscaled/untranslated
    // (rendered pinned to the top-left instead of centered and fit).
    Object.defineProperty(player, "offsetWidth", { value: 400, configurable: true });
    Object.defineProperty(player, "offsetHeight", { value: 300, configurable: true });

    expect(player.iframe.style.transform).toBe("");

    player._onMessage(timelineMessage(120));

    expect(player.iframe.style.transform).not.toBe("");
    expect(player.iframe.style.transform).toContain("translate(-50%, -50%)");
  });

  it("warns at most once per instance when rescale keeps no-oping after ready", () => {
    // A player that stays zero-size after ready (hidden tab, collapsed
    // carousel card) keeps getting rescale attempts from every subsequent
    // width/height attribute change and ResizeObserver tick. The diagnostic
    // warning must not spam the console once per instance.
    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => undefined);

    player._onMessage(timelineMessage(120)); // first no-op after ready
    player.setAttribute("width", "800"); // still zero-size — would no-op again
    player.setAttribute("height", "450"); // ditto

    expect(warnSpy).toHaveBeenCalledTimes(1);
  });
});

describe("HyperframesPlayer audio lock — Claude desktop UA fallback", () => {
  // Some host renderers (observed on the Claude desktop Electron client) strip
  // unknown custom-element attributes before they reach the DOM, so the
  // `audio-locked` attribute is lost. The player self-imposes the lock based
  // on UA detection so chat-host audio stays muted even without the attribute.
  let player: HTMLElement & { muted: boolean; audioLocked: boolean };
  let originalUserAgent: PropertyDescriptor | undefined;

  function stubUserAgent(ua: string) {
    Object.defineProperty(navigator, "userAgent", {
      value: ua,
      configurable: true,
    });
  }

  beforeEach(async () => {
    originalUserAgent = Object.getOwnPropertyDescriptor(
      Object.getPrototypeOf(navigator),
      "userAgent",
    );
    await import("./hyperframes-player.js");
    player = document.createElement("hyperframes-player") as typeof player;
  });

  afterEach(() => {
    if (originalUserAgent) {
      Object.defineProperty(Object.getPrototypeOf(navigator), "userAgent", originalUserAgent);
    }
    vi.restoreAllMocks();
    document.body.innerHTML = "";
  });

  it("forces muted on Claude desktop UA even without the audio-locked attribute", () => {
    stubUserAgent(
      "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 " +
        "(KHTML, like Gecko) Claude/1.11187.4 Chrome/126.0.0.0 Electron/31.0.0 Safari/537.36",
    );

    document.body.appendChild(player);

    expect(player.hasAttribute("audio-locked")).toBe(false);
    expect(player.muted).toBe(true);
    expect(player.hasAttribute("muted")).toBe(true);
  });

  it("re-asserts mute on Claude desktop when something tries to unmute", () => {
    stubUserAgent("Claude/1.11187.4 Chrome/126.0.0.0 Electron/31.0.0");
    document.body.appendChild(player);

    player.muted = false;
    expect(player.hasAttribute("muted")).toBe(true);

    player.removeAttribute("muted");
    expect(player.hasAttribute("muted")).toBe(true);
  });

  it("hides the volume controls on Claude desktop without the attribute", () => {
    stubUserAgent("Claude/1.11187.4 Chrome/126.0.0.0 Electron/31.0.0");
    player.setAttribute("controls", "");
    document.body.appendChild(player);

    const volumeWrap = player.shadowRoot!.querySelector(".hfp-volume-wrap") as HTMLElement;
    expect(volumeWrap.style.display).toBe("none");
  });

  it("does NOT force mute on a regular browser UA", () => {
    stubUserAgent(
      "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 " +
        "(KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36",
    );

    document.body.appendChild(player);

    expect(player.hasAttribute("audio-locked")).toBe(false);
    expect(player.muted).toBe(false);
    expect(player.hasAttribute("muted")).toBe(false);
  });

  it("does NOT force mute on Electron apps that aren't Claude desktop", () => {
    // Other Electron clients (e.g. VS Code embedded view) shouldn't be muted.
    stubUserAgent(
      "Mozilla/5.0 (Macintosh) AppleWebKit/537.36 Chrome/126.0.0.0 Electron/31.0.0 Safari/537.36",
    );

    document.body.appendChild(player);

    expect(player.muted).toBe(false);
  });

  it("keeps `audioLocked` property reflecting only the attribute, not the UA fallback", () => {
    // External consumers (pacific widget, etc.) read `audioLocked` to mirror
    // their own state. The UA fallback is an internal safety net and must not
    // leak into the public property — otherwise unsetting `audioLocked` would
    // appear to have no effect from the consumer's perspective.
    stubUserAgent("Claude/1.11187.4 Chrome/126.0.0.0 Electron/31.0.0");
    document.body.appendChild(player);

    expect(player.audioLocked).toBe(false);
  });
});

// ── Playback rate ──

describe("HyperframesPlayer playback rate", () => {
  let player: HTMLElement & {
    playbackRate: number;
    iframeElement: HTMLIFrameElement;
  };
  let mockAudio: {
    preload: string;
    src: string;
    muted: boolean;
    volume: number;
    playbackRate: number;
    currentTime: number;
    load: ReturnType<typeof vi.fn>;
    play: ReturnType<typeof vi.fn>;
    pause: ReturnType<typeof vi.fn>;
  };

  beforeEach(async () => {
    await import("./hyperframes-player.js");

    mockAudio = {
      preload: "",
      src: "",
      muted: false,
      volume: 1,
      playbackRate: 1,
      currentTime: 0,
      load: vi.fn(),
      play: vi.fn().mockResolvedValue(undefined),
      pause: vi.fn(),
    };
    vi.spyOn(globalThis, "Audio").mockImplementation(function () {
      return mockAudio as unknown as HTMLAudioElement;
    });

    player = document.createElement("hyperframes-player") as typeof player;
  });

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

  it("defaults playbackRate to 1", () => {
    document.body.appendChild(player);
    expect(player.playbackRate).toBe(1);
  });

  it("clamps playbackRate to [0.1, 5]", () => {
    document.body.appendChild(player);

    player.playbackRate = 100;
    expect(player.playbackRate).toBe(5);
    // Assert the reflected attribute directly so the setter clamp is pinned
    // independently of the getter clamp.
    expect(player.getAttribute("playback-rate")).toBe("5");

    player.playbackRate = 0.01;
    expect(player.playbackRate).toBe(0.1);
    expect(player.getAttribute("playback-rate")).toBe("0.1");
  });

  it("falls back to 1 for a non-positive or non-finite playbackRate", () => {
    document.body.appendChild(player);

    player.playbackRate = -2;
    expect(player.playbackRate).toBe(1);
    expect(player.getAttribute("playback-rate")).toBe("1");

    player.playbackRate = 0;
    expect(player.playbackRate).toBe(1);

    player.playbackRate = NaN;
    expect(player.playbackRate).toBe(1);
  });

  it("propagates the clamped rate to parent media, never an out-of-range value", () => {
    player.setAttribute("audio-src", "https://cdn.example.com/narration.mp3");
    document.body.appendChild(player);

    player.setAttribute("playback-rate", "50");
    expect(mockAudio.playbackRate).toBe(5);

    player.setAttribute("playback-rate", "0.01");
    expect(mockAudio.playbackRate).toBe(0.1);
  });

  it("sends the clamped rate as a set-playback-rate control to the iframe", () => {
    document.body.appendChild(player);

    const postMessageSpy = vi.fn();
    Object.defineProperty(player.iframeElement, "contentWindow", {
      value: { postMessage: postMessageSpy },
      configurable: true,
    });

    player.setAttribute("playback-rate", "50");
    expect(postMessageSpy).toHaveBeenCalledWith(
      expect.objectContaining({
        source: "hf-parent",
        type: "control",
        action: "set-playback-rate",
        playbackRate: 5,
      }),
      "*",
    );
  });

  it("clamps an out-of-range value set directly via the attribute on read", () => {
    document.body.appendChild(player);

    player.setAttribute("playback-rate", "999");
    expect(player.playbackRate).toBe(5);
  });
});

// ── Composition dimension attributes ──
//
// width/height feed scaleIframeToFit's `w / compositionWidth` division. A
// non-numeric, zero, or negative attribute must fall back to the defaults
// instead of reaching the scale math as NaN (invalid `scale(NaN)` transform)
// or zero (division by zero) — both blank the player with no signal.

describe("HyperframesPlayer composition dimension attributes", () => {
  type PlayerWithDimensions = HTMLElement & {
    _compositionWidth?: number;
    _compositionHeight?: number;
  };

  let player: PlayerWithDimensions;

  beforeEach(async () => {
    await import("./hyperframes-player.js");
    player = document.createElement("hyperframes-player") as PlayerWithDimensions;
    document.body.appendChild(player);
  });

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

  it("applies a valid width and height", () => {
    player.setAttribute("width", "1280");
    player.setAttribute("height", "720");
    expect(player._compositionWidth).toBe(1280);
    expect(player._compositionHeight).toBe(720);
  });

  it("falls back to defaults for non-numeric values", () => {
    player.setAttribute("width", "abc");
    player.setAttribute("height", "abc");
    expect(player._compositionWidth).toBe(1920);
    expect(player._compositionHeight).toBe(1080);
  });

  it("falls back to defaults for zero", () => {
    player.setAttribute("width", "0");
    player.setAttribute("height", "0");
    expect(player._compositionWidth).toBe(1920);
    expect(player._compositionHeight).toBe(1080);
  });

  it("falls back to defaults for negative values", () => {
    player.setAttribute("width", "-500");
    player.setAttribute("height", "-500");
    expect(player._compositionWidth).toBe(1920);
    expect(player._compositionHeight).toBe(1080);
  });

  it("recovers the defaults when the attribute is removed", () => {
    player.setAttribute("width", "1280");
    player.removeAttribute("width");
    expect(player._compositionWidth).toBe(1920);
  });
});

describe("HyperframesPlayer video mode", () => {
  type VideoPlayer = HTMLElement & {
    play: () => void;
    pause: () => void;
    seek: (t: number) => void;
    currentTime: number;
    duration: number;
    paused: boolean;
    ready: boolean;
    muted: boolean;
    volume: number;
    playbackRate: number;
    iframeElement: HTMLIFrameElement;
    _onIframeLoad: () => void;
  };

  const FILM = "https://cdn.example.com/film.mp4";
  let player: VideoPlayer;
  let playSpy: MockInstance<HTMLMediaElement["play"]>;
  let frames: FrameRequestCallback[];

  function createPlayer(attrs: Record<string, string>): VideoPlayer {
    const el = document.createElement("hyperframes-player") as VideoPlayer;
    for (const [name, value] of Object.entries(attrs)) el.setAttribute(name, value);
    document.body.appendChild(el);
    return el;
  }

  function videoOf(el: VideoPlayer): HTMLVideoElement {
    const video = el.shadowRoot?.querySelector("video");
    if (!video) throw new Error("no <video> in the player");
    return video;
  }

  function setMedia(video: HTMLMediaElement, props: Record<string, unknown>) {
    for (const [name, value] of Object.entries(props)) {
      Object.defineProperty(video, name, { configurable: true, writable: true, value });
    }
  }

  function loadMetadata(video: HTMLVideoElement, duration = 6, width = 1080, height = 1920) {
    setMedia(video, { duration, videoWidth: width, videoHeight: height });
    video.dispatchEvent(new Event("durationchange"));
    video.dispatchEvent(new Event("loadedmetadata"));
  }

  function flushFrame() {
    const frame = frames.shift();
    if (!frame) throw new Error("no animation frame queued");
    frame(performance.now());
  }

  beforeEach(async () => {
    await import("./hyperframes-player.js");
    // Like a browser, play() and pause() flip `paused` at once; their events come later, if at all.
    playSpy = vi
      .spyOn(HTMLMediaElement.prototype, "play")
      .mockImplementation(function (this: HTMLMediaElement) {
        setMedia(this, { paused: false });
        return Promise.resolve();
      });
    vi.spyOn(HTMLMediaElement.prototype, "pause").mockImplementation(
      function (this: HTMLMediaElement) {
        setMedia(this, { paused: true });
      },
    );
    vi.spyOn(HTMLMediaElement.prototype, "load").mockImplementation(() => undefined);
    frames = [];
    vi.spyOn(window, "requestAnimationFrame").mockImplementation((callback) => {
      frames.push(callback);
      return frames.length;
    });
    player = createPlayer({ type: "video/mp4", src: FILM });
  });

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

  it("plays a video file in a <video playsinline>, not in the composition iframe", () => {
    const video = videoOf(player);

    expect(video.getAttribute("src")).toBe(FILM);
    expect(video.playsInline).toBe(true);
    expect(player.iframeElement.src).not.toContain("film.mp4");
    expect(player.iframeElement.hidden).toBe(true);
  });

  it("keeps a composition player free of any <video>", () => {
    const composition = createPlayer({ src: "https://cdn.example.com/index.html" });

    expect(composition.shadowRoot?.querySelector("video")).toBeNull();
    expect(composition.iframeElement.src).toContain("index.html");
  });

  it("fires ready with the video's duration and size", () => {
    const readies: unknown[] = [];
    player.addEventListener("ready", (event) => readies.push((event as CustomEvent).detail));

    loadMetadata(videoOf(player));

    expect(readies).toEqual([{ duration: 6, compositionWidth: 1080, compositionHeight: 1920 }]);
    expect(player.ready).toBe(true);
  });

  it("fires the video's first resize with the player already ready", () => {
    const seen: string[] = [];
    player.addEventListener("resize", () =>
      seen.push(`resize ready=${player.ready} d=${player.duration}`),
    );

    loadMetadata(videoOf(player));

    expect(seen).toEqual(["resize ready=true d=6"]);
  });

  it("stays ready when the hidden iframe finishes loading", () => {
    loadMetadata(videoOf(player));

    player._onIframeLoad();

    expect(player.ready).toBe(true);
    expect(player.duration).toBe(6);
  });

  it("drives the video with play, pause and seek", () => {
    const video = videoOf(player);
    loadMetadata(video);

    player.play();
    expect(playSpy).toHaveBeenCalledTimes(1);
    expect(player.paused).toBe(false);

    player.seek(2.5);
    expect(video.currentTime).toBe(2.5);
    expect(player.currentTime).toBe(2.5);
    expect(player.paused).toBe(true);
    expect(HTMLMediaElement.prototype.pause).toHaveBeenCalled();
  });

  it("reports time while playing and fires ended at the end", () => {
    const video = videoOf(player);
    loadMetadata(video);
    const times: number[] = [];
    let ended = 0;
    player.addEventListener("timeupdate", (event) =>
      times.push((event as CustomEvent<{ currentTime: number }>).detail.currentTime),
    );
    player.addEventListener("ended", () => ended++);

    player.play();
    setMedia(video, { currentTime: 6 });
    flushFrame();

    expect(times).toEqual([6]);
    expect(ended).toBe(1);
    expect(player.paused).toBe(true);
  });

  it("restarts at the end with loop instead of firing ended", () => {
    const video = videoOf(player);
    loadMetadata(video);
    player.setAttribute("loop", "");
    let ended = 0;
    player.addEventListener("ended", () => ended++);

    player.play();
    setMedia(video, { currentTime: 6 });
    flushFrame();

    expect(ended).toBe(0);
    expect(video.currentTime).toBe(0);
    expect(playSpy).toHaveBeenCalledTimes(2);
    expect(player.paused).toBe(false);
  });

  it("fires error at once with the video's error code", () => {
    const video = videoOf(player);
    const errors: unknown[] = [];
    player.addEventListener("error", (event) =>
      errors.push((event as unknown as CustomEvent).detail),
    );

    setMedia(video, { error: { code: 4, message: "Format not supported" } });
    video.dispatchEvent(new Event("error"));

    expect(errors).toEqual([{ message: "Format not supported", code: 4 }]);
  });

  it("fires durationchange and resize when the video changes after ready", () => {
    const video = videoOf(player);
    loadMetadata(video);
    const seen: string[] = [];
    player.addEventListener("durationchange", (event) =>
      seen.push(`duration ${(event as CustomEvent<{ duration: number }>).detail.duration}`),
    );
    player.addEventListener("resize", () => seen.push("resize"));

    setMedia(video, { duration: 8, videoWidth: 1920, videoHeight: 1080 });
    video.dispatchEvent(new Event("durationchange"));
    video.dispatchEvent(new Event("resize"));

    expect(seen).toEqual(["duration 8", "resize"]);
  });

  it("mirrors muted and volume onto the video", () => {
    const video = videoOf(player);

    player.muted = true;
    player.volume = 0.25;

    expect(video.muted).toBe(true);
    expect(video.volume).toBe(0.25);
  });

  it("plays on ready with autoplay", () => {
    const autoplay = createPlayer({ type: "video/mp4", src: FILM, autoplay: "", muted: "" });

    loadMetadata(videoOf(autoplay));

    expect(playSpy).toHaveBeenCalledTimes(1);
    expect(autoplay.paused).toBe(false);
  });

  it("reports a blocked play and lands paused", async () => {
    loadMetadata(videoOf(player));
    playSpy.mockRejectedValueOnce(new DOMException("blocked", "NotAllowedError"));
    const errors: unknown[] = [];
    player.addEventListener("playbackerror", (event) =>
      errors.push((event as CustomEvent<{ source: string }>).detail.source),
    );

    player.play();
    await Promise.resolve();
    await Promise.resolve();

    expect(errors).toEqual(["video"]);
    expect(player.paused).toBe(true);
  });

  it("ignores a play interrupted by pause", async () => {
    loadMetadata(videoOf(player));
    playSpy.mockRejectedValueOnce(new DOMException("interrupted", "AbortError"));
    const errors: unknown[] = [];
    player.addEventListener("playbackerror", (event) => errors.push(event));

    player.play();
    await Promise.resolve();
    await Promise.resolve();

    expect(errors).toEqual([]);
  });

  it("stops the composition probe when a composition player switches to video", () => {
    vi.useFakeTimers();
    try {
      const switching = createPlayer({ src: "https://cdn.example.com/index.html" });
      const errors: unknown[] = [];
      switching.addEventListener("error", (event) => errors.push(event));
      switching._onIframeLoad();

      switching.setAttribute("type", "video/mp4");
      vi.advanceTimersByTime(10_000);

      expect(errors).toEqual([]);
    } finally {
      vi.useRealTimers();
    }
  });

  it("keeps the playback rate across a new src", () => {
    player.playbackRate = 2;

    player.setAttribute("src", "https://cdn.example.com/other.mp4");

    expect(videoOf(player).defaultPlaybackRate).toBe(2);
    expect(videoOf(player).playbackRate).toBe(2);
  });

  it("leaves a playing video alone when a shader or sandbox option changes", () => {
    const video = videoOf(player);
    loadMetadata(video);
    player.seek(3);

    player.setAttribute("shader-capture-scale", "2");
    player.setAttribute("sandbox-origin", "");

    expect(player.currentTime).toBe(3);
    expect(player.ready).toBe(true);
  });

  it("follows a pause the page did not ask for, but not the one at the end", () => {
    const video = videoOf(player);
    loadMetadata(video);
    const pauses: Event[] = [];
    player.addEventListener("pause", (event) => pauses.push(event));

    player.play();
    setMedia(video, { paused: true, ended: true });
    video.dispatchEvent(new Event("pause"));
    expect(player.paused).toBe(false);

    setMedia(video, { ended: false });
    video.dispatchEvent(new Event("pause"));
    expect(player.paused).toBe(true);
    expect(pauses).toHaveLength(1);
  });

  it("ignores a pause event that lands after the player played again", () => {
    const video = videoOf(player);
    loadMetadata(video);
    player.play();
    player.seek(2);
    player.play();
    player.pause();
    player.play();
    const pauses: Event[] = [];
    player.addEventListener("pause", (event) => pauses.push(event));

    video.dispatchEvent(new Event("pause"));

    expect(player.paused).toBe(false);
    expect(pauses).toEqual([]);
  });

  it("follows a play the page did not ask for, but not a stale one", () => {
    const video = videoOf(player);
    loadMetadata(video);
    player.play();
    player.pause();
    video.dispatchEvent(new Event("play"));
    expect(player.paused).toBe(true);

    const plays: Event[] = [];
    player.addEventListener("play", (event) => plays.push(event));
    setMedia(video, { paused: false });
    video.dispatchEvent(new Event("play"));

    expect(player.paused).toBe(false);
    expect(plays).toHaveLength(1);
  });

  it("reads the paused frame from the video, not the last clock sample", () => {
    const withControls = createPlayer({ type: "video/mp4", src: FILM, controls: "" });
    const video = videoOf(withControls);
    loadMetadata(video);
    withControls.play();
    setMedia(video, { currentTime: 2.37 });

    withControls.pause();

    expect(withControls.currentTime).toBe(2.37);
    expect(withControls.shadowRoot?.textContent).toContain("0:02 / 0:06");
  });

  it("switches from a playing video to a composition paused", () => {
    const withControls = createPlayer({ type: "video/mp4", src: FILM, controls: "" });
    loadMetadata(videoOf(withControls));
    withControls.play();

    withControls.removeAttribute("type");

    expect(withControls.paused).toBe(true);
    expect(withControls.shadowRoot?.querySelector('[aria-label="Play"]')).not.toBeNull();
  });

  it("reports a load failure after play as error only", async () => {
    const video = videoOf(player);
    let reject: (error: unknown) => void = () => {};
    playSpy.mockImplementationOnce(() => new Promise((_resolve, fail) => (reject = fail)));
    const seen: string[] = [];
    for (const type of ["pause", "error", "playbackerror"]) {
      player.addEventListener(type, () => seen.push(type));
    }
    loadMetadata(video);
    player.play();

    video.dispatchEvent(new Event("error"));
    reject(new DOMException("no supported source", "NotSupportedError"));
    await Promise.resolve();
    await Promise.resolve();

    expect(seen).toEqual(["pause", "error"]);
  });

  it("reports a blocked play once when the page already paused", async () => {
    loadMetadata(videoOf(player));
    playSpy.mockRejectedValueOnce(new DOMException("blocked", "NotAllowedError"));
    const seen: string[] = [];
    for (const type of ["pause", "playbackerror"]) {
      player.addEventListener(type, () => seen.push(type));
    }

    player.play();
    player.pause();
    await Promise.resolve();
    await Promise.resolve();

    expect(seen).toEqual(["pause", "playbackerror"]);
  });

  it("ignores a blocked play that lands after the video was removed", async () => {
    let reject: (error: unknown) => void = () => {};
    playSpy.mockImplementationOnce(() => new Promise((_resolve, fail) => (reject = fail)));
    loadMetadata(videoOf(player));
    player.play();
    const seen: Event[] = [];
    player.addEventListener("playbackerror", (event) => seen.push(event));

    player.removeAttribute("type");
    reject(new DOMException("blocked", "NotAllowedError"));
    await Promise.resolve();
    await Promise.resolve();

    expect(seen).toEqual([]);
  });

  it("ignores a composition's late runtime message once it plays a video", () => {
    window.dispatchEvent(
      new MessageEvent("message", {
        source: player.iframeElement.contentWindow,
        data: { source: "hf-preview", type: "timeline", durationInFrames: 120, scenes: [] },
      }),
    );

    expect(player.ready).toBe(false);
    expect(player.duration).toBe(0);
  });

  it("gives srcdoc precedence over a video src", () => {
    loadMetadata(videoOf(player));
    player.play();

    player.setAttribute("srcdoc", "<p>composition</p>");

    expect(player.shadowRoot?.querySelector("video")).toBeNull();
    expect(player.iframeElement.hidden).toBe(false);
    expect(player.iframeElement.getAttribute("srcdoc")).toContain("composition");
  });

  it("plays the video src once srcdoc is removed", () => {
    const both = createPlayer({ type: "video/mp4", src: FILM, srcdoc: "<p>composition</p>" });
    expect(both.shadowRoot?.querySelector("video")).toBeNull();

    both.removeAttribute("srcdoc");
    loadMetadata(videoOf(both));
    both.play();

    expect(videoOf(both).getAttribute("src")).toBe(FILM);
    expect(playSpy).toHaveBeenCalledTimes(1);
    expect(both.paused).toBe(false);
  });

  it("reads the video type without regard to case or padding", () => {
    const upper = createPlayer({ type: " Video/MP4 ", src: FILM });

    expect(videoOf(upper).getAttribute("src")).toBe(FILM);
  });

  it("fires timeupdate with the exact frame before pause", () => {
    const video = videoOf(player);
    loadMetadata(video);
    player.play();
    setMedia(video, { currentTime: 2.37 });
    const seen: string[] = [];
    player.addEventListener("timeupdate", (event) =>
      seen.push(`timeupdate ${(event as CustomEvent<{ currentTime: number }>).detail.currentTime}`),
    );
    player.addEventListener("pause", () => seen.push("pause"));

    player.pause();

    expect(seen).toEqual(["timeupdate 2.37", "pause"]);
  });

  it("starts paused when srcdoc replaces a playing video", () => {
    loadMetadata(videoOf(player));
    player.play();

    player.setAttribute("srcdoc", "<p>composition</p>");

    expect(player.paused).toBe(true);
  });

  it("autoplays the video once srcdoc is removed from a playing composition", () => {
    const both = createPlayer({
      type: "video/mp4",
      src: FILM,
      srcdoc: "<p>composition</p>",
      autoplay: "",
      muted: "",
    });
    both.play();

    both.removeAttribute("srcdoc");
    loadMetadata(videoOf(both));

    expect(playSpy).toHaveBeenCalledTimes(1);
    expect(both.paused).toBe(false);
  });

  it("keeps a srcdoc composition when type changes under it", () => {
    const both = createPlayer({ type: "video/mp4", src: FILM, srcdoc: "<p>composition</p>" });
    window.dispatchEvent(
      new MessageEvent("message", {
        source: both.iframeElement.contentWindow,
        data: { source: "hf-preview", type: "timeline", durationInFrames: 120, scenes: [] },
      }),
    );
    expect(both.ready).toBe(true);

    both.removeAttribute("type");

    expect(both.ready).toBe(true);
  });

  it("shows a new src as paused at the start in the controls", () => {
    const withControls = createPlayer({ type: "video/mp4", src: FILM, controls: "" });
    const video = videoOf(withControls);
    loadMetadata(video);
    withControls.play();
    withControls.seek(3);
    withControls.play();
    expect(withControls.shadowRoot?.textContent).toContain("0:03 / 0:06");

    // As in a browser, the new source has no duration until its metadata loads.
    setMedia(video, { duration: Number.NaN });
    withControls.setAttribute("src", "https://cdn.example.com/other.mp4");

    const playButton = withControls.shadowRoot?.querySelector('[aria-label="Play"]');
    expect(playButton).not.toBeNull();
    expect(withControls.shadowRoot?.textContent).toContain("0:00 / 0:00");
    expect(withControls.duration).toBe(0);
  });

  it("stops playing when the video fails", () => {
    const video = videoOf(player);
    loadMetadata(video);
    player.play();

    video.dispatchEvent(new Event("error"));

    expect(player.paused).toBe(true);
  });

  it("removes the video when the player leaves the page and brings it back on return", () => {
    player.remove();
    expect(player.shadowRoot?.querySelector("video")).toBeNull();
    expect(player.iframeElement.hidden).toBe(false);

    document.body.appendChild(player);
    expect(videoOf(player).getAttribute("src")).toBe(FILM);
  });

  it("goes back to a composition when the video type is removed", () => {
    player.removeAttribute("type");

    expect(player.shadowRoot?.querySelector("video")).toBeNull();
    expect(player.iframeElement.hidden).toBe(false);
    expect(player.iframeElement.src).toContain("film.mp4");
  });
});

// Video mode must leave a player without a video type exactly as it was.
describe("HyperframesPlayer composition behaviour outside video mode", () => {
  type CompositionPlayer = HTMLElement & {
    play: () => void;
    pause: () => void;
    currentTime: number;
    paused: boolean;
    iframeElement: HTMLIFrameElement;
    _currentTime: number;
    _directTimelineAdapter: unknown;
  };
  const COMPOSITION = "composition.html";

  function createPlayer(attrs: Record<string, string>): CompositionPlayer {
    const el = document.createElement("hyperframes-player") as CompositionPlayer;
    for (const [name, value] of Object.entries(attrs)) el.setAttribute(name, value);
    document.body.appendChild(el);
    return el;
  }

  beforeEach(async () => {
    await import("./hyperframes-player.js");
  });

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

  it("does not reset paused when a composition src changes", () => {
    const player = createPlayer({ src: COMPOSITION });
    player.play();

    player.setAttribute("src", "other-composition.html");

    expect(player.paused).toBe(false);
  });

  it("keeps the last clock sample when a direct timeline pauses", () => {
    const player = createPlayer({ src: COMPOSITION });
    player._directTimelineAdapter = {
      duration: () => 6,
      time: () => 2.37,
      seek: () => {},
      play: () => {},
      pause: () => {},
    };
    player._currentTime = 1;
    const updates: Event[] = [];
    player.addEventListener("timeupdate", (event) => updates.push(event));

    player.pause();

    expect(player.currentTime).toBe(1);
    expect(updates).toEqual([]);
  });

  it("does not reload src when srcdoc is removed", () => {
    const player = createPlayer({ src: COMPOSITION, srcdoc: "<p>composition</p>" });
    player.iframeElement.setAttribute("src", "about:blank#kept");

    player.removeAttribute("srcdoc");

    expect(player.iframeElement.getAttribute("src")).toBe("about:blank#kept");
  });
});

describe("HyperframesPlayer click-to-play", () => {
  type ClickPlayer = HTMLElement & {
    play: () => void;
    pause: () => void;
    disableClickToPlay: boolean;
  };

  let player: ClickPlayer;

  beforeEach(async () => {
    await import("./hyperframes-player.js");
    player = document.createElement("hyperframes-player") as ClickPlayer;
    document.body.appendChild(player);
  });

  afterEach(() => {
    player.remove();
    vi.restoreAllMocks();
  });

  it("plays on a click by default", () => {
    const play = vi.spyOn(player, "play").mockImplementation(() => undefined);

    player.click();

    expect(play).toHaveBeenCalledTimes(1);
  });

  it("leaves clicks to the host with disable-click-to-play", () => {
    const play = vi.spyOn(player, "play").mockImplementation(() => undefined);
    const pause = vi.spyOn(player, "pause").mockImplementation(() => undefined);

    player.disableClickToPlay = true;
    player.click();

    expect(player.hasAttribute("disable-click-to-play")).toBe(true);
    expect(play).not.toHaveBeenCalled();
    expect(pause).not.toHaveBeenCalled();
  });
});

describe("HyperframesPlayer retained runtime data", () => {
  interface RuntimeDataPlayer extends HTMLElement {
    iframeElement: HTMLIFrameElement;
    setRuntimeData: (channel: string, payload: unknown) => void;
    clearRuntimeData: (channel: string) => void;
    _onMessage: (event: MessageEvent) => void;
  }

  let player: RuntimeDataPlayer;
  let postSpy: MockInstance<typeof window.postMessage>;

  const readyMessage = () =>
    new MessageEvent("message", {
      source: window,
      data: { source: "hf-preview", type: "ready" },
    });

  const runtimeCalls = () =>
    postSpy.mock.calls.filter((call) => {
      const message = call[0] as { action?: string };
      return message.action === "set-runtime-data" || message.action === "clear-runtime-data";
    });

  beforeEach(async () => {
    await import("./hyperframes-player.js");
    player = document.createElement("hyperframes-player") as RuntimeDataPlayer;
    postSpy = vi.spyOn(window, "postMessage").mockImplementation(() => undefined);
    Object.defineProperty(player.iframeElement, "contentWindow", {
      configurable: true,
      get: () => window,
    });
    delete (window as Window & { __hyperframes?: unknown }).__hyperframes;
    document.body.appendChild(player);
  });

  afterEach(() => {
    player.remove();
    delete (window as Window & { __hyperframes?: unknown }).__hyperframes;
    vi.restoreAllMocks();
  });

  it("retains data set before load and replays it exactly once after runtime ready", () => {
    player.setRuntimeData("captions", { words: ["before"] });
    expect(runtimeCalls()).toHaveLength(0);

    player._onMessage(readyMessage());

    expect(runtimeCalls()).toHaveLength(1);
    expect(runtimeCalls()[0]?.[0]).toMatchObject({
      action: "set-runtime-data",
      channel: "captions",
      payload: { words: ["before"] },
    });
  });

  it("delivers after readiness and replays only the latest value after a source swap", () => {
    player._onMessage(readyMessage());
    player.setRuntimeData("captions", { words: ["first"] });
    postSpy.mockClear();

    player.setAttribute("srcdoc", "<!doctype html><html><body></body></html>");
    player.setRuntimeData("captions", { words: ["latest"] });
    expect(runtimeCalls()).toHaveLength(0);
    player._onMessage(readyMessage());

    expect(runtimeCalls()).toHaveLength(1);
    expect(runtimeCalls()[0]?.[0]).toMatchObject({ payload: { words: ["latest"] } });
  });

  it("clears the current channel and does not replay it", () => {
    player._onMessage(readyMessage());
    player.setRuntimeData("captions", { words: [] });
    player.clearRuntimeData("captions");
    expect(runtimeCalls().at(-1)?.[0]).toMatchObject({
      action: "clear-runtime-data",
      channel: "captions",
    });
    postSpy.mockClear();
    player.setAttribute("srcdoc", "<!doctype html><html></html>");
    player._onMessage(readyMessage());
    expect(runtimeCalls()).toHaveLength(0);
  });

  it("uses the same-origin registry directly and falls back to postMessage otherwise", () => {
    const direct = vi.fn();
    (window as Window & { __hyperframes?: unknown }).__hyperframes = {
      setRuntimeData: direct,
    };
    player._onMessage(readyMessage());
    postSpy.mockClear();

    player.setRuntimeData("captions", { words: ["direct"] });

    expect(direct).toHaveBeenCalledWith("captions", { words: ["direct"] }, expect.any(Number));
    expect(runtimeCalls()).toHaveLength(0);
  });

  it("does not deliver while disconnected and preserves the standard sandbox", () => {
    player._onMessage(readyMessage());
    postSpy.mockClear();
    player.remove();
    player.setRuntimeData("captions", { words: ["offline"] });
    expect(runtimeCalls()).toHaveLength(0);
    expect(player.iframeElement.sandbox.contains("allow-scripts")).toBe(true);
    expect(player.iframeElement.sandbox.contains("allow-same-origin")).toBe(true);
    expect(player.iframeElement.sandbox.contains("allow-top-navigation")).toBe(false);
    expect(player.iframeElement.referrerPolicy).toBe("no-referrer");
  });

  it("supports an opaque-origin sandbox for hosts that do not need direct iframe DOM access", () => {
    player.setAttribute("sandbox-origin", "opaque");
    expect(player.iframeElement.sandbox.contains("allow-scripts")).toBe(true);
    expect(player.iframeElement.sandbox.contains("allow-same-origin")).toBe(false);
    expect(player.iframeElement.sandbox.contains("allow-top-navigation")).toBe(false);

    player.removeAttribute("sandbox-origin");
    expect(player.iframeElement.sandbox.contains("allow-same-origin")).toBe(true);
  });

  it("treats every non-null sandbox-origin value as restrictive", () => {
    player.setAttribute("sandbox-origin", "opaqu");
    expect(player.iframeElement.sandbox.contains("allow-same-origin")).toBe(false);
  });

  it("rejects payloads that structuredClone cannot transfer", () => {
    expect(() => player.setRuntimeData("captions", () => undefined)).toThrow();
  });

  it("fails closed when structuredClone is unavailable", () => {
    const original = globalThis.structuredClone;
    Object.defineProperty(globalThis, "structuredClone", {
      configurable: true,
      value: undefined,
    });
    try {
      expect(() => player.setRuntimeData("captions", { words: ["unsafe"] })).toThrow(
        /requires structuredClone support/,
      );
      player._onMessage(readyMessage());
      expect(runtimeCalls()).toHaveLength(0);
    } finally {
      Object.defineProperty(globalThis, "structuredClone", {
        configurable: true,
        value: original,
      });
    }
  });

  it("reports postMessage delivery failures instead of silently dropping runtime data", () => {
    player._onMessage(readyMessage());
    postSpy.mockImplementation(() => {
      throw new DOMException("payload cannot be cloned", "DataCloneError");
    });
    const errors: CustomEvent[] = [];
    player.addEventListener("runtimedataerror", (event) => errors.push(event as CustomEvent));

    player.setRuntimeData("captions", { words: ["value"] });

    expect(errors).toHaveLength(1);
    expect(errors[0]?.detail).toMatchObject({
      channel: "captions",
      requestId: expect.any(Number),
      message: "payload cannot be cloned",
    });
  });

  it("reports a null iframe window as a delivery failure", () => {
    player._onMessage(readyMessage());
    Object.defineProperty(player.iframeElement, "contentWindow", {
      configurable: true,
      get: () => null,
    });
    const errors: CustomEvent[] = [];
    player.addEventListener("runtimedataerror", (event) => errors.push(event as CustomEvent));

    player.setRuntimeData("captions", { words: ["value"] });

    expect(errors).toHaveLength(1);
    expect(errors[0]?.detail).toMatchObject({
      channel: "captions",
      requestId: expect.any(Number),
      message: "Composition iframe is unavailable",
    });
  });

  it("reports a bounded error when the runtime never responds", () => {
    vi.useFakeTimers();
    try {
      player._onMessage(readyMessage());
      const errors: CustomEvent[] = [];
      player.addEventListener("runtimedataerror", (event) => errors.push(event as CustomEvent));

      player.setRuntimeData("captions", { words: ["value"] });
      vi.advanceTimersByTime(10_000);

      expect(errors).toHaveLength(1);
      expect(errors[0]?.detail).toMatchObject({
        channel: "captions",
        requestId: expect.any(Number),
        message: "Runtime data delivery timed out after 10000ms",
      });
    } finally {
      vi.useRealTimers();
    }
  });

  it("ignores a superseded completion and correlates the latest application", () => {
    player._onMessage(readyMessage());
    postSpy.mockClear();
    const applied: CustomEvent[] = [];
    player.addEventListener("runtimedataapplied", (event) => applied.push(event as CustomEvent));

    player.setRuntimeData("captions", { words: ["first"] });
    player.setRuntimeData("captions", { words: ["latest"] });
    const requests = runtimeCalls().map((call) => (call[0] as { requestId: number }).requestId);

    player._onMessage(
      new MessageEvent("message", {
        source: window,
        data: {
          source: "hf-preview",
          type: "runtime-data-applied",
          channel: "captions",
          requestId: requests[0],
        },
      }),
    );
    expect(applied).toHaveLength(0);

    player._onMessage(
      new MessageEvent("message", {
        source: window,
        data: {
          source: "hf-preview",
          type: "runtime-data-applied",
          channel: "captions",
          requestId: requests[1],
        },
      }),
    );
    expect(applied).toHaveLength(1);
    expect(applied[0]?.detail).toEqual({ channel: "captions", requestId: requests[1] });
  });
});

describe("HyperframesPlayer asset-ready gate", () => {
  type PlayerInternal = HTMLElement & {
    iframe: HTMLIFrameElement;
    _ready: boolean;
    _pendingPlay: boolean;
    _paused: boolean;
    assetsReady: boolean;
    painted: boolean;
    _waitForAssetsReady(doc: Document | null): void;
    _onIframeLoad(): void;
    play(): void;
    pause(): void;
    seek(timeInSeconds: number): void;
    shaderLoader: {
      showAssetsLoading(): void;
      hide(): void;
      update(status: { loading: boolean; ready: boolean }, mode: string): void;
    };
    _settleAssetsReady(generation: number): void;
    assetsLoadingUi: "player" | "none";
  };

  beforeEach(async () => {
    await import("./hyperframes-player.js");
  });

  // A bare iframe fires its own async `load` a few ms after append, which
  // resets _assetsReady — await it first so it can't land mid-test.
  async function createConnectedPlayer(): Promise<PlayerInternal> {
    const player = document.createElement("hyperframes-player") as PlayerInternal;
    document.body.appendChild(player);
    await new Promise<void>((resolve) => {
      player.iframe.addEventListener("load", () => resolve(), { once: true });
    });
    player._ready = true;
    return player;
  }

  // A composition doc with one video stuck at readyState 0 — the shared
  // "something is still loading" fixture for the defer/timeout tests below.
  function createStalledVideoDoc(): { doc: Document; video: HTMLVideoElement } {
    const doc = document.implementation.createHTMLDocument("composition");
    const video = doc.createElement("video");
    Object.defineProperty(video, "readyState", { value: 0, configurable: true });
    doc.body.appendChild(video);
    return { doc, video };
  }

  const post = (player: PlayerInternal, data: Record<string, unknown>) =>
    (player as unknown as { _onMessage(e: MessageEvent): void })._onMessage({
      source: player.iframe.contentWindow,
      data: { source: "hf-preview", ...data },
    } as unknown as MessageEvent);

  it("ignores its iframe's blank-document load that arrives before it is connected", () => {
    const player = document.createElement("hyperframes-player") as PlayerInternal & {
      probe: { start(): void };
    };
    const start = vi.spyOn(player.probe, "start");
    // Mid-insertion the element already reads as connected; connectedCallback has not run yet.
    Object.defineProperty(player, "isConnected", { get: () => true, configurable: true });

    player.iframe.dispatchEvent(new Event("load"));

    expect(start).not.toHaveBeenCalled();
  });

  it("handles its iframe's load before a host's load listener runs", async () => {
    const player = document.createElement("hyperframes-player") as PlayerInternal & {
      _readyDocument: Document | null;
    };
    const readyAtHostLoad: boolean[] = [];
    player.iframe.addEventListener("load", () => readyAtHostLoad.push(player._ready));
    document.body.appendChild(player);
    await vi.waitFor(() => expect(readyAtHostLoad).toHaveLength(1));
    player._ready = true;
    player._readyDocument = document.implementation.createHTMLDocument("previous document");

    player.iframe.dispatchEvent(new Event("load"));

    expect(readyAtHostLoad[1]).toBe(false);
    player.remove();
  });

  it("paints a document before its load when nothing first-frame is pending", async () => {
    const player = await createConnectedPlayer();
    player._ready = false;
    const doc = player.iframe.contentDocument!;
    Object.defineProperty(doc, "readyState", { get: () => "interactive", configurable: true });
    const holdLoad = (e: Event) => e.stopImmediatePropagation();
    doc.defaultView!.addEventListener("load", holdLoad, { capture: true });
    try {
      post(player, { type: "timeline", durationInFrames: 60 });

      await vi.waitFor(() => expect(player.painted).toBe(true));
    } finally {
      doc.defaultView!.removeEventListener("load", holdLoad, { capture: true });
      delete (doc as { readyState?: unknown }).readyState;
      player.remove();
    }
  });

  it("stays unpainted for first-frame media a script adds before the document's load", async () => {
    const player = await createConnectedPlayer();
    player._ready = false;
    const doc = player.iframe.contentDocument!;
    let readyState: DocumentReadyState = "interactive";
    Object.defineProperty(doc, "readyState", { get: () => readyState, configurable: true });
    post(player, { type: "timeline", durationInFrames: 60 });

    const video = doc.createElement("video");
    video.setAttribute("data-start", "0");
    Object.defineProperty(video, "readyState", { value: 0, configurable: true });
    doc.body.appendChild(video);
    readyState = "complete";
    doc.defaultView!.dispatchEvent(new Event("load"));
    player._onIframeLoad();
    await new Promise((resolve) => setTimeout(resolve, 300));

    expect(player._ready).toBe(true);
    expect(player.assetsReady).toBe(false);
    expect(player.painted).toBe(false);
    delete (doc as { readyState?: unknown }).readyState;
    player.remove();
  });

  it("holds an opaque-origin composition until its runtime posts assets-ready", async () => {
    const player = await createConnectedPlayer();
    player._ready = false;
    Object.defineProperty(player.iframe, "contentDocument", { get: () => null });
    post(player, { type: "timeline", durationInFrames: 60, assetsReady: false });
    expect(player.assetsReady).toBe(false);

    post(player, { type: "assets-ready", timedOut: false });
    expect(player.assetsReady).toBe(true);

    player.remove();
  });

  it("keeps a queued play across the iframe load event while the runtime still reports assets pending", async () => {
    const player = await createConnectedPlayer();
    player._ready = false;
    Object.defineProperty(player.iframe, "contentDocument", { get: () => null });
    post(player, { type: "timeline", durationInFrames: 60, assetsReady: false });
    player.play();
    expect(player._pendingPlay).toBe(true);

    player._onIframeLoad();
    post(player, { type: "assets-ready", timedOut: false });

    expect(player.assetsReady).toBe(true);
    expect(player._ready).toBe(true);
    expect(player._pendingPlay).toBe(false);
    expect(player._paused).toBe(false);

    player.remove();
  });

  it("drops a queued play when an assetsready listener pauses", async () => {
    const player = await createConnectedPlayer();
    player._ready = false;
    Object.defineProperty(player.iframe, "contentDocument", { get: () => null });
    post(player, { type: "timeline", durationInFrames: 60, assetsReady: false });
    player.play();
    const seen: string[] = [];
    for (const type of ["assetsready", "play", "pause"]) {
      player.addEventListener(type, () => seen.push(type));
    }
    player.addEventListener("assetsready", () => player.pause(), { once: true });

    post(player, { type: "assets-ready", timedOut: false });

    expect(seen).toEqual(["assetsready", "pause"]);
    expect(player._paused).toBe(true);

    player.remove();
  });

  it("stays ready when a late iframe load follows a settled opaque-origin wait", async () => {
    const player = await createConnectedPlayer();
    player._ready = false;
    Object.defineProperty(player.iframe, "contentDocument", { get: () => null });
    post(player, { type: "timeline", durationInFrames: 60, assetsReady: false });
    post(player, { type: "assets-ready", timedOut: false });
    expect(player._ready).toBe(true);

    player._onIframeLoad();

    expect(player._ready).toBe(true);
    expect(player.assetsReady).toBe(true);
    player.play();
    expect(player._paused).toBe(false);

    player.remove();
  });

  it("keeps a same-origin handshake when that document's load event arrives after ready", async () => {
    const player = await createConnectedPlayer();
    player._ready = false;
    const doc = document.implementation.createHTMLDocument("composition");
    Object.defineProperty(player.iframe, "contentDocument", { get: () => doc, configurable: true });
    post(player, { type: "timeline", durationInFrames: 60 });
    await vi.waitFor(() => expect(player.assetsReady).toBe(true));

    const settled = vi.fn();
    player.addEventListener("assetsready", settled);
    player._onIframeLoad();
    await new Promise((resolve) => setTimeout(resolve, 50));

    expect(player._ready).toBe(true);
    expect(player.assetsReady).toBe(true);
    expect(settled).not.toHaveBeenCalled();

    const next = document.implementation.createHTMLDocument("next composition");
    Object.defineProperty(player.iframe, "contentDocument", { get: () => next });
    player._onIframeLoad();
    expect(player._ready).toBe(false);

    player.remove();
  });

  it("does not wait on an opaque-origin runtime that already settled its assets", async () => {
    const player = await createConnectedPlayer();
    player._ready = false;
    Object.defineProperty(player.iframe, "contentDocument", { get: () => null });
    post(player, { type: "timeline", durationInFrames: 60, assetsReady: true });

    expect(player.assetsReady).toBe(true);

    player.remove();
  });

  it("does not wait on an opaque-origin runtime that never announced the capability", async () => {
    const player = await createConnectedPlayer();
    player._ready = false;
    Object.defineProperty(player.iframe, "contentDocument", { get: () => null });
    post(player, { type: "timeline", durationInFrames: 60 });

    expect(player.assetsReady).toBe(true);

    player.remove();
  });

  it("settles immediately for a cross-origin composition (doc === null)", async () => {
    const player = await createConnectedPlayer();

    player._waitForAssetsReady(null);

    expect(player.assetsReady).toBe(true);
    expect(player.hasAttribute("assets-loading")).toBe(false);

    player.remove();
  });

  it("debounces the loading overlay so a fast, nothing-pending wait never shows it", async () => {
    const player = await createConnectedPlayer();
    const doc = player.iframe.contentDocument!;
    const showSpy = vi.spyOn(player.shaderLoader, "showAssetsLoading");
    // The overlay delay runs on fake time; the iframe's own frames stay real, however slow.
    vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
    try {
      player._waitForAssetsReady(doc);
      expect(player.assetsReady).toBe(false);

      // Only paint-and-idle is pending on this blank iframe doc (no runtime, no media).
      const win = doc.defaultView!;
      for (let frame = 0; frame < 600 && !player.assetsReady; frame++) {
        await new Promise<void>((resolve) => win.requestAnimationFrame(() => resolve()));
      }
      expect(player.assetsReady).toBe(true);

      vi.advanceTimersByTime(1_000);
      expect(player.hasAttribute("assets-loading")).toBe(false);
      expect(showSpy).not.toHaveBeenCalled();
    } finally {
      vi.useRealTimers();
      player.remove();
    }
  });

  it("fires painted only after the raised loader has faded out, not at assetsready", async () => {
    const player = await createConnectedPlayer();
    const { doc, video } = createStalledVideoDoc();
    stubIframeContentDocument(player.iframe, doc);
    const events: string[] = [];
    player.addEventListener("assetsready", () => events.push("assetsready"));
    player.addEventListener("painted", () => events.push("painted"));

    player._waitForAssetsReady(doc);
    await new Promise((resolve) => setTimeout(resolve, 160));
    expect(player.hasAttribute("assets-loading")).toBe(true);
    expect(player.painted).toBe(false);

    video.dispatchEvent(new Event("canplay"));
    await new Promise((resolve) => setTimeout(resolve, 0));
    expect(events).toEqual(["assetsready"]);
    expect(player.painted).toBe(false);

    await new Promise((resolve) => setTimeout(resolve, 500));
    expect(events).toEqual(["assetsready", "painted"]);
    expect(player.painted).toBe(true);

    player._waitForAssetsReady(doc);
    expect(player.painted).toBe(false);

    player.remove();
  });

  it("fires painted right after assetsready when no loader was ever raised", async () => {
    const player = await createConnectedPlayer();
    const painted = vi.fn();
    player.addEventListener("painted", painted);

    player._waitForAssetsReady(null);

    expect(player.assetsReady).toBe(true);
    expect(player.painted).toBe(true);
    expect(painted).toHaveBeenCalledTimes(1);

    player.remove();
  });

  it("dispatches painted once for the current generation when settles share a loader fade", async () => {
    vi.useFakeTimers();
    try {
      const player = await createConnectedPlayer();
      const painted = vi.fn();
      player.addEventListener("painted", painted);
      player.shaderLoader.showAssetsLoading();

      player._waitForAssetsReady(null);
      player._waitForAssetsReady(null);
      await vi.runOnlyPendingTimersAsync();

      expect(painted).toHaveBeenCalledTimes(1);
      player.remove();
    } finally {
      vi.useRealTimers();
    }
  });

  it("defers play() until a pending video settles, then plays and clears the overlay attribute", async () => {
    const player = await createConnectedPlayer();

    const { doc, video } = createStalledVideoDoc();
    stubIframeContentDocument(player.iframe, doc);

    const playSpy = vi.fn();
    player.addEventListener("play", playSpy);

    player._waitForAssetsReady(doc);
    expect(player.assetsReady).toBe(false);
    // The loading overlay is debounced (ASSETS_LOADING_SHOW_DELAY_MS) so a
    // wait that resolves fast never flashes it — advance past the debounce
    // to exercise the shown state, since this video is still genuinely stuck.
    await new Promise((resolve) => setTimeout(resolve, 160));
    expect(player.hasAttribute("assets-loading")).toBe(true);

    player.play();
    expect(player._pendingPlay).toBe(true);
    expect(playSpy).not.toHaveBeenCalled();

    video.dispatchEvent(new Event("canplay"));
    // A macrotask flush drains the whole promise chain regardless of its
    // depth (resolved media promise -> Promise.all -> Promise.race -> settle).
    await new Promise((resolve) => setTimeout(resolve, 0));

    expect(player.assetsReady).toBe(true);
    expect(player.hasAttribute("assets-loading")).toBe(false);
    expect(player._pendingPlay).toBe(false);
    expect(playSpy).toHaveBeenCalledTimes(1);

    player.remove();
  });

  it("keeps a play queued before a same-origin iframe load and starts it once the wait settles", async () => {
    const player = await createConnectedPlayer();
    const { doc, video } = createStalledVideoDoc();
    stubIframeContentDocument(player.iframe, doc);
    const playSpy = vi.fn();
    player.addEventListener("play", playSpy);

    // First ready's asset wait, a play() while it is pending, then the document's own load event.
    player._waitForAssetsReady(doc);
    player.play();
    expect(player._pendingPlay).toBe(true);
    player._onIframeLoad();
    post(player, { type: "timeline", durationInFrames: 60 });
    video.dispatchEvent(new Event("canplay"));
    await new Promise((resolve) => setTimeout(resolve, 0));

    expect(player.assetsReady).toBe(true);
    expect(player._paused).toBe(false);
    expect(playSpy).toHaveBeenCalledTimes(1);

    player.remove();
  });

  it("drops a queued play when the host points the player at a different composition", async () => {
    const player = await createConnectedPlayer();
    const { doc } = createStalledVideoDoc();
    stubIframeContentDocument(player.iframe, doc);

    player._waitForAssetsReady(doc);
    player.play();
    expect(player._pendingPlay).toBe(true);
    player.setAttribute("srcdoc", "<p>another composition</p>");

    expect(player._pendingPlay).toBe(false);

    player.remove();
  });

  it("keeps a queued play through a shader-options reload of the same composition", async () => {
    const player = await createConnectedPlayer();
    const { doc } = createStalledVideoDoc();
    stubIframeContentDocument(player.iframe, doc);

    player._waitForAssetsReady(doc);
    player.play();
    player.setAttribute("shader-loading", "player");

    expect(player._pendingPlay).toBe(true);

    player.remove();
  });

  it("never raises the loading card with assets-loading-ui=none, and still reports every asset event", async () => {
    const player = await createConnectedPlayer();
    player.setAttribute("assets-loading-ui", "none");
    const { doc, video } = createStalledVideoDoc();
    stubIframeContentDocument(player.iframe, doc);
    const showSpy = vi.spyOn(player.shaderLoader, "showAssetsLoading");
    const events: string[] = [];
    player.addEventListener("assetsready", () => events.push("assetsready"));
    player.addEventListener("painted", () => events.push("painted"));

    player._waitForAssetsReady(doc);
    await new Promise((resolve) => setTimeout(resolve, 160));
    expect(player.hasAttribute("assets-loading")).toBe(true);
    expect(showSpy).not.toHaveBeenCalled();

    video.dispatchEvent(new Event("canplay"));
    await new Promise((resolve) => setTimeout(resolve, 0));
    expect(events).toEqual(["assetsready", "painted"]);
    expect(player.hasAttribute("assets-loading")).toBe(false);

    player.remove();
  });

  it("hides a loading card already up when assets-loading-ui switches to none", async () => {
    const player = await createConnectedPlayer();
    const { doc } = createStalledVideoDoc();
    stubIframeContentDocument(player.iframe, doc);
    const showSpy = vi.spyOn(player.shaderLoader, "showAssetsLoading");
    const hideSpy = vi.spyOn(player.shaderLoader, "hide");
    expect(player.assetsLoadingUi).toBe("player");

    player._waitForAssetsReady(doc);
    await new Promise((resolve) => setTimeout(resolve, 160));
    expect(showSpy).toHaveBeenCalledTimes(1);
    player.assetsLoadingUi = "none";

    expect(player.getAttribute("assets-loading-ui")).toBe("none");
    expect(hideSpy).toHaveBeenCalled();

    player.remove();
  });

  it("keeps a shader load drawn over the loading card when assets-loading-ui switches to none", async () => {
    const player = await createConnectedPlayer();
    const { doc } = createStalledVideoDoc();
    stubIframeContentDocument(player.iframe, doc);

    player._waitForAssetsReady(doc);
    await new Promise((resolve) => setTimeout(resolve, 160));
    player.shaderLoader.update({ loading: true, ready: false }, "player");
    player.assetsLoadingUi = "none";

    const loader = player.shadowRoot?.querySelector(".hfp-shader-loader");
    expect(loader?.classList.contains("hfp-visible")).toBe(true);
    expect(loader?.getAttribute("aria-label")).toBe("Preparing scene transitions");

    player.remove();
  });

  it("leaves a shader load on screen when assets settle, and reports painted once it is gone", async () => {
    const player = await createConnectedPlayer();
    const { doc, video } = createStalledVideoDoc();
    stubIframeContentDocument(player.iframe, doc);
    const events: string[] = [];
    player.addEventListener("assetsready", () => events.push("assetsready"));
    player.addEventListener("painted", () => events.push("painted"));

    player._waitForAssetsReady(doc);
    await new Promise((resolve) => setTimeout(resolve, 160));
    player.shaderLoader.update({ loading: true, ready: false }, "player");
    video.dispatchEvent(new Event("canplay"));
    await new Promise((resolve) => setTimeout(resolve, 450));

    const loader = player.shadowRoot?.querySelector(".hfp-shader-loader");
    expect(loader?.classList.contains("hfp-visible")).toBe(true);
    expect(events).toEqual(["assetsready"]);

    player.shaderLoader.update({ loading: false, ready: true }, "player");
    await new Promise((resolve) => setTimeout(resolve, 450));
    expect(events).toEqual(["assetsready", "painted"]);

    player.remove();
  });

  it("cancels a queued play if the user pauses while assets are still buffering", async () => {
    const player = await createConnectedPlayer();

    const { doc, video } = createStalledVideoDoc();
    stubIframeContentDocument(player.iframe, doc);

    const playSpy = vi.fn();
    player.addEventListener("play", playSpy);

    player._waitForAssetsReady(doc);
    player.play();
    expect(player._pendingPlay).toBe(true);

    player.pause();
    expect(player._pendingPlay).toBe(false);
    expect(player._paused).toBe(true);

    video.dispatchEvent(new Event("canplay"));
    await new Promise((resolve) => setTimeout(resolve, 0));

    expect(player.assetsReady).toBe(true);
    expect(player._pendingPlay).toBe(false);
    expect(player._paused).toBe(true);
    expect(playSpy).not.toHaveBeenCalled();

    player.remove();
  });

  it("cancels a queued play if the user seeks while assets are still buffering", async () => {
    const player = await createConnectedPlayer();

    const { doc, video } = createStalledVideoDoc();
    stubIframeContentDocument(player.iframe, doc);

    const playSpy = vi.fn();
    player.addEventListener("play", playSpy);

    player._waitForAssetsReady(doc);
    player.play();
    expect(player._pendingPlay).toBe(true);

    player.seek(1.5);
    expect(player._pendingPlay).toBe(false);

    video.dispatchEvent(new Event("canplay"));
    await new Promise((resolve) => setTimeout(resolve, 0));

    expect(player.assetsReady).toBe(true);
    expect(player._pendingPlay).toBe(false);
    expect(playSpy).not.toHaveBeenCalled();

    player.remove();
  });

  it("settles a play() called twice while buffering into exactly one playback start (pre-existing idempotency, not the pause/seek cancel)", async () => {
    const player = await createConnectedPlayer();

    const { doc, video } = createStalledVideoDoc();
    stubIframeContentDocument(player.iframe, doc);

    const playSpy = vi.fn();
    player.addEventListener("play", playSpy);

    player._waitForAssetsReady(doc);
    player.play();
    player.play();
    expect(player._pendingPlay).toBe(true);

    video.dispatchEvent(new Event("canplay"));
    await new Promise((resolve) => setTimeout(resolve, 0));

    expect(player.assetsReady).toBe(true);
    expect(player._pendingPlay).toBe(false);
    // Two queued play() calls settle into exactly one playback start, never two.
    expect(playSpy).toHaveBeenCalledTimes(1);

    player.remove();
  });

  it("plays anyway once the 8s timeout elapses for an asset that never settles", async () => {
    // Real timers for the initial (blank) iframe load, then switch to fake
    // timers so the 8s asset-ready timeout can be advanced instantly.
    const player = await createConnectedPlayer();
    vi.useFakeTimers();
    try {
      const { doc } = createStalledVideoDoc();
      // A document with no browsing context (created via createHTMLDocument,
      // as this fixture is) reports hidden=true per spec regardless of the
      // real page — stub it visible so this test isn't about visibility.
      Object.defineProperty(doc, "hidden", { value: false, configurable: true });
      stubIframeContentDocument(player.iframe, doc);

      player._waitForAssetsReady(doc);
      player.play();
      expect(player._pendingPlay).toBe(true);

      const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => undefined);

      await vi.advanceTimersByTimeAsync(8_000);

      expect(player.assetsReady).toBe(true);
      expect(player._pendingPlay).toBe(false);
      expect(warnSpy).toHaveBeenCalledTimes(1);
      expect(warnSpy.mock.calls[0]?.[0]).toContain("assets-loading timed out");
      // computeReady is reported alongside the media/image/font scan, since
      // compute (window.__renderReady) can also be why the timeout fired.
      expect(warnSpy.mock.calls[0]?.[1]).toMatchObject({
        computeReady: false,
        documentHidden: false,
      });
      warnSpy.mockRestore();

      player.remove();
    } finally {
      vi.useRealTimers();
    }
  });

  it("reports documentHidden: true when the composition document is backgrounded", async () => {
    const player = await createConnectedPlayer();
    vi.useFakeTimers();
    try {
      const { doc } = createStalledVideoDoc();
      Object.defineProperty(doc, "hidden", { value: true, configurable: true });
      stubIframeContentDocument(player.iframe, doc);

      player._waitForAssetsReady(doc);
      const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => undefined);

      await vi.advanceTimersByTimeAsync(8_000);

      expect(warnSpy.mock.calls[0]?.[1]).toMatchObject({ documentHidden: true });
      warnSpy.mockRestore();

      player.remove();
    } finally {
      vi.useRealTimers();
    }
  });

  it("ignores a superseded wait's settle after a composition swap mid-wait", async () => {
    const player = await createConnectedPlayer();

    const { doc: docA, video: videoA } = createStalledVideoDoc();
    stubIframeContentDocument(player.iframe, docA);
    player._waitForAssetsReady(docA);

    // Simulates a src/srcdoc swap arriving while A's wait is still in flight,
    // then B's own ready handler firing (which is what real navigation does:
    // _onIframeLoad clears _ready, the new composition's ready handler sets
    // it again before calling _waitForAssetsReady).
    player._onIframeLoad();
    player._ready = true;
    const { doc: docB, video: videoB } = createStalledVideoDoc();
    stubIframeContentDocument(player.iframe, docB);
    player._waitForAssetsReady(docB);
    player.play();
    expect(player._pendingPlay).toBe(true);

    const playSpy = vi.fn();
    player.addEventListener("play", playSpy);

    videoA.dispatchEvent(new Event("canplay"));
    await new Promise((resolve) => setTimeout(resolve, 0));

    // A's stale settle must not mark B ready or play it — B's own video is
    // still stuck.
    expect(player.assetsReady).toBe(false);
    expect(player._pendingPlay).toBe(true);
    expect(playSpy).not.toHaveBeenCalled();

    videoB.dispatchEvent(new Event("canplay"));
    await new Promise((resolve) => setTimeout(resolve, 0));

    expect(player.assetsReady).toBe(true);
    expect(player._pendingPlay).toBe(false);
    expect(playSpy).toHaveBeenCalledTimes(1);

    player.remove();
  });

  it("does not resume play() after disconnect once a pending wait settles late", async () => {
    const player = await createConnectedPlayer();

    const { doc, video } = createStalledVideoDoc();
    stubIframeContentDocument(player.iframe, doc);
    player._waitForAssetsReady(doc);
    player.play();
    expect(player._pendingPlay).toBe(true);

    const playSpy = vi.fn();
    player.addEventListener("play", playSpy);

    player.remove();
    video.dispatchEvent(new Event("canplay"));
    await new Promise((resolve) => setTimeout(resolve, 0));

    expect(playSpy).not.toHaveBeenCalled();
  });

  it("dispatches 'play' exactly once for a call made before the probe resolves", async () => {
    const player = await createConnectedPlayer();
    player._ready = false;

    const playSpy = vi.fn();
    player.addEventListener("play", playSpy);

    player.play();
    expect(player._pendingPlay).toBe(true);
    expect(playSpy).not.toHaveBeenCalled();

    (
      player as unknown as {
        _onProbeReady: (r: {
          duration: number;
          adapter: { kind: string; getDuration: () => number };
          compositionSize: null;
        }) => void;
      }
    )._onProbeReady({
      duration: 5,
      adapter: { kind: "runtime", getDuration: () => 5 },
      compositionSize: null,
    });
    // The blank iframe doc has no pending media, but play() also queues on
    // the paint-and-idle default now — it fires once that settles.
    await awaitPaintAndIdle(player.iframe.contentDocument!.defaultView!);

    expect(playSpy).toHaveBeenCalledTimes(1);

    player.remove();
  });
});