Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
/**
* Unit tests for the pure functions in iframe.ts (no browser needed).
*
* elementFromPoint requires a real layout engine — the adapter's elementAtPoint()
* is NOT tested here. Cover it with an integration test mounting a same-origin
* iframe (WS-A1 follow-on).
*
* applyDraft / commitPreview / cancelPreview require HTMLElement.style + querySelector
* which are also browser-only. They are tested via a lightweight fake-DOM helper
* that simulates style.setProperty / getAttribute / removeProperty.
*
* WS-G image-alpha tests cover:
* - alphaIsOpaque (pure predicate)
* - mapPointToImagePixel (pure coordinate mapping)
* - z-stack fallthrough via mock elementsFromPoint
* - canvas taint → opaque fallback
* - non-image regression (WS-A1 opacity behavior unchanged)
*
* Paint-query tests (elementPaintsInk / compositionPaintsAt / isProvablyEmptyAt) live at
* bottom of this file and carry their own fake-DOM helpers: the walk is geometric, so
* they need element boxes and computed style rather than a hit-test stack.
*/
import { describe, it, expect, vi, beforeEach } from "vitest";
import {
resolveNearestHfElement,
computeDraftPosition,
createIframePreviewAdapter,
alphaIsOpaque,
mapPointToImagePixel,
elementPaintsInk,
compositionPaintsAt,
_imgCanvasCache,
} from "./iframe.js";
import type { ElementAtPointResult } from "./types.js";
import type { EditOp } from "../types.js";
// ─── Minimal fake element ────────────────────────────────────────────────────
interface FakeEl {
attrs: Record<string, string>;
tagName: string;
parentElement: FakeEl | null;
getAttribute(name: string): string | null;
hasAttribute(name: string): boolean;
}
function fakeEl(
attrs: Record<string, string>,
tagName: string,
parent: FakeEl | null = null,
): FakeEl {
return {
attrs,
tagName,
parentElement: parent,
getAttribute(name) {
return Object.prototype.hasOwnProperty.call(this.attrs, name) ? this.attrs[name] : null;
},
hasAttribute(name) {
return Object.prototype.hasOwnProperty.call(this.attrs, name);
},
};
}
const visible = () => true;
const invisible = () => false;
// ─── resolveNearestHfElement ──────────────────────────────────────────────────
describe("resolveNearestHfElement", () => {
it("returns null for a null input", () => {
expect(resolveNearestHfElement(null, visible)).toBeNull();
});
it("returns the element itself when it carries data-hf-id", () => {
const el = fakeEl({ "data-hf-id": "hf-abc" }, "div");
const result = resolveNearestHfElement(el as unknown as Element, visible);
expect(result).toEqual<ElementAtPointResult>({ id: "hf-abc", tag: "div" });
});
it("walks up to a parent that carries data-hf-id", () => {
const parent = fakeEl({ "data-hf-id": "hf-parent" }, "section");
const child = fakeEl({}, "span", parent);
const result = resolveNearestHfElement(child as unknown as Element, visible);
expect(result).toEqual<ElementAtPointResult>({ id: "hf-parent", tag: "section" });
});
it("returns null when the nearest data-hf-id node is data-hf-root", () => {
const root = fakeEl({ "data-hf-id": "hf-stage", "data-hf-root": "" }, "div");
const child = fakeEl({}, "p", root);
expect(resolveNearestHfElement(child as unknown as Element, visible)).toBeNull();
});
it("returns null when the element itself is data-hf-root", () => {
const root = fakeEl({ "data-hf-id": "hf-stage", "data-hf-root": "" }, "div");
expect(resolveNearestHfElement(root as unknown as Element, visible)).toBeNull();
});
it("returns null when isVisible returns false for the matching element", () => {
const el = fakeEl({ "data-hf-id": "hf-abc" }, "div");
expect(resolveNearestHfElement(el as unknown as Element, invisible)).toBeNull();
});
it("skips an opacity-0 element and returns null (isVisible called on the resolved node)", () => {
const parent = fakeEl({ "data-hf-id": "hf-parent" }, "div");
const child = fakeEl({}, "span", parent);
const isVisible = vi.fn((el: Element) => {
const fe = el as unknown as FakeEl;
return fe.attrs["data-hf-id"] !== "hf-parent";
});
expect(resolveNearestHfElement(child as unknown as Element, isVisible)).toBeNull();
expect(isVisible).toHaveBeenCalledTimes(1);
});
it("returns null when no data-hf-id found in any ancestor", () => {
const grandparent = fakeEl({}, "body");
const parent = fakeEl({}, "div", grandparent);
const child = fakeEl({}, "span", parent);
expect(resolveNearestHfElement(child as unknown as Element, visible)).toBeNull();
});
it("tag is lowercased", () => {
const el = fakeEl({ "data-hf-id": "hf-xyz" }, "DIV");
const result = resolveNearestHfElement(el as unknown as Element, visible);
expect(result?.tag).toBe("div");
});
it("stops at the nearest ancestor — does not continue past first data-hf-id", () => {
const outer = fakeEl({ "data-hf-id": "hf-outer" }, "section");
const inner = fakeEl({ "data-hf-id": "hf-inner" }, "div", outer);
const child = fakeEl({}, "span", inner);
const result = resolveNearestHfElement(child as unknown as Element, visible);
expect(result?.id).toBe("hf-inner");
});
});
// ─── computeDraftPosition ─────────────────────────────────────────────────────
describe("computeDraftPosition", () => {
it("applies delta to base data-x/data-y", () => {
expect(computeDraftPosition("100", "200", 30, -10)).toEqual({ x: 130, y: 190 });
});
it("defaults missing data-x/data-y to 0", () => {
expect(computeDraftPosition(null, null, 50, 25)).toEqual({ x: 50, y: 25 });
});
it("defaults non-numeric data-x/data-y to 0", () => {
expect(computeDraftPosition("abc", "xyz", 10, 5)).toEqual({ x: 10, y: 5 });
});
it("works with zero delta (no-move commit)", () => {
expect(computeDraftPosition("40", "80", 0, 0)).toEqual({ x: 40, y: 80 });
});
it("handles negative base positions", () => {
expect(computeDraftPosition("-20", "0", 5, 10)).toEqual({ x: -15, y: 10 });
});
});
// ─── IframePreviewAdapter selection ──────────────────────────────────────────
function stubIframe() {
return {} as HTMLIFrameElement;
}
describe("IframePreviewAdapter selection", () => {
it("on('selection') fires when select() is called", () => {
const adapter = createIframePreviewAdapter(stubIframe());
const cb = vi.fn();
adapter.on("selection", cb);
adapter.select(["hf-abc"]);
expect(cb).toHaveBeenCalledWith(["hf-abc"]);
});
it("off unsubscribes the handler", () => {
const adapter = createIframePreviewAdapter(stubIframe());
const cb = vi.fn();
const off = adapter.on("selection", cb);
off();
adapter.select(["hf-abc"]);
expect(cb).not.toHaveBeenCalled();
});
it("additive select merges with prior selection", () => {
const adapter = createIframePreviewAdapter(stubIframe());
const cb = vi.fn();
adapter.on("selection", cb);
adapter.select(["hf-a"]);
adapter.select(["hf-b"], { additive: true });
expect(cb).toHaveBeenLastCalledWith(expect.arrayContaining(["hf-a", "hf-b"]));
});
it("non-additive select replaces prior selection", () => {
const adapter = createIframePreviewAdapter(stubIframe());
const cb = vi.fn();
adapter.on("selection", cb);
adapter.select(["hf-a"]);
adapter.select(["hf-b"]);
expect(cb).toHaveBeenLastCalledWith(["hf-b"]);
});
it("multiple handlers all fire", () => {
const adapter = createIframePreviewAdapter(stubIframe());
const cb1 = vi.fn();
const cb2 = vi.fn();
adapter.on("selection", cb1);
adapter.on("selection", cb2);
adapter.select(["hf-abc"]);
expect(cb1).toHaveBeenCalledOnce();
expect(cb2).toHaveBeenCalledOnce();
});
});
// ─── applyDraft / commitPreview / cancelPreview ───────────────────────────────
// Tests use a fake iframe+element because HTMLElement.style requires a browser.
interface FakeStyle {
_props: Record<string, string>;
setProperty(name: string, value: string): void;
getPropertyValue(name: string): string;
removeProperty(name: string): void;
}
interface FakeDomEl {
_attrs: Record<string, string>;
style: FakeStyle;
isConnected: boolean;
getAttribute(name: string): string | null;
setAttribute(name: string, value: string): void;
hasAttribute(name: string): boolean;
querySelector(sel: string): FakeDomEl | null;
}
function fakeDomEl(id: string, dataX: string | null, dataY: string | null): FakeDomEl {
const style: FakeStyle = {
_props: {},
setProperty(name, value) {
this._props[name] = value;
},
getPropertyValue(name) {
return this._props[name] ?? "";
},
removeProperty(name) {
delete this._props[name];
},
};
const attrs: Record<string, string> = { "data-hf-id": id };
if (dataX !== null) attrs["data-x"] = dataX;
if (dataY !== null) attrs["data-y"] = dataY;
const el: FakeDomEl = {
_attrs: attrs,
style,
isConnected: true,
getAttribute(name) {
return this._attrs[name] ?? null;
},
setAttribute(name, value) {
this._attrs[name] = value;
},
hasAttribute(name) {
return name in this._attrs;
},
querySelector(_sel: string) {
return null;
},
};
return el;
}
function fakeIframe(el: FakeDomEl | null): HTMLIFrameElement {
return {
contentDocument: {
querySelector(_sel: string) {
return el;
},
},
} as unknown as HTMLIFrameElement;
}
describe("IframePreviewAdapter draft / commit / cancel", () => {
it("commitPreview without applyDraft is a no-op", () => {
const dispatch = vi.fn();
const adapter = createIframePreviewAdapter(stubIframe(), dispatch);
adapter.commitPreview();
expect(dispatch).not.toHaveBeenCalled();
});
it("cancelPreview without applyDraft is a no-op", () => {
const dispatch = vi.fn();
const adapter = createIframePreviewAdapter(stubIframe(), dispatch);
adapter.cancelPreview();
expect(dispatch).not.toHaveBeenCalled();
});
it("commitPreview dispatches moveElement with correct absolute position", () => {
const dispatch = vi.fn();
const el = fakeDomEl("hf-abc", "100", "200");
const adapter = createIframePreviewAdapter(fakeIframe(el), dispatch);
adapter.applyDraft("hf-abc", { dx: 30, dy: -20 });
adapter.commitPreview();
expect(dispatch).toHaveBeenCalledWith<[EditOp]>({
type: "moveElement",
target: "hf-abc",
x: 130,
y: 180,
});
});
it("commitPreview with missing data-x/data-y defaults base to 0", () => {
const dispatch = vi.fn();
const el = fakeDomEl("hf-abc", null, null);
const adapter = createIframePreviewAdapter(fakeIframe(el), dispatch);
adapter.applyDraft("hf-abc", { dx: 50, dy: 25 });
adapter.commitPreview();
expect(dispatch).toHaveBeenCalledWith<[EditOp]>({
type: "moveElement",
target: "hf-abc",
x: 50,
y: 25,
});
});
it("commitPreview mirrors the move onto the live element and applies the translate", () => {
const el = fakeDomEl("hf-abc", "100", "200");
const adapter = createIframePreviewAdapter(fakeIframe(el), vi.fn());
adapter.applyDraft("hf-abc", { dx: 30, dy: -20 });
adapter.commitPreview();
expect(el.getAttribute("data-x")).toBe("130");
expect(el.getAttribute("data-y")).toBe("180");
// Baseline captured from the pre-drag values.
expect(el.getAttribute("data-hf-edit-base-x")).toBe("100");
expect(el.getAttribute("data-hf-edit-base-y")).toBe("200");
// Final translate = delta from the baseline, held without a reload.
expect(el.getAttribute("data-hf-edit-original-translate")).toBe("");
expect(el.style.getPropertyValue("translate")).toBe("30px -20px");
// A second drag composes from the committed state and keeps the baseline.
adapter.applyDraft("hf-abc", { dx: 10, dy: 10 });
expect(el.style.getPropertyValue("translate")).toBe("40px -10px");
adapter.commitPreview();
expect(el.getAttribute("data-x")).toBe("140");
expect(el.getAttribute("data-hf-edit-base-x")).toBe("100");
expect(el.style.getPropertyValue("translate")).toBe("40px -10px");
});
it("applyDraft translates the element live and cancelPreview restores it", () => {
const el = fakeDomEl("hf-abc", "0", "0");
el.style.setProperty("translate", "5px 6px");
const adapter = createIframePreviewAdapter(fakeIframe(el), vi.fn());
adapter.applyDraft("hf-abc", { dx: 30, dy: -20 });
expect(el.style.getPropertyValue("translate")).toBe("35px -14px");
adapter.cancelPreview();
expect(el.style.getPropertyValue("translate")).toBe("5px 6px");
expect(el.getAttribute("data-hf-edit-base-x")).toBeNull();
});
it("cancelPreview removes a draft translate when there was none before", () => {
const el = fakeDomEl("hf-abc", "0", "0");
const adapter = createIframePreviewAdapter(fakeIframe(el), vi.fn());
adapter.applyDraft("hf-abc", { dx: 30 });
expect(el.style.getPropertyValue("translate")).toBe("30px 0px");
adapter.cancelPreview();
expect(el.style.getPropertyValue("translate")).toBe("");
});
it("applyDraft reuses the cached element across repeated calls (no re-query)", () => {
const el = fakeDomEl("hf-abc", "0", "0");
let queryCount = 0;
const iframe = {
contentDocument: {
querySelector(_sel: string) {
queryCount++;
return el;
},
},
} as unknown as HTMLIFrameElement;
const adapter = createIframePreviewAdapter(iframe);
adapter.applyDraft("hf-abc", { dx: 1, dy: 1 });
adapter.applyDraft("hf-abc", { dx: 2, dy: 2 });
adapter.applyDraft("hf-abc", { dx: 3, dy: 3 });
// Queried once on the first call; the next two reuse the connected cache.
expect(queryCount).toBe(1);
});
it("commitPreview without a dispatch callback is a no-op", () => {
const el = fakeDomEl("hf-abc", "0", "0");
const adapter = createIframePreviewAdapter(fakeIframe(el));
adapter.applyDraft("hf-abc", { dx: 10, dy: 10 });
// should not throw
adapter.commitPreview();
});
it("cancelPreview reverts the draft translate without dispatching", () => {
const dispatch = vi.fn();
const el = fakeDomEl("hf-abc", "100", "200");
const adapter = createIframePreviewAdapter(fakeIframe(el), dispatch);
adapter.applyDraft("hf-abc", { dx: 30, dy: 20 });
expect(el.style.getPropertyValue("translate")).toBe("30px 20px");
adapter.cancelPreview();
expect(dispatch).not.toHaveBeenCalled();
expect(el.style.getPropertyValue("translate")).toBe("");
});
it("second commitPreview after first is a no-op (draft cleared)", () => {
const dispatch = vi.fn();
const el = fakeDomEl("hf-abc", "0", "0");
const adapter = createIframePreviewAdapter(fakeIframe(el), dispatch);
adapter.applyDraft("hf-abc", { dx: 10, dy: 5 });
adapter.commitPreview();
adapter.commitPreview();
expect(dispatch).toHaveBeenCalledTimes(1);
});
it("switching applyDraft to a new id reverts the abandoned element", () => {
const elA = fakeDomEl("hf-a", "0", "0");
const elB = fakeDomEl("hf-b", "0", "0");
const iframe = {
contentDocument: {
querySelector(sel: string) {
return sel.includes("hf-a") ? elA : elB;
},
},
} as unknown as HTMLIFrameElement;
const adapter = createIframePreviewAdapter(iframe, vi.fn());
adapter.applyDraft("hf-a", { dx: 80, dy: 0 });
expect(elA.style.getPropertyValue("translate")).toBe("80px 0px");
adapter.applyDraft("hf-b", { dx: 10, dy: 10 });
// The abandoned element is restored; the delta does not carry over.
expect(elA.style.getPropertyValue("translate")).toBe("");
expect(elB.style.getPropertyValue("translate")).toBe("10px 10px");
});
it("commitPreview reverts the draft translate when dispatch throws", () => {
const el = fakeDomEl("hf-abc", "0", "0");
el.style.setProperty("translate", "5px 6px");
const dispatch = vi.fn(() => {
throw new Error("element_not_found");
});
const adapter = createIframePreviewAdapter(fakeIframe(el), dispatch);
adapter.applyDraft("hf-abc", { dx: 30, dy: 20 });
expect(() => adapter.commitPreview()).toThrow("element_not_found");
expect(el.style.getPropertyValue("translate")).toBe("5px 6px");
expect(el.getAttribute("data-hf-edit-base-x")).toBeNull();
});
it("cancelPreview does not promote a computed (stylesheet) translate to inline", () => {
const el = fakeDomEl("hf-abc", "0", "0");
// Simulate a stylesheet-authored translate visible only via computed style.
(el as unknown as { ownerDocument: unknown }).ownerDocument = {
defaultView: {
getComputedStyle: () => ({ getPropertyValue: () => "-50% -50%" }),
},
};
const adapter = createIframePreviewAdapter(fakeIframe(el), vi.fn());
adapter.applyDraft("hf-abc", { dx: 30, dy: 20 });
// Draft composes onto the computed baseline (calc for non-px units).
expect(el.style.getPropertyValue("translate")).toBe("calc(-50% + 30px) calc(-50% + 20px)");
adapter.cancelPreview();
// Inline translate removed — the stylesheet value stays authoritative.
expect(el.style.getPropertyValue("translate")).toBe("");
});
});
// ─── WS-G: alphaIsOpaque ──────────────────────────────────────────────────────
describe("alphaIsOpaque", () => {
function makeImageData(alpha: number): ImageData {
const data = new Uint8ClampedArray([255, 0, 0, alpha]);
return { data, width: 1, height: 1, colorSpace: "srgb" } as unknown as ImageData;
}
it("returns false for a fully transparent pixel (a=0)", () => {
expect(alphaIsOpaque(makeImageData(0))).toBe(false);
});
it("returns true for a fully opaque pixel (a=255)", () => {
expect(alphaIsOpaque(makeImageData(255))).toBe(true);
});
it("returns true for alpha at default threshold (a=1 >= 1)", () => {
expect(alphaIsOpaque(makeImageData(1), 1)).toBe(true);
});
it("respects a custom threshold: a=100 < threshold=128 → false", () => {
expect(alphaIsOpaque(makeImageData(100), 128)).toBe(false);
});
it("respects a custom threshold: a=200 >= threshold=128 → true", () => {
expect(alphaIsOpaque(makeImageData(200), 128)).toBe(true);
});
it("threshold edge: a === threshold → true", () => {
expect(alphaIsOpaque(makeImageData(64), 64)).toBe(true);
});
});
// ─── WS-G: mapPointToImagePixel ───────────────────────────────────────────────
describe("mapPointToImagePixel", () => {
// A 200×100 CSS box displaying a 400×200 natural image.
const rect = { left: 10, top: 20, width: 200, height: 100 };
const natural = { width: 400, height: 200 };
it("fill: maps center of box to center of natural image", () => {
const result = mapPointToImagePixel(rect, natural, "fill", "50% 50%", {
x: rect.left + rect.width / 2,
y: rect.top + rect.height / 2,
});
expect(result).toEqual({ px: 200, py: 100 });
});
it("fill: maps top-left corner to natural (0, 0)", () => {
const result = mapPointToImagePixel(rect, natural, "fill", "50% 50%", {
x: rect.left,
y: rect.top,
});
expect(result).toEqual({ px: 0, py: 0 });
});
it("fill: maps bottom-right corner to natural (399, 199)", () => {
const result = mapPointToImagePixel(rect, natural, "fill", "50% 50%", {
x: rect.left + rect.width,
y: rect.top + rect.height,
});
// rect.width maps to naturalWidth → px = floor(200/200 * 400) = 400, clamped to 399
expect(result).toEqual({ px: 399, py: 199 });
});
it("returns null when point is outside the CSS box (left)", () => {
const result = mapPointToImagePixel(rect, natural, "fill", "50% 50%", {
x: rect.left - 1,
y: rect.top + 10,
});
expect(result).toBeNull();
});
it("returns null when point is outside the CSS box (above)", () => {
const result = mapPointToImagePixel(rect, natural, "fill", "50% 50%", {
x: rect.left + 10,
y: rect.top - 1,
});
expect(result).toBeNull();
});
describe("cover", () => {
// 200×100 box, 100×100 natural → scale = max(2, 1) = 2 (cover clips Y;
// the 200×200 rendered image overflows top/bottom — cover never letterboxes)
// rendered: 200×200; centered by default (50% 50%)
// imgTop = (100 - 200)/2 = -50; imgLeft = (200-200)/2 = 0
const coverRect = { left: 0, top: 0, width: 200, height: 100 };
const coverNatural = { width: 100, height: 100 };
it("cover: point in center maps to center of natural image", () => {
// x=100, y=50 → rx=100-0=100, ry=50-(-50)=100; px=100/2=50, py=100/2=50
const result = mapPointToImagePixel(coverRect, coverNatural, "cover", "50% 50%", {
x: 100,
y: 50,
});
expect(result).toEqual({ px: 50, py: 50 });
});
});
describe("contain", () => {
// 200×100 box, 400×100 natural → scale = min(0.5, 1) = 0.5
// rendered: 200×50; centered by default
// imgLeft = (200-200)/2 = 0; imgTop = (100-50)/2 = 25
const containRect = { left: 0, top: 0, width: 200, height: 100 };
const containNatural = { width: 400, height: 100 };
it("contain: point in rendered area maps to natural pixel", () => {
// y=50 → ry = 50-25 = 25; py = 25/0.5 = 50
// x=100 → rx = 100-0 = 100; px = 100/0.5 = 200
const result = mapPointToImagePixel(containRect, containNatural, "contain", "50% 50%", {
x: 100,
y: 50,
});
expect(result).toEqual({ px: 200, py: 50 });
});
it("contain: point in letterbox region (above image) → null", () => {
// imgTop = 25; y=10 → ry=10-25 = -15 → null
const result = mapPointToImagePixel(containRect, containNatural, "contain", "50% 50%", {
x: 100,
y: 10,
});
expect(result).toBeNull();
});
it("contain: point in letterbox region (below image) → null", () => {
// imgTop = 25; rendered height = 50 → imgBottom = 75; y=80 > 75 → null
const result = mapPointToImagePixel(containRect, containNatural, "contain", "50% 50%", {
x: 100,
y: 80,
});
expect(result).toBeNull();
});
});
it("out-of-box point returns null regardless of object-fit", () => {
const r = { left: 50, top: 50, width: 100, height: 100 };
const n = { width: 200, height: 200 };
// Point to the left of the CSS box
expect(mapPointToImagePixel(r, n, "cover", "50% 50%", { x: 49, y: 100 })).toBeNull();
});
describe("none", () => {
// object-fit:none draws the image at natural size, positioned in the box.
// box 100×100, natural 50×50, "50% 50%" → availX=availY=50, offset=25.
const r = { left: 0, top: 0, width: 100, height: 100 };
const n = { width: 50, height: 50 };
it("none: box center maps to image center", () => {
// click (50,50): px=floor(50-25)=25, py=25
expect(mapPointToImagePixel(r, n, "none", "50% 50%", { x: 50, y: 50 })).toEqual({
px: 25,
py: 25,
});
});
it("none: point inside the box but outside the natural-size image → null", () => {
// image occupies 25..75; click at (10,10) is left/above it
expect(mapPointToImagePixel(r, n, "none", "50% 50%", { x: 10, y: 10 })).toBeNull();
});
});
describe("object-position", () => {
// contain so object-position has an effect on the vertical axis.
// box 200×100, natural 400×100 → scale 0.5, rendered 200×50; availX=0, availY=50.
const r = { left: 0, top: 0, width: 200, height: 100 };
const n = { width: 400, height: 100 };
it("'left top' aligns the image to the top of the box", () => {
expect(mapPointToImagePixel(r, n, "contain", "left top", { x: 0, y: 0 })).toEqual({
px: 0,
py: 0,
});
});
it("reversed keyword pair 'top left' resolves identically to 'left top'", () => {
const reversed = mapPointToImagePixel(r, n, "contain", "top left", { x: 0, y: 0 });
const canonical = mapPointToImagePixel(r, n, "contain", "left top", { x: 0, y: 0 });
expect(reversed).toEqual(canonical);
expect(reversed).toEqual({ px: 0, py: 0 });
});
it("'bottom left' (vertical-first) and 'left bottom' both align bottom-left", () => {
// bottom → imgTop=availY=50; bottom edge click y=100 → ry=50 → py=floor(50/0.5)=100→clamp 99
const vh = mapPointToImagePixel(r, n, "contain", "bottom left", { x: 0, y: 100 });
const hv = mapPointToImagePixel(r, n, "contain", "left bottom", { x: 0, y: 100 });
expect(vh).toEqual(hv);
expect(vh).toEqual({ px: 0, py: 99 });
});
it("supports pixel object-position values", () => {
// "0px 10px" → imgTop=10; click (0,10) → ry=0 → py=0
expect(mapPointToImagePixel(r, n, "contain", "0px 10px", { x: 0, y: 10 })).toEqual({
px: 0,
py: 0,
});
});
});
it("cover/contain returns null for a zero-dimension natural image", () => {
const r = { left: 0, top: 0, width: 200, height: 100 };
expect(
mapPointToImagePixel(r, { width: 0, height: 100 }, "cover", "50% 50%", { x: 10, y: 10 }),
).toBeNull();
});
});
// ─── WS-G: z-stack fallthrough (mock elementsFromPoint) ──────────────────────
/**
* WS-G z-stack tests.
*
* The adapter's elementAtPoint uses elementsFromPoint (z-stack) and checks
* `candidate instanceof win.HTMLImageElement`. Since happy-dom / the Bun test
* runner doesn't expose a global HTMLImageElement, we supply a local stub
* class and wire it into the fake contentWindow so the instanceof check works.
*
* Canvas pixel reads (getImageData) are unavailable in the test environment, so
* we patch globalThis.OffscreenCanvas to control alpha values:
* - opaque: getImageData → alpha=255
* - transparent: getImageData → alpha=0
* - tainted: getImageData → throws SecurityError
*/
// ─── Stub HTMLImageElement (no global in Node/Bun) ───────────────────────────
class FakeHTMLImageElement {
attrs: Record<string, string>;
tagName: string;
parentElement: FakeHTMLImageElement | null;
/** A clear pixel falls through to the style/own-text checks, which read this. */
childNodes: Array<{ nodeType: number; textContent: string }> = [];
naturalWidth: number;
naturalHeight: number;
currentSrc: string;
src: string;
constructor(id: string, parent: FakeHTMLImageElement | null = null) {
this.attrs = { "data-hf-id": id };
this.tagName = "IMG";
this.parentElement = parent;
this.naturalWidth = 100;
this.naturalHeight = 100;
this.currentSrc = `http://example.com/img-${id}.png`;
this.src = `http://example.com/img-${id}.png`;
}
getBoundingClientRect(): DOMRect {
return { left: 0, top: 0, width: 100, height: 100, right: 100, bottom: 100 } as DOMRect;
}
getAttribute(name: string): string | null {
return Object.prototype.hasOwnProperty.call(this.attrs, name) ? this.attrs[name] : null;
}
hasAttribute(name: string): boolean {
return Object.prototype.hasOwnProperty.call(this.attrs, name);
}
}
// WS-G tests reuse the existing FakeEl / fakeEl helper from above.
// buildFakeIframeWithStack accepts FakeEl or FakeHTMLImageElement.
function buildFakeIframeWithStack(stack: Array<FakeEl | FakeHTMLImageElement>) {
return {
contentDocument: {
elementsFromPoint(_x: number, _y: number) {
return stack;
},
},
contentWindow: {
// Supply our stub class so `candidate instanceof win.HTMLImageElement` works
HTMLImageElement: FakeHTMLImageElement,
getComputedStyle(_el: Element) {
return { opacity: "1" } as CSSStyleDeclaration;
},
},
} as unknown as HTMLIFrameElement;
}
// ─── OffscreenCanvas stub helpers ────────────────────────────────────────────
type CanvasAlphaBehavior = "opaque" | "transparent" | "tainted";
function stubOffscreenCanvas(behavior: CanvasAlphaBehavior): () => void {
const orig = globalThis.OffscreenCanvas as typeof OffscreenCanvas | undefined;
globalThis.OffscreenCanvas = class {
width: number;
height: number;
constructor(w: number, h: number) {
this.width = w;
this.height = h;
}
getContext(_type: string) {
return {
drawImage() {},
getImageData() {
if (behavior === "tainted") {
throw new DOMException("Tainted canvases may not be exported.", "SecurityError");
}
const alpha = behavior === "opaque" ? 255 : 0;
return { data: new Uint8ClampedArray([255, 0, 0, alpha]), width: 1, height: 1 };
},
};
}
} as unknown as typeof OffscreenCanvas;
return () => {
if (orig === undefined) {
delete (globalThis as Record<string, unknown>).OffscreenCanvas;
} else {
globalThis.OffscreenCanvas = orig;
}
};
}
/**
* Run a z-stack image-alpha test with a controlled canvas behavior.
* Abstracts the restore/try/finally boilerplate shared across multiple tests.
*/
function withCanvasStub(
behavior: CanvasAlphaBehavior,
fn: (
makeImgStack: (
imgId: string,
behind?: Array<FakeEl | FakeHTMLImageElement>,
) => HTMLIFrameElement,
) => void,
): void {
const restore = stubOffscreenCanvas(behavior);
try {
fn((imgId, behind = []) => {
const img = new FakeHTMLImageElement(imgId);
return buildFakeIframeWithStack([img, ...behind]);
});
} finally {
restore();
}
}
describe("WS-G: z-stack fallthrough via mock elementsFromPoint", () => {
// Clear the module-level canvas cache before each test so stubs from a
// previous test don't affect the next one.
beforeEach(() => {
_imgCanvasCache.clear();
});
it("non-image hit resolves normally (WS-A1 regression)", () => {
// No images in the stack — should behave exactly like WS-A1.
const div = fakeEl({ "data-hf-id": "hf-div" }, "DIV");
const iframe = buildFakeIframeWithStack([div]);
const adapter = createIframePreviewAdapter(iframe);
const result = adapter.elementAtPoint(50, 50);
expect(result).toEqual({ id: "hf-div", tag: "div" });
});
it("opaque image hit resolves to the image element", () => {
withCanvasStub("opaque", (makeImgStack) => {
const iframe = makeImgStack("hf-img", [fakeEl({ "data-hf-id": "hf-behind" }, "DIV")]);
const result = createIframePreviewAdapter(iframe).elementAtPoint(50, 50);
expect(result).toEqual({ id: "hf-img", tag: "img" });
});
});
it("transparent image pixel falls through to the element behind", () => {
withCanvasStub("transparent", (makeImgStack) => {
const iframe = makeImgStack("hf-img", [fakeEl({ "data-hf-id": "hf-behind" }, "DIV")]);
const result = createIframePreviewAdapter(iframe).elementAtPoint(50, 50);
expect(result).toEqual({ id: "hf-behind", tag: "div" });
});
});
it("tainted canvas (SecurityError) falls back to treating pixel as opaque", () => {
// Taint fallback → opaque → hit the image, not the behind-layer element
withCanvasStub("tainted", (makeImgStack) => {
const iframe = makeImgStack("hf-tainted", [fakeEl({ "data-hf-id": "hf-behind" }, "DIV")]);
const result = createIframePreviewAdapter(iframe).elementAtPoint(50, 50);
expect(result).toEqual({ id: "hf-tainted", tag: "img" });
});
});
it("transparent image over transparent image falls through to the div behind both", () => {
// Two consecutive transparent fallthroughs — exercises the loop iterating
// past more than one transparent image before hitting an opaque layer.
withCanvasStub("transparent", (makeImgStack) => {
const img2 = new FakeHTMLImageElement("hf-img2");
const iframe = makeImgStack("hf-img1", [img2, fakeEl({ "data-hf-id": "hf-behind" }, "DIV")]);
const result = createIframePreviewAdapter(iframe).elementAtPoint(50, 50);
expect(result).toEqual({ id: "hf-behind", tag: "div" });
});
});
it("transparent image with no element behind returns null", () => {
// No behind element in stack — transparent hit returns null.
withCanvasStub("transparent", (makeImgStack) => {
const iframe = makeImgStack("hf-img");
const result = createIframePreviewAdapter(iframe).elementAtPoint(50, 50);
expect(result).toBeNull();
});
});
it("survives a window without HTMLImageElement and a doc without elementsFromPoint", () => {
const div = fakeEl({ "data-hf-id": "hf-div" }, "DIV");
const fakeIframe = (doc: unknown, win: unknown) =>
({ contentDocument: doc, contentWindow: win }) as unknown as HTMLIFrameElement;
const expected = { id: "hf-div", tag: "div" };
// No HTMLImageElement on the window — `instanceof` must not throw.
const noCtor = fakeIframe(
{ elementsFromPoint: () => [div] },
{ getComputedStyle: () => ({ opacity: "1" }) },
);
expect(createIframePreviewAdapter(noCtor).elementAtPoint(50, 50)).toEqual(expected);
// No elementsFromPoint on the doc — fall back to elementFromPoint.
const noStack = fakeIframe(
{ elementFromPoint: () => div },
{ HTMLImageElement: FakeHTMLImageElement, getComputedStyle: () => ({ opacity: "1" }) },
);
expect(createIframePreviewAdapter(noStack).elementAtPoint(50, 50)).toEqual(expected);
});
});
// ─── Paint query: elementPaintsInk / compositionPaintsAt / isProvablyEmptyAt ───
/**
* The paint query decides whether a host layering a transparent composition over
* other content swallows a click or lets it through, so both directions matter: a
* false negative makes visible artwork unclickable, a false positive makes the
* composition opaque to interaction again.
*
* These need richer fakes than the resolver tests above — boxes, computed style and
* a document to walk — because the walk is geometric rather than a z-stack.
*/
interface PaintRect {
left: number;
top: number;
width: number;
height: number;
}
const PAINT_DEFAULT_STYLE: Record<string, string> = {
display: "block",
visibility: "visible",
opacity: "1",
backgroundColor: "rgba(0, 0, 0, 0)",
backgroundImage: "none",
};
const paintStyles = new WeakMap<object, Record<string, string>>();
function domRect(r: PaintRect): DOMRect {
return {
...r,
right: r.left + r.width,
bottom: r.top + r.height,
} as DOMRect;
}
interface PaintNode {
tagName: string;
attrs: Record<string, string>;
parentElement: PaintNode | null;
childNodes: Array<{ nodeType: number; textContent: string }>;
children: PaintNode[];
getBoundingClientRect(): DOMRect;
getAttribute(name: string): string | null;
hasAttribute(name: string): boolean;
querySelector(selector: string): PaintNode | null;
}
function pnode(init: {
tag?: string;
attrs?: Record<string, string>;
style?: Record<string, string>;
rect?: PaintRect;
text?: string;
parent?: PaintNode | null;
}): PaintNode {
const rect = init.rect ?? { left: 0, top: 0, width: 100, height: 100 };
const node: PaintNode = {
tagName: (init.tag ?? "div").toUpperCase(),
attrs: { "data-hf-id": `hf-${init.tag ?? "div"}`, ...init.attrs },
parentElement: init.parent ?? null,
childNodes: init.text === undefined ? [] : [{ nodeType: 3, textContent: init.text }],
children: [],
getBoundingClientRect: () => domRect(rect),
getAttribute(name) {
return Object.prototype.hasOwnProperty.call(this.attrs, name) ? this.attrs[name] : null;
},
hasAttribute(name) {
return Object.prototype.hasOwnProperty.call(this.attrs, name);
},
querySelector(selector) {
return this.children.find((c) => c.tagName.toLowerCase() === selector) ?? null;
},
};
if (init.style) paintStyles.set(node, init.style);
init.parent?.children.push(node);
return node;
}
/** An image node the walk can pick up: a FakeHTMLImageElement with a box and a parent. */
function pimg(
id: string,
rect: PaintRect,
opts?: { parent?: PaintNode | null; src?: string; naturalWidth?: number },
): FakeHTMLImageElement {
const img = new FakeHTMLImageElement(id);
img.getBoundingClientRect = () => domRect(rect);
img.parentElement = (opts?.parent ?? null) as unknown as FakeHTMLImageElement | null;
if (opts?.src) {
img.src = opts.src;
img.currentSrc = opts.src;
}
if (opts?.naturalWidth !== undefined) img.naturalWidth = opts.naturalWidth;
return img;
}
function paintWin(): Window & typeof globalThis {
return {
HTMLImageElement: FakeHTMLImageElement,
getComputedStyle(el: object) {
const merged = { ...PAINT_DEFAULT_STYLE, ...(paintStyles.get(el) ?? {}) };
return {
...merged,
getPropertyValue(name: string) {
if (merged[name] !== undefined) return merged[name];
return name.endsWith("-width") ? "0px" : "none";
},
} as unknown as CSSStyleDeclaration;
},
} as unknown as Window & typeof globalThis;
}
function paintDoc(nodes: object[], readyState = "complete"): Document {
const matching = (selector: string) => {
if (selector === "*") return nodes;
const attr = selector.slice(1, -1);
return nodes.filter((n) => (n as PaintNode).hasAttribute(attr));
};
return {
readyState,
querySelectorAll: matching,
querySelector: (selector: string) => matching(selector)[0] ?? null,
} as unknown as Document;
}
/** OffscreenCanvas stub that counts pixel reads, for the lazy-sampling guard. */
function stubCountingCanvas(): { restore: () => void; reads: () => number } {
const orig = globalThis.OffscreenCanvas as typeof OffscreenCanvas | undefined;
let reads = 0;
globalThis.OffscreenCanvas = class {
constructor(
public width: number,
public height: number,
) {}
getContext(_type: string) {
return {
drawImage() {},
getImageData() {
reads++;
return { data: new Uint8ClampedArray([255, 0, 0, 255]), width: 1, height: 1 };
},
};
}
} as unknown as typeof OffscreenCanvas;
return {
restore: () => {
if (orig === undefined) {
delete (globalThis as Record<string, unknown>).OffscreenCanvas;
} else {
globalThis.OffscreenCanvas = orig;
}
},
reads: () => reads,
};
}
const el = (n: PaintNode) => n as unknown as Element;
describe("elementPaintsInk", () => {
const win = paintWin();
it("treats a bare layout wrapper as NOT painting", () => {
// The common case, and the reason this exists: a composition is mostly full-bleed
// wrappers with no visual presence, and every one covers what sits beneath.
expect(elementPaintsInk(el(pnode({})), win)).toBe(false);
});
it("counts a background colour, but not a transparent one", () => {
expect(elementPaintsInk(el(pnode({ style: { backgroundColor: "#ff0000" } })), win)).toBe(true);
expect(elementPaintsInk(el(pnode({ style: { backgroundColor: "rgba(0,0,0,0)" } })), win)).toBe(
false,
);
expect(elementPaintsInk(el(pnode({ style: { backgroundColor: "transparent" } })), win)).toBe(
false,
);
});
it("reads the alpha, so a NON-BLACK zero-alpha colour is still no ink", () => {
// Only the `transparent` keyword computes to rgba(0,0,0,0); a faded-out white stays
// rgba(255, 255, 255, 0), which a set of known spellings counts as painted.
for (const color of [
"rgba(255, 255, 255, 0)",
"rgba(12, 34, 56, 0.0)",
"rgb(255 255 255 / 0)",
"hsla(0, 0%, 0%, 0)",
"hsl(120 50% 50% / 0)",
]) {
expect(elementPaintsInk(el(pnode({ style: { backgroundColor: color } })), win), color).toBe(
false,
);
}
// A non-zero alpha still paints, however faint.
expect(
elementPaintsInk(el(pnode({ style: { backgroundColor: "rgba(255, 255, 255, 0.01)" } })), win),
).toBe(true);
// rgb() with no alpha component is opaque.
expect(elementPaintsInk(el(pnode({ style: { backgroundColor: "rgb(1, 2, 3)" } })), win)).toBe(
true,
);
});
it("counts a background image", () => {
expect(elementPaintsInk(el(pnode({ style: { backgroundImage: "url(a.png)" } })), win)).toBe(
true,
);
});
it("counts a visible border but not a zero-width or `none` one", () => {
const bordered = pnode({
style: { "border-top-style": "solid", "border-top-width": "2px" },
});
expect(elementPaintsInk(el(bordered), win)).toBe(true);
const zeroWidth = pnode({
style: { "border-top-style": "solid", "border-top-width": "0px" },
});
expect(elementPaintsInk(el(zeroWidth), win)).toBe(false);
const styleNone = pnode({
style: { "border-top-style": "none", "border-top-width": "2px" },
});
expect(elementPaintsInk(el(styleNone), win)).toBe(false);
});
it("counts intrinsic media regardless of styling", () => {
for (const tag of ["video", "canvas", "svg"]) {
expect(elementPaintsInk(el(pnode({ tag })), win), tag).toBe(true);
}
});
it("counts an element's OWN text, not text belonging to a descendant", () => {
expect(elementPaintsInk(el(pnode({ tag: "span", text: "Clean" })), win)).toBe(true);
// Without the own-text rule every ancestor of a caption would count as painting,
// and the whole frame would read as covered.
const wrapper = pnode({});
pnode({ tag: "span", text: "Clean", parent: wrapper });
expect(elementPaintsInk(el(wrapper), win)).toBe(false);
expect(elementPaintsInk(el(pnode({ text: " \n " })), win)).toBe(false);
});
});
describe("elementPaintsInk: <img> routes through the alpha sampler", () => {
beforeEach(() => {
_imgCanvasCache.clear();
});
const rect = { left: 0, top: 0, width: 100, height: 100 };
/** Ink at the centre of a 100×100 image, under a controlled canvas behaviour. */
function inkAtCentre(
behavior: CanvasAlphaBehavior,
build: () => Element = () => pimg("hf-img", rect) as unknown as Element,
): boolean {
const restore = stubOffscreenCanvas(behavior);
try {
return elementPaintsInk(build(), paintWin(), { x: 50, y: 50 });
} finally {
restore();
}
}
it("an opaque pixel paints", () => {
expect(inkAtCentre("opaque")).toBe(true);
});
it("a transparent pixel does NOT paint — the whole point of the alpha path", () => {
expect(inkAtCentre("transparent")).toBe(false);
});
it("a tainted canvas fails safe to painted", () => {
expect(inkAtCentre("tainted")).toBe(true);
});
it("an unloaded image fails safe to painted", () => {
expect(
inkAtCentre(
"transparent",
() => pimg("hf-img", rect, { naturalWidth: 0 }) as unknown as Element,
),
).toBe(true);
});
it("falls back to the tag rule when no point is supplied", () => {
// Point-free callers are asking "could this paint at all", which for an image is yes.
expect(elementPaintsInk(pimg("hf-img", rect) as unknown as Element, paintWin())).toBe(true);
});
it("<picture> defers to the <img> it wraps rather than painting unconditionally", () => {
const withInnerImg = () => {
const picture = pnode({ tag: "picture" });
picture.children.push(pimg("hf-inner", rect) as unknown as PaintNode);
return el(picture);
};
expect(inkAtCentre("transparent", withInnerImg)).toBe(false);
});
it("a clear pixel still paints when the image itself has background or border ink", () => {
// object-fit letterbox over a white plate: the bitmap misses, the chip is still visible.
const restore = stubOffscreenCanvas("transparent");
try {
const img = pimg("hf-chip", rect);
paintStyles.set(img, { backgroundColor: "#fff" });
expect(elementPaintsInk(img as unknown as Element, paintWin(), { x: 50, y: 50 })).toBe(true);
} finally {
restore();
}
});
it("<picture> with no inner <img> still paints", () => {
expect(elementPaintsInk(el(pnode({ tag: "picture" })), paintWin(), { x: 1, y: 1 })).toBe(true);
});
});
describe("compositionPaintsAt", () => {
beforeEach(() => {
_imgCanvasCache.clear();
});
const FRAME: PaintRect = { left: 0, top: 0, width: 1000, height: 1000 };
const root = () => pnode({ attrs: { "data-composition-id": "main" }, rect: FRAME });
it("an unpainted full-bleed wrapper does not mask a painted child", () => {
const nodes = [
root(),
pnode({ rect: FRAME }),
pnode({
attrs: { "data-hf-id": "hf-sun" },
style: { backgroundColor: "#ff0" },
rect: { left: 100, top: 100, width: 180, height: 180 },
}),
];
const paints = compositionPaintsAt(paintDoc(nodes), paintWin(), 150, 150, {
fullBleedFraction: 0.9,
});
expect(paints).toBe(true);
});
it("reports no ink where only an unpainted wrapper sits", () => {
const nodes = [root(), pnode({ rect: FRAME })];
expect(compositionPaintsAt(paintDoc(nodes), paintWin(), 500, 500)).toBe(false);
});
it("reports no ink outside every box", () => {
const nodes = [
root(),
pnode({
style: { backgroundColor: "#f00" },
rect: { left: 0, top: 0, width: 10, height: 10 },
}),
];
expect(compositionPaintsAt(paintDoc(nodes), paintWin(), 500, 500)).toBe(false);
});
it("fullBleedFraction rejects a lone full-bleed painter; the default accepts it", () => {
const nodes = [root(), pnode({ style: { backgroundColor: "rgba(0,0,0,0.3)" }, rect: FRAME })];
// Host policy: an editor reads "you clicked a layer covering the whole frame" as
// "you clicked the background".
expect(
compositionPaintsAt(paintDoc(nodes), paintWin(), 500, 500, { fullBleedFraction: 0.9 }),
).toBe(false);
// The literal ink question: a full-frame scrim does put ink there.
expect(compositionPaintsAt(paintDoc(nodes), paintWin(), 500, 500)).toBe(true);
});
it("measures full-bleed against the innermost root CONTAINING the point", () => {
// A 300×300 painter really is full-bleed inside the 300×300 sub-composition it lives
// in, even though it covers 9% of the outer frame.
const nested: PaintRect = { left: 0, top: 0, width: 300, height: 300 };
const nodes = [
root(),
pnode({ attrs: { "data-composition-id": "inner" }, rect: nested }),
pnode({ style: { backgroundColor: "#f00" }, rect: nested }),
];
expect(
compositionPaintsAt(paintDoc(nodes), paintWin(), 150, 150, { fullBleedFraction: 0.9 }),
).toBe(false);
});
it("never vetoes a PIXEL-VERIFIED hit, however large the box", () => {
// The flagship shape: a full-frame transparent PNG overlay. Its box IS the frame, so an
// area-based veto called every opaque pixel "background" and the visible artwork became
// unclickable. Box area is not ink area once the pixel has actually been read.
const restore = stubOffscreenCanvas("opaque");
try {
const frame: PaintRect = { left: 0, top: 0, width: 1000, height: 1000 };
const nodes = [root(), pimg("hf-overlay", frame)];
expect(
compositionPaintsAt(paintDoc(nodes), paintWin(), 500, 500, { fullBleedFraction: 0.9 }),
).toBe(true);
} finally {
restore();
}
});
it("still vetoes a full-bleed image whose pixels could NOT be read", () => {
// A tainted cross-origin image is a fail-safe "opaque", not a measurement. Exempting it
// would make every full-frame CDN-backed overlay permanently absorb clicks.
const restore = stubOffscreenCanvas("tainted");
try {
const frame: PaintRect = { left: 0, top: 0, width: 1000, height: 1000 };
const nodes = [root(), pimg("hf-overlay", frame)];
expect(
compositionPaintsAt(paintDoc(nodes), paintWin(), 500, 500, { fullBleedFraction: 0.9 }),
).toBe(false);
} finally {
restore();
}
});
it("counts ink painted by the composition root itself", () => {
// A root carrying a background is painting, and at fraction 0 the literal ink question
// has to say so. A non-zero fraction still discounts it: a root's box IS the frame.
const painted = () =>
pnode({
attrs: { "data-composition-id": "main", "data-hf-id": "hf-root" },
style: { backgroundColor: "#111" },
rect: { left: 0, top: 0, width: 1000, height: 1000 },
});
expect(compositionPaintsAt(paintDoc([painted()]), paintWin(), 500, 500)).toBe(true);
expect(
compositionPaintsAt(paintDoc([painted()]), paintWin(), 500, 500, { fullBleedFraction: 0.9 }),
).toBe(false);
});
it("ignores a sub-composition the point is NOT inside when sizing the frame", () => {
// Regression: taking the smallest root in the DOCUMENT let a badge in one corner set the
// reference frame for the whole canvas, so mid-size artwork out in the 1000×1000 outer
// frame measured against 300×300, read as full-bleed, and went click-through under
// something the user can plainly see — the unsafe direction.
const badge: PaintRect = { left: 0, top: 0, width: 300, height: 300 };
const nodes = [
root(),
pnode({ attrs: { "data-composition-id": "badge" }, rect: badge }),
pnode({
style: { backgroundColor: "#f00" },
rect: { left: 500, top: 500, width: 300, height: 300 },
}),
];
expect(
compositionPaintsAt(paintDoc(nodes), paintWin(), 600, 600, { fullBleedFraction: 0.9 }),
).toBe(true);
});
it("disables the full-bleed rule when no root contains the point", () => {
const nodes = [
pnode({
attrs: { "data-composition-id": "elsewhere" },
rect: { left: 0, top: 0, width: 10, height: 10 },
}),
pnode({
style: { backgroundColor: "#f00" },
rect: { left: 400, top: 400, width: 200, height: 200 },
}),
];
expect(
compositionPaintsAt(paintDoc(nodes), paintWin(), 500, 500, { fullBleedFraction: 0.9 }),
).toBe(true);
});
it("skips display:none, visibility:hidden and zero-area boxes", () => {
const painted = { backgroundColor: "#f00" };
const box = { left: 0, top: 0, width: 100, height: 100 };
for (const style of [
{ ...painted, display: "none" },
{ ...painted, visibility: "hidden" },
]) {
const nodes = [root(), pnode({ style, rect: box })];
expect(compositionPaintsAt(paintDoc(nodes), paintWin(), 50, 50)).toBe(false);
}
const collapsed = [
root(),
pnode({ style: painted, rect: { left: 0, top: 0, width: 0, height: 0 } }),
];
expect(compositionPaintsAt(paintDoc(collapsed), paintWin(), 0, 0)).toBe(false);
});
it("skips an element hidden by an ANCESTOR's opacity:0", () => {
// getComputedStyle does not multiply the cascade, so a fully opaque child inside a
// fade-in wrapper that has not started yet reads as painting unless the check walks up.
const wrapper = pnode({
style: { opacity: "0" },
rect: { left: 0, top: 0, width: 200, height: 200 },
});
const child = pnode({
attrs: { "data-hf-id": "hf-child" },
style: { backgroundColor: "#f00" },
rect: { left: 0, top: 0, width: 100, height: 100 },
parent: wrapper,
});
expect(compositionPaintsAt(paintDoc([root(), wrapper, child]), paintWin(), 50, 50)).toBe(false);
});
it("addressableOnly:false picks up a node the stamping pass never saw", () => {
// Runtime-generated nodes (split-text word spans, clones) carry no data-hf-id.
const generated = pnode({
tag: "span",
attrs: {},
text: "word",
rect: { left: 0, top: 0, width: 50, height: 20 },
});
delete generated.attrs["data-hf-id"];
const nodes = [root(), generated];
expect(compositionPaintsAt(paintDoc(nodes), paintWin(), 10, 10)).toBe(false);
expect(
compositionPaintsAt(paintDoc(nodes), paintWin(), 10, 10, { addressableOnly: false }),
).toBe(true);
});
it("samples alpha lazily — the smallest painting box wins before the rest are read", () => {
// Guards the per-frame cost: ink is evaluated down the ordered candidates, so a hit
// on the most specific element must not have already paid for the ones behind it.
const canvas = stubCountingCanvas();
try {
const nodes = [
root(),
pimg("hf-big", { left: 0, top: 0, width: 400, height: 400 }, { src: "http://x/big.png" }),
pimg(
"hf-small",
{ left: 0, top: 0, width: 100, height: 100 },
{ src: "http://x/small.png" },
),
];
expect(compositionPaintsAt(paintDoc(nodes), paintWin(), 50, 50)).toBe(true);
expect(canvas.reads()).toBe(1);
} finally {
canvas.restore();
}
});
});
describe("IframePreviewAdapter.isProvablyEmptyAt", () => {
beforeEach(() => {
_imgCanvasCache.clear();
});
const iframeWith = (doc: unknown, win: unknown) =>
({ contentDocument: doc, contentWindow: win }) as unknown as HTMLIFrameElement;
it("is never provably empty when the document is not reachable", () => {
// Unknowable is not empty: the composition stays clickable rather than vanishing.
expect(createIframePreviewAdapter(iframeWith(null, paintWin())).isProvablyEmptyAt(1, 1)).toBe(
false,
);
expect(createIframePreviewAdapter(iframeWith(paintDoc([]), null)).isProvablyEmptyAt(1, 1)).toBe(
false,
);
});
it("is never provably empty when contentDocument access throws (cross-origin)", () => {
const hostile = {} as HTMLIFrameElement;
Object.defineProperty(hostile, "contentDocument", {
get() {
throw new DOMException("Blocked a frame", "SecurityError");
},
});
expect(createIframePreviewAdapter(hostile).isProvablyEmptyAt(1, 1)).toBe(false);
});
it("is never provably empty while the document is still loading", () => {
// A same-origin iframe mid-navigation is READABLE and empty, so the !doc guard never
// fires — walking it would answer a confident "no ink" under an arriving composition.
const stamped = [pnode({ attrs: { "data-hf-id": "hf-a" } })];
expect(
createIframePreviewAdapter(
iframeWith(paintDoc(stamped, "loading"), paintWin()),
).isProvablyEmptyAt(1, 1),
).toBe(false);
// Loaded but carrying nothing of the composition — equally unknowable.
expect(
createIframePreviewAdapter(iframeWith(paintDoc([]), paintWin())).isProvablyEmptyAt(1, 1),
).toBe(false);
});
it("inverts the walk: empty where nothing paints, not empty over ink", () => {
const nodes = [
pnode({
attrs: { "data-composition-id": "main" },
rect: { left: 0, top: 0, width: 500, height: 500 },
}),
pnode({
style: { backgroundColor: "#f00" },
rect: { left: 0, top: 0, width: 100, height: 100 },
}),
];
const adapter = createIframePreviewAdapter(iframeWith(paintDoc(nodes), paintWin()));
expect(adapter.isProvablyEmptyAt(50, 50)).toBe(false); // over the painted box
expect(adapter.isProvablyEmptyAt(400, 400)).toBe(true); // empty region
});
});