@zaip-ai/cli 6.3.0 → 7.5.0

package/templates/.agents/design/design-system-maker/frontend/shared/frontend.test.mjs

@@ -0,0 +1,357 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  CollectionPager,
+  connect,
+  detail,
+  generate,
+  moveToTrash,
+  reprocess,
+  request,
+  restore,
+} from "./api.js";
+import { extractionCard } from "./components.js";
+import registerScenarios0 from "./frontend-scenarios-2.test.mjs";
+import { jobText } from "./job-view.js";
+import {
+  coverage,
+  entryPath,
+  known,
+  matches,
+  normalizeInputUrl,
+  revisionParam,
+  swatches,
+  viewerPath,
+} from "./model.js";
+import { reportSections } from "./report-view.js";
+import { renderDetail } from "./viewer-detail.js";
+
+const sample = {
+  id: "sample",
+  slug: "sample",
+  name: '<img src=x onerror="alert(1)">',
+  host: "example.test",
+  url: "https://example.test/",
+  status: "partial",
+  revision: 2,
+  theme: null,
+  archetype: null,
+  visual: {
+    inferred_swatches: [
+      { value: "#22d3ee", kind: "inferred" },
+      { value: "url(https://evil.test)", kind: "inferred" },
+    ],
+  },
+  uncertainty: ["Rendered fidelity unknown"],
+  capabilities: null,
+  provenance: null,
+};
+const reply = (body, status = 200) => ({ ok: status < 400, status, json: async () => body });
+class TextNode {
+  childNodes = [];
+  attrs = {};
+  style = {
+    setProperty(name, value) {
+      this[name] = value;
+    },
+    removeProperty(name) {
+      delete this[name];
+    },
+  };
+  classList = { toggle() {}, remove() {} };
+  dataset = {};
+  textContent = "";
+  constructor(tag) {
+    this.tag = tag;
+  }
+  querySelector(tag) {
+    const node = this.childNodes.find((child) => child.tag === tag);
+    if (node)
+      node.remove = () => {
+        this.childNodes = this.childNodes.filter((child) => child !== node);
+      };
+    return node ?? null;
+  }
+  append(...children) {
+    this.childNodes.push(...children);
+  }
+  prepend(...children) {
+    this.childNodes.unshift(...children);
+  }
+  replaceChildren(...children) {
+    this.childNodes = children;
+  }
+  setAttribute(key, value) {
+    this.attrs[key] = value;
+  }
+  addEventListener() {}
+  set innerHTML(_value) {
+    throw new Error("Unsafe active HTML sink used");
+  }
+}
+function nodes(root) {
+  return [root, ...root.childNodes.flatMap(nodes)];
+}
+
+test("Unknowns stay explicit, swatches are bounded hex and search coverage stays local", () => {
+  assert.equal(known(null), "Desconhecido");
+  assert.equal(swatches(sample).length, 1);
+  assert.equal(
+    swatches({ visual: { inferred_swatches: Array(30).fill({ value: "#abc", kind: "inferred" }) } })
+      .length,
+    12,
+  );
+  assert.equal(matches(sample, "#22D3EE"), true);
+  assert.equal(matches(sample, "Desconhecido"), false);
+  assert.match(coverage(100, 101, 0, "missing"), /apenas os itens carregados/);
+  assert.doesNotMatch(coverage(0, null, 0, ""), /coleção completa/);
+  assert.match(coverage(101, 101, 101, ""), /coleção completa/);
+});
+
+test("Navigation and artifact paths cannot become source URLs or paths", () => {
+  assert.equal(viewerPath("sample", 2), "/viewer/?id=sample&revision=2");
+  assert.equal(entryPath("sample", "screenshot", 2), "/api/extracts/sample/screenshot?revision=2");
+  for (const id of ["../secret", "https://evil.test", "sample/preview.html", "<svg>"])
+    assert.throws(() => entryPath(id));
+  assert.throws(() => entryPath("sample", "preview.html"));
+  assert.throws(() => revisionParam("-1"));
+});
+
+test("Collection pagination exposes item 101, serializes clicks, and retries failed pages", async (t) => {
+  const calls = [];
+  t.mock.method(globalThis, "fetch", async (path) => {
+    calls.push(path);
+    if (calls.length === 1)
+      return reply({
+        extracts: Array.from({ length: 100 }, (_, i) => ({ id: `output-${i}` })),
+        total: 101,
+        next_offset: 100,
+      });
+    if (calls.length === 2) return reply({ error: "Temporary error" }, 503);
+    return reply({ extracts: [{ id: "output-100" }], total: 101, next_offset: null });
+  });
+  const pager = new CollectionPager();
+  await Promise.all([pager.more(), pager.more()]);
+  assert.equal(calls.length, 1);
+  await assert.rejects(pager.more(), /Temporary error/);
+  assert.equal(pager.next, 100);
+  await pager.more();
+  await pager.more();
+  assert.equal(pager.items.length, 101);
+  assert.equal(pager.next, null);
+  assert.deepEqual(calls.slice(1), [
+    "/api/extracts?offset=100&limit=100",
+    "/api/extracts?offset=100&limit=100",
+  ]);
+});
+
+test("Generation sends only the whitelisted body and memory nonce; history remains revision-specific", async (t) => {
+  assert.throws(() => generate({ url: "https://example.test" }), /Reconecte/);
+  const calls = [];
+  t.mock.method(globalThis, "fetch", async (path, options) => {
+    calls.push({ path, options });
+    return reply(path === "/api/session" ? { nonce: "memory-only", capabilities: {} } : {});
+  });
+  await connect();
+  await generate({
+    url: "https://example.test",
+    name: "Example",
+    id: "sample",
+    expected_revision: 23,
+    provider: "ignored",
+    fixture_authorization: true,
+  });
+  const post = calls[1];
+  assert.deepEqual(JSON.parse(post.options.body), {
+    url: "https://example.test",
+    name: "Example",
+    id: "sample",
+    expected_revision: 23,
+  });
+  assert.equal(post.options.headers["X-Maker-Nonce"], "memory-only");
+  const signal = new AbortController().signal;
+  await detail("sample", 2, 20, signal);
+  assert.equal(calls[2].path, "/api/extracts/sample?revision=2&history_offset=20&history_limit=20");
+  assert.equal(calls[2].options.signal, signal);
+  await assert.rejects(request("https://evil.test/api/session"), /API local/);
+});
+
+test("Presentation preserves hostile text as text and uses only managed screenshot/export URLs", (t) => {
+  const previous = Object.getOwnPropertyDescriptor(globalThis, "document");
+  Object.defineProperty(globalThis, "document", {
+    configurable: true,
+    value: { createElement: (tag) => new TextNode(tag) },
+  });
+  t.after(() => {
+    if (previous) Object.defineProperty(globalThis, "document", previous);
+    else delete globalThis.document;
+  });
+  const card = extractionCard(sample);
+  assert.ok(nodes(card).some((node) => node.textContent === sample.name));
+  assert.equal(
+    nodes(card).some((node) => node.tag === "img"),
+    false,
+  );
+  const hero = new TextNode("div");
+  const panel = new TextNode("div");
+  const value = {
+    summary: {
+      ...sample,
+      designMdUrl: "https://evil.test",
+      visual: { ...sample.visual, screenshotUrl: "https://evil.test/image" },
+      capabilities: { screenshot_verified: true },
+    },
+    revision: 2,
+    revision_count: 23,
+    revisions: [{ revision: 2, status: "partial", updated_at: "test-time" }],
+    tokens: { candidates: [{ value: "<script>bad()</script>" }], components: [] },
+    designMd: "<script>bad()</script>",
+    error: "Previous process interrupted",
+  };
+  renderDetail(value, { hero, panel, current() {}, viewRevision() {}, historyMore() {} });
+  const all = [...nodes(hero), ...nodes(panel)];
+  assert.equal(
+    all.find((node) => node.tag === "img").src,
+    "/api/extracts/sample/screenshot?revision=2",
+  );
+  assert.equal(
+    all.some((node) => node.tag === "pre"),
+    false,
+  );
+  assert.ok(
+    all.some((node) => node.href === "/api/extracts/sample/design?revision=2&format=compact"),
+  );
+  assert.ok(all.some((node) => node.textContent.includes("interrupted")));
+  assert.ok(all.some((node) => node.textContent === "Voltar à revisão atual"));
+  assert.ok(all.filter((node) => node.href).every((node) => node.href.startsWith("/")));
+});
+
+test("HTTPS normalization is explicit and never converts credentials or unsafe protocols", () => {
+  assert.deepEqual(normalizeInputUrl("example.test/path?v=2"), {
+    url: "https://example.test/path?v=2",
+    addedHttps: true,
+  });
+  assert.equal(normalizeInputUrl("https://example.test/path?v=2").addedHttps, false);
+  for (const value of [
+    "",
+    "javascript:alert(1)",
+    "file:///private",
+    "https://name:secret@example.test",
+  ])
+    assert.throws(() => normalizeInputUrl(value));
+});
+
+test("Reprocess keeps saved URL server-side; trash/restore send both exact revision guards and nonce", async (t) => {
+  const calls = [];
+  t.mock.method(globalThis, "fetch", async (path, options) => {
+    calls.push({ path, options });
+    return reply(path === "/api/session" ? { nonce: "new-memory-session", capabilities: {} } : {});
+  });
+  await connect();
+  await reprocess("sample", 23);
+  await moveToTrash({ id: "sample", revision: 23, trash_revision: 4 });
+  await restore({ id: "sample", revision: 23, trash_revision: 5 });
+  assert.deepEqual(JSON.parse(calls[1].options.body), { expected_revision: 23 });
+  assert.equal(calls[1].path, "/api/extracts/sample/reprocess");
+  assert.equal(calls[2].options.method, "DELETE");
+  assert.deepEqual(JSON.parse(calls[2].options.body), {
+    expected_revision: 23,
+    expected_trash_revision: 4,
+  });
+  assert.equal(calls[3].path, "/api/trash/sample/restore");
+  assert.deepEqual(JSON.parse(calls[3].options.body), {
+    expected_revision: 23,
+    expected_trash_revision: 5,
+  });
+  for (const call of calls.slice(1))
+    assert.equal(call.options.headers["X-Maker-Nonce"], "new-memory-session");
+  const pager = new CollectionPager("trash");
+  t.mock.method(globalThis, "fetch", async (path) => {
+    assert.equal(path, "/api/trash?offset=0&limit=100");
+    return reply({ extracts: [], total: 0, next_offset: null });
+  });
+  await pager.more();
+  assert.equal(pager.next, null);
+});
+
+test("Full report retains all colors, typed declarations, HTML count and persisted formula without active source markup", (t) => {
+  const previous = Object.getOwnPropertyDescriptor(globalThis, "document");
+  Object.defineProperty(globalThis, "document", {
+    configurable: true,
+    value: { createElement: (tag) => new TextNode(tag) },
+  });
+  t.after(() => {
+    if (previous) Object.defineProperty(globalThis, "document", previous);
+    else delete globalThis.document;
+  });
+  const provenance = {
+    url: "https://example.test/style.css",
+    selector: ":root",
+    source_hash: "a".repeat(64),
+  };
+  const row = {
+    value: "Typeface",
+    declared_value: "<script>hostile()</script>",
+    property: "font-family",
+    kind: "inferred",
+    occurrences: 2,
+    evidence: ["css-1"],
+    provenance,
+  };
+  const colors = Array.from({ length: 30 }, (_, i) => ({
+    ...row,
+    property: "color",
+    value: `#${(i + 1).toString(16).padStart(6, "0")}`,
+  }));
+  const report = {
+    status: "measured-evidence",
+    method_version: "css-evidence-v1",
+    score: 0,
+    score_kind: "extraction-evidence-coverage",
+    sampling: { sampled: 0, total: 0, truncated: 0 },
+    metrics: [
+      {
+        id: "category-coverage",
+        numerator: 0,
+        denominator: 0,
+        ratio: 0,
+        weight: 35,
+        explanation: "Unavailable denominator",
+      },
+    ],
+    colors,
+    typography: [row],
+    spacing: [],
+    radii: [],
+    element_count: 99,
+    components: [],
+    resources: [],
+    gaps: ["Zero denominator"],
+  };
+  const all = reportSections(report, sample).flatMap(nodes);
+  assert.equal(all.filter((node) => node.dataset.reportColor).length, 30);
+  assert.ok(all.some((node) => node.textContent === colors[29].value));
+  assert.ok(all.some((node) => node.textContent === "99 ELEMENTOS HTML"));
+  assert.ok(all.some((node) => node.textContent.includes("0 / 0")));
+  assert.ok(all.some((node) => node.textContent === row.declared_value));
+  assert.ok(all.some((node) => node.textContent === "font-family"));
+  assert.ok(all.some((node) => node.href === "/api/extracts/sample/report-markdown?revision=2"));
+  assert.equal(
+    all.some((node) => node.tag === "script"),
+    false,
+  );
+});
+
+test("Terminal job status is honored while inconsistent historical phase/time stay explicit", () => {
+  assert.equal(jobText({ status: "completed", phase: "completed" }), "Relatório gerado");
+  assert.match(
+    jobText({ status: "completed", phase: "commit" }),
+    /^Relatório gerado · Última fase registrada:/,
+  );
+  assert.match(
+    jobText({ status: "failed", phase: "fetch-html", error: "Interrupted" }),
+    /^Extração falhou.*Interrupted/,
+  );
+});
+
+registerScenarios0();

