@hypit/hypit 0.1.4 → 0.1.6

package/packages/provider-hyperframes-local/README.md

@@ -9,24 +9,32 @@ content identity or hidden output metadata.
 
 Normalized transparent videos displayed by Media or project components use the ordinary video path.
 The engine decodes them to PNG frames with alpha, then Chrome blends them with lower layers and
-the authored Canvas background. PNG is the intermediate capture format; it does not ask to erase
-the Film's background. The returned MP4 contains the completed composition.
+the authored Canvas background. Final frames use fast PNG encoding after Chrome has composited
+the image onto an opaque canvas (black beneath the authored background). This trades intermediate
+compression effort for speed without JPEG frame compression. Source alpha, CSS filters, canvas and
+WebGL remain part of the browser composition. The returned MP4 contains the completed composition.
 
 Runtime configuration separates work size from shared capacity:
 
 - `defaultConcurrency` limits whole render requests admitted by the Endpoint's Runtime capacity resource.
 - Optional `browserCapacity` limits Chrome slots shared by all render Needs in the same `pool`.
-  Each Need reserves its actual worker count atomically with the whole-request slot. A request larger
-  than this budget reports a configuration error; it does not silently reduce the requested workers.
+  Each Need reserves its fixed count or automatic ceiling atomically with the whole-request slot.
+  An explicit count larger than this budget reports a configuration error. Auto fits its ceiling
+  to the shared budget before admission.
   Both reservations last for the whole Need, including preparation and final encoding. Closing one
   Chrome early does not release part of that reservation. Without `browserCapacity`, admission uses
   the whole-request limit alone.
 - `workers` controls independent Chrome processes inside one admitted render. Explicit counts are
-  honored, capped only by selected frame count. `auto` uses half the available CPU parallelism,
-  bounded to 1–4 workers.
+  honored, capped only by selected frame count. `auto` starts below its ceiling, then compares useful
+  capture batches before adding another browser. Insufficient benefit or falling throughput retires
+  surplus browsers between batches. Completed frames are retained; there is no calibration render.
+- Optional `maxWorkers` sets the automatic ceiling. Without it, the Provider leaves two CPU slots
+  and half the machine/container memory for other work, budgeting about 1.5 GiB per Chrome process.
+  Auto also caps the reservation to the number of roughly one-second batches in the selected range.
 
 The Runtime Profile configures these controls through the Provider because they are deployment policy.
-`auto` is resolved when the Provider is activated, so admission and execution use the same count. It never
+The automatic ceiling is fixed at activation, and range sizing is identical in admission and execution.
+Actual concurrency adapts inside that reservation; it is not a machine-wide history or performance database. It never
 renders program audio; `@hypit/provider-media-local` separately prepares `TimelineAudio` and muxes
 the final media.
 
@@ -48,11 +56,16 @@ For a Runtime Profile, place `pool` on the Endpoint entry and these Provider set
 This configuration admits one 4-worker request at a time under its 6-browser budget even though
 the whole-request limit is 2. Two 4-worker requests would need 8 browser slots. Choose budgets from
 the actual machine and shared workloads; the example is not an automatic tuning recommendation.
-Reload the Runtime Worker after changing its Profile and restart Studio if it uses that Profile.
+New Builds use the edited Provider configuration; active Builds retain their selected configuration.
+Restart Studio if its existing session needs to load the edited Profile.
 
 `browserGpu` picks Chrome's rasterizer and defaults to `hardware`. Set `software` without a usable
 GPU, or `auto` to let the engine decide. Capture uses screenshots and independent browser processes;
-the CLI's automatic worker and drawElement policies do not override the count.
+the CLI's automatic worker and drawElement policies do not override the count. The opaque screenshot
+adapter uses the engine's public session, video injector and page seek protocol plus Chrome CDP.
+It waits for seek completion, dynamic images/fonts and the page compositor before capturing PNGs.
+The pinned engine couples its PNG session setup to transparent export, so this adapter initializes
+an opaque session and chooses PNG separately at capture. It does not patch engine methods or files.
 
 The Runtime Adapter also declares one managed browser program. `programs up` invokes the pinned
 HyperFrames CLI's `browser ensure`; its probe resolves and starts that browser and checks
