Skip to content

Commit 58cff5f

Browse files
committed
feat(engine): surface escape hatches in page.goto Nav timeout errors
Field signal ts=1784146416 (darwin/arm64, CLI 0.7.58, 7/10): host page.goto hit Navigation timeout of 60000ms twice on a CSS 3D + audio composition; Docker rendered the same composition successfully. Puppeteer's stock "Navigation timeout of 60000 ms exceeded" text names none of HyperFrames' existing escape hatches, so the reporter had no signal that the failure had knobs. Wraps main-render Puppeteer `page.goto` errors matching /Navigation timeout|net::ERR_TIMED_OUT/i with an augmented message that names: - The effective timeout currently applied (`cfg.pageNavigationTimeout`). - Raise-the-timeout: `PRODUCER_PAGE_NAVIGATION_TIMEOUT_MS` env, `--browser-timeout` CLI flag (seconds). - Browser-binary escape hatch: `HYPERFRAMES_BROWSER_PATH` env. - Field-signal shape: darwin/arm64 + CSS 3D + audio compound Docker hint — gated on all three inputs being explicitly true; falls back to generic hints when any input is unknown. Mirrors #2443's HYPERFRAMES_BROWSER_PATH surfacing pattern (which covered download-time failures) at the runtime `page.goto` layer. Non-matching errors flow through unchanged. Original error preserved via `err.cause`. Wired into `renderOrchestrator.executeRenderJob`'s top-level catch, composed after `augmentProtocolTimeoutError` so the two augmenters never both fire on the same error (mutually exclusive regexes). Current wire-up passes no `hasCss3D` / `hasAudio` context — no compile-time CSS-3D signal is threaded through the render pipeline, and `hasAudio` is block-scoped inside the try. Per the helper's fallback docs, unknown flags route to the generic env + browser-path hints. A future compile-time CSS-3D scan can thread both flags to enable the full compound Docker hint without touching this helper's signature. Stack: PR #3 of 9 (base via/win32-streaming-encode-autodisable). Signed-off-by: Via <[email protected]>
1 parent cbf2a2e commit 58cff5f

4 files changed

Lines changed: 346 additions & 1 deletion

File tree

‎packages/engine/src/index.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,11 @@ export {
8383
augmentProtocolTimeoutError,
8484
isProtocolTimeoutError,
8585
} from "./services/protocolTimeoutErrorHint.js";
86+
export {
87+
augmentPageNavigationTimeoutError,
88+
isPageNavigationTimeoutError,
89+
type NavigationTimeoutHintContext,
90+
} from "./services/pageNavigationTimeoutErrorHint.js";
8691