package/templates/.agents/design/design-system-maker/frontend/shared/job-view.js

@@ -0,0 +1,81 @@
+import { el } from "./components.js";
+import { extractionState } from "./extraction-state.js";
+import { samplingLabel } from "./model.js";
+
+export const phaseLabels = {
+  queued: "Na fila",
+  "fetch-html": "Coletando HTML",
+  "parse-css": "Analisando CSS",
+  "fetch-css": "Coletando folhas CSS",
+  "browser-open": "Abrindo navegador local",
+  "browser-wait": "Aguardando sua ação no navegador",
+  "browser-capture": "Capturando página no navegador",
+  "build-report": "Gerando relatório",
+  "verify-artifacts": "Verificando artefatos",
+  commit: "Persistindo revisão",
+  completed: "Relatório gerado",
+  failed: "Extração falhou",
+};
+export function durationText(ms) {
+  return Number.isFinite(ms)
+    ? `${(ms / 1000).toLocaleString("pt-BR", { maximumFractionDigits: 2 })} s`
+    : "Ainda não registrado";
+}
+export function jobText(value) {
+  if (value.status === "failed" && value.failure?.kind === "cancelled") return "Extração cancelada";
+  if (value.status === "failed" && extractionState(value).httpStatus === 403)
+    return `${extractionState(value).title} · ${value.failure?.message ?? value.error ?? "Origem recusou o coletor"}`;
+  const terminal = ["completed", "failed"].includes(value.status);
+  const label = terminal
+    ? phaseLabels[value.status]
+    : (phaseLabels[value.phase] ?? value.phase ?? value.status);
+  const phaseMismatch =
+    terminal && value.phase !== value.status
+      ? ` · Última fase registrada: ${phaseLabels[value.phase] ?? value.phase ?? "não disponível"}`
+      : "";
+  return `${label}${phaseMismatch}${value.error ? ` · Falha / interrupção: ${value.error}` : ""}`;
+}
+export function renderJobProgress(value, target, log) {
+  target.replaceChildren();
+  const line = el(
+    "p",
+    "job-timing",
+    `Duração observada: ${durationText(value.duration_ms)} · Recursos recebidos: ${value.progress?.resources_received ?? "não registrado"}`,
+  );
+  target.append(line);
+  if (value.browser) {
+    if (value.browser.action) target.append(el("p", "", value.browser.action));
+    if (value.browser.deadline_at && ["opening", "waiting-human"].includes(value.browser.state))
+      target.append(el("p", "meta", `Espera limitada até: ${value.browser.deadline_at}`));
+    if (value.browser.state === "unavailable")
+      target.append(
+        el(
+          "p",
+          "help",
+          "Navegador local indisponível nesta tentativa. Confira a falha registrada abaixo.",
+        ),
+      );
+  }
+  if (value.started_at) target.append(el("p", "meta", `Início: ${value.started_at}`));
+  if (value.completed_at) target.append(el("p", "meta", `Fim: ${value.completed_at}`));
+  else if (["completed", "failed"].includes(value.status))
+    target.append(el("p", "meta", "Horário de término não registrado neste job."));
+  if (value.status === "completed")
+    target.append(
+      el("p", "", samplingLabel(value.summary?.sampling)),
+      el(
+        "p",
+        "help",
+        "A operação terminou. A cobertura CSS e os limites de navegador permanecem separados do resultado do job.",
+      ),
+    );
+  const events = value.events ?? [];
+  log.textContent = events.length
+    ? events
+        .map(
+          (event) =>
+            `${event.at} · ${phaseLabels[event.phase] ?? event.phase} · ${event.resources_received} recursos`,
+        )
+        .join("\n")
+    : (value.log ?? []).join("\n") || "Nenhum evento recebido ainda.";
+}