@@ -71,8 +84,12 @@ const visual = await renderHyperframesVisual(
 
 Omit `range` for the complete document. Ranges are zero-based and half-open on the original
 programme clock. At 30 fps, `[240, 360)` returns 120 frames covering seconds 8–12.
-`onProgress` reports preparation, worker ranges, browser PIDs, completion and elapsed time to direct
-executor callers. The Runtime Provider does not currently forward these events as Build progress.
+`onProgress` reports resource staging, source decoding, the requested range, per-worker frame counts, browser PIDs,
+encoding, storage and elapsed time to direct executor callers. The Provider reduces parallel worker
+events to a single phase and aggregate count through `context.reportProgress`. CLI status and follow
+display that activity without `--verbose`. Counter writes are coalesced to about once per second;
+phase changes and completed counts are reported promptly. Local activity belongs to the running
+Command, not a remote Operation or a repeatedly rewritten Result manifest.
 `processTimeoutMs` defaults to 30 minutes and starts one deadline before resource preparation. It
 covers resource reads, Surface validation, rendering and output storage. `signal` can end the same
 execution earlier. ResourceStore I/O and Surface probes receive the cancellation signal; a custom
@@ -95,10 +112,13 @@ cleanup. A completed worker closes its Chrome immediately.
 One call stages the HTML and every declared asset once. Typed Surface validation includes a complete
 decoded-frame count, even for a short render interval. The renderer then finds source-frame windows
 needed by that interval, merges overlapping windows, and extracts them one source/window at a time.
-Decoded PNGs are shared by all workers in this call. Each worker initializes its own page and captures
-its assigned frames at their original absolute times. Output numbering starts at zero; final H.264
-encoding runs once after all workers finish. More workers parallelize capture, while staging,
-validation, source extraction and final encoding still contribute their own cost.
+Decoded PNGs are shared by all workers in this call. Each worker initializes its own page, then takes
+short contiguous frame batches from the render's in-memory queue. A free worker can continue with
+another batch instead of waiting for a worker assigned a more expensive passage. Batches span at
+most about one second and preserve the original absolute frame times. Output numbering starts at
+zero; final H.264 encoding runs once after all workers finish. This division is internal to one
+render call; it does not create or resume Builds. Extra workers help only while aggregate throughput
+improves. Staging, validation, source extraction and final encoding still contribute their own cost.
 
 Each call has its own temporary directory, local server port and Chrome processes. Separate renders
 do not share staged files or decoded PNGs. Exact compiler sampling markers retain loops, holds and
@@ -127,3 +147,11 @@ Direct `renderHyperframesVisual()` calls do not enter Runtime's shared admission
 
 The current package executes trusted official code in a local process. It is not a sandbox for
 untrusted documents or community renderer implementations.
+
+Provider calls forward renderer diagnostics through `context.reportDiagnostic`. The initial record
+states the frame count, worker policy/ceiling, capture path, quality, GPU mode and selected encoder.
+Phase timings, concurrency changes and per-worker seek/preparation/PNG totals are recorded once
+per phase, decision or finished worker. Disposable capture-process
+stdout/stderr are streamed as diagnostics and drained before the call returns; existing output limits
+still apply. Phase changes cover preparation, decoding, browser startup, capture, encoding and storage.
+`hypit logs <build-id>` retains those records after temporary rendering files have been removed.

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

@@ -21,7 +21,7 @@ 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", "quality", "browserGpu",
+      "nodePath", "hyperframesCliPath", "ffprobePath", "ffmpegPath", "workers", "maxWorkers", "quality", "browserGpu",
       "defaultConcurrency", "browserCapacity", "initializationTimeoutMs", "frameTimeoutMs", "processTimeoutMs", "maxProcessOutputBytes", "maxRenderedBytes",
     ], "local HyperFrames");
     runtimeConfigString(config.nodePath, "HyperFrames nodePath");
