synthesisui 0.16.266 → 0.16.269

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/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/commands/mcp.js

@@ -3,6 +3,7 @@ import { readdir, readFile } from "node:fs/promises";
 import { join, relative, resolve } from "node:path";
 import { provenanceAction, toolSlug, withSource, } from "../agent-provenance.js";
 import { pinnedHookVersion } from "../agent-wiring.js";
+import { elementClass, kebabAxis } from "../component-codegen.js";
 import { composePlan, FAMILIES, isFamily, noFamilyAnswer, renderPlan, } from "../compose-context.js";
 import { readToken, resolveRegistry } from "../config.js";
 import { readEvents } from "../doctor/ledger.js";
@@ -11,6 +12,7 @@ import { diagnose, nameToWrite, scanSource } from "../doctor/scan.js";
 import { nearestToken, normalizeValue, tokenFor } from "../doctor/tokens.js";
 import { fromCensus } from "../memory/observation.js";
 import { handleRecall, handleRemember, MEMORY_TOOLS } from "../memory/tools.js";
+import { readInstalledConvention } from "../project-facts.js";
 import { repoStateOf } from "../repo-state.js";
 import { detectStack } from "../stack.js";
 import { component } from "./component.js";
@@ -974,7 +976,7 @@ query) {
     }
 }
 async function describeComponent(root, name) {
-    const { documents, requires } = await loadSystem(root);
+    const { documents, requires, table } = await loadSystem(root);
     let recipe;
     for (const doc of documents) {
         const d = doc;
@@ -1118,6 +1120,69 @@ async function describeComponent(root, name) {
     if (composes.length > 0) {
         out.push("", `Built out of: ${composes.join(", ")}. Change one of those in one place rather than reproducing it here, and call describe_component on it before you do.`);
     }
+    /**
+     * HOW TO DRESS IT - and it was the half this answer never carried.
+     *
+     * Measured on the owner's own census (21/08): his Button declares three axes -
+     * `variant` with eight options, `size` with four, `glow` with two - plus
+     * defaults, 32 layers and 78 properties. The whole reply for a component like
+     * that was its name, its description and "no rules govern this yet". An agent
+     * reading it composes without knowing `gold` exists, and nothing anywhere
+     * says an option was missed.
+     *
+     * The material was already here: `recipe.variants` is the SAME field the
+     * `GUIDE.md` reads to print `data-variant="primary|gold|…"`. Two surfaces
+     * answering one question, and only the file on disk answered it.
+     *
+     * The class comes from `readInstalledConvention`, never from a literal `ds-`:
+     * an imported system may carry its own prefix in `meta.classNames`, and
+     * telling the agent to write a class that does not exist is worse than
+     * telling it nothing.
+     */
+    const axes = Object.entries(recipe.variants ?? {});
+    if (axes.length > 0) {
+        const convention = await readInstalledConvention(root, String(table.slug ?? ""));
+        const cls = elementClass(name, convention);
+        out.push("", `How to dress it: \`${cls}\`, plus one data attribute per axis.`);
+        for (const [axis, options] of axes) {
+            const names = Object.keys(options ?? {});
+            if (names.length === 0)
+                continue;
+            const resting = recipe.defaults?.[axis];
+            /**
+             * O DEFAULT É O QUE ELE NÃO PRECISA ESCREVER, e dizer isso encurta o
+             * código que o agente produz em vez de só informá-lo.
+             */
+            const rest = resting
+                ? ` - at rest it is \`${resting}\`, so you can leave the attribute out`
+                : "";
+            out.push(`  data-${kebabAxis(axis)}="${names.join("|")}"${rest}`);
+        }
+        const states = Object.keys(recipe.states ?? {});
+        if (states.length > 0) {
+            out.push(`  states the recipe already carries: ${states.join(", ")} - they are CSS, so do not write them again in JS.`);
+        }
+        out.push(`  Or call add_component { "name": "${name}" } and get it as typed code, one prop per axis.`);
+    }
+    /**
+     * AS INSTRUÇÕES DE RENDER QUE A LEITURA MEDIU - e até aqui elas morriam no
+     * terminal.
+     *
+     * O CLI mede `renderNotes` por componente e imprime uma vez, no import. São
+     * 25 delas em 14 dos 59 componentes do dono, e uma diz: *"`ring` gates a look
+     * and is a boolean rather than an axis - `data-ring` has to be set for it to
+     * apply"*. Sem essa linha o agente escreve markup correto e o look nunca
+     * aparece, que é o pior modo de falhar - nada reclama.
+     *
+     * O princípio, e ele vale além destas notas: **interpretada ou não por nós,
+     * a instrução vai para quem constrói**. Uma nota que a esteira não soube
+     * transformar em regra continua sendo a coisa mais útil que existe sobre
+     * aquele componente.
+     */
+    const renderNotes = recipe.renderNotes ?? [];
+    if (renderNotes.length > 0) {
+        out.push("", "Read off your own code, and it decides whether the look appears:", ...renderNotes.map((n) => `  ${n}`));
+    }
     /**
      * WHAT IT NEEDS INSTALLED - the whole reason this tool earns its place.
      *

package/dist/component-codegen.js

@@ -4,8 +4,16 @@ export const DEFAULT_CONVENTION = {
     partSeparator: "-",
 };
 const kebab = (v) => v.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
-/** `metric-card` → `ds-metric-card`, or `metric-card`, or `sui-metric-card`. */
-const elementClass = (name, c) => `${c.prefix}${kebab(name)}`;
+/**
+ * `metric-card` → `ds-metric-card`, or `metric-card`, or `sui-metric-card`.
+ *
+ * EXPORTADA porque o `describe_component` passou a dizer ao agente qual classe
+ * escrever, e uma segunda implementação do mesmo nome é como as duas começam a
+ * divergir: o MCP mandaria escrever uma classe que este codegen não emite.
+ */
+export const elementClass = (name, c) => `${c.prefix}${kebab(name)}`;
+/** O mesmo kebab que decide a classe e o `data-*`, para quem precisa só do eixo. */
+export const kebabAxis = (v) => kebab(v);
 /** `metric-card` + `title` → `ds-metric-card-title`, or `metric-card__title`. */
 const partClassName = (name, part, c) => `${elementClass(name, c)}${c.partSeparator}${kebab(part)}`;
 const pascal = (name) => name

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/fonts.js

@@ -12,12 +12,31 @@ const GENERIC_FAMILIES = new Set([
     "inherit",
     "initial",
 ]);
-/** Famílias CUSTOM (display/body/mono), dedup e sem os genéricos. */
+/**
+ * TODA VAGA DE FONTE DO DOCUMENTO, dedup e sem os genéricos.
+ *
+ * Enumerava `[display, body, mono]` literalmente, e o documento passou a aceitar as famílias que o
+ * código DELE declara além das nossas três - `--font-serif` do codelevel é "Instrument Serif", 25 usos,
+ * reservada por ele para "editorial moments". O token existia, o compilador emitia
+ * `--ds-typography-families-serif`, e ninguém baixava a fonte: o texto saía no fallback do navegador e
+ * nada avisava. Um token que aponta para uma fonte que ninguém carregou é pior que um token ausente -
+ * o ausente pelo menos aparece na conta.
+ *
+ * A ORDEM É DETERMINÍSTICA: as três vagas primeiro, as dele em ordem alfabética. Isto vira href num
+ * arquivo gerado, e um conjunto que muda de ordem entre rodadas produz diff onde nada mudou.
+ */
+export const familySlots = (families) => {
+    const ours = ["display", "body", "mono"].filter((k) => k in families);
+    const theirs = Object.keys(families)
+        .filter((k) => !ours.includes(k))
+        .sort();
+    return [...ours, ...theirs];
+};
 export function customFontFamilies(families) {
     const seen = new Set();
     const names = [];
-    for (const family of [families.display, families.body, families.mono]) {
-        const name = family?.trim();
+    for (const slot of familySlots(families)) {
+        const name = families[slot]?.trim();
         if (!name)
             continue;
         const key = name.toLowerCase();
@@ -47,7 +66,8 @@ export function googleFontsHref(families) {
  * fallback - it works everywhere but swaps visibly on cold loads.
  */
 export function nextFontSnippet(families, slug, appDir = "app") {
-    const roles = ["display", "body", "mono"].filter((role) => {
+    /** Toda vaga que o documento tem, não só as nossas três - ver `customFontFamilies`. */
+    const roles = familySlots(families).filter((role) => {
         const name = families[role]?.trim();
         return name && !GENERIC_FAMILIES.has(name.toLowerCase());
     });
@@ -58,7 +78,7 @@ export function nextFontSnippet(families, slug, appDir = "app") {
     const importNames = [];
     const consts = [];
     for (const role of roles) {
-        const name = families[role].trim();
+        const name = (families[role] ?? "").trim();
         if (!seen.has(name)) {
             seen.set(name, role);
             importNames.push(importName(name));
@@ -81,13 +101,13 @@ export function nextFontSnippet(families, slug, appDir = "app") {
         ...consts,
     ];
     const roleVar = (role) => {
-        const name = families[role].trim();
+        const name = (families[role] ?? "").trim();
         return `--font-ds-${seen.get(name)}`;
     };
     const layout = [
         `// ${appDir}/layout.tsx`,
-        `import { ${[...new Set(roles.map((r) => seen.get(families[r].trim())))].join(", ")} } from "./fonts";`,
-        `<body data-ds="${slug}" className={\`${[...new Set(roles.map((r) => `\${${seen.get(families[r].trim())}.variable}`))].join(" ")}\`}>`,
+        `import { ${[...new Set(roles.map((r) => seen.get((families[r] ?? "").trim())))].join(", ")} } from "./fonts";`,
+        `<body data-ds="${slug}" className={\`${[...new Set(roles.map((r) => `\${${seen.get((families[r] ?? "").trim())}.variable}`))].join(" ")}\`}>`,
     ];
     const css = [
         `/* ${appDir}/globals.css - AFTER the tokens.css import */`,

package/dist/guide.js

@@ -1,4 +1,12 @@
-import { nextFontSnippet } from "./fonts.js";
+/**
+ * UMA IMPLEMENTAÇÃO SÓ, e este arquivo tinha a terceira.
+ *
+ * `customFontFamilies` existia aqui, em `fonts.ts` e em `ds-font-link.tsx` - três cópias de um
+ * julgamento, e as três enumeravam `[display, body, mono]`. Quando o documento passou a aceitar as
+ * famílias que o código dele declara, as três deixaram de carregar a fonte ao mesmo tempo. Este
+ * arquivo já importava `nextFontSnippet` do mesmo módulo; a cópia não tinha razão de existir.
+ */
+import { customFontFamilies, familySlots, nextFontSnippet } from "./fonts.js";
 import { animationShorthand, classifyKeyframe, describeKeyframe, isFullRotation, } from "./motion.js";
 const kebab = (v) => v.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
 /**
@@ -25,21 +33,6 @@ const GENERIC_FAMILIES = new Set([
     "initial",
 ]);
 /** Famílias custom do documento (display/body/mono), deduplicadas, sem genéricos. */
-function customFontFamilies(families) {
-    const seen = new Set();
-    const out = [];
-    for (const family of [families.display, families.body, families.mono]) {
-        const name = family?.trim();
-        if (!name)
-            continue;
-        const key = name.toLowerCase();
-        if (GENERIC_FAMILIES.has(key) || seen.has(key))
-            continue;
-        seen.add(key);
-        out.push(name);
-    }
-    return out;
-}
 /**
  * THE STRUCTURE, WITH WHAT EACH PART IS FOR AND WHEN IT EXISTS.
  *
@@ -269,6 +262,14 @@ export function buildGuide(payload) {
     const { document: doc, slug, name, version } = payload;
     const { meta, foundations, motion, components } = doc;
     const semanticRoles = Object.keys(foundations.color.semantic);
+    /**
+     * AS CORES QUE ELE NOMEIA POR PROPÓSITO, no arquivo que o agente lê primeiro.
+     *
+     * O compilador passou a emitir `--ds-color-tier-gold` e o `find_token` já as acha (ele lê o
+     * `tokens.css`), mas o GUIDE é onde o agente descobre o vocabulário ANTES de perguntar - e ele não
+     * as mencionava. São 19 no censo do dono, e são a parte que faz o sistema dele ser dele.
+     */
+    const namedColours = Object.keys(foundations.color.named ?? {});
     const seriesKeys = Object.keys(foundations.color.series ?? {});
     const fontFamilies = customFontFamilies(foundations.typography.families);
     const fontsHref = fontFamilies.length > 0
@@ -680,13 +681,17 @@ ${hasTailwind
 - **Always use semantic tokens**, never raw values nor primitives directly.
   Color: \`var(--ds-color-semantic-<role>)\`${hasTailwind ? " (utility: `bg-<role>`/`text-<role>`)" : ""}. The roles are: ${list(semanticRoles)}.
 - Primitives (\`--ds-color-<palette>-<step>\`) exist but should **not** be referenced directly -
-  they feed the semantic roles.${seriesKeys.length > 0
+  they feed the semantic roles.${namedColours.length > 0
+        ? `\n- **Yours by name** → \`var(--ds-color-<name>)\`: ${namedColours.length} colour${namedColours.length === 1 ? "" : "s"} your code names by PURPOSE rather than by step, so no scale could hold ${namedColours.length === 1 ? "it" : "them"} - ${list(namedColours.slice(0, 8))}${namedColours.length > 8 ? ", …" : ""}. These are yours: reach for them when the purpose matches, and prefer a semantic role when it does not.`
+        : ""}${seriesKeys.length > 0
         ? `\n- Data-viz → \`var(--ds-color-series-<n>)\`${hasTailwind ? " (utility: `bg-series-<n>`/`text-series-<n>`/`fill-series-<n>`)" : ""}: categorical chart/series colors, ${seriesKeys.length} of them (${list(seriesKeys)}). Use them in order for multi-series charts; they re-paint with the system.`
         : ""}
 - Spacing → \`var(--ds-spacing-<key>)\`: ${list(Object.keys(foundations.spacing))}.
 - Radius → \`var(--ds-radius-<key>)\`: ${list(Object.keys(foundations.radius))}.
 - Shadow → \`var(--ds-shadow-<key>)\`: ${list(Object.keys(foundations.shadow))}.
-- Typography: families \`--ds-typography-families-{display,body,mono}\` (${foundations.typography.families.display}, ${foundations.typography.families.body}, ${foundations.typography.families.mono});
+- Typography: families ${familySlots(foundations.typography.families)
+        .map((slot) => `\`--ds-typography-families-${slot}\` (${foundations.typography.families[slot]})`)
+        .join(", ")};
   weights${hasTailwind ? " (utility: `font-<key>`)" : ""}: ${list(weights)};
   scale \`--ds-typography-scale-<key>-font-size\`${hasTailwind ? " (utility: `text-<key>`)" : ""}: ${list(Object.keys(foundations.typography.scale))}.
 - Motion: durations \`--ds-motion-durations-<key>\` (${list(Object.keys(motion.durations))}) and

package/dist/install-marks.js

@@ -115,7 +115,7 @@
  * O índice de componentes é BYTE-IDÊNTICO nos dois caminhos - mesma fonte canônica, mesmos nomes,
  * mesma quantidade (`claude-md.f0.spec.ts`). O corte troca uma frase, nunca o inventário.
  */
-export const MATERIALISER_SINCE = "0.16.265";
+export const MATERIALISER_SINCE = "0.16.269";
 /**
  * A ÚLTIMA VERSÃO EM QUE O QUE O HOOK RODA MUDOU.
  *

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.266",
+  "version": "0.16.269",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {