@hyperframes/engine 0.8.204 → 0.8.206

package/dist/index.d.ts

@@ -46,7 +46,7 @@ export { beginFrameCapture, pageScreenshotCapture, getCdpSession, injectVideoFra
 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";
 export { spawnStreamingEncoder, createFrameReorderBuffer, type StreamingEncoder, type StreamingEncoderOptions, type StreamingEncoderResult, type FrameReorderBuffer, } from "./services/streamingEncoder.js";
-export { parseVideoElements, parseImageElements, extractVideoFramesRange, extractAllVideoFrames, isVideoPastTimelineEnd, resolveTimelineExtractionWindow, resolveVideoExtractionWindow, rebaseVideoToWindow, resolveFinalFrameExtractionWindow, resolveFrameFormat, resolveVideoExtractionDuration, resolvePlayableVideoDuration, extractionFrameCountForDuration, resolveProjectRelativeSrc, getFrameAtTime, isVideoHiddenBeforeStreamStart, createFrameLookupTable, FrameLookupTable, analyzeClipMediaFit, classifyVideoExtractionError, isVideoSourceExtractionError, runVideoExtractionWithRetry, safeVideoExtractionSourceIdentity, VideoSourceExtractionError, type VideoElement, type ImageElement, type ExtractedFrames, type DeferredFrameRange, type FrameRange, type ExtractionOptions, type ExtractionResult, type ExtractionPhaseBreakdown, type TimelineExtractionWindow, type VideoExtractionFailure, type VideoExtractionFailureKind, type VideoExtractionFailureGroupDetails, type VideoExtractionFailureRetry, type VideoExtractionFailureStatusClass, type SafeVideoExtractionSourceIdentity, type VideoFrameFormat, VIDEO_FRAME_FORMATS, isVideoFrameFormat, EXTRACT_CACHE_MIN_AGE_MS, } from "./services/videoFrameExtractor.js";
+export { parseVideoElements, parseImageElements, extractVideoFramesRange, extractAllVideoFrames, isVideoPastTimelineEnd, resolveTimelineExtractionWindow, resolveVideoExtractionWindow, rebaseVideoToWindow, resolveFinalFrameExtractionWindow, resolveFrameFormat, resolveVideoExtractionDuration, resolvePlayableVideoDuration, extractionFrameCountForDuration, resolveProjectRelativeSrc, getFrameAtTime, isVideoHiddenBeforeStreamStart, createFrameLookupTable, FrameLookupTable, analyzeClipMediaFit, classifyVideoExtractionError, isVideoSourceExtractionError, runVideoExtractionWithRetry, safeVideoExtractionSourceIdentity, VideoSourceExtractionError, type VideoElement, type ImageElement, type ExtractedFrames, type DeferredFrameRange, type FrameRange, type ExtractionOptions, type ExtractionResult, type ExtractionPhaseBreakdown, type TimelineExtractionWindow, type VideoExtractionFailure, type VideoExtractionFailureKind, type VideoExtractionFailureGroupDetails, type VideoExtractionFailureRetry, type VideoExtractionFailureStatusClass, type SafeVideoExtractionSourceIdentity, type VideoFrameFormat, VIDEO_FRAME_FORMATS, isVideoFrameFormat, EXTRACT_CACHE_MIN_AGE_MS, sdrCanvasColourFilters, } from "./services/videoFrameExtractor.js";
 export { isSelfOrAncestorHidden } from "./services/mediaHidden.js";
 export { directorySizeBytes, gcExtractionCache } from "./services/extractionCache.js";
 export { resolveReferencedStart, resolveReferencedDuration, type RefResolverEl, type RefResolverDoc, } from "./services/referenceResolver.js";
@@ -65,7 +65,7 @@ export type { MotionBlurOptions, MotionBlurBlendSpace } from "./services/motionB
 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, declareContentAddressedUrl, declareProbeFactsUrl, PROBE_FACTS_VERSION, buildProbeFactsText, probeMediaProfile, analyzeKeyframeIntervals, type VideoMetadata, type AudioMetadata, type MediaProbeProfile, type KeyframeAnalysis, } from "./utils/ffprobe.js";
