@hyperframes/engine 0.7.59 → 0.7.61

package/dist/services/frameCapture.js

@@ -237,6 +237,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)} ` +
@@ -347,11 +364,13 @@ async function initDrawElementOrTransparentBackground(session, page, logInitPhas
         (!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).");
     }
@@ -397,6 +416,7 @@ async function initDrawElementOrTransparentBackground(session, page, logInitPhas
         });
         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, ~151+); run `hyperframes browser ensure --force` to fetch a supported " +
@@ -420,6 +440,7 @@ async function initDrawElementOrTransparentBackground(session, page, logInitPhas
         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
@@ -439,6 +460,11 @@ async function initDrawElementOrTransparentBackground(session, page, logInitPhas
                 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();
@@ -469,6 +495,7 @@ async function initDrawElementOrTransparentBackground(session, page, logInitPhas
                 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 ` +
@@ -484,6 +511,7 @@ async function initDrawElementOrTransparentBackground(session, page, logInitPhas
             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();
@@ -642,8 +670,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`
@@ -744,6 +820,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,
@@ -1260,14 +1337,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) => {
@@ -2556,16 +2638,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;
     }
@@ -2729,6 +2817,26 @@ function medianOf(samples) {
     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, p) {
+    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);
+}
 export function getCapturePerfSummary(session) {
     const frames = Math.max(1, session.capturePerf.frames);
     return {
@@ -2738,6 +2846,8 @@ export function getCapturePerfSummary(session) {
         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,
         warnings: session.warnings.map((warning) => ({
             ...warning,
@@ -2758,6 +2868,7 @@ export function getCapturePerfSummary(session) {
         beginFrameHasDamage: session.beginFrameHasDamageCount,
         captureMode: session.captureMode,
         deGateReason: session.deGateReason,
+        deFallbackTrigger: session.deFallbackTrigger,
         deWorkerEncode: session.workerEncodeEnabled ?? false,
         deVerifyArmed: session.deVerifyFrames?.size ?? 0,
         deVerifyInitMs: session.deVerifyInitMs ?? 0,