@hypit/hypit 0.1.3 → 0.1.5

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();

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

@@ -0,0 +1,53 @@
+import type { OperationProgress } from "@hypit/endpoint-kit";
+import type { HyperframesRenderProgress } from "./render.js";
+
+/** Reduce parallel capture events to one readable progress report for this render request. */
+export function renderProgressReporter(
+  report: ((progress: OperationProgress) => Promise<void>) | undefined,
+  totalFrames: number,
+  now: () => number = Date.now,
+) {
+  const workers = new Map<number, number>();
+  let rendering = false;
+  let lastPhase: string | undefined;
+  let lastAt = -Infinity;
+  let writes = Promise.resolve();
+  const frames = () => ({ phase: "rendering frames", completed: [...workers.values()].reduce((a, b) => a + b, 0),
+    total: totalFrames, unit: "frames" });
+  return {
+    onProgress(event: HyperframesRenderProgress): void {
+      if (report === undefined) return;
+      let progress: OperationProgress;
+      switch (event.phase) {
+        case "staging": progress = { phase: "preparing resources" }; break;
+        case "decoding": progress = { phase: "decoding source frames", completed: event.completed, total: event.total, unit: "frames" }; break;
+        case "prepared":
+        case "worker-initializing":
+          if (rendering) return;
+          progress = { phase: "starting browsers" }; break;
+        case "worker-start":
+          rendering = true;
+          workers.set(event.worker, 0);
+          progress = frames(); break;
+        case "worker-progress":
+          workers.set(event.worker, event.completed);
+          progress = frames(); break;
+        case "worker-complete":
+          workers.set(event.worker, event.completed);
+          progress = frames(); break;
+        case "encoding": progress = { phase: "encoding video" }; break;
+        case "storing": progress = { phase: "storing output" }; break;
+        case "complete": return;
+      }
+      const at = now();
+      if (progress.phase === lastPhase && at - lastAt < 1_000
+        && (progress.total === undefined || progress.completed !== progress.total)) return;
+      lastPhase = progress.phase;
+      lastAt = at;
+      // Attach rejection handling immediately; flush still propagates storage failure to the caller.
+      writes = writes.then(() => report(progress));
+      void writes.catch(() => {});
+    },
+    flush: () => writes,
+  };
+}

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

@@ -3,8 +3,9 @@ import { mediaTypes } from "@hypit/media";
 import { renderHyperframesCapabilities, verifyHyperframesVisualRequest } from "@hypit/render-hyperframes";
 import { canonicalize } from "@hypit/protocol";
 import { resolveNodePackageExecutable } from "@hypit/package-loader-node";
-import { renderHyperframesVisual, resolveExecutionOptions } from "./render.js";
+import { renderHyperframesVisual, resolveExecutionOptions, renderWorkerLimit } from "./render.js";
 import type { HyperframesExecutionOptions } from "./options.js";
+import { renderProgressReporter } from "./progress.js";
 
 export type * from "./options.js";
 export const localHyperframesProviderModuleRef = { name: "@hypit/provider-hyperframes-local", version: "1" } as const;
@@ -31,6 +32,8 @@ export function createLocalHyperframesProvider(config: CreateLocalHyperframesPro
   if (config.browserCapacity !== undefined && (!Number.isSafeInteger(config.browserCapacity) || config.browserCapacity < 1)) {
     throw new Error("HyperFrames browserCapacity must be a positive integer");
   }
+  const maxWorkers = execution.workers === "auto" ? Math.min(execution.maxWorkers, config.browserCapacity ?? Infinity) : execution.maxWorkers;
+  const reserved = { ...execution, maxWorkers };
   return defineEndpointPackage({
     module: localHyperframesProviderModuleRef,
     facet: "render",
@@ -47,15 +50,25 @@ export function createLocalHyperframesProvider(config: CreateLocalHyperframesPro
         unitsForRequest: (request: import("@hypit/endpoint-kit").EndpointRequest) => {
           verifyHyperframesVisualRequest(request.constraints);
           const { document, range } = request.constraints;
-          return { [browsers]: Math.min(execution.workers,
-            range === undefined ? document.frameCount : range.endFrameExclusive - range.startFrame) };
+          return { [browsers]: renderWorkerLimit(reserved,
+            range === undefined ? document.frameCount : range.endFrameExclusive - range.startFrame,
+            document.frameRate.numerator / document.frameRate.denominator) };
         },
       }),
       handler: async (context) => {
         const request = context.need.constraints;
         verifyHyperframesVisualRequest(request);
-        const visual = await renderHyperframesVisual(request, { ...config, workers: execution.workers, resources: context.resources });
-        return { value: { kind: "inline", value: canonicalize(visual) } };
+        const frameCount = request.range === undefined ? request.document.frameCount
+          : request.range.endFrameExclusive - request.range.startFrame;
+        const progress = renderProgressReporter(context.reportProgress, frameCount);
+        try {
+          const visual = await renderHyperframesVisual(request, { ...config, workers: execution.workers, maxWorkers,
+            resources: context.resources, onProgress: progress.onProgress,
+            ...(context.reportDiagnostic === undefined ? {} : { onDiagnostic: context.reportDiagnostic }) });
+          return { value: { kind: "inline", value: canonicalize(visual) } };
+        } finally {
+          await progress.flush();
+        }
       },
     }],
   });