@hyperframes/producer 0.8.210 → 0.8.212

package/dist/index.js

@@ -64,6 +64,7 @@ import { fileURLToPath as fileURLToPath4 } from "url";
 // src/services/fileServer.ts
 import { Hono } from "hono";
 import { serve } from "@hono/node-server";
+import { settleOnBrowserSafePort } from "@hyperframes/engine";
 import {
   existsSync as existsSync2,
   realpathSync,
@@ -778,18 +779,21 @@ function createFileServer(options) {
   return new Promise((resolve13, reject) => {
     const connections = /* @__PURE__ */ new Set();
     const server = serve({ fetch: app.fetch, port, hostname: "127.0.0.1" }, (info) => {
-      resolve13({
-        url: `http://localhost:${info.port}`,
-        port: info.port,
-        addPreHeadScript: (script) => {
-          preHeadScripts.push(script);
-        },
-        close: () => {
-          for (const socket of connections) socket.destroy();
-          connections.clear();
-          server.close();
-        }
-      });
+      const bound = port === 0 ? settleOnBrowserSafePort(server, "127.0.0.1") : Promise.resolve(info.port);
+      bound.then((boundPort) => {
+        resolve13({
+          url: `http://localhost:${boundPort}`,
+          port: boundPort,
+          addPreHeadScript: (script) => {
+            preHeadScripts.push(script);
+          },
+          close: () => {
+            for (const socket of connections) socket.destroy();
+            connections.clear();
+            server.close();
+          }
+        });
+      }, reject);
     });
     server.on("connection", (socket) => {
       connections.add(socket);
@@ -926,6 +930,7 @@ import { fileURLToPath as fileURLToPath2 } from "node:url";
 var DEFAULT_RENDERS_DIR = process.env.PRODUCER_RENDERS_DIR ?? // fileURLToPath (not URL.pathname): on Windows .pathname is "/D:/..." which
 // resolves to a bogus renders dir.
 nodeResolve(fileURLToPath2(import.meta.url), "../../..", "renders");
+var LEADING_PARENT_SEGMENT_RE = /^\.\.(?:[\\/]|$)/;
 function isPathInside2(childPath, parentPath, options = {}) {
   const resolvePath = options.pathModule?.resolve ?? nodeResolve;
   const relativePath = options.pathModule?.relative ?? nodeRelative;
@@ -934,7 +939,7 @@ function isPathInside2(childPath, parentPath, options = {}) {
   const absParent = resolvePath(parentPath);
   if (absChild === absParent) return true;
   const rel = relativePath(absParent, absChild);
-  return rel !== "" && !rel.startsWith("..") && !isPathAbsolute(rel);
+  return rel !== "" && !LEADING_PARENT_SEGMENT_RE.test(rel) && !isPathAbsolute(rel);
 }
 function toExternalAssetKey(absPath) {
   if (absPath.startsWith("hf-ext/")) return absPath;
@@ -6868,9 +6873,10 @@ function detectShaderTransitionUsage(html) {
 async function resolveMediaDuration(src, mediaStart, playbackRate, baseDir, downloadDir, tagName, elementIdentity, log, urlByAbsentLocalPath, probes) {
   let filePath = src;
   if (isHttpUrl(src)) {
-    if (!existsSync10(downloadDir)) mkdirSync7(downloadDir, { recursive: true });
+    const remoteDir = join15(downloadDir, REMOTE_MEDIA_SUBDIR);
+    if (!existsSync10(remoteDir)) mkdirSync7(remoteDir, { recursive: true });
     try {
-      filePath = await downloadToTemp(src, downloadDir, void 0, void 0, void 0, {
+      filePath = await downloadToTemp(src, remoteDir, void 0, void 0, void 0, {
         onTelemetry: logRemoteDownloadTelemetry
       });
     } catch {
@@ -11703,7 +11709,7 @@ function videoEncoderOptions(input, engineCfg) {
   };
 }
 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";
+  return workerCount > 1 && workerCount < cpuCount && !input.isPngSequence && !input.isGif && !input.enableChunkedEncode && input.preset.codec === "h264" && !input.preset.hdr && input.captureImageFormat === "jpeg";
 }
 async function readLandedFrame(workerPath, mergedPath) {
   if (workerPath !== void 0) {
@@ -12822,6 +12828,11 @@ function resolveDeShortBand(args) {
   if (args.elementCountSource !== "live") return "unmeasured";
   return args.bandOpen ? "applied" : "skipped_elements";
 }
+function resolveDeSingleMinFrames(env) {
+  const raw = env.HF_DE_SINGLE_MIN_FRAMES;
+  const value = raw === void 0 || raw.trim() === "" ? 0 : Number(raw);
+  return Number.isFinite(value) ? value : 0;
+}
 function shouldPreferSingleWorkerDrawElement(args) {
   return args.workerCount > 1 && args.useDrawElement && !args.deCompileGate && !args.forceScreenshot && outputUsesH264Pipeline(args.outputFormat) && args.minFrames > 0 && args.totalFrames >= args.minFrames && args.singleWorkerStreamingOk && !args.layeredOrEffectRoute && !args.supersampling && !args.probeDeGated && !args.experimentalParallelDeOptIn;
 }
@@ -12939,12 +12950,25 @@ function shouldSegmentCapture(args) {
   if (raw === "true") return true;
   return args.durationSeconds >= resolveSegmentedMinSeconds(args.env);
 }
+function isAppleGpuDiskCapture(args) {
+  return args.platform === "darwin" && args.browserGpuMode === "hardware" && !args.layered && !args.parallelStream;
+}
 function shouldStreamParallelCapture(args) {
   return args.routerEnabled && args.workerCount > 1 && !args.useDrawElement && outputUsesH264Pipeline(args.outputFormat) && args.streamingOk && !args.layeredOrEffectRoute;
 }
 function shouldClampDefaultDrawElement(args) {
   return args.useDrawElement && !args.fastCaptureExplicitOptIn && (!args.useStreamingEncode || args.workerCount > 1) && !args.deParallelStreamVerified;
 }
+function calibrationCaptureConfig(cfg, env = process.env) {
+  const parallelKeepsDrawElement = !shouldClampDefaultDrawElement({
+    useDrawElement: cfg.useDrawElement,
+    fastCaptureExplicitOptIn: env.PRODUCER_EXPERIMENTAL_FAST_CAPTURE === "true",
+    useStreamingEncode: true,
+    workerCount: 2,
+    deParallelStreamVerified: env.HF_DE_PARALLEL_STREAM === "true"
+  });
+  return parallelKeepsDrawElement ? cfg : { ...cfg, useDrawElement: false };
+}
 function resolveCaptureForceScreenshotForPageSideCompositing(args) {
   return args.usePageSideCompositing ? true : args.forceScreenshot;
 }
@@ -13028,6 +13052,7 @@ async function executeRenderPipeline(input) {
   let captureCompositionHeight;
   let captureTotalFrames;
   const perfStages = {};
+  let pendingAudio;
   const hdrDiagnostics = {
     videoExtractionFailures: 0,
     imageDecodeFailures: 0
@@ -13389,7 +13414,7 @@ async function executeRenderPipeline(input) {
     updateJobStatus(job, "preprocessing", "Processing audio tracks", 20, onProgress, {
       code: "process_audio"
     });
-    const audioResult = await observeRenderStage(
+    const audioStage = observeRenderStage(
       observability,
       "audio_process",
       { audioCount: composition.audios.length },
@@ -13408,32 +13433,7 @@ async function executeRenderPipeline(input) {
         log
       })
     );
-    const { audioOutputPath, hasAudio } = audioResult;
-    perfStages.audioProcessMs = audioResult.audioProcessMs;
-    recordLimiterAttenuation(job, audioResult.audioLoweredDb);
-    if (audioResult.audioError) {
-      const audioFailures = audioResult.audioFailures ?? [];
-      const failureOwner = audioFailures.length === 0 ? void 0 : audioFailures.some((failure) => failure.owner === "system") ? "system" : "user";
-      const retryable = audioFailures.length === 0 ? void 0 : audioFailures.every((failure) => failure.retryable);
-      applyRenderWarningPolicy(
-        job,
-        [
-          {
-            code: "audio_processing_failed",
-            message: `Audio mix failed; output would be video-only: ${audioResult.audioError}`,
-            details: {
-              mediaType: "audio",
-              audioFailures: audioFailureDiagnostics2(audioFailures),
-              failureReasons: [...new Set(audioFailures.map((failure) => failure.reason))],
-              failureStages: [...new Set(audioFailures.map((failure) => failure.stage))],
-              failureOwner,
-              retryable
-            }
-          }
-        ],
-        log
-      );
-    }
+    pendingAudio = audioStage.catch(() => void 0);
     const stage4Start = Date.now();
     updateJobStatus(job, "rendering", "Starting frame capture", 25, onProgress, {
       code: "start_browsers"
@@ -13537,9 +13537,7 @@ async function executeRenderPipeline(input) {
     const hasHdrContent = Boolean(effectiveHdr && nativeHdrIds.size > 0);
     if (hasHdrContent) assertOutputScaleSupported(deviceScaleFactor, "hdr_layered");
     routePageMotionBlur = pageMotionBlurForRoute({ hasHdrContent, useLayeredComposite: false });
-    const deSingleMinFramesRaw = process.env.HF_DE_SINGLE_MIN_FRAMES;
-    const deSingleMinFramesNum = deSingleMinFramesRaw === void 0 || deSingleMinFramesRaw.trim() === "" ? 900 : Number(deSingleMinFramesRaw);
-    const deSingleMinFrames = Number.isFinite(deSingleMinFramesNum) ? deSingleMinFramesNum : 900;
+    const deSingleMinFrames = resolveDeSingleMinFrames(process.env);
     const deShortBandMinFrames = envInt("HF_DE_SHORT_MIN_FRAMES", 250);
     const deShortBandMaxElements = envInt("HF_DE_SHORT_MAX_ELEMENTS", 2500);
     const {
@@ -13708,7 +13706,7 @@ async function executeRenderPipeline(input) {
           stagePhase: "calibrating"
         }),
         () => runCaptureCalibration({
-          cfg,
+          cfg: calibrationCaptureConfig(cfg),
           fileServer: activeFileServer,
           workDir,
           log,
@@ -13744,10 +13742,28 @@ async function executeRenderPipeline(input) {
         deParallelRouterEligible
       });
     }
+    const appleGpuDiskCapture = isAppleGpuDiskCapture({
+      platform: process.platform,
+      browserGpuMode: resolvedBrowserGpuMode,
+      layered: shouldUseLayeredComposite({
+        hasHdrContent,
+        hasShaderTransitions: compiled.hasShaderTransitions && !isGif,
+        isPngSequence
+      }),
+      parallelStream: isCaptureParallelStreamRouterEnabled(
+        process.env,
+        resolveParallelCaptureMode({
+          platform: process.platform,
+          headlessShellPath: resolveHeadlessShellPath(cfg),
+          forceScreenshot: captureForceScreenshot,
+          deviceScaleFactor: captureOptions.deviceScaleFactor
+        })
+      )
+    });
     workerCount = resolveRenderWorkerCount(
       totalFrames,
       job.config.workers,
-      cfg,
+      { ...cfg, appleGpuDiskCapture },
       compiled,
       log,
       captureCalibration?.estimate,
@@ -14107,6 +14123,33 @@ async function executeRenderPipeline(input) {
     }
     const effectiveQuality = job.config.crf ?? preset.quality;
     const effectiveBitrate = job.config.crf != null ? void 0 : job.config.videoBitrate;
+    const audioResult = await audioStage;
+    const { audioOutputPath, hasAudio } = audioResult;
+    perfStages.audioProcessMs = audioResult.audioProcessMs;
+    recordLimiterAttenuation(job, audioResult.audioLoweredDb);
+    if (audioResult.audioError) {
+      const audioFailures = audioResult.audioFailures ?? [];
+      const failureOwner = audioFailures.length === 0 ? void 0 : audioFailures.some((failure) => failure.owner === "system") ? "system" : "user";
+      const retryable = audioFailures.length === 0 ? void 0 : audioFailures.every((failure) => failure.retryable);
+      applyRenderWarningPolicy(
+        job,
+        [
+          {
+            code: "audio_processing_failed",
+            message: `Audio mix failed; output would be video-only: ${audioResult.audioError}`,
+            details: {
+              mediaType: "audio",
+              audioFailures: audioFailureDiagnostics2(audioFailures),
+              failureReasons: [...new Set(audioFailures.map((failure) => failure.reason))],
+              failureStages: [...new Set(audioFailures.map((failure) => failure.stage))],
+              failureOwner,
+              retryable
+            }
+          }
+        ],
+        log
+      );
+    }
     resetCaptureAttemptProgress(job);
     if (capturePlan.kind === "hdr_layered") {
       const layeredPlan = capturePlan;
@@ -14821,6 +14864,7 @@ async function executeRenderPipeline(input) {
     updateJobStatus(job, "complete", "Render complete", 100, onProgress);
     await eventPublisher.flush();
   } catch (caught) {
+    await pendingAudio;
     const error = tooSlowError ?? caught;
     if (!tooSlowError && (error instanceof RenderCancelledError || executionSignal?.aborted)) {
       job.error = error instanceof Error ? error.message : "render_cancelled";

package/dist/public-server.js

@@ -85,6 +85,7 @@ import { fileURLToPath as fileURLToPath4 } from "url";
 // src/services/fileServer.ts
 import { Hono } from "hono";
 import { serve } from "@hono/node-server";
+import { settleOnBrowserSafePort } from "@hyperframes/engine";
 import {
   existsSync as existsSync2,
   realpathSync,
@@ -799,18 +800,21 @@ function createFileServer(options) {
   return new Promise((resolve11, reject) => {
     const connections = /* @__PURE__ */ new Set();
     const server = serve({ fetch: app.fetch, port, hostname: "127.0.0.1" }, (info) => {
-      resolve11({
-        url: `http://localhost:${info.port}`,
-        port: info.port,
-        addPreHeadScript: (script) => {
-          preHeadScripts.push(script);
-        },
-        close: () => {
-          for (const socket of connections) socket.destroy();
-          connections.clear();
-          server.close();
-        }
-      });
+      const bound = port === 0 ? settleOnBrowserSafePort(server, "127.0.0.1") : Promise.resolve(info.port);
+      bound.then((boundPort) => {
+        resolve11({
+          url: `http://localhost:${boundPort}`,
+          port: boundPort,
+          addPreHeadScript: (script) => {
+            preHeadScripts.push(script);
+          },
+          close: () => {
+            for (const socket of connections) socket.destroy();
+            connections.clear();
+            server.close();
+          }
+        });
+      }, reject);
     });
     server.on("connection", (socket) => {
       connections.add(socket);
@@ -944,6 +948,7 @@ import { fileURLToPath as fileURLToPath2 } from "node:url";
 var DEFAULT_RENDERS_DIR = process.env.PRODUCER_RENDERS_DIR ?? // fileURLToPath (not URL.pathname): on Windows .pathname is "/D:/..." which
 // resolves to a bogus renders dir.
 nodeResolve(fileURLToPath2(import.meta.url), "../../..", "renders");
+var LEADING_PARENT_SEGMENT_RE = /^\.\.(?:[\\/]|$)/;
 function isPathInside2(childPath, parentPath, options = {}) {
   const resolvePath = options.pathModule?.resolve ?? nodeResolve;
   const relativePath = options.pathModule?.relative ?? nodeRelative;
@@ -952,7 +957,7 @@ function isPathInside2(childPath, parentPath, options = {}) {
   const absParent = resolvePath(parentPath);
   if (absChild === absParent) return true;
   const rel = relativePath(absParent, absChild);
-  return rel !== "" && !rel.startsWith("..") && !isPathAbsolute(rel);
+  return rel !== "" && !LEADING_PARENT_SEGMENT_RE.test(rel) && !isPathAbsolute(rel);
 }
 function toExternalAssetKey(absPath) {
   if (absPath.startsWith("hf-ext/")) return absPath;
@@ -6885,9 +6890,10 @@ function detectShaderTransitionUsage(html) {
 async function resolveMediaDuration(src, mediaStart, playbackRate, baseDir, downloadDir, tagName, elementIdentity, log, urlByAbsentLocalPath, probes) {
   let filePath = src;
   if (isHttpUrl(src)) {
-    if (!existsSync10(downloadDir)) mkdirSync7(downloadDir, { recursive: true });
+    const remoteDir = join15(downloadDir, REMOTE_MEDIA_SUBDIR);
+    if (!existsSync10(remoteDir)) mkdirSync7(remoteDir, { recursive: true });
     try {
-      filePath = await downloadToTemp(src, downloadDir, void 0, void 0, void 0, {
+      filePath = await downloadToTemp(src, remoteDir, void 0, void 0, void 0, {
         onTelemetry: logRemoteDownloadTelemetry
       });
     } catch {
@@ -11684,7 +11690,7 @@ function videoEncoderOptions(input, engineCfg) {
   };
 }
 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";
+  return workerCount > 1 && workerCount < cpuCount && !input.isPngSequence && !input.isGif && !input.enableChunkedEncode && input.preset.codec === "h264" && !input.preset.hdr && input.captureImageFormat === "jpeg";
 }
 async function readLandedFrame(workerPath, mergedPath) {
   if (workerPath !== void 0) {
@@ -12803,6 +12809,11 @@ function resolveDeShortBand(args) {
   if (args.elementCountSource !== "live") return "unmeasured";
   return args.bandOpen ? "applied" : "skipped_elements";
 }
+function resolveDeSingleMinFrames(env) {
+  const raw = env.HF_DE_SINGLE_MIN_FRAMES;
+  const value = raw === void 0 || raw.trim() === "" ? 0 : Number(raw);
+  return Number.isFinite(value) ? value : 0;
+}
 function shouldPreferSingleWorkerDrawElement(args) {
   return args.workerCount > 1 && args.useDrawElement && !args.deCompileGate && !args.forceScreenshot && outputUsesH264Pipeline(args.outputFormat) && args.minFrames > 0 && args.totalFrames >= args.minFrames && args.singleWorkerStreamingOk && !args.layeredOrEffectRoute && !args.supersampling && !args.probeDeGated && !args.experimentalParallelDeOptIn;
 }
@@ -12920,12 +12931,25 @@ function shouldSegmentCapture(args) {
   if (raw === "true") return true;
   return args.durationSeconds >= resolveSegmentedMinSeconds(args.env);
 }
+function isAppleGpuDiskCapture(args) {
+  return args.platform === "darwin" && args.browserGpuMode === "hardware" && !args.layered && !args.parallelStream;
+}
 function shouldStreamParallelCapture(args) {
   return args.routerEnabled && args.workerCount > 1 && !args.useDrawElement && outputUsesH264Pipeline(args.outputFormat) && args.streamingOk && !args.layeredOrEffectRoute;
 }
 function shouldClampDefaultDrawElement(args) {
   return args.useDrawElement && !args.fastCaptureExplicitOptIn && (!args.useStreamingEncode || args.workerCount > 1) && !args.deParallelStreamVerified;
 }
+function calibrationCaptureConfig(cfg, env = process.env) {
+  const parallelKeepsDrawElement = !shouldClampDefaultDrawElement({
+    useDrawElement: cfg.useDrawElement,
+    fastCaptureExplicitOptIn: env.PRODUCER_EXPERIMENTAL_FAST_CAPTURE === "true",
+    useStreamingEncode: true,
+    workerCount: 2,
+    deParallelStreamVerified: env.HF_DE_PARALLEL_STREAM === "true"
+  });
+  return parallelKeepsDrawElement ? cfg : { ...cfg, useDrawElement: false };
+}
 function resolveCaptureForceScreenshotForPageSideCompositing(args) {
   return args.usePageSideCompositing ? true : args.forceScreenshot;
 }
@@ -13009,6 +13033,7 @@ async function executeRenderPipeline(input) {
   let captureCompositionHeight;
   let captureTotalFrames;
   const perfStages = {};
+  let pendingAudio;
   const hdrDiagnostics = {
     videoExtractionFailures: 0,
     imageDecodeFailures: 0
@@ -13370,7 +13395,7 @@ async function executeRenderPipeline(input) {
     updateJobStatus(job, "preprocessing", "Processing audio tracks", 20, onProgress, {
       code: "process_audio"
     });
-    const audioResult = await observeRenderStage(
+    const audioStage = observeRenderStage(
       observability,
       "audio_process",
       { audioCount: composition.audios.length },
@@ -13389,32 +13414,7 @@ async function executeRenderPipeline(input) {
         log
       })
     );
-    const { audioOutputPath, hasAudio } = audioResult;
-    perfStages.audioProcessMs = audioResult.audioProcessMs;
-    recordLimiterAttenuation(job, audioResult.audioLoweredDb);
-    if (audioResult.audioError) {
-      const audioFailures = audioResult.audioFailures ?? [];
-      const failureOwner = audioFailures.length === 0 ? void 0 : audioFailures.some((failure) => failure.owner === "system") ? "system" : "user";
-      const retryable = audioFailures.length === 0 ? void 0 : audioFailures.every((failure) => failure.retryable);
-      applyRenderWarningPolicy(
-        job,
-        [
-          {
-            code: "audio_processing_failed",
-            message: `Audio mix failed; output would be video-only: ${audioResult.audioError}`,
-            details: {
-              mediaType: "audio",
-              audioFailures: audioFailureDiagnostics2(audioFailures),
-              failureReasons: [...new Set(audioFailures.map((failure) => failure.reason))],
-              failureStages: [...new Set(audioFailures.map((failure) => failure.stage))],
-              failureOwner,
-              retryable
-            }
-          }
-        ],
-        log
-      );
-    }
+    pendingAudio = audioStage.catch(() => void 0);
     const stage4Start = Date.now();
     updateJobStatus(job, "rendering", "Starting frame capture", 25, onProgress, {
       code: "start_browsers"
@@ -13518,9 +13518,7 @@ async function executeRenderPipeline(input) {
     const hasHdrContent = Boolean(effectiveHdr && nativeHdrIds.size > 0);
     if (hasHdrContent) assertOutputScaleSupported(deviceScaleFactor, "hdr_layered");
     routePageMotionBlur = pageMotionBlurForRoute({ hasHdrContent, useLayeredComposite: false });
-    const deSingleMinFramesRaw = process.env.HF_DE_SINGLE_MIN_FRAMES;
-    const deSingleMinFramesNum = deSingleMinFramesRaw === void 0 || deSingleMinFramesRaw.trim() === "" ? 900 : Number(deSingleMinFramesRaw);
-    const deSingleMinFrames = Number.isFinite(deSingleMinFramesNum) ? deSingleMinFramesNum : 900;
+    const deSingleMinFrames = resolveDeSingleMinFrames(process.env);
     const deShortBandMinFrames = envInt("HF_DE_SHORT_MIN_FRAMES", 250);
     const deShortBandMaxElements = envInt("HF_DE_SHORT_MAX_ELEMENTS", 2500);
     const {
@@ -13689,7 +13687,7 @@ async function executeRenderPipeline(input) {
           stagePhase: "calibrating"
         }),
         () => runCaptureCalibration({
-          cfg,
+          cfg: calibrationCaptureConfig(cfg),
           fileServer: activeFileServer,
           workDir,
           log,
@@ -13725,10 +13723,28 @@ async function executeRenderPipeline(input) {
         deParallelRouterEligible
       });
     }
+    const appleGpuDiskCapture = isAppleGpuDiskCapture({
+      platform: process.platform,
+      browserGpuMode: resolvedBrowserGpuMode,
+      layered: shouldUseLayeredComposite({
+        hasHdrContent,
+        hasShaderTransitions: compiled.hasShaderTransitions && !isGif,
+        isPngSequence
+      }),
+      parallelStream: isCaptureParallelStreamRouterEnabled(
+        process.env,
+        resolveParallelCaptureMode({
+          platform: process.platform,
+          headlessShellPath: resolveHeadlessShellPath(cfg),
+          forceScreenshot: captureForceScreenshot,
+          deviceScaleFactor: captureOptions.deviceScaleFactor
+        })
+      )
+    });
     workerCount = resolveRenderWorkerCount(
       totalFrames,
       job.config.workers,
-      cfg,
+      { ...cfg, appleGpuDiskCapture },
       compiled,
       log,
       captureCalibration?.estimate,
@@ -14088,6 +14104,33 @@ async function executeRenderPipeline(input) {
     }
     const effectiveQuality = job.config.crf ?? preset.quality;
     const effectiveBitrate = job.config.crf != null ? void 0 : job.config.videoBitrate;
+    const audioResult = await audioStage;
+    const { audioOutputPath, hasAudio } = audioResult;
+    perfStages.audioProcessMs = audioResult.audioProcessMs;
+    recordLimiterAttenuation(job, audioResult.audioLoweredDb);
+    if (audioResult.audioError) {
+      const audioFailures = audioResult.audioFailures ?? [];
+      const failureOwner = audioFailures.length === 0 ? void 0 : audioFailures.some((failure) => failure.owner === "system") ? "system" : "user";
+      const retryable = audioFailures.length === 0 ? void 0 : audioFailures.every((failure) => failure.retryable);
+      applyRenderWarningPolicy(
+        job,
+        [
+          {
+            code: "audio_processing_failed",
+            message: `Audio mix failed; output would be video-only: ${audioResult.audioError}`,
+            details: {
+              mediaType: "audio",
+              audioFailures: audioFailureDiagnostics2(audioFailures),
+              failureReasons: [...new Set(audioFailures.map((failure) => failure.reason))],
+              failureStages: [...new Set(audioFailures.map((failure) => failure.stage))],
+              failureOwner,
+              retryable
+            }
+          }
+        ],
+        log
+      );
+    }
     resetCaptureAttemptProgress(job);
     if (capturePlan.kind === "hdr_layered") {
       const layeredPlan = capturePlan;
@@ -14802,6 +14845,7 @@ async function executeRenderPipeline(input) {
     updateJobStatus(job, "complete", "Render complete", 100, onProgress);
     await eventPublisher.flush();
   } catch (caught) {
+    await pendingAudio;
     const error = tooSlowError ?? caught;
     if (!tooSlowError && (error instanceof RenderCancelledError || executionSignal?.aborted)) {
       job.error = error instanceof Error ? error.message : "render_cancelled";

package/dist/services/render/captureCost.d.ts

@@ -8,7 +8,7 @@
  * (`CAPTURE_CALIBRATION_TARGET_MS`) are tunable knobs — they pin the
  * relationship between observed capture time and worker count.
  */
-import { type BeforeCaptureHook, type CaptureOptions, type CaptureSession, type EngineConfig, type WorkerSizing } from "@hyperframes/engine";
+import { type BeforeCaptureHook, type CaptureOptions, type CaptureSession, type EngineConfig, type WorkerSizing, type WorkerSizingConfig } from "@hyperframes/engine";
 import type { CompiledComposition } from "../htmlCompiler.js";
 import type { FileServerHandle } from "../fileServer.js";
 import { type ProducerLogger } from "../../logger.js";
@@ -56,7 +56,7 @@ export declare function estimateCaptureCostMultiplier(compiled: Pick<CompiledCom
  * synthetic `WorkerSizing` (the real one depends on the host's heap).
  */
 export declare function buildHeapAdvisoryWarning(sizing: WorkerSizing, requestedWorkers: number | undefined): string | undefined;
-export declare function resolveRenderWorkerCount(totalFrames: number, requestedWorkers: number | undefined, cfg: EngineConfig, compiled: Pick<CompiledComposition, "hasShaderTransitions" | "renderModeHints">, log?: ProducerLogger, measuredCaptureCost?: CaptureCostEstimate, 
+export declare function resolveRenderWorkerCount(totalFrames: number, requestedWorkers: number | undefined, cfg: EngineConfig & Pick<WorkerSizingConfig, "appleGpuDiskCapture">, compiled: Pick<CompiledComposition, "hasShaderTransitions" | "renderModeHints">, log?: ProducerLogger, measuredCaptureCost?: CaptureCostEstimate, 
 /** Sink for the sizing provenance so the orchestrator can thread it into telemetry. */
 onSizing?: (sizing: WorkerSizing) => void): number;
 export declare function createCaptureCalibrationConfig(cfg: EngineConfig): EngineConfig;

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

@@ -104,8 +104,8 @@ export interface EncodeStageResult {
     encodeMs: number;
 }
 /**
- * Software libx264 from JPEG only: the streaming encoder then runs the disk encoder's
- * arguments (same bytes). Needs a core the capture workers leave free.
+ * h264 from JPEG only, software or GPU: the streaming encoder then runs the disk encoder's
+ * arguments. Needs a core the capture workers leave free.
  */
 export declare function canEncodeWhileCapturing(input: EncodeStageInput, workerCount: number, cpuCount: number): boolean;
 export interface EncodeWhileCapturing {

package/dist/services/renderOrchestrator.d.ts

@@ -829,15 +829,17 @@ export declare function resolveDeShortBand(args: {
     bandOpen: boolean;
     elementCountSource: "live" | "static";
 }): "applied" | "skipped_elements" | "unmeasured" | undefined;
+/** Single-worker drawElement inversion floor; off (0) by default: parallel screenshot capture was
+ * ~25% faster wherever it fired. HF_DE_SINGLE_MIN_FRAMES=<n> turns it back on. */
+export declare function resolveDeSingleMinFrames(env: NodeJS.ProcessEnv): number;
 /**
  * DE priority inversion predicate: should a multi-worker render drop to
  * single-worker verified drawElement streaming?
  *
- * Benchmarked 2026-07-08: above ~900 frames DE-single beats screenshot-parallel
- * at every worker count (2,380f: 66s vs 109–127s at W2–W5); below it DE's fixed
- * init cost (verify + dedup arming) loses by a small margin. Only fires for the
- * exact benchmarked configuration: default-on DE, mp4, streaming-eligible,
- * no compile gate, no forced screenshot.
+ * Opt-in (see resolveDeSingleMinFrames): re-measured on hardware-GL Macs, one
+ * drawElement worker was ~25% slower than 4 screenshot workers at 1,271 and 9,000
+ * frames. Only fires for default-on DE, mp4, streaming-eligible, no compile gate,
+ * no forced screenshot.
  */
 export declare function shouldPreferSingleWorkerDrawElement(args: {
     workerCount: number;
@@ -1226,6 +1228,13 @@ export declare function shouldSegmentCapture(args: {
     /** shouldUseStreamingEncode(cfg, format, 1, duration) at the call site. */
     streamingOk: boolean;
 }): boolean;
+/** Worker sizing's Apple-GPU budget fits only frames written to disk by screenshot workers. */
+export declare function isAppleGpuDiskCapture(args: {
+    platform: NodeJS.Platform;
+    browserGpuMode: "software" | "hardware";
+    layered: boolean;
+    parallelStream: boolean;
+}): boolean;
 export declare function shouldStreamParallelCapture(args: {
     /** Router switch for this render — see isCaptureParallelStreamRouterEnabled. */
     routerEnabled: boolean;
@@ -1260,6 +1269,11 @@ export declare function shouldClampDefaultDrawElement(args: {
      * self-verification net is present. */
     deParallelStreamVerified: boolean;
 }): boolean;
+/**
+ * Calibration sizes a parallel render, and parallel workers capture by screenshot
+ * unless drawElement was opted into: measure that mode, without a drawElement init.
+ */
+export declare function calibrationCaptureConfig(cfg: EngineConfig, env?: NodeJS.ProcessEnv): EngineConfig;
 export declare function resolveCaptureForceScreenshotForPageSideCompositing(args: {
     forceScreenshot: boolean;
     usePageSideCompositing: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/producer",
-  "version": "0.8.210",
+  "version": "0.8.212",
   "description": "HTML-to-video rendering engine using Chrome's BeginFrame API",
   "repository": {
     "type": "git",
@@ -33,13 +33,13 @@
     "hono": "^4.6.0",
     "linkedom": "^0.18.12",
     "postcss": "^8.4.0",
-    "puppeteer": "^25.2.1",
-    "puppeteer-core": "^25.2.1",
-    "@hyperframes/core": "0.8.210",
-    "@hyperframes/engine": "0.8.210",
-    "@hyperframes/lint": "0.8.210",
-    "@hyperframes/studio-server": "0.8.210",
-    "@hyperframes/parsers": "0.8.210"
+    "puppeteer": "~25.11.0",
+    "puppeteer-core": "^25.11.0",
+    "@hyperframes/engine": "0.8.212",
+    "@hyperframes/lint": "0.8.212",
+    "@hyperframes/parsers": "0.8.212",
+    "@hyperframes/studio-server": "0.8.212",
+    "@hyperframes/core": "0.8.212"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",
@@ -48,7 +48,7 @@
     "tsx": "^4.21.0",
     "typescript": "^5.7.2",
     "vitest": "^4.1.11",
-    "@hyperframes/aws-lambda": "0.8.210"
+    "@hyperframes/aws-lambda": "0.8.212"
   },
   "engines": {
     "node": ">=22"