@hyperframes/engine 0.8.210 → 0.8.212

package/dist/index.d.ts

@@ -38,12 +38,13 @@ export { chromeMajorCeiling } from "./services/chromeHostCeiling.js";
 export { acquireBrowser, setHostHandlesSigint, releaseBrowser, drainBrowserPool, closeBrowserPool, resolveHeadlessShellPath, resolveBrowserGpuMode, buildChromeArgs, compositionRequiresWebGpu, assertWebGpuAdapterAvailable, usesSoftwareWebGpu, WebGpuUnavailableError, ENABLE_BROWSER_POOL, BrowserLeasePool, type GpuProbeLifecycle, type BuildChromeArgsOptions, type BrowserLaunchFingerprint, type BrowserLease, type BrowserPoolState, type CaptureMode, type AcquiredBrowser, } from "./services/browserManager.js";
 export { augmentProtocolTimeoutError, isProtocolTimeoutError, } from "./services/protocolTimeoutErrorHint.js";
 export { augmentPageNavigationTimeoutError, isPageNavigationTimeoutError, type NavigationTimeoutHintContext, } from "./services/pageNavigationTimeoutErrorHint.js";
+export { forcePreservedDrawingBuffer } from "./services/drawElementService.js";
 export { createCaptureSession, initializeSession, closeCaptureSession, captureFrame, captureFrameToBuffer, captureFrameToBufferPipelined, captureFramesBatchPipelined, DrawElementVerificationError, isDrawElementVerificationError, getDrawElementVerificationDetails, type DrawElementVerificationDetails, recaptureDrawElementFrameForVerify, completeDeferredDrawElementInit, writeCapturedFrame, discardWarmupCapture, getCompositionDuration, getCapturePerfSummary, percentileOf, prepareCaptureSessionForReuse, deriveBeginFrameProbeTimeTicks, type CaptureSession, isTransientBrowserError, isMemoryExhaustionError, type BeforeCaptureHook, type DiscardWarmupInnerCapture, type StaticVerificationOutcome, VfxFailureError, waitForImagesReady, evaluateHfDiagnostic, buildZeroDurationDiagnostic, } from "./services/frameCapture.js";
 export { CaptureFailure, classifyCaptureFailure, isFatalCaptureFailure, type CaptureFailureKind, type CaptureWorkerDiagnostic, } from "./services/captureFailure.js";
 export { createChromeMemorySampler, type ChromeMemoryStats, } from "./services/chromeMemorySampler.js";
 export { installMediaRenderIdBridge } from "./services/mediaRenderIdBridge.js";
 export { beginFrameCapture, pageScreenshotCapture, getCdpSession, injectVideoFramesBatch, syncVideoFrameVisibility, cdpSessionCache, probeBeginFrameLiveness, initTransparentBackground, capturesAlpha, captureAlphaPng, applyDomLayerMask, removeDomLayerMask, DOM_LAYER_MASK_STYLE_ID, type BeginFrameResult, } from "./services/screenshotService.js";