+export { extractMediaMetadata, extractVideoMetadata, extractFinalVideoFrameTimestamp, extractAudioMetadata, declareContentAddressedUrl, declareProbeFactsUrl, PROBE_FACTS_VERSION, buildProbeFactsText, probeMediaProfile, runFfprobe, analyzeKeyframeIntervals, type VideoMetadata, type AudioMetadata, type MediaProbeProfile, type KeyframeAnalysis, } from "./utils/ffprobe.js";
 export { NOT_MEDIA_PAYLOAD, NotMediaPayloadError, assertMediaPayload, fingerprintElementId, isNotMediaPayload, } from "./utils/notMediaPayload.js";
 export { assertPublicHttpsUrl, isBlockedNetworkHost, downloadToTemp, fetchPublicHttpsText, isHttpUrl, safeDownloadUrlIdentity, writeUrlDownloadTelemetry, type SafeDownloadUrlIdentity, type UrlDownloadOptions, type UrlDownloadTelemetry, type PublicHttpsTextOptions, } from "./utils/urlDownloader.js";
 export { runFfmpeg, formatFfmpegError, describeFfmpegFailure, isExternalFfmpegInterruption, type RunFfmpegOptions, type RunFfmpegResult, } from "./utils/runFfmpeg.js";

package/dist/index.js

@@ -50,7 +50,7 @@ export { beginFrameCapture, pageScreenshotCapture, getCdpSession, injectVideoFra
 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";
 export { spawnStreamingEncoder, createFrameReorderBuffer, } from "./services/streamingEncoder.js";
 // ── Media processing ───────────────────────────────────────────────────────────
-export { parseVideoElements, parseImageElements, extractVideoFramesRange, extractAllVideoFrames, isVideoPastTimelineEnd, resolveTimelineExtractionWindow, resolveVideoExtractionWindow, rebaseVideoToWindow, resolveFinalFrameExtractionWindow, resolveFrameFormat, resolveVideoExtractionDuration, resolvePlayableVideoDuration, extractionFrameCountForDuration, resolveProjectRelativeSrc, getFrameAtTime, isVideoHiddenBeforeStreamStart, createFrameLookupTable, FrameLookupTable, analyzeClipMediaFit, classifyVideoExtractionError, isVideoSourceExtractionError, runVideoExtractionWithRetry, safeVideoExtractionSourceIdentity, VideoSourceExtractionError, VIDEO_FRAME_FORMATS, isVideoFrameFormat, EXTRACT_CACHE_MIN_AGE_MS, } from "./services/videoFrameExtractor.js";
+export { parseVideoElements, parseImageElements, extractVideoFramesRange, extractAllVideoFrames, isVideoPastTimelineEnd, resolveTimelineExtractionWindow, resolveVideoExtractionWindow, rebaseVideoToWindow, resolveFinalFrameExtractionWindow, resolveFrameFormat, resolveVideoExtractionDuration, resolvePlayableVideoDuration, extractionFrameCountForDuration, resolveProjectRelativeSrc, getFrameAtTime, isVideoHiddenBeforeStreamStart, createFrameLookupTable, FrameLookupTable, analyzeClipMediaFit, classifyVideoExtractionError, isVideoSourceExtractionError, runVideoExtractionWithRetry, safeVideoExtractionSourceIdentity, VideoSourceExtractionError, VIDEO_FRAME_FORMATS, isVideoFrameFormat, EXTRACT_CACHE_MIN_AGE_MS, sdrCanvasColourFilters, } from "./services/videoFrameExtractor.js";
 export { isSelfOrAncestorHidden } from "./services/mediaHidden.js";
 export { directorySizeBytes, gcExtractionCache } from "./services/extractionCache.js";
 export { resolveReferencedStart, resolveReferencedDuration, } from "./services/referenceResolver.js";
@@ -69,7 +69,7 @@ export { appendSoftwareEncoderThreadsArg } from "./services/softwareEncoderThrea
 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, declareContentAddressedUrl, declareProbeFactsUrl, PROBE_FACTS_VERSION, buildProbeFactsText, probeMediaProfile, analyzeKeyframeIntervals, } from "./utils/ffprobe.js";
+export { extractMediaMetadata, extractVideoMetadata, extractFinalVideoFrameTimestamp, extractAudioMetadata, declareContentAddressedUrl, declareProbeFactsUrl, PROBE_FACTS_VERSION, buildProbeFactsText, probeMediaProfile, runFfprobe, analyzeKeyframeIntervals, } from "./utils/ffprobe.js";
 export { NOT_MEDIA_PAYLOAD, NotMediaPayloadError, assertMediaPayload, fingerprintElementId, isNotMediaPayload, } from "./utils/notMediaPayload.js";
 export { assertPublicHttpsUrl, isBlockedNetworkHost, downloadToTemp, fetchPublicHttpsText, isHttpUrl, safeDownloadUrlIdentity, writeUrlDownloadTelemetry, } from "./utils/urlDownloader.js";
 export { runFfmpeg, formatFfmpegError, describeFfmpegFailure, isExternalFfmpegInterruption, } from "./utils/runFfmpeg.js";

