@hyperframes/engine 0.8.203 → 0.8.205

package/dist/services/browserManager.d.ts

@@ -48,6 +48,7 @@ interface BeginFrameProbeResult {
     supported: boolean;
     detail: string;
     durationMs: number;
+    timedOut?: boolean;
 }
 declare function closeBrowserAfterFailedProbe(browser: Browser, timeoutMs?: number): Promise<void>;
 declare function probeBeginFrameSupport(browser: Browser, timeoutMs?: number): Promise<BeginFrameProbeResult>;

package/dist/services/browserManager.js

@@ -245,22 +245,25 @@ const BEGINFRAME_ONLY_FLAGS = new Set([
 function stripBeginFrameFlags(args) {
     return args.filter((a) => !BEGINFRAME_ONLY_FLAGS.has(a));
 }
+class BeginFrameProbeTimeout extends Error {
+}
 const BEGINFRAME_PROBE_TIMEOUT_MS = 2000;
+const BEGINFRAME_PROBE_RETRY_TIMEOUT_MS = 8000;
 const BEGINFRAME_PROBE_CLEANUP_TIMEOUT_MS = 250;
 async function awaitBeforeDeadline(operation, deadline, label) {
     const remainingMs = deadline - Date.now();
     if (remainingMs <= 0) {
-        throw new Error(`beginFrame probe timeout before ${label}`);
+        throw new BeginFrameProbeTimeout(`beginFrame probe timeout before ${label}`);
     }
-    return rejectAfter(operation, remainingMs, `beginFrame probe timeout during ${label}`);
+    return rejectAfter(operation, remainingMs, new BeginFrameProbeTimeout(`beginFrame probe timeout during ${label}`));
 }
-async function rejectAfter(operation, timeoutMs, message) {
+async function rejectAfter(operation, timeoutMs, error) {
     let timeout;
     try {
         return await Promise.race([
             operation,
             new Promise((_, reject) => {
-                timeout = setTimeout(() => reject(new Error(message)), timeoutMs);
+                timeout = setTimeout(() => reject(typeof error === "string" ? new Error(error) : error), timeoutMs);
             }),
         ]);
     }
@@ -345,7 +348,8 @@ async function probeBeginFrameSupport(browser, timeoutMs = BEGINFRAME_PROBE_TIME
             await awaitBeforeDeadline(new Promise((resolveDelay) => setTimeout(resolveDelay, 10)), deadline, `screenshot retry delay ${attempts}`);
         }
         if (!isPng) {
-            throw new Error(`beginFrame screenshot returned ${bytes.length} bytes after ` +
+            const Failure = bytes.length === 0 ? BeginFrameProbeTimeout : Error;
+            throw new Failure(`beginFrame screenshot returned ${bytes.length} bytes after ` +
                 `${attempts} attempts in ${Date.now() - started}ms with signature ` +
                 `${bytes.length >= 4 ? bytes.subarray(0, 4).toString("hex") : "<empty>"}`);
         }
@@ -362,6 +366,7 @@ async function probeBeginFrameSupport(browser, timeoutMs = BEGINFRAME_PROBE_TIME
             supported: false,
             detail: error instanceof Error ? error.message : String(error),
             durationMs: Date.now() - started,
+            timedOut: error instanceof BeginFrameProbeTimeout,
         };
     }
     if (page && !(await settleWithin(page.close(), BEGINFRAME_PROBE_CLEANUP_TIMEOUT_MS))) {
@@ -653,42 +658,43 @@ async function launchBrowser(fingerprint) {
     const env = launchEnv(fingerprint);
     let captureMode = fingerprint.requestedCaptureMode;
     let browser;
+    const launch = (args) => ppt.launch({
+        ...sigintLaunchOptions(),
+        headless: true,
+        args: withHyperframesBrowserMarker(args),
+        defaultViewport: null,
+        executablePath: fingerprint.executablePath,
+        env,
+        timeout: fingerprint.browserTimeoutMs,
+        protocolTimeout: fingerprint.protocolTimeoutMs,
+    });
+    const probe = (target, timeoutMs) => probeBeginFrameSupport(target, timeoutMs).catch((error) => ({
+        supported: true,
+        detail: `probe harness error ignored: ${error instanceof Error ? error.message : String(error)}`,
+        durationMs: 0,
+        timedOut: false,
+    }));
     try {
-        browser = await ppt.launch({
-            ...sigintLaunchOptions(),
-            headless: true,
-            args: withHyperframesBrowserMarker(fingerprint.args),
-            defaultViewport: null,
-            executablePath: fingerprint.executablePath,
-            env,
-            timeout: fingerprint.browserTimeoutMs,
-            protocolTimeout: fingerprint.protocolTimeoutMs,
-        });
+        browser = await launch(fingerprint.args);
         const browserVersion = await browser.version().catch(() => "unknown");
         const gpuFlags = fingerprint.args.filter((a) => a.startsWith("--use-gl=") || a.startsWith("--use-angle="));
         console.error(`[BrowserManager] Browser launched (${browserVersion}, ${captureMode}, gl=${gpuFlags.join(" ") || "default"}, headlessShell=${!!fingerprint.executablePath}, platform=${process.platform})`);
         if (captureMode === "beginframe") {
-            const probe = await probeBeginFrameSupport(browser).catch((error) => ({
-                supported: true,
-                detail: `probe harness error ignored: ${error instanceof Error ? error.message : String(error)}`,
-                durationMs: 0,
-            }));
-            if (!probe.supported) {
+            let result = await probe(browser);
+            if (!result.supported && result.timedOut) {
+                console.warn(`[BrowserManager] HeadlessExperimental.beginFrame probe timed out after ${result.durationMs}ms: ` +
+                    `${result.detail}; retrying once with a longer budget.`);
+                await closeBrowserAfterFailedProbe(browser);
+                browser = await launch(fingerprint.args);
+                result = await probe(browser, BEGINFRAME_PROBE_RETRY_TIMEOUT_MS);
+            }
+            if (!result.supported) {
                 await closeBrowserAfterFailedProbe(browser);
                 browser = undefined;
-                console.warn(`[BrowserManager] HeadlessExperimental.beginFrame probe failed after ${probe.durationMs}ms: ` +
-                    `${probe.detail}; falling back to screenshot mode.`);
+                console.warn(`[BrowserManager] HeadlessExperimental.beginFrame probe failed after ${result.durationMs}ms: ` +
+                    `${result.detail}; falling back to screenshot mode.`);
                 captureMode = "screenshot";
-                browser = await ppt.launch({
-                    ...sigintLaunchOptions(),
-                    headless: true,
-                    args: withHyperframesBrowserMarker(stripBeginFrameFlags([...fingerprint.args])),
-                    defaultViewport: null,
-                    executablePath: fingerprint.executablePath,
-                    env,
-                    timeout: fingerprint.browserTimeoutMs,
-                    protocolTimeout: fingerprint.protocolTimeoutMs,
-                });
+                browser = await launch(stripBeginFrameFlags([...fingerprint.args]));
             }
         }
         return { browser, captureMode };

package/dist/services/frameCapture.js

@@ -834,7 +834,6 @@ async function installMediaPageHooks(page, options) {
         await page.evaluateOnNewDocument(holdRenderFrameVideos, options.skipReadinessVideoIds, MEDIA_RENDER_ID_ATTR);
     }
 }
-// fallow-ignore-next-line unit-size
 export async function createCaptureSession(serverUrl, outputDir, options, onBeforeCapture = null, config) {
     if (!existsSync(outputDir))
         mkdirSync(outputDir, { recursive: true });
@@ -1845,7 +1844,6 @@ export function classifyPageError(details, projectScripts) {
     const owned = (url) => url !== undefined && (projectScripts.has(url) || url.startsWith(COMPOSITION_SOURCE_URL));
     return urls.some(owned) ? `runtime-error:${firstLine}` : null;
 }
-// fallow-ignore-next-line unit-size
 export async function initializeSession(session) {
     const { page, serverUrl } = session;
     // Forward browser console to host. HyperFrames runtime logs get a dedicated
@@ -3339,8 +3337,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);
@@ -3765,7 +3763,7 @@ export async function closeCaptureSession(session) {
         session.chromeMemory.stop();
         // One last sample so the summary reflects the session's end state, not a
         // point up to `intervalMs` earlier. Best effort; the page may be gone.
-        await session.chromeMemory.sampleOnce();
+        await waitForCloseWithTimeout(session.chromeMemory.sampleOnce());
     }
     if (session.page && !session.pageReleased) {
         const blur = await describePageMotionBlurAtEnd(session.page);

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

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