fix(producer): long, mostly still films reach their first frame before the stall check stops them (#7521)

* perf(engine): check still frames once per page and share the result with later sessions

* perf(producer): the probe skips the still-frame check unless its session captures

* chore(engine): keep the comment share of the deferred still-frame check files at their base

* fix(producer): the probe session's deferred still-frame check counts as stall-watcher activity

* docs(engine): the still-frame spot-check range is the task's span, not only its own frames

* fix(engine): a reused fast-capture probe session keeps still-frame reuse
This commit is contained in:
Miguel Ángel
2026-11-11 05:40:33 +00:00
committed by GitHub
parent 7ae1ae6494
commit 5073100b7d
16 changed files with 755 additions and 27 deletions
+1
View File
@@ -52,6 +52,7 @@ export type {
CaptureWarning,
CaptureWarningCode,
SubTimelineWaitMemo,
StaticDedupMemo,
SubTimelineWaitOutcome,
} from "./types.js";
@@ -0,0 +1,136 @@
import { mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import {
armDeferredStaticDedup,
armStaticDedup,
prepareCaptureSessionForReuse,
verifyStaticFramesSafe,
type CaptureSession,
} from "./frameCapture.js";
import { pageScreenshotCapture } from "./screenshotService.js";
vi.mock("./screenshotService.js", async (importOriginal) => {
const actual = await importOriginal<typeof import("./screenshotService.js")>();
return { ...actual, pageScreenshotCapture: vi.fn(async () => Buffer.from("still")) };
});
const dirs: string[] = [];
afterEach(() => {
for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
});
/** A session that deferred a check predicting frames 5 and 6 still; unverified arming makes the check visible. */
function deferredSession(deferred: boolean): CaptureSession {
const stats = { eligible: true, staticFrameSet: new Set([5, 6]), totalFrames: 10 };
return {
captureMode: "screenshot",
options: { fps: { num: 30, den: 1 } },
page: {},
...(deferred ? { staticDedupDeferred: stats } : {}),
} as unknown as CaptureSession;
}
describe("still-frame check activity", () => {
it("reports every check screenshot to onStaticDedupActivity", async () => {
const onStaticDedupActivity = vi.fn();
const page = { evaluate: vi.fn(async () => {}) };
const session = { options: { onStaticDedupActivity } } as unknown as CaptureSession;
const frames = new Set(Array.from({ length: 100 }, (_, index) => index + 1));
const result = await verifyStaticFramesSafe(
session,
page as unknown as Parameters<typeof verifyStaticFramesSafe>[1],
frames,
30,
1,
);
expect(result.stats.screenshots).toBeGreaterThan(0);
expect(onStaticDedupActivity).toHaveBeenCalledTimes(result.stats.screenshots);
expect(vi.mocked(pageScreenshotCapture)).toHaveBeenCalledTimes(result.stats.screenshots);
});
});
/** A page whose timeline walk sees one tween in [0 s, 1 s) of a 4 s film; `inject()` adds the drawElement canvas. */
function fastCapturePage() {
let injected = false;
const page = {
evaluate: vi.fn(async (fn: unknown) => {
const source = String(fn);
if (source.includes("getChildren")) {
return {
intervals: [{ start: 0, end: 1, spatial: true }],
tweenCount: 1,
duration: 4,
hasVideo: false,
hasCanvas: injected,
hasFrameSources: false,
hasIframe: false,
hasNonGsapAnim: false,
hasUnresolvableClipStart: false,
hasTimelineCall: false,
};
}
if (source.includes("__hf_page_composite_prepare")) return false;
return [];
}),
};
return { page, inject: () => (injected = true) };
}
describe("a probe session on the fast capture path", () => {
it("keeps still-frame dedup when it is reused to capture after its canvas went in", async () => {
const dir = mkdtempSync(join(tmpdir(), "hf-dedup-defer-"));
dirs.push(dir);
const { page, inject } = fastCapturePage();
const session = {
captureMode: "screenshot",
options: { fps: { num: 30, den: 1 }, deferStaticDedup: true },
config: {},
page,
deRiskFrames: new Set([90]),
} as unknown as CaptureSession;
vi.stubEnv("HF_STATIC_DEDUP_VERIFY", "false");
let predicted = new Set<number>();
try {
await armStaticDedup(session, session.page, () => {});
expect(session.staticFrames).toBeUndefined();
predicted = new Set(session.staticDedupDeferred?.staticFrameSet ?? []);
inject();
session.captureMode = "drawelement";
await prepareCaptureSessionForReuse(session, join(dir, "frames"), null);
} finally {
vi.unstubAllEnvs();
}
expect(session.staticDedupSkipReason).toBeUndefined();
expect(predicted.has(90)).toBe(true);
predicted.delete(90);
expect(session.staticFrames).toEqual(predicted);
expect(predicted.size).toBe(87);
});
});
describe("a deferred still-frame check", () => {
beforeEach(() => vi.stubEnv("HF_STATIC_DEDUP_VERIFY", "false"));
afterEach(() => vi.unstubAllEnvs());
it("runs only on a session that deferred it", async () => {
const other = deferredSession(false);
await armDeferredStaticDedup(other);
expect(other.staticFrames).toBeUndefined();
const deferred = deferredSession(true);
await armDeferredStaticDedup(deferred);
expect(deferred.staticDedupDeferred).toBeUndefined();
expect(deferred.staticFrames?.size).toBe(2);
});
it("runs when the session is reused to capture", async () => {
const dir = mkdtempSync(join(tmpdir(), "hf-dedup-defer-"));
dirs.push(dir);
const deferred = deferredSession(true);
await prepareCaptureSessionForReuse(deferred, join(dir, "frames"), null);
expect(deferred.staticDedupDeferred).toBeUndefined();
expect(deferred.staticFrames?.size).toBe(2);
});
});
@@ -0,0 +1,241 @@
import { beforeEach, describe, expect, it, vi } from "vitest";
import {
armFromSharedStaticDedup,
claimStaticDedupCheck,
pickStaticSpotCheck,
shareableStaticFrames,
staticDedupMemoKey,
type CaptureSession,
type StaticVerificationResult,
} from "./frameCapture.js";
import type { CaptureOptions, StaticDedupMemo } from "../types.js";
import { pageScreenshotCapture } from "./screenshotService.js";
vi.mock("./screenshotService.js", async (importOriginal) => {
const actual = await importOriginal<typeof import("./screenshotService.js")>();
return { ...actual, pageScreenshotCapture: vi.fn() };
});
const fps = 30;
function framesOf(runs: Array<[number, number]>): number[] {
return runs.flatMap(([a, b]) => Array.from({ length: b - a + 1 }, (_, index) => a + index));
}
// Twenty still runs of 60 frames, one every 100 frames, across a 2,000-frame film.
const STILL_RUNS: Array<[number, number]> = Array.from({ length: 20 }, (_, k) => [
k * 100 + 10,
k * 100 + 69,
]);
const STILL = framesOf(STILL_RUNS);
function sessionWith(memo: StaticDedupMemo, options: Partial<CaptureOptions> = {}): CaptureSession {
return {
captureMode: "screenshot",
options: {
width: 1920,
height: 1080,
fps: { num: 30, den: 1 },
format: "png",
transparent: true,
staticDedupMemo: memo,
compositionHash: "composition-a",
...options,
},
} as unknown as CaptureSession;
}
/** A fake verification page: seeks set the current frame, screenshots return `contentAt` of it. */
function fakePage(contentAt: (frame: number) => string) {
const seen: number[] = [];
let frame = 0;
const page = {
evaluate: vi.fn(async (_fn: unknown, t: number) => {
frame = Math.round(t * fps);
}),
close: vi.fn(async () => {}),
};
vi.mocked(pageScreenshotCapture).mockImplementation(async () => {
seen.push(frame);
return Buffer.from(contentAt(frame));
});
const openVerificationPage = vi.fn(async () => page as never);
return { seen, openVerificationPage };
}
function verdictOf(
outcome: StaticVerificationResult["outcome"],
frames: number[],
): StaticVerificationResult {
return {
outcome,
verifiedFrames: new Set(frames),
stats: {} as StaticVerificationResult["stats"],
};
}
beforeEach(() => {
vi.mocked(pageScreenshotCapture).mockReset();
});
describe("staticDedupMemoKey", () => {
it("matches only when every pixel-deciding input matches", () => {
const memo: StaticDedupMemo = {};
const base = staticDedupMemoKey(sessionWith(memo));
expect(base).toBeDefined();
expect(
staticDedupMemoKey(sessionWith(memo, { staticDedupFrameRange: { start: 0, end: 9 } })),
).toBe(base);
for (const change of [
{ compositionHash: "composition-b" },
{ width: 1280 },
{ deviceScaleFactor: 2 },
{ transparent: false },
{ format: "jpeg" as const },
{ variables: { title: "other" } },
{ hiddenElementIds: ["logo"] },
]) {
expect(staticDedupMemoKey(sessionWith(memo, change))).not.toBe(base);
}
const beginframe = { ...sessionWith(memo), captureMode: "beginframe" } as CaptureSession;
expect(staticDedupMemoKey(beginframe)).not.toBe(base);
});
it("is absent without a memo or a composition hash, so the session verifies for itself", () => {
expect(staticDedupMemoKey(sessionWith(undefined as never))).toBeUndefined();
expect(staticDedupMemoKey(sessionWith({}, { compositionHash: undefined }))).toBeUndefined();
});
});
describe("shareableStaticFrames", () => {
it("shares the frames of a verdict that verified runs, including one stopped by its budget", () => {
expect(shareableStaticFrames(verdictOf("time_budget", [10, 11, 12]))).toEqual([10, 11, 12]);
});
it.each([
["no verdict at all", null],
["a budget stop with no run verified", verdictOf("time_budget", [])],
["a mismatch", verdictOf("mismatch", [])],
["an infrastructure failure", verdictOf("infrastructure", [])],
["an unprofitable plan", verdictOf("unprofitable", [])],
])("shares dedup off after %s", (_label, verdict) => {
expect(shareableStaticFrames(verdict)).toBeNull();
});
});
describe("claimStaticDedupCheck", () => {
it("lets the first session for a key verify and the later ones wait for its result", async () => {
const memo: StaticDedupMemo = {};
const first = claimStaticDedupCheck(sessionWith(memo));
const second = claimStaticDedupCheck(
sessionWith(memo, { staticDedupFrameRange: { start: 0, end: 9 } }),
);
expect(first?.kind).toBe("verify");
expect(second?.kind).toBe("reuse");
if (first?.kind !== "verify" || second?.kind !== "reuse") throw new Error("unexpected claims");
first.settle([10, 11]);
await expect(second.check).resolves.toEqual([10, 11]);
});
it("passes a failed check on as off, so a waiting session takes no screenshot", async () => {
const memo: StaticDedupMemo = {};
const first = claimStaticDedupCheck(sessionWith(memo));
const second = claimStaticDedupCheck(sessionWith(memo));
if (first?.kind !== "verify" || second?.kind !== "reuse") throw new Error("unexpected claims");
first.settle(shareableStaticFrames(verdictOf("time_budget", [])));
const { seen, openVerificationPage } = fakePage(() => "still");
const session = sessionWith(memo);
await armFromSharedStaticDedup(session, await second.check, new Set(STILL), fps, vi.fn(), {
openVerificationPage,
});
expect(session.staticDedupSkipReason).toBe("verification_failed");
expect(openVerificationPage).not.toHaveBeenCalled();
expect(seen).toEqual([]);
});
it("gives a session with a different page its own check", () => {
const memo: StaticDedupMemo = {};
claimStaticDedupCheck(sessionWith(memo));
expect(
claimStaticDedupCheck(sessionWith(memo, { compositionHash: "composition-b" }))?.kind,
).toBe("verify");
});
it("claims nothing without a memo or a composition hash", () => {
expect(claimStaticDedupCheck(sessionWith(undefined as never))).toBeUndefined();
expect(claimStaticDedupCheck(sessionWith({}, { compositionHash: undefined }))).toBeUndefined();
});
});
describe("pickStaticSpotCheck", () => {
it("picks at most 4 runs of at most 48 frames, all inside the session's frames", () => {
const picked = [...pickStaticSpotCheck(new Set(STILL), { start: 500, end: 1500 })];
expect(picked.every((frame) => frame >= 500 && frame < 1500)).toBe(true);
const runStarts = picked.filter((frame) => !picked.includes(frame - 1));
expect(runStarts).toEqual([510, 810, 1110, 1410]);
expect(picked.length).toBe(4 * 48);
});
it("skips runs that start at frame 0 or are too short to verify", () => {
const picked = pickStaticSpotCheck(new Set([0, 1, 2, 3, 20, 21, 40, 41, 42]), undefined);
expect([...picked]).toEqual([40, 41, 42]);
});
});
describe("armFromSharedStaticDedup", () => {
const worker = (memo: StaticDedupMemo, options: Partial<CaptureOptions> = {}) =>
sessionWith(memo, { staticDedupFrameRange: { start: 500, end: 1500 }, ...options });
it("reuses the shared set after a spot check of 12 screenshots inside the worker's frames", async () => {
const { seen, openVerificationPage } = fakePage(() => "still");
const session = worker({});
const log = vi.fn();
await armFromSharedStaticDedup(session, STILL, new Set(STILL), fps, log, {
openVerificationPage,
});
expect(session.staticFrames).toEqual(new Set(STILL));
expect(seen.length).toBe(12);
expect(seen.every((frame) => frame >= 500 && frame < 1500)).toBe(true);
expect(log).toHaveBeenCalledTimes(1);
});
it("keeps only the shared frames this worker also predicts still", async () => {
const { openVerificationPage } = fakePage(() => "still");
const session = worker({});
const predicted = new Set(framesOf(STILL_RUNS.slice(0, 10)));
await armFromSharedStaticDedup(session, STILL, predicted, fps, vi.fn(), {
openVerificationPage,
});
expect(session.staticFrames).toEqual(predicted);
});
it("takes no screenshot when the render already found verification gives nothing", async () => {
const { seen, openVerificationPage } = fakePage(() => "still");
const session = worker({});
const log = vi.fn();
await armFromSharedStaticDedup(session, null, new Set(STILL), fps, log, {
openVerificationPage,
});
expect(session.staticFrames).toBeUndefined();
expect(session.staticDedupSkipReason).toBe("verification_failed");
expect(openVerificationPage).not.toHaveBeenCalled();
expect(seen).toEqual([]);
expect(log).toHaveBeenCalledTimes(1);
});
it("turns dedup off for the worker when the shared set is wrong for its page", async () => {
// The shared set says these frames are still, but on this page everything from 800 on moves.
const { openVerificationPage } = fakePage((frame) =>
frame < 800 ? "still" : `frame ${frame}`,
);
const session = worker({});
const log = vi.fn();
await armFromSharedStaticDedup(session, STILL, new Set(STILL), fps, log, {
openVerificationPage,
});
expect(session.staticFrames).toBeUndefined();
expect(session.staticDedupSkipReason).toBe("verification_failed");
expect(log).toHaveBeenCalledTimes(1);
expect(log.mock.calls[0]![0]).toContain("spot check of the shared set: mismatch");
});
});
+236 -12
View File
@@ -120,6 +120,7 @@ import type {
SubTimelineWaitMemo,
SubTimelineWaitOutcome,
} from "../types.js";
import { PROVENANCE_VERSION } from "../utils/renderProvenance.js";
import { cloneCaptureWarnings } from "./captureWarning.js";
import { installMediaRenderIdBridge } from "./mediaRenderIdBridge.js";
import {
@@ -213,6 +214,8 @@ export interface CaptureSession {
* Undefined when armed or disabled.
*/
staticDedupSkipReason?: string;
/** The init-time page analysis of a check deferred by `deferStaticDedup`; `armDeferredStaticDedup` runs it. */
staticDedupDeferred?: StaticFrameStats;
// Tracks whether the page/browser handles have already been released by
// closeCaptureSession. Used to make closeCaptureSession idempotent under
// browser-pool semantics (see the function body for the full invariant).
@@ -1311,9 +1314,6 @@ async function initDrawElementOrTransparentBackground(
// passed) and the DOM is still normal (canvas not yet injected, so the
// verification screenshots are valid). drawElement-path only; see armStaticDedup.
await armStaticDedup(session, page, logInitPhase);
// A static frame reuses the previous drawElement capture; a risk frame is captured by
// another session, so its neighbours must not reuse across it.
for (const f of session.deRiskFrames ?? []) session.staticFrames?.delete(f);
// Video comps on injector-less sessions (probe sessions initialize before
// video extraction) DEFER the rest of the drawElement init: ground-truth
// screenshots would capture black <video> boxes, and once the canvas is
@@ -3701,6 +3701,8 @@ export function isStaticDedupFrameAnalysisSafe(totalFrames: number): boolean {
* comp on any signal the tween-walker can't see: video / canvas / webgl (redraw without
* a tween), zero tweens (non-GSAP animation), or a running CSS/WAAPI animation.
*/
type StaticFrameStats = Awaited<ReturnType<typeof computeStaticFrameSet>>;
export async function computeStaticFrameSet(
page: Page,
fps: number,
@@ -4240,6 +4242,7 @@ export async function verifyStaticFramesSafe(
await seekToFrame(frameIdx);
stats.screenshots++;
const buf = await capture(page, session.options);
session.options.onStaticDedupActivity?.();
if (stats.screenshots === 1) firstShotMs = now() - shotStart;
return buf;
};
@@ -4280,6 +4283,138 @@ export async function verifyStaticFramesSafe(
}
}
// A session reusing an earlier session's verified set re-verifies this many short runs of its own frames.
const STATIC_SPOT_CHECK_RUNS = 4;
const STATIC_SPOT_CHECK_FRAMES = 2 * STATIC_VERIFY_REFERENCE_STRIDE;
/** Sessions share a dedup verdict only when every input that decides their pixels is equal. */
export function staticDedupMemoKey(session: CaptureSession): string | undefined {
const options = session.options;
if (!options.staticDedupMemo || !options.compositionHash) return undefined;
return JSON.stringify([
options.compositionHash,
options.width,
options.height,
options.deviceScaleFactor ?? 1,
session.captureMode,
options.format ?? null,
options.quality ?? null,
options.transparent === true,
options.fps,
[...(options.hiddenElementIds ?? [])].sort(),
options.variables ?? null,
options.motionBlur ?? null,
options.pageMotionBlur ?? null,
PROVENANCE_VERSION,
]);
}
/** Up to STATIC_SPOT_CHECK_RUNS short runs of `frames` inside `range`: the first, the last and evenly between. */
export function pickStaticSpotCheck(
frames: ReadonlySet<number>,
range?: { start: number; end: number },
): Set<number> {
const inRange = [...frames]
.filter((frame) => !range || (frame >= range.start && frame < range.end))
.sort((left, right) => left - right);
const runs = contiguousStaticRuns(inRange).filter((run) => run.a >= 1 && run.b - run.a >= 2);
const count = Math.min(STATIC_SPOT_CHECK_RUNS, runs.length);
const picked = new Set<number>();
for (let index = 0; index < count; index++) {
const run = runs[count === 1 ? 0 : Math.round((index * (runs.length - 1)) / (count - 1))]!;
const end = Math.min(run.b, run.a + STATIC_SPOT_CHECK_FRAMES - 1);
for (let frame = run.a; frame <= end; frame++) picked.add(frame);
}
return picked;
}
export interface SharedStaticDedupDependencies {
openVerificationPage?: (session: CaptureSession) => Promise<Page>;
}
export type StaticDedupClaim =
| { kind: "verify"; settle: (frames: readonly number[] | null) => void }
| { kind: "reuse"; check: Promise<readonly number[] | null> };
/** The first session for a key verifies and must settle; later sessions with that key reuse its check. */
export function claimStaticDedupCheck(session: CaptureSession): StaticDedupClaim | undefined {
const key = staticDedupMemoKey(session);
const memo = session.options.staticDedupMemo;
if (!key || !memo) return undefined;
const checks = (memo.checks ??= new Map());
const pending = checks.get(key);
if (pending) return { kind: "reuse", check: pending };
let settle!: (frames: readonly number[] | null) => void;
checks.set(key, new Promise((resolve) => (settle = resolve)));
return { kind: "verify", settle };
}
/** What a verification gives later sessions: its fully verified frames, or null when it has none. */
export function shareableStaticFrames(
verdict: StaticVerificationResult | null,
): readonly number[] | null {
const usable =
verdict !== null &&
verdict.outcome !== "mismatch" &&
verdict.outcome !== "infrastructure" &&
verdict.outcome !== "unprofitable" &&
verdict.verifiedFrames.size > 0;
return usable ? [...verdict.verifiedFrames] : null;
}
/**
* Arms dedup from an earlier session's check of the same page. The shared frames are narrowed to this
* session's own prediction and spot-checked; any failure turns dedup off for this session only.
*/
export async function armFromSharedStaticDedup(
session: CaptureSession,
sharedFrames: readonly number[] | null,
predicted: ReadonlySet<number>,
fps: number,
logInitPhase: (phase: string) => void,
dependencies: SharedStaticDedupDependencies = {},
): Promise<void> {
if (!sharedFrames) {
session.staticDedupSkipReason = "verification_failed";
logInitPhase(
"static-frame dedup: disabled (an earlier session of this render could not verify it)",
);
return;
}
const frames = new Set(sharedFrames.filter((frame) => predicted.has(frame)));
const spot = pickStaticSpotCheck(frames, session.options.staticDedupFrameRange);
if (spot.size === 0) {
session.staticDedupSkipReason = "ineligible";
logInitPhase("static-frame dedup: disabled (no shared static run in this session's frames)");
return;
}
const openPage = dependencies.openVerificationPage ?? createStaticVerificationPage;
let page: Page | undefined;
let verdict: StaticVerificationResult | undefined;
try {
page = await openPage(session);
verdict = await verifyStaticFramesSafe(session, page, spot, fps, 1);
} catch {
verdict = undefined;
} finally {
await page?.close().catch(() => {});
}
if (verdict?.outcome !== "verified" || verdict.verifiedFrames.size !== spot.size) {
session.staticDedupSkipReason = "verification_failed";
const at = verdict?.badFrame === undefined ? "" : ` at frame ${verdict.badFrame}`;
logInitPhase(
`static-frame dedup: disabled (spot check of the shared set: ${verdict?.outcome ?? "infrastructure"}${at})`,
);
return;
}
session.staticDedupVerification = verdict;
session.staticFrames = frames;
logInitPhase(
`static-frame dedup: ${frames.size}/${predicted.size} predicted frame(s) reusable (shared check, ` +
`spot check ${spot.size} frame(s), screenshots=${verdict.stats.screenshots}, elapsedMs=${verdict.stats.elapsedMs})`,
);
}
/**
* Arm static-frame dedup for this render (default-on; opt out with HF_STATIC_DEDUP=false).
* Runs at init in normal DOM state so the verification screenshots are valid. Predicts
@@ -4287,7 +4422,7 @@ export async function verifyStaticFramesSafe(
* and on success stores it on the session for captureFrameCore to reuse. Sample budget
* via HF_STATIC_DEDUP_SAMPLES (default 24).
*/
async function armStaticDedup(
export async function armStaticDedup(
session: CaptureSession,
page: Page,
logInitPhase: (phase: string) => void,
@@ -4313,13 +4448,46 @@ async function armStaticDedup(
);
session.motionBlurNonSpatialFrames = sharedStaticFrameStats.nonSpatialOnlyFrameSet;
}
await armStaticDedupFrames(session, page, logInitPhase, sharedStaticFrameStats);
}
/** Runs the still-frame check a session deferred at init; a no-op for any other session. */
export async function armDeferredStaticDedup(session: CaptureSession): Promise<void> {
const stats = session.staticDedupDeferred;
if (!stats) return;
session.staticDedupDeferred = undefined;
const startedAt = Date.now();
const logInitPhase = (phase: string) =>
console.error(
`[initSession:${session.captureMode}] ${phase} (deferred, ${Date.now() - startedAt}ms)`,
);
if (videoInjectionBlocksStaticDedup(session, logInitPhase)) return;
await checkStaticFrames(session, stats, logInitPhase);
}
function videoInjectionBlocksStaticDedup(
session: CaptureSession,
logInitPhase: (phase: string) => void,
): boolean {
if (!session.onBeforeCapture) return false;
session.staticDedupSkipReason = "video_injection";
logInitPhase("static-frame dedup: disabled (before-capture hook / video injection active)");
return true;
}
async function armStaticDedupFrames(
session: CaptureSession,
page: Page,
logInitPhase: (phase: string) => void,
sharedStaticFrameStats?: StaticFrameStats,
): Promise<void> {
// Idempotent: the drawElement init path arms dedup BEFORE canvas injection
// (verification screenshots need the un-injected DOM), and initializeSession
// calls this again unconditionally afterwards. Once staticFrames is
// populated, re-running would overwrite the armed state with
// skipReason="capture_mode" (captureMode is "drawelement" by then) —
// contradictory telemetry — and re-run the verification seeks. No-op instead.
if (session.staticFrames || session.staticDedupSkipReason) return;
if (session.staticFrames || session.staticDedupSkipReason || session.staticDedupDeferred) return;
// Default ON for everyone; opt out via HF_STATIC_DEDUP in {false,0,off} (resolved into
// EngineConfig.staticFrameDedup by resolveConfig). Verification is the safety net at scale.
// Default-on: only an explicit `staticFrameDedup === false` (resolved from
@@ -4344,11 +4512,7 @@ async function armStaticDedup(
);
return;
}
if (session.onBeforeCapture) {
session.staticDedupSkipReason = "video_injection";
logInitPhase("static-frame dedup: disabled (before-capture hook / video injection active)");
return;
}
if (videoInjectionBlocksStaticDedup(session, logInitPhase)) return;
const pageComposite = await page
.evaluate(
() =>
@@ -4370,6 +4534,34 @@ async function armStaticDedup(
logInitPhase(`static-frame dedup: disabled (${stats.reason})`);
return;
}
// Deferred after the page is read, so a later drawElement canvas cannot change the analysis.
if (session.options.deferStaticDedup) {
session.staticDedupDeferred = stats;
logInitPhase("static-frame dedup: deferred until this session captures");
return;
}
await checkStaticFrames(session, stats, logInitPhase);
}
/** Verifies (or shares) the predicted still frames and arms them, without the risk frames. */
async function checkStaticFrames(
session: CaptureSession,
stats: StaticFrameStats,
logInitPhase: (phase: string) => void,
): Promise<void> {
try {
await verifyOrShareStaticFrames(session, stats, logInitPhase);
} finally {
for (const f of session.deRiskFrames ?? []) session.staticFrames?.delete(f);
}
}
async function verifyOrShareStaticFrames(
session: CaptureSession,
stats: StaticFrameStats,
logInitPhase: (phase: string) => void,
): Promise<void> {
const fps = fpsToNumber(session.options.fps);
const rawSamples = Number(process.env.HF_STATIC_DEDUP_SAMPLES ?? "24");
const samples = Number.isFinite(rawSamples) && rawSamples >= 1 ? rawSamples : 24;
session.staticDedupPredictedCount = stats.staticFrameSet.size;
@@ -4381,6 +4573,36 @@ async function armStaticDedup(
);
return;
}
const claim = claimStaticDedupCheck(session);
if (claim?.kind === "reuse") {
await armFromSharedStaticDedup(
session,
await claim.check,
stats.staticFrameSet,
fps,
logInitPhase,
);
return;
}
// Every exit settles the claim, so sessions waiting on this check never hang.
let shared: StaticVerificationResult | null = null;
try {
await verifyAndArmStaticDedup(session, stats, fps, samples, logInitPhase, (verdict) => {
shared = verdict;
});
} finally {
claim?.settle(shareableStaticFrames(shared));
}
}
async function verifyAndArmStaticDedup(
session: CaptureSession,
stats: Awaited<ReturnType<typeof computeStaticFrameSet>>,
fps: number,
samples: number,
logInitPhase: (phase: string) => void,
onVerdict: (verdict: StaticVerificationResult) => void,
): Promise<void> {
let verificationPage: Page | undefined;
let verdict: StaticVerificationResult;
try {
@@ -4400,6 +4622,7 @@ async function armStaticDedup(
await verificationPage?.close().catch(() => {});
}
session.staticDedupVerification = verdict;
onVerdict(verdict);
if (verdict.outcome === "mismatch" || verdict.outcome === "infrastructure") {
session.staticDedupSkipReason = "verification_failed";
logInitPhase(
@@ -5662,11 +5885,11 @@ export async function closeCaptureSession(session: CaptureSession): Promise<void
session.isInitialized = false;
}
export function prepareCaptureSessionForReuse(
export async function prepareCaptureSessionForReuse(
session: CaptureSession,
outputDir: string,
onBeforeCapture: BeforeCaptureHook | null,
): void {
): Promise<void> {
if (!existsSync(outputDir)) {
mkdirSync(outputDir, { recursive: true });
}
@@ -5689,6 +5912,7 @@ export function prepareCaptureSessionForReuse(
session.lastFrameBuffer = undefined;
session.lastFrameAbsoluteIndex = undefined;
session.staticDedupCount = 0;
await armDeferredStaticDedup(session);
}
export async function getCompositionDuration(session: CaptureSession): Promise<number> {
@@ -933,7 +933,7 @@ async function executeWorkerTask(
const launch = createCaptureSession(
serverUrl,
task.outputDir,
captureOptions,
{ ...captureOptions, staticDedupFrameRange: { start: task.startFrame, end: task.endFrame } },
createBeforeCaptureHook(),
workerConfig,
);
+16
View File
@@ -38,6 +38,14 @@ export interface SubTimelineWaitMemo {
loggedSceneCallbackErrors?: string[];
}
/**
* Shared by every capture session of one render: per key, the first session's static-frame dedup check,
* which later sessions with that key wait for. It resolves to the verified frames, or null for none.
*/
export interface StaticDedupMemo {
checks?: Map<string, Promise<readonly number[] | null>>;
}
export type CaptureWarningCode =
| "media_readiness_timeout"
| "media_load_failed"
@@ -226,6 +234,14 @@ export interface CaptureOptions {
skipReadinessVideoIds?: readonly string[];
/** Pass one object to every session of a render; see `SubTimelineWaitMemo`. */
subTimelineWaitMemo?: SubTimelineWaitMemo;
/** Pass one object to every session of a render, with `compositionHash`; see `StaticDedupMemo`. */
staticDedupMemo?: StaticDedupMemo;
/** Hash of the composition HTML this session loads; part of the static dedup sharing key. */
compositionHash?: string;
/** The frames of this session's task, [start, end); an interleaved task captures only some of them. */
staticDedupFrameRange?: { start: number; end: number };
deferStaticDedup?: boolean;
onStaticDedupActivity?: () => void;
/**
* Render-time variable overrides for the composition. The engine injects
* these as `window.__hfVariables` via `evaluateOnNewDocument` before any
@@ -132,6 +132,7 @@ export {
rebuildExtractedFramesFromPlanDir,
RenderChunkValidationError,
} from "./chunkFrames.js";
import { noteStaticDedupActivity } from "../render/shared.js";
const LEGACY_DISTRIBUTED_VP9_CPU_USED = 2;
@@ -749,6 +750,7 @@ export async function renderChunk(
deferredVideos.filter((video) => remoteVideoIds.has(video.videoId)),
),
});
captureOptions.onStaticDedupActivity = () => noteStaticDedupActivity(job);
// Resolve worker count up-front. Sequential capture reuses the initialized
// session below. Parallel BeginFrame capture pays one bounded preflight
@@ -215,6 +215,41 @@ describe("RenderObservabilityRecorder", () => {
vi.useRealTimers();
});
it("keeps the first-frame window open while bounded check work goes on, and stalls once it stops", async () => {
vi.useFakeTimers();
const recorder = new RenderObservabilityRecorder({
pipelineStartMs: Date.now(),
log: makeLog(),
renderJobId: "render-stall-activity",
});
let activity = 0;
const checking = setInterval(() => (activity += 1), 1_000);
let outcome: unknown = "pending";
const stage = observeRenderStage(
recorder,
"capture_disk",
undefined,
() => new Promise<void>(() => {}),
{
stall: {
progress: () => 0,
noProgressMs: 10_000,
firstProgressMs: 10_000,
activity: () => activity,
},
},
);
stage.catch((error: unknown) => (outcome = error));
await vi.advanceTimersByTimeAsync(60_000);
expect(outcome).toBe("pending");
clearInterval(checking);
await vi.advanceTimersByTimeAsync(20_000);
expect((outcome as Error).message).toBe(
"[Render] capture_disk stalled: no progress for 10000ms (stuck at 0).",
);
vi.useRealTimers();
});
describe("the stall watchdog across a system sleep", () => {
const watch = () => {
const recorder = new RenderObservabilityRecorder({
@@ -618,6 +618,8 @@ export interface StageStallRule {
tailMs?: number;
detail?: () => string | undefined;
attemptOpened?: () => void;
/** Bounded work that is not progress but not a stall either: a change keeps the current window open. */
activity?: () => number;
}
/**
@@ -648,26 +650,26 @@ const STALL_POLL_MS = 5_000;
function watchStall(phase: string, rule: StageStallRule) {
const detail = rule.detail ?? (() => undefined);
let last = rule.progress();
let lastActivity = rule.activity?.();
let budgetMs = rule.firstProgressMs;
const silence = createStallClock();
const pollMs = Math.min(STALL_POLL_MS, rule.noProgressMs, rule.firstProgressMs);
let attempt: AbortController | undefined;
let timer: ReturnType<typeof setInterval> | undefined;
let inTail = false;
const activityMoved = (): boolean => {
const activity = rule.activity?.();
if (activity === lastActivity) return false;
lastActivity = activity;
return true;
};
const restartWindow = (ms: number) => {
last = rule.progress();
budgetMs = ms;
silence.reset();
};
const tripped = new Promise<never>((_, reject) => {
timer = setInterval(() => {
const current = rule.progress();
if (rule.complete?.() && !inTail) {
inTail = true;
return restartWindow(rule.tailMs ?? rule.noProgressMs);
}
if (current !== last) return restartWindow(rule.noProgressMs);
if (silence.idle(pollMs) < budgetMs) return;
const trip = (current: number) => {
const error = new RenderStageStalledError(phase, budgetMs, current, detail());
if (attempt && !attempt.signal.aborted) {
attempt.abort(error);
@@ -675,6 +677,16 @@ function watchStall(phase: string, rule: StageStallRule) {
}
clearInterval(timer);
reject(error);
};
timer = setInterval(() => {
const current = rule.progress();
if (rule.complete?.() && !inTail) {
inTail = true;
return restartWindow(rule.tailMs ?? rule.noProgressMs);
}
if (current !== last) return restartWindow(rule.noProgressMs);
if (activityMoved()) return silence.reset();
if (silence.idle(pollMs) >= budgetMs) trip(current);
}, pollMs);
});
const openAttempt: OpenStallAttempt = (parent) => {
@@ -401,6 +401,17 @@ export function forgetWorkerPhases(job: object): void {
workerPhasesByJob.delete(job);
}
const staticDedupActivityByJob = new WeakMap<object, number>();
/** Counts a render's still-frame check screenshots; the capture stall watcher reads it as activity. */
export function noteStaticDedupActivity(job: object): void {
staticDedupActivityByJob.set(job, (staticDedupActivityByJob.get(job) ?? 0) + 1);
}
export function staticDedupActivity(job: object): number {
return staticDedupActivityByJob.get(job) ?? 0;
}
export function describeWorkerPhases(job: object): string | undefined {
const phases = workerPhasesByJob.get(job);
if (!phases?.size) return undefined;
@@ -355,8 +355,12 @@ function defaultSessionFactory(input: CaptureSegmentedStageInput): SessionFactor
};
const session = probeSession ?? (await openSession());
if (probeSession) {
openSegmentedSessionReuse(input, probeSession, injector);
const reused = probeSession;
probeSession = null;
await openSegmentedSessionReuse(input, reused, injector).catch(async (error: unknown) => {
await closeCaptureSession(reused).catch(() => {});
throw error;
});
}
try {
if (!session.isInitialized) await withinInitBudget(initializeSession(session), session);
@@ -370,12 +374,12 @@ function defaultSessionFactory(input: CaptureSegmentedStageInput): SessionFactor
};
}
function openSegmentedSessionReuse(
async function openSegmentedSessionReuse(
input: CaptureSegmentedStageInput,
session: CaptureSession,
injector: () => BeforeCaptureHook | null,
): void {
prepareCaptureSessionForReuse(session, input.framesDir, injector());
): Promise<void> {
await prepareCaptureSessionForReuse(session, input.framesDir, injector());
}
async function openSegmentedSession(
@@ -499,7 +499,7 @@ async function runSequentialDiskCapture(
// Reuse preparation can fail on the output dir (permissions, read-only, disk full);
// keep it inside try/finally so the borrowed probe browser is still closed.
if (probeSession) {
prepareCaptureSessionForReuse(session, framesDir, videoInjector);
await prepareCaptureSessionForReuse(session, framesDir, videoInjector);
probeSession = null;
}
await ensureSessionReady(session, {
@@ -1085,7 +1085,7 @@ export async function runCaptureStreamingStage(
const session = probeSession ?? (await openSession());
captureBeyondViewport = session.options.captureBeyondViewport;
if (probeSession) {
prepareCaptureSessionForReuse(session, framesDir, videoInjector);
await prepareCaptureSessionForReuse(session, framesDir, videoInjector);
probeSession = null;
}
// The screenshot capture of today: same config with fast capture off. Its frames are not
@@ -212,7 +212,9 @@ mock.module("../../htmlCompiler.js", () => ({
resolveCompositionDurations: async () => [],
}));
const notedStaticDedupActivity: object[] = [];
mock.module("../shared.js", () => ({
noteStaticDedupActivity: (job: object) => notedStaticDedupActivity.push(job),
BROWSER_MEDIA_EPSILON: 0.0001,
projectBrowserEndToCompositionTimeline: (
existingStart: number,
@@ -1208,6 +1210,32 @@ describe("runProbeStage — forceScreenshot threading", () => {
expect(input.cfg.forceScreenshot).toBe(false);
});
it("defers the probe's still-frame check and gives its session the render's memo and page hash", async () => {
capturedOptions.length = 0;
const { runProbeStage } = await import("./probeStage.js");
const staticDedupMemo = {};
await runProbeStage({ ...makeProbeInput({}), staticDedupMemo });
const options = capturedOptions[0] as {
deferStaticDedup?: boolean;
staticDedupMemo?: object;
compositionHash?: string;
};
expect(options.deferStaticDedup).toBe(true);
expect(options.staticDedupMemo).toBe(staticDedupMemo);
expect(options.compositionHash).toMatch(/^[0-9a-f]{16}$/);
});
it("reports the deferred check's screenshots to the render's stall watcher when its session is reused", async () => {
capturedOptions.length = 0;
notedStaticDedupActivity.length = 0;
const { runProbeStage } = await import("./probeStage.js");
const input = makeProbeInput({});
await runProbeStage(input);
const options = capturedOptions[0] as { onStaticDedupActivity?: () => void };
options.onStaticDedupActivity?.();
expect(notedStaticDedupActivity).toEqual([input.job]);
});
it("passes forceScreenshot:false through unchanged when neither cfg nor stage input forces it", async () => {
capturedCfgs.length = 0;
@@ -36,6 +36,7 @@ import {
type CompositionLengthSource,
type EngineConfig,
type SubTimelineWaitMemo,
type StaticDedupMemo,
closeCaptureSession,
compositionRequiresWebGpu,
createCaptureSession,
@@ -75,6 +76,7 @@ import {
import type { ProducerLogger } from "../../../logger.js";
import {
BROWSER_MEDIA_EPSILON,
noteStaticDedupActivity,
projectBrowserEndToCompositionTimeline,
resolveBrowserMediaEnd,
writeCompiledArtifacts,
@@ -84,6 +86,7 @@ import type { RenderJob } from "../../renderOrchestrator.js";
import { isActionableProbeFailure } from "./probeFailures.js";
import { preflightCompositionAssetMediaTypes } from "../../assetMediaType.js";
import { resolveCaptureSurface } from "../captureImageFormat.js";
import { computeCompositionObservabilityHash } from "../observability.js";
export interface ProbeStageInput {
projectDir: string;
@@ -109,6 +112,7 @@ export interface ProbeStageInput {
needsAlpha: boolean;
deviceScaleFactor: number;
subTimelineWaitMemo: SubTimelineWaitMemo;
staticDedupMemo?: StaticDedupMemo;
}
const FRAME_BOUNDARY_EPSILON = 1e-3;
@@ -370,6 +374,7 @@ export async function runProbeStage(input: ProbeStageInput): Promise<ProbeStageR
needsAlpha,
deviceScaleFactor,
subTimelineWaitMemo,
staticDedupMemo,
} = input;
let { compiled } = input;
@@ -446,6 +451,10 @@ export async function runProbeStage(input: ProbeStageInput): Promise<ProbeStageR
pageMotionBlur: job.config.pageMotionBlur,
requiresWebGpu: compositionRequiresWebGpu(compiled.html),
subTimelineWaitMemo,
staticDedupMemo,
compositionHash: computeCompositionObservabilityHash(compiled.html),
deferStaticDedup: true,
onStaticDedupActivity: () => noteStaticDedupActivity(job),
};
const PROBE_MAX_ATTEMPTS = 2;
@@ -71,6 +71,7 @@ import {
type CaptureOptions,
type CaptureVideoMetadataHint,
type SubTimelineWaitMemo,
type StaticDedupMemo,
type CaptureSession,
type BeforeCaptureHook,
createVideoFrameInjector,
@@ -148,6 +149,8 @@ import {
createMemorySampler,
describeWorkerPhases,
forgetWorkerPhases,
noteStaticDedupActivity,
staticDedupActivity,
type MemorySampler,
reportExtractProgress,
updateJobStatus,
@@ -1251,6 +1254,7 @@ export function frameStallRule(
tailMs: Math.max(TAIL_STALL_MS, noProgressMs),
detail: () => describeWorkerPhases(job),
attemptOpened: () => forgetWorkerPhases(job),
activity: () => staticDedupActivity(job),
};
}
@@ -3426,6 +3430,7 @@ async function executeRenderPipeline(input: {
Object.assign(job, result),
);
const subTimelineWaitMemo: SubTimelineWaitMemo = {};
const staticDedupMemo: StaticDedupMemo = {};
const probeResult = await observeRenderStage(
observability,
"browser_probe",
@@ -3447,6 +3452,7 @@ async function executeRenderPipeline(input: {
needsAlpha,
deviceScaleFactor,
subTimelineWaitMemo,
staticDedupMemo,
recordReferenceBackground,
}),
// Browser probe is pre-capture; report `browser calibrating` so a
@@ -3829,6 +3835,9 @@ async function executeRenderPipeline(input: {
videoMetadataHints,
skipReadinessVideoIds: videoReadinessSkipIds,
subTimelineWaitMemo,
staticDedupMemo,
compositionHash,
onStaticDedupActivity: () => noteStaticDedupActivity(job),
// Probe-resolved duration: drawElement self-verification derives its
// sample frame indices from this so they land inside the drained range.
compositionDurationSeconds: job.duration,