Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
// fallow-ignore-file complexity code-duplication
/**
* Frame Capture Service
*
* Uses Puppeteer to capture frames from any web page implementing the
* window.__hf seek protocol. Navigates to a file server URL, waits for
* the page to expose window.__hf, then captures frames deterministically
* via Chrome's BeginFrame API or Page.captureScreenshot fallback.
*/
import {
type Browser,
type Page,
type Protocol,
type Viewport,
type ConsoleMessage,
} from "puppeteer-core";
import { existsSync, mkdirSync, writeFileSync } from "fs";
import { join } from "path";
import {
COMPOSITION_SOURCE_URL,
quantizeSeekTime,
quantizeTimeToFrame,
fpsToNumber,
resolveAuthoredTimingWindow,
type RawAuthoredTiming,
} from "@hyperframes/core";
import { DrawElementCaptureError } from "./drawElementCaptureError.js";
import { encodePng } from "../utils/alphaBlit.js";
import {
DEFAULT_SAMPLES_PER_FRAME,
MotionBlurAccumulator,
SPATIAL_TWEEN_PROPERTIES,
adaptiveSampleCount,
motionBlurProbeTimes,
motionBlurSampleTimes,
motionBlurWindowIsStatic,
probeDiffMagnitude,
resolveMotionBlurPlan,
type MotionBlurPlan,
} from "./motionBlur.js";
import {
describePageMotionBlur,
describePageMotionBlurAtEnd,
installPageMotionBlur,
} from "./pageMotionBlur.js";
// ── Extracted modules ───────────────────────────────────────────────────────
import {
acquireBrowser,
releaseBrowser,
forceReleaseBrowser,
buildChromeArgs,
resolveBrowserGpuMode,
captureWithoutWaylandDisplay,
resolveHeadlessShellPath,
compositionRequiresWebGpu,
assertWebGpuAdapterAvailable,
usesSoftwareWebGpu,
type BrowserLease,
type CaptureMode,
} from "./browserManager.js";
import {
beginFrameCapture,
ensureRenderFrameSiblings,
getCdpSession,
pageContentExceedsCaptureHeight,
pageScreenshotCapture,
initTransparentBackground,
shouldDefaultCaptureBeyondViewport,
} from "./screenshotService.js";
import {
classifyGpuRenderer,
detectGpuBackend,
injectDrawElementCanvas,
captureDrawElementFrame,
resolveDrawElementCaptureMode,
instrumentAcceleratedCanvases,
initDrawElementWorkerEncode,
cleanupDrawElementWorkerEncode,
produceDrawElementFrame,
produceDrawElementFrameBatch,
DE_CANVAS_NOT_INITIALIZED_CODE,
} from "./drawElementService.js";
import { initThreeDProjection, detectCssEffectRisk } from "./threeDProjection.js";
import { isPsnrFilterAvailable } from "../utils/psnrFilterAvailability.js";
import { DEFAULT_CONFIG, applyConcreteGpuScreenshotClamp, type EngineConfig } from "../config.js";
import type {
CaptureOptions,
CaptureVideoMetadataHint,
CaptureResult,
CaptureBufferResult,
CapturePerfSummary,
CaptureWarning,
HfSeekOptions,
SubTimelineWaitMemo,
SubTimelineWaitOutcome,
} from "../types.js";
import { cloneCaptureWarnings } from "./captureWarning.js";
import { installMediaRenderIdBridge } from "./mediaRenderIdBridge.js";
import {
createChromeMemorySampler,
type ChromeMemorySampler,
type ChromePids,
} from "./chromeMemorySampler.js";
import { sampleProcessRss } from "../utils/processRss.js";
export { isMemoryExhaustionError, isTransientBrowserError } from "./captureFailure.js";
export type { CaptureOptions, CaptureResult, CaptureBufferResult, CapturePerfSummary };
/** Called after seeking, before screenshot. Use for video frame injection or other pre-capture work.
* `heldVideoTime` (motion-blur samples only) is the output frame's time: a video on screen at
* 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. */
browserLease?: BrowserLease;
page: Page;
options: CaptureOptions;
serverUrl: string;
outputDir: string;
/** The composition served at `serverUrl` declares `data-requires-webgpu`. */
requiresWebGpu?: boolean;
/** The browser was launched to run that WebGPU on SwiftShader ({@link usesSoftwareWebGpu}). */
softwareWebGpu?: boolean;
onBeforeCapture: BeforeCaptureHook | null;
isInitialized: boolean;
/**
* Static-frame dedup (default-on; opt out with `HF_STATIC_DEDUP=false`): indices of frames byte-identical
* to their predecessor (no GSAP tween / clip cut active in either), predicted from
* window.__timelines and empirically anchor-verified. These reuse `lastFrameBuffer`
* instead of re-seeking + re-screenshotting. Undefined when disabled or ineligible.
*/
staticFrames?: Set<number>;
/** Last non-deduped frame buffer, reused for every `staticFrames` index in its run. */
lastFrameBuffer?: Buffer;
/** Absolute index represented by lastFrameBuffer; reuse requires direct adjacency. */
lastFrameAbsoluteIndex?: number;
/** Count of frames served from a reused buffer (dedup telemetry). */
staticDedupCount?: number;
/** Live Chrome memory sampler; started in initializeSession, stopped in closeCaptureSession. */
chromeMemory?: ChromeMemorySampler;
/**
* Resolved sub-frame motion-blur plan, or undefined when off. Set once by
* `resolveSessionMotionBlur` at the end of initialization, where the capture mode has
* settled, so an unsupported combination fails before the first frame rather than
* silently rendering unblurred.
*/
motionBlur?: MotionBlurPlan;
/** Frames confirmed to move only non-spatial properties (opacity, colour); set for
* adaptive motion blur. Absent from this set means "probe" — see computeStaticFrameSet. */
motionBlurNonSpatialFrames?: Set<number>;
// ── Static-dedup observability (set by armStaticDedup; surfaced via
// getCapturePerfSummary → RenderPerfSummary → the render_complete event) ──
// `armed` derives from the verified staticFrames set. Predicted count is stored
// separately because partial budget arming intentionally makes them diverge.
/** Dedup was enabled for this render (default-on; opt out with `HF_STATIC_DEDUP=false`). */
staticDedupEnabled?: boolean;
/** Original predicted-static count, before profitability or partial verification. */
staticDedupPredictedCount?: number;
/** Bounded verifier taxonomy and counters for debug/perf reporting. */
staticDedupVerification?: StaticVerificationResult;
/**
* Short machine code for WHY dedup did not arm, for a low-cardinality breakdown.
* One of: `capture_mode` | `video_injection` | `page_composite` |
* `ineligible` | `unprofitable` | `verification_failed` | `verification_budget`.
* Undefined when armed or disabled.
*/
staticDedupSkipReason?: string;
// 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).
pageReleased?: boolean;
browserReleased?: boolean;
browserConsoleBuffer: string[];
/**
* Script resources that failed to load (request failure or HTTP >= 400).
* pollSubCompositionTimelines fail-fasts on these: a comp whose timeline
* script 404'd can never register window.__timelines[id], so waiting the
* full playerReadyTimeout (45s) buys nothing (~1% of wild local renders
* were hitting that wall — a 705-render spike at the 45s setup bucket).
*/
scriptLoadFailures: string[];
/** Uncaught page errors; a timed-out timeline wait with any of these becomes a script failure. */
pageErrors: string[];
/** The first VFX chain error; its frames would lack the effect, so it stops the render. */
vfxFailure?: string;
/** Outcome of the sub-composition timeline wait: ready | timeout | script_failure. */
subTimelineWaitOutcome?: SubTimelineWaitOutcome;
/**
* Composition ids still unregistered when the timeline wait gave up. Already
* computed for the stderr warning; kept on the session so the STRUCTURED
* warning can name them too — a programmatic caller reads `warnings`, not
* our console output.
*/
pendingTimelineIds?: string[];
/** The render's shared memo when the caller passed one, else this session's own. */
subTimelineWaitMemo: SubTimelineWaitMemo;
/** Structured readiness warnings surfaced to the producer's render policy. */
warnings: CaptureWarning[];
initTelemetry?: {
initDurationMs: number;
tweenCount: number;
/** Live DOM element count at end of init; undefined when the measurement itself failed. Observational — see collectSessionInitTelemetry. */
elementCount?: number;
};
capturePerf: {
frames: number;
seekMs: number;
beforeCaptureMs: number;
screenshotMs: number;
totalMs: number;
/** Per-frame capture durations (batch frames get the batch mean). Basis for
* the warmup-robust p50 in the perf summary. */
frameMs: number[];
};
captureMode: CaptureMode;
/**
* Browser LAUNCH mode, immutable after createCaptureSession. `captureMode`
* is reassigned by initializeSession (e.g. to "drawelement"), so callers
* that need to know whether this browser actually drives BeginFrame (the
* SwiftShader liveness probe) read this field instead.
*/
launchCaptureMode: CaptureMode;
// BeginFrame state
beginFrameTimeTicks: number;
beginFrameIntervalMs: number;
beginFrameHasDamageCount: number;
beginFrameNoDamageCount: number;
beginFrameSeekPresented?: boolean;
/** Optional producer config — when set, overrides module-level env var constants. */
config?: Partial<EngineConfig>;
/** True if running on SwiftShader (detected at init). Undefined before init. */
isSwiftShader?: boolean;
/**
* Low-cardinality GPU bucket (`<backend>/<vendor>`, e.g. `d3d11/nvidia`)
* derived from the WebGL renderer at DE session init. Surfaces in
* CapturePerfSummary → render telemetry so backend-specific drawElement
* damage (Metal vs D3D11 vs GL) clusters attributably. The raw
* driver-supplied string is deliberately NOT retained — see
* classifyGpuRenderer.
*/
gpuRenderer?: string;
/** drawElementImage canvas was injected and is ready for capture. */
drawElementReady?: boolean;
/**
* Worker-encode pipeline is active for this session. Set by
* `initDrawElementOrTransparentBackground` when `enableDrawElementWorkerEncode`
* is true and capture mode resolved to "drawelement".
*/
workerEncodeEnabled?: boolean;
/**
* Frame indices that must be captured via screenshot rather than drawElement.
* Populated at init by the clip-cut boundary predictor (Lim 6): frames where
* the outgoing clip is dropped a frame before the incoming clip's paint record
* is ready → black frame. Controlled by `HF_FAST_CAPTURE_BOUNDARY_SS=false`.
* Empty/undefined when the predictor produces no frames.
*/
clipBoundaryFrames?: Set<number>;
/** Rolling drawElement frame byte-sizes (last ~60), for silent-blank-drop detection:
* drawElement intermittently returns an anomalously small (blank) frame with no
* throw; a frame far below the running median is re-captured via screenshot. */
deFrameSizes?: number[];
/** Last non-deduped encode result, reused for a static frame on the drawElement
* worker-encode path (mirrors `lastFrameBuffer` on the screenshot path). Only set
* when static-frame dedup is armed on the drawElement path. */
lastEncodeResult?: Promise<Buffer>;
/** Frame index lastEncodeResult belongs to — static-dedup reuse must verify
* every frame in (lastEncodeResultFrame, i] is predicted-static (under the
* interleaved parallel stride the "previous" produced frame is i−N, and
* reusing it for frame i is only valid when the whole gap is static). */
lastEncodeResultFrame?: number;
/** Per-render self-verification ground truth (ungated-release safety net):
* K screenshot frames captured at init BEFORE the drawElement canvas is
* injected (the only window where a page screenshot shows the live DOM, not
* the capture canvas's stale bitmap). The producer drain compares the DE
* frame at each index against these; a breach aborts the render with
* DrawElementVerificationError and the orchestrator re-renders via the
* screenshot path. */
deVerifyFrames?: Map<number, Buffer>;
/** Low-cardinality init-gate reason when drawElement routed to baseline (telemetry). */
deGateReason?: string;
/**
* Full trigger string when drawElement gated off to the screenshot fallback
* path — preserves the specific CSS effect (`filter:blur`,
* `filter:drop-shadow`, `backdrop-filter`, `clip-path`) that
* {@link deGateReason} sanitizes down to a low-cardinality bucket. Populated
* on the same fallback-gate branches as `deGateReason`; consumed by the
* `capture_fallback_profile` observability checkpoint gated behind
* `HF_PROFILE_FALLBACK_CAPTURE=true`. See
* `packages/producer/src/services/render/fallbackCaptureProfile.ts`.
*/
deFallbackTrigger?: string;
/** Wall-clock ms spent capturing self-verification ground truth at init (telemetry). */
deVerifyInitMs?: number;
/** Count of paint-record/canvas failures requiring fresh screenshot capture (telemetry). */
deNcprFallbacks?: number;
/**
* Count of drawElement frame captures that blew `HF_DE_FRAME_TIMEOUT_MS`
* because the renderer stopped scheduling after drawElementImage returned
* (PRINFRA-488). Each one aborts the drawElement attempt so the whole render
* 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
* sessions initialize before extraction) and the comp has <video> elements,
* so ground-truth screenshots would capture black video boxes. The capture
* stage completes the init via completeDeferredDrawElementInit once
* prepareCaptureSessionForReuse attaches the injector.
*/
deInitDeferred?: boolean;
}
/**
* drawElement self-verification failure — a captured DE frame diverged from its
* pre-injection screenshot ground truth (or a blank frame survived a retry).
* The orchestrator catches this and re-renders the whole job with
* forceScreenshot. Discriminant-based guard (not instanceof) so it survives
* duplicated module instances across package boundaries.
*/
/**
* Structured detail carried alongside the human-readable message — lets
* telemetry report the actual failure kind / failing dB / frame index
* instead of the orchestrator having to regex them back out of formatted
* text (a message-text dependency is exactly the failure mode this shape
* exists to close — review finding: message wording, translation, or a
* cross-module/serialized error must never be able to flip the reported
* kind). All fields but `kind` are optional: a blank-frame trip has no PSNR
* score, so `failedDb`/`verifyThresholdDb` are omitted for that throw site.
*/
export interface DrawElementVerificationDetails {
kind: "blank" | "psnr";
frameIndex?: number;
failedDb?: number;
verifyThresholdDb?: number;
}
export class DrawElementVerificationError extends Error {
readonly kind: "blank" | "psnr";
readonly frameIndex?: number;
readonly failedDb?: number;
readonly verifyThresholdDb?: number;
constructor(message: string, details: DrawElementVerificationDetails) {
super(message);
this.name = "DrawElementVerificationError";
// Discriminant property, assigned dynamically: isDrawElementVerificationError
// reads it structurally so detection survives duplicated module instances
// across package boundaries (where instanceof fails).
(this as unknown as { deVerificationFailure: boolean }).deVerificationFailure = true;
this.kind = details.kind;
this.frameIndex = details.frameIndex;
this.failedDb = details.failedDb;
this.verifyThresholdDb = details.verifyThresholdDb;
}
}
export function isDrawElementVerificationError(err: unknown): boolean {
// Walk the cause chain — the producer wraps capture errors (CaptureStageError).
let e: unknown = err;
for (let depth = 0; depth < 5 && typeof e === "object" && e !== null; depth++) {
if ((e as { deVerificationFailure?: boolean }).deVerificationFailure === true) return true;
e = (e as { cause?: unknown }).cause;
}
return false;
}
/**
* Extracts the structured details off a (possibly cause-wrapped) verification
* error — same chain-walk as isDrawElementVerificationError, structural
* (not instanceof) for the same duplicated-module-instance reason. Returns
* undefined when the error isn't a verification failure at all.
*/
export function getDrawElementVerificationDetails(
err: unknown,
): DrawElementVerificationDetails | undefined {
let e: unknown = err;
for (let depth = 0; depth < 5 && typeof e === "object" && e !== null; depth++) {
const rec = e as { deVerificationFailure?: boolean } & Partial<DrawElementVerificationDetails>;
if (rec.deVerificationFailure === true) {
// Every construction path sets `kind` (required on the constructor), so
// this only defends against a malformed cross-module-instance shape —
// treat anything other than exactly "blank" as "psnr", the same
// fallback polarity the old message regex had, but driven by a
// structural field instead of parsing text.
const details: DrawElementVerificationDetails = {
kind: rec.kind === "blank" ? "blank" : "psnr",
};
if (typeof rec.frameIndex === "number") details.frameIndex = rec.frameIndex;
if (typeof rec.failedDb === "number") details.failedDb = rec.failedDb;
if (typeof rec.verifyThresholdDb === "number")
details.verifyThresholdDb = rec.verifyThresholdDb;
return details;
}
e = (e as { cause?: unknown }).cause;
}
return undefined;
}
/** Wait for inline CSS background images introduced by the latest seek. */
export async function decodeDynamicCssBackgroundImages(page: Page): Promise<void> {
await page.evaluate(async () => {
const root = globalThis as typeof globalThis & {
__hf_css_background_decoded?: Set<string>;
__hfDecodeDynamicCssBackgroundImages?: () => Promise<void>;
};
const decode = (root.__hfDecodeDynamicCssBackgroundImages ??= async () => {
const decoded = (root.__hf_css_background_decoded ??= new Set<string>());
const urls: string[] = [];
const parseBackgroundUrls = (value: string): string[] => {
const found: string[] = [];
let cursor = 0;
while (cursor < value.length) {
const start = value.indexOf("url(", cursor);
if (start < 0) break;
let index = start + 4;
while (index < value.length && /\s/.test(value[index] ?? "")) index += 1;
const quote = value[index] === '"' || value[index] === "'" ? value[index] : null;
if (quote) index += 1;
const contentStart = index;
let contentEnd = -1;
while (index < value.length) {
const char = value[index];
if (char === "\\") {
index = Math.min(index + 2, value.length);
continue;
}
if ((quote && char === quote) || (!quote && char === ")")) {
contentEnd = index;
break;
}
index += 1;
}
if (contentEnd < 0) break;
if (quote) {
index += 1;
while (index < value.length && /\s/.test(value[index] ?? "")) index += 1;
if (value[index] !== ")") {
cursor = index;
continue;
}
}
const url = value.slice(contentStart, contentEnd).trim();
if (url) found.push(url);
cursor = index + 1;
}
return found;
};
for (const element of document.querySelectorAll<HTMLElement>('[style*="background"]')) {
const backgroundImage = element.style.backgroundImage;
if (!backgroundImage || backgroundImage === "none") continue;
for (const url of parseBackgroundUrls(backgroundImage)) {
if (!decoded.has(url)) urls.push(url);
}
}
await Promise.all(
[...new Set(urls)].map(async (url) => {
const image = new Image();
image.src = url;
try {
await image.decode();
decoded.add(url);
} catch {
// Keep existing capture behavior for missing assets; request diagnostics report them.
}
}),
);
});
await decode();
});
}
// Circular buffer for browser console messages dumped on render failure diagnostics.
// Complex compositions produce 100+ messages; 50 was too small to capture relevant errors.
const BROWSER_CONSOLE_BUFFER_SIZE = 200;
const CAPTURE_SESSION_CLOSE_TIMEOUT_MS = 5_000;
function appendBrowserDiagnostic(session: CaptureSession, text: string): void {
session.browserConsoleBuffer.push(text);
if (session.browserConsoleBuffer.length > BROWSER_CONSOLE_BUFFER_SIZE) {
session.browserConsoleBuffer.shift();
}
}
async function collectSessionInitTelemetry(
page: Page,
initStart: number,
): Promise<{ initDurationMs: number; tweenCount: number; elementCount?: number }> {
const initDurationMs = Date.now() - initStart;
// Live DOM size, measured once the init sequence has completed so
// script-generated elements are present. This is the SAME quantity the
// short-comp routing gate wants, but measured here it is observational
// only — capture has already started, so it is far too late to route on.
// Its job is coverage: the routing gate can only read a live count on the
// ~17% of renders that get a probe session, which leaves the fleet
// element-count distribution unknowable for the rest (and hides exactly
// the dangerous shape — small source markup, huge runtime DOM).
//
// Coverage caveat, since the "every render reaches this" claim is easy to
// over-read: every render that SURVIVES TO END OF INIT reaches it. Renders
// that die in browser launch, navigation, or OOM before init completes
// never emit — and on the huge-DOM tail this field exists to characterize,
// those are disproportionately the ones that fail early. The distribution
// is therefore survivor-biased toward smaller comps; treat the tail as a
// lower bound (review finding).
// Deliberately `undefined` (not 0) when the measurement fails, breaking
// from the tweenCount fallback pattern directly above. A page.evaluate
// crash during init is most likely on exactly the huge-DOM compositions
// this field exists to observe, and a 0 there is indistinguishable from a
// legitimately empty comp — the fleet p50/p99 would silently absorb both
// (review finding). Mirrors the live/static provenance split the routing
// resolver already uses: "not measured" must not read as "measured small".
// getElementsByTagName over querySelectorAll: a live HTMLCollection's
// length avoids materializing a 40k-node static NodeList on the tail this
// is here to characterize.
let elementCount: number | undefined;
try {
elementCount = await page.evaluate(() => document.getElementsByTagName("*").length);
} catch {
elementCount = undefined;
}
let tweenCount = 0;
try {
tweenCount = await page.evaluate(() => {
const timelines =
(window as unknown as { __timelines?: Record<string, unknown> }).__timelines || {};
const seen = new Set<object>();
let count = 0;
for (const timeline of Object.values(timelines)) {
const maybeTimeline = timeline as { getChildren?: unknown };
if (typeof maybeTimeline?.getChildren !== "function") continue;
const children = maybeTimeline.getChildren(true, true, false) as unknown[];
for (const child of children) {
if (child && typeof child === "object" && !seen.has(child)) {
seen.add(child);
count++;
}
}
}
return count;
});
} catch {
tweenCount = 0;
}
return { initDurationMs, tweenCount, elementCount };
}
async function recordSessionInitTelemetry(
session: CaptureSession,
initStart: number,
): Promise<void> {
const telemetry = await collectSessionInitTelemetry(session.page, initStart);
session.initTelemetry = telemetry;
appendBrowserDiagnostic(
session,
`[FrameCapture:INIT] complete initDurationMs=${telemetry.initDurationMs} tweenCount=${telemetry.tweenCount}` +
// Omitted rather than zeroed when unmeasured, so the parser reports
// absent instead of inventing an empty DOM.
(telemetry.elementCount === undefined ? "" : ` elementCount=${telemetry.elementCount}`),
);
}
export function sanitizeDiagnosticUrl(input: string): string {
if (!input) return "(empty)";
if (input.startsWith("data:")) return "data:<redacted>";
if (input.startsWith("blob:")) return "blob:<redacted>";
if (input.startsWith("/")) {
try {
const url = new URL(input, "http://hyperframes.local");
return url.pathname;
} catch {
return input;
}
}
try {
const url = new URL(input);
url.username = "";
url.password = "";
url.search = "";
url.hash = "";
return url.toString();
} catch {
return input;
}
}
export function formatNavigationFailureDiagnostic(input: {
captureMode: CaptureMode;
url: string;
timeoutMs: number;
elapsedMs: number;
error: unknown;
}): string {
const message = input.error instanceof Error ? input.error.message : String(input.error);
return (
`[FrameCapture:ERROR] page.goto failed ` +
`mode=${input.captureMode} timeoutMs=${input.timeoutMs} elapsedMs=${input.elapsedMs} ` +
`url=${sanitizeDiagnosticUrl(input.url)} error=${message}`
);
}
export function formatNavigationStartDiagnostic(input: {
captureMode: CaptureMode;
url: string;
timeoutMs: number;
}): string {
return (
`[FrameCapture:NAV] page.goto start ` +
`mode=${input.captureMode} timeoutMs=${input.timeoutMs} ` +
`url=${sanitizeDiagnosticUrl(input.url)}`
);
}
export function formatRequestFailureDiagnostic(input: {
method: string;
resourceType: string;
url: string;
failureText: string;
}): string {
return (
`[Browser:REQUESTFAILED] ${input.method} ${sanitizeDiagnosticUrl(input.url)} ` +
`resource=${input.resourceType} error=${input.failureText}`
);
}
/**
* Chromium reports media loads that it intentionally cancels during probing as
* request failures. They are expected when the probe discovers or seeks local
* audio/video and do not indicate a missing asset.
*/
export function shouldIgnoreRequestFailureDiagnostic(input: {
resourceType: string;
url: string;
failureText: string;
}): boolean {
if (input.failureText !== "net::ERR_ABORTED") return false;
if (input.resourceType === "media") return true;
try {
return /\.(?:aac|flac|m4a|mp3|mp4|mov|oga|ogg|ogv|wav|webm)$/i.test(
new URL(input.url).pathname,
);
} catch {
return false;
}
}
export function formatHttpErrorDiagnostic(input: {
method: string;
resourceType: string;
url: string;
status: number;
statusText: string;
}): string {
const statusText = input.statusText ? ` ${input.statusText}` : "";
return (
`[Browser:HTTP${input.status}] ${input.method} ${sanitizeDiagnosticUrl(input.url)} ` +
`resource=${input.resourceType}${statusText}`
);
}
/**
* Fixed warmup-loop iteration count used when `CaptureOptions.lockWarmupTicks`
* is `true`. Picked to roughly match the median tick count observed by the
* unlocked wall-clock loop during a typical 2s page load at 30fps — so
* `beginFrameTimeTicks` lands in a similar range regardless of host speed.
*/
export const LOCKED_WARMUP_TICKS = 60;
/**
* Internal driver for the BeginFrame warmup loop.
*
* - Unlocked: exits as soon as `state.running` flips to `false`. Tick count
* varies with wall-clock page-load time.
* - Locked: ignores `state.running` entirely and exits once it has driven
* exactly `LOCKED_WARMUP_TICKS` iterations. Caller awaits this promise
* after page-readiness so `session.beginFrameTimeTicks` is identical
* across hosts.
* - `tick` errors are swallowed (Chrome's `beginFrame` is best-effort
* during page load — the page hasn't installed CDP listeners yet). When
* `tick` throws, the iteration count does NOT advance.
*
* `intervalMs` is the BeginFrame interval (≈33ms at 30fps).
*
* `frameTimeTicks` is derived as `ticks * intervalMs` and exposed via
* {@link warmupFrameTimeTicks} — not stored on the state, to keep `ticks`
* the single source of truth.
*/
export interface WarmupTickState {
running: boolean;
ticks: number;
/** Set when session init fails: stops the loop in either mode, since a closed page fails every tick. */
cancelled?: boolean;
}
export interface WarmupTickOptions {
intervalMs: number;
lockWarmupTicks: boolean;
tick: (frameTimeTicks: number, intervalMs: number) => Promise<void>;
/** Injectable so tests can advance "time" without real setTimeout. */
sleep?: (ms: number) => Promise<void>;
}
const realSleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
/**
* Derive the current simulated frame time from a warmup state. Single source
* of truth so tests and callers stay in sync.
*/
export function warmupFrameTimeTicks(state: WarmupTickState, intervalMs: number): number {
return state.ticks * intervalMs;
}
const BEGIN_FRAME_CAPTURE_HEADROOM_INTERVALS = 10;
const BEGIN_FRAME_COMMIT_LEAD_INTERVALS = 6;
const BEGIN_FRAME_PROBE_LEAD_INTERVALS = 5;
export interface BeginFrameTimelineTicks {
capture: number;
commit: number;
probe: number;
}
export interface PreparedBeginFrameTimeline {
commitParams: {
frameTimeTicks: number;
interval: number;
noDisplayUpdates: false;
};
timeline: BeginFrameTimelineTicks;
}
/**
* Place frame zero after the warmup clock while retaining capture-rate-sized
* headroom for the visual commit and liveness probe ticks that precede it.
*
* The warmup and capture intervals can differ (warmup currently runs at a
* fixed 33ms). Basing both clocks on the capture interval would move time
* backwards whenever the output frame rate is faster than the warmup rate.
*/
export function deriveBeginFrameTimeTicks(
state: WarmupTickState,
warmupIntervalMs: number,
captureIntervalMs: number,
): number {
const legacyCaptureTimeTicks =
(state.ticks + BEGIN_FRAME_CAPTURE_HEADROOM_INTERVALS) * captureIntervalMs;
const legacyCommitTimeTicks = deriveBeginFrameCommitTimeTicks(
legacyCaptureTimeTicks,
captureIntervalMs,
);
const lastWarmupTimeTicks = Math.max(0, state.ticks - 1) * warmupIntervalMs;
if (legacyCommitTimeTicks > lastWarmupTimeTicks) return legacyCaptureTimeTicks;
const monotonicCaptureTimeTicks =
warmupFrameTimeTicks(state, warmupIntervalMs) +
BEGIN_FRAME_CAPTURE_HEADROOM_INTERVALS * captureIntervalMs;
return monotonicCaptureTimeTicks;
}
function deriveBeginFrameCommitTimeTicks(
captureTimeTicks: number,
captureIntervalMs: number,
): number {
return captureTimeTicks - BEGIN_FRAME_COMMIT_LEAD_INTERVALS * captureIntervalMs;
}
export function deriveBeginFrameProbeTimeTicks(
captureTimeTicks: number,
captureIntervalMs: number,
): number {
return Math.max(0, captureTimeTicks - BEGIN_FRAME_PROBE_LEAD_INTERVALS * captureIntervalMs);
}
export function deriveBeginFrameTimelineTicks(
state: WarmupTickState,
warmupIntervalMs: number,
captureIntervalMs: number,
): BeginFrameTimelineTicks {
const capture = deriveBeginFrameTimeTicks(state, warmupIntervalMs, captureIntervalMs);
return {
capture,
commit: deriveBeginFrameCommitTimeTicks(capture, captureIntervalMs),
probe: deriveBeginFrameProbeTimeTicks(capture, captureIntervalMs),
};
}
export function prepareBeginFrameTimeline(
session: Pick<CaptureSession, "beginFrameIntervalMs" | "beginFrameTimeTicks">,
state: WarmupTickState,
warmupIntervalMs: number,
): PreparedBeginFrameTimeline {
const timeline = deriveBeginFrameTimelineTicks(
state,
warmupIntervalMs,
session.beginFrameIntervalMs,
);
session.beginFrameTimeTicks = timeline.capture;
return {
timeline,
commitParams: {
frameTimeTicks: timeline.commit,
interval: session.beginFrameIntervalMs,
noDisplayUpdates: false,
},
};
}
/** Runs BeginFrame session setup; a failure stops the warm-up loop, which would otherwise tick forever. */
export async function cancelWarmupOnError<T>(
state: WarmupTickState,
setup: () => Promise<T>,
): Promise<T> {
try {
return await setup();
} catch (error) {
state.cancelled = true;
throw error;
}
}
export async function driveWarmupTicks(
options: WarmupTickOptions,
state: WarmupTickState,
): Promise<void> {
const sleep = options.sleep ?? realSleep;
while (!state.cancelled) {
if (options.lockWarmupTicks) {
// Locked mode exits on the iteration count, ignoring `state.running` —
// the caller flips `running=false` after page-readiness but we keep
// ticking until LOCKED_WARMUP_TICKS so the count is host-independent.
if (state.ticks >= LOCKED_WARMUP_TICKS) return;
} else {
// Unlocked mode is wall-clock-bounded.
if (!state.running) return;
}
try {
await options.tick(state.ticks * options.intervalMs, options.intervalMs);
state.ticks += 1;
} catch {
// Page not ready yet; keep spinning.
}
await sleep(options.intervalMs);
}
}
export function resolveCaptureSessionOptions(
options: CaptureOptions,
browserVersion: string,
platform: NodeJS.Platform = process.platform,
): CaptureOptions {
return {
...options,
captureBeyondViewport:
options.captureBeyondViewport ?? shouldDefaultCaptureBeyondViewport(browserVersion, platform),
};
}
async function waitForCloseWithTimeout(promise: Promise<unknown>): Promise<boolean> {
let timedOut = false;
let timer: ReturnType<typeof setTimeout> | undefined;
await Promise.race([
promise.then(
() => undefined,
() => undefined,
),
new Promise<void>((resolve) => {
timer = setTimeout(() => {
timedOut = true;
resolve();
}, CAPTURE_SESSION_CLOSE_TIMEOUT_MS);
}),
]);
if (timer) clearTimeout(timer);
return !timedOut;
}
/**
* Post-readiness capture-surface init, shared by the screenshot and BeginFrame
* init paths (called after the page is fully ready). When `useDrawElement` is
* set, detect SwiftShader and route: transparent+SwiftShader falls back to
* screenshot capture (the drawElement transparent path is broken on SwiftShader),
* everything else injects the drawElement canvas and switches to "drawelement"
* mode. Otherwise, for PNG output, force a transparent page background so the
* screenshots carry a real alpha channel (Chrome resets the override on every
* navigation, so this must run after page load).
*
* drawElement is also skipped when scaling (deviceScaleFactor other than 1):
* `drawElementImage` reads the canvas at CSS pixels and has no equivalent of
* `Page.captureScreenshot`'s clip+scale, so it would silently capture at 1x and
* drop the requested supersample. Such renders fall through to the screenshot
* path (preMode already forces "screenshot" for DPR other than 1).
*/
async function initDrawElementOrTransparentBackground(
session: CaptureSession,
page: Page,
logInitPhase: (phase: string) => void,
): Promise<void> {
const supersampling = (session.options.deviceScaleFactor ?? 1) !== 1;
// forceScreenshot is an explicit routing decision made upstream (render-mode
// compat hints like raw requestAnimationFrame, alpha formats, low-memory) —
// drawElement must not override it. Concretely: an rAF-compat comp on
// SwiftShader gets a screenshot-launched (free-running) browser, where
// drawElement runs in paint-event-sync mode; SwiftShader never refreshes a
// 2d canvas bitmap inside a cached paint record there, so every canvas
// captures frozen-blank (raf-ball rendered fully black). On a GPU the same
// path happens to work, but the hint asked for screenshot — honor it.
const forceScreenshot = session.config?.forceScreenshot ?? false;
// DIAGNOSTIC ONLY — HF_FORCE_DRAWELEMENT=1 forces the drawElement path,
// bypassing every compile/init gate AND the compatibility hints (it overrides
// forceScreenshot). Exists for upstream-Chromium repro work (isolating gate
// behavior from drawElementImage behavior, e.g. the crbug 521861819 149-vs-151
// comparison) and for R&D on gated effect classes. Renders under this flag may
// be DAMAGED by design — the gates it skips exist because measured damage
// (blur/backdrop ~18-49dB, 3D backface, SwiftShader sub-layer drops) is real.
// Never set it in production; it is intentionally not documented in user-facing
// help, and the safety-net blank guard also stands down under it so diagnostic
// frames arrive unmodified.
const forceDE = process.env.HF_FORCE_DRAWELEMENT === "1";
const useDrawElement =
((session.config?.useDrawElement ?? false) || forceDE) &&
!supersampling &&
(!forceScreenshot || forceDE);
if ((session.config?.useDrawElement ?? false) && supersampling) {
session.deGateReason = "supersampling";
session.deFallbackTrigger = "supersampling";
console.log(
"[engine] --experimental-fast-capture disabled for this render: drawElementImage " +
"ignores deviceScaleFactor, so scaled (DPR other than 1) output uses screenshot capture.",
);
}
if ((session.config?.useDrawElement ?? false) && !supersampling && forceScreenshot) {
session.deGateReason = "render_mode_hint";
session.deFallbackTrigger = "render_mode_hint";
console.log(
"[engine] fast capture falls back to screenshot: render-mode compatibility " +
"hint forced screenshot capture (e.g. raw requestAnimationFrame composition).",
);
}
if (useDrawElement) {
const gpuBackend = await detectGpuBackend(page);
session.isSwiftShader = gpuBackend.isSwiftShader;
session.gpuRenderer = classifyGpuRenderer(gpuBackend.renderer);
const transparent = session.options.format === "png";
async function routeToFallback(): Promise<void> {
session.captureMode = session.launchCaptureMode;
if (transparent) {
await initTransparentBackground(session.page);
}
// Static-frame dedup is capture-mode-independent (the serial path reuses
// lastFrameBuffer regardless of how the frame was captured) and lossless
// (anchor-verified). A comp only reaches THIS fallback with useDrawElement=true
// AND forceScreenshot=false — i.e. it is deterministic: raw-rAF / iframe /
// htmlInCanvas comps are forced to screenshot upstream (forceScreenshot=true) and
// never enter this block, so they never arm dedup. The comps that DO fall back here
// (blur / backdrop / 3D / at-risk) carry only a compositor
// EFFECT drawElement can't paint, not nondeterminism, so their predicted-static set
// is sound. Verification seeks via Page.captureScreenshot, which hangs on a
// BeginFrame-launched browser — gate on the launch mode (macOS fast-capture launches
// screenshot-mode; Linux/Docker launches beginframe and is skipped).
if (session.launchCaptureMode === "screenshot") {
await armStaticDedup(session, page, logInitPhase);
}
}
// Capability gate: `canvas.drawElementImage` is an unlaunched Blink feature
// that only exists on recent Chrome builds (150+ behind a flag); it is absent
// from Stable and from most system Chrome installs. The
// `--enable-features=CanvasDrawElement` flag no-ops silently on a build that
// doesn't implement it, so without this probe the first drawElementImage()
// call throws `TypeError: ... is not a function` deep inside the capture
// loop and takes the whole render down instead of falling back (HF#2060).
// Cheap (no paint-wait) and must run before any other drawElement work.
// Not gated by forceDE (HF_FORCE_DRAWELEMENT, an R&D knob that bypasses the
// quality gates below to measure raw damage) — there's no "forced but
// degraded" mode for a method that doesn't exist, only a crash, so this
// always routes to the fallback instead.
const supportsDrawElement = await page.evaluate(() => {
const c = document.createElement("canvas");
const ctx = c.getContext("2d");
return (
typeof (ctx as unknown as { drawElementImage?: unknown })?.drawElementImage === "function"
);
});
if (!supportsDrawElement) {
session.deGateReason = "unsupported_chrome";
session.deFallbackTrigger = "unsupported_chrome";
console.log(
`[engine] fast capture falls back to ${session.launchCaptureMode} capture: ` +
"this Chrome build does not implement canvas.drawElementImage (Dev/Canary-only " +
"feature); run `hyperframes browser ensure --force` to fetch a supported " +
"build, or set HYPERFRAMES_BROWSER_PATH to one.",
);
await routeToFallback();
return;
}
// ffmpeg-psnr preflight: the disk-sample self-verify path
// (parallelCoordinator's psnrForDiskSample → psnrDb) shells to
// `ffmpeg -lavfi psnr`. When the resident ffmpeg is missing or was built
// without libpostproc, every per-sample compare throws and
// psnrForDiskSample swallows the error — the safety net silently fails
// open. Force-fallback to the reliable capture path so the safety net
// for drawElement isn't the one thing standing between a compositor bug
// and a shipped video. Skipped under HF_FORCE_DRAWELEMENT (matches the
// policy of every other gate below).
if (!forceDE && !(await isPsnrFilterAvailable())) {
session.deGateReason = "ffmpeg_no_psnr_filter";
session.deFallbackTrigger = "ffmpeg_no_psnr_filter";
console.warn(
`[engine] fast capture falls back to ${session.launchCaptureMode} capture: ` +
"host ffmpeg is missing or was built without the `psnr` filter " +
"(libpostproc), so drawElement self-verification cannot run. Install " +
"an ffmpeg build that includes libpostproc (or set HYPERFRAMES_FFMPEG_PATH " +
"to one) to re-enable fast capture.",
);
await routeToFallback();
return;
}
// SwiftShader gate: drawElement's only advantage is skipping the GPU→CPU
// screenshot-readback IPC. On a software rasterizer (Docker/CI, no GPU) both
// paths block on identical software raster, so drawElement is parity-or-slower
// — route to the platform baseline.
//
// Two gates were REMOVED here once Chrome 151 fixed crbug 521861819
// (drawElementImage dropped compositor-promoted opacity layers mid-fade):
// - the <video> gate (a proxy for the word-by-word caption opacity pattern,
// Lim 2), and
// - the stacked-fade gate (>=2 overlapping viewport-scale opacity-fade targets).
// Both reproduced on Chrome <=150 (video+caption-fade ~12 dB; stacked fade
// 24.5 dB) and both render correctly on 151 (verified: video+nested-fade repro
// PSNR=inf; efb59c5b 24.5→47.4 dB, 0 damaged frames). 151 is the pinned floor.
const mode = resolveDrawElementCaptureMode(session.isSwiftShader, transparent);
if (mode === "screenshot") {
session.deGateReason = "swiftshader";
session.deFallbackTrigger = "swiftshader";
// Fall back to the browser's LAUNCH mode, not unconditionally to
// "screenshot": on a BeginFrame-launched browser (Linux fast capture)
// Page.captureScreenshot hangs for the full protocol timeout, while
// beginFrameCapture is the platform's normal baseline path.
console.log(
`[engine] fast capture falls back to ${session.launchCaptureMode} capture: ` +
"SwiftShader (software rasterizer, no GPU egress to skip, drawElement is " +
"parity-or-slower; see fast-capture-limitations.md)",
);
await routeToFallback();
} else {
// CSS-effect gate: backdrop-filter samples the compositor backdrop and
// filter:blur/drop-shadow render differently through the paint-record
// path — drawElementImage can't reproduce either, producing 18–49 dB
// damaged frames (community eval). Fall back to the platform baseline.
// HF_FAST_CAPTURE_CSSFX=true bypasses for R&D.
if (!forceDE && process.env.HF_FAST_CAPTURE_CSSFX !== "true") {
const cssFx = await detectCssEffectRisk(page);
if (cssFx) {
session.deGateReason = `css_effect:${(cssFx.split(":")[0] ?? "").replace(/[^a-z-]/gi, "")}`;
// Full specific effect from `detectCssEffectRisk` (e.g. "filter:blur",
// "mix-blend-mode", "webgl-context") — `deGateReason` keeps its
// low-cardinality prefix, `deFallbackTrigger` the full value.
session.deFallbackTrigger = cssFx;
console.log(
`[engine] fast capture falls back to ${session.launchCaptureMode} capture: ` +
`${cssFx} detected (drawElementImage cannot reproduce it; see fast-capture-limitations.md)`,
);
await routeToFallback();
return;
}
}
// Lim 7: timeline-interval at-risk predictor. Walk window.__timelines and
// find tweens animating compositor-incompatible props (opacity, filter,
// blend-mode, 3D transform, clip-path, mask). drawElementImage drops these
// mid-animation (crbug 521861819 et al), and whether it drops a given one
// cannot be told reliably without rendering (jump-seek != sequential render,
// proven 2026-06-16) nor from geometry (size is a proxy, not the mechanism).
// The only deterministic + reliable route to 0 damage is to gate on the
// PRESENCE of any such tween — a pure fact of the declared timeline, the same
// every run. Conservative by design: comps whose risky tweens drawElement
// would have handled also fall back, but correctness is never at risk and the
// fast path stays open for static + plain-2D-transform comps (x/y/scale are
// NOT in the at-risk set). Tune the gate's frame-fraction floor with
// HF_FAST_CAPTURE_INTERVAL_FRACTION (default 0 = any at-risk frame gates).
// Must run BEFORE canvas injection so a whole-comp fallback doesn't leave the
// drawElement canvas wrapping the composition root. Disable with
// HF_FAST_CAPTURE_INTERVAL_SS=false.
if (!forceDE && process.env.HF_FAST_CAPTURE_INTERVAL_SS !== "false") {
const fps = fpsToNumber(session.options.fps);
const { frames: atRisk, totalFrames } = await computeTimelineAtRiskFrames(page, fps);
const atRiskFraction = atRisk.size / totalFrames;
const fractionFloor = Number(process.env.HF_FAST_CAPTURE_INTERVAL_FRACTION ?? "0");
logInitPhase(
`timeline at-risk predictor: ${atRisk.size}/${totalFrames} frames (${Math.round(atRiskFraction * 100)}%)`,
);
if (atRisk.size > 0 && atRiskFraction > fractionFloor) {
session.deGateReason = "at_risk_timeline";
session.deFallbackTrigger = "at_risk_timeline";
console.log(
`[engine] fast capture falls back to ${session.launchCaptureMode} capture: ` +
`${atRisk.size}/${totalFrames} frames animate a compositor-incompatible prop ` +
`(blend/3D/clip/mask); drawElementImage drops these mid-animation ` +
`(deterministic timeline gate; see fast-capture-limitations.md Lim 7)`,
);
await routeToFallback();
return;
}
}
// Rewrite CSS 3D contexts into WebGL-projected canvases BEFORE the
// layoutsubtree canvas goes in (rects are measured in normal layout).
// drawElementImage cannot paint 3D rendering contexts — see
// threeDProjection.ts. No-op for compositions without 3D content.
const threeD = await initThreeDProjection(page);
if (!forceDE && !threeD.ok) {
session.deGateReason = "3d_init_failed";
session.deFallbackTrigger = "3d_init_failed";
console.log(
`[engine] fast capture falls back to ${session.launchCaptureMode} capture: ` +
`3D projection init failed (${threeD.reason ?? "unknown"})`,
);
await routeToFallback();
return;
}
if (threeD.groups > 0) {
logInitPhase(
`3D projection active: ${threeD.groups} context(s), ${threeD.quads} quad(s), ` +
`${threeD.selfQuads ?? 0} self-quad el(s), ${threeD.stubTargets ?? 0} stub target(s)`,
);
}
// Task B: arm static-frame dedup here — drawElement is confirmed (all gates
// 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);
// 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
// injected they can never be retaken. The capture stage completes the
// init after prepareCaptureSessionForReuse attaches the injector.
if (!session.onBeforeCapture && !forceDE) {
const hasVideos = await page.evaluate(() => document.querySelector("video") !== null);
if (hasVideos) {
session.deInitDeferred = true;
logInitPhase("drawElement init deferred: video comp awaiting frame injector");
return;
}
}
await finalizeDrawElementInit(session, page, logInitPhase, { transparent, forceDE });
}
} else if (session.options.format === "png") {
await initTransparentBackground(session.page);
}
}
/**
* The tail of drawElement init: self-verification ground truth (pre-injection),
* canvas injection, capture-mode flip, clip-boundary predictor, worker-encode.
* Runs inline when the session already has its video-frame injector (or the
* comp has no videos); runs deferred via completeDeferredDrawElementInit for
* probe-initialized video comps.
*/
async function finalizeDrawElementInit(
session: CaptureSession,
page: Page,
logInitPhase: (phase: string) => void,
opts: { transparent: boolean; forceDE: boolean },
): Promise<void> {
const { transparent, forceDE } = opts;
// Install the page-local decoder before batch drawElement capture begins;
// the batch loop re-runs it after every in-page seek.
await decodeDynamicCssBackgroundImages(page);
// Self-verification ground truth: must run pre-injection — after the canvas
// wraps the root, a page screenshot shows the canvas's last-drawn bitmap,
// not the live DOM (see the Lim 6 boundary-screenshot note).
{
const verifyStart = Date.now();
await captureDeVerificationFrames(session, page, logInitPhase);
session.deVerifyInitMs = Date.now() - verifyStart;
}
await injectDrawElementCanvas(page, session.options.width, session.options.height);
if (transparent) {
await initTransparentBackground(session.page);
}
session.captureMode = "drawelement";
session.drawElementReady = true;
logInitPhase("drawElement canvas injected");
// Lim 6: clip-cut boundary frames — screenshot these instead of drawElement.
if (process.env.HF_FAST_CAPTURE_BOUNDARY_SS !== "false" && !forceDE) {
const fps = fpsToNumber(session.options.fps);
const boundaryFrames = await computeClipBoundaryFrames(page, fps);
if (boundaryFrames.size > 0) {
session.clipBoundaryFrames = boundaryFrames;
logInitPhase(`screenshot fallback: ${boundaryFrames.size} clip-boundary frame(s)`);
}
}
// Worker-encode pipeline: macOS hardware GPU path only (syncToPaintEvent=true,
// beginFrameTimeTicks=0). Skip for BeginFrame (Linux/Docker) and transparent
// (PNG) output — those use the existing synchronous path unchanged.
const workerEncodeEnabled =
(session.config?.enableDrawElementWorkerEncode ?? false) &&
!transparent &&
session.beginFrameTimeTicks === 0;
if (workerEncodeEnabled) {
await initDrawElementWorkerEncode(page);
session.workerEncodeEnabled = true;
logInitPhase("drawElement worker encode initialized");
}
}
/**
* Complete a deferred drawElement init (see CaptureSession.deInitDeferred).
* Call after prepareCaptureSessionForReuse has attached the video-frame
* injector; no-op when the session is not deferred or still has no injector.
*/
export async function completeDeferredDrawElementInit(session: CaptureSession): Promise<void> {
if (!session.deInitDeferred || !session.onBeforeCapture) return;
const page = session.page;
const logInitPhase = (phase: string) =>
console.log(`[initSession:${session.captureMode}] ${phase} (deferred drawElement init)`);
await finalizeDrawElementInit(session, page, logInitPhase, {
transparent: session.options.format === "png",
forceDE: process.env.HF_FORCE_DRAWELEMENT === "1",
});
session.deInitDeferred = false;
}
// fallow-ignore-next-line unit-size
export async function createCaptureSession(
serverUrl: string,
outputDir: string,
options: CaptureOptions,
onBeforeCapture: BeforeCaptureHook | null = null,
config?: Partial<EngineConfig>,
): Promise<CaptureSession> {
if (!existsSync(outputDir)) mkdirSync(outputDir, { recursive: true });
// Determine capture mode before building args — BeginFrame flags only apply on Linux.
// BeginFrame's compositor does not preserve alpha; callers that pass
// `options.format === "png"` for transparent capture should also set
// `config.forceScreenshot = true` (the producer's renderOrchestrator does this
// automatically when `RenderConfig.format` is an alpha-capable value).
// Exception: `useDrawElement=true` with png self-manages the screenshot-browser
// requirement (both the SwiftShader fallback and the GPU transparent path need
// a screenshot-launched browser — the SwiftShader path calls Page.captureScreenshot
// which hangs on a BeginFrame browser, and the GPU path doesn't need BeginFrame
// because the compositor runs freely on a screenshot-launched browser).
const headlessShell = resolveHeadlessShellPath(config);
const isLinux = process.platform === "linux";
const forceScreenshot = config?.forceScreenshot ?? DEFAULT_CONFIG.forceScreenshot;
const useDrawElement = config?.useDrawElement ?? false;
const drawElementTransparent = useDrawElement && options.format === "png";
// drawElement and page-side shader compositing are mutually incompatible
// capture strategies: drawElement reads the composition root's paint records
// directly and skips the prepare→micro-screenshot→resolve protocol (the
// micro-screenshot would also hang on an opaque/beginframe-launched browser).
// `resolveConfig` forces page-side compositing off whenever useDrawElement is
// set, so this only trips for a direct caller that bypassed resolveConfig and
// passed both flags — warn once and treat page-side as disabled.
if (
useDrawElement &&
(config?.enablePageSideCompositing ?? DEFAULT_CONFIG.enablePageSideCompositing)
) {
console.warn(
"[engine] useDrawElement is incompatible with page-side shader compositing, " +
"ignoring enablePageSideCompositing for this render. Prefer resolveConfig, " +
"which disables page-side compositing automatically for fast-capture renders.",
);
}
// BeginFrame's screenshot does not honor a viewport `deviceScaleFactor`
// (the captured surface is sized by the OS window in CSS pixels regardless
// of `Emulation.setDeviceMetricsOverride`'s DPR). When supersampling we
// need explicit clip+scale on `Page.captureScreenshot`, so fall back to
// the screenshot path for any DPR other than 1.
const supersampling = (options.deviceScaleFactor ?? 1) !== 1;
const requestedGpuMode = config?.browserGpuMode ?? DEFAULT_CONFIG.browserGpuMode;
const resolvedGpuMode = await resolveBrowserGpuMode(requestedGpuMode, {
chromePath: headlessShell ?? undefined,
browserTimeout: config?.browserTimeout,
});
// Apply the software-GPU→screenshot invariant at the concrete-resolved
// point too — `resolveConfig` can only see the pre-resolve `browserGpuMode`
// string, so `"auto"` that probes to software would otherwise slip through
// and launch BeginFrame + SwiftShader (the exact combination the invariant
// is meant to prevent). Both env and programmatic opt-outs preserved via
// `applyConcreteGpuScreenshotClamp` (the programmatic one carried on the
// config as `forceScreenshotExplicitlyOptedOut`, since at this point the
// boolean `forceScreenshot === false` is otherwise ambiguous between
// default and explicit opt-out).
const effectiveForceScreenshot = applyConcreteGpuScreenshotClamp(
forceScreenshot,
resolvedGpuMode,
config,
);
const preMode: CaptureMode =
headlessShell &&
isLinux &&
!effectiveForceScreenshot &&
!supersampling &&
!drawElementTransparent
? "beginframe"
: "screenshot";
// Callers that already have the HTML pass options.requiresWebGpu; others
// fall back to fetching the server about to be navigated to anyway. A
// fetch failure defaults to false — the real page.goto moments later
// still fails loudly if the server is actually down.
const requiresWebGpu =
options.requiresWebGpu ??
(await fetch(`${serverUrl}/index.html`, { signal: AbortSignal.timeout(5_000) })
.then((res) => res.text())
.then(compositionRequiresWebGpu)
.catch(() => false));
const gpuConfig = { ...config, browserGpuMode: resolvedGpuMode };
const chromeArgs = buildChromeArgs(
{ width: options.width, height: options.height, captureMode: preMode, requiresWebGpu },
gpuConfig,
);
const withoutWaylandDisplay = await captureWithoutWaylandDisplay(resolvedGpuMode);
const browserLease = await acquireBrowser(chromeArgs, { ...config, withoutWaylandDisplay });
return constructCaptureSessionWithRollback({
browserLease,
serverUrl,
outputDir,
options,
onBeforeCapture,
config,
useDrawElement,
requiresWebGpu,
softwareWebGpu: usesSoftwareWebGpu(requiresWebGpu, gpuConfig),
});
}
interface CaptureSessionConstructionInput {
browserLease: BrowserLease;
serverUrl: string;
outputDir: string;
options: CaptureOptions;
onBeforeCapture: BeforeCaptureHook | null;
config?: Partial<EngineConfig>;
useDrawElement: boolean;
requiresWebGpu?: boolean;
softwareWebGpu?: boolean;
}
async function constructCaptureSessionWithRollback(
input: CaptureSessionConstructionInput,
): Promise<CaptureSession> {
let page: Page | undefined;
try {
return await constructCaptureSession({
...input,
onPageCreated: (createdPage) => {
page = createdPage;
},
});
} catch (error) {
let pageClosed = true;
try {
if (page) {
const rollbackPage = page;
pageClosed = await waitForCloseWithTimeout(
Promise.resolve().then(() => rollbackPage.close()),
);
}
} finally {
if (!pageClosed) {
console.warn(
"[FrameCapture] Timed out closing page during construction rollback; forcing browser process shutdown",
);
input.browserLease.forceRelease();
} else {
const browserClosed = await waitForCloseWithTimeout(input.browserLease.release());
if (!browserClosed) {
console.warn(
"[FrameCapture] Timed out closing browser during construction rollback; forcing browser process shutdown",
);
input.browserLease.forceRelease();
}
}
}
throw error;
}
}
async function constructCaptureSession(
input: CaptureSessionConstructionInput & { onPageCreated(page: Page): void },
): Promise<CaptureSession> {
const {
browserLease,
serverUrl,
outputDir,
options,
onBeforeCapture,
config,
useDrawElement,
requiresWebGpu,
softwareWebGpu,
onPageCreated,
} = input;
const { browser, captureMode } = browserLease;
const page = await browser.newPage();
onPageCreated(page);
// Cap the existing session's inspection buffer; new sessions have separate buffers.
const frame = page.mainFrame();
// Frame.client is runtime-only, so keep capture working when it is absent.
const { CDPSession } = await import("puppeteer-core");
if ("client" in frame && frame.client instanceof CDPSession) {
await frame.client.send("Network.enable", {
maxTotalBufferSize: 32 * 1024 * 1024,
maxResourceBufferSize: 16 * 1024 * 1024,
});
}
// Polyfill esbuild's keepNames helper inside the page.
//
// The engine is published as raw TypeScript (`packages/engine/package.json`
// points `main`/`exports` at `./src/index.ts`) and downstream consumers
// execute it through transpilers that may inject `__name(fn, "name")`
// wrappers around named functions. Empirically, this happens with:
// - tsx (its esbuild loader runs with keepNames=true), used by the
// producer's parity-harness, ad-hoc dev scripts, and the
// `bun run --filter @hyperframes/engine test` Vitest path.
// - any tsup/esbuild build that explicitly enables keepNames.
//
// The HeyGen CLI (`packages/cli`) bundles this engine via tsup with
// keepNames left at its default (false) — verified by grepping
// `packages/cli/dist/cli.js`, where `__name(...)` call sites are absent.
// Bun's TS loader also does not currently inject `__name`. Even so,
// anything that calls `page.evaluate(fn)` with a nested named function
// under tsx (most local development and tests) will serialize bodies
// like `__name(nested,"nested")` and crash with `__name is not defined`
// in the browser. The shim makes such calls a no-op.
//
// An alternative is to load browser-side code as raw text and inject it
// via `page.addScriptTag({ content: ... })` — see
// `packages/cli/src/commands/contrast-audit.browser.js` for that pattern.
// Until every `page.evaluate(fn)` call site migrates, this polyfill is
// the single line of defense. The companion regression test in
// `frameCapture-namePolyfill.test.ts` verifies the shim stays wired up.
await page.evaluateOnNewDocument(() => {
const w = window as unknown as { __name?: <T>(fn: T, _name: string) => T };
if (typeof w.__name !== "function") {
w.__name = <T>(fn: T, _name: string): T => fn;
}
});
// Media elements are addressed by a document-unique render id, not by the
// per-file element id. Install the resolvers before any page script runs.
await installMediaRenderIdBridge(page);
// Fast capture: record accelerated canvases (webgl/webgl2/webgpu) and force
// preserveDrawingBuffer before any page script can create a context — their
// paint records freeze at the first frame, so captureDrawElementFrame
// composites their live content via drawImage instead (see
// instrumentAcceleratedCanvases). Must be registered before navigation.
if (useDrawElement) {
await page.evaluateOnNewDocument(instrumentAcceleratedCanvases);
}
// The opacity → autoAlpha tween rewrite was RETIRED with the requestPaint
// contract adoption (crbug 529829538 closed WAI): a requestPaint-driven
// paint refreshes nested opacity layers natively, and the rewrite itself
// measured ~28 dB of damage on comps whose fades it touched. Warn instead
// of silently ignoring the old escape hatch.
if (process.env.HF_FAST_CAPTURE_AUTOALPHA !== undefined) {
console.warn(
"[engine] HF_FAST_CAPTURE_AUTOALPHA is retired and ignored: the requestPaint " +
"paint contract captures animated opacity natively (see drawElementService.ts).",
);
}
// Re-apply the captured root's own compositor-applied props to the 2D
// context where the snapshot does not carry them (see the correction
// comment in drawElementService.ts drawAndEncode: transform always —
// never baked, verified under the requestPaint contract 2026-07-07;
// opacity ratio only on non-requestPaint paints, where the snapshot holds
// the load-time value). On by default; disable with
// HF_FAST_CAPTURE_ROOT_PROPS=false.
if (useDrawElement && process.env.HF_FAST_CAPTURE_ROOT_PROPS !== "false") {
await page.evaluateOnNewDocument(() => {
(window as unknown as { __HF_ROOT_PROPS__?: boolean }).__HF_ROOT_PROPS__ = true;
});
}
// Inject render-time variable overrides before any page script runs, so the
// runtime helper `getVariables()` returns the merged result on its first
// call. Pass the JSON string and parse inside the page so we don't require
// any JSON-incompatible value to round-trip through Puppeteer's serializer.
if (options.variables && Object.keys(options.variables).length > 0) {
const variablesJson = JSON.stringify(options.variables);
await page.evaluateOnNewDocument((json: string) => {
type WindowWithVariables = Window & { __hfVariables?: Record<string, unknown> };
try {
(window as WindowWithVariables).__hfVariables = JSON.parse(json);
} catch {
// The CLI validated the JSON before this point — a parse failure here
// means the page swapped JSON.parse, which is the page's problem.
}
}, variablesJson);
}
await installPageMotionBlur(page, options);
const browserVersion = await browser.version();
const sessionOptions = resolveCaptureSessionOptions(options, browserVersion);
const expectedMajor = config?.expectedChromiumMajor;
if (Number.isFinite(expectedMajor)) {
const actualChromiumMajor = Number.parseInt(
(browserVersion.match(/(\d+)\./) || [])[1] || "",
10,
);
if (Number.isFinite(actualChromiumMajor) && actualChromiumMajor !== expectedMajor) {
throw new Error(
`[FrameCapture] Chromium major mismatch expected=${expectedMajor} actual=${actualChromiumMajor} raw=${browserVersion}`,
);
}
}
const viewport: Viewport = {
width: sessionOptions.width,
height: sessionOptions.height,
deviceScaleFactor: sessionOptions.deviceScaleFactor || 1,
};
await page.setViewport(viewport);
// Transparent-background setup is intentionally NOT done here. Chrome resets
// the default-background-color override on navigation, and the
// `html,body{background:transparent}` stylesheet that
// `initTransparentBackground` injects must land in a real `document.head`.
// See `initializeSession()` below — it calls `initTransparentBackground` for
// PNG captures after `page.goto(...)` and the `window.__hf` readiness poll.
return {
browser,
browserLease,
page,
options: sessionOptions,
serverUrl,
outputDir,
onBeforeCapture,
requiresWebGpu,
softwareWebGpu,
isInitialized: false,
browserConsoleBuffer: [],
scriptLoadFailures: [],
pageErrors: [],
subTimelineWaitMemo: sessionOptions.subTimelineWaitMemo ?? {},
warnings: [],
capturePerf: {
frames: 0,
seekMs: 0,
beforeCaptureMs: 0,
screenshotMs: 0,
totalMs: 0,
frameMs: [],
},
captureMode,
launchCaptureMode: captureMode,
beginFrameTimeTicks: 0,
// Frame interval in ms: 1000 * den / num. For 30/1 → 33.333…, for
// 30000/1001 (NTSC) → 33.366…. JavaScript number precision is fine at
// these scales — no rounding required.
beginFrameIntervalMs: (1000 * options.fps.den) / Math.max(1, options.fps.num),
beginFrameHasDamageCount: 0,
beginFrameNoDamageCount: 0,
config,
};
}
/**
* Classify a console "Failed to load resource" error as a font-load failure.
*
* These are expected when deterministic font injection replaces Google Fonts
* @import URLs with embedded base64 — or when the render environment has no
* network access to Google Fonts. Suppressing them reduces noise in render
* output without hiding real asset failures (images, videos, scripts, etc.).
*
* Chrome's `msg.text()` for a failed resource is typically just
* `"Failed to load resource: net::ERR_FAILED"` — the URL is only on
* `msg.location().url`. We match against both so the filter works regardless
* of which form Chrome emits.
*/
export function isFontResourceError(type: string, text: string, locationUrl: string): boolean {
if (type !== "error") return false;
if (!text.startsWith("Failed to load resource")) return false;
return /fonts\.googleapis|fonts\.gstatic|\.(woff2?|ttf|otf)(\b|$)/i.test(
`${locationUrl} ${text}`,
);
}
export function formatConsoleDiagnostic(
type: string,
text: string,
locationUrl: string,
): { text: string; suppressHostLog: boolean } {
const isFontLoadError = isFontResourceError(type, text, locationUrl);
if (isFontLoadError) return { text: `[Browser] ${text}`, suppressHostLog: true };
if (text.startsWith("[hyperframes]")) {
return {
text: `[HyperFrames] ${text.slice("[hyperframes]".length).trim()}`,
suppressHostLog: false,
};
}
// Other "Failed to load resource" 404s are typically non-blocking (e.g.
// favicon, sourcemaps, optional assets). Prefix them so users know they
// are harmless and don't confuse them with real render errors.
const isResourceLoadError = type === "error" && text.startsWith("Failed to load resource");
const prefix = isResourceLoadError
? "[non-blocking]"
: type === "error"
? "[Browser:ERROR]"
: type === "warn"
? "[Browser:WARN]"
: "[Browser]";
return { text: `${prefix} ${text}`, suppressHostLog: false };
}
export const HF_READY_DIAGNOSTIC_EXPR = `(async function() {
var hf = window.__hf;
var player = window.__player;
var renderReady = !!window.__renderReady;
var hasSeek = !!(hf && typeof hf.seek === "function");
var duration = hf ? hf.duration : -1;
var hasTimeline = !!(window.__timelines && Object.keys(window.__timelines).length > 0);
var root = document.querySelector("[data-composition-id]");
var declaredDuration = root ? Number(root.getAttribute("data-duration")) : -1;
var registry = (window.__hf && window.__hf.buildReady) || {};
var keys = Object.keys(registry);
// A microtask race mis-sorts a non-native thenable (extra adoption tick)
// and rejects the whole expression on a rejected entry. Settling each
// key onto its own record and waiting one macrotask avoids both.
var settled = {};
if (keys.length > 0) {
keys.forEach(function(key) {
Promise.resolve(registry[key]).then(
function() { settled[key] = "resolved"; },
function() { settled[key] = "rejected"; },
);
});
await new Promise(function(r) { setTimeout(r, 0); });
}
// A thenable resolving via its own setTimeout(0) can still misreport as
// pending here (macrotask registration order, not resolution order), a
// narrow case that self-corrects on the next ~1s diagnostic tick.
var pendingBuildReadyKeys = keys.filter(function(key) { return !settled[key]; });
var rejectedBuildReadyKeys = keys.filter(function(key) { return settled[key] === "rejected"; });
return {
renderReady: renderReady,
hasHf: !!hf,
hasSeek: hasSeek,
hasPlayer: !!player,
duration: duration,
hasTimeline: hasTimeline,
declaredDuration: declaredDuration,
pendingBuildReadyKeys: pendingBuildReadyKeys,
rejectedBuildReadyKeys: rejectedBuildReadyKeys,
};
})()`;
export interface HfDiagnostic {
renderReady: boolean;
hasHf: boolean;
hasSeek: boolean;
hasPlayer: boolean;
duration: number;
hasTimeline: boolean;
declaredDuration: number;
pendingBuildReadyKeys: string[];
rejectedBuildReadyKeys: string[];
}
// fallow-ignore-next-line complexity
export function buildZeroDurationDiagnostic(diag: HfDiagnostic): string {
const hints: string[] = [];
if (diag.pendingBuildReadyKeys.length > 0) {
hints.push(
`window.__hf.buildReady never resolved for: ${diag.pendingBuildReadyKeys.join(", ")}. ` +
"The runtime holds render-ready until every registered buildReady promise settles. " +
"Find where the composition registers that key and confirm it actually resolves.",
);
}
if (diag.rejectedBuildReadyKeys.length > 0) {
hints.push(
`window.__hf.buildReady rejected for: ${diag.rejectedBuildReadyKeys.join(", ")}. ` +
"That key's build promise failed rather than hanging. Find why it rejects.",
);
}
if (!diag.hasPlayer) {
hints.push("window.__player was never set: the HyperFrames runtime did not initialize.");
}
if (!diag.hasTimeline) {
hints.push(
"No GSAP timeline registered (window.__timelines is empty). " +
"CSS/WAAPI/Lottie animations are usually auto-detected (the runtime infers " +
"duration from the longest running animation), but this composition's duration " +
"could not be inferred, which usually means an infinite/unbounded animation " +
"(e.g. animation-iteration-count: infinite, repeat: -1 WAAPI, or a looping Lottie " +
"clip) or a Three.js scene with no discoverable AnimationClip.",
);
}
if (diag.declaredDuration <= 0 && !diag.hasTimeline) {
hints.push(
'Fix: add data-duration="<seconds>" to your root <div data-composition-id="..."> element.',
);
}
if (diag.hasSeek && diag.duration === 0 && diag.renderReady) {
hints.push("The runtime finished initializing but reported zero duration. This is permanent.");
}
return (
`[FrameCapture] Composition has zero duration.\n` +
` Runtime ready: ${diag.renderReady}, __player: ${diag.hasPlayer}, ` +
`__hf.seek: ${diag.hasSeek}, GSAP timeline: ${diag.hasTimeline}, ` +
`data-duration: ${diag.declaredDuration > 0 ? diag.declaredDuration + "s" : "not set"}\n` +
(hints.length > 0 ? hints.map((h) => ` → ${h}`).join("\n") : "")
);
}
async function evaluateHfDiagnostic(page: Page): Promise<HfDiagnostic> {
return (await page.evaluate(HF_READY_DIAGNOSTIC_EXPR)) as HfDiagnostic;
}
export async function pollHfReady(
page: Page,
timeoutMs: number,
intervalMs: number = 100,
): Promise<void> {
const readyExpr = `!!(window.__hf && typeof window.__hf.seek === "function" && window.__hf.duration > 0)`;
const FAST_FAIL_AFTER_MS = 10_000;
// Throttle diagnostic CDP calls to ~1000ms — running evaluateHfDiagnostic on
// every 100ms poll tick after the 10s mark generates ~350 unnecessary CDP
// round-trips per failed render. One diagnostic per second is enough.
const DIAGNOSTIC_INTERVAL_MS = 1_000;
const deadline = Date.now() + timeoutMs;
let lastDiagnosticAt = 0;
while (Date.now() < deadline) {
const state = await page.evaluate(
`typeof window.__hfStartupError === "string" ? window.__hfStartupError : ${readyExpr}`,
);
if (typeof state === "string") throw new Error(state);
if (state) return;
const elapsed = timeoutMs - (deadline - Date.now());
if (elapsed >= FAST_FAIL_AFTER_MS) {
const now = Date.now();
if (now - lastDiagnosticAt >= DIAGNOSTIC_INTERVAL_MS) {
lastDiagnosticAt = now;
const diag = await evaluateHfDiagnostic(page);
// Only fast-fail when ALL signals are permanently zero:
// 1. No GSAP timeline registered (GSAP sets duration synchronously
// before __renderReady, so a missing timeline won't self-correct).
// 2. No data-duration declared on the root element.
// 3. hf.duration is still 0 — this also covers CSS/WAAPI/Lottie
// auto-inference (see runtime/init.ts resolveAdapterDurationFloorSeconds):
// those runtimes report a non-zero hf.duration once discovery
// resolves, without any GSAP timeline or data-duration. Checking
// hf.duration directly (rather than only the two authored
// signals) avoids fast-failing a composition whose inferred
// duration just hasn't landed yet.
// A composition with a GSAP timeline but no data-duration is still
// valid — GSAP drives duration via __timelines, not data-duration.
if (
diag.renderReady &&
diag.hasSeek &&
!diag.hasTimeline &&
diag.declaredDuration <= 0 &&
diag.duration <= 0
) {
throw new Error(buildZeroDurationDiagnostic(diag));
}
}
}
await new Promise((resolve) => setTimeout(resolve, intervalMs));
}
const diag = await evaluateHfDiagnostic(page);
if (diag.hasSeek && diag.duration === 0) {
throw new Error(buildZeroDurationDiagnostic(diag));
}
throw new Error(
`[FrameCapture] window.__hf not ready after ${timeoutMs}ms. ` +
`Page must expose window.__hf = { duration, seek }.\n` +
` State: __hf=${diag.hasHf}, seek=${diag.hasSeek}, player=${diag.hasPlayer}, ` +
`renderReady=${diag.renderReady}, duration=${diag.duration}`,
);
}
// Enumerated regardless of bail reason, so the warning names every composition still
// waited on, not only a failed script URL.
async function listUnregisteredTimelineIds(page: Page): Promise<string[]> {
const evaluated = await page.evaluate(`(function() {
var hosts = document.querySelectorAll("[data-composition-id]");
var timelines = window.__timelines || {};
var m = [];
for (var i = 0; i < hosts.length; i++) {
if (hosts[i].hasAttribute("data-no-timeline")) continue;
var id = hosts[i].getAttribute("data-composition-id");
if (id && !timelines[id]) m.push(id);
}
return m;
})()`);
// Builds a warning, so it must never throw: normalise a loosely typed result.
return Array.isArray(evaluated) ? evaluated.map((id) => String(id)) : [];
}
export async function waitForSubCompositionTimelines(
session: CaptureSession,
page: Page,
timeoutMs: number,
): Promise<void> {
const memo = session.subTimelineWaitMemo;
session.subTimelineWaitOutcome = await pollSubCompositionTimelines(page, timeoutMs, {
getScriptLoadFailures: () => session.scriptLoadFailures,
onPending: (ids) => {
session.pendingTimelineIds = [...ids];
},
shouldStop: () => session.vfxFailure !== undefined,
knownUnregisteredIds: memo.unregisteredIds,
});
// Only a clean full-length timeout is replayed: a VFX stop ends early, and page or script
// errors must reach each session so it can still classify the wait as a script failure.
const cleanTimeout =
session.subTimelineWaitOutcome === "timeout" &&
session.vfxFailure === undefined &&
session.pageErrors.length === 0 &&
session.scriptLoadFailures.length === 0;
if (cleanTimeout) {
memo.unregisteredIds = session.pendingTimelineIds ?? [];
}
}
export interface SubTimelinePollOptions {
intervalMs?: number;
// Fail-fast: a script resource that failed to load can never register its timeline,
// so once failures exist the poll ends `scriptFailureGraceMs` after it started.
getScriptLoadFailures?: () => readonly string[];
scriptFailureGraceMs?: number;
// Receives the ids still unregistered at bail time, for the structured warning.
onPending?: (ids: readonly string[]) => void;
// Ends the wait at once; the caller then fails the render for its own reason.
shouldStop?: () => boolean;
// Ids an earlier session of this render already timed out on: not waited for again.
knownUnregisteredIds?: readonly string[];
}
export async function pollSubCompositionTimelines(
page: Page,
timeoutMs: number,
{
intervalMs = 150,
getScriptLoadFailures,
scriptFailureGraceMs = 2_000,
onPending,
shouldStop,
knownUnregisteredIds = [],
}: SubTimelinePollOptions = {},
): Promise<SubTimelineWaitOutcome> {
// Hosts may opt out of the timeline wait with `data-no-timeline` —
// compositions driven purely by CSS animations / rAF (the render-compat
// contract) never register window.__timelines[id], and without the opt-out
// they stall here for the full playerReadyTimeout (45 s) on every render.
const expression = `(function() {
var hosts = document.querySelectorAll("[data-composition-id]");
if (hosts.length === 0) return true;
var timelines = window.__timelines || {};
var known = ${JSON.stringify(knownUnregisteredIds)};
for (var i = 0; i < hosts.length; i++) {
if (hosts[i].hasAttribute("data-no-timeline")) continue;
var id = hosts[i].getAttribute("data-composition-id");
if (!id || known.indexOf(id) !== -1) continue;
if (!timelines[id]) return false;
}
return true;
})()`;
const start = Date.now();
const deadline = start + timeoutMs;
let ready = false;
let scriptFailureBail = false;
for (;;) {
ready = Boolean(await page.evaluate(expression));
if (ready || shouldStop?.()) break;
const now = Date.now();
if (now >= deadline) break;
const failures = getScriptLoadFailures?.() ?? [];
if (failures.length > 0 && now - start >= scriptFailureGraceMs) {
scriptFailureBail = true;
console.warn(
`[FrameCapture] Sub-composition timeline wait cut short after ${now - start}ms: ` +
`script resource(s) failed to load (${failures.join(", ")}), so ` +
`the timeline registration they carry can never arrive. ` +
`Fix the script reference; the render proceeds without those animations.`,
);
break;
}
await new Promise((resolve) => setTimeout(resolve, intervalMs));
}
// Skipped known ids still count: if one is still unregistered, report the timeout again.
const pendingIds =
ready && knownUnregisteredIds.length === 0 ? [] : await listUnregisteredTimelineIds(page);
if (ready && pendingIds.length > 0 && (getScriptLoadFailures?.() ?? []).length > 0) {
scriptFailureBail = true;
}
// Always force a timeline rebind once sub-composition timelines are
// confirmed present. The previous implementation only called rebind
// when the timeline count grew during the poll, which missed the case
// where all sub-comp scripts had already executed before the poll
// started — leaving child timelines un-nested in the root and causing
// the earliest sub-composition (data-start near 0) to render without
// its GSAP animations.
if (ready && pendingIds.length === 0) {
await page.evaluate(`(function() {
if (typeof window.__hfForceTimelineRebind === "function") {
window.__hfForceTimelineRebind();
}
})()`);
return "ready";
}
onPending?.(pendingIds);
const missing = pendingIds.join(", ");
if (scriptFailureBail) {
console.warn(`[FrameCapture] Composition(s) still waiting on the failed script: ${missing}.`);
} else {
console.warn(
`[FrameCapture] Sub-composition timelines not registered after ${timeoutMs}ms: ${missing}. ` +
`Compositions that load data asynchronously (e.g. fetch) must register window.__timelines[id] after setup completes. ` +
`Compositions intentionally driven without GSAP timelines (CSS animations / rAF) can mark the host with data-no-timeline to skip this wait.`,
);
}
return scriptFailureBail ? "script_failure" : "timeout";
}
async function pollVideosReady(
page: Page,
skipIds: readonly string[],
timeoutMs: number,
intervalMs: number = 100,
): Promise<boolean> {
const check = async (): Promise<boolean> => {
return Boolean(
await page.evaluate((skipIdList: readonly string[]) => {
const skip = new Set(skipIdList);
const vids = Array.from(document.querySelectorAll("video")).filter((v) => !skip.has(v.id));
return (
vids.length === 0 ||
vids.every((v) => {
const ve = v as HTMLVideoElement;
if (ve.readyState >= 2) return true;
if (ve.error) return true;
if (ve.networkState === HTMLMediaElement.NETWORK_NO_SOURCE) return true;
return false;
})
);
}, skipIds),
);
};
const deadline = Date.now() + timeoutMs;
while (Date.now() < deadline) {
if (await check()) return true;
await new Promise((resolve) => setTimeout(resolve, intervalMs));
}
return check();
}
// Wait for every `<img>` with a non-`data:` src to have settled — either
// successfully loaded (`complete && naturalWidth > 0`) or failed with a
// broken-image marker (`complete && naturalWidth === 0`, the HTMLImageElement
// equivalent of HTMLMediaElement.error). htmlCompiler localises remote `<img>`
// URLs to the local file server before this point, so in practice this polls
// for the local fetch to land — but the guard is a defensive net so that any
// future composition path that leaves a remote URL in place won't capture
// frames before the pixels arrive. Mirrors `pollVideosReady` for parity with
// the video-side readiness contract (videos exit-early on `ve.error`; images
// exit-early on `complete && naturalWidth === 0`).
/** @internal exported for unit testing only */
export async function pollImagesReady(
page: Page,
timeoutMs: number,
intervalMs: number = 100,
): Promise<boolean> {
const check = async (): Promise<boolean> => {
return Boolean(
await page.evaluate(() => {
const imgs = Array.from(document.querySelectorAll("img"));
return (
imgs.length === 0 ||
imgs.every((img) => {
const ie = img as HTMLImageElement;
const src = ie.getAttribute("src") || "";
if (!src || src.startsWith("data:")) return true;
// A `complete` image with zero naturalWidth has settled with an
// error (404 / decode failure / CORS rejection / blocked). Treat
// as done — waiting won't make it load — and let the render
// continue with the broken-image marker visible. Mirrors how
// pollVideosReady treats `ve.error`.
if (ie.complete && ie.naturalWidth === 0) return true;
if (ie.complete && ie.naturalWidth > 0) return true;
return false;
})
);
}),
);
};
const deadline = Date.now() + timeoutMs;
while (Date.now() < deadline) {
if (await check()) return true;
await new Promise((resolve) => setTimeout(resolve, intervalMs));
}
return check();
}
export async function waitForImagesReady(
page: Page,
timeoutMs: number,
onUnloaded: (sources: string) => void,
): Promise<boolean> {
const ready = await pollImagesReady(page, timeoutMs);
if (!ready) {
onUnloaded(
await page.evaluate(() =>
Array.from(document.querySelectorAll("img"))
.filter((img) => {
const src = img.getAttribute("src") || "";
if (!src || src.startsWith("data:")) return false;
return !(img.complete && img.naturalWidth > 0);
})
.map((img) => img.src || img.getAttribute("src") || "(no src)")
.join(", "),
),
);
}
await decodeAllImages(page);
return ready;
}
type MediaReadinessSnapshot = {
pendingImages: string[];
failedImages: string[];
pendingVideos: string[];
failedVideos: string[];
};
/** @internal exported for contract testing. */
export async function collectMediaReadinessWarnings(
page: Page,
skipIds: readonly string[],
timeoutMs: number,
): Promise<CaptureWarning[]> {
const snapshot = await page.evaluate((skipIdList: readonly string[]): MediaReadinessSnapshot => {
const skipped = new Set(skipIdList);
const result: MediaReadinessSnapshot = {
pendingImages: [],
failedImages: [],
pendingVideos: [],
failedVideos: [],
};
for (const img of document.querySelectorAll("img")) {
const src = img.getAttribute("src") || "";
if (!src || src.startsWith("data:")) continue;
if (!img.complete) result.pendingImages.push(img.src || src);
else if (img.naturalWidth <= 0) result.failedImages.push(img.src || src);
}
// Browser media readiness is a frame-capture requirement only for video.
// Audio is extracted and mixed out of band by the producer, so an idle
// DOM <audio> element can legitimately remain at HAVE_NOTHING here. The
// producer reports actual extraction/mix failures as audio_processing_failed.
for (const media of document.querySelectorAll("video")) {
const mediaElement = media as HTMLMediaElement;
if (skipped.has(mediaElement.id)) continue;
const src = mediaElement.currentSrc || mediaElement.getAttribute("src") || "(no src)";
const failed =
Boolean(mediaElement.error) ||
mediaElement.networkState === HTMLMediaElement.NETWORK_NO_SOURCE;
const pending = !failed && mediaElement.readyState < HTMLMediaElement.HAVE_CURRENT_DATA;
if (failed) result.failedVideos.push(src);
else if (pending) result.pendingVideos.push(src);
}
return result;
}, skipIds);
const warnings: CaptureWarning[] = [];
const append = (
code: CaptureWarning["code"],
mediaType: "image" | "video" | "audio",
sources: string[],
) => {
if (sources.length === 0) return;
const timedOut = code === "media_readiness_timeout";
warnings.push({
code,
message: timedOut
? `${mediaType} media did not become capture-ready within ${timeoutMs}ms`
: `${mediaType} media failed to load before capture`,
details: { mediaType, sources: [...new Set(sources)].sort(), timeoutMs },
});
};
append("media_readiness_timeout", "image", snapshot.pendingImages);
append("media_load_failed", "image", snapshot.failedImages);
append("media_readiness_timeout", "video", snapshot.pendingVideos);
append("media_load_failed", "video", snapshot.failedVideos);
return warnings;
}
function recordCaptureWarnings(session: CaptureSession, warnings: readonly CaptureWarning[]): void {
for (const warning of warnings) {
const key = `${warning.code}:${JSON.stringify(warning.details ?? {})}`;
if (
session.warnings.some(
(existing) => `${existing.code}:${JSON.stringify(existing.details ?? {})}` === key,
)
) {
continue;
}
session.warnings.push(warning);
console.warn(`[FrameCapture:${warning.code}] ${warning.message}`, warning.details ?? {});
}
}
export function recordSubTimelineWarning(session: CaptureSession, timeoutMs: number): void {
const outcome = session.subTimelineWaitOutcome;
if (outcome === "ready" || !outcome) return;
const threwThenTimedOut = outcome === "timeout" && session.pageErrors.length > 0;
const scriptFailure = outcome === "script_failure" || threwThenTimedOut;
const sources = [...session.scriptLoadFailures, ...session.pageErrors];
const pending = session.pendingTimelineIds ?? [];
const pendingSuffix = pending.length > 0 ? ` (still unregistered: ${pending.join(", ")})` : "";
recordCaptureWarnings(session, [
{
code: scriptFailure ? "sub_timeline_script_failure" : "sub_timeline_readiness_timeout",
message: threwThenTimedOut
? `A composition script threw and a timeline did not register within ${timeoutMs}ms` +
`${pendingSuffix} (${sources.join(", ")}). Fix the error; a composition animated by ` +
`CSS or rAF rather than a GSAP timeline must mark its host with data-no-timeline.`
: scriptFailure
? `A sub-composition timeline script failed to load (${sources.join(", ")})`
: `Sub-composition timelines did not become ready within ${timeoutMs}ms${pendingSuffix}. ` +
`This can be intentional: a composition driven by CSS animations or rAF never registers ` +
`window.__timelines[id], and marking its host with data-no-timeline skips the wait entirely. ` +
`Otherwise, a composition that sets up asynchronously must register window.__timelines[id] ` +
`once setup completes.`,
details: {
timeoutMs,
sources,
pendingCompositionIds: [...pending],
},
},
]);
}
/**
* Runtime-mounted map-viewport markers, keyed by the CSS selector each map
* library stamps on its live container. Selector presence means an actual map
* INSTANCE is rendering in the page — not merely that a map library script
* loaded — which keeps false positives low (a baked map video carries none of
* these).
*/
const LIVE_MAP_MARKERS: ReadonlyArray<{ selector: string; library: string }> = [
{ selector: ".leaflet-container", library: "Leaflet" },
{ selector: ".maplibregl-map", library: "MapLibre GL" },
{ selector: ".mapboxgl-map", library: "Mapbox GL" },
{ selector: ".gm-style", library: "Google Maps" },
{ selector: ".ol-viewport", library: "OpenLayers" },
];
/**
* Build the `live_map_detected` warning for the detected map libraries.
* A live tile map violates the deterministic-render contract (tiles are
* render-time network fetches): none of the readiness polls cover late-added
* tile images or map canvases, so frames captured before tiles arrive ship a
* blank/partial map with no error — the render exits success. Wild signature:
* PRINFRA-300 (blank hook scene, zero diagnostics, "fixed" by re-render).
*/
export function buildLiveMapWarning(libraries: readonly string[]): CaptureWarning {
return {
code: "live_map_detected",
message:
`Live map viewport(s) detected in the composition (${libraries.join(", ")}). ` +
`Map tiles load over the network at render time, which the deterministic-render ` +
`contract forbids: frames captured before tiles arrive ship a blank or partial map ` +
`with no error. Bake the map to a video first (the hyperframes skill's ` +
`scripts/bake-basemap.mjs, see references/film.md) and use the baked file as the imagery layer.`,
details: { sources: [...libraries] },
};
}
/** Detect live map viewports in the page and record the warning. */
async function recordLiveMapWarning(session: CaptureSession, page: Page): Promise<void> {
const libraries = (await page.evaluate(
(markers: ReadonlyArray<{ selector: string; library: string }>) =>
markers.filter((m) => document.querySelector(m.selector) !== null).map((m) => m.library),
LIVE_MAP_MARKERS,
)) as string[];
if (libraries.length === 0) return;
recordCaptureWarnings(session, [buildLiveMapWarning(libraries)]);
}
// Force every successfully-loaded `<img>` to be GPU-uploaded before the first
// frame capture. `naturalWidth > 0` means the bitmap has been decoded into
// CPU memory, but compositor-side GPU upload can still happen lazily on first
// paint. Calling `img.decode()` returns a Promise that resolves once the image
// is ready for synchronous painting — eliminating the small first-frame race
// between "image is technically loaded" and "the rasterized texture is on the
// GPU and ready to composite".
//
// Note this is purely an init-time guard; it doesn't prevent Chrome from
// evicting decoded pixels mid-render. The producer-side `localizeRemoteImageSources`
// is what bounds the eviction risk (a re-fetch hits the local file server's
// disk-backed paging, not S3 over the network).
//
// Critical: `decode()` on an in-flight image waits for the fetch to resolve.
// If `pollImagesReady` timed out with some images still loading (`!complete`),
// calling `decode()` on them would block here until the network finally
// completes — or until puppeteer's evaluate timeout fires and throws an
// uncaught error that aborts the render. Skip in-flight and broken images;
// only force GPU upload for images that successfully loaded.
async function decodeAllImages(page: Page): Promise<void> {
await page.evaluate(async () => {
const imgs = Array.from(document.querySelectorAll("img"));
await Promise.all(
imgs.map((img) => {
const ie = img as HTMLImageElement;
if (typeof ie.decode !== "function") return Promise.resolve();
// Skip still-loading images (in-flight decode() would hang) and
// broken images (decode() rejects, but pre-filtering is clearer
// than relying on the .catch).
if (!ie.complete || ie.naturalWidth === 0) return Promise.resolve();
return ie.decode().catch(() => undefined);
}),
);
});
}
export async function applyVideoMetadataHints(
page: Page,
hints: readonly CaptureVideoMetadataHint[] | undefined,
): Promise<void> {
if (!hints || hints.length === 0) return;
// fallow-ignore-next-line complexity
await page.evaluate(
async (metadataHints: CaptureVideoMetadataHint[]) => {
const posters = new Set<string>();
for (const hint of metadataHints) {
if (
!hint.id ||
!Number.isFinite(hint.width) ||
!Number.isFinite(hint.height) ||
hint.width <= 0 ||
hint.height <= 0
) {
continue;
}
const video = (window.__hfMediaEl?.(hint.id) ??
document.getElementById(hint.id)) as HTMLVideoElement | null;
if (!video || video.hasAttribute("poster")) continue;
const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${hint.width}" height="${hint.height}"/>`;
const intrinsicSizePoster = `data:image/svg+xml,${encodeURIComponent(svg)}`;
video.poster = intrinsicSizePoster;
posters.add(intrinsicSizePoster);
}
await Promise.all(
[...posters].map((src) => {
const image = new Image();
image.src = src;
return image.decode();
}),
);
},
[...hints],
);
}
async function waitForOptionalTailwindReady(page: Page, timeoutMs: number): Promise<void> {
const hasTailwindReady = await page.evaluate(
`(() => { const ready = window.__tailwindReady; return !!ready && typeof ready.then === "function"; })()`,
);
if (!hasTailwindReady) return;
const ready = await Promise.race([
page.evaluate(
`Promise.resolve(window.__tailwindReady).then(() => true, () => false)`,
) as Promise<boolean>,
new Promise<boolean>((resolve) => setTimeout(() => resolve(false), timeoutMs)),
]);
if (!ready) {
throw new Error(
`[FrameCapture] window.__tailwindReady not resolved after ${timeoutMs}ms. Tailwind browser runtime must finish before frame capture starts.`,
);
}
}
/** Thrown once a VFX chain fails: the frames it paints would render without the effect. */
export class VfxFailureError extends Error {
constructor(readonly detail: string) {
super(`A VFX chain failed, so its frames would render without the effect (${detail})`);
this.name = "VfxFailureError";
}
}
function assertVfxIntact(session: CaptureSession): void {
if (session.vfxFailure) throw new VfxFailureError(session.vfxFailure);
}
// A `vfx:` detail is a chain that cannot paint, so every frame is wrong; `vfx-frame:` is one frame, a page error.
function recordConsoleScriptError(session: CaptureSession, error: string | null): void {
if (!error?.startsWith("runtime-error:vfx:")) {
recordPageError(session, error);
return;
}
if (session.vfxFailure) return;
session.vfxFailure = error;
const message = new VfxFailureError(error).message;
recordCaptureWarnings(session, [{ code: "vfx_failure", message, details: { sources: [error] } }]);
}
function recordPageError(session: CaptureSession, error: string | null): void {
if (error && !session.pageErrors.includes(error)) session.pageErrors.push(error);
}
// A 4xx `response` and a `requestfailed` can both fire for the same script
// (e.g. a `requestfailed` following the 4xx), and repeated <script> tags for
// the same URL duplicate it further — dedupe so the fail-fast warning names
// each failed URL once.
function recordScriptLoadFailure(session: CaptureSession, url: string): void {
if (!session.scriptLoadFailures.includes(url)) {
session.scriptLoadFailures.push(url);
}
}
const SCRIPT_ERROR_LABEL = "[HyperFrames] composition script error:";
/** `runtime-error:<first line>` for the error a framework wrapper logs when a composition script throws. */
export function classifyConsoleScriptError(type: string, text: string): string | null {
if (type !== "error" || !text.startsWith(SCRIPT_ERROR_LABEL)) return null;
const [detail = ""] = text.slice(SCRIPT_ERROR_LABEL.length).trim().split("\n");
return `runtime-error:${detail.trimEnd() || "unknown"}`;
}
export function classifyConsoleScriptFailure(type: string, text: string): string | null {
if (type !== "error") return null;
if (
/failed to find a valid digest in the ['"]integrity['"] attribute/i.test(text) &&
/resource has been blocked/i.test(text)
) {
return "runtime-error:subresource-integrity";
}
return null;
}
function isPlayPauseAbort(message: string): boolean {
return /^AbortError:/.test(message) && message.includes("play()") && message.includes("pause()");
}
/** `runtime-error:<first line>` when a script served with the composition threw; null if not attributable to one. */
export function classifyPageError(
details: Protocol.Runtime.ExceptionDetails,
projectScripts: ReadonlySet<string>,
): string | null {
const exception = details.exception;
const message = String(exception?.description ?? exception?.value ?? details.text);
const [firstLine = ""] = message.split("\n");
if (isPlayPauseAbort(firstLine)) return null;
const frames = (details.stackTrace?.callFrames ?? []).map((frame) => frame.url);
// Frameless: a parse error names its script; a rejection names whatever document is current, so it is unattributable.
if (frames.length === 0 && details.text.startsWith("Uncaught (in promise)")) return null;
const urls = frames.length > 0 ? frames : [details.url];
// The render compiler names the composition's inline code.
// Inline handlers report the document, which a widget can move.
const owned = (url: string | undefined) =>
url !== undefined && (projectScripts.has(url) || url.startsWith(COMPOSITION_SOURCE_URL));
return urls.some(owned) ? `runtime-error:${firstLine}` : null;
}
// fallow-ignore-next-line unit-size
export async function initializeSession(session: CaptureSession): Promise<void> {
const { page, serverUrl } = session;
// Forward browser console to host. HyperFrames runtime logs get a dedicated
// prefix so page-context observability is visible in producer stdout.
page.on("console", (msg: ConsoleMessage) => {
const type = msg.type();
const text = msg.text();
const locationUrl = msg.location()?.url ?? "";
const diagnostic = formatConsoleDiagnostic(type, text, locationUrl);
if (!diagnostic.suppressHostLog) console.log(diagnostic.text);
appendBrowserDiagnostic(session, diagnostic.text);
// A blocked script can never register its timeline (#3352); a thrown one may still, so it only counts on timeout.
const scriptFailure = classifyConsoleScriptFailure(type, text);
if (scriptFailure) recordScriptLoadFailure(session, scriptFailure);
recordConsoleScriptError(session, classifyConsoleScriptError(type, text));
});
page.on("pageerror", (err) => {
const message = err instanceof Error ? err.message : String(err);
const text = `[Browser:PAGEERROR] ${message}`;
// Benign play/pause race during frame capture — suppress terminal noise, keep in buffer.
if (!isPlayPauseAbort(message)) console.error(text);
appendBrowserDiagnostic(session, text);
});
page.on("requestfailed", (request) => {
const resourceType = request.resourceType();
const url = request.url();
const failureText = request.failure()?.errorText ?? "unknown";
if (resourceType === "script") {
recordScriptLoadFailure(session, request.url());
}
if (shouldIgnoreRequestFailureDiagnostic({ resourceType, url, failureText })) return;
appendBrowserDiagnostic(
session,
formatRequestFailureDiagnostic({
method: request.method(),
resourceType,
url,
failureText,
}),
);
});
const projectScripts = new Set<string>();
page.on("response", (response) => {
const status = response.status();
const request = response.request();
const isScript = request.resourceType() === "script";
const responseUrl = response.url();
if (status < 400) {
if (isScript && responseUrl.startsWith(`${serverUrl}/`)) projectScripts.add(responseUrl);
return;
}
if (isScript) recordScriptLoadFailure(session, responseUrl);
appendBrowserDiagnostic(
session,
formatHttpErrorDiagnostic({
method: request.method(),
resourceType: request.resourceType(),
url: response.url(),
status,
statusText: response.statusText(),
}),
);
});
// Navigate to the file server
const url = `${serverUrl}/index.html`;
// Unlike the pageerror Error, this keeps the script URL of syntax errors and thrown non-errors.
const runtimeClient = await getCdpSession(page);
runtimeClient.on("Runtime.exceptionThrown", ({ exceptionDetails }) => {
recordPageError(session, classifyPageError(exceptionDetails, projectScripts));
});
await runtimeClient.send("Runtime.enable");
const pageNavigationTimeout =
session.config?.pageNavigationTimeout ?? DEFAULT_CONFIG.pageNavigationTimeout;
const initStart = Date.now();
const logInitPhase = (phase: string) => {
console.log(`[initSession:${session.captureMode}] ${phase} (${Date.now() - initStart}ms)`);
};
const gotoEntryPage = async (): Promise<void> => {
appendBrowserDiagnostic(
session,
formatNavigationStartDiagnostic({
captureMode: session.captureMode,
url,
timeoutMs: pageNavigationTimeout,
}),
);
logInitPhase("page.goto start");
try {
await page.goto(url, { waitUntil: "domcontentloaded", timeout: pageNavigationTimeout });
} catch (error) {
appendBrowserDiagnostic(
session,
formatNavigationFailureDiagnostic({
captureMode: session.captureMode,
url,
timeoutMs: pageNavigationTimeout,
elapsedMs: Date.now() - initStart,
error,
}),
);
throw error;
}
await assertWebGpuAdapterAvailable(
page,
session.requiresWebGpu ?? false,
session.softwareWebGpu,
);
};
if (session.captureMode === "screenshot") {
// Screenshot mode: standard navigation, rAF works normally
await gotoEntryPage();
logInitPhase("page.goto complete");
// Flush the GSAP proxy queue synchronously instead of waiting for
// rAF-based batch ticks (100 ops/tick at ~16ms). In headless mode there's
// no UI responsiveness concern, so draining instantly eliminates the
// largest init-time cost for tween-heavy compositions.
await page.evaluate(`window.__hfFlushSync?.()`);
logInitPhase("GSAP proxy flush complete");
const pageReadyTimeout =
session.config?.playerReadyTimeout ?? DEFAULT_CONFIG.playerReadyTimeout;
await pollHfReady(page, pageReadyTimeout);
logInitPhase("pollHfReady complete");
await waitForSubCompositionTimelines(session, page, pageReadyTimeout);
logInitPhase(`pollSubCompositionTimelines complete (${session.subTimelineWaitOutcome})`);
assertVfxIntact(session);
recordSubTimelineWarning(session, pageReadyTimeout);
await applyVideoMetadataHints(page, session.options.videoMetadataHints);
logInitPhase("applyVideoMetadataHints complete");
// Run independent readiness checks in parallel — videos, images, fonts,
// and Tailwind don't depend on each other's completion.
const skipVideoIds = session.options.skipReadinessVideoIds ?? [];
const [videosReady] = await Promise.all([
pollVideosReady(page, skipVideoIds, pageReadyTimeout),
waitForImagesReady(page, pageReadyTimeout, (failedImages) =>
console.warn(
`[FrameCapture] Some image elements did not load within ${pageReadyTimeout}ms: ${failedImages}. ` +
`Continuing render. Affected images may appear blank/missing in early frames.`,
),
),
page.evaluate(`document.fonts?.ready`),
waitForOptionalTailwindReady(page, pageReadyTimeout),
]);
logInitPhase("media + fonts + tailwind ready");
if (!videosReady) {
const failedVideos = await page.evaluate((skipIdList: readonly string[]) => {
const skip = new Set(skipIdList);
return Array.from(document.querySelectorAll("video"))
.filter((v) => !skip.has(v.id))
.filter((v) => (v as HTMLVideoElement).readyState < 2 && !(v as HTMLVideoElement).error)
.map((v) => (v as HTMLVideoElement).src || v.getAttribute("src") || "(no src)")
.join(", ");
}, skipVideoIds);
console.warn(
`[FrameCapture] Some video elements did not decode within ${pageReadyTimeout}ms: ${failedVideos}. ` +
`Continuing render. Affected videos will appear as blank/black frames.`,
);
}
recordCaptureWarnings(
session,
await collectMediaReadinessWarnings(page, skipVideoIds, pageReadyTimeout),
);
await recordLiveMapWarning(session, page);
await recordSessionInitTelemetry(session, initStart);
// Ground-truth-check the upstream captureBeyondViewport request (see
// pageContentExceedsCaptureHeight) now that the page is fully settled —
// downgrade it when the page doesn't actually overflow the requested
// capture height, since the beyond-viewport CDP path is otherwise pure
// downside (HF#2550: phantom duplicate content on SwiftShader) for
// content it was never needed for.
if (session.options.captureBeyondViewport) {
const needsBeyondViewport = await pageContentExceedsCaptureHeight(
page,
session.options.height,
);
if (!needsBeyondViewport) {
session.options.captureBeyondViewport = false;
logInitPhase("captureBeyondViewport downgraded: page content fits the capture viewport");
}
}
// drawElement or transparent-background init — runs after page is fully ready.
await initDrawElementOrTransparentBackground(session, page, logInitPhase);
await armStaticDedup(session, session.page, logInitPhase);
await ensureRenderFrameSiblings(session.page);
finalizeSessionInit(session);
return;
}
// In BeginFrame mode, Chrome's event loop is paused until we issue frames.
// Start a warmup loop to drive rAF/setTimeout callbacks during page load.
//
// The unlocked path runs while `warmupState.running` stays true — wall-
// clock-bounded. The locked path (`options.lockWarmupTicks`) additionally
// exits at exactly `LOCKED_WARMUP_TICKS` iterations so `beginFrameTimeTicks`
// is deterministic across hosts with different page-load latencies.
const warmupIntervalMs = 33; // ~30fps
const warmupState: WarmupTickState = {
running: true,
ticks: 0,
};
const lockWarmupTicks = session.options.lockWarmupTicks === true;
let warmupClient: import("puppeteer-core").CDPSession | null = null;
const acquireWarmupClient = async (): Promise<void> => {
try {
warmupClient = await getCdpSession(page);
await warmupClient.send("HeadlessExperimental.enable");
} catch {
/* page not ready yet */
}
};
const warmupLoopPromise = (async () => {
await acquireWarmupClient();
await driveWarmupTicks(
{
intervalMs: warmupIntervalMs,
lockWarmupTicks,
tick: async (frameTimeTicks, interval) => {
if (!warmupClient) {
// No CDP yet — let driveWarmupTicks count the tick anyway so the
// locked iteration count is reached deterministically. Throwing
// would skip the ticks++ increment, leaking host-load variance
// back into the count.
return;
}
await warmupClient.send("HeadlessExperimental.beginFrame", {
frameTimeTicks,
interval,
noDisplayUpdates: true,
});
},
},
warmupState,
);
})();
warmupLoopPromise.catch(() => {});
logInitPhase("warmup loop started");
await cancelWarmupOnError(warmupState, async () => {
await gotoEntryPage();
logInitPhase("page.goto complete");
// Flush the GSAP proxy queue synchronously. In BeginFrame mode the rAF-based
// batch drain runs on the warmup loop's 33ms ticks — for tween-heavy
// compositions this is the dominant init cost. Flushing synchronously
// eliminates the wait entirely.
await page.evaluate(`window.__hfFlushSync?.()`);
logInitPhase("GSAP proxy flush complete");
// Poll for window.__hf readiness using manual evaluate loop (waitForFunction
// uses rAF polling internally, which won't fire in beginFrame mode).
const pageReadyTimeout =
session.config?.playerReadyTimeout ?? DEFAULT_CONFIG.playerReadyTimeout;
await pollHfReady(page, pageReadyTimeout);
logInitPhase("pollHfReady complete");
await waitForSubCompositionTimelines(session, page, pageReadyTimeout);
logInitPhase(`pollSubCompositionTimelines complete (${session.subTimelineWaitOutcome})`);
assertVfxIntact(session);
recordSubTimelineWarning(session, pageReadyTimeout);
await applyVideoMetadataHints(page, session.options.videoMetadataHints);
logInitPhase("applyVideoMetadataHints complete");
// Run independent readiness checks in parallel — videos, images, fonts,
// and Tailwind don't depend on each other's completion.
const bfSkipVideoIds = session.options.skipReadinessVideoIds ?? [];
const [bfVideosReady] = await Promise.all([
pollVideosReady(page, bfSkipVideoIds, pageReadyTimeout),
waitForImagesReady(page, pageReadyTimeout, (failedImages) =>
console.warn(
`[FrameCapture] Some image elements did not load within ${pageReadyTimeout}ms: ${failedImages}. ` +
`Continuing render. Affected images may appear blank/missing in early frames.`,
),
),
page.evaluate(`document.fonts?.ready`),
waitForOptionalTailwindReady(page, pageReadyTimeout),
]);
logInitPhase("media + fonts + tailwind ready");
if (!bfVideosReady) {
const failedVideos = await page.evaluate((skipIdList: readonly string[]) => {
const skip = new Set(skipIdList);
return Array.from(document.querySelectorAll("video"))
.filter((v) => !skip.has(v.id))
.filter((v) => (v as HTMLVideoElement).readyState < 2 && !(v as HTMLVideoElement).error)
.map((v) => (v as HTMLVideoElement).src || v.getAttribute("src") || "(no src)")
.join(", ");
}, bfSkipVideoIds);
console.warn(
`[FrameCapture] Some video elements did not decode within ${pageReadyTimeout}ms: ${failedVideos}. ` +
`Continuing render. Affected videos will appear as blank/black frames.`,
);
}
recordCaptureWarnings(
session,
await collectMediaReadinessWarnings(page, bfSkipVideoIds, pageReadyTimeout),
);
await recordLiveMapWarning(session, page);
await recordSessionInitTelemetry(session, initStart);
});
// Stop warmup, then drain the loop in BOTH modes before any further
// BeginFrame on this session (drawElement init, the render-frame commit tick
// at the end of init, and frame 0). Clearing the flag only stops new
// iterations — a warmup `HeadlessExperimental.beginFrame` may still be in
// flight, and a second beginFrame on the same session while one is pending
// fails with "Another frame is pending". Locked mode additionally needs the
// await to reach the exact LOCKED_WARMUP_TICKS count before deriving the
// baseline below.
warmupState.running = false;
await warmupLoopPromise.catch(() => {});
// Preserve the legacy baseline when it is already safe. Otherwise continue
// from the clock actually used by warmup, then reserve capture-rate headroom
// for the commit and probe ticks below. Locked mode still produces an
// identical timeline on every host because its driver ends at exactly
// LOCKED_WARMUP_TICKS.
const preparedBeginFrameTimeline = prepareBeginFrameTimeline(
session,
warmupState,
warmupIntervalMs,
);
// drawElement or transparent-background init — runs after page is fully ready.
// IMPORTANT: must stay after beginFrameTimeTicks is set above. The per-frame
// drawelement branch gates its BeginFrame call on `beginFrameTimeTicks > 0`;
// if this ran first, ticks would be 0 and the paused compositor would never
// advance for opaque drawElement on Linux. (In beginframe-launched mode,
// transparent is always false — useDrawElement+png forces preMode="screenshot"
// upstream — so the SwiftShader fallback inside the helper is dead-but-harmless
// defense-in-depth here.)
await initDrawElementOrTransparentBackground(session, page, logInitPhase);
await armStaticDedup(session, session.page, logInitPhase);
// Pre-create the hidden `__render_frame__` siblings so the first per-session
// `injectVideoFramesBatch` takes the `hasImg = true` (src-update) path instead
// of inserting a fresh `<img>` mid-capture. Then drive ONE non-capture,
// *visual* BeginFrame (`noDisplayUpdates: false`) to actually composite the
// new layers before the first real capture. The warmup ticks above are
// `noDisplayUpdates: true` (they advance the clock but don't paint), and the
// seek in `prepareFrameForCapture` doesn't tick, so without this commit tick
// the first *display-producing* BeginFrame would be the capture itself — and
// the freshly-inserted layers would miss it (the per-session worker-boundary
// near-black flash). The tick time sits in the gap between the last warmup
// tick and frame 0 (`beginFrameTimeTicks` carries +10 intervals of headroom),
// so ticks stay monotonic and no render frame is consumed.
//
// It must land BELOW the producer's BeginFrame liveness probe, which fires
// from probeStage right after init at `beginFrameTimeTicks - 5·interval`
// (screenshotService.probeBeginFrameLiveness). This commit tick is sent during
// init — temporally before the probe — so if its tick were above the probe's,
// the probe would run backwards in BeginFrame time (non-monotonic) and
// chrome-headless-shell stalls it indefinitely (surfaced as a "SwiftShader
// heavy-layer" probe timeout, then routed to screenshot capture). At the
// original `-1·interval` that stalled every comp reaching the probe; at
// `-6·interval` the order stays warmup < commit < probe < capture.
await ensureRenderFrameSiblings(page);
const commitCdp = await getCdpSession(page);
await commitCdp.send("HeadlessExperimental.beginFrame", preparedBeginFrameTimeline.commitParams);
finalizeSessionInit(session);
}
async function captureFrameErrorDiagnostics(
session: CaptureSession,
frameIndex: number,
time: number,
error: Error,
): Promise<string | null> {
try {
const diagnosticsDir = join(session.outputDir, "diagnostics");
if (!existsSync(diagnosticsDir)) mkdirSync(diagnosticsDir, { recursive: true });
const base = join(diagnosticsDir, `frame-error-${frameIndex}`);
const pageScreenshotCanResolve = session.launchCaptureMode !== "beginframe";
if (pageScreenshotCanResolve) {
await session.page.screenshot({ path: `${base}.png`, type: "png", fullPage: true });
}
const html = await session.page.content();
writeFileSync(`${base}.html`, html, "utf-8");
writeFileSync(
`${base}.json`,
JSON.stringify(
{
frameIndex,
time,
error: error.message,
stack: error.stack,
browserConsoleTail: session.browserConsoleBuffer.slice(-30),
},
null,
2,
),
"utf-8",
);
return `${base}.json`;
} catch {
return null;
}
}
/**
* Internal helper: seek timeline and inject video frames.
* Shared by captureFrame (disk) and captureFrameToBuffer (buffer).
* Returns timing breakdown for perf tracking.
*/
export async function waitForPendingSeekCompletion(page: Pick<Page, "evaluate">): Promise<void> {
await page.evaluate(async () => {
const waitForCompletion = (
window as Window & { __hfWaitForSeekCompletion?: () => Promise<void> }
).__hfWaitForSeekCompletion;
await waitForCompletion?.();
});
}
/**
* Seek the page timeline and report whether a page-side composite is pending.
*
* The page's `seek()` owns all framework-specific stepping (GSAP, CSS animations, WAAPI);
* the options object reaches it untouched through the producer's `__hf.seek` bridge.
* Seek and pending-flag read share one round trip.
*/
async function seekPageTimeline(
page: Page,
time: number,
seekOptions: HfSeekOptions | undefined,
): Promise<boolean> {
return page.evaluate(
(t: number, opts: HfSeekOptions | undefined) => {
if (window.__hf && typeof window.__hf.seek === "function") {
window.__hf.seek(t, opts);
}
return !!(window as unknown as { __hf_page_composite_pending?: boolean })
.__hf_page_composite_pending;
},
time,
seekOptions,
);
}
async function prepareFrameForCapture(
session: CaptureSession,
frameIndex: number,
time: number,
seekOptions?: HfSeekOptions,
heldVideoTime?: number,
): Promise<{
quantizedTime: number;
seekMs: number;
beforeCaptureMs: number;
}> {
const { page, options } = session;
if (!session.isInitialized) {
throw new Error("[FrameCapture] Session not initialized");
}
assertVfxIntact(session);
const quantizedTime = quantizeSeekTime(
time,
fpsToNumber(options.fps),
seekOptions?.subFrameDivisions,
);
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;
// Before-capture hook (e.g. video frame injection) — runs before
// page-side compositor clones so cloneNode picks up injected <img>
// 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 & {
__hf?: { colorGrading?: { waitForActiveLuts?: () => Promise<number> } };
}
).__hf?.colorGrading;
await runtime?.waitForActiveLuts?.();
});
const beforeCaptureMs = Date.now() - beforeCaptureStart;
// Page-side compositing three-phase protocol:
// 1. prepare — clone scenes (now containing injected video <img>s)
// 2. micro-screenshot — force browser to paint cloned elements
// 3. resolve — drawElementImage reads paint records, shader composites
if (
hasPendingComposite &&
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") {
await w.__hf_page_composite_prepare();
}
});
const cdp = await getCdpSession(page);
await cdp.send("Page.captureScreenshot", {
format: "jpeg",
quality: 1,
clip: { x: 0, y: 0, width: 1, height: 1, scale: 1 },
});
await page.evaluate(() => {
const w = window as unknown as { __hf_page_composite_resolve?: () => boolean };
if (typeof w.__hf_page_composite_resolve === "function") {
w.__hf_page_composite_resolve();
}
});
}
session.captureStep = "capturing the frame";
return { quantizedTime, seekMs, beforeCaptureMs };
}
// ── Static-frame dedup (default-on, opt-out HF_STATIC_DEDUP=false) ─────────────
// Skip re-seeking + re-screenshotting frames that are byte-identical to their
// predecessor. A frame is dedupable iff no GSAP tween or clip cut is active in it or
// its predecessor (predicted from window.__timelines), AND an empirical anchor-compare
// confirms it. Capture-mode-independent (works on screenshot + beginframe), lossless
// (verification disables the whole comp on any drift), default off. Pays on
// static-hold content (title cards, slideshows, data-viz pauses); a no-op on
// continuously-animated comps and disqualified by video/canvas/non-GSAP animation.
/**
* Clip-cut boundary frames (±1) from the [data-start] schedule. A hard scene swap at a
* cut changes content with no tween; treat those frames as animated so the post-cut
* frame is captured fresh and later static frames reuse the correct scene.
*/
export function computeAuthoredClipBoundaryFrames(
schedule: RawAuthoredTiming[],
fps: number,
): Set<number> {
const frames = new Set<number>();
for (const rawTiming of schedule) {
const timing = resolveAuthoredTimingWindow(rawTiming);
if (!timing) continue;
const edges = [Math.round(timing.start * fps)];
if (timing.end != null) edges.push(Math.round(timing.end * fps));
for (const e of edges) {
for (const f of [e - 1, e, e + 1]) {
if (f >= 0) frames.add(f);
}
}
}
return frames;
}
async function computeClipBoundaryFrames(page: Page, fps: number): Promise<Set<number>> {
const schedule = await page.evaluate(() =>
Array.from(document.querySelectorAll("[data-start]")).map((el) => ({
start: el.getAttribute("data-start"),
duration: el.getAttribute("data-duration"),
authoredDuration: el.getAttribute("data-hf-authored-duration"),
end: el.getAttribute("data-end"),
authoredEnd: el.getAttribute("data-hf-authored-end"),
})),
);
return computeAuthoredClipBoundaryFrames(schedule, fps);
}
// Static dedup is an optional optimization. Building frame-index Sets scales with the
// composition's declared duration, so malformed/sentinel durations must fail closed before
// allocating them. Normal capture and the producer's typed duration validation still proceed.
export const MAX_STATIC_DEDUP_ANALYSIS_FRAMES = 1_000_000;
export function isStaticDedupFrameAnalysisSafe(totalFrames: number): boolean {
return (
Number.isFinite(totalFrames) &&
Number.isSafeInteger(totalFrames) &&
totalFrames > 0 &&
totalFrames <= MAX_STATIC_DEDUP_ANALYSIS_FRAMES
);
}
/**
* Predict the dedupable (static) frame set from window.__timelines. A frame f (f>0) is
* static iff NEITHER f NOR f-1 falls inside any GSAP tween interval — content didn't
* change f-1→f, so f can reuse f-1's buffer. Requiring BOTH neighbours static under-
* claims by one frame at each tween edge (the SAFE direction). Disqualifies the whole
* 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.
*/
export async function computeStaticFrameSet(
page: Page,
fps: number,
): Promise<{
totalFrames: number;
staticFrameSet: Set<number>;
/** Frames whose only active motion is non-spatial (opacity, colour); safe to skip
* the adaptive probe. Empty (not meaningful) when `!eligible`. */
nonSpatialOnlyFrameSet: Set<number>;
hasVideo: boolean;
hasCanvas: boolean;
hasNonGsapAnim: boolean;
tweenCount: number;
eligible: boolean;
reason: string;
}> {
const result = await page.evaluate((spatialProps: readonly string[]) => {
type AnyTween = {
startTime(): number;
duration(): number;
totalDuration?(): number;
getChildren?(nested: boolean, tweens: boolean, timelines: boolean): AnyTween[];
vars?: Record<string, unknown>;
};
// Passed in from SPATIAL_TWEEN_PROPERTIES rather than declared here, so the list
// stays the one this module's own tests exercise (the matching code itself must
// stay inline — this closure is serialized and runs in the page realm).
const SPATIAL_PROPS = new Set(spatialProps);
function isSpatial(vars: Record<string, unknown> | undefined): boolean {
if (!vars) return false;
for (const key of Object.keys(vars)) if (SPATIAL_PROPS.has(key)) return true;
return false;
}
const intervals: Array<{ start: number; end: number; spatial: boolean }> = [];
let tweenCount = 0;
// totalDuration() (NOT duration()): a repeat/yoyo tween animates past one iteration;
// a repeating timeline is marked opaque over its whole span (conservative).
// A GSAP tl.call() is a zero-duration tween whose vars wire the callback as
// onComplete (and onReverseComplete, fired on backward crossing — GSAP has
// no separate "undo" callback, so both directions invoke the SAME forward
// side effect). A one-shot DOM mutation driven this way (e.g. a counter's
// textContent) is not seek-idempotent: crossing it during the static-dedup
// verifier's own arm-time seeking permanently mutates the page, and that
// corruption can leak into a LATER, unrelated static run's real capture
// (the verifier's mismatch check only catches drift within the run being
// checked, not contamination from a run checked afterward). No reliable
// way to tell a DOM-mutating call() from a harmless one (analytics ping,
// class toggle with no visual effect) without executing it, so disqualify
// the whole comp on ANY call() rather than risk shipping wrong pixels.
let hasTimelineCall = false;
function walk(tl: AnyTween, offset: number): void {
if (typeof tl.getChildren !== "function") return;
// A timeline with an onUpdate callback can drive motion without any
// visible tween (e.g. setting x/y from Math.random inside onUpdate).
// Mark its entire span as animated so those frames are never deduped.
if (typeof tl.vars?.onUpdate === "function") {
const total = typeof tl.totalDuration === "function" ? tl.totalDuration() : 0;
// onUpdate can move anything (e.g. x/y from Math.random) — conservatively spatial.
if (total > 0) intervals.push({ start: offset, end: offset + total, spatial: true });
}
for (const child of tl.getChildren(false, true, true)) {
const start = offset + (typeof child.startTime === "function" ? child.startTime() : 0);
const single = typeof child.duration === "function" ? child.duration() : 0;
const total = typeof child.totalDuration === "function" ? child.totalDuration() : single;
if (typeof child.getChildren === "function") {
if (total > single + 1e-6) {
// A repeating nested timeline's own children are walked for their real
// vars below; this span is a conservative (spatial) placeholder for the
// repeat/yoyo overrun, which a per-child walk doesn't otherwise cover.
intervals.push({ start, end: start + total, spatial: true });
// Still descend for hasTimelineCall even though the repeating
// span is already opaque (its frames are excluded from dedup
// regardless): a call() inside it is a review-flagged detection
// gap otherwise — the arm-time verifier can still forward-seek
// through this span while checking a LATER static run, firing
// the call() and corrupting the page (review).
walk(child, start);
} else {
walk(child, start);
}
} else {
tweenCount++;
intervals.push({ start, end: start + total, spatial: isSpatial(child.vars) });
if (
total <= 1e-6 &&
(typeof child.vars?.onComplete === "function" ||
typeof child.vars?.onReverseComplete === "function")
) {
hasTimelineCall = true;
}
}
}
}
const w = window as unknown as {
__timelines?: Record<string, AnyTween>;
__hf?: { duration?: number };
__hfHasFrameSources?: () => boolean;
};
for (const tl of Object.values(w.__timelines || {})) {
if (tl && typeof tl.getChildren === "function") walk(tl, 0);
}
const hasVideo = !!document.querySelector("video");
const hasCanvas = !!document.querySelector("canvas");
const hasFrameSources = w.__hfHasFrameSources?.() ?? false;
const hasIframe = !!document.querySelector("iframe");
// A non-numeric data-start (reference expression like "intro+0.5") can't be turned
// into a clip-cut boundary by computeClipBoundaryFrames' parseFloat, so the cut goes
// unprotected and could be deduped into the previous scene. Disqualify the comp.
const hasUnresolvableClipStart = Array.from(document.querySelectorAll("[data-start]")).some(
(el) => {
const v = (el as HTMLElement).dataset.start;
return v != null && v.trim() !== "" && !Number.isFinite(parseFloat(v));
},
);
// Non-GSAP animation (CSS @keyframes / transitions / WAAPI) surfaces via
// getAnimations(); any running/paused one can change content without a tween.
let hasNonGsapAnim = false;
try {
const docAnims = (document as unknown as { getAnimations?: () => Animation[] }).getAnimations;
if (typeof docAnims === "function") {
hasNonGsapAnim = docAnims.call(document).some((a) => {
const t = a as Animation & { playState?: string };
return t.playState === "running" || t.playState === "paused";
});
}
} catch {
hasNonGsapAnim = true;
}
return {
intervals,
tweenCount,
duration: w.__hf?.duration ?? 0,
hasVideo,
hasCanvas,
hasFrameSources,
hasIframe,
hasNonGsapAnim,
hasUnresolvableClipStart,
hasTimelineCall,
};
}, SPATIAL_TWEEN_PROPERTIES);
const {
intervals,
tweenCount,
duration,
hasVideo,
hasCanvas,
hasFrameSources,
hasIframe,
hasNonGsapAnim,
hasUnresolvableClipStart,
hasTimelineCall,
} = result as {
intervals: Array<{ start: number; end: number; spatial: boolean }>;
tweenCount: number;
duration: number;
hasVideo: boolean;
hasCanvas: boolean;
hasFrameSources: boolean;
hasIframe: boolean;
hasNonGsapAnim: boolean;
hasUnresolvableClipStart: boolean;
hasTimelineCall: boolean;
};
const totalFrames = Math.max(1, Math.ceil(duration * fps));
if (!isStaticDedupFrameAnalysisSafe(totalFrames)) {
return {
totalFrames,
staticFrameSet: new Set<number>(),
nonSpatialOnlyFrameSet: new Set<number>(),
hasVideo,
hasCanvas,
hasNonGsapAnim,
tweenCount,
eligible: false,
reason: `static-dedup frame analysis limit (${MAX_STATIC_DEDUP_ANALYSIS_FRAMES})`,
};
}
const animated = new Set<number>();
const spatialFrameSet = new Set<number>();
for (const { start, end, spatial } of intervals) {
const lo = Math.max(0, Math.floor(start * fps));
const hi = Math.min(totalFrames - 1, Math.ceil(end * fps));
for (let f = lo; f <= hi; f++) {
animated.add(f);
if (spatial) spatialFrameSet.add(f);
}
}
for (const f of await computeClipBoundaryFrames(page, fps)) animated.add(f);
const reasons: string[] = [];
if (!(duration > 0)) reasons.push("unknown/zero duration");
if (hasVideo) reasons.push("video");
if (hasCanvas) reasons.push("canvas/webgl");
// GSAP intervals cannot predict frame-source or opaque iframe draws.
if (hasFrameSources) reasons.push("registered frame source");
if (hasIframe) reasons.push("iframe");
if (tweenCount === 0) reasons.push("no GSAP tweens (non-GSAP animation)");
if (hasNonGsapAnim) reasons.push("running CSS/WAAPI animation");
// tl.call() side effects are not seek-idempotent (see hasTimelineCall detection
// above) — the arm-time verifier's own forward-seeking can permanently fire
// one, corrupting the page for a later, unrelated static run's real capture
// even though each run's own verification passes in isolation (HF static-
// dedup content-drift report, tools-onboarding FR render).
if (hasTimelineCall) reasons.push("tl.call() side effect (not seek-safe)");
if (hasUnresolvableClipStart) reasons.push("unresolvable clip start (reference expression)");
const eligible = reasons.length === 0;
const staticFrameSet = new Set<number>();
if (eligible) {
for (let f = 1; f < totalFrames; f++) {
if (!animated.has(f) && !animated.has(f - 1)) staticFrameSet.add(f);
}
}
const nonSpatialOnlyFrameSet = new Set<number>();
if (eligible) {
for (const f of animated) if (!spatialFrameSet.has(f)) nonSpatialOnlyFrameSet.add(f);
}
return {
totalFrames,
staticFrameSet,
nonSpatialOnlyFrameSet,
hasVideo,
hasCanvas,
hasNonGsapAnim,
tweenCount,
eligible,
reason: eligible ? "eligible" : reasons.join("+"),
};
}
// Fixed density target for verification checks: never leave a gap wider than this
// many frames within a run, independent of the user-tunable sampleCount. This is
// what fixes long runs going nearly unverified — deliberately NOT derived from
// sampleCount, so that knob's effect on density stays monotonic (see below).
const STATIC_VERIFY_REFERENCE_STRIDE = 24;
// Verification uses full-page screenshots, whose cost scales with canvas size
// and page complexity rather than frame count. Bound wall time as well as the
// capture count so a long composition cannot spend minutes proving an
// optimization before the real render starts. Exhaustion fails closed: dedup is
// disabled and normal capture proceeds.
const STATIC_VERIFY_MAX_MS = 15_000;
// Two captures (anchor + comparison) are the minimum proof for a run. Four hundred
// therefore permits 200 fully verified runs while bounding pathological schedules.
const STATIC_VERIFY_MIN_SCREENSHOT_CAP = 400;
// Preserve the legacy tuning headroom: raising the composition-wide sample floor may
// raise the cap proportionally, but never changes the fixed wall deadline.
const STATIC_VERIFY_SAMPLE_CAP_MULTIPLIER = 8;
// Keep sample-driven work within the 400-screenshot base cap: 50 comparisons × 8
// legacy headroom. Mandatory <=24-gap points may still raise the independent cap.
const STATIC_VERIFY_MAX_GLOBAL_SAMPLE_FLOOR =
STATIC_VERIFY_MIN_SCREENSHOT_CAP / STATIC_VERIFY_SAMPLE_CAP_MULTIPLIER;
export interface StaticVerificationRun {
a: number;
b: number;
anchor: number;
comparisons: number[];
frameCount: number;
netSavings: number;
}
export interface StaticVerificationPlan {
runs: StaticVerificationRun[];
skippedRuns: Array<{ a: number; b: number; reason: "unprofitable" }>;
effectiveSampleFloor: number;
predictedFrames: number;
verifiedCandidateFrames: number;
plannedAnchors: number;
plannedComparisons: number;
plannedScreenshots: number;
}
function contiguousStaticRuns(frames: number[]): Array<{ a: number; b: number }> {
const runs: Array<{ a: number; b: number }> = [];
for (const frame of frames) {
const last = runs.at(-1);
if (last && frame === last.b + 1) last.b = frame;
else runs.push({ a: frame, b: frame });
}
return runs;
}
function mandatoryRunComparisons(anchor: number, end: number): number[] {
const points = new Set<number>();
for (
let frame = anchor + STATIC_VERIFY_REFERENCE_STRIDE;
frame < end;
frame += STATIC_VERIFY_REFERENCE_STRIDE
) {
points.add(frame);
}
points.add(end);
return [...points].sort((left, right) => left - right);
}
/** Pure composition-wide planner. Every retained run is profitable and has gaps <=24 frames. */
export function planStaticVerification(
staticFrames: Set<number>,
sampleFloor: number,
): StaticVerificationPlan {
const frames = [...staticFrames].sort((left, right) => left - right);
const allRuns = contiguousStaticRuns(frames).map(({ a, b }): StaticVerificationRun => {
const comparisons = mandatoryRunComparisons(a - 1, b);
const frameCount = b - a + 1;
return {
a,
b,
anchor: a - 1,
comparisons,
frameCount,
netSavings: frameCount - comparisons.length - 1,
};
});
const runs = allRuns.filter((run) => run.anchor >= 0 && run.netSavings > 0);
const skippedRuns = allRuns
.filter((run) => run.anchor < 0 || run.netSavings <= 0)
.map((run) => ({ a: run.a, b: run.b, reason: "unprofitable" as const }));
const normalizedSampleFloor = Number.isFinite(sampleFloor)
? Math.max(1, Math.floor(sampleFloor))
: 1;
const effectiveSampleFloor = Math.min(
normalizedSampleFloor,
STATIC_VERIFY_MAX_GLOBAL_SAMPLE_FLOOR,
);
const comparisonCount = () => runs.reduce((sum, run) => sum + run.comparisons.length, 0);
while (comparisonCount() < effectiveSampleFloor) {
const candidates = runs
.filter((run) => run.frameCount > run.comparisons.length + 2)
.flatMap((run) => {
const points = [run.anchor, ...run.comparisons];
return points.slice(1).map((right, index) => ({
run,
left: points[index]!,
right,
width: right - points[index]!,
}));
})
.filter((gap) => gap.width > 1)
.sort(
(left, right) =>
right.width - left.width || left.run.a - right.run.a || left.left - right.left,
);
const selected = candidates[0];
if (!selected) break;
selected.run.comparisons.push(Math.floor((selected.left + selected.right) / 2));
selected.run.comparisons.sort((left, right) => left - right);
selected.run.netSavings = selected.run.frameCount - selected.run.comparisons.length - 1;
}
runs.sort((left, right) => right.netSavings - left.netSavings || left.a - right.a);
const plannedComparisons = comparisonCount();
return {
runs,
skippedRuns,
effectiveSampleFloor,
predictedFrames: frames.length,
verifiedCandidateFrames: runs.reduce((sum, run) => sum + run.frameCount, 0),
plannedAnchors: runs.length,
plannedComparisons,
plannedScreenshots: runs.length + plannedComparisons,
};
}
export type StaticVerificationOutcome =
| "verified"
| "unprofitable"
| "time_budget"
| "count_budget"
| "mismatch"
| "infrastructure";
export interface StaticVerificationStats {
plannedRuns: number;
completedRuns: number;
plannedAnchors: number;
completedAnchors: number;
plannedComparisons: number;
completedComparisons: number;
seeks: number;
screenshots: number;
byteComparisons: number;
elapsedMs: number;
predictedFrames: number;
verifiedFrames: number;
unverifiedFrames: number;
}
export interface StaticVerificationResult {
outcome: StaticVerificationOutcome;
verifiedFrames: Set<number>;
badFrame?: number;
stats: StaticVerificationStats;
}
interface StaticVerificationDependencies {
now?: () => number;
capture?: typeof pageScreenshotCapture;
}
/**
* Prepare an isolated page for static-frame verification. Verification seeks
* intentionally visit frames out of capture order on a SEPARATE page that is
* never used for the real capture — out-of-order event-callback side effects
* are contained to this disposable page and cannot corrupt sequential capture.
*/
export async function createStaticVerificationPage(session: CaptureSession): Promise<Page> {
const page = await session.browser.newPage();
const pageNavigationTimeout =
session.config?.pageNavigationTimeout ?? DEFAULT_CONFIG.pageNavigationTimeout;
const pageReadyTimeout = session.config?.playerReadyTimeout ?? DEFAULT_CONFIG.playerReadyTimeout;
try {
await page.evaluateOnNewDocument(() => {
const w = window as unknown as { __name?: <T>(fn: T, _name: string) => T };
if (typeof w.__name !== "function") {
w.__name = <T>(fn: T, _name: string): T => fn;
}
});
if (session.options.variables && Object.keys(session.options.variables).length > 0) {
const variablesJson = JSON.stringify(session.options.variables);
await page.evaluateOnNewDocument((json: string) => {
(window as Window & { __hfVariables?: Record<string, unknown> }).__hfVariables =
JSON.parse(json);
}, variablesJson);
}
await installPageMotionBlur(page, session.options);
await page.setViewport({
width: session.options.width,
height: session.options.height,
deviceScaleFactor: session.options.deviceScaleFactor || 1,
});
await page.goto(`${session.serverUrl}/index.html`, {
waitUntil: "domcontentloaded",
timeout: pageNavigationTimeout,
});
await page.evaluate(`window.__hfFlushSync?.()`);
await pollHfReady(page, pageReadyTimeout);
await pollSubCompositionTimelines(page, pageReadyTimeout, {
getScriptLoadFailures: () => session.scriptLoadFailures,
knownUnregisteredIds: session.subTimelineWaitMemo.unregisteredIds,
});
await applyVideoMetadataHints(page, session.options.videoMetadataHints);
const skipVideoIds = session.options.skipReadinessVideoIds ?? [];
await Promise.all([
pollVideosReady(page, skipVideoIds, pageReadyTimeout),
pollImagesReady(page, pageReadyTimeout).then((ready) =>
ready ? decodeAllImages(page) : undefined,
),
page.evaluate(`document.fonts?.ready`),
waitForOptionalTailwindReady(page, pageReadyTimeout),
]);
if (session.options.format === "png") await initTransparentBackground(page);
return page;
} catch (error) {
await page.close().catch(() => {});
throw error;
}
}
/**
* Empirically verify the predicted-static set before trusting it. Group static frames
* into runs; each run [a..b] reuses anchor a-1. CRITICAL: compare against the ANCHOR,
* not the predecessor — a slow drift with sub-quantization per-frame deltas is byte-
* identical frame-to-frame yet drifts far from the anchor by the run's end (the real
* frozen error). Capture each run's anchor once, compare its end plus deterministic
* composition-wide points that preserve a 24-frame maximum gap; any mismatch ⇒ the
* run isn't truly static ⇒ disable dedup whole-comp. Capture-mode-
* independent (seeks + screenshots in normal DOM). Budget exhaustion may retain only
* runs whose anchor and every planned comparison completed successfully.
*/
export async function verifyStaticFramesSafe(
session: CaptureSession,
page: Page,
staticFrames: Set<number>,
fps: number,
sampleCount: number,
dependencies: StaticVerificationDependencies = {},
): Promise<StaticVerificationResult> {
const plan = planStaticVerification(staticFrames, sampleCount);
const now = dependencies.now ?? Date.now;
const capture = dependencies.capture ?? pageScreenshotCapture;
const startedAt = now();
const deadline = startedAt + STATIC_VERIFY_MAX_MS;
const verifiedFrames = new Set<number>();
const stats: StaticVerificationStats = {
plannedRuns: plan.runs.length,
completedRuns: 0,
plannedAnchors: plan.plannedAnchors,
completedAnchors: 0,
plannedComparisons: plan.plannedComparisons,
completedComparisons: 0,
seeks: 0,
screenshots: 0,
byteComparisons: 0,
elapsedMs: 0,
predictedFrames: plan.predictedFrames,
verifiedFrames: 0,
unverifiedFrames: plan.predictedFrames,
};
const finish = (
outcome: StaticVerificationOutcome,
badFrame?: number,
): StaticVerificationResult => ({
outcome,
verifiedFrames,
...(badFrame == null ? {} : { badFrame }),
stats,
});
if (plan.runs.length === 0) return finish("unprofitable");
const seekToFrame = async (frameIdx: number): Promise<void> => {
stats.seeks++;
const t = quantizeTimeToFrame(frameIdx / fps, fps);
await page.evaluate((tt: number) => {
const hf = (
window as unknown as {
__hf?: { seek?: (t: number, options?: { suppressEvents?: boolean }) => void };
}
).__hf;
if (hf && typeof hf.seek === "function") hf.seek(tt, { suppressEvents: false });
}, t);
};
const hardCap = Math.max(
STATIC_VERIFY_MIN_SCREENSHOT_CAP,
plan.effectiveSampleFloor * STATIC_VERIFY_SAMPLE_CAP_MULTIPLIER,
Math.ceil(plan.predictedFrames / STATIC_VERIFY_REFERENCE_STRIDE) * 3 + plan.runs.length,
);
const seekCapture = async (
frameIdx: number,
): Promise<Buffer | "time_budget" | "count_budget"> => {
if (now() >= deadline) return "time_budget";
if (stats.screenshots >= hardCap) return "count_budget";
await seekToFrame(frameIdx);
stats.screenshots++;
return capture(page, session.options);
};
// Verify profitable runs in deterministic savings order. A run is added to the armed
// set only after its anchor and every planner-selected comparison match. Budget exits
// retain completed runs; mismatch or infrastructure failure clears all verified frames.
try {
for (const run of plan.runs) {
const anchorBuf = await seekCapture(run.anchor);
if (typeof anchorBuf === "string") return finish(anchorBuf, run.a);
stats.completedAnchors++;
for (const f of run.comparisons) {
const cur = await seekCapture(f);
if (typeof cur === "string") return finish(cur, f);
stats.completedComparisons++;
stats.byteComparisons++;
if (!anchorBuf.equals(cur)) {
verifiedFrames.clear();
stats.verifiedFrames = 0;
stats.unverifiedFrames = plan.predictedFrames;
return finish("mismatch", f);
}
}
stats.completedRuns++;
for (let frame = run.a; frame <= run.b; frame++) verifiedFrames.add(frame);
stats.verifiedFrames = verifiedFrames.size;
stats.unverifiedFrames = plan.predictedFrames - verifiedFrames.size;
}
return finish("verified");
} catch {
verifiedFrames.clear();
stats.verifiedFrames = 0;
stats.unverifiedFrames = plan.predictedFrames;
return finish("infrastructure");
} finally {
await seekToFrame(0).catch(() => {});
stats.elapsedMs = Math.max(0, now() - startedAt);
}
}
/**
* 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
* the static set, anchor-verifies it (skip with HF_STATIC_DEDUP_VERIFY=false — unsafe),
* and on success stores it on the session for captureFrameCore to reuse. Sample budget
* via HF_STATIC_DEDUP_SAMPLES (default 24).
*/
async function armStaticDedup(
session: CaptureSession,
page: Page,
logInitPhase: (phase: string) => void,
): Promise<void> {
// Adaptive motion-blur sample-count classification shares the GSAP-timeline walk
// below but is gated independently of dedup (capture mode / before-capture hooks are
// about buffer-reuse safety, irrelevant to which properties a tween touches), so it
// is computed here, once, ahead of dedup's own idempotency check. Cached in
// `sharedStaticFrameStats` so dedup's own call further down does not repeat the walk.
// Reads `session.options.motionBlur` (the raw caller options), not `session.motionBlur`
// (the resolved plan) — every armStaticDedup call site runs before finalizeSessionInit
// resolves the plan, so the resolved field is never set yet at this point.
let sharedStaticFrameStats: Awaited<ReturnType<typeof computeStaticFrameSet>> | undefined;
if (
session.options.motionBlur &&
session.options.motionBlur.samplesPerFrame === undefined &&
!session.motionBlurNonSpatialFrames
) {
sharedStaticFrameStats = await computeStaticFrameSet(page, fpsToNumber(session.options.fps));
session.motionBlurNonSpatialFrames = sharedStaticFrameStats.nonSpatialOnlyFrameSet;
}
// 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;
// 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
// HF_STATIC_DEDUP) disables; a missing config leaves dedup enabled.
session.staticDedupEnabled = session.config?.staticFrameDedup !== false;
if (!session.staticDedupEnabled) return;
// Conservative gates: dedup is verified against the plain screenshot path, so only arm
// where the production capture matches what verification measures, and where reuse is
// sound. Skip when:
// - capture mode is not screenshot (BeginFrame advances the compositor clock per
// frame; skipping beginFrame for static frames gaps the tick sequence, and the
// verifier uses pageScreenshotCapture not beginFrameCapture — its proof wouldn't
// transfer);
// - a before-capture hook is set (per-frame video-frame injection — those frames are
// NOT static even if the GSAP timeline is idle, and the injector is skipped on reuse);
// - page-side compositing is active (shader transitions / drawElement composite paint
// a frame the plain verification screenshot doesn't reproduce).
if (session.captureMode !== "screenshot") {
session.staticDedupSkipReason = "capture_mode";
logInitPhase(
`static-frame dedup: disabled (capture mode ${session.captureMode}, not screenshot)`,
);
return;
}
if (session.onBeforeCapture) {
session.staticDedupSkipReason = "video_injection";
logInitPhase("static-frame dedup: disabled (before-capture hook / video injection active)");
return;
}
const pageComposite = await page
.evaluate(
() =>
typeof (window as unknown as { __hf_page_composite_prepare?: unknown })
.__hf_page_composite_prepare === "function",
)
.catch(() => true); // fail CLOSED: if we can't determine, assume compositing → skip dedup
if (pageComposite) {
session.staticDedupSkipReason = "page_composite";
logInitPhase("static-frame dedup: disabled (page-side compositing active)");
return;
}
const fps = fpsToNumber(session.options.fps);
const stats = sharedStaticFrameStats ?? (await computeStaticFrameSet(page, fps));
if (!stats.eligible || stats.staticFrameSet.size === 0) {
session.staticDedupSkipReason = "ineligible";
logInitPhase(`static-frame dedup: disabled (${stats.reason})`);
return;
}
const rawSamples = Number(process.env.HF_STATIC_DEDUP_SAMPLES ?? "24");
const samples = Number.isFinite(rawSamples) && rawSamples >= 1 ? rawSamples : 24;
session.staticDedupPredictedCount = stats.staticFrameSet.size;
if (process.env.HF_STATIC_DEDUP_VERIFY === "false") {
session.staticFrames = stats.staticFrameSet;
logInitPhase(
`static-frame dedup: ${stats.staticFrameSet.size}/${stats.totalFrames} frame(s) reusable ` +
`(verification explicitly disabled)`,
);
return;
}
let verificationPage: Page | undefined;
let verdict: StaticVerificationResult;
try {
verificationPage = await createStaticVerificationPage(session);
verdict = await verifyStaticFramesSafe(
session,
verificationPage,
stats.staticFrameSet,
fps,
samples,
);
} catch {
session.staticDedupSkipReason = "verification_failed";
logInitPhase("static-frame dedup: disabled (verification infrastructure failure)");
return;
} finally {
await verificationPage?.close().catch(() => {});
}
session.staticDedupVerification = verdict;
if (verdict.outcome === "mismatch" || verdict.outcome === "infrastructure") {
session.staticDedupSkipReason = "verification_failed";
logInitPhase(
verdict.outcome === "mismatch"
? `static-frame dedup: disabled (verification mismatch at predicted-static frame ${verdict.badFrame})`
: "static-frame dedup: disabled (verification infrastructure failure)",
);
return;
}
if (verdict.outcome === "unprofitable") {
session.staticDedupSkipReason = "unprofitable";
logInitPhase("static-frame dedup: disabled (verification cost cannot save captures)");
return;
}
if (verdict.verifiedFrames.size === 0) {
session.staticDedupSkipReason = "verification_budget";
logInitPhase(
`static-frame dedup: disabled (${verdict.outcome} before frame ${verdict.badFrame}; no run fully verified)`,
);
return;
}
session.staticFrames = verdict.verifiedFrames;
logInitPhase(
`static-frame dedup: ${verdict.verifiedFrames.size}/${stats.staticFrameSet.size} predicted frame(s) reusable ` +
`(outcome=${verdict.outcome}, runs=${verdict.stats.completedRuns}/${verdict.stats.plannedRuns}, ` +
`screenshots=${verdict.stats.screenshots}, seeks=${verdict.stats.seeks}, elapsedMs=${verdict.stats.elapsedMs})`,
);
}
/**
* Walk window.__timelines and collect frame intervals where GSAP tweens animate
* compositor-incompatible properties (blend-mode, 3D transforms, clip-path, mask).
* drawElement cannot reproduce these effects mid-tween → capture those frames via
* screenshot instead. opacity/filter fades were dropped from the set once Chrome 151
* fixed crbug 521861819.
*
* Returns the union of at-risk frame indices (±1 margin around each tween interval)
* and totalFrames (for fraction computation by the caller).
*/
async function computeTimelineAtRiskFrames(
page: Page,
fps: number,
): Promise<{ frames: Set<number>; totalFrames: number }> {
const result = await page.evaluate(() => {
// opacity/autoAlpha/filter fades were removed from this set once Chrome 151
// fixed crbug 521861819 (drawElementImage dropped promoted opacity layers
// mid-fade) — those now render correctly on the drawElement path. backdrop-filter
// and filter:blur stay gated by detectCssEffectRisk (architectural single-element
// capture limit, not 521861819). What remains here is the per-tween backstop for
// effects drawElementImage still cannot reproduce mid-animation: mix-blend-mode,
// CSS 3D transforms (crbug 522872457), clip-path, and mask.
const AT_RISK_PROPS = new Set([
"backdropFilter",
"backdrop-filter",
"mixBlendMode",
"mix-blend-mode",
"rotationX",
"rotationY",
"rotateX",
"rotateY",
"z",
"translateZ",
"clipPath",
"clip-path",
"maskImage",
"mask",
]);
type AnyTween = {
startTime(): number;
duration(): number;
vars?: Record<string, unknown>;
getChildren?(nested: boolean, tweens: boolean, timelines: boolean): AnyTween[];
};
function walkTimeline(
tl: AnyTween,
offset: number,
out: Array<{ start: number; end: number }>,
): void {
if (typeof tl.getChildren !== "function") return;
for (const child of tl.getChildren(false, true, true)) {
const childStart = offset + (typeof child.startTime === "function" ? child.startTime() : 0);
const childDur = typeof child.duration === "function" ? child.duration() : 0;
if (typeof child.getChildren === "function") {
walkTimeline(child, childStart, out);
} else {
const vars = child.vars || {};
if (Object.keys(vars).some((k) => AT_RISK_PROPS.has(k))) {
out.push({ start: childStart, end: childStart + childDur });
}
}
}
}
const w = window as unknown as {
__timelines?: Record<string, AnyTween>;
__hf?: { duration?: number };
};
const timelines = w.__timelines || {};
const intervals: Array<{ start: number; end: number }> = [];
for (const tl of Object.values(timelines)) {
if (tl && typeof tl.getChildren === "function") {
walkTimeline(tl, 0, intervals);
}
}
const duration = w.__hf?.duration ?? 0;
return { intervals, duration };
});
const { intervals, duration } = result as {
intervals: Array<{ start: number; end: number }>;
duration: number;
};
const frames = new Set<number>();
for (const { start, end } of intervals) {
const lo = Math.floor(start * fps) - 1;
const hi = Math.ceil(end * fps) + 1;
for (let f = Math.max(0, lo); f <= hi; f++) {
frames.add(f);
}
}
const totalFrames = Math.max(1, Math.ceil(duration * fps));
return { frames, totalFrames };
}
/**
* True for the drawElement `InvalidStateError: No cached paint record for element`
* thrown when a subtree element has no paint record for the current frame (display
* toggled / detached / freshly-shown at a clip-cut boundary). Per-frame, not
* whole-comp — callers fall back to screenshot for the single frame.
*
* This is a NATIVE Chrome DOMException (`drawElementImage`'s own error), so we
* can't bake a discriminant into it the way we can for our own thrown errors
* (see {@link isCanvasNotInitializedError}) — Puppeteer's `page.evaluate`
* error reconstruction also doesn't preserve a usable `.name` for it (comes
* back generic). Match on the FULL native phrase ("...for element"), not just
* the generic "No cached paint record" prefix, to cut the odds of an
* unrelated message coincidentally matching (review: substring-match footgun).
*/
function isNoCachedPaintRecordError(err: unknown): boolean {
const msg = err instanceof Error ? err.message : String(err);
return msg.includes("No cached paint record for element");
}
/**
* True for the drawElement "capture canvas isn't set up yet" error — thrown
* (or, on the batch path, returned as a string) by drawElementService when
* the injected capture canvas (`#__hf_de_canvas`) isn't set up yet (observed
* at frame 0 on some macOS/Chrome combinations, see #3423). Recoverable:
* the composition root IS present, so `pageScreenshotCapture` captures valid
* content.
*
* This is distinct from the composition-root-missing case
* (`HF_DE_COMPOSITION_ROOT_MISSING`), which is NOT recoverable — the page
* has no composition content to screenshot, so falling back would capture
* blank or navigated-away content.
*
* Matches the {@link DE_CANVAS_NOT_INITIALIZED_CODE} discriminant baked into
* the message (not free-text), so it survives `produceDrawElementFrameBatch`'s
* "batch produce failed at frame N: <code>: ..." wrapping.
*/
function isCanvasNotInitializedError(err: unknown): boolean {
const msg = err instanceof Error ? err.message : String(err);
return msg.includes(DE_CANVAS_NOT_INITIALIZED_CODE);
}
/**
* Single gate for drawElement failures the fast-capture pipeline knows how to
* recover from by falling back to screenshot capture instead of aborting the
* render. Both {@link captureFrameCore} and {@link captureFrameToBufferPipelined}
* consult this so a newly-recognized recoverable error only needs to be taught
* here once.
*/
function isRecoverableDrawElementError(err: unknown): boolean {
return isNoCachedPaintRecordError(err) || isCanvasNotInitializedError(err);
}
/**
* Per-frame deadline for the drawElement capture round-trip.
*
* drawElementImage can return normally and then leave the renderer not draining
* its task queue: the `setTimeout(…, 0)` that drawAndEncode schedules to run
* `toDataURL` never fires, so the capture `page.evaluate` never settles.
* Reproduced deterministically on Chromium 152.0.7977.30, one comp, always the
* same frame (PRINFRA-488). Nothing below the render-level watchdog bounded
* this, so a single bad frame failed the ENTIRE render after a 60 s stall.
*
* This bounds the round-trip so the producer can discard the wedged page and
* retry the whole render on a fresh screenshot session. A per-frame screenshot
* cannot recover because the same page has stopped scheduling. Tune with
* `HF_DE_FRAME_TIMEOUT_MS`; 0 disables.
*/
const DE_FRAME_TIMEOUT_MS = Number(process.env.HF_DE_FRAME_TIMEOUT_MS ?? "15000");
class DeFrameTimeoutError extends Error {
constructor(label: string, ms: number) {
super(`drawElement ${label} exceeded ${ms}ms (renderer stopped scheduling; see PRINFRA-488)`);
this.name = "DeFrameTimeoutError";
}
}
/**
* Race `work` against a deadline. The losing promise is NOT cancellable —
* puppeteer cannot abort an in-flight `page.evaluate` — so its rejection is
* swallowed to avoid an unhandled rejection when it eventually settles (or
* never does). The orphaned round-trip keeps running in its Chrome worker;
* that worker is reclaimed by the outer retry rebuilding the page
* (`closeOrphanedProbeForRetry`), not by anything here.
*
* `onTimeout` fires exactly when the deadline wins, and is the ONLY place the
* stall is observable: because the deadline races `work` from outside, nothing
* inside `work` — including its own catch blocks — ever sees this error.
*
* Exported for the deadline unit test; `captureFrameToBuffer` is the only
* production caller.
*/
export async function withFrameDeadline<T>(
work: Promise<T>,
label: string,
ms: number,
onTimeout?: () => void,
): Promise<T> {
if (!(ms > 0)) return work;
let timer: ReturnType<typeof setTimeout> | undefined;
const guard = new Promise<never>((_resolve, reject) => {
timer = setTimeout(() => {
onTimeout?.();
reject(new DeFrameTimeoutError(label, ms));
}, ms);
});
try {
return await Promise.race([work, guard]);
} finally {
if (timer) clearTimeout(timer);
void work.catch(() => {
/* orphaned round-trip — see doc above */
});
}
}
/**
* Resolve the session's motion-blur plan, rejecting combinations the accumulation pass
* cannot render correctly instead of silently producing an unblurred frame.
*
* Called once initialization has settled the capture mode. `format: "png"` is required
* because samples are averaged pixel by pixel: JPEG samples would be averaged after
* lossy quantization and the blended frame is re-encoded as PNG.
*/
export function resolveSessionMotionBlur(session: CaptureSession): MotionBlurPlan | undefined {
const plan = resolveMotionBlurPlan(session.options.motionBlur);
if (!plan) return undefined;
if (session.captureMode !== "screenshot") {
throw new Error(
`[MotionBlur] sub-frame motion blur requires screenshot capture mode, got "${session.captureMode}"`,
);
}
if (session.options.format !== "png") {
throw new Error(
`[MotionBlur] sub-frame motion blur requires format "png", got "${session.options.format ?? "jpeg"}"`,
);
}
return plan;
}
/** Frame timings shared by the single-capture and accumulation paths. */
interface CapturedSurface {
buffer: Buffer;
quantizedTime: number;
seekMs: number;
beforeCaptureMs: number;
screenshotMs: number;
}
/** Seek to `time` and capture one surface with the session's capture mode. */
async function captureFrameSurface(
session: CaptureSession,
frameIndex: number,
time: number,
seekOptions?: HfSeekOptions,
heldVideoTime?: number,
): Promise<CapturedSurface> {
const { page, options } = session;
const { quantizedTime, seekMs, beforeCaptureMs } = await prepareFrameForCapture(
session,
frameIndex,
time,
seekOptions,
heldVideoTime,
);
const screenshotStart = Date.now();
let screenshotBuffer: Buffer;
if (session.captureMode === "beginframe") {
const frameTimeTicks = session.beginFrameTimeTicks + frameIndex * session.beginFrameIntervalMs;
if (!session.beginFrameSeekPresented) {
// A session's first capture can return the frame composited during init instead of
// this seek, so display the seek once at a tick between the probe and this capture.
const client = await getCdpSession(page);
await client.send("HeadlessExperimental.beginFrame", {
frameTimeTicks: frameTimeTicks - session.beginFrameIntervalMs / 2,
interval: session.beginFrameIntervalMs,
noDisplayUpdates: false,
});
session.beginFrameSeekPresented = true;
}
const result = await beginFrameCapture(
page,
options,
frameTimeTicks,
session.beginFrameIntervalMs,
);
if (result.hasDamage) session.beginFrameHasDamageCount++;
else session.beginFrameNoDamageCount++;
screenshotBuffer = result.buffer;
} else if (
session.captureMode === "drawelement" &&
session.clipBoundaryFrames?.has(frameIndex) &&
process.env.HF_FAST_CAPTURE_BOUNDARY_SS === "true"
) {
throw new DrawElementCaptureError(
frameIndex,
"boundary screenshot requested on an injected canvas page",
);
} else if (session.captureMode === "drawelement") {
// Advance compositor state via BeginFrame when available (Linux headless-shell);
// on macOS the compositor advances naturally without BeginFrame.
if (session.beginFrameTimeTicks > 0) {
const client = await getCdpSession(page);
await client.send("HeadlessExperimental.beginFrame", {
frameTimeTicks: session.beginFrameTimeTicks + frameIndex * session.beginFrameIntervalMs,
interval: session.beginFrameIntervalMs,
noDisplayUpdates: false,
// no screenshot param — we capture via canvas
});
}
try {
screenshotBuffer = await captureDrawElementFrame(
page,
options.width,
options.height,
options.format ?? "jpeg",
options.quality ?? 80,
// Paint-event sync only without BeginFrame (macOS / screenshot-launched):
// under BeginFrame control the per-frame beginFrame above already painted
// a fresh snapshot, and no further paint would arrive during a wait.
session.beginFrameTimeTicks === 0,
);
// A tiny JPEG may be a dropped paint record. Never screenshot this page:
// its injected canvas can still hold the preceding frame's bitmap.
// Restart on a fresh screenshot page even if this was a simple valid frame.
if ((options.format ?? "jpeg") !== "png" && process.env.HF_FORCE_DRAWELEMENT !== "1") {
const sizes = (session.deFrameSizes ??= []);
const sorted = sizes.length >= 12 ? [...sizes].sort((a, b) => a - b) : null;
const median = sorted ? (sorted[sorted.length >> 1] ?? 0) : 0;
const floor = Math.max(20000, median * 0.12);
if (screenshotBuffer.length < floor) {
throw new DrawElementCaptureError(
frameIndex,
`suspect small frame (${screenshotBuffer.length}B < ${Math.round(floor)}B)`,
);
} else {
if (sizes.length >= 60) sizes.shift();
sizes.push(screenshotBuffer.length);
}
}
} catch (err) {
// Missing paint records/canvas state require a new screenshot page.
if (isRecoverableDrawElementError(err)) {
session.deNcprFallbacks = (session.deNcprFallbacks ?? 0) + 1;
const reason = isCanvasNotInitializedError(err)
? "drawElement canvas not initialized"
: "No cached paint record";
throw new DrawElementCaptureError(frameIndex, reason, err);
} else {
throw err;
}
}
} else {
screenshotBuffer = await pageScreenshotCapture(page, options);
}
const screenshotMs = Date.now() - screenshotStart;
return { buffer: screenshotBuffer, quantizedTime, seekMs, beforeCaptureMs, screenshotMs };
}
/**
* Mark the session ready to capture.
*
* The single owner of what finishing initialization means, because `initializeSession`
* has two exits: screenshot mode returns early, and every other mode falls through the
* end. Resolving motion blur at only one of them marks the session ready with no plan,
* which silently renders unblurred rather than failing. Both fields are set here so a
* third exit cannot forget one.
*/
function finalizeSessionInit(session: CaptureSession): void {
session.motionBlur = resolveSessionMotionBlur(session);
session.isInitialized = true;
startChromeMemorySampler(session);
}
/** Shape of one `SystemInfo.getProcessInfo` row; only the fields we read. */
export interface CdpProcessInfoRow {
type: string;
id: number;
cpuTime: number;
}
/** Group Chrome child pids by role. `browser` comes from puppeteer, not CDP. */
export function classifyChromeProcesses(
browserPid: number | undefined,
processInfo: readonly CdpProcessInfoRow[],
): ChromePids {
const renderers: number[] = [];
const gpu: number[] = [];
for (const row of processInfo) {
if (row.type === "renderer") renderers.push(row.id);
else if (row.type === "GPU") gpu.push(row.id);
}
return browserPid === undefined ? { renderers, gpu } : { browser: browserPid, renderers, gpu };
}
/** The slice of a CDP session `readChromePids` needs. */
interface ProcessInfoCdpSession {
send(method: "SystemInfo.getProcessInfo"): Promise<{
processInfo: readonly CdpProcessInfoRow[];
}>;
detach(): Promise<void>;
}
/**
* Chrome pids for one browser. `SystemInfo.getProcessInfo` is served ONLY by
* the browser target — a page-target session rejects with "is only supported
* on the browser target", which the sampler would swallow into a permanently
* empty reading. Hence the explicit browser-session factory.
*/
export async function readChromePids(
browserPid: number | undefined,
createBrowserCdpSession: () => Promise<ProcessInfoCdpSession>,
): Promise<ChromePids> {
const cdp = await createBrowserCdpSession();
try {
const info = await cdp.send("SystemInfo.getProcessInfo");
return classifyChromeProcesses(browserPid, info.processInfo);
} finally {
await cdp.detach().catch(() => {});
}
}
const CHROME_MEMORY_SAMPLE_MS_DEFAULT = 2_000;
function resolveChromeMemorySampleMs(): number {
const raw = process.env.HF_CHROME_MEMORY_SAMPLE_MS;
const parsed = raw === undefined ? Number.NaN : Number(raw);
return Number.isFinite(parsed) && parsed >= 250 ? parsed : CHROME_MEMORY_SAMPLE_MS_DEFAULT;
}
function startChromeMemorySampler(session: CaptureSession): void {
if (session.chromeMemory) return;
if (process.env.HF_CHROME_MEMORY_SAMPLER === "false") return;
const sampler = createChromeMemorySampler({
intervalMs: resolveChromeMemorySampleMs(),
onSample: session.options.onMemorySample,
sampleRss: (pids) => sampleProcessRss(pids),
getPids: () =>
readChromePids(session.browser.process()?.pid, () =>
session.browser.target().createCDPSession(),
),
});
session.chromeMemory = sampler;
sampler.start();
}
/** Choose how many samples this frame gets when the plan is adaptive: the floor with
* no probe for a frame confirmed non-spatial, otherwise two edge probes (see
* motionBlurProbeTimes) mapped through adaptiveSampleCount. Probe cost is returned
* alongside the count so the caller folds it into the frame's timing totals. */
async function resolveAdaptiveSampleCount(
session: CaptureSession,
frameIndex: number,
absFrameIndex: number,
plan: MotionBlurPlan,
fps: number,
sampleSeek: HfSeekOptions,
frameTime: number,
): Promise<{
samplesPerFrame: number;
seekMs: number;
beforeCaptureMs: number;
screenshotMs: number;
}> {
if (session.motionBlurNonSpatialFrames?.has(absFrameIndex)) {
return {
samplesPerFrame: DEFAULT_SAMPLES_PER_FRAME,
seekMs: 0,
beforeCaptureMs: 0,
screenshotMs: 0,
};
}
const { windowStart, windowEnd } = motionBlurProbeTimes(plan, absFrameIndex, fps);
const probeA = await captureFrameSurface(session, frameIndex, windowStart, sampleSeek, frameTime);
const probeB = await captureFrameSurface(session, frameIndex, windowEnd, sampleSeek, frameTime);
return {
samplesPerFrame: adaptiveSampleCount(probeDiffMagnitude(probeA.buffer, probeB.buffer)),
seekMs: probeA.seekMs + probeB.seekMs,
beforeCaptureMs: probeA.beforeCaptureMs + probeB.beforeCaptureMs,
screenshotMs: probeA.screenshotMs + probeB.screenshotMs,
};
}
/**
* Capture one output frame as the average of some number of sub-frame captures — fixed
* by the caller, or chosen per frame from measured motion (see
* `resolveAdaptiveSampleCount`).
*
* Callback invariant: exactly one eventful seek per output frame, at the frame time,
* arriving from the previous frame's time. Every sample seek (including a probe)
* suppresses events and the playhead is restored to the frame time afterwards, so a
* composition's own onUpdate/onComplete fire on the same interval boundaries as a
* render with blur off.
*/
async function captureAccumulatedFrame(
session: CaptureSession,
frameIndex: number,
absFrameIndex: number,
plan: MotionBlurPlan,
): Promise<CapturedSurface> {
const fps = fpsToNumber(session.options.fps);
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;
}
const sampleSeek: HfSeekOptions = {
suppressEvents: true,
subFrameDivisions: plan.subFrameDivisions,
};
let samplesPerFrame = plan.fixedSamplesPerFrame;
if (samplesPerFrame === null) {
const chosen = await resolveAdaptiveSampleCount(
session,
frameIndex,
absFrameIndex,
plan,
fps,
sampleSeek,
frameTime,
);
samplesPerFrame = chosen.samplesPerFrame;
totals.seekMs += chosen.seekMs;
totals.beforeCaptureMs += chosen.beforeCaptureMs;
totals.screenshotMs += chosen.screenshotMs;
}
const accumulator = new MotionBlurAccumulator(plan.blend);
for (const sampleTime of motionBlurSampleTimes(plan, absFrameIndex, fps, samplesPerFrame)) {
const sample = await captureFrameSurface(
session,
frameIndex,
sampleTime,
sampleSeek,
frameTime,
);
totals.seekMs += sample.seekMs;
totals.beforeCaptureMs += sample.beforeCaptureMs;
totals.screenshotMs += sample.screenshotMs;
accumulator.add(sample.buffer);
}
const restoreSeekStart = Date.now();
session.captureStep = "seeking the timeline";
await seekPageTimeline(session.page, frameTime, { suppressEvents: true });
totals.seekMs += Date.now() - restoreSeekStart;
const blended = accumulator.finish();
return {
buffer: encodePng(blended.width, blended.height, blended.data),
quantizedTime: frameTime,
...totals,
};
}
async function captureFrameCore(
session: CaptureSession,
frameIndex: number,
time: number,
): Promise<{ buffer: Buffer; quantizedTime: number; captureTimeMs: number }> {
const { options } = session;
const startTime = Date.now();
// Static-frame dedup: this frame is byte-identical to its predecessor (predicted +
// anchor-verified at init) → reuse the prior buffer, skip the seek + screenshot.
// KEY: index by the ABSOLUTE composition frame (derived from `time`), NOT the
// `frameIndex` arg — chunked/parallel/distributed callers pass a chunk-RELATIVE
// frameIndex (captureStage passes the loop `i`, parallelCoordinator passes
// `i-outputFrameOffset`) while staticFrames is keyed in absolute frames. Using `time`
// is correct on every path (sequential, per-worker range, distributed chunk) because
// `time` is always the absolute composition time for the frame. Each session captures
// its range in ascending order, so lastFrameBuffer is the correct in-range anchor (and
// since a static run is verified identical, reusing the run's first in-range capture
// equals reusing the global anchor). Telemetry: count reuses separately; do NOT bump
// capturePerf.frames (that would dilute the per-frame timing averages).
// Use the SAME floor+epsilon idiom as quantizeTimeToFrame so the dedup lookup agrees
// with the frame the seek actually lands on, even if `time` ever isn't exactly i/fps.
const absFrameIndex = Math.floor(time * fpsToNumber(options.fps) + 1e-9);
if (
session.staticFrames?.has(absFrameIndex) &&
session.lastFrameBuffer &&
session.lastFrameAbsoluteIndex === absFrameIndex - 1 &&
(!session.motionBlur ||
motionBlurWindowIsStatic(session.motionBlur, absFrameIndex, session.staticFrames))
) {
session.staticDedupCount = (session.staticDedupCount ?? 0) + 1;
session.lastFrameAbsoluteIndex = absFrameIndex;
return {
buffer: session.lastFrameBuffer,
quantizedTime: quantizeTimeToFrame(time, fpsToNumber(options.fps)),
captureTimeMs: Date.now() - startTime,
};
}
try {
const plan = session.motionBlur;
// One capture per frame, or `plan.samplesPerFrame` captures averaged into one. Both
// report the same timings, so perf accounting and the dedup anchor stay shared.
const { buffer, quantizedTime, seekMs, beforeCaptureMs, screenshotMs } = plan
? await captureAccumulatedFrame(session, frameIndex, absFrameIndex, plan)
: await captureFrameSurface(session, frameIndex, time);
const captureTimeMs = Date.now() - startTime;
session.capturePerf.frames += 1;
session.capturePerf.seekMs += seekMs;
session.capturePerf.beforeCaptureMs += beforeCaptureMs;
session.capturePerf.screenshotMs += screenshotMs;
session.capturePerf.totalMs += captureTimeMs;
session.capturePerf.frameMs.push(captureTimeMs);
if (session.capturePerf.frames === 1) {
const blur = await describePageMotionBlur(session.page).catch(() => null);
if (blur) console.log(blur);
}
// Retain this freshly-captured buffer so the following static frames can reuse it.
if (session.staticFrames) {
session.lastFrameBuffer = buffer;
session.lastFrameAbsoluteIndex = absFrameIndex;
}
return { buffer, quantizedTime, captureTimeMs };
} catch (captureError) {
if (session.isInitialized) {
await captureFrameErrorDiagnostics(
session,
frameIndex,
time,
captureError instanceof Error ? captureError : new Error(String(captureError)),
);
}
throw captureError;
}
}
export async function captureFrame(
session: CaptureSession,
frameIndex: number,
time: number,
): Promise<CaptureResult> {
const { buffer, quantizedTime, captureTimeMs } = await captureFrameCore(
session,
frameIndex,
time,
);
const framePath = writeCapturedFrame(session, frameIndex, buffer);
return { frameIndex, time: quantizedTime, path: framePath, captureTimeMs };
}
/**
* File extension for a captured frame, keyed on the format the frames were actually
* captured in. The encoder's input pattern and the writer must agree, so both read this
* rather than re-deriving the answer from whether the OUTPUT needs alpha, which is a
* different question and stops being equivalent as soon as anything else forces PNG.
*/
export function frameFileExtension(format: "jpeg" | "png" | undefined): "png" | "jpg" {
return format === "png" ? "png" : "jpg";
}
/**
* Write an already-captured frame buffer to the session's output dir using the
* canonical `frame_NNNNNN.{jpg,png}` naming. `fileIndex` is the ENCODER-facing
* index (0-based within the captured range), which may differ from the absolute
* composition frame index used for seeking/boundary lookups. Extracted so the
* disk worker-encode pipeline can write a buffer produced by
* `captureFrameToBufferPipelined` without duplicating the naming convention.
*/
export function writeCapturedFrame(
session: CaptureSession,
fileIndex: number,
buffer: Buffer,
): string {
const ext = frameFileExtension(session.options.format);
const framePath = join(session.outputDir, `frame_${String(fileIndex).padStart(6, "0")}.${ext}`);
writeFileSync(framePath, buffer);
return framePath;
}
/**
* Capture a frame and return the screenshot as a Buffer instead of writing to disk.
* Used by the streaming encode pipeline to pipe frames directly to FFmpeg stdin.
*/
export async function captureFrameToBuffer(
session: CaptureSession,
frameIndex: number,
time: number,
): Promise<CaptureBufferResult> {
const { buffer, captureTimeMs } =
session.captureMode === "drawelement"
? await withFrameDeadline(
captureFrameCore(session, frameIndex, time),
`frame ${frameIndex}`,
DE_FRAME_TIMEOUT_MS,
() => {
// Deliberately NO per-frame screenshot fallback. When the renderer
// stops scheduling it is wedged for EVERY subsequent round-trip on
// that page — measured: the screenshot fallback blew the same
// deadline. Fail fast and let the producer re-render the whole comp
// on a fresh page via the screenshot path, the only recovery that
// works. Counted here rather than in captureFrameCore's catch: the
// deadline rejects from outside it, so that catch never runs.
session.deFrameTimeouts = (session.deFrameTimeouts ?? 0) + 1;
console.log(
`[engine] fast capture frame ${frameIndex}: capture exceeded ` +
`${DE_FRAME_TIMEOUT_MS}ms; renderer stalled after drawElementImage ` +
`(PRINFRA-488). Failing the drawElement attempt so the whole render ` +
`retries via screenshot.`,
);
},
)
: await captureFrameCore(session, frameIndex, time);
return { buffer, captureTimeMs };
}
/**
* Pipelined drawElement frame capture for the worker-encode path.
*
* Performs seek prep + paint-wait + drawElementImage + composite +
* `createImageBitmap` + transfers the bitmap to the in-page encode worker.
* Returns `encodeResult` immediately (before the worker finishes encoding).
* The caller overlaps frame N's encode with frame N+1's produce phase.
*
* Requirements:
* - `session.workerEncodeEnabled` must be true (set by initializeSession when
* `config.enableDrawElementWorkerEncode` is true and mode resolved to drawelement).
* - JPEG format only. PNG falls back to `captureFrameToBuffer`.
* - macOS hardware GPU path (syncToPaintEvent=true, beginFrameTimeTicks=0).
* BeginFrame (Linux) uses the standard synchronous path unchanged.
*/
/**
* Worker-encode path, gated to drawElement capture. It does not route through
* `captureFrameCore` and so has no accumulation branch; that is safe only because
* `resolveSessionMotionBlur` rejects every capture mode except screenshot, which makes
* this function unreachable with motion blur on. Widening the supported capture modes
* means handling accumulation here too.
*/
export async function captureFrameToBufferPipelined(
session: CaptureSession,
frameIndex: number,
time: number,
): Promise<{ encodeResult: Promise<Buffer>; captureTimeMs: number }> {
const { page, options } = session;
const startTime = Date.now();
// Task B: static-frame dedup (worker path). Reuse the prior frame's encode result
// and skip the seek + drawElement + encode entirely. Same predicate as the serial
// path; clip-cut frames are excluded from staticFrames so they always capture.
if (session.staticFrames?.has(frameIndex) && session.lastEncodeResult) {
// Reuse is valid only when EVERY frame in (lastEncodeResultFrame, i] is
// predicted-static — then all of them (and the reused buffer) share the
// same pixels. Sequential capture reduces to has(i) (gap = {i}); the
// interleaved parallel stride makes the gap N frames wide.
const lastIdx = session.lastEncodeResultFrame ?? frameIndex - 1;
let gapStatic = true;
for (let j = lastIdx + 1; j <= frameIndex; j++) {
if (!session.staticFrames.has(j)) {
gapStatic = false;
break;
}
}
if (gapStatic) {
session.staticDedupCount = (session.staticDedupCount ?? 0) + 1;
session.capturePerf.frames += 1;
// Advance the watermark on reuse too, not just on real captures — the
// gap-check above starts from lastEncodeResultFrame, so leaving it
// pinned to the last REAL capture makes every consecutive reuse rescan
// an ever-widening window instead of just the one new frame (review).
session.lastEncodeResultFrame = frameIndex;
return { encodeResult: session.lastEncodeResult, captureTimeMs: Date.now() - startTime };
}
}
try {
const { quantizedTime, seekMs, beforeCaptureMs } = await prepareFrameForCapture(
session,
frameIndex,
time,
);
void quantizedTime;
if (
session.clipBoundaryFrames?.has(frameIndex) &&
process.env.HF_FAST_CAPTURE_BOUNDARY_SS === "true"
) {
throw new DrawElementCaptureError(
frameIndex,
"boundary screenshot requested on an injected canvas page",
);
}
// Worker-encode is gated to the macOS GPU path (beginFrameTimeTicks === 0,
// syncToPaintEvent = true); see initDrawElementOrTransparentBackground. The
// BeginFrame branch present in the synchronous captureFrameCore is therefore
// unreachable here and intentionally omitted.
const { encodeResult } = await produceDrawElementFrame(
page,
options.width,
options.height,
options.quality ?? 80,
true,
);
const captureTimeMs = Date.now() - startTime;
session.capturePerf.frames += 1;
session.capturePerf.seekMs += seekMs;
session.capturePerf.beforeCaptureMs += beforeCaptureMs;
// screenshotMs reflects produce time only (encode is async, not tracked here)
session.capturePerf.screenshotMs += captureTimeMs - seekMs - beforeCaptureMs;
session.capturePerf.totalMs += captureTimeMs;
session.capturePerf.frameMs.push(captureTimeMs);
// Task B: retain this encode result so a following static frame can reuse it.
if (session.staticFrames) {
session.lastEncodeResult = encodeResult;
session.lastEncodeResultFrame = frameIndex;
}
return { encodeResult, captureTimeMs };
} catch (captureError) {
// Mirror captureFrameCore: capture per-frame diagnostics (frame-error
// PNG/HTML/JSON + console tail) before rethrowing so pipelined-path
// failures are debuggable like the serial path. Runs BEFORE the
// recoverable-error wrapper below because the serial path's diagnostics
// sit in an outer catch that its own DrawElementCaptureError throw
// propagates through — ordering it after the wrapper would silently skip
// the bundle for exactly the NCPR/canvas failures worth debugging.
// Bounded: a recoverable error aborts the whole attempt, so this fires at
// most once per attempt. captureFrameErrorDiagnostics self-catches, so a
// dead page cannot mask the structural error the producer retries on.
if (session.isInitialized) {
await captureFrameErrorDiagnostics(
session,
frameIndex,
time,
captureError instanceof Error ? captureError : new Error(String(captureError)),
);
}
// The viewport can contain the last injected bitmap, not the sought frame.
if (isRecoverableDrawElementError(captureError)) {
session.deNcprFallbacks = (session.deNcprFallbacks ?? 0) + 1;
const reason = isCanvasNotInitializedError(captureError)
? "drawElement canvas not initialized"
: "No cached paint record";
throw new DrawElementCaptureError(frameIndex, reason, captureError);
}
throw captureError;
}
}
/**
* Verification-grade single-frame recapture for the producer's blank-frame
* guard. Unlike {@link captureFrameToBufferPipelined} it takes NO shortcuts
* and has NO fallbacks, both of which can return the WRONG FRAME's pixels at
* drain time:
* - the static-dedup fast path returns session.lastEncodeResult, which by
* drain time can hold a frame several indices AHEAD of the suspect frame;
* - a screenshot of the injected page may hold the LAST drawn drawElement
* frame, not this one. Capture failures therefore require a fresh page.
* Any failure here throws; the caller treats that as verification failure and
* falls back the whole render (correct, never wrong-frame).
*/
export async function recaptureDrawElementFrameForVerify(
session: CaptureSession,
frameIndex: number,
time: number,
): Promise<Buffer> {
const { page, options } = session;
if (!session.isInitialized) {
throw new Error("[FrameCapture] Session not initialized");
}
await prepareFrameForCapture(session, frameIndex, time);
const { encodeResult } = await produceDrawElementFrame(
page,
options.width,
options.height,
options.quality ?? 80,
true,
);
return encodeResult;
}
/**
* P6 prototype (HF_DE_BATCH): capture N consecutive frames in one CDP
* round-trip via {@link produceDrawElementFrameBatch}. The caller pre-plans the
* batch (consecutive frame indices, none static-dedup'd, none opt-in
* boundary-screenshot). On a mid-batch in-page failure the remaining frames'
* handling depends on whether the failure is one of the recoverable
* per-frame drawElement conditions (canvas-not-initialized / no-cached-paint-
* record, #3423):
* - Recoverable: reject the batch with DrawElementCaptureError so the producer
* re-renders on a fresh screenshot page. The injected canvas is not a valid
* screenshot fallback surface.
* - Anything else (unrecognized error): fall through to
* {@link captureFrameToBufferPipelined}, which re-attempts drawElement (so
* a genuinely transient, non-drawElement-specific failure still gets a
* second chance) and owns the same recoverable-error/fatal-error split for
* whatever it encounters — so failure behavior for a truly fatal error is
* identical to the unbatched path, just discovered at batch granularity.
*/
export async function captureFramesBatchPipelined(
session: CaptureSession,
frameIndices: number[],
times: number[],
): Promise<Array<{ frameIndex: number; encodeResult: Promise<Buffer> }>> {
const { page, options } = session;
if (!session.isInitialized) {
throw new Error("[FrameCapture] Session not initialized");
}
assertVfxIntact(session);
const startTime = Date.now();
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,
options.width,
options.height,
options.quality ?? 80,
);
// A later batch failure abandons this prefix. Its asynchronous encodes can
// still reject while session cleanup shuts the worker down.
for (const result of encodeResults) void result.catch(() => {});
const okCount = failedAt === null ? frameIndices.length : failedAt;
const elapsed = Date.now() - startTime;
session.capturePerf.frames += okCount;
// Round-trips are fused — attribute the whole batch to produce time; each
// frame gets the batch mean for the per-frame sample series.
session.capturePerf.screenshotMs += elapsed;
session.capturePerf.totalMs += elapsed;
if (okCount > 0) {
const perFrame = elapsed / okCount;
for (let s2 = 0; s2 < okCount; s2++) session.capturePerf.frameMs.push(perFrame);
}
const results: Array<{ frameIndex: number; encodeResult: Promise<Buffer> }> = [];
for (let i = 0; i < okCount; i++) {
const frameIndex = frameIndices[i];
const encodeResult = encodeResults[i];
if (frameIndex === undefined || !encodeResult) break;
results.push({ frameIndex, encodeResult });
}
if (failedAt !== null) {
// `error` is a plain string here (produceDrawElementFrameBatch returns it
// out of an in-page evaluate rather than throwing an Error instance) —
// isRecoverableDrawElementError accepts `unknown` and stringifies non-Error
// input, so passing the string straight through classifies it correctly,
// including through produceDrawElementFrameBatch's own error text (which
// embeds the same DE_CANVAS_NOT_INITIALIZED_CODE / native paint-record
// phrase the per-frame paths match on).
if (isRecoverableDrawElementError(error)) {
const reason = isCanvasNotInitializedError(error)
? "drawElement canvas not initialized"
: "No cached paint record";
session.deNcprFallbacks = (session.deNcprFallbacks ?? 0) + 1;
throw new DrawElementCaptureError(frameIndices[failedAt] ?? failedAt, reason, error);
} else {
console.log(
`[engine] fast capture: batch produce failed at frame ` +
`${frameIndices[failedAt] ?? "?"} (${error ?? "?"}); ` +
`re-capturing ${frameIndices.length - failedAt} frame(s) per-frame`,
);
for (let i = failedAt; i < frameIndices.length; i++) {
const frameIndex = frameIndices[i];
const time = times[i];
if (frameIndex === undefined || time === undefined) break;
const { encodeResult } = await captureFrameToBufferPipelined(session, frameIndex, time);
results.push({ frameIndex, encodeResult });
}
}
}
// Task B: retain the last encode result so a following static frame can reuse it.
const last = results[results.length - 1];
if (session.staticFrames && last) session.lastEncodeResult = last.encodeResult;
return results;
}
/**
* Type of the "inner capture" function consumed by
* {@link discardWarmupCapture}. Matches the real `captureFrameCore` signature
* with the buffer-bearing result trimmed to what the caller actually uses
* (the wrapper never inspects the buffer). Exposed so unit tests can inject
* a stub instead of driving Chrome end-to-end.
*/
export type DiscardWarmupInnerCapture = (
session: CaptureSession,
frameIndex: number,
time: number,
) => Promise<{ buffer: Buffer; quantizedTime: number; captureTimeMs: number }>;
/**
* Perform one capture, throw away the buffer, and restore any session
* side-effects (perf counters, BeginFrame damage tallies) so downstream
* captures see state identical to a fresh session.
*
* Distributed chunk workers need this because Chrome's BeginFrame screenshot
* pipeline maintains a per-process `lastFrameCache`: when a captured frame's
* `hasDamage` reports `false`, the screenshot path returns the previously
* captured buffer. For chunk N (N > 0) the worker has no prior frame in its
* cache, so the very first capture's `hasDamage` reporting diverges from
* what an in-process render at the same absolute frame index would see (the
* in-process renderer always has frame N-1 cached). One discard capture
* before the first real capture primes the cache.
*
* The function intentionally restores perf state so the warmup capture does
* NOT bias `getCapturePerfSummary()`'s per-frame averages.
*
* No file is written; the buffer is discarded.
*
* @param session — initialized capture session
* @param frameIndex — frame index to warm up with (default 0). Chunk
* workers typically pass their chunk's first absolute frame index.
* @param time — time in seconds (default 0). Chunk workers typically pass
* the corresponding `frameIndex / fps`.
* @param innerCapture — injectable for tests; defaults to the real
* `captureFrameCore`.
*/
export async function discardWarmupCapture(
session: CaptureSession,
frameIndex: number = 0,
time: number = 0,
innerCapture: DiscardWarmupInnerCapture = captureFrameCore,
): Promise<void> {
// The discarded capture mutates frameMs, so preserve its samples by value.
const perfBefore = { ...session.capturePerf, frameMs: [...session.capturePerf.frameMs] };
const hasDamageBefore = session.beginFrameHasDamageCount;
const noDamageBefore = session.beginFrameNoDamageCount;
const dedupCountBefore = session.staticDedupCount;
const lastFrameBufferBefore = session.lastFrameBuffer;
const lastFrameAbsoluteIndexBefore = session.lastFrameAbsoluteIndex;
try {
await innerCapture(session, frameIndex, time);
} finally {
// Always restore — even on error. A failed warmup capture should not
// leak inflated perf counters, a phantom dedup reuse, or a warmup-era
// lastFrameBuffer anchor into the real capture summary/state.
session.capturePerf = perfBefore;
session.beginFrameHasDamageCount = hasDamageBefore;
session.beginFrameNoDamageCount = noDamageBefore;
session.staticDedupCount = dedupCountBefore;
session.lastFrameBuffer = lastFrameBufferBefore;
session.lastFrameAbsoluteIndex = lastFrameAbsoluteIndexBefore;
}
}
export async function closeCaptureSession(session: CaptureSession): Promise<void> {
if (session.chromeMemory) {
session.chromeMemory.stop();
// One last sample so the summary reflects the session's end state, not a
// point up to `intervalMs` earlier. Best effort; the page may be gone.
await session.chromeMemory.sampleOnce();
}
if (session.page && !session.pageReleased) {
const blur = await describePageMotionBlurAtEnd(session.page);
if (blur) console.log(blur);
}
// Realized static-dedup telemetry: how much the cache actually helped this
// render (vs the prediction logged at arm time). Both capture paths
// (sequential orchestrator + parallel workers) close their session here, so
// this is the one uniform emit point. Zero the count afterward so the
// idempotent re-close (HDR cleanup) doesn't double-log.
const reused = session.staticDedupCount ?? 0;
if (session.staticFrames && reused > 0) {
const captured = session.capturePerf.frames; // excludes reuses by design
const total = captured + reused;
const pct = total > 0 ? Math.round((reused / total) * 100) : 0;
const avgTotalMs = captured > 0 ? Math.round(session.capturePerf.totalMs / captured) : 0;
console.log(
`[static-dedup] reused ${reused}/${total} frame(s) (${pct}%), ` +
`est. ~${reused * avgTotalMs}ms saved (avg ${avgTotalMs}ms/frame)`,
);
session.staticDedupCount = 0;
}
// INVARIANT: closeCaptureSession is idempotent. The renderOrchestrator HDR
// cleanup path tracks a `domSessionClosed` flag and may still re-call this
// in the outer finally if the inner cleanup raised before the flag flipped.
//
// Naive idempotency would be unsafe under pool semantics: releaseBrowser
// decrements pooledBrowserRefCount, so calling it twice for the same
// acquire could close a browser that another session still holds. We make
// it safe by gating each release behind a per-session "released" flag —
// the second call sees the flag already set and skips the release.
//
// We set the flag AFTER (not before) the await so that if a release throws
// midway, the unreleased resource is retried by the outer defensive call.
// Example: page release succeeds, browser release throws → pageReleased=true
// but browserReleased=false → second call no-ops on page and retries browser.
// This matches the orchestrator's intent for HDR cleanup.
if (session.workerEncodeEnabled && session.page && !session.pageReleased) {
cleanupDrawElementWorkerEncode(session.page);
}
if (!session.pageReleased && session.page) {
const pageClosed = await waitForCloseWithTimeout(session.page.close());
if (!pageClosed) {
console.warn("[FrameCapture] Timed out closing page; forcing browser process shutdown");
if (session.browserLease) session.browserLease.forceRelease();
else forceReleaseBrowser(session.browser);
session.browserReleased = true;
}
session.pageReleased = true;
}
if (!session.browserReleased && session.browser) {
const browserClosed = await waitForCloseWithTimeout(
session.browserLease?.release() ?? releaseBrowser(session.browser, session.config),
);
if (!browserClosed) {
console.warn("[FrameCapture] Timed out closing browser; forcing browser process shutdown");
if (session.browserLease) session.browserLease.forceRelease();
else forceReleaseBrowser(session.browser);
}
session.browserReleased = true;
}
session.isInitialized = false;
}
export function prepareCaptureSessionForReuse(
session: CaptureSession,
outputDir: string,
onBeforeCapture: BeforeCaptureHook | null,
): void {
if (!existsSync(outputDir)) {
mkdirSync(outputDir, { recursive: true });
}
session.outputDir = outputDir;
session.onBeforeCapture = onBeforeCapture;
session.capturePerf = {
frames: 0,
seekMs: 0,
beforeCaptureMs: 0,
screenshotMs: 0,
totalMs: 0,
frameMs: [],
};
session.beginFrameHasDamageCount = 0;
session.beginFrameNoDamageCount = 0;
// Reset per-render dedup state so a buffer captured by the prior render/probe can't
// bleed into this render's first static frame. staticFrames (the armed set) is left
// intact: it's keyed in absolute frames and stays valid for a same-composition reuse;
// lastFrameBuffer must be re-seeded by this render's first fresh capture.
session.lastFrameBuffer = undefined;
session.lastFrameAbsoluteIndex = undefined;
session.staticDedupCount = 0;
}
export async function getCompositionDuration(session: CaptureSession): Promise<number> {
if (!session.isInitialized) throw new Error("[FrameCapture] Session not initialized");
return session.page.evaluate(() => {
return window.__hf?.duration ?? 0;
});
}
/**
* Ungated-release safety net, part 1: capture K screenshot ground-truth frames
* BEFORE the drawElement canvas is injected (the only window where a page
* screenshot shows the live DOM). The producer's drain compares each DE frame
* at these indices against its screenshot; a breach (or a blank frame that
* survives one retry) throws DrawElementVerificationError, and the orchestrator
* re-renders the whole job via the screenshot path.
*
* Env: HF_DE_VERIFY = sample count (default 4, clamp 0..8; 0 disables).
* Deterministic index selection: fixed fractions of the timeline, nudged off
* clip-cut boundaries (screenshot-vs-DE is legitimately ±1-frame desynced
* there — Lim 6). Skipped for tiny comps (<10 frames) and under
* HF_FORCE_DRAWELEMENT (debug escape hatch).
*
* False-positive bias is intentional: a nondeterministic comp may mismatch its
* init-time screenshot → the render falls back to the screenshot path (slower,
* never wrong). Cost when passing: ~K×(seek+screenshot) ≈ 150–300ms at init.
*/
/**
* Timeline fractions the self-verify samples. First k-1 evenly spaced, last
* pinned at 95%: late-onset damage (an end-of-comp reveal exposing pixels DE
* paints wrong) was invisible to the old (i+1)/(k+1) grid, whose final sample
* sat at 80% — measured miss: a body-gradient drop starting at ~79% of the
* timeline passed verification while the drained output bottomed at 30.9 dB.
*/
export function computeDeVerifySampleFractions(k: number): number[] {
if (k <= 0) return [];
if (k === 1) return [0.95];
return [...Array.from({ length: k - 1 }, (_, i) => (i + 1) / k), 0.95];
}
async function captureDeVerificationFrames(
session: CaptureSession,
page: Page,
logInitPhase: (phase: string) => void,
): Promise<void> {
// Explicit HF_DE_VERIFY wins; otherwise the session's own sample count
// (raised by the parallel coordinator for multi-worker DE), then default 4.
const kRaw = Number(process.env.HF_DE_VERIFY ?? session.options.deVerifySamples ?? "4");
const k = Number.isFinite(kRaw) ? Math.max(0, Math.min(8, Math.floor(kRaw))) : 4;
if (k === 0 || process.env.HF_FORCE_DRAWELEMENT === "1") return;
if (session.options.format === "png") return; // worker-encode drain (the consumer) is jpeg-only
const fps = fpsToNumber(session.options.fps);
// Prefer the producer-resolved duration (the range that will actually be
// drained). The page's raw __hf.duration can exceed it — timelines outrun
// their data-duration, and infinite-repeat GSAP reports a huge sentinel —
// and indices derived from it would never be drained, silently disarming
// verification for exactly the comps that need it.
const duration =
session.options.compositionDurationSeconds ??
(await page.evaluate(
() => (window as unknown as { __hf?: { duration?: number } }).__hf?.duration ?? 0,
));
const totalFrames = Math.floor(duration * fps);
if (totalFrames < 10) return;
if (duration > 3600) {
// No producer duration and the page reports an implausible one.
logInitPhase(`drawElement self-verify skipped: implausible duration ${duration}s`);
return;
}
// Ground truth must show what the real capture paths would show: <video>
// pixels come from the onBeforeCapture injector. When this session has no
// injector (e.g. a probe session initialized before the render wires one
// up) a video comp's truth would screenshot black boxes and every sample
// would false-positive into the screenshot fallback — skip instead.
if (!session.onBeforeCapture) {
const hasVideos = await page.evaluate(() => document.querySelector("video") !== null);
if (hasVideos) {
logInitPhase("drawElement self-verify skipped: video comp without frame injector");
return;
}
}
const boundary = await computeClipBoundaryFrames(page, fps);
// Ascending order, and seek frame 0 first: GSAP .from()/overlapping tweens
// lazily record their start values on FIRST seek — scrubbing mid-timeline
// before the render's frame-0 seek corrupts those caches for the whole
// render (the detectCssEffectRisk lesson), and because DE frames and truth
// would share the corruption, PSNR would pass on the damaged output.
// Seeking 0 → ascending reproduces the render's own seek order.
const fractions = computeDeVerifySampleFractions(k);
const seekTo = async (t: number): Promise<void> => {
await page.evaluate((tt: number) => {
const hf = (
window as unknown as {
__hf?: { seek?: (x: number, options?: { suppressEvents?: boolean }) => void };
}
).__hf;
if (hf && typeof hf.seek === "function") hf.seek(tt, { suppressEvents: true });
}, t);
};
await seekTo(quantizeTimeToFrame(0, fps));
// Force one frame so lazy tween initialization paints at t=0 state.
await pageScreenshotCapture(page, session.options);
const frames = new Map<number, Buffer>();
for (const f of fractions) {
let idx = Math.min(totalFrames - 1, Math.max(1, Math.round(totalFrames * f)));
// Nudge off clip-cut boundaries (±1-frame desync is legitimate there);
// if the nudge saturates on a boundary index, skip the sample entirely.
let guard = 0;
while (boundary.has(idx) && guard++ < 6) idx = Math.min(totalFrames - 1, idx + 2);
if (boundary.has(idx)) continue;
if (frames.has(idx)) continue;
const t = quantizeTimeToFrame(idx / fps, fps);
await seekTo(t);
// Video frame injection (same hook the real capture paths run) — without
// it, <video> elements screenshot black and every video comp would
// false-positive into the screenshot fallback.
if (session.onBeforeCapture) await session.onBeforeCapture(page, t);
// Double-capture: the first screenshot forces a frame, which is what runs
// rAF-driven callbacks (count-up text counters land a tick after seek()
// returns — a single immediate screenshot captures stale text and
// false-positives the verify: 3bea8c73 28.7dB vs a truth missing its stat
// values while the DE frame was correct). NOTE: waiting on rAF via
// evaluate instead deadlocks — headless only fires rAF when a frame is
// produced, and nothing produces one until a screenshot asks.
await pageScreenshotCapture(page, session.options);
frames.set(idx, await pageScreenshotCapture(page, session.options));
}
// Leave the page at frame 0 so the render's first seek starts from the
// same state as an unverified render.
await seekTo(quantizeTimeToFrame(0, fps));
session.deVerifyFrames = frames;
logInitPhase(
`drawElement self-verify armed: ${frames.size} ground-truth frame(s) @ [${[...frames.keys()].join(", ")}] of ${totalFrames}`,
);
}
function medianOf(samples: number[]): number {
if (samples.length === 0) return 0;
const sorted = [...samples].sort((a, b) => a - b);
return Math.round(sorted[Math.floor(sorted.length / 2)] ?? 0);
}
/**
* Percentile of a positive-real sample set (nearest-rank; matches how the
* existing {@link medianOf} p50 helper picks the middle index). `p` is a
* fraction in [0, 1]; the sample at `floor(p * n)` (clamped to `[0, n-1]`)
* is returned. Sample set is not mutated. Returns 0 for empty input, mirroring
* the p50 helper.
*
* Used for the `capture_fallback_profile` observability checkpoint added in
* the fast-capture fallback profiling PR: we already collect `capturePerf.frameMs`
* per session, so computing p95/p99 is one sort + two lookups — cheap enough
* to always compute alongside the existing p50, no separate opt-in path
* needed for the math. The env gate lives at the emission site.
*/
export function percentileOf(samples: number[], p: number): number {
if (samples.length === 0) return 0;
const sorted = [...samples].sort((a, b) => a - b);
const idx = Math.min(sorted.length - 1, Math.max(0, Math.floor(p * sorted.length)));
return Math.round(sorted[idx] ?? 0);
}
/** Threshold for surfacing paint-record/canvas failures in partial-session diagnostics. */
const DE_FALLBACK_RATIO_WARN_THRESHOLD = 0.5;
export function getCapturePerfSummary(session: CaptureSession): CapturePerfSummary {
const frames = Math.max(1, session.capturePerf.frames);
const ncprFallbacks = session.deNcprFallbacks ?? 0;
// These now reject capture and require a fresh screenshot page. Keep the
// counter for failed-session telemetry; it no longer represents usable
// per-frame screenshots from the injected canvas page.
if (frames > 0 && ncprFallbacks / frames > DE_FALLBACK_RATIO_WARN_THRESHOLD) {
const pct = Math.round((ncprFallbacks / frames) * 100);
console.warn(
`[engine] fast capture: ${ncprFallbacks}/${frames} frame(s) (${pct}%) rejected ` +
`due to missing canvas/paint records; fresh screenshot capture required.`,
);
}
return {
frames: session.capturePerf.frames,
avgTotalMs: Math.round(session.capturePerf.totalMs / frames),
avgSeekMs: Math.round(session.capturePerf.seekMs / frames),
avgBeforeCaptureMs: Math.round(session.capturePerf.beforeCaptureMs / frames),
avgScreenshotMs: Math.round(session.capturePerf.screenshotMs / frames),
p50TotalMs: medianOf(session.capturePerf.frameMs),
p95TotalMs: percentileOf(session.capturePerf.frameMs, 0.95),
p99TotalMs: percentileOf(session.capturePerf.frameMs, 0.99),
subTimelineWaitOutcome: session.subTimelineWaitOutcome,
initDurationMs: session.initTelemetry?.initDurationMs,
initTweenCount: session.initTelemetry?.tweenCount,
initElementCount: session.initTelemetry?.elementCount,
warnings: cloneCaptureWarnings(session.warnings),
staticDedupReused: session.staticDedupCount ?? 0,
staticDedupEnabled: session.staticDedupEnabled ?? false,
// armed ⟺ a non-empty static set survived verification.
staticDedupArmed: (session.staticFrames?.size ?? 0) > 0,
staticDedupPredicted: session.staticDedupPredictedCount ?? 0,
staticDedupVerified: session.staticFrames?.size ?? 0,
staticDedupVerificationOutcome: session.staticDedupVerification?.outcome,
staticDedupVerificationPlannedRuns: session.staticDedupVerification?.stats.plannedRuns,
staticDedupVerificationCompletedRuns: session.staticDedupVerification?.stats.completedRuns,
staticDedupVerificationScreenshots: session.staticDedupVerification?.stats.screenshots,
staticDedupVerificationSeeks: session.staticDedupVerification?.stats.seeks,
staticDedupVerificationComparisons: session.staticDedupVerification?.stats.byteComparisons,
staticDedupVerificationElapsedMs: session.staticDedupVerification?.stats.elapsedMs,
staticDedupSkipReason: session.staticDedupSkipReason,
beginFrameNoDamage: session.beginFrameNoDamageCount,
beginFrameHasDamage: session.beginFrameHasDamageCount,
captureMode: session.captureMode,
gpuRenderer: session.gpuRenderer,
chromeBrowserRssPeakMb: session.chromeMemory?.stats().browserRssPeakMb,
chromeRendererRssPeakMb: session.chromeMemory?.stats().rendererRssPeakMb,
chromeRssLastMb: session.chromeMemory?.stats().rssLastMb,
chromeGpuProcessSeenLastSample: session.chromeMemory?.stats().gpuProcessSeenLastSample,
chromeMemorySamples: session.chromeMemory?.stats().samples,
deGateReason: session.deGateReason,
deFallbackTrigger: session.deFallbackTrigger,
deWorkerEncode: session.workerEncodeEnabled ?? false,
deVerifyArmed: session.deVerifyFrames?.size ?? 0,
deVerifyInitMs: session.deVerifyInitMs ?? 0,
deBoundaryFrames: session.clipBoundaryFrames?.size ?? 0,
deNcprFallbacks: ncprFallbacks,
deFrameTimeouts: session.deFrameTimeouts ?? 0,
};
}