fix(cli): three occlusion-probe false-positive sources in text_occluded

- pointer-events:none text is invisible to elementFromPoint, so the probe
  always hit whatever paints beneath and misread visible text as buried;
  restore hit-testing on the element for the duration of the probe
- a backgroundImage counted as opaque regardless of alpha, so a 4%-alpha
  grid/scrim gradient qualified as an occluder; gradients now occlude only
  when their colours reach alpha > 0.6 (url() images unchanged)
- a visible container whose every text-bearing descendant is still at
  opacity 0 (entrance not started) was probed anyway; skip when no text
  ink is on screen

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: xuanruli

packages/cli/src/commands/layout-audit.browser.js

@@ -659,11 +659,39 @@
   }
 
   function hasOpaqueBackground(style) {
-    if (style.backgroundImage && style.backgroundImage !== "none") return true;
+    if (style.backgroundImage && style.backgroundImage !== "none") {
+      if (style.backgroundImage.includes("url(")) return true;
+      // A gradient only occludes as much as the colours in it: a 4%-alpha
+      // grid/scrim pattern must not count as an opaque occluder.
+      if (gradientMaxAlpha(style.backgroundImage) > 0.6) return true;
+    }
     if (isTransparentColor(style.backgroundColor)) return false;
     return colorAlpha(style.backgroundColor) > 0.6;
   }
 
+  function gradientMaxAlpha(backgroundImage) {
+    const colors = backgroundImage.match(/rgba?\([^)]*\)|#[0-9a-fA-F]{3,8}\b|\btransparent\b/g);
+    if (!colors) return 1; // named colours we cannot parse — keep the old (opaque) behaviour
+    let max = 0;
+    for (const color of colors) {
+      if (color === "transparent") continue;
+      if (color.startsWith("#")) {
+        const hex = color.slice(1);
+        max = Math.max(
+          max,
+          hex.length === 4
+            ? parseInt(hex[3] + hex[3], 16) / 255
+            : hex.length === 8
+              ? parseInt(hex.slice(6), 16) / 255
+              : 1,
+        );
+      } else {
+        max = Math.max(max, colorAlpha(color));
+      }
+    }
+    return max;
+  }
+
   const RASTER_TAGS = new Set(["IMG", "VIDEO", "CANVAS"]);
   const FRAME_MEDIA_TAGS = new Set([...RASTER_TAGS, "SVG"]);
 
