synthesisui 0.16.390 → 0.16.395

package/dist/absorb-plan.js

@@ -10,7 +10,11 @@ const HOME = {
 };
 /** Uma palavra de categoria no começo do nome deles não é família - é a categoria repetida. */
 const CATEGORY = /^(color|colour|radius|rounded|spacing|space|gap|font|type|text|duration|motion|ease|easing)-/;
-const clean = (name) => name.replace(/^--/, "").toLowerCase();
+/**
+ * O nome sem o sigilo. `$` e `@` entram porque o vocabulário dele pode estar num pré-processador -
+ * um `$gray_dark` que mantivesse o `$` viraria o caminho `color.$gray.dark`, que não é um caminho.
+ */
+const clean = (name) => name.replace(/^(--|[$@])/, "").toLowerCase();
 /**
  * QUAL DOS NOMES DELE, quando mais de um segura o mesmo valor - e aqui a natureza do ACHADO decide.
  *
@@ -105,7 +109,31 @@ function nearestOwn(theirs, literal, kind) {
  * existente com outro valor - isso não é absorver, é repintar.
  */
 export function absorbPlan(d, theirs, have, cap = 40) {
-    const unnamed = d.repeats.filter((r) => !r.token);
+    /**
+     * A REPETIÇÃO É UM FILTRO DE RUÍDO, E RUÍDO É UMA PROPRIEDADE DA ESCALA - não do valor.
+     *
+     * Ordenar por repetição está certo onde a deriva se concentra: no `~/projects/web-subscribe` são
+     * 858 valores distintos escritos à mão, e mostrar os 40 mais repetidos é o que transforma isso numa
+     * fila de trabalho. Num projeto que acabou de nascer, o mesmo corte apaga o projeto inteiro.
+     *
+     * Medido em 07/09 sobre três populações:
+     *
+     *     ~/projects/web-subscribe   858 distintos   484 repetidos   362 apareciam uma vez só
+     *     ~/projects/web-onboarding   52 distintos    21 repetidos    29 apareciam uma vez só
+     *     create-next-app real          4 distintos     0 repetidos     4 apareciam uma vez só
+     *
+     * Naquele último o `absorb` respondia que não havia nada a absorver, três linhas depois de o
+     * `doctor` dizer *"0 of 4 have a name waiting"*.
+     *
+     * A REGRA SAI DO TETO QUE JÁ EXISTE, e por isso não é mais um número escolhido por nós: o corte
+     * serve para ESCOLHER quando não cabe tudo. Quando tudo cabe, não há o que escolher, e esconder
+     * metade é esconder por hábito. Num repositório grande nada muda - 484 já estouram o teto sozinhos.
+     */
+    const repeated = d.repeats.filter((r) => !r.token);
+    const single = d.once.filter((r) => !r.token);
+    const unnamed = repeated.length + single.length <= cap
+        ? [...repeated, ...single]
+        : repeated;
     const entries = [];
     for (const r of unnamed) {
         if (entries.length >= cap)
@@ -133,7 +161,25 @@ export function absorbPlan(d, theirs, have, cap = 40) {
          * `var(--dashboard-white-500)` e o `absorb`, no mesmo dia, pedia que ele batizasse `#fff`. Dois
          * comandos com conselhos opostos sobre o mesmo valor.
          */
-        const theirName = nameOf(r.kind, theirs.byValue.get(normalizeValue(r.literal, theirs.rootPx)));
+        /**
+         * O NOME DELE VEM DAS DUAS FORMAS - e sem a segunda os dois comandos voltam a se contradizer.
+         *
+         * É o mesmo defeito que esta função já corrigiu uma vez, reaberto por outro caminho: o `doctor`
+         * passou a dizer *"#555 · your code calls it $gray_dark"* e o `absorb`, no mesmo repositório,
+         * pedia que ele batizasse o `#555`. Dois comandos com conselhos opostos sobre o mesmo valor.
+         *
+         * A ORDEM É A MESMA DO RESTO DA ESTEIRA: primeiro o nome que o navegador recebe, e só depois o
+         * que o pré-processador resolve. Onde ele nomeia nas duas formas, ganha a custom property.
+         *
+         * E aqui o nome compilado NÃO é um beco: o caminho que sai dele vira um token de verdade na
+         * fundação, que o navegador recebe - então as ocorrências em `.tsx`, que nunca poderiam receber
+         * um `$`, ficam trocáveis pelo caminho que já existe (`absorb` -> `upgrade` -> `doctor --fix`).
+         * Medido em 07/09 no `~/projects/web-subscribe`: 323 ocorrências têm nome dele, e só 52 delas
+         * estão num arquivo que poderia escrever o `$` diretamente.
+         */
+        const value = normalizeValue(r.literal, theirs.rootPx);
+        const theirName = nameOf(r.kind, theirs.byValue.get(value)) ??
+            nameOf(r.kind, theirs.compiledAway.get(value)?.map((c) => c.name));
         const path = pathFor(r.kind, theirName);
         /** "≈ perto de um token seu" só interessa a quem não tem um EXATO - com o nome na mão, a dica
          *  vira ruído, e no arquivo de proposta ela vira uma segunda opção que não é opção. */
@@ -151,7 +197,11 @@ export function absorbPlan(d, theirs, have, cap = 40) {
             ...(near ? { near } : {}),
         });
     }
-    return { entries, more: Math.max(0, unnamed.length - entries.length) };
+    return {
+        entries,
+        more: Math.max(0, unnamed.length - entries.length),
+        unnamed: d.repeats.length + d.once.length,
+    };
 }
 /** Quantas linhas da proposta ainda precisam de um nome humano. */
 export const needingName = (plan) => plan.entries.filter((e) => !e.path);
