Skip to content

Write HTML. Render video. Built for agents.

47.1 KB
Raw Blame
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import type { HfVfxCapture } from "../vfx";
import { resetSeekDispatchState, waitForSeekCompletion } from "./adapters/seek-dispatch";
import { initVfx, paintVfx } from "./vfx";

/**
 * No def has `capture !== "none"` until Task 2.2 registers `wave-warp`, so the
 * capture tests below lift a real `fractal-noise` chain into `self` through the
 * two functions the runtime asks. `null` leaves the real answers alone, so the
 * Task 1.2 cases in this file are untouched.
 */
const override = vi.hoisted(() => ({
  capture: null as HfVfxCapture | null,
  /** Appends a `ref` param with this key to every def, as `luma-matte` has. */
  refKey: null as string | null,
}));

vi.mock("../vfx", async (importOriginal) => {
  const actual = await importOriginal<typeof import("../vfx")>();
  return {
    ...actual,
    chainCapture: (chain: import("../vfx").HfVfxChain) =>
      override.capture ?? actual.chainCapture(chain),
    getVfxDef: (id: string) => {
      const def = actual.getVfxDef(id);
      if (!def) return def;
      if (!override.capture && !override.refKey) return def;
      return {
        ...def,
        capture: override.capture ?? def.capture,
        params: override.refKey
          ? [...def.params, { kind: "ref", key: override.refKey, label: "Second source" }]
          : def.params,
      };
    },
    normalizeVfxParams: (id: string, values: import("../vfx").HfVfxParamValues | undefined) => {
      const normalized = actual.normalizeVfxParams(id, values);
      // The real `normalizeVfxParams` reads the real def, which has no ref
      // param, so the injected one would be dropped before the runtime saw it.
      if (override.refKey) normalized[override.refKey] = String(values?.[override.refKey] ?? "");
      return normalized;
    },
  };
});

const LABEL = "[HyperFrames] composition script error:";

interface MockGl {
  calls: string[];
  uniforms: Record<string, unknown>;
  programCount: number;
  usedPrograms: unknown[];
  shaderSources: string[];
  viewports: number[][];
}

/**
 * The slice of WebGL2 the vfx runtime touches. jsdom has no GL at all, so the
 * unit tests stand a recorder in front of it and assert on the call order and
 * the uniform values rather than on pixels — pixels are the browser test's job.
 */
function createMockGl(): WebGL2RenderingContext & MockGl {
  const state: MockGl = {
    calls: [],
    uniforms: {},
    programCount: 0,
    usedPrograms: [],
    shaderSources: [],
    viewports: [],
  };
  let currentProgram: unknown = null;
  const gl = {
    ...state,
    VERTEX_SHADER: 0x8b31,
    FRAGMENT_SHADER: 0x8b30,
    COMPILE_STATUS: 0x8b81,
    LINK_STATUS: 0x8b82,
    TRIANGLES: 0x0004,
    TEXTURE_2D: 0x0de1,
    TEXTURE0: 0x84c0,
    TEXTURE1: 0x84c1,
    RGBA: 0x1908,
    UNSIGNED_BYTE: 0x1401,
    CLAMP_TO_EDGE: 0x812f,
    LINEAR: 0x2601,
    TEXTURE_WRAP_S: 0x2802,
    TEXTURE_WRAP_T: 0x2803,
    TEXTURE_MIN_FILTER: 0x2801,
    TEXTURE_MAG_FILTER: 0x2800,
    FRAMEBUFFER: 0x8d40,
    COLOR_ATTACHMENT0: 0x8ce0,
    UNPACK_FLIP_Y_WEBGL: 0x9240,
    UNPACK_PREMULTIPLY_ALPHA_WEBGL: 0x9241,
    createShader: () => ({}),
    shaderSource: (_s: unknown, src: string) => state.shaderSources.push(src),
    compileShader: () => {},
    getShaderParameter: () => true,
    getShaderInfoLog: () => "",
    deleteShader: () => {},
    createProgram: () => ({ id: ++state.programCount }),
    attachShader: () => {},
    linkProgram: () => {},
    getProgramParameter: () => true,
    getProgramInfoLog: () => "",
    deleteProgram: () => {},
    getUniformLocation: (_p: unknown, name: string) => name,
    useProgram: (p: unknown) => {
      currentProgram = p;
      state.usedPrograms.push(p);
      state.calls.push("useProgram");
    },
    uniform1f: (name: string, v: number) => {
      state.uniforms[name] = v;
    },
    uniform1i: (name: string, v: number) => {
      state.uniforms[name] = v;
    },
    uniform2f: (name: string, a: number, b: number) => {
      state.uniforms[name] = [a, b];
    },
    viewport: (_x: number, _y: number, w: number, h: number) => state.viewports.push([w, h]),
    drawArrays: () => state.calls.push(`draw:${(currentProgram as { id: number }).id}`),
    createTexture: () => ({}),
    bindTexture: () => {},
    texParameteri: () => {},
    texImage2D: () => {},
    activeTexture: () => {},
    pixelStorei: () => {},
    createFramebuffer: () => ({}),
    bindFramebuffer: (_t: unknown, fb: unknown) => state.calls.push(fb ? "fbo" : "screen"),
    framebufferTexture2D: () => {},
    deleteFramebuffer: () => {},
    deleteTexture: () => {},
  } as unknown as WebGL2RenderingContext & MockGl;
  return gl;
}

let gl: (WebGL2RenderingContext & MockGl) | null = null;
let errors: unknown[][] = [];

function installCanvasMock(webgl2: () => unknown): void {
  vi.spyOn(HTMLCanvasElement.prototype, "getContext").mockImplementation(function (
    this: HTMLCanvasElement,
    kind: string,
  ) {
    return kind === "webgl2" ? (webgl2() as never) : null;
  } as never);
}

/**
 * Hosts are 0×0 in jsdom; the runtime refuses to paint a zero-area box. Sets
 * both the layout box (`offsetWidth`/`offsetHeight`, what `deviceSize` reads)
 * and the client rect (what a GSAP transform would inflate) to the same
 * values by default — a test that wants to simulate a transformed host
 * overrides `getBoundingClientRect` afterwards.
 */
function sizeHost(host: HTMLElement, width = 320, height = 180): void {
  host.getBoundingClientRect = () =>
    ({ width, height, left: 0, top: 0, right: width, bottom: height, x: 0, y: 0 }) as DOMRect;
  Object.defineProperty(host, "offsetWidth", { value: width, configurable: true });
  Object.defineProperty(host, "offsetHeight", { value: height, configurable: true });
}

