@hyperframes/engine 0.8.207 → 0.8.208

package/dist/services/browserManager.d.ts

@@ -61,32 +61,6 @@ export declare const _closeBrowserAfterFailedProbeForTests: typeof closeBrowserA
 export declare function _resetAutoBrowserGpuModeCacheForTests(): void;
 /** True when a `resolvedMode` render must launch without WAYLAND_DISPLAY to reach the GPU. */
 export declare function captureWithoutWaylandDisplay(resolvedMode: "software" | "hardware"): Promise<boolean>;
-/**
- * Resolve `browserGpuMode` to a concrete `"software" | "hardware"` answer.
- *
- * For `"software"` this is a pure pass-through. For `"auto"` it launches a
- * tiny Chrome with the platform's hardware GPU args, runs a one-shot WebGL
- * availability probe, and falls back to `"software"` if hardware-mode WebGL
- * is unavailable. The Promise is cached for the process lifetime, so
- * concurrent callers (parallel workers) share the same probe.
- *
- * `"hardware"` (an explicit `--browser-gpu` / `PRODUCER_BROWSER_GPU_MODE=
- * hardware`) is honoured verbatim — the operator asked for it — but runs the
- * SAME probe to VERIFY it, because Chrome's hardware GL args are advisory:
- * with no usable GPU in the sandbox (no `/dev/dri`, no NVIDIA container
- * runtime, missing EGL/driver libraries) Chrome silently falls back to
- * software WebGL and the render just runs at CPU speed. Without this check
- * the only trace is a buried `Automatic fallback to software WebGL` browser
- * warning — heygen-com/hyperframes#2967 rendered 19186 frames on CPU while
- * `--browser-gpu` was set and nothing said so. The probe result never
- * changes the returned mode; it only makes the fallback loud.
- *
- * Any probe failure (Chrome launch error, navigation timeout, missing canvas
- * API, etc.) is treated as a `"software"` result. The render path with
- * SwiftShader always works, so a misclassification toward software is the
- * safe failure mode; misclassifying toward hardware would error on the real
- * render.
- */
 export declare function resolveBrowserGpuMode(mode: EngineConfig["browserGpuMode"], options?: GpuProbeOptions): Promise<"software" | "hardware">;
 type BrowserLaunchConfig = Partial<Pick<EngineConfig, "browserTimeout" | "protocolTimeout" | "chromePath" | "forceScreenshot">> & {
     withoutWaylandDisplay?: boolean;

package/dist/services/browserManager.js

@@ -5,6 +5,7 @@
  * Manages Puppeteer browser lifecycle: Chrome executable resolution,
  * launch args, pooled browser acquisition/release.
  */
+import { explainChromeLaunchFailure } from "./chromeStartup.js";
 import { withHyperframesBrowserMarker } from "@hyperframes/core/browser-marker";
 import { scanHtmlOpeningTags } from "@hyperframes/parsers/html-attribute-spans";
 import { execSync } from "child_process";
@@ -462,7 +463,8 @@ async function probeWebGlMode(ppt, options, env, label = "") {
     }
     catch (err) {
         logResolvedBrowserGpuMode("software", label + formatProbeFailure(err));
-        return { mode: "software", cause: "probe-error" };
+        const aborted = err instanceof Error && err.name === "AbortError";
+        return { mode: "software", cause: "probe-error", ...(aborted && { aborted }) };
     }
 }
 function envWithoutWaylandDisplay() {
@@ -524,12 +526,24 @@ function wslAccess(options) {
  * safe failure mode; misclassifying toward hardware would error on the real
  * render.
  */
+async function sharedGpuProbe(options) {
+    const shared = (_autoBrowserGpuModeCache ??= probeAutoBrowserGpuMode(options));
+    const outcome = await shared;
+    if (!outcome.aborted)
+        return outcome;
+    if (_autoBrowserGpuModeCache === shared)
+        _autoBrowserGpuModeCache = undefined;
+    const own = await probeAutoBrowserGpuMode(options);
+    if (!own.aborted)
+        _autoBrowserGpuModeCache ??= Promise.resolve(own);
+    return own;
+}
 export function resolveBrowserGpuMode(mode, options = {}) {
     if (mode === "software")
         return Promise.resolve(mode);
-    _autoBrowserGpuModeCache ??= probeAutoBrowserGpuMode(options);
+    const probe = sharedGpuProbe(options);
     if (mode === "auto") {
-        return _autoBrowserGpuModeCache.then((probed) => {
+        return probe.then((probed) => {
             if (probed.mode === "software" && probed.wslAccess && !_wslSoftwareNoteLogged) {
                 _wslSoftwareNoteLogged = true;
                 console.error(buildWslSoftwareNote(probed));
@@ -537,7 +551,7 @@ export function resolveBrowserGpuMode(mode, options = {}) {
             return probed.mode;
         });
     }
-    return _autoBrowserGpuModeCache.then((probed) => {
+    return probe.then((probed) => {
         // Warn once per cache lifetime, not once per caller: `createCaptureSession`
         // resolves the mode for the probe browser AND every parallel worker, so
         // an un-deduplicated warning prints N+1 times and buries itself.
@@ -658,7 +672,8 @@ async function launchBrowser(fingerprint) {
     const env = launchEnv(fingerprint);
     let captureMode = fingerprint.requestedCaptureMode;
     let browser;
-    const launch = (args) => ppt.launch({
+    const launch = (args) => ppt
+        .launch({
         ...ownedLaunchOptions(),
         headless: true,
         args: withHyperframesBrowserMarker(args),
@@ -667,6 +682,13 @@ async function launchBrowser(fingerprint) {
         env,
         timeout: fingerprint.browserTimeoutMs,
         protocolTimeout: fingerprint.protocolTimeoutMs,
+    })
+        .catch(async (error) => {
+        const defaults = await ppt.defaultArgs({
+            headless: true,
+            args: withHyperframesBrowserMarker(args),
+        });
+        throw await explainChromeLaunchFailure(error, fingerprint.executablePath, defaults);
     });
     const probe = (target, timeoutMs) => probeBeginFrameSupport(target, timeoutMs).catch((error) => ({
         supported: true,

package/dist/services/chromeHostCeiling.d.ts

@@ -7,7 +7,7 @@ export declare const isManagedChromeDir: (versionName: string) => boolean;
 /** Newest first, by numeric build (`linux-148.0.1` before `linux-99.0.1`). */
 export declare function compareBrowserVersionsDescending(left: string, right: string): number;
 /** Whether a shell loads a blank page and exits: an old build can die at launch on a newer OS. Asked once per path. */
-export declare function shellStarts(binary: string): boolean;
+export declare function shellStarts(binary: string, timeoutMs?: number): boolean;
 /** The shared Puppeteer cache's shell: the managed build, else the newest under the host's ceiling that starts.
  * `shell` names a version dir's executable, or undefined when it holds no usable file. */
 export declare function pickSharedShell(versions: readonly string[], shell: (version: string) => string | undefined): string | undefined;

package/dist/services/chromeHostCeiling.js

@@ -52,11 +52,13 @@ export function compareBrowserVersionsDescending(left, right) {
 const starts = new Map();
 const debug = debuglog("hyperframes:browser");
 /** Whether a shell loads a blank page and exits: an old build can die at launch on a newer OS. Asked once per path. */
-export function shellStarts(binary) {
+export function shellStarts(binary, timeoutMs = 10_000) {
     let answer = starts.get(binary);
     if (answer === undefined) {
         const probe = ["--no-sandbox", "--dump-dom", "about:blank"];
-        answer = spawnSync(binary, probe, { stdio: "ignore", timeout: 10_000 })?.status === 0;
+        answer =
+            spawnSync(binary, probe, { stdio: "ignore", timeout: timeoutMs, killSignal: "SIGKILL" })
+                ?.status === 0;
         if (!answer)
             debug("skipping %s: it did not start", binary);
         starts.set(binary, answer);

package/dist/services/chromeStartup.d.ts

@@ -0,0 +1,10 @@
+/** Names an exit code the way a person can act on it; undefined when it has no name. */
+export declare function nameChromeExit(code: number | null, platform?: NodeJS.Platform): string | undefined;
+/** Starts the browser once more with the failed launch's flags and says how it ended. */
+export declare function diagnoseChromeStartup(executablePath: string, args: readonly string[], options?: {
+    timeoutMs?: number;
+    platform?: NodeJS.Platform;
+    signal?: AbortSignal;
+}): Promise<string>;
+/** The launch error, with the startup diagnosis appended; the original stays as `cause`. */
+export declare function explainChromeLaunchFailure(error: unknown, executablePath: string | undefined, args: readonly string[] | undefined, signal?: AbortSignal): Promise<unknown>;

package/dist/services/chromeStartup.js

@@ -0,0 +1,85 @@
+import { spawn } from "node:child_process";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { removeTreeBestEffort } from "@hyperframes/core/remove-tree";
+const STDERR_TAIL_LINES = 8;
+const PROBE_TIMEOUT_MS = 8_000;
+// NTSTATUS codes a Windows process dies with before it can print anything.
+const WINDOWS_EXITS = [
+    [0xc0000135, "0xC0000135: a required runtime or DLL is missing (Visual C++ runtime)."],
+    [0xc0000017, "0xC0000017: Windows had no memory to start it (out of memory)."],
+    [0xc0000142, "0xC0000142: a DLL failed to initialise, often security software blocking it."],
+    [0xc0000022, "0xC0000022: access denied, often antivirus or a policy blocking the executable."],
+    [0xc000007b, "0xC000007B: the executable and a DLL do not match (32-bit and 64-bit)."],
+];
+/** Names an exit code the way a person can act on it; undefined when it has no name. */
+export function nameChromeExit(code, platform = process.platform) {
+    if (platform !== "win32" || code === null)
+        return undefined;
+    const unsigned = code >>> 0;
+    return WINDOWS_EXITS.find(([known]) => known === unsigned)?.[1];
+}
+function startupArgs(args, profile) {
+    const kept = args.filter((arg) => arg.startsWith("--") &&
+        !arg.startsWith("--remote-debugging") &&
+        !arg.startsWith("--user-data-dir"));
+    return [...kept, `--user-data-dir=${profile}`, "--remote-debugging-port=0", "about:blank"];
+}
+function tail(stderr) {
+    return stderr
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .slice(-STDERR_TAIL_LINES)
+        .join("\n");
+}
+/** Starts the browser once more with the failed launch's flags and says how it ended. */
+export async function diagnoseChromeStartup(executablePath, args, options = {}) {
+    const profile = mkdtempSync(join(tmpdir(), "hf-chrome-probe-"));
+    const timeoutMs = options.timeoutMs ?? PROBE_TIMEOUT_MS;
+    try {
+        return await new Promise((resolve) => {
+            let stderr = "";
+            const child = spawn(executablePath, startupArgs(args, profile), {
+                stdio: ["ignore", "ignore", "pipe"],
+                windowsHide: true,
+            });
+            const timer = setTimeout(() => {
+                child.kill();
+                resolve(`Chrome started and kept running for ${timeoutMs} ms when launched on its own.`);
+            }, timeoutMs);
+            options.signal?.addEventListener("abort", () => {
+                clearTimeout(timer);
+                child.kill();
+                resolve("The startup check was cancelled.");
+            }, { once: true });
+            child.stderr.on("data", (chunk) => {
+                stderr = (stderr + chunk.toString()).slice(-4000);
+            });
+            child.once("error", (error) => {
+                clearTimeout(timer);
+                resolve(`Chrome could not be started: ${error.message}`);
+            });
+            child.once("exit", (code, signal) => {
+                clearTimeout(timer);
+                const how = signal ? `was stopped by ${signal}` : `exited with code ${code}`;
+                const named = nameChromeExit(code, options.platform);
+                const lines = tail(stderr);
+                resolve([`Chrome ${how} when launched on its own.`, named, lines && `stderr:\n${lines}`]
+                    .filter(Boolean)
+                    .join("\n"));
+            });
+        });
+    }
+    finally {
+        removeTreeBestEffort(profile);
+    }
+}
+/** 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))
+        return error;
+    const diagnosis = await diagnoseChromeStartup(executablePath, args ?? [], { signal });
+    return new Error(`${error.message}\n${diagnosis}`, { cause: error });
+}

package/dist/services/parallelCoordinator.d.ts

@@ -239,6 +239,8 @@ export interface ParallelCaptureHooks {
      */
     onWorkerFailure?: (failure: CaptureFailure) => void;
     onWorkerOperation?: (diagnostic: ParallelWorkerPhaseDiagnostic) => void;
+    /** Worker 0 runs this on its initialised session; the other workers wait for it. A rejection fails the pool. */
+    verifyFirstSession?: (session: CaptureSession) => Promise<void>;
 }
 /**
  * The pool's single failure gate. Both halves of the contract the streaming

package/dist/services/parallelCoordinator.js

@@ -552,7 +552,7 @@ export async function verifyDiskDrawElementSamples(session, task, streaming) {
 // flagged only because the disk self-verify call shifted its line range into
 // the changed-code audit. Not restructured by this PR.
 // fallow-ignore-next-line complexity
-async function executeWorkerTask(task, serverUrl, captureOptions, createBeforeCaptureHook, signal, onFrameCaptured, onFrameBuffer, config, parallel, onFailure, onWorkerPhase, onWorkerOperation) {
+async function executeWorkerTask(task, serverUrl, captureOptions, createBeforeCaptureHook, signal, onFrameCaptured, onFrameBuffer, config, parallel, onFailure, onWorkerPhase, onWorkerOperation, gate) {
     const startTime = Date.now();
     let framesCaptured = 0;
     if (!existsSync(task.outputDir))
@@ -603,6 +603,8 @@ async function executeWorkerTask(task, serverUrl, captureOptions, createBeforeCa
                 await assertSwiftShader(activeSession.page, readWebGlVendorInfoFromCanvas);
             }
             await initializeSession(activeSession);
+            if (gate)
+                await (task.workerId === 0 ? gate.verify(activeSession) : gate.wait());
         });
         canvasDrawElement = activeSession.captureMode === "drawelement";
         gpuBackend = activeSession.gpuRenderer ?? "unknown";
@@ -622,6 +624,8 @@ async function executeWorkerTask(task, serverUrl, captureOptions, createBeforeCa
         };
     }
     catch (error) {
+        if (task.workerId === 0)
+            gate?.fail(error);
         const diagnostics = session ? selectWorkerDiagnostics(session.browserConsoleBuffer) : [];
         const workerDiagnostic = {
             workerId: task.workerId,
@@ -687,6 +691,23 @@ export function isPoolFatalWorkerFailure(failure, streaming) {
         return failure.kind !== "cancelled";
     return isFatalCaptureFailure(failure);
 }
+function createFirstSessionGate(verify) {
+    let fail;
+    let pass;
+    const settled = new Promise((resolve, reject) => {
+        pass = resolve;
+        fail = reject;
+    });
+    settled.catch(() => { });
+    return {
+        verify: (session) => verify(session).then(pass, (error) => {
+            fail(error);
+            throw error;
+        }),
+        wait: () => settled,
+        fail,
+    };
+}
 function pageErrorLinesOf(session) {
     return session.browserConsoleBuffer.filter((line) => line.includes("PAGEERROR"));
 }
@@ -777,7 +798,8 @@ export async function executeParallelCapture(serverUrl, workDir, tasks, captureO
         hooks,
     });
     const onFailure = failureHandler.onFailure;
-    const results = await Promise.all(tasks.map((task) => executeWorkerTask(task, serverUrl, workerCaptureOptions, createBeforeCaptureHook, workerSignal, onFrameCaptured, onFrameBuffer, config, parallel, onFailure, onWorkerPhase, hooks?.onWorkerOperation)));
+    const gate = hooks?.verifyFirstSession && createFirstSessionGate(hooks.verifyFirstSession);
+    const results = await Promise.all(tasks.map((task) => executeWorkerTask(task, serverUrl, workerCaptureOptions, createBeforeCaptureHook, workerSignal, onFrameCaptured, onFrameBuffer, config, parallel, onFailure, onWorkerPhase, hooks?.onWorkerOperation, gate)));
     flagSilentWorkerExits(results);
     const errors = results.filter((r) => r.failure || r.error);
     if (errors.length > 0) {

package/dist/services/videoFrameExtractor.d.ts

@@ -188,6 +188,8 @@ export interface VideoExtractionFailure {
      * can contain a local path or a signed source URL.
      */
     error: string;
+    /** ffmpeg's last stderr lines, without paths or URLs: what a producer-facing error may say. */
+    ffmpegReason?: string;
 }
 export type VideoExtractionFailureStatusClass = "http_4xx" | "http_5xx" | "timeout" | "network" | "other";
 export interface VideoExtractionFailureRetry {
@@ -211,8 +213,9 @@ export declare class VideoSourceExtractionError extends Error {
     readonly kind: VideoExtractionFailureKind;
     readonly retryable: boolean;
     readonly diagnostic: string;
+    readonly ffmpegReason?: string | undefined;
     readonly hyperframesVideoSourceExtractionError: true;
-    constructor(kind: VideoExtractionFailureKind, retryable: boolean, message: string, diagnostic?: string);
+    constructor(kind: VideoExtractionFailureKind, retryable: boolean, message: string, diagnostic?: string, ffmpegReason?: string | undefined);
 }
 export declare function isVideoSourceExtractionError(error: unknown): error is VideoSourceExtractionError;
 /**

package/dist/services/videoFrameExtractor.js

@@ -7,7 +7,7 @@
  */
 import { audioGroupsById, isMemberGroupHidden, isSelfOrAncestorHidden } from "./mediaHidden.js";
 import { copyFileSync, existsSync, linkSync, mkdirSync, rmSync } from "fs";
-import { join } from "path";
+import { basename, join } from "path";
 import { cpus } from "os";
 import { createConcurrencyLimit } from "../utils/concurrencyLimit.js";
 import { parseHTML } from "linkedom";
@@ -208,15 +208,34 @@ export class VideoSourceExtractionError extends Error {
     kind;
     retryable;
     diagnostic;
+    ffmpegReason;
     hyperframesVideoSourceExtractionError = true;
-    constructor(kind, retryable, message, diagnostic = message) {
+    constructor(kind, retryable, message, diagnostic = message, ffmpegReason) {
         super(message);
         this.kind = kind;
         this.retryable = retryable;
         this.diagnostic = diagnostic;
+        this.ffmpegReason = ffmpegReason;
         this.name = "VideoSourceExtractionError";
     }
 }
+const FFMPEG_REASON_LINES = 3;
+const FFMPEG_REASON_CHARS = 300;
+/** ffmpeg's last stderr lines for an error that leaves this host: no local path, file name or URL. */
+function ffmpegReasonFrom(stderr, paths) {
+    let text = stderr;
+    for (const known of paths.filter(Boolean).sort((a, b) => b.length - a.length))
+        text = text.split(known).join("<path>");
+    return text
+        .replace(/[a-z][a-z\d+.-]*:\/\/[^\s'"]+/gi, "<url>")
+        .replace(/(?:[a-z]:)?(?:[\\/][^\s\\/:'"]+){2,}/gi, "<path>")
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .slice(-FFMPEG_REASON_LINES)
+        .join(" | ")
+        .slice(-FFMPEG_REASON_CHARS);
+}
 export function isVideoSourceExtractionError(error) {
     return (typeof error === "object" &&
         error !== null &&
@@ -745,13 +764,18 @@ outputDirOverride) {
         const timeoutSuffix = timedOut ? ` (no new frame for ${ffmpegProcessTimeout} ms)` : "";
         const diagnostic = `${hdrPrefix}FFmpeg exited with code ${processResult.exitCode}${timeoutSuffix}: ` +
             processResult.stderr.slice(-500);
+        const ffmpegReason = ffmpegReasonFrom(processResult.stderr, [
+            videoPath,
+            basename(videoPath),
+            videoOutputDir,
+        ]);
         if (timedOut) {
-            throw new VideoSourceExtractionError("ffmpeg_timeout", true, "Video frame extraction timed out", diagnostic);
+            throw new VideoSourceExtractionError("ffmpeg_timeout", true, "Video frame extraction timed out", diagnostic, ffmpegReason);
         }
         const transientIo = /resource temporarily unavailable|device or resource busy|input\/output error/i.test(processResult.stderr);
         throw new VideoSourceExtractionError(transientIo ? "ffmpeg_transient" : "ffmpeg_failed", transientIo, transientIo
             ? "Video frame extraction hit a transient I/O failure"
-            : "Video source could not be decoded", diagnostic);
+            : "Video source could not be decoded", diagnostic, ffmpegReason);
     }
     const framePaths = framePathsFromDirectory(videoOutputDir, format, !!options.frameRanges);
     if (framePaths.size === 0 && duration > 0) {
@@ -1223,13 +1247,9 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
             resolvedVideos.push({ video, videoPath });
         }
         catch (err) {
-            const classified = classifyVideoExtractionError(err);
             errors.push({
-                videoId: video.id,
-                kind: classified.kind,
-                retryable: classified.retryable,
+                ...extractionError(video.id, err),
                 ...(err instanceof UrlDownloadError ? { group: downloadFailureGroup(video.src, err) } : {}),
-                error: classified.diagnostic,
             });
         }
     }
@@ -1417,6 +1437,7 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
             kind: classified.kind,
             retryable: classified.retryable,
             error: classified.diagnostic,
+            ...(classified.ffmpegReason ? { ffmpegReason: classified.ffmpegReason } : {}),
         };
     }
     function scopedExtractionOptions(work) {
@@ -1775,12 +1796,7 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
                 ? `[shared extraction, leader ${outcome.error.videoId}] ${outcome.error.error}`
                 : outcome.error.error;
             results.push({
-                error: {
-                    videoId: prepared.work.video.id,
-                    kind: outcome.error.kind,
-                    retryable: outcome.error.retryable,
-                    error: message,
-                },
+                error: { ...outcome.error, videoId: prepared.work.video.id, error: message },
             });
             continue;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/engine",
-  "version": "0.8.207",
+  "version": "0.8.208",
   "description": "Seekable web page to video rendering engine (Puppeteer + FFmpeg)",
   "repository": {
     "type": "git",
@@ -27,6 +27,10 @@
       "import": "./dist/services/chromeHostCeiling.js",
       "types": "./dist/services/chromeHostCeiling.d.ts"
     },
+    "./chrome-startup": {
+      "import": "./dist/services/chromeStartup.js",
+      "types": "./dist/services/chromeStartup.d.ts"
+    },
     "./system-memory": {
       "import": "./dist/services/systemMemory.js",
       "types": "./dist/services/systemMemory.d.ts"
@@ -50,8 +54,8 @@
     "linkedom": "^0.18.12",
     "puppeteer": "^25.8.0",
     "puppeteer-core": "^25.8.0",
-    "@hyperframes/core": "^0.8.207",
-    "@hyperframes/parsers": "^0.8.207"
+    "@hyperframes/core": "^0.8.208",
+    "@hyperframes/parsers": "^0.8.208"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",