synthesisui 0.16.265 → 0.16.268

package/dist/anatomy-patch.js

@@ -0,0 +1,62 @@
+/** Um patch que não diz nada não é um patch - e distinguir isso de `undefined` importa. */
+export function hasEdits(patch) {
+    return Boolean((patch?.names?.length ?? 0) > 0 || (patch?.fold?.length ?? 0) > 0);
+}
+/**
+ * O PATCH APLICADO SOBRE A ÁRVORE DERIVADA - e ela é a fonte, não o rascunho.
+ *
+ * Idempotente por construção: aplicar duas vezes o mesmo patch dá o mesmo resultado, porque a
+ * operação é indexada por `at` e não acumula.
+ *
+ * O que um índice desconhecido faz: NADA, e em silêncio é errado. Quem chama recebe a lista dos
+ * índices que não existiam, para dizer em voz alta - um nome escrito para um nó que a derivação não
+ * produziu é uma decisão perdida, e perder calado é o defeito que a lei 8 proíbe.
+ */
+export function applyAnatomyPatch(read, patch) {
+    const byAt = new Map();
+    for (const n of patch.names ?? [])
+        byAt.set(n.at, n.name);
+    const fold = new Set(patch.fold ?? []);
+    const seen = new Set();
+    let renamed = 0;
+    let folded = 0;
+    const walk = (nodes) => {
+        const out = [];
+        for (const node of nodes) {
+            const at = typeof node.at === "number" ? node.at : null;
+            if (at !== null)
+                seen.add(at);
+            const children = Array.isArray(node.children) ? walk(node.children) : [];
+            /**
+             * DOBRAR SOBE OS FILHOS. Um nó dobrado que era uma FRONTEIRA não some: `component` e
+             * `external` são o que o cliente declarou, e a Lei "o código deles vence" não abre exceção
+             * para economia nossa.
+             */
+            if (at !== null &&
+                fold.has(at) &&
+                node.as !== "component" &&
+                node.as !== "external") {
+                folded += 1;
+                out.push(...children);
+                continue;
+            }
+            const name = at !== null ? byAt.get(at) : undefined;
+            if (name !== undefined && name !== node.name)
+                renamed += 1;
+            out.push({
+                ...node,
+                ...(name !== undefined ? { name } : {}),
+                ...(children.length > 0 ? { children } : {}),
+            });
+        }
+        return out;
+    };
+    const patched = walk(read);
+    const asked = [...byAt.keys(), ...fold];
+    return {
+        read: patched,
+        renamed,
+        folded,
+        unknown: [...new Set(asked.filter((at) => !seen.has(at)))].sort((a, b) => a - b),
+    };
+}

package/dist/color-forms.js

