@hyperframes/engine 0.8.211 → 0.8.212

package/dist/index.d.ts

@@ -38,6 +38,7 @@ export { chromeMajorCeiling } from "./services/chromeHostCeiling.js";
 export { acquireBrowser, setHostHandlesSigint, releaseBrowser, drainBrowserPool, closeBrowserPool, resolveHeadlessShellPath, resolveBrowserGpuMode, buildChromeArgs, compositionRequiresWebGpu, assertWebGpuAdapterAvailable, usesSoftwareWebGpu, WebGpuUnavailableError, ENABLE_BROWSER_POOL, BrowserLeasePool, type GpuProbeLifecycle, type BuildChromeArgsOptions, type BrowserLaunchFingerprint, type BrowserLease, type BrowserPoolState, type CaptureMode, type AcquiredBrowser, } from "./services/browserManager.js";
 export { augmentProtocolTimeoutError, isProtocolTimeoutError, } from "./services/protocolTimeoutErrorHint.js";
 export { augmentPageNavigationTimeoutError, isPageNavigationTimeoutError, type NavigationTimeoutHintContext, } from "./services/pageNavigationTimeoutErrorHint.js";
+export { forcePreservedDrawingBuffer } from "./services/drawElementService.js";
 export { createCaptureSession, initializeSession, closeCaptureSession, captureFrame, captureFrameToBuffer, captureFrameToBufferPipelined, captureFramesBatchPipelined, DrawElementVerificationError, isDrawElementVerificationError, getDrawElementVerificationDetails, type DrawElementVerificationDetails, recaptureDrawElementFrameForVerify, completeDeferredDrawElementInit, writeCapturedFrame, discardWarmupCapture, getCompositionDuration, getCapturePerfSummary, percentileOf, prepareCaptureSessionForReuse, deriveBeginFrameProbeTimeTicks, type CaptureSession, isTransientBrowserError, isMemoryExhaustionError, type BeforeCaptureHook, type DiscardWarmupInnerCapture, type StaticVerificationOutcome, VfxFailureError, waitForImagesReady, evaluateHfDiagnostic, buildZeroDurationDiagnostic, } from "./services/frameCapture.js";
 export { CaptureFailure, classifyCaptureFailure, isFatalCaptureFailure, type CaptureFailureKind, type CaptureWorkerDiagnostic, } from "./services/captureFailure.js";
 export { createChromeMemorySampler, type ChromeMemoryStats, } from "./services/chromeMemorySampler.js";

package/dist/index.js

