@hyperframes/engine 0.8.214 → 0.8.216

package/dist/config.d.ts

@@ -92,6 +92,8 @@ export interface EngineConfig {
      * the runtime probe fires). Not intended to be set by callers.
      */
     forceScreenshotExplicitlyOptedOut?: boolean;
+    /** How long a BeginFrame capture may take to draw its first frame before the render retries by screenshot. */
+    beginFrameFirstFrameDeadlineMs?: number;
     /**
      * Low-memory render profile. When `true`, the orchestrator collapses the
      * pipeline to its cheapest shape on memory-constrained hosts: it skips the

package/dist/config.js

@@ -61,6 +61,7 @@ const OPTIONAL_ENGINE_CONFIG_FIELDS = [
     "expectedChromiumMajor",
     "pageSideCompositingAutoDisabled",
     "forceScreenshotExplicitlyOptedOut",
+    "beginFrameFirstFrameDeadlineMs",
     "streamingEncodeAutoDisabledOnWin32Compound",
     "runtimeManifestPath",
     "extractCacheDir",
@@ -148,6 +149,9 @@ function validateEngineConfigScalars(config) {
     if (typeof config.jpegQuality === "number" && config.jpegQuality > 100) {
         throw new Error("Engine config jpegQuality must be <= 100");
     }
+    if (config.beginFrameFirstFrameDeadlineMs !== undefined) {
+        assertEngineConfigNumber(config, "beginFrameFirstFrameDeadlineMs", 1, true);
+    }
 }
 function validateEngineConfigParallelism(config) {
     if (config.concurrency !== "auto" &&

package/dist/index.d.ts

@@ -39,7 +39,7 @@ export { acquireBrowser, setHostHandlesSigint, releaseBrowser, drainBrowserPool,
 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 { createCaptureSession, initializeSession, closeCaptureSession, captureFrame, captureFrameToBuffer, captureFrameToBufferPipelined, captureFramesBatchPipelined, DrawElementVerificationError, isDrawElementVerificationError, getDrawElementVerificationDetails, type DrawElementVerificationDetails, recaptureDrawElementFrameForVerify, completeDeferredDrawElementInit, writeCapturedFrame, discardWarmupCapture, getCompositionDuration, getCompositionLengthSource, type CompositionLengthSource, 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";
@@ -69,7 +69,7 @@ export { isBrowserSafePort, listenOnBrowserSafePort, settleOnBrowserSafePort, }
 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";
-export { assertPublicHttpsUrl, isBlockedNetworkHost, downloadToTemp, fetchPublicHttpsText, isHttpUrl, safeDownloadUrlIdentity, writeUrlDownloadTelemetry, type SafeDownloadUrlIdentity, type UrlDownloadOptions, type UrlDownloadTelemetry, type PublicHttpsTextOptions, } from "./utils/urlDownloader.js";
+export { _setDownloadFetchForTests, assertPublicHttpsUrl, isBlockedNetworkHost, downloadToTemp, fetchPublicHttpsText, isHttpUrl, safeDownloadUrlIdentity, writeUrlDownloadTelemetry, type SafeDownloadUrlIdentity, type UrlDownloadOptions, type UrlDownloadTelemetry, type PublicHttpsTextOptions, } from "./utils/urlDownloader.js";
 export { runFfmpeg, formatFfmpegError, describeFfmpegFailure, isExternalFfmpegInterruption, type RunFfmpegOptions, type RunFfmpegResult, } from "./utils/runFfmpeg.js";
 export { aacSegmentCount, encodeAac } from "./services/aacEncode.js";
 export { ManagedChildProcess, type ManagedChildProcessOptions, type ManagedChildProcessOutcome, type ManagedProcessTerminationReason, } from "./utils/managedChildProcess.js";

package/dist/index.js

@@ -41,7 +41,7 @@ export { augmentProtocolTimeoutError, isProtocolTimeoutError, } from "./services
 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 { createCaptureSession, initializeSession, closeCaptureSession, captureFrame, captureFrameToBuffer, captureFrameToBufferPipelined, captureFramesBatchPipelined, DrawElementVerificationError, isDrawElementVerificationError, getDrawElementVerificationDetails, recaptureDrawElementFrameForVerify, completeDeferredDrawElementInit, writeCapturedFrame, discardWarmupCapture, getCompositionDuration, getCompositionLengthSource, 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";
 // ── Screenshot (BeginFrame) ─────────────────────────────────────────────────────
@@ -73,7 +73,7 @@ export { isBrowserSafePort, listenOnBrowserSafePort, settleOnBrowserSafePort, }
 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";
-export { assertPublicHttpsUrl, isBlockedNetworkHost, downloadToTemp, fetchPublicHttpsText, isHttpUrl, safeDownloadUrlIdentity, writeUrlDownloadTelemetry, } from "./utils/urlDownloader.js";
+export { _setDownloadFetchForTests, assertPublicHttpsUrl, isBlockedNetworkHost, downloadToTemp, fetchPublicHttpsText, isHttpUrl, safeDownloadUrlIdentity, writeUrlDownloadTelemetry, } from "./utils/urlDownloader.js";
 export { runFfmpeg, formatFfmpegError, describeFfmpegFailure, isExternalFfmpegInterruption, } from "./utils/runFfmpeg.js";
 export { aacSegmentCount, encodeAac } from "./services/aacEncode.js";
 export { ManagedChildProcess, } from "./utils/managedChildProcess.js";

package/dist/services/chunkEncoder.js

@@ -22,7 +22,7 @@ import { appendRenderProvenanceArgs } from "../utils/renderProvenance.js";
 export const ENCODER_PRESETS = {
     draft: { preset: "ultrafast", quality: 28, codec: "h264" },
     standard: { preset: "medium", quality: 18, codec: "h264" },
-    high: { preset: "slow", quality: 15, codec: "h264" },
+    high: { preset: "fast", quality: 15, codec: "h264" },
 };
 function appendEncodeTimeoutMessage(error, timedOut, timeoutMs) {
     if (!timedOut)

package/dist/services/frameCapture.d.ts

@@ -14,6 +14,7 @@ import { pageScreenshotCapture } from "./screenshotService.js";
 import { type EngineConfig } from "../config.js";
 import type { CaptureOptions, CaptureVideoMetadataHint, CaptureResult, CaptureBufferResult, CapturePerfSummary, CaptureWarning, SubTimelineWaitMemo, SubTimelineWaitOutcome } from "../types.js";
 import { type ChromeMemorySampler, type ChromePids } from "./chromeMemorySampler.js";
+import type { CompositionLengthSource } from "@hyperframes/core/runtime/composition-length";
 export { isMemoryExhaustionError, isTransientBrowserError } from "./captureFailure.js";
 export type { CaptureOptions, CaptureResult, CaptureBufferResult, CapturePerfSummary };
 /** Called after seeking, before screenshot. Use for video frame injection or other pre-capture work.
@@ -748,6 +749,9 @@ export declare function discardWarmupCapture(session: CaptureSession, frameIndex
 export declare function closeCaptureSession(session: CaptureSession): Promise<void>;
 export declare function prepareCaptureSessionForReuse(session: CaptureSession, outputDir: string, onBeforeCapture: BeforeCaptureHook | null): void;
 export declare function getCompositionDuration(session: CaptureSession): Promise<number>;
+export type { CompositionLengthSource };
+/** Which input set the composition's length, as the runtime published it; null when it did not. */
+export declare function getCompositionLengthSource(session: CaptureSession): Promise<CompositionLengthSource | null>;
 /**
  * Ungated-release safety net, part 1: capture K screenshot ground-truth frames
  * BEFORE the drawElement canvas is injected (the only window where a page

package/dist/services/frameCapture.js

@@ -3956,6 +3956,12 @@ export async function getCompositionDuration(session) {
         return window.__hf?.duration ?? 0;
     });
 }
+/** Which input set the composition's length, as the runtime published it; null when it did not. */
+export async function getCompositionLengthSource(session) {
+    if (!session.isInitialized)
+        throw new Error("[FrameCapture] Session not initialized");
+    return session.page.evaluate(() => window.__hf?.lengthSource ?? null);
+}
 /**
  * Ungated-release safety net, part 1: capture K screenshot ground-truth frames
  * BEFORE the drawElement canvas is injected (the only window where a page

package/dist/services/parallelCoordinator.js

@@ -16,7 +16,7 @@ import { DEFAULT_CONFIG } from "../config.js";
 import { assertSwiftShader } from "../utils/assertSwiftShader.js";
 import { readWebGlVendorInfoFromCanvas } from "../utils/readWebGlVendorInfoFromCanvas.js";
 import { resolveHeadlessShellPath } from "./browserManager.js";
-import { getSystemTotalMb } from "./systemMemory.js";
+import { getCgroupCpuLimit, getSystemTotalMb } from "./systemMemory.js";
 import { CaptureFailure, classifyCaptureFailure, isFatalCaptureFailure, } from "./captureFailure.js";
 // System-memory budget per parallel worker. Each worker is a full Chrome
 // process (SwiftShader compositor + raster threads) plus its share of parent-
@@ -27,11 +27,13 @@ const MEMORY_PER_WORKER_MB = 1536;
 // Parent-process V8 heap the coordinator itself needs regardless of worker
 // count (compile artifacts, puppeteer sessions, encoder state).
 const HEAP_RESERVED_MB = 1024;
-// Parent-process V8 heap consumed per worker (protocol buffers + in-flight
-// frame buffers). Derived from the field OOM: 6 workers exhausted a ~4GB
-// default heap ⇒ >~500MB/worker + base. Caps auto sizing; an explicit
-// `--workers N` is still the operator's call.
-const HEAP_PER_WORKER_MB = 640;
+// Parent heap per worker, by --trace-gc in a 10 GB container (10-28): 21 MB on a short film, 228 MB on a 1080×1920
+// video-heavy one (427 → 1,110 MB from 1 to 4 workers). 320 keeps 1.4× over that; `--workers N` still overrides.
+const HEAP_PER_WORKER_MB = 320;
+// The desktop app keeps the old figure: its 4,192 MB heap is where 5 workers ran out (#5149). A packaged app runs the
+// CLI on its own plain Node, so it is known by the client tag it sets on every CLI call, or by Electron itself.
+const DESKTOP_HEAP_PER_WORKER_MB = 640;
+const inDesktopApp = () => Boolean(process.versions.electron) || /^desktop\//.test(process.env.HYPERFRAMES_CLIENT ?? "");
 // 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;
@@ -139,8 +141,14 @@ export function computeWorkerSizing(totalFrames, requested, config) {
     const heapLimitMb = Math.round(getHeapStatistics().heap_size_limit / (1024 * 1024));
     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);
+        (appleDisk
+            ? APPLE_DISK_HEAP_PER_WORKER_MB
+            : inDesktopApp()
+                ? DESKTOP_HEAP_PER_WORKER_MB
+                : HEAP_PER_WORKER_MB)));
+    // A CPU quota (docker --cpus) bounds workers at its whole CPUs: at 3.5, 3 beat 2 and 4 (johnny, 10-28).
+    const cpuQuota = getCgroupCpuLimit();
+    const cpuBasedWorkers = Math.max(1, cpuQuota === null ? cpuCount - 2 : Math.min(cpuCount - 2, Math.floor(cpuQuota)));
     const memoryBasedWorkers = Math.max(1, Math.floor((totalMemoryMb * 0.5) / MEMORY_PER_WORKER_MB));
     const frameBasedWorkers = Math.floor(totalFrames / MIN_FRAMES_PER_WORKER);
     const captureCostMultiplier = Math.max(1, config?.captureCostMultiplier ?? 1);

package/dist/services/systemMemory.d.ts

@@ -9,8 +9,12 @@
  */
 /** Parse cgroup v2/v1 memory limits from sysfs file contents into MiB. */
 export declare function parseCgroupLimitMb(v2Content: string | null, v1Content: string | null): number | null;
