raptor-aios 0.13.2 → 0.14.1

package/CHANGELOG.md

@@ -5,6 +5,44 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.14.1] - 2026-06-21
+
+### Fixed
+
+- **Correções do code-review xhigh do épico de fidelidade visual.** `gate.design.fidelity`
+  resiliente a race (`readFileSync`/`statSync` não crasham mais) e com contenção de
+  evidência à prova de symlink (`realpathSync`); duplicata de screenshot comparada por
+  path resolvido. Parser do scorecard mais estrito: divergência com enum inválido e
+  região sem `id` são **descartadas** (em vez de retornar objeto com tipo inválido).
+  `token-diff` normaliza hex de 4 dígitos (`#rgba`). Scripts `hex-scan`/`screenshot.sh`
+  validam argumentos (sem crash de `shift`; resolução do core com mensagem clara). Doc:
+  diagrama Mermaid corrigido (linter havia transformado arestas em tabela).
+
+## [0.14.0] - 2026-06-21
+
+### Added
+
+- **Loop de fidelidade visual (Figma → React Native) — nota por micro-região.**
+  Transforma "a tela tem os tokens" em "a tela replica o Figma". Cada tela ganha
+  uma seção `## Anatomy` em `design/screens/<slug>.md` (regiões→elementos amarrados
+  a token) — o **contrato** de fidelidade. Um agente `design-fidelity` (read-only,
+  adversarial) pontua cada micro-região 60–100 (nota = a dimensão mais fraca; mínimo
+  default 95) e escreve `design/visual-review/<slug>.fidelity.json` (schema
+  `raptor.fidelity/v1`). Peças:
+  - `gate.design.fidelity` (estático, `required`): lê o scorecard e trava o
+    `raptor verify` se alguma região < mínimo, hex hardcoded, screenshot de evidência
+    ausente/duplicada, ou divergência `design-decision` sem aprovação — nunca roda o
+    app (como os gates M7 leem `impl-log.md`). Piso de threshold: o scorecard pode
+    endurecer, nunca afrouxar.
+  - `raptor verify fidelity [feature]`: lente read-only que pontua os scorecards.
+  - `raptor design fidelity <feature>`: driver do loop — reporta a fidelidade e emite
+    o prompt do scorer; o loop é dirigido pelo agente iterando até convergir.
+  - Backbone determinístico (anti-gaming, medido pelo Raptor): `hex-scan` (hex +
+    `rgb()/rgba()/hsl()` + cores nomeadas em prop de cor), `token-diff` (drift
+    Figma×impl) e `scripts/app/screenshot.sh` (captura de evidência iOS/Android).
+  - Evento de auditoria `design.fidelity.scored` registra cada ciclo.
+  - Doc: [docs/visual-fidelity-loop.md](docs/visual-fidelity-loop.md).
+
 ## [0.13.2] - 2026-06-19
 
 ### Fixed

package/README.md

