// fallow-ignore-file code-duplication complexity /** * DrawElement Capture Service * * `canvas.drawElementImage(element, x, y)` reads DOM paint records directly into * a canvas, bypassing the full compositor pipeline. Requires the Chrome flag * `--enable-features=CanvasDrawElement` (already added globally) and a * `` wrapper around the composition root. * * Performance: ~46% faster than Page.captureScreenshot on local GPU. * Alpha: pixel-perfect (PSNR=∞) on GPU. Falls back to screenshot in Docker * (SwiftShader) when transparent output is requested — SwiftShader drops promoted * compositor sub-layers on a transparent canvas destination (Chromium bug, filed * Blink>Canvas, 2026-06-08). */ import type { Page } from "puppeteer-core"; /** * Discriminant prefix embedded in every "capture canvas isn't set up yet" * error THIS module throws/returns (as opposed to the native * `InvalidStateError: No cached paint record for element` DOMException that * `drawElementImage` itself throws, which we don't control the text of). * * These errors cross a `page.evaluate` boundary: Puppeteer reconstructs them * as a plain `Error` on the Node side (see puppeteer-core's * `createEvaluationError`), so custom properties/subclasses don't survive — * only `message` (and `name`, which for a plain `Error` thrown in-page is * just `"Error"`) make the round trip. A stable, low-cardinality code baked * into the message is therefore the closest available substitute for a real * error-code discriminant. frameCapture.ts matches on this exact code * (substring) rather than on the free-text tail, so classification survives * the message being re-wrapped (e.g. `produceDrawElementFrameBatch`'s * "batch produce failed at frame N: : ..." wrapping) and won't * false-positive on unrelated prose that happens to contain the words * "canvas" and "initialized". * * IMPORTANT: because `page.evaluate` serializes closures via `Function#toString`, * the three throw/return sites below CANNOT reference this constant directly * (it wouldn't be in scope inside the browser) — they inline the same literal * string. Keep all three in sync with this constant if it ever changes. */ export const DE_CANVAS_NOT_INITIALIZED_CODE = "HF_DE_CANVAS_NOT_INITIALIZED"; /** * Resolve which capture mode to use when `useDrawElement` is true. * * Cases that fall back to screenshot (see docs/fast-capture-limitations.md): * - SwiftShader (software rasterizer, i.e. Docker/CI with no GPU): drawElement * yields NO speedup here and is slightly slower. Its entire advantage is * skipping the GPU→CPU screenshot readback IPC — on SwiftShader there is no * GPU, so both paths block on identical software rasterization (measured * parity: font-variant-numeric baseline 7822ms vs fast 7979ms, page-side * draw/readback/encode all ~0ms). The drawElement path only adds a per-frame * CDP round-trip on top of the same raster cost, and on a transparent * destination additionally drops promoted sub-layers (Chromium bug * 521434899). The speedup is real only on a hardware GPU (macOS 1.6×), so * SwiftShader always routes to the platform baseline. * * The former