@hyperframes/engine 0.8.197 → 0.8.199

package/dist/index.d.ts

@@ -38,7 +38,7 @@ export { chromeMajorCeiling } from "./services/chromeHostCeiling.js";
 export { acquireBrowser, setHostHandlesSigint, releaseBrowser, drainBrowserPool, closeBrowserPool, resolveHeadlessShellPath, resolveBrowserGpuMode, buildChromeArgs, compositionRequiresWebGpu, assertWebGpuAdapterAvailable, usesSoftwareWebGpu, WebGpuUnavailableError, ENABLE_BROWSER_POOL, BrowserLeasePool, type GpuProbeLifecycle, type BuildChromeArgsOptions, type BrowserLaunchFingerprint, type BrowserLease, type BrowserPoolState, type CaptureMode, type AcquiredBrowser, } from "./services/browserManager.js";
 export { augmentProtocolTimeoutError, isProtocolTimeoutError, } from "./services/protocolTimeoutErrorHint.js";
 export { augmentPageNavigationTimeoutError, isPageNavigationTimeoutError, type NavigationTimeoutHintContext, } from "./services/pageNavigationTimeoutErrorHint.js";
-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 { 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, evaluateHfDiagnostic, buildZeroDurationDiagnostic, } 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";
@@ -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, 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, } from "./services/videoFrameExtractor.js";
 export { directorySizeBytes, gcExtractionCache } from "./services/extractionCache.js";
 export { resolveReferencedStart, resolveReferencedDuration, type RefResolverEl, type RefResolverDoc, } from "./services/referenceResolver.js";
 export { createVideoFrameInjector } from "./services/videoFrameInjector.js";

package/dist/index.js

@@ -40,7 +40,7 @@ export { acquireBrowser, setHostHandlesSigint, releaseBrowser, drainBrowserPool,
 export { augmentProtocolTimeoutError, isProtocolTimeoutError, } from "./services/protocolTimeoutErrorHint.js";
 export { augmentPageNavigationTimeoutError, isPageNavigationTimeoutError, } from "./services/pageNavigationTimeoutErrorHint.js";
 // ── Frame capture pipeline ──────────────────────────────────────────────────────
-export { createCaptureSession, initializeSession, closeCaptureSession, captureFrame, captureFrameToBuffer, captureFrameToBufferPipelined, captureFramesBatchPipelined, DrawElementVerificationError, isDrawElementVerificationError, getDrawElementVerificationDetails, recaptureDrawElementFrameForVerify, completeDeferredDrawElementInit, writeCapturedFrame, discardWarmupCapture, getCompositionDuration, getCapturePerfSummary, percentileOf, prepareCaptureSessionForReuse, deriveBeginFrameProbeTimeTicks, isTransientBrowserError, isMemoryExhaustionError, VfxFailureError, waitForImagesReady, } from "./services/frameCapture.js";
+export { createCaptureSession, initializeSession, closeCaptureSession, captureFrame, captureFrameToBuffer, captureFrameToBufferPipelined, captureFramesBatchPipelined, DrawElementVerificationError, isDrawElementVerificationError, getDrawElementVerificationDetails, recaptureDrawElementFrameForVerify, completeDeferredDrawElementInit, writeCapturedFrame, discardWarmupCapture, getCompositionDuration, getCapturePerfSummary, percentileOf, prepareCaptureSessionForReuse, deriveBeginFrameProbeTimeTicks, isTransientBrowserError, isMemoryExhaustionError, VfxFailureError, waitForImagesReady, evaluateHfDiagnostic, buildZeroDurationDiagnostic, } from "./services/frameCapture.js";
 export { CaptureFailure, classifyCaptureFailure, isFatalCaptureFailure, } from "./services/captureFailure.js";
 export { createChromeMemorySampler, } from "./services/chromeMemorySampler.js";
 // ── Screenshot (BeginFrame) ─────────────────────────────────────────────────────
@@ -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, 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, } from "./services/videoFrameExtractor.js";
 export { directorySizeBytes, gcExtractionCache } from "./services/extractionCache.js";
 export { resolveReferencedStart, resolveReferencedDuration, } from "./services/referenceResolver.js";
 export { createVideoFrameInjector } from "./services/videoFrameInjector.js";

