Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
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.htmlnew file mode 100644index 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() >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) => void;+onError: (message: string) => 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 filediff --git a/packages/player/src/composition-probe.ts b/packages/player/src/composition-probe.tsindex 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 complexitythis._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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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,