@hyperframes/producer 0.8.183 → 0.8.184

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export { type BrowserDiagnosticSummary, type RenderCaptureObservability, type Re
 export { localizeRemoteMediaSources, localizeRemoteImageSources, localizeRemoteFontFaces, } from "./services/htmlCompiler.js";
 export { createCaptureSession, initializeSession, closeCaptureSession, captureFrame, captureFrameToBuffer, getCompositionDuration, getCapturePerfSummary, isTransientBrowserError, prepareCaptureSessionForReuse, type CaptureOptions, type CaptureSession, type CaptureResult, type CapturePerfSummary, type BeforeCaptureHook, } from "./services/frameCapture.js";
 export { createFileServer, type FileServerOptions, type FileServerHandle, } from "./services/fileServer.js";
+export { prepareAnimatedGifInputs } from "./services/animatedGifPrep.js";
 export { createVideoFrameInjector } from "@hyperframes/engine";
 export { resolveConfig, DEFAULT_CONFIG, type ProducerConfig } from "./config.js";
 export { type ProducerLogger, type LogLevel, createConsoleLogger, defaultLogger, } from "./logger.js";

package/dist/index.js

@@ -8982,6 +8982,7 @@ async function runCaptureStage(input) {
           if (progress.capturedFrames === 0) reportWorkerStartup(job, progress, onProgress);
           return;
         }
+        if (progress.landedFrame) input.onFrameLanded?.(progress.landedFrame);
         job.framesRendered = progress.capturedFrames;
         checkDiskProjection(progress.capturedFrames);
         const frameProgress = progress.capturedFrames / progress.totalFrames;
@@ -10151,6 +10152,7 @@ import {
   statSync as statSync5,
   writeFileSync as writeFileSync4
 } from "node:fs";
+import { readFile as readFile2 } from "node:fs/promises";
 import { dirname as dirname8, join as join24 } from "node:path";
 import {
   encodeFramesChunkedConcat,
@@ -10158,7 +10160,8 @@ import {
   formatFfmpegError,
   MIXED_AUDIO_FILENAME as MIXED_AUDIO_FILENAME2,
   resolveConfig,
-  runFfmpeg as runFfmpeg3
+  runFfmpeg as runFfmpeg3,
+  spawnStreamingEncoder as spawnStreamingEncoder4
 } from "@hyperframes/engine";
 import {
   clearGifFramesBeforeNext,
@@ -10295,6 +10298,124 @@ function startEncodeProgress(job, stage, onProgress) {
   });
   return (frames = total) => reportEncodeProgress(job, frames, total, onProgress, 75);
 }
+function resolveEngineConfig(input) {
+  return input.engineConfig ?? input.job.config.producerConfig ?? resolveConfig();
+}
+function videoEncoderOptions(input, engineCfg) {
+  const { job, preset } = input;
+  return {
+    fps: job.config.fps,
+    width: input.width,
+    height: input.height,
+    codec: preset.codec,
+    preset: preset.preset,
+    quality: input.effectiveQuality,
+    bitrate: input.effectiveBitrate,
+    pixelFormat: preset.pixelFormat,
+    vp9CpuUsed: engineCfg.vp9CpuUsed,
+    useGpu: job.config.useGpu,
+    hdr: preset.hdr,
+    // Distributed chunk renders pass these so the encoder writes closed-GOP
+    // keyframes that survive `-f concat -c copy` at assemble time. In-process
+    // renders leave both undefined → preserves the existing open-GOP output.
+    lockGopForChunkConcat: input.lockGopForChunkConcat === true,
+    gopSize: input.gopSize
+  };
+}
+function canEncodeWhileCapturing(input, workerCount, cpuCount) {
+  return workerCount > 1 && workerCount < cpuCount && !input.isPngSequence && !input.isGif && !input.enableChunkedEncode && input.preset.codec === "h264" && !input.preset.hdr && input.job.config.useGpu !== true && input.captureImageFormat === "jpeg" && input.lockGopForChunkConcat !== true;
+}
+async function readLandedFrame(workerPath, mergedPath) {
+  if (workerPath !== void 0) {
+    try {
+      return await readFile2(workerPath);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+  }
+  return readFile2(mergedPath);
+}
+function encodeWhileCapturing(input, totalFrames) {
+  const engineCfg = resolveEngineConfig(input);
+  const stop = new AbortController();
+  const signal = input.abortSignal ? AbortSignal.any([input.abortSignal, stop.signal]) : stop.signal;
+  const landed = /* @__PURE__ */ new Map();
+  let captureDone = false;
+  let framesFed = 0;
+  let wake = null;
+  const nudge = () => {
+    wake?.();
+    wake = null;
+  };
+  signal.addEventListener("abort", nudge, { once: true });
+  let reportFed = null;
+  const encoder = spawnStreamingEncoder4(
+    input.videoOnlyPath,
+    { ...videoEncoderOptions(input, engineCfg), imageFormat: "jpeg" },
+    signal,
+    engineCfg
+  );
+  const fed = (async () => {
+    const stream = await encoder;
+    for (let next = 0; next < totalFrames; next++) {
+      while (!landed.has(next) && !captureDone && !signal.aborted) {
+        await new Promise((resolve12) => wake = resolve12);
+      }
+      if (signal.aborted) return;
+      const mergedPath = join24(input.framesDir, formatCaptureFrameName(next, "jpg"));
+      const frame = await readLandedFrame(landed.get(next), mergedPath);
+      landed.delete(next);
+      if (!await stream.writeFrame(frame)) {
+        throw new Error(stream.getExitError() ?? "encoder exited before the last frame");
+      }
+      framesFed++;
+      reportFed?.(framesFed);
+    }
+  })().then(
+    () => void 0,
+    (error) => error ?? new Error("encode failed")
+  );
+  const closeEncoder = async () => (await encoder.catch(() => null))?.close();
+  return {
+    onFrameLanded: (frame) => {
+      landed.set(frame.index, frame.path);
+      nudge();
+    },
+    finish: async () => {
+      const start = Date.now();
+      captureDone = true;
+      input.log.info("[Render] Encoded frames while capturing", {
+        framesFed,
+        totalFrames
+      });
+      const encoded = startEncodeProgress(input.job, "Encoding video", input.onProgress);
+      reportFed = encoded;
+      nudge();
+      const failure = await fed;
+      const result = await closeEncoder();
+      input.assertNotAborted();
+      if (failure === void 0 && result?.success) {
+        encoded();
+        return { encodeMs: Date.now() - start };
+      }
+      input.log.warn(
+        "[Render] Encoding while capturing failed; encoding the frames after capture",
+        {
+          error: String(failure ?? result?.error)
+        }
+      );
+      return runEncodeStage(input);
+    },
+    abort: async () => {
+      stop.abort();
+      await fed;
+      await closeEncoder();
+    },
+    get framesFed() {
+      return framesFed;
+    }
+  };
+}
 async function runEncodeStage(input) {
   const {
     job,
@@ -10302,16 +10423,11 @@ async function runEncodeStage(input) {
     outputPath,
     framesDir,
     videoOnlyPath,
-    width,
-    height,
     needsAlpha,
     hasAudio,
     audioOutputPath,
     isPngSequence,
     isGif,
-    preset,
-    effectiveQuality,
-    effectiveBitrate,
     enableChunkedEncode,
     chunkedEncodeSize,
     abortSignal,
@@ -10341,7 +10457,7 @@ async function runEncodeStage(input) {
     encoded();
     return { encodeMs: Date.now() - stage5Start };
   }
-  const engineCfg = input.engineConfig ?? job.config.producerConfig ?? resolveConfig();
+  const engineCfg = resolveEngineConfig(input);
   if (isGif) {
     const encoded = startEncodeProgress(job, "Encoding GIF", onProgress);
     if (hasAudio) {
@@ -10371,24 +10487,7 @@ async function runEncodeStage(input) {
   const videoEngineCfg = scaledEncodeTimeout > engineCfg.ffmpegEncodeTimeout ? { ...engineCfg, ffmpegEncodeTimeout: scaledEncodeTimeout } : engineCfg;
   const frameExt = frameFileExtension2(input.captureImageFormat);
   const framePattern = `frame_%06d.${frameExt}`;
-  const encoderOpts = {
-    fps: job.config.fps,
-    width,
-    height,
-    codec: preset.codec,
-    preset: preset.preset,
-    quality: effectiveQuality,
-    bitrate: effectiveBitrate,
-    pixelFormat: preset.pixelFormat,
-    vp9CpuUsed: engineCfg.vp9CpuUsed,
-    useGpu: job.config.useGpu,
-    hdr: preset.hdr,
-    // Distributed chunk renders pass these so the encoder writes closed-GOP
-    // keyframes that survive `-f concat -c copy` at assemble time. In-process
-    // renders leave both undefined → preserves the existing open-GOP output.
-    lockGopForChunkConcat: input.lockGopForChunkConcat === true,
-    gopSize: input.gopSize
-  };
+  const encoderOpts = videoEncoderOptions(input, engineCfg);
   const encodeResult = enableChunkedEncode ? await encodeFramesChunkedConcat(
     framesDir,
     framePattern,
@@ -13313,6 +13412,34 @@ async function executeRenderPipeline(input) {
           throw new Error(`Disk capture requires sdr_disk plan; got ${capturePlan.kind}`);
         }
         resetCaptureAttemptProgress(job);
+        const encodeInput = {
+          job,
+          log,
+          outputPath: stagedOutputPath,
+          framesDir,
+          videoOnlyPath,
+          width,
+          height,
+          needsAlpha,
+          captureImageFormat: captureOptions.format ?? "jpeg",
+          hasAudio,
+          audioOutputPath,
+          isPngSequence,
+          isGif,
+          preset,
+          effectiveQuality,
+          effectiveBitrate,
+          enableChunkedEncode,
+          chunkedEncodeSize,
+          engineConfig: cfg,
+          // Same value the streaming encoder above spreads — the disk and
+          // chunked-concat encoders need an identical GOP lock for HLS.
+          ...hlsEncoderGopLock,
+          abortSignal: executionSignal,
+          assertNotAborted,
+          onProgress
+        };
+        const overlap = !cfg.useDrawElement && workerSizing !== void 0 && canEncodeWhileCapturing(encodeInput, capturePlan.workerCount, workerSizing.cpuCount) ? encodeWhileCapturing(encodeInput, totalFrames) : null;
         const captureFrameStart = Date.now();
         const invokeDiskCapture = (diskPlan) => observeRenderStage(
           observability,
@@ -13334,13 +13461,15 @@ async function executeRenderPipeline(input) {
             createRenderVideoFrameInjector,
             abortSignal: executionSignal,
             assertNotAborted,
-            onProgress
+            onProgress,
+            onFrameLanded: (frame) => overlap?.onFrameLanded(frame)
           })
         );
         let captureRes;
         try {
           captureRes = await invokeDiskCapture(capturePlan);
         } catch (err) {
+          await overlap?.abort();
           if (!isDrawElementVerificationError(err) && !isDrawElementCaptureError(err) || err instanceof RenderCancelledError || executionSignal?.aborted === true) {
             throw err;
           }
@@ -13409,33 +13538,7 @@ async function executeRenderPipeline(input) {
             isGif,
             chunkedEncode: enableChunkedEncode
           }),
-          () => runEncodeStage({
-            job,
-            log,
-            outputPath: stagedOutputPath,
-            framesDir,
-            videoOnlyPath,
-            width,
-            height,
-            needsAlpha,
-            captureImageFormat: captureOptions.format ?? "jpeg",
-            hasAudio,
-            audioOutputPath,
-            isPngSequence,
-            isGif,
-            preset,
-            effectiveQuality,
-            effectiveBitrate,
-            enableChunkedEncode,
-            chunkedEncodeSize,
-            engineConfig: cfg,
-            // Same value the streaming encoder above spreads — the disk and
-            // chunked-concat encoders need an identical GOP lock for HLS.
-            ...hlsEncoderGopLock,
-            abortSignal: executionSignal,
-            assertNotAborted,
-            onProgress
-          })
+          () => overlap ? overlap.finish() : runEncodeStage(encodeInput)
         );
         perfStages.encodeMs = encodeRes.encodeMs;
       }
@@ -18794,6 +18897,12 @@ function validatePlanVideosForChunk(value) {
     );
   }
 }
+var MIN_FRAMES_PER_CHUNK_BROWSER = 20;
+function resolveChunkCaptureWorkers(framesInChunk, machineSized, maxCaptureWorkers) {
+  if (maxCaptureWorkers === void 0) return machineSized;
+  const byFrames = Math.floor(framesInChunk / MIN_FRAMES_PER_CHUNK_BROWSER);
+  return Math.max(machineSized, Math.floor(Math.min(maxCaptureWorkers, byFrames)));
+}
 function resolveChunkFrameRange(slice, chunkIndex, frameRange) {
   if (frameRange === void 0) return { startFrame: slice.startFrame, endFrame: slice.endFrame };
   const { startFrame, endFrame } = frameRange;
@@ -19030,7 +19139,11 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
         deferredVideos.filter((video) => remoteVideoIds.has(video.videoId))
       )
     });
-    const chunkWorkerCount = calculateOptimalWorkers2(framesInChunk, void 0, cfg);
+    const chunkWorkerCount = resolveChunkCaptureWorkers(
+      framesInChunk,
+      calculateOptimalWorkers2(framesInChunk, void 0, cfg),
+      options?.maxCaptureWorkers
+    );
     let session = null;
     let outputKind;
     let framesEncoded = 0;
@@ -19447,6 +19560,7 @@ export {
   plan,
   planV2,
   planV2WithPublisher,
+  prepareAnimatedGifInputs,
   prepareCaptureSessionForReuse4 as prepareCaptureSessionForReuse,
   prepareHyperframeLintBody,
   publishPlanV2FromExecutionPlan,

package/dist/public-server.js

@@ -8965,6 +8965,7 @@ async function runCaptureStage(input) {
           if (progress.capturedFrames === 0) reportWorkerStartup(job, progress, onProgress);
           return;
         }
+        if (progress.landedFrame) input.onFrameLanded?.(progress.landedFrame);
         job.framesRendered = progress.capturedFrames;
         checkDiskProjection(progress.capturedFrames);
         const frameProgress = progress.capturedFrames / progress.totalFrames;
@@ -10134,6 +10135,7 @@ import {
   statSync as statSync5,
   writeFileSync as writeFileSync4
 } from "node:fs";
+import { readFile as readFile2 } from "node:fs/promises";
 import { dirname as dirname8, join as join24 } from "node:path";
 import {
   encodeFramesChunkedConcat,
@@ -10141,7 +10143,8 @@ import {
   formatFfmpegError,
   MIXED_AUDIO_FILENAME as MIXED_AUDIO_FILENAME2,
   resolveConfig,
-  runFfmpeg as runFfmpeg3
+  runFfmpeg as runFfmpeg3,
+  spawnStreamingEncoder as spawnStreamingEncoder4
 } from "@hyperframes/engine";
 import {
   clearGifFramesBeforeNext,
@@ -10278,6 +10281,124 @@ function startEncodeProgress(job, stage, onProgress) {
   });
   return (frames = total) => reportEncodeProgress(job, frames, total, onProgress, 75);
 }
+function resolveEngineConfig(input) {
+  return input.engineConfig ?? input.job.config.producerConfig ?? resolveConfig();
+}
+function videoEncoderOptions(input, engineCfg) {
+  const { job, preset } = input;
+  return {
+    fps: job.config.fps,
+    width: input.width,
+    height: input.height,
+    codec: preset.codec,
+    preset: preset.preset,
+    quality: input.effectiveQuality,
+    bitrate: input.effectiveBitrate,
+    pixelFormat: preset.pixelFormat,
+    vp9CpuUsed: engineCfg.vp9CpuUsed,
+    useGpu: job.config.useGpu,
+    hdr: preset.hdr,
+    // Distributed chunk renders pass these so the encoder writes closed-GOP
+    // keyframes that survive `-f concat -c copy` at assemble time. In-process
+    // renders leave both undefined → preserves the existing open-GOP output.
+    lockGopForChunkConcat: input.lockGopForChunkConcat === true,
+    gopSize: input.gopSize
+  };
+}
+function canEncodeWhileCapturing(input, workerCount, cpuCount) {
+  return workerCount > 1 && workerCount < cpuCount && !input.isPngSequence && !input.isGif && !input.enableChunkedEncode && input.preset.codec === "h264" && !input.preset.hdr && input.job.config.useGpu !== true && input.captureImageFormat === "jpeg" && input.lockGopForChunkConcat !== true;
+}
+async function readLandedFrame(workerPath, mergedPath) {
+  if (workerPath !== void 0) {
+    try {
+      return await readFile2(workerPath);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+  }
+  return readFile2(mergedPath);
+}
+function encodeWhileCapturing(input, totalFrames) {
+  const engineCfg = resolveEngineConfig(input);
+  const stop = new AbortController();
+  const signal = input.abortSignal ? AbortSignal.any([input.abortSignal, stop.signal]) : stop.signal;
+  const landed = /* @__PURE__ */ new Map();
+  let captureDone = false;
+  let framesFed = 0;
+  let wake = null;
+  const nudge = () => {
+    wake?.();
+    wake = null;
+  };
+  signal.addEventListener("abort", nudge, { once: true });
+  let reportFed = null;
+  const encoder = spawnStreamingEncoder4(
+    input.videoOnlyPath,
+    { ...videoEncoderOptions(input, engineCfg), imageFormat: "jpeg" },
+    signal,
+    engineCfg
+  );
+  const fed = (async () => {
+    const stream = await encoder;
+    for (let next = 0; next < totalFrames; next++) {
+      while (!landed.has(next) && !captureDone && !signal.aborted) {
+        await new Promise((resolve10) => wake = resolve10);
+      }
+      if (signal.aborted) return;
+      const mergedPath = join24(input.framesDir, formatCaptureFrameName(next, "jpg"));
+      const frame = await readLandedFrame(landed.get(next), mergedPath);
+      landed.delete(next);
+      if (!await stream.writeFrame(frame)) {
+        throw new Error(stream.getExitError() ?? "encoder exited before the last frame");
+      }
+      framesFed++;
+      reportFed?.(framesFed);
+    }
+  })().then(
+    () => void 0,
+    (error) => error ?? new Error("encode failed")
+  );
+  const closeEncoder = async () => (await encoder.catch(() => null))?.close();
+  return {
+    onFrameLanded: (frame) => {
+      landed.set(frame.index, frame.path);
+      nudge();
+    },
+    finish: async () => {
+      const start = Date.now();
+      captureDone = true;
+      input.log.info("[Render] Encoded frames while capturing", {
+        framesFed,
+        totalFrames
+      });
+      const encoded = startEncodeProgress(input.job, "Encoding video", input.onProgress);
+      reportFed = encoded;
+      nudge();
+      const failure = await fed;
+      const result = await closeEncoder();
+      input.assertNotAborted();
+      if (failure === void 0 && result?.success) {
+        encoded();
+        return { encodeMs: Date.now() - start };
+      }
+      input.log.warn(
+        "[Render] Encoding while capturing failed; encoding the frames after capture",
+        {
+          error: String(failure ?? result?.error)
+        }
+      );
+      return runEncodeStage(input);
+    },
+    abort: async () => {
+      stop.abort();
+      await fed;
+      await closeEncoder();
+    },
+    get framesFed() {
+      return framesFed;
+    }
+  };
+}
 async function runEncodeStage(input) {
   const {
     job,
@@ -10285,16 +10406,11 @@ async function runEncodeStage(input) {
     outputPath,
     framesDir,
     videoOnlyPath,
-    width,
-    height,
     needsAlpha,
     hasAudio,
     audioOutputPath,
     isPngSequence,
     isGif,
-    preset,
-    effectiveQuality,
-    effectiveBitrate,
     enableChunkedEncode,
     chunkedEncodeSize,
     abortSignal,
@@ -10324,7 +10440,7 @@ async function runEncodeStage(input) {
     encoded();
     return { encodeMs: Date.now() - stage5Start };
   }
-  const engineCfg = input.engineConfig ?? job.config.producerConfig ?? resolveConfig();
+  const engineCfg = resolveEngineConfig(input);
   if (isGif) {
     const encoded = startEncodeProgress(job, "Encoding GIF", onProgress);
     if (hasAudio) {
@@ -10354,24 +10470,7 @@ async function runEncodeStage(input) {
   const videoEngineCfg = scaledEncodeTimeout > engineCfg.ffmpegEncodeTimeout ? { ...engineCfg, ffmpegEncodeTimeout: scaledEncodeTimeout } : engineCfg;
   const frameExt = frameFileExtension2(input.captureImageFormat);
   const framePattern = `frame_%06d.${frameExt}`;
-  const encoderOpts = {
-    fps: job.config.fps,
-    width,
-    height,
-    codec: preset.codec,
-    preset: preset.preset,
-    quality: effectiveQuality,
-    bitrate: effectiveBitrate,
-    pixelFormat: preset.pixelFormat,
-    vp9CpuUsed: engineCfg.vp9CpuUsed,
-    useGpu: job.config.useGpu,
-    hdr: preset.hdr,
-    // Distributed chunk renders pass these so the encoder writes closed-GOP
-    // keyframes that survive `-f concat -c copy` at assemble time. In-process
-    // renders leave both undefined → preserves the existing open-GOP output.
-    lockGopForChunkConcat: input.lockGopForChunkConcat === true,
-    gopSize: input.gopSize
-  };
+  const encoderOpts = videoEncoderOptions(input, engineCfg);
   const encodeResult = enableChunkedEncode ? await encodeFramesChunkedConcat(
     framesDir,
     framePattern,
@@ -13286,6 +13385,34 @@ async function executeRenderPipeline(input) {
           throw new Error(`Disk capture requires sdr_disk plan; got ${capturePlan.kind}`);
         }
         resetCaptureAttemptProgress(job);
+        const encodeInput = {
+          job,
+          log,
+          outputPath: stagedOutputPath,
+          framesDir,
+          videoOnlyPath,
+          width,
+          height,
+          needsAlpha,
+          captureImageFormat: captureOptions.format ?? "jpeg",
+          hasAudio,
+          audioOutputPath,
+          isPngSequence,
+          isGif,
+          preset,
+          effectiveQuality,
+          effectiveBitrate,
+          enableChunkedEncode,
+          chunkedEncodeSize,
+          engineConfig: cfg,
+          // Same value the streaming encoder above spreads — the disk and
+          // chunked-concat encoders need an identical GOP lock for HLS.
+          ...hlsEncoderGopLock,
+          abortSignal: executionSignal,
+          assertNotAborted,
+          onProgress
+        };
+        const overlap = !cfg.useDrawElement && workerSizing !== void 0 && canEncodeWhileCapturing(encodeInput, capturePlan.workerCount, workerSizing.cpuCount) ? encodeWhileCapturing(encodeInput, totalFrames) : null;
         const captureFrameStart = Date.now();
         const invokeDiskCapture = (diskPlan) => observeRenderStage(
           observability,
@@ -13307,13 +13434,15 @@ async function executeRenderPipeline(input) {
             createRenderVideoFrameInjector,
             abortSignal: executionSignal,
             assertNotAborted,
-            onProgress
+            onProgress,
+            onFrameLanded: (frame) => overlap?.onFrameLanded(frame)
           })
         );
         let captureRes;
         try {
           captureRes = await invokeDiskCapture(capturePlan);
         } catch (err) {
+          await overlap?.abort();
           if (!isDrawElementVerificationError(err) && !isDrawElementCaptureError(err) || err instanceof RenderCancelledError || executionSignal?.aborted === true) {
             throw err;
           }
@@ -13382,33 +13511,7 @@ async function executeRenderPipeline(input) {
             isGif,
             chunkedEncode: enableChunkedEncode
           }),
-          () => runEncodeStage({
-            job,
-            log,
-            outputPath: stagedOutputPath,
-            framesDir,
-            videoOnlyPath,
-            width,
-            height,
-            needsAlpha,
-            captureImageFormat: captureOptions.format ?? "jpeg",
-            hasAudio,
-            audioOutputPath,
-            isPngSequence,
-            isGif,
-            preset,
-            effectiveQuality,
-            effectiveBitrate,
-            enableChunkedEncode,
-            chunkedEncodeSize,
-            engineConfig: cfg,
-            // Same value the streaming encoder above spreads — the disk and
-            // chunked-concat encoders need an identical GOP lock for HLS.
-            ...hlsEncoderGopLock,
-            abortSignal: executionSignal,
-            assertNotAborted,
-            onProgress
-          })
+          () => overlap ? overlap.finish() : runEncodeStage(encodeInput)
         );
         perfStages.encodeMs = encodeRes.encodeMs;
       }

package/dist/services/distributed/renderChunk.d.ts

@@ -73,7 +73,7 @@ export interface ChunkResult {
     sessionBootMs: number;
     captureStageMs: number;
     encodeStageMs: number;
-    /** Capture workers used for this chunk (`calculateOptimalWorkers` result). */
+    /** Capture workers used for this chunk (`resolveChunkCaptureWorkers` result). */
     workers: number;
     /**
      * Effective engine mode used by every worker, after any browser fallback.
@@ -110,11 +110,18 @@ export interface RenderChunkOptions {
      * whole slice.
      */
     frameRange?: ChunkFrameRange;
+    /**
+     * Capture browsers the runtime can host. Raises the machine-wide sizing up to
+     * this many, one browser per 20 frames; never lowers it.
+     */
+    maxCaptureWorkers?: number;
 }
+/** Capture browsers for a chunk: the machine-wide sizing, raised by the runtime's budget. */
+export declare function resolveChunkCaptureWorkers(framesInChunk: number, machineSized: number, maxCaptureWorkers: number | undefined): number;
 /** The frames a chunk renders: its slice, or a validated sub-range of it. */
 export declare function resolveChunkFrameRange(slice: ChunkSliceJson, chunkIndex: number, frameRange: ChunkFrameRange | undefined): ChunkFrameRange;
 /** Compatibility-safe adapter seam for built-in or injected chunk renderers. */
-export type ChunkRenderer = (planDir: string, chunkIndex: number, outputChunkPath: string) => Promise<ChunkResult>;
+export type ChunkRenderer = (planDir: string, chunkIndex: number, outputChunkPath: string, options?: RenderChunkOptions) => Promise<ChunkResult>;
 interface DistributedCaptureSessionDependencies {
     createCaptureSession: typeof createCaptureSession;
     assertSwiftShader: typeof assertSwiftShader;

package/dist/services/render/stages/captureStage.d.ts

@@ -34,7 +34,7 @@
  * `safeCleanup`, `sampleDirectoryBytes`, etc.) into a shared module so
  * the stages can import them without reaching back into the orchestrator.
  */
-import { type BeforeCaptureHook, type CaptureOptions, type CapturePerfSummary, type CaptureSession, type EngineConfig } from "@hyperframes/engine";
+import { type BeforeCaptureHook, type CaptureOptions, type CapturePerfSummary, type CaptureSession, type EngineConfig, type LandedFrame } from "@hyperframes/engine";
 import type { FileServerHandle } from "../../fileServer.js";
 import type { ProducerLogger } from "../../../logger.js";
 import { type CaptureAttemptSummary, type ProgressCallback, type RenderConfig, type RenderJob } from "../../renderOrchestrator.js";
@@ -87,6 +87,7 @@ export interface CaptureStageInput {
         startFrame: number;
         endFrame: number;
     };
+    onFrameLanded?: (frame: LandedFrame) => void;
 }
 export interface CaptureStageResult {
     /** Final worker count after any adaptive retry. */