Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
fix(layout): flag text a clipping card cuts off (#4577)
Xuanru Li09ab947e1ad0
diff --git a/packages/cli/src/commands/layout-audit.browser.js b/packages/cli/src/commands/layout-audit.browser.jsindex bb5d917453..be2a90de05 100644--- a/packages/cli/src/commands/layout-audit.browser.js+++ b/packages/cli/src/commands/layout-audit.browser.js@@ -471,19 +471,55 @@};}- // An ancestor (up to and including `stopAt`) that clips its overflow makes any- // text spilling past it invisible — that clipping IS the layout mechanism- // (odometer/ticker reels, masked windows), not a defect to report.- function clippedByAncestor(element, stopAt) {- for (let current = element; current; current = current.parentElement) {- if (current !== element && clipsOverflow(getComputedStyle(current))) return true;- if (current === stopAt) break;- }- return false;+ function horizontalTextMetrics(element, style) {+ if (style.writingMode && style.writingMode !== "horizontal-tb") return null;+ const context = document.createElement("canvas").getContext("2d");+ if (!context) return null;+ context.font = `${style.fontStyle} ${style.fontWeight} ${style.fontSize} ${style.fontFamily}`;+ let text = textContentFor(element, true);+ if (style.textTransform === "uppercase") text = text.toUpperCase();+ if (style.textTransform === "lowercase") text = text.toLowerCase();+ const metrics = context.measureText(text);+ return metrics.fontBoundingBoxAscent + metrics.fontBoundingBoxDescent > 0 ? metrics : null;+ }++ function intersectsTextWindow(rect, clip, tolerance) {+ return (+ Math.min(rect.right, clip.right) - Math.max(rect.left, clip.left) > tolerance &&+ Math.min(rect.bottom, clip.bottom) - Math.max(rect.top, clip.top) > tolerance+ );+ }++ function visibleTextLineRects(element, rects, style, clip, tolerance) {+ const metrics = horizontalTextMetrics(element, style);+ const fontHeight = metrics ? metrics.fontBoundingBoxAscent + metrics.fontBoundingBoxDescent : 0;+ const lineHeight = parsePx(style.lineHeight) || fontHeight;+ return rects.flatMap((rect) => {+ if (!metrics) return intersectsTextWindow(rect, clip, tolerance) ? [rect] : [];+ const scale = rect.height / fontHeight;+ const inkTop =+ rect.top + (metrics.fontBoundingBoxAscent - metrics.actualBoundingBoxAscent) * scale;+ const inkBottom =+ rect.bottom - (metrics.fontBoundingBoxDescent - metrics.actualBoundingBoxDescent) * scale;+ const ink = { ...rect, top: inkTop, bottom: inkBottom };+ if (!intersectsTextWindow(ink, clip, tolerance)) return [];+ // Negative leading belongs outside the used line box. Font metrics scale+ // with the Range rect, so zoomed cards retain the same clipping decision.+ const inset = Math.max(0, (rect.height - lineHeight * scale) / 2);+ return [+ toRect({+ ...rect,+ top: rect.top + inset,+ bottom: rect.bottom - inset,+ height: rect.height - 2 * inset,+ }),+ ];+ });}function textOverflowIssues(element, root, rootRect, time, tolerance, clippedIssue) {- const textRect = textRectFor(element, true);+ const lineRects = textClientRects(element, true).map(toRect);+ const textRect = unionRects(lineRects);if (!textRect) return [];const text = textContentFor(element, true);const selector = selectorFor(element);@@ -491,32 +527,26 @@const container = nearestConstraint(element, root, rootRect);const containerRect = container === root ? rootRect : toRect(container.getBoundingClientRect());- // Glyph ink (ascenders / descenders / accents / heavy display faces) routinely exceeds a- // snug line-height box by a few px, proportional to font size. When the constraining box- // does NOT clip, that vertical spill is normal typography — it shows in the padding, nothing- // is hidden — not a layout defect (it false-flagged caption words). Allow a font-metric- // vertical tolerance there; keep it tight when the box actually clips (a real cut-off) and- // always tight horizontally (too-wide text is a real wrap/legibility issue).const elementStyle = getComputedStyle(element);const containerClips = clipsOverflow(container === root ? getComputedStyle(root) : getComputedStyle(container),);+ const visibleTextRect = containerClips+ ? unionRects(visibleTextLineRects(element, lineRects, elementStyle, containerRect, tolerance))+ : textRect;const verticalTolerance = containerClips? tolerance: Math.max(tolerance, parsePx(elementStyle.fontSize) * 0.2);- const containerOverflow = overflowFor(textRect, containerRect, tolerance, verticalTolerance);+ const containerOverflow = visibleTextRect+ ? overflowFor(visibleTextRect, containerRect, tolerance, verticalTolerance)+ : null;const billedAsClippedText =container === element &&clippedIssue != null &&containerOverflow != null &&containerOverflow.left == null &&containerOverflow.top == null;- if (- containerOverflow &&- !billedAsClippedText &&- !hasTextClipOptOut(element) &&- !clippedByAncestor(element, container)- ) {+ if (containerOverflow && !billedAsClippedText && !hasTextClipOptOut(element)) {const style = elementStyle;issues.push({code: "text_box_overflow",@@ -526,11 +556,11 @@containerSelector: selectorFor(container),text,message: "Text extends outside its nearest visual/container box.",- rect: textRect,+ rect: visibleTextRect,containerRect,overflow: containerOverflow,fixHint: textOverflowFixHint(- textRect,+ visibleTextRect,containerRect,containerOverflow,parsePx(style.fontSize),diff --git a/packages/cli/src/commands/layout-audit.browser.test.ts b/packages/cli/src/commands/layout-audit.browser.test.tsindex 2a0a2fd86e..d6427853b7 100644--- a/packages/cli/src/commands/layout-audit.browser.test.ts+++ b/packages/cli/src/commands/layout-audit.browser.test.ts@@ -622,6 +622,162 @@ describe("layout-audit.browser", () => {expect(runAudit().some((issue) => issue.code === "text_box_overflow")).toBe(true);});+ it("flags text a clipping parent cuts off", () => {+ document.body.innerHTML = `+ <div id="root" data-composition-id="main" data-width="640" data-height="360">+ <div id="card">+ <div id="headline">CREATIVE CHOICES</div>+ </div>+ </div>+ `;+ installGeometry(+ {+ root: rect({ left: 0, top: 0, width: 640, height: 360 }),+ card: rect({ left: 40, top: 60, width: 200, height: 80 }),+ headline: rect({ left: 50, top: 20, width: 160, height: 200 }),+ text: rect({ left: 50, top: 20, width: 160, height: 200 }),+ },+ {+ card: {+ overflow: "hidden",+ overflowX: "hidden",+ overflowY: "hidden",+ backgroundColor: "rgb(40, 20, 60)",+ borderTopLeftRadius: "34px",+ borderTopRightRadius: "34px",+ borderBottomRightRadius: "34px",+ borderBottomLeftRadius: "34px",+ },+ },+ );+ installAuditScript();++ const found = runAudit().filter((issue) => issue.code === "text_box_overflow");+ expect(found).toHaveLength(1);+ expect(found[0]?.selector).toBe("#headline");+ expect(found[0]?.containerSelector).toBe("#card");+ expect(found[0]?.overflow?.top).toBeGreaterThan(2);+ expect(found[0]?.overflow?.bottom).toBeGreaterThan(2);+ expect(runAudit().some((issue) => issue.code === "clipped_text")).toBe(false);++ document.querySelector("#card")?.setAttribute("data-layout-allow-overflow", "");+ expect(runAudit().some((issue) => issue.code === "text_box_overflow")).toBe(false);+ });++ it("flags visible text entirely outside a non-clipping card", () => {+ document.body.innerHTML = `+ <div id="root" data-composition-id="main" data-width="640" data-height="360">+ <div id="card"><div id="headline">Visible overflow</div></div>+ </div>+ `;+ installGeometry(+ {+ root: rect({ left: 0, top: 0, width: 640, height: 360 }),+ card: rect({ left: 40, top: 60, width: 200, height: 80 }),+ headline: rect({ left: 50, top: 170, width: 160, height: 30 }),+ text: rect({ left: 50, top: 170, width: 160, height: 30 }),+ },+ {+ card: {+ overflow: "visible",+ backgroundColor: "rgb(40, 20, 60)",+ borderTopLeftRadius: "34px",+ },+ },+ );+ installAuditScript();++ const found = runAudit().filter((issue) => issue.code === "text_box_overflow");+ expect(found).toHaveLength(1);+ expect(found[0]?.selector).toBe("#headline");+ expect(found[0]?.containerSelector).toBe("#card");+ expect(found[0]?.overflow?.bottom).toBe(60);+ });++ it("does not flag a line parked entirely outside a clipping window", () => {+ document.body.innerHTML = `+ <div id="root" data-composition-id="main" data-width="640" data-height="360">+ <div id="card">+ <div id="headline">9</div>+ </div>+ </div>+ `;+ installGeometry(+ {+ root: rect({ left: 0, top: 0, width: 640, height: 360 }),+ card: rect({ left: 40, top: 60, width: 40, height: 20 }),+ headline: rect({ left: 40, top: 0, width: 40, height: 20 }),+ text: rect({ left: 40, top: 0, width: 40, height: 20 }),+ },+ {+ card: {+ overflow: "hidden",+ overflowX: "hidden",+ overflowY: "hidden",+ },+ },+ );+ installAuditScript();++ expect(runAudit().some((issue) => issue.code === "text_box_overflow")).toBe(false);+ });++ it.each([+ { name: "resting tight line", top: 87, height: 145, clipHeight: 120, scale: 1, error: false },+ { name: "parked touching line", top: 195, height: 113, clipHeight: 96, scale: 1, error: false },+ { name: "real cut", top: 87, height: 145, clipHeight: 60, scale: 1, error: true },+ { name: "scaled real cut", top: 93.5, height: 72.5, clipHeight: 30, scale: 0.5, error: true },+ ])("uses scaled line boxes for $name", ({ top, height, clipHeight, scale, error }) => {+ document.body.innerHTML = `+ <div id="root" data-composition-id="main" data-width="640" data-height="360">+ <div id="card"><div id="headline">HELLO</div></div>+ </div>`;+ const contextSpy = vi.spyOn(HTMLCanvasElement.prototype, "getContext") as unknown as {+ mockReturnValue(value: CanvasRenderingContext2D): void;+ };+ contextSpy.mockReturnValue({+ font: "",+ measureText: () => ({+ fontBoundingBoxAscent: 115,+ fontBoundingBoxDescent: 30,+ actualBoundingBoxAscent: 85,+ actualBoundingBoxDescent: 0,+ }),+ } as unknown as CanvasRenderingContext2D);+ installGeometry(+ {+ root: rect({ left: 0, top: 0, width: 640, height: 360 }),+ card: rect({ left: 40, top: 100, width: 400 * scale, height: clipHeight }),+ headline: rect({ left: 40, top, width: 300 * scale, height }),+ text: rect({ left: 40, top, width: 300 * scale, height }),+ },+ {+ card: { overflow: "hidden", overflowX: "hidden", overflowY: "hidden" },+ headline: { lineHeight: "120px" },+ },+ );+ installAuditScript();+ expect(runAudit().some((issue) => issue.code === "text_box_overflow")).toBe(error);+ });++ it("ignores subpixel contact with a clipping window", () => {+ document.body.innerHTML = `+ <div id="root" data-composition-id="main" data-width="640" data-height="360">+ <div id="card"><div id="headline">NEXT</div></div>+ </div>`;+ installGeometry(+ {+ root: rect({ left: 0, top: 0, width: 640, height: 360 }),+ card: rect({ left: 40, top: 100, width: 400, height: 96 }),+ headline: rect({ left: 40, top: 195.7, width: 300, height: 96 }),+ text: rect({ left: 40, top: 195.7, width: 300, height: 96 }),+ },+ { card: { overflow: "hidden", overflowX: "hidden", overflowY: "hidden" } },+ );+ installAuditScript();+ expect(runAudit().some((issue) => issue.code === "text_box_overflow")).toBe(false);+ });+it("keeps auditing visible descendants beyond the second element", () => {document.body.innerHTML = `<div id="root" data-composition-id="main" data-width="640" data-height="360">diff --git a/packages/cli/src/commands/layout-audit.chromium.test.ts b/packages/cli/src/commands/layout-audit.chromium.test.tsnew file mode 100644index 0000000000..4162912ba9--- /dev/null+++ b/packages/cli/src/commands/layout-audit.chromium.test.ts@@ -0,0 +1,82 @@+import { afterAll, beforeAll, describe, expect, it } from "vitest";+import { readFileSync } from "node:fs";+import puppeteer, { type Browser } from "puppeteer-core";++declare global {+ interface Window {+ __hyperframesLayoutAudit(options: { time: number; tolerance: number }): { code: string }[];+ }+}++const executablePath = process.env.PUPPETEER_EXECUTABLE_PATH;+const script = readFileSync(new URL("./layout-audit.browser.js", import.meta.url), "utf8");++describe.runIf(executablePath)("layout audit in Chromium", () => {+ let browser: Browser;+ beforeAll(async () => {+ browser = await puppeteer.launch({ executablePath, args: ["--no-sandbox"] });+ });+ afterAll(async () => {+ await browser?.close();+ });++ it.each([+ { name: "line-height 1", css: "height:120px", textStyle: "", error: false },+ { name: "line-height .9", css: "height:108px;line-height:.9", textStyle: "", error: false },+ { name: "line-height .98", css: "height:117.6px;line-height:.98", textStyle: "", error: false },+ {+ name: "parked flush below",+ css: "height:120px",+ textStyle: "transform:translateY(120px)",+ error: false,+ },+ {+ name: "parked flush above",+ css: "height:120px",+ textStyle: "transform:translateY(-120px)",+ error: false,+ },+ {+ name: "parked with empty leading inside the window",+ css: "height:120px",+ textStyle: "transform:translateY(114px)",+ error: false,+ },+ { name: "partial cut", css: "height:60px", textStyle: "", error: true },+ {+ name: "scaled partial cut",+ css: "height:60px;transform:scale(.5);transform-origin:top left",+ textStyle: "",+ error: true,+ },+ {+ name: "RTL left cut",+ css: "height:120px;direction:rtl",+ textStyle: "transform:translateX(-100px)",+ error: true,+ },+ {+ name: "vertical cut",+ css: "height:60px;writing-mode:vertical-rl",+ textStyle: "",+ error: true,+ },+ ])("handles $name", async ({ css, textStyle, error }) => {+ const page = await browser.newPage();+ try {+ await page.setContent(`<body style="margin:0">+ <div data-composition-id="main" data-width="1000" data-height="800" style="width:1000px;height:800px">+ <div style="position:absolute;left:100px;top:100px;width:400px;overflow:hidden;font:120px/1 Arial;${css}">+ <div style="${textStyle}">HELLO</div>+ </div>+ </div></body>`);+ await page.addScriptTag({ content: script });+ const issues = await page.evaluate(() =>+ window.__hyperframesLayoutAudit({ time: 1, tolerance: 2 }),+ );+ expect(issues.some((issue) => issue.code === "text_box_overflow")).toBe(error);+ } finally {+ await page.close();+ }+ });+});diff --git a/packages/cli/src/utils/layoutAudit.test.ts b/packages/cli/src/utils/layoutAudit.test.tsindex b92389122e..9596244b92 100644--- a/packages/cli/src/utils/layoutAudit.test.ts+++ b/packages/cli/src/utils/layoutAudit.test.ts@@ -166,15 +166,11 @@ describe("layoutAudit helpers", () => {expect(formatted).toContain("t=1-5s (3 samples)");});- // The clip rule that suppresses the odometer/ticker false positive: text- // spilling past an `overflow:hidden` reel window is the mechanism, not a bug.- it("treats clipping overflow values as masking (suppress) and visible as not (still report)", () => {- // Intended clipping — the queued digit rows of a reel are masked here.+ it("treats hidden, clip, auto, and scroll as clipping", () => {expect(overflowValueClips("hidden")).toBe(true);expect(overflowValueClips("clip")).toBe(true);expect(overflowValueClips("auto")).toBe(true);expect(overflowValueClips("scroll")).toBe(true);- // Genuine overflow — nothing masks the text, so it must STILL be reported.expect(overflowValueClips("visible")).toBe(false);expect(overflowValueClips("clip visible")).toBe(false);expect(overflowValueClips("")).toBe(false);diff --git a/packages/cli/src/utils/layoutAudit.ts b/packages/cli/src/utils/layoutAudit.tsindex 10f4cfef94..56fbc6aee5 100644--- a/packages/cli/src/utils/layoutAudit.ts+++ b/packages/cli/src/utils/layoutAudit.ts@@ -118,12 +118,9 @@ export function computeOverflow(}/**- * Whether a computed `overflow*` value clips its box. Mirrors the rule the- * browser audit (layout-audit.browser.js) uses to decide that text spilling- * past such an ancestor is intentionally masked (odometer/ticker reels) rather- * than a `text_box_overflow` defect. Kept here as the one unit-testable seam of- * that suppression: only `visible` (and the `clip visible` no-op) must NOT clip- * — every clipping value must, or real masked overflow gets reported as a bug.+ * Whether a computed `overflow*` value clips its box. Mirrors+ * `clipsOverflowValue` in layout-audit.browser.js. `visible` and `clip visible`+ * do not clip.*/export function overflowValueClips(value: string | null | undefined): boolean {return !!value && value !== "visible" && value !== "clip visible";