package/templates/.agents/design/design-system-maker/frontend/shared/model-hydration.js

@@ -0,0 +1,26 @@
+import { detail } from "./api.js";
+
+const cache = new Map();
+export async function hydrateVisualModels(items) {
+  const pending = items
+    .slice(0, 100)
+    .filter((item) => !item.visual_model && !["failed", "collecting"].includes(item.status));
+  let index = 0;
+  await Promise.all(
+    Array.from({ length: Math.min(3, pending.length) }, async () => {
+      while (index < pending.length) {
+        const item = pending[index++];
+        const key = `${item.id}:${item.revision}`;
+        if (!cache.has(key))
+          cache.set(
+            key,
+            detail(item.id, item.revision)
+              .then((value) => value.visual_model ?? value.summary?.visual_model ?? null)
+              .catch(() => null),
+          );
+        const model = await cache.get(key);
+        if (model) item.visual_model = model;
+      }
+    }),
+  );
+}

package/templates/.agents/design/design-system-maker/frontend/shared/model.js

@@ -0,0 +1,103 @@
+import { paletteEvidence } from "./palette-evidence.js";
+
+export const labels = {
+  collecting: "Coletando",
+  partial: "Coleta concluída",
+  ready: "Coleta concluída",
+  failed: "Falha na coleta",
+  queued: "Na fila",
+  running: "Em execução",
+  completed: "Relatório gerado",
+};
+export function statusLabel(status) {
+  return labels[status] ?? "Desconhecido";
+}
+export function known(value, fallback = "Desconhecido") {
+  return value == null ? fallback : String(value);
+}
+export function swatches(summary) {
+  return (summary?.visual?.inferred_swatches ?? [])
+    .slice(0, 12)
+    .filter(
+      (item) =>
+        item.kind === "inferred" &&
+        /^#(?:[a-f\d]{3}|[a-f\d]{4}|[a-f\d]{6}|[a-f\d]{8})$/i.test(item.value),
+    );
+}
+export function matches(summary, query) {
+  const values = [
+    summary.design_code,
+    summary.design_code ? `#${summary.design_code}` : null,
+    summary.name,
+    summary.slug,
+    summary.host,
+    summary.theme,
+    summary.archetype,
+    ...swatches(summary).map((item) => item.value),
+  ];
+  return values
+    .filter((value) => value != null)
+    .join(" ")
+    .toLocaleLowerCase("pt-BR")
+    .includes(query.trim().toLocaleLowerCase("pt-BR"));
+}
+export function cardPalette(summary, limit = 8) {
+  return paletteEvidence(summary).colors.slice(0, limit);
+}
+export function coverage(loaded, total, filtered, query) {
+  const scope =
+    total == null
+      ? `${loaded} carregados · total ainda desconhecido`
+      : `${loaded} de ${total} carregados`;
+  return query.trim()
+    ? `${filtered} encontrados nos ${scope}. A busca cobre apenas os itens carregados.`
+    : `${scope}${total == null ? "" : total > loaded ? " · carregue mais para ampliar a busca" : " · coleção completa"}`;
+}
+export function entryPath(id, artifact = "", revision = null) {
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$/.test(id))
+    throw new Error("Identificador de output inválido");
+  if (
+    !["", "design", "proposal", "screenshot", "favicon", "report", "report-markdown"].includes(
+      artifact,
+    )
+  )
+    throw new Error("Artefato inválido");
+  if (revision != null && (!Number.isInteger(revision) || revision < 1))
+    throw new Error("Revisão inválida");
+  return `/api/extracts/${encodeURIComponent(id)}${artifact ? `/${artifact}` : ""}${revision == null ? "" : `?revision=${revision}`}`;
+}
+export function normalizeInputUrl(value) {
+  const raw = value.trim();
+  if (!raw) throw new Error("Informe uma URL pública.");
+  const suppliedProtocol = /^[a-z][a-z\d+.-]*:/i.test(raw);
+  const normalized = new URL(suppliedProtocol ? raw : `https://${raw.replace(/^\/\//, "")}`);
+  if (
+    !["http:", "https:"].includes(normalized.protocol) ||
+    normalized.username ||
+    normalized.password
+  )
+    throw new Error("Informe uma URL HTTP/HTTPS sem credenciais.");
+  return { url: normalized.href, addedHttps: !suppliedProtocol };
+}
+export function samplingLabel(sampling) {
+  return sampling
+    ? `CSS amostrado: ${sampling.sampled} de ${sampling.total} declarações; ${sampling.truncated} omitidas.`
+    : "Amostragem não registrada nesta revisão.";
+}
+export function scoreLabel(report) {
+  if (report?.status === "failed") return "Coleta falhou · sem relatório medido";
+  if (report?.status === "collecting") return "Aguardando conclusão da extração";
+  return report?.score_kind === "extraction-evidence-coverage" && Number.isFinite(report.score)
+    ? `Cobertura da extração: ${report.score}/100`
+    : "Cobertura não registrada nesta revisão";
+}
+export function viewerPath(id, revision = null) {
+  entryPath(id, "", revision);
+  return `/viewer/?id=${encodeURIComponent(id)}${revision == null ? "" : `&revision=${revision}`}`;
+}
+export function revisionParam(value) {
+  if (value == null) return null;
+  const revision = Number(value);
+  if (!Number.isInteger(revision) || revision < 1) throw new Error("Revisão inválida na navegação");
+  return revision;
+}