@@ -166,9 +216,21 @@ export function describeAbsorb(plan) {
     const ready = plan.entries.filter((e) => e.path);
     const pending = needingName(plan);
     const lines = [];
+    /**
+     * VAZIO POR DOIS MOTIVOS OPOSTOS, e a frase afirmava só um.
+     *
+     * "every repeated value already has a name" é notícia boa. Mas a lista também fica vazia quando não
+     * há valor NENHUM escrito à mão - e aí a frase de cima descreve um repositório que não é o dele.
+     * Medido em 07/09 numa cópia de `create-next-app`: 4 valores sem nome, e esta era a resposta.
+     *
+     * A distinção não é cosmética: um manda seguir em frente, o outro diz que o comando não tem
+     * trabalho porque o projeto não tem deriva. Duas conversas diferentes.
+     */
     if (plan.entries.length === 0)
         return [
-            "Nothing to absorb: every repeated value your code writes by hand already has a name in the system.",
+            plan.unnamed > 0
+                ? `Nothing to absorb here: the ${plan.unnamed} value${plan.unnamed === 1 ? "" : "s"} written by hand ${plan.unnamed === 1 ? "already has" : "already have"} a name in your system.`
+                : "Nothing to absorb: no design value in this project is written by hand.",
         ];
     /**
      * A SEÇÃO DOS QUE JÁ TÊM NOME SÓ EXISTE SE ALGUM TIVER - e no dia 1 nenhum tem.
@@ -187,9 +249,18 @@ export function describeAbsorb(plan) {
         const close = pending.filter((e) => e.near);
         if (ready.length > 0)
             lines.push("");
+        /**
+         * "REPEATED" SÓ QUANDO ELES SE REPETEM - e desde que o corte por repetição deixou de valer para
+         * projeto pequeno, essa palavra passou a descrever um repositório que não é o dele.
+         *
+         * Medido em 07/09 numa cópia de `create-next-app`: a linha dizia *"4 repeated values"* sobre
+         * quatro valores que aparecem uma vez cada. Uma palavra errada na primeira linha do comando gasta
+         * a credibilidade das outras dez.
+         */
+        const everyOneRepeats = pending.every((e) => e.count > 1);
         lines.push(ready.length > 0
             ? `${pending.length} nobody names yet. Naming is a design decision, so those wait for a word from you:`
-            : `${pending.length} repeated values, and none of them has a name yet. Naming is a design decision, so each waits for a word from you:`);
+            : `${pending.length} ${everyOneRepeats ? "repeated values" : "values written by hand"}, and none of them has a name yet. Naming is a design decision, so each waits for a word from you:`);
         for (const e of pending.slice(0, 8))
             lines.push(`  ${e.value.padEnd(24)} ${`<${e.kind}, ${e.files} file${e.files === 1 ? "" : "s"}>`.padEnd(28)} ${e.near ? `≈ your ${e.near.name} (${e.near.away})` : 'path: ""'}`);
         if (pending.length > 8)

package/dist/commands/absorb.js

@@ -3,8 +3,10 @@ import { dirname, join, resolve } from "node:path";
 import { absorbPlan, describeAbsorb, needingName, } from "../absorb-plan.js";
 import { readProjectConfig, readToken, resolveRegistry } from "../config.js";
 import { diagnose, scanSource } from "../doctor/scan.js";
+import { withTheirNames } from "../doctor/their-names.js";
 import { measuredScope, scopePaths } from "../measured-scope.js";
 import { body, paint, section, snippet } from "../output.js";
+import { resolveDeps, tailwindMajor } from "../stack.js";
 import { loadSystem, walkAll } from "./doctor.js";
 /**
  * `synthesisui absorb` - O SISTEMA APRENDE O DESIGN QUE O CÓDIGO JÁ TEM.
@@ -66,12 +68,28 @@ export async function absorb(opts) {
      * ideia primeiro e ficou com a implementação de todo mundo.
      */
     const theirs = installed.theirs;