function makeHost(chain: string, id = "h1"): HTMLElement {
  const host = document.createElement("div");
  host.id = id;
  host.setAttribute("data-vfx-chain", chain);
  sizeHost(host);
  document.body.appendChild(host);
  return host;
}

const ONE_NODE =
  '{"version":1,"nodes":[{"type":"fractal-noise","id":"n1","params":{"contrast":562}}]}';
const TWO_NODES =
  '{"version":1,"nodes":[{"type":"fractal-noise","id":"n1","params":{}},' +
  '{"type":"fractal-noise","id":"n2","params":{}}]}';

/**
 * One fixture for every describe in this file: a clean body, a recording mock
 * GL behind `getContext`, a console spy, a page-composite slot nobody else
 * owns, and the def overrides this test lifts its chains through.
 */
function installVfxHarness(capture: HfVfxCapture | null, refKey: string | null = null): void {
  document.body.innerHTML = "";
  gl = createMockGl();
  installCanvasMock(() => gl);
  errors = [];
  override.capture = capture;
  override.refKey = refKey;
  // `paintVfx` registers its preview capture into the module-level
  // seek-completion set; a leftover entry would stall the next test's barrier.
  resetSeekDispatchState();
  clearCompositeSlot();
  vi.spyOn(console, "error").mockImplementation((...args: unknown[]) => {
    errors.push(args);
  });
}

function releaseVfxHarness(): void {
  // Empty the registry BEFORE the canvas mock comes off, or jsdom's real
  // (unimplemented) getContext runs and floods the console.
  document.body.innerHTML = "";
  override.capture = null;
  override.refKey = null;
  initVfx(document.body, 30);
  clearCompositeSlot();
  resetSeekDispatchState();
  vi.unstubAllGlobals();
  vi.restoreAllMocks();
}

/**
 * One macrotask. The preview capture path awaits a `paint` event, a
 * `Promise.all` over every source, and then the capture itself, so counting
 * microtask ticks by hand is a test that breaks when a hop is added; a timer
 * tick settles all of them.
 */
function flushTasks(): Promise<void> {
  return new Promise<void>((resolve) => setTimeout(resolve, 0));
}

function clearCompositeSlot(): void {
  delete compositeWindow().__hf_page_composite_pending;
  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);

  it("registers every [data-vfx-chain] host and creates a missing .hf-vfx-out", () => {
    const a = makeHost(ONE_NODE, "a");
    const b = makeHost(ONE_NODE, "b");
    const preset = document.createElement("canvas");
    preset.className = "hf-vfx-out";
    b.appendChild(preset);

    const registry = initVfx(document.body, 30);

    expect(registry).toHaveLength(2);
    expect(a.querySelectorAll("canvas.hf-vfx-out")).toHaveLength(1);
    expect(b.querySelectorAll("canvas.hf-vfx-out")).toHaveLength(1);
    expect(registry[1]!.out).toBe(preset);
    expect(errors).toEqual([]);
  });

  it("gives an exporter-emitted .hf-vfx-out the same box as one it creates", () => {
    const a = makeHost(ONE_NODE, "a");
    const b = makeHost(ONE_NODE, "b");
    const preset = document.createElement("canvas");
    preset.className = "hf-vfx-out";
    b.appendChild(preset);

    initVfx(document.body, 30);

    const created = a.querySelector("canvas.hf-vfx-out") as HTMLCanvasElement;
    // The exporter emits the canvas bare (`<canvas class="hf-vfx-out"></canvas>`).
    // Adopted untouched it stays `position:static; display:inline`, wraps to the
    // line after the `.hf-vfx-src` canvas and paints one layer height below the
    // host — measured on retro-wave `#main-l6-text` (findings Task 3.5b).
    expect(preset.style.position).toBe("absolute");
    expect(preset.style.cssText).toBe(created.style.cssText);
    expect(errors).toEqual([]);
  });

  it("reports an unsupported chain version loudly and registers nothing", () => {
    makeHost('{"version":2,"nodes":[]}');

    const registry = initVfx(document.body, 30);

    expect(registry).toHaveLength(0);
    expect(errors).toHaveLength(1);
    expect(errors[0]![0]).toBe(LABEL);
    expect(String(errors[0]![1])).toMatch(/vfx/);
    expect(String(errors[0]![1])).toMatch(/version/);
  });

  it("reports an unknown effect type loudly", () => {
    makeHost('{"version":1,"nodes":[{"type":"nope","id":"n1","params":{}}]}');

    expectRefused(/unknown effect type/, /^vfx: /);
  });

  it("reports an unavailable WebGL2 context loudly and registers nothing", () => {
    makeHost(ONE_NODE);
    installCanvasMock(() => null);

    expect(initVfx(document.body, 30)).toHaveLength(0);
    expect(errors).toHaveLength(1);
    expect(String(errors[0]![1])).toMatch(/WebGL2/);
  });

  it("draws one full-screen triangle per enabled node, last pass to the canvas", () => {
    makeHost(TWO_NODES);
    initVfx(document.body, 30);

    // Second paint: the ping-pong targets already exist, so the call list is
    // exactly the draw sequence — which also pins that they are reused.
    paintVfx(1.25);
    gl!.calls.length = 0;
    paintVfx(1.25);

    expect(gl!.calls).toEqual(["useProgram", "fbo", "draw:1", "useProgram", "screen", "draw:2"]);
  });

  it("passes the seek time, the composition fps and the device-pixel size as uniforms", () => {
    makeHost(ONE_NODE);
    initVfx(document.body, 24);

    paintVfx(1.5);

    expect(gl!.uniforms["u_t"]).toBe(1.5);
    expect(gl!.uniforms["u_fps"]).toBe(24);
    expect(gl!.uniforms["u_size"]).toEqual([320, 180]);
    expect(gl!.viewports.at(-1)).toEqual([320, 180]);
  });

  it("takes a static param from the chain and an animated one from its CSS var", () => {
    const host = makeHost(ONE_NODE);
    host.style.setProperty("--vfx-n1-opacity", "42");
    initVfx(document.body, 30);

    paintVfx(0);

    expect(gl!.uniforms["u_contrast"]).toBe(562);
    expect(gl!.uniforms["u_opacity"]).toBe(42);
  });

  it("clamps a param that the chain put outside the def's range", () => {
    makeHost(
      '{"version":1,"nodes":[{"type":"fractal-noise","id":"n1","params":{"contrast":99999}}]}',
    );
    initVfx(document.body, 30);

    paintVfx(0);

    expect(gl!.uniforms["u_contrast"]).toBe(1000);
  });

  it("sizes the output canvas from the host's layout box, not its transformed AABB", () => {
    // A GSAP `transform: scale(2)` inflates getBoundingClientRect but leaves
    // offsetWidth/offsetHeight alone — the runtime must use the latter, or a
    // scaled or rotated host gets an inflated canvas and a stretched capture.
    const host = makeHost(ONE_NODE);
    sizeHost(host, 200, 100);
    host.getBoundingClientRect = () =>
      ({
        width: 400,
        height: 200,
        left: 0,
        top: 0,
        right: 400,
        bottom: 200,
        x: 0,
        y: 0,
      }) as DOMRect;
    initVfx(document.body, 30);

    paintVfx(0);

    expect(gl!.uniforms["u_size"]).toEqual([200, 100]);
    expect(gl!.viewports.at(-1)).toEqual([200, 100]);
  });

  it("does not paint a host whose box has no area", () => {
    const host = makeHost(ONE_NODE);
    sizeHost(host, 0, 0);
    initVfx(document.body, 30);

    paintVfx(0);

    expect(gl!.calls).toEqual([]);
  });

  it("reports a lost WebGL context once and then paints that host no more", () => {
    const host = makeHost(ONE_NODE);
    const entries = initVfx(document.body, 30);
    const out = host.querySelector("canvas.hf-vfx-out") as HTMLCanvasElement;
    const lose = (): void => {
      out.dispatchEvent(new Event("webglcontextlost", { cancelable: true }));
    };

    lose();
    paintVfx(0);
    // A second loss event, and a second paint, must stay quiet: the report is
    // the moment of loss, not every frame after it.
    lose();
    paintVfx(1);

    expect({
      contextLost: entries[0]!.contextLost,
      reports: errors.length,
      message: String(errors[0]?.[1] ?? ""),
      calls: gl!.calls,
    }).toEqual({
      contextLost: true,
      reports: 1,
      message: expect.stringMatching(/context lost/i) as unknown as string,
      calls: [],
    });
  });

  it("forgets the previous composition's hosts when re-initialised", () => {
    makeHost(ONE_NODE);
    initVfx(document.body, 30);
    document.body.innerHTML = "";

    expect(initVfx(document.body, 30)).toHaveLength(0);
    paintVfx(0);
    expect(gl!.calls).toEqual([]);
  });
});

