@hyperframes/engine 0.8.185 → 0.8.188

package/dist/index.d.ts

@@ -41,6 +41,7 @@ export { augmentPageNavigationTimeoutError, isPageNavigationTimeoutError, type N
 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, } 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, 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, 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";
@@ -57,7 +58,9 @@ export { calculateOptimalWorkers, computeWorkerSizing, selectVerifySampleIndices
 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";
+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 { readWebGlVendorInfoFromCanvas } from "./utils/readWebGlVendorInfoFromCanvas.js";
 export { extractMediaMetadata, extractVideoMetadata, extractFinalVideoFrameTimestamp, extractAudioMetadata, probeMediaProfile, analyzeKeyframeIntervals, type VideoMetadata, type AudioMetadata, type MediaProbeProfile, type KeyframeAnalysis, } from "./utils/ffprobe.js";

package/dist/index.js

@@ -44,6 +44,7 @@ export { createCaptureSession, initializeSession, closeCaptureSession, captureFr
 export { CaptureFailure, classifyCaptureFailure, isFatalCaptureFailure, } from "./services/captureFailure.js";
 export { createChromeMemorySampler, } from "./services/chromeMemorySampler.js";
 // ── Screenshot (BeginFrame) ─────────────────────────────────────────────────────
+export { installMediaRenderIdBridge } from "./services/mediaRenderIdBridge.js";
 export { beginFrameCapture, pageScreenshotCapture, getCdpSession, injectVideoFramesBatch, syncVideoFrameVisibility, cdpSessionCache, probeBeginFrameLiveness, initTransparentBackground, 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, HLS_MASTER_PLAYLIST, HLS_VIDEO_PLAYLIST, HLS_AUDIO_PLAYLIST, } from "./services/chunkEncoder.js";
@@ -63,6 +64,7 @@ export { createFileServer, } from "./services/fileServer.js";
 // ── Utilities ──────────────────────────────────────────────────────────────────
 export { quantizeTimeToFrame, MEDIA_VISUAL_STYLE_PROPERTIES } from "@hyperframes/core";
 export { frameFileExtension } from "./services/frameCapture.js";
+export { frameSequencePath } from "./services/extractedFrameIndex.js";
 export { assertSwiftShader, readWebGlVendorInfo, SwiftShaderAssertionError, BROWSER_GPU_NOT_SOFTWARE, } from "./utils/assertSwiftShader.js";
 export { readWebGlVendorInfoFromCanvas } from "./utils/readWebGlVendorInfoFromCanvas.js";
 export { extractMediaMetadata, extractVideoMetadata, extractFinalVideoFrameTimestamp, extractAudioMetadata, probeMediaProfile, analyzeKeyframeIntervals, } from "./utils/ffprobe.js";

package/dist/services/aacEncode.js

@@ -57,6 +57,8 @@ export async function encodeAac(input, outputPath, totalDuration, { signal, time
             path: join(dir, `${k}.aac`),
         }));
         const results = await Promise.all(segments.map(({ trim, path }) => runFfmpeg([
+            "-cpuflags",
+            "0",
             "-i",
             input,
             "-af",

package/dist/services/audioFxRender.d.ts

@@ -107,6 +107,7 @@ export declare function applyAudioFxChain(inputWav: string, chain: HfAudioFxChai
     signal?: AbortSignal;
     automation?: HfAutomation;
     envelope?: AudioFxEnvelope;
+    inputGain?: number;
     streaming?: Partial<AudioFxStreamingLimits>;
 }): Promise<{
     path: string;

package/dist/services/audioFxRender.js

@@ -258,6 +258,11 @@ function applyEnvelopeToPlanes(planes, sampleRate, gainAt, startFrame = 0) {
             plane[frame] = (plane[frame] ?? 0) * gain;
     }
 }
+/** The clip's `data-volume`, ahead of the chain where an editor puts clip gain. */
+function applyInputGain(planes, gain = 1) {
+    if (gain !== 1)
+        applyEnvelopeToPlanes(planes, 1, () => gain);
+}
 const DEFAULT_STREAMING_LIMITS = {
     aboveBytes: 512 * 1024 * 1024,
     segmentSeconds: 300,
@@ -324,6 +329,7 @@ async function renderInSegments(openPage, inputWav, header, chain, outputWav, op
                 throw new AudioFxRenderError(`Audio FX cancelled for track ${options.trackId}`);
             }
             const planes = deinterleave(readFrames(inFd, header, seg.readFrom, seg.readTo), channels);
+            applyInputGain(planes, options.inputGain);
             // A fresh page per window, so the browser never holds more than one window of audio.
             const page = await openPage();
             let outPlanes;
@@ -397,6 +403,7 @@ export async function applyAudioFxChain(inputWav, chain, outputWav, options) {
     }
     const input = readWav(inputWav);
     const planes = deinterleave(input.samples, input.channels);
+    applyInputGain(planes, options.inputGain);
     // An empty track has nothing to process — and an OfflineAudioContext of zero
     // length throws, which is fatal for the WHOLE render rather than this track:
     // the error travels past the mixer's per-track failure collector. ffmpeg

package/dist/services/audioMixer.d.ts

@@ -18,11 +18,12 @@ export declare function buildTrackInputFilter(track: Pick<AudioTrack, "start" |
  * sampled, or the bake would quietly straighten it.
  *
  * Times come out in composition seconds, which is what the baker subtracts the
- * track start from. Returns null when the track has no volume lane.
+ * track start from. Values are `gainedVolume` of the track's `data-volume`.
+ * Returns null when the track has no volume lane.
  */
 export declare function volumeLaneKeyframes(automation: {
     lanes: HfAutomationLane[];
-}, trackStart: number, duration: number): AudioVolumeKeyframe[] | null;
+}, trackStart: number, duration: number, gain: number, gainAhead?: boolean): AudioVolumeKeyframe[] | null;
 /**
  * The top-level root's `data-fx-chain`. It belongs to the composition, not to a clip,
  * so `processCompositionAudio` takes it beside the tracks: a track the render adds

package/dist/services/audioMixer.js

@@ -6,11 +6,11 @@ import { parseHTML } from "linkedom";
 import { extractAudioMetadata } from "../utils/ffprobe.js";
 import { isNotMediaPayload } from "../utils/notMediaPayload.js";
 import { urlInputArgs } from "../utils/urlInput.js";
-import { clampAudioGain } from "@hyperframes/core/audio-gain";
+import { clampAudioGain, clipGain } from "@hyperframes/core/audio-gain";
 import { clampFadesToDuration, readElementFades } from "@hyperframes/core/audio-fade";
 import { downloadToTemp, isHttpUrl, UrlDownloadError, writeUrlDownloadTelemetry, } from "../utils/urlDownloader.js";
 import { DEFAULT_CONFIG } from "../config.js";
-import { formatFfmpegError, runFfmpeg } from "../utils/runFfmpeg.js";
+import { describeFfmpegFailure, runFfmpeg } from "../utils/runFfmpeg.js";
 import { encodeAac } from "./aacEncode.js";
 import { audioSubprocessEvidence } from "./audioFailureDiagnostic.js";
 import { unwrapTemplate } from "../utils/htmlTemplate.js";
@@ -18,8 +18,8 @@ import { resolveMediaElementSrc, resolveProjectRelativeSrc } from "./videoFrameE
 import { resolveReferencedStart } from "./referenceResolver.js";
 import { isKnownInactiveTimelineWindow } from "./mediaTimelineWindow.js";
 import { applyVolumeEnvelopeToWav } from "./audioVolumeEnvelope.js";
-import { HF_AUDIO_FX_ATTR, parseAudioFxChain, } from "@hyperframes/core/audio-fx";
-import { HF_AUDIO_AUTOMATION_ATTR, parseAutomation, resolveAutomation, sampleAutomationLane, VOLUME_TARGET, } from "@hyperframes/core/audio-automation";
+import { enabledAudioFxNodes, HF_AUDIO_FX_ATTR, parseAudioFxChain, } from "@hyperframes/core/audio-fx";
+import { gainedVolume, gainedVolumePoints, HF_AUDIO_AUTOMATION_ATTR, isBentSegment, volumeSegmentSampleCount, parseAutomation, resolveAutomation, sampleAutomationLane, VOLUME_TARGET, } from "@hyperframes/core/audio-automation";
 import { chainTailSeconds } from "@hyperframes/core/audio-fx-tail";
 import { isAudibleVideoElement, MEDIA_RENDER_ID_ATTR, normalizePlaybackRate, normalizeRateSpec, parseStrictFiniteTimingNumber, readElementRateSpec, readMediaStart, sourceTimeAt, timeAtSourceTime, } from "@hyperframes/core";
 import { readMasterFxChain, resolveAudioGroups } from "@hyperframes/core/audio-groups";
@@ -315,7 +315,7 @@ function downloadFailure(error, elementId) {
         detail: boundedDetail(`Download failed for audio element ${elementId}: ${message}`),
     };
 }
-function ffmpegFailure(stage, result, elementId) {
+function ffmpegFailure(stage, result, timeoutMs, elementId) {
     const stderr = result.stderr ?? "";
     let reason = "ffmpeg_failed";
     let owner = "system";
@@ -352,12 +352,10 @@ function ffmpegFailure(stage, result, elementId) {
         elementId,
         subprocess: audioSubprocessEvidence(result),
         detail: boundedDetail(result.error?.message
-            ? `${formatFfmpegError(result.exitCode, stderr)}: ${result.error.message}`
-            : formatFfmpegError(result.exitCode, stderr)),
+            ? `${describeFfmpegFailure(result, timeoutMs)}: ${result.error.message}`
+            : describeFfmpegFailure(result, timeoutMs)),
     };
 }
-/** Extra samples per second inside a segment the baker cannot draw straight. */
-const CURVED_SEGMENT_SAMPLES_PER_SEC = 30;
 /**
  * A volume lane as keyframes for the PCM baker.
  *
@@ -366,36 +364,38 @@ const CURVED_SEGMENT_SAMPLES_PER_SEC = 30;
  * sampled, or the bake would quietly straighten it.
  *
  * Times come out in composition seconds, which is what the baker subtracts the
- * track start from. Returns null when the track has no volume lane.
+ * track start from. Values are `gainedVolume` of the track's `data-volume`.
+ * Returns null when the track has no volume lane.
  */
-export function volumeLaneKeyframes(automation, trackStart, duration) {
+export function volumeLaneKeyframes(automation, trackStart, duration, gain, gainAhead = false) {
     const lane = automation.lanes.find((l) => l.target === VOLUME_TARGET);
     if (!lane || lane.points.length === 0)
         return null;
+    const points = gainedVolumePoints(lane, gain, gainAhead);
     const out = [];
     const push = (t, v) => {
         out.push({ time: trackStart + t, volume: v });
     };
     // The envelope holds its first value before the first point, rather than
     // falling back to `data-volume`.
-    const first = lane.points[0];
+    const first = points[0];
     if (first.t > 0)
         push(0, first.v);
-    for (let i = 0; i < lane.points.length; i += 1) {
-        const a = lane.points[i];
+    for (let i = 0; i < points.length; i += 1) {
+        const a = points[i];
         push(a.t, a.v);
-        const b = lane.points[i + 1];
-        if (!b || !a.curve)
+        const b = points[i + 1];
+        if (!b || !isBentSegment(a))
             continue;
-        const steps = Math.max(2, Math.ceil((b.t - a.t) * CURVED_SEGMENT_SAMPLES_PER_SEC));
+        const steps = volumeSegmentSampleCount(b.t - a.t);
         for (let k = 1; k < steps; k += 1) {
             const t = a.t + ((b.t - a.t) * k) / steps;
-            push(t, sampleAutomationLane(lane, t));
+            push(t, gainedVolume(sampleAutomationLane(lane, t), gain, gainAhead));
         }
     }
     // Hold the last value to the clip's end, so the baker does not ramp away
     // from it toward whatever it would otherwise assume.
-    const last = lane.points[lane.points.length - 1];
+    const last = points[points.length - 1];
     if (duration > last.t)
         push(duration, last.v);
     return out;
@@ -547,7 +547,7 @@ async function extractAudioSegment(srcPath, outputPath, stage, mediaStart, durat
             failure,
         };
     }
-    let failure = result.success ? undefined : ffmpegFailure(stage, result);
+    let failure = result.success ? undefined : ffmpegFailure(stage, result, ffmpegProcessTimeout);
     const probedLinkFailedToRead = readsUrl && (failure?.reason === "invalid_media" || failure?.reason === "ffmpeg_failed");
     if (failure && probedLinkFailedToRead) {
         failure = { ...failure, reason: "download_failed", owner: "system", retryable: true };
@@ -594,7 +594,9 @@ async function generateSilence(outputPath, duration, signal, config) {
             failure,
         };
     }
-    const failure = !result.success ? ffmpegFailure("silence", result) : undefined;
+    const failure = !result.success
+        ? ffmpegFailure("silence", result, ffmpegProcessTimeout)
+        : undefined;
     return {
         success: result.success,
         outputPath,
@@ -732,7 +734,7 @@ async function mixAudioTracks(tracks, outputPath, totalDuration, signal, config)
         };
     }
     if (!result.success) {
-        const failure = ffmpegFailure("mix", result);
+        const failure = ffmpegFailure("mix", result, ffmpegProcessTimeout);
         return {
             success: false,
             outputPath,
@@ -785,15 +787,16 @@ async function mixGroupMembers(memberTracks, outputPath, totalDuration, signal,
     const outputDir = dirname(outputPath);
     if (!existsSync(outputDir))
         mkdirSync(outputDir, { recursive: true });
-    const buildInputFilters = (ignoreKeyframes) => memberTracks.map((track, i) => {
+    const buildInputFilters = (ignoreKeyframes, padMembers) => memberTracks.map((track, i) => {
         const volumeFilter = buildVolumeExpression(track, ignoreKeyframes);
-        return buildTrackInputFilter(track, i, volumeFilter, totalDuration);
+        return buildTrackInputFilter(track, i, volumeFilter, totalDuration, padMembers);
     });
     const mixInputs = memberTracks.map((_, i) => `[a${i}]`).join("");
     const runOnce = async (useNormalize, ignoreKeyframes = false) => {
-        const inputFilters = buildInputFilters(ignoreKeyframes);
+        const inputFilters = buildInputFilters(ignoreKeyframes, !useNormalize);
+        const padUnitySumOnceToFilm = `[mixed];[mixed]apad,asetpts=N/SR/TB,atrim=0:${formatFilterNumber(totalDuration)}`;
         const mixFilter = useNormalize
-            ? `${mixInputs}amix=inputs=${memberTracks.length}:duration=longest:dropout_transition=0:normalize=0[out]`
+            ? `${mixInputs}amix=inputs=${memberTracks.length}:duration=longest:dropout_transition=0:normalize=0${padUnitySumOnceToFilm}[out]`
             : // Every member is padded and trimmed to totalDuration above, and
                 // dropout_transition=0 keeps all N inputs active for that whole span.
                 // amix's default normalize therefore divides by exactly N throughout;
@@ -868,7 +871,7 @@ async function mixGroupMembers(memberTracks, outputPath, totalDuration, signal,
         }
     }
     if (signal?.aborted || !result.success) {
-        const failure = ffmpegFailure("mix", result);
+        const failure = ffmpegFailure("mix", result, ffmpegProcessTimeout);
         return { success: false, error: failure.detail, failure };
     }
     return { success: true, degradedAutomation };
@@ -893,7 +896,7 @@ async function mixThroughFloatSum(tracks, masterChain, outputPath, workDir, tota
         timeout: config?.ffmpegProcessTimeout ?? DEFAULT_CONFIG.ffmpegProcessTimeout,
     });
     if (!encoded.success) {
-        const failure = ffmpegFailure("mix", encoded);
+        const failure = ffmpegFailure("mix", encoded, config?.ffmpegProcessTimeout ?? DEFAULT_CONFIG.ffmpegProcessTimeout);
         return {
             success: false,
             outputPath,
@@ -1060,8 +1063,9 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
             // 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.
+            const chain = element.fxChain ? parseAudioFxChain(element.fxChain) : undefined;
             const automation = element.automation
-                ? resolveAutomation(parseAutomation(element.automation), element.fxChain ? parseAudioFxChain(element.fxChain) : undefined)
+                ? 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
@@ -1070,9 +1074,13 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
             // 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.
+            const gainBeforeFx = chain !== undefined && enabledAudioFxNodes(chain).length > 0;
             const laneKeyframes = automation
-                ? volumeLaneKeyframes(automation, element.start, element.end - element.start)
+                ? volumeLaneKeyframes(automation, element.start, element.end - element.start, element.volume ?? 1, gainBeforeFx)
                 : null;
+            const tweened = !laneKeyframes && (element.volumeKeyframes?.length ?? 0) > 0;
             const envelopeKeyframes = laneKeyframes ?? element.volumeKeyframes;
             const envelope = envelopeKeyframes && envelopeKeyframes.length > 0
                 ? {
@@ -1083,11 +1091,10 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
                 : null;
             let bakedEnvelope = false;
             let tailSeconds = 0;
-            if (element.fxChain) {
+            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.
-                const chain = parseAudioFxChain(element.fxChain);
                 // The rendered WAV is longer than the input by exactly this much, so
                 // the mix has to be told to let it through.
                 tailSeconds = chainTailSeconds(chain, automation ?? undefined);
@@ -1096,6 +1103,7 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
                     signal: effectiveSignal,
                     ...(automation ? { automation } : {}),
                     ...(envelope ? { envelope } : {}),
+                    ...(gainBeforeFx ? { inputGain: clipGain(element.volume ?? 1, tweened) } : {}),
                 });
                 audioSrcPath = fxResult.path;
                 bakedEnvelope = fxResult.envelopeBaked;
@@ -1116,7 +1124,7 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
                 mediaStart: element.mediaStart,
                 duration: element.end - element.start,
                 // Gain is already in the samples when baked, so mix at unity.
-                volume: bakedEnvelope ? 1.0 : (element.volume ?? 1.0),
+                volume: bakedEnvelope || (gainBeforeFx && !tweened) ? 1.0 : (element.volume ?? 1.0),
                 volumeKeyframes: bakedEnvelope ? undefined : (envelopeKeyframes ?? undefined),
                 ...(element.fadeIn ? { fadeIn: element.fadeIn } : {}),
                 ...(element.fadeOut ? { fadeOut: element.fadeOut } : {}),
@@ -1260,7 +1268,9 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
             const automation = meta.automation
                 ? resolveAutomation(parseAutomation(meta.automation), meta.fxChain ? parseAudioFxChain(meta.fxChain) : undefined)
                 : null;
-            const laneKeyframes = automation ? volumeLaneKeyframes(automation, 0, totalDuration) : null;
+            const laneKeyframes = automation
+                ? volumeLaneKeyframes(automation, 0, totalDuration, meta.volume)
+                : null;
             const envelope = laneKeyframes && laneKeyframes.length > 0
                 ? { keyframes: laneKeyframes, trackStart: 0, baseVolume: meta.volume }
                 : null;

package/dist/services/chunkEncoder.js

@@ -5,6 +5,7 @@
  * Encodes captured frames into video using FFmpeg.
  * Supports CPU (libx264) and GPU encoding.
  */
+import { frameSequencePath } from "./extractedFrameIndex.js";
 import { closeSync, copyFileSync, existsSync, ftruncateSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, statSync, writeFileSync, writeSync, } from "fs";
 import { join, dirname, extname } from "path";
 import { DEFAULT_CONFIG } from "../config.js";
@@ -396,7 +397,7 @@ export async function encodeFramesFromDir(framesDir, framePattern, outputPath, o
     if (options.useGpu) {
         gpuEncoder = await getCachedGpuEncoder();
     }
-    const inputPath = join(framesDir, framePattern);
+    const inputPath = frameSequencePath(framesDir, framePattern);
     const inputArgs = ["-framerate", fpsToFfmpegArg(options.fps), "-i", inputPath];
     const args = buildEncoderArgs(options, inputArgs, outputPath, gpuEncoder);
     const encodeTimeout = config?.ffmpegEncodeTimeout ?? DEFAULT_CONFIG.ffmpegEncodeTimeout;
@@ -534,7 +535,7 @@ export async function encodeFramesChunkedConcat(framesDir, framePattern, outputP
                 ? ".mov"
                 : ".mp4";
         const chunkPath = join(chunkDir, `chunk_${String(i).padStart(4, "0")}${ext}`);
-        const inputPath = join(framesDir, framePattern);
+        const inputPath = frameSequencePath(framesDir, framePattern);
         const inputArgs = [
             "-framerate",
             fpsToFfmpegArg(options.fps),

package/dist/services/extractedFrameIndex.d.ts

@@ -1,5 +1,6 @@
 export type ExtractedFrameFormat = "jpg" | "png";
 export declare const FRAME_FILENAME_PREFIX = "frame_";
+export declare function frameSequencePath(dir: string, framePattern: string): string;
 export declare class ExtractedFrameSequenceError extends Error {
     constructor(message: string);
 }

package/dist/services/extractedFrameIndex.js

@@ -1,6 +1,9 @@
 import { readdirSync } from "node:fs";
 import { join } from "node:path";
 export const FRAME_FILENAME_PREFIX = "frame_";
+export function frameSequencePath(dir, framePattern) {
+    return join(dir.replaceAll("%", "%%"), framePattern);
+}
 export class ExtractedFrameSequenceError extends Error {
     constructor(message) {
         super(message);

package/dist/services/frameCapture.js

@@ -13,6 +13,7 @@ import { COMPOSITION_SOURCE_URL, quantizeSeekTime, quantizeTimeToFrame, fpsToNum
 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";
+import { describePageMotionBlur, describePageMotionBlurAtEnd, installPageMotionBlur, } from "./pageMotionBlur.js";
 // ── Extracted modules ───────────────────────────────────────────────────────
 import { acquireBrowser, releaseBrowser, forceReleaseBrowser, buildChromeArgs, resolveBrowserGpuMode, captureWithoutWaylandDisplay, resolveHeadlessShellPath, compositionRequiresWebGpu, assertWebGpuAdapterAvailable, usesSoftwareWebGpu, } from "./browserManager.js";
 import { beginFrameCapture, ensureRenderFrameSiblings, getCdpSession, pageContentExceedsCaptureHeight, pageScreenshotCapture, initTransparentBackground, shouldDefaultCaptureBeyondViewport, } from "./screenshotService.js";
@@ -946,6 +947,7 @@ async function constructCaptureSession(input) {
             }
         }, variablesJson);
     }
+    await installPageMotionBlur(page, options);
     const browserVersion = await browser.version();
     const sessionOptions = resolveCaptureSessionOptions(options, browserVersion);
     const expectedMajor = config?.expectedChromiumMajor;
@@ -2462,6 +2464,7 @@ export async function createStaticVerificationPage(session) {
                     JSON.parse(json);
             }, variablesJson);
         }
+        await installPageMotionBlur(page, session.options);
         await page.setViewport({
             width: session.options.width,
             height: session.options.height,
@@ -3192,6 +3195,11 @@ async function captureFrameCore(session, frameIndex, time) {
         session.capturePerf.screenshotMs += screenshotMs;
         session.capturePerf.totalMs += captureTimeMs;
         session.capturePerf.frameMs.push(captureTimeMs);
+        if (session.capturePerf.frames === 1) {
+            const blur = await describePageMotionBlur(session.page).catch(() => null);
+            if (blur)
+                console.log(blur);
+        }
         // Retain this freshly-captured buffer so the following static frames can reuse it.
         if (session.staticFrames) {
             session.lastFrameBuffer = buffer;
@@ -3527,6 +3535,11 @@ export async function closeCaptureSession(session) {
         // point up to `intervalMs` earlier. Best effort; the page may be gone.
         await session.chromeMemory.sampleOnce();
     }
+    if (session.page && !session.pageReleased) {
+        const blur = await describePageMotionBlurAtEnd(session.page);
+        if (blur)
+            console.log(blur);
+    }
     // Realized static-dedup telemetry: how much the cache actually helped this
     // render (vs the prediction logged at arm time). Both capture paths
     // (sequential orchestrator + parallel workers) close their session here, so

package/dist/services/mediaRenderIdBridge.d.ts

@@ -4,14 +4,14 @@
  * The pipeline addresses media by id, but element ids are only unique within
  * one composition FILE and the render document inlines many, so
  * `document.getElementById` silently resolves duplicates to whichever element
- * comes first. The producer stamps a document-unique `data-hf-render-id`
+ * comes first. The compiler stamps a document-unique `data-hf-render-id`
  * (core's mediaRenderIds.ts); these helpers are the single place that knows to
  * prefer it, so every capture stage addresses the same element.
  *
  * Installed via `evaluateOnNewDocument` so it exists before any page script.
- * Every call site keeps a `getElementById` fallback for documents that were
- * never compiled by the producer (snapshot, check, and direct engine callers),
- * where the authored id already is the identity.
+ * Every call site keeps a `getElementById` fallback for uncompiled documents
+ * passed directly to the engine. CLI captures and producer renders both carry
+ * document-unique IDs from the compiler.
  *
  * `__hfMediaId` mirrors core's `readMediaRenderId`, which is the definition of
  * this rule; the copy exists only because code serialized into `page.evaluate`

package/dist/services/mediaRenderIdBridge.js

@@ -4,14 +4,14 @@
  * The pipeline addresses media by id, but element ids are only unique within
  * one composition FILE and the render document inlines many, so
  * `document.getElementById` silently resolves duplicates to whichever element
- * comes first. The producer stamps a document-unique `data-hf-render-id`
+ * comes first. The compiler stamps a document-unique `data-hf-render-id`
  * (core's mediaRenderIds.ts); these helpers are the single place that knows to
  * prefer it, so every capture stage addresses the same element.
  *
  * Installed via `evaluateOnNewDocument` so it exists before any page script.
- * Every call site keeps a `getElementById` fallback for documents that were
- * never compiled by the producer (snapshot, check, and direct engine callers),
- * where the authored id already is the identity.
+ * Every call site keeps a `getElementById` fallback for uncompiled documents
+ * passed directly to the engine. CLI captures and producer renders both carry
+ * document-unique IDs from the compiler.
  *
  * `__hfMediaId` mirrors core's `readMediaRenderId`, which is the definition of
  * this rule; the copy exists only because code serialized into `page.evaluate`

package/dist/services/pageMotionBlur.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Tells the page's capture motion blur (`data-motion-blur="on"`) to stand down, before any of
+ * its scripts run: when the engine blurs (it would average frames that are already blurred) or
+ * when the render must match a Studio preview that could not blur (`pageMotionBlur: "off"`).
+ */
+import type { Page } from "puppeteer-core";
+import type { CaptureOptions } from "../types.js";
+export declare function installPageMotionBlur(page: Pick<Page, "evaluateOnNewDocument">, options: Pick<CaptureOptions, "motionBlur" | "pageMotionBlur" | "deviceScaleFactor">): Promise<void>;
+/** One line saying what the page's blur did for this session; null when the page never asked for blur. */
+export declare function describePageMotionBlur(page: Pick<Page, "evaluate">): Promise<string | null>;
+/** The session's closing line, only when frames fell back to plain DOM: the first-frame line cannot know. */
+export declare function describePageMotionBlurAtEnd(page: Pick<Page, "evaluate">, timeoutMs?: number): Promise<string | null>;

package/dist/services/pageMotionBlur.js

@@ -0,0 +1,66 @@
+/**
+ * Tells the page's capture motion blur (`data-motion-blur="on"`) to stand down, before any of
+ * its scripts run: when the engine blurs (it would average frames that are already blurred) or
+ * when the render must match a Studio preview that could not blur (`pageMotionBlur: "off"`).
+ */
+import { PAGE_DEVICE_SCALE_GLOBAL, PAGE_MOTION_BLUR_OFF_GLOBAL, acceleratedCanvasTrackerSource, } from "@hyperframes/core";
+function pageOffReason(options) {
+    if (options.motionBlur)
+        return "engine-motion-blur";
+    if (options.pageMotionBlur === "off")
+        return "preview-unsupported";
+    return options.pageMotionBlur ?? null;
+}
+export async function installPageMotionBlur(page, options) {
+    await page.evaluateOnNewDocument(acceleratedCanvasTrackerSource());
+    const scale = options.deviceScaleFactor ?? 1;
+    if (scale > 1) {
+        await page.evaluateOnNewDocument((key, v) => {
+            window[key] = v;
+        }, PAGE_DEVICE_SCALE_GLOBAL, scale);
+    }
+    const off = pageOffReason(options);
+    if (!off)
+        return;
+    await page.evaluateOnNewDocument((key, v) => {
+        window[key] = v;
+    }, PAGE_MOTION_BLUR_OFF_GLOBAL, off);
+}
+async function readPageMotionBlur(page) {
+    return page.evaluate(() => {
+        const api = Reflect.get(window, "__hfMotionBlur");
+        const report = api && typeof api === "object" ? Reflect.get(api, "report") : null;
+        const got = typeof report === "function" ? report() : null;
+        if (!got || typeof got !== "object")
+            return null;
+        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,
+        };
+    });
+}
+const formatPageMotionBlur = (r) => `[motion-blur] ${r.state} reasonCode=${r.code} movers=${r.movers} failedFrames=${r.failedFrames}`;
+/** 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);
+    return r && formatPageMotionBlur(r);
+}
+/** The session's closing line, only when frames fell back to plain DOM: the first-frame line cannot know. */
+export async function describePageMotionBlurAtEnd(page, timeoutMs = 1500) {
+    let timer;
+    const stuck = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(null), timeoutMs);
+    });
+    try {
+        const r = await Promise.race([readPageMotionBlur(page), stuck]);
+        return r && r.failedFrames > 0 ? `${formatPageMotionBlur(r)} (session end)` : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/services/screenshotService.js

@@ -556,6 +556,7 @@ async function injectResolvedVideoFramesBatch(page, updates) {
     async (items, visualProperties, colorGradingSourceHiddenAttr) => {
         const injectedIds = [];
         const pendingDecodes = [];
+        const imagesToPublish = [];
         const replacementLayoutProperties = new Set([
             "width",
             "height",
@@ -692,6 +693,8 @@ async function injectResolvedVideoFramesBatch(page, updates) {
             img.style.objectFit = computedStyle.objectFit;
             img.style.objectPosition = computedStyle.objectPosition;
             img.style.zIndex = computedStyle.zIndex;
+            // Publish after full decode so raster cannot race it with a reduced JPEG decode.
+            img.style.setProperty("visibility", "hidden", "important");
             img.decoding = "sync";
             if (img.getAttribute("src") !== item.dataUri) {
                 if (item.crossOrigin)
@@ -705,7 +708,7 @@ async function injectResolvedVideoFramesBatch(page, updates) {
                 }));
             }
             img.style.opacity = String(computedOpacity);
-            img.style.visibility = "visible";
+            imagesToPublish.push(img);
             // Hide the native <video> with visibility only — never clobber inline
             // opacity, so subsequent reads (and queryElementStacking) see the real
             // GSAP-controlled value.
@@ -716,6 +719,8 @@ async function injectResolvedVideoFramesBatch(page, updates) {
         if (pendingDecodes.length > 0) {
             await Promise.all(pendingDecodes);
         }
+        for (const img of imagesToPublish)
+            img.style.visibility = "visible";
         if (injectedIds.length > 0) {
             const redraw = window
                 .__hf?.colorGrading?.redraw;
@@ -757,7 +762,7 @@ export async function syncVideoFrameVisibility(page, activeVideoIds) {
             const img = video.nextElementSibling;
             const hasImg = img && img.classList.contains("__render_frame__");
             const ancestorHidden = isVisualAncestorHidden(video);
-            const visible = active.has(video.id) && !ancestorHidden;
+            const visible = active.has(window.__hfMediaId?.(video) || video.id) && !ancestorHidden;
             if (visible) {
                 // Active video: show injected <img>, hide native <video>.
                 // Do NOT clobber inline opacity here — GSAP-controlled opacity must

package/dist/services/videoFrameExtractor.js

@@ -27,7 +27,7 @@ import { isFfmpegFilterAvailable } from "../utils/psnrFilterAvailability.js";
 import { DEFAULT_CONFIG } from "../config.js";
 import { unwrapTemplate } from "../utils/htmlTemplate.js";
 import { FRAME_FILENAME_PREFIX, gcExtractionCache, gcSweepDue, lookupCacheEntry, partialCacheEntryDir, publishCacheEntry, readContentSha256, readKeyStat, rehydrateCacheEntry, touchCacheEntry, } from "./extractionCache.js";
-import { framePathsFromDirectory } from "./extractedFrameIndex.js";
+import { framePathsFromDirectory, frameSequencePath } from "./extractedFrameIndex.js";
 export { resolveProjectRelativeSrc };
 /**
  * The single source of truth for the source-video frame-extraction allow-list.
@@ -571,7 +571,7 @@ outputDirOverride) {
     }
     const format = resolveFrameFormat(metadata, options.format);
     const framePattern = `${FRAME_FILENAME_PREFIX}%05d.${format}`;
-    const outputPattern = join(videoOutputDir, framePattern);
+    const outputPattern = frameSequencePath(videoOutputDir, framePattern);
     // Forced-SDR extraction tone-maps HDR with zscale, the Studio proxy policy. A macOS ffmpeg
     // without zscale falls back to VideoToolbox, whose frames stay HDR and are tone-mapped by
     // Chrome instead (darker), and the render warns once.

package/dist/types.d.ts

@@ -8,6 +8,7 @@ import type { AudioFailureDiagnostic } from "./services/audioMixer.types.js";
 import type { Fps } from "@hyperframes/core";
 import type { ChromeMemoryStats } from "./services/chromeMemorySampler.js";
 import type { MotionBlurOptions } from "./services/motionBlur.js";
+export type PageMotionBlurOff = "off" | "hdr-render" | "layered-composite" | "distributed-render";
 /**
  * Outcome of waiting for a sub-composition's GSAP timelines to register.
  * Threaded string-typed through `CapturePerfSummary` / `RenderPerfSummary` /
@@ -151,6 +152,8 @@ export interface CaptureOptions {
      * screenshot capture mode; see `services/motionBlur.ts`.
      */
     motionBlur?: MotionBlurOptions;
+    /** Why the page's capture motion blur stands down: the preview could not blur, or the route cannot host it. */
+    pageMotionBlur?: PageMotionBlurOff;
     deviceScaleFactor?: number;
     /**
      * Opt into Chrome's capture-beyond-viewport screenshot path. Leave undefined

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/engine",
-  "version": "0.8.185",
+  "version": "0.8.188",
   "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.185",
-    "@hyperframes/parsers": "^0.8.185"
+    "@hyperframes/core": "^0.8.188",
+    "@hyperframes/parsers": "^0.8.188"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",