+/** The CPUs a cgroup quota allows (v2 `cpu.max`, else v1 quota over period), or null when it sets none. */
+export declare function parseCgroupCpus(v2Content: string | null, v1Quota: string | null, v1Period: string | null): number | null;
 /** Test-only: reset the cached cgroup memory probe. */
 export declare function _resetCgroupLimitCacheForTests(): void;
+/** The CPUs this process's cgroup may use (docker `--cpus`), or null off Linux or without a quota. */
+export declare function getCgroupCpuLimit(): number | null;
 /**
  * Actual Linux cgroup memory ceiling in MiB, or null when the process is not
  * cgroup-limited. Unlike getSystemTotalMb this never falls back to host RAM.

package/dist/services/systemMemory.js

@@ -23,7 +23,11 @@ const CGROUP_V2_MEMORY_MAX_PATH = "/sys/fs/cgroup/memory.max";
 const CGROUP_V1_MEMORY_LIMIT_PATH = "/sys/fs/cgroup/memory/memory.limit_in_bytes";
 // Kernel no-limit sentinel is page-rounded 2^63-1 (~9223372036854771712); >= 2^60 is implausible as a real limit.
 const CGROUP_V1_NO_LIMIT_CUTOFF_BYTES = 2n ** 60n;
+const CGROUP_V2_CPU_MAX_PATH = "/sys/fs/cgroup/cpu.max";
+const CGROUP_V1_CPU_QUOTA_PATH = "/sys/fs/cgroup/cpu/cpu.cfs_quota_us";
+const CGROUP_V1_CPU_PERIOD_PATH = "/sys/fs/cgroup/cpu/cpu.cfs_period_us";
 let _cachedCgroupLimitMb;
+let _cachedCgroupCpus;
 let _warnedCgroupReadFailure = false;
 /** Parse cgroup v2/v1 memory limits from sysfs file contents into MiB. */
 export function parseCgroupLimitMb(v2Content, v1Content) {
@@ -58,11 +62,39 @@ function parsePositiveByteLimitMb(content, noLimitCutoffBytes) {
     }
     return Number(bytes / BYTES_PER_MIB_BIGINT);
 }