package/dist/services/browserManager.d.ts

@@ -12,8 +12,9 @@ export { BrowserLeasePool } from "./browserLeasePool.js";
 export type { BrowserLaunchFingerprint, BrowserLease, BrowserPoolState, CaptureMode, } from "./browserLeasePool.js";
 /** Set while the host cancels renders on Ctrl+C; Puppeteer's own handler would exit before any cleanup ran. */
 export declare function setHostHandlesSigint(owned: boolean): void;
-export declare const sigintLaunchOptions: () => {
+export declare const ownedLaunchOptions: () => {
     handleSIGINT: boolean;
+    pipe: boolean;
 };
 export interface GpuProbeLifecycle {
     launch(puppeteer: PuppeteerNode, options: LaunchOptions): Promise<Browser>;

package/dist/services/browserManager.js

@@ -23,7 +23,7 @@ let hostHandlesSigint = false;
 export function setHostHandlesSigint(owned) {
     hostHandlesSigint = owned;
 }
-export const sigintLaunchOptions = () => ({ handleSIGINT: !hostHandlesSigint });
+export const ownedLaunchOptions = () => ({ handleSIGINT: !hostHandlesSigint, pipe: true });
 function isSoftwareWebGlRenderer(rendererInfo) {
     const renderer = rendererInfo.trim().toLowerCase();
     return (renderer.includes("swiftshader") ||
@@ -54,7 +54,7 @@ async function probeHardwareWebGlInfo(ppt, options) {
     let probeBrowser;
     try {
         const launchOptions = {
-            ...sigintLaunchOptions(),
+            ...ownedLaunchOptions(),
             headless: true,
             args: withHyperframesBrowserMarker(options.args),
             defaultViewport: { width: 64, height: 64 },
@@ -659,7 +659,7 @@ async function launchBrowser(fingerprint) {
     let captureMode = fingerprint.requestedCaptureMode;
     let browser;
     const launch = (args) => ppt.launch({
-        ...sigintLaunchOptions(),
+        ...ownedLaunchOptions(),
         headless: true,
         args: withHyperframesBrowserMarker(args),
         defaultViewport: null,

package/dist/services/frameCapture.d.ts

@@ -6,7 +6,7 @@
  * the page to expose window.__hf, then captures frames deterministically
  * via Chrome's BeginFrame API or Page.captureScreenshot fallback.
  */
-import { type Browser, type Page, type Protocol } from "puppeteer-core";
+import { type Browser, type CDPSession, type Page, type Protocol } from "puppeteer-core";
 import { type RawAuthoredTiming } from "@hyperframes/core";
 import { type MotionBlurPlan } from "./motionBlur.js";
 import { type BrowserLease, type CaptureMode } from "./browserManager.js";
@@ -429,6 +429,7 @@ export interface IsolatedComposition {
     compositionId: string;
     elementId: string | null;
 }
+export declare function authorScriptsMayRegisterTimelines(runtimeAttr: string, authoredBegin: string, authoredEnd: string): Promise<boolean>;
 export interface SubTimelinePollOptions {
     intervalMs?: number;
     getScriptLoadFailures?: () => readonly string[];
@@ -467,6 +468,8 @@ export declare function classifyConsoleScriptError(type: string, text: string):
 export declare function classifyConsoleScriptFailure(type: string, text: string): string | null;
 /** `runtime-error:<first line>` when a script served with the composition threw; null if not attributable to one. */
 export declare function classifyPageError(details: Protocol.Runtime.ExceptionDetails, projectScripts: ReadonlySet<string>): string | null;
+/** ` [thrown at: <url>:<line>:<col>, <lookup>]` for a throw's authored frame, so the author can find the element. */
+export declare function describeThrowSite(client: CDPSession, details: Protocol.Runtime.ExceptionDetails, projectScripts: ReadonlySet<string>): Promise<string>;
 export declare function initializeSession(session: CaptureSession): Promise<void>;
 /**
  * Internal helper: seek timeline and inject video frames.

package/dist/services/frameCapture.js

@@ -9,7 +9,7 @@
  */
 import { existsSync, mkdirSync, writeFileSync } from "fs";
 import { join } from "path";
-import { COMPOSITION_SOURCE_URL, MEDIA_RENDER_ID_ATTR, quantizeSeekTime, quantizeTimeToFrame, fpsToNumber, resolveAuthoredTimingWindow, SCENE_CALLBACK_ERROR_PREFIX, } from "@hyperframes/core";
+import { COMPOSITION_SOURCE_URL, MEDIA_RENDER_ID_ATTR, quantizeSeekTime, quantizeTimeToFrame, fpsToNumber, resolveAuthoredTimingWindow, AUTHORED_SOURCE_BEGIN, AUTHORED_SOURCE_END, RUNTIME_BOOTSTRAP_ATTR, SCENE_CALLBACK_ERROR_PREFIX, } from "@hyperframes/core";
 import { holdRenderFrameVideos } from "./renderFrameVideoHold.js";
 import { DrawElementCaptureError } from "./drawElementCaptureError.js";
 import { encodePng } from "../utils/alphaBlit.js";
@@ -1361,6 +1361,50 @@ export async function waitForSubCompositionTimelines(session, page, timeoutMs, o
         memo.unregisteredIds = session.pendingTimelineIds ?? [];
     }
 }
+// Runs in the page. False once every inline, template and same-origin script is read and none
+// mentions __timelines or imports code; an unreadable or module script, or a page still loading, answers true.
+export async function authorScriptsMayRegisterTimelines(runtimeAttr, authoredBegin, authoredEnd) {
+    if (document.readyState !== "complete")
+        return true;
+    const memo = globalThis;
+    memo.__hfAuthorScan ??= await (async () => {
+        const scripts = [
+            ...Array.from(document.querySelectorAll("script")),
+            ...Array.from(document.querySelectorAll("template")).flatMap((t) => Array.from(t.content.querySelectorAll("script"))),
+        ].filter((script) => !script.hasAttribute(runtimeAttr));
+        // Code that imports another file may register through it, which is not read here.
+        const mayRegister = (code) => code.includes("__timelines") || /\bimport\s*\(|^\s*import\s*[\w{*"']/m.test(code);
+        for (const script of scripts) {
+            if (script.type === "module")
+                return true;
+            if (!script.src) {
+                const text = script.textContent ?? "";
+                const authored = text.includes(authoredBegin)
+                    ? text
+                        .split(authoredBegin)
+                        .slice(1)
+                        .map((region) => region.split(authoredEnd)[0])
+                        .join("\n")
+                    : text;
+                if (mayRegister(authored))
+                    return true;
+                continue;
+            }
+            const url = new URL(script.src, location.href);
+            if (url.origin !== location.origin)
+                return true;
+            try {
+                if (mayRegister(await (await fetch(url)).text()))
+                    return true;
+            }
+            catch {
+                return true;
+            }
+        }
+        return false;
+    })();
+    return memo.__hfAuthorScan;
+}
 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
@@ -1386,15 +1430,19 @@ export async function pollSubCompositionTimelines(page, timeoutMs, { intervalMs
     // 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));
+        const failures = getScriptLoadFailures?.() ?? [];
+        const errors = getPageErrors?.() ?? [];
+        const failed = failures.length > 0 ? failures : errors;
+        // A failed script keeps the wait, so the failure is still named; only a quiet page is ready early.
+        ready =
+            Boolean(await page.evaluate(expression)) ||
+                (failed.length === 0 &&
+                    !(await page.evaluate(authorScriptsMayRegisterTimelines, RUNTIME_BOOTSTRAP_ATTR, AUTHORED_SOURCE_BEGIN, AUTHORED_SOURCE_END)));
         if (ready || shouldStop?.())
             break;
         const now = Date.now();
         if (now >= deadline)
             break;
-        const failures = getScriptLoadFailures?.() ?? [];
-        const errors = getPageErrors?.() ?? [];
-        const failed = failures.length > 0 ? failures : errors;
         const graceMs = failures.length > 0 ? scriptFailureGraceMs : scriptErrorGraceMs;
         if (failed.length > 0)
             errorSeenAt ??= now;
@@ -1839,10 +1887,41 @@ export function classifyPageError(details, projectScripts) {
     if (frames.length === 0 && details.text.startsWith("Uncaught (in promise)"))
         return null;
     const urls = frames.length > 0 ? frames : [details.url];
-    // The render compiler names the composition's inline code.
-    // Inline handlers report the document, which a widget can move.
-    const owned = (url) => url !== undefined && (projectScripts.has(url) || url.startsWith(COMPOSITION_SOURCE_URL));
-    return urls.some(owned) ? `runtime-error:${firstLine}` : null;
+    return urls.some((url) => isOwnedScriptUrl(url, projectScripts))
+        ? `runtime-error:${firstLine}`
+        : null;
+}
+// The render compiler names the composition's inline code.
+// Inline handlers report the document, which a widget can move.
+function isOwnedScriptUrl(url, projectScripts) {
+    return url !== undefined && (projectScripts.has(url) || url.startsWith(COMPOSITION_SOURCE_URL));
+}
+const LOOKUP_CALL = /\b(?:getElementById|querySelectorAll|querySelector|getElementsByClassName|getElementsByTagName)\(\s*(["'`])((?:(?!\1).)*)\1/g;
+/** ` [thrown at: <url>:<line>:<col>, <lookup>]` for a throw's authored frame, so the author can find the element. */
+export async function describeThrowSite(client, details, projectScripts) {
+    const frame = (details.stackTrace?.callFrames ?? []).find((f) => isOwnedScriptUrl(f.url, projectScripts));
+    if (!frame)
+        return "";
+    let where = `${frame.url}:${frame.lineNumber + 1}:${frame.columnNumber + 1}`;
+    try {
+        // Source is only fetchable with the debugger on; enabling after the fact keeps script ids.
+        await client.send("Debugger.enable");
+        const { scriptSource } = await client.send("Debugger.getScriptSource", {
+            scriptId: frame.scriptId,
+        });
+        const line = scriptSource.split("\n")[frame.lineNumber] ?? "";
+        const lookups = [...line.matchAll(LOOKUP_CALL)];
+        // Only a lone lookup is certain to be the one that returned null; with several the position alone is given.
+        if (lookups.length === 1)
+            where += `, ${lookups[0]?.[0]})`;
+    }
+    catch {
+        // Source unavailable: line:col alone still locates the throw.
+    }
+    finally {
+        await client.send("Debugger.disable").catch(() => undefined);
+    }
+    return ` [thrown at: ${where}]`;
 }
 export async function initializeSession(session) {
     const { page, serverUrl } = session;
@@ -1913,7 +1992,20 @@ export async function initializeSession(session) {
     // Unlike the pageerror Error, this keeps the script URL of syntax errors and thrown non-errors.
     const runtimeClient = await getCdpSession(page);
     runtimeClient.on("Runtime.exceptionThrown", ({ exceptionDetails }) => {
-        recordPageError(session, classifyPageError(exceptionDetails, projectScripts));
+        const error = classifyPageError(exceptionDetails, projectScripts);
+        recordPageError(session, error);
+        if (!error)
+            return;
+        // Recorded first so fail-fast sees it; the throw site is appended once the source is fetched.
+        void describeThrowSite(runtimeClient, exceptionDetails, projectScripts).then((site) => {
+            const i = session.pageErrors.indexOf(error);
+            if (!site || i < 0)
+                return;
+            if (session.pageErrors.includes(`${error}${site}`))
+                session.pageErrors.splice(i, 1);
+            else
+                session.pageErrors[i] = `${error}${site}`;
+        });
     });
     await runtimeClient.send("Runtime.enable");
     const pageNavigationTimeout = session.config?.pageNavigationTimeout ?? DEFAULT_CONFIG.pageNavigationTimeout;
@@ -3337,8 +3429,8 @@ async function captureAccumulatedFrame(session, frameIndex, absFrameIndex, plan)
     await seekPageTimeline(session.page, frameTime, undefined);
     const totals = { seekMs: Date.now() - eventfulSeekStart, beforeCaptureMs: 0, screenshotMs: 0 };
     if (session.onBeforeCapture) {
-        // The injector copies a video's own style only when its frame changes: inject at frameTime
-        // first so the held frame carries frameTime's style, not the first sample's.
+        // Sub-samples leave a video's style alone: inject at frameTime first so the held frame
+        // carries frameTime's style, not the first sample's.
         const injectStart = Date.now();
         session.captureStep = "injecting video frames";
         await session.onBeforeCapture(session.page, frameTime, frameTime);

package/dist/services/hdrCapture.js

@@ -19,7 +19,7 @@
  * Performance: ~6 fps at 1080x1920 via base64 transfer.
  */
 import { withHyperframesBrowserMarker } from "@hyperframes/core/browser-marker";
-import { resolveFullChromePath, sigintLaunchOptions } from "./browserManager.js";
+import { resolveFullChromePath, ownedLaunchOptions } from "./browserManager.js";
 // ── PQ (SMPTE 2084) OETF ─────────────────────────────────────────────────────
 const PQ_M1 = 0.1593017578125;
 const PQ_M2 = 78.84375;
@@ -181,7 +181,7 @@ export async function launchHdrBrowser(width, height) {
         throw new Error("[HDR] No Chrome binary found. Install: npx @puppeteer/browsers install chrome@stable");
     }
     const browser = await ppt.launch({
-        ...sigintLaunchOptions(),
+        ...ownedLaunchOptions(),
         headless: false,
         executablePath: chromePath,
         args: withHyperframesBrowserMarker(buildHdrChromeArgs(width, height)),

package/dist/services/screenshotService.d.ts

@@ -194,9 +194,11 @@ export declare function ensureRenderFrameSiblings(page: Page): Promise<void>;
  * cache entry for a frame that never reached the page, which would otherwise
  * short-circuit the next inject at the same frameIndex and leave the host's
  * first visible frame blank.
+ *
+ * `restyleIds` keep their current picture and only re-copy the video's style.
  */
 export declare function injectVideoFramesBatch(page: Page, updates: Array<{
     videoId: string;
     dataUri: string;
-}>): Promise<string[]>;
+}>, restyleIds?: readonly string[]): Promise<string[]>;
 export declare function syncVideoFrameVisibility(page: Page, activeVideoIds: string[]): Promise<void>;

package/dist/services/screenshotService.js

@@ -548,13 +548,21 @@ export async function ensureRenderFrameSiblings(page) {
  * cache entry for a frame that never reached the page, which would otherwise
  * short-circuit the next inject at the same frameIndex and leave the host's
  * first visible frame blank.
+ *
+ * `restyleIds` keep their current picture and only re-copy the video's style.
  */
-export async function injectVideoFramesBatch(page, updates) {
-    if (updates.length === 0)
+export async function injectVideoFramesBatch(page, updates, restyleIds = []) {
+    if (updates.length === 0 && restyleIds.length === 0)
         return [];
-    return withVideoFrameSources(page, updates, (resolved) => injectResolvedVideoFramesBatch(page, resolved));
+    return withVideoFrameSources(page, updates, (resolved) => injectResolvedVideoFramesBatch(page, resolved, restyleIds));
 }
-async function injectResolvedVideoFramesBatch(page, updates) {
+async function injectResolvedVideoFramesBatch(page, updates, restyleIds) {
+    // Build the sibling id with core's function rather than a template here,
+    // so the id the readers look up has exactly one definition.
+    const items = [
+        ...updates,
+        ...restyleIds.map((videoId) => ({ videoId })),
+    ].map((item) => ({ ...item, frameId: renderFrameIdForRenderId(item.videoId) }));
     return await page.evaluate(
     // fallow-ignore-next-line complexity
     async (items, visualProperties, colorGradingSourceHiddenAttr) => {
@@ -615,6 +623,9 @@ async function injectResolvedVideoFramesBatch(page, updates) {
                 continue;
             let img = video.nextElementSibling;
             const hasImg = img !== null && img.classList.contains("__render_frame__");
+            const restyleOnly = item.dataUri === undefined;
+            if (restyleOnly && !hasImg)
+                continue;
             if (isVisualAncestorHidden(video)) {
                 // Don't paint a frame over a hidden host — if an existing replacement
                 // <img> is still around from when the host was visible, hide it so it
@@ -700,7 +711,7 @@ async function injectResolvedVideoFramesBatch(page, updates) {
             // 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.dataUri !== undefined && img.getAttribute("src") !== item.dataUri) {
                 if (item.crossOrigin)
                     img.crossOrigin = item.crossOrigin;
                 else
@@ -718,23 +729,21 @@ async function injectResolvedVideoFramesBatch(page, updates) {
             // GSAP-controlled value.
             video.style.setProperty("visibility", "hidden", "important");
             video.style.setProperty("pointer-events", "none", "important");
-            injectedIds.push(item.videoId);
+            if (!restyleOnly)
+                injectedIds.push(item.videoId);
         }
         if (pendingDecodes.length > 0) {
             await Promise.all(pendingDecodes);
         }
         for (const img of imagesToPublish)
             img.style.visibility = "visible";
-        if (injectedIds.length > 0) {
+        if (imagesToPublish.length > 0) {
             const redraw = window
                 .__hf?.colorGrading?.redraw;
             redraw?.();
         }
         return injectedIds;
-    }, 
-    // Build the sibling id with core's function rather than a template here,
-    // so the id the readers look up has exactly one definition.
-    updates.map((update) => ({ ...update, frameId: renderFrameIdForRenderId(update.videoId) })), [...MEDIA_VISUAL_STYLE_PROPERTIES], COLOR_GRADING_SOURCE_HIDDEN_ATTR);
+    }, items, [...MEDIA_VISUAL_STYLE_PROPERTIES], COLOR_GRADING_SOURCE_HIDDEN_ATTR);
 }
 export async function syncVideoFrameVisibility(page, activeVideoIds) {
     await page.evaluate(

package/dist/services/videoFrameExtractor.d.ts

@@ -258,6 +258,7 @@ export interface ImageElement {
     end: number;
 }
 export declare function parseImageElements(html: string): ImageElement[];
+export declare function sdrCanvasColourFilters(metadata: VideoMetadata, toneMappedToSdr?: boolean): string[];
 export declare function extractVideoFramesRange(...args: Parameters<typeof extractVideoFramesRangeUnredacted>): Promise<ExtractedFrames>;
 declare function extractVideoFramesRangeUnredacted(videoPath: string, videoId: string, startTime: number, duration: number, options: ExtractionOptions, signal?: AbortSignal, config?: Partial<Pick<EngineConfig, "ffmpegProcessTimeout">>, 
 /** Frames go straight here, with no per-videoId subdir (the cache layer's keyed entry). */

package/dist/services/videoFrameExtractor.js

@@ -14,7 +14,7 @@ import { parseHTML } from "linkedom";
 import { isPathInside } from "@hyperframes/parsers/asset-paths";
 import { resolveProjectRelativeSrc } from "@hyperframes/parsers/asset-resolution";
 import { alphaDecoderFor } from "@hyperframes/parsers/media-alpha";
-import { MEDIA_RENDER_ID_ATTR, isAudibleVideoElement, fpsToFfmpegArg, fpsToNumber, MEDIA_DURATION_CLAMP_EPSILON_SECONDS, normalizeRateSpec, readElementRateSpec, shiftRateLane, sourceTimeAt, timeAtSourceTime, exportClipWindow, hasClipStarted, isInClipWindow, parseStrictFiniteTimingNumber, readMediaStart, toFps, firstFrameColourArgs, hdrToSdrToneMapFilter, parseFirstFrameColour, } from "@hyperframes/core";
+import { MEDIA_RENDER_ID_ATTR, isAudibleVideoElement, fpsToFfmpegArg, fpsToNumber, MEDIA_DURATION_CLAMP_EPSILON_SECONDS, normalizeRateSpec, readElementRateSpec, shiftRateLane, sourceTimeAt, timeAtSourceTime, exportClipWindow, hasClipStarted, isInClipWindow, mediaElementTime, parseStrictFiniteTimingNumber, readMediaStart, toFps, firstFrameColourArgs, hdrToSdrToneMapFilter, parseFirstFrameColour, } from "@hyperframes/core";
 import { resolveReferencedStart } from "./referenceResolver.js";
 import { isKnownInactiveTimelineWindow } from "./mediaTimelineWindow.js";
 import { extractFinalVideoFrameTimestamp, extractMediaMetadata, mediaFileIdentity, readMetadataCache, readStoredFinalFrame, resolvePlayableVideoDuration, writeMetadataCache, } from "../utils/ffprobe.js";
@@ -477,6 +477,12 @@ function chromeGuessForUntaggedMatrix(metadata) {
     const hd = metadata.height >= 720 && !CHROME_BT601_UNTAGGED_CODECS.has(metadata.videoCodec);
     return [`setparams=colorspace=${hd ? "bt709" : "smpte170m"}`];
 }
+export function sdrCanvasColourFilters(metadata, toneMappedToSdr = false) {
+    if (!isHdrColorSpaceUtil(metadata.colorSpace)) {
+        return [...chromeGuessForUntaggedMatrix(metadata), SDR_CANVAS_PASSTHROUGH_FILTER];
+    }
+    return toneMappedToSdr ? [SDR_CANVAS_PASSTHROUGH_FILTER] : [];
+}
 /**
  * Longest stretch of output one ffmpeg process extracts; longer ranges split into segments
  * that run side by side. Segments sample the same absolute times as a single pass, so their
@@ -678,7 +684,7 @@ outputDirOverride) {
         vfFilters.push(hdrToSdrToneMapFilter(metadata.colorSpace ?? {}, frameColour));
     }
     if (toneMappedToSdr || (!isHdr && !options.sdrToHdrTransfer)) {
-        vfFilters.push(...(isHdr ? [] : chromeGuessForUntaggedMatrix(metadata)), SDR_CANVAS_PASSTHROUGH_FILTER);
+        vfFilters.push(...sdrCanvasColourFilters(metadata, toneMappedToSdr));
         if (format === "jpg") {
             if (options.shownBox)
                 vfFilters.push(halveToCoverScaleFilter(options.shownBox));
@@ -1832,9 +1838,9 @@ function getFrameIndexAtTime(extracted, globalTime, videoStart, loop = false, me
         if (cycle > 0 && sourceTime >= cycle)
             sourceTime %= cycle;
     }
-    // Add epsilon before flooring to avoid IEEE 754 boundary errors where
-    // e.g. 0.28 * 25 === 6.999999999999999 instead of 7.
-    const frameIndex = Math.floor(sourceTime * extracted.fps + 1e-9);
+    // The frame the preview's <video> shows at this source time, so render and preview pick the same one.
+    const shownTime = mediaElementTime(mediaStart + sourceTime) - mediaStart;
+    const frameIndex = Math.floor(shownTime * extracted.fps);
     if (frameIndex < 0 || extracted.totalFrames <= 0)
         return null;
     if (isVideoHiddenBeforeStreamStart(extracted.metadata.videoStreamLeadSeconds, mediaStart + sourceTime)) {

package/dist/services/videoFrameInjector.js

@@ -159,14 +159,19 @@ export function createVideoFrameInjector(frameLookup, config) {
             }
         }
         const updates = [];
+        const restyleIds = [];
         const activeIds = new Set();
+        const isBlurSubSample = heldVideoTime !== undefined && heldVideoTime !== time;
         if (activePayloads.size > 0) {
             const pendingReads = [];
             for (const [videoId, payload] of activePayloads) {
                 activeIds.add(videoId);
                 const lastFrameIndex = lastInjectedFrameByVideo.get(videoId);
-                if (lastFrameIndex === payload.frameIndex)
+                if (lastFrameIndex === payload.frameIndex) {
+                    if (!isBlurSubSample)
+                        restyleIds.push(videoId);
                     continue;
+                }
                 pendingReads.push(frameCache
                     .get(payload.framePath)
                     .then((dataUri) => ({ videoId, dataUri, frameIndex: payload.frameIndex })));
@@ -179,14 +184,14 @@ export function createVideoFrameInjector(frameLookup, config) {
             }
         }
         await syncVideoFrameVisibility(page, Array.from(activeIds));
-        if (updates.length > 0) {
+        if (updates.length > 0 || restyleIds.length > 0) {
             // Only record cache entries for videos the page actually painted.
             // injectVideoFramesBatch skips any video whose visual ancestor is
             // hidden (sub-comp host out-of-window) and returns the subset of ids
             // it really wrote — recording the rest would short-circuit the next
             // call at the same frameIndex and leave the host's first visible
             // frame blank.
-            const injectedIds = new Set(await injectVideoFramesBatch(page, updates.map((u) => ({ videoId: u.videoId, dataUri: u.dataUri }))));
+            const injectedIds = new Set(await injectVideoFramesBatch(page, updates.map((u) => ({ videoId: u.videoId, dataUri: u.dataUri })), restyleIds));
             for (const update of updates) {
                 if (injectedIds.has(update.videoId)) {
                     lastInjectedFrameByVideo.set(update.videoId, update.frameIndex);

package/dist/utils/ffprobe.d.ts

@@ -1,3 +1,8 @@
+/** Spawn ffprobe with given args, return stdout. Throws on non-zero exit or missing binary. */
+export declare function runFfprobe(filePath: string, argsWithoutInput: string[], signal?: AbortSignal, stdoutOptions?: {
+    retainTail?: boolean;
+    maxChars?: number;
+}): Promise<string>;
 export interface MediaProbeCacheEntry<T = FFProbeOutput> {
     identity: string | null;
     promise: Promise<T>;

package/dist/utils/ffprobe.js

@@ -49,7 +49,7 @@ function sanitizeFfprobeDiagnostic(stderr, filePath) {
     return `…${redacted.slice(-(FFPROBE_ERROR_MAX_CHARS - 1))}`;
 }
 /** Spawn ffprobe with given args, return stdout. Throws on non-zero exit or missing binary. */
-async function runFfprobe(filePath, argsWithoutInput, signal, stdoutOptions) {
+export async function runFfprobe(filePath, argsWithoutInput, signal, stdoutOptions) {
     // `--` stops option parsing so a path like "-intro.mp4" is a filename, but
     // it does NOT cover a path of exactly "-": ffprobe rewrites that to `fd:`
     // AFTER option parsing and then reads stdin. Since stdin here is a pipe the

package/package.json

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