@hyperframes/engine 0.7.60 → 0.7.62

package/dist/services/frameCapture.js

@@ -12,10 +12,11 @@ import { join } from "path";
 import { quantizeTimeToFrame, fpsToNumber } from "@hyperframes/core";
 // ── Extracted modules ───────────────────────────────────────────────────────
 import { acquireBrowser, releaseBrowser, forceReleaseBrowser, buildChromeArgs, resolveBrowserGpuMode, resolveHeadlessShellPath, } from "./browserManager.js";
-import { beginFrameCapture, ensureRenderFrameSiblings, getCdpSession, pageScreenshotCapture, initTransparentBackground, shouldDefaultCaptureBeyondViewport, } from "./screenshotService.js";
+import { beginFrameCapture, ensureRenderFrameSiblings, getCdpSession, pageContentExceedsCaptureHeight, pageScreenshotCapture, initTransparentBackground, shouldDefaultCaptureBeyondViewport, } from "./screenshotService.js";
 import { detectSwiftShader, injectDrawElementCanvas, captureDrawElementFrame, resolveDrawElementCaptureMode, instrumentAcceleratedCanvases, initDrawElementWorkerEncode, cleanupDrawElementWorkerEncode, produceDrawElementFrame, produceDrawElementFrameBatch, } from "./drawElementService.js";
 import { initThreeDProjection, detectCssEffectRisk } from "./threeDProjection.js";
 import { DEFAULT_CONFIG, applyConcreteGpuScreenshotClamp } from "../config.js";