+    /**
+     * SEM SISTEMA NOSSO, A TABELA DA VARREDURA É A DELE - a mesma queda que o `doctor` já faz.
+     *
+     * O QUE ACONTECIA: este comando varria com `installed.table`, que sem sistema instalado é a tabela
+     * VAZIA. Então nada tinha nome, nem o que o próprio código dele nomeia - e a linha
+     * `--background: #ffffff`, que é onde o token dele NASCE, entrava na proposta como um valor solto
+     * a ser batizado. Medido em 07/09 numa cópia de `create-next-app`: 4 das 8 entradas eram as
+     * declarações dos tokens dele, e duas delas já traziam `theirName` preenchido - a proposta pedindo
+     * um nome para o que ela mesma acabara de dizer que já tem um.
+     *
+     * O `doctor` resolve isto há tempos, e a linha é literalmente a dele: quando não há nada nosso, o
+     * vocabulário dele é o único que existe, e é contra ele que a medição acontece.
+     */
+    const table = installed.table.byName.size > 0
+        ? installed.table
+        : withTheirNames(theirs, theirs);
     const reports = [];
     for await (const file of walkAll(roots)) {
         const source = await readFile(file, "utf8").catch(() => null);
         if (source === null)
             continue;
-        reports.push(scanSource(file.slice(root.length + 1), source, installed.table));
+        reports.push(scanSource(file.slice(root.length + 1), source, table));
     }
     const plan = absorbPlan(diagnose(reports), theirs, pathsInSystem(installed.documents), opts.cap ?? 40);
     console.log(section(hasSystem
@@ -173,13 +191,36 @@ async function sendProposal(root, path, registry) {
         console.log(body(paint.dim(proposal.slug
             ? "Your config says absorbed values belong in your CSS, so nothing was sent."
             : "You have no system yet, so these belong in your own CSS - nothing was sent, and nothing needed an account.")));
+        /**
+         * NUM TAILWIND v4, `:root` DECLARA A VARIÁVEL E NÃO GERA A CLASSE.
+         *
+         * O QUE ELE VIVIA: nomeava `#383838` de `color.ink.700`, colava o bloco que este comando
+         * imprime, e `text-ink-700` continuava não existindo. A variável estava lá, o doctor a
+         * reconhecia - e o código dele não tinha como usá-la. A metade visível da promessa não chegava.
+         *
+         * É a mesma lei que a `INV-VOLTA-13` já enuncia do outro lado da esteira: *"no Tailwind v4 só
+         * `@theme` gera utilitário"*. A folha que a plataforma instala sabe disso desde 23/08; o bloco
+         * que a plataforma manda ELE colar não sabia.
+         *
+         * E A SINTAXE SAI DO PROJETO, nunca de um padrão nosso - `tailwindMajor` já existe e o
+         * comentário dele diz por quê: *"gerar a sintaxe de uma para um projeto da outra produz um
+         * arquivo que o build DELE não entende, e é o pior tipo de saída, porque parece certa até
+         * alguém compilar"*. Sem Tailwind, ou na v3, `:root` continua sendo a resposta certa: lá o
+         * utilitário nasce do `tailwind.config`, não do CSS.
+         */
+        const major = tailwindMajor(await resolveDeps(root));
+        const block = major === 4 ? "@theme" : ":root";
         console.log("");
-        console.log("  :root {");
+        console.log(`  ${block} {`);
         for (const e of ready)
             console.log(`    --${e.path.replace(/\./g, "-")}: ${e.value};`);
         console.log("  }");
         console.log("");
-        console.log(body("The next import or `sync` reads these back as tokens you declared, and from then on the doctor holds your code to them by your own names."));
+        console.log(body(major === 4
+            ? "In `@theme` and not `:root`: on Tailwind v4 only `@theme` generates the utility, so this is what makes `text-ink-700` exist in your code."
+            : "The next import or `sync` reads these back as tokens you declared, and from then on the doctor holds your code to them by your own names."));
+        if (major === 4)
+            console.log(body("The next import or `sync` reads these back as tokens you declared, and from then on the doctor holds your code to them by your own names."));
         return;
     }
     const token = await readToken();

package/dist/commands/doctor.js

@@ -400,14 +400,20 @@ async function harvestOwnTokens(roots,
  *  e `4px` deixaria de casar com `0.25rem` de um lado só. */
 measured) {
     let css = "";
+    /** UMA A UMA, e não só concatenadas: a regra de escopo de `their-compiled-names.ts` decide pelo
+     *  `@import` de um arquivo no outro, e a concatenação apaga de qual arquivo cada linha veio. */
+    const sheets = new Map();
     for await (const file of walkAll(roots)) {
         if (!/\.(css|scss|sass|less)$/i.test(file))
             continue;
-        css += `\n${await readFile(file, "utf8").catch(() => "")}`;
+        const source = await readFile(file, "utf8").catch(() => "");
+        sheets.set(file, source);
+        css += `\n${source}`;
     }
     return buildTable({
         css,
         source: "yours",
+        sheets,
         rootPx: measured?.px,
         rootFrom: measured?.from ?? null,
     });
@@ -464,10 +470,27 @@ function verdict(d, hasSystem, overruled, conflicts) {
      */
     if (!hasSystem) {
         const distinct = new Set(d.findings.map((f) => f.literal.toLowerCase()));
+        /**
+         * O QUE O CÓDIGO DELE JÁ NOMEIA - e sem esta linha o relatório se contradiz.
+         *
+         * "none of them has a name yet" é o fecho de um projeto sem sistema, e ele era verdade enquanto
+         * a plataforma só lia custom properties. Agora o detalhe imprime `#555 · your code calls it
+         * $gray_dark` três linhas acima: o resumo dizendo que nada tem nome, sobre um valor que a linha
+         * de cima acabou de nomear, é o defeito que faz alguém desconfiar do relatório inteiro.
+         *
+         * E o número muda a decisão dele: quem já batizou metade dos valores no Sass não está no dia
+         * zero - ele está a um `absorb` de trazer esses nomes para um vocabulário que o navegador
+         * recebe, o que é uma conversa diferente de "escolha o sistema de alguém".
+         */
+        const spoken = new Set(d.findings
+            .filter((f) => f.theirCompiledName)
+            .map((f) => f.literal.toLowerCase()));
         return [
             ...head,
             body(`${distinct.size} distinct design values are written by hand here.`),
-            body("No design system is installed, so none of them has a name yet."),
+            spoken.size === 0
+                ? body("No design system is installed, so none of them has a name yet.")
+                : body(`No design system is installed, but your own code already names ${spoken.size} of them - in Sass or Less, which the browser never receives.`),
             "",
             body("Name them yourself - this reads them and asks you for the words:"),
             snippet(["npx synthesisui@latest absorb"]),
@@ -1534,9 +1557,19 @@ export async function doctor(opts) {
                     ? `→ no ${x.kind} named for it · the value lives as ${x.token}`
                     : nameToWrite(x)
                         ? `→ ${nameToWrite(x)}${alsoNamed(x)}`
-                        : near
-                            ? `→ nearest is ${near.theirs ?? near.name} (${near.value})`
-                            : "→ no token holds this value yet";
+                        : /**
+                           * O CÓDIGO DELE JÁ NOMEIA ISTO, e a linha dizia que nada nomeava.
+                           *
+                           * Vem antes de `near` porque um nome EXATO que ele escreveu vale mais que o degrau
+                           * mais próximo de outra coisa. Sem seta de troca: `$gray_dark` não existe num `.tsx`
+                           * e a troca segura depende de duas provas que esta camada não tem - ver
+                           * `TheirName.writable`.
+                           */
+                            x.theirCompiledName
+                                ? `· your code calls it ${x.theirCompiledName}`
+                                : near
+                                    ? `→ nearest is ${near.theirs ?? near.name} (${near.value})`
+                                    : "→ no token holds this value yet";
                 say(`      ${String(x.line).padStart(4)}  ${x.literal}  ${named}`);
             }
             if (f.findings.length > shown.length) {
@@ -1891,11 +1924,25 @@ export async function doctor(opts) {
              * que NENHUM dos dois nomeia o valor. É isso que a linha passa a dizer, e é o que separa esta
              * fila da anterior: aquela tem nome esperando, esta precisa de um.
              */
-            what: near
-                ? `${r.literal} - name it, or snap to ${near.theirs ?? near.name}`
-                : r.crossFamily
-                    ? `${r.literal} - no ${r.kind} named for it, and the value lives as ${r.token} in another family`
-                    : `${r.literal} - no name for it, here or in your CSS`,
+            /**
+             * O SEU CÓDIGO JÁ NOMEIA ISTO, e a linha dizia o contrário.
+             *
+             * "no name for it, here or in your CSS" é uma afirmação sobre o repositório DELE, e ela era
+             * falsa sempre que o nome estava num pré-processador: medido em 07/09 no `web-subscribe`,
+             * `#555` é `$gray_dark` em `css/colors.scss` e aparecia como "sem nome" em 27 arquivos.
+             *
+             * A linha DIZ o nome e não convida a trocar - `$gray_dark` não existe num `.tsx`, e a troca
+             * segura depende de o arquivo de destino compilar aquele pré-processador e importar aquela
+             * folha, que é o próximo passo desta frente. Dizer o que existe já muda a decisão dele; trocar
+             * sem essas duas provas quebraria o build.
+             */
+            what: r.theirCompiledName
+                ? `${r.literal} - your code calls it ${r.theirCompiledName} (no fix: it never reaches the browser)`
+                : near
+                    ? `${r.literal} - name it, or snap to ${near.theirs ?? near.name}`
+                    : r.crossFamily
+                        ? `${r.literal} - no ${r.kind} named for it, and the value lives as ${r.token} in another family`
+                        : `${r.literal} - no name for it, here or in your CSS`,
             size: `${r.files} file${r.files === 1 ? "" : "s"}`,
             cheap: false,
         });

package/dist/doctor/scan.js

@@ -540,7 +540,18 @@ function scanCore(file, source, table) {
                 ...(/(?<!r)em$/i.test(literal.trim())
                     ? { fontRelative: true }
                     : {}),
-                ...(theirs ? { theirToken: theirs.name } : {}),
+                ...(theirs?.writable ? { theirToken: theirs.name } : {}),
+                /**
+                 * O NOME QUE SÓ SE DIZ - `$gray_dark` do Sass, `@brand` do Less.
+                 *
+                 * Separado de `theirToken` porque aquele campo é o que o `--fix` ESCREVE, e um nome de
+                 * pré-processador escrito num `.tsx` é código quebrado. Aqui ele serve ao relatório, que
+                 * deixa de afirmar "no name for it, here or in your CSS" sobre um valor que o código dele
+                 * nomeia - a afirmação era sobre o repositório DELE, e era falsa.
+                 */
+                ...(theirs && !theirs.writable
+                    ? { theirCompiledName: theirs.name }
+                    : {}),
                 ...(theirs?.also.length ? { theirAlso: theirs.also } : {}),
                 /**
                  * A COINCIDÊNCIA VIAJA COM O ACHADO - ver `tokenMatch`.
@@ -737,6 +748,9 @@ export function diagnose(files) {
                 kind: f.kind,
                 token: f.token,
                 ...(f.theirToken ? { theirToken: f.theirToken } : {}),
+                ...(f.theirCompiledName
+                    ? { theirCompiledName: f.theirCompiledName }
+                    : {}),
                 ...(f.theirAlso?.length ? { theirAlso: f.theirAlso } : {}),
                 ...(f.fontRelative ? { fontRelative: true } : {}),
                 count: 1,
@@ -745,25 +759,31 @@ export function diagnose(files) {
             });
         }
     }
-    const repeats = [...byLiteral.entries()]
+    const everyLiteral = [...byLiteral.entries()]
         .map(([key, v]) => ({
         literal: key.slice(key.indexOf(":") + 1),
         kind: v.kind,
         token: v.token,
         ...(v.theirToken ? { theirToken: v.theirToken } : {}),
+        ...(v.theirCompiledName
+            ? { theirCompiledName: v.theirCompiledName }
+            : {}),
         ...(v.theirAlso?.length ? { theirAlso: v.theirAlso } : {}),
         ...(v.fontRelative ? { fontRelative: true } : {}),
         count: v.count,
         files: v.files.size,
         ...(v.crossFamily ? { crossFamily: true } : {}),
     }))
-        .filter((r) => r.count > 1)
         .sort((a, b) => b.count - a.count);
+    const repeats = everyLiteral.filter((r) => r.count > 1);
+    /** Ver `Diagnosis.once` - o que o corte por repetição deixa de fora. */
+    const once = everyLiteral.filter((r) => r.count === 1);
     return {
         // A file with a phantom name and no drift has nothing to say by the old
         // measure and the worst thing to say by the new one. Both keep it.
         files: files.filter((f) => f.findings.length > 0 || (f.phantoms?.length ?? 0) > 0),
         findings: flat,
+        once,
         counts,
         /**
          * QUANTOS JÁ TÊM NOME NESTE REPOSITÓRIO - e o dele conta.

package/dist/doctor/style-ledger.js

@@ -450,6 +450,26 @@ export function describeValueRuler(values) {
     const decisions = values.seen - values.structure;
     const closed = values.interpreted + values.answered;
     const percent = decisions > 0 ? Math.round((closed / decisions) * 100) : 0;
+    /**
+     * NADA PARA MEDIR NÃO É ZERO POR CENTO - e a frase dizia zero três vezes.
+     *
+     * O QUE O CLIENTE VIA, caminhado em 07/09 num `create-next-app` recém-criado: *"Of the 0 class
+     * declarations on your components, 0 are structure. Of the 0 design decisions, 0 are interpreted -
+     * 0%."* Três zeros e um 0% sobre um projeto onde a régua não tinha o que medir, porque ele ainda
+     * não escreveu um componente - só páginas, e uma página não é componente de design system, o que o
+     * próprio relatório explica seis linhas acima.
+     *
+     * `0%` é um número de DESEMPENHO, e ali não houve desempenho nenhum. É a lei 14 do `CLAUDE.md`:
+     * *"um zero pelado lê como falha nossa; um zero com motivo lê como fato"* - e para quem acabou de
+     * apontar a plataforma para o próprio projeto, uma linha de 0% é a primeira impressão.
+     *
+     * A frase que substitui diz o FATO e o caminho, sem inventar percentual: não há componente para
+     * medir ainda.
+     */
+    if (values.seen === 0)
+        return [
+            "No component of yours carries a class declaration yet - so there is nothing for this ruler to read. It starts answering once a component exists, and pages do not count as components.",
+        ];
     return [
         `Of the ${values.seen} class declarations on your components, ${values.structure} are structure (layout plumbing, not design decisions). Of the ${decisions} design decisions, ${closed} are interpreted${values.answered > 0 ? ` (${values.answered} of them answered by you)` : ""} - ${percent}%.`,
     ];

package/dist/doctor/their-compiled-names.js

@@ -0,0 +1,121 @@
+import { dirname, join, resolve } from "node:path";
+/**
+ * OS NOMES DELE QUE SOMEM NA COMPILAÇÃO - e que a plataforma afirmava não existir.
+ *
+ * O QUE O CLIENTE VIA. Um projeto que declara `$gray_dark: #555` em `css/colors.scss` e escreve
+ * `#555` em dezenas de arquivos recebia, do nosso relatório: *"#555 - no name for it, here or in
+ * your CSS"*. A frase é uma afirmação sobre o repositório DELE, e ela era falsa. Medido em 07/09 no
+ * `~/projects/web-subscribe`: `doctor` dizia `13 tokens found` num projeto com 27 nomes de cor
+ * declarados e partilhados, e 323 ocorrências ficavam sem o nome que o próprio código já lhes dá.
+ *
+ * POR QUE A PLATAFORMA NÃO OS VIA, e não era descuido: a colheita lê custom properties (`--x`), que
+ * é o que o navegador recebe. Uma variável de pré-processador - `$x` no Sass, `@x` no Less - resolve
+ * em tempo de compilação e não chega ao CSS final. Ela é vocabulário dele para LER, nunca endereço
+ * para APONTAR: escrever `var($gray_dark)` não existe.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * A REGRA QUE SEPARA A FEATURE DO DEFEITO: ESCOPO.
+ *
+ * Uma custom property em `:root` é global por construção - é isso que a torna vocabulário. Um `$x` no
+ * topo de um arquivo é uma constante DAQUELE arquivo, e tratar as duas como a mesma coisa inventa
+ * vocabulário em vez de ler o que existe.
+ *
+ * Medido no mesmo repositório, e a diferença é a feature inteira:
+ *
+ *     323  ocorrências ganham o nome certo   ($ declarado em folha que outra folha importa)
+ *    1085  ganhariam um nome FALSO           ($color e $primary-color declarados dentro de um
+ *                                             styles.module.scss de um componente - `$color: #FFF`
+ *                                             existe em dois módulos diferentes, e `#fff` aparece
+ *                                             596 vezes no projeto inteiro)
+ *
+ * Então só conta o que é PARTILHADO: um arquivo que outro arquivo importa foi escrito para ser
+ * vocabulário comum, e quem decide isso é o `@import`/`@use`/`@forward` dele - não uma convenção de
+ * nome de arquivo nossa, que seria a forma de fixar o hábito de um repositório dentro do produto.
+ */
+/** As extensões cujo vocabulário some antes do navegador. */
+const PREPROCESSED = /\.(scss|sass|less)$/i;
+/** `$nome: valor;` no Sass, `@nome: valor;` no Less - no topo do arquivo, fora de qualquer bloco. */
+const DECLARATION = /^[ \t]*([$@][a-zA-Z0-9_-]+)[ \t]*:[ \t]*([^;{}]+);/gm;
+/**
+ * `!default` É A MARCA DA PRÓPRIA LINGUAGEM PARA "ISTO É O PADRÃO DE UMA BIBLIOTECA".
+ *
+ * Em Sass ele significa literalmente *este valor vale se quem me usa não definiu outro* - a forma
+ * como um pacote publica vocabulário configurável. Um valor que ELE decidiu não carrega `!default`,
+ * e é essa diferença que separa a decisão dele do default de um pacote que alguém copiou para
+ * dentro do repositório.
+ *
+ * Medido em 07/09 no `~/projects/web-subscribe`, que tem `bootstrap-sass` e `ionicons` copiados para
+ * `css/`: dos 1185 nomes que a varredura encontra, 1125 são desses dois pacotes e TODOS trazem
+ * `!default`. Sem esta porta, o relatório responderia que o `#555` dele "se chama
+ * `$navbar-default-link-active-color`" - o vocabulário de uma biblioteca apresentado como o dele,
+ * que é o oposto exato do que este leitor existe para fazer.
+ *
+ * O LADO SEGURO DO ERRO, declarado: um projeto que use `!default` no PRÓPRIO vocabulário perde esses
+ * nomes e volta a ver "no name for it". Deixar de nomear o que existe custa uma linha de relatório;
+ * batizar o valor dele com a palavra de um pacote custa a confiança na próxima linha.
+ */
+const LIBRARY_DEFAULT = /!\s*default\b/i;
+/** `@import "colors"`, `@use "./colors" as c`, `@forward "colors"`. */
+const REFERENCE = /@(?:import|use|forward)\s+["']([^"']+)["']/g;
+/**
+ * QUAIS FOLHAS OUTRA FOLHA IMPORTA - a prova de que aquele arquivo é vocabulário comum.
+ *
+ * A resolução segue o que o Sass faz: a extensão é opcional e o parcial pode ter o `_` na frente.
+ * Um especificador que não aponta para nenhum arquivo do projeto é um pacote (`@import "bootstrap"`),
+ * e pacote não é vocabulário dele.
+ */
+export function sharedSheets(sheets) {
+    const known = new Set(sheets.keys());
+    const shared = new Set();
+    for (const [path, source] of sheets) {
+        const dir = dirname(path);
+        for (const [, spec] of source.matchAll(REFERENCE)) {
+            const bare = spec.replace(/\.(scss|sass|less|css)$/i, "");
+            const base = bare.split("/").pop() ?? bare;
+            const parent = bare.slice(0, bare.length - base.length);
+            for (const candidate of [
+                `${bare}.scss`,
+                `${bare}.sass`,
+                `${bare}.less`,
+                `${bare}.css`,
+                join(parent, `_${base}.scss`),
+                join(parent, `_${base}.sass`),
+                join(parent, `_${base}.less`),
+            ]) {
+                const abs = resolve(dir, candidate);
+                if (known.has(abs)) {
+                    shared.add(abs);
+                    break;
+                }
+            }
+        }
+    }
+    return shared;
+}
+/**
+ * O VOCABULÁRIO PARTILHADO QUE O NAVEGADOR NUNCA VÊ.
+ *
+ * A primeira declaração vence, a mesma regra que a colheita de custom properties usa: uma folha
+ * posterior sobrescrevendo uma anterior é cascata, e este leitor não vê cascata.
+ */
+export function compiledNames(sheets) {
+    const shared = sharedSheets(sheets);
+    const out = [];
+    const seen = new Set();
+    for (const [path, source] of sheets) {
+        if (!PREPROCESSED.test(path) || !shared.has(path))
+            continue;
+        for (const [, name, value] of source.matchAll(DECLARATION)) {
+            if (seen.has(name) || LIBRARY_DEFAULT.test(value))
+                continue;
+            seen.add(name);
+            /** `!global` diz onde a atribuição vale, não o que ela vale - sai do valor e não da lista. */
+            out.push({
+                name,
+                value: value.replace(/!\s*global\b/i, "").trim(),
+                file: path,
+            });
+        }
+    }
+    return out;
+}

package/dist/doctor/their-names.js

@@ -47,7 +47,12 @@ import { FAMILY_PREFIX, familySays, formDecides, normalizeValue, UNAMBIGUOUS, }
  * que o próprio css dele nomeia `--dashboard-font-family`. É pouco, e é o único grupo que sobrou do
  * item que eu tinha nomeado - os `em` saíram na leva anterior.
  */
-const segments = (name) => name.replace(/^--/, "").split("-");
+/**
+ * O nome sem o sigilo, em pedaços. `$` e `@` entram porque o vocabulário dele pode estar num
+ * pré-processador (ver `their-compiled-names.ts`), e um `$gray-dark` que não perdesse o `$` nunca
+ * casaria segmento nenhum no desempate - o critério existiria e nunca alcançaria esses nomes.
+ */
+const segments = (name) => name.replace(/^(--|[$@])/, "").split("-");
 /**
  * QUAL DOS NOMES DELE, quando mais de um segura o mesmo valor - e são 18 no repo real.
  *
@@ -132,13 +137,20 @@ roles) {
  * sistema do dono, `#f59e0b` é `--color-tier-gold` E `--color-feedback-warning` - dois conceitos
  * dele, gamificação e estado -, e o relatório dizia `→ {color.tier-gold}` como se fosse fato.
  */
-function escolha(candidates, ours, convention, roles) {
+function escolha(candidates, ours, convention, roles, 
+/** `false` para nome de pré-processador - ver `TheirName.writable`. */
+writable = true) {
     const name = pick(candidates, ours, convention, roles);
-    return { name, also: candidates.filter((c) => c !== name) };
+    return { name, also: candidates.filter((c) => c !== name), writable };
 }
 export function theirNames(ours, theirs) {
     const out = new Map();
-    if (theirs.byName.size === 0)
+    /**
+     * AS DUAS FONTES, e não só a primeira: um projeto que declara o vocabulário INTEIRO em Sass tem
+     * `byName` vazio e mesmo assim tem nomes para dizer. Sair aqui devolvia mapa vazio para ele, e o
+     * relatório voltava a afirmar que o repositório não nomeia um valor que o repositório nomeia.
+     */
+    if (theirs.byName.size === 0 && theirs.compiledAway.size === 0)
         return out;
     /**
      * OS PAPÉIS QUE ESTE SISTEMA DECLARA, derivados dos NOSSOS nomes - ver o critério 2 de `pick`.
@@ -205,6 +217,29 @@ export function theirNames(ours, theirs) {
             out.set(key, escolha(candidates, null, convention, roles));
         }
     }
+    /**
+     * POR ÚLTIMO, O QUE SÓ SE DIZ - e ser o último é a regra, não a ordem do arquivo.
+     *
+     * Onde ele nomeia o mesmo valor nas duas formas, quem ganha é a custom property: ela resolve no
+     * navegador, o `--fix` pode escrevê-la e ela sobrevive a qualquer mudança de pré-processador. Só
+     * quando NENHUM nome que o navegador recebe segura aquele valor é que o nome compilado entra - e
+     * entra marcado como não escrevível.
+     *
+     * A mesma porta da forma vale aqui: `UNAMBIGUOUS` deixa passar o que a FORMA já classifica (cor,
+     * duração, pilha de fontes) e deixa o comprimento cru de fora. Sem isso, um `$mobile_gutter: 10px`
+     * seria oferecido como o nome de todo `10px` do projeto - medido em 07/09 no `web-subscribe`, onde
+     * `10px` aparece em 102 arquivos e quase nenhum é um gutter.
+     */
+    for (const [value, names] of theirs.compiledAway) {
+        for (const [kind, form] of Object.entries(UNAMBIGUOUS)) {
+            if (!form.test(value))
+                continue;
+            const key = `${kind}:${value}`;
+            if (out.has(key))
+                continue;
+            out.set(key, escolha(names.map((n) => n.name), null, convention, roles, false));
+        }
+    }
     return out;
 }
 /**

package/dist/doctor/tokens.js

@@ -13,6 +13,7 @@
  */
 import { DEFAULT_ROOT_PX } from "./root-size.js";
 import { parseSchemeBlocks } from "./scheme-blocks.js";
+import { compiledNames } from "./their-compiled-names.js";
 export const EMPTY_TABLE = {
     source: null,
     name: null,
@@ -24,6 +25,7 @@ export const EMPTY_TABLE = {
     rootFrom: null,
     aliases: new Map(),
     declared: new Set(),
+    compiledAway: new Map(),
     keyframes: new Set(),
 };
 const hex2 = (n) => Math.max(0, Math.min(255, Math.round(n)))
@@ -318,6 +320,17 @@ export function buildTable(input) {
     const byName = source === "installed"
         ? parseTokens(input.css)
         : parseRootTokens(input.css);
+    /**
+     * O VOCABULÁRIO DELE QUE NÃO CHEGA AO NAVEGADOR, somado ao que chega.
+     *
+     * Entra DEPOIS das custom properties e sem sobrescrever nenhuma: onde as duas formas nomeiam o
+     * mesmo valor, o nome que o navegador recebe é o que resolve, e é ele que a folha pode apontar.
+     */
+    const compiled = source === "installed" || !input.sheets ? [] : compiledNames(input.sheets);
+    const compiledAway = new Map();
+    for (const one of compiled)
+        if (!byName.has(one.name))
+            compiledAway.set(one.name, one);
     /**
      * Built from the RESOLVED map, not from `byName`. A semantic role that
      * aliases a primitive has to be findable by the primitive's value, or the
@@ -337,6 +350,24 @@ export function buildTable(input) {
      */
     const raw = source === "installed" ? parseTokensWithAliases(input.css) : new Map();
     const isAlias = (name) => /^var\(/.test((raw.get(name) ?? "").trim());
+    /**
+     * OS NOMES QUE SÓ SE DIZEM, indexados pelo MESMO valor normalizado das outras tabelas.
+     *
+     * Fora de `byName` e de `byValue` de propósito: aquelas duas respondem "o meu sistema nomeia
+     * isto?", que é a pergunta da cobertura e do `--fix`. Um nome que o navegador nunca recebe não
+     * pode entrar em nenhuma das duas - inflaria a contagem de tokens dele (medido em 07/09 no
+     * `web-subscribe`: 13 viraria 1198, e 1125 dos acrescentados eram bootstrap e ionicons copiados
+     * para dentro do repositório) e ofereceria ao `--fix` um nome que quebra um `.tsx`.
+     */
+    const byCompiledValue = new Map();
+    for (const one of compiledAway.values()) {
+        const key = normalizeValue(one.value, rootPx);
+        const list = byCompiledValue.get(key);
+        if (list)
+            list.push(one);
+        else
+            byCompiledValue.set(key, [one]);
+    }
     const byValue = new Map();
     for (const [name, value] of resolved) {
         const key = normalizeValue(value, rootPx);
@@ -360,6 +391,7 @@ export function buildTable(input) {
         /** Vazio até `withTheirNames` ler o vocabulário dele - ver `their-names.ts`. */
         aliases: new Map(),
         declared: parseDeclaredNames(input.css),
+        compiledAway: byCompiledValue,
         keyframes: new Set([...input.css.matchAll(/@keyframes\s+([a-zA-Z0-9_-]+)/g)].map((m) => m[1])),
     };
 }
@@ -418,7 +450,11 @@ kind) {
     const theirs = kind
         ? table.aliases.get(`${kind}:${normalizeValue(best.value, table.rootPx)}`)
         : undefined;
-    return theirs ? { ...best, theirs: theirs.name } : best;
+    /**
+     * SÓ UM NOME ESCREVÍVEL - esta linha convida a trocar (`snap to X`), e um nome de pré-processador
+     * não pode ir para o código dele. Ver `TheirName.writable`.
+     */
+    return theirs?.writable ? { ...best, theirs: theirs.name } : best;
 }
 /**
  * The family a token belongs to, from the drift it was found in.

package/dist/stack.js

@@ -235,11 +235,39 @@ classStyle) {
  *
  * `null` quando o pacote não está lá ou quando a faixa não diz um número - um intervalo que não se
  * resolve é ausência de resposta, e supor a v4 seria escolher o mais novo por conveniência nossa.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * O MAIOR SOZINHO É UMA FAIXA, e exigir o ponto apagava metade dos projetos v4.
+ *
+ * A primeira versão desta função casava `(\d+)\.` - um número SEGUIDO DE PONTO. `^4.1.2` respondia
+ * 4; `^4`, que é exatamente o que o `create-next-app` e o instalador do Tailwind v4 escrevem,
+ * respondia `null`. E `null` aqui não é neutro: é a plataforma dizendo *não sei qual versão* sobre um
+ * projeto que declara a versão na primeira linha do `package.json` dele.
+ *
+ * Medido em 07/09 nos sete projetos com Tailwind desta máquina:
+ *
+ *     "^4"       3 projetos   -> null    test_ds_01, web-subscribe, web-dashboard
+ *     "^3.4.1"   1 projeto    -> 3
+ *     "^3.3.5"   1 projeto    -> 3
+ *     "3.4.3"    1 projeto    -> 3
+ *     "4.1.11"   1 projeto    -> 4
+ *
+ * Os três invisíveis são os três v4 - e não por acaso: é a v4 que se instala como `^4`. Quem paga é
+ * quem começa um projeto HOJE.
+ *
+ * A AMBIGUIDADE CONTINUA VALENDO `null`, e agora ela é medida em vez de suposta: cada faixa da
+ * expressão diz um maior, e a resposta só existe quando todas dizem o MESMO. `>=3 <5` continua sendo
+ * ausência de resposta, porque é; `^4` deixa de ser, porque não é.
  */
 export function tailwindMajor(deps) {
     const raw = deps.tailwindcss;
     if (!raw)
         return null;
-    const m = /(\d+)\./.exec(raw.replace(/^[^0-9]*/, ""));
-    return m ? Number(m[1]) : null;
+    const majors = new Set();
+    for (const part of raw.split(/\s*\|\|\s*|\s+|,/).filter(Boolean)) {
+        const m = /(\d+)/.exec(part.replace(/^[^0-9]*/, ""));
+        if (m)
+            majors.add(Number(m[1]));
+    }
+    return majors.size === 1 ? [...majors][0] : null;
 }

package/dist/their-vars.js

@@ -101,7 +101,14 @@ export function pointAtTheirNames(css, theirs, resolvable) {
      * buildou não tem como provar o que resolve, e um par afirmado sem prova é pior que par nenhum.
      */
     if (!resolvable || theirs.byName.size === 0)
-        return { css, pointed: 0, pruned: 0, cycles: 0, pairs: [] };
+        return {
+            css,
+            pointed: 0,
+            pruned: 0,
+            compiledAway: 0,
+            cycles: 0,
+            pairs: [],
+        };
     const ours = buildTable({ css, source: "installed" });
     const alias = theirNames(ours, theirs);
     /**
@@ -116,6 +123,7 @@ export function pointAtTheirNames(css, theirs, resolvable) {
         bridged.set(theirName, ourName);
     let pointed = 0;
     let pruned = 0;
+    let compiledAway = 0;
     let cycles = 0;
     /** Ver `PointedAt.pairs`: o mapa sai do mesmo casamento que reescreve a linha. */
     const pairs = [];
@@ -126,9 +134,19 @@ export function pointAtTheirNames(css, theirs, resolvable) {
         const kind = Object.entries(FAMILY_KIND).find(([prefix]) => name.startsWith(prefix))?.[1];
         if (!kind)
             return line;
-        const theirName = alias.get(`${kind}:${normalizeValue(value.trim(), ours.rootPx)}`)?.name;
+        const theirs_ = alias.get(`${kind}:${normalizeValue(value.trim(), ours.rootPx)}`);
+        const theirName = theirs_?.name;
         if (!theirName || theirName === name)
             return line;
+        /**
+         * UM NOME DE PRÉ-PROCESSADOR NÃO É UM ENDEREÇO. `var($gray_dark)` não existe em CSS nenhum,
+         * então a linha fica com o valor - e a recusa se conta pela SUA causa, não como se o build
+         * dele tivesse podado um token que ele pode voltar a usar.
+         */
+        if (!theirs_.writable) {
+            compiledAway += 1;
+            return line;
+        }
         /**
          * A PONTE JÁ APONTA PARA CÁ - então apontar de volta fecha um ciclo, e um ciclo não deixa o
          * valor errado: deixa a propriedade INVÁLIDA. A utility dele já resolve pelo nosso token, que é
@@ -146,7 +164,7 @@ export function pointAtTheirNames(css, theirs, resolvable) {
         pairs.push({ ours: name, theirs: theirName, value: value.trim() });
         return `${indent}${name}${sep}var(${theirName});`;
     });
-    return { css: out, pointed, pruned, cycles, pairs };
+    return { css: out, pointed, pruned, compiledAway, cycles, pairs };
 }
 /**
  * O PREFIXO DA NOSSA VARIÁVEL -> A FAMÍLIA, e a chave que `theirNames` devolve é `<família>:<valor>`.
@@ -171,7 +189,14 @@ const FAMILY_KIND = {
 export async function pointTokensAtTheirNames(root, payload) {
     const css = payload.artifacts["tokens.css"] ?? "";
     if (!css)
-        return { css, pointed: 0, pruned: 0, cycles: 0, pairs: [] };
+        return {
+            css,
+            pointed: 0,
+            pruned: 0,
+            compiledAway: 0,
+            cycles: 0,
+            pairs: [],
+        };
     const [theirs, resolvable] = await Promise.all([
         harvestTheirCss(root),
         resolvableVars(root),
@@ -190,6 +215,9 @@ async function harvestTheirCss(root) {
         "_synthesisui",
     ]);
     let css = "";
+    /** As folhas UMA A UMA, porque a regra de escopo de `their-compiled-names.ts` precisa saber qual
+     *  arquivo importa qual - a concatenação apaga exatamente essa informação. */
+    const sheets = new Map();
     const walk = async (dir) => {
         for (const entry of await readdir(dir, { withFileTypes: true }).catch(() => [])) {
             if (skip.has(entry.name) || entry.name.startsWith("."))
@@ -197,12 +225,15 @@ async function harvestTheirCss(root) {
             const path = join(dir, entry.name);
             if (entry.isDirectory())
                 await walk(path);
-            else if (/\.(css|scss|sass|less)$/i.test(entry.name))
-                css += `\n${await readFile(path, "utf8").catch(() => "")}`;
+            else if (/\.(css|scss|sass|less)$/i.test(entry.name)) {
+                const source = await readFile(path, "utf8").catch(() => "");
+                sheets.set(path, source);
+                css += `\n${source}`;
+            }
         }
     };
     await walk(root);
-    return buildTable({ css, source: "yours" });
+    return buildTable({ css, source: "yours", sheets });
 }
 /**
  * AS LINHAS QUE APONTAM PARA UM NOME DELE QUE NÃO EXISTE MAIS.

package/package.json

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