+/** The CPUs a cgroup quota allows (v2 `cpu.max`, else v1 quota over period), or null when it sets none. */
+export function parseCgroupCpus(v2Content, v1Quota, v1Period) {
+    if (v2Content !== null) {
+        const [quota, period] = v2Content.trim().split(/\s+/);
+        return quotaCpus(quota, period);
+    }
+    return quotaCpus(v1Quota?.trim(), v1Period?.trim());
+}
+function quotaCpus(quota, period) {
+    if (!quota || !period || !/^\d+$/.test(quota) || !/^\d+$/.test(period))
+        return null;
+    const [q, p] = [Number(quota), Number(period)];
+    return q > 0 && p > 0 ? q / p : null;
+}
 /** Test-only: reset the cached cgroup memory probe. */
 export function _resetCgroupLimitCacheForTests() {
     _cachedCgroupLimitMb = undefined;
+    _cachedCgroupCpus = undefined;
     _warnedCgroupReadFailure = false;
 }
+/** The CPUs this process's cgroup may use (docker `--cpus`), or null off Linux or without a quota. */
+export function getCgroupCpuLimit() {
+    if (_cachedCgroupCpus !== undefined)
+        return _cachedCgroupCpus;
+    if (process.platform !== "linux")
+        return (_cachedCgroupCpus = null);
+    const v2 = readCgroupFile(CGROUP_V2_CPU_MAX_PATH);
+    _cachedCgroupCpus =
+        v2 !== null
+            ? parseCgroupCpus(v2, null, null)
+            : parseCgroupCpus(null, readCgroupFile(CGROUP_V1_CPU_QUOTA_PATH), readCgroupFile(CGROUP_V1_CPU_PERIOD_PATH));
+    return _cachedCgroupCpus;
+}
 /**
  * Actual Linux cgroup memory ceiling in MiB, or null when the process is not
  * cgroup-limited. Unlike getSystemTotalMb this never falls back to host RAM.

package/dist/services/videoFrameInjector.js

@@ -270,7 +270,13 @@ export async function measureVideoShownBoxes(page, videoIds, times) {
         const fullSize = new Set();
         const gradedThroughGroup = (video) => {
             const groupId = video.getAttribute(groupAttr);
-            const group = groupId ? document.getElementById(groupId) : null;
+            if (!groupId)
+                return false;
+            // the member's own composition first: ids are unique only per composition file
+            const scope = video.closest("[data-composition-id]");
+            const group = (scope &&
+                Array.from(scope.getElementsByTagName(groupTag)).find((g) => g.id === groupId)) ||
+                document.getElementById(groupId);
             return group?.localName === groupTag && group.hasAttribute(gradingAttr);
         };
         const keepsFullSize = (video) => {

package/dist/types.d.ts

@@ -6,6 +6,7 @@
  */
 import type { AudioFailureDiagnostic } from "./services/audioMixer.types.js";
 import type { Fps } from "@hyperframes/core";
