fix(core): a VFX layer hidden or late while empty renders once it has a size

Author: miguel-heygen

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,9 +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/);
-    expect(String(errors[0]![1]).startsWith("vfx: ")).toBe(true);
+    expectRefused(/unknown effect type/, /^vfx: /);
   });
 
   it("reports an unavailable WebGL2 context loudly and registers nothing", () => {
@@ -493,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", () => {
@@ -943,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

@@ -117,8 +117,8 @@ interface VfxCaptureSource {
   visible: boolean;
   /** `.hf-vfx-in` measured 0×0 and that has already been reported once. */
   emptyBoxReported: boolean;
-  /** The last capture found `.hf-vfx-in` 0×0; Chrome draws nothing of it until it is re-inserted (measured). */
-  capturedEmpty: boolean;
+  /** `.hf-vfx-in` measured 0×0 at the last seek, whether or not anything captured it. */
+  laidOutEmpty: boolean;
 }
 
 /**
@@ -518,7 +518,7 @@ function resolveCaptureSource(
     // Only a `ref` source may be visible; `resolveRefSource` sets it.
     visible: false,
     emptyBoxReported: false,
-    capturedEmpty: false,
+    laidOutEmpty: deviceSize(inner) === null,
   };
 }
 
@@ -981,7 +981,6 @@ function captureSource(
           `size — the wrapper must state an explicit width and height in px.`,
       );
     }
-    src.capturedEmpty = true;
     return captureEmpty(entry, src, size, mode);
   }
   resizeCaptureCanvas(src, size);
@@ -1320,6 +1319,15 @@ async function capturePreviewThenPaint(
   await Promise.all(entries.map((entry) => capturePaintedHost(entry, t, seq, speculative)));
 }
 
+/** A `.hf-vfx-in` laid out at 0×0 and then sized stays blank in its capture until it is 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
@@ -1353,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.
@@ -1374,11 +1383,6 @@ export function paintVfx(t: number, options?: { engineMode?: boolean }): void {
     else paintEntry(entry, t);
   }
   if (capturing.length === 0) return;
-  for (const src of capturing.flatMap(entrySources)) {
-    if (!src.capturedEmpty || deviceSize(src.inner) === null) continue;
-    src.capturedEmpty = false;
-    src.canvas.insertBefore(src.inner, src.inner.nextSibling);
-  }
   // Engine mode arms the page-composite protocol AND the preview-side capture,
   // then paints on whichever completes first. Arming alone was a bet that every
   // capture host runs under `frameCapture.ts`, and it does not: `hyperframes

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

@@ -163,27 +163,28 @@ describe("classifyPageError", () => {
   });
 
   // initializeSession registers its listeners before the incomplete fake session makes it throw.
-  it("records the page's uncaught errors from scripts it loaded from the server", async () => {
+  async function listenedSession() {
     const runtimeListeners = new Map<string, (event: unknown) => void>();
     const pageListeners = new Map<string, (event: unknown) => void>();
-    const client = {
-      on: (event: string, listener: (event: unknown) => void) =>
-        runtimeListeners.set(event, listener),
-      send: async () => ({}),
-    };
-    const page = {
-      on: (event: string, listener: (event: unknown) => void) => pageListeners.set(event, listener),
-      createCDPSession: async () => client,
-    };
+    const listen =
+      (listeners: typeof pageListeners) => (event: string, listener: (event: unknown) => void) =>
+        listeners.set(event, listener);
+    const client = { on: listen(runtimeListeners), send: async () => ({}) };
+    const page = { on: listen(pageListeners), createCDPSession: async () => client };
     const session = {
       page,
       serverUrl: server,
-      scriptLoadFailures: [],
-      pageErrors: [],
-      warnings: [],
+      scriptLoadFailures: [] as string[],
+      pageErrors: [] as string[],
+      warnings: [] as { code: string }[],
       browserConsoleBuffer: [],
-    };
-    await initializeSession(session as unknown as CaptureSession).catch(() => {});
+    } as unknown as CaptureSession;
+    await initializeSession(session).catch(() => {});
+    return { session, pageListeners, runtimeListeners };
+  }
+
+  it("records the page's uncaught errors from scripts it loaded from the server", async () => {
+    const { session, pageListeners, runtimeListeners } = await listenedSession();
     const loaded = (url: string, resourceType: string) => ({
       status: () => 200,
       url: () => url,
@@ -201,21 +202,7 @@ describe("classifyPageError", () => {
   });
 
   it("records the first VFX error to stop the render, and a scene's logged throw as a page error", async () => {
-    const pageListeners = new Map<string, (event: unknown) => void>();
-    const client = { on: () => {}, send: async () => ({}) };
-    const page = {
-      on: (event: string, listener: (event: unknown) => void) => pageListeners.set(event, listener),
-      createCDPSession: async () => client,
-    };
-    const session = {
-      page,
-      serverUrl: server,
-      scriptLoadFailures: [] as string[],
-      pageErrors: [] as string[],
-      warnings: [] as { code: string }[],
-      browserConsoleBuffer: [],
-    } as unknown as CaptureSession;
-    await initializeSession(session).catch(() => {});
+    const { session, pageListeners } = await listenedSession();
     const logged = (detail: string) =>
       pageListeners.get("console")?.({
         type: () => "error",

packages/producer/src/services/scriptFailureAttribution.test.ts

@@ -153,8 +153,8 @@ describe("a failed VFX chain", () => {
     expect(await timelineWarningCodes(files)).toEqual([]);
   }, 30_000);
 
-  // A layer animated in from zero width is empty on its first frame, which is correct; later frames paint.
-  it("keeps one frame's empty capture a page error, not a stop", async () => {
+  // A wrapper with no size reports one empty capture per source: a page error, not a stop.
+  it("keeps a wrapper with no size a page error, not a stop", async () => {
     const files = { "index.html": vfxComposition(vfxNode("wave-warp", warp), "width:0") };
     const errors = await sessionErrors(files, "vfx-frame:", 2);
     expect(errors.codes).toEqual([]);

packages/producer/src/services/vfxDeterminism.test.ts

@@ -686,41 +686,58 @@ describe("data-vfx-chain in the browser", () => {
     }
   }, 60_000);
 
-  // Chrome draws nothing of a child it first painted at 0×0 until it is re-inserted (measured in 152).
-  it("paints a layer that grows from 0×0 on the next frame, not empty for the rest of the shot", async () => {
-    const page = await open(fixture(waveWarpChain({ height: 0, width: 93.4 }), "width:0px"));
-    try {
-      expect(await seekAndResolve(page, 0)).toBe(true);
-      expect((await sample(page, [60])).left).toEqual([0, 0, 0, 0]);
-      expect(pageErrors.get(page)).toEqual([expect.stringContaining("vfx-frame:")]);
-
-      pageErrors.get(page)!.length = 0;
-      await page.evaluate(() => {
-        (document.querySelector(".hf-vfx-in") as HTMLElement).style.width = "";
-      });
-      expect(await seekAndResolve(page, 1 / 30)).toBe(true);
-      expect((await sample(page, [60])).left).toEqual([255, 0, 0, 255]);
-    } finally {
-      await page.close();
-    }
-  }, 60_000);
-
-  it("paints the layer empty, not the previous frame again, once it shrinks to 0×0", async () => {
-    const page = await open(fixture(waveWarpChain({ height: 0, width: 93.4 })));
-    try {
-      expect(await seekAndResolve(page, 0)).toBe(true);
-      expect((await sample(page, [60])).left).toEqual([255, 0, 0, 255]);
-
-      await page.evaluate(() => {
-        (document.querySelector(".hf-vfx-in") as HTMLElement).style.width = "0px";
-      });
-      expect(await seekAndResolve(page, 1 / 30)).toBe(true);
-      expect((await sample(page, [60])).left).toEqual([0, 0, 0, 0]);
-      expect(pageErrors.get(page)).toEqual([expect.stringContaining("vfx-frame:")]);
-    } finally {
-      await page.close();
-    }
-  }, 60_000);
+  const RED = [255, 0, 0, 255];
+  const CLEAR = [0, 0, 0, 0];
+  // The wrapper's style before and after; how many one-frame reports the shot makes.
+  it.each([
+    [
+      "grows from 0×0: it paints on the next frame, not empty for the rest",
+      "width:0px",
+      "",
+      CLEAR,
+      RED,
+      1,
+    ],
+    [
+      "shrinks to 0×0: it paints empty, not the previous frame again",
+      "",
+      "width:0px",
+      RED,
+      CLEAR,
+      1,
+    ],
+    [
+      "is hidden at 0×0, then shown and sized: it paints on that frame",
+      "width:0px;visibility:hidden",
+      "",
+      CLEAR,
+      RED,
+      0,
+    ],
+  ])(
+    "a layer that %s",
+    async (_case, before, after, firstPixel, nextPixel, reports) => {
+      const page = await open(fixture(waveWarpChain({ height: 0, width: 93.4 }), before));
+      const restyle = (css: string) =>
+        page.evaluate((style: string) => {
+          (document.querySelector(".hf-vfx-in") as HTMLElement).style.cssText = style;
+        }, css);
+      try {
+        expect(await seekAndResolve(page, 0)).toBe(true);
+        expect((await sample(page, [60])).left).toEqual(firstPixel);
+        const reported = [...pageErrors.get(page)!];
+        pageErrors.get(page)!.length = 0;
+        await restyle(after);
+        expect(await seekAndResolve(page, 1 / 30)).toBe(true);
+        expect((await sample(page, [60])).left).toEqual(nextPixel);
+        const frameReports = [...reported, ...pageErrors.get(page)!];
+        expect(frameReports).toEqual(Array(reports).fill(expect.stringContaining("vfx-frame:")));
+      } finally {
+        await page.close();
+      }
+    },
+    60_000,
+  );
 
   /**
    * `hyperframes snapshot` (and `check`/`compare`/`validate`/`layout`, and