interface CompositeWindow extends Window {
  __hf_page_composite_pending?: boolean;
  __hf_page_composite_resolve?: () => boolean;
}

function compositeWindow(): CompositeWindow {
  return window as CompositeWindow;
}

interface MockCtx2d {
  cleared: number[][];
  drawn: { el: Element; w: number; h: number }[];
}

/** The 2-D slice a capture host uses, with `drawElementImage` present. */
function createMockCtx2d(onDraw?: () => void): MockCtx2d {
  const state: MockCtx2d = { cleared: [], drawn: [] };
  return Object.assign(state, {
    clearRect: (_x: number, _y: number, w: number, h: number) => state.cleared.push([w, h]),
    drawElementImage: (el: Element, _x: number, _y: number, w: number, h: number) => {
      onDraw?.();
      state.drawn.push({ el, w, h });
    },
  }) as MockCtx2d;
}

/**
 * A capture wrapper as the exporter emits it. `.hf-vfx-in` is given a real
 * layout box because inside a `layoutsubtree` canvas an unsized wrapper
 * measures 0×0 and captures nothing in silence — the runtime refuses it, so a
 * fixture without a box would be testing that refusal and nothing else.
 */
function makeCaptureWrapper(ctx: unknown, forId?: string): HTMLCanvasElement {
  const src = document.createElement("canvas");
  src.className = "hf-vfx-src";
  src.setAttribute("layoutsubtree", "");
  if (forId !== undefined) src.setAttribute("data-vfx-for", forId);
  if (ctx !== undefined) {
    src.getContext = ((kind: string) => (kind === "2d" ? ctx : null)) as never;
  }
  const inner = document.createElement("div");
  inner.className = "hf-vfx-in";
  sizeHost(inner, 320, 180);
  src.appendChild(inner);
  return src;
}

/** A `self` host as the exporter emits it: src canvas wrapping `.hf-vfx-in`. */
function makeCaptureHost(ctx: unknown, id = "cap", chain = ONE_NODE): HTMLElement {
  const host = makeHost(chain, id);
  host.insertBefore(makeCaptureWrapper(ctx), host.firstChild);
  return host;
}

/**
 * A `backdrop` host as interface v1.1 shapes it: the wrapper holding every
 * layer below the host is the host's PRECEDING SIBLING, named by
 * `data-vfx-for`, not a child of the host.
 */
function makeBackdropHost(ctx: unknown, id = "adj", chain = ONE_NODE): HTMLElement {
  const host = makeHost(chain, id);
  host.parentElement!.insertBefore(makeCaptureWrapper(ctx, id), host);
  return host;
}

