fix(cli): contrast gate judges only readable content; examples pass check

Three filters keep the escalated contrast gate honest, each surfaced by
running check across the registry examples:
- data-layout-ignore (the layout audit's existing decorative opt-out)
  now also excludes set-dressing text from the contrast audit — one
  vocabulary for 'not copy a viewer must read'.
- Text that has (nearly) left the canvas is skipped: sampling a clamped
  off-canvas box reads border pixels and produced the classic false
  white-on-white (a cursor exiting the frame).
- Contrast failures follow the same persistence rule as layout findings:
  observed at a single sample of a multi-sample sweep demotes to
  warning; held failures gate.

Example fixes the sweep exposed: motion-blur's 21 deliberately-dim rail
labels are marked decorative (its vivid labels pass on their own);
nyt-graph's subtitle and source-note adopt the gate's suggested
compliant gray; decision-tree's declared duration drops 15s to 10s —
its content ends at ~9.5s and every render shipped a blank white tail.

packages/cli/src/utils/checkBrowser.test.ts

@@ -51,6 +51,18 @@ afterEach(() => {
   Reflect.deleteProperty(window, "__contrastAuditRestoreIfPending");
 });
 
+function installSessionMock(page: ReturnType<typeof fakePage>): void {
+  const browser = Object.assign(Object.create(null), {
+    close: vi.fn(async () => undefined),
+  });
+  vi.mocked(openSettledCompositionPage).mockImplementation(
+    async (_html: string, _url: string, options: OpenSettledCompositionPageOptions) => {
+      await options.beforeNavigate?.(page);
+      return { page, browser, renderReadyTimedOut: false };
+    },
+  );
+}
+
 it("carries raw browser geometry through the page driver and pipeline", async () => {
   vi.spyOn(Date, "now")
     .mockReturnValueOnce(100)
@@ -68,15 +80,7 @@ it("carries raw browser geometry through the page driver and pipeline", async ()
   Object.defineProperty(window, "innerHeight", { configurable: true, value: 360 });
   installRects();
   const page = fakePage();
-  const browser = Object.assign(Object.create(null), {
-    close: vi.fn(async () => undefined),
-  });
-  vi.mocked(openSettledCompositionPage).mockImplementation(
-    async (_html: string, _url: string, options: OpenSettledCompositionPageOptions) => {
-      await options.beforeNavigate?.(page);
-      return { page, browser, renderReadyTimedOut: false };
-    },
-  );
+  installSessionMock(page);
 
   const result = await runBrowserCheck(
     PROJECT,
@@ -184,15 +188,7 @@ it("round-trips the browser script's raw contrast candidates back into finish",
     }
   });
   page.screenshot = vi.fn(async () => "c3R1Yg==");
-  const browser = Object.assign(Object.create(null), {
-    close: vi.fn(async () => undefined),
-  });
-  vi.mocked(openSettledCompositionPage).mockImplementation(
-    async (_html: string, _url: string, options: OpenSettledCompositionPageOptions) => {
-      await options.beforeNavigate?.(page);
-      return { page, browser, renderReadyTimedOut: false };
-    },
-  );
+  installSessionMock(page);
 
   await runBrowserCheck(
     PROJECT,

packages/cli/src/utils/checkPipeline.ts

@@ -632,21 +632,45 @@ export function checkExitCode(report: CheckReport): 0 | 1 {
   return report.ok ? 0 : 1;
 }
 
+// Same persistence rule the layout findings follow: a failure observed at a
+// single contrast sample is usually text caught mid-entrance/exit (its real
+// background not painted yet — white-on-white at exactly 1.0 is the classic
+// shape), so it demotes to warning. A failure HELD at 2+ samples for the same
+// element is a real, gating defect. Single-sample sweeps can't distinguish,
+// so they keep full severity.
+function contrastFailureHeld(
+  entries: ContrastAuditEntry[],
+): (entry: ContrastAuditEntry) => boolean {
+  const sampledTimes = new Set(entries.map((entry) => entry.time)).size;
+  const failureSamples = new Map<string, Set<number>>();
+  for (const entry of entries) {
+    if (entry.wcagAA) continue;
+    const key = `${entry.selector}|${entry.text}`;
+    const times = failureSamples.get(key) ?? new Set<number>();
+    times.add(entry.time);
+    failureSamples.set(key, times);
+  }
+  return (entry) =>
+    sampledTimes < 2 || (failureSamples.get(`${entry.selector}|${entry.text}`)?.size ?? 0) >= 2;
+}
+
 function buildContrastResults(entries: ContrastAuditEntry[]): {
   findings: CheckContrastFinding[];
   passed: number;
 } {
   const findings: CheckContrastFinding[] = [];
   let passed = 0;
+  const isHeld = contrastFailureHeld(entries);
   for (const entry of entries) {
     if (entry.wcagAA) {
       passed += 1;
       continue;
     }
+    const held = isHeld(entry);
     const requiredRatio = requiredContrastRatio(entry.large);
     findings.push({
       code: "contrast_aa_failure",
-      severity: "error",
+      severity: held ? "error" : "warning",
       message: `Contrast is ${entry.ratio}:1; WCAG AA requires ${requiredRatio}:1.`,
       text: entry.text,
       fg: entry.fg,