synthesisui 0.16.231 → 0.16.234

package/dist/absorb-plan.js

@@ -1,5 +1,5 @@
 import { deltaE, JND } from "./doctor/color-distance.js";
-import { nearestToken, normalizeValue, } from "./doctor/tokens.js";
+import { familySays, nearestToken, normalizeValue, } from "./doctor/tokens.js";
 /** Onde cada tipo de valor mora na fundação. `color` é o único com dois segmentos. */
 const HOME = {
     color: "color",
@@ -18,23 +18,18 @@ const clean = (name) => name.replace(/^--/, "").toLowerCase();
  * para um achado de espaçamento, e o caminho que sai daí é `typography.h2` sobre uma margem - o mesmo
  * erro de categoria que o `crossFamily` foi criado para impedir do outro lado da esteira.
  *
- * A primeira palavra do nome dele é a pista, e é a mesma lista que o `CATEGORY` acima já usa. Quando
- * nenhum candidato concorda com a natureza do achado, COR ainda passa - um hex numa posição de cor
- * não tem ambiguidade de família - e comprimento não passa: sem concordância não há o que separasse
- * um token de tipo de um de espaçamento, e o valor volta sem caminho para a pessoa decidir.
+ * A pista são as palavras de família do nome dele - `familySays`, a MESMA tabela que o mapa de
+ * vocabulário usa para recusar uma sugestão de categoria trocada. Duas listas para a mesma pergunta é
+ * como duas telas passam a discordar sobre o mesmo `12px`.
+ *
+ * Quando nenhum candidato concorda com a natureza do achado, COR ainda passa - um hex numa posição de
+ * cor não tem ambiguidade de família - e comprimento não passa: sem concordância não há o que
+ * separasse um token de tipo de um de espaçamento, e o valor volta sem caminho para a pessoa decidir.
  */
-const KIND_WORDS = {
-    color: ["color", "colour"],
-    radius: ["radius", "rounded"],
-    spacing: ["spacing", "space", "gap"],
-    font: ["font", "type", "text"],
-    motion: ["duration", "motion", "ease", "easing", "transition"],
-};
 function nameOf(kind, candidates) {
     if (!candidates || candidates.length === 0)
         return undefined;
-    const head = (n) => clean(n).split("-")[0] ?? "";
-    const agrees = candidates.find((n) => KIND_WORDS[kind].includes(head(n)));
+    const agrees = candidates.find((n) => familySays(kind, n));
     if (agrees)
         return agrees;
     return kind === "color" ? candidates[0] : undefined;

package/dist/commands/doctor.js

@@ -748,7 +748,7 @@ export async function doctor(opts) {
     const asideTotal = [...aside.values()].reduce((n, v) => n + v, 0);
     if (verbose) {
         for (const [reason, count] of aside) {
-            console.log(body(`set aside: ${plural(count, "value")} in ${reason}`));
+            console.log(body(`out of the count: ${plural(count, "value")} in ${reason}`));
         }
     }
     else if (asideTotal > 0) {
@@ -1157,7 +1157,14 @@ export async function doctor(opts) {
         console.log(body("Add the name to the system, or use one it has. Do not leave it."));
     }
     if (d.findings.length > 0) {
-        say(section("Drift"));
+        /**
+         * "Drift" É A NOSSA PALAVRA para um valor fora do sistema, e era o TÍTULO de uma seção inteira.
+         *
+         * A rodada padrão perdeu o vocabulário nosso em 13/08 e o `--verbose` ficou - a guarda rodava
+         * sobre a saída sem `--verbose`, que é o que a maioria lê. O que a seção lista é literal escrito
+         * à mão, e é isso que o título passa a dizer.
+         */
+        say(section("Values written by hand"));
         const order = ["color", "radius", "spacing", "font"].filter((k) => d.counts[k] > 0);
         for (const kind of order) {
             say(body(`${d.counts[kind]}  ${KIND_LABEL[kind]}`));

package/dist/commands/use.js

@@ -53,9 +53,9 @@ export async function use(slug, intent, opts) {
     const hasDoctrine = await exists(join(slugDir, "doctrine.json"));
     const readFirst = [
         hasDoctrine
-            ? "- Call `system_doctrine` first — this system's rules and philosophy, pinned to the installed version; obey them above everything else. Without MCP, the same data is `doctrine.json` and the `philosophy` of `design-system.json`"
+            ? "- Call `system_doctrine` first - this system's rules and philosophy, pinned to the installed version; obey them above everything else. Without MCP, the same data is `doctrine.json` and the `philosophy` of `design-system.json`"
             : "",
-        `- ${base}/v${version}/GUIDE.md — how to apply the system, the recipes and the token vocabulary`,
+        `- ${base}/v${version}/GUIDE.md - how to apply the system, the recipes and the token vocabulary`,
     ].filter(Boolean);
     // The styling contract differs by target: Next projects in this product use
     // Tailwind v4 backed by the DS; the "general" target is framework-agnostic CSS.

package/dist/component-codegen.js

@@ -1,3 +1,4 @@
+import { PHRASING_FORMS, } from "./types.js";
 export const DEFAULT_CONVENTION = {
     prefix: "ds-",
     partSeparator: "-",
@@ -106,11 +107,22 @@ function elementFor(name, recipe) {
      * UI and a hand-written disclosure, because it reads the SHAPE.
      */
     if (tag === "button") {
-        const holdsBlock = (nodes) => nodes.some((n) => n.as === "slot" ||
-            n.as === "button" ||
-            n.as === "field" ||
-            n.as === "component" ||
-            n.as === "external" ||
+        /**
+         * A LISTA SAI DE `PHRASING_FORMS`, e a enumeração à mão estava incompleta - conserto de 14/08.
+         *
+         * Ela esquecia `heading`, `row` e `stack`, e o custo é a marcação que a lei nomeia logo acima: uma
+         * raiz `action` com um heading no topo saía como `<button><h3>…</h3></button>`. Reproduzido pelo
+         * próprio codegen:
+         *
+         *     preview.kind = "action", parts = [{ as: "heading" }]  ->  ComponentProps<"button">
+         *
+         * E o ramo abaixo já sabia que heading importa - ele devolve `article` quando o topo tem um -,
+         * então era código morto: o gate nunca deixava chegar até ele.
+         *
+         * O complemento de phrasing é a pergunta certa, e não uma lista de formas de bloco: são três nomes
+         * de um lado contra oito do outro, e a lista curta é a que não esquece um.
+         */
+        const holdsBlock = (nodes) => nodes.some((n) => !PHRASING_FORMS.includes(n.as) ||
             (n.children != null && n.children.length > 0));
         const tree = recipe.preview?.parts;
         if (tree && tree.length > 0 && holdsBlock(tree)) {

package/dist/doctor/ledger.js

@@ -1,5 +1,6 @@
 import { appendFile, readFile, stat, writeFile } from "node:fs/promises";
 import { join } from "node:path";
+import { nameToWrite } from "./scan.js";
 /**
  * THE LAYER THAT REMEMBERS - governance that cannot answer "is it getting
  * better?" is a sequence of moments, not a system.
@@ -43,13 +44,23 @@ const MATCHED_CAP = 300;
  * `Diagnosis` mora em `scan.ts`, e importar de lá para cá fecharia um ciclo.
  */
 export function suggestionsFrom(repeats) {
+    /**
+     * O FILTRO É "TEM NOME", e não "tem nome NOSSO" - senão a contagem do outro lado mente.
+     *
+     * A versão anterior exigia `r.token`, então as 23 sugestões que só o vocabulário DELE nomeia nunca
+     * saíam do repositório: a plataforma achava que 59 ofertas foram feitas onde foram 82. Para COR não
+     * há julgamento a perder (um hex numa posição de cor não tem ambiguidade de família), mas "0 de 843
+     * erradas" é um fato, e não ter o número é diferente de o número ser zero.
+     */
     return repeats
-        .filter((r) => Boolean(r.token))
+        .filter((r) => Boolean(nameToWrite(r)))
         .slice(0, MATCHED_CAP)
         .map((r) => ({
         literal: r.literal,
         kind: r.kind,
         token: r.token,
+        /** Não-nulo por construção: o filtro acima só deixa passar quem tem nome. */
+        shown: nameToWrite(r),
         count: r.count,
     }));
 }

package/dist/doctor/their-names.js

@@ -1,4 +1,4 @@
-import { DS_FAMILY, normalizeValue } from "./tokens.js";
+import { FAMILY_PREFIX, familySays, normalizeValue, } from "./tokens.js";
 /**
  * COMO ELE CHAMA O VALOR - para a gente parar de renomear as variáveis dele.
  *
@@ -116,7 +116,7 @@ export function theirNames(ours, theirs) {
         const head = segments(name)[0] ?? "";
         convention.set(head, (convention.get(head) ?? 0) + 1);
     }
-    for (const [kind, prefix] of Object.entries(DS_FAMILY)) {
+    for (const [kind, prefix] of Object.entries(FAMILY_PREFIX)) {
         for (const [name, raw] of ours.byName) {
             if (!name.startsWith(prefix))
                 continue;
@@ -127,7 +127,28 @@ export function theirNames(ours, theirs) {
             const candidates = theirs.byValue.get(value);
             if (!candidates || candidates.length === 0)
                 continue;
-            out.set(key, pick(candidates, name, convention));
+            /**
+             * E A CATEGORIA DO NOME DELE TEM QUE FECHAR - senão o nosso nome fica, e ele está certo.
+             *
+             * O NOSSO prefixo carrega a família por construção; o dele não carrega nada garantido. Quando a
+             * FORMA do valor já decide (hex, `ms`, pilha de fontes) não há o que proteger e o nome dele
+             * entra. Quando o valor é um comprimento cru, `12px` pode ser `--text-caption` ou `--spacing-sm`
+             * no vocabulário dele, e escolher errado escreve um token de tipo num `border-radius`.
+             *
+             * Medido no repositório real em 14/08, antes desta linha: 290 sugestões com a categoria trocada,
+             * 66 delas gravadas por um `--fix --write`, e a pior na PRIMEIRA página do relatório -
+             * `0.25em → --radius-xs` em 116 arquivos. Ver `FAMILY_WORDS`.
+             *
+             * Recusar aqui não perde informação: sem alias, `nameToWrite` cai no NOSSO token, que é da
+             * família certa porque foi o prefixo dela que o trouxe a este laço.
+             */
+            const formDecides = Object.values(UNAMBIGUOUS).some((f) => f.test(value));
+            const usable = formDecides
+                ? candidates
+                : candidates.filter((n) => familySays(kind, n));
+            if (usable.length === 0)
+                continue;
+            out.set(key, pick(usable, name, convention));
         }
     }
     for (const [value, candidates] of theirs.byValue) {

package/dist/doctor/tokens.js

@@ -506,13 +506,62 @@ export function nearestToken(table, literal) {
  */
 /** Exportado para `their-names.ts`, que precisa da MESMA divisão de família para validar a natureza
  *  de um nome dele - duas tabelas de família seriam duas leis. */
-export const DS_FAMILY = {
+/**
+ * O ESPELHO de `FAMILY_PREFIX` e `FAMILY_WORDS` em `libs/ds-contracts/src/token-ref.ts`.
+ *
+ * O CLI é publicado standalone (`dependencies: {}`) e não pode importar os contratos, então as duas
+ * cópias são inevitáveis - `family-vocabulary.spec.ts` compara as duas com o arquivo do contrato, como
+ * o gêmeo do `frontier-kind` já faz. O nome é o MESMO dos dois lados de propósito: `DS_FAMILY` aqui e
+ * `FAMILY` lá era a mesma tabela com dois nomes, e ninguém que lesse um dos dois saberia do outro.
+ */
+export const FAMILY_PREFIX = {
     color: "--ds-color-",
     radius: "--ds-radius-",
     spacing: "--ds-spacing-",
     font: "--ds-typography-",
     motion: "--ds-motion-",
 };
+/**
+ * AS PALAVRAS COM QUE O MUNDO NOMEIA CADA FAMÍLIA - e é isto que impede um erro de categoria.
+ *
+ * O NOSSO prefixo carrega a família (`--ds-spacing-md` é espaçamento por construção). O DELE não
+ * carrega nada garantido, e nada verificava: `--text-caption` e `--spacing-sm` podem segurar o mesmo
+ * `12px`, e sugerir o primeiro para um `border-radius` é escrever um token de tipo numa posição de
+ * raio. É exatamente o erro que o `crossFamily` foi criado para impedir do NOSSO lado, e ele passou
+ * a acontecer pelo lado dele quando o mapa de vocabulário nasceu.
+ *
+ * Medido no repositório real em 14/08, antes desta trava:
+ *
+ *     2680  achados com nome dele
+ *     1635  categoria concorda
+ *      290  categoria DISCORDA   <- sugestão errada na tela
+ *       66  dessas o `--fix --write` GRAVARIA (o resto é `em`, que já tem trava)
+ *      755  nome sem palavra de categoria - e são todos cor (748) e fonte (7)
+ *
+ * A pior estava na primeira página: `0.25em → --radius-xs` em 116 arquivos, na lista das mais
+ * repetidas. E `4px → --radius-xs` num padding é uma escrita silenciosa, sem `em` para barrá-la.
+ *
+ * `text` está na lista de tipo porque `--text-h2` é a forma dominante no mundo real, e `transition`
+ * na de motion pelo mesmo motivo.
+ */
+export const FAMILY_WORDS = {
+    color: ["color", "colour"],
+    radius: ["radius", "rounded", "corner"],
+    spacing: ["spacing", "space", "gap", "inset"],
+    font: ["font", "type", "text"],
+    motion: ["duration", "motion", "ease", "easing", "transition"],
+};
+/**
+ * O NOME DELE DIZ QUE É DESTA FAMÍLIA - por QUALQUER segmento, não só pelo primeiro.
+ *
+ * `--dashboard-radius-lg` é um raio e o primeiro segmento é o namespace dele. Olhar só o começo
+ * recusaria um nome certo por causa de um prefixo de produto, que é a metade oposta do mesmo erro.
+ */
+export const familySays = (kind, name) => {
+    const words = FAMILY_WORDS[kind] ?? [];
+    const segments = name.replace(/^--/, "").toLowerCase().split("-");
+    return segments.some((seg) => words.includes(seg));
+};
 /**
  * O token que carrega este valor, e SE ELE É DA MESMA FAMÍLIA.
  *
@@ -535,7 +584,7 @@ export function tokenMatch(table, literal, kind) {
     const hit = table.byValue.get(normalizeValue(literal, table.rootPx));
     if (!hit || hit.length === 0)
         return null;
-    const prefix = kind ? DS_FAMILY[kind] : undefined;
+    const prefix = kind ? FAMILY_PREFIX[kind] : undefined;
     const family = prefix ? hit.filter((n) => n.startsWith(prefix)) : [];
     const pool = family.length > 0 ? family : hit;
     // Semantic roles name intent; primitives name a shelf. Prefer intent.

package/dist/install-marks.js

@@ -71,7 +71,16 @@
  * a prop, e 104 das 207 condições sem expressão nenhuma. Um `upgrade` anterior a esta versão reescreve
  * os componentes dele com a perda intacta.
  */
-export const MATERIALISER_SINCE = "0.16.220";
+/**
+ * 0.16.220 -> 0.16.233 em 14/08: o componente materializado muda de bytes. A regra de contenção HTML
+ * era enumerada à mão em `elementFor` e a enumeração esquecia `heading`, `row` e `stack` - uma raiz de
+ * papel `action` com um heading no topo saía como `<button><h3>…</h3></button>`, que é marcação
+ * inválida embarcada num copy-paste. Agora sai `<article>`.
+ *
+ * Zero ocorrências no sistema real medido (todos os headings dele estão aninhados, e o `children > 0`
+ * já os pegava), então para ele o `upgrade` é no-op. A marca é sobre o caso geral.
+ */
+export const MATERIALISER_SINCE = "0.16.233";
 /**
  * A ÚLTIMA VERSÃO EM QUE O QUE O HOOK RODA MUDOU.
  *
@@ -123,7 +132,14 @@ export const MATERIALISER_SINCE = "0.16.220";
  * e diz que o sistema não nomeia a fonte que o css dela nomeia. Medido no repositório real: as trocas
  * com nome disponível foram de 1624 para 1631.
  */
-export const CHECKER_SINCE = "0.16.231";
+/**
+ * 0.16.231 -> 0.16.232 em 14/08, e este é o pior que esta marca já carregou: o pinado não erra por
+ * omissão, ele erra o CONSELHO. O mapa de vocabulário escolhia entre os nomes DELE sem conferir a
+ * categoria, então um hook pinado antes disto olha um `border-radius: 12px` recém-escrito e manda usar
+ * `var(--text-caption)` - um token de tipo numa posição de raio. Medido no repositório real: 290
+ * sugestões com a categoria trocada, 66 delas graváveis por um `--fix --write`.
+ */
+export const CHECKER_SINCE = "0.16.232";
 /**
  * A ÚLTIMA VERSÃO EM QUE OS LEITORES PASSARAM A PRODUZIR UM CENSO DIFERENTE.
  *

package/dist/last-sync.js

@@ -124,7 +124,7 @@ export function describeDelta(now, before) {
         ? `, and the reader moved ${before.cli} → ${now.cli}, so some of this is us reading better rather than your code changing`
         : "";
     if (parts.length > 0)
-        return `${parts.join(" · ")} — since your last sync${when ? `, ${when}` : ""}${reader}`;
+        return `${parts.join(" · ")} - since your last sync${when ? `, ${when}` : ""}${reader}`;
     /**
      * NADA MUDOU É DIFERENTE DE NÃO DÁ PARA SABER. Um carimbo de uma versão anterior a esta não tem
      * as impressões, então afirmar que nada mudou seria afirmar sobre o que não foi medido - e é

package/dist/types.js

@@ -3,4 +3,13 @@
  * import `@synthesisui-hub/ds-contracts` (it only consumes the endpoint JSON).
  * We type only what the CLI reads to generate GUIDE.md and the .lock.
  */
-export {};
+/**
+ * AS TRÊS FORMAS QUE SÃO PHRASING CONTENT - e é a lista CURTA de propósito.
+ *
+ * `<button><Upload/>Upload</button>` é HTML válido: o modelo de conteúdo de um botão é phrasing, e um
+ * glifo e uma corrida de palavras são phrasing. Tudo o mais é bloco, e perguntar pelo complemento é o
+ * que impede a lista de esquecer um nome - foi assim que `heading`, `row` e `stack` ficaram fora da
+ * enumeração à mão do `elementFor` até 14/08, e uma raiz `action` com heading no topo saía como
+ * `<button><h3>…</h3></button>`.
+ */
+export const PHRASING_FORMS = ["icon", "text", "image"];

package/package.json

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