8792
// ── Frame capture pipeline ──────────────────────────────────────────────────────
8893
export {
Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
import { describe, expect, it } from "vitest";
2+
import {
3+
augmentPageNavigationTimeoutError,
4+
isPageNavigationTimeoutError,
5+
} from "./pageNavigationTimeoutErrorHint.js";
6+
7+
describe("augmentPageNavigationTimeoutError", () => {
8+
it("passes non-Navigation-timeout errors through unchanged (same instance)", () => {
9+
const original = new Error("Runtime.callFunctionOn timed out");
10+
const result = augmentPageNavigationTimeoutError(original, 60_000);
11+
expect(result).toBe(original);
12+
expect(result.message).toBe("Runtime.callFunctionOn timed out");
13+
});
14+
15+
it("augments 'Navigation timeout of Xms exceeded' with the effective timeout", () => {
16+
const original = new Error("Navigation timeout of 60000 ms exceeded");
17+
const result = augmentPageNavigationTimeoutError(original, 60_000);
18+
expect(result).not.toBe(original);
19+
expect(result.message).toContain(original.message);
20+
expect(result.message).toContain(
21+
"HyperFrames effective page.goto navigation timeout: 60000 ms",
22+
);
23+
});
24+
25+
it("includes the env + CLI + browser-path hints in the generic augmentation", () => {
26+
const original = new Error("Navigation timeout of 60000 ms exceeded");
27+
const result = augmentPageNavigationTimeoutError(original, 60_000);
28+
expect(result.message).toContain("PRODUCER_PAGE_NAVIGATION_TIMEOUT_MS");
29+
expect(result.message).toContain("--browser-timeout");
30+
expect(result.message).toContain("HYPERFRAMES_BROWSER_PATH");
31+
});
32+
33+
it("preserves err.cause on the augmented error", () => {
34+
const original = new Error("Navigation timeout of 60000 ms exceeded");
35+
const result = augmentPageNavigationTimeoutError(original, 60_000);
36+
expect((result as Error & { cause?: unknown }).cause).toBe(original);
37+
});
38+
39+
it("augments net::ERR_TIMED_OUT errors as well", () => {
40+
const original = new Error("net::ERR_TIMED_OUT at http://127.0.0.1:4173/index.html");
41+
const result = augmentPageNavigationTimeoutError(original, 120_000);
42+
expect(result).not.toBe(original);
43+
expect(result.message).toContain("HyperFrames effective page.goto navigation timeout: 120000");
44+
});
45+
46+
it("coerces non-Error thrown values into Error without augmenting", () => {
47+
const result = augmentPageNavigationTimeoutError("plain string failure", 60_000);
48+
expect(result).toBeInstanceOf(Error);
49+
expect(result.message).toBe("plain string failure");
50+
// Not augmented: coerced string doesn't match the Nav-timeout regex.
51+
expect(result.message).not.toContain("HyperFrames effective page.goto navigation timeout");
52+
});
53+
54+
it("fires the darwin/arm64 + CSS 3D + audio Docker hint only when all three match", () => {
55+
const original = new Error("Navigation timeout of 60000 ms exceeded");
56+
const result = augmentPageNavigationTimeoutError(original, 60_000, {
57+
platform: "darwin",
58+
arch: "arm64",
59+
hasCss3D: true,
60+
hasAudio: true,
61+
});
62+
expect(result.message).toContain("ts=1784146416");
63+
expect(result.message).toContain("--docker");
64+
expect(result.message).toContain("CSS 3D rendering context");
65+
});
66+
67+
it("does not surface the Docker hint on non-darwin platforms even when CSS 3D + audio are true", () => {
68+
const original = new Error("Navigation timeout of 60000 ms exceeded");
69+
const result = augmentPageNavigationTimeoutError(original, 60_000, {
70+
platform: "linux",
71+
arch: "x64",
72+
hasCss3D: true,
73+
hasAudio: true,
74+
});
75+
expect(result.message).not.toContain("ts=1784146416");
76+
expect(result.message).not.toContain("--docker");
77+
// Generic hints still fire.
78+
expect(result.message).toContain("PRODUCER_PAGE_NAVIGATION_TIMEOUT_MS");
79+
expect(result.message).toContain("HYPERFRAMES_BROWSER_PATH");
80+
});
81+
82+
it("does not surface the Docker hint on darwin/x64 (Intel Macs)", () => {
83+
const original = new Error("Navigation timeout of 60000 ms exceeded");
84+
const result = augmentPageNavigationTimeoutError(original, 60_000, {
85+
platform: "darwin",
86+
arch: "x64",
87+
hasCss3D: true,
88+
hasAudio: true,
89+
});
90+
expect(result.message).not.toContain("ts=1784146416");
91+
expect(result.message).not.toContain("--docker");
92+
});
93+
94+
it("does not surface the Docker hint on darwin/arm64 without CSS 3D", () => {
95+
const original = new Error("Navigation timeout of 60000 ms exceeded");
96+
const result = augmentPageNavigationTimeoutError(original, 60_000, {
97+
platform: "darwin",
98+
arch: "arm64",
99+
hasCss3D: false,
100+
hasAudio: true,
101+
});
102+
expect(result.message).not.toContain("ts=1784146416");
103+
expect(result.message).not.toContain("--docker");
104+
});
105+
106+
it("does not surface the Docker hint on darwin/arm64 without audio", () => {
107+
const original = new Error("Navigation timeout of 60000 ms exceeded");
108+
const result = augmentPageNavigationTimeoutError(original, 60_000, {
109+
platform: "darwin",
110+
arch: "arm64",
111+
hasCss3D: true,
112+
hasAudio: false,
113+
});
114+
expect(result.message).not.toContain("ts=1784146416");
115+
expect(result.message).not.toContain("--docker");
116+
});
117+
118+
it("does not surface the Docker hint when CSS 3D / audio inputs are unknown (fallback documented)", () => {
119+
// Current wire-up in renderOrchestrator passes hasCss3D: undefined because
120+
// no compile-time CSS-3D signal is threaded through the pipeline. The
121+
// Docker hint is intentionally strict about `=== true` — this test locks
122+
// that behaviour so a future compile-time hasCss3D scan can flip it on
123+
// by supplying the flag, without accidentally firing before then.
124+
const original = new Error("Navigation timeout of 60000 ms exceeded");
125+
const result = augmentPageNavigationTimeoutError(original, 60_000, {
126+
platform: "darwin",
127+
arch: "arm64",
128+
// hasCss3D + hasAudio omitted (undefined).
129+
});
130+
expect(result.message).not.toContain("ts=1784146416");
131+
expect(result.message).not.toContain("--docker");
132+
// Generic hints still fire.
133+
expect(result.message).toContain("PRODUCER_PAGE_NAVIGATION_TIMEOUT_MS");
134+
expect(result.message).toContain("HYPERFRAMES_BROWSER_PATH");
135+
});
136+
137+
it("defaults platform/arch to the current process when context omits them", () => {
138+
// Regression: earlier draft required an explicit platform. Make sure the
139+
// helper still augments (with generic hints) when no context is passed.
140+
const original = new Error("Navigation timeout of 60000 ms exceeded");
141+
const result = augmentPageNavigationTimeoutError(original, 60_000);
142+
expect(result).not.toBe(original);
143+
expect(result.message).toContain("PRODUCER_PAGE_NAVIGATION_TIMEOUT_MS");
144+
expect(result.message).toContain("HYPERFRAMES_BROWSER_PATH");
145+
});
146+
});
147+
148+
describe("isPageNavigationTimeoutError", () => {
149+
it("returns true for matching messages", () => {
150+
expect(isPageNavigationTimeoutError(new Error("Navigation timeout of 60000 ms exceeded"))).toBe(
151+
true,
152+
);
153+
expect(isPageNavigationTimeoutError("net::ERR_TIMED_OUT")).toBe(true);
154+
});
155+
156+
it("returns false for non-matching messages", () => {
157+
expect(isPageNavigationTimeoutError(new Error("Runtime.callFunctionOn timed out"))).toBe(false);
158+
expect(isPageNavigationTimeoutError(new Error("Target closed"))).toBe(false);
159+
expect(isPageNavigationTimeoutError(null)).toBe(false);
160+
expect(isPageNavigationTimeoutError(undefined)).toBe(false);
161+
expect(isPageNavigationTimeoutError(42)).toBe(false);
162+
});
163+
});
Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
/**
2+
* Augment Puppeteer `page.goto` navigation-timeout errors with actionable
3+
* guidance that names the HyperFrames-specific knobs. Puppeteer's stock error
4+
* text ("Navigation timeout of 60000 ms exceeded") doesn't tell the user
5+
* which env var / CLI flag raises this timeout in HyperFrames, or which
6+
* browser-binary override lets them route around a slow pinned build.
7+
*
8+
* Sibling of `augmentProtocolTimeoutError` (surfaces
9+
* `PRODUCER_PUPPETEER_PROTOCOL_TIMEOUT_MS` / `--protocol-timeout` on the
10+
* `Runtime.callFunctionOn timed out` class), and mirrors the surfacing
11+
* pattern from #2443 (which surfaces `HYPERFRAMES_BROWSER_PATH` on
12+
* download-time failures). This helper covers the runtime `page.goto` layer
13+
* instead:
14+
*
15+
* 1. Raise-the-timeout: `PRODUCER_PAGE_NAVIGATION_TIMEOUT_MS` env,
16+
* `--browser-timeout` CLI flag (SECONDS, not ms).
17+
* 2. Escape-hatch browser binary: `HYPERFRAMES_BROWSER_PATH` env, points
18+
* at a system Chrome / chrome-headless-shell path.
19+
* 3. Field-signal shape: darwin/arm64 CSS 3D + audio compound
20+
* (ts=1784146416) that succeeded under Docker — gated on all three
21+
* inputs being explicitly true.
22+
*
23+
* Design is conservative — non-matching errors flow through unchanged (same
24+
* instance). Non-Error inputs are coerced with `new Error(String(err))` so
25+
* callers always receive a well-typed `Error`. Original error preserved via
26+
* `err.cause` for downstream logging / observability.
27+
*
28+
* ─────────────────────────────────────────────────────────────────────────
29+
* Compound-hint fallback (documented per stack-review guardrails)
30+
* ─────────────────────────────────────────────────────────────────────────
31+
* The field signal cites the darwin/arm64 + CSS-3D + audio-track compound as
32+
* the shape where the Docker fallback rendered identically. The Docker hint
33+
* therefore fires ONLY when all three are true. When any one is unknown
34+
* (`undefined`) the helper falls back to the generic env + browser-path
35+
* hints — the Docker fallback is not universally applicable and surfacing
36+
* it outside the known-good compound risks recommending Docker on shapes it
37+
* hasn't been verified for.
38+
*
39+
* At the current wire-up in `renderOrchestrator.executeRenderJob`'s
40+
* top-level catch, `hasAudio` is in scope (computed in the `audio_process`
41+
* stage) but a CSS-3D compile-time signal isn't threaded through the
42+
* pipeline: grep `packages/producer/src/services/` and
43+
* `packages/engine/src/services/` — no compile-time `hasCss3D` boolean
44+
* exists; `parseTransformMatrix` in `alphaBlit.ts` detects 3D matrices at
45+
* engine-init runtime, AFTER `page.goto` has already succeeded. So the
46+
* current wire-up passes `hasCss3D: undefined`, and the Docker hint does
47+
* NOT fire in production today. The helper accepts both flags so a future
48+
* PR that lands a compile-time `hasCss3D` scan (e.g. an htmlCompiler.ts
49+
* pass over `transform-style: preserve-3d`, `perspective:`, `rotateX(`,
50+
* `rotateY(`, `matrix3d(`) can enable the full compound hint without
51+
* touching this helper's signature.
52+
*/
53+
54+
const NAVIGATION_TIMEOUT_MATCHER = /Navigation timeout|net::ERR_TIMED_OUT/i;
55+
56+
export interface NavigationTimeoutHintContext {
57+
/** `process.platform` at the catch site. Defaults to the current process. */
58+
platform?: NodeJS.Platform;
59+
/** `process.arch` at the catch site. Defaults to the current process. */
60+
arch?: NodeJS.Architecture | string;
61+
/**
62+
* Whether the composition uses a CSS 3D rendering context. Callers pass
63+
* `undefined` when this signal isn't threaded through — the Docker hint
64+
* then does not fire (see fallback docs above).
65+
*/
66+
hasCss3D?: boolean;
67+
/**
68+
* Whether the composition has an audio track. Callers pass `undefined`
69+
* when the signal isn't threaded through — the Docker hint then does not
70+
* fire.
71+
*/
72+
hasAudio?: boolean;
73+
}
74+
75+
export function augmentPageNavigationTimeoutError(
76+
err: unknown,
77+
effectiveTimeoutMs: number,
78+
context: NavigationTimeoutHintContext = {},
79+
): Error {
80+
if (!(err instanceof Error)) return new Error(String(err));
81+
if (!NAVIGATION_TIMEOUT_MATCHER.test(err.message)) return err;
82+
83+
const platform = context.platform ?? process.platform;
84+
const arch = context.arch ?? process.arch;
85+
86+
const dockerHint = shouldSurfaceDockerHint({
87+
platform,
88+
arch,
89+
hasCss3D: context.hasCss3D,
90+
hasAudio: context.hasAudio,
91+
})
92+
? buildDockerHintBlock()
93+
: "";
94+
95+
const augmented = new Error(
96+
`${err.message}\n\n` +
97+
`HyperFrames effective page.goto navigation timeout: ${effectiveTimeoutMs} ms.\n\n` +
98+
`To raise the timeout:\n` +
99+
` Env: PRODUCER_PAGE_NAVIGATION_TIMEOUT_MS=<higher-ms> (milliseconds)\n` +
100+
` CLI: --browser-timeout <seconds> (seconds)\n\n` +
101+
`To use a different browser binary (e.g. system Chrome instead of the pinned chrome-headless-shell):\n` +
102+
` Env: HYPERFRAMES_BROWSER_PATH=<path-to-Chrome-or-chrome-headless-shell>\n` +
103+
dockerHint,
104+
);
105+
(augmented as Error & { cause?: unknown }).cause = err;
106+
return augmented;
107+
}
108+
109+
/**
110+
* Predicate variant: exposed for callers that only need to classify an
111+
* error (e.g. observability, tests) without materialising an augmented
112+
* Error. Uses the same matcher as the augmentation path so the two never
113+
* drift.
114+
*/
115+
export function isPageNavigationTimeoutError(err: unknown): boolean {
116+
const message = err instanceof Error ? err.message : typeof err === "string" ? err : "";
117+
return NAVIGATION_TIMEOUT_MATCHER.test(message);
118+
}
119+
120+
interface DockerHintGate {
121+
platform: NodeJS.Platform | string;
122+
arch: NodeJS.Architecture | string;
123+
hasCss3D?: boolean;
124+
hasAudio?: boolean;
125+
}
126+
127+
/**
128+
* The Docker fallback hint fires only on the darwin/arm64 + CSS-3D + audio
129+
* compound the field signal exercised. Requiring all three to be
130+
* explicitly true (not just truthy — `undefined` is not enough) prevents
131+
* the hint from firing on shapes where the Docker fallback hasn't been
132+
* verified. Other platforms have different failure modes and different
133+
* remediation surfaces (Windows GPU compound → PR #2505, Linux headless
134+
* quirks → separate).
135+
*/
136+
function shouldSurfaceDockerHint(gate: DockerHintGate): boolean {
137+
return (
138+
gate.platform === "darwin" &&
139+
gate.arch === "arm64" &&
140+
gate.hasCss3D === true &&
141+
gate.hasAudio === true
142+
);
143+
}
144+
145+
function buildDockerHintBlock(): string {
146+
return (
147+
`\nField signal ts=1784146416 (darwin/arm64 host mode, CLI 0.7.58): the compound of\n` +
148+
`a CSS 3D rendering context + audio track on macOS arm64 has been reported to hit\n` +
149+
`Navigation timeout twice at page.goto while the same composition renders\n` +
150+
`identically under Docker. Consider:\n` +
151+
` hyperframes render ... --docker\n`
152+
);
153+
}

‎packages/producer/src/services/renderOrchestrator.ts‎

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,7 @@ import {
7979
isDrawElementVerificationError,
8080
getDrawElementVerificationDetails,
8181
augmentProtocolTimeoutError,
82+
augmentPageNavigationTimeoutError,
8283
} from "@hyperframes/engine";
8384
import { join, dirname, resolve } from "path";
8485
import { totalmem } from "node:os";
@@ -3155,7 +3156,30 @@ export async function executeRenderJob(
31553156
// unchanged when the message doesn't match, so non-timeout failures (memory
31563157
// exhaustion, other CDP errors) flow through with no change.
31573158
const protocolTimeoutError = augmentProtocolTimeoutError(error, cfg.protocolTimeout);
3158-
const errorMessage = memoryGuidance ?? normalizeErrorMessage(protocolTimeoutError);
3159+
// Surface HyperFrames' PRODUCER_PAGE_NAVIGATION_TIMEOUT_MS env +
3160+
// --browser-timeout CLI + HYPERFRAMES_BROWSER_PATH escape hatch in
3161+
// Puppeteer `page.goto` navigation-timeout errors. Puppeteer's stock
3162+
// "Navigation timeout of 60000 ms exceeded" text names none of these
3163+
// levers. Field signal ts=1784146416 (darwin/arm64, CLI 0.7.58): host
3164+
// page.goto hit Navigation timeout twice on a CSS 3D + audio composition;
3165+
// Docker rendered the same composition successfully. Mirrors #2443's
3166+
// HYPERFRAMES_BROWSER_PATH surfacing at the runtime-navigation layer
3167+
// (vs download-time). `augmentPageNavigationTimeoutError` returns the
3168+
// input unchanged when the message doesn't match the Nav-timeout regex,
3169+
// so protocol-timeout / memory / other CDP errors flow through unchanged.
3170+
// hasCss3D + hasAudio are both left undefined here — no compile-time
3171+
// CSS-3D signal is currently threaded through the render pipeline, and
3172+
// `hasAudio` from the audio_process stage is block-scoped inside the
3173+
// try. Per the helper's fallback docs, unknown flags route to the
3174+
// generic env + browser-path hints (Docker compound hint suppressed).
3175+
// A future compile-time CSS-3D scan (e.g. htmlCompiler.ts pass over
3176+
// `transform-style: preserve-3d`, `perspective:`, `rotateX(`, etc.) can
3177+
// thread both flags here to enable the full compound Docker hint.
3178+
const navigationTimeoutError = augmentPageNavigationTimeoutError(
3179+
protocolTimeoutError,
3180+
cfg.pageNavigationTimeout,
3181+
);
3182+
const errorMessage = memoryGuidance ?? normalizeErrorMessage(navigationTimeoutError);
31593183
const carriedBrowserConsole = getCaptureStageBrowserConsole(error);
31603184
if (carriedBrowserConsole.length > 0) {
31613185
lastBrowserConsole = [...lastBrowserConsole, ...carriedBrowserConsole].slice(-200);

0 commit comments

Comments
 (0)