package/templates/.agents/design/design-system-maker/frontend/shared/palette-evidence.js

@@ -0,0 +1,106 @@
+import { safeColor } from "./visual-model.js";
+
+export const colorRoleLabels = {
+  background: "Fundo",
+  foreground: "Texto",
+  primary: "Primária",
+  primary_foreground: "Texto primário",
+  card: "Superfície",
+  card_foreground: "Texto da superfície",
+  accent: "Destaque",
+  secondary: "Secundária",
+  muted: "Texto secundário",
+  border: "Borda",
+};
+export const colorSourceLabels = {
+  observed: "Observada na captura",
+  declared: "Candidata CSS",
+  fallback: "Fallback local",
+};
+export const colorContextLabels = {
+  action: "Ação",
+  "gradient-text": "Texto em gradiente",
+  pseudo: "Pseudoelemento",
+  "svg-paint": "SVG",
+  footer: "Rodapé",
+  surface: "Superfície",
+  text: "Texto",
+};
+export function paletteEvidence(value) {
+  const raw = value?.visual_model ?? value?.summary?.visual_model;
+  const summary = value?.summary ?? value;
+  const observed = [],
+    declared = [];
+  const add = (row, source, label = null) => {
+    const color = safeColor(row?.value);
+    if (!color || /^#[\da-f]{6}00$/i.test(color) || !["observed", "declared"].includes(source))
+      return;
+    const group = source === "observed" ? observed : declared;
+    const existing = group.find((item) => item.value.toLowerCase() === color.toLowerCase());
+    if (existing) {
+      if (label && !existing.labels.includes(label)) existing.labels.push(label);
+      if (
+        existing.contexts.length < 192 &&
+        !existing.contexts.some(
+          (context) =>
+            context.property === row.property &&
+            context.element_id === row.element_id &&
+            context.provenance?.selector === row.provenance?.selector &&
+            context.provenance?.url === row.provenance?.url &&
+            context.reason === row.reason,
+        )
+      )
+        existing.contexts.push({ ...row, source });
+      return;
+    }
+    group.push({
+      ...row,
+      value: color,
+      kind: "inferred",
+      source,
+      labels: label ? [label] : [],
+      contexts: [{ ...row, source }],
+    });
+  };
+  const tokens = Object.entries(raw?.tokens?.colors ?? {});
+  const semanticSource = raw?.theme?.basis === "browser-computed-style" ? "observed" : "declared";
+  for (const [name, row] of tokens.filter(([name]) => ["primary", "accent"].includes(name)))
+    if (row?.kind === "inferred") add(row, semanticSource, colorRoleLabels[name] ?? name);
+  for (const row of (raw?.color_candidates ?? []).slice(0, 32))
+    if (row?.kind == null || row.kind === "inferred") add(row, row.source);
+  for (const [name, row] of tokens)
+    if (row?.kind === "inferred") add(row, semanticSource, colorRoleLabels[name] ?? name);
+  for (const row of (value?.report?.colors ?? []).slice(0, 128)) add(row, "declared");
+  for (const row of (summary?.visual?.inferred_swatches ?? []).slice(0, 32))
+    if (row?.kind === "inferred") add(row, "declared");
+  // A CSS candidate already seen in the capture is represented with the stronger evidence.
+  for (const row of declared) {
+    const captured = observed.find((item) => item.value.toLowerCase() === row.value.toLowerCase());
+    if (captured) captured.contexts.push(...row.contexts);
+  }
+  const cssOnly = declared.filter(
+    (row) => !observed.some((item) => item.value.toLowerCase() === row.value.toLowerCase()),
+  );
+  const missingRoles = ["primary", "accent"].filter(
+    (name) =>
+      raw?.tokens?.colors?.[name]?.kind !== "inferred" || !safeColor(raw.tokens.colors[name].value),
+  );
+  return {
+    observed,
+    declared: cssOnly,
+    colors: [...observed, ...cssOnly],
+    missingRoles,
+    coverage: raw?.coverage,
+  };
+}
+const count = (value) => (Number.isInteger(value) && value >= 0 ? value : "não registrado");
+export function captureCoverageLabel(value) {
+  const coverage = paletteEvidence(value).coverage;
+  const source = value?.source ?? value?.summary?.source ?? value?.proposal?.source;
+  if (source && source.type !== "url")
+    return "Fonte local analisada; sem captura renderizada. Valores e papéis são inferidos; arquivos, revisão e hashes permanecem na proveniência.";
+  if (!coverage || coverage.status === "legacy-unknown")
+    return "Cobertura da captura não registrada nesta revisão. Cores observadas não comprovam uma paleta completa.";
+  const status = coverage.status === "incomplete" ? "Captura incompleta" : "Captura por amostragem";
+  return `${status}: ${count(coverage.sampled)} amostras; ${count(coverage.scanned)} elementos examinados; ${count(coverage.omitted)} omitidos. Não comprova uma paleta completa.`;
+}