@@ -40,6 +40,7 @@ export { acquireBrowser, setHostHandlesSigint, releaseBrowser, drainBrowserPool,
 export { augmentProtocolTimeoutError, isProtocolTimeoutError, } from "./services/protocolTimeoutErrorHint.js";
 export { augmentPageNavigationTimeoutError, isPageNavigationTimeoutError, } from "./services/pageNavigationTimeoutErrorHint.js";
 // ── Frame capture pipeline ──────────────────────────────────────────────────────
+export { forcePreservedDrawingBuffer } from "./services/drawElementService.js";
 export { createCaptureSession, initializeSession, closeCaptureSession, captureFrame, captureFrameToBuffer, captureFrameToBufferPipelined, captureFramesBatchPipelined, DrawElementVerificationError, isDrawElementVerificationError, getDrawElementVerificationDetails, recaptureDrawElementFrameForVerify, completeDeferredDrawElementInit, writeCapturedFrame, discardWarmupCapture, getCompositionDuration, getCapturePerfSummary, percentileOf, prepareCaptureSessionForReuse, deriveBeginFrameProbeTimeTicks, isTransientBrowserError, isMemoryExhaustionError, VfxFailureError, waitForImagesReady, evaluateHfDiagnostic, buildZeroDurationDiagnostic, } from "./services/frameCapture.js";
 export { CaptureFailure, classifyCaptureFailure, isFatalCaptureFailure, } from "./services/captureFailure.js";
 export { createChromeMemorySampler, } from "./services/chromeMemorySampler.js";

package/dist/services/chromeStartup.js

@@ -78,7 +78,14 @@ export async function diagnoseChromeStartup(executablePath, args, options = {})
 }
 /** The launch error, with the startup diagnosis appended; the original stays as `cause`. */
 export async function explainChromeLaunchFailure(error, executablePath, args, signal) {
-    if (!executablePath || !(error instanceof Error))
+    if (!(error instanceof Error))
+        return error;
+    const { code, errno, syscall } = error;
+    if (code === "UNKNOWN" && syscall === "spawn")
+        return new Error(`Windows refused to start the browser${executablePath ? ` at ${executablePath}` : ""} (error ${errno ?? "unknown"}, spawn UNKNOWN). ` +
+            "Security software may be blocking it, or the computer may be out of memory. " +
+            "Close other apps and retry; if it persists, run `hyperframes browser ensure --force` to download it again.", { cause: error });
+    if (!executablePath)
         return error;
     const diagnosis = await diagnoseChromeStartup(executablePath, args ?? [], { signal });
     return new Error(`${error.message}\n${diagnosis}`, { cause: error });

package/dist/services/drawElementService.d.ts

@@ -71,13 +71,16 @@ export declare function resolveDrawElementCaptureMode(isSwiftShader: boolean, tr
  * captureDrawElementFrame can hide them from paint records and drawImage
  * their live content underneath the drawElementImage output.
  *
- * WebGL contexts additionally get `preserveDrawingBuffer: true` forced —
- * without it the drawing buffer is cleared after each compositor present and
- * drawImage(glCanvas) reads blank.
+ * Register forcePreservedDrawingBuffer first: this wrapper only records.
  *
  * Must be registered via page.evaluateOnNewDocument BEFORE navigation.
  */
 export declare function instrumentAcceleratedCanvases(): void;
+/**
+ * WebGL contexts keep their drawing buffer after a frame is presented, so drawImage(glCanvas) reads the frame
+ * instead of blank. Must be registered via page.evaluateOnNewDocument BEFORE navigation.
+ */
+export declare function forcePreservedDrawingBuffer(): void;
 export interface GpuBackendInfo {
     /** SwiftShader (software rasterizer) — e.g. Docker headless-shell. */
     isSwiftShader: boolean;

package/dist/services/drawElementService.js

@@ -79,9 +79,7 @@ export function resolveDrawElementCaptureMode(isSwiftShader, transparent) {
  * captureDrawElementFrame can hide them from paint records and drawImage
  * their live content underneath the drawElementImage output.
  *
- * WebGL contexts additionally get `preserveDrawingBuffer: true` forced —
- * without it the drawing buffer is cleared after each compositor present and
- * drawImage(glCanvas) reads blank.
+ * Register forcePreservedDrawingBuffer first: this wrapper only records.
  *
  * Must be registered via page.evaluateOnNewDocument BEFORE navigation.
  */
@@ -92,11 +90,9 @@ export function instrumentAcceleratedCanvases() {
     const orig = HTMLCanvasElement.prototype.getContext;
     // oxlint-disable-next-line no-explicit-any
     HTMLCanvasElement.prototype.getContext = function (type, attrs) {
-        const isGl = type === "webgl" || type === "webgl2" || type === "experimental-webgl";
-        const isAccel = isGl || type === "webgpu";
-        const finalAttrs = isGl ? { ...attrs, preserveDrawingBuffer: true } : attrs;
+        const isAccel = type === "webgl" || type === "webgl2" || type === "experimental-webgl" || type === "webgpu";
         // oxlint-disable-next-line no-explicit-any
-        const ctx = orig.call(this, type, finalAttrs);
+        const ctx = orig.call(this, type, attrs);
         if (ctx && isAccel) {
             const list = w.__hf_accel_canvases ?? [];
             if (!list.includes(this))
@@ -117,6 +113,19 @@ export function instrumentAcceleratedCanvases() {
         return ctx;
     };
 }
+/**
+ * WebGL contexts keep their drawing buffer after a frame is presented, so drawImage(glCanvas) reads the frame
+ * instead of blank. Must be registered via page.evaluateOnNewDocument BEFORE navigation.
+ */
+export function forcePreservedDrawingBuffer() {
+    const orig = HTMLCanvasElement.prototype.getContext;
+    // oxlint-disable-next-line no-explicit-any
+    HTMLCanvasElement.prototype.getContext = function (type, attrs) {
+        const isGl = type === "webgl" || type === "webgl2" || type === "experimental-webgl";
+        // oxlint-disable-next-line no-explicit-any
+        return orig.call(this, type, isGl ? { ...attrs, preserveDrawingBuffer: true } : attrs);
+    };
+}
 /**
  * Low-cardinality bucket for a raw WebGL renderer string: `<backend>/<vendor>`
  * (e.g. `metal/apple`, `d3d11/nvidia`, `swiftshader/other`).

package/dist/services/frameCapture.js

@@ -18,7 +18,7 @@ import { describePageMotionBlur, describePageMotionBlurAtEnd, installPageMotionB
 // ── Extracted modules ───────────────────────────────────────────────────────
 import { acquireBrowser, releaseBrowser, forceReleaseBrowser, buildChromeArgs, resolveBrowserGpuMode, captureWithoutWaylandDisplay, resolveHeadlessShellPath, compositionRequiresWebGpu, assertWebGpuAdapterAvailable, usesSoftwareWebGpu, } from "./browserManager.js";
 import { beginFrameCapture, ensureRenderFrameSiblings, getCdpSession, pageContentExceedsCaptureHeight, pageScreenshotCapture, initTransparentBackground, capturesAlpha, shouldDefaultCaptureBeyondViewport, } from "./screenshotService.js";
-import { classifyGpuRenderer, detectGpuBackend, injectDrawElementCanvas, captureDrawElementFrame, resolveDrawElementCaptureMode, instrumentAcceleratedCanvases, initDrawElementWorkerEncode, cleanupDrawElementWorkerEncode, produceDrawElementFrame, produceDrawElementFrameBatch, DE_CANVAS_NOT_INITIALIZED_CODE, } from "./drawElementService.js";
+import { classifyGpuRenderer, detectGpuBackend, injectDrawElementCanvas, captureDrawElementFrame, resolveDrawElementCaptureMode, forcePreservedDrawingBuffer, instrumentAcceleratedCanvases, initDrawElementWorkerEncode, cleanupDrawElementWorkerEncode, produceDrawElementFrame, produceDrawElementFrameBatch, DE_CANVAS_NOT_INITIALIZED_CODE, } from "./drawElementService.js";
 import { initThreeDProjection, scanCssEffects } from "./threeDProjection.js";
 import { planRiskFrames, scanCssEffectLiveFrames, riskSessionFits, withFramesAfterCallback, MAX_RISK_FRAME_FRACTION, } from "./riskFrames.js";
 import { getAvailableMemoryMb } from "./systemMemory.js";
@@ -1006,6 +1006,7 @@ async function constructCaptureSession(input) {
     // composites their live content via drawImage instead (see
     // instrumentAcceleratedCanvases). Must be registered before navigation.
     if (useDrawElement) {
+        await page.evaluateOnNewDocument(forcePreservedDrawingBuffer);
         await page.evaluateOnNewDocument(instrumentAcceleratedCanvases);
     }
     // The opacity → autoAlpha tween rewrite was RETIRED with the requestPaint

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/engine",
-  "version": "0.8.211",
+  "version": "0.8.212",
   "description": "Seekable web page to video rendering engine (Puppeteer + FFmpeg)",
   "repository": {
     "type": "git",
@@ -54,8 +54,8 @@
     "linkedom": "^0.18.12",
     "puppeteer": "~25.11.0",
     "puppeteer-core": "^25.11.0",
-    "@hyperframes/parsers": "^0.8.211",
-    "@hyperframes/core": "^0.8.211"
+    "@hyperframes/core": "^0.8.212",
+    "@hyperframes/parsers": "^0.8.212"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",