+import type { CompositionLengthSource } from "@hyperframes/core/runtime/composition-length";
 import type { ChromeMemoryStats } from "./services/chromeMemorySampler.js";
 import type { MotionBlurOptions } from "./services/motionBlur.js";
 export type PageMotionBlurOff = "off" | "hdr-render" | "layered-composite" | "distributed-render";
@@ -114,6 +115,8 @@ export interface HfSeekOptions {
 export interface HfProtocol {
     /** Total duration of the composition in seconds */
     duration: number;
+    /** Which input set `duration`. */
+    lengthSource?: CompositionLengthSource;
     /** Seek to a specific time. Must produce deterministic visual output. */
     seek(time: number, options?: HfSeekOptions): void;
     /** Optional: media elements the engine should handle */

package/dist/utils/renderProvenance.js

@@ -1,4 +1,5 @@
 import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { readTagCI } from "./ffprobe.js";
@@ -91,9 +92,26 @@ export function resolveOwnVersionFrom(startDir) {
             break;
         dir = parent;
     }
+    // An app that bundles the engine into its own dist has no package of ours above the bundle; the
+    // @hyperframes/engine installed beside it is the one it was built from.
+    const installed = installedEngineVersion(startDir);
+    if (installed)
+        return installed;
     reportUnresolved(`no package.json matching ${OWN_PACKAGE_NAME} within ${MAX_WALK_DEPTH} levels`);
     return UNRESOLVED_VERSION;
 }
+function installedEngineVersion(fromDir) {
+    try {
+        const path = createRequire(join(fromDir, "index.js")).resolve("@hyperframes/engine/package.json");
+        const pkg = JSON.parse(readFileSync(path, "utf8"));
+        if (pkg.name === "@hyperframes/engine" && typeof pkg.version === "string" && pkg.version)
+            return pkg.version;
+    }
+    catch {
+        // Not installed beside us: the caller reports it.
+    }
+    return undefined;
+}
 /**
  * Make the failure audible. The point of this change is that a resolution
  * failure stops being indistinguishable from data - a silent fallback is what

package/dist/utils/urlDownloader.d.ts

@@ -54,7 +54,11 @@ export declare function isBlockedNetworkHost(hostname: string): boolean;
  * address range (SSRF guard).
  */
 export declare function assertPublicHttpsUrl(url: string): void;
+type DownloadFetch = (url: string, init: RequestInit) => Promise<Response>;
+/** Test seam: replaces the transport every download goes through; no argument restores it. */
+export declare function _setDownloadFetchForTests(replacement?: DownloadFetch): void;
 /** Fetch bounded UTF-8 text while applying the downloader's redirect and SSRF policy to every hop. */
 export declare function fetchPublicHttpsText(url: string, options: PublicHttpsTextOptions): Promise<string>;
 export declare function downloadToTemp(url: string, destDir: string, timeoutMs?: number, signal?: AbortSignal, onTransientRetry?: (error: UrlDownloadError) => void, options?: UrlDownloadOptions): Promise<string>;
 export declare function isHttpUrl(path: string): boolean;
+export {};

package/dist/utils/urlDownloader.js

@@ -1,5 +1,7 @@
 import { closeSync, createReadStream, createWriteStream, existsSync, fsyncSync, linkSync, mkdtempSync, mkdirSync, lstatSync, openSync, readdirSync, rmdirSync, rmSync, statSync, unlinkSync, } from "fs";
 import { createHash, randomUUID } from "crypto";
+import dns from "node:dns";
+import { fetchGoesThroughEnvProxy } from "@hyperframes/core/env-proxy";
 import { BlockList, isIP } from "node:net";
 import { dirname, extname, join } from "path";
 import { Readable, Transform } from "stream";
@@ -360,6 +362,49 @@ async function acquireCachePathLock(localPath, timeoutMs, signal) {
 }
 const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
 const MAX_REDIRECTS = 5;
+const NON_PUBLIC_ADDRESS_CODE = "HF_NON_PUBLIC_ADDRESS";
+/** Resolves a host and refuses to connect when any answer is a non-public address. */
+const publicOnlyLookup = (hostname, options, callback) => {
+    dns.lookup(hostname, { ...options, all: true }, (error, answers) => {
+        if (error)
+            return callback(error, "", 0);
+        if (answers.length === 0 ||
+            answers.some((a) => isBlockedNetworkHost(a.address.split("%")[0]))) {
+            const refused = Object.assign(new Error("host resolves to a non-public address"), {
+                code: NON_PUBLIC_ADDRESS_CODE,
+            });
+            return callback(refused, "", 0);
+        }
+        if (options.all)
+            return callback(null, answers);
+        return callback(null, answers[0].address, answers[0].family);
+    });
+};
+let undiciTransport;
+const fetchPublic = async (url, init) => {
+    // Behind an env proxy the proxy resolves the name; the URL and redirect checks are the guard then.
+    if (fetchGoesThroughEnvProxy())
+        return fetch(url, init);
+    undiciTransport ??= import("undici").then(({ Agent, fetch: undiciFetch }) => {
+        const dispatcher = new Agent({ connect: { lookup: publicOnlyLookup } });
+        return (target, options) => undiciFetch(target, { ...options, dispatcher });
+    });
+    return (await undiciTransport)(url, init);
+};
+let downloadFetch = fetchPublic;
+/** Test seam: replaces the transport every download goes through; no argument restores it. */
+export function _setDownloadFetchForTests(replacement) {
+    downloadFetch = replacement ?? fetchPublic;
+}
+function refusedNonPublicAddress(error) {
+    for (let depth = 0; error && depth < 4; depth += 1) {
+        if (typeof error === "object" && "code" in error && error.code === NON_PUBLIC_ADDRESS_CODE) {
+            return true;
+        }
+        error = typeof error === "object" && "cause" in error ? error.cause : undefined;
+    }
+    return false;
+}
 function assertAllowedDownloadUrl(url, redirect) {
     try {
         assertPublicHttpsUrl(url);
@@ -398,10 +443,16 @@ async function fetchWithValidatedRedirects(initialUrl, controller) {
         // lgtm[js/file-access-to-http] — every redirect hop is fetched manually
         // only after the HTTPS/private-host guard above; automatic redirect
         // following is disabled so an allowed host cannot bounce into IMDS.
-        const response = await fetch(currentUrl, {
+        const response = await downloadFetch(currentUrl, {
             signal: controller.signal,
             redirect: "manual",
             headers: { "accept-encoding": "identity" },
+        }).catch((error) => {
+            if (!refusedNonPublicAddress(error))
+                throw error;
+            throw new UrlDownloadError("http_rejected", false, redirects > 0
+                ? "Download redirect target is not permitted"
+                : "Download URL is not permitted");
         });
         if (!REDIRECT_STATUSES.has(response.status))
             return { response, finalUrl: currentUrl };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/engine",
-  "version": "0.8.214",
+  "version": "0.8.216",
   "description": "Seekable web page to video rendering engine (Puppeteer + FFmpeg)",
   "repository": {
     "type": "git",
@@ -54,8 +54,9 @@
     "linkedom": "^0.18.12",
     "puppeteer": "~25.11.0",
     "puppeteer-core": "^25.11.0",
-    "@hyperframes/parsers": "^0.8.214",
-    "@hyperframes/core": "^0.8.214"
+    "undici": "7.25.0",
+    "@hyperframes/core": "^0.8.216",
+    "@hyperframes/parsers": "^0.8.216"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",