mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-16 14:27:26 +00:00
* fix(cli): pick a macOS 12 capable Chrome on macOS 12 instead of the pinned build * test(engine): stop building subprocess eval scripts from strings
4858 lines
203 KiB
TypeScript
4858 lines
203 KiB
TypeScript
// 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 Viewport, type ConsoleMessage } from "puppeteer-core";
|
||
import { existsSync, mkdirSync, writeFileSync } from "fs";
|
||
import { join } from "path";
|
||
import {
|
||
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";
|
||
|
||
// ── Extracted modules ───────────────────────────────────────────────────────
|
||
import {
|
||
acquireBrowser,
|
||
releaseBrowser,
|
||
forceReleaseBrowser,
|
||
buildChromeArgs,
|
||
resolveBrowserGpuMode,
|
||
resolveHeadlessShellPath,
|
||
compositionRequiresWebGpu,
|
||
assertWebGpuAdapterAvailable,
|
||
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,
|
||
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. */
|
||
export type BeforeCaptureHook = (page: Page, time: number) => Promise<void>;
|
||
|
||
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;
|
||
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[];
|
||
/** Outcome of the sub-composition timeline wait: ready | timeout | script_failure. */
|
||
subTimelineWaitOutcome?: SubTimelineWaitOutcome;
|
||
/** 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;
|
||
/** 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;
|
||
/**
|
||
* 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;
|
||
}
|
||
|
||
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,
|
||
},
|
||
};
|
||
}
|
||
|
||
export async function driveWarmupTicks(
|
||
options: WarmupTickOptions,
|
||
state: WarmupTickState,
|
||
): Promise<void> {
|
||
const sleep = options.sleep ?? realSleep;
|
||
while (true) {
|
||
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 supersampling (deviceScaleFactor > 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 > 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 supersampled (DPR > 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: falling 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: falling 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: falling 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: falling 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 ("filter:blur" / "filter:drop-shadow" /
|
||
// "backdrop-filter" / "clip-path") — `deGateReason` sanitizes
|
||
// this to the low-cardinality prefix; `deFallbackTrigger` keeps
|
||
// the fine-grained value for the diagnostic profile emission.
|
||
session.deFallbackTrigger = cssFx;
|
||
console.log(
|
||
`[engine] fast capture: falling 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: falling 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: falling 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 > 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 chromeArgs = buildChromeArgs(
|
||
{ width: options.width, height: options.height, captureMode: preMode, requiresWebGpu },
|
||
{ ...config, browserGpuMode: resolvedGpuMode },
|
||
);
|
||
|
||
const browserLease = await acquireBrowser(chromeArgs, config);
|
||
return constructCaptureSessionWithRollback({
|
||
browserLease,
|
||
serverUrl,
|
||
outputDir,
|
||
options,
|
||
onBeforeCapture,
|
||
config,
|
||
useDrawElement,
|
||
requiresWebGpu,
|
||
});
|
||
}
|
||
|
||
interface CaptureSessionConstructionInput {
|
||
browserLease: BrowserLease;
|
||
serverUrl: string;
|
||
outputDir: string;
|
||
options: CaptureOptions;
|
||
onBeforeCapture: BeforeCaptureHook | null;
|
||
config?: Partial<EngineConfig>;
|
||
useDrawElement: boolean;
|
||
requiresWebGpu?: 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,
|
||
onPageCreated,
|
||
} = input;
|
||
const { browser, captureMode } = browserLease;
|
||
|
||
const page = await browser.newPage();
|
||
onPageCreated(page);
|
||
// 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);
|
||
}
|
||
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
|
||
// `[data-composition-id]{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,
|
||
isInitialized: false,
|
||
browserConsoleBuffer: [],
|
||
scriptLoadFailures: [],
|
||
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) — 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;
|
||
}
|
||
|
||
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 ready = Boolean(await page.evaluate(readyExpr));
|
||
if (ready) 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}`,
|
||
);
|
||
}
|
||
|
||
export async function pollSubCompositionTimelines(
|
||
page: Page,
|
||
timeoutMs: number,
|
||
intervalMs: number = 150,
|
||
// Fail-fast hook: when a SCRIPT resource failed to load (404 / request
|
||
// failure), the timeline registration it carried can never arrive — the
|
||
// full-timeout wait buys nothing (measured: a 705-render spike at the 45s
|
||
// setup bucket in 30 days of wild local renders, ~1% of renders, each also
|
||
// shipping silently-broken animations). Once failures are present the poll
|
||
// is cut to `scriptFailureGraceMs` from its start.
|
||
getScriptLoadFailures?: () => readonly string[],
|
||
scriptFailureGraceMs: number = 2_000,
|
||
): 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 || {};
|
||
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) 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) 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(", ")}) — ` +
|
||
`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));
|
||
}
|
||
// 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) {
|
||
await page.evaluate(`(function() {
|
||
if (typeof window.__hfForceTimelineRebind === "function") {
|
||
window.__hfForceTimelineRebind();
|
||
}
|
||
})()`);
|
||
return "ready";
|
||
}
|
||
// Enumerate the still-unregistered composition ids regardless of bail
|
||
// reason — a script-failure bail used to skip this entirely, so a render
|
||
// with multiple sub-compositions only named the failed script URL(s), not
|
||
// which composition(s) it was still waiting on (review).
|
||
const missing = 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.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();
|
||
}
|
||
|
||
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 ?? {});
|
||
}
|
||
}
|
||
|
||
function recordSubTimelineWarning(session: CaptureSession, timeoutMs: number): void {
|
||
if (session.subTimelineWaitOutcome === "ready" || !session.subTimelineWaitOutcome) return;
|
||
const scriptFailure = session.subTimelineWaitOutcome === "script_failure";
|
||
const hasRuntimeErrors = session.scriptLoadFailures.some((f) => f.startsWith("runtime-error:"));
|
||
recordCaptureWarnings(session, [
|
||
{
|
||
code: scriptFailure ? "sub_timeline_script_failure" : "sub_timeline_readiness_timeout",
|
||
message: scriptFailure
|
||
? hasRuntimeErrors
|
||
? `A sub-composition script threw during execution — timeline registration never arrived (${session.scriptLoadFailures.join(", ")})`
|
||
: `A sub-composition timeline script failed to load (${session.scriptLoadFailures.join(", ")})`
|
||
: `Sub-composition timelines did not become ready within ${timeoutMs}ms`,
|
||
details: { timeoutMs, sources: [...session.scriptLoadFailures] },
|
||
},
|
||
]);
|
||
}
|
||
|
||
/**
|
||
* 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 (see the motion-graphics maps skill / ` +
|
||
`bake-basemap.mjs) 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);
|
||
}),
|
||
);
|
||
});
|
||
}
|
||
|
||
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(
|
||
(metadataHints: CaptureVideoMetadataHint[]) => {
|
||
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) continue;
|
||
|
||
if (!video.hasAttribute("width")) video.setAttribute("width", String(hint.width));
|
||
if (!video.hasAttribute("height")) video.setAttribute("height", String(hint.height));
|
||
|
||
const computed = window.getComputedStyle(video);
|
||
if (
|
||
!video.style.aspectRatio &&
|
||
(!computed.aspectRatio || computed.aspectRatio === "auto")
|
||
) {
|
||
video.style.aspectRatio = `${hint.width} / ${hint.height}`;
|
||
}
|
||
}
|
||
},
|
||
[...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.`,
|
||
);
|
||
}
|
||
}
|
||
|
||
// 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);
|
||
}
|
||
}
|
||
|
||
export function classifyConsoleScriptFailure(type: string, text: string): string | null {
|
||
if (type !== "error") return null;
|
||
if (text.startsWith("[HyperFrames] composition script error:")) {
|
||
const detail = text.slice("[HyperFrames] composition script error:".length).trim();
|
||
const compId = detail.split(" ")[0] || "unknown";
|
||
return `runtime-error:${compId}`;
|
||
}
|
||
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;
|
||
}
|
||
|
||
// 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);
|
||
|
||
// Composition script runtime errors mean the GSAP timeline registration
|
||
// can never arrive — same fail-fast treatment as script load failures.
|
||
// Without this, pollSubCompositionTimelines burns the full timeout and
|
||
// the render silently succeeds with a degenerate 2-frame output (#3352).
|
||
const scriptFailure = classifyConsoleScriptFailure(type, text);
|
||
if (scriptFailure) recordScriptLoadFailure(session, scriptFailure);
|
||
});
|
||
|
||
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.
|
||
const isPlayAbort =
|
||
/^AbortError:/.test(message) && message.includes("play()") && message.includes("pause()");
|
||
if (!isPlayAbort) {
|
||
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,
|
||
}),
|
||
);
|
||
});
|
||
|
||
page.on("response", (response) => {
|
||
const status = response.status();
|
||
if (status < 400) return;
|
||
|
||
const request = response.request();
|
||
if (request.resourceType() === "script") {
|
||
recordScriptLoadFailure(session, response.url());
|
||
}
|
||
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`;
|
||
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);
|
||
};
|
||
|
||
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");
|
||
|
||
session.subTimelineWaitOutcome = await pollSubCompositionTimelines(
|
||
page,
|
||
pageReadyTimeout,
|
||
undefined,
|
||
() => session.scriptLoadFailures,
|
||
);
|
||
logInitPhase(`pollSubCompositionTimelines complete (${session.subTimelineWaitOutcome})`);
|
||
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),
|
||
pollImagesReady(page, pageReadyTimeout).then(async (ready) => {
|
||
if (!ready) {
|
||
const failedImages = await page.evaluate(() => {
|
||
return Array.from(document.querySelectorAll("img"))
|
||
.filter((img) => {
|
||
const ie = img as HTMLImageElement;
|
||
const src = ie.getAttribute("src") || "";
|
||
if (!src || src.startsWith("data:")) return false;
|
||
return !(ie.complete && ie.naturalWidth > 0);
|
||
})
|
||
.map((img) => (img as HTMLImageElement).src || img.getAttribute("src") || "(no src)")
|
||
.join(", ");
|
||
});
|
||
console.warn(
|
||
`[FrameCapture] Some image elements did not load within ${pageReadyTimeout}ms: ${failedImages}. ` +
|
||
`Continuing render — affected images may appear blank/missing in early frames.`,
|
||
);
|
||
}
|
||
await decodeAllImages(page);
|
||
return ready;
|
||
}),
|
||
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 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;
|
||
try {
|
||
await pollHfReady(page, pageReadyTimeout);
|
||
logInitPhase("pollHfReady complete");
|
||
} catch (err) {
|
||
warmupState.running = false;
|
||
throw err;
|
||
}
|
||
|
||
session.subTimelineWaitOutcome = await pollSubCompositionTimelines(
|
||
page,
|
||
pageReadyTimeout,
|
||
undefined,
|
||
() => session.scriptLoadFailures,
|
||
);
|
||
logInitPhase(`pollSubCompositionTimelines complete (${session.subTimelineWaitOutcome})`);
|
||
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),
|
||
pollImagesReady(page, pageReadyTimeout).then(async (ready) => {
|
||
if (!ready) {
|
||
const failedImages = await page.evaluate(() => {
|
||
return Array.from(document.querySelectorAll("img"))
|
||
.filter((img) => {
|
||
const ie = img as HTMLImageElement;
|
||
const src = ie.getAttribute("src") || "";
|
||
if (!src || src.startsWith("data:")) return false;
|
||
return !(ie.complete && ie.naturalWidth > 0);
|
||
})
|
||
.map((img) => (img as HTMLImageElement).src || img.getAttribute("src") || "(no src)")
|
||
.join(", ");
|
||
});
|
||
console.warn(
|
||
`[FrameCapture] Some image elements did not load within ${pageReadyTimeout}ms: ${failedImages}. ` +
|
||
`Continuing render — affected images may appear blank/missing in early frames.`,
|
||
);
|
||
}
|
||
await decodeAllImages(page);
|
||
return ready;
|
||
}),
|
||
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}`);
|
||
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,
|
||
): Promise<{
|
||
quantizedTime: number;
|
||
seekMs: number;
|
||
beforeCaptureMs: number;
|
||
}> {
|
||
const { page, options } = session;
|
||
|
||
if (!session.isInitialized) {
|
||
throw new Error("[FrameCapture] Session not initialized");
|
||
}
|
||
|
||
const quantizedTime = quantizeSeekTime(
|
||
time,
|
||
fpsToNumber(options.fps),
|
||
seekOptions?.subFrameDivisions,
|
||
);
|
||
|
||
const seekStart = Date.now();
|
||
const hasPendingComposite = await seekPageTimeline(page, quantizedTime, seekOptions);
|
||
|
||
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) {
|
||
await session.onBeforeCapture(page, quantizedTime);
|
||
}
|
||
await waitForPendingSeekCompletion(page);
|
||
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"
|
||
) {
|
||
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();
|
||
}
|
||
});
|
||
}
|
||
|
||
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 };
|
||
};
|
||
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");
|
||
// 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,
|
||
hasNonGsapAnim,
|
||
hasUnresolvableClipStart,
|
||
hasTimelineCall,
|
||
};
|
||
}, SPATIAL_TWEEN_PROPERTIES);
|
||
|
||
const {
|
||
intervals,
|
||
tweenCount,
|
||
duration,
|
||
hasVideo,
|
||
hasCanvas,
|
||
hasNonGsapAnim,
|
||
hasUnresolvableClipStart,
|
||
hasTimelineCall,
|
||
} = result as {
|
||
intervals: Array<{ start: number; end: number; spatial: boolean }>;
|
||
tweenCount: number;
|
||
duration: number;
|
||
hasVideo: boolean;
|
||
hasCanvas: 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");
|
||
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 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);
|
||
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. See docs/fast-capture-limitations.md Lim 7.
|
||
*
|
||
* 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. `<video>` content is
|
||
* out of scope because it is supplied by the before-capture frame-injection hook rather
|
||
* than by the timeline seek, so it cannot follow a sub-frame time.
|
||
*/
|
||
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"}"`,
|
||
);
|
||
}
|
||
if (session.onBeforeCapture) {
|
||
throw new Error(
|
||
"[MotionBlur] sub-frame motion blur cannot run with injected video frames: video content is extracted per output frame and does not follow a sub-frame seek",
|
||
);
|
||
}
|
||
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,
|
||
): Promise<CapturedSurface> {
|
||
const { page, options } = session;
|
||
const { quantizedTime, seekMs, beforeCaptureMs } = await prepareFrameForCapture(
|
||
session,
|
||
frameIndex,
|
||
time,
|
||
seekOptions,
|
||
);
|
||
|
||
const screenshotStart = Date.now();
|
||
let screenshotBuffer: Buffer;
|
||
|
||
if (session.captureMode === "beginframe") {
|
||
const frameTimeTicks = session.beginFrameTimeTicks + frameIndex * session.beginFrameIntervalMs;
|
||
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,
|
||
): 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);
|
||
const probeB = await captureFrameSurface(session, frameIndex, windowEnd, sampleSeek);
|
||
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();
|
||
await seekPageTimeline(session.page, frameTime, undefined);
|
||
const totals = { seekMs: Date.now() - eventfulSeekStart, beforeCaptureMs: 0, screenshotMs: 0 };
|
||
|
||
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,
|
||
);
|
||
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);
|
||
totals.seekMs += sample.seekMs;
|
||
totals.beforeCaptureMs += sample.beforeCaptureMs;
|
||
totals.screenshotMs += sample.screenshotMs;
|
||
accumulator.add(sample.buffer);
|
||
}
|
||
|
||
const restoreSeekStart = Date.now();
|
||
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);
|
||
|
||
// 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");
|
||
}
|
||
const startTime = Date.now();
|
||
const fps = fpsToNumber(options.fps);
|
||
const quantized = times.map((t) => quantizeTimeToFrame(t, fps));
|
||
|
||
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> {
|
||
// Snapshot the side-effect counters captureFrameCore mutates. We use a
|
||
// shallow `{...}` for capturePerf because all five fields are primitive
|
||
// numbers — no nested state to deep-copy.
|
||
const perfBefore = { ...session.capturePerf };
|
||
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();
|
||
}
|
||
// 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,
|
||
};
|
||
}
|