synthesisui 0.16.432 → 0.16.434

package/dist/commands/import.js

@@ -56,6 +56,7 @@ import { consumersOf, outsideScope, } from "../outside-scope.js";
 import { phase, startProgress } from "../progress.js";
 import { repoStateOf } from "../repo-state.js";
 import { relatorioHtml, secoesDe } from "../report-html.js";
+import { abertura, aneis, historiaDeCor, oQueMuda } from "../report-insight.js";
 import { runtimeDeclaredVars, runtimeDeclaredVarsIn } from "../runtime-vars.js";
 import { detectStack, resolveDeps, stackVersions } from "../stack.js";
 import { desligarCaptura, ligarCaptura } from "../transcript.js";
@@ -3778,6 +3779,20 @@ async function mostrarInspecao(c, root, transcrito) {
             },
         ],
         secoes,
+        /**
+         * O ESPELHO (dono, 18/09): a pagina abre com a MESMA regua que o produto usa - cobertura de
+         * token, o vocabulario dela, e o quanto a leitura entendeu. Nenhum numero novo: os tres saem
+         * de campos que a medicao ja produz.
+         */
+        abertura: abertura(c, c.measured?.repo ?? basename(root)),
+        aneis: aneis(c),
+        cor: historiaDeCor(c),
+        /**
+         * O COMANDO NO TOPO E NO FIM (dono, 18/09): quem decidiu adotar no meio da leitura nao
+         * deveria ter que voltar ao terminal para descobrir o que digitar.
+         */
+        comando: "npx synthesisui@latest import",
+        muda: oQueMuda(c),
     });
     console.log(section("What came out of your files"));
     console.log(body(`${paint.strong(`${lidos} of ${total}`)} components came out with a blueprint${pct === null

package/dist/report-html.js

@@ -82,37 +82,113 @@ ${layout()}
         <p class="kicker">Read by SynthesisUI</p>
         <p class="bar-repo">${escapar(cabecalho.repo)}</p>
       </div>
-      <p class="meta">${escapar(quando)} &middot; CLI ${escapar(cabecalho.cli)} &middot; nothing left this machine</p>
+      <div class="bar-fim">
+        <p class="meta">${escapar(quando)} &middot; CLI ${escapar(cabecalho.cli)} &middot; nothing left this machine</p>${input.comando
+        ? `
+        <code class="comando">${escapar(input.comando)}</code>`
+        : ""}
+      </div>
     </div>
   </header>
 
-  <main class="wrap">
+  <div class="wrap">
+    <nav class="lado">
+      <p class="kicker">What is in here</p>
+      <ol>
+          ${indice}
+      </ol>
+    </nav>
+
+  <main class="fluxo">
     <section class="hero chapter" style="--ordem:0">
       <h1>${escapar(cabecalho.repo)}</h1>
-      <p class="lede">This is what your own code says about itself.</p>
+      <p class="lede">${escapar(input.abertura ?? "This is what your own code says about itself.")}</p>
       <div class="stats">
 ${numeros}
       </div>
+${desenharAneis(input.aneis ?? [])}
+${desenharCor(input.cor)}
     </section>
 
-    <nav class="chapter" style="--ordem:1">
-      <p class="kicker">What is in here</p>
-      <ol>
-          ${indice}
-      </ol>
-    </nav>
-
 ${corpo}
 
+${desenharMuda(input.muda ?? [], input.comando)}
+
     <footer>
       <p>Dressed by Halogen v${HALOGEN_VERSION}, a design system from the SynthesisUI gallery.</p>
       <p>This file lives in your project and was never sent anywhere. Re-run the command to refresh it.</p>
     </footer>
   </main>
+  </div>
 </body>
 </html>
 `;
 }
+/**
+ * A ÚLTIMA COISA QUE ELA LÊ: a conta, e não mais um inventário.
+ *
+ * Um relatório que termina na décima sexta lista deixa a pessoa com o diagnóstico e sem o passo.
+ * Este capítulo diz o que muda COM OS NÚMEROS DELA e entrega o comando ao lado - a mesma linha que
+ * já está no topo, porque quem chegou até aqui não deveria ter que subir para achá-la.
+ */
+function desenharMuda(linhas, comando) {
+    if (linhas.length === 0)
+        return "";
+    return `      <section class="chapter muda" style="--ordem:12">
+        <h2><span>What changes if you bring it in</span></h2>
+${linhas.map((l) => `        <p class="callout">${escapar(l)}</p>`).join("\n")}${comando
+        ? `
+        <code class="comando grande">${escapar(comando)}</code>`
+        : ""}
+      </section>`;
+}
+/**
+ * OS TRÊS ANÉIS DA NOSSA LEITURA DE TOKEN (pedido dele, 18/09) - e eles abrem a página porque são
+ * a régua do produto: quanto já vem de token, quanto ela declara, e quanto a leitura entendeu.
+ *
+ * O anel é um `conic-gradient` e nada mais: sem biblioteca, sem `<script>`, e sem uma requisição.
+ * A fatia é a proporção MEDIDA - e um anel só existe onde há denominador, porque desenhar a fatia
+ * de um total que ninguém contou é inventar a proporção.
+ */
+function desenharAneis(aneis) {
+    if (aneis.length === 0)
+        return "";
+    const cartoes = aneis
+        .map((a) => {
+        const pct = a.de > 0 ? Math.round((a.parte / a.de) * 100) : 0;
+        return `          <div class="anel-cartao">
+            <div class="anel" style="--fatia:${pct}%" role="img" aria-label="${escapar(`${a.titulo}: ${a.numero}`)}">
+              <b>${escapar(a.numero)}</b>
+            </div>
+            <div class="anel-texto">
+              <h3>${escapar(a.titulo)}</h3>
+              <p>${escapar(a.frase)}</p>
+            </div>
+          </div>`;
+    })
+        .join("\n");
+    return `      <section class="aneis chapter" style="--ordem:1">
+${cartoes}
+      </section>`;
+}
+/**
+ * A HISTÓRIA DAS CORES, com a paleta desenhada do lado - as cores DELA, nos valores dela.
+ *
+ * Os quadradinhos não são enfeite: uma frase sobre quarenta e sete cores colidindo é abstrata até
+ * a pessoa VER que duas casas ao lado da outra são a mesma cor.
+ */
+function desenharCor(cor) {
+    if (!cor || cor.linhas.length === 0)
+        return "";
+    const amostras = cor.paleta
+        .map((c) => `<i style="--amostra:${escapar(c)}" title="${escapar(c)}"></i>`)
+        .join("");
+    return `      <section class="chapter cor" style="--ordem:2">
+        <h2><span>Your colours</span></h2>
+${cor.linhas.map((l) => `        <p class="callout">${escapar(l)}</p>`).join("\n")}
+        <div class="paleta" aria-hidden="true">${amostras}</div>
+      </section>`;
+}
 /**
  * O NÚMERO COM A FATIA DESENHADA - e a barra só aparece quando existe denominador medido.
  *
@@ -150,13 +226,16 @@ function desenharCorpo(s) {
     const familias = agrupar(resto);
     const corpo = familias
         .map((f) => f.tipo === "tabela"
-        ? `        <details class="familia" open>
+        ? `        <details class="familia">
           <summary><span>${escapar(f.rotulo)}</span> <b>${f.itens.length}</b></summary>
           <ul class="grade">
 ${f.itens.map((i) => `            <li>${escapar(i)}</li>`).join("\n")}
           </ul>
         </details>`
-        : `        <pre>${escapar(f.itens.join("\n"))}</pre>`)
+        : `        <details class="tecnico">
+          <summary>${f.itens.filter((l) => l.trim()).length} lines of detail</summary>
+          <pre>${escapar(f.itens.join("\n"))}</pre>
+        </details>`)
         .join("\n");
     return destaque
         ? `        <p class="callout">${escapar(destaque)}</p>\n${corpo}`
@@ -295,7 +374,8 @@ function layout() {
     const corpo = `var(${FAMILY_SEAM_PREFIX}body, ui-sans-serif, system-ui, sans-serif)`;
     const mono = `var(${FAMILY_SEAM_PREFIX}mono, ui-monospace, monospace)`;
     const display = `var(${FAMILY_SEAM_PREFIX}display, inherit)`;
-    return `body {
+    return `html { scroll-behavior: smooth; }
+body {
   margin: 0;
   background: var(--ds-color-semantic-canvas);
   color: var(--ds-color-semantic-foreground);
@@ -312,8 +392,11 @@ function layout() {
   background: var(--ds-color-semantic-raised, var(--ds-color-semantic-surface));
   border-bottom: 1px solid var(--ds-color-semantic-border);
 }
+/* A BARRA ALINHA COM A COLUNA DO CONTEUDO: mesma largura maxima, mesma margem lateral. Antes ela
+   media 920px enquanto o corpo media 1200, entao o titulo do topo e o titulo da pagina comecavam em
+   colunas diferentes - a primeira coisa que o olho nota, e a mais facil de consertar. */
 .bar-in {
-  max-width: 920px;
+  max-width: 1200px;
   margin-inline: auto;
   padding: 11px 24px;
   display: flex;
@@ -323,9 +406,48 @@ function layout() {
   justify-content: space-between;
 }
 .bar-repo { margin: 2px 0 0; font-weight: 600; }
+.bar-fim { display: flex; align-items: center; gap: 14px; flex-wrap: wrap; }
+
+/* O COMANDO NO TOPO, sem rolar: quem decidiu adotar no meio da leitura nao volta para procura-lo. */
+.comando {
+  font-family: ${mono};
+  font-size: 12px;
+  padding: 6px 12px;
+  border-radius: var(--ds-radius-sm, 8px);
+  border: 1px solid var(--ds-color-semantic-border);
+  background: var(--ds-color-semantic-canvas);
+  color: var(--ds-color-semantic-foreground);
+  user-select: all;
+}
+.comando.grande {
+  display: inline-block;
+  margin-top: 14px;
+  font-size: 14px;
+  padding: 12px 18px;
+}
 .bar-id { min-width: 0; }
 
-.wrap { max-width: 920px; margin-inline: auto; padding: 0 24px 96px; }
+.wrap {
+  max-width: 1200px;
+  margin-inline: auto;
+  padding: 0 24px 96px;
+  display: grid;
+  grid-template-columns: 230px minmax(0, 1fr);
+  gap: 40px;
+  align-items: start;
+}
+.fluxo { min-width: 0; }
+
+/* A LATERAL SEGURA A ROLAGEM INTEIRA: quem esta no capitulo doze pula para o tres sem subir, que
+   era o que a lista no topo obrigava. Em tela estreita ela vira topo - uma coluna de 250px num
+   celular come metade da leitura. */
+.lado {
+  position: sticky;
+  top: 76px;
+  max-height: calc(100vh - 100px);
+  overflow: auto;
+  padding: 20px 0 0;
+}
 
 .kicker {
   margin: 0;
@@ -378,7 +500,7 @@ h1 {
 
 nav { margin: 44px 0 8px; }
 nav ol {
-  margin: 12px 0 0;
+  margin: 10px 0 0;
   padding: 0;
   list-style: none;
   counter-reset: capitulo;
@@ -390,10 +512,21 @@ nav li {
   counter-increment: capitulo;
   display: flex;
   align-items: baseline;
-  gap: 12px;
-  padding: 7px 10px;
+  gap: 10px;
+  padding: 5px 9px;
+  font-size: 13px;
+  line-height: 1.35;
+  border: 1px solid transparent;
   border-radius: var(--ds-radius-sm, 8px);
 }
+/* O ITEM CLICADO FICA MARCADO: sem isto a lateral e uma lista de dezesseis iguais, e a pessoa perde
+   de onde veio no instante em que rola. O foco sobrevive ao clique, entao a marca tambem. */
+nav li:has(a:focus),
+nav li:has(a:focus-visible) {
+  border-color: var(--ds-color-semantic-accent);
+  background: var(--ds-color-semantic-surface);
+}
+nav li:has(a:focus) a { color: var(--ds-color-semantic-accent); }
 nav li:hover { background: var(--ds-color-semantic-surface); }
 nav li::before {
   content: counter(capitulo);
@@ -501,7 +634,66 @@ footer { margin-top: 40px; color: var(--ds-color-semantic-muted); font-size: 13p
 .chapter { animation: entrar 620ms cubic-bezier(0.22, 1, 0.36, 1) both; animation-delay: calc(var(--ordem, 0) * 55ms); }
 
 @media (prefers-reduced-motion: reduce) {
-  .chapter, .bar-track i { animation: none; }
+  html { scroll-behavior: auto; }
+  .chapter, .bar-track i, .anel { animation: none; }
+}
+
+/* OS ANEIS: um gradiente conico e mais nada - sem biblioteca e sem script, que e o contrato. */
+.aneis {
+  display: grid;
+  gap: 18px;
+  margin-top: 16px;
+}
+.anel-cartao { display: flex; gap: 18px; align-items: center; }
+.anel {
+  flex: 0 0 auto;
+  width: 84px;
+  height: 84px;
+  border-radius: 50%;
+  display: grid;
+  place-items: center;
+  background: conic-gradient(
+    var(--ds-color-semantic-accent) var(--fatia),
+    var(--ds-color-semantic-overlay, var(--ds-color-semantic-border)) 0
+  );
+  animation: girar 900ms cubic-bezier(0.22, 1, 0.36, 1) both;
+}
+.anel b {
+  width: 62px;
+  height: 62px;
+  border-radius: 50%;
+  background: var(--ds-color-semantic-surface);
+  display: grid;
+  place-items: center;
+  font-size: 15px;
+  font-variant-numeric: tabular-nums;
+}
+.anel-texto h3 { margin: 0 0 4px; font-size: 15px; }
+.anel-texto p { margin: 0; color: var(--ds-color-semantic-muted); font-size: 14px; }
+
+.paleta { display: flex; flex-wrap: wrap; gap: 6px; margin-top: 14px; }
+.paleta i {
+  width: 30px;
+  height: 30px;
+  border-radius: var(--ds-radius-sm, 8px);
+  background: var(--amostra);
+  border: 1px solid var(--ds-color-semantic-border);
+}
+
+/* O DETALHE TECNICO NASCE FECHADO: ele e a evidencia, nao a conclusao. */
+.tecnico { margin: 0 0 12px; }
+.tecnico summary {
+  cursor: pointer;
+  font-size: 13px;
+  color: var(--ds-color-semantic-faint);
+}
+.tecnico pre { margin-top: 10px; }
+
+@keyframes girar { from { --fatia: 0%; } }
+
+@media (max-width: 900px) {
+  .wrap { grid-template-columns: minmax(0, 1fr); gap: 0; }
+  .lado { position: static; max-height: none; padding-bottom: 20px; }
 }
 
 @media print {

package/dist/report-insight.js

@@ -0,0 +1,171 @@
+import { deltaE, isNearDuplicate } from "./doctor/color-distance.js";
+/**
+ * OS TRÊS ANÉIS QUE ABREM A PÁGINA (pedido dele, 18/09) - e são os três da nossa própria leitura de
+ * token: cobertura, quanto ela declara, e consistência.
+ *
+ * Um anel só nasce quando existe denominador MEDIDO. Sem ele o número fica sozinho: desenhar uma
+ * fatia sobre um total que ninguém contou é inventar a proporção, que é o defeito que a barra da
+ * plataforma já cometeu uma vez.
+ */
+export function aneis(c) {
+    const saida = [];
+    const observados = c.observed ?? [];
+    if (observados.length > 0) {
+        const comNome = observados.filter((v) => v.token).length;
+        saida.push({
+            titulo: "From your tokens",
+            numero: `${pct(comNome, observados.length)}%`,
+            parte: comNome,
+            de: observados.length,
+            frase: `${comNome} of the ${observados.length} design values in your code already have a name in your own system. The other ${observados.length - comNome} are written by hand, so changing one means finding every copy.`,
+        });
+    }
+    const declarados = Object.keys(c.declared ?? {}).length;
+    if (declarados > 0 && observados.length > 0) {
+        const familias = porFamilia(observados);
+        saida.push({
+            titulo: "Your vocabulary",
+            numero: String(declarados),
+            parte: Math.min(declarados, observados.length),
+            de: observados.length,
+            frase: `You declare ${declarados} tokens today${familias ? `, and the values they cover are ${familias}` : ""}. These are your names, and they travel unchanged.`,
+        });
+    }
+    const cl = c.values?.classes;
+    if (cl && cl.seen > cl.structure) {
+        const decisoes = cl.seen - cl.structure;
+        saida.push({
+            titulo: "What we could read",
+            numero: `${pct(cl.interpreted, decisoes)}%`,
+            parte: cl.interpreted,
+            de: decisoes,
+            frase: `Of the ${decisoes} style decisions in your components, we understood ${cl.interpreted}. The remaining ${decisoes - cl.interpreted} are shapes this version does not read yet - they are named in the chapters below, with the file and line.`,
+        });
+    }
+    return saida;
+}
+/** As famílias com valor, em palavras: "456 colour, 210 spacing". Vazio quando não há o que dizer. */
+function porFamilia(observados) {
+    const nomes = {
+        color: "colour",
+        spacing: "spacing",
+        radius: "radius",
+        font: "type",
+        motion: "motion",
+    };
+    const conta = new Map();
+    for (const v of observados)
+        conta.set(v.kind, (conta.get(v.kind) ?? 0) + 1);
+    const partes = [...conta.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .map(([k, n]) => `${n} ${nomes[k] ?? k}`);
+    return partes.join(", ");
+}
+function pct(parte, de) {
+    if (de <= 0)
+        return 0;
+    return Math.max(0, Math.min(100, Math.round((parte / de) * 100)));
+}
+/**
+ * O PARÁGRAFO DE ABERTURA - o que foi encontrado, em linguagem de quem não abriu o código.
+ *
+ * Montado dos NÚMEROS, nunca de um modelo: ele muda quando o repositório muda, e é verdade em
+ * qualquer projeto - inclusive num que ninguém aqui jamais viu. Um texto fixo com números colados
+ * seria a mesma frase mentindo em metade dos casos.
+ */
+export function abertura(c, repo) {
+    const observados = c.observed ?? [];
+    const comNome = observados.filter((v) => v.token).length;
+    const total = c.coverage?.components ?? 0;
+    const frases = [];
+    if (total > 0)
+        frases.push(`We read ${total} component${total === 1 ? "" : "s"} in ${repo} and wrote down how each one is built.`);
+    if (observados.length > 0)
+        frases.push(comNome === 0
+            ? `Every one of the ${observados.length} design values we found is written by hand - there is no token behind any of them yet.`
+            : `Of the ${observados.length} design values we found, ${comNome} already come from a token you declare, and ${observados.length - comNome} are still written by hand.`);
+    frases.push("Nothing below is a rule we brought. It is what your own files already do, counted.");
+    return frases.join(" ");
+}
+/**
+ * A HISTÓRIA DAS CORES - a paleta, as que colidem, e o contraste do que dá para checar.
+ *
+ * COLISÃO NÃO É ERRO, e a frase diz isso: duas cores a menos de um passo perceptível uma da outra
+ * são indistinguíveis na tela, então manter as duas custa uma decisão e não entrega nenhuma. Quem
+ * decide se elas viram uma é ela.
+ *
+ * O CONTRASTE É A ÚNICA COISA AQUI COM VEREDITO, porque `4.5:1` não é régua nossa sobre o gosto
+ * dela - é o padrão publicado sobre o texto ser legível. E o relatório diz QUANTOS pares conseguiu
+ * checar: onde a leitura não enxerga frente e fundo juntos, ele declara a lacuna em vez de dar uma
+ * nota que não mediu.
+ */
+export function historiaDeCor(c, pares = []) {
+    const cores = (c.observed ?? [])
+        .filter((v) => v.kind === "color")
+        .sort((a, b) => b.count - a.count);
+    if (cores.length === 0)
+        return { linhas: [], paleta: [] };
+    const linhas = [];
+    const comNome = cores.filter((v) => v.token).length;
+    linhas.push(`You paint with ${cores.length} distinct colours, and ${comNome} of them already have a name in your system.`);
+    const colisoes = colidem(cores.map((v) => v.value));
+    if (colisoes > 0)
+        linhas.push(`${colisoes} of them sit within one perceptible step of another colour you also use - close enough that the eye reads them as the same. Keeping both costs a decision and delivers no difference; whether they become one is yours to say.`);
+    else
+        linhas.push("No two of them are close enough to be mistaken for each other - every colour you keep is a colour someone can tell apart.");
+    if (pares.length === 0) {
+        linhas.push("Contrast was not checked: nothing in the files puts a text colour and a background together in a way this reading can see. It needs both sides of a pair, and that only shows up once components are imported.");
+    }
+    else {
+        const baixos = pares.filter((p) => p.razao < 4.5);
+        linhas.push(baixos.length === 0
+            ? `All ${pares.length} text-on-background pairs we could check reach 4.5:1, the published floor for body text.`
+            : `${baixos.length} of the ${pares.length} text-on-background pairs we could check fall below 4.5:1, the published floor for body text - the lowest is ${baixos[0].razao.toFixed(2)}:1. Below that, people with low vision stop being able to read it.`);
+    }
+    return { linhas, paleta: cores.slice(0, 24).map((v) => v.value) };
+}
+/** Quantas cores têm ao menos uma vizinha indistinguível. Conta CORES, nunca pares. */
+function colidem(valores) {
+    const hex = valores.filter((v) => /^#[0-9a-fA-F]{3,8}$/.test(v));
+    let n = 0;
+    for (let i = 0; i < hex.length; i += 1) {
+        for (let j = 0; j < hex.length; j += 1) {
+            if (i === j)
+                continue;
+            if (isNearDuplicate(hex[i], hex[j]) ||
+                (deltaE(hex[i], hex[j]) ?? 99) < 2) {
+                n += 1;
+                break;
+            }
+        }
+    }
+    return n;
+}
+/**
+ * O QUE MUDA SE ELA ADOTAR - com os números DELA, e sem uma promessa que a medição não sustente.
+ *
+ * O QUE O CLIENTE GANHA: a última coisa que ela lê não é mais um inventário, é a conta. Quantos dos
+ * valores que hoje ela repete à mão passam a ter um nome, e por que o problema para de voltar.
+ *
+ * E ELE NÃO PROMETE O QUE NÃO MEDIU: o número aqui é o que está escrito à mão HOJE, no repositório
+ * dela. Um texto que dissesse "seu design fica consistente" seria a mesma frase para todo mundo, e
+ * portanto verdade para ninguém.
+ */
+export function oQueMuda(c) {
+    const observados = c.observed ?? [];
+    if (observados.length === 0)
+        return [];
+    const aMao = observados.filter((v) => !v.token);
+    if (aMao.length === 0)
+        return [
+            "Every design value in your code already comes from a token you declare. What SynthesisUI adds here is keeping it that way: the check runs after every file your agent writes, and a value that drifts off your own scale comes back to you as a decision instead of landing silently.",
+        ];
+    const repetidos = aMao.filter((v) => v.count > 1);
+    const usos = repetidos.reduce((n, v) => n + v.count, 0);
+    const linhas = [];
+    linhas.push(`${aMao.length} of your design values are written by hand today. Importing gives each one a name in your own vocabulary, so changing it later means changing it once instead of finding every copy.`);
+    if (repetidos.length > 0)
+        linhas.push(`${repetidos.length} of those are repeated - ${usos} uses across your files. Every copy is a place the next change can be forgotten, which is how two screens end up almost the same colour.`);
+    linhas.push("And it stops coming back: once the system is in the repository, the check runs after every file your agent writes and catches a value that drifts off your own scale, before it ships.");
+    return linhas;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synthesisui",
-  "version": "0.16.432",
+  "version": "0.16.434",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {