@hyperframes/engine 0.8.219 → 0.8.221

package/dist/services/chromeStartup.js

@@ -83,8 +83,9 @@ export async function explainChromeLaunchFailure(error, executablePath, args, si
     const { code, errno, syscall } = error;
     if (code === "UNKNOWN" && syscall === "spawn")
         return new Error(`Windows refused to start the browser${executablePath ? ` at ${executablePath}` : ""} (error ${errno ?? "unknown"}, spawn UNKNOWN). ` +
-            "Security software may be blocking it, or the computer may be out of memory. " +
-            "Close other apps and retry; if it persists, run `hyperframes browser ensure --force` to download it again.", { cause: error });
+            "Windows Application Control or security software may be blocking it, or the computer may be out of memory. " +
+            "Close other apps and retry. If a policy blocks the file, allow that path or set HYPERFRAMES_BROWSER_PATH to a Chrome or Edge your policy allows; " +
+            "if the file is damaged, run `hyperframes browser ensure --force` to download it again.", { cause: error });
     if (!executablePath)
         return error;
     const diagnosis = await diagnoseChromeStartup(executablePath, args ?? [], { signal });

package/dist/services/frameCapture.d.ts

@@ -430,7 +430,7 @@ export interface IsolatedComposition {
     compositionId: string;
     elementId: string | null;
 }
