Skip to content

Write HTML. Render video. Built for agents.

fix(core): a runtime that fails to start names its real error instead of a half-built page (#5406)

Miguel Ángel3aba29ce056a
diff --git a/packages/cli/src/capture/captureCompositionFrame.test.ts b/packages/cli/src/capture/captureCompositionFrame.test.ts
index bc1b9489f8..16c23b80c6 100644
--- a/packages/cli/src/capture/captureCompositionFrame.test.ts
+++ b/packages/cli/src/capture/captureCompositionFrame.test.ts
@@ -52,9 +52,9 @@ afterEach(() => {
describe("waitForRuntimeReady", () => {
it("waits for the runtime's render-ready flag and reports a timeout as not ready", async () => {
- const { waitForFunction } = fakeSeekPage();
+ const { waitForFunction, evaluate } = fakeSeekPage();
- await expect(waitForRuntimeReady({ waitForFunction }, 123)).resolves.toBe(true);
+ await expect(waitForRuntimeReady({ waitForFunction, evaluate }, 123)).resolves.toBe(true);
expect(waitForFunction).toHaveBeenCalledWith(expect.any(Function), { timeout: 123 });
const ready = waitForFunction.mock.calls[0]![0];
vi.stubGlobal("window", { __timelines: {} });
@@ -63,7 +63,23 @@ describe("waitForRuntimeReady", () => {
expect(ready()).toBe(true);
waitForFunction.mockRejectedValueOnce(new Error("Waiting failed: 1ms exceeded"));
- await expect(waitForRuntimeReady({ waitForFunction }, 1)).resolves.toBe(false);
+ await expect(waitForRuntimeReady({ waitForFunction, evaluate }, 1)).resolves.toBe(false);
+ });
+
+ it("fails with the runtime's start-up error instead of reporting the page ready", async () => {
+ const { waitForFunction, evaluate } = fakeSeekPage();
+ const startupError = "HyperFrames runtime failed: TypeError: boom";
+ evaluate.mockResolvedValue(startupError);
+
+ const ready = waitForFunction.mock.calls.length;
+ await expect(waitForRuntimeReady({ waitForFunction, evaluate }, 123)).rejects.toThrow(
+ startupError,
+ );
+ const predicate = waitForFunction.mock.calls[ready]![0];
+ vi.stubGlobal("window", { __hfStartupError: startupError });
+ expect(predicate()).toBe(true);
+ vi.stubGlobal("window", { __hfStartupError: { message: "not a string" } });
+ expect(predicate()).toBe(false);
});
it("is what layout, motion-shot and validate wait on before they sample the page", () => {
diff --git a/packages/cli/src/capture/captureCompositionFrame.ts b/packages/cli/src/capture/captureCompositionFrame.ts
index a44a6349c1..df64340db5 100644
--- a/packages/cli/src/capture/captureCompositionFrame.ts
+++ b/packages/cli/src/capture/captureCompositionFrame.ts
@@ -97,7 +97,10 @@ export function resolveCliChromeGpuMode(
}
function compositionRuntimeReadyInBrowser(): boolean {
- return Boolean(Reflect.get(window, "__renderReady"));
+ return (
+ Boolean(Reflect.get(window, "__renderReady")) ||
+ typeof Reflect.get(window, "__hfStartupError") === "string"
+ );
}
function shaderTransitionsReadyInBrowser(): boolean {
@@ -126,14 +129,19 @@ function shaderTransitionsReadyInBrowser(): boolean {
return shaderTransitionRegistryReady() ?? shaderLoadingOverlayReady();
}
-export function waitForRuntimeReady(
- page: Required<Pick<CompositionSeekPage, "waitForFunction">>,
+export async function waitForRuntimeReady(
+ page: Required<Pick<CompositionSeekPage, "waitForFunction" | "evaluate">>,
timeoutMs: number,
): Promise<boolean> {
- return page
+ const settled = await page
.waitForFunction(compositionRuntimeReadyInBrowser, { timeout: timeoutMs })
.then(() => true)
.catch(() => false);
+ const startupError = await page
+ .evaluate(() => Reflect.get(window, "__hfStartupError"))
+ .catch(() => undefined);
+ if (typeof startupError === "string") throw new Error(startupError);
+ return settled;
}
async function waitForCompositionSettle(
diff --git a/packages/cli/src/commands/motionShot.browserClose.test.ts b/packages/cli/src/commands/motionShot.browserClose.test.ts
new file mode 100644
index 0000000000..0ab81a1d2c
--- /dev/null
+++ b/packages/cli/src/commands/motionShot.browserClose.test.ts
@@ -0,0 +1,56 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, expect, it, vi } from "vitest";
+
+const browser = vi.hoisted(() => ({
+ close: vi.fn(async () => undefined),
+ newPage: vi.fn(async () => ({
+ setViewport: async () => undefined,
+ goto: async () => undefined,
+ evaluate: async () => undefined,
+ })),
+}));
+
+vi.mock("@hyperframes/core/compiler", () => ({
+ bundleToSingleHtml: async () => '<div data-composition-id="main"></div>',
+}));
+vi.mock("@hyperframes/engine", async (importOriginal) => ({
+ ...(await importOriginal<typeof import("@hyperframes/engine")>()),
+ buildChromeArgs: () => [],
+}));
+vi.mock("../browser/manager.js", () => ({
+ ensureBrowser: async () => ({ executablePath: "/chrome" }),
+}));
+vi.mock("../utils/staticProjectServer.js", () => ({
+ serveStaticProjectHtml: async () => ({ url: "http://127.0.0.1:1/", close: async () => {} }),
+}));
+vi.mock("../browser/launch.js", () => ({
+ launchManagedBrowser: async () => browser,
+ resolveManagedGpuMode: async () => "software",
+}));
+vi.mock("../capture/captureCompositionFrame.js", async (importOriginal) => ({
+ ...(await importOriginal<typeof import("../capture/captureCompositionFrame.js")>()),
+ waitForRuntimeReady: async () => {
+ throw new Error("HyperFrames runtime failed: Error: boom.");
+ },
+}));
+
+afterEach(() => {
+ vi.clearAllMocks();
+});
+
+it("closes the browser when the runtime fails to start, so the command exits", async () => {
+ const dir = mkdtempSync(join(tmpdir(), "hf-motion-shot-"));
+ try {
+ const { captureMotionPathShot } = await import("./motionShot.js");
+
+ await expect(
+ captureMotionPathShot(dir, [{ selector: "#box" }], join(dir, "out.png")),
+ ).rejects.toThrow("HyperFrames runtime failed");
+
+ expect(browser.close).toHaveBeenCalled();
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
diff --git a/packages/cli/src/commands/motionShot.ts b/packages/cli/src/commands/motionShot.ts
index fae2696daf..458adf1003 100644
--- a/packages/cli/src/commands/motionShot.ts
+++ b/packages/cli/src/commands/motionShot.ts
@@ -410,20 +410,25 @@ async function openCompositionPage(
executablePath,
args: buildChromeArgs({ ...size, captureMode: "screenshot", requiresWebGpu }, gpuConfig),
});
- const page = await browser.newPage();
- const navigationTimeout = resolveDiagnosticNavigationTimeoutMs();
- await page.setViewport(size);
- await page.goto(url, { waitUntil: "domcontentloaded", timeout: navigationTimeout });
- await assertWebGpuAdapterAvailable(page, requiresWebGpu, softwareWebGpu);
- await waitForRuntimeReady(page, 10000);
- await page
- .evaluate(async () => {
- const d = document as unknown as { fonts?: { ready?: Promise<unknown> } };
- if (d.fonts?.ready) await d.fonts.ready;
- })
- .catch(() => {});
- await installSeekHelper(page);
- return { browser, page, size };
+ try {
+ const page = await browser.newPage();
+ const navigationTimeout = resolveDiagnosticNavigationTimeoutMs();
+ await page.setViewport(size);
+ await page.goto(url, { waitUntil: "domcontentloaded", timeout: navigationTimeout });
+ await assertWebGpuAdapterAvailable(page, requiresWebGpu, softwareWebGpu);
+ await waitForRuntimeReady(page, 10000);
+ await page
+ .evaluate(async () => {
+ const d = document as unknown as { fonts?: { ready?: Promise<unknown> } };
+ if (d.fonts?.ready) await d.fonts.ready;
+ })
+ .catch(() => {});
+ await installSeekHelper(page);
+ return { browser, page, size };
+ } catch (err) {
+ await browser.close().catch(() => {});
+ throw err;
+ }
}
// Longest seekable duration (seconds) across registered timelines, player/root
diff --git a/packages/cli/src/commands/validate.browserClose.test.ts b/packages/cli/src/commands/validate.browserClose.test.ts
new file mode 100644
index 0000000000..a6418380df
--- /dev/null
+++ b/packages/cli/src/commands/validate.browserClose.test.ts
@@ -0,0 +1,65 @@
+import { afterEach, expect, it, vi } from "vitest";
+import { resolveProjectMock, runAndCaptureStdio } from "./deprecationTestHarness.js";
+
+const browser = vi.hoisted(() => ({
+ close: vi.fn(async () => undefined),
+ newPage: vi.fn(async () => ({
+ setViewport: async () => undefined,
+ on: () => undefined,
+ goto: async () => undefined,
+ evaluate: async () => undefined,
+ })),
+}));
+
+vi.mock("../utils/project.js", () => resolveProjectMock());
+vi.mock("../utils/lintProject.js", () => ({ lintProject: async () => ({ results: [] }) }));
+vi.mock("../utils/producer.js", () => ({
+ loadProducer: async () => {
+ const keep = async (html: string) => ({ html, remoteMediaAssets: new Map() });
+ return {
+ localizeRemoteMediaSources: keep,
+ localizeRemoteImageSources: keep,
+ localizeRemoteFontFaces: keep,
+ };
+ },
+}));
+vi.mock("@hyperframes/core/compiler", () => ({
+ bundleToSingleHtml: async () => '<div data-composition-id="main"></div>',
+}));
+vi.mock("@hyperframes/engine", async (importOriginal) => ({
+ ...(await importOriginal<typeof import("@hyperframes/engine")>()),
+ buildChromeArgs: () => [],
+}));
+vi.mock("../browser/manager.js", () => ({
+ ensureBrowser: async () => ({ executablePath: "/chrome" }),
+}));
+vi.mock("../utils/staticProjectServer.js", () => ({
+ serveStaticProjectHtml: async () => ({ url: "http://127.0.0.1:1/", close: async () => {} }),
+}));
+vi.mock("../browser/launch.js", () => ({
+ launchManagedBrowser: async () => browser,
+ resolveManagedGpuMode: async () => "software",
+}));
+vi.mock("../capture/captureCompositionFrame.js", async (importOriginal) => ({
+ ...(await importOriginal<typeof import("../capture/captureCompositionFrame.js")>()),
+ installPageFunctionGuard: async () => undefined,
+ waitForRuntimeReady: async () => {
+ throw new Error("HyperFrames runtime failed: Error: boom.");
+ },
+}));
+
+afterEach(() => {
+ vi.restoreAllMocks();
+ vi.clearAllMocks();
+});
+
+it("closes the browser when the runtime fails to start, so validate exits", async () => {
+ const { default: validateCommand } = await import("./validate.js");
+
+ const { stdoutText } = await runAndCaptureStdio(validateCommand);
+
+ expect(stdoutText + JSON.stringify(vi.mocked(console.log).mock.calls)).toContain(
+ "HyperFrames runtime failed",
+ );
+ expect(browser.close).toHaveBeenCalled();
+});
diff --git a/packages/cli/src/commands/validate.ts b/packages/cli/src/commands/validate.ts
index 35e63f1804..eb3e3997c0 100644
--- a/packages/cli/src/commands/validate.ts
+++ b/packages/cli/src/commands/validate.ts
@@ -450,75 +450,78 @@ async function validateInBrowser(
args: buildChromeArgs({ ...viewport, captureMode: "screenshot", requiresWebGpu }, gpuConfig),
});
- const page = await chromeBrowser.newPage();
- await installPageFunctionGuard(page);
- await page.setViewport(viewport);
-
- page.on("console", (msg) => {
- const type = msg.type();
- const loc = msg.location();
- const text = msg.text();
- if (type === "error") {
- if (text.startsWith("Failed to load resource")) return;
- errors.push({ level: "error", text, url: loc.url, line: loc.lineNumber });
- } else if (type === "warn") {
- warnings.push({ level: "warning", text, url: loc.url, line: loc.lineNumber });
- }
- });
-
- page.on("pageerror", (err) => {
- const text = normalizeErrorMessage(err);
- // CDN scripts (e.g. GSAP from jsdelivr) returning HTML error pages
- // instead of JS produce "Unexpected token '<'" SyntaxErrors. These
- // are network failures, not composition authoring errors.
- if (text.includes("Unexpected token '<'") || text.includes("Unexpected token '&lt;'")) return;
- errors.push({ level: "error", text });
- });
+ try {
+ const page = await chromeBrowser.newPage();
+ await installPageFunctionGuard(page);
+ await page.setViewport(viewport);
+
+ page.on("console", (msg) => {
+ const type = msg.type();
+ const loc = msg.location();
+ const text = msg.text();
+ if (type === "error") {
+ if (text.startsWith("Failed to load resource")) return;
+ errors.push({ level: "error", text, url: loc.url, line: loc.lineNumber });
+ } else if (type === "warn") {
+ warnings.push({ level: "warning", text, url: loc.url, line: loc.lineNumber });
+ }
+ });
- page.on("requestfailed", (req) => {
- const url = req.url();
- if (url.includes("favicon") || url.startsWith("data:")) return;
- const failureText = req.failure()?.errorText;
- if (shouldIgnoreRequestFailure(url, failureText, req.resourceType())) return;
- const path = projectPathOfUrl(url);
- errors.push({
- level: "error",
- text: `Failed to load ${path}: ${failureText ?? "net::ERR_FAILED"}`,
- url,
+ page.on("pageerror", (err) => {
+ const text = normalizeErrorMessage(err);
+ // CDN scripts (e.g. GSAP from jsdelivr) returning HTML error pages
+ // instead of JS produce "Unexpected token '<'" SyntaxErrors. These
+ // are network failures, not composition authoring errors.
+ if (text.includes("Unexpected token '<'") || text.includes("Unexpected token '&lt;'"))
+ return;
+ errors.push({ level: "error", text });
});
- });
- page.on("response", (res) => {
- if (res.status() >= 400) {
- const url = res.url();
- if (url.includes("favicon")) return;
- if (shouldIgnoreHttpError(url, res.status())) return;
+ page.on("requestfailed", (req) => {
+ const url = req.url();
+ if (url.includes("favicon") || url.startsWith("data:")) return;
+ const failureText = req.failure()?.errorText;
+ if (shouldIgnoreRequestFailure(url, failureText, req.resourceType())) return;
const path = projectPathOfUrl(url);
- errors.push({ level: "error", text: `${res.status()} loading ${path}`, url });
- }
- });
+ errors.push({
+ level: "error",
+ text: `Failed to load ${path}: ${failureText ?? "net::ERR_FAILED"}`,
+ url,
+ });
+ });
- const navTimeoutMs = resolveNavigationTimeoutMs(opts.timeout);
- try {
- await page.goto(server.url, { waitUntil: "domcontentloaded", timeout: navTimeoutMs });
- } catch (err) {
- const hinted = navigationTimeoutHint(err, navTimeoutMs);
- if (hinted) throw hinted;
- throw err;
- }
- await assertWebGpuAdapterAvailable(page, requiresWebGpu, softwareWebGpu);
- await waitForRuntimeReady(page, opts.timeout ?? 3000);
- await new Promise((r) => setTimeout(r, opts.timeout ?? 3000));
+ page.on("response", (res) => {
+ if (res.status() >= 400) {
+ const url = res.url();
+ if (url.includes("favicon")) return;
+ if (shouldIgnoreHttpError(url, res.status())) return;
+ const path = projectPathOfUrl(url);
+ errors.push({ level: "error", text: `${res.status()} loading ${path}`, url });
+ }
+ });
- for (const w of await auditClipDurations(page, analyzeClipMediaFit, opts.timeout ?? 3000)) {
- warnings.push(w);
- }
+ const navTimeoutMs = resolveNavigationTimeoutMs(opts.timeout);
+ try {
+ await page.goto(server.url, { waitUntil: "domcontentloaded", timeout: navTimeoutMs });
+ } catch (err) {
+ const hinted = navigationTimeoutHint(err, navTimeoutMs);
+ if (hinted) throw hinted;
+ throw err;
+ }
+ await assertWebGpuAdapterAvailable(page, requiresWebGpu, softwareWebGpu);
+ await waitForRuntimeReady(page, opts.timeout ?? 3000);
+ await new Promise((r) => setTimeout(r, opts.timeout ?? 3000));
- if (opts.contrast) {
- contrast = await runContrastAudit(page);
- }
+ for (const w of await auditClipDurations(page, analyzeClipMediaFit, opts.timeout ?? 3000)) {
+ warnings.push(w);
+ }
- await chromeBrowser.close();
+ if (opts.contrast) {
+ contrast = await runContrastAudit(page);
+ }
+ } finally {
+ await chromeBrowser.close().catch(() => {});
+ }
} finally {
await server.close();
localized.cleanup();
diff --git a/packages/cli/src/utils/checkBrowser.test.ts b/packages/cli/src/utils/checkBrowser.test.ts
index 60b5df99c7..bc6768cf57 100644
--- a/packages/cli/src/utils/checkBrowser.test.ts
+++ b/packages/cli/src/utils/checkBrowser.test.ts
@@ -14,6 +14,7 @@ import {
keepBrokenImageAborts,
preResolveHostileMediaProxies,
runBrowserCheck,
+ collectSeekClock,
} from "./checkBrowser.js";
import type { ProjectDir } from "./project.js";
@@ -528,6 +529,28 @@ it("elevates and deduplicates WebGPU validation warnings while preserving ordina
);
});
+describe("collectSeekClock", () => {
+ afterEach(() => {
+ Reflect.deleteProperty(window, "__timelines");
+ Reflect.deleteProperty(window, "__hfSeekClocks");
+ });
+
+ const seekPage = { evaluate: async (fn: () => unknown) => fn() } as unknown as Parameters<
+ typeof collectSeekClock
+ >[0];
+
+ it("skips a custom clock whose time() returns null instead of reading it as 0", async () => {
+ Reflect.set(window, "__timelines", {
+ root: { duration: () => 9, seek() {}, time: () => null },
+ card: { duration: () => 9, seek() {}, time: () => 3 },
+ });
+
+ const clocks = await collectSeekClock(seekPage);
+
+ expect(clocks.map((clock) => clock.time)).toEqual([3]);
+ });
+});
+
describe("keepBrokenImageAborts", () => {
const draft = (url: string, abortedImage: boolean) => ({
code: "request_failed",
diff --git a/packages/cli/src/utils/checkBrowser.ts b/packages/cli/src/utils/checkBrowser.ts
index 043734386f..295eee1d1a 100644
--- a/packages/cli/src/utils/checkBrowser.ts
+++ b/packages/cli/src/utils/checkBrowser.ts
@@ -647,10 +647,8 @@ export async function collectSeekClock(page: Page): Promise<SeekClock[]> {
callOrUndefined(timeline, "totalDuration") ?? callOrUndefined(timeline, "duration"),
);
if (typeof timeline !== "object" || !timeline || !(total > 0)) continue;
- const time = Number(
- callOrUndefined(timeline, "totalTime") ?? callOrUndefined(timeline, "time"),
- );
- if (!Number.isFinite(time)) continue;
+ const time = callOrUndefined(timeline, "totalTime") ?? callOrUndefined(timeline, "time");
+ if (typeof time !== "number" || !Number.isFinite(time)) continue;
const progress = Number(callOrUndefined(timeline, "totalProgress") ?? time / total);
const done = callOrUndefined(timeline, "reversed") === true ? progress <= 0 : progress >= 1;
clocks.push({ id: idOf(timeline), time, done });
diff --git a/packages/core/src/generated/position-edits-render-inline.ts b/packages/core/src/generated/position-edits-render-inline.ts
index 29052cdd83..5788290675 100644
--- a/packages/core/src/generated/position-edits-render-inline.ts
+++ b/packages/core/src/generated/position-edits-render-inline.ts
@@ -1,6 +1,6 @@
// Generated by scripts/build-position-edits-render.ts; do not edit.
const POSITION_EDITS_RENDER_IIFE: string =
- '"use strict";(()=>{function T(){return globalThis}function P(e,t){if(typeof window>"u")return;let o=T(),r=o.__hf?.onSwallowed;if(r)try{r({label:e,error:t})}catch(s){}(o.__hfDebug||o.__HYPERFRAMES_DEBUG)&&console.debug(`[hyperframes] ${e} swallowed:`,t)}var x=null;function R(e,t){if(x)try{x({source:"hf-preview",type:"analytics",event:e,properties:t??{}})}catch(o){P("runtime.analytics.site1",o)}}var W="http://www.w3.org/1999/xhtml";function N(e){return e!=null&&e.nodeType===1}function _(e){return N(e)&&(e.namespaceURI===W||e.namespaceURI==="http://www.w3.org/2000/svg")}var w="data-hf-edit-base-x",y="data-hf-edit-base-y",m="data-hf-edit-original-translate",k=e=>{let t=parseFloat(e??"");return Number.isFinite(t)?t:0},O=e=>{let t=[],o=0,r="";for(let s of e.trim())s==="("&&(o+=1),s===")"&&(o=Math.max(0,o-1)),/\\s/.test(s)&&o===0?(r&&t.push(r),r=""):r+=s;return r&&t.push(r),t},L=/^-?(?:\\d+(?:\\.\\d+)?|\\.\\d+)px$/,E=(e,t)=>L.test(e)&&L.test(t)?`${parseFloat(e)+parseFloat(t)}px`:`calc(${e} + ${t})`,V=(e,t,o)=>{if(!e||e==="none")return`${t} ${o}`;let[r,s,a]=O(e);if(r===void 0)return`${t} ${o}`;if(s===void 0)return`${E(r,t)} ${o}`;let i=a===void 0?"":` ${a}`;return`${E(r,t)} ${E(s,o)}${i}`},j=e=>{try{e.ownerDocument.defaultView?.gsap?.getProperty?.(e,"x")}catch{}},G=e=>{let t=e.style.getPropertyValue("translate").trim();if(t)return t==="none"?"":t;try{let o=e.ownerDocument.defaultView,r=o?o.getComputedStyle(e).getPropertyValue("translate").trim():"";return r==="none"?"":r}catch{return""}},b=new WeakMap;function B(e,t){let o=b.get(e);if(!t?.force&&o!==void 0&&e.style.getPropertyValue("translate")!==o){R("position_edit_fold_skipped",{hfId:e.getAttribute("data-hf-id")});return}let r=k(e.getAttribute("data-x"))-k(e.getAttribute(w)),s=k(e.getAttribute("data-y"))-k(e.getAttribute(y));e.hasAttribute(m)||e.setAttribute(m,G(e)),o===void 0&&j(e);let a=e.getAttribute(m)??"",i=V(a,`${r}px`,`${s}px`);e.style.setProperty("translate",i),b.set(e,e.style.getPropertyValue("translate"))}function S(e,t){let o=e.querySelectorAll(`[${m}]:not([${w}]):not([${y}])`);for(let a=0;a<o.length;a++){let i=o[a];if(i===void 0||!_(i))continue;let g=i.getAttribute(m)??"";g===""?i.style.removeProperty("translate"):i.style.setProperty("translate",g),i.removeAttribute(m),b.delete(i)}let r=e.querySelectorAll(`[${w}], [${y}]`),s=0;for(let a=0;a<r.length;a++){let i=r[a];i===void 0||!_(i)||(B(i,t),s+=1)}return s}var $="__hfPositionEditsSeekReapplyWrapped",D=new WeakSet,M=new WeakMap,H=new WeakMap;function F(e){let t=e,o=()=>{try{S(t.document)}catch{}},r=n=>typeof n=="function"&&(D.has(n)||!!n[$]),s=n=>{D.add(n);try{Object.defineProperty(n,$,{value:!0})}catch{}},a=n=>{if(typeof n!="function"||r(n))return n;let l=function(...u){let d=n.apply(this,u);return o(),d};return s(l),l},i=(n,l)=>{let u=M.get(n);if(u?.has(l))return!0;let d=Object.getOwnPropertyDescriptor(n,l);if(d?.configurable===!1){let c=n[l];return typeof c=="function"&&(n[l]=a(c),o()),!1}let p=n[l],f=d?.set;return Object.defineProperty(n,l,{configurable:!0,enumerable:d?.enumerable??!0,get:()=>p,set:c=>{p=a(c),f?.call(n,c)}}),p=a(p),u??(u=new Set),u.add(l),M.set(n,u),o(),!0},g=(n,l)=>{let u=H.get(t),d=Object.getOwnPropertyDescriptor(t,n);if(!u?.has(n)){if(d?.configurable===!1){let c=t[n];return c?i(c,l):!1}let f=t[n];Object.defineProperty(t,n,{configurable:!0,enumerable:d?.enumerable??!0,get:()=>f,set:c=>{f=c,f&&i(f,l)}}),u??(u=new Set),u.add(n),H.set(t,u)}let p=t[n];return p?i(p,l):!1},v=()=>{let n=g("__hf","seek"),l=g("__player","renderSeek");return n&&l};if(v())return;let h=120,A=t.setInterval(()=>{if(v()){t.clearInterval(A);return}h-=1,h<=0&&t.clearInterval(A)},50)}function I(){document.querySelector(`[${w}], [${y}]`)&&(S(document),F(window))}document.readyState==="loading"?document.addEventListener("DOMContentLoaded",I,{once:!0}):I();})();\n';
+ '"use strict";(()=>{function T(){return globalThis}function P(e,t){if(typeof window>"u")return;let o=T(),r=o.__hf?.onSwallowed;if(r)try{r({label:e,error:t})}catch(s){}(o.__hfDebug||o.__HYPERFRAMES_DEBUG)&&console.debug(`[hyperframes] ${e} swallowed:`,t)}var x=null;function R(e,t){if(x)try{x({source:"hf-preview",type:"analytics",event:e,properties:t??{}})}catch(o){P("runtime.analytics.site1",o)}}var W="http://www.w3.org/1999/xhtml";function N(e){return e!=null&&e.nodeType===1}function k(e){return N(e)&&(e.namespaceURI===W||e.namespaceURI==="http://www.w3.org/2000/svg")}var w="data-hf-edit-base-x",y="data-hf-edit-base-y",m="data-hf-edit-original-translate",_=e=>{let t=parseFloat(e??"");return Number.isFinite(t)?t:0},O=e=>{let t=[],o=0,r="";for(let s of e.trim())s==="("&&(o+=1),s===")"&&(o=Math.max(0,o-1)),/\\s/.test(s)&&o===0?(r&&t.push(r),r=""):r+=s;return r&&t.push(r),t},L=/^-?(?:\\d+(?:\\.\\d+)?|\\.\\d+)px$/,E=(e,t)=>L.test(e)&&L.test(t)?`${parseFloat(e)+parseFloat(t)}px`:`calc(${e} + ${t})`,V=(e,t,o)=>{if(!e||e==="none")return`${t} ${o}`;let[r,s,a]=O(e);if(r===void 0)return`${t} ${o}`;if(s===void 0)return`${E(r,t)} ${o}`;let i=a===void 0?"":` ${a}`;return`${E(r,t)} ${E(s,o)}${i}`},j=e=>{try{e.ownerDocument.defaultView?.gsap?.getProperty?.(e,"x")}catch{}},C=e=>{let t=e.style.getPropertyValue("translate").trim();if(t)return t==="none"?"":t;try{let o=e.ownerDocument.defaultView,r=o?o.getComputedStyle(e).getPropertyValue("translate").trim():"";return r==="none"?"":r}catch{return""}},b=new WeakMap;function G(e,t){let o=b.get(e);if(!t?.force&&o!==void 0&&e.style.getPropertyValue("translate")!==o){R("position_edit_fold_skipped",{hfId:e.getAttribute("data-hf-id")});return}let r=_(e.getAttribute("data-x"))-_(e.getAttribute(w)),s=_(e.getAttribute("data-y"))-_(e.getAttribute(y));e.hasAttribute(m)||e.setAttribute(m,C(e)),o===void 0&&j(e);let a=e.getAttribute(m)??"",i=V(a,`${r}px`,`${s}px`);e.style.setProperty("translate",i),b.set(e,e.style.getPropertyValue("translate"))}function S(e,t){let o=e.querySelectorAll(`[${m}]:not([${w}]):not([${y}])`);for(let a=0;a<o.length;a++){let i=o[a];if(i===void 0||!k(i))continue;let g=i.getAttribute(m)??"";g===""?i.style.removeProperty("translate"):i.style.setProperty("translate",g),i.removeAttribute(m),b.delete(i)}let r=e.querySelectorAll(`[${w}], [${y}]`),s=0;for(let a=0;a<r.length;a++){let i=r[a];i===void 0||!k(i)||(G(i,t),s+=1)}return s}var $="__hfPositionEditsSeekReapplyWrapped",D=new WeakSet,M=new WeakMap,H=new WeakMap;function F(e){let t=e,o=()=>{try{S(t.document)}catch{}},r=n=>typeof n=="function"&&(D.has(n)||!!n[$]),s=n=>{D.add(n);try{Object.defineProperty(n,$,{value:!0})}catch{}},a=n=>{if(typeof n!="function"||r(n))return n;let l=function(...u){let d=n.apply(this,u);return o(),d};return s(l),l},i=(n,l)=>{let u=M.get(n);if(u?.has(l))return!0;let d=Object.getOwnPropertyDescriptor(n,l);if(d?.configurable===!1){let c=n[l];return typeof c=="function"&&(n[l]=a(c),o()),!1}let p=n[l],f=d?.set;return Object.defineProperty(n,l,{configurable:!0,enumerable:d?.enumerable??!0,get:()=>p,set:c=>{p=a(c),f?.call(n,c)}}),p=a(p),u??(u=new Set),u.add(l),M.set(n,u),o(),!0},g=(n,l)=>{let u=H.get(t),d=Object.getOwnPropertyDescriptor(t,n);if(!u?.has(n)){if(d?.configurable===!1){let c=t[n];return c?i(c,l):!1}let f=t[n];Object.defineProperty(t,n,{configurable:!0,enumerable:d?.enumerable??!0,get:()=>f,set:c=>{f=c,f&&i(f,l)}}),u??(u=new Set),u.add(n),H.set(t,u)}let p=t[n];return p?i(p,l):!1},h=()=>{let n=g("__hf","seek"),l=g("__player","renderSeek");return n&&l};if(h())return;let v=120,A=t.setInterval(()=>{if(h()){t.clearInterval(A);return}v-=1,v<=0&&t.clearInterval(A)},50)}function I(){document.querySelector(`[${w}], [${y}]`)&&(S(document),F(window))}document.readyState==="loading"?document.addEventListener("DOMContentLoaded",I,{once:!0}):I();})();\n';
/** Returns the pre-built position-edits render IIFE as a string constant. */
export function getPositionEditsRenderScript(): string {
diff --git a/packages/core/src/runtime/clipTree.test.ts b/packages/core/src/runtime/clipTree.test.ts
index ba61438acc..8e31c30871 100644
--- a/packages/core/src/runtime/clipTree.test.ts
+++ b/packages/core/src/runtime/clipTree.test.ts
@@ -81,6 +81,28 @@ describe("createClipTree", () => {
);
});
+ it.each([
+ ["a number", { duration: 4, seek() {} }],
+ [
+ "a method that throws",
+ {
+ duration() {
+ throw new Error("boom");
+ },
+ seek() {},
+ },
+ ],
+ ])("keeps a sub-composition whose registered duration is %s on the root window", (_, tl) => {
+ document.body.innerHTML = `
+ <div data-composition-id="root" data-duration="10" data-start="0" id="root">
+ <div data-composition-id="extra" data-start="0" id="extra"></div>
+ </div>`;
+ const registry = { extra: tl } as unknown as typeof params.timelineRegistry;
+ expect(
+ createClipTree({ ...params, timelineRegistry: registry }).roots.map((n) => n.id),
+ ).toContain("extra");
+ });
+
it.each([10, 11])(
"does not replace a known zero media span with root duration (start=%s)",
(start) => {
diff --git a/packages/core/src/runtime/clipTree.ts b/packages/core/src/runtime/clipTree.ts
index f22c80e8e3..47ad3575b9 100644
--- a/packages/core/src/runtime/clipTree.ts
+++ b/packages/core/src/runtime/clipTree.ts
@@ -17,6 +17,7 @@ import {
resolveTimedImageDurationSeconds,
} from "./playbackRate";
import { isMediaElement } from "./domRealm";
+import { readTimelineDurationSeconds } from "./timelineDuration";
import { findRootCompositionElement } from "./compositionDimension";
export interface ClipNode {
@@ -67,8 +68,8 @@ function durationFromTimeline(
): number | null {
const compId = el.getAttribute("data-composition-id");
if (!compId) return null;
- const d = Number(registry[compId]?.duration?.());
- return Number.isFinite(d) && d > 0 ? d : null;
+ const d = readTimelineDurationSeconds(registry[compId]);
+ return d != null && d > 0 ? d : null;
}
function durationFromMedia(el: Element): number | null {
diff --git a/packages/core/src/runtime/diagnostics.ts b/packages/core/src/runtime/diagnostics.ts
index 5ba8d433b7..2d282a4190 100644
--- a/packages/core/src/runtime/diagnostics.ts
+++ b/packages/core/src/runtime/diagnostics.ts
@@ -29,6 +29,19 @@
*/
import { getDebugSurface } from "./globals.js";
+/** The named error readiness waits fail with once start-up or the render-ready publish throws; it stays set. */
+export function recordStartupError(error: unknown): void {
+ let detail = "unknown error";
+ try {
+ detail = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+ } catch (err) {
+ swallow("runtime.startupError", err);
+ }
+ (window as Window & { __hfStartupError?: string }).__hfStartupError =
+ `HyperFrames runtime failed: ${detail}. Check the composition's scripts and window.__timelines ` +
+ `entries; if they look right, report this as a HyperFrames bug.`;
+}
+
export function swallow(label: string, error?: unknown): void {
if (typeof window === "undefined") return;
const w = getDebugSurface();
diff --git a/packages/core/src/runtime/entry.startupFailure.test.ts b/packages/core/src/runtime/entry.startupFailure.test.ts
new file mode 100644
index 0000000000..bb40776332
--- /dev/null
+++ b/packages/core/src/runtime/entry.startupFailure.test.ts
@@ -0,0 +1,141 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { RuntimeTimelineLike } from "./types";
+
+// Its own file: a start-up that throws never installs its teardown, so what it started would leak into later tests.
+async function evaluateRuntime(): Promise<void> {
+ vi.resetModules();
+ await import("./entry");
+}
+
+function mountRoot(): void {
+ document.body.innerHTML = `<div data-composition-id="main" data-root="true" data-start="0"
+ data-width="1920" data-height="1080"></div>`;
+ const duration = () => 10;
+ window.__timelines = {
+ main: {
+ play() {},
+ pause() {},
+ seek() {},
+ time: () => 0,
+ duration,
+ } as unknown as RuntimeTimelineLike,
+ };
+}
+
+describe("runtime start-up failure", () => {
+ afterEach(() => {
+ vi.useRealTimers();
+ vi.unstubAllGlobals();
+ vi.doUnmock("./init");
+ vi.doUnmock("./clipTree");
+ vi.doUnmock("./timeline");
+ document.body.innerHTML = "";
+ window.__timelines = {};
+ delete window.__renderReady;
+ delete window.__hfStartupError;
+ delete window.__hfTimelinesBuilding;
+ window.__hfRuntimeTeardown?.();
+ delete (window as { __hyperframeRuntimeBootstrapped?: boolean })
+ .__hyperframeRuntimeBootstrapped;
+ });
+
+ it("records a named start-up error when runtime start-up throws", async () => {
+ vi.doMock("./init", async (importOriginal) => ({
+ ...(await importOriginal<typeof import("./init")>()),
+ initSandboxRuntimeModular: () => {
+ throw new TypeError("boom");
+ },
+ }));
+
+ await expect(evaluateRuntime()).rejects.toThrow("boom");
+ expect(window.__hfStartupError).toContain("HyperFrames runtime failed: TypeError: boom");
+ expect(window.__hfStartupError).toContain(
+ "Check the composition's scripts and window.__timelines",
+ );
+ });
+
+ it("still records the failure when the thrown value cannot be printed", async () => {
+ const thrown: unknown = Object.create(null);
+ vi.doMock("./init", async (importOriginal) => ({
+ ...(await importOriginal<typeof import("./init")>()),
+ initSandboxRuntimeModular: () => {
+ throw thrown;
+ },
+ }));
+
+ await expect(evaluateRuntime()).rejects.toBe(thrown);
+ expect(window.__hfStartupError).toContain("HyperFrames runtime failed: unknown error.");
+ });
+
+ it("is not marked render-ready when posting the timeline throws", async () => {
+ vi.useFakeTimers();
+ vi.stubGlobal("CSS", { escape: (value: string) => value });
+ mountRoot();
+ vi.doMock("./clipTree", async (importOriginal) => ({
+ ...(await importOriginal<typeof import("./clipTree")>()),
+ createClipTree: () => {
+ throw new Error("clip tree");
+ },
+ }));
+
+ await expect(evaluateRuntime()).rejects.toThrow("clip tree");
+ expect(window.__renderReady).not.toBe(true);
+ expect(window.__hfStartupError).toContain("HyperFrames runtime failed: Error: clip tree");
+ });
+
+ it("names the error when a timeline post after start-up throws", async () => {
+ vi.useFakeTimers();
+ vi.stubGlobal("CSS", { escape: (value: string) => value });
+ mountRoot();
+ let failPosts = false;
+ vi.doMock("./timeline", async (importOriginal) => {
+ const actual = await importOriginal<typeof import("./timeline")>();
+ return {
+ ...actual,
+ collectRuntimeTimelinePayload: (
+ ...args: Parameters<typeof actual.collectRuntimeTimelinePayload>
+ ) => {
+ if (failPosts) throw new Error("late timeline post");
+ return actual.collectRuntimeTimelinePayload(...args);
+ },
+ };
+ });
+
+ await evaluateRuntime();
+ expect(window.__renderReady).toBe(true);
+ expect(window.__hfStartupError).toBeUndefined();
+ failPosts = true;
+
+ expect(() => vi.advanceTimersByTime(1)).toThrow("late timeline post");
+ expect(window.__renderReady).not.toBe(true);
+ expect(window.__hfStartupError).toContain(
+ "HyperFrames runtime failed: Error: late timeline post",
+ );
+ });
+
+ it("keeps a start-up error after a later timeline post succeeds", async () => {
+ vi.useFakeTimers();
+ vi.stubGlobal("CSS", { escape: (value: string) => value });
+ mountRoot();
+ let posts = 0;
+ vi.doMock("./timeline", async (importOriginal) => {
+ const actual = await importOriginal<typeof import("./timeline")>();
+ return {
+ ...actual,
+ collectRuntimeTimelinePayload: (
+ ...args: Parameters<typeof actual.collectRuntimeTimelinePayload>
+ ) => {
+ posts += 1;
+ if (posts === 2) throw new Error("end of start-up");
+ return actual.collectRuntimeTimelinePayload(...args);
+ },
+ };
+ });
+
+ await expect(evaluateRuntime()).rejects.toThrow("end of start-up");
+ vi.advanceTimersByTime(1);
+
+ expect(posts).toBeGreaterThan(2);
+ expect(window.__hfStartupError).toContain("HyperFrames runtime failed: Error: end of start-up");
+ });
+});
diff --git a/packages/core/src/runtime/entry.ts b/packages/core/src/runtime/entry.ts
index 6e1d56226a..bdbf4782f2 100644
--- a/packages/core/src/runtime/entry.ts
+++ b/packages/core/src/runtime/entry.ts
@@ -1,4 +1,5 @@
import { refreshSvgSelectorAliases } from "../compiler/svgSelectorAliases";
+import { recordStartupError } from "./diagnostics";
import {
initSandboxRuntimeModular,
installAuthoredMediaCapture,
@@ -68,7 +69,12 @@ function bootstrapHyperframeRuntime(): void {
return;
}
win.__hyperframeRuntimeBootstrapped = true;
- initSandboxRuntimeModular();
+ try {
+ initSandboxRuntimeModular();
+ } catch (err) {
+ recordStartupError(err);
+ throw err;
+ }
}
// Compiled composition scripts wait for web fonts, so what they measure matches every run.
diff --git a/packages/core/src/runtime/init.test.ts b/packages/core/src/runtime/init.test.ts
index eafa8260d9..7d4fef3648 100644
--- a/packages/core/src/runtime/init.test.ts
+++ b/packages/core/src/runtime/init.test.ts
@@ -5214,6 +5214,37 @@ describe("initSandboxRuntimeModular", () => {
player?.renderSeek(2);
}).not.toThrow();
});
+
+ const throwingDurationGetter = Object.defineProperty({ seek() {} }, "duration", {
+ get() {
+ throw new Error("getter");
+ },
+ });
+ it.each([
+ ["a number", { duration: 4, seek() {} }],
+ [
+ "a method that throws",
+ {
+ duration() {
+ throw new Error("boom");
+ },
+ seek() {},
+ },
+ ],
+ ["a getter that throws", throwingDurationGetter],
+ ])("starts and seeks when a sub-composition's registered duration is %s", (_, extra) => {
+ document.body.innerHTML = `
+ <div data-composition-id="main" data-root="true" data-start="0" data-duration="10" data-width="1920" data-height="1080">
+ <div data-composition-id="extra" data-start="0"></div>
+ </div>`;
+ window.__timelines = {
+ main: createMockTimeline(10),
+ extra: extra as unknown as RuntimeTimelineLike,
+ };
+
+ expect(() => initSandboxRuntimeModular()).not.toThrow();
+ expect(() => window.__player?.renderSeek(1)).not.toThrow();
+ });
});
// jsdom has no AudioContext; without one `WebAudioTransport.init()` fails, Web Audio scheduling
diff --git a/packages/core/src/runtime/init.ts b/packages/core/src/runtime/init.ts
index 6dd1ac75b7..76217e6d12 100644
--- a/packages/core/src/runtime/init.ts
+++ b/packages/core/src/runtime/init.ts
@@ -127,7 +127,8 @@ import type {
SceneAnimation,
} from "./types";
import type { PlayerAPI } from "../core.types";
-import { swallow } from "./diagnostics";
+import { recordStartupError, swallow } from "./diagnostics";
+import { readTimelineDurationSeconds } from "./timelineDuration";
import {
CHANGE_DRIVEN_SERVICE_MIN_INTERVAL_MS,
MEDIA_BIND_INTERVAL_FRAMES,
@@ -1012,14 +1013,8 @@ export function initSandboxRuntimeModular(): void {
let externalCompositionsReady = !hasExternalCompositions && !hasInlineTemplateCompositions;
const getTimelineDurationSeconds = (timeline: RuntimeTimelineLike | null): number | null => {
- if (!timeline || typeof timeline.duration !== "function") return null;
- try {
- const raw = Number(timeline.duration());
- if (!Number.isFinite(raw)) return null;
- return Math.max(0, raw);
- } catch {
- return null;
- }
+ const raw = readTimelineDurationSeconds(timeline);
+ return raw == null ? null : Math.max(0, raw);
};
const isUsableTimelineDuration = (durationSeconds: number | null): durationSeconds is number =>
@@ -4126,7 +4121,13 @@ export function initSandboxRuntimeModular(): void {
// Set after any GSAP batching has completed. renderSeek works with or
// without a GSAP timeline (CSS/WAAPI/Lottie compositions use adapters only).
window.__renderReady = true;
- postTimeline();
+ try {
+ postTimeline();
+ } catch (err) {
+ window.__renderReady = false;
+ recordStartupError(err);
+ throw err;
+ }
postState(true);
};
diff --git a/packages/core/src/runtime/startResolver.ts b/packages/core/src/runtime/startResolver.ts
index f331d65990..878b4377ea 100644
--- a/packages/core/src/runtime/startResolver.ts
+++ b/packages/core/src/runtime/startResolver.ts
@@ -1,5 +1,5 @@
import type { RuntimeTimelineLike } from "./types";
-import { swallow } from "./diagnostics";
+import { readTimelineDurationSeconds } from "./timelineDuration";
import { resolveAuthoredTimingWindow } from "./authoredTiming";
// Straight from playbackRate, not through media.ts's re-export: media.ts
// imports mediaVolumeEnvelope, which needs this resolver, and the round trip
@@ -84,18 +84,8 @@ export function createRuntimeStartTimeResolver(params: {
if (resolved == null || resolved <= 0) {
const compositionId = element.getAttribute("data-composition-id");
if (compositionId) {
- const timeline = timelineRegistry[compositionId] ?? null;
- if (timeline && typeof timeline.duration === "function") {
- try {
- const timelineDuration = Number(timeline.duration());
- if (Number.isFinite(timelineDuration) && timelineDuration > 0) {
- resolved = timelineDuration;
- }
- } catch (err) {
- // ignore broken timeline impls
- swallow("runtime.startResolver.site1", err);
- }
- }
+ const timelineDuration = readTimelineDurationSeconds(timelineRegistry[compositionId]);
+ if (timelineDuration != null && timelineDuration > 0) resolved = timelineDuration;
}
}
if (resolved != null && Number.isFinite(resolved) && resolved > 0) {
diff --git a/packages/core/src/runtime/timeline.ts b/packages/core/src/runtime/timeline.ts
index 36be7d827a..911e897c00 100644
--- a/packages/core/src/runtime/timeline.ts
+++ b/packages/core/src/runtime/timeline.ts
@@ -12,6 +12,7 @@ import {
resolveAuthoredTimingWindow,
} from "./authoredTiming";
import { swallow } from "./diagnostics";
+import { readTimelineDurationSeconds } from "./timelineDuration";
import { readElementPlaybackRate, readElementPlaybackStart } from "./media";
import {
parseStrictFiniteTimingNumber,
@@ -53,10 +54,7 @@ export function isRuntimeElementVisibleAt(
const compId = rawNode.getAttribute("data-composition-id");
if (compId) {
const compTimeline = options.timelineRegistry[compId];
- const liveDuration =
- compTimeline && typeof compTimeline.duration === "function"
- ? Number(compTimeline.duration())
- : null;
+ const liveDuration = readTimelineDurationSeconds(compTimeline);
const hasAuthoredTiming =
rawNode.hasAttribute("data-duration") ||
rawNode.hasAttribute("data-end") ||
@@ -66,7 +64,6 @@ export function isRuntimeElementVisibleAt(
!hasAuthoredTiming &&
(duration == null || duration <= 0) &&
liveDuration != null &&
- Number.isFinite(liveDuration) &&
liveDuration > 0
) {
duration = liveDuration;
@@ -261,14 +258,8 @@ export function collectRuntimeTimelinePayload(params: {
});
const resolveTimelineDurationSeconds = (compositionId: string | null): number | null => {
if (!compositionId) return null;
- const timeline = timelineRegistry[compositionId] ?? null;
- if (!timeline || typeof timeline.duration !== "function") return null;
- try {
- const duration = Number(timeline.duration());
- return Number.isFinite(duration) && duration > 0 ? duration : null;
- } catch {
- return null;
- }
+ const duration = readTimelineDurationSeconds(timelineRegistry[compositionId]);
+ return duration != null && duration > 0 ? duration : null;
};
const resolveMediaWindowEndSeconds = (): number | null => {
const mediaNodes = Array.from(
diff --git a/packages/core/src/runtime/timelineDuration.ts b/packages/core/src/runtime/timelineDuration.ts
new file mode 100644
index 0000000000..ec8e94dfda
--- /dev/null
+++ b/packages/core/src/runtime/timelineDuration.ts
@@ -0,0 +1,16 @@
+import { swallow } from "./diagnostics";
+import type { RuntimeTimelineLike } from "./types";
+
+/** A registered timeline's finite duration(); a partial, throwing or non-numeric entry reads as null. */
+export function readTimelineDurationSeconds(
+ timeline: Pick<RuntimeTimelineLike, "duration"> | null | undefined,
+): number | null {
+ try {
+ if (typeof timeline?.duration !== "function") return null;
+ const seconds = Number(timeline.duration());
+ return Number.isFinite(seconds) ? seconds : null;
+ } catch (err) {
+ swallow("runtime.timelineDuration", err);
+ return null;
+ }
+}
diff --git a/packages/core/src/runtime/window.d.ts b/packages/core/src/runtime/window.d.ts
index 3ab1185db3..542b834dc0 100644
--- a/packages/core/src/runtime/window.d.ts
+++ b/packages/core/src/runtime/window.d.ts
@@ -92,6 +92,8 @@ declare global {
};
__playerReady?: boolean;
__renderReady?: boolean;
+ /** Set when start-up or the render-ready publish threw; readiness waits fail with it instead of seeking. */
+ __hfStartupError?: string;
__hfRuntimeTeardown?: (() => void) | null;
/** What each composition's scripts started on gsap's global timeline, by composition id. */
__hfSceneAnimations?: Record<string, SceneAnimation[]> | null;
diff --git a/packages/engine/src/services/frameCapture.test.ts b/packages/engine/src/services/frameCapture.test.ts
index d0513ffc71..bc5a362128 100644
--- a/packages/engine/src/services/frameCapture.test.ts
+++ b/packages/engine/src/services/frameCapture.test.ts
@@ -4,6 +4,7 @@ import { COMPOSITION_SOURCE_URL } from "@hyperframes/core";
import type { CaptureSession } from "./frameCapture.js";
import {
buildZeroDurationDiagnostic,
+ pollHfReady,
captureFramesBatchPipelined,
captureFrameToBufferPipelined,
classifyConsoleScriptError,
@@ -559,6 +560,18 @@ describe("DrawElementVerificationError details", () => {
});
});
+describe("pollHfReady", () => {
+ it("fails at once with the runtime's start-up error instead of waiting out the timeout", async () => {
+ const startupError = "HyperFrames runtime failed: TypeError: boom";
+ const page = {
+ evaluate: async (expr: unknown) =>
+ String(expr).includes("__hfStartupError") ? startupError : false,
+ } as unknown as Parameters<typeof pollHfReady>[0];
+
+ await expect(pollHfReady(page, 60_000)).rejects.toThrow(startupError);
+ });
+});
+
describe("buildZeroDurationDiagnostic", () => {
const baseDiag = {
renderReady: false,
diff --git a/packages/engine/src/services/frameCapture.ts b/packages/engine/src/services/frameCapture.ts
index 14ab1d62fe..6a97fd9393 100644
--- a/packages/engine/src/services/frameCapture.ts
+++ b/packages/engine/src/services/frameCapture.ts
@@ -1705,7 +1705,11 @@ async function evaluateHfDiagnostic(page: Page): Promise<HfDiagnostic> {
return (await page.evaluate(HF_READY_DIAGNOSTIC_EXPR)) as HfDiagnostic;
}
-async function pollHfReady(page: Page, timeoutMs: number, intervalMs: number = 100): Promise<void> {
+export async function pollHfReady(
+ page: Page,
+ timeoutMs: number,
+ intervalMs: number = 100,
+): Promise<void> {
const readyExpr = `!!(window.__hf && typeof window.__hf.seek === "function" && window.__hf.duration > 0)`;
const FAST_FAIL_AFTER_MS = 10_000;
// Throttle diagnostic CDP calls to ~1000ms — running evaluateHfDiagnostic on
@@ -1716,8 +1720,11 @@ async function pollHfReady(page: Page, timeoutMs: number, intervalMs: number = 1
let lastDiagnosticAt = 0;
while (Date.now() < deadline) {
- const ready = Boolean(await page.evaluate(readyExpr));
- if (ready) return;
+ const state = await page.evaluate(
+ `typeof window.__hfStartupError === "string" ? window.__hfStartupError : ${readyExpr}`,
+ );
+ if (typeof state === "string") throw new Error(state);
+ if (state) return;
const elapsed = timeoutMs - (deadline - Date.now());
if (elapsed >= FAST_FAIL_AFTER_MS) {
@@ -3695,7 +3702,7 @@ async function armStaticDedup(
* compositor-incompatible properties (blend-mode, 3D transforms, clip-path, mask).
* drawElement cannot reproduce these effects mid-tween → capture those frames via
* screenshot instead. opacity/filter fades were dropped from the set once Chrome 151
- * fixed crbug 521861819. See docs/fast-capture-limitations.md Lim 7.
+ * fixed crbug 521861819.
*
* Returns the union of at-risk frame indices (±1 margin around each tween interval)
* and totalFrames (for fraction computation by the caller).
diff --git a/packages/producer/src/services/htmlCompiler.test.ts b/packages/producer/src/services/htmlCompiler.test.ts
index 4a2ab4c937..0e39d2aeeb 100644
--- a/packages/producer/src/services/htmlCompiler.test.ts
+++ b/packages/producer/src/services/htmlCompiler.test.ts
@@ -2425,6 +2425,37 @@ describe("resolveCompositionDurations strict literal timing", () => {
}
});
+ it("falls back to the authored duration when the registered duration() throws", async () => {
+ const previousDocument = globalThis.document;
+ const previousWindow = globalThis.window;
+ globalThis.window = {
+ __timelines: {
+ scene: {
+ duration() {
+ throw new Error("boom");
+ },
+ },
+ },
+ } as any;
+ globalThis.document = {
+ getElementById: () => ({
+ getAttribute: (name: string) => (name === "data-composition-duration" ? "5" : null),
+ }),
+ } as any;
+ try {
+ const page = {
+ evaluate: async (fn: (arg: unknown) => unknown, arg: unknown) => fn(arg),
+ } as any;
+ const result = await resolveCompositionDurations(page, [
+ { id: "scene", tagName: "div", start: 0, mediaStart: 0, playbackRate: 1 },
+ ]);
+ expect(result).toEqual([{ id: "scene", duration: 5 }]);
+ } finally {
+ globalThis.document = previousDocument;
+ globalThis.window = previousWindow;
+ }
+ });
+
it("does not partially parse trailing-garbage composition duration", async () => {
const previousDocument = globalThis.document;
const previousWindow = globalThis.window;
diff --git a/packages/producer/src/services/htmlCompiler.ts b/packages/producer/src/services/htmlCompiler.ts
index fea11f52a0..f03f109743 100644
--- a/packages/producer/src/services/htmlCompiler.ts
+++ b/packages/producer/src/services/htmlCompiler.ts
@@ -2662,12 +2662,15 @@ export async function resolveCompositionDurations(
for (const id of compIds) {
// Try window.__timelines[id].duration() first (GSAP timeline)
const tl = timelines[id];
- if (tl && typeof tl.duration === "function") {
- const dur = tl.duration();
- if (dur > 0) {
- resolved.push({ id, duration: dur, source: "__timelines" });
- continue;
- }
+ let dur = 0;
+ try {
+ dur = typeof tl?.duration === "function" ? Number(tl.duration()) : 0;
+ } catch {
+ dur = 0;
+ }
+ if (dur > 0) {
+ resolved.push({ id, duration: dur, source: "__timelines" });
+ continue;
}
// Fallback: check for authored duration on the element itself