Skip to content

Write HTML. Render video. Built for agents.

fix(player): load compositions from document duration (#5176)

Miguel Ángeld2a3c076d0bb
diff --git a/docs/contracts/2026-10-07-composition-probe.html b/docs/contracts/2026-10-07-composition-probe.html
new file mode 100644
index 0000000000..39c8ca99d2
--- /dev/null
+++ b/docs/contracts/2026-10-07-composition-probe.html
@@ -0,0 +1,78 @@
+<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Composition probe contract</title><style>
+:root{color-scheme:light dark;
+ --bg:#fbfbfa;--card:#ffffff;--line:#e6e4df;--ink:#1c1c1a;--dim:#6b6b66;--faint:#9a9a94;
+ --go:#178a5a;--go-bg:#e8f6ee;--warn:#a6690a;--warn-bg:#fbf1dc;--bad:#c0392b;--bad-bg:#fbe7e4;--info:#2a5db0;--info-bg:#e8eefb;
+ --mono:ui-monospace,SFMono-Regular,Menlo,monospace;--sans:-apple-system,BlinkMacSystemFont,"Segoe UI",Inter,sans-serif}
+@media (prefers-color-scheme:dark){:root{--bg:#111213;--card:#191b1d;--line:#2a2d31;--ink:#ecebe8;--dim:#a2a29c;--faint:#6f6f6a;
+ --go:#5fd39a;--go-bg:#12291f;--warn:#e6b35a;--warn-bg:#2b2311;--bad:#ff7b6b;--bad-bg:#2d1714;--info:#7fa9ff;--info-bg:#15203a}}
+*{box-sizing:border-box}
+body{margin:0;background:var(--bg);color:var(--ink);font:16px/1.55 var(--sans)}
+.wrap{max-width:900px;margin:0 auto;padding:56px 24px 96px}
+header h1{font-size:30px;line-height:1.15;letter-spacing:-.4px;margin:0 0 10px}
+header .what{font-size:18px;color:var(--dim);margin:0 0 18px;max-width:70ch}
+.strip{display:flex;gap:10px;flex-wrap:wrap;align-items:center;font:13px var(--mono);color:var(--faint)}
+.strip .sep{opacity:.5}
+.pill{display:inline-flex;align-items:center;gap:6px;font:600 12px/1 var(--mono);padding:6px 10px;border-radius:999px;white-space:nowrap}
+.pill.go{color:var(--go);background:var(--go-bg)}.pill.warn{color:var(--warn);background:var(--warn-bg)}
+.pill.bad{color:var(--bad);background:var(--bad-bg)}.pill.info{color:var(--info);background:var(--info-bg)}
+.pill b{font-size:13px}
+section{margin-top:56px}
+h2{font-size:22px;letter-spacing:-.3px;margin:0 0 6px}
+.sub{color:var(--dim);margin:0 0 18px;font-size:15px}
+.card{background:var(--card);border:1px solid var(--line);border-radius:14px;padding:20px 22px;margin:14px 0}
+.breath{border-left:4px solid var(--go);font-size:18px;line-height:1.5}
+.breath b{color:var(--go)}
+.plain{color:var(--dim);font-size:15px;margin:0 0 10px}
+.plain::before{content:"In plain words ";font:600 11px var(--mono);letter-spacing:1px;color:var(--faint);text-transform:uppercase}
+pre{background:var(--bg);border:1px solid var(--line);border-radius:10px;padding:14px 16px;overflow:auto;font:13px/1.55 var(--mono);margin:10px 0}
+code{font:13px var(--mono);background:var(--bg);border:1px solid var(--line);border-radius:5px;padding:1px 6px}
+.cite{font:12px var(--mono);color:var(--faint);margin-top:8px;display:block}
+.states{display:flex;gap:8px;margin:12px 0 4px;flex-wrap:wrap}
+table{width:100%;border-collapse:collapse;margin:10px 0;font-size:14.5px}
+th{text-align:left;font:600 11px/1.4 var(--mono);text-transform:uppercase;letter-spacing:.7px;color:var(--faint);border-bottom:1px solid var(--line);padding:8px 10px}
+td{padding:10px;border-bottom:1px solid var(--line);vertical-align:top}
+tr:last-child td{border-bottom:0}
+td.k{font:13px var(--mono);white-space:nowrap}
+.decision{border-left:4px solid var(--info)}
+.decision h3{margin:0 0 8px;font-size:17px}
+.decision .ask{color:var(--info);font-weight:600}
+blockquote{margin:12px 0;padding:8px 0 8px 16px;border-left:2px solid var(--line);color:var(--dim);font-style:italic;font-size:14.5px}
+blockquote .src{display:block;font-style:normal;font:12px var(--mono);color:var(--faint);margin-top:6px}
+ul,ol{padding-left:22px}li{margin:6px 0}
+.mermaid{background:var(--card);border:1px solid var(--line);border-radius:14px;padding:18px;margin:14px 0;overflow:auto}
+.mermaid svg{max-width:100%}
+footer{margin-top:72px;padding-top:16px;border-top:1px solid var(--line);font:12px/1.7 var(--mono);color:var(--faint)}
+</style></head><body><div class="wrap"><header><h1>Load compositions without a GSAP timeline</h1><p class="what">A valid document still loads. A real script failure keeps its own message.</p><div class="strip">Audited 3 boundaries · Not exercised 4 composition classes · No new authoring format<br>hyperframes @ 9701f0da61ddbf32d0c9d7bbf4fabc02b3ee3263 · 2026-10-07</div></header>
+<section><div class="card breath"><b>In one breath.</b> The document already owns duration and Studio already records early script errors, but the probe accepts only a positive adapter duration.</div></section>
+<section><h2>Where the value travels</h2><div class="mermaid">flowchart LR
+ D[Document and scripts] --> P[CompositionProbe]
+ P --> H[Player error event]
+ H --> R[React Player]
+ R --> N[NLE shadow]
+ N --> S[Shadow discard]
+ S --> T[Editor toast]</div></section>
+<section><h2>The contract, per boundary</h2>
+<div class="card"><h3>Document duration</h3><p class="plain">Use the existing root declaration or timed clip ends. Do not invent a timeline length.</p><pre>readStaticCompositionMeta(doc: Document):
+ { width: number | null; height: number | null;
+ fps: number; durationSeconds: number } | null</pre><span class="cite">Producer: packages/core/src/runtime/compositionLength.ts:141, declaration read at152; package-subpaths.json:323 exposes runtime/composition-length. Current probe consumer composition-probe.ts:118 requires adapter.getDuration() &gt;0. Proposed reuse is not exercised.</span><div class="states"><span class="pill go">exists</span><span class="pill go">export reachable</span><span class="pill bad">probe does not read</span></div></div>
+<div class="card"><h3>Early script failures</h3><p class="plain">The preview server captures browser errors before author scripts execute. Read that same buffer before reporting readiness or a timeout.</p><pre>var seen=window.__hfPreviewErrors=[];
+addEventListener("error",function(e){seen.push(e.message||String(e))});</pre><span class="cite">Producer: packages/studio-server/src/routes/preview.ts:326, inserted at338 before scripts. Constant: packages/core/src/studioPreviewMark.ts:4. Existing reader: packages/studio/src/hooks/useConsoleErrorCapture.ts:68. New probe read not exercised. Resource events may yield generic Event text; unhandled rejection is not captured by this producer.</span><div class="states"><span class="pill go">exists</span><span class="pill go">same-origin reachable</span><span class="pill go">server writes; console reads</span></div></div>
+<div class="card"><h3>Probe result and failure</h3><p class="plain">A probe error discards the hidden edit preview while the live preview stays visible.</p><pre>onReady: (result: ProbeResult) =&gt; void;
+onError: (message: string) =&gt; void;
+new CustomEvent("error", { detail: { message } })</pre><span class="cite">Producer: composition-probe.ts:123/136; hyperframes-player.ts:208. Accepting lines: studio/player/components/Player.tsx:241, components/nle/NLEPreview.tsx:556, player/hooks/useShadowPreviewReload.ts:116, components/EditorShell.tsx:186. Ready accepts duration and adapter at hyperframes-player.ts:1305.</span><div class="states"><span class="pill go">exists</span><span class="pill go">wired through every layer</span><span class="pill go">probe writes; toast reads</span></div></div></section>
+<section><h2>How it says no</h2><table><tr><th>Cause</th><th>Current observable</th><th>Evidence</th></tr><tr><td>No GSAP or no positive adapter duration</td><td>Composition timeline not found after 8s</td><td>composition-probe.ts:118/134</td></tr><tr><td>Real early script error</td><td>Same timeout if no adapter appears</td><td>Probe has no early-error reader; error buffer reader search bounded to all packages excluding generated/dist</td></tr><tr><td>Injected runtime never appears</td><td>Probe can wait indefinitely</td><td>Early return at115 bypasses timeout at134</td></tr></table></section>
+<section><h2>Decisions only you can make</h2><div class="card"><h3>1. Slow initialization with no usable document duration</h3><p>The task already decides valid document duration and real script errors. The remaining wait policy is unknown: a probe failure at8s discards a shadow whose outer budget allows up to45s.</p><table><tr><th>Option</th><th>Consequence</th></tr><tr><td>Keep finite8s failure</td><td>Preserves the existing probe budget. Slow unresolved initialization still fails, with an accurate readiness cause.</td></tr><tr><td>Let the outer shadow budget own waiting</td><td>Studio can accept initialization after8s; embeddable player needs its own finite bound. Changes lifecycle scope.</td></tr></table><p>Recommendation: first prove the slow class with real browser fixtures. Preserve the existing finite probe budget unless that evidence calls for a separately owned wait policy.</p></div></section>
+<section><h2>Coverage, honestly</h2><p><b>Audited:</b> producer bodies and accepting lines above at the pinned main ref.</p><p><b>Trusting:</b> no runtime claims credited from mocks.</p><p><b>Not exercised:</b> CSS-only, bare render(t), WAAPI, zero-duration timeline, script failure, and delayed initialization still need red tests and real reload captures. No implementation has been written.</p></section>
+<section><h2>What would prove this page wrong</h2><ul><li>A served CSS-only document with positive declared duration already completes the current probe.</li><li>An early throwing author script reaches the reload toast with its own message on this main head.</li><li>A pending runtime injection reaches the existing8s timeout despite the early return.</li></ul></section></div><script type="module">
+try {
+ const m = await import("https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs");
+ const dark = matchMedia("(prefers-color-scheme: dark)").matches;
+ m.default.initialize({ startOnLoad: false, theme: dark ? "dark" : "neutral", securityLevel: "loose",
+ themeVariables: { fontFamily: "ui-monospace, Menlo, monospace", fontSize: "13px" } });
+ await m.default.run({ querySelector: ".mermaid" });
+} catch (e) {
+ for (const el of document.querySelectorAll(".mermaid")) {
+ const pre = document.createElement("pre"); pre.textContent = el.textContent.trim(); el.replaceWith(pre);
+ }
+}
+</script></body></html>
\ No newline at end of file
diff --git a/packages/player/src/composition-probe.ts b/packages/player/src/composition-probe.ts
index b3c500b104..226919f850 100644
--- a/packages/player/src/composition-probe.ts
+++ b/packages/player/src/composition-probe.ts
@@ -3,13 +3,15 @@
* and detect whether the HyperFrames runtime needs to be injected.
*
* The probe interval polls every 200 ms until one of:
- * - A `PlaybackDurationAdapter` resolves with a positive duration, or
+ * - An adapter or the document resolves with a positive duration, or
* - 40 attempts (~8 s) expire without a result.
*
* The `CompositionProbe` class owns the interval; the caller must call
* `stop()` on disconnect or src change.
*/
+import { readStaticCompositionMeta } from "@hyperframes/core/runtime/composition-length";
+import { STUDIO_PREVIEW_ERRORS } from "@hyperframes/core/studio-preview-mark";
import { shouldInjectRuntime } from "./shouldInjectRuntime.js";
import {
type DirectTimelineAdapter,
@@ -63,9 +65,29 @@ export function readCompositionSizeFromDocument(
return width !== null && height !== null ? { width, height } : null;
}
+type ProbeOutcome =
+ | { kind: "ready"; result: ProbeResult }
+ | { kind: "error"; message: string }
+ | null;
+
+function firstAuthorError(errors: unknown): string | null {
+ if (!Array.isArray(errors)) return null;
+ return (
+ errors.find(
+ (value): value is string =>
+ typeof value === "string" && value.trim() !== "" && value !== "[object Event]",
+ ) ?? null
+ );
+}
+
export class CompositionProbe {
private _interval: ReturnType<typeof setInterval> | null = null;
private _runtimeInjected = false;
+ private _failure: { document: Document | null } | null = null;
+
+ get failed(): boolean {
+ return this._failure !== null && this._failure.document === this._iframe.contentDocument;
+ }
constructor(
private readonly _iframe: HTMLIFrameElement,
@@ -77,68 +99,87 @@ export class CompositionProbe {
return this._runtimeInjected;
}
- /** Start (or restart) the probe. Stops any previously running probe first. */
+ /** Start or restart the probe, stopping the active interval first. */
start(): void {
this.stop();
+ this._failure = null;
this._runtimeInjected = false;
let attempts = 0;
- // fallow-ignore-next-line complexity
this._interval = setInterval(() => {
attempts++;
+ let outcome: ProbeOutcome = null;
try {
- const win = this._iframe.contentWindow as Window & {
- __player?: { getDuration: () => number };
- __timelines?: Record<string, { duration: () => number }>;
- __hf?: unknown;
- };
- if (!win) return;
-
- const hasRuntime = !!(win.__hf || win.__player);
- const hasTimelines = !!(win.__timelines && Object.keys(win.__timelines).length > 0);
- const hasNestedCompositions =
- !!this._iframe.contentDocument?.querySelector("[data-composition-src]");
-
- if (
- shouldInjectRuntime({
- hasRuntime,
- hasTimelines,
- hasNestedCompositions,
- runtimeInjected: this._runtimeInjected,
- attempts,
- })
- ) {
- this._injectRuntime();
- return;
- }
-
- if (this._runtimeInjected && !hasRuntime) return;
-
- const adapter = this._resolvePlaybackDurationAdapter(win);
- if (adapter && adapter.getDuration() > 0) {
- this.stop();
-
- const compositionSize = readCompositionSizeFromDocument(this._iframe.contentDocument);
-
- this._callbacks.onReady({
- duration: adapter.getDuration(),
- adapter,
- compositionSize,
- });
- return;
+ outcome = this._poll(attempts);
+ } catch (error) {
+ if (!(error instanceof DOMException && error.name === "SecurityError")) {
+ outcome = {
+ kind: "error",
+ message: error instanceof Error ? error.message : String(error),
+ };
}
- } catch {
- /* cross-origin */
}
-
+ if (outcome) {
+ this.stop();
+ if (outcome.kind === "error") {
+ this._failure = { document: this._iframe.contentDocument };
+ this._callbacks.onError(outcome.message);
+ } else this._callbacks.onReady(outcome.result);
+ return;
+ }
if (attempts >= 40) {
this.stop();
+ this._failure = { document: this._iframe.contentDocument };
this._callbacks.onError("Composition timeline not found after 8s");
}
}, 200);
}
+ private _poll(attempts: number): ProbeOutcome {
+ const win = this._iframe.contentWindow;
+ if (!win) return null;
+ const message = firstAuthorError(Reflect.get(win, STUDIO_PREVIEW_ERRORS));
+ if (message !== null) return { kind: "error", message };
+ const doc = this._iframe.contentDocument;
+ const timelines = Reflect.get(win, "__timelines");
+ const hasRuntime = this.hasRuntimeBridge(win);
+ if (
+ shouldInjectRuntime({
+ hasRuntime,
+ hasTimelines: isObjectRecord(timelines) && Object.keys(timelines).length > 0,
+ hasNestedCompositions: !!doc?.querySelector("[data-composition-src]"),
+ runtimeInjected: this._runtimeInjected,
+ attempts,
+ })
+ ) {
+ this._injectRuntime();
+ return null;
+ }
+ if (this._runtimeInjected && !hasRuntime) return null;
+ const result = this._resolveReadyResult(win, doc);
+ return result ? { kind: "ready", result } : null;
+ }
+
+ private _resolveReadyResult(win: Window, doc: Document | null): ProbeResult | null {
+ const adapter: PlaybackDurationAdapter = this._resolvePlaybackDurationAdapter(win) ?? {
+ kind: "document",
+ getDuration: () => 0,
+ };
+ let duration = adapter.getDuration();
+ if (!Number.isFinite(duration) || duration <= 0) {
+ if (adapter.kind === "direct-timeline") return null;
+ duration = doc ? (readStaticCompositionMeta(doc)?.durationSeconds ?? 0) : 0;
+ }
+ if (duration <= 0) return null;
+ return {
+ duration,
+ adapter: { ...adapter, getDuration: () => duration },
+ compositionSize: readCompositionSizeFromDocument(doc),
+ };
+ }
+
stop(): void {
+ if (!this.failed) this._failure = null;
if (this._interval !== null) {
clearInterval(this._interval);
this._interval = null;
diff --git a/packages/player/src/compositionProbeReadiness.test.ts b/packages/player/src/compositionProbeReadiness.test.ts
new file mode 100644
index 0000000000..fbd32ccfef
--- /dev/null
+++ b/packages/player/src/compositionProbeReadiness.test.ts
@@ -0,0 +1,183 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { CompositionProbe } from "./composition-probe.js";
+
+function mount(markup: string, globals: Record<string, unknown> = {}) {
+ const iframe = document.createElement("iframe");
+ document.body.appendChild(iframe);
+ iframe.contentDocument!.body.innerHTML = markup;
+ Object.assign(iframe.contentWindow!, globals);
+ const onReady = vi.fn();
+ const onError = vi.fn();
+ const probe = new CompositionProbe(iframe, { onReady, onError });
+ probe.start();
+ return { iframe, probe, onReady, onError };
+}
+const root =
+ '<div data-composition-id="main" data-duration="6" data-width="1920" data-height="1080"></div>';
+function timeline(duration: number) {
+ return {
+ duration: () => duration,
+ time: () => 0,
+ seek: () => {},
+ play: () => {},
+ pause: () => {},
+ };
+}
+
+describe("composition probe readiness", () => {
+ beforeEach(() => vi.useFakeTimers());
+ afterEach(() => {
+ vi.clearAllTimers();
+ vi.useRealTimers();
+ document.body.innerHTML = "";
+ });
+
+ it.each<[string, string, Record<string, unknown>]>([
+ ["CSS-only", "<style>@keyframes fade { to { opacity: 0; } }</style>" + root, {}],
+ ["bare render(t)", root, { render: (t: number) => t }],
+ [
+ "WAAPI",
+ root +
+ '<script>document.querySelector("div").animate([{opacity:1},{opacity:0}],6000)</script>',
+ {},
+ ],
+ ])("loads a %s document with its authored duration", (_name, markup, globals) => {
+ const { onReady, onError } = mount(markup, globals);
+ vi.advanceTimersByTime(8000);
+ expect(onReady).toHaveBeenCalledOnce();
+ expect(onReady.mock.calls[0][0].duration).toBe(6);
+ expect(onError).not.toHaveBeenCalled();
+ });
+ it("waits for a registered timeline to grow inside its initialization grace", () => {
+ let duration = 0;
+ const registered = { ...timeline(0), duration: () => duration };
+ const { onReady, onError } = mount(root, { __timelines: { main: registered } });
+ vi.advanceTimersByTime(600);
+ expect(onReady).not.toHaveBeenCalled();
+ duration = 9;
+ vi.advanceTimersByTime(200);
+ expect(onReady).toHaveBeenCalledOnce();
+ expect(onReady.mock.calls[0][0].duration).toBe(9);
+ expect(onReady.mock.calls[0][0].adapter.timeline).toBe(registered);
+ expect(onError).not.toHaveBeenCalled();
+ });
+ it("uses document duration through the runtime fallback when a timeline stays zero", () => {
+ const { iframe, onReady } = mount(root, { __timelines: { main: timeline(0) } });
+ vi.advanceTimersByTime(999);
+ expect(onReady).not.toHaveBeenCalled();
+ vi.advanceTimersByTime(1);
+ expect(iframe.contentDocument!.querySelector("script")).not.toBeNull();
+ Object.assign(iframe.contentWindow!, { __player: { getDuration: () => 0 } });
+ vi.advanceTimersByTime(200);
+ expect(onReady).toHaveBeenCalledOnce();
+ expect(onReady.mock.calls[0][0].duration).toBe(6);
+ expect(onReady.mock.calls[0][0].adapter.kind).toBe("runtime");
+ expect(onReady.mock.calls[0][0].adapter.getDuration()).toBe(6);
+ });
+ it("uses document clip ends when the runtime reports zero length", () => {
+ const { onReady } = mount(
+ '<div data-composition-id="main"><div data-start="2" data-duration="3"></div></div>',
+ { __player: { getDuration: () => 0 } },
+ );
+ vi.advanceTimersByTime(8000);
+ expect(onReady).toHaveBeenCalledOnce();
+ expect(onReady.mock.calls[0][0].duration).toBe(5);
+ expect(onReady.mock.calls[0][0].adapter.kind).toBe("runtime");
+ });
+ it("reports the first retained author error before accepting a positive adapter", () => {
+ const { onReady, onError } = mount(root, {
+ __player: { getDuration: () => 6 },
+ __hfPreviewErrors: [
+ null,
+ "",
+ "Uncaught ReferenceError: missingScene is not defined",
+ "Uncaught Error: later",
+ ],
+ });
+ vi.advanceTimersByTime(8000);
+ expect(onError).toHaveBeenCalledExactlyOnceWith(
+ "Uncaught ReferenceError: missingScene is not defined",
+ );
+ expect(onReady).not.toHaveBeenCalled();
+ });
+ it("reports an author error even while runtime injection is pending", () => {
+ const { iframe, onError } = mount(
+ '<div data-composition-id="main"><div data-composition-src="child.html"></div></div>',
+ );
+ vi.advanceTimersByTime(200);
+ Object.assign(iframe.contentWindow!, {
+ __hfPreviewErrors: ["Uncaught Error: child setup failed"],
+ });
+ vi.advanceTimersByTime(7800);
+ expect(onError).toHaveBeenCalledExactlyOnceWith("Uncaught Error: child setup failed");
+ });
+ it("times out pending runtime injection at eight seconds", () => {
+ const { onReady, onError } = mount(
+ '<div data-composition-id="main"><div data-composition-src="child.html"></div></div>',
+ );
+ vi.advanceTimersByTime(7999);
+ expect(onError).not.toHaveBeenCalled();
+ vi.advanceTimersByTime(1);
+ expect(onError).toHaveBeenCalledExactlyOnceWith("Composition timeline not found after 8s");
+ expect(onReady).not.toHaveBeenCalled();
+ vi.advanceTimersByTime(8000);
+ expect(onError).toHaveBeenCalledOnce();
+ });
+ it("does not invent duration for an unresolved document", () => {
+ const { onReady, onError } = mount('<div data-composition-id="main"></div>');
+ vi.advanceTimersByTime(8000);
+ expect(onReady).not.toHaveBeenCalled();
+ expect(onError).toHaveBeenCalledExactlyOnceWith("Composition timeline not found after 8s");
+ });
+ it("rejects initialization later than eight seconds", () => {
+ const { iframe, onReady, onError } = mount('<div data-composition-id="main"></div>');
+ vi.advanceTimersByTime(8000);
+ Object.assign(iframe.contentWindow!, { __player: { getDuration: () => 6 } });
+ vi.advanceTimersByTime(1000);
+ expect(onReady).not.toHaveBeenCalled();
+ expect(onError).toHaveBeenCalledOnce();
+ });
+ it("accepts initialization inside the eight-second budget", () => {
+ const { iframe, onReady, onError } = mount('<div data-composition-id="main"></div>');
+ vi.advanceTimersByTime(7400);
+ Object.assign(iframe.contentWindow!, { __player: { getDuration: () => 6 } });
+ vi.advanceTimersByTime(600);
+ expect(onReady).toHaveBeenCalledOnce();
+ expect(onError).not.toHaveBeenCalled();
+ });
+ it("keeps a positive adapter duration over document fallback", () => {
+ const { onReady } = mount(root, { __player: { getDuration: () => 9 } });
+ vi.advanceTimersByTime(200);
+ expect(onReady.mock.calls[0][0].duration).toBe(9);
+ });
+ it("ignores resource-event placeholders and reports the first author message", () => {
+ const { onError } = mount(root, {
+ __hfPreviewErrors: ["[object Event]", "Uncaught Error: author failed"],
+ });
+ vi.advanceTimersByTime(200);
+ expect(onError).toHaveBeenCalledExactlyOnceWith("Uncaught Error: author failed");
+ });
+ it("ignores a malformed error buffer and still loads a valid document", () => {
+ const { onReady, onError } = mount(root, { __hfPreviewErrors: { message: "not the buffer" } });
+ vi.advanceTimersByTime(200);
+ expect(onReady).toHaveBeenCalledOnce();
+ expect(onError).not.toHaveBeenCalled();
+ });
+ it("uses document duration when the adapter duration is not finite", () => {
+ const { onReady } = mount(root, { __player: { getDuration: () => Infinity } });
+ vi.advanceTimersByTime(200);
+ expect(onReady.mock.calls[0][0].duration).toBe(6);
+ });
+ it("surfaces an adapter exception instead of masking it as a timeout", () => {
+ const { onReady, onError } = mount(root, {
+ __player: {
+ getDuration: () => {
+ throw new Error("adapter initialization failed");
+ },
+ },
+ });
+ vi.advanceTimersByTime(8000);
+ expect(onReady).not.toHaveBeenCalled();
+ expect(onError).toHaveBeenCalledExactlyOnceWith("adapter initialization failed");
+ });
+});
diff --git a/packages/player/src/hyperframes-player.ts b/packages/player/src/hyperframes-player.ts
index f51d5dda2d..8567b727ea 100644
--- a/packages/player/src/hyperframes-player.ts
+++ b/packages/player/src/hyperframes-player.ts
@@ -1216,7 +1216,7 @@ class HyperframesPlayer extends HTMLElement {
private _onMessage(e: MessageEvent) {
// The iframe window outlives its documents: a late composition message must not reach a video.
- if (this._videoSource) return;
+ if (this._videoSource || this.probe.failed) return;
this._applyThenEmit(() => this._handleRuntimeMessage(e));
}
@@ -1413,6 +1413,7 @@ class HyperframesPlayer extends HTMLElement {
/** Every host-driven navigation or teardown: the old document's handshake, asset wait and
* data deliveries end here. A queued play is the caller's, so only its owners clear it. */
private _abandonComposition(reason: string): void {
+ this.probe.stop();
this._ready = false;
this._readyDocument = null;
this._invalidateAssetsWait();
diff --git a/packages/player/src/probeTerminalReadiness.test.ts b/packages/player/src/probeTerminalReadiness.test.ts
new file mode 100644
index 0000000000..55fe62d182
--- /dev/null
+++ b/packages/player/src/probeTerminalReadiness.test.ts
@@ -0,0 +1,105 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { HyperframesPlayer } from "./hyperframes-player.js";
+
+function mountPlayer() {
+ const player = document.createElement("hyperframes-player") as HyperframesPlayer;
+ document.body.appendChild(player);
+ const iframe = player.shadowRoot!.querySelector("iframe")!;
+ iframe.contentDocument!.body.innerHTML =
+ '<div data-composition-id="main"><div data-composition-src="child.html"></div></div>';
+ const onError = vi.fn();
+ const onReady = vi.fn();
+ player.addEventListener("error", onError);
+ player.addEventListener("ready", onReady);
+ iframe.dispatchEvent(new Event("load"));
+ return { player, iframe, onError, onReady };
+}
+
+function sendTimeline(iframe: HTMLIFrameElement) {
+ window.dispatchEvent(
+ new MessageEvent("message", {
+ source: iframe.contentWindow,
+ data: { source: "hf-preview", type: "timeline", durationInFrames: 270, scenes: [] },
+ }),
+ );
+}
+
+function keepDocument(iframe: HTMLIFrameElement, doc: Document | null) {
+ Object.defineProperty(iframe, "contentDocument", { configurable: true, get: () => doc });
+}
+
+function expectUnready(player: HyperframesPlayer, onReady: ReturnType<typeof vi.fn>) {
+ expect(onReady).not.toHaveBeenCalled();
+ expect(player.ready).toBe(false);
+ expect(player.duration).toBe(0);
+}
+
+function expectTimelineReady(player: HyperframesPlayer, onReady: ReturnType<typeof vi.fn>) {
+ expect(onReady).toHaveBeenCalledOnce();
+ expect(player.ready).toBe(true);
+ expect(player.duration).toBe(9);
+}
+
+describe("terminal probe readiness", () => {
+ beforeEach(async () => {
+ await import("./hyperframes-player.js");
+ vi.useFakeTimers();
+ });
+ afterEach(() => {
+ document.body.innerHTML = "";
+ vi.clearAllTimers();
+ vi.useRealTimers();
+ });
+
+ it("does not accept a runtime timeline message after the probe timed out", () => {
+ const { player, iframe, onError, onReady } = mountPlayer();
+ vi.advanceTimersByTime(8000);
+ expect(onError).toHaveBeenCalledOnce();
+ vi.advanceTimersByTime(1000);
+ sendTimeline(iframe);
+ expectUnready(player, onReady);
+ });
+
+ it("rejects the failed document while its replacement is still navigating", () => {
+ const { player, iframe, onReady } = mountPlayer();
+ vi.advanceTimersByTime(8000);
+ keepDocument(iframe, iframe.contentDocument);
+ player.setAttribute("src", "next.html");
+ sendTimeline(iframe);
+ expectUnready(player, onReady);
+ });
+
+ it("accepts the replacement document handshake before its load event", () => {
+ const { player, iframe, onReady } = mountPlayer();
+ vi.advanceTimersByTime(8000);
+ keepDocument(iframe, iframe.contentDocument);
+ player.setAttribute("src", "next.html");
+ const replacement = document.implementation.createHTMLDocument("Replacement");
+ keepDocument(iframe, replacement);
+ sendTimeline(iframe);
+ expectTimelineReady(player, onReady);
+ });
+
+ it("keeps an opaque document failure latched until its next load event", () => {
+ const { player, iframe, onError, onReady } = mountPlayer();
+ keepDocument(iframe, null);
+ vi.advanceTimersByTime(8000);
+ expect(onError).toHaveBeenCalledOnce();
+ player.setAttribute("src", "https://example.org/next.html");
+ sendTimeline(iframe);
+ expect(onReady).not.toHaveBeenCalled();
+ expect(player.ready).toBe(false);
+ iframe.dispatchEvent(new Event("load"));
+ sendTimeline(iframe);
+ expectTimelineReady(player, onReady);
+ });
+
+ it("does not accept a runtime handshake after reporting an author error", () => {
+ const { player, iframe, onError, onReady } = mountPlayer();
+ Object.assign(iframe.contentWindow!, { __hfPreviewErrors: ["Uncaught Error: author failed"] });
+ vi.advanceTimersByTime(200);
+ expect(onError.mock.calls[0][0].detail.message).toBe("Uncaught Error: author failed");
+ sendTimeline(iframe);
+ expectUnready(player, onReady);
+ });
+});
diff --git a/packages/player/src/timeline-adapters.ts b/packages/player/src/timeline-adapters.ts
index e38a98a94a..0c42194779 100644
--- a/packages/player/src/timeline-adapters.ts
+++ b/packages/player/src/timeline-adapters.ts
@@ -1,5 +1,5 @@
/**
- * Types and type-guards for the two playback adapter paths the player supports:
+ * Types and type-guards for the playback adapter paths the player supports:
*
* - `RuntimeDurationAdapter` — the HyperFrames runtime exposes `window.__player`
* with a `getDuration()` method. This is the standard path for compositions
@@ -31,6 +31,7 @@ export interface DirectTimelineAdapter {
}
export type PlaybackDurationAdapter =
+ | { kind: "document"; getDuration: () => number }
| { kind: "runtime"; getDuration: () => number }
| { kind: "direct-timeline"; timeline: DirectTimelineAdapter; getDuration: () => number };
diff --git a/packages/player/vitest.config.ts b/packages/player/vitest.config.ts
index efdfc71735..d1120714f3 100644
--- a/packages/player/vitest.config.ts
+++ b/packages/player/vitest.config.ts
@@ -9,6 +9,11 @@ const coreRoot = resolve(fileURLToPath(new URL("../core/src", import.meta.url)))
export default defineConfig({
resolve: {
alias: {
+ "@hyperframes/core/runtime/composition-length": resolve(
+ coreRoot,
+ "runtime/compositionLength.ts",
+ ),
+ "@hyperframes/core/studio-preview-mark": resolve(coreRoot, "studioPreviewMark.ts"),
"@hyperframes/core/composition-contract": resolve(coreRoot, "compositionContract.ts"),
"@hyperframes/parsers/composition-contract": resolve(
coreRoot,