@@ -43,11 +43,12 @@ const localHyperframesRuntimeAdapter = createRuntimeEndpointAdapterFacet({
     const configuredCli = runtimeConfigString(config.hyperframesCliPath, "HyperFrames hyperframesCliPath");
     const configuredFfprobe = runtimeConfigString(config.ffprobePath, "HyperFrames ffprobePath");
     const nodePath = resolveRuntimeExecutable(context.dataRoot, configuredNode ?? process.execPath);
-    const hyperframesCliPath = resolveRuntimeExecutable(context.dataRoot, configuredCli ?? defaultHyperframesCliPath());
+    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");
     const defaultConcurrency = runtimeConfigPositiveInteger(config.defaultConcurrency, "HyperFrames defaultConcurrency");
+    const maxWorkers = runtimeConfigPositiveInteger(config.maxWorkers, "HyperFrames maxWorkers");
     const browserCapacity = runtimeConfigPositiveInteger(config.browserCapacity, "HyperFrames browserCapacity");
     const initializationTimeoutMs = runtimeConfigPositiveInteger(config.initializationTimeoutMs, "HyperFrames initializationTimeoutMs");
     const frameTimeoutMs = runtimeConfigPositiveInteger(config.frameTimeoutMs, "HyperFrames frameTimeoutMs");
@@ -59,10 +60,10 @@ const localHyperframesRuntimeAdapter = createRuntimeEndpointAdapterFacet({
         instance: context.instance,
         pool: context.pool,
         nodePath,
-        hyperframesCliPath,
         ffprobePath,
         ffmpegPath,
         ...(workers === undefined ? {} : { workers: workers as HyperframesWorkers }),
+        ...(maxWorkers === undefined ? {} : { maxWorkers }),
         ...(quality === undefined ? {} : { quality: quality as HyperframesQuality }),
         ...(browserGpu === undefined ? {} : { browserGpu: browserGpu as HyperframesBrowserGpu }),
         ...(defaultConcurrency === undefined ? {} : { defaultConcurrency }),

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

@@ -1,3 +1,4 @@
+import type { ExecutionDiagnostic } from "@hypit/runtime";
 import { execFile, spawn } from "node:child_process";
 import { promisify } from "node:util";
 import { fileURLToPath } from "node:url";
@@ -11,7 +12,17 @@ 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") {
-    await exec("taskkill", ["/PID", String(pid), "/T", "/F"], { windowsHide: true, timeout: cleanupMs });
+    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 { stdout } = await exec("ps", ["-A", "-o", "pid=,ppid="], { timeout: cleanupMs });
@@ -47,6 +58,7 @@ export async function runCaptureProcess(
   signal: AbortSignal,
   onProgress: (event: HyperframesRenderProgress) => void,
   entry = new URL("./capture-worker.ts", import.meta.url),
+  onDiagnostic?: (diagnostic: ExecutionDiagnostic) => Promise<void>,
 ): Promise<void> {
   signal.throwIfAborted();
   await new Promise<void>((resolve, reject) => {
@@ -58,6 +70,7 @@ export async function runCaptureProcess(
     let completed = false;
     let outputBytes = 0;
     let stderr = "";
+    let diagnostics = Promise.resolve();
     let grace: ReturnType<typeof setTimeout> | undefined;
     let killing: Promise<void> | undefined;
     const kill = () => {
@@ -80,8 +93,16 @@ export async function runCaptureProcess(
       if (error) stderr = `${stderr}${chunk.toString()}`.slice(-32_000);
       if (outputBytes > input.config.maxProcessOutputBytes) stop(new Error("HyperFrames process output exceeded the configured limit"));
     };
-    child.stdout?.on("data", (chunk: Buffer) => log(chunk, false));
-    child.stderr?.on("data", (chunk: Buffer) => log(chunk, true));
+    for (const [stream, pipe] of [["stdout", child.stdout], ["stderr", child.stderr]] as const) {
+      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))));
+        }
+      });
+    }
     child.on("message", (value: { type: string; event?: HyperframesRenderProgress; error?: string }) => {
       if (value.type === "progress" && value.event !== undefined) {
         try { onProgress(value.event); } catch (error) { stop(error instanceof Error ? error : new Error(String(error))); }
@@ -98,7 +119,8 @@ export async function runCaptureProcess(
     child.on("close", () => {
       if (grace !== undefined) clearTimeout(grace);
       signal.removeEventListener("abort", abort);
-      void (killing ?? Promise.resolve()).then(() => {
+      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}`));
         else resolve();

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

@@ -6,6 +6,9 @@ import type { HyperframesRenderProgress, resolveExecutionOptions } from "./rende
 import { assert, runProcess } from "./process.js";
 import { verifyOutput } from "./output.js";
 import { distributeFrameRange, sourceFrameAt, sourceWindows, videoSlots } from "./sampling.js";
+import { renderWorkerLimit } from "./render.js";
+import { CaptureConcurrency } from "./concurrency.js";
+import { createOpaqueFrameCapture } from "./opaque-capture.js";
 
 export type CaptureInput = {
   readonly document: HyperframesDocument;
@@ -22,8 +25,14 @@ export async function captureStagedVisual(input: CaptureInput, controller: Abort
   const { document, range, config, directory: work } = input;
   const signal = controller.signal;
   const frameCount = range.endFrameExclusive - range.startFrame;
-  const tasks = distributeFrameRange(range, config.workers);
   const fps = { num: document.frameRate.numerator, den: document.frameRate.denominator };
+  const limit = renderWorkerLimit(config, frameCount, fps.num / fps.den);
+  const concurrency = new CaptureConcurrency(limit, config.workers === "auto");
+  // Short contiguous batches retain sequential capture while allowing free browsers
+  // to help with expensive passages. This queue exists only inside this render.
+  const batchCount = Math.max(limit, Math.ceil(frameCount / Math.max(1, Math.round(fps.num / fps.den))));
+  const batches = distributeFrameRange(range, batchCount);
+  let nextBatch = 0;
   const started = performance.now();
   const elapsedMs = () => Math.round(performance.now() - started);
   const engine = await import(input.engineModule) as typeof import("@hyperframes/engine");
@@ -65,7 +74,11 @@ export async function captureStagedVisual(input: CaptureInput, controller: Abort
     const sources = new Map<string, { frames: Map<number, string>; width: number; height: number }>();
     let sourceFrames = 0;
     // One source at a time bounds decoder pressure independently of browser concurrency.
-    for (const source of sourceWindows(slots, range)) {
+    const windows = sourceWindows(slots, range);
+    const sourceTotal = windows.reduce((sum, source) => sum + source.windows.reduce((count, window) =>
+      count + window.endFrameExclusive - window.startFrame, 0), 0);
+    if (sourceTotal > 0) onProgress({ phase: "decoding", completed: 0, total: sourceTotal, elapsedMs: elapsedMs() });
+    for (const source of windows) {
       const path = resolve(work, source.src);
       assert(path.startsWith(`${work}${sep}`), "HyperFrames source is outside the staged project");
       const frames = new Map<number, string>();
@@ -86,6 +99,7 @@ export async function captureStagedVisual(input: CaptureInput, controller: Abort
         width = extracted.metadata.width;
         height = extracted.metadata.height;
         sourceFrames += count;
+        onProgress({ phase: "decoding", completed: sourceFrames, total: sourceTotal, elapsedMs: elapsedMs() });
       }
       sources.set(source.src, { frames, width, height });
     }
@@ -109,9 +123,24 @@ export async function captureStagedVisual(input: CaptureInput, controller: Abort
     const serverUrl = server.url;
     const outputFrames = join(work, "frames");
     await mkdir(outputFrames);
-    onProgress?.({ phase: "prepared", workers: tasks.length, sourceFrames, elapsedMs: elapsedMs() });
-    const results = await Promise.allSettled(tasks.map(async (task, worker) => {
+    onProgress?.({ phase: "prepared", workers: concurrency.target, sourceFrames, elapsedMs: elapsedMs() });
+    const jobs: Promise<void>[] = [];
+    let active = 0, open = 0, initializing = 0, capturedFrames = 0;
+    let startupMs = 0;
+    const launch = (): void => {
+      const worker = jobs.length;
+      jobs.push(runWorker(worker));
+      // Failure stops all jobs promptly; all jobs are still awaited below.
+      void jobs[worker]!.catch(() => {});
+    };
+    const runWorker = async (worker: number): Promise<void> => {
       let session: Session | undefined;
+      let ready = false;
+      active++;
+      open++;
+      initializing++;
+      const launched = performance.now();
+      let setupMs = 0;
       try {
         signal.throwIfAborted();
         const directory = join(work, `worker-${worker}`);
@@ -120,7 +149,9 @@ export async function captureStagedVisual(input: CaptureInput, controller: Abort
           frameSrcResolver: (path) => new URL(relative(work, path).split(sep).map(encodeURIComponent).join("/"), `${serverUrl}/`).href,
         });
         session = await engine.createCaptureSession(serverUrl, directory, {
-          ...document.canvas, fps, format: "png",
+          // Engine initialization couples PNG to transparent-export mode. Use
+          // its opaque session setup; our capture adapter writes lossless PNG.
+          ...document.canvas, fps, format: "jpeg",
           compositionDurationSeconds: document.frameCount * fps.den / fps.num,
           skipReadinessVideoIds: slots.map((slot) => slot.id),
           videoMetadataHints: slots.flatMap((slot) => {
@@ -132,38 +163,77 @@ export async function captureStagedVisual(input: CaptureInput, controller: Abort
         signal.throwIfAborted();
         const activeSession = session;
         const browserPid = session.browser.process()?.pid;
-        onProgress?.({ phase: "worker-initializing", worker, range: task, browserPid, elapsedMs: elapsedMs() });
+        onProgress?.({ phase: "worker-initializing", worker, range, browserPid, elapsedMs: elapsedMs() });
         await stage(`worker ${worker} initialization`, config.initializationTimeoutMs, () => engine.initializeSession(activeSession));
-        // HyperFrames' PNG capture clears the page/composition backgrounds for
-        // standalone transparent exports. Here PNGs are intermediate frames of
-        // a Film, whose authored Canvas background still belongs in the image.
-        await activeSession.page.evaluate(() => {
-          globalThis.document.getElementById("__hf_transparent_bg__")?.remove();
-        });
-        onProgress?.({ phase: "worker-start", worker, range: task, browserPid, elapsedMs: elapsedMs() });
-        for (let frame = task.startFrame; frame < task.endFrameExclusive; frame++) {
-          signal.throwIfAborted();
-          const captured = await stage(`worker ${worker} frame ${frame}`, config.frameTimeoutMs, async () => {
-            const capture = await engine.captureFrameToBuffer(activeSession, frame, frame * fps.den / fps.num);
-            const programError = await activeSession.page.evaluate(() =>
-              (window as unknown as { __hypitBrowserProgramError?: string }).__hypitBrowserProgramError);
-            if (programError !== undefined) throw new Error(`Browser program failed at frame ${frame}: ${programError}`);
-            return capture;
-          });
-          await writeFile(join(outputFrames, `${String(frame - range.startFrame).padStart(9, "0")}.png`), captured.buffer);
+        const captureFrame = await createOpaqueFrameCapture(activeSession);
+        setupMs = performance.now() - launched;
+        startupMs = Math.max(startupMs, setupMs);
+        ready = true;
+        initializing--;
+        if (initializing === 0) concurrency.settled(performance.now());
+        onProgress?.({ phase: "worker-start", worker, range, browserPid, elapsedMs: elapsedMs() });
+        let completed = 0;
+        let lastProgressAt = performance.now();
+        const timing = { seekMs: 0, prepareMs: 0, screenshotMs: 0 };
+        while (true) {
+          // Retire only between complete batches, before claiming more work.
+          if (active > concurrency.target) break;
+          const batch = batches[nextBatch++];
+          if (batch === undefined) break;
+          for (let frame = batch.startFrame; frame < batch.endFrameExclusive; frame++) {
+            signal.throwIfAborted();
+            const captured = await stage(`worker ${worker} frame ${frame}`, config.frameTimeoutMs, () => captureFrame(frame));
+            timing.seekMs += captured.seekMs;
+            timing.prepareMs += captured.prepareMs;
+            timing.screenshotMs += captured.screenshotMs;
+            await writeFile(join(outputFrames, `${String(frame - range.startFrame).padStart(9, "0")}.png`), captured.buffer);
+            completed++;
+            capturedFrames++;
+            if (performance.now() - lastProgressAt >= 1_000) {
+              onProgress({ phase: "worker-progress", worker, completed, elapsedMs: elapsedMs() });
+              lastProgressAt = performance.now();
+            }
+          }
+          const decision = concurrency.complete({ now: performance.now(), frames: batch.endFrameExclusive - batch.startFrame,
+            remainingFrames: frameCount - capturedFrames, startupMs, active: initializing === 0 ? active : 0 });
+          if (decision !== undefined) {
+            console.log(`Capture auto: ${active} -> ${decision.workers} browsers; ${decision.fps.toFixed(1)} frames/s; ${decision.reason}`);
+            while (active < decision.workers && open < limit && nextBatch < batches.length) launch();
+          }
         }
-        onProgress?.({ phase: "worker-complete", worker, range: task, browserPid, elapsedMs: elapsedMs() });
+        console.log(`Capture worker ${worker}: ${completed} frames; startup ${Math.round(setupMs)} ms; `
+          + `seek ${Math.round(timing.seekMs)} ms; prepare ${Math.round(timing.prepareMs)} ms; PNG ${Math.round(timing.screenshotMs)} ms`);
+        onProgress({ phase: "worker-complete", worker, completed, browserPid, elapsedMs: elapsedMs() });
       } catch (error) {
         controller.abort(error);
         throw error;
       } finally {
+        active--;
+        if (!ready) initializing--;
         if (session !== undefined) await close(session);
+        open--;
+        // A restoring decision can wait for a retiring Chrome to release its
+        // slot. Closing processes still count against the reserved ceiling.
+        if (!signal.aborted && active < concurrency.target && open < limit && nextBatch < batches.length) launch();
       }
-    }));
+    };
+    const initialWorkers = concurrency.target;
+    console.log(`Capture: opaque fast PNG; ${config.workers === "auto" ? "auto" : "fixed"} workers ${initialWorkers}, limit ${limit}`);
+    for (let i = 0; i < initialWorkers; i++) launch();
+    // New workers can join while earlier jobs run; collect every launched job.
+    let awaited = 0;
+    let failure: unknown;
+    while (awaited < jobs.length) {
+      const pending = jobs.slice(awaited);
+      awaited = jobs.length;
+      const results = await Promise.allSettled(pending);
+      for (const result of results) if (result.status === "rejected") failure ??= result.reason;
+    }
+    if (failure !== undefined) throw failure;
     signal.throwIfAborted();
-    for (const result of results) if (result.status === "rejected") throw result.reason;
     await Promise.all(closing.values());
     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,
       argv: ["-v", "error", "-y", "-framerate", `${fps.num}/${fps.den}`, "-i", join(outputFrames, "%09d.png"),

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

@@ -0,0 +1,86 @@
+import { availableParallelism, totalmem } from "node:os";
+
+function hostMemory(): number {
+  const constrained = process.constrainedMemory?.() ?? 0;
+  return constrained > 0 ? Math.min(totalmem(), constrained) : totalmem();
+}
+
+/** Stable reservation ceiling. Actual load tuning happens inside the admitted render. */
+export function autoWorkerLimit(cpu = availableParallelism(), memory = hostMemory()): number {
+  // Chrome owns raster surfaces, decoded media and the JS heap in separate
+  // processes. Leave half the memory and two CPU slots to the host/other stages.
+  const byMemory = Math.floor(memory / 2 / (1.5 * 1024 ** 3));
+  return Math.max(1, Math.min(Math.max(1, cpu - 2), byMemory));
+}
+
+/**
+ * Online throughput comparison of useful capture batches. All samples and
+ * decisions die with this attempt. A change never invalidates captured frames.
+ */
+export class CaptureConcurrency {
+  target: number;
+  private since: number | undefined;
+  private frames = 0;
+  private batches = 0;
+  private baseline: { workers: number; rate: number } | undefined;
+  private previousRate: number | undefined;
+  private growth = true;
+
+  constructor(readonly limit: number, readonly automatic: boolean) {
+    this.target = automatic ? Math.max(1, Math.ceil(limit / 2)) : limit;
+  }
+
+  settled(now: number): void {
+    this.since = now;
+    this.frames = 0;
+    this.batches = 0;
+  }
+
+  complete(input: { now: number; frames: number; remainingFrames: number; startupMs: number; active: number }):
+    { workers: number; reason: string; fps: number } | undefined {
+    if (!this.automatic) return;
+    if (input.active !== this.target) { this.since = undefined; return; }
+    if (this.since === undefined) { this.settled(input.now); return; }
+    this.frames += input.frames;
+    this.batches++;
+    const elapsed = input.now - this.since;
+    // At least two batches per worker and a browser startup's worth of useful
+    // work amortize short fluctuations. No synthetic calibration is rendered.
+    if (this.batches < this.target * 2 || elapsed < Math.max(1_000, input.startupMs)) return;
+    const rate = this.frames * 1_000 / elapsed;
+    let next = this.target;
+    let reason = "";
+    if (this.baseline !== undefined) {
+      const before = this.baseline;
+      this.baseline = undefined;
+      const added = this.target > before.workers;
+      if (rate < before.rate * (added ? 1.05 : 0.95)) {
+        next = before.workers;
+        reason = added ? "extra browser did not improve throughput" : "fewer browsers reduced throughput";
+        this.growth = false;
+      }
+    } else if (this.previousRate !== undefined && rate < this.previousRate * 0.7 && this.target > 1
+      && input.remainingFrames > this.frames * 2) {
+      // A slower passage is not proof of contention. Compare fewer browsers
+      // on subsequent useful work and restore the old count if it is worse.
+      this.baseline = { workers: this.target, rate };
+      next--;
+      reason = "compare fewer browsers after throughput changed";
+      this.growth = false;
+    }
+    if (next === this.target && this.growth && next < this.limit
+      && input.remainingFrames / rate * 1_000 > input.startupMs * (next + 1) * 2) {
+      // A new browser must have enough remaining work to repay its startup,
+      // even if its ideal contribution is only 1/(N+1) of current throughput.
+      this.baseline = { workers: this.target, rate };
+      next++;
+      reason = "remaining capture can amortize another browser";
+    }
+    this.previousRate = rate;
+    this.settled(input.now);
+    if (next === this.target) return;
+    this.target = next;
+    this.since = undefined;
+    return { workers: next, reason, fps: rate };
+  }
+}

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

@@ -0,0 +1,92 @@
+import type { CaptureSession, HfProtocol } from "@hyperframes/engine";
+import { getCdpSession } from "@hyperframes/engine";
+
+/** The optional completion hooks supplied by the pinned Hyperframes page runtime. */
+type RenderWindow = Window & {
+  __hf: HfProtocol & { colorGrading?: { waitForActiveLuts?: () => Promise<void> } };
+  __hfWaitForSeekCompletion?: () => Promise<void>;
+  __hf_page_composite_pending?: boolean;
+  __hf_page_composite_prepare?: () => Promise<void>;
+  __hf_page_composite_resolve?: () => void;
+  __hypitBrowserProgramError?: string;
+};
+
+/**
+ * A screenshot adapter for this Provider's opaque MP4 output. Session lifecycle,
+ * the page's seek protocol and the video injector remain engine-owned. Encoding
+ * the already-composited frame as a fast PNG does not change source alpha.
+ * No engine/session methods are replaced and no installed dependency is patched.
+ */
+export async function createOpaqueFrameCapture(session: CaptureSession) {
+  const { page, options } = session;
+  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.
+  await page.evaluate(() => {
+    const decoded = new Map<string, Promise<void>>();
+    (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());
+      }
+      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);
+        }
+      }
+      await Promise.all(pending);
+    };
+  });
+  return async (frame: number) => {
+    const time = frame * options.fps.den / options.fps.num;
+    const start = performance.now();
+    await page.evaluate(async t => {
+      const w = window as unknown as RenderWindow;
+      await w.__hf.seek(t);
+    }, time);
+    const sought = performance.now();
+    await session.onBeforeCapture?.(page, time);
+    const composite = await page.evaluate(async () => {
+      const w = window as unknown as RenderWindow & { __hypitPrepareImages: () => Promise<void> };
+      await w.__hfWaitForSeekCompletion?.();
+      await w.__hf.colorGrading?.waitForActiveLuts?.();
+      await w.__hypitPrepareImages();
+      if (w.__hypitBrowserProgramError !== undefined) throw new Error(w.__hypitBrowserProgramError);
+      if (w.__hf_page_composite_pending) {
+        await w.__hf_page_composite_prepare?.();
+        return true;
+      }
+      return false;
+    });
+    if (composite) {
+      // The runtime's shader compositor needs a paint between preparing its DOM
+      // layers and resolving them. A 1 px capture flushes Chrome's compositor.
+      await cdp.send("Page.captureScreenshot", {
+        format: "jpeg", quality: 1, clip: { x: 0, y: 0, width: 1, height: 1, scale: 1 },
+      });
+      await page.evaluate(() => (window as unknown as RenderWindow).__hf_page_composite_resolve?.());
+    }
+    const prepared = performance.now();
+    const result = await cdp.send("Page.captureScreenshot", {
+      format: "png", optimizeForSpeed: true, fromSurface: true,
+      captureBeyondViewport: options.captureBeyondViewport ?? false,
+      clip: { x: 0, y: 0, width: options.width, height: options.height, scale: options.deviceScaleFactor ?? 1 },
+    });
+    return { buffer: Buffer.from(result.data, "base64"),
+      seekMs: sought - start, prepareMs: prepared - sought, screenshotMs: performance.now() - prepared };
+  };
+}

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

@@ -8,6 +8,8 @@ export type HyperframesExecutionOptions = {
   readonly ffmpegPath?: string;
   /** Parallel Chrome workers inside one render. This is separate from Provider request concurrency. */
   readonly workers?: HyperframesWorkers;
+  /** Upper bound for auto's browser reservation; explicit workers remain fixed. */
+  readonly maxWorkers?: number;
   readonly quality?: HyperframesQuality;
   /** Chrome's rasterizer, default hardware. Use software without a usable GPU. */
   readonly browserGpu?: HyperframesBrowserGpu;

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

@@ -22,13 +22,16 @@ export function localHyperframesBrowserProgram(
   input: {
     readonly id: string;
     readonly nodePath: string;
-    readonly hyperframesCliPath: string;
+    readonly hyperframesCliPath: string | (() => string);
     readonly ffprobePath: string;
     readonly ffmpegPath?: string;
   },
 ): ManagedProgram {
+  const cliPath = () => typeof input.hyperframesCliPath === "string" ? input.hyperframesCliPath : input.hyperframesCliPath();
   const probeBrowser = async (): Promise<ManagedProgramState> => {
-    const located = await run(input.nodePath, [input.hyperframesCliPath, "browser", "path"]);
+    let executable: string;
+    try { executable = cliPath(); } catch (error) { return { state: "down", detail: error instanceof Error ? error.message : String(error) }; }
+    const located = await run(input.nodePath, [executable, "browser", "path"]);
     if (!located.ok) return { state: "down", detail: `HyperFrames browser is unavailable: ${located.output}` };
     const path = located.output.trim();
     if (path.length === 0 || path.includes("\n") || path.includes("\r")) {
@@ -44,7 +47,7 @@ export function localHyperframesBrowserProgram(
     id: input.id,
     installation: {
       probe: probeBrowser,
-      commands: [{ command: input.nodePath, args: [input.hyperframesCliPath, "browser", "ensure"] }],
+      get commands() { return [{ command: input.nodePath, args: [cliPath(), "browser", "ensure"] }]; },
     },
     async probe(): Promise<ManagedProgramState> {
       const browser = await probeBrowser();