-export { buildEncoderArgs, encodeFramesFromDir, buildConcatArgs, concatVideoFiles, encodeFramesChunkedConcat, muxVideoWithAudio, applyFaststart, packageHls, detectGpuEncoder, ENCODER_PRESETS, getEncoderPreset, PRORES_PROFILES, PRORES_PROFILE_NAMES, isProresProfile, type ProresProfile, appendRateCapArgs, keyframeIntervalToGopSize, HLS_MASTER_PLAYLIST, HLS_VIDEO_PLAYLIST, HLS_AUDIO_PLAYLIST, type GpuEncoder, type PackageHlsOptions, } from "./services/chunkEncoder.js";
+export { buildEncoderArgs, encodeFramesFromDir, buildConcatArgs, concatVideoFiles, encodeFramesChunkedConcat, muxVideoWithAudio, applyFaststart, packageHls, detectGpuEncoder, getCachedGpuEncoder, ENCODER_PRESETS, getEncoderPreset, PRORES_PROFILES, PRORES_PROFILE_NAMES, isProresProfile, type ProresProfile, appendRateCapArgs, keyframeIntervalToGopSize, HLS_MASTER_PLAYLIST, HLS_VIDEO_PLAYLIST, HLS_AUDIO_PLAYLIST, type GpuEncoder, type PackageHlsOptions, } from "./services/chunkEncoder.js";
 export type { EncoderOptions, EncodeResult, MuxResult } from "./services/chunkEncoder.types.js";
 export { spawnStreamingEncoder, createFrameReorderBuffer, type StreamingEncoder, type StreamingEncoderOptions, type StreamingEncoderResult, type FrameReorderBuffer, } from "./services/streamingEncoder.js";
 export { parseVideoElements, parseImageElements, extractVideoFramesRange, extractAllVideoFrames, isVideoPastTimelineEnd, resolveTimelineExtractionWindow, resolveVideoExtractionWindow, rebaseVideoToWindow, resolveFinalFrameExtractionWindow, resolveFrameFormat, resolveVideoExtractionDuration, resolvePlayableVideoDuration, extractionFrameCountForDuration, resolveProjectRelativeSrc, getFrameAtTime, isVideoHiddenBeforeStreamStart, createFrameLookupTable, FrameLookupTable, analyzeClipMediaFit, classifyVideoExtractionError, isVideoSourceExtractionError, runVideoExtractionWithRetry, safeVideoExtractionSourceIdentity, VideoSourceExtractionError, type VideoElement, type ImageElement, type ExtractedFrames, type DeferredFrameRange, type FrameRange, type ExtractionOptions, type ExtractionResult, type ExtractionPhaseBreakdown, type TimelineExtractionWindow, type VideoExtractionFailure, type VideoExtractionFailureKind, type VideoExtractionFailureGroupDetails, type VideoExtractionFailureRetry, type VideoExtractionFailureStatusClass, type SafeVideoExtractionSourceIdentity, type VideoFrameFormat, VIDEO_FRAME_FORMATS, isVideoFrameFormat, EXTRACT_CACHE_MIN_AGE_MS, sdrCanvasColourFilters, } from "./services/videoFrameExtractor.js";