@@ -0,0 +1,180 @@
+/**
+ * TODA FORMA DE COR, REDUZIDA A UMA - e sem isto o detector via duas cores onde há uma.
+ *
+ * O QUÊ: `#fff`, `#ffffff`, `rgb(255 255 255)` e `rgba(255,255,255,1)` passam a ser o mesmo valor, e
+ * uma cor com alfa passa a ser dita como *"o seu token com N% de opacidade"* em vez de uma cor nova.
+ *
+ * POR QUÊ: medido no `codelevel-ds` em 21/08 e é literal - o leitor gravou `#fff` do código-fonte e a
+ * receita compilada carrega `#ffffff`. **Para um detector que compara string são duas cores**, então o
+ * branco pintado **43 vezes** nas receitas dele nunca apareceu na lista de "valores que o seu sistema
+ * nunca nomeou". E as maiores órfãs dele são `rgba(15,23,42,0.30)` e `rgba(192,132,252,0.18)`, que o
+ * filtro de `#hex` descartava inteiras.
+ *
+ * A meta é 100% de cobertura das receitas (dono, 21/08), e ela não sobrevive a um comparador de
+ * string.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * O ALFA É SEPARADO DO RGB, e essa é a decisão que impede poluir o vocabulário dele
+ *
+ * `rgba(37,99,235,0.5)` tem duas leituras possíveis e só ele sabe qual é: *"uma cor nova"* ou *"o meu
+ * `brand-blue` com metade da opacidade"*. Guardar o alfa à parte é o que permite a segunda: o RGB
+ * casa com um token que ele já declara, e a tela diz **opacidade** em vez de sugerir um nome novo.
+ * Sem isso, cada nível de transparência de uma mesma cor pediria um token próprio.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * O QUE ESTE MÓDULO NÃO FAZ, e é declarado em vez de fingido
+ *
+ * `color-mix(in srgb, #fff 40%, transparent)` é uma FUNÇÃO de composição, não um valor: resolvê-la
+ * exige o espaço de cor e o segundo operando, e chutar produziria um valor que o navegador nunca
+ * pinta. O que este módulo faz é EXTRAIR as cores literais de dentro dela, que é o que permite dizer
+ * *"esta mistura usa um branco que nada nomeia"* sem afirmar a cor resultante.
+ *
+ * `currentColor`, `transparent`, `inherit` e nome de cor CSS não entram: os três primeiros não são
+ * decisão de paleta, e um nome CSS (`rebeccapurple`) é raro o bastante para não valer uma tabela de
+ * 148 entradas que envelhece.
+ */
+const clamp255 = (n) => Math.max(0, Math.min(255, Math.round(n)));
+const hex2 = (n) => clamp255(n).toString(16).padStart(2, "0");
+/** `#f0a` -> `#ff00aa`, e `#ff00aa80` devolve o alfa junto. */
+function fromHex(raw) {
+    const h = raw.trim().replace(/^#/, "");
+    if (!/^[0-9a-f]{3,8}$/i.test(h))
+        return null;
+    const dup = (s) => s
+        .split("")
+        .map((c) => c + c)
+        .join("");
+    if (h.length === 3 || h.length === 4) {
+        const [r, g, b, a] = dup(h).match(/../g);
+        return {
+            hex: `#${r}${g}${b}`.toLowerCase(),
+            alpha: a === undefined ? 1 : Number.parseInt(a, 16) / 255,
+        };
+    }
+    if (h.length === 6)
+        return { hex: `#${h}`.toLowerCase(), alpha: 1 };
+    if (h.length === 8)
+        return {
+            hex: `#${h.slice(0, 6)}`.toLowerCase(),
+            alpha: Number.parseInt(h.slice(6, 8), 16) / 255,
+        };
+    return null;
+}
+/** `50%` -> 0.5 · `.5` -> 0.5 · `1` -> 1. Serve alfa e componente percentual. */
+const unit = (raw, of = 1) => {
+    const t = raw.trim();
+    if (t.endsWith("%")) {
+        const n = Number.parseFloat(t);
+        return Number.isFinite(n) ? (n / 100) * of : Number.NaN;
+    }
+    const n = Number.parseFloat(t);
+    return Number.isFinite(n) ? n : Number.NaN;
+};
+/** `rgb(255 0 0 / 50%)` e `rgba(255,0,0,.5)` - a sintaxe moderna e a legada. */
+function fromRgb(raw) {
+    const m = /^rgba?\(([^)]*)\)$/i.exec(raw.trim());
+    if (!m)
+        return null;
+    const [body, alphaPart] = m[1].split("/");
+    const parts = body
+        .trim()
+        .split(/[\s,]+/)
+        .filter(Boolean);
+    if (parts.length < 3)
+        return null;
+    const [r, g, b] = parts.slice(0, 3).map((p) => unit(p, 255));
+    if (![r, g, b].every(Number.isFinite))
+        return null;
+    /** O alfa vem depois da barra na sintaxe moderna, ou como quarto item na legada. */
+    const rawAlpha = alphaPart ?? parts[3];
+    const alpha = rawAlpha === undefined ? 1 : unit(rawAlpha);
+    return {
+        hex: `#${hex2(r)}${hex2(g)}${hex2(b)}`,
+        alpha: Number.isFinite(alpha) ? Math.max(0, Math.min(1, alpha)) : 1,
+    };
+}
+/** `hsl(210 40% 50%)` e `hsla(210,40%,50%,.5)`. */
+function fromHsl(raw) {
+    const m = /^hsla?\(([^)]*)\)$/i.exec(raw.trim());
+    if (!m)
+        return null;
+    const [body, alphaPart] = m[1].split("/");
+    const parts = body
+        .trim()
+        .split(/[\s,]+/)
+        .filter(Boolean);
+    if (parts.length < 3)
+        return null;
+    const h = ((Number.parseFloat(parts[0]) % 360) + 360) % 360;
+    const s = unit(parts[1]);
+    const l = unit(parts[2]);
+    if (![h, s, l].every(Number.isFinite))
+        return null;
+    const c = (1 - Math.abs(2 * l - 1)) * s;
+    const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
+    const mm = l - c / 2;
+    const seg = Math.floor(h / 60) % 6;
+    const table = [
+        [c, x, 0],
+        [x, c, 0],
+        [0, c, x],
+        [0, x, c],
+        [x, 0, c],
+        [c, 0, x],
+    ];
+    const [r, g, b] = table[seg].map((v) => (v + mm) * 255);
+    const rawAlpha = alphaPart ?? parts[3];
+    const alpha = rawAlpha === undefined ? 1 : unit(rawAlpha);
+    return {
+        hex: `#${hex2(r)}${hex2(g)}${hex2(b)}`,
+        alpha: Number.isFinite(alpha) ? Math.max(0, Math.min(1, alpha)) : 1,
+    };
+}
+/**
+ * QUALQUER FORMA -> a canônica. `null` para o que não é uma cor literal.
+ *
+ * Palavra-chave fica fora de propósito: `transparent` e `currentColor` não são decisão de paleta, e um
+ * token para elas seria vocabulário que ninguém procura.
+ */
+export function colorForm(value) {
+    const v = value.trim();
+    if (!v || /^(transparent|currentcolor|inherit|initial|unset|none)$/i.test(v))
+        return null;
+    return fromHex(v) ?? fromRgb(v) ?? fromHsl(v);
+}
+/**
+ * AS CORES LITERAIS DENTRO DE UM VALOR - inclusive as de dentro de uma função de composição.
+ *
+ * Um `boxShadow` carrega a cor no meio de offsets (`0 2px 4px rgba(0,0,0,.02)`), e um `color-mix`
+ * carrega duas. Comparar o valor inteiro contra uma paleta nunca casaria; extrair as cores casa.
+ *
+ * A ordem de varredura é a das formas mais longas primeiro (`rgba(` antes de `#`), senão um hex dentro
+ * de um `color-mix` seria contado duas vezes - uma pela função e outra por ele mesmo.
+ */
+export function colorsIn(value) {
+    const out = [];
+    const seen = new Set();
+    const push = (c) => {
+        if (!c)
+            return;
+        const key = `${c.hex}|${c.alpha}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        out.push(c);
+    };
+    const rest = value.replace(/\b(?:rgba?|hsla?)\([^)]*\)/gi, (m) => (push(colorForm(m)), " "));
+    for (const m of rest.match(/#[0-9a-f]{3,8}\b/gi) ?? [])
+        push(colorForm(m));
+    return out;
+}
+/**
+ * A COMPARAÇÃO "É O MEU TOKEN COM ALFA?" NÃO MORA AQUI, e a razão é o `reachable`.
+ *
+ * Escrevi um `sameHue(a, b)` e ele nasceu órfão: quem faz essa pergunta - `v2-proposal` - precisa
+ * responder para uma PALETA inteira, e um mapa de hex canônico -> token responde em O(1) onde uma
+ * comparação par a par pediria uma varredura. O helper era mais bonito e menos útil.
+ *
+ * O que este módulo entrega para aquela pergunta é o `hex` canônico separado do `alpha`, que é a parte
+ * difícil. Comparar hex é `===`.
+ */

package/dist/commands/connect.js

@@ -225,10 +225,16 @@ export async function connect(opts) {
      * Custou tempo de gente de verdade: 20/08, `codelevel-monorepo`. Rodou `connect`, conferiu o
      * `CLAUDE.md`, achou o bloco vazio, e não havia nada dizendo que faltava um comando. Lacuna
      * silenciosa é o que faz um produto correto parecer quebrado.
+     *
+     * E SÃO DOIS CAMINHOS, não um. A primeira versão desta mensagem mandava `add <slug>` e só - o que
+     * desorienta justamente quem acabou de rodar `connect` num projeto que AINDA NÃO TEM sistema, que é
+     * a primeira corrida e o caso mais comum. Para essa pessoa o passo seguinte é a skill que este mesmo
+     * comando acabou de instalar, e não um comando de terminal. Quem já tem sistema na plataforma é o
+     * outro caso, e ele também é dito.
      */
     const anyInstalled = (await installedSlugs(root).catch(() => [])).length > 0;
     if (!anyInstalled)
-        console.log(body("· no design system installed here yet - `synthesisui list` shows yours, and `synthesisui add <slug>` brings one in. Until then the agent has no index and memory has nothing to belong to."));
+        console.log(body("· no design system installed here yet - the agent has no index, and memory has nothing to belong to.\n  This repo has none yet:  ask the agent for `/sui-init`, or `/sui-import-ds` to turn this project into one.\n  You already have one:     `synthesisui list` shows them, `synthesisui add <slug>` brings it in."));
     /**
      * O QUE ESTE CLI REESCREVEU NA PASTA DO SISTEMA - dito primeiro, porque é o que a pessoa não sabia
      * que estava devendo. Ela rodou `connect` para atualizar a fiação; os arquivos do install estarem

package/dist/commands/import.js

@@ -1,6 +1,7 @@
 import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
 import { basename, dirname, join, relative } from "node:path";
 import { anatomyFromSketch } from "../anatomy-from-sketch.js";
+import { applyAnatomyPatch, hasEdits, } from "../anatomy-patch.js";
 import { resolveAnatomy, resolveFlatParts, safePartName, } from "../anatomy-read.js";
 import { readCredentials, readToken, resolveRegistry, sameRegistry, } from "../config.js";
 import { declaredElsewhere } from "../declared-elsewhere.js";
@@ -3101,16 +3102,37 @@ quiet = false) {
                 ? (entry?.root).at
                 : undefined)
             : anatomy;
+        /**
+         * A DERIVAÇÃO COM O PATCH DO AGENTE POR CIMA - a fonte é o CLI, a decisão é dele.
+         *
+         * A ordem das três é deliberada: anatomia autoral vence (ela sempre venceu), depois a derivada
+         * COM patch, depois a derivada crua. Um patch sobre uma árvore que não existe não tem onde
+         * aplicar, então ele só é consultado quando há derivação.
+         *
+         * O que sai daqui é `AnatomyRead[]` nos três casos - por isso `resolveAnatomy`, `censusToPatch`,
+         * o codegen e o Canvas não sabem que o patch existe.
+         */
+        const patched = derived && derived.read.length > 0 && hasEdits(entry?.patch)
+            ? applyAnatomyPatch(derived.read, entry?.patch)
+            : null;
+        if (patched && patched.unknown.length > 0)
+            /**
+             * DITO, NUNCA ENGOLIDO: um nome escrito para um nó que a derivação não produziu é uma decisão
+             * perdida, e o agente precisa saber que a perdeu para escrevê-la onde ela cabe.
+             */
+            notes.add(`${component}: the anatomy patch named ${patched.unknown.length} node${patched.unknown.length === 1 ? "" : "s"} the derivation does not have (sketch ${patched.unknown.join(", ")}) - those names were dropped`);
         const resolved = Array.isArray(framed) && framed.length > 0
             ? resolveAnatomy(framed, declared, deps, resolveRef, entry?.root, 
             // The component's own sketch, so a node naming itself by index reads
             // the exact class string the census measured (dono, 01/08).
             looks[component]?.sketch, census.sxSpacing)
-            : derived && derived.read.length > 0
-                ? resolveAnatomy(derived.read, declared, deps, resolveRef, entry?.root, looks[component]?.sketch, census.sxSpacing)
-                : Array.isArray(entry?.parts) && entry.parts.length > 0
-                    ? resolveFlatParts(entry.parts, declared)
-                    : null;
+            : patched
+                ? resolveAnatomy(patched.read, declared, deps, resolveRef, entry?.root, looks[component]?.sketch, census.sxSpacing)
+                : derived && derived.read.length > 0
+                    ? resolveAnatomy(derived.read, declared, deps, resolveRef, entry?.root, looks[component]?.sketch, census.sxSpacing)
+                    : Array.isArray(entry?.parts) && entry.parts.length > 0
+                        ? resolveFlatParts(entry.parts, declared)
+                        : null;
         if (!resolved)
             continue;
         const hasParts = Object.keys(resolved.parts).length > 0;

package/dist/doctor/color-distance.js

@@ -1,3 +1,4 @@
+import { colorForm } from "../color-forms.js";
 /**
  * PERCEPTUAL COLOUR DISTANCE, in the CLI.
  *
@@ -18,20 +19,40 @@
  * exactly the evidence the normalisation pass is looking for. With this, a rare
  * value rides along when it sits close to one we already kept.
  */
-const HEX6 = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i;
 /** The just-noticeable difference for ΔE76. Same constant as the platform's. */
 export const JND = 2.3;
-function toRgb(hex) {
-    const h = hex.trim().replace("#", "");
-    if (!HEX6.test(`#${h}`))
+/**
+ * QUALQUER FORMA DE COR -> RGB, e é aqui que o motor deixou de ser hex-only (21/08).
+ *
+ * O QUÊ: `rgb(79 70 229)` e `hsl(0 0% 100%)` são cor, e este motor devolvia `null` para as duas.
+ *
+ * POR QUÊ, medido: num projeto que declara a paleta em `rgb`/`hsl`, `deltaE` devolvia `null` para todo
+ * par, o que reconhecia **0 de 2** tokens dele - e a consequência era o oposto do propósito do
+ * produto: propor NOME NOVO para as duas cores que ele já nomeia. A ferramenta cunhando exatamente a
+ * duplicata que existe para retirar. Não é caso exótico: é o que Tailwind 4 emite em `@theme` e o que
+ * qualquer projeto de CSS Modules escreve à mão.
+ *
+ * COMO: `colorForm` já sabe ler hex 3/6/8, `rgb`/`rgba` (legado e moderno) e `hsl`/`hsla`, então a
+ * conversão passa por ela em vez de por um regex próprio. `src/color-forms.ts` é byte-idêntico ao
+ * `apps/web/src/lib/engine/color-forms.ts`, garantido por spec - o CLI publica standalone e não pode
+ * importar do app.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * TRANSLÚCIDO CONTINUA FORA, e isso é deliberado
+ *
+ * `rgba(0,0,0,.02)` e `#000000` têm o mesmo RGB e aparências opostas. Aceitar o alfa aqui faria o
+ * agrupamento dobrar um véu de 2% dentro de um preto sólido com ΔE 0 - "a mesma decisão", que é
+ * falso. Um valor translúcido é *"o token dele com alfa"* (decisão 4 do dono, 21/08), e quem trata
+ * disso é a lista de opacidades da proposta, não a distância perceptual.
+ *
+ * Então: alfa < 1 devolve `null`, exatamente como antes - o hex de 8 dígitos e o `rgba` já caíam fora
+ * por não casarem o regex. O que muda é só a cor OPACA escrita em outra forma.
+ */
+function toRgb(value) {
+    const form = colorForm(value);
+    if (!form || form.alpha < 1)
         return null;
-    const full = h.length === 3
-        ? h
-            .split("")
-            .map((c) => c + c)
-            .join("")
-        : h;
-    const n = Number.parseInt(full, 16);
+    const n = Number.parseInt(form.hex.slice(1), 16);
     if (Number.isNaN(n))
         return null;
     return [(n >> 16) & 255, (n >> 8) & 255, n & 255];

package/dist/naming-queue.js

@@ -1,6 +1,39 @@
 import { anatomyFromSketch } from "./anatomy-from-sketch.js";
 /** O nó que a derivação não soube nomear. `box` é o último recurso dela. */
 const UNNAMED = "box";
+/**
+ * O ENCANAMENTO, RECONHECIDO POR REGRA - e ele sai da fila sem sair da árvore.
+ *
+ * O playbook já enuncia a regra: *"What you still collapse is a wrapper whose only job is `flex` -
+ * fold it into the `row` it already is, because that is not a region, it is plumbing."* E a Lei 12 já
+ * lê `flex-col`/`grid`/`flex` do class string em `arrangement()`, então **a informação de layout já
+ * viaja**. Pedir um nome para um `div` cujo class list inteiro é `mt-5` é pedir uma decisão de modelo
+ * que não acrescenta nada ao que o cliente recebe.
+ *
+ * PADDING NÃO É ENCANAMENTO, e a medição é o que decidiu. `p-4` num modal É o corpo dele; `space-y-3
+ * p-4` num cartão É o miolo. Margem, `gap` e `flex` movem o nó no pai e não desenham caixa nenhuma;
+ * padding cria uma área interna, que é exatamente o que uma região "body" parece.
+ *
+ * O custo de ser conservador é pequeno e foi medido, não suposto: dos 757 nós da fila em
+ * `apps/web-dashboard`, **311 são só arranjo** e 3 não têm classe, contra **12 de padding puro** e 35
+ * de arranjo+padding. Excluir padding custa 47 nós e preserva 47 regiões de verdade.
+ *
+ * Foi o fixture do próprio spec que levantou a dúvida - `p-[1rem] pr-[2rem] pl-[2rem]`, do
+ * `SubscribeSetting` real - e ele continua sendo cobrado, porque continua sendo uma região.
+ *
+ * NADA É RENOMEADO. O nó continua na árvore com o `box` que a derivação lhe deu, e `part` continua
+ * saindo igual - inclusive o sufixo `-2`. Renomear seria mudar chave de `part` no documento do
+ * cliente, que é referenciada por codegen e por override dele: um ganho de tempo nosso não paga isso.
+ *
+ * A RÉGUA É CONSERVADORA NO LADO CERTO: qualquer classe de APARÊNCIA mantém o nó na fila.
+ * `w-full bg-darkgray-800/95 absolute h-full` sobrevive por causa do `bg-`; o que cai é `mt-5`.
+ */
+const PLUMBING = /^(?:m[trblxy]?-|space-[xy]-|gap(?:-[xy])?-|flex$|flex-|grid$|grid-|items-|justify-|self-|content-|place-|w-full$|h-full$|min-[wh]-|max-[wh]-|relative$|absolute$|static$|block$|inline(?:-|$)|shrink|grow|order-|col-|row-|basis-)/;
+/** Só encanamento, ou nenhuma classe: os dois casos são estrutura sem aparência. */
+function isPlumbing(classes) {
+    const words = (classes ?? "").trim().split(/\s+/).filter(Boolean);
+    return words.every((w) => PLUMBING.test(w));
+}
 function walk(read, onNode) {
     for (const node of read) {
         onNode(node);
@@ -21,6 +54,7 @@ export function namingQueue(looks, defines, versionOf) {
     let nodes = 0;
     let named = 0;
     let settled = 0;
+    let plumbing = 0;
     for (const component of Object.keys(looks)) {
         const sketch = looks[component]?.sketch;
         if (!Array.isArray(sketch) || sketch.length === 0)
@@ -40,6 +74,14 @@ export function namingQueue(looks, defines, versionOf) {
             if (typeof at !== "number")
                 return;
             const raw = sketch[at];
+            /**
+             * Encanamento não entra na fila, e é CONTADO - senão a diferença entre "não havia trabalho" e
+             * "a régua o dispensou" fica invisível, e um número que ninguém explica é pior que nenhum.
+             */
+            if (isPlumbing(raw?.classes)) {
+                plumbing += 1;
+                return;
+            }
             unnamed.push({
                 tag: raw?.tag ?? "div",
                 at,
@@ -52,5 +94,5 @@ export function namingQueue(looks, defines, versionOf) {
         }
         pending.push({ component, nodes: unnamed });
     }
-    return { components, nodes, named, settled, pending };
+    return { components, nodes, named, settled, plumbing, pending };
 }

package/package.json

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