Skip to content

Write HTML. Render video. Built for agents.

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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.j
import { 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 page
diff --git a/packages/cli/src/commands/validate.test.ts b/packages/cli/src/commands/validate.test.ts
index 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.ts
index 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/compositionViewport
import { 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.ts
index 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.ts
index 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 | un
return 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.ts
index 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.ts
index 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,