fix(engine): a render fails when a composition's own script throws before its timeline binds

packages/core/src/compiler/htmlDocument.test.ts

@@ -141,12 +141,15 @@ describe("htmlDocument helpers", () => {
     expect(stripEmbeddedRuntimeScripts(html)).toBe(html);
   });
 
+  const injectedTag = (code: string) =>
+    `<script>${code}\n//# sourceURL=hyperframes://injected/0</script>`;
+
   it("injects head and body scripts without replacement-token interpolation", () => {
     const html = "<html><head></head><body></body></html>";
     const injected = injectScriptsIntoHtml(html, ["window.x = '$&';"], ["window.y = '$&';"]);
 
-    expect(injected).toContain("<script>window.x = '$&';</script>\n</head>");
-    expect(injected).toContain("<script>window.y = '$&';</script>\n</body>");
+    expect(injected).toContain(`${injectedTag("window.x = '$&';")}\n</head>`);
+    expect(injected).toContain(`${injectedTag("window.y = '$&';")}\n</body>`);
   });
 
   it("injects early head scripts before authored head scripts", () => {
@@ -175,16 +178,16 @@ describe("htmlDocument helpers", () => {
     const injected = injectScriptsIntoHtml(html, ["window.h = 1;"], ["window.b = 1;"]);
 
     expect(injected.split(`<script>${vendor}</script>`)).toHaveLength(3);
-    expect(injected).toContain("<script>window.h = 1;</script>\n</HEAD >");
-    expect(injected).toContain("<script>window.b = 1;</script>\n</body></html>");
+    expect(injected).toContain(`${injectedTag("window.h = 1;")}\n</HEAD >`);
+    expect(injected).toContain(`${injectedTag("window.b = 1;")}\n</body></html>`);
   });
 
   it("falls back to the document's own <body> when </head> is omitted", () => {
     const vendor = 'w.print("<head>"),w.print("<body>")';
     const html = `<html><head><script>${vendor}</script><body><p>x</p></body></html>`;
     const injected = injectScriptsIntoHtml(html, ["window.h = 1;"], []);
 
-    expect(injected).toContain(`<script>${vendor}</script><script>window.h = 1;</script>\n<body>`);
+    expect(injected).toContain(`<script>${vendor}</script>${injectedTag("window.h = 1;")}\n<body>`);
   });
 
   it("injects at head start past a script that prints <head>, and before <body> without a head", () => {
@@ -205,16 +208,16 @@ describe("htmlDocument helpers", () => {
   it("keeps indexes right after a character that lowercases to two (İ)", () => {
     const page = "<html><head><title>İzmir</title></head><body><h1>İstanbul</h1></body></html>";
     const injected = injectScriptsIntoHtml(page, ["a=1"], ["b=2"]);
-    expect(injected).toContain("<script>a=1</script>\n</head>");
-    expect(injected).toContain("<script>b=2</script>\n</body></html>");
+    expect(injected).toContain(`${injectedTag("a=1")}\n</head>`);
+    expect(injected).toContain(`${injectedTag("b=2")}\n</body></html>`);
 
     const stripped = stripEmbeddedRuntimeScripts(
       '<p>İİ</p><script src="hyperframe.runtime.iife.js"></script><p>kept</p>',
     );
     expect(stripped).toBe("<p>İİ</p><p>kept</p>");
 
     const escaped = injectScriptsIntoHtml(page, ['x="İİ</SCRIPT>"'], []);
-    expect(escaped).toContain('<script>x="İİ<\\/SCRIPT>"</script>');
+    expect(escaped).toContain(injectedTag('x="İİ<\\/SCRIPT>"'));
   });
 
   it("skips a script tag written inside an attribute value", () => {
@@ -242,7 +245,7 @@ describe("htmlDocument helpers", () => {
   it("treats a quote as a value only after =, like the browser", () => {
     const page = "<html><head><meta name=it's></head><body><p>don't</p></body></html>";
     expect(injectScriptsIntoHtml(page, ["H"], [])).toContain(
-      "<meta name=it's><script>H</script>\n</head>",
+      `<meta name=it's>${injectedTag("H")}\n</head>`,
     );
 
     for (const meta of [

packages/core/src/compiler/htmlDocument.ts

@@ -201,7 +201,10 @@ function escapeCaseInsensitiveToken(
 }
 
 function inlineScriptTags(scripts: readonly string[]): string {
-  return scripts.map((source) => `<script>${escapeInlineScriptSource(source)}</script>`).join("\n");
+  return scripts
+    .map((source, index) => `${source}\n//# sourceURL=hyperframes://injected/${index}`)
+    .map((source) => `<script>${escapeInlineScriptSource(source)}</script>`)
+    .join("\n");
 }
 
 const RAW_TEXT_TAGS = ["script", "style", "title", "textarea"] as const;

packages/core/src/compiler/index.ts

@@ -69,6 +69,7 @@ export {
   deferScriptsUntilFonts,
   headStyleRuns,
   inlineScriptRuns,
+  isJavaScriptType,
   styleElementsFor,
   type CompositionStyle,
   type InlineScriptRun,

packages/core/src/compiler/scriptRuns.ts

@@ -70,6 +70,7 @@ export const AFTER_FONTS_SCRIPTS = `script[type="${AFTER_FONTS_SCRIPT_TYPE}"], s
 
 export const AFTER_FONTS_CLAIM = "__hfAfterFontsClaimed";
 export const INLINED_FILE_ATTR = "data-hf-inlined-src";
+export const COMPOSITION_SOURCE_URL = "hyperframes-composition://body";
 
 export const DEFERRED_FILE = `[defer][src], [defer][${INLINED_FILE_ATTR}]`;
 const AFTER_FONTS_FALLBACK_ATTR = "data-hf-after-fonts-fallback";
@@ -96,7 +97,8 @@ const afterFontsFallback = () => `document.addEventListener("DOMContentLoaded",
     el.replaceWith(s);
     if (!waits) next();
   })();
-});`;
+});
+//# sourceURL=hyperframes://after-fonts-fallback`;
 
 /** Gives each body script a type the browser does not run, so the runtime can run it once web fonts are ready. */
 export function deferScriptsUntilFonts(

packages/core/src/index.ts

@@ -182,6 +182,7 @@ export {
   type SubCompositionValidityReason,
 } from "./compiler/subCompositionValidity";
 export { RUNTIME_BOOTSTRAP_ATTR, stripEmbeddedRuntimeScripts } from "./compiler/htmlDocument";
+export { COMPOSITION_SOURCE_URL } from "./compiler/scriptRuns";
 export { queryByAttr } from "./utils/cssSelector";
 export {
   AUDIBLE_MEDIA_SELECTOR,

packages/core/src/runtime/vfx.test.ts

@@ -225,6 +225,12 @@ function clearCompositeSlot(): void {
   delete compositeWindow().__hf_page_composite_resolve;
 }
 
+/** The chain registers nothing, and its one error matches every pattern. */
+function expectRefused(...patterns: RegExp[]): void {
+  expect(initVfx(document.body, 30)).toHaveLength(0);
+  for (const pattern of patterns) expect(String(errors[0]![1])).toMatch(pattern);
+}
+
 describe("vfx runtime", () => {
   beforeEach(() => installVfxHarness(null));
   afterEach(releaseVfxHarness);
@@ -279,8 +285,7 @@ describe("vfx runtime", () => {
   it("reports an unknown effect type loudly", () => {
     makeHost('{"version":1,"nodes":[{"type":"nope","id":"n1","params":{}}]}');
 
-    expect(initVfx(document.body, 30)).toHaveLength(0);
-    expect(String(errors[0]![1])).toMatch(/unknown effect type/);
+    expectRefused(/unknown effect type/, /^vfx: /);
   });
 
   it("reports an unavailable WebGL2 context loudly and registers nothing", () => {
@@ -492,8 +497,7 @@ describe("vfx runtime — self capture", () => {
   it("names the Chrome flag when drawElementImage is missing", () => {
     makeCaptureHost({ clearRect: () => {} });
 
-    expect(initVfx(document.body, 30)).toHaveLength(0);
-    expect(String(errors[0]![1])).toMatch(/chrome:\/\/flags\/#canvas-draw-element/);
+    expectRefused(/chrome:\/\/flags\/#canvas-draw-element/);
   });
 
   it("arms the page-composite protocol instead of painting inline in engine mode", () => {
@@ -722,6 +726,7 @@ describe("vfx runtime — self capture", () => {
       expect(errors[0]![0]).toBe(LABEL);
       expect(String(errors[0]![1])).toMatch(/#cap-stalled/);
       expect(String(errors[0]![1])).toMatch(/no paint arrived within 2000ms/);
+      expect(String(errors[0]![1]).startsWith("vfx-frame: ")).toBe(true);
       expect(String(errors[0]![1])).toMatch(/BeginFrame/);
     } finally {
       vi.useRealTimers();
@@ -839,6 +844,7 @@ describe("vfx runtime — backdrop capture", () => {
     expect(errors).toHaveLength(1);
     expect(String(errors[0]![1])).toMatch(/measures 0×0/);
     expect(String(errors[0]![1])).toMatch(/explicit width and height in px/);
+    expect(String(errors[0]![1]).startsWith("vfx-frame: ")).toBe(true);
   });
 
   it("refuses a .hf-vfx-in that is not the capture canvas's immediate child", () => {
@@ -940,24 +946,19 @@ describe("vfx runtime — ref (second source) params", () => {
     makeRefTarget(undefined, "matte-1", false);
     makeCaptureHost(createMockCtx2d(), "cap", REF_NODE);
 
-    expect(initVfx(document.body, 30)).toHaveLength(0);
-    expect(String(errors[0]![1])).toMatch(/"matte" source/);
-    expect(String(errors[0]![1])).toMatch(/hf-vfx-src/);
+    expectRefused(/"matte" source/, /hf-vfx-src/);
   });
 
   it("refuses a ref naming an element that is not in the composition", () => {
     makeCaptureHost(createMockCtx2d(), "cap", REF_NODE);
 
-    expect(initVfx(document.body, 30)).toHaveLength(0);
-    expect(String(errors[0]![1])).toMatch(/#matte-1/);
-    expect(String(errors[0]![1])).toMatch(/not in the composition/);
+    expectRefused(/#matte-1/, /not in the composition/);
   });
 
   it("refuses a node that names no ref element at all", () => {
     makeCaptureHost(createMockCtx2d(), "cap", ONE_NODE);
 
-    expect(initVfx(document.body, 30)).toHaveLength(0);
-    expect(String(errors[0]![1])).toMatch(/needs a "matte" param/);
+    expectRefused(/needs a "matte" param/);
   });
 
   it("captures a hidden matte as empty instead of failing the frame", async () => {

packages/core/src/runtime/vfx.ts

@@ -11,9 +11,8 @@
  * randomness, no state carried between paints. That is the determinism
  * contract the exporter's gate depends on.
  *
- * Every failure is loud: the `[HyperFrames] composition script error:` prefix
- * is what the engine turns into `runtime-error:<compId>` and fails fast on, so
- * a broken chain stops a render instead of silently rendering the wrong frame.
+ * Every failure is loud: the engine records the `[HyperFrames] composition script error:`
+ * prefix as a composition script error, which fails a render whose timeline wait times out.
  */
 
 import {
@@ -44,7 +43,7 @@ import { isCanvasElement, isHtmlElement } from "./domRealm";
  */
 const VFX_REF_VISIBLE_ATTR = "data-vfx-ref-visible";
 
-/** The prefix `frameCapture.ts` matches to fail a render fast. */
+/** The prefix `frameCapture.ts` records as a composition script error. */
 const VFX_ERROR_LABEL = "[HyperFrames] composition script error:";
 
 /**
@@ -118,6 +117,8 @@ interface VfxCaptureSource {
   visible: boolean;
   /** `.hf-vfx-in` measured 0×0 and that has already been reported once. */
   emptyBoxReported: boolean;
+  /** `.hf-vfx-in` measured 0×0 at registration or the last seek, captured or not. */
+  laidOutEmpty: boolean;
 }
 
 /**
@@ -213,6 +214,12 @@ function reportVfxError(message: string): void {
   console.error(VFX_ERROR_LABEL, `vfx: ${message}`);
 }
 
+/** One frame's capture failed; later frames may still paint, so the engine does not stop the render on it. */
+function reportVfxFrameError(message: string): void {
+  // eslint-disable-next-line no-console
+  console.error(VFX_ERROR_LABEL, `vfx-frame: ${message}`);
+}
+
 function compileShader(
   gl: WebGL2RenderingContext,
   type: number,
@@ -511,6 +518,7 @@ function resolveCaptureSource(
     // Only a `ref` source may be visible; `resolveRefSource` sets it.
     visible: false,
     emptyBoxReported: false,
+    laidOutEmpty: deviceSize(inner) === null,
   };
 }
 
@@ -907,6 +915,18 @@ function resizeCaptureCanvas(src: VfxCaptureSource, size: { width: number; heigh
   if (src.canvas.height !== size.height) src.canvas.height = size.height;
 }
 
+function captureEmpty(
+  entry: VfxEntry,
+  src: VfxCaptureSource,
+  size: { width: number; height: number },
+  mode: CaptureMode,
+): true {
+  resizeCaptureCanvas(src, size);
+  src.ctx.clearRect(0, 0, size.width, size.height);
+  if (mode.upload) uploadCaptureTexture(entry.gl, src);
+  return true;
+}
+
 /**
  * Read one source's pixels into its texture. Both `clearRect`s matter: the
  * first because `drawElementImage` composites onto whatever is there, the
@@ -945,28 +965,23 @@ function captureSource(
   // first. An empty `u_src2` is also the right answer — under Alpha the layer
   // it mattes disappears, under Alpha Inverted it passes, which is what After
   // Effects does with a matte that is not there yet.
-  if (!isPaintableSource(src)) {
-    resizeCaptureCanvas(src, size);
-    src.ctx.clearRect(0, 0, size.width, size.height);
-    if (mode.upload) uploadCaptureTexture(entry.gl, src);
-    return true;
-  }
+  if (!isPaintableSource(src)) return captureEmpty(entry, src, size, mode);
   // The one capture failure Chrome does NOT report: inside a `layoutsubtree`
   // canvas a child sized by `inset`/percentages measures 0×0, and
   // `drawElementImage` then succeeds and draws nothing at all — no throw, no
   // warning, a blank layer. Measured (vault `layoutsubtree-capture-rules`),
-  // so it is checked here and said out loud, once per source rather than once
-  // per frame.
+  // so it is said out loud once per source, and the frame paints from an empty
+  // capture rather than repeating the last one.
   if (deviceSize(src.inner) === null) {
     if (!src.emptyBoxReported) {
       src.emptyBoxReported = true;
-      reportVfxError(
+      reportVfxFrameError(
         `${describeHost(entry.host)}: the .hf-vfx-in wrapper measures 0×0, so its capture ` +
           `would be empty. Inside a layoutsubtree canvas an inset or percentage box has no ` +
           `size — the wrapper must state an explicit width and height in px.`,
       );
     }
-    return false;
+    return captureEmpty(entry, src, size, mode);
   }
   resizeCaptureCanvas(src, size);
   src.ctx.clearRect(0, 0, size.width, size.height);
@@ -1201,7 +1216,7 @@ function awaitCanvasPaint(canvas: HTMLCanvasElement): Promise<"painted" | "timeo
 async function awaitSourcePaints(entry: VfxEntry, sources: VfxCaptureSource[]): Promise<boolean> {
   const outcomes = await Promise.all(sources.map((source) => awaitCanvasPaint(source.canvas)));
   if (!outcomes.includes("timeout")) return true;
-  reportVfxError(
+  reportVfxFrameError(
     `${describeHost(entry.host)}: no paint arrived within ${CAPTURE_PAINT_TIMEOUT_MS}ms, so ` +
       `this frame's capture was skipped (a BeginFrame-controlled compositor without a tick ` +
       `for this frame is a known cause).`,
@@ -1304,6 +1319,15 @@ async function capturePreviewThenPaint(
   await Promise.all(entries.map((entry) => capturePaintedHost(entry, t, seq, speculative)));
 }
 
+/** A `.hf-vfx-in` first painted at 0×0 and then sized can stay blank in its capture until re-inserted (measured). */
+function reinsertRegrownSources(): void {
+  for (const src of registry.flatMap(entrySources)) {
+    const empty = deviceSize(src.inner) === null;
+    if (src.laidOutEmpty && !empty) src.canvas.insertBefore(src.inner, src.inner.nextSibling);
+    src.laidOutEmpty = empty;
+  }
+}
+
 /**
  * Repaint every registered chain for composition-local time `t`. Called from
  * the runtime transport's `seek` (preview) and `renderSeek` (engine) — the two
@@ -1337,6 +1361,7 @@ async function capturePreviewThenPaint(
 export function paintVfx(t: number, options?: { engineMode?: boolean }): void {
   lastPaintTime = t;
   const seq = ++paintSeq;
+  reinsertRegrownSources();
   const capturing: VfxEntry[] = [];
   for (const entry of registry) {
     // Reported once, at the moment of loss; repeating it per frame is spam.

packages/engine/src/index.ts

@@ -134,6 +134,7 @@ export {
   type BeforeCaptureHook,
   type DiscardWarmupInnerCapture,
   type StaticVerificationOutcome,
+  VfxFailureError,
 } from "./services/frameCapture.js";
 export {
   CaptureFailure,

packages/engine/src/services/frameCapture-subTimelinePoll.test.ts

@@ -41,6 +41,24 @@ describe("pollSubCompositionTimelines fail-fast", () => {
     expect(Date.now() - started).toBeLessThan(5_000);
   });
 
+  it("stops at once when the caller says so, without waiting out the timeout", async () => {
+    const page = makeMockPage((expr) =>
+      expr.includes("__hfForceTimelineRebind") ? undefined : false,
+    );
+    const shouldStop = vi.fn(() => true);
+    const outcome = await pollSubCompositionTimelines(
+      page,
+      60_000,
+      10,
+      () => [],
+      undefined,
+      undefined,
+      shouldStop,
+    );
+    expect(outcome).toBe("timeout");
+    expect(shouldStop).toHaveBeenCalledTimes(1);
+  });
+
   it("waits the full timeout when timelines are missing but no script failed", async () => {
     const page = makeMockPage(() => false);
     const outcome = await pollSubCompositionTimelines(page, 120, 10, () => []);