@@ -55,7 +56,7 @@ export { MIXED_AUDIO_FILENAME, parseAudioElements, parseMasterFxChain, processCo
 export { audioFailureDiagnostics } from "./services/audioFailureDiagnostic.js";
 export { cloneCaptureWarning, cloneCaptureWarnings } from "./services/captureWarning.js";
 export type { AudioElement, AudioFailureReason, AudioFailureStage, AudioProcessingFailure, AudioFailureDiagnostic, AudioSubprocessEvidence, AudioTrack, AudioVolumeKeyframe, MixResult, } from "./services/audioMixer.types.js";
-export { calculateOptimalWorkers, computeWorkerSizing, selectVerifySampleIndicesForTask, verifyDiskDrawElementSamples, distributeFrames, distributeFramesInterleaved, executeParallelCapture, mergeWorkerFrames, getSystemResources, shouldDisableBrowserPoolForParallelWorker, type WorkerTask, type WorkerResult, type WorkerSizing, type WorkerSizingBound, type LandedFrame, type ParallelProgress, type ParallelWorkerPhaseDiagnostic, } from "./services/parallelCoordinator.js";
+export { calculateOptimalWorkers, computeWorkerSizing, selectVerifySampleIndicesForTask, verifyDiskDrawElementSamples, distributeFrames, distributeFramesInterleaved, executeParallelCapture, mergeWorkerFrames, getSystemResources, shouldDisableBrowserPoolForParallelWorker, type WorkerTask, type WorkerResult, type WorkerSizing, type WorkerSizingBound, type WorkerSizingConfig, type LandedFrame, type ParallelProgress, type ParallelWorkerPhaseDiagnostic, } from "./services/parallelCoordinator.js";
 export { createFileServer, type FileServerOptions, type FileServerHandle, } from "./services/fileServer.js";
 export { quantizeTimeToFrame, MEDIA_VISUAL_STYLE_PROPERTIES } from "@hyperframes/core";
 export { frameFileExtension } from "./services/frameCapture.js";
@@ -64,6 +65,7 @@ export { frameSequencePath } from "./services/extractedFrameIndex.js";
 export type { MotionBlurOptions, MotionBlurBlendSpace } from "./services/motionBlur.js";
 export type { PageMotionBlurOff } from "./types.js";
 export { assertSwiftShader, readWebGlVendorInfo, SwiftShaderAssertionError, BROWSER_GPU_NOT_SOFTWARE, } from "./utils/assertSwiftShader.js";
+export { isBrowserSafePort, listenOnBrowserSafePort, settleOnBrowserSafePort, } from "./utils/browserSafePort.js";
 export { readWebGlVendorInfoFromCanvas } from "./utils/readWebGlVendorInfoFromCanvas.js";
 export { extractMediaMetadata, extractVideoMetadata, extractFinalVideoFrameTimestamp, extractAudioMetadata, declareContentAddressedUrl, declareProbeFactsUrl, PROBE_FACTS_VERSION, buildProbeFactsText, probeMediaProfile, runFfprobe, analyzeKeyframeIntervals, type VideoMetadata, type AudioMetadata, type MediaProbeProfile, type KeyframeAnalysis, } from "./utils/ffprobe.js";
 export { NOT_MEDIA_PAYLOAD, NotMediaPayloadError, assertMediaPayload, fingerprintElementId, isNotMediaPayload, } from "./utils/notMediaPayload.js";

package/dist/index.js

@@ -40,6 +40,7 @@ export { acquireBrowser, setHostHandlesSigint, releaseBrowser, drainBrowserPool,
 export { augmentProtocolTimeoutError, isProtocolTimeoutError, } from "./services/protocolTimeoutErrorHint.js";
 export { augmentPageNavigationTimeoutError, isPageNavigationTimeoutError, } from "./services/pageNavigationTimeoutErrorHint.js";
 // ── Frame capture pipeline ──────────────────────────────────────────────────────
+export { forcePreservedDrawingBuffer } from "./services/drawElementService.js";
 export { createCaptureSession, initializeSession, closeCaptureSession, captureFrame, captureFrameToBuffer, captureFrameToBufferPipelined, captureFramesBatchPipelined, DrawElementVerificationError, isDrawElementVerificationError, getDrawElementVerificationDetails, recaptureDrawElementFrameForVerify, completeDeferredDrawElementInit, writeCapturedFrame, discardWarmupCapture, getCompositionDuration, getCapturePerfSummary, percentileOf, prepareCaptureSessionForReuse, deriveBeginFrameProbeTimeTicks, isTransientBrowserError, isMemoryExhaustionError, VfxFailureError, waitForImagesReady, evaluateHfDiagnostic, buildZeroDurationDiagnostic, } from "./services/frameCapture.js";
 export { CaptureFailure, classifyCaptureFailure, isFatalCaptureFailure, } from "./services/captureFailure.js";
 export { createChromeMemorySampler, } from "./services/chromeMemorySampler.js";
@@ -47,7 +48,7 @@ export { createChromeMemorySampler, } from "./services/chromeMemorySampler.js";
 export { installMediaRenderIdBridge } from "./services/mediaRenderIdBridge.js";
 export { beginFrameCapture, pageScreenshotCapture, getCdpSession, injectVideoFramesBatch, syncVideoFrameVisibility, cdpSessionCache, probeBeginFrameLiveness, initTransparentBackground, capturesAlpha, captureAlphaPng, applyDomLayerMask, removeDomLayerMask, DOM_LAYER_MASK_STYLE_ID, } from "./services/screenshotService.js";
 // ── Encoding ───────────────────────────────────────────────────────────────────
-export { buildEncoderArgs, encodeFramesFromDir, buildConcatArgs, concatVideoFiles, encodeFramesChunkedConcat, muxVideoWithAudio, applyFaststart, packageHls, detectGpuEncoder, ENCODER_PRESETS, getEncoderPreset, PRORES_PROFILES, PRORES_PROFILE_NAMES, isProresProfile, appendRateCapArgs, keyframeIntervalToGopSize, HLS_MASTER_PLAYLIST, HLS_VIDEO_PLAYLIST, HLS_AUDIO_PLAYLIST, } from "./services/chunkEncoder.js";
+export { buildEncoderArgs, encodeFramesFromDir, buildConcatArgs, concatVideoFiles, encodeFramesChunkedConcat, muxVideoWithAudio, applyFaststart, packageHls, detectGpuEncoder, getCachedGpuEncoder, ENCODER_PRESETS, getEncoderPreset, PRORES_PROFILES, PRORES_PROFILE_NAMES, isProresProfile, appendRateCapArgs, keyframeIntervalToGopSize, HLS_MASTER_PLAYLIST, HLS_VIDEO_PLAYLIST, HLS_AUDIO_PLAYLIST, } from "./services/chunkEncoder.js";
 export { spawnStreamingEncoder, createFrameReorderBuffer, } from "./services/streamingEncoder.js";
 // ── Media processing ───────────────────────────────────────────────────────────
 export { parseVideoElements, parseImageElements, extractVideoFramesRange, extractAllVideoFrames, isVideoPastTimelineEnd, resolveTimelineExtractionWindow, resolveVideoExtractionWindow, rebaseVideoToWindow, resolveFinalFrameExtractionWindow, resolveFrameFormat, resolveVideoExtractionDuration, resolvePlayableVideoDuration, extractionFrameCountForDuration, resolveProjectRelativeSrc, getFrameAtTime, isVideoHiddenBeforeStreamStart, createFrameLookupTable, FrameLookupTable, analyzeClipMediaFit, classifyVideoExtractionError, isVideoSourceExtractionError, runVideoExtractionWithRetry, safeVideoExtractionSourceIdentity, VideoSourceExtractionError, VIDEO_FRAME_FORMATS, isVideoFrameFormat, EXTRACT_CACHE_MIN_AGE_MS, sdrCanvasColourFilters, } from "./services/videoFrameExtractor.js";
@@ -68,6 +69,7 @@ export { frameFileExtension } from "./services/frameCapture.js";
 export { appendSoftwareEncoderThreadsArg } from "./services/softwareEncoderThreads.js";
 export { frameSequencePath } from "./services/extractedFrameIndex.js";
 export { assertSwiftShader, readWebGlVendorInfo, SwiftShaderAssertionError, BROWSER_GPU_NOT_SOFTWARE, } from "./utils/assertSwiftShader.js";
+export { isBrowserSafePort, listenOnBrowserSafePort, settleOnBrowserSafePort, } from "./utils/browserSafePort.js";
 export { readWebGlVendorInfoFromCanvas } from "./utils/readWebGlVendorInfoFromCanvas.js";
 export { extractMediaMetadata, extractVideoMetadata, extractFinalVideoFrameTimestamp, extractAudioMetadata, declareContentAddressedUrl, declareProbeFactsUrl, PROBE_FACTS_VERSION, buildProbeFactsText, probeMediaProfile, runFfprobe, analyzeKeyframeIntervals, } from "./utils/ffprobe.js";
 export { NOT_MEDIA_PAYLOAD, NotMediaPayloadError, assertMediaPayload, fingerprintElementId, isNotMediaPayload, } from "./utils/notMediaPayload.js";

package/dist/services/aacEncode.js

@@ -57,7 +57,7 @@ function supportsSettsDuration(binary = getFfmpegBinary()) {
     let supported = settsDurationSupport.get(binary);
     if (!supported) {
         supported = new Promise((resolve) => {
-            execFile(binary, ["-hide_banner", "-h", "bsf=setts"], (error, stdout) => {
+            execFile(binary, ["-hide_banner", "-h", "bsf=setts"], { windowsHide: true }, (error, stdout) => {
                 // A binary that cannot even print help fails the encode with its own error, not this one.
                 resolve(error !== null || stdout.includes("duration"));
             });

package/dist/services/chromeHostCeiling.js

@@ -57,8 +57,12 @@ export function shellStarts(binary, timeoutMs = 10_000) {
     if (answer === undefined) {
         const probe = ["--no-sandbox", "--dump-dom", "about:blank"];
         answer =
-            spawnSync(binary, probe, { stdio: "ignore", timeout: timeoutMs, killSignal: "SIGKILL" })
-                ?.status === 0;
+            spawnSync(binary, probe, {
+                stdio: "ignore",
+                timeout: timeoutMs,
+                killSignal: "SIGKILL",
+                windowsHide: true,
+            })?.status === 0;
         if (!answer)
             debug("skipping %s: it did not start", binary);
         starts.set(binary, answer);

package/dist/services/chromeStartup.js

@@ -78,7 +78,14 @@ export async function diagnoseChromeStartup(executablePath, args, options = {})
 }
 /** The launch error, with the startup diagnosis appended; the original stays as `cause`. */
 export async function explainChromeLaunchFailure(error, executablePath, args, signal) {
-    if (!executablePath || !(error instanceof Error))
+    if (!(error instanceof Error))
+        return error;
+    const { code, errno, syscall } = error;
+    if (code === "UNKNOWN" && syscall === "spawn")
+        return new Error(`Windows refused to start the browser${executablePath ? ` at ${executablePath}` : ""} (error ${errno ?? "unknown"}, spawn UNKNOWN). ` +
+            "Security software may be blocking it, or the computer may be out of memory. " +
+            "Close other apps and retry; if it persists, run `hyperframes browser ensure --force` to download it again.", { cause: error });
+    if (!executablePath)
         return error;
     const diagnosis = await diagnoseChromeStartup(executablePath, args ?? [], { signal });
     return new Error(`${error.message}\n${diagnosis}`, { cause: error });

package/dist/services/chunkEncoder.d.ts

@@ -72,7 +72,7 @@ export declare function isProresProfile(value: unknown): value is ProresProfile;
 export declare function getEncoderPreset(quality: "draft" | "standard" | "high", format?: "mp4" | "webm" | "mov", hdr?: {
     transfer: HdrTransfer;
 }, proresProfile?: ProresProfile): EncoderPreset;
-export { detectGpuEncoder, type GpuEncoder } from "../utils/gpuEncoder.js";
+export { detectGpuEncoder, getCachedGpuEncoder, type GpuEncoder } from "../utils/gpuEncoder.js";
 /** The `lockGopForChunkConcat` / `gopSize` pair, shared by every encoder entry point. */
 export interface LockedGopOptions {
     lockGopForChunkConcat?: boolean;

package/dist/services/chunkEncoder.js

@@ -103,7 +103,7 @@ export function getEncoderPreset(quality, format = "mp4", hdr, proresProfile = "
     return { ...base, pixelFormat: "yuv420p" };
 }
 // Re-export GPU utilities so existing consumers that import from chunkEncoder still work.
-export { detectGpuEncoder } from "../utils/gpuEncoder.js";
+export { detectGpuEncoder, getCachedGpuEncoder } from "../utils/gpuEncoder.js";
 /**
  * Integer GOP length, or `null` when no lock was requested. Throws on a lock
  * with an invalid size — a silent fallback ships open-GOP output that only

package/dist/services/drawElementService.d.ts

@@ -71,13 +71,16 @@ export declare function resolveDrawElementCaptureMode(isSwiftShader: boolean, tr
  * captureDrawElementFrame can hide them from paint records and drawImage
  * their live content underneath the drawElementImage output.
  *
- * WebGL contexts additionally get `preserveDrawingBuffer: true` forced —
- * without it the drawing buffer is cleared after each compositor present and
- * drawImage(glCanvas) reads blank.
+ * Register forcePreservedDrawingBuffer first: this wrapper only records.
  *
  * Must be registered via page.evaluateOnNewDocument BEFORE navigation.
  */
 export declare function instrumentAcceleratedCanvases(): void;
+/**
+ * WebGL contexts keep their drawing buffer after a frame is presented, so drawImage(glCanvas) reads the frame
+ * instead of blank. Must be registered via page.evaluateOnNewDocument BEFORE navigation.
+ */
+export declare function forcePreservedDrawingBuffer(): void;
 export interface GpuBackendInfo {
     /** SwiftShader (software rasterizer) — e.g. Docker headless-shell. */
     isSwiftShader: boolean;

package/dist/services/drawElementService.js

@@ -79,9 +79,7 @@ export function resolveDrawElementCaptureMode(isSwiftShader, transparent) {
  * captureDrawElementFrame can hide them from paint records and drawImage
  * their live content underneath the drawElementImage output.
  *
- * WebGL contexts additionally get `preserveDrawingBuffer: true` forced —
- * without it the drawing buffer is cleared after each compositor present and
- * drawImage(glCanvas) reads blank.
+ * Register forcePreservedDrawingBuffer first: this wrapper only records.
  *
  * Must be registered via page.evaluateOnNewDocument BEFORE navigation.
  */
@@ -92,11 +90,9 @@ export function instrumentAcceleratedCanvases() {
     const orig = HTMLCanvasElement.prototype.getContext;
     // oxlint-disable-next-line no-explicit-any
     HTMLCanvasElement.prototype.getContext = function (type, attrs) {
-        const isGl = type === "webgl" || type === "webgl2" || type === "experimental-webgl";
-        const isAccel = isGl || type === "webgpu";
-        const finalAttrs = isGl ? { ...attrs, preserveDrawingBuffer: true } : attrs;
+        const isAccel = type === "webgl" || type === "webgl2" || type === "experimental-webgl" || type === "webgpu";
         // oxlint-disable-next-line no-explicit-any
-        const ctx = orig.call(this, type, finalAttrs);
+        const ctx = orig.call(this, type, attrs);
         if (ctx && isAccel) {
             const list = w.__hf_accel_canvases ?? [];
             if (!list.includes(this))
@@ -117,6 +113,19 @@ export function instrumentAcceleratedCanvases() {
         return ctx;
     };
 }
+/**
+ * WebGL contexts keep their drawing buffer after a frame is presented, so drawImage(glCanvas) reads the frame
+ * instead of blank. Must be registered via page.evaluateOnNewDocument BEFORE navigation.
+ */
+export function forcePreservedDrawingBuffer() {
+    const orig = HTMLCanvasElement.prototype.getContext;
+    // oxlint-disable-next-line no-explicit-any
+    HTMLCanvasElement.prototype.getContext = function (type, attrs) {
+        const isGl = type === "webgl" || type === "webgl2" || type === "experimental-webgl";
+        // oxlint-disable-next-line no-explicit-any
+        return orig.call(this, type, isGl ? { ...attrs, preserveDrawingBuffer: true } : attrs);
+    };
+}
 /**
  * Low-cardinality bucket for a raw WebGL renderer string: `<backend>/<vendor>`
  * (e.g. `metal/apple`, `d3d11/nvidia`, `swiftshader/other`).

package/dist/services/frameCapture.js

@@ -18,7 +18,7 @@ import { describePageMotionBlur, describePageMotionBlurAtEnd, installPageMotionB
 // ── Extracted modules ───────────────────────────────────────────────────────
 import { acquireBrowser, releaseBrowser, forceReleaseBrowser, buildChromeArgs, resolveBrowserGpuMode, captureWithoutWaylandDisplay, resolveHeadlessShellPath, compositionRequiresWebGpu, assertWebGpuAdapterAvailable, usesSoftwareWebGpu, } from "./browserManager.js";
 import { beginFrameCapture, ensureRenderFrameSiblings, getCdpSession, pageContentExceedsCaptureHeight, pageScreenshotCapture, initTransparentBackground, capturesAlpha, shouldDefaultCaptureBeyondViewport, } from "./screenshotService.js";
-import { classifyGpuRenderer, detectGpuBackend, injectDrawElementCanvas, captureDrawElementFrame, resolveDrawElementCaptureMode, instrumentAcceleratedCanvases, initDrawElementWorkerEncode, cleanupDrawElementWorkerEncode, produceDrawElementFrame, produceDrawElementFrameBatch, DE_CANVAS_NOT_INITIALIZED_CODE, } from "./drawElementService.js";
+import { classifyGpuRenderer, detectGpuBackend, injectDrawElementCanvas, captureDrawElementFrame, resolveDrawElementCaptureMode, forcePreservedDrawingBuffer, instrumentAcceleratedCanvases, initDrawElementWorkerEncode, cleanupDrawElementWorkerEncode, produceDrawElementFrame, produceDrawElementFrameBatch, DE_CANVAS_NOT_INITIALIZED_CODE, } from "./drawElementService.js";
 import { initThreeDProjection, scanCssEffects } from "./threeDProjection.js";
 import { planRiskFrames, scanCssEffectLiveFrames, riskSessionFits, withFramesAfterCallback, MAX_RISK_FRAME_FRACTION, } from "./riskFrames.js";
 import { getAvailableMemoryMb } from "./systemMemory.js";
@@ -1006,6 +1006,7 @@ async function constructCaptureSession(input) {
     // composites their live content via drawImage instead (see
     // instrumentAcceleratedCanvases). Must be registered before navigation.
     if (useDrawElement) {
+        await page.evaluateOnNewDocument(forcePreservedDrawingBuffer);
         await page.evaluateOnNewDocument(instrumentAcceleratedCanvases);
     }
     // The opacity → autoAlpha tween rewrite was RETIRED with the requestPaint

package/dist/services/parallelCoordinator.d.ts

@@ -83,6 +83,8 @@ export interface WorkerSizingConfig extends Partial<Pick<EngineConfig, "concurre
      * than a plain DOM screenshot. Explicit --workers requests ignore this hint.
      */
     captureCostMultiplier?: number;
+    /** macOS, hardware GPU, screenshot frames written to disk (not streamed through this process). */
+    appleGpuDiskCapture?: boolean;
 }
 type WorkerBrowserPoolDecision = {
     parallel?: boolean;

package/dist/services/parallelCoordinator.js

@@ -32,6 +32,10 @@ const HEAP_RESERVED_MB = 1024;
 // default heap ⇒ >~500MB/worker + base. Caps auto sizing; an explicit
 // `--workers N` is still the operator's call.
 const HEAP_PER_WORKER_MB = 640;
+// Apple-GPU disk capture measured ~15-25 MB parent heap per worker; 14 cores kept gaining to 8.
+const APPLE_DISK_HEAP_PER_WORKER_MB = 128;
+const APPLE_DISK_CORES_PER_WORKER = 1.75;
+const APPLE_DISK_MAX_WORKERS = 8;
 const MIN_WORKERS = 1;
 const MAX_WORKER_DIAGNOSTIC_LINES = 8;
 // Hard ceiling on explicit `--workers N` requests. Above this, the cost of
@@ -133,7 +137,9 @@ export function computeWorkerSizing(totalFrames, requested, config) {
     // is immediately reclaimable.
     const totalMemoryMb = getSystemTotalMb();
     const heapLimitMb = Math.round(getHeapStatistics().heap_size_limit / (1024 * 1024));
-    const heapBasedWorkers = Math.max(1, Math.floor((heapLimitMb - HEAP_RESERVED_MB) / HEAP_PER_WORKER_MB));
+    const appleDisk = config?.appleGpuDiskCapture === true;
+    const heapBasedWorkers = Math.max(1, Math.floor((heapLimitMb - HEAP_RESERVED_MB) /
+        (appleDisk ? APPLE_DISK_HEAP_PER_WORKER_MB : HEAP_PER_WORKER_MB)));
     const cpuBasedWorkers = Math.max(1, cpuCount - 2);
     const memoryBasedWorkers = Math.max(1, Math.floor((totalMemoryMb * 0.5) / MEMORY_PER_WORKER_MB));
     const frameBasedWorkers = Math.floor(totalFrames / MIN_FRAMES_PER_WORKER);
@@ -164,9 +170,14 @@ export function computeWorkerSizing(totalFrames, requested, config) {
         if (concurrency !== "auto") {
             return Math.max(MIN_WORKERS, Math.min(ABSOLUTE_MAX_WORKERS, Math.floor(concurrency)));
         }
-        return defaultSafeMaxWorkers();
+        return appleDisk
+            ? Math.max(defaultSafeMaxWorkers(), APPLE_DISK_MAX_WORKERS)
+            : defaultSafeMaxWorkers();
     })();
-    const effectiveCoresPerWorker = config?.coresPerWorker ?? DEFAULT_CONFIG.coresPerWorker;
+    const configuredCoresPerWorker = config?.coresPerWorker ?? DEFAULT_CONFIG.coresPerWorker;
+    const effectiveCoresPerWorker = appleDisk && configuredCoresPerWorker === DEFAULT_CONFIG.coresPerWorker
+        ? APPLE_DISK_CORES_PER_WORKER
+        : configuredCoresPerWorker;
     const effectiveMinParallelFrames = config?.minParallelFrames ?? DEFAULT_CONFIG.minParallelFrames;
     const effectiveLargeRenderThreshold = config?.largeRenderThreshold ?? DEFAULT_CONFIG.largeRenderThreshold;
     if (totalFrames < MIN_FRAMES_PER_WORKER * 2) {

package/dist/utils/browserSafePort.d.ts

@@ -0,0 +1,8 @@
+import type { Server } from "node:net";
+export declare const isBrowserSafePort: (port: number) => boolean;
+type Bindable = Pick<Server, "address" | "close" | "listen" | "once" | "off">;
+/** Rebinds an already-listening server until the OS hands it a port a browser will load from. */
+export declare function settleOnBrowserSafePort(server: Bindable, host: string): Promise<number>;
+/** `server.listen(0, host)` that never lands on a port Chromium blocks; resolves to the bound port. */
+export declare function listenOnBrowserSafePort(server: Bindable, host: string): Promise<number>;
+export {};

package/dist/utils/browserSafePort.js

@@ -0,0 +1,38 @@
+// Chromium refuses to load from these ports (net::ERR_UNSAFE_PORT); net/base/port_util.cc kRestrictedPorts.
+const RESTRICTED_PORTS = new Set([
+    1, 7, 9, 11, 13, 15, 17, 19, 20, 21, 22, 23, 25, 37, 42, 43, 53, 69, 77, 79, 87, 95, 101, 102,
+    103, 104, 109, 110, 111, 113, 115, 117, 119, 123, 135, 137, 139, 143, 161, 179, 389, 427, 465,
+    512, 513, 514, 515, 526, 530, 531, 532, 540, 548, 554, 556, 563, 587, 601, 636, 989, 990, 993,
+    995, 1719, 1720, 1723, 2049, 3659, 4045, 5060, 5061, 6000, 6566, 6665, 6666, 6667, 6668, 6669,
+    6697, 10080,
+]);
+const MAX_ATTEMPTS = 32;
+export const isBrowserSafePort = (port) => !RESTRICTED_PORTS.has(port);
+function listenOnce(server, host) {
+    return new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, host, () => {
+            server.off("error", reject);
+            resolve(server.address().port);
+        });
+    });
+}
+function closeServer(server) {
+    return new Promise((resolve) => server.close(() => resolve()));
+}
+/** Rebinds an already-listening server until the OS hands it a port a browser will load from. */
+export async function settleOnBrowserSafePort(server, host) {
+    let port = server.address().port;
+    for (let attempt = 1; !isBrowserSafePort(port); attempt++) {
+        if (attempt >= MAX_ATTEMPTS)
+            throw new Error(`The OS kept offering browser-restricted ports (last: ${port}).`);
+        await closeServer(server);
+        port = await listenOnce(server, host);
+    }
+    return port;
+}
+/** `server.listen(0, host)` that never lands on a port Chromium blocks; resolves to the bound port. */
+export async function listenOnBrowserSafePort(server, host) {
+    await listenOnce(server, host);
+    return settleOnBrowserSafePort(server, host);
+}

package/dist/utils/ffprobe.js

@@ -296,7 +296,10 @@ function ffprobeMajor() {
     runtimeFfprobeMajor ??= new Promise((resolve) => {
         let out = "";
         const binary = getFfprobeBinary();
-        const proc = spawn(binary, ["-version"], { stdio: ["ignore", "pipe", "ignore"] });
+        const proc = spawn(binary, ["-version"], {
+            stdio: ["ignore", "pipe", "ignore"],
+            windowsHide: true,
+        });
         proc.stdout.on("data", (chunk) => (out += String(chunk)));
         proc.on("error", () => resolve(undefined));
         proc.on("close", () => resolve(Number(/version n?(\d+)/.exec(out)?.[1]) || undefined));

package/dist/utils/gpuEncoder.d.ts

@@ -10,6 +10,7 @@ export declare function getCompiledGpuEncoders(ffmpegEncodersStdout: string): Co
 export declare function selectUsableGpuEncoder(candidates: readonly ConcreteGpuEncoder[], isUsable: (encoder: ConcreteGpuEncoder) => Promise<boolean>): Promise<GpuEncoder>;
 export declare function detectGpuEncoder(): Promise<GpuEncoder>;
 export declare function getCachedGpuEncoder(): Promise<GpuEncoder>;
+export declare function resetCachedGpuEncoder(): void;
 export declare function getGpuEncoderName(encoder: GpuEncoder, codec: "h264" | "h265"): string;
 export declare function buildVideoToolboxRateControlArgs(input: {
     bitrate?: string;

package/dist/utils/gpuEncoder.js

@@ -64,12 +64,13 @@ export async function detectGpuEncoder() {
     return selectUsableGpuEncoder(candidates, canUseGpuEncoder).catch(() => null);
 }
 let cachedGpuEncoder = undefined;
-export async function getCachedGpuEncoder() {
-    if (cachedGpuEncoder === undefined) {
-        cachedGpuEncoder = await detectGpuEncoder();
-    }
+export function getCachedGpuEncoder() {
+    cachedGpuEncoder ??= detectGpuEncoder();
     return cachedGpuEncoder;
 }
+export function resetCachedGpuEncoder() {
+    cachedGpuEncoder = undefined;
+}
 export function getGpuEncoderName(encoder, codec) {
     if (!encoder)
         return codec === "h264" ? "libx264" : "libx265";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/engine",
-  "version": "0.8.210",
+  "version": "0.8.212",
   "description": "Seekable web page to video rendering engine (Puppeteer + FFmpeg)",
   "repository": {
     "type": "git",
@@ -52,10 +52,10 @@
     "@hono/node-server": "^2.0.5",
     "hono": "^4.6.0",
     "linkedom": "^0.18.12",
-    "puppeteer": "^25.8.0",
-    "puppeteer-core": "^25.8.0",
-    "@hyperframes/core": "^0.8.210",
-    "@hyperframes/parsers": "^0.8.210"
+    "puppeteer": "~25.11.0",
+    "puppeteer-core": "^25.11.0",
+    "@hyperframes/core": "^0.8.212",
+    "@hyperframes/parsers": "^0.8.212"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",