Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
fix(cli): check and snapshot wait for a slow CDN script as long as render does (#5847)
Miguel Ángel18fc3901c79e
diff --git a/packages/cli/src/capture/captureCompositionFrame.browserFallback.test.ts b/packages/cli/src/capture/captureCompositionFrame.browserFallback.test.tsindex 624f95cf2b..7eca25de4a 100644--- a/packages/cli/src/capture/captureCompositionFrame.browserFallback.test.ts+++ b/packages/cli/src/capture/captureCompositionFrame.browserFallback.test.ts@@ -30,6 +30,8 @@ vi.mock("@hyperframes/engine", () => ({assertWebGpuAdapterAvailable: mocks.assertWebGpuAdapterAvailable,resolveConfig: mocks.resolveConfig,usesSoftwareWebGpu: mocks.usesSoftwareWebGpu,+ DEFAULT_CONFIG: { pageNavigationTimeout: 60_000 },+ resolvePageNavigationTimeout: () => 60_000,}));import { openSettledCompositionPage } from "./captureCompositionFrame.js";diff --git a/packages/cli/src/capture/captureCompositionFrame.slowScript.browser.test.ts b/packages/cli/src/capture/captureCompositionFrame.slowScript.browser.test.tsnew file mode 100644index 0000000000..293fa770bb--- /dev/null+++ b/packages/cli/src/capture/captureCompositionFrame.slowScript.browser.test.ts@@ -0,0 +1,46 @@+import { createServer, type Server } from "node:http";+import type { AddressInfo } from "node:net";+import { afterAll, beforeAll, expect, it } from "vitest";+import { openSettledCompositionPage } from "./captureCompositionFrame.js";++// GSAP from a slow CDN: a parser-blocking script holds DOMContentLoaded back.+const SCRIPT_DELAY_MS = 15_000;+const HTML = `<!doctype html><html><head><script src="/slow.js"></script></head>+<body><div data-composition-id="main" data-width="320" data-height="180" data-duration="1"></div></body></html>`;++let server: Server;+let url: string;++beforeAll(async () => {+ server = createServer((req, res) => {+ if (req.url === "/slow.js") {+ setTimeout(() => {+ res.writeHead(200, { "Content-Type": "text/javascript" });+ res.end("window.slowScriptRan = true;");+ }, SCRIPT_DELAY_MS);+ return;+ }+ res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });+ res.end(HTML);+ });+ await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));+ url = `http://127.0.0.1:${(server.address() as AddressInfo).port}/`;+});++afterAll(() => {+ server.closeAllConnections();+ server.close();+});++it("opens a composition whose parser-blocking script takes 15 s, as render does", async () => {+ const { browser, page } = await openSettledCompositionPage(HTML, url, {+ renderReadyTimeoutMs: 500,+ renderReadyWarningSuffix: "test",+ browserGpuMode: "software",+ });+ try {+ expect(await page.evaluate(() => Reflect.get(window, "slowScriptRan"))).toBe(true);+ } finally {+ await browser.close();+ }+}, 90_000);diff --git a/packages/cli/src/capture/captureCompositionFrame.ts b/packages/cli/src/capture/captureCompositionFrame.tsindex 989fdb222d..6a63a58f4a 100644--- a/packages/cli/src/capture/captureCompositionFrame.ts+++ b/packages/cli/src/capture/captureCompositionFrame.ts@@ -18,7 +18,7 @@ import {import { windowsChromeCrashRemediation } from "../browser/windowsCrash.js";import { resolveCompositionViewportFromHtml } from "../utils/compositionViewport.js";import { normalizeErrorMessage } from "../utils/errorMessage.js";-import { resolveDiagnosticNavigationTimeoutMs } from "../utils/renderArgs.js";+import { pageNavigationTimeoutMs } from "../utils/renderArgs.js";import { gotoWhenSent } from "./navigateForCapture.js";const SHADER_TRANSITIONS_TIMEOUT_MS = 90_000;@@ -94,8 +94,7 @@ export interface SettledCompositionPage {}export interface OpenSettledCompositionPageOptions {- // Separate from the post-navigation render-ready budget. Diagnostic callers- // without their own navigation knob keep the historical 10-second minimum.+ // Separate from the post-navigation render-ready budget; can only lengthen render's page-load budget.navigationTimeoutMs?: number;renderReadyTimeoutMs: number;renderReadyWarningSuffix: string;@@ -281,11 +280,7 @@ export async function openSettledCompositionPage(await page.setViewport(viewport);if (answer) await answerPageInProcess(page, url, answer);await options.beforeNavigate?.(page);- await gotoWhenSent(- page,- url,- resolveDiagnosticNavigationTimeoutMs(process.env, options.navigationTimeoutMs),- );+ await gotoWhenSent(page, url, pageNavigationTimeoutMs(options.navigationTimeoutMs));await assertWebGpuAdapterAvailable(page, requiresWebGpu, softwareWebGpu);const renderReadyTimedOut = !(await waitForCompositionSettle(page, options));return { browser: chromeBrowser, page, renderReadyTimedOut };diff --git a/packages/cli/src/commands/layout.ts b/packages/cli/src/commands/layout.tsindex 194d8977e7..d39738b5d4 100644--- a/packages/cli/src/commands/layout.ts+++ b/packages/cli/src/commands/layout.ts@@ -7,7 +7,7 @@ import { fileURLToPath } from "node:url";import type { Example } from "./_examples.js";import { c } from "../ui/colors.js";import { resolveProject } from "../utils/project.js";-import { resolveDiagnosticNavigationTimeoutMs } from "../utils/renderArgs.js";+import { pageNavigationTimeoutMs } from "../utils/renderArgs.js";import { gotoWhenSent } from "../capture/navigateForCapture.js";import { normalizeErrorMessage } from "../utils/errorMessage.js";import { serveStaticProjectHtml } from "../utils/staticProjectServer.js";@@ -185,7 +185,7 @@ async function alignViewportToComposition(});await page.setViewport(size);- await gotoWhenSent(page, url, resolveDiagnosticNavigationTimeoutMs());+ await gotoWhenSent(page, url, pageNavigationTimeoutMs());}async function runLayoutAudit(@@ -235,7 +235,7 @@ async function runLayoutAudit(const page = await chromeBrowser.newPage();await installPageFunctionGuard(page);await page.setViewport({ width: 1920, height: 1080 });- await gotoWhenSent(page, server.url, resolveDiagnosticNavigationTimeoutMs());+ await gotoWhenSent(page, server.url, pageNavigationTimeoutMs());await assertWebGpuAdapterAvailable(page, requiresWebGpu, softwareWebGpu);await alignViewportToComposition(page, server.url);await waitForRuntimeReady(page, opts.timeout);diff --git a/packages/cli/src/commands/motionShot.ts b/packages/cli/src/commands/motionShot.tsindex 8a07008f0e..b326ce19b1 100644--- a/packages/cli/src/commands/motionShot.ts+++ b/packages/cli/src/commands/motionShot.ts@@ -13,7 +13,7 @@ import { launchManagedBrowser, resolveManagedGpuMode } from "../browser/launch.jimport { mkdirSync, statSync, writeFileSync } from "node:fs";import { dirname, resolve } from "node:path";-import { resolveDiagnosticNavigationTimeoutMs } from "../utils/renderArgs.js";+import { pageNavigationTimeoutMs } from "../utils/renderArgs.js";import { gotoWhenSent } from "../capture/navigateForCapture.js";import { resolveCompositionViewportFromHtml } from "../utils/compositionViewport.js";import { waitForRuntimeReady } from "../capture/captureCompositionFrame.js";@@ -427,7 +427,7 @@ async function openCompositionPage(try {const page = await browser.newPage();await page.setViewport(size);- await gotoWhenSent(page, url, resolveDiagnosticNavigationTimeoutMs());+ await gotoWhenSent(page, url, pageNavigationTimeoutMs());await assertWebGpuAdapterAvailable(page, requiresWebGpu, softwareWebGpu);await waitForRuntimeReady(page, 10000);await pagediff --git a/packages/cli/src/commands/validate.test.ts b/packages/cli/src/commands/validate.test.tsindex 1af6dcab96..bfe021fd1a 100644--- a/packages/cli/src/commands/validate.test.ts+++ b/packages/cli/src/commands/validate.test.ts@@ -16,7 +16,6 @@ import {navigationTimeoutHint,projectPathOfUrl,raceMediaReady,- resolveNavigationTimeoutMs,shouldIgnoreRequestFailure,shouldIgnoreHttpError,} from "./validate.js";@@ -338,24 +337,6 @@ describe("extractCompositionErrorsFromLint", () => {});});-// Regression: `validate` used a hardcoded 10s page-navigation timeout that-// ignored --timeout, so a composition loading GSAP from a CDN <script> (which-// blocks domcontentloaded) failed with an opaque "Navigation timeout of 10000ms"-// even though the full render's larger budget rode it out — with no knob to-// extend it. resolveNavigationTimeoutMs makes --timeout raise the nav budget-// (never below the 10s floor); navigationTimeoutHint replaces the opaque error.-describe("resolveNavigationTimeoutMs", () => {- it("keeps the 10s floor when --timeout is unset or smaller", () => {- expect(resolveNavigationTimeoutMs(undefined)).toBe(10000);- expect(resolveNavigationTimeoutMs(3000)).toBe(10000); // the default --timeout- expect(resolveNavigationTimeoutMs(0)).toBe(10000);- });-- it("raises the navigation budget to --timeout when it exceeds the floor", () => {- expect(resolveNavigationTimeoutMs(30000)).toBe(30000);- });-});-describe("navigationTimeoutHint", () => {it("replaces a Puppeteer navigation-timeout error with an actionable CDN/--timeout hint", () => {const hinted = navigationTimeoutHint(diff --git a/packages/cli/src/commands/validate.ts b/packages/cli/src/commands/validate.tsindex eb3e3997c0..a356ffd351 100644--- a/packages/cli/src/commands/validate.ts+++ b/packages/cli/src/commands/validate.ts@@ -17,6 +17,7 @@ import { resolveCompositionViewportFromHtml } from "../utils/compositionViewportimport { c } from "../ui/colors.js";import { decodeWellFormedEscapes } from "@hyperframes/studio-server";import { printDeprecationNotice, withMeta } from "../utils/updateCheck.js";+import { pageNavigationTimeoutMs } from "../utils/renderArgs.js";import {installPageFunctionGuard,resolveCliChromeGpuMode,@@ -49,31 +50,17 @@ const CONTRAST_SAMPLES = 5;const SEEK_SETTLE_MS = 150;const PREFERRED_SEEK_TARGET_WAIT_MS = 500;const MEDIA_EXTENSIONS = /\.(aac|flac|m4a|mov|mp3|mp4|oga|ogg|wav|webm)$/i;-// Floor for the initial page navigation. A blocking external <script> (GSAP-// from a CDN, etc.) delays `domcontentloaded`; the actual render (much larger-// budget) rides it out, so validate's navigation must be at least as patient as-// the user's --timeout, never stuck below this floor.-const NAV_TIMEOUT_FLOOR_MS = 10000;--// Navigation budget = the larger of the floor and the user's --timeout, so-// `--timeout` (already the "wait longer for slow loads" knob for media/settle)-// also extends navigation instead of being ignored by a hardcoded 10s.-export function resolveNavigationTimeoutMs(optTimeout?: number): number {- return Math.max(NAV_TIMEOUT_FLOOR_MS, optTimeout ?? 0);-}-// Turn Puppeteer's opaque "Navigation timeout of Nms exceeded" into an-// actionable message: the usual cause is a blocking CDN <script> that render-// tolerates but validate's tighter budget does not. Returns a replacement Error-// for a navigation timeout, or null for any other error (caller rethrows as-is).+// actionable message: the usual cause is a slow blocking CDN <script>. Returns a+// replacement Error for a navigation timeout, or null for any other error.export function navigationTimeoutHint(err: unknown, navTimeoutMs: number): Error | null {const msg = err instanceof Error ? err.message : String(err);if (!/navigation timeout/i.test(msg)) return null;return new Error(`Page navigation timed out after ${navTimeoutMs}ms. A blocking external <script> ` +- `(e.g. GSAP loaded from a CDN) can delay page load past this budget even when the ` +- `full render succeeds. Vendor the script locally (recommended for deterministic ` +- `renders), or re-run with a longer --timeout.`,+ `(e.g. GSAP loaded from a CDN) can delay page load past this budget, which render ` ++ `shares. Vendor the script locally (recommended for deterministic renders), or ` ++ `re-run with a longer --timeout or PRODUCER_PAGE_NAVIGATION_TIMEOUT_MS.`,);}@@ -500,7 +487,7 @@ async function validateInBrowser(}});- const navTimeoutMs = resolveNavigationTimeoutMs(opts.timeout);+ const navTimeoutMs = pageNavigationTimeoutMs(opts.timeout);try {await page.goto(server.url, { waitUntil: "domcontentloaded", timeout: navTimeoutMs });} catch (err) {diff --git a/packages/cli/src/utils/renderArgs.test.ts b/packages/cli/src/utils/renderArgs.test.tsindex 69d1bf9e98..ed6b2d65f8 100644--- a/packages/cli/src/utils/renderArgs.test.ts+++ b/packages/cli/src/utils/renderArgs.test.ts@@ -1,4 +1,5 @@-import { describe, expect, it } from "vitest";+import { afterEach, describe, expect, it, vi } from "vitest";+import { DEFAULT_CONFIG } from "@hyperframes/engine";import { mkdirSync, mkdtempSync, rmSync, writeFileSync, type Stats } from "node:fs";import { tmpdir } from "node:os";import { dirname, join, resolve } from "node:path";@@ -6,7 +7,7 @@ import {MAX_PAGE_NAVIGATION_TIMEOUT_SECONDS,hasExplicitCompositionArg,parseBrowserTimeoutMsArg,- resolveDiagnosticNavigationTimeoutMs,+ pageNavigationTimeoutMs,parseCompositionEntryArg,parseGifLoopArg,parseHlsSegmentSecondsArg,@@ -106,35 +107,42 @@ describe("parseBrowserTimeoutMsArg", () => {});});-describe("resolveDiagnosticNavigationTimeoutMs", () => {- it("uses the render navigation timeout env override", () => {- expect(- resolveDiagnosticNavigationTimeoutMs({ PRODUCER_PAGE_NAVIGATION_TIMEOUT_MS: "90000" }),- ).toBe(90_000);- });+describe("pageNavigationTimeoutMs", () => {+ afterEach(() => vi.unstubAllEnvs());- it("falls back to ten seconds for missing or invalid values", () => {- expect(resolveDiagnosticNavigationTimeoutMs({})).toBe(10_000);- expect(- resolveDiagnosticNavigationTimeoutMs({ PRODUCER_PAGE_NAVIGATION_TIMEOUT_MS: "invalid" }),- ).toBe(10_000);+ it("gives check and snapshot the page-load budget render uses", () => {+ expect(pageNavigationTimeoutMs()).toBe(DEFAULT_CONFIG.pageNavigationTimeout);+ vi.stubEnv("PRODUCER_PAGE_NAVIGATION_TIMEOUT_MS", "90000");+ expect(pageNavigationTimeoutMs()).toBe(90_000);});- it("raises the diagnostic navigation budget to a larger caller-provided minimum", () => {- expect(resolveDiagnosticNavigationTimeoutMs({}, 30_000)).toBe(30_000);+ it("falls back to that default for a zero or invalid override", () => {+ vi.stubEnv("PRODUCER_PAGE_NAVIGATION_TIMEOUT_MS", "0");+ expect(pageNavigationTimeoutMs()).toBe(DEFAULT_CONFIG.pageNavigationTimeout);+ vi.stubEnv("PRODUCER_PAGE_NAVIGATION_TIMEOUT_MS", "invalid");+ expect(pageNavigationTimeoutMs()).toBe(DEFAULT_CONFIG.pageNavigationTimeout);});- it("does not let a caller-provided minimum shorten the default budget", () => {- expect(resolveDiagnosticNavigationTimeoutMs({}, 3_000)).toBe(10_000);+ it("prints no render-only warning where render would disable streaming encode", () => {+ const platform = Object.getOwnPropertyDescriptor(process, "platform")!;+ Object.defineProperty(process, "platform", { value: "win32" });+ vi.stubEnv("PRODUCER_BROWSER_GPU_MODE", "software");+ vi.stubEnv("PRODUCER_MAX_WORKERS", "1");+ const stderr = vi.spyOn(console, "error").mockImplementation(() => undefined);+ try {+ expect(pageNavigationTimeoutMs()).toBe(DEFAULT_CONFIG.pageNavigationTimeout);+ expect(stderr).not.toHaveBeenCalled();+ } finally {+ stderr.mockRestore();+ Object.defineProperty(process, "platform", platform);+ }});- it("does not let a caller-provided minimum shorten the environment override", () => {- expect(- resolveDiagnosticNavigationTimeoutMs(- { PRODUCER_PAGE_NAVIGATION_TIMEOUT_MS: "90000" },- 30_000,- ),- ).toBe(90_000);+ it("lets a command's longer --timeout raise it, never lower it", () => {+ expect(pageNavigationTimeoutMs(DEFAULT_CONFIG.pageNavigationTimeout * 2)).toBe(+ DEFAULT_CONFIG.pageNavigationTimeout * 2,+ );+ expect(pageNavigationTimeoutMs(3_000)).toBe(DEFAULT_CONFIG.pageNavigationTimeout);});});diff --git a/packages/cli/src/utils/renderArgs.ts b/packages/cli/src/utils/renderArgs.tsindex 984eac2240..f35134a06f 100644--- a/packages/cli/src/utils/renderArgs.ts+++ b/packages/cli/src/utils/renderArgs.ts@@ -1,3 +1,4 @@+import { DEFAULT_CONFIG, resolvePageNavigationTimeout } from "@hyperframes/engine";import { failUsage } from "./commandResult.js";/*** Pure parsers for `hyperframes render` argv that aren't already shared@@ -118,20 +119,13 @@ export function resolveBrowserTimeoutMsArg(raw: string | undefined): number | unreturn result.value;}-/**- * Navigation budget shared by snapshot/check/inspect browser diagnostics.- *- * The environment variable remains the historical global override. Callers- * with their own timeout knob can supply a minimum without shortening that- * override or the existing 10-second default.- */-export function resolveDiagnosticNavigationTimeoutMs(- env: Record<string, string | undefined> = process.env,- minimumTimeoutMs = 0,-): number {- const parsed = Number(env.PRODUCER_PAGE_NAVIGATION_TIMEOUT_MS);- const configured = Number.isFinite(parsed) && parsed > 0 ? parsed : 10_000;- return Math.max(configured, minimumTimeoutMs);+/** The page-load budget render uses, raised to a command's own longer `--timeout`. */+export function pageNavigationTimeoutMs(minimumTimeoutMs = 0): number {+ const configured = resolvePageNavigationTimeout();+ return Math.max(+ configured > 0 ? configured : DEFAULT_CONFIG.pageNavigationTimeout,+ minimumTimeoutMs,+ );}// ── --composition ──────────────────────────────────────────────────────diff --git a/packages/engine/src/config.ts b/packages/engine/src/config.tsindex 0c96f7dd5d..9829642d83 100644--- a/packages/engine/src/config.ts+++ b/packages/engine/src/config.ts@@ -799,6 +799,13 @@ export function explainDrawElementDisabled(args: {return "disabled";}+/** `pageNavigationTimeout` alone, for callers that need the page-load budget without the rest of the config. */+export function resolvePageNavigationTimeout(): number {+ const raw = process.env.PRODUCER_PAGE_NAVIGATION_TIMEOUT_MS;+ const parsed = raw === undefined || raw === "" ? NaN : Number(raw);+ return Number.isFinite(parsed) ? parsed : DEFAULT_CONFIG.pageNavigationTimeout;+}+export function resolveConfig(overrides?: Partial<EngineConfig>): EngineConfig {const env = (key: string): string | undefined => process.env[key];const envNum = (key: string, fallback: number): number => {@@ -932,10 +939,7 @@ export function resolveConfig(overrides?: Partial<EngineConfig>): EngineConfig {"PRODUCER_RENDER_READY_TIMEOUT_MS",DEFAULT_CONFIG.renderReadyTimeout,),- pageNavigationTimeout: envNum(- "PRODUCER_PAGE_NAVIGATION_TIMEOUT_MS",- DEFAULT_CONFIG.pageNavigationTimeout,- ),+ pageNavigationTimeout: resolvePageNavigationTimeout(),verifyRuntime: env("PRODUCER_VERIFY_HYPERFRAME_RUNTIME") !== "false",runtimeManifestPath: env("PRODUCER_HYPERFRAME_MANIFEST_PATH"),diff --git a/packages/engine/src/index.ts b/packages/engine/src/index.tsindex e6fa67ca28..77b306e58e 100644--- a/packages/engine/src/index.ts+++ b/packages/engine/src/index.ts@@ -49,6 +49,7 @@ export type {// ── Configuration ──────────────────────────────────────────────────────────────export {resolveConfig,+ resolvePageNavigationTimeout,validateEngineConfigSnapshot,DEFAULT_CONFIG,scaleProtocolTimeoutForComposition,