@hyperframes/engine 0.9.8 → 0.9.9

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 CDPSession, type Page, type Protocol } from "puppeteer-core";
+import { type Browser, type CDPSession, type HTTPRequest, 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";
@@ -89,6 +89,8 @@ export interface CaptureSession {
      * were hitting that wall — a 705-render spike at the 45s setup bucket).
      */
     scriptLoadFailures: string[];
+    /** Closed origin and error of each of `scriptLoadFailures`, same order. */
+    scriptLoadCauses?: ScriptLoadCause[];
     /** Uncaught page errors; a timed-out timeline wait with any of these becomes a script failure. */
     pageErrors: string[];
     /** The first VFX chain error; its frames would lack the effect, so it stops the render. */
@@ -464,6 +466,15 @@ export declare class VfxFailureError extends Error {
     readonly detail: string;
     constructor(detail: string);
 }
+type ScriptLoadOrigin = "local" | "cdn" | "remote" | "unknown";
+export interface ScriptLoadCause {
+    origin: ScriptLoadOrigin;
+    /** `net::ERR_*`, `http-<status>` or `unknown`. */
+    code: string;
+}
+/** Where a failed script came from and why, never its URL, host or path. */
+export declare function classifyScriptLoadCause(url: string, serverUrl: string, failure: string | number): ScriptLoadCause;
+export declare function recordFailedRequest(session: CaptureSession, request: Pick<HTTPRequest, "resourceType" | "url" | "method" | "failure">): void;
 /** `runtime-error:<first line>` for the error a framework wrapper logs when a composition script throws. */
 export declare function classifyConsoleScriptError(type: string, text: string): string | null;
 export declare function classifyConsoleScriptFailure(type: string, text: string): string | null;

package/dist/services/frameCapture.js

@@ -1686,6 +1686,7 @@ export function recordSubTimelineWarning(session, timeoutMs) {
     const threwThenTimedOut = session.pageErrors.length > 0 && session.scriptLoadFailures.length === 0;
     const scriptFailure = isScriptFailure(session);
     const sources = [...session.scriptLoadFailures, ...session.pageErrors];
+    const loadCauses = session.scriptLoadCauses ?? [];
     const pending = session.pendingTimelineIds ?? [];
     const pendingSuffix = pending.length > 0 ? ` (still unregistered: ${pending.join(", ")})` : "";
     const isolated = session.isolatedCompositions ?? [];
@@ -1713,7 +1714,8 @@ export function recordSubTimelineWarning(session, timeoutMs) {
                     `${pendingSuffix} (${sources.join(", ")}). Fix the error; a composition animated by ` +
                     `CSS or rAF rather than a GSAP timeline must mark its host with data-no-timeline.`
                 : scriptFailure
-                    ? `A sub-composition timeline script failed to load (${sources.join(", ")})`
+                    ? `A sub-composition timeline script failed to load (${sources.join(", ")})` +
+                        scriptLoadCauseSuffix(loadCauses)
                     : `Sub-composition timelines did not become ready within ${timeoutMs}ms${pendingSuffix}. ` +
                         `This can be intentional: a composition driven by CSS animations or rAF never registers ` +
                         `window.__timelines[id], and marking its host with data-no-timeline skips the wait entirely. ` +
@@ -1891,11 +1893,44 @@ function recordPageError(session, error) {
 // (e.g. a `requestfailed` following the 4xx), and repeated <script> tags for
 // the same URL duplicate it further — dedupe so the fail-fast warning names
 // each failed URL once.
-function recordScriptLoadFailure(session, url) {
+function recordScriptLoadFailure(session, url, cause) {
     if (!session.scriptLoadFailures.includes(url)) {
         session.scriptLoadFailures.push(url);
+        (session.scriptLoadCauses ??= []).push(cause);
     }
 }
+const CDN_HOSTS = /^(?:cdn\.jsdelivr\.net|unpkg\.com|cdnjs\.cloudflare\.com)$/;
+/** Where a failed script came from and why, never its URL, host or path. */
+export function classifyScriptLoadCause(url, serverUrl, failure) {
+    let origin = "unknown";
+    if (url.startsWith(`${serverUrl}/`))
+        origin = "local";
+    else if (/^https?:\/\//.test(url)) {
+        origin = CDN_HOSTS.test(new URL(url).hostname) ? "cdn" : "remote";
+    }
+    const code = typeof failure === "number"
+        ? `http-${failure}`
+        : /^net::ERR_[A-Z0-9_]{1,40}$/.test(failure)
+            ? failure
+            : "unknown";
+    return { origin, code };
+}
+function scriptLoadCauseSuffix(causes) {
+    const shown = causes.slice(0, 4).map((c) => `${c.origin}/${c.code}`);
+    return shown.length === 0 ? "" : ` [script_load: ${shown.join(", ")}]`;
+}
+const CANCELLED_BY_THE_PAGE_NOT_REFUSED = "net::ERR_ABORTED";
+export function recordFailedRequest(session, request) {
+    const resourceType = request.resourceType();
+    const url = request.url();
+    const failureText = request.failure()?.errorText ?? "unknown";
+    if (resourceType === "script" && failureText !== CANCELLED_BY_THE_PAGE_NOT_REFUSED) {
+        recordScriptLoadFailure(session, url, classifyScriptLoadCause(url, session.serverUrl, failureText));
+    }
+    if (shouldIgnoreRequestFailureDiagnostic({ resourceType, url, failureText }))
+        return;
+    appendBrowserDiagnostic(session, formatRequestFailureDiagnostic({ method: request.method(), resourceType, url, failureText }));
+}
 const SCRIPT_ERROR_LABEL = "[HyperFrames] composition script error:";
 /** `runtime-error:<first line>` for the error a framework wrapper logs when a composition script throws. */
 export function classifyConsoleScriptError(type, text) {
@@ -1980,7 +2015,7 @@ export async function initializeSession(session) {
         // A blocked script can never register its timeline (#3352); a thrown one may still, so it only counts on timeout.
         const scriptFailure = classifyConsoleScriptFailure(type, text);
         if (scriptFailure)
-            recordScriptLoadFailure(session, scriptFailure);
+            recordScriptLoadFailure(session, scriptFailure, { origin: "unknown", code: "unknown" });
         recordConsoleScriptError(session, classifyConsoleScriptError(type, text));
     });
     page.on("pageerror", (err) => {
@@ -1991,22 +2026,7 @@ export async function initializeSession(session) {
             console.error(text);
         appendBrowserDiagnostic(session, text);
     });
-    page.on("requestfailed", (request) => {
-        const resourceType = request.resourceType();
-        const url = request.url();
-        const failureText = request.failure()?.errorText ?? "unknown";
-        if (resourceType === "script") {
-            recordScriptLoadFailure(session, request.url());
-        }
-        if (shouldIgnoreRequestFailureDiagnostic({ resourceType, url, failureText }))
-            return;
-        appendBrowserDiagnostic(session, formatRequestFailureDiagnostic({
-            method: request.method(),
-            resourceType,
-            url,
-            failureText,
-        }));
-    });
+    page.on("requestfailed", (request) => recordFailedRequest(session, request));
     const projectScripts = new Set();
     page.on("response", (response) => {
         const status = response.status();
@@ -2018,8 +2038,9 @@ export async function initializeSession(session) {
                 projectScripts.add(responseUrl);
             return;
         }
-        if (isScript)
-            recordScriptLoadFailure(session, responseUrl);
+        if (isScript) {
+            recordScriptLoadFailure(session, responseUrl, classifyScriptLoadCause(responseUrl, serverUrl, status));
+        }
         appendBrowserDiagnostic(session, formatHttpErrorDiagnostic({
             method: request.method(),
             resourceType: request.resourceType(),

package/package.json

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