describe("vfx runtime — self capture", () => {
  beforeEach(() => installVfxHarness("self"));
  afterEach(releaseVfxHarness);

  it("refuses a capture host that has no .hf-vfx-src canvas", () => {
    makeHost(ONE_NODE);

    expect(initVfx(document.body, 30)).toHaveLength(0);
    expect(String(errors[0]![1])).toMatch(/hf-vfx-src/);
  });

  it("names the Chrome flag when drawElementImage is missing", () => {
    makeCaptureHost({ clearRect: () => {} });

    expectRefused(/chrome:\/\/flags\/#canvas-draw-element/);
  });

  describe.each([
    ["dropped layoutsubtree", "updateElementGeometry", "drawable"],
    ["still has layoutsubtree", "layoutSubtree", null],
  ])("in a browser that %s", (_name, member, content) => {
    const canvasProto = HTMLCanvasElement.prototype as unknown as Record<string, unknown>;
    beforeEach(() => {
      vi.stubGlobal(
        "CanvasRenderingContext2D",
        class {
          drawElementImage(): void {}
        },
      );
      canvasProto.requestPaint = () => {};
      canvasProto[member] = () => {};
    });
    afterEach(() => {
      vi.unstubAllGlobals();
      delete canvasProto.requestPaint;
      delete canvasProto[member];
    });

    it("marks the capture canvas and its child only where the exporter's markup needs it", () => {
      const host = makeCaptureHost(createMockCtx2d());
      initVfx(document.body, 30);
      expect(host.querySelector("canvas.hf-vfx-src")?.getAttribute("content")).toBe(content);
      expect(host.querySelector(".hf-vfx-in")?.hasAttribute("drawable")).toBe(content !== null);
    });
  });

  it("arms the page-composite protocol instead of painting inline in engine mode", () => {
    makeCaptureHost(createMockCtx2d());
    initVfx(document.body, 30);

    paintVfx(1.25, { engineMode: true });

    expect(compositeWindow().__hf_page_composite_pending).toBe(true);
    expect(typeof compositeWindow().__hf_page_composite_resolve).toBe("function");
    expect(gl!.calls).toEqual([]);
  });

  it("captures, uploads and paints when the engine resolves, then clears the flag", () => {
    const ctx = createMockCtx2d();
    const host = makeCaptureHost(ctx);
    initVfx(document.body, 30);
    paintVfx(1.25, { engineMode: true });

    expect(compositeWindow().__hf_page_composite_resolve!()).toBe(true);

    expect(ctx.drawn).toHaveLength(1);
    expect(ctx.drawn[0]!.el).toBe(host.querySelector(".hf-vfx-in"));
    // Cleared before the draw AND after the upload: the src canvas bitmap does
    // paint on screen even though its layoutsubtree children do not.
    expect(ctx.cleared).toEqual([
      [320, 180],
      [320, 180],
    ]);
    expect(gl!.calls).toEqual(["useProgram", "screen", "draw:1"]);
    expect(compositeWindow().__hf_page_composite_pending).toBe(false);
  });

  it("composes with a resolver that was already installed, running it first", () => {
    const order: string[] = [];
    compositeWindow().__hf_page_composite_resolve = () => {
      order.push("prior");
      return true;
    };
    const ctx = createMockCtx2d(() => order.push("vfx"));
    makeCaptureHost(ctx);
    initVfx(document.body, 30);

    paintVfx(0, { engineMode: true });
    compositeWindow().__hf_page_composite_resolve!();

    expect(order).toEqual(["prior", "vfx"]);
  });

  it("re-wraps a resolver that was installed after ours", () => {
    const order: string[] = [];
    const ctx = createMockCtx2d(() => order.push("vfx"));
    makeCaptureHost(ctx);
    initVfx(document.body, 30);
    paintVfx(0, { engineMode: true });

    // shader-transitions' 50 ms poll lands after us and assigns over the slot.
    compositeWindow().__hf_page_composite_resolve = () => {
      order.push("late");
      return true;
    };
    paintVfx(0, { engineMode: true });
    compositeWindow().__hf_page_composite_resolve!();

    expect(order).toEqual(["late", "vfx"]);
  });

  it("reports a throwing drawElementImage loudly and paints nothing", () => {
    const ctx = createMockCtx2d(() => {
      throw new Error(
        "Failed to execute 'drawElementImage' on 'CanvasRenderingContext2D': " +
          "No cached paint record for element.",
      );
    });
    makeCaptureHost(ctx);
    initVfx(document.body, 30);
    paintVfx(0, { engineMode: true });

    expect(compositeWindow().__hf_page_composite_resolve!()).toBe(false);
    expect(String(errors[0]![1])).toMatch(/No cached paint record for element/);
    expect(gl!.calls).toEqual([]);
  });

  it("skips a host the clip runtime has hidden at this time", () => {
    const ctx = createMockCtx2d();
    const host = makeCaptureHost(ctx);
    initVfx(document.body, 30);
    host.style.visibility = "hidden";

    paintVfx(0, { engineMode: true });

    expect(compositeWindow().__hf_page_composite_pending).toBeUndefined();
    expect(ctx.drawn).toHaveLength(0);
  });

  it("asks the canvas to paint before capturing on the preview path", async () => {
    const ctx = createMockCtx2d();
    const host = makeCaptureHost(ctx);
    const src = host.querySelector("canvas.hf-vfx-src") as HTMLCanvasElement & {
      requestPaint?: () => void;
    };
    let requested = 0;
    src.requestPaint = () => {
      requested += 1;
    };
    initVfx(document.body, 30);

    paintVfx(0.5);
    expect(requested).toBe(1);
    expect(ctx.drawn).toHaveLength(0);

    src.dispatchEvent(new Event("paint"));
    await flushTasks();

    expect(ctx.drawn).toHaveLength(1);
    expect(compositeWindow().__hf_page_composite_pending).toBeUndefined();
  });

  /**
   * `seekCompositionTimeline` — the seek every `snapshot`/`check`/`compare`/
   * `validate`/`layout` run goes through — awaits
   * `window.__hfWaitForSeekCompletion` (this function) and then screenshots.
   * If the preview capture is not in that set, the screenshot is a race the
   * host count decides.
   *
   * rAF is stubbed to never call back so the ONLY thing that can finish
   * `awaitCanvasPaint` is a `paint` event; with the real one the barrier would
   * resolve on a timer and the case would prove nothing.
   */
  it("holds the seek-completion barrier until every capture host has painted", async () => {
    vi.stubGlobal("requestAnimationFrame", () => 1);
    const ctxA = createMockCtx2d();
    const ctxB = createMockCtx2d();
    const srcOf = (host: HTMLElement): HTMLCanvasElement =>
      host.querySelector("canvas.hf-vfx-src") as HTMLCanvasElement;
    const a = makeCaptureHost(ctxA, "cap-a");
    const b = makeCaptureHost(ctxB, "cap-b");
    initVfx(document.body, 30);

    paintVfx(0.5);
    let resolved = false;
    const barrier = waitForSeekCompletion().then(() => {
      resolved = true;
    });
    await flushTasks();
    const beforeAnyPaint = resolved;

    srcOf(a).dispatchEvent(new Event("paint"));
    await flushTasks();
    // Still held: one host of two is not a finished frame.
    const afterFirstPaint = resolved;

    srcOf(b).dispatchEvent(new Event("paint"));
    await flushTasks();
    await barrier;

    expect({
      beforeAnyPaint,
      afterFirstPaint,
      resolved,
      drawn: [ctxA.drawn.length, ctxB.drawn.length],
    }).toEqual({
      beforeAnyPaint: false,
      afterFirstPaint: false,
      resolved: true,
      drawn: [1, 1],
    });
    expect(errors).toEqual([]);
  });

  /**
   * The worst case the ceiling exists for: a host whose canvas never fires
   * `paint` AND whose rAF never calls back — what a BeginFrame-controlled
   * compositor (Linux headless-shell, `drawelement` capture) looks like when
   * `frameCapture.ts` drains this barrier before issuing the frame's
   * `HeadlessExperimental.beginFrame`. Unbounded, that host holds the barrier
   * every `__hfWaitForSeekCompletion` caller awaits forever.
   *
   * Fake timers so the 2 s ceiling costs no wall clock. The second host proves
   * the bound is per host: it paints promptly and is captured then, not after
   * the stalled host's ceiling.
   */
  it("bounds a never-painting host's wait, reports it loudly, and leaves its peers alone", async () => {
    vi.useFakeTimers();
    try {
      vi.stubGlobal("requestAnimationFrame", () => 1);
      const ctxStalled = createMockCtx2d();
      const ctxPainting = createMockCtx2d();
      const srcOf = (host: HTMLElement): HTMLCanvasElement =>
        host.querySelector("canvas.hf-vfx-src") as HTMLCanvasElement;
      makeCaptureHost(ctxStalled, "cap-stalled");
      const painting = makeCaptureHost(ctxPainting, "cap-painting");
      initVfx(document.body, 30);

      paintVfx(0.5);
      let resolved = false;
      const barrier = waitForSeekCompletion().then(() => {
        resolved = true;
      });

      // The healthy host paints immediately and is captured on its own
      // schedule — before the stalled host's ceiling, not after it.
      srcOf(painting).dispatchEvent(new Event("paint"));
      await vi.advanceTimersByTimeAsync(0);
      const paintingDrawnEarly = ctxPainting.drawn.length;
      const heldBeforeCeiling = resolved;

      await vi.advanceTimersByTimeAsync(2000);
      await barrier;

      expect({
        paintingDrawnEarly,
        heldBeforeCeiling,
        resolved,
        stalledDrawn: ctxStalled.drawn.length,
        paintingDrawn: ctxPainting.drawn.length,
      }).toEqual({
        paintingDrawnEarly: 1,
        heldBeforeCeiling: false,
        resolved: true,
        // The stalled host is skipped, not guessed at.
        stalledDrawn: 0,
        paintingDrawn: 1,
      });
      expect(errors).toHaveLength(1);
      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();
    }
  });
});

/**
 * Interface v1.1's `backdrop` shape. The def side is unchanged — a kernel that
 * reads `u_src` cannot tell whose pixels those are — so these cases are about
 * the DOM: where the wrapper is, and what happens to the layers inside it when
 * the host itself is not painting.
 */
describe("vfx runtime — backdrop capture", () => {
  beforeEach(() => installVfxHarness("self"));
  afterEach(releaseVfxHarness);

  it("reads its source from the data-vfx-for sibling and records it as a backdrop", () => {
    const ctx = createMockCtx2d();
    const host = makeBackdropHost(ctx, "adj-1");

    const registry = initVfx(document.body, 30);
    paintVfx(1.25, { engineMode: true });

    expect(compositeWindow().__hf_page_composite_resolve!()).toBe(true);
    expect(registry).toHaveLength(1);
    // Resolved, not declared: the chain's defs say `self`, the DOM says the
    // pixels come from the wrapper beside the host.
    expect(registry[0]!.capture).toBe("backdrop");
    expect(host.querySelector(".hf-vfx-in")).toBeNull();
    expect(ctx.drawn.map((d) => d.el)).toEqual([
      document.querySelector('canvas[data-vfx-for="adj-1"] > .hf-vfx-in'),
    ]);
    expect(gl!.calls).toEqual(["useProgram", "screen", "draw:1"]);
    expect(errors).toEqual([]);
  });

  it("prefers the data-vfx-for sibling over a wrapper inside the host", () => {
    const below = createMockCtx2d();
    const own = createMockCtx2d();
    const host = makeBackdropHost(below, "adj-1");
    host.appendChild(makeCaptureWrapper(own));

    initVfx(document.body, 30);
    paintVfx(0, { engineMode: true });
    compositeWindow().__hf_page_composite_resolve!();

    expect({ below: below.drawn.length, own: own.drawn.length }).toEqual({ below: 1, own: 0 });
  });

  it("keeps drawing the layers below while the backdrop host is hidden", () => {
    const ctx = createMockCtx2d();
    const host = makeBackdropHost(ctx, "adj-1");
    initVfx(document.body, 30);
    host.style.visibility = "hidden";

    paintVfx(0, { engineMode: true });

    expect(compositeWindow().__hf_page_composite_pending).toBe(true);
    expect(compositeWindow().__hf_page_composite_resolve!()).toBe(true);
    expect({
      // Captured: the wrapper's children are invisible to the page compositor,
      // so an undrawn bitmap would delete every layer below the adjustment.
      drawn: ctx.drawn.length,
      // Cleared ONCE — before the draw. The second clear is what a painting
      // frame does to stop the raw capture showing through `.hf-vfx-out`;
      // here the bitmap IS the frame and must stay.
      cleared: ctx.cleared,
      // The kernel does not run: the adjustment layer is off.
      calls: gl!.calls,
    }).toEqual({ drawn: 1, cleared: [[320, 180]], calls: [] });
    expect(errors).toEqual([]);
  });

  it("passes the layers below through on the preview path too", async () => {
    const ctx = createMockCtx2d();
    const host = makeBackdropHost(ctx, "adj-1");
    const src = document.querySelector('canvas[data-vfx-for="adj-1"]')!;
    initVfx(document.body, 30);
    host.style.visibility = "hidden";

    paintVfx(0.5);
    src.dispatchEvent(new Event("paint"));
    await flushTasks();

    expect(ctx.drawn).toHaveLength(1);
    expect(gl!.calls).toEqual([]);
  });

  it("still skips a hidden self host, whose source is inside it", () => {
    const ctx = createMockCtx2d();
    const host = makeCaptureHost(ctx, "cap");
    initVfx(document.body, 30);
    host.style.visibility = "hidden";

    paintVfx(0, { engineMode: true });

    expect(compositeWindow().__hf_page_composite_pending).toBeUndefined();
    expect(ctx.drawn).toHaveLength(0);
  });

  it("reports a .hf-vfx-in that measures 0×0 once, not once per frame", () => {
    const ctx = createMockCtx2d();
    const host = makeCaptureHost(ctx, "cap");
    const inner = host.querySelector(".hf-vfx-in") as HTMLElement;
    sizeHost(inner, 0, 0);
    initVfx(document.body, 30);

    paintVfx(0, { engineMode: true });
    compositeWindow().__hf_page_composite_resolve!();
    paintVfx(1, { engineMode: true });
    compositeWindow().__hf_page_composite_resolve!();

    expect(ctx.drawn).toHaveLength(0);
    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", () => {
    const ctx = createMockCtx2d();
    const host = makeCaptureHost(ctx, "cap");
    const inner = host.querySelector(".hf-vfx-in")!;
    const between = document.createElement("div");
    inner.parentElement!.appendChild(between);
    between.appendChild(inner);

    // Chrome: "Only immediate children of the <canvas> element can be passed
    // to DrawElementImage" — a registration error, not a per-frame throw.
    expect(initVfx(document.body, 30)).toHaveLength(0);
    expect(String(errors[0]![1])).toMatch(/hf-vfx-in/);
  });
});

/**
 * Interface v1.1's second source: a `ref` param carrying the id of another
 * element, captured into `u_src2`. `luma-matte` is the first def to use one.
 */
describe("vfx runtime — ref (second source) params", () => {
  const REF_NODE =
    '{"version":1,"nodes":[{"type":"fractal-noise","id":"n1","params":{"matte":"matte-1"}}]}';

  /** The element a `ref` names, wrapped by the exporter like any other source. */
  function makeRefTarget(ctx: unknown, id = "matte-1", wrapped = true): HTMLElement {
    const el = document.createElement("div");
    el.id = id;
    sizeHost(el);
    if (wrapped) el.appendChild(makeCaptureWrapper(ctx));
    document.body.appendChild(el);
    return el;
  }

  beforeEach(() => installVfxHarness("self", "matte"));
  afterEach(releaseVfxHarness);

  it("captures the ref's element into u_src2 alongside the host's own u_src", () => {
    const ctx = createMockCtx2d();
    const matteCtx = createMockCtx2d();
    makeRefTarget(matteCtx);
    makeCaptureHost(ctx, "cap", REF_NODE);

    expect(initVfx(document.body, 30)).toHaveLength(1);
    paintVfx(0, { engineMode: true });
    compositeWindow().__hf_page_composite_resolve!();

    expect({ src: ctx.drawn.length, matte: matteCtx.drawn.length }).toEqual({ src: 1, matte: 1 });
    // Unit 0 is the chain's own texture, unit 1 the second source.
    expect(gl!.uniforms["u_src"]).toBe(0);
    expect(gl!.uniforms["u_src2"]).toBe(1);
    expect(errors).toEqual([]);
  });

  it("captures one texture for two nodes that name the same element", () => {
    const ctx = createMockCtx2d();
    const matteCtx = createMockCtx2d();
    makeRefTarget(matteCtx);
    makeCaptureHost(
      ctx,
      "cap",
      '{"version":1,"nodes":[{"type":"fractal-noise","id":"n1","params":{"matte":"matte-1"}},' +
        '{"type":"fractal-noise","id":"n2","params":{"matte":"matte-1"}}]}',
    );

    initVfx(document.body, 30);
    paintVfx(0, { engineMode: true });
    compositeWindow().__hf_page_composite_resolve!();

    expect(matteCtx.drawn).toHaveLength(1);
  });

  it("binds u_src2 explicitly when a MANDATORY ref names its own host", () => {
    // Unlike displacement-map's optional `map` (self-reference there is
    // treated exactly like "empty"), a mandatory ref like luma-matte's
    // `matte` has no shader-side branch to fall back on — the shader always
    // samples `u_src2`, so a self-reference needs u_src2 pointed at u_src's
    // own texture unit rather than left to an unbound sampler's default.
    const ctx = createMockCtx2d();
    makeCaptureHost(
      ctx,
      "cap",
      '{"version":1,"nodes":[{"type":"fractal-noise","id":"n1","params":{"matte":"cap"}}]}',
    );

    expect(initVfx(document.body, 30)).toHaveLength(1);
    paintVfx(0, { engineMode: true });
    compositeWindow().__hf_page_composite_resolve!();

    // One capture only — no second `drawElementImage` for the same image.
    expect(ctx.drawn).toHaveLength(1);
    expect(gl!.uniforms["u_src2"]).toBe(0);
    expect(gl!.uniforms["u_hasSrc2"]).toBe(1);
    expect(errors).toEqual([]);
  });

  it("refuses a ref whose element carries no capture wrapper", () => {
    makeRefTarget(undefined, "matte-1", false);
    makeCaptureHost(createMockCtx2d(), "cap", REF_NODE);

    expectRefused(/"matte" source/, /hf-vfx-src/);
  });

  it("refuses a ref naming an element that is not in the composition", () => {
    makeCaptureHost(createMockCtx2d(), "cap", REF_NODE);

    expectRefused(/#matte-1/, /not in the composition/);
  });

  it("refuses a node that names no ref element at all", () => {
    makeCaptureHost(createMockCtx2d(), "cap", ONE_NODE);

    expectRefused(/needs a "matte" param/);
  });

  it("captures a hidden matte as empty instead of failing the frame", async () => {
    // The exporter wraps a matte layer's own element, and the clip runtime
    // hides that element outside its window — so `.hf-vfx-in` is hidden too.
    // Waiting for a paint that cannot come would burn the 2 s ceiling on every
    // frame of a matte's out point, and drawing it would throw. Only the matte
    // ELEMENT is hidden here: the wrapper inside it inherits it, which is the
    // shape the exporter and the clip runtime actually produce.
    vi.stubGlobal("requestAnimationFrame", () => 1);
    const ctx = createMockCtx2d();
    const matteCtx = createMockCtx2d();
    const matte = makeRefTarget(matteCtx);
    const host = makeCaptureHost(ctx, "cap", REF_NODE);
    initVfx(document.body, 30);
    matte.style.visibility = "hidden";

    paintVfx(0.5);
    host.querySelector("canvas.hf-vfx-src")!.dispatchEvent(new Event("paint"));
    await flushTasks();

    expect({ src: ctx.drawn.length, matte: matteCtx.drawn.length }).toEqual({ src: 1, matte: 0 });
    // An empty u_src2, not a skipped frame: the host still paints, and the
    // kernel reads a matte that covers nothing.
    expect(gl!.calls).toEqual(["useProgram", "screen", "draw:1"]);
    expect(errors).toEqual([]);
  });

  it("treats a matte whose OWNING element is display:none as hidden too", async () => {
    // `display` does not inherit: `.hf-vfx-in` inside a `display:none` matte
    // still computes `display:block`, so a check at `inner` alone calls it
    // paintable, waits out the 2 s ceiling, then fails as a misleading 0×0.
    // The clip runtime uses `display:none` for `data-hidden` and for in-flow
    // timed leaves, so the ancestor walk has to find it.
    vi.stubGlobal("requestAnimationFrame", () => 1);
    const ctx = createMockCtx2d();
    const matteCtx = createMockCtx2d();
    const matte = makeRefTarget(matteCtx);
    const host = makeCaptureHost(ctx, "cap", REF_NODE);
    initVfx(document.body, 30);
    matte.style.display = "none";

    paintVfx(0.5);
    // Only the host's canvas paints — the matte's never will, and the frame
    // must not wait on it.
    host.querySelector("canvas.hf-vfx-src")!.dispatchEvent(new Event("paint"));
    await flushTasks();

    expect({ src: ctx.drawn.length, matte: matteCtx.drawn.length }).toEqual({ src: 1, matte: 0 });
    expect(gl!.calls).toEqual(["useProgram", "screen", "draw:1"]);
    expect(errors).toEqual([]);
  });

  it("keeps a visible ref's bitmap and draws it at the ref's own box", async () => {
    // retro-wave `Logo Anim` layer 5 is layer 4's displacement map AND a layer
    // that paints: clearing its bitmap after the upload would delete it from
    // the frame, and drawing it at the host's box would resample it.
    const ctx = createMockCtx2d();
    const matteCtx = createMockCtx2d();
    const matte = makeRefTarget(matteCtx);
    matte.querySelector("canvas.hf-vfx-src")!.setAttribute("data-vfx-ref-visible", "");
    sizeHost(matte.querySelector(".hf-vfx-in") as HTMLElement, 640, 360);
    makeCaptureHost(ctx, "cap", REF_NODE);

    initVfx(document.body, 30);
    paintVfx(0, { engineMode: true });
    compositeWindow().__hf_page_composite_resolve!();

    expect(matteCtx.drawn).toEqual([{ el: matte.querySelector(".hf-vfx-in"), w: 640, h: 360 }]);
    // Cleared once, before the draw: the bitmap that is left is the layer.
    expect(matteCtx.cleared).toEqual([[640, 360]]);
    // The host's own capture is unchanged — host box, cleared after upload.
    expect(ctx.drawn.map((d) => [d.w, d.h])).toEqual([[320, 180]]);
    expect(ctx.cleared).toEqual([
      [320, 180],
      [320, 180],
    ]);
    expect(errors).toEqual([]);
  });

  it("clears an ordinary ref's bitmap and draws it at the host's box", () => {
    const matteCtx = createMockCtx2d();
    const matte = makeRefTarget(matteCtx);
    sizeHost(matte.querySelector(".hf-vfx-in") as HTMLElement, 640, 360);
    makeCaptureHost(createMockCtx2d(), "cap", REF_NODE);

    initVfx(document.body, 30);
    paintVfx(0, { engineMode: true });
    compositeWindow().__hf_page_composite_resolve!();

    // Host box, so `u_src`, `u_src2` and `.hf-vfx-out` share a pixel grid.
    expect(matteCtx.drawn.map((d) => [d.w, d.h])).toEqual([[320, 180]]);
    expect(matteCtx.cleared).toEqual([
      [320, 180],
      [320, 180],
    ]);
  });

  it("holds the preview barrier until the ref's canvas has painted too", async () => {
    vi.stubGlobal("requestAnimationFrame", () => 1);
    const ctx = createMockCtx2d();
    const matteCtx = createMockCtx2d();
    const matte = makeRefTarget(matteCtx);
    const host = makeCaptureHost(ctx, "cap", REF_NODE);
    initVfx(document.body, 30);

    paintVfx(0.5);
    let resolved = false;
    const barrier = waitForSeekCompletion().then(() => {
      resolved = true;
    });
    host.querySelector("canvas.hf-vfx-src")!.dispatchEvent(new Event("paint"));
    await flushTasks();
    const afterHostPaint = resolved;

    matte.querySelector("canvas.hf-vfx-src")!.dispatchEvent(new Event("paint"));
    await flushTasks();
    await barrier;

    expect({ afterHostPaint, resolved, matte: matteCtx.drawn.length }).toEqual({
      afterHostPaint: false,
      resolved: true,
      matte: 1,
    });
  });

  it("still captures a visible ref while its own host is hidden", () => {
    // retro-wave `Logo Anim` layer 5's own AE layer can outlive layer 4's (the
    // kernel host's) data-start/data-duration window. Before the fix, a
    // hidden non-backdrop host was dropped entirely, so this ref went missing
    // before its host's window and stale (last captured frame) after it.
    const ctx = createMockCtx2d();
    const matteCtx = createMockCtx2d();
    const matte = makeRefTarget(matteCtx);
    matte.querySelector("canvas.hf-vfx-src")!.setAttribute("data-vfx-ref-visible", "");
    sizeHost(matte.querySelector(".hf-vfx-in") as HTMLElement, 640, 360);
    const host = makeCaptureHost(ctx, "cap", REF_NODE);
    initVfx(document.body, 30);
    host.style.visibility = "hidden";

    paintVfx(0, { engineMode: true });

    expect(compositeWindow().__hf_page_composite_pending).toBe(true);
    expect(compositeWindow().__hf_page_composite_resolve!()).toBe(true);
    expect(matteCtx.drawn).toEqual([{ el: matte.querySelector(".hf-vfx-in"), w: 640, h: 360 }]);
    // Cleared once, before the draw — kept, not re-cleared after: the bitmap
    // that is left is the ref's own on-page layer.
    expect(matteCtx.cleared).toEqual([[640, 360]]);
    // Never uploaded: no kernel runs for a hidden host, so nothing binds it.
    // The hidden host's own (non-ref) capture never runs either.
    expect({ ctx: ctx.drawn.length, calls: gl!.calls }).toEqual({ ctx: 0, calls: [] });
    expect(errors).toEqual([]);
  });

  it("captures a visible ref through the preview path even while its host is hidden", async () => {
    const ctx = createMockCtx2d();
    const matteCtx = createMockCtx2d();
    const matte = makeRefTarget(matteCtx);
    matte.querySelector("canvas.hf-vfx-src")!.setAttribute("data-vfx-ref-visible", "");
    sizeHost(matte.querySelector(".hf-vfx-in") as HTMLElement, 640, 360);
    const host = makeCaptureHost(ctx, "cap", REF_NODE);
    initVfx(document.body, 30);
    host.style.visibility = "hidden";

    paintVfx(0.5);
    // A ref-only frame waits on the REF's own canvas, never the hidden host's
    // — the host's canvas fires no "paint" at all while it stays hidden.
    matte.querySelector("canvas.hf-vfx-src")!.dispatchEvent(new Event("paint"));
    await flushTasks();

    expect({ matte: matteCtx.drawn.length, ctx: ctx.drawn.length, calls: gl!.calls }).toEqual({
      matte: 1,
      ctx: 0,
      calls: [],
    });
  });

  it("still captures a visible ref while its BACKDROP host is hidden", () => {
    // The prior fix only covered a non-backdrop hidden host: captureHiddenEntry
    // returned capturePassThrough(entry) for a backdrop and never reached
    // captureVisibleRefsOnly, so an adjustment layer whose displacement map is
    // itself a visible layer lost that layer outside the adjustment's window.
    const belowCtx = createMockCtx2d();
    const matteCtx = createMockCtx2d();
    const matte = makeRefTarget(matteCtx);
    matte.querySelector("canvas.hf-vfx-src")!.setAttribute("data-vfx-ref-visible", "");
    sizeHost(matte.querySelector(".hf-vfx-in") as HTMLElement, 640, 360);
    const host = makeBackdropHost(belowCtx, "adj-1", REF_NODE);
    initVfx(document.body, 30);
    host.style.visibility = "hidden";

    paintVfx(0, { engineMode: true });

    expect(compositeWindow().__hf_page_composite_resolve!()).toBe(true);
    // The pass-through still runs (the adjustment layer's own layers below).
    expect(belowCtx.drawn).toHaveLength(1);
    // ...and the visible ref, on a DIFFERENT element, still draws too.
    expect(matteCtx.drawn).toEqual([{ el: matte.querySelector(".hf-vfx-in"), w: 640, h: 360 }]);
    expect(errors).toEqual([]);
  });

  it("still captures a visible ref through the preview path while its BACKDROP host is hidden", async () => {
    const belowCtx = createMockCtx2d();
    const matteCtx = createMockCtx2d();
    const matte = makeRefTarget(matteCtx);
    matte.querySelector("canvas.hf-vfx-src")!.setAttribute("data-vfx-ref-visible", "");
    sizeHost(matte.querySelector(".hf-vfx-in") as HTMLElement, 640, 360);
    const host = makeBackdropHost(belowCtx, "adj-1", REF_NODE);
    const below = document.querySelector('canvas[data-vfx-for="adj-1"]')!;
    initVfx(document.body, 30);
    host.style.visibility = "hidden";

    paintVfx(0.5);
    // A pass-through frame now waits on the backdrop wrapper AND the visible
    // ref's own canvas, so both must paint before the barrier releases.
    below.dispatchEvent(new Event("paint"));
    matte.querySelector("canvas.hf-vfx-src")!.dispatchEvent(new Event("paint"));
    await flushTasks();

    expect({ below: belowCtx.drawn.length, matte: matteCtx.drawn.length }).toEqual({
      below: 1,
      matte: 1,
    });
  });
});

/**
 * `displacement-map`'s `map` ref (plan Backlog, "one-line def change after
 * Task 2.6"). Optional, so the self-referential form every corpus instance
 * uses keeps working untouched.
 */
describe("vfx runtime — an optional ref (displacement-map's map)", () => {
  const mapChain = (params: Record<string, unknown>): string =>
    JSON.stringify({
      version: 1,
      nodes: [{ type: "displacement-map", id: "n1", params }],
    });

  function makeMapTarget(ctx: unknown, id = "map-1"): HTMLElement {
    const el = document.createElement("div");
    el.id = id;
    sizeHost(el);
    el.appendChild(makeCaptureWrapper(ctx));
    document.body.appendChild(el);
    return el;
  }

  beforeEach(() => installVfxHarness(null));
  afterEach(releaseVfxHarness);

  it("binds a named map element as u_src2 and tells the kernel it is there", () => {
    const ctx = createMockCtx2d();
    const mapCtx = createMockCtx2d();
    const map = makeMapTarget(mapCtx);
    makeCaptureHost(ctx, "cap", mapChain({ useH: 1, maxH: 20, map: "map-1" }));

    expect(initVfx(document.body, 30)).toHaveLength(1);
    paintVfx(0, { engineMode: true });
    compositeWindow().__hf_page_composite_resolve!();

    expect(mapCtx.drawn[0]!.el).toBe(map.querySelector(".hf-vfx-in"));
    expect(gl!.uniforms["u_src2"]).toBe(1);
    expect(gl!.uniforms["u_hasSrc2"]).toBe(1);
    expect(errors).toEqual([]);
  });

  it("falls back to the layer's own pixels when the map is empty", () => {
    const ctx = createMockCtx2d();
    makeCaptureHost(ctx, "cap", mapChain({ useH: 1, maxH: 20 }));

    expect(initVfx(document.body, 30)).toHaveLength(1);
    paintVfx(0, { engineMode: true });
    compositeWindow().__hf_page_composite_resolve!();

    // One capture, not two, and the kernel is told to read `u_src` as its map.
    expect(ctx.drawn).toHaveLength(1);
    expect(gl!.uniforms["u_hasSrc2"]).toBe(0);
    expect(errors).toEqual([]);
  });

  it("treats a map naming the host itself as the self-referential form", () => {
    const ctx = createMockCtx2d();
    makeCaptureHost(ctx, "cap", mapChain({ useH: 1, maxH: 20, map: "cap" }));

    expect(initVfx(document.body, 30)).toHaveLength(1);
    paintVfx(0, { engineMode: true });
    compositeWindow().__hf_page_composite_resolve!();

    expect(ctx.drawn).toHaveLength(1);
    expect(gl!.uniforms["u_hasSrc2"]).toBe(0);
    expect(errors).toEqual([]);
  });

  it("still refuses a map that names an element with no capture wrapper", () => {
    const orphan = document.createElement("div");
    orphan.id = "map-1";
    document.body.appendChild(orphan);
    makeCaptureHost(createMockCtx2d(), "cap", mapChain({ map: "map-1" }));

    expect(initVfx(document.body, 30)).toHaveLength(0);
    expect(String(errors[0]![1])).toMatch(/"map" source/);
  });
});