Skip to content

Write HTML. Render video. Built for agents.

fix(engine): a render stall names the step Chrome hung in and says what to do (#5450)

Miguel Ángelbb34e301ec3c
diff --git a/packages/engine/src/services/frameCapture-motionBlur.test.ts b/packages/engine/src/services/frameCapture-motionBlur.test.ts
index 1a6f3fa1d2..8ef8aedd42 100644
--- a/packages/engine/src/services/frameCapture-motionBlur.test.ts
+++ b/packages/engine/src/services/frameCapture-motionBlur.test.ts
@@ -591,3 +591,47 @@ describe("computeStaticFrameSet's real page-side property matching (not a canned
expect(result.nonSpatialOnlyFrameSet.has(0)).toBe(true);
});
});
+
+describe("a stall on a motion-blurred frame names the step in progress", () => {
+ it("names the frame seek, the injection and the restore seek, not the previous frame's step", async () => {
+ const steps: string[] = [];
+ const session = makeSession({
+ captureStep: "capturing the frame",
+ onBeforeCapture: async () => {
+ steps.push(`inject:${session.captureStep}`);
+ },
+ });
+ const page = globalThis as unknown as {
+ window: { __hf: { seek: (time: number, options?: { subFrameDivisions?: number }) => void } };
+ };
+ page.window.__hf.seek = (_time, options) => {
+ if (options?.subFrameDivisions === undefined) steps.push(`seek:${session.captureStep}`);
+ };
+
+ await captureFrameToBuffer(session, 10, 10 / 30);
+
+ expect(steps[0]).toBe("seek:seeking the timeline");
+ expect(steps[1]).toBe("inject:injecting video frames");
+ expect(steps[steps.length - 1]).toBe("seek:seeking the timeline");
+ });
+
+ it("names the seek and the injection on a frame without motion blur too", async () => {
+ const steps: string[] = [];
+ const session = makeSession({
+ motionBlur: undefined,
+ captureStep: "capturing the frame",
+ onBeforeCapture: async () => {
+ steps.push(`inject:${session.captureStep}`);
+ },
+ });
+ const page = globalThis as unknown as { window: { __hf: { seek: () => void } } };
+ page.window.__hf.seek = () => {
+ steps.push(`seek:${session.captureStep}`);
+ };
+
+ await captureFrameToBuffer(session, 10, 10 / 30);
+
+ expect(steps).toEqual(["seek:seeking the timeline", "inject:injecting video frames"]);
+ expect(session.captureStep).toBe("capturing the frame");
+ });
+});
diff --git a/packages/engine/src/services/frameCapture.ts b/packages/engine/src/services/frameCapture.ts
index 6a97fd9393..4ce71a25a6 100644
--- a/packages/engine/src/services/frameCapture.ts
+++ b/packages/engine/src/services/frameCapture.ts
@@ -108,6 +108,16 @@ export type { CaptureOptions, CaptureResult, CaptureBufferResult, CapturePerfSum
* both times shows its frame for `heldVideoTime`, so footage does not smear. */
export type BeforeCaptureHook = (page: Page, time: number, heldVideoTime?: number) => Promise<void>;
+/** The per-frame wait a capture is in, worded for the stall error a user reads. */
+type CaptureStep =
+ | "seeking the timeline"
+ | "decoding CSS background images"
+ | "injecting video frames"
+ | "waiting for page seek handlers"
+ | "loading color-grading LUTs"
+ | "compositing the page"
+ | "capturing the frame";
+
export interface CaptureSession {
browser: Browser;
/** Exact ownership token for this browser acquisition. */
@@ -298,6 +308,7 @@ export interface CaptureSession {
* retries via screenshot.
*/
deFrameTimeouts?: number;
+ captureStep?: CaptureStep;
/**
* drawElement init passed every gate but stopped before verification +
* canvas injection: the session has no video-frame injector yet (probe
@@ -2856,8 +2867,10 @@ async function prepareFrameForCapture(
);
const seekStart = Date.now();
+ session.captureStep = "seeking the timeline";
const hasPendingComposite = await seekPageTimeline(page, quantizedTime, seekOptions);
+ session.captureStep = "decoding CSS background images";
await decodeDynamicCssBackgroundImages(page);
const seekMs = Date.now() - seekStart;
@@ -2867,9 +2880,12 @@ async function prepareFrameForCapture(
// replacements for <video> elements.
const beforeCaptureStart = Date.now();
if (session.onBeforeCapture) {
+ session.captureStep = "injecting video frames";
await session.onBeforeCapture(page, quantizedTime, heldVideoTime);
}
+ session.captureStep = "waiting for page seek handlers";
await waitForPendingSeekCompletion(page);
+ session.captureStep = "loading color-grading LUTs";
await page.evaluate(async () => {
const runtime = (
window as Window & {
@@ -2889,6 +2905,7 @@ async function prepareFrameForCapture(
session.captureMode !== "beginframe" &&
session.captureMode !== "drawelement"
) {
+ session.captureStep = "compositing the page";
await page.evaluate(async () => {
const w = window as unknown as { __hf_page_composite_prepare?: () => Promise<boolean> };
if (typeof w.__hf_page_composite_prepare === "function") {
@@ -2909,6 +2926,7 @@ async function prepareFrameForCapture(
});
}
+ session.captureStep = "capturing the frame";
return { quantizedTime, seekMs, beforeCaptureMs };
}
@@ -4189,12 +4207,14 @@ async function captureAccumulatedFrame(
const frameTime = quantizeSeekTime(absFrameIndex / fps, fps);
const eventfulSeekStart = Date.now();
+ session.captureStep = "seeking the timeline";
await seekPageTimeline(session.page, frameTime, undefined);
const totals = { seekMs: Date.now() - eventfulSeekStart, beforeCaptureMs: 0, screenshotMs: 0 };
if (session.onBeforeCapture) {
// The injector copies a video's own style only when its frame changes: inject at frameTime
// first so the held frame carries frameTime's style, not the first sample's.
const injectStart = Date.now();
+ session.captureStep = "injecting video frames";
await session.onBeforeCapture(session.page, frameTime, frameTime);
totals.beforeCaptureMs += Date.now() - injectStart;
}
@@ -4237,6 +4257,7 @@ async function captureAccumulatedFrame(
}
const restoreSeekStart = Date.now();
+ session.captureStep = "seeking the timeline";
await seekPageTimeline(session.page, frameTime, { suppressEvents: true });
totals.seekMs += Date.now() - restoreSeekStart;
@@ -4603,6 +4624,7 @@ export async function captureFramesBatchPipelined(
const fps = fpsToNumber(options.fps);
const quantized = times.map((t) => quantizeTimeToFrame(t, fps));
+ session.captureStep = "capturing the frame";
const { encodeResults, failedAt, error } = await produceDrawElementFrameBatch(
page,
quantized,
diff --git a/packages/producer/src/services/render/stages/captureSegmentedStage.ts b/packages/producer/src/services/render/stages/captureSegmentedStage.ts
index 1b60ba4c7d..8f46ad2dc4 100644
--- a/packages/producer/src/services/render/stages/captureSegmentedStage.ts
+++ b/packages/producer/src/services/render/stages/captureSegmentedStage.ts
@@ -203,7 +203,7 @@ async function captureSegmentFrames(
ctx.captureFrame(ctx.session, i, time),
ctx.stallTimeoutMs - (Date.now() - lastProgressAt),
{
- captureMode: ctx.session.captureMode,
+ session: ctx.session,
frameIndex: i,
totalFrames: ctx.totalFrames,
stallTimeoutMs: ctx.stallTimeoutMs,
diff --git a/packages/producer/src/services/render/stages/captureStreamingStage.test.ts b/packages/producer/src/services/render/stages/captureStreamingStage.test.ts
index 44ca736bf5..de9f578c49 100644
--- a/packages/producer/src/services/render/stages/captureStreamingStage.test.ts
+++ b/packages/producer/src/services/render/stages/captureStreamingStage.test.ts
@@ -61,11 +61,12 @@ mock.module("@hyperframes/engine", () => ({
}
return [];
},
- captureFrameToBuffer: async () => {
+ captureFrameToBuffer: async (session: { captureStep?: string }) => {
if (failCaptureFrameToBuffer) {
throw new Error("captureFrameToBuffer failed");
}
if (hangSequentialUntilStall) {
+ session.captureStep = "capturing the frame";
return new Promise(() => {});
}
return { buffer: Buffer.from("frame"), captureTimeMs: 1 };
@@ -600,6 +601,7 @@ describe("runCaptureStreamingStage", () => {
expect(caught).toBeInstanceOf(Error);
expect((caught as Error & { cause?: Error }).cause?.name).toBe("SequentialCaptureStallError");
expect((caught as Error).message).toContain("Sequential screenshot capture stalled");
+ expect((caught as Error).message).toContain("(stuck at frame 0/10 while capturing the frame)");
expect((caught as Error).message).not.toContain("drawElement");
expect(closeCaptureSession).toHaveBeenCalledTimes(1);
});
diff --git a/packages/producer/src/services/render/stages/captureStreamingStage.ts b/packages/producer/src/services/render/stages/captureStreamingStage.ts
index 99d99f706a..9d2ecf433e 100644
--- a/packages/producer/src/services/render/stages/captureStreamingStage.ts
+++ b/packages/producer/src/services/render/stages/captureStreamingStage.ts
@@ -93,6 +93,9 @@ import type { SdrStreamingCapturePlan } from "../capturePlan.js";
*/
const DEFAULT_CAPTURE_STALL_MS = 60_000;
const DE_STALL_POLL_MS = 5_000;
+const STALL_ADVICE =
+ "Chrome stopped answering. If another app is keeping the GPU or CPU busy " +
+ "(a 3D render, a game, another export), let it finish or render one job at a time, then retry.";
/**
* The parallel no-progress watchdog tripped. Typed like the sequential stall
@@ -116,12 +119,12 @@ class ParallelCaptureStallError extends Error {
}) {
const phases = args.phaseSummary ? ` Last worker phases: ${args.phaseSummary}.` : "";
super(
- args.variant === "drain"
+ (args.variant === "drain"
? `[Render] Parallel ${args.captureLabel} capture stalled: no frame progress for ` +
- `${args.stallTimeoutMs}ms (stuck at ${args.lastCapturedFrames}/${args.totalFrames}).${phases}`
+ `${args.stallTimeoutMs}ms (stuck at ${args.lastCapturedFrames}/${args.totalFrames}).${phases}`
: `[Render] Parallel ${args.captureLabel} capture stalled after ${args.stallTimeoutMs}ms ` +
- `with no frame progress (last frame ${args.lastCapturedFrames}/${args.totalFrames}); ` +
- `retrying on a fresh screenshot session.${phases}`,
+ `with no frame progress (last frame ${args.lastCapturedFrames}/${args.totalFrames}); ` +
+ `retrying on a fresh screenshot session.${phases}`) + ` ${STALL_ADVICE}`,
);
this.name = "ParallelCaptureStallError";
this.variant = args.variant;
@@ -160,21 +163,25 @@ function captureModeLabel(mode: CaptureSession["captureMode"]): string {
return "screenshot";
}
+type StalledSession = Pick<CaptureSession, "captureMode" | "captureStep">;
+
class SequentialCaptureStallError extends Error {
readonly captureMode: CaptureSession["captureMode"];
constructor(
- captureMode: CaptureSession["captureMode"],
+ session: StalledSession,
stallTimeoutMs: number,
frameIndex: number,
totalFrames: number,
) {
+ const step = session.captureStep ? ` while ${session.captureStep}` : "";
super(
- `[Render] Sequential ${captureModeLabel(captureMode)} capture stalled: ` +
- `no frame progress for ${stallTimeoutMs}ms (stuck at frame ${frameIndex}/${totalFrames}).`,
+ `[Render] Sequential ${captureModeLabel(session.captureMode)} capture stalled: ` +
+ `no frame progress for ${stallTimeoutMs}ms (stuck at frame ${frameIndex}/${totalFrames}${step}). ` +
+ STALL_ADVICE,
);
this.name = "SequentialCaptureStallError";
- this.captureMode = captureMode;
+ this.captureMode = session.captureMode;
}
}
@@ -182,7 +189,7 @@ export function raceAgainstStall<T>(
promise: Promise<T>,
deadlineMs: number,
input: {
- captureMode: CaptureSession["captureMode"];
+ session: StalledSession;
frameIndex: number;
totalFrames: number;
stallTimeoutMs: number;
@@ -195,11 +202,11 @@ export function raceAgainstStall<T>(
reject(
signal?.aborted
? new Error(
- `[Render] Sequential ${captureModeLabel(input.captureMode)} capture aborted ` +
+ `[Render] Sequential ${captureModeLabel(input.session.captureMode)} capture aborted ` +
`while a capture call was in flight (frame ${input.frameIndex}/${input.totalFrames}).`,
)
: new SequentialCaptureStallError(
- input.captureMode,
+ input.session,
input.stallTimeoutMs,
input.frameIndex,
input.totalFrames,
@@ -473,7 +480,7 @@ async function runWorkerEncodePipelineLoop(
raceAgainstStall(
promise,
stallTimeoutMs - (Date.now() - lastProgressAt),
- { captureMode: session.captureMode, frameIndex: idx, totalFrames, stallTimeoutMs },
+ { session, frameIndex: idx, totalFrames, stallTimeoutMs },
abortSignal,
);
@@ -953,7 +960,7 @@ export async function runCaptureStreamingStage(
const { buffer } = await raceAgainstStall(
captureFrameToBuffer(session, i, time),
stallTimeoutMs - (Date.now() - lastProgressAt),
- { captureMode: session.captureMode, frameIndex: i, totalFrames, stallTimeoutMs },
+ { session, frameIndex: i, totalFrames, stallTimeoutMs },
abortSignal,
);
await reorderBuffer.waitForFrame(i);