@zaip-ai/cli 6.3.0 → 7.5.0

package/templates/.agents/tools/visual-url/captured-visual.mjs

@@ -0,0 +1,301 @@
+import { captureCoverage, chroma, gradientColors, mergeCandidates } from "./color-candidates.mjs";
+// Project verified browser observations into local demonstration roles. Semantic
+// assignment is inferred; the referenced scalar/viewport remain observed evidence.
+export function applyCapturedVisual(model, proposal, normalize) {
+  if (!proposal.capabilities?.browser_resolved || !proposal.capabilities?.runtime_rendered)
+    return model;
+  const nodes = [];
+  let node;
+  for (const item of proposal.observations) {
+    if (
+      item.kind !== "observed" ||
+      item.reason !== null ||
+      item.provenance.method !== "browser-computed-style" ||
+      !item.provenance.viewport
+    )
+      continue;
+    const property = /^Browser computed ([a-z-]+)$/.exec(item.subject)?.[1];
+    if (!property) continue;
+    const selector = item.provenance.selector;
+    node = nodes.findLast((row) => row.selector === selector && !row.values[property]);
+    if (!node) {
+      node = { selector, values: {}, raw: {}, context: null };
+      nodes.push(node);
+    }
+    node.raw[property] = item;
+    if (property === "sample-context") {
+      try {
+        const value = JSON.parse(item.value);
+        if (
+          ["action", "heading", "surface"].includes(value.role) &&
+          /^(?:[a-z]{1,16})$/.test(value.tag) &&
+          /^(body|header|footer|nav|main|section|article|aside)$/.test(value.region)
+        )
+          node.context = {
+            role: value.role,
+            tag: value.tag,
+            region: value.region,
+            element_id: /^rendered-\d{1,4}$/.test(value.element_id) ? value.element_id : null,
+            action_selector:
+              typeof value.action_selector === "string" && value.action_selector.length <= 500
+                ? value.action_selector
+                : null,
+            source_type: value.source_type === "pseudo" ? "pseudo" : "element",
+            in_viewport: value.in_viewport === true,
+          };
+      } catch {
+        /* Invalid context cannot affect semantic roles. */
+      }
+    }
+    const value = normalize(property, item.value);
+    // Even an unsupported property delimits duplicate same-selector nodes.
+    node.values[property] =
+      value === null
+        ? { unavailable: true }
+        : {
+            value,
+            property,
+            kind: "inferred",
+            evidence: [item.id],
+            provenance: item.provenance,
+            reason: "Papel de demonstração inferido de estilo calculado no viewport capturado",
+          };
+  }
+  if (!nodes.length) return model;
+  const tag = (n) =>
+    n.selector
+      .split(" > ")
+      .at(-1)
+      .match(/^[a-z][a-z0-9]*/)?.[0];
+  model.status = "inferred";
+  const scalar = (node, key) => (node?.values[key]?.value ? node.values[key] : null);
+  const opaque = (token) => token && /^#[a-f\d]{6}(?:ff)?$/i.test(token.value);
+  const body = nodes.find((n) => /^body(?:#|$)/.test(n.selector));
+  const root = nodes.find((n) => /^html(?:#|$)/.test(n.selector));
+  const colors = model.tokens.colors;
+  const background = [scalar(body, "background-color"), scalar(root, "background-color")].find(
+    opaque,
+  );
+  const foreground = scalar(body, "color");
+  if (background) colors.background = background;
+  if (foreground) colors.foreground = foreground;
+  // Existing declarations can belong to an inactive theme. Keep unknown roles
+  // neutral/derived in the renderer instead of mixing them into the captured one.
+  for (const key of [
+    "card",
+    "card_foreground",
+    "secondary",
+    "muted",
+    "border",
+    "accent",
+    "primary",
+    "primary_foreground",
+  ])
+    colors[key] = null;
+  if (background) colors.card = background;
+  if (foreground) colors.card_foreground = foreground;
+  const luminance = (hex) => {
+    const c = [1, 3, 5]
+      .map((i) => parseInt(hex.slice(i, i + 2), 16) / 255)
+      .map((v) => (v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4));
+    return 0.2126 * c[0] + 0.7152 * c[1] + 0.0722 * c[2];
+  };
+  const canvas = colors.background?.value;
+  const paint = [];
+  for (const n of nodes) {
+    const action =
+      n.context?.role === "action" || ["button", "a", "input", "select"].includes(tag(n));
+    const clipped = n.raw["background-clip"]?.value === "text";
+    for (const property of ["background-color", "background-image", "color", "fill", "stroke"]) {
+      const item = n.raw[property];
+      if (!item) continue;
+      const values =
+        property === "background-image"
+          ? gradientColors(item.value)
+          : [scalar(n, property)?.value].filter(Boolean);
+      for (const value of values) {
+        if (!/^#[a-f\d]{6}$/i.test(value)) continue;
+        const role_hint =
+          action && property === "background-color"
+            ? "action"
+            : property === "background-image" && clipped
+              ? "gradient-text"
+              : n.context?.source_type === "pseudo"
+                ? "pseudo"
+                : ["fill", "stroke"].includes(property)
+                  ? "svg-paint"
+                  : n.context?.region === "footer"
+                    ? "footer"
+                    : property === "background-color" || property === "background-image"
+                      ? "surface"
+                      : "text";
+        const token = {
+          value,
+          property: property === "background-image" ? "color" : property,
+          kind: "inferred",
+          evidence: [item.id],
+          provenance: item.provenance,
+          reason:
+            "Papel proposto a partir de cor computada; contraste não determina presença da cor",
+        };
+        const actionPaint =
+          action && ["background-color", "background-image"].includes(property) && value !== canvas;
+        // Ordinary text is an inventory value, never evidence of an action/highlight role.
+        const highlightPaint =
+          value !== canvas &&
+          !["html", "body"].includes(tag(n)) &&
+          ["background-color", "background-image", "fill", "stroke"].includes(property) &&
+          chroma(value) >= 0.08;
+        const rank =
+          (role_hint === "action"
+            ? 100
+            : role_hint === "gradient-text"
+              ? 70
+              : role_hint === "surface"
+                ? 50
+                : 20) +
+          chroma(value) * 10;
+        paint.push({
+          n,
+          token,
+          actionPaint,
+          highlightPaint,
+          rank,
+          candidate: {
+            value,
+            property,
+            source: "observed",
+            kind: "inferred",
+            evidence: [item.id],
+            provenance: item.provenance,
+            role_hint,
+            element_id: n.context?.element_id ?? null,
+            in_viewport: n.context?.in_viewport ?? null,
+            ...(n.context?.action_selector ? { action_selector: n.context.action_selector } : {}),
+            reason:
+              "Valor computado observado; papel semântico inferido, sem descartar baixo contraste",
+          },
+        });
+      }
+    }
+  }
+  // Equal semantic/chroma evidence follows the stable element path, not sampling order.
+  paint.sort(
+    (a, b) => b.rank - a.rank || a.n.selector.localeCompare(b.n.selector, "en", { numeric: true }),
+  );
+  const primaryPaint = paint.find((row) => row.actionPaint);
+  const primary = primaryPaint?.n;
+  if (primaryPaint) {
+    colors.primary = primaryPaint.token;
+    // A text/gradient/SVG color is not evidence of a filled control/text pair.
+    const textSource = primary.context?.action_selector
+      ? nodes.find((row) => row.selector === primary.context.action_selector)
+      : primary;
+    colors.primary_foreground =
+      primaryPaint.candidate.property === "background-color" ? scalar(textSource, "color") : null;
+  }
+  const accent = paint.find(
+    (row) => row.highlightPaint && row.token.value !== colors.primary?.value,
+  );
+  if (accent) colors.accent = accent.token;
+  const inventory = mergeCandidates(
+    paint.map((row) => row.candidate),
+    model.color_candidates ?? [],
+  );
+  model.color_candidates = inventory.rows;
+  model.coverage = { ...captureCoverage(proposal), candidates_omitted: inventory.omitted };
+  const heading = nodes.find((n) => /^h[1-3]$/.test(tag(n)));
+  const typography = model.tokens.typography;
+  for (const [role, property] of Object.entries({
+    body_family: "font-family",
+    size: "font-size",
+    weight: "font-weight",
+    line_height: "line-height",
+    letter_spacing: "letter-spacing",
+  })) {
+    const value = scalar(body, property);
+    if (value) typography[role] = value;
+  }
+  typography.heading_family = scalar(heading, "font-family") ?? typography.body_family;
+  // Repeated selectors (e.g. many buttons) do not identify a unique node. Never
+  // apply the first matching node's colors to all demo controls.
+  if (body)
+    model.components = model.components.map(({ tokens, ...item }) => ({ ...item, tokens: {} }));
+  if (primary)
+    model.components = [
+      {
+        tag: "button",
+        selector: "button-primary",
+        role: "button",
+        text: "Primário",
+        evidence: colors.primary.evidence,
+        provenance: colors.primary.provenance,
+        tokens: {
+          background: colors.primary,
+          foreground: colors.primary_foreground,
+          radius: scalar(primary, "border-radius"),
+          font_family: scalar(primary, "font-family"),
+          font_weight: scalar(primary, "font-weight"),
+          border: scalar(primary, "border-color"),
+          shadow: scalar(primary, "box-shadow"),
+        },
+      },
+      ...model.components,
+    ].slice(0, 12);
+  // Only uniquely addressed captured elements can receive their own mappings.
+  // Repeated legacy selectors must never spread one button's style to all buttons.
+  const captured = nodes
+    .filter(
+      (n) =>
+        ["button", "a", "input", "select", "nav"].includes(tag(n)) &&
+        nodes.filter((other) => other.selector === n.selector).length === 1,
+    )
+    .slice(0, 10)
+    .map((n) => ({
+      tag: tag(n),
+      selector: n.selector,
+      role: tag(n),
+      text: "",
+      evidence: scalar(n, "color")?.evidence ?? [],
+      provenance: scalar(n, "color")?.provenance,
+      tokens: Object.fromEntries(
+        Object.entries({
+          foreground: "color",
+          background: "background-color",
+          radius: "border-radius",
+          border: "border-color",
+          padding: "padding",
+          font_family: "font-family",
+          font_size: "font-size",
+          font_weight: "font-weight",
+          shadow: "box-shadow",
+        }).map(([role, property]) => [role, scalar(n, property)]),
+      ),
+    }));
+  model.components = [
+    ...model.components.filter((c) => c.selector === "button-primary"),
+    ...captured,
+    ...model.components.filter(
+      (c) => c.selector !== "button-primary" && !captured.some((n) => n.selector === c.selector),
+    ),
+  ].slice(0, 12);
+  model.unknown = model.unknown.filter(
+    (key) => !key.startsWith("colors.") && !key.startsWith("typography."),
+  );
+  for (const group of ["colors", "typography"])
+    for (const [key, value] of Object.entries(model.tokens[group]))
+      if (!value) model.unknown.push(`${group}.${key}`);
+  model.theme = {
+    ...model.theme,
+    status: background ? "observed" : "unknown",
+    active: background ? (luminance(background.value) < 0.25 ? "dark" : "light") : null,
+    basis: "browser-computed-style",
+    viewport: body?.values.color?.provenance?.viewport ?? null,
+  };
+  model.limitations = [
+    "Estilos calculados da captura priorizados; papéis semânticos de demonstração são inferidos.",
+    "A captura cobre um viewport e momento; CSS declarado pode incluir cores de outros temas, estados e elementos fora da captura.",
+    "Valores ausentes usam alternativas neutras locais; fontes dependem dos arquivos disponíveis no dispositivo.",
+  ];
+  return model;
+}

package/templates/.agents/tools/visual-url/cli.mjs

@@ -0,0 +1,29 @@
+import { realpath } from "node:fs/promises";
+import { read } from "./files.mjs";
+import { extract } from "./runtime.mjs";
+
+try {
+  const [command, ...args] = process.argv.slice(2);
+  const options = {};
+  if (command !== "extract") throw new Error("Expected extract command");
+  for (let index = 0; index < args.length; index += 2) {
+    if (
+      !["--workspace", "--input"].includes(args[index]) ||
+      !args[index + 1] ||
+      Object.hasOwn(options, args[index])
+    )
+      throw new Error("Invalid/duplicate extraction option");
+    options[args[index]] = args[index + 1];
+  }
+  if (!options["--workspace"] || !options["--input"]?.startsWith(".local/"))
+    throw new Error("Explicit workspace and local input required");
+  const workspace = await realpath(options["--workspace"]);
+  const input = JSON.parse((await read(workspace, options["--input"])).toString("utf8"));
+  const result = await extract({ workspace, input });
+  process.stdout.write(`${JSON.stringify({ ok: true, ...result })}\n`);
+} catch (error) {
+  process.stdout.write(
+    `${JSON.stringify({ ok: false, error: error.code ? `Extraction I/O error: ${error.code}` : error.message, failure: error.failure ?? null })}\n`,
+  );
+  process.exitCode = 1;
+}

package/templates/.agents/tools/visual-url/color-candidates.mjs

@@ -0,0 +1,161 @@
+import { normalizeColor } from "./colors.mjs";
+
+export function gradientColors(value) {
+  if (
+    typeof value !== "string" ||
+    value.length > 2048 ||
+    /url\(|var\(|[;{}<>\\]/i.test(value) ||
+    !/^(?:repeating-)?(?:linear|radial|conic)-gradient\(.+\)$/i.test(value)
+  )
+    return [];
+  const colors = [];
+  const remaining = value
+    .replace(
+      /(?:rgba?|hsla?)\([^()]{1,128}\)|#[a-f\d]{3,8}\b|\b(?:transparent|black|white|red|blue|green|gray|grey|yellow|orange|purple|pink|cyan|magenta|navy|teal)\b/gi,
+      (match) => {
+        const color = normalizeColor(match);
+        if (color && color.length === 7) colors.push(color);
+        return "0";
+      },
+    )
+    .replace(/(?:repeating-)?(?:linear|radial|conic)-gradient\(/gi, "(");
+  // Only scalar stops and standard geometry survive. No arbitrary CSS is emitted.
+  if (/[a-z-]+\s*\(/i.test(remaining) || /[^\w\s.,()%+\-]/.test(remaining)) return [];
+  return [...new Set(colors)].slice(0, 8);
+}
+
+export function chroma(value) {
+  const rgb = [1, 3, 5].map((i) => parseInt(value.slice(i, i + 2), 16));
+  return (Math.max(...rgb) - Math.min(...rgb)) / 255;
+}
+
+export function captureCoverage(proposal) {
+  const observation = proposal.observations.find(
+    (item) =>
+      item.subject === "Browser capture coverage" &&
+      item.kind === "observed" &&
+      item.reason === null &&
+      item.provenance?.method === "browser-computed-style" &&
+      item.provenance.viewport,
+  );
+  let data;
+  try {
+    data = JSON.parse(observation?.value ?? "null");
+  } catch {
+    /* legacy or invalid metadata */
+  }
+  const count = (value) => Number.isSafeInteger(value) && value >= 0 && value <= 10000000;
+  const valid =
+    data?.method === "region-paint-balanced-v1" &&
+    [data.scanned, data.sampled, data.omitted, data.scan_omitted].every(count) &&
+    data.sampled <= 48 &&
+    data.scanned <= 2000;
+  const ready = data?.readiness;
+  const readiness =
+    ready &&
+    ["loaded", "loading", "unavailable"].includes(ready.fonts) &&
+    [ready.images_pending, ready.images_failed, ready.images_omitted].every(count) &&
+    typeof ready.layout_stable === "boolean"
+      ? {
+          fonts: ready.fonts,
+          images_pending: ready.images_pending,
+          images_failed: ready.images_failed,
+          images_omitted: ready.images_omitted,
+          layout_stable: ready.layout_stable,
+        }
+      : null;
+  return valid
+    ? {
+        method: data.method,
+        status:
+          !readiness ||
+          readiness.fonts !== "loaded" ||
+          readiness.images_pending ||
+          readiness.images_failed ||
+          readiness.images_omitted ||
+          !readiness.layout_stable ||
+          data.scan_omitted
+            ? "incomplete"
+            : "sampled",
+        scanned: data.scanned,
+        sampled: data.sampled,
+        omitted: data.omitted,
+        scan_omitted: data.scan_omitted,
+        readiness,
+        limitations: [
+          "Amostra limitada de elementos renderizados no documento; não mede pixels ou cobertura de todos os estados.",
+          "Elementos fora do viewport não são comprovados pelo screenshot; imagens de fundo e recursos tardios podem permanecer ausentes.",
+        ],
+      }
+    : {
+        status: "legacy-unknown",
+        method: null,
+        scanned: null,
+        sampled: null,
+        omitted: null,
+        readiness: null,
+        limitations: [
+          "Captura salva sem inventário de amostragem/prontidão; cobertura não estabelecida.",
+        ],
+      };
+}
+
+export function declaredCandidates(declarations, resolve) {
+  const result = [],
+    seen = new Set();
+  for (const item of declarations) {
+    if (!/color|background|fill|stroke|primary|accent|foreground|muted|^--/.test(item.property))
+      continue;
+    const raw = resolve(item);
+    if (!raw) continue;
+    const colors = [normalizeColor(raw), ...gradientColors(raw)].filter(Boolean);
+    for (const value of colors) {
+      if (value.length !== 7 || seen.has(value)) continue;
+      seen.add(value);
+      result.push({
+        value,
+        source: "declared",
+        kind: "inferred",
+        property: item.property,
+        evidence: [item.id],
+        provenance: item.provenance,
+        role_hint: null,
+        reason: "Declaração CSS; elemento, estado e tema ativo não comprovados",
+      });
+    }
+  }
+  return result;
+}
+
+export function mergeCandidates(observed, declared) {
+  const rows = [],
+    seen = new Set();
+  for (const item of [...observed, ...declared]) {
+    const key = `${item.source}:${item.value}:${item.property}:${item.provenance?.selector}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    rows.push(item);
+  }
+  const representative = new Set();
+  const measuredRows = rows.filter((row) => row.source === "observed");
+  const measured = [
+    ...measuredRows.filter((row) => {
+      if (representative.has(row.value)) return false;
+      representative.add(row.value);
+      return true;
+    }),
+    ...measuredRows.filter(
+      (row) => measuredRows.find((other) => other.value === row.value) !== row,
+    ),
+  ];
+  const css = rows.filter((row) => row.source === "declared");
+  const selected = [
+    ...measured.slice(0, 24),
+    ...css.slice(0, Math.max(8, 32 - Math.min(measured.length, 24))),
+  ];
+  for (const row of [...measured.slice(24), ...css.slice(8)]) {
+    if (selected.length >= 32) break;
+    if (!selected.includes(row)) selected.push(row);
+  }
+  return { rows: selected.slice(0, 32), omitted: Math.max(0, rows.length - selected.length) };
+}

package/templates/.agents/tools/visual-url/colors.mjs

@@ -0,0 +1,98 @@
+const named = {
+  transparent: "#00000000",
+  black: "#000000",
+  white: "#ffffff",
+  red: "#ff0000",
+  blue: "#0000ff",
+  green: "#008000",
+  gray: "#808080",
+  grey: "#808080",
+  yellow: "#ffff00",
+  orange: "#ffa500",
+  purple: "#800080",
+  pink: "#ffc0cb",
+  cyan: "#00ffff",
+  magenta: "#ff00ff",
+  navy: "#000080",
+  teal: "#008080",
+};
+const clamp = (value, maximum) => Math.max(0, Math.min(maximum, value));
+function number(value, maximum) {
+  if (!/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)%?$/.test(value)) return null;
+  const result = Number.parseFloat(value) * (value.endsWith("%") ? maximum / 100 : 1);
+  return Number.isFinite(result) ? clamp(result, maximum) : null;
+}
+function hex(channels) {
+  const rgb = channels
+    .slice(0, 3)
+    .map((value) => Math.round(value).toString(16).padStart(2, "0"))
+    .join("");
+  const alpha = Math.round(channels[3] * 255);
+  return `#${rgb}${alpha === 255 ? "" : alpha.toString(16).padStart(2, "0")}`;
+}
+export function normalizeColor(value) {
+  const text = value.trim().toLowerCase();
+  if (Object.hasOwn(named, text)) return named[text];
+  if (/^#[a-f0-9]{3,4}$/.test(text))
+    return normalizeColor(
+      `#${text
+        .slice(1)
+        .split("")
+        .map((char) => char + char)
+        .join("")}`,
+    );
+  if (/^#[a-f0-9]{6}(?:[a-f0-9]{2})?$/.test(text))
+    return text.endsWith("ff") && text.length === 9 ? text.slice(0, 7) : text;
+  const match = /^(rgba?|hsla?)\(([^()]{1,256})\)$/.exec(text);
+  if (!match) return null;
+  const values = match[2].trim().split(/[\s,/]+/);
+  if (values.length < 3 || values.length > 4) return null;
+  const alpha = values.length === 4 ? number(values[3], 1) : 1;
+  if (alpha === null) return null;
+  if (match[1].startsWith("rgb")) {
+    const channels = values.slice(0, 3).map((value) => number(value, 255));
+    return channels.includes(null) ? null : hex([...channels, alpha]);
+  }
+  const hue = /^([+-]?(?:\d+(?:\.\d*)?|\.\d+))(deg|turn|rad)?$/.exec(values[0]);
+  if (!hue || !values[1].endsWith("%") || !values[2].endsWith("%")) return null;
+  const h =
+    ((((Number(hue[1]) * (hue[2] === "turn" ? 360 : hue[2] === "rad" ? 180 / Math.PI : 1)) % 360) +
+      360) %
+      360) /
+    30;
+  const s = number(values[1], 1),
+    l = number(values[2], 1);
+  if (![h, s, l].every((value) => value !== null && Number.isFinite(value))) return null;
+  const a = s * Math.min(l, 1 - l);
+  const channel = (n) => {
+    const k = (n + h) % 12;
+    return 255 * (l - a * Math.max(-1, Math.min(k - 3, 9 - k, 1)));
+  };
+  return hex([channel(0), channel(8), channel(4), alpha]);
+}
+export function resolveVariables(value, lookup, seen = new Set(), depth = 0) {
+  if (depth > 8 || value.length > 2048) return null;
+  let output = value;
+  for (let replacements = 0; replacements < 32; replacements++) {
+    const start = output.indexOf("var(");
+    if (start < 0) return output;
+    let nesting = 1,
+      end = start + 4,
+      comma = -1;
+    for (; end < output.length && nesting; end++) {
+      if (output[end] === "(") nesting++;
+      else if (output[end] === ")") nesting--;
+      else if (output[end] === "," && nesting === 1 && comma < 0) comma = end;
+    }
+    if (nesting) return null;
+    const name = output.slice(start + 4, comma < 0 ? end - 1 : comma).trim();
+    if (!/^--[\w-]+$/.test(name) || seen.has(name)) return null;
+    const candidate = lookup(name) ?? (comma < 0 ? null : output.slice(comma + 1, end - 1).trim());
+    if (candidate === null || candidate === undefined) return null;
+    const resolved = resolveVariables(candidate, lookup, new Set([...seen, name]), depth + 1);
+    if (resolved === null) return null;
+    output = output.slice(0, start) + resolved + output.slice(end);
+    if (output.length > 2048) return null;
+  }
+  return null;
+}

package/templates/.agents/tools/visual-url/contrast.mjs

@@ -0,0 +1,40 @@
+import { normalizeColor } from "./colors.mjs";
+
+export function contrastRatio(first, second) {
+  const luminance = (value) => {
+    const color = typeof value === "string" ? normalizeColor(value) : null;
+    if (!/^#[\da-f]{6}(?:ff)?$/i.test(color ?? "")) return null;
+    const channels = [1, 3, 5].map((index) => {
+      const channel = Number.parseInt(color.slice(index, index + 2), 16) / 255;
+      return channel <= 0.04045 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4;
+    });
+    return channels[0] * 0.2126 + channels[1] * 0.7152 + channels[2] * 0.0722;
+  };
+  const a = luminance(first),
+    b = luminance(second);
+  return a == null || b == null ? null : (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05);
+}
+
+export function semanticContrast(model) {
+  const pairs = [];
+  for (const [foreground, background, label] of [
+    ["foreground", "background", "Texto / fundo"],
+    ["primary_foreground", "primary", "Texto / botão primário"],
+    ["card_foreground", "card", "Texto / superfície"],
+    ["muted", "background", "Texto secundário / fundo"],
+  ]) {
+    const text = model?.tokens?.colors?.[foreground],
+      surface = model?.tokens?.colors?.[background];
+    const ratio = contrastRatio(text?.value, surface?.value);
+    if (ratio != null)
+      pairs.push({
+        label,
+        foreground: text.value,
+        background: surface.value,
+        ratio,
+        grade: ratio >= 7 ? "AAA" : ratio >= 4.5 ? "AA" : "Fail",
+        evidence: [...new Set([...(text.evidence ?? []), ...(surface.evidence ?? [])])],
+      });
+  }
+  return pairs;
+}