@hyperframes/engine 0.8.186 → 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,6 +58,7 @@ 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";

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/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/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/package.json

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