Skip to content

Write HTML. Render video. Built for agents.

fix(cli): recognize ancestor gradient text masks (#5207)

Abdullah M. Naziff802aedb5b32
diff --git a/packages/cli/src/commands/layout-audit.browser.js b/packages/cli/src/commands/layout-audit.browser.js
index e082e557f2..3790c4ac8d 100644
--- a/packages/cli/src/commands/layout-audit.browser.js
+++ b/packages/cli/src/commands/layout-audit.browser.js
@@ -1163,6 +1163,73 @@
};
}
+ function layoutOffset(element) {
+ let left = 0;
+ let top = 0;
+ for (let current = element; current instanceof HTMLElement; current = current.offsetParent) {
+ left += current.offsetLeft;
+ top += current.offsetTop;
+ if (current !== element) {
+ left += current.clientLeft;
+ top += current.clientTop;
+ }
+ }
+ return { left, top };
+ }
+
+ function ancestorBackgroundPaintsText(element, textRect) {
+ // Chromium 150+ includes independently painted descendants in text masks;
+ // older builds drop their glyphs: https://github.com/heygen-com/hyperframes/issues/5117.
+ const chromium = window.navigator.userAgent.match(/(?:HeadlessChrome|Chrome)\/(\d+)/);
+ if (!chromium || Number(chromium[1]) < 150 || !(element instanceof HTMLElement)) return false;
+
+ for (
+ let ancestor = element.parentElement;
+ ancestor instanceof HTMLElement;
+ ancestor = ancestor.parentElement
+ ) {
+ const style = getComputedStyle(ancestor);
+ const clips = splitTopLevelCommas(
+ style.webkitBackgroundClip || style.backgroundClip || "border-box",
+ ).map((clip) => clip.trim());
+ if (!clips.includes("text")) continue;
+ // Chromium builds the mask before descendant transforms, so moving the
+ // child must not move its glyphs out of the mask for this check.
+ const offset = layoutOffset(element);
+ const parentOffset = layoutOffset(ancestor);
+ const elementRect = element.getBoundingClientRect();
+ const scaleX = elementRect.width > 0 ? element.offsetWidth / elementRect.width : 1;
+ const scaleY = elementRect.height > 0 ? element.offsetHeight / elementRect.height : 1;
+ const backgroundRect = rectFromOrigin(0, 0, ancestor.offsetWidth, ancestor.offsetHeight);
+ const overlaps =
+ element.offsetWidth > 0 && element.offsetHeight > 0
+ ? textClientRects(element, true).some((rect) => {
+ const layoutRect = rectFromOrigin(
+ offset.left - parentOffset.left + (rect.left - elementRect.left) * scaleX,
+ offset.top - parentOffset.top + (rect.top - elementRect.top) * scaleY,
+ rect.width * scaleX,
+ rect.height * scaleY,
+ );
+ return intersectionArea(layoutRect, backgroundRect) > 0;
+ })
+ : !overflowFor(textRect, ancestor.getBoundingClientRect(), 2);
+ if (!overlaps) continue;
+
+ const images = splitTopLevelCommas(style.backgroundImage || "none");
+ const imagePaints = images.some(
+ (image, index) =>
+ clips[index % clips.length] === "text" &&
+ /(?:linear|radial|conic)-gradient\(/i.test(image) &&
+ gradientMaxAlpha(image) > 0.05,
+ );
+ const colorPaints =
+ clips[(images.length - 1) % clips.length] === "text" &&
+ colorAlpha(style.backgroundColor || "rgba(0, 0, 0, 0)") > 0.05;
+ if (imagePaints || colorPaints) return true;
+ }
+ return false;
+ }
+
// Text whose glyphs paint with an effectively transparent fill renders
// invisibly even though the element, its box, opacity and color all read as
// present — so geometry/occlusion/contrast audits miss it (contrast reads
@@ -1194,6 +1261,7 @@
// clipped text. If nothing paints, fall through and report it.
if (paintsGlyphs) return null;
}
+ if (ancestorBackgroundPaintsText(element, textRect)) return null;
return {
code: "text_not_painted",
severity: "error",
diff --git a/packages/cli/src/commands/layout-audit.browser.test.ts b/packages/cli/src/commands/layout-audit.browser.test.ts
index 082bf7d13e..cdfc8a7234 100644
--- a/packages/cli/src/commands/layout-audit.browser.test.ts
+++ b/packages/cli/src/commands/layout-audit.browser.test.ts
@@ -945,6 +945,139 @@ describe("layout-audit.browser invisible text", () => {
flagged(invisibleTextScene(style({ webkitTextFillColor: "rgba(0, 0, 0, 0)" }), "")),
).toBe(false);
});
+
+ function ancestorGradientScene(
+ ancestorStyle: Partial<CSSStyleDeclaration> = {},
+ headlineStyle: Partial<CSSStyleDeclaration> = {},
+ chromiumVersion = 152,
+ outsideBackground = false,
+ viewportTop?: number,
+ ): AuditIssue[] {
+ vi.spyOn(window.navigator, "userAgent", "get").mockReturnValue(
+ `Mozilla/5.0 HeadlessChrome/${chromiumVersion}.0.0.0 Safari/537.36`,
+ );
+ document.body.innerHTML = `
+ <div id="root" data-composition-id="main" data-width="640" data-height="360">
+ <div id="gradient"><div id="wrapper"><span id="headline">Headline copy</span></div></div>
+ </div>
+ `;
+ const gradient = document.getElementById("gradient");
+ const headline = document.getElementById("headline");
+ if (!gradient || !headline) throw new Error("Missing gradient text fixture");
+ Object.defineProperties(gradient, {
+ offsetLeft: { configurable: true, value: 40 },
+ offsetTop: { configurable: true, value: 140 },
+ offsetWidth: { configurable: true, value: 400 },
+ offsetHeight: { configurable: true, value: 80 },
+ });
+ Object.defineProperties(headline, {
+ offsetParent: { configurable: true, value: gradient },
+ offsetLeft: { configurable: true, value: 0 },
+ offsetTop: { configurable: true, value: outsideBackground ? 110 : 10 },
+ offsetWidth: { configurable: true, value: 300 },
+ offsetHeight: { configurable: true, value: 56 },
+ });
+ const textRect = rect({
+ left: 40,
+ top: viewportTop ?? (outsideBackground ? 250 : 150),
+ width: 300,
+ height: 56,
+ });
+ installGeometry(
+ {
+ root: rect({ left: 0, top: 0, width: 640, height: 360 }),
+ gradient: rect({ left: 40, top: 140, width: 400, height: 80 }),
+ wrapper: textRect,
+ headline: textRect,
+ text: textRect,
+ },
+ {
+ gradient: {
+ backgroundClip: "text",
+ backgroundImage: "linear-gradient(90deg, rgb(255, 0, 0), rgb(0, 0, 255))",
+ ...ancestorStyle,
+ },
+ headline: { webkitTextFillColor: "rgba(0, 0, 0, 0)", ...headlineStyle },
+ },
+ );
+ installAuditScript();
+ return runAudit();
+ }
+
+ it.each([
+ { name: "plain nested text", css: {} },
+ { name: "transformed text", css: { transform: "matrix(1, 0, 0, 1, 0, 0)" } },
+ { name: "positioned text", css: { position: "relative" } },
+ { name: "faded text", css: { opacity: "0.9" } },
+ { name: "filtered text", css: { filter: "blur(0px)" } },
+ { name: "text with its own empty mask", css: { backgroundClip: "text" } },
+ ])("accepts $name painted by an ancestor gradient", ({ css }) => {
+ expect(flagged(ancestorGradientScene({}, css))).toBe(false);
+ });
+
+ it("accepts text painted by an ancestor's solid clipped background", () => {
+ expect(
+ flagged(
+ ancestorGradientScene({ backgroundImage: "none", backgroundColor: "rgb(255, 0, 0)" }),
+ ),
+ ).toBe(false);
+ });
+
+ it("matches a text clip to the background layer that paints it", () => {
+ expect(
+ flagged(
+ ancestorGradientScene({
+ backgroundClip: "border-box, text",
+ backgroundImage: "none, linear-gradient(rgb(255, 0, 0), rgb(0, 0, 255))",
+ }),
+ ),
+ ).toBe(false);
+ });
+
+ it.each([
+ { name: "absent background", css: { backgroundImage: "none" } },
+ {
+ name: "transparent gradient",
+ css: { backgroundImage: "linear-gradient(transparent, rgba(0, 0, 0, 0))" },
+ },
+ { name: "unclipped background", css: { backgroundClip: "border-box" } },
+ { name: "image with unknown transparency", css: { backgroundImage: 'url("missing.png")' } },
+ {
+ name: "gradient on a different background layer",
+ css: {
+ backgroundClip: "border-box, text",
+ backgroundImage: "linear-gradient(rgb(255, 0, 0), rgb(0, 0, 255)), none",
+ },
+ },
+ {
+ name: "unclipped solid background",
+ css: {
+ backgroundClip: "text, border-box",
+ backgroundImage: "none, none",
+ backgroundColor: "rgb(255, 0, 0)",
+ },
+ },
+ ])("keeps reporting invisible text beneath an $name", ({ css }) => {
+ expect(flagged(ancestorGradientScene(css))).toBe(true);
+ });
+
+ it("keeps reporting text outside the ancestor's background box", () => {
+ expect(flagged(ancestorGradientScene({}, {}, 152, true))).toBe(true);
+ });
+
+ it("keeps reporting independently painted descendants on Chrome 148", () => {
+ expect(flagged(ancestorGradientScene({}, { transform: "matrix(1, 0, 0, 1, 0, 0)" }, 148))).toBe(
+ true,
+ );
+ });
+
+ it("uses the untransformed layout position for a translated child", () => {
+ expect(
+ flagged(
+ ancestorGradientScene({}, { transform: "matrix(1, 0, 0, 1, 0, 150)" }, 152, false, 300),
+ ),
+ ).toBe(false);
+ });
});
describe("layout-audit.browser coordinate-frame findings", () => {
diff --git a/packages/cli/src/commands/layout-audit.chromium.test.ts b/packages/cli/src/commands/layout-audit.chromium.test.ts
index caa04affb9..3964f54f34 100644
--- a/packages/cli/src/commands/layout-audit.chromium.test.ts
+++ b/packages/cli/src/commands/layout-audit.chromium.test.ts
@@ -41,6 +41,110 @@ describe.runIf(executablePath)("layout audit in Chromium", () => {
}
}
+ function gradientHeading(content: string, backgroundStyle = ""): string {
+ return `<div data-composition-id="main" data-width="640" data-height="360" style="position:relative;width:640px;height:360px;background:#0a0a0a">
+ <h1 style="position:absolute;left:40px;top:100px;width:560px;margin:0;font:700 64px/1.2 Arial;-webkit-text-fill-color:transparent;background-image:linear-gradient(90deg,#f4f4f4,#f5e6c8);background-clip:text;${backgroundStyle}">${content}</h1>
+ </div>`;
+ }
+
+ async function gradientFrame(body: string) {
+ const page = await browser.newPage();
+ try {
+ await page.setViewport({ width: 640, height: 360, deviceScaleFactor: 1 });
+ await page.setContent(`<body style="margin:0">${body}</body>`);
+ await page.addScriptTag({ content: script });
+ const codes = await page.evaluate(() =>
+ window.__hyperframesLayoutAudit({ time: 1, tolerance: 2 }).map((issue) => issue.code),
+ );
+ return { codes, image: await page.screenshot() };
+ } finally {
+ await page.close();
+ }
+ }
+
+ it.each([
+ { name: "inline child", content: "<span>Gradient text</span>", layered: false },
+ { name: "nested child", content: "<div><span>Gradient text</span></div>", layered: false },
+ {
+ name: "transformed child",
+ content: '<div style="transform:translateY(0)">Gradient text</div>',
+ layered: true,
+ },
+ {
+ name: "translated child",
+ content: '<div style="transform:translateY(150px)">Gradient text</div>',
+ layered: true,
+ },
+ {
+ name: "positioned child",
+ content: '<div style="position:relative">Gradient text</div>',
+ layered: true,
+ },
+ {
+ name: "filtered child",
+ content: '<div style="filter:blur(0px)">Gradient text</div>',
+ layered: true,
+ },
+ { name: "faded child", content: '<div style="opacity:.9">Gradient text</div>', layered: true },
+ ])("recognizes ancestor gradient paint for a $name", async ({ content, layered }) => {
+ const direct = await gradientFrame(gradientHeading("Gradient text"));
+ const descendant = await gradientFrame(gradientHeading(content));
+ const version = await browser.version();
+ const chromiumVersion = Number(version.split("/")[1]?.split(".")[0]);
+ if (chromiumVersion >= 150) {
+ expect(descendant.image).toEqual(direct.image);
+ expect(descendant.codes).not.toContain("text_not_painted");
+ } else {
+ if (layered) expect(descendant.image).not.toEqual(direct.image);
+ else expect(descendant.image).toEqual(direct.image);
+ expect(descendant.codes).toContain("text_not_painted");
+ }
+ });
+
+ it.each([
+ { name: "absent gradient", backgroundStyle: "background-image:none" },
+ {
+ name: "transparent gradient",
+ backgroundStyle: "background-image:linear-gradient(transparent,transparent)",
+ },
+ { name: "unclipped background", backgroundStyle: "background-clip:border-box" },
+ {
+ name: "misaligned background layers",
+ backgroundStyle:
+ "background-image:linear-gradient(red,blue),none;background-clip:border-box,text",
+ },
+ ])("reports invisible glyphs beneath an $name", async ({ backgroundStyle }) => {
+ expect(
+ await auditCodes(gradientHeading("<span>Gradient text</span>", backgroundStyle)),
+ ).toContain("text_not_painted");
+ });
+
+ it("reports transparent SVG text beneath an HTML text mask", async () => {
+ const codes = await auditCodes(
+ gradientHeading(
+ '<svg width="500" height="80"><text x="0" y="60" fill="transparent">Gradient text</text></svg>',
+ ),
+ );
+ expect(codes).toContain("text_not_painted");
+ });
+
+ it("reports text positioned outside the ancestor background", async () => {
+ const codes = await auditCodes(
+ gradientHeading('<span style="position:relative;top:150px">Gradient text</span>'),
+ );
+ expect(codes).toContain("text_not_painted");
+ });
+
+ it.each([
+ { name: "padding", css: "padding-top:150px" },
+ { name: "text indentation", css: "text-indent:1000px;white-space:nowrap" },
+ ])("reports glyphs moved outside the mask by $name", async ({ css }) => {
+ const codes = await auditCodes(
+ gradientHeading(`<div style="${css}">Gradient text</div>`, "height:100px"),
+ );
+ expect(codes).toContain("text_not_painted");
+ });
+
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 },