package/dist/services/frameCapture.d.ts

@@ -410,6 +410,7 @@ export interface HfDiagnostic {
     rejectedBuildReadyKeys: string[];
 }
 export declare function buildZeroDurationDiagnostic(diag: HfDiagnostic): string;
+export declare function evaluateHfDiagnostic(page: Page): Promise<HfDiagnostic>;
 export declare function pollHfReady(page: Page, timeoutMs: number, intervalMs?: number): Promise<void>;
 export declare function waitForSubCompositionTimelines(session: CaptureSession, page: Page, timeoutMs: number, options?: {
     scriptErrorGraceMs?: number;
@@ -760,6 +761,8 @@ export declare function getCompositionDuration(session: CaptureSession): Promise
  * timeline passed verification while the drained output bottomed at 30.9 dB.
  */
 export declare function computeDeVerifySampleFractions(k: number): number[];
+/** Seeks the page the truth is read from; callbacks run unless suppressed (suppressed, a count-up's text is stale). */
+export declare function seekDeVerifyTruth(page: Page, t: number, suppressEvents: boolean): Promise<void>;
 /**
  * Percentile of a positive-real sample set (nearest-rank; matches how the
  * existing {@link medianOf} p50 helper picks the middle index). `p` is a

package/dist/services/frameCapture.js

@@ -1131,7 +1131,7 @@ export function buildZeroDurationDiagnostic(diag) {
         `data-duration: ${diag.declaredDuration > 0 ? diag.declaredDuration + "s" : "not set"}\n` +
         (hints.length > 0 ? hints.map((h) => `  → ${h}`).join("\n") : ""));
 }
-async function evaluateHfDiagnostic(page) {
+export async function evaluateHfDiagnostic(page) {
     return (await page.evaluate(HF_READY_DIAGNOSTIC_EXPR));
 }
 export async function pollHfReady(page, timeoutMs, intervalMs = 100) {
@@ -3774,6 +3774,14 @@ export function computeDeVerifySampleFractions(k) {
         return [0.95];
     return [...Array.from({ length: k - 1 }, (_, i) => (i + 1) / k), 0.95];
 }
+/** Seeks the page the truth is read from; callbacks run unless suppressed (suppressed, a count-up's text is stale). */
+export async function seekDeVerifyTruth(page, t, suppressEvents) {
+    await page.evaluate((tt, suppress) => {
+        const hf = window.__hf;
+        if (hf && typeof hf.seek === "function")
+            hf.seek(tt, { suppressEvents: suppress });
+    }, t, suppressEvents);
+}
 async function captureDeVerificationFrames(session, page, logInitPhase) {
     // Explicit HF_DE_VERIFY wins; otherwise the session's own sample count
     // (raised by the parallel coordinator for multi-worker DE), then default 4.
@@ -3819,48 +3827,54 @@ async function captureDeVerificationFrames(session, page, logInitPhase) {
     // would share the corruption, PSNR would pass on the damaged output.
     // Seeking 0 → ascending reproduces the render's own seek order.
     const fractions = computeDeVerifySampleFractions(k);
-    const seekTo = async (t) => {
-        await page.evaluate((tt) => {
-            const hf = window.__hf;
-            if (hf && typeof hf.seek === "function")
-                hf.seek(tt, { suppressEvents: true });
-        }, t);
-    };
-    await seekTo(quantizeTimeToFrame(0, fps));
-    // Force one frame so lazy tween initialization paints at t=0 state.
-    await pageScreenshotCapture(page, session.options);
+    // A video-free comp reads its truth on a disposable page: callbacks that run there
+    // cannot leave the render's own page changed. The video injector is tied to the render page.
+    const disposable = session.onBeforeCapture
+        ? null
+        : await createStaticVerificationPage(session).catch(() => {
+            logInitPhase("self-verify truth page unavailable; reading it on the render page");
+            return null;
+        });
+    const isolated = disposable !== null;
+    const truthPage = disposable ?? page;
+    const seekTo = (t) => seekDeVerifyTruth(truthPage, t, !isolated);
     const frames = new Map();
-    for (const f of fractions) {
-        let idx = Math.min(totalFrames - 1, Math.max(1, Math.round(totalFrames * f)));
-        // Nudge off clip-cut boundaries (±1-frame desync is legitimate there);
-        // if the nudge saturates on a boundary index, skip the sample entirely.
-        let guard = 0;
-        while (boundary.has(idx) && guard++ < 6)
-            idx = Math.min(totalFrames - 1, idx + 2);
-        if (boundary.has(idx))
-            continue;
-        if (frames.has(idx))
-            continue;
-        const t = quantizeTimeToFrame(idx / fps, fps);
-        await seekTo(t);
-        // Video frame injection (same hook the real capture paths run) — without
-        // it, <video> elements screenshot black and every video comp would
-        // false-positive into the screenshot fallback.
-        if (session.onBeforeCapture)
-            await session.onBeforeCapture(page, t);
-        // Double-capture: the first screenshot forces a frame, which is what runs
-        // rAF-driven callbacks (count-up text counters land a tick after seek()
-        // returns — a single immediate screenshot captures stale text and
-        // false-positives the verify: 3bea8c73 28.7dB vs a truth missing its stat
-        // values while the DE frame was correct). NOTE: waiting on rAF via
-        // evaluate instead deadlocks — headless only fires rAF when a frame is
-        // produced, and nothing produces one until a screenshot asks.
-        await pageScreenshotCapture(page, session.options);
-        frames.set(idx, await pageScreenshotCapture(page, session.options));
-    }
-    // Leave the page at frame 0 so the render's first seek starts from the
-    // same state as an unverified render.
-    await seekTo(quantizeTimeToFrame(0, fps));
+    try {
+        await seekTo(quantizeTimeToFrame(0, fps));
+        // Force one frame so lazy tween initialization paints at t=0 state.
+        await pageScreenshotCapture(truthPage, session.options);
+        for (const f of fractions) {
+            let idx = Math.min(totalFrames - 1, Math.max(1, Math.round(totalFrames * f)));
+            // Nudge off clip-cut boundaries (±1-frame desync is legitimate there);
+            // if the nudge saturates on a boundary index, skip the sample entirely.
+            let guard = 0;
+            while (boundary.has(idx) && guard++ < 6)
+                idx = Math.min(totalFrames - 1, idx + 2);
+            if (boundary.has(idx))
+                continue;
+            if (frames.has(idx))
+                continue;
+            const t = quantizeTimeToFrame(idx / fps, fps);
+            await seekTo(t);
+            // Video frame injection (same hook the real capture paths run) — without
+            // it, <video> elements screenshot black and every video comp would
+            // false-positive into the screenshot fallback.
+            if (session.onBeforeCapture)
+                await session.onBeforeCapture(truthPage, t);
+            // The first screenshot forces a frame, which runs rAF-driven callbacks (a count-up lands
+            // a tick after seek()); waiting on rAF via evaluate deadlocks, headless fires it only
+            // when a frame is produced.
+            await pageScreenshotCapture(truthPage, session.options);
+            frames.set(idx, await pageScreenshotCapture(truthPage, session.options));
+        }
+        // The render's own page goes back to frame 0 so its first seek starts like an unverified render.
+        if (!isolated)
+            await seekTo(quantizeTimeToFrame(0, fps));
+    }
+    finally {
+        if (isolated)
+            await truthPage.close().catch(() => { });
+    }
     session.deVerifyFrames = frames;
     logInitPhase(`drawElement self-verify armed: ${frames.size} ground-truth frame(s) @ [${[...frames.keys()].join(", ")}] of ${totalFrames}`);
 }

package/package.json

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