@hypit/hypit 0.1.13 → 0.1.14

package/packages/provider-hyperframes-local/src/activation.ts

@@ -1,3 +1,4 @@
+import { resolve } from "node:path";
 import {
   createRuntimeEndpointAdapterFacet,
   runtimeConfigExact,
@@ -11,7 +12,7 @@ import {
 } from "@hypit/runtime-host-node";
 
 import { createLocalHyperframesProvider } from "./provider.js";
-import { defaultHyperframesCliPath } from "./provider.js";
+import { configuredBrowserPath, browserExecutablePath, selectedBrowserVersion } from "./browser.js";
 import type { HyperframesBrowserGpu, HyperframesQuality, HyperframesWorkers } from "./provider.js";
 import { localHyperframesBrowserProgram } from "./program.js";
 
@@ -21,11 +22,10 @@ const localHyperframesRuntimeAdapter = createRuntimeEndpointAdapterFacet({
     if (context.pool === undefined) throw new Error("local HyperFrames Provider Pool is required");
     const config = runtimeConfigObject(context.config, "local HyperFrames");
     runtimeConfigExact(config, [
-      "nodePath", "hyperframesCliPath", "ffprobePath", "ffmpegPath", "workers", "maxWorkers", "quality", "browserGpu",
+      "nodePath", "chromePath", "browserVersion", "browserCacheDirectory", "browserDownloadBaseUrl", "ffprobePath", "ffmpegPath", "workers", "maxWorkers", "quality", "browserGpu",
       "defaultConcurrency", "browserCapacity", "initializationTimeoutMs", "frameTimeoutMs", "processTimeoutMs", "maxProcessOutputBytes", "maxRenderedBytes",
     ], "local HyperFrames");
     runtimeConfigString(config.nodePath, "HyperFrames nodePath");
-    runtimeConfigString(config.hyperframesCliPath, "HyperFrames hyperframesCliPath");
     runtimeConfigString(config.ffprobePath, "HyperFrames ffprobePath");
     const workers = config.workers;
     if (workers !== undefined && workers !== "auto") {
@@ -40,10 +40,21 @@ const localHyperframesRuntimeAdapter = createRuntimeEndpointAdapterFacet({
       throw new Error("HyperFrames browserGpu is invalid");
     }
     const configuredNode = runtimeConfigString(config.nodePath, "HyperFrames nodePath");
-    const configuredCli = runtimeConfigString(config.hyperframesCliPath, "HyperFrames hyperframesCliPath");
+    const configuredChrome = runtimeConfigString(config.chromePath, "HyperFrames chromePath");
+    const browserVersion = runtimeConfigString(config.browserVersion, "HyperFrames browserVersion");
+    const browserDownloadBaseUrl = runtimeConfigString(config.browserDownloadBaseUrl, "HyperFrames browserDownloadBaseUrl");
+    const configuredCache = runtimeConfigString(config.browserCacheDirectory, "HyperFrames browserCacheDirectory");
+    const chromePath = configuredBrowserPath({ ...(configuredChrome === undefined ? {} : {
+      chromePath: resolve(context.dataRoot, configuredChrome),
+    }) });
+    const browser = {
+      ...(browserVersion === undefined ? {} : { browserVersion }),
+      ...(browserDownloadBaseUrl === undefined ? {} : { browserDownloadBaseUrl }),
+      ...(chromePath === undefined ? {} : { chromePath }),
+      ...(configuredCache === undefined ? {} : { browserCacheDirectory: resolve(context.dataRoot, configuredCache) }),
+    };
     const configuredFfprobe = runtimeConfigString(config.ffprobePath, "HyperFrames ffprobePath");
     const nodePath = resolveRuntimeExecutable(context.dataRoot, configuredNode ?? process.execPath);
-    const hyperframesCliPath = () => resolveRuntimeExecutable(context.dataRoot, configuredCli ?? defaultHyperframesCliPath());
     const configuredFfmpeg = runtimeConfigString(config.ffmpegPath, "HyperFrames ffmpegPath");
     const ffmpegPath = resolveRuntimeExecutable(context.dataRoot, configuredFfmpeg ?? "ffmpeg");
     const ffprobePath = resolveRuntimeExecutable(context.dataRoot, configuredFfprobe ?? "ffprobe");
@@ -60,6 +71,7 @@ const localHyperframesRuntimeAdapter = createRuntimeEndpointAdapterFacet({
         instance: context.instance,
         pool: context.pool,
         nodePath,
+        ...browser,
         ffprobePath,
         ffmpegPath,
         ...(workers === undefined ? {} : { workers: workers as HyperframesWorkers }),
@@ -77,11 +89,13 @@ const localHyperframesRuntimeAdapter = createRuntimeEndpointAdapterFacet({
       program: localHyperframesBrowserProgram({
         id: context.instance,
         nodePath,
-        hyperframesCliPath,
+        ...browser,
         ffprobePath,
         ffmpegPath,
       }),
       diagnose: async () => [
+        { severity: "info", code: "HYPERFRAMES_BROWSER_SELECTION", subject: context.instance,
+          message: `${chromePath === undefined ? `Managed Chrome Headless Shell ${selectedBrowserVersion(browser)} (${browserVersion === undefined ? "Provider recommendation" : "Profile version"})` : "Profile browser"}: ${browserExecutablePath(browser)}` },
         ...await diagnoseRuntimeExecutable({ root: context.dataRoot, configured: configuredFfmpeg, fallback: "ffmpeg", subject: "FFmpeg" }),
         ...await diagnoseRuntimeExecutable({
           root: context.dataRoot,

package/packages/provider-hyperframes-local/src/browser-install.ts

@@ -0,0 +1,5 @@
+import { installRenderBrowser } from "./browser.js";
+
+const [cacheDir, version, baseUrl] = process.argv.slice(2);
+if (process.argv.length < 4 || process.argv.length > 5 || !cacheDir || !version) throw new Error("Expected the render browser cache directory, exact version and optional archive base URL");
+await installRenderBrowser(cacheDir, version, baseUrl);

package/packages/provider-hyperframes-local/src/browser.ts

@@ -0,0 +1,118 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { access, stat } from "node:fs/promises";
+import { constants, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { Browser, computeExecutablePath, detectBrowserPlatform, getDownloadUrl, install, uninstall } from "@puppeteer/browsers";
+
+// The Provider's release owns this recommendation alongside its engine dependencies.
+// It is installation input, not a second browser discovery policy in executable code.
+const manifest = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+export const recommendedBrowserVersion: string = exactBrowserVersion(manifest.hypit?.renderBrowser?.version);
+
+function exactBrowserVersion(value: unknown): string {
+  if (typeof value !== "string" || !/^\d+\.\d+\.\d+\.\d+$/u.test(value)) {
+    throw new Error("HyperFrames browserVersion must be an exact four-part Chrome version; channels such as latest are not selections");
+  }
+  return value;
+}
+
+export type BrowserOptions = {
+  readonly chromePath?: string;
+  readonly browserVersion?: string;
+  readonly browserCacheDirectory?: string;
+  /** Chrome for Testing archive base URL; used only during explicit preparation. */
+  readonly browserDownloadBaseUrl?: string;
+};
+
+export function browserDownloadBaseUrl(options: BrowserOptions): string | undefined {
+  const value = options.browserDownloadBaseUrl;
+  if (value === undefined) return undefined;
+  if (options.chromePath !== undefined) {
+    throw new Error("HyperFrames chromePath and browserDownloadBaseUrl are mutually exclusive; a user-managed browser is not downloaded");
+  }
+  let url: URL;
+  try { url = new URL(value); } catch {
+    throw new Error("HyperFrames browserDownloadBaseUrl must be an absolute HTTP(S) archive base URL");
+  }
+  if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
+    throw new Error("HyperFrames browserDownloadBaseUrl must be an HTTP(S) archive base URL without credentials, query or fragment");
+  }
+  return url.href.replace(/\/+$/u, "");
+}
+
+export function browserDownloadUrl(options: BrowserOptions): string {
+  const baseUrl = browserDownloadBaseUrl(options);
+  const version = selectedBrowserVersion(options);
+  if (version === undefined) throw new Error("A user-managed browser has no download URL");
+  const platform = detectBrowserPlatform();
+  if (platform === undefined) throw new Error("The managed render browser is unavailable for this host; select chromePath");
+  return getDownloadUrl(Browser.CHROMEHEADLESSSHELL, platform, version, baseUrl).href;
+}
+
+/** Only Profile/caller configuration selects a browser; environment hints are not inputs. */
+export function configuredBrowserPath(options: BrowserOptions): string | undefined {
+  browserDownloadBaseUrl(options);
+  if (options.chromePath !== undefined && options.browserVersion !== undefined) {
+    throw new Error("HyperFrames chromePath and browserVersion are mutually exclusive");
+  }
+  if (options.chromePath === "") throw new Error("HyperFrames chromePath must not be empty");
+  return options.chromePath === undefined ? undefined : resolve(options.chromePath);
+}
+
+export function selectedBrowserVersion(options: BrowserOptions): string | undefined {
+  return configuredBrowserPath(options) === undefined
+    ? exactBrowserVersion(options.browserVersion ?? recommendedBrowserVersion) : undefined;
+}
+
+export function browserCacheDirectory(options: BrowserOptions): string {
+  return resolve(options.browserCacheDirectory ?? join(homedir(), ".cache", "hyperframes", "chrome"));
+}
+
+export function browserExecutablePath(options: BrowserOptions): string {
+  const configured = configuredBrowserPath(options);
+  if (configured !== undefined) return configured;
+  const version = selectedBrowserVersion(options)!;
+  try {
+    return computeExecutablePath({
+      browser: Browser.CHROMEHEADLESSSHELL, buildId: version, cacheDir: browserCacheDirectory(options),
+    });
+  } catch (error) {
+    throw new Error("The managed render browser is unavailable for this host. Select an installed Chrome/Chromium with the Provider's chromePath.", { cause: error });
+  }
+}
+
+export async function requireBrowserExecutable(path: string, version?: string): Promise<void> {
+  try {
+    if (!(await stat(path)).isFile()) throw new Error("Browser path is not a file");
+    await access(path, constants.X_OK);
+    const { stdout } = await promisify(execFile)(path, ["--version"], { timeout: 15_000, windowsHide: true });
+    if (!stdout.trim()) throw new Error("Browser returned no version");
+    if (version !== undefined && !stdout.trim().split(/\s+/u).includes(version)) {
+      throw new Error(`Expected Chrome Headless Shell ${version}, received ${stdout.trim()}`);
+    }
+  }
+  catch (error) {
+    throw new Error(`Render browser is unavailable at ${path}: ${error instanceof Error ? error.message : String(error)}. Prepare the selected Runtime with hypit runtime up --runtime <profile>, or correct its chromePath.`, { cause: error });
+  }
+}
+
+/** Called only by the selected ManagedProgram's explicit installation command. */
+export async function installRenderBrowser(cacheDir: string, version: string, downloadBaseUrl?: string): Promise<void> {
+  const buildId = exactBrowserVersion(version);
+  const options = { browserVersion: buildId, ...(downloadBaseUrl === undefined ? {} : { browserDownloadBaseUrl: downloadBaseUrl }) };
+  const baseUrl = browserDownloadBaseUrl(options);
+  const url = browserDownloadUrl(options);
+  const path = computeExecutablePath({ browser: Browser.CHROMEHEADLESSSHELL, buildId, cacheDir });
+  process.stdout.write(`Preparing Chrome Headless Shell ${buildId} at ${path}\nDownload source: ${url}\n`);
+  try { await requireBrowserExecutable(path, buildId); return; } catch { /* Explicit preparation repairs this selection only. */ }
+  await uninstall({ browser: Browser.CHROMEHEADLESSSHELL, buildId, cacheDir });
+  try {
+    // A single baseUrl uses the library's DefaultProvider without its provider-chain fallback.
+    await install({ browser: Browser.CHROMEHEADLESSSHELL, buildId, cacheDir, ...(baseUrl === undefined ? {} : { baseUrl }) });
+    await requireBrowserExecutable(path, buildId);
+  } catch (error) {
+    throw new Error(`Could not prepare Chrome Headless Shell ${buildId} from ${url} at ${path}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+  }
+}

package/packages/provider-hyperframes-local/src/capture-bootstrap.ts

@@ -1,5 +1,5 @@
 /**
- * Preloaded into the disposable capture process, which never enters `bin/hypit.mjs`.
+ * Preloaded into capture and browser-install processes, which never enter `bin/hypit.mjs`.
  *
  * `module.registerHooks` is process-local, so the resolver the launcher installs does not
  * reach a child that Node starts directly. This registers the same resolution environment
@@ -11,11 +11,9 @@
  */
 import { resolve } from "node:path";
 
-// `bin/hypit.mjs` publishes this for every process it starts; the fallback mirrors
-// `packages/video-cli/src/distribution.ts` for callers that import a Distribution directly.
-const distributionRoot = resolve(
-  process.env.HYPIT_DISTRIBUTION_ROOT ?? resolve(import.meta.dirname, "../../.."),
-);
+// This preload belongs to the Provider the parent actually loaded. Inherited shell
+// hints must not redirect its dependencies to a different Hypit installation.
+const distributionRoot = resolve(import.meta.dirname, "../../..");
 
 const { installDistributionPackageResolution, installExternalPackageResolution } =
   await import("../../package-loader-node/src/distribution-resolution.js");

package/packages/provider-hyperframes-local/src/capture-exit.ts

@@ -0,0 +1,24 @@
+import { writeSync } from "node:fs";
+import { killRenderDescendantsSync } from "./process-tree.js";
+
+// Installed before loading the engine: process.exit and uncaught exceptions can
+// bypass async finally blocks, including during engine import/browser launch.
+// Keep cleanup inside the still-live owner, not a history of browser PIDs.
+const cleanup = () => {
+  try { killRenderDescendantsSync(process.pid); }
+  catch (error) {
+    writeSync(2, `Render exit cleanup could not be confirmed: ${String(error)}\n`);
+  }
+};
+const terminate = () => process.exit(143);
+const interrupt = () => process.exit(130);
+process.once("exit", cleanup);
+process.once("SIGTERM", terminate);
+process.once("SIGINT", interrupt);
+
+/** Call only after capture has closed every resource successfully. */
+export function releaseCaptureExitCleanup(): void {
+  process.off("exit", cleanup);
+  process.off("SIGTERM", terminate);
+  process.off("SIGINT", interrupt);
+}

package/packages/provider-hyperframes-local/src/capture-process.ts

@@ -1,58 +1,12 @@
 import type { ExecutionDiagnostic } from "@hypit/runtime";
-import { execFile, spawn } from "node:child_process";
-import { promisify } from "node:util";
+import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { setTimeout as delay } from "node:timers/promises";
+import { killRenderTree } from "./process-tree.js";
 import type { CaptureInput } from "./capture.js";
 import type { HyperframesRenderProgress } from "./render.js";
 
-const exec = promisify(execFile);
 const cleanupMs = 5_000;
 
-/** Chrome starts its own process group, so stopping only the Node child is insufficient. */
-async function killRenderTree(pid: number): Promise<void> {
-  if (process.platform === "win32") {
-    try {
-      await exec("taskkill", ["/PID", String(pid), "/T", "/F"], { windowsHide: true, timeout: cleanupMs });
-    } catch (error) {
-      // The worker may exit after reporting completion, before taskkill opens it.
-      // Ask the OS whether it is gone; localized taskkill output is not an API.
-      try { process.kill(pid, 0); }
-      catch (probeError) {
-        if ((probeError as NodeJS.ErrnoException).code === "ESRCH") return;
-      }
-      throw error;
-    }
-    return;
-  }
-  const descendants = [pid];
-  for (let i = 0; i < descendants.length; i++) {
-    const children = await exec("pgrep", ["-P", String(descendants[i])], { timeout: cleanupMs })
-      .then(({ stdout }) => stdout.trim().split(/\s+/u).filter(Boolean).map(Number),
-        (error) => { if ((error as { code?: unknown }).code === 1) return []; throw error; });
-    for (const child of children) if (!descendants.includes(child)) descendants.push(child);
-  }
-  // Kill the whole tree before waiting: only after every ancestor is dead are
-  // orphaned descendants reparented and reaped, making kill(pid, 0) read ESRCH.
-  for (const child of descendants.reverse()) {
-    for (const target of [-child, child]) {
-      try { process.kill(target, "SIGKILL"); }
-      catch (error) { if ((error as NodeJS.ErrnoException).code !== "ESRCH") throw error; }
-    }
-  }
-  const deadline = Date.now() + cleanupMs;
-  let remaining = descendants;
-  while (remaining.length > 0) {
-    remaining = remaining.filter((child) => {
-      try { process.kill(child, 0); return true; }
-      catch (error) { if ((error as NodeJS.ErrnoException).code === "ESRCH") return false; throw error; }
-    });
-    if (remaining.length === 0) break;
-    if (Date.now() >= deadline) throw new Error(`Render process ${remaining[0]} did not stop after SIGKILL`);
-    await delay(20);
-  }
-}
-
 /** One disposable execution, with no persisted state or resubmission behavior. */
 export async function runCaptureProcess(
   input: CaptureInput,
@@ -68,6 +22,7 @@ export async function runCaptureProcess(
     const child = spawn(process.execPath, [
       "--import", import.meta.resolve("tsx"),
       "--import", new URL("./capture-bootstrap.ts", import.meta.url).href,
+      "--import", new URL("./capture-exit.ts", import.meta.url).href,
       fileURLToPath(entry),
     ], {
       detached: process.platform !== "win32", windowsHide: true,
@@ -76,6 +31,7 @@ export async function runCaptureProcess(
     let failure: Error | undefined;
     let completed = false;
     let closed = false;
+    let exited = false;
     let outputBytes = 0;
     let stderr = "";
     let diagnostics = Promise.resolve();
@@ -83,6 +39,14 @@ export async function runCaptureProcess(
     let killing: Promise<void> | undefined;
     const kill = () => {
       if (grace !== undefined) clearTimeout(grace);
+      grace = undefined;
+      // A PID is no longer ours after exit. Inherited pipes can outlive it, but
+      // looking up that old PID cannot recover the former process tree safely.
+      if (exited) {
+        child.stdout?.destroy();
+        child.stderr?.destroy();
+        return Promise.resolve();
+      }
       killing ??= (child.pid === undefined ? Promise.resolve() : killRenderTree(child.pid)).catch((error) => {
         if (!completed) failure = new Error(`${failure?.message ?? "Render cleanup failed"}; ${String(error)}`);
         diagnostic({ level: "warning", message: `Render process-tree cleanup could not be confirmed: ${String(error)}` });
@@ -103,7 +67,9 @@ export async function runCaptureProcess(
     };
     const awaitExit = () => {
       grace ??= setTimeout(() => {
-        diagnostic({ level: "warning", message: `Render process did not exit within ${cleanupMs} ms; terminating its remaining process tree` });
+        diagnostic({ level: "warning", message: exited
+          ? `Render process exited but its output pipes did not close within ${cleanupMs} ms; closing this execution's pipes`
+          : `Render process did not exit within ${cleanupMs} ms; terminating its remaining process tree` });
         void kill();
       }, cleanupMs);
     };
@@ -140,14 +106,25 @@ export async function runCaptureProcess(
       }
     });
     child.on("error", (error) => { failure ??= error; void kill(); });
-    child.on("close", () => {
+    child.once("exit", (code, exitSignal) => {
+      exited = true;
+      if (!completed && failure === undefined) {
+        failure = new Error(`HyperFrames process exited before completion (${exitSignal ?? `code ${String(code)}`})`);
+      }
+      if (exitSignal !== null && killing === undefined) {
+        diagnostic({ level: "warning", message: `Render process was terminated by ${exitSignal}; descendant cleanup could not be confirmed` });
+      }
+      // An abruptly orphaned descendant may still hold stdout/stderr open.
+      awaitExit();
+    });
+    child.on("close", (code, exitSignal) => {
       closed = true;
       if (grace !== undefined) clearTimeout(grace);
       signal.removeEventListener("abort", abort);
       void (killing ?? Promise.resolve()).then(async () => {
         await diagnostics;
-        if (failure !== undefined) reject(failure);
-        else if (!completed) reject(new Error(`HyperFrames process exited before completion: ${stderr}`));
+        if (failure !== undefined) reject(new Error(`${failure.message}${stderr ? `\n${stderr}` : ""}`, { cause: failure }));
+        else if (!completed) reject(new Error(`HyperFrames process exited before completion (${exitSignal ?? `code ${String(code)}`}): ${stderr}`));
         else resolve();
       });
     });

package/packages/provider-hyperframes-local/src/capture-worker.ts

@@ -1,3 +1,4 @@
+import { releaseCaptureExitCleanup } from "./capture-exit.js";
 import { captureStagedVisual } from "./capture.js";
 import type { CaptureInput } from "./capture.js";
 
@@ -13,6 +14,7 @@ const finish = (value: { type: "completed" } | { type: "failed"; error: string }
   if (value.type === "failed") { report(value); return; }
   // Successful capture has closed its resources. Flush the result before closing our IPC handle;
   // our own disconnect is not a cancellation by the owner.
+  releaseCaptureExitCleanup();
   process.off("disconnect", disconnected);
   process.off("message", receive);
   if (!process.connected) return;

package/packages/provider-hyperframes-local/src/capture.ts

@@ -3,7 +3,7 @@ import { join, relative, resolve, sep } from "node:path";
 import type { HyperframesDocument } from "@hypit/hyperframes";
 import type { MediaFrameRange } from "@hypit/media";
 import type { HyperframesRenderProgress, resolveExecutionOptions } from "./render.js";
-import { assert, runProcess } from "./process.js";
+import { assert, mediaExecutablePath, runProcess } from "./process.js";
 import { verifyOutput } from "./output.js";
 import { distributeFrameRange, sourceFrameAt, sourceWindows, videoSlots } from "./sampling.js";
 import { renderWorkerLimit } from "./render.js";
@@ -13,7 +13,7 @@ import { createOpaqueFrameCapture } from "./opaque-capture.js";
 export type CaptureInput = {
   readonly document: HyperframesDocument;
   readonly range: MediaFrameRange;
-  readonly config: ReturnType<typeof resolveExecutionOptions>;
+  readonly config: ReturnType<typeof resolveExecutionOptions> & { readonly chromePath: string };
   readonly directory: string;
   readonly engineModule: string;
   readonly producerModule: string;
@@ -36,6 +36,13 @@ export async function captureStagedVisual(input: CaptureInput, controller: Abort
   const started = performance.now();
   const elapsedMs = () => Math.round(performance.now() - started);
   const engine = await import(input.engineModule) as typeof import("@hyperframes/engine");
+  const [ffmpegPath, ffprobePath] = await Promise.all([
+    mediaExecutablePath(config.ffmpegPath), mediaExecutablePath(config.ffprobePath),
+  ]);
+  // This is one disposable render process. Use the engine's public override
+  // ports here without changing the Runtime owner's environment or other renders.
+  process.env[engine.FFMPEG_PATH_ENV] = ffmpegPath;
+  process.env[engine.FFPROBE_PATH_ENV] = ffprobePath;
   const { createFileServer } = await import(input.producerModule) as typeof import("@hyperframes/producer");
   type Session = Awaited<ReturnType<typeof engine.createCaptureSession>>;
   const sessions = new Set<Session>();
@@ -158,7 +165,7 @@ export async function captureStagedVisual(input: CaptureInput, controller: Abort
             const source = sources.get(slot.src);
             return source === undefined ? [] : [{ id: slot.id, width: source.width, height: source.height }];
           }),
-        }, injector, { browserGpuMode: config.browserGpu, enableBrowserPool: false, forceScreenshot: true, useDrawElement: false });
+        }, injector, { chromePath: config.chromePath, browserGpuMode: config.browserGpu, enableBrowserPool: false, forceScreenshot: true, useDrawElement: false });
         sessions.add(session);
         signal.throwIfAborted();
         const activeSession = session;
@@ -235,14 +242,14 @@ export async function captureStagedVisual(input: CaptureInput, controller: Abort
     const output = join(work, "visual.mp4");
     onProgress({ phase: "encoding", elapsedMs: elapsedMs() });
     const crf = { draft: 28, standard: 23, high: 18 }[config.quality];
-    await runProcess({ executable: config.ffmpegPath,
+    await runProcess({ executable: ffmpegPath,
       argv: ["-v", "error", "-y", "-framerate", `${fps.num}/${fps.den}`, "-i", join(outputFrames, "%09d.png"),
         "-frames:v", String(frameCount), "-an", "-c:v", "libx264", "-crf", String(crf),
         "-preset", config.quality === "draft" ? "veryfast" : "medium", "-pix_fmt", "yuv420p", "-movflags", "+faststart", output],
       timeoutMs: config.processTimeoutMs, maxOutputBytes: config.maxProcessOutputBytes, signal });
     const outputStat = await stat(output);
     assert(outputStat.size > 0 && outputStat.size <= config.maxRenderedBytes, "HyperFrames output is empty or exceeds its byte limit");
-    await verifyOutput({ path: output, document: { ...document, frameCount }, ffprobePath: config.ffprobePath,
+    await verifyOutput({ path: output, document: { ...document, frameCount }, ffprobePath,
       timeoutMs: config.processTimeoutMs, maxOutputBytes: config.maxProcessOutputBytes, signal });
     signal.throwIfAborted();
     return output;

package/packages/provider-hyperframes-local/src/opaque-capture.ts

@@ -22,33 +22,61 @@ export async function createOpaqueFrameCapture(session: CaptureSession) {
   const cdp = await getCdpSession(page);
   // MP4 has no alpha channel. The authored Canvas paints over this final matte.
   await cdp.send("Emulation.setDefaultBackgroundColorOverride", { color: { r: 0, g: 0, b: 0, a: 1 } });
-  // These decoded image handles belong to this page, just like its DOM. Retain
-  // only URLs used by inline background images; changing a style can need a load
-  // even after initializeSession has finished its initial resource readiness.
+  // Image readiness belongs to this page. A seek can select a new image through
+  // attributes, a CSS class or a pseudo-element after initial page readiness.
   await page.evaluate(() => {
     const decoded = new Map<string, Promise<void>>();
+    const images = {
+      load(url: string): Promise<void> {
+        let ready = decoded.get(url);
+        if (ready === undefined) {
+          const image = new Image();
+          image.src = url;
+          ready = image.decode().catch(error => {
+            throw new Error(`HyperFrames image could not be decoded: ${url}`, { cause: error });
+          });
+          decoded.set(url, ready);
+        }
+        return ready;
+      },
+      background(value: string, pending: Promise<unknown>[]) {
+        for (const match of value.matchAll(/url\(\s*(?:"((?:\\.|[^"\\])*)"|'((?:\\.|[^'\\])*)'|([^\s"'()]+))\s*\)/gu)) {
+          const url = (match[1] ?? match[2] ?? match[3] ?? "").trim();
+          if (url) pending.push(this.load(url));
+        }
+      },
+      style(style: CSSStyleDeclaration, pending: Promise<unknown>[]) {
+        for (const value of [style.backgroundImage, style.maskImage, style.borderImageSource, style.listStyleImage, style.content]) {
+          this.background(value, pending);
+        }
+      },
+    };
     (window as unknown as { __hypitPrepareImages: () => Promise<void> }).__hypitPrepareImages = async () => {
       const pending: Promise<unknown>[] = [];
-      if (document.fonts.status === "loading") pending.push(document.fonts.ready);
       for (const image of Array.from(document.images)) {
-        if (!image.complete) pending.push(image.decode());
+        if ((image.currentSrc || image.getAttribute("src") || image.getAttribute("srcset"))
+          && (!image.complete || image.naturalWidth === 0)) {
+          pending.push(image.decode().catch(error => {
+            throw new Error(`HyperFrames image could not be decoded: ${image.currentSrc || image.src}`, { cause: error });
+          }));
+        }
       }
-      for (const element of Array.from(document.querySelectorAll<HTMLElement>('[style*="background"]'))) {
-        const background = element.style.backgroundImage;
-        for (const match of background.matchAll(/url\(\s*(?:"((?:\\.|[^"])*)"|'((?:\\.|[^'])*)'|([^)]*))\s*\)/gu)) {
-          const url = (match[1] ?? match[2] ?? match[3] ?? "").trim();
-          if (!url) continue;
-          let ready = decoded.get(url);
-          if (ready === undefined) {
-            const image = new Image();
-            image.src = url;
-            ready = image.decode();
-            decoded.set(url, ready);
-          }
-          pending.push(ready);
+      for (const element of Array.from(document.querySelectorAll("*"))) {
+        images.style(getComputedStyle(element), pending);
+        for (const pseudo of ["::before", "::after"]) {
+          const style = getComputedStyle(element, pseudo);
+          if (style.content !== "none" && style.content !== "normal") images.style(style, pending);
         }
       }
+      for (const image of Array.from(document.querySelectorAll("svg image"))) {
+        const href = image.getAttribute("href") ?? image.getAttributeNS("http://www.w3.org/1999/xlink", "href");
+        if (href) pending.push(images.load(new URL(href, document.baseURI).href));
+      }
       await Promise.all(pending);
+      await document.fonts.ready;
+      document.fonts.forEach(font => {
+        if (font.status === "error") throw new Error(`HyperFrames font could not be loaded: ${font.family}`);
+      });
     };
   });
   return async (frame: number) => {

package/packages/provider-hyperframes-local/src/options.ts

@@ -2,9 +2,9 @@ export type HyperframesWorkers = number | "auto";
 export type HyperframesQuality = "draft" | "standard" | "high";
 export type HyperframesBrowserGpu = "auto" | "software" | "hardware";
 
-export type HyperframesExecutionOptions = {
+export type HyperframesExecutionOptions = import("./browser.js").BrowserOptions & {
   readonly ffprobePath?: string;
-  /** Final H.264 encoder. Source extraction uses the pinned engine's binary resolver. */
+  /** Selected FFmpeg command for both source extraction and final H.264 encoding. */
   readonly ffmpegPath?: string;
   /** Parallel Chrome workers inside one render. This is separate from Provider request concurrency. */
   readonly workers?: HyperframesWorkers;

package/packages/provider-hyperframes-local/src/process-tree.ts

@@ -0,0 +1,82 @@
+import { execFile, execFileSync } from "node:child_process";
+import { promisify } from "node:util";
+import { setTimeout as delay } from "node:timers/promises";
+
+const exec = promisify(execFile);
+const cleanupMs = 5_000;
+
+/** Chrome starts its own process group, so stopping only the Node child is insufficient. */
+export async function killRenderTree(pid: number): Promise<void> {
+  if (process.platform === "win32") {
+    try {
+      await exec("taskkill", ["/PID", String(pid), "/T", "/F"], { windowsHide: true, timeout: cleanupMs });
+    } catch (error) {
+      // The worker may exit after reporting completion, before taskkill opens it.
+      // Ask the OS whether it is gone; localized taskkill output is not an API.
+      try { process.kill(pid, 0); }
+      catch (probeError) {
+        if ((probeError as NodeJS.ErrnoException).code === "ESRCH") return;
+      }
+      throw error;
+    }
+    return;
+  }
+  const descendants = [pid];
+  for (let i = 0; i < descendants.length; i++) {
+    const children = await exec("pgrep", ["-P", String(descendants[i])], { timeout: cleanupMs })
+      .then(({ stdout }) => stdout.trim().split(/\s+/u).filter(Boolean).map(Number),
+        (error) => { if ((error as { code?: unknown }).code === 1) return []; throw error; });
+    for (const child of children) if (!descendants.includes(child)) descendants.push(child);
+  }
+  // Kill the whole tree before waiting: only after every ancestor is dead are
+  // orphaned descendants reparented and reaped, making kill(pid, 0) read ESRCH.
+  for (const child of descendants.reverse()) {
+    for (const target of [-child, child]) {
+      try { process.kill(target, "SIGKILL"); }
+      catch (error) { if ((error as NodeJS.ErrnoException).code !== "ESRCH") throw error; }
+    }
+  }
+  const deadline = Date.now() + cleanupMs;
+  let remaining = descendants;
+  while (remaining.length > 0) {
+    remaining = remaining.filter((child) => {
+      try { process.kill(child, 0); return true; }
+      catch (error) { if ((error as NodeJS.ErrnoException).code === "ESRCH") return false; throw error; }
+    });
+    if (remaining.length === 0) break;
+    if (Date.now() >= deadline) throw new Error(`Render process ${remaining[0]} did not stop after SIGKILL`);
+    await delay(20);
+  }
+}
+
+/** Exit callbacks cannot await: stop live descendants before the owner is reparented. */
+export function killRenderDescendantsSync(pid: number): void {
+  if (process.platform === "win32") {
+    // taskkill owns the traversal, including this exiting process, on Windows.
+    execFileSync("taskkill", ["/PID", String(pid), "/T", "/F"], {
+      windowsHide: true, timeout: cleanupMs, stdio: "pipe",
+    });
+    return;
+  }
+  const descendants = [pid];
+  for (let i = 0; i < descendants.length; i++) {
+    let output: string;
+    try {
+      output = execFileSync("pgrep", ["-P", String(descendants[i])], {
+        encoding: "utf8", timeout: cleanupMs, stdio: ["ignore", "pipe", "pipe"],
+      });
+    } catch (error) {
+      if ((error as { status?: unknown }).status === 1) continue;
+      throw error;
+    }
+    for (const child of output.trim().split(/\s+/u).filter(Boolean).map(Number)) {
+      if (!descendants.includes(child)) descendants.push(child);
+    }
+  }
+  for (const child of descendants.slice(1).reverse()) {
+    for (const target of [-child, child]) {
+      try { process.kill(target, "SIGKILL"); }
+      catch (error) { if ((error as NodeJS.ErrnoException).code !== "ESRCH") throw error; }
+    }
+  }
+}