+export { isMemoryExhaustionError, isTransientBrowserError } from "./captureFailure.js";
 export class DrawElementVerificationError extends Error {
     kind;
     frameIndex;
@@ -237,6 +238,23 @@ export function formatRequestFailureDiagnostic(input) {
     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) {
+    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) {
     const statusText = input.statusText ? ` ${input.statusText}` : "";
     return (`[Browser:HTTP${input.status}] ${input.method} ${sanitizeDiagnosticUrl(input.url)} ` +
@@ -653,8 +671,56 @@ export async function createCaptureSession(serverUrl, outputDir, options, onBefo
         ? "beginframe"
         : "screenshot";
     const chromeArgs = buildChromeArgs({ width: options.width, height: options.height, captureMode: preMode }, { ...config, browserGpuMode: resolvedGpuMode });
-    const { browser, captureMode } = await acquireBrowser(chromeArgs, config);
+    const browserLease = await acquireBrowser(chromeArgs, config);
+    return constructCaptureSessionWithRollback({
+        browserLease,
+        serverUrl,
+        outputDir,
+        options,
+        onBeforeCapture,
+        config,
+        useDrawElement,
+    });
+}
+async function constructCaptureSessionWithRollback(input) {
+    let page;
+    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) {
+    const { browserLease, serverUrl, outputDir, options, onBeforeCapture, config, useDrawElement, 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`
@@ -755,6 +821,7 @@ export async function createCaptureSession(serverUrl, outputDir, options, onBefo
     // PNG captures after `page.goto(...)` and the `window.__hf` readiness poll.
     return {
         browser,
+        browserLease,
         page,
         options: sessionOptions,
         serverUrl,
@@ -1271,14 +1338,19 @@ export async function initializeSession(session) {
         appendBrowserDiagnostic(session, text);
     });
     page.on("requestfailed", (request) => {
-        if (request.resourceType() === "script") {
+        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: request.resourceType(),
-            url: request.url(),
-            failureText: request.failure()?.errorText ?? "unknown",
+            resourceType,
+            url,
+            failureText,
         }));
     });
     page.on("response", (response) => {
@@ -1386,6 +1458,19 @@ export async function initializeSession(session) {
         }
         recordCaptureWarnings(session, await collectMediaReadinessWarnings(page, skipVideoIds, pageReadyTimeout));
         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);
@@ -2567,16 +2652,22 @@ export async function closeCaptureSession(session) {
         const pageClosed = await waitForCloseWithTimeout(session.page.close());
         if (!pageClosed) {
             console.warn("[FrameCapture] Timed out closing page; forcing browser process shutdown");
-            forceReleaseBrowser(session.browser);
+            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(releaseBrowser(session.browser, session.config));
+        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");
-            forceReleaseBrowser(session.browser);
+            if (session.browserLease)
+                session.browserLease.forceRelease();
+            else
+                forceReleaseBrowser(session.browser);
         }
         session.browserReleased = true;
     }
@@ -2799,98 +2890,4 @@ export function getCapturePerfSummary(session) {
         deNcprFallbacks: session.deNcprFallbacks ?? 0,
     };
 }
-// ── Transient browser error classification ─────────────────────────────────
-// Puppeteer/Chrome can fail with transient errors that succeed on retry with a
-// fresh browser session. These are infrastructure-level failures (frame
-// detachment, connection drop, OOM kill, launch failure) — NOT composition bugs.
-const TRANSIENT_BROWSER_ERROR_PATTERNS = [
-    /Navigating frame was detached/i,
-    /Target closed/i,
-    /Session closed/i,
-    /browser has disconnected/i,
-    /Page crashed/i,
-    /Execution context was destroyed/i,
-    /Cannot find context with specified id/i,
-    /Failed to launch the browser process/i,
-    /Navigation timeout of \d+ ms exceeded/i,
-    /ECONNREFUSED/i,
-    // Chromium can briefly invalidate even a localhost connection when Windows
-    // reports an adapter/route change. A fresh capture session succeeds once the
-    // network stack settles, so treat this like the other bounded navigation
-    // retries instead of failing the render immediately.
-    /net::ERR_NETWORK_CHANGED/i,
-    // pollHfReady's own timeout — thrown when window.__renderReady never flips
-    // true within playerReadyTimeout. "Runtime ready: false" means init simply
-    // didn't finish in time (commonly a slow/contended host, e.g. several
-    // concurrent renders), which a fresh session usually clears on retry. This
-    // is distinct from the "Runtime ready: true" fast-fail case a few lines up
-    // in pollHfReady (no timeline + no data-duration) — that's a genuine
-    // authoring bug and intentionally NOT matched here, so it still fails fast.
-    /Composition has zero duration[\s\S]*Runtime ready: false/,
-];
-export function isTransientBrowserError(error) {
-    const message = error instanceof Error ? error.message : String(error);
-    return TRANSIENT_BROWSER_ERROR_PATTERNS.some((pattern) => pattern.test(message));
-}
-// ── Memory-exhaustion classification ────────────────────────────────────────
-// A render can run the Node process (or a page-side allocation) out of memory
-// on an oversized composition — huge canvas, thousands of frames, or a very
-// large frame cache. These surface as cryptic V8 RangeErrors ("Set maximum
-// size exceeded", "Invalid array length"/"string length", "Array buffer
-// allocation failed") or a hard V8 heap-limit abort. They are NOT transient
-// (a retry re-hits the same ceiling) and NOT composition-logic bugs — they're
-// resource limits. Classify them so the caller can surface actionable guidance
-// (lower resolution / fps / duration, or enable low-memory mode) instead of a
-// raw RangeError.
-// Deliberately specific: each pattern is a distinct V8/Node allocation-failure
-// signature. We intentionally do NOT match a bare /out of memory/ — that
-// substring appears in benign browser-console noise (WebGL `CONTEXT_LOST … out
-// of memory`, GPU driver notes) that gets carried into the error path, and
-// misclassifying it would replace the real failure message with generic OOM
-// guidance.
-const MEMORY_EXHAUSTION_ERROR_PATTERNS = [
-    /Set maximum size exceeded/i,
-    /Map maximum size exceeded/i,
-    /Invalid (?:array|string) length/i,
-    /Array buffer allocation failed/i,
-    /Cannot create a string longer than/i,
-    /Reached heap limit/i,
-    /JavaScript heap out of memory/i,
-];
-// The producer's deployed runtime is Bun (JavaScriptCore), not Node (V8) —
-// see `packages/gcp-cloud-run/Dockerfile`'s `CMD ["bun", "dist/server.js"]`.
-// JSC's own allocation-failure message for the equivalent single-oversized-
-// allocation RangeErrors above is the bare string "Out of memory" (verified:
-// `new Uint8Array(Number.MAX_SAFE_INTEGER)`, an unbounded `Set`, and
-// `"x".repeat(2**53)` all throw exactly this under Bun) — none of the V8
-// patterns above match it. This is exactly the substring the comment above
-// says NOT to match anywhere in the message (benign browser-console noise
-// like a WebGL `CONTEXT_LOST … out of memory` carries that phrase too), so
-// this checks the ENTIRE (trimmed) message equals it, not merely contains
-// it — a compound message with other text around the phrase still misses.
-const BUN_MEMORY_EXHAUSTION_EXACT_MESSAGE = /^out of memory\.?$/i;
-// The parallel-DE capture path — the exact cohort the OOM-aware retry in
-// renderOrchestrator.ts targets — never reaches isMemoryExhaustionError with
-// a bare message: `executeParallelCapture`/`formatWorkerFailure`
-// (parallelCoordinator.ts) always wrap a worker's error as
-// "Worker N: <message>", optionally suffixed "; diagnostics: ..." and joined
-// with other failed workers' segments via "; ", all prefixed
-// "[Parallel] Capture failed: ". The exact-match check above is defeated by
-// that wrapping entirely (verified) — this pattern recovers the Bun OOM
-// signal by requiring "out of memory" appear immediately after "Worker N: "
-// and immediately before end-of-string, ";", or ".", i.e. as the WHOLE
-// worker-segment content, not merely somewhere inside it. This preserves the
-// exact-match property (no bare "out of memory" substring inside otherwise-
-// unrelated worker text, e.g. "Worker 2: WebGL context lost, out of memory
-// reported by driver" does NOT match) while surviving this codebase's own
-// error-flattening.
-const BUN_MEMORY_EXHAUSTION_WRAPPED_WORKER_MESSAGE = /\bworker \d+: out of memory\.?(?:;|$)/i;
-export function isMemoryExhaustionError(error) {
-    const message = error instanceof Error ? error.message : String(error);
-    if (BUN_MEMORY_EXHAUSTION_EXACT_MESSAGE.test(message.trim()))
-        return true;
-    if (BUN_MEMORY_EXHAUSTION_WRAPPED_WORKER_MESSAGE.test(message))
-        return true;
-    return MEMORY_EXHAUSTION_ERROR_PATTERNS.some((pattern) => pattern.test(message));
-}
 //# sourceMappingURL=frameCapture.js.map