@@ -7,8 +7,8 @@
 [![npm](https://img.shields.io/npm/v/raptor-aios?color=ef4444&label=raptor-aios&logo=npm)](https://www.npmjs.com/package/raptor-aios)
 [![node](https://img.shields.io/badge/node-%E2%89%A5%2020-3c873a?logo=node.js&logoColor=white)](https://nodejs.org)
 [![platform](https://img.shields.io/badge/target-React%20Native-61dafb?logo=react&logoColor=black)](https://reactnative.dev)
-[![tests](https://img.shields.io/badge/tests-1374%20passing-22c55e)](#️-desenvolvimento-local)
-[![version](https://img.shields.io/badge/version-0.13.0-ef4444)](CHANGELOG.md)
+[![tests](https://img.shields.io/badge/tests-1481%20passing-22c55e)](#️-desenvolvimento-local)
+[![version](https://img.shields.io/badge/version-0.14.0-ef4444)](CHANGELOG.md)
 [![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
 </div>
@@ -40,6 +40,7 @@ raptor new login-biometrico -d "Permitir login com Face ID / digital"
 - [📱 Fluxo correto com React Native](#-fluxo-correto-com-react-native)
 - [🛡️ Gates: o que bloqueia o quê](#️-gates-o-que-bloqueia-o-quê)
 - [🔬 A ponta de verificação (`verify`)](#-a-ponta-de-verificação-verify)
+- [🎯 Fidelidade visual (Figma → React Native)](#-fidelidade-visual-figma--react-native)
 - [🧰 Capacidades do Raptor](#-capacidades-do-raptor)
 - [📖 Referência de comandos CLI](#-referência-de-comandos-cli)
 - [🗂️ Estrutura criada no projeto](#️-estrutura-criada-no-projeto)
@@ -61,6 +62,7 @@ O Raptor leva o SDD a sério para o mundo mobile, adicionando o que falta para u
 | 📜 **Trilha de auditoria**              | Cada passo emite eventos em `audit.jsonl`, validáveis contra um JSON Schema canônico.                                                                                   |
 | 🔗 **Rastreabilidade código↔spec (M7)** | Cada artefato de código aponta para os critérios de aceitação que satisfaz, com evidência pareada (*code + test*).                                                      |
 | 🔬 **Verificação real**                 | `verify a11y/perf/stores/os-matrix` medem o app de verdade e comparam com o que a spec/plan declararam.                                                                 |
+| 🎯 **Fidelidade visual (Figma→RN)**      | Decompõe a tela em **anatomia**, dá **nota por micro-região** (mín. 95) e **trava o merge** via `gate.design.fidelity` até a implementação replicar o Figma. Guia: [docs/visual-fidelity-loop.md](docs/visual-fidelity-loop.md). |
 | 🤖 **Agnóstico de agente**              | Materializa slash commands para Claude Code, Cursor, Copilot, Codex, Gemini e Antigravity.                                                                              |
 | ✨ **Specs sem pontas soltas**          | A spec nasce preenchida (defaults informados), com teto de 3 dúvidas de alto impacto, e um `/raptor-clarify` investigativo que caça lacunas antes do planejamento.      |
 | 🌿 **Branch & commit sob controle**     | Cada feature ganha sua branch (`feat/001-…`) automaticamente, e hooks *warn-only* alertam sobre arquivos sensíveis ou fora do contexto — sem travar seu fluxo git.      |
@@ -454,12 +456,48 @@ Declarar não é cumprir. O Raptor **mede** e compara com o declarado:
 | `raptor verify stores <feat>`       | M1        | Compara `spec.stores` com `AndroidManifest.xml`/`Info.plist`; `--fix` adiciona faltantes |
 | `raptor verify os-matrix <feat>`    | M4        | Compara `plan.os_matrix` com Gradle/Podfile; `--fix` alinha                              |
 | `raptor verify architecture <feat>` | M8 (exp.) | Checagem estática de arquitetura limpa sobre o grafo de imports                          |
+| `raptor verify fidelity <feat>`     | M3        | Pontua os scorecards de fidelidade visual por micro-região (60–100, mín. 95) vs Figma     |
 | `raptor verify <feat>`              | —         | Roda **todos** os gates da feature de uma vez                                            |
 
 > 🧪 **Exemplo real:** `verify stores` detectou que `ACCESS_FINE_LOCATION` e `POST_NOTIFICATIONS` estavam na spec mas **ausentes** do `AndroidManifest.xml` — e `--fix` corrigiu. `verify perf` mediu TTFI mediano de **957ms** contra orçamento de 2000ms.
 
 ---
 
+## 🎯 Fidelidade visual (Figma → React Native)
+
+> **Novo na v0.14.0.** Transforma _"a tela tem os tokens"_ em _"a tela **replica** o Figma"_.
+
+<p align="center"><img src="docs/assets/visual-fidelity-loop.svg" alt="Visual Fidelity Loop — anatomia, loop de fidelidade e gate" width="760"></p>
+
+Capturar o design não garante fidelidade. O Raptor decompõe cada tela em **anatomia**
+(regiões → elementos amarrados a token), pontua cada **micro-região de 60 a 100** (mínimo
+**95**) e **trava o `verify`** via `gate.design.fidelity` até a implementação replicar o
+protótipo — com um **backbone determinístico** (hex / `rgb()` / token + screenshots de
+evidência) que o Raptor mede sozinho, então o agente **não consegue inflar a nota**.
+
+```bash
+raptor design fidelity 001-home   # driver do loop: reporta a fidelidade + emite o prompt do scorer
+raptor verify fidelity 001-home   # lente read-only: nota por micro-região (60–100, mín. 95)
+raptor verify 001-home            # gate.design.fidelity (estático) trava se alguma região < mínimo
+```
+
+```
+=== fidelity: 001-home ===
+  ✅ home-unavailable [unavailable] header: 97/95
+  ✅ home-unavailable [unavailable] earnings-card: 99/95
+  ✅ home-unavailable [unavailable] status-component: 98/95
+  Summary: 5 region(s) scored — 5 pass, 0 fail.
+```
+
+O agente `design-fidelity` (read-only, _"na dúvida, reprova"_) é acionado **depois do
+implement**: extrai os valores reais do Figma, captura o app rodando, pontua cada
+micro-região e escreve `design/visual-review/<slug>.fidelity.json`. O gate **estático** lê
+esse scorecard (como os gates M7 leem `impl-log.md`) e nunca roda o app.
+
+> 📖 **Guia completo** — use cases, workflow, exemplos e diagramas: [docs/visual-fidelity-loop.md](docs/visual-fidelity-loop.md).
+
+---
+
 ## 🧰 Capacidades do Raptor
 
 |       Capacidade        |                                           Para que serve                                           |                         Comandos                         |
@@ -472,7 +510,7 @@ Declarar não é cumprir. O Raptor **mede** e compara com o declarado:
 | 🪝 **Hooks**             | Scripts disparados em **34 pontos** do ciclo (`before_*`/`after_*` de 17 comandos).                | `raptor hook list · run`                                 |
 | 📦 **Extensões**         | Pacotes self-contained (templates/gates/hooks/workflows).                                          | `raptor extension add · list · info · remove`            |
 | 🎟️ **Jira**             | Puxa issues do Jira (somente leitura) para semear specs.                                           | `raptor jira connect · status · pull · disconnect`       |
-| 🎨 **Figma / Design**    | Captura **determinística** de tokens/telas/assets/fontes do Figma (provider `figma-rest` + PAT) e semeia `design/`. | `raptor design connect · status · pull · sync · disconnect` |
+| 🎨 **Figma / Design**    | Captura **determinística** de tokens/telas/assets/fontes do Figma (provider `figma-rest` + PAT) e semeia `design/`; **loop de fidelidade visual** com nota por micro-região. | `raptor design connect · status · pull · sync · fidelity · disconnect` |
 | 📜 **Auditoria & trace** | Consulta a trilha de eventos e a rastreabilidade.                                                  | `raptor audit query · show` · `raptor trace`             |
 
 ### 🎟️ Integração com Jira
@@ -497,6 +535,8 @@ raptor design sync home             # re-captura idempotente (nunca sobrescreve
 
 O provider **`figma-rest`** usa a REST API da Figma com um PAT (`${FIGMA_TOKEN}` no `raptor.yml`), é determinístico e roda em CI. A captura gera `design/tokens.json` (colors/typography/spacing/radii), `design/screens/<slug>.md` (frames de topo) e `design/assets-manifest.json` (assets baixados com SHA-256, guarda anti-SSRF). Quando há captura real, os prompts fazem o **flip REDISTRIBUIR**: o agente passa a *refinar e redistribuir* os artefatos em disco em vez de "olhar o Figma" — cobrado pelo `gate.design.ready`.
 
+> 🎯 **Fidelidade visual:** depois do `implement`, um loop garante que a tela **replica** o Figma (anatomia + nota por micro-região + `gate.design.fidelity`) — veja [🎯 Fidelidade visual (Figma → React Native)](#-fidelidade-visual-figma--react-native).
+
 > 📖 Detalhes, providers e limitações: [docs/design-figma-sync.md](docs/design-figma-sync.md) e [docs/design-gate.md](docs/design-gate.md).
 
 ---

package/dist/_core/dist/agents/prompt-builder.js

@@ -37,12 +37,68 @@ const PHASE_MAP = {
             "   artefatos semeados (`design/tokens.json` populado, `design/screens/*.md`), REFINE e",
             "   redistribua esses artefatos em vez de re-buscar; senão use o Figma MCP para ENXERGAR o",
             "   design. Derive telas/fluxos/critérios das telas reais e refine (ou crie) `design/screens/<nome>.md`.",
+            "9. Para cada tela, AUTORE a anatomia: uma seção `## Anatomy` em `design/screens/<nome>.md` decompondo",
+            "   a tela em regiões→elementos, cada valor amarrado a token (`{color.*}`/`{space.*}`/`{radius.*}`/`{type.*}`).",
+            "   Gramática: `- region: <id> — <notas>` e itens indentados `- <elemento> — <spec>`. É o CONTRATO de",
+            "   fidelidade pontuado pós-implement por `raptor design fidelity` + `gate.design.fidelity`.",
             "",
             "### Feature a especificar:",
             "",
             "{{DESCRIPTION}}",
         ].join("\n"),
     },
+    "design-fidelity": {
+        command: "design-fidelity",
+        inputs: [
+            { filename: "spec.md", role: "spec" },
+            { filename: "constitution.md", role: "constitution" },
+        ],
+        expectedOutput: "specs/{feature}/design/visual-review/*.fidelity.json",
+        outputSchema: "raptor.fidelity/v1",
+        scope: {
+            read: ["specs/{feature}/**", "src/**", "assets/**", ".raptor/constitution.md"],
+            write: ["specs/{feature}/design/visual-review/**"],
+            forbidden: [
+                "src/**",
+                ".raptor/audit.jsonl",
+                "specs/{feature}/spec.md",
+                "specs/{feature}/plan.md",
+                "specs/{feature}/tasks.md",
+            ],
+        },
+        bodyTemplate: [
+            "## Instrução",
+            "",
+            "Você é o agente de FIDELIDADE VISUAL do Raptor — read-only no código. Seu papel é",
+            "PONTUAR a fidelidade da tela implementada contra o Figma, com rigor adversarial:",
+            "na dúvida, REPROVE. Você produz EVIDÊNCIA; não edita `src/` enquanto pontua",
+            "(a correção é etapa separada do loop).",
+            "",
+            "Para CADA tela que declara `## Anatomy` (em `design/screens/<tela>.md`) e cada estado",
+            "relevante (disponível, loading, erro, vazio…):",
+            "1. Leia a ANATOMIA da tela (seção `## Anatomy`): regiões→elementos→tokens.",
+            "2. Extraia do Figma os valores REAIS do nó com `get_design_context` / `get_variable_defs` /",
+            "   `get_screenshot`. REGRA DE OURO: o nó vence a percepção — nunca chute px/cor/raio/peso.",
+            "3. Capture o app RODANDO (evidência, não invente): rode",
+            "   `scripts/app/screenshot.sh design/visual-review/_shots/<tela>.<estado>.app.png` e salve o",
+            "   screenshot do Figma como `…<estado>.figma.png`.",
+            "4. Compare Figma×app POR MICRO-REGIÃO e pontue 60–100 em cada dimensão",
+            "   (layout, spacing, color, typography, dimensions, icon, states). A nota da região = a",
+            "   dimensão MAIS FRACA (o elo). Mínimo de aprovação = 95 (ou o threshold do preset).",
+            "5. Backbone determinístico (não falsifique): rode `node scripts/review/hex-scan.mjs src --json`",
+            "   e preencha `deterministic.hex_hardcoded` com o resultado REAL; rode",
+            "   `node scripts/review/diff-tokens.mjs <figma-tokens.json> design/tokens.json --json` p/ o drift.",
+            "6. Registre cada divergência `{ dimension, figma, rn, fix, severity, status }`. `status`:",
+            "   `resolved` (corrigida), `open` (ainda falha) ou `design-decision` (desvio semântico —",
+            "   troca de ícone/cor/copy — que EXIGE aprovação humana antes de passar o gate).",
+            "7. Escreva `design/visual-review/<tela>.fidelity.json` (schema `raptor.fidelity/v1`):",
+            "   `states[].regions[]` com `score`+`dimensions`+`divergences`, `screenshot_figma`/`screenshot_app`,",
+            "   `deterministic`, e `learnings[]` (aprendizados reutilizáveis). TODA região da anatomia deve",
+            "   ser pontuada.",
+            "8. NÃO edite `src/` aqui. `gate.design.fidelity` trava o `raptor verify` até toda região ≥ mínimo,",
+            "   sem hex hardcoded e com screenshots de evidência presentes em disco.",
+        ].join("\n"),
+    },
     plan: {
         command: "plan",
         inputs: [

package/dist/_core/dist/audit/schema.js

@@ -65,6 +65,7 @@ export const auditEventSchema = {
                 "jira.issues.created",
                 "design.imported",
                 "design.synced",
+                "design.fidelity.scored",
                 "branch.created",
                 "branch.switched",
                 "commit.guarded",

package/dist/_core/dist/design/anatomy.js

@@ -0,0 +1,85 @@
+import { slugify } from "./slug.js";
+const LIST_ITEM = /^(\s*)[-*]\s+(.*\S)\s*$/;
+const REGION_PREFIX = /^(?:region|regi[aã]o)\s*:\s*(.+)$/i;
+const DELIM = /\s+[—–-]\s+|\s*:\s+/;
+function splitHead(text) {
+    const m = DELIM.exec(text);
+    if (!m)
+        return { head: text.trim() };
+    if (m.index <= 0) {
+        return { head: "", tail: text.slice(m.index + m[0].length).trim() || undefined };
+    }
+    return {
+        head: text.slice(0, m.index).trim(),
+        tail: text.slice(m.index + m[0].length).trim() || undefined,
+    };
+}
+function sliceAnatomy(content) {
+    const lines = content.split(/\r?\n/);
+    let start = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (/^##\s+anatomy\b/i.test(lines[i].trim())) {
+            start = i + 1;
+            break;
+        }
+    }
+    if (start === -1)
+        return null;
+    const out = [];
+    for (let i = start; i < lines.length; i++) {
+        if (/^#{1,6}\s+\S/.test(lines[i]))
+            break;
+        out.push(lines[i]);
+    }
+    return out;
+}
+export function parseAnatomy(content) {
+    const body = sliceAnatomy(content);
+    if (body === null) {
+        return { regions: [], problems: ["no `## Anatomy` section found"] };
+    }
+    const regions = [];
+    const problems = [];
+    const seenIds = new Set();
+    let current = null;
+    let inFence = false;
+    for (const line of body) {
+        if (/^\s*(?:```|~~~)/.test(line)) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            continue;
+        const item = LIST_ITEM.exec(line);
+        if (!item)
+            continue;
+        const text = item[2].trim();
+        const region = REGION_PREFIX.exec(text);
+        if (region) {
+            const { head, tail } = splitHead(region[1].trim());
+            const id = slugify(head);
+            if (!id) {
+                problems.push(`region with empty label: "${text}"`);
+                current = null;
+                continue;
+            }
+            if (seenIds.has(id)) {
+                problems.push(`duplicate region "${id}"`);
+            }
+            seenIds.add(id);
+            current = { id, label: head, ...(tail ? { notes: tail } : {}), elements: [] };
+            regions.push(current);
+            continue;
+        }
+        if (!current) {
+            problems.push(`element "${text}" appears before any region`);
+            continue;
+        }
+        const { head, tail } = splitHead(text);
+        current.elements.push({ name: head, ...(tail ? { spec: tail } : {}) });
+    }
+    if (regions.length === 0 && problems.length === 0) {
+        problems.push("`## Anatomy` section has no regions");
+    }
+    return { regions, problems };
+}

package/dist/_core/dist/design/fidelity.js

@@ -0,0 +1,265 @@
+export const FIDELITY_SCORECARD_SCHEMA = "raptor.fidelity/v1";
+export const FIDELITY_DIMENSIONS = [
+    "layout",
+    "spacing",
+    "color",
+    "typography",
+    "dimensions",
+    "icon",
+    "states",
+];
+export const DEFAULT_FIDELITY_THRESHOLD = 95;
+export const DIVERGENCE_SEVERITIES = ["minor", "major", "blocker"];
+export const DIVERGENCE_STATUSES = ["resolved", "open", "design-decision"];
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function isScore(v) {
+    return typeof v === "number" && Number.isFinite(v) && v >= 0 && v <= 100;
+}
+function validateDivergence(d, label, problems) {
+    if (!isRecord(d)) {
+        problems.push(`${label}: divergence must be an object`);
+        return null;
+    }
+    let valid = true;
+    const dim = d["dimension"];
+    if (typeof dim !== "string" || !FIDELITY_DIMENSIONS.includes(dim)) {
+        problems.push(`${label}: divergence "dimension" must be one of ${FIDELITY_DIMENSIONS.join("|")}`);
+        valid = false;
+    }
+    const sev = d["severity"];
+    if (typeof sev !== "string" || !DIVERGENCE_SEVERITIES.includes(sev)) {
+        problems.push(`${label}: divergence "severity" must be one of ${DIVERGENCE_SEVERITIES.join("|")}`);
+        valid = false;
+    }
+    const status = d["status"];
+    if (typeof status !== "string" || !DIVERGENCE_STATUSES.includes(status)) {
+        problems.push(`${label}: divergence "status" must be one of ${DIVERGENCE_STATUSES.join("|")}`);
+        valid = false;
+    }
+    if (!valid)
+        return null;
+    return {
+        dimension: dim,
+        figma: typeof d["figma"] === "string" ? d["figma"] : "",
+        rn: typeof d["rn"] === "string" ? d["rn"] : "",
+        ...(typeof d["fix"] === "string" ? { fix: d["fix"] } : {}),
+        severity: sev,
+        status: status,
+    };
+}
+function validateRegion(r, label, problems) {
+    if (!isRecord(r)) {
+        problems.push(`${label} must be an object`);
+        return null;
+    }
+    const id = r["id"];
+    if (typeof id !== "string" || !id.trim()) {
+        problems.push(`${label}: missing "id"`);
+        return null;
+    }
+    if (!isScore(r["score"])) {
+        problems.push(`${label}: "score" must be a number 0–100`);
+    }
+    let dimensions;
+    if (r["dimensions"] !== undefined) {
+        if (!isRecord(r["dimensions"])) {
+            problems.push(`${label}: "dimensions" must be an object`);
+        }
+        else {
+            dimensions = {};
+            for (const [k, v] of Object.entries(r["dimensions"])) {
+                if (!FIDELITY_DIMENSIONS.includes(k)) {
+                    problems.push(`${label}: unknown dimension "${k}"`);
+                    continue;
+                }
+                if (!isScore(v)) {
+                    problems.push(`${label}: dimension "${k}" must be a number 0–100`);
+                    continue;
+                }
+                dimensions[k] = v;
+            }
+        }
+    }
+    let divergences;
+    if (r["divergences"] !== undefined) {
+        if (!Array.isArray(r["divergences"])) {
+            problems.push(`${label}: "divergences" must be an array`);
+        }
+        else {
+            divergences = [];
+            r["divergences"].forEach((d, i) => {
+                const parsed = validateDivergence(d, `${label}.divergences[${i}]`, problems);
+                if (parsed)
+                    divergences.push(parsed);
+            });
+        }
+    }
+    return {
+        id,
+        ...(typeof r["label"] === "string" ? { label: r["label"] } : {}),
+        score: isScore(r["score"]) ? r["score"] : 0,
+        ...(dimensions ? { dimensions } : {}),
+        ...(divergences ? { divergences } : {}),
+    };
+}
+export function parseFidelityScorecard(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        return {
+            scorecard: null,
+            problems: [`fidelity scorecard is not valid JSON: ${err instanceof Error ? err.message : String(err)}`],
+        };
+    }
+    if (!isRecord(parsed)) {
+        return { scorecard: null, problems: ["fidelity scorecard must be a JSON object"] };
+    }
+    const problems = [];
+    if (parsed["schema"] !== FIDELITY_SCORECARD_SCHEMA) {
+        problems.push(`fidelity scorecard schema must be "${FIDELITY_SCORECARD_SCHEMA}" (got ${JSON.stringify(parsed["schema"])})`);
+        return { scorecard: null, problems };
+    }
+    if (typeof parsed["screen"] !== "string" || !parsed["screen"].trim()) {
+        problems.push('fidelity scorecard: missing "screen"');
+    }
+    if (parsed["threshold"] !== undefined && !isScore(parsed["threshold"])) {
+        problems.push('fidelity scorecard: "threshold" must be a number 0–100');
+    }
+    const states = [];
+    const rawStates = parsed["states"];
+    if (!Array.isArray(rawStates)) {
+        problems.push('fidelity scorecard: "states" must be an array');
+    }
+    else {
+        rawStates.forEach((st, si) => {
+            if (!isRecord(st)) {
+                problems.push(`state[${si}] must be an object`);
+                return;
+            }
+            const stateName = typeof st["state"] === "string" && st["state"].trim() ? st["state"] : `state[${si}]`;
+            if (typeof st["state"] !== "string" || !st["state"].trim()) {
+                problems.push(`state[${si}]: missing "state"`);
+            }
+            const regions = [];
+            if (!Array.isArray(st["regions"])) {
+                problems.push(`state "${stateName}": "regions" must be an array`);
+            }
+            else {
+                st["regions"].forEach((r, ri) => {
+                    const region = validateRegion(r, `state "${stateName}" region[${ri}]`, problems);
+                    if (region)
+                        regions.push(region);
+                });
+            }
+            states.push({
+                state: typeof st["state"] === "string" ? st["state"] : stateName,
+                ...(typeof st["screenshot_figma"] === "string" ? { screenshot_figma: st["screenshot_figma"] } : {}),
+                ...(typeof st["screenshot_app"] === "string" ? { screenshot_app: st["screenshot_app"] } : {}),
+                regions,
+            });
+        });
+    }
+    let deterministic;
+    if (parsed["deterministic"] !== undefined) {
+        if (!isRecord(parsed["deterministic"])) {
+            problems.push('fidelity scorecard: "deterministic" must be an object');
+        }
+        else {
+            const det = parsed["deterministic"];
+            deterministic = {
+                ...(Array.isArray(det["hex_hardcoded"]) ? { hex_hardcoded: det["hex_hardcoded"].map(String) } : {}),
+                ...(typeof det["screenshots_present"] === "boolean" ? { screenshots_present: det["screenshots_present"] } : {}),
+                ...(typeof det["token_diff"] === "string" ? { token_diff: det["token_diff"] } : {}),
+            };
+        }
+    }
+    const scorecard = {
+        schema: FIDELITY_SCORECARD_SCHEMA,
+        screen: typeof parsed["screen"] === "string" ? parsed["screen"] : "",
+        ...(typeof parsed["node_id"] === "string" ? { node_id: parsed["node_id"] } : {}),
+        ...(isScore(parsed["threshold"]) ? { threshold: parsed["threshold"] } : {}),
+        states,
+        ...(deterministic ? { deterministic } : {}),
+        ...(isScore(parsed["min_score"]) ? { min_score: parsed["min_score"] } : {}),
+        ...(typeof parsed["passed"] === "boolean" ? { passed: parsed["passed"] } : {}),
+        ...(Array.isArray(parsed["learnings"]) ? { learnings: parsed["learnings"].map(String) } : {}),
+    };
+    return { scorecard, problems };
+}
+export function regionScore(region) {
+    const dims = region.dimensions
+        ? Object.values(region.dimensions).filter((n) => typeof n === "number" && Number.isFinite(n))
+        : [];
+    if (dims.length > 0)
+        return Math.min(...dims);
+    return typeof region.score === "number" ? region.score : 0;
+}
+export function evaluateScorecard(card, opts) {
+    const threshold = opts?.threshold ?? card.threshold ?? DEFAULT_FIDELITY_THRESHOLD;
+    const regions = [];
+    const pendingDesignDecisions = [];
+    for (const st of card.states ?? []) {
+        for (const r of st.regions ?? []) {
+            const reasons = [];
+            const score = regionScore(r);
+            if (score < threshold)
+                reasons.push(`score ${score} < threshold ${threshold}`);
+            const dimVals = r.dimensions
+                ? Object.values(r.dimensions).filter((n) => typeof n === "number" && Number.isFinite(n))
+                : [];
+            if (r.dimensions !== undefined) {
+                if (dimVals.length === 0) {
+                    reasons.push("declared dimensions breakdown is empty");
+                }
+                else if (typeof r.score === "number") {
+                    const weakest = Math.min(...dimVals);
+                    if (r.score !== weakest) {
+                        reasons.push(`declared score ${r.score} must equal the weakest dimension ${weakest}`);
+                    }
+                }
+            }
+            for (const d of r.divergences ?? []) {
+                if (d.status === "open")
+                    reasons.push(`open divergence in ${d.dimension}`);
+                if (d.status === "design-decision") {
+                    pendingDesignDecisions.push({ state: st.state, region: r.id, dimension: d.dimension });
+                }
+            }
+            regions.push({
+                state: st.state,
+                region: r.id,
+                score,
+                threshold,
+                pass: reasons.length === 0,
+                reasons,
+            });
+        }
+    }
+    const hexHardcoded = card.deterministic?.hex_hardcoded ?? [];
+    const screenshotsPresent = card.deterministic?.screenshots_present ?? false;
+    const failing = regions.filter((r) => !r.pass);
+    const reasons = [];
+    if (regions.length === 0)
+        reasons.push("scorecard scored no regions");
+    for (const st of card.states ?? []) {
+        if ((st.regions?.length ?? 0) === 0)
+            reasons.push(`state "${st.state}" has no regions`);
+    }
+    if (hexHardcoded.length > 0)
+        reasons.push(`${hexHardcoded.length} hardcoded hex colour(s)`);
+    const ok = reasons.length === 0 && failing.length === 0;
+    return {
+        threshold,
+        regions,
+        failing,
+        hexHardcoded,
+        screenshotsPresent,
+        pendingDesignDecisions,
+        reasons,
+        ok,
+    };
+}

package/dist/_core/dist/design/hex-scan.js

@@ -0,0 +1,62 @@
+const TOKEN_DIR = /(?:^|\/)(?:design-system|design_system|tokens?|theme|palette|colou?rs?)\//i;
+const HEX = /(?<![\w#&])#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})\b/g;
+const COLOR_FUNC = /(?<!\w)(?:rgba?|hsla?)\s*\([^)]*\)/gi;
+const NAMED_COLOR_ASSIGN = /\b\w*(?:[Cc]olor|[Ff]ill|[Ss]troke|[Tt]int|[Ss]hadow)\b\s*[:=]\s*["']([A-Za-z]+)["']/g;
+const CSS_NAMED_COLORS = new Set([
+    "aliceblue", "antiquewhite", "aqua", "aquamarine", "azure", "beige", "bisque", "black", "blanchedalmond",
+    "blue", "blueviolet", "brown", "burlywood", "cadetblue", "chartreuse", "chocolate", "coral", "cornflowerblue",
+    "cornsilk", "crimson", "cyan", "darkblue", "darkcyan", "darkgoldenrod", "darkgray", "darkgreen", "darkgrey",
+    "darkkhaki", "darkmagenta", "darkolivegreen", "darkorange", "darkorchid", "darkred", "darksalmon",
+    "darkseagreen", "darkslateblue", "darkslategray", "darkslategrey", "darkturquoise", "darkviolet", "deeppink",
+    "deepskyblue", "dimgray", "dimgrey", "dodgerblue", "firebrick", "floralwhite", "forestgreen", "fuchsia",
+    "gainsboro", "ghostwhite", "gold", "goldenrod", "gray", "green", "greenyellow", "grey", "honeydew", "hotpink",
+    "indianred", "indigo", "ivory", "khaki", "lavender", "lavenderblush", "lawngreen", "lemonchiffon", "lightblue",
+    "lightcoral", "lightcyan", "lightgoldenrodyellow", "lightgray", "lightgreen", "lightgrey", "lightpink",
+    "lightsalmon", "lightseagreen", "lightskyblue", "lightslategray", "lightslategrey", "lightsteelblue",
+    "lightyellow", "lime", "limegreen", "linen", "magenta", "maroon", "mediumaquamarine", "mediumblue",
+    "mediumorchid", "mediumpurple", "mediumseagreen", "mediumslateblue", "mediumspringgreen", "mediumturquoise",
+    "mediumvioletred", "midnightblue", "mintcream", "mistyrose", "moccasin", "navajowhite", "navy", "oldlace",
+    "olive", "olivedrab", "orange", "orangered", "orchid", "palegoldenrod", "palegreen", "paleturquoise",
+    "palevioletred", "papayawhip", "peachpuff", "peru", "pink", "plum", "powderblue", "purple", "rebeccapurple",
+    "red", "rosybrown", "royalblue", "saddlebrown", "salmon", "sandybrown", "seagreen", "seashell", "sienna",
+    "silver", "skyblue", "slateblue", "slategray", "slategrey", "snow", "springgreen", "steelblue", "tan", "teal",
+    "thistle", "tomato", "turquoise", "violet", "wheat", "white", "whitesmoke", "yellow", "yellowgreen",
+]);
+function isCommentLine(trimmed) {
+    return (trimmed.startsWith("//") ||
+        trimmed.startsWith("*") ||
+        trimmed.startsWith("/*") ||
+        trimmed.startsWith("{/*"));
+}
+export function scanHardcodedHex(files, opts) {
+    const findings = [];
+    for (const { path, content } of files) {
+        if (TOKEN_DIR.test(path))
+            continue;
+        if (opts?.allowPaths?.some((p) => path.includes(p)))
+            continue;
+        const lines = content.split(/\r?\n/);
+        lines.forEach((line, i) => {
+            const trimmed = line.trim();
+            if (isCommentLine(trimmed))
+                return;
+            const push = (hex) => findings.push({ file: path, line: i + 1, hex, snippet: trimmed.slice(0, 120) });
+            for (const re of [HEX, COLOR_FUNC]) {
+                re.lastIndex = 0;
+                let m;
+                while ((m = re.exec(line)))
+                    push(m[0]);
+            }
+            NAMED_COLOR_ASSIGN.lastIndex = 0;
+            let m;
+            while ((m = NAMED_COLOR_ASSIGN.exec(line))) {
+                if (CSS_NAMED_COLORS.has(m[1].toLowerCase()))
+                    push(m[1]);
+            }
+        });
+    }
+    return findings;
+}
+export function hexFindingsToScorecard(findings) {
+    return findings.map((f) => `${f.hex} at ${f.file}:${f.line}`);
+}

package/dist/_core/dist/design/index.js

@@ -9,6 +9,10 @@ export * from "./slug.js";
 export * from "./asset-paths.js";
 export * from "./asset-normalize.js";
 export * from "./screens.js";
+export * from "./anatomy.js";
+export * from "./fidelity.js";
+export * from "./hex-scan.js";
+export * from "./token-diff.js";
 export * from "./downloader.js";
 export * from "./font-resolver.js";
 export * from "./figma-dialects.js";