@agent-native/core-corpus 0.213.1 → 0.216.0

package/corpus/templates/slides-2/app/lib/contrast-audit.ts

@@ -0,0 +1,390 @@
+import type {
+  ContrastAuditBrowserResult,
+  ContrastAuditRequest,
+  ContrastAuditSlideInput,
+  ContrastAuditSlideTarget,
+  ContrastFailure,
+  ContrastSkipped,
+  ContrastUnverified,
+} from "@shared/contrast-audit";
+import {
+  contrastSlideRenderFingerprint,
+  deckContrastRenderKey,
+} from "@shared/contrast-audit";
+import type { AxeResults, NodeResult, RunOptions } from "axe-core";
+
+import {
+  type ContrastMeasurement,
+  measureRenderedContrast,
+  RESOLVABLE_REASONS,
+} from "./contrast-resolve";
+
+const MAX_TEXT_CHARS = 80;
+// Returns as soon as the tab catches up; the ceiling only matters when sync lags.
+const RENDER_WAIT_MS = 15_000;
+const RENDER_POLL_MS = 150;
+
+const CONTRAST_RUN_OPTIONS: RunOptions = {
+  runOnly: { type: "rule", values: ["color-contrast"] },
+  resultTypes: ["violations", "incomplete"],
+  iframes: false,
+  elementRef: true,
+};
+
+type ContrastResults = Pick<AxeResults, "violations" | "incomplete" | "passes">;
+
+export interface AuditableDeck {
+  id: string;
+  designSystemId?: string | null;
+  /** Raw JSON of the linked design system's data, if resolved. */
+  designSystemData?: string | null;
+  tweaks?: unknown;
+  aspectRatio?: string | null;
+  slides: Array<ContrastAuditSlideInput & { skipped?: boolean }>;
+}
+
+type ContrastCheckData = {
+  fgColor?: string;
+  bgColor?: string;
+  contrastRatio?: number;
+  fontSize?: string;
+  fontWeight?: string;
+  expectedContrastRatio?: string;
+  messageKey?: string;
+};
+
+function checkData(node: NodeResult): ContrastCheckData {
+  const data = node.any[0]?.data;
+  return data && typeof data === "object" ? (data as ContrastCheckData) : {};
+}
+
+function describeElement(element: Element | undefined): {
+  objectId?: string;
+  text: string;
+} {
+  const text = (element?.textContent ?? "")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, MAX_TEXT_CHARS);
+  const objectId =
+    element
+      ?.closest("[data-slide-object-id]")
+      ?.getAttribute("data-slide-object-id") ?? undefined;
+  return objectId ? { objectId, text } : { text };
+}
+
+function parseRequiredRatio(value: string | undefined): number {
+  const parsed = Number.parseFloat(value ?? "");
+  return Number.isFinite(parsed) ? parsed : Number.NaN;
+}
+
+export function mapAxeContrastResults(
+  results: ContrastResults,
+  slideId: string,
+  resolve?: (element: Element) => ContrastMeasurement | null,
+): {
+  failures: ContrastFailure[];
+  unverified: ContrastUnverified[];
+  checkedNodeCount: number;
+} {
+  const nodesFor = (group: AxeResults["violations"]) =>
+    group
+      .filter((rule) => rule.id === "color-contrast")
+      .flatMap((rule) => rule.nodes);
+
+  const violations = nodesFor(results.violations);
+  const allIncomplete = nodesFor(results.incomplete);
+  const passes = nodesFor(results.passes);
+  const incomplete: NodeResult[] = [];
+  const resolvedFailures: ContrastFailure[] = [];
+  for (const node of allIncomplete) {
+    const reason = checkData(node).messageKey ?? "";
+    const measured =
+      resolve && node.element && RESOLVABLE_REASONS.has(reason)
+        ? resolve(node.element)
+        : null;
+    if (!measured) {
+      incomplete.push(node);
+    } else if (measured.ratio < measured.requiredRatio) {
+      resolvedFailures.push({
+        slideId,
+        ...describeElement(node.element),
+        ...measured,
+      });
+    }
+  }
+
+  const failures = violations.map((node): ContrastFailure => {
+    const data = checkData(node);
+    return {
+      slideId,
+      ...describeElement(node.element),
+      foreground: data.fgColor ?? "unknown",
+      background: data.bgColor ?? "unknown",
+      ratio: typeof data.contrastRatio === "number" ? data.contrastRatio : 0,
+      requiredRatio: parseRequiredRatio(data.expectedContrastRatio),
+      fontSize: data.fontSize ?? "unknown",
+      fontWeight: data.fontWeight ?? "unknown",
+    };
+  });
+  const unverified = incomplete.map(
+    (node): ContrastUnverified => ({
+      slideId,
+      ...describeElement(node.element),
+      reason: checkData(node).messageKey ?? "unknown",
+    }),
+  );
+
+  return {
+    failures: [...failures, ...resolvedFailures],
+    unverified,
+    checkedNodeCount: violations.length + allIncomplete.length + passes.length,
+  };
+}
+
+/**
+ * Slide-number tokens paint their digits from `::before`, which axe never
+ * measures; report them so a deck cannot claim to pass with an unchecked footer.
+ */
+export function slideNumberTokenUnverified(
+  canvas: Element,
+  slideId: string,
+): ContrastUnverified[] {
+  if (!canvas.hasAttribute("data-slide-count")) return [];
+  return Array.from(
+    canvas.querySelectorAll("[data-slide-number],[data-slide-total]"),
+  ).map(
+    (token): ContrastUnverified => ({
+      slideId,
+      ...describeElement(token),
+      reason: "slideNumberToken",
+    }),
+  );
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function nextFrame(): Promise<void> {
+  return new Promise((resolve) => requestAnimationFrame(() => resolve()));
+}
+
+async function loadAxe() {
+  return (await import("axe-core")).default;
+}
+
+// axe reports text as pseudoContent when any ancestor has an absolutely
+// positioned ::before/::after with a background, ignoring opacity — so the
+// thumbnail list's scroll shadow blocks every slide. It reports the nearest
+// such ancestor, so one outside the canvas means nothing in the slide covers
+// the text, and it is safe to re-check with pseudo detection off.
+async function auditCanvas(
+  axe: Awaited<ReturnType<typeof loadAxe>>,
+  canvas: HTMLElement,
+): Promise<ContrastResults> {
+  const results = await axe.run(canvas, CONTRAST_RUN_OPTIONS);
+  const chromeBlocked = new Set(
+    results.incomplete
+      .filter((rule) => rule.id === "color-contrast")
+      .flatMap((rule) => rule.nodes)
+      .filter((node) => {
+        if (checkData(node).messageKey !== "pseudoContent") return false;
+        const owner = node.any[0]?.relatedNodes?.[0]?.element;
+        return !!owner && !canvas.contains(owner);
+      }),
+  );
+  if (chromeBlocked.size === 0) return results;
+
+  // axe accepts per-check options at run time; its typings omit them.
+  const ignorePseudo: RunOptions & {
+    checks: Record<string, { options: Record<string, unknown> }>;
+  } = {
+    ...CONTRAST_RUN_OPTIONS,
+    checks: { "color-contrast": { options: { ignorePseudo: true } } },
+  };
+  const recheck = await axe.run(
+    { include: [...chromeBlocked].map((node) => node.element!) },
+    ignorePseudo,
+  );
+  return {
+    violations: [...results.violations, ...recheck.violations],
+    incomplete: [
+      ...results.incomplete.map((rule) => ({
+        ...rule,
+        nodes: rule.nodes.filter((node) => !chromeBlocked.has(node)),
+      })),
+      ...recheck.incomplete,
+    ],
+    passes: [...results.passes, ...recheck.passes],
+  };
+}
+
+// Hit-testing skips pointer-events:none, which thumbnails and decorative
+// overlays commonly set; without this a translucent overlay would be missing
+// from the stack and the text measured against the layer beneath it.
+function withCanvasHitTesting<T>(
+  canvas: HTMLElement,
+  run: (hitTest: (x: number, y: number) => Element[]) => T,
+): T {
+  const style = document.createElement("style");
+  style.textContent =
+    "[data-contrast-hit-test], [data-contrast-hit-test] * { pointer-events: auto !important; }";
+  canvas.setAttribute("data-contrast-hit-test", "");
+  document.head.append(style);
+  try {
+    return run((x, y) => document.elementsFromPoint(x, y));
+  } finally {
+    style.remove();
+    canvas.removeAttribute("data-contrast-hit-test");
+  }
+}
+
+/**
+ * Waits for the open deck to reach the version the server asked about. The
+ * server's write reaches this tab through sync, so an audit started the moment
+ * the agent finishes an edit would otherwise check the previous HTML.
+ */
+async function waitForRequestedVersion(
+  request: ContrastAuditRequest,
+  getDeck: () => AuditableDeck | null,
+): Promise<AuditableDeck | null> {
+  const deadline = Date.now() + RENDER_WAIT_MS;
+  for (;;) {
+    const deck = getDeck();
+    if (deck && deck.id === request.deckId) {
+      const current = new Map(
+        deck.slides.map((slide) => [
+          slide.id,
+          contrastSlideRenderFingerprint(slide),
+        ]),
+      );
+      const caughtUp =
+        deckContrastRenderKey(deck) === request.renderKey &&
+        request.slides.every(
+          (slide) => current.get(slide.id) === slide.contentHash,
+        );
+      if (caughtUp || Date.now() >= deadline) return deck;
+    } else if (Date.now() >= deadline) {
+      return deck;
+    }
+    await sleep(RENDER_POLL_MS);
+  }
+}
+
+export async function runContrastAudit(
+  request: ContrastAuditRequest,
+  getDeck: () => AuditableDeck | null,
+): Promise<ContrastAuditBrowserResult> {
+  const openDeck = getDeck();
+  if (!openDeck || openDeck.id !== request.deckId) {
+    throw new Error(
+      `This tab has ${openDeck ? `deck ${openDeck.id}` : "no deck"} open, not ${request.deckId}.`,
+    );
+  }
+
+  const deck = await waitForRequestedVersion(request, getDeck);
+  if (!deck || deck.id !== request.deckId) {
+    throw new Error(`Deck ${request.deckId} was closed during the audit.`);
+  }
+  const renderKey = deckContrastRenderKey(deck);
+  const audited: ContrastAuditSlideTarget[] = [];
+  const failures: ContrastFailure[] = [];
+  const unverified: ContrastUnverified[] = [];
+  const skipped: ContrastSkipped[] = [];
+
+  if (renderKey !== request.renderKey) {
+    return {
+      deckId: deck.id,
+      renderKey,
+      audited,
+      failures,
+      unverified,
+      skipped: request.slides.map((slide) => ({
+        slideId: slide.id,
+        reason: "stale-render",
+      })),
+    };
+  }
+
+  // Let React commit the version the loop above observed in state.
+  await nextFrame();
+  await nextFrame();
+
+  const axe = await loadAxe();
+  const slidesById = new Map(deck.slides.map((slide) => [slide.id, slide]));
+
+  for (const target of request.slides) {
+    const slide = slidesById.get(target.id);
+    const contentHash = slide ? contrastSlideRenderFingerprint(slide) : null;
+    if (!slide || contentHash !== target.contentHash) {
+      skipped.push({ slideId: target.id, reason: "stale-render" });
+      continue;
+    }
+    // A hidden slide's thumbnail is dimmed under a scrim, which axe would
+    // fold into every ratio and report as a failure the slide doesn't have.
+    if (slide.skipped) {
+      skipped.push({ slideId: target.id, reason: "hidden-from-presentation" });
+      continue;
+    }
+
+    const id = CSS.escape(target.id);
+    const thumbnail = document.querySelector(
+      `[data-slide-thumbnail-id="${id}"]`,
+    );
+    const canvas = thumbnail?.querySelector<HTMLElement>(
+      `[data-slide-canvas="${id}"]`,
+    );
+    if (!thumbnail || !canvas) {
+      skipped.push({ slideId: target.id, reason: "not-rendered" });
+      continue;
+    }
+    if (thumbnail.querySelector(".slide-thumbnail-ai-shimmer")) {
+      skipped.push({ slideId: target.id, reason: "generating" });
+      continue;
+    }
+
+    const axeResults = await auditCanvas(axe, canvas);
+    const mapped = withCanvasHitTesting(canvas, (hitTest) =>
+      mapAxeContrastResults(axeResults, target.id, (element) =>
+        measureRenderedContrast(element, canvas, hitTest),
+      ),
+    );
+    // A thumbnail scrolled out of the sidebar comes back as per-text
+    // "outsideViewport". That describes the slide's position, not its text,
+    // so the slide was not checked rather than full of unverifiable text.
+    if (mapped.unverified.some((entry) => entry.reason === "outsideViewport")) {
+      skipped.push({ slideId: target.id, reason: "not-in-view" });
+      continue;
+    }
+    // axe drops text it considers off screen instead of reporting it, so a
+    // slide with text and zero checked nodes was not checked — not clean.
+    if (mapped.checkedNodeCount === 0 && canvas.textContent?.trim()) {
+      skipped.push({ slideId: target.id, reason: "not-checked" });
+      continue;
+    }
+    // axe.run() is async; sync or a user edit can change this slide (or the
+    // design system it inherits colors from) before it resolves. Re-read the
+    // live deck rather than trust the snapshot captured before the await.
+    const liveDeck = getDeck();
+    const liveSlide = liveDeck?.slides.find((entry) => entry.id === target.id);
+    const stillCurrent =
+      liveDeck &&
+      liveDeck.id === request.deckId &&
+      deckContrastRenderKey(liveDeck) === request.renderKey &&
+      liveSlide &&
+      contrastSlideRenderFingerprint(liveSlide) === target.contentHash;
+    if (!stillCurrent) {
+      skipped.push({ slideId: target.id, reason: "stale-render" });
+      continue;
+    }
+    audited.push({ id: target.id, contentHash });
+    failures.push(...mapped.failures);
+    unverified.push(
+      ...mapped.unverified,
+      ...slideNumberTokenUnverified(canvas, target.id),
+    );
+  }
+
+  return { deckId: deck.id, renderKey, audited, failures, unverified, skipped };
+}

package/corpus/templates/slides-2/app/lib/contrast-resolve.ts

@@ -0,0 +1,240 @@
+export interface Rgba {
+  r: number;
+  g: number;
+  b: number;
+  a: number;
+}
+
+export interface ContrastMeasurement {
+  foreground: string;
+  background: string;
+  ratio: number;
+  requiredRatio: number;
+  fontSize: string;
+  fontWeight: string;
+}
+
+export type HitTest = (x: number, y: number) => Element[];
+
+// Reasons that only mean "axe could not work out the background". Others
+// (icon glyphs, pseudo content, off-screen text) are not background questions.
+export const RESOLVABLE_REASONS = new Set([
+  "bgOverlap",
+  "bgImage",
+  "bgGradient",
+  "elmPartiallyObscured",
+  "elmPartiallyObscuring",
+]);
+
+const REPLACED_TAGS = new Set([
+  "IMG",
+  "SVG",
+  "VIDEO",
+  "CANVAS",
+  "IFRAME",
+  "PICTURE",
+  "OBJECT",
+  "EMBED",
+]);
+const MAX_TEXT_RECTS = 6;
+
+export function parseCssColor(value: string): Rgba | null {
+  const match = /^rgba?\(([^)]+)\)$/i.exec(value.trim());
+  if (!match) return null;
+  const parts = match[1].split(/[\s,/]+/).filter(Boolean);
+  if (parts.length < 3 || parts.length > 4) return null;
+  const [r, g, b] = parts.slice(0, 3).map(Number);
+  const alpha = parts[3];
+  const a =
+    alpha === undefined
+      ? 1
+      : alpha.endsWith("%")
+        ? Number.parseFloat(alpha) / 100
+        : Number(alpha);
+  if (![r, g, b, a].every(Number.isFinite)) return null;
+  return { r, g, b, a };
+}
+
+function over(top: Rgba, bottom: Rgba): Rgba {
+  const mix = (t: number, b: number) => t * top.a + b * (1 - top.a);
+  return {
+    r: mix(top.r, bottom.r),
+    g: mix(top.g, bottom.g),
+    b: mix(top.b, bottom.b),
+    a: 1,
+  };
+}
+
+function luminance({ r, g, b }: Rgba): number {
+  const channel = (value: number) => {
+    const c = value / 255;
+    return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+}
+
+// Floored so a ratio just under the threshold never displays or compares as a pass.
+export function contrastRatio(a: Rgba, b: Rgba): number {
+  const [light, dark] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+  return Math.floor(((light + 0.05) / (dark + 0.05)) * 100) / 100;
+}
+
+export function requiredContrastRatio(
+  fontSizePx: number,
+  fontWeight: number,
+): number {
+  const pt = (fontSizePx * 72) / 96;
+  return pt >= 18 || (pt >= 14 && fontWeight >= 700) ? 3 : 4.5;
+}
+
+function toHex({ r, g, b }: Rgba): string {
+  return `#${[r, g, b].map((c) => Math.round(c).toString(16).padStart(2, "0")).join("")}`;
+}
+
+function styleOf(element: Element, pseudo?: string): CSSStyleDeclaration {
+  return element.ownerDocument.defaultView!.getComputedStyle(element, pseudo);
+}
+
+function pseudoPaints(element: Element): boolean {
+  return ["::before", "::after"].some((pseudo) => {
+    const style = styleOf(element, pseudo);
+    const content = style.content;
+    if (!content || content === "none" || content === "normal") return false;
+    const bg = parseCssColor(style.backgroundColor);
+    return (
+      (bg?.a ?? 1) > 0 ||
+      (!!style.backgroundImage && style.backgroundImage !== "none")
+    );
+  });
+}
+
+function blends(style: CSSStyleDeclaration): boolean {
+  const set = (value: string | undefined) =>
+    !!value && value !== "none" && value !== "normal";
+  return (
+    set(style.mixBlendMode) ||
+    set(style.filter) ||
+    set(style.getPropertyValue("backdrop-filter")) ||
+    set(style.getPropertyValue("mask-image")) ||
+    set(style.getPropertyValue("-webkit-mask-image"))
+  );
+}
+
+function translucentUpTo(element: Element, canvas: Element): boolean {
+  for (let node: Element | null = element; node; node = node.parentElement) {
+    if (Number.parseFloat(styleOf(node).opacity || "1") < 1) return true;
+    if (node === canvas) return false;
+  }
+  return false;
+}
+
+function paintsOver(element: Element): boolean {
+  if (REPLACED_TAGS.has(element.tagName.toUpperCase())) return true;
+  const style = styleOf(element);
+  if ((parseCssColor(style.backgroundColor)?.a ?? 1) > 0) return true;
+  if (style.backgroundImage && style.backgroundImage !== "none") return true;
+  if (pseudoPaints(element)) return true;
+  return [...element.childNodes].some(
+    (child) => child.nodeType === Node.TEXT_NODE && child.textContent?.trim(),
+  );
+}
+
+function samplePoints(element: Element): Array<[number, number]> {
+  const range = element.ownerDocument.createRange();
+  const rects: DOMRect[] = [];
+  for (const child of element.childNodes) {
+    if (child.nodeType !== Node.TEXT_NODE || !child.textContent?.trim())
+      continue;
+    range.selectNodeContents(child);
+    rects.push(
+      ...[...range.getClientRects()].filter((r) => r.width > 0 && r.height > 0),
+    );
+  }
+  return rects.slice(0, MAX_TEXT_RECTS).flatMap((rect) => {
+    const y = rect.top + rect.height / 2;
+    return [0.2, 0.5, 0.8].map((f): [number, number] => [
+      rect.left + rect.width * f,
+      y,
+    ]);
+  });
+}
+
+/** Opaque background under one point of the text, or null when it is not a flat color. */
+function backgroundAt(
+  element: Element,
+  canvas: Element,
+  stack: Element[],
+): Rgba | null {
+  const index = stack.indexOf(element);
+  if (index < 0) return null;
+  const above = stack.slice(0, index).filter((layer) => canvas.contains(layer));
+  if (above.some(paintsOver)) return null;
+
+  const layers: Rgba[] = [];
+  for (const layer of stack.slice(index)) {
+    if (!canvas.contains(layer)) return null;
+    if (REPLACED_TAGS.has(layer.tagName.toUpperCase())) return null;
+    const style = styleOf(layer);
+    if (blends(style) || pseudoPaints(layer)) return null;
+    if (style.backgroundImage && style.backgroundImage !== "none") return null;
+    if (translucentUpTo(layer, canvas)) return null;
+    const bg = parseCssColor(style.backgroundColor);
+    if (!bg) return null;
+    if (bg.a === 0) continue;
+    layers.push(bg);
+    if (bg.a >= 1) {
+      return layers.reduceRight((below, above) => over(above, below));
+    }
+  }
+  return null;
+}
+
+/**
+ * Measures text contrast from what is actually painted under its glyphs.
+ * Returns null unless every sampled point sits on flat colors all the way
+ * down to an opaque layer inside the slide, so an unresolvable case stays
+ * unverified rather than becoming a guessed pass.
+ */
+export function measureRenderedContrast(
+  element: Element,
+  canvas: Element,
+  hitTest: HitTest,
+): ContrastMeasurement | null {
+  if (!canvas.contains(element)) return null;
+  const style = styleOf(element);
+  const clip =
+    style.getPropertyValue("-webkit-background-clip") || style.backgroundClip;
+  if (clip === "text" || blends(style) || translucentUpTo(element, canvas))
+    return null;
+  const fill = parseCssColor(
+    style.getPropertyValue("-webkit-text-fill-color") || style.color,
+  );
+  if (!fill || fill.a === 0) return null;
+
+  const points = samplePoints(element);
+  if (points.length === 0) return null;
+
+  const fontSizePx = Number.parseFloat(style.fontSize);
+  const fontWeight = Number.parseFloat(style.fontWeight) || 400;
+  if (!Number.isFinite(fontSizePx)) return null;
+  const requiredRatio = requiredContrastRatio(fontSizePx, fontWeight);
+
+  let worst: { ratio: number; fg: Rgba; bg: Rgba } | null = null;
+  for (const [x, y] of points) {
+    const bg = backgroundAt(element, canvas, hitTest(x, y));
+    if (!bg) return null;
+    const fg = over(fill, bg);
+    const ratio = contrastRatio(fg, bg);
+    if (!worst || ratio < worst.ratio) worst = { ratio, fg, bg };
+  }
+  if (!worst) return null;
+
+  return {
+    foreground: toHex(worst.fg),
+    background: toHex(worst.bg),
+    ratio: worst.ratio,
+    requiredRatio,
+    fontSize: `${((fontSizePx * 72) / 96).toFixed(1)}pt (${fontSizePx}px)`,
+    fontWeight: String(fontWeight),
+  };
+}