@hyperframes/engine 0.8.189 → 0.8.191

package/dist/services/audioMixer.d.ts

@@ -37,5 +37,6 @@ export declare function processCompositionAudio(elements: AudioElement[], baseDi
     /** Serialised master bus chain, from `parseMasterFxChain`. */
     masterFxChain?: string;
     urlByAbsentLocalPath?: ReadonlyMap<string, string>;
+    audioSidecarUrlByLocalPath?: ReadonlyMap<string, string>;
     keepEncoderInputAt?: string;
 }, compiledDir?: string): Promise<MixResult>;

package/dist/services/audioMixer.js

@@ -11,6 +11,8 @@ import { clampFadesToDuration, readElementFades } from "@hyperframes/core/audio-
 import { downloadToTemp, isHttpUrl, UrlDownloadError, writeUrlDownloadTelemetry, } from "../utils/urlDownloader.js";
 import { DEFAULT_CONFIG } from "../config.js";
 import { describeFfmpegFailure, runFfmpeg } from "../utils/runFfmpeg.js";
+import { cpus } from "node:os";
+import { createConcurrencyLimit } from "../utils/concurrencyLimit.js";
 import { encodeAac } from "./aacEncode.js";
 import { audioSubprocessEvidence } from "./audioFailureDiagnostic.js";
 import { unwrapTemplate } from "../utils/htmlTemplate.js";
@@ -129,6 +131,8 @@ function legacyFilterScriptOptionIsUnsupported(stderr) {
  * no audio). 32 segments keeps a wide safety margin and is far more resolution
  * than a piecewise-linear volume envelope needs.
  */
+// Caps the ffmpeg runs that prepare clips; all of a long mix's clips at once starved the host (200 clips, 200 ffmpeg).
+const inPrepareSlot = createConcurrencyLimit(Math.max(2, Math.floor(cpus().length / 2)));
 const MAX_VOLUME_SEGMENTS = 32;
 /**
  * Volume delta below which a keyframe is collinear enough to drop. Kept tight
@@ -499,9 +503,10 @@ export function parseAudioElements(html) {
     return elements;
 }
 const FAIL_ON_READ_ERROR_INSTEAD_OF_ENDING_THERE = ["-xerror"];
+const SIDECAR_WARM_UP_SECONDS = 1;
 /** Decode `duration` s of audio from `mediaStart` in Chrome's media time. Until every stream has
  * started, an input seek snaps audio to the video's first keyframe, so read by timestamp instead. */