@@ -754,18 +782,50 @@
   // reads very differently from a label buried under an overlay. Still
   // returns the first opaque element found, for `containerSelector`.
   function occlusionCoverage(element, textRect) {
-    let occluder = null;
-    let hits = 0;
-    for (const yFraction of OCCLUSION_PROBE_Y_FRACTIONS) {
-      const y = textRect.top + textRect.height * yFraction;
-      for (const xFraction of OCCLUSION_PROBE_X_FRACTIONS) {
-        const hit = occluderAt(element, textRect.left + textRect.width * xFraction, y);
-        if (!hit) continue;
-        hits += 1;
-        if (!occluder) occluder = hit;
+    // pointer-events:none makes the element invisible to elementFromPoint, so
+    // the probe would always "hit" whatever paints beneath it and misread
+    // perfectly visible text as buried (decorative text commonly carries
+    // pointer-events:none). Restore hit-testing for the duration of the probe.
+    const restore = restoreHitTesting(element);
+    try {
+      let occluder = null;
+      let hits = 0;
+      for (const yFraction of OCCLUSION_PROBE_Y_FRACTIONS) {
+        const y = textRect.top + textRect.height * yFraction;
+        for (const xFraction of OCCLUSION_PROBE_X_FRACTIONS) {
+          const hit = occluderAt(element, textRect.left + textRect.width * xFraction, y);
+          if (!hit) continue;
+          hits += 1;
+          if (!occluder) occluder = hit;
+        }
       }
+      return { occluder, coveredFraction: round(hits / OCCLUSION_GRID_POINTS) };
+    } finally {
+      restore();
     }
-    return { occluder, coveredFraction: round(hits / OCCLUSION_GRID_POINTS) };
+  }
+
+  function restoreHitTesting(element) {
+    if (getComputedStyle(element).pointerEvents !== "none") return () => {};
+    const previous = element.style.getPropertyValue("pointer-events");
+    const priority = element.style.getPropertyPriority("pointer-events");
+    element.style.setProperty("pointer-events", "auto", "important");
+    return () => {
+      if (previous) element.style.setProperty("pointer-events", previous, priority);
+      else element.style.removeProperty("pointer-events");
+    };
+  }
+
+  // The container can be fully visible while every text-bearing descendant is
+  // still at opacity 0 (entrance not started yet) — there is no ink on screen
+  // to occlude, so probing it only manufactures false "buried text" findings.
+  function hasVisibleTextInk(element) {
+    const nodes = [element, ...element.querySelectorAll("*")];
+    for (const node of nodes) {
+      if (directTextNodes(node).length === 0) continue;
+      if (opacityChain(node) >= 0.2) return true;
+    }
+    return false;
   }
 
   // Catches the blind spot the overflow checks miss: text that fits its box
@@ -775,6 +835,7 @@
   // cover on a paragraph is usually a styling artifact, not a reading defect.
   function occludedTextIssue(element, time) {
     if (hasAllowOcclusionFlag(element)) return null;
+    if (!hasVisibleTextInk(element)) return null;
     const textRect = textRectFor(element);
     if (!textRect) return null;
     const text = textContentFor(element);

packages/cli/src/commands/layout-audit.browser.test.ts

@@ -904,6 +904,71 @@ describe("layout-audit.browser occlusion", () => {
     });
     expect(issues.some((issue) => issue.code === "text_occluded")).toBe(true);
   });
+
+  it("does not flag visible text carrying pointer-events:none (probe restores hit-testing)", () => {
+    document.body.innerHTML = `
+      <div id="root" data-composition-id="main" data-width="1920" data-height="1080">
+        <div id="headline">Headline copy</div>
+        <div id="overlay"></div>
+      </div>
+    `;
+    installOcclusionGeometry({
+      styleOverrides: {
+        headline: { pointerEvents: "none" },
+        overlay: { backgroundColor: "rgb(10, 10, 10)" },
+      },
+      headlineTextRect: rect({ left: 200, top: 500, width: 600, height: 80 }),
+      topmostId: "overlay",
+    });
+    // Simulate real hit-testing: once the probe restores hit-testing (inline
+    // pointer-events: auto), the topmost element at the text IS the text.
+    (document as unknown as { elementFromPoint: () => Element | null }).elementFromPoint = () => {
+      const headline = document.getElementById("headline");
+      return headline?.style.getPropertyValue("pointer-events") === "auto"
+        ? headline
+        : document.getElementById("overlay");
+    };
+    installAuditScript();
+    expect(runAudit().some((issue) => issue.code === "text_occluded")).toBe(false);
+  });
+
+  it("does not count a low-alpha gradient overlay (grid/scrim) as an opaque occluder", () => {
+    const issues = auditOcclusionScene({
+      overlayStyle: {
+        backgroundImage:
+          "repeating-linear-gradient(0deg, rgba(255, 255, 255, 0.04) 0px, transparent 1px)",
+      },
+      topmostId: "overlay",
+    });
+    expect(issues.some((issue) => issue.code === "text_occluded")).toBe(false);
+  });
+
+  it("still counts an opaque gradient panel as an occluder", () => {
+    const occluded = auditOcclusionScene({
+      overlayStyle: { backgroundImage: "linear-gradient(rgb(10, 10, 10), rgb(40, 40, 40))" },
+      topmostId: "overlay",
+    }).find((issue) => issue.code === "text_occluded");
+    expect(occluded).toBeDefined();
+  });
+
+  it("does not probe text whose every text node is still at opacity 0 (entrance not started)", () => {
+    document.body.innerHTML = `
+      <div id="root" data-composition-id="main" data-width="1920" data-height="1080">
+        <div id="headline"><span id="inner">Headline copy</span></div>
+        <div id="overlay"></div>
+      </div>
+    `;
+    installOcclusionGeometry({
+      styleOverrides: {
+        inner: { opacity: "0" },
+        overlay: { backgroundColor: "rgb(10, 10, 10)" },
+      },
+      headlineTextRect: rect({ left: 200, top: 500, width: 600, height: 80 }),
+      topmostId: "overlay",
+    });
+    installAuditScript();
+    expect(runAudit().some((issue) => issue.code === "text_occluded")).toBe(false);
+  });
 });
 
 // Mirrors OCCLUSION_PROBE_Y_FRACTIONS / OCCLUSION_PROBE_X_FRACTIONS in