-export declare function authorScriptsMayRegisterTimelines(runtimeAttr: string, authoredBegin: string, authoredEnd: string): Promise<boolean>;
+export declare function authorScriptsMayRegisterTimelines(runtimeAttr: string, authoredBegin: string, authoredEnd: string, skipIds?: readonly string[]): Promise<boolean>;
 export interface SubTimelinePollOptions {
     intervalMs?: number;
     getScriptLoadFailures?: () => readonly string[];

package/dist/services/frameCapture.js

@@ -1362,9 +1362,9 @@ 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) {
+// Runs in the page. False once every script is read and none can register an id still waited on;
+// an unreadable, module or importing script, a computed key, or a page still loading answers true.
+export async function authorScriptsMayRegisterTimelines(runtimeAttr, authoredBegin, authoredEnd, skipIds = []) {
     if (document.readyState !== "complete")
         return true;
     const memo = globalThis;
@@ -1373,38 +1373,66 @@ export async function authorScriptsMayRegisterTimelines(runtimeAttr, authoredBeg
             ...Array.from(document.querySelectorAll("script")),
             ...Array.from(document.querySelectorAll("template")).flatMap((t) => Array.from(t.content.querySelectorAll("script"))),
         ].filter((script) => !script.hasAttribute(runtimeAttr));
+        const scan = { opaque: false, mentions: false, ids: [] };
         // 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);
+        const mayImport = (code) => /\bimport\s*\(|^\s*import\s*[\w{*"']/m.test(code);
+        const read = (code) => {
+            if (mayImport(code))
+                scan.opaque = true;
+            if (!code.includes("__timelines"))
+                return;
+            scan.mentions = true;
+            const literalKey = /__timelines\s*(?:\[\s*(["'])((?:(?!\1).)+)\1\s*\]|\.([A-Za-z_$][\w$]*))/g;
+            const rest = code
+                .replace(/__timelines\s*=\s*(?:window\.__timelines\s*\|\|\s*)?\{\s*\}/g, "")
+                .replace(literalKey, (_m, _q, bracketId, dotId) => {
+                scan.ids.push(bracketId ?? dotId);
+                return "";
+            });
+            if (rest.includes("__timelines"))
+                scan.opaque = true;
+        };
         for (const script of scripts) {
             if (script.type === "module")
-                return true;
+                return { ...scan, opaque: true };
             if (!script.src) {
                 const text = script.textContent ?? "";
-                const authored = text.includes(authoredBegin)
+                read(text.includes(authoredBegin)
                     ? text
                         .split(authoredBegin)
                         .slice(1)
                         .map((region) => region.split(authoredEnd)[0])
                         .join("\n")
-                    : text;
-                if (mayRegister(authored))
-                    return true;
+                    : text);
                 continue;
             }
             const url = new URL(script.src, location.href);
             if (url.origin !== location.origin)
-                return true;
+                return { ...scan, opaque: true };
             try {
-                if (mayRegister(await (await fetch(url)).text()))
-                    return true;
+                read(await (await fetch(url)).text());
             }
             catch {
-                return true;
+                return { ...scan, opaque: true };
             }
         }
-        return false;
+        return scan;
     })();
-    return memo.__hfAuthorScan;
+    const { opaque, mentions, ids } = memo.__hfAuthorScan;
+    if (opaque)
+        return true;
+    if (!mentions)
+        return false;
+    const timelines = window.__timelines ?? {};
+    return Array.from(document.querySelectorAll("[data-composition-id]")).some((host) => {
+        const id = host.getAttribute("data-composition-id");
+        const authoredId = host.getAttribute("data-hf-original-composition-id") ?? id;
+        return (id &&
+            !host.hasAttribute("data-no-timeline") &&
+            !timelines[id] &&
+            !skipIds.includes(id) &&
+            ids.includes(authoredId ?? id));
+    });
 }
 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` —
@@ -1438,7 +1466,7 @@ export async function pollSubCompositionTimelines(page, timeoutMs, { intervalMs
         ready =
             Boolean(await page.evaluate(expression)) ||
                 (failed.length === 0 &&
-                    !(await page.evaluate(authorScriptsMayRegisterTimelines, RUNTIME_BOOTSTRAP_ATTR, AUTHORED_SOURCE_BEGIN, AUTHORED_SOURCE_END)));
+                    !(await page.evaluate(authorScriptsMayRegisterTimelines, RUNTIME_BOOTSTRAP_ATTR, AUTHORED_SOURCE_BEGIN, AUTHORED_SOURCE_END, knownUnregisteredIds)));
         if (ready || shouldStop?.())
             break;
         const now = Date.now();

package/dist/services/videoFrameExtractor.js

@@ -697,6 +697,9 @@ outputDirOverride) {
         vfFilters.push("format=nv12");
     }
     const samplingAt = vfFilters.length;
+    if (metadata.sampleAspectRatio) {
+        vfFilters.push("scale=trunc(iw*sar/2)*2:ih", "setsar=1");
+    }
     // Each slot takes the last frame starting at or before its time. Ticks of 2 ms or finer
     // first shift half a tick, absorbing container rounding (WebM/MKV use whole ms).
     const samplingFilters = (seek) => sampleAtOutputFps

package/dist/utils/ffprobe.d.ts

@@ -42,6 +42,7 @@ export interface VideoMetadata {
     colorSpace: VideoColorSpace | null;
     colorRange?: string;
     pixelFormat?: string;
+    sampleAspectRatio?: number;
     /** Decoded frame count from the video stream's `nb_frames`. Omitted when the
      * container does not surface a reliable count (still images, malformed
      * streams, or muxes that require `-count_packets` to populate). Callers
@@ -79,6 +80,7 @@ interface FFProbeStream {
     nb_frames?: string;
     nb_read_packets?: string;
     pix_fmt?: string;
+    sample_aspect_ratio?: string;
     r_frame_rate?: string;
     avg_frame_rate?: string;
     sample_rate?: string;
@@ -169,6 +171,7 @@ export declare function readTagCI(tags: Record<string, string | undefined> | und
  *    smallest representable 2dp rate instead.
  */
 export declare function parseFrameRate(frameRateStr: string | undefined): number;
+export declare function parseSampleAspectRatio(value: string | undefined): number | undefined;
 /**
  * Whether the first frame decoded with `decoder` (alpha-aware) has an alpha pixel format; undefined on any
  * failure. ffprobe cannot pick a decoder, so ffmpeg writes the frame as rawvideo, which keeps its pix_fmt.

package/dist/utils/ffprobe.js

@@ -629,6 +629,13 @@ export function parseFrameRate(frameRateStr) {
     // caller's 30fps default.
     return rounded > 0 ? rounded : 0.01;
 }
+export function parseSampleAspectRatio(value) {
+    const [num, den] = (value ?? "").split(":").map(Number);
+    if (!num || !den || !Number.isFinite(num) || !Number.isFinite(den))
+        return undefined;
+    const ratio = num / den;
+    return Math.abs(ratio - 1) < 1e-3 ? undefined : ratio;
+}
 /**
  * Whether the first frame decoded with `decoder` (alpha-aware) has an alpha pixel format; undefined on any
  * failure. ffprobe cannot pick a decoder, so ffmpeg writes the frame as rawvideo, which keeps its pix_fmt.
@@ -756,6 +763,7 @@ export async function extractMediaMetadata(filePath) {
         };
         const colorSpace = merged.colorTransfer || merged.colorPrimaries || merged.colorSpace ? merged : null;
         const pixelFormat = videoStream.pix_fmt || "";
+        const sampleAspectRatio = parseSampleAspectRatio(videoStream.sample_aspect_ratio);
         const hasAlpha = videoStreamHasAlpha(videoStream);
         const alphaDecoder = hasAlpha ? null : alphaDecoderFor(videoStream.codec_name);
         const alphaPlaneDecoded = alphaDecoder
@@ -808,6 +816,7 @@ export async function extractMediaMetadata(filePath) {
             colorSpace,
             colorRange: videoStream.color_range,
             pixelFormat,
+            ...(sampleAspectRatio === undefined ? {} : { sampleAspectRatio }),
             frames,
         };
     })();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/engine",
-  "version": "0.8.219",
+  "version": "0.8.221",
   "description": "Seekable web page to video rendering engine (Puppeteer + FFmpeg)",
   "repository": {
     "type": "git",
@@ -55,8 +55,8 @@
     "puppeteer": "~25.11.0",
     "puppeteer-core": "^25.11.0",
     "undici": "7.25.0",
-    "@hyperframes/parsers": "^0.8.219",
-    "@hyperframes/core": "^0.8.219"
+    "@hyperframes/core": "^0.8.221",
+    "@hyperframes/parsers": "^0.8.221"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",