-async function extractAudioSegment(srcPath, outputPath, stage, mediaStart, duration, playbackRate = 1, signal, config) {
+async function extractAudioSegment(srcPath, outputPath, stage, mediaStart, duration, playbackRate = 1, signal, config, audioSidecarUrl) {
     const ffmpegProcessTimeout = config?.ffmpegProcessTimeout ?? DEFAULT_CONFIG.ffmpegProcessTimeout;
     const outputDir = dirname(outputPath);
     if (!existsSync(outputDir))
@@ -523,13 +528,18 @@ async function extractAudioSegment(srcPath, outputPath, stage, mediaStart, durat
     const timestampTrim = inputSeek
         ? null
         : `atrim=start=${start}:end=${formatFilterNumber(mediaStart + sourceDuration)},asetpts=PTS-${start}/TB,aresample=async=1:first_pts=0`;
-    const outputArgs = preparedAudioOutputArgs(metadata, normalizedPlaybackRate, duration, timestampTrim);
+    const fromSidecar = audioSidecarUrl !== undefined && inputSeek && normalizedPlaybackRate === 1;
+    const warmUp = fromSidecar ? Math.min(SIDECAR_WARM_UP_SECONDS, mediaStart) : 0;
+    const outputArgs = preparedAudioOutputArgs(metadata, normalizedPlaybackRate, duration, warmUp > 0 ? `atrim=start=${warmUp},asetpts=PTS-STARTPTS` : timestampTrim);
+    const readFrom = fromSidecar ? audioSidecarUrl : srcPath;
     const args = [
         ...(readsUrl ? FAIL_ON_READ_ERROR_INSTEAD_OF_ENDING_THERE : []),
-        ...urlInputArgs(srcPath),
-        ...(inputSeek ? ["-ss", String(mediaStart), "-t", String(sourceDuration)] : []),
+        ...urlInputArgs(readFrom),
+        ...(inputSeek
+            ? ["-ss", String(mediaStart - warmUp), "-t", String(sourceDuration + warmUp)]
+            : []),
         "-i",
-        srcPath,
+        readFrom,
     ];
     args.push("-vn", "-acodec", "pcm_s16le", "-ar", "48000", ...outputArgs);
     if (normalizedPlaybackRate !== 1)
@@ -1043,7 +1053,7 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
         else
             signal.addEventListener("abort", () => internalController.abort(), { once: true });
     }
-    await Promise.all(elements.map(async (element, index) => {
+    await Promise.all(elements.map((element, index) => inPrepareSlot(async () => {
         if (effectiveSignal.aborted) {
             failures.push({
                 stage: "cancelled",
@@ -1058,11 +1068,13 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
         try {
             let srcPath = element.src;
             let readInPlace = false;
+            let audioSidecarUrl;
             if (!isHttpUrl(srcPath)) {
                 // Same browser-URL path semantics as videos.
                 srcPath = resolveProjectRelativeSrc(element.src, baseDir, compiledDir);
                 const remoteUrl = config?.urlByAbsentLocalPath?.get(srcPath);
                 if (remoteUrl) {
+                    audioSidecarUrl = config?.audioSidecarUrlByLocalPath?.get(srcPath);
                     srcPath = remoteUrl;
                     readInPlace = true;
                 }
@@ -1089,12 +1101,7 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
                 });
                 return;
             }
-            // STUDIO-5433: an audio src that resolved to a text document (an
-            // unresolved nested-composition preview URL, or a 403/404 body served
-            // with a 200) never reaches the probe below when the element carries an
-            // authored duration or `loop`. It then fails inside ffmpeg as
-            // `prepare/ffmpeg_failed` with owner "system" — an authoring bug paged
-            // as a platform fault, after every frame has already been captured.
+            // A src that resolved to a text document is an authoring error, not an ffmpeg failure.
             if (await isNotMediaPayload(srcPath)) {
                 failures.push({
                     stage: "source",
@@ -1118,12 +1125,13 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
                 }
                 const effectiveDuration = timeAtSourceTime(normalizeRateSpec(element.playbackRate), metadata.durationSeconds - element.mediaStart);
                 element.end =
-                    element.start + (effectiveDuration > 0 ? effectiveDuration : metadata.durationSeconds);
+                    element.start +
+                        (effectiveDuration > 0 ? effectiveDuration : metadata.durationSeconds);
             }
             let audioSrcPath = srcPath;
             if (element.type === "video") {
                 const extractedPath = join(workDir, `${element.id}-extracted.wav`);
-                const extractResult = await extractAudioSegment(srcPath, extractedPath, "extract", element.mediaStart, element.end - element.start, element.playbackRate, effectiveSignal, config);
+                const extractResult = await extractAudioSegment(srcPath, extractedPath, "extract", element.mediaStart, element.end - element.start, element.playbackRate, effectiveSignal, config, audioSidecarUrl);
                 if (!extractResult.success) {
                     failures.push(extractResult.failure
                         ? { ...extractResult.failure, elementId: element.id }
@@ -1157,24 +1165,14 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
                 }
                 audioSrcPath = trimmedPath;
             }
-            // Apply the track's FX chain to the dry, trimmed audio, before volume
-            // automation is baked in: effects should see the raw signal, and the
-            // envelope belongs on their output. A missing or broken chain is fatal
-            // for the whole mix rather than a per-track warning — quietly rendering
-            // the dry signal ships a mix that sounds plausible and is wrong.
+            // The FX chain runs on the dry trimmed audio, before the envelope. A broken chain fails the mix.
             const chain = element.fxChain ? parseAudioFxChain(element.fxChain) : undefined;
             const automation = element.automation
                 ? resolveAutomation(parseAutomation(element.automation), chain)
                 : null;
-            // Computed before the chain runs, not after: the FX pass bakes the
-            // envelope into its float output so the duck lands before the ±1 clamp
-            // in writeWav, instead of after it.
-            //
-            // A volume lane supersedes keyframes probed from the timeline: the two
-            // would fight, and the lane is the explicit one. `lint` warns when a
-            // track carries both.
-            //
-            // With clip gain ahead of the chain, the lane carries its share of the capped product.
+            // Computed before the chain so the FX pass bakes the envelope in ahead of the ±1 clamp.
+            // A volume lane supersedes probed keyframes. With clip gain ahead of the chain, the lane
+            // carries its share of the capped product.
             const gainBeforeFx = chain !== undefined && enabledAudioFxNodes(chain).length > 0;
             const laneKeyframes = automation
                 ? volumeLaneKeyframes(automation, element.start, element.end - element.start, element.volume ?? 1, gainBeforeFx)
@@ -1191,11 +1189,7 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
             let bakedEnvelope = false;
             let tailSeconds = 0;
             if (chain) {
-                // The chain is serialised into the attribute, the same way colour
-                // grading carries its config, so there is no side-car file to find,
-                // resolve or lose.
-                // The rendered WAV is longer than the input by exactly this much, so
-                // the mix has to be told to let it through.
+                // The rendered WAV is longer than the input by the chain's tail; the mix lets it through.
                 tailSeconds = chainTailSeconds(chain, automation ?? undefined);
                 const fxResult = await applyAudioFxChain(audioSrcPath, chain, join(workDir, `${element.id}-fx.wav`), {
                     trackId: element.id,
@@ -1207,11 +1201,7 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
                 audioSrcPath = fxResult.path;
                 bakedEnvelope = fxResult.envelopeBaked;
             }
-            // Primary volume-automation path for a track the FX pass did not bake:
-            // multiply the envelope into the PCM samples (sample-accurate, no
-            // keyframe ceiling). If the WAV isn't the expected 16-bit PCM, fall
-            // back to the ffmpeg expression path by leaving the keyframes on the
-            // track for buildVolumeExpression to handle.
+            // Bake the envelope into the PCM samples; a non-16-bit WAV falls back to the ffmpeg expression.
             if (envelope && !bakedEnvelope) {
                 bakedEnvelope = applyVolumeEnvelopeToWav(audioSrcPath, envelope.keyframes, envelope.trackStart, envelope.baseVolume);
             }
@@ -1247,7 +1237,7 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
                 detail: boundedDetail(`Audio processing failed for element ${element.id}: ${err instanceof Error ? err.message : String(err)}`),
             });
         }
-    })).catch((err) => {
+    }, effectiveSignal))).catch((err) => {
         // Promise.all rejected on the first fatal failure without waiting for its
         // siblings; abort them so their ffmpeg stops before workDir disappears.
         internalController.abort();

package/dist/services/browserManager.js

@@ -244,7 +244,6 @@ const BEGINFRAME_ONLY_FLAGS = new Set([
 function stripBeginFrameFlags(args) {
     return args.filter((a) => !BEGINFRAME_ONLY_FLAGS.has(a));
 }
-const BEGINFRAME_SCREENSHOT_PROBE_ATTEMPTS = 10;
 const BEGINFRAME_PROBE_TIMEOUT_MS = 2000;
 const BEGINFRAME_PROBE_CLEANUP_TIMEOUT_MS = 250;
 async function awaitBeforeDeadline(operation, deadline, label) {
@@ -325,7 +324,8 @@ async function probeBeginFrameSupport(browser, timeoutMs = BEGINFRAME_PROBE_TIME
         let bytes = Buffer.alloc(0);
         let isPng = false;
         let attempts = 0;
-        for (attempts = 1; attempts <= BEGINFRAME_SCREENSHOT_PROBE_ATTEMPTS; attempts += 1) {
+        while (!isPng && Date.now() < deadline) {
+            attempts += 1;
             const response = await awaitBeforeDeadline(client.send("HeadlessExperimental.beginFrame", {
                 frameTimeTicks: 1000 + (attempts - 1) * 33,
                 interval: 33,
@@ -339,13 +339,13 @@ async function probeBeginFrameSupport(browser, timeoutMs = BEGINFRAME_PROBE_TIME
                     bytes[1] === 0x50 &&
                     bytes[2] === 0x4e &&
                     bytes[3] === 0x47;
-            if (isPng)
+            if (isPng || Date.now() + 10 >= deadline)
                 break;
             await awaitBeforeDeadline(new Promise((resolveDelay) => setTimeout(resolveDelay, 10)), deadline, `screenshot retry delay ${attempts}`);
         }
         if (!isPng) {
             throw new Error(`beginFrame screenshot returned ${bytes.length} bytes after ` +
-                `${BEGINFRAME_SCREENSHOT_PROBE_ATTEMPTS} attempts with signature ` +
+                `${attempts} attempts in ${Date.now() - started}ms with signature ` +
                 `${bytes.length >= 4 ? bytes.subarray(0, 4).toString("hex") : "<empty>"}`);
         }
         await awaitBeforeDeadline(client.detach(), deadline, "CDP detach").catch(() => { });

package/dist/services/drawElementService.js

@@ -934,6 +934,7 @@ export async function produceDrawElementFrameBatch(page, times, width, height, q
             try {
                 if (aw.__hf && typeof aw.__hf.seek === "function")
                     aw.__hf.seek(t);
+                await aw.__hfWaitForSeekCompletion?.();
                 await aw.__hfDecodeDynamicCssBackgroundImages?.();
                 aw.__hf3d?.update();
                 const accel = (aw.__hf_accel_canvases ?? []).filter((c) => root.contains(c));

package/dist/services/frameCapture.d.ts

@@ -98,6 +98,7 @@ export interface CaptureSession {
      * our console output.
      */
     pendingTimelineIds?: string[];
+    isolatedCompositions?: IsolatedComposition[];
     /** The render's shared memo when the caller passed one, else this session's own. */
     subTimelineWaitMemo: SubTimelineWaitMemo;
     /** Structured readiness warnings surfaced to the producer's render policy. */
@@ -164,6 +165,12 @@ export interface CaptureSession {
      * drawElement intermittently returns an anomalously small (blank) frame with no
      * throw; a frame far below the running median is re-captured via screenshot. */
     deFrameSizes?: number[];
+    /** Absolute floor of the serial drawElement size guard. Starts at 20000 bytes and drops to
+     * half of a small frame that redraws byte-identically. */
+    deAbsFloor?: number;
+    /** The last small drawElement frame that redrew byte-identically; an equal frame is kept
+     * without a redraw. */
+    deAcceptedSmall?: Buffer;
     /** Last non-deduped encode result, reused for a static frame on the drawElement
      * worker-encode path (mirrors `lastFrameBuffer` on the screenshot path). Only set
      * when static-frame dedup is armed on the drawElement path. */
@@ -404,16 +411,25 @@ export interface HfDiagnostic {
 }
 export declare function buildZeroDurationDiagnostic(diag: HfDiagnostic): string;
 export declare function pollHfReady(page: Page, timeoutMs: number, intervalMs?: number): Promise<void>;
-export declare function waitForSubCompositionTimelines(session: CaptureSession, page: Page, timeoutMs: number): Promise<void>;
+export declare function waitForSubCompositionTimelines(session: CaptureSession, page: Page, timeoutMs: number, options?: {
+    scriptErrorGraceMs?: number;
+}): Promise<void>;
+export interface IsolatedComposition {
+    compositionId: string;
+    elementId: string | null;
+}
 export interface SubTimelinePollOptions {
     intervalMs?: number;
     getScriptLoadFailures?: () => readonly string[];
     scriptFailureGraceMs?: number;
+    getPageErrors?: () => readonly string[];
+    scriptErrorGraceMs?: number;
     onPending?: (ids: readonly string[]) => void;
     shouldStop?: () => boolean;
     knownUnregisteredIds?: readonly string[];
 }
-export declare function pollSubCompositionTimelines(page: Page, timeoutMs: number, { intervalMs, getScriptLoadFailures, scriptFailureGraceMs, onPending, shouldStop, knownUnregisteredIds, }?: SubTimelinePollOptions): Promise<SubTimelineWaitOutcome>;
+export declare function pollSubCompositionTimelines(page: Page, timeoutMs: number, { intervalMs, getScriptLoadFailures, scriptFailureGraceMs, getPageErrors, scriptErrorGraceMs, onPending, shouldStop, knownUnregisteredIds, }?: SubTimelinePollOptions): Promise<SubTimelineWaitOutcome>;
+export declare function pollVideosReady(page: Page, skipIds: readonly string[], timeoutMs: number, intervalMs?: number): Promise<boolean>;
 /** @internal exported for unit testing only */
 export declare function pollImagesReady(page: Page, timeoutMs: number, intervalMs?: number): Promise<boolean>;
 export declare function waitForImagesReady(page: Page, timeoutMs: number, onUnloaded: (sources: string) => void): Promise<boolean>;

package/dist/services/frameCapture.js

@@ -9,7 +9,8 @@
  */
 import { existsSync, mkdirSync, writeFileSync } from "fs";
 import { join } from "path";
-import { COMPOSITION_SOURCE_URL, quantizeSeekTime, quantizeTimeToFrame, fpsToNumber, resolveAuthoredTimingWindow, } from "@hyperframes/core";
+import { COMPOSITION_SOURCE_URL, MEDIA_RENDER_ID_ATTR, quantizeSeekTime, quantizeTimeToFrame, fpsToNumber, resolveAuthoredTimingWindow, } from "@hyperframes/core";
+import { holdRenderFrameVideos } from "./renderFrameVideoHold.js";
 import { DrawElementCaptureError } from "./drawElementCaptureError.js";
 import { encodePng } from "../utils/alphaBlit.js";
 import { DEFAULT_SAMPLES_PER_FRAME, MotionBlurAccumulator, SPATIAL_TWEEN_PROPERTIES, adaptiveSampleCount, motionBlurProbeTimes, motionBlurSampleTimes, motionBlurWindowIsStatic, probeDiffMagnitude, resolveMotionBlurPlan, } from "./motionBlur.js";
@@ -902,6 +903,9 @@ async function constructCaptureSession(input) {
     // Media elements are addressed by a document-unique render id, not by the
     // per-file element id. Install the resolvers before any page script runs.
     await installMediaRenderIdBridge(page);
+    if (options.skipReadinessVideoIds?.length) {
+        await page.evaluateOnNewDocument(holdRenderFrameVideos, options.skipReadinessVideoIds, MEDIA_RENDER_ID_ATTR);
+    }
     // Fast capture: record accelerated canvases (webgl/webgl2/webgpu) and force
     // preserveDrawingBuffer before any page script can create a context — their
     // paint records freeze at the first frame, so captureDrawElementFrame
@@ -1198,16 +1202,61 @@ async function listUnregisteredTimelineIds(page) {
     // Builds a warning, so it must never throw: normalise a loosely typed result.
     return Array.isArray(evaluated) ? evaluated.map((id) => String(id)) : [];
 }
-export async function waitForSubCompositionTimelines(session, page, timeoutMs) {
+function isScriptFailure(session) {
+    const outcome = session.subTimelineWaitOutcome;
+    return outcome === "script_failure" || (outcome === "timeout" && session.pageErrors.length > 0);
+}
+/** A nested composition whose script threw gets an empty timeline, but only while another nested timeline is live. */
+async function isolateUnregisteredCompositions(page) {
+    const isolated = await page.evaluate(`(function() {
+    var timelines = (window.__timelines = window.__timelines || {});
+    var out = [];
+    if (!window.gsap) return out;
+    var broken = [];
+    var live = 0;
+    var hosts = document.querySelectorAll("[data-composition-id]");
+    for (var i = 0; i < hosts.length; i++) {
+      var host = hosts[i];
+      var id = host.getAttribute("data-composition-id");
+      if (!id || host.hasAttribute("data-no-timeline")) continue;
+      var isRoot = !host.parentElement || !host.parentElement.closest("[data-composition-id]");
+      if (timelines[id]) {
+        if (!isRoot) live++;
+      } else if (isRoot) {
+        return out;
+      } else {
+        broken.push(host);
+      }
+    }
+    if (live === 0) return out;
+    broken.forEach(function(host) {
+      var tl = window.gsap.timeline({ paused: true });
+      var duration = parseFloat(host.getAttribute("data-duration"));
+      if (duration > 0) tl.set({}, {}, duration);
+      var id = host.getAttribute("data-composition-id");
+      timelines[id] = tl;
+      out.push({ compositionId: id, elementId: host.id || host.getAttribute("data-hf-id") || null });
+    });
+    if (out.length && typeof window.__hfForceTimelineRebind === "function") window.__hfForceTimelineRebind();
+    return out;
+  })()`);
+    return Array.isArray(isolated) ? isolated : [];
+}
+export async function waitForSubCompositionTimelines(session, page, timeoutMs, options = {}) {
     const memo = session.subTimelineWaitMemo;
     session.subTimelineWaitOutcome = await pollSubCompositionTimelines(page, timeoutMs, {
         getScriptLoadFailures: () => session.scriptLoadFailures,
+        getPageErrors: () => session.pageErrors,
+        scriptErrorGraceMs: options.scriptErrorGraceMs,
         onPending: (ids) => {
             session.pendingTimelineIds = [...ids];
         },
         shouldStop: () => session.vfxFailure !== undefined,
         knownUnregisteredIds: memo.unregisteredIds,
     });
+    if (isScriptFailure(session) && session.scriptLoadFailures.length === 0) {
+        session.isolatedCompositions = await isolateUnregisteredCompositions(page);
+    }
     // Only a clean full-length timeout is replayed: a VFX stop ends early, and page or script
     // errors must reach each session so it can still classify the wait as a script failure.
     const cleanTimeout = session.subTimelineWaitOutcome === "timeout" &&
@@ -1218,7 +1267,7 @@ export async function waitForSubCompositionTimelines(session, page, timeoutMs) {
         memo.unregisteredIds = session.pendingTimelineIds ?? [];
     }
 }
-export async function pollSubCompositionTimelines(page, timeoutMs, { intervalMs = 150, getScriptLoadFailures, scriptFailureGraceMs = 2_000, onPending, shouldStop, knownUnregisteredIds = [], } = {}) {
+export async function pollSubCompositionTimelines(page, timeoutMs, { intervalMs = 150, getScriptLoadFailures, scriptFailureGraceMs = 2_000, getPageErrors, scriptErrorGraceMs = 5_000, onPending, shouldStop, knownUnregisteredIds = [], } = {}) {
     // Hosts may opt out of the timeline wait with `data-no-timeline` —
     // compositions driven purely by CSS animations / rAF (the render-compat
     // contract) never register window.__timelines[id], and without the opt-out
@@ -1240,6 +1289,8 @@ export async function pollSubCompositionTimelines(page, timeoutMs, { intervalMs
     const deadline = start + timeoutMs;
     let ready = false;
     let scriptFailureBail = false;
+    // A page error is given its grace from when it first appeared, not from when the poll began.
+    let errorSeenAt;
     for (;;) {
         ready = Boolean(await page.evaluate(expression));
         if (ready || shouldStop?.())
@@ -1248,12 +1299,18 @@ export async function pollSubCompositionTimelines(page, timeoutMs, { intervalMs
         if (now >= deadline)
             break;
         const failures = getScriptLoadFailures?.() ?? [];
-        if (failures.length > 0 && now - start >= scriptFailureGraceMs) {
+        const errors = getPageErrors?.() ?? [];
+        const failed = failures.length > 0 ? failures : errors;
+        const graceMs = failures.length > 0 ? scriptFailureGraceMs : scriptErrorGraceMs;
+        if (failed.length > 0)
+            errorSeenAt ??= now;
+        const sinceFailure = failures.length > 0 ? now - start : now - (errorSeenAt ?? now);
+        if (failed.length > 0 && sinceFailure >= graceMs) {
             scriptFailureBail = true;
             console.warn(`[FrameCapture] Sub-composition timeline wait cut short after ${now - start}ms: ` +
-                `script resource(s) failed to load (${failures.join(", ")}), so ` +
+                `script(s) failed (${failed.join(", ")}), so ` +
                 `the timeline registration they carry can never arrive. ` +
-                `Fix the script reference; the render proceeds without those animations.`);
+                `Fix the script.`);
             break;
         }
         await new Promise((resolve) => setTimeout(resolve, intervalMs));
@@ -1290,11 +1347,13 @@ export async function pollSubCompositionTimelines(page, timeoutMs, { intervalMs
     }
     return scriptFailureBail ? "script_failure" : "timeout";
 }
-async function pollVideosReady(page, skipIds, timeoutMs, intervalMs = 100) {
+export async function pollVideosReady(page, skipIds, timeoutMs, intervalMs = 100) {
     const check = async () => {
         return Boolean(await page.evaluate((skipIdList) => {
             const skip = new Set(skipIdList);
-            const vids = Array.from(document.querySelectorAll("video")).filter((v) => !skip.has(v.id));
+            const vids = Array.from(document.querySelectorAll("video"))
+                .filter((v) => !skip.has(v.id))
+                .filter((v) => !v.closest("[data-hidden]"));
             return (vids.length === 0 ||
                 vids.every((v) => {
                     const ve = v;
@@ -1445,16 +1504,33 @@ export function recordSubTimelineWarning(session, timeoutMs) {
     const outcome = session.subTimelineWaitOutcome;
     if (outcome === "ready" || !outcome)
         return;
-    const threwThenTimedOut = outcome === "timeout" && session.pageErrors.length > 0;
-    const scriptFailure = outcome === "script_failure" || threwThenTimedOut;
+    const threwThenTimedOut = session.pageErrors.length > 0 && session.scriptLoadFailures.length === 0;
+    const scriptFailure = isScriptFailure(session);
     const sources = [...session.scriptLoadFailures, ...session.pageErrors];
     const pending = session.pendingTimelineIds ?? [];
     const pendingSuffix = pending.length > 0 ? ` (still unregistered: ${pending.join(", ")})` : "";
+    const isolated = session.isolatedCompositions ?? [];
+    if (isolated.length > 0) {
+        recordCaptureWarnings(session, [
+            {
+                code: "script_error_isolated",
+                message: `A composition script failed, so its animation was skipped and the render went on: ` +
+                    `${isolated.map((c) => c.elementId ?? c.compositionId).join(", ")} (${sources.join(", ")}).`,
+                details: {
+                    sources,
+                    pendingCompositionIds: [...pending],
+                    isolatedElements: isolated,
+                    failureOwner: "user",
+                },
+            },
+        ]);
+        return;
+    }
     recordCaptureWarnings(session, [
         {
             code: scriptFailure ? "sub_timeline_script_failure" : "sub_timeline_readiness_timeout",
             message: threwThenTimedOut
-                ? `A composition script threw and a timeline did not register within ${timeoutMs}ms` +
+                ? `A composition script threw before its timeline registered` +
                     `${pendingSuffix} (${sources.join(", ")}). Fix the error; a composition animated by ` +
                     `CSS or rAF rather than a GSAP timeline must mark its host with data-no-timeline.`
                 : scriptFailure
@@ -1798,6 +1874,7 @@ export async function initializeSession(session) {
                 const skip = new Set(skipIdList);
                 return Array.from(document.querySelectorAll("video"))
                     .filter((v) => !skip.has(v.id))
+                    .filter((v) => !v.closest("[data-hidden]"))
                     .filter((v) => v.readyState < 2 && !v.error)
                     .map((v) => v.src || v.getAttribute("src") || "(no src)")
                     .join(", ");
@@ -1910,6 +1987,7 @@ export async function initializeSession(session) {
                 const skip = new Set(skipIdList);
                 return Array.from(document.querySelectorAll("video"))
                     .filter((v) => !skip.has(v.id))
+                    .filter((v) => !v.closest("[data-hidden]"))
                     .filter((v) => v.readyState < 2 && !v.error)
                     .map((v) => v.src || v.getAttribute("src") || "(no src)")
                     .join(", ");
@@ -2921,6 +2999,50 @@ export function resolveSessionMotionBlur(session) {
     }
     return plan;
 }
+/**
+ * Size guard for a serial drawElement frame. A frame far below the rolling median may be a
+ * dropped paint record, which is intermittent, so the frame is drawn once more: a byte-identical
+ * redraw is real content (a flat or dark frame) and is kept, as the streaming drain guard in the
+ * producer keeps it. Segmented capture reaches only this guard, so it must judge a small frame
+ * the same way, or a render that passes in one pass fails when segmented (GH #5685). A redraw
+ * that differs and is still small throws, and the caller restarts on a fresh screenshot page.
+ */
+async function judgeSmallDrawElementFrame(session, frameIndex, buffer, redraw) {
+    const sizes = (session.deFrameSizes ??= []);
+    const sorted = sizes.length >= 12 ? [...sizes].sort((a, b) => a - b) : null;
+    const median = sorted ? (sorted[sorted.length >> 1] ?? 0) : 0;
+    const floor = Math.max(session.deAbsFloor ?? 20000, median * 0.12);
+    let kept = buffer;
+    if (buffer.length < floor && !session.deAcceptedSmall?.equals(buffer)) {
+        const suspect = () => new DrawElementCaptureError(frameIndex, `suspect small frame (${buffer.length}B < ${Math.round(floor)}B)`);
+        // Under BeginFrame control the page paints only on the frame already sent for this index,
+        // so a second draw reads the same snapshot and cannot tell a drop from real content.
+        if (session.beginFrameTimeTicks > 0)
+            throw suspect();
+        const retry = await redraw();
+        if (retry.equals(buffer)) {
+            // Halving the floor keeps a run of similar flat frames from redrawing every frame.
+            session.deAbsFloor = Math.min(session.deAbsFloor ?? 20000, Math.floor(buffer.length / 2));
+            session.deAcceptedSmall = buffer;
+        }
+        else if (retry.length < floor) {
+            throw suspect();
+        }
+        else {
+            kept = retry;
+        }
+    }
+    if (sizes.length >= 60)
+        sizes.shift();
+    sizes.push(kept.length);
+    return kept;
+}
+/** Seek to `time` again and draw the frame once more, for {@link judgeSmallDrawElementFrame}. */
+async function redrawDrawElementFrame(session, frameIndex, time, seekOptions, heldVideoTime) {
+    const { page, options } = session;
+    await prepareFrameForCapture(session, frameIndex, time, seekOptions, heldVideoTime);
+    return captureDrawElementFrame(page, options.width, options.height, options.format ?? "jpeg", options.quality ?? 80, true);
+}
 /** Seek to `time` and capture one surface with the session's capture mode. */
 async function captureFrameSurface(session, frameIndex, time, seekOptions, heldVideoTime) {
     const { page, options } = session;
@@ -2972,20 +3094,8 @@ async function captureFrameSurface(session, frameIndex, time, seekOptions, heldV
             session.beginFrameTimeTicks === 0);
             // A tiny JPEG may be a dropped paint record. Never screenshot this page:
             // its injected canvas can still hold the preceding frame's bitmap.
-            // Restart on a fresh screenshot page even if this was a simple valid frame.
             if ((options.format ?? "jpeg") !== "png" && process.env.HF_FORCE_DRAWELEMENT !== "1") {
-                const sizes = (session.deFrameSizes ??= []);
-                const sorted = sizes.length >= 12 ? [...sizes].sort((a, b) => a - b) : null;
-                const median = sorted ? (sorted[sorted.length >> 1] ?? 0) : 0;
-                const floor = Math.max(20000, median * 0.12);
-                if (screenshotBuffer.length < floor) {
-                    throw new DrawElementCaptureError(frameIndex, `suspect small frame (${screenshotBuffer.length}B < ${Math.round(floor)}B)`);
-                }
-                else {
-                    if (sizes.length >= 60)
-                        sizes.shift();
-                    sizes.push(screenshotBuffer.length);
-                }
+                screenshotBuffer = await judgeSmallDrawElementFrame(session, frameIndex, screenshotBuffer, () => redrawDrawElementFrame(session, frameIndex, time, seekOptions, heldVideoTime));
             }
         }
         catch (err) {

package/dist/services/pageMotionBlur.js

@@ -33,15 +33,17 @@ async function readPageMotionBlur(page) {
         const got = typeof report === "function" ? report() : null;
         if (!got || typeof got !== "object")
             return null;
+        const tier = Reflect.get(got, "tier");
         return {
             state: String(Reflect.get(got, "state")),
             code: String(Reflect.get(got, "reasonCode")),
             movers: Number(Reflect.get(got, "movers")),
             failedFrames: Number(Reflect.get(got, "failedFrames")) || 0,
+            tier: typeof tier === "string" ? tier : null,
         };
     });
 }
-const formatPageMotionBlur = (r) => `[motion-blur] ${r.state} reasonCode=${r.code} movers=${r.movers} failedFrames=${r.failedFrames}`;
+const formatPageMotionBlur = (r) => `[motion-blur] ${r.state} reasonCode=${r.code} movers=${r.movers} failedFrames=${r.failedFrames}${r.tier ? ` tier=${r.tier}` : ""}`;
 /** One line saying what the page's blur did for this session; null when the page never asked for blur. */
 export async function describePageMotionBlur(page) {
     const r = await readPageMotionBlur(page);

package/dist/services/renderFrameVideoHold.d.ts

@@ -0,0 +1,2 @@
+/** In-page, before any script: holds replaced videos at preload none from parse (Chrome ignores a later none). */
+export declare function holdRenderFrameVideos(ids: readonly string[], renderIdAttr: string): void;

package/dist/services/renderFrameVideoHold.js

@@ -0,0 +1,19 @@
+/** In-page, before any script: holds replaced videos at preload none from parse (Chrome ignores a later none). */
+export function holdRenderFrameVideos(ids, renderIdAttr) {
+    const held = new Set(ids);
+    window.__HF_RENDER_FRAME_VIDEO_IDS = ids;
+    const hold = (el) => {
+        if (el instanceof HTMLVideoElement && held.has(el.getAttribute(renderIdAttr) || el.id))
+            el.preload = "none";
+    };
+    new MutationObserver((records) => {
+        for (const record of records)
+            for (const node of record.addedNodes) {
+                if (node.nodeType !== 1)
+                    continue;
+                hold(node);
+                for (const video of node.querySelectorAll("video"))
+                    hold(video);
+            }
+    }).observe(document, { childList: true, subtree: true });
+}

package/dist/types.d.ts

@@ -22,7 +22,7 @@ export type SubTimelineWaitOutcome = "ready" | "timeout" | "script_failure";
 export interface SubTimelineWaitMemo {
     unregisteredIds?: readonly string[];
 }
-export type CaptureWarningCode = "media_readiness_timeout" | "media_load_failed" | "audio_processing_failed" | "sub_timeline_readiness_timeout" | "sub_timeline_script_failure" | "vfx_failure" | "live_map_detected";
+export type CaptureWarningCode = "media_readiness_timeout" | "media_load_failed" | "audio_processing_failed" | "sub_timeline_readiness_timeout" | "sub_timeline_script_failure" | "script_error_isolated" | "vfx_failure" | "live_map_detected";
 /** Structured correctness warning produced while preparing a capture session. */
 export interface CaptureWarning {
     code: CaptureWarningCode;
@@ -31,6 +31,10 @@ export interface CaptureWarning {
         mediaType?: "image" | "video" | "audio";
         sources?: string[];
         pendingCompositionIds?: string[];
+        isolatedElements?: Array<{
+            compositionId: string;
+            elementId: string | null;
+        }>;
         timeoutMs?: number;
         audioFailures?: AudioFailureDiagnostic[];
         failureReasons?: string[];

package/dist/utils/ffprobe.d.ts

@@ -51,6 +51,8 @@ export interface AudioMetadata {
     bitrate?: number;
     /** Seconds after the file's media time 0 at which its last audio or video stream starts. */
     latestStreamLeadSeconds?: number;
+    audioStreamLeadSeconds?: number;
+    audioStreamCount?: number;
 }
 interface FFProbeStream {
     codec_type: string;

package/dist/utils/ffprobe.js

@@ -774,6 +774,8 @@ export async function extractAudioMetadata(filePath, options) {
             audioCodec,
             bitrate: output.format.bit_rate ? parseInt(output.format.bit_rate) : undefined,
             latestStreamLeadSeconds: latestStreamLeadSeconds(output),
+            audioStreamLeadSeconds: streamLeadSeconds(output, audioStream),
+            audioStreamCount: output.streams.filter((s) => s.codec_type === "audio").length,
         };
     })();
     if (options?.signal)
@@ -858,8 +860,7 @@ async function probeDecodedAudioDuration(filePath, sampleRate, startSeconds, con
     return lastFrame.timestamp + lastFrame.nbSamples / sampleRate - startSeconds;
 }
 const keyframeCache = new Map();
-/** Intervals beyond this cause seeking issues in the headless renderer and
- *  audio/video desync — the sole threshold for `isProblematic` below. */
+/** Advisory threshold for seeking cost; GOP length alone does not establish incorrect output. */
 const PROBLEMATIC_KEYFRAME_INTERVAL_SECONDS = 2;
 /**
  * Checks keyframe intervals in a video stream; intervals over the threshold below flag `isProblematic`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/engine",
-  "version": "0.8.189",
+  "version": "0.8.191",
   "description": "Seekable web page to video rendering engine (Puppeteer + FFmpeg)",
   "repository": {
     "type": "git",
@@ -50,8 +50,8 @@
     "linkedom": "^0.18.12",
     "puppeteer": "^25.8.0",
     "puppeteer-core": "^25.8.0",
-    "@hyperframes/core": "^0.8.189",
-    "@hyperframes/parsers": "^0.8.189"
+    "@hyperframes/parsers": "^0.8.191",
+    "@hyperframes/core": "^0.8.191"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",