@hypit/hypit 0.1.12 → 0.1.14

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,
@@ -75,6 +30,8 @@ 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();
@@ -82,16 +39,39 @@ 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)}` });
         child.kill("SIGKILL");
       });
       return killing;
     };
     const stop = (error: Error) => {
       failure ??= error;
+      if (closed) return;
       if (child.connected) child.send({ type: "abort", error: failure.message }, () => {});
-      grace ??= setTimeout(() => { void kill(); }, cleanupMs);
+      awaitExit();
+    };
+    const diagnostic = (value: ExecutionDiagnostic) => {
+      if (onDiagnostic === undefined) return;
+      diagnostics = diagnostics.then(() => onDiagnostic(value))
+        .catch((error) => stop(error instanceof Error ? error : new Error(String(error))));
+    };
+    const awaitExit = () => {
+      grace ??= setTimeout(() => {
+        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);
     };
     const abort = () => stop(signal.reason instanceof Error ? signal.reason : new Error(String(signal.reason)));
     signal.addEventListener("abort", abort, { once: true });
@@ -104,10 +84,7 @@ export async function runCaptureProcess(
       pipe?.setEncoding("utf8");
       pipe?.on("data", (text: string) => {
         log(Buffer.from(text), stream === "stderr");
-        if (onDiagnostic !== undefined && text.trim()) {
-          diagnostics = diagnostics.then(() => onDiagnostic({ stream, level: "info", message: text.trimEnd() }))
-            .catch((error) => stop(error instanceof Error ? error : new Error(String(error))));
-        }
+        if (text.trim()) diagnostic({ stream, level: "info", message: text.trimEnd() });
       });
     }
     child.on("message", (value: { type: string; event?: HyperframesRenderProgress; error?: string }) => {
@@ -117,19 +94,37 @@ export async function runCaptureProcess(
         stop(new Error(value.error));
       } else if (value.type === "completed" || value.type === "failed") {
         completed = value.type === "completed";
-        if (!completed) failure ??= new Error(value.error);
-        // The worker has finished cleanup. Terminate any leftover descendants before releasing capacity.
-        void kill();
+        if (completed) {
+          // Successful capture has closed its resources and will disconnect after this message.
+          awaitExit();
+        } else {
+          failure ??= new Error(value.error);
+          // Resource cleanup may itself have failed. Keep the worker alive until
+          // its remaining descendants have been discovered and terminated.
+          void kill();
+        }
       }
     });
     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,17 +1,38 @@
+import { releaseCaptureExitCleanup } from "./capture-exit.js";
 import { captureStagedVisual } from "./capture.js";
 import type { CaptureInput } from "./capture.js";
 
 const controller = new AbortController();
 const message = (error: unknown) => error instanceof Error ? error.message : String(error);
+const disconnected = () => controller.abort(new Error("Render owner disconnected"));
+const report = (value: object) => {
+  if (process.connected) process.send?.(value, undefined, undefined, (error) => { if (error) controller.abort(error); });
+};
+const finish = (value: { type: "completed" } | { type: "failed"; error: string }) => {
+  // Failure can leave descendants behind. Keep the owner connected until it has
+  // discovered and stopped that tree, rather than orphaning it by exiting first.
+  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;
+  process.send?.(value, undefined, undefined, (error) => {
+    if (error) { console.error(message(error)); process.exitCode = 1; }
+    if (process.connected) process.disconnect();
+  });
+};
 controller.signal.addEventListener("abort", () => {
-  process.send?.({ type: "stopping", error: message(controller.signal.reason) });
+  report({ type: "stopping", error: message(controller.signal.reason) });
 }, { once: true });
-process.on("message", (value: { type: "start"; input: CaptureInput } | { type: "abort"; error: string }) => {
+const receive = (value: { type: "start"; input: CaptureInput } | { type: "abort"; error: string }) => {
   if (value.type === "abort") { controller.abort(new Error(value.error)); return; }
   void captureStagedVisual(value.input, controller,
-    (event) => process.send?.({ type: "progress", event })).then(
-    () => process.send?.({ type: "completed" }),
-    (error) => process.send?.({ type: "failed", error: message(error) }),
+    (event) => report({ type: "progress", event })).then(
+    () => finish({ type: "completed" }),
+    (error) => finish({ type: "failed", error: message(error) }),
   );
-});
-process.on("disconnect", () => controller.abort(new Error("Render owner disconnected")));
+};
+process.on("message", receive);
+process.on("disconnect", disconnected);

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; }
+    }
+  }
+}