synthesisui 0.16.286 → 0.16.289

package/dist/anatomy-read.js

@@ -32,6 +32,7 @@
 import { readSxProps } from "./doctor/style-props.js";
 import { transcribe, } from "./doctor/transcribe.js";
 import { frontierKind, packageRoot } from "./frontier-kind.js";
+import { withGlobal } from "./global-wear.js";
 /** The ten forms, closed. A renderer that accepts any tag draws anything. */
 const FORMS = new Set([
     "image",
@@ -252,7 +253,18 @@ sketch,
  * A escala de espaçamento que o projeto DELES declara para o `sx`. Ausente = o default
  * documentado do MUI, que é fato da biblioteca que eles escolheram - ver `spacingOf`.
  */
-sxSpacing) {
+sxSpacing, 
+/**
+ * AS CLASSES DA FOLHA GLOBAL DELE - ver `Census.globalClasses` e `wearGlobal`.
+ *
+ * O QUE ISSO ALCANÇA QUE NADA MAIS ALCANÇAVA: uma utility que ele escreve num NÓ FILHO. O
+ * `LeaderboardRow` do `codelevel-ui` põe `text-grad-xp` num `<span>` dentro de um ternário, e o
+ * `QuestItem` põe `text-grad` numa tabela que pertence ao filho - as duas passam por aqui, e não
+ * pela raiz nem pela tabela de variantes do componente.
+ *
+ * Ausente é a resposta de quem não tem folha global, e nesse caso nada muda.
+ */
+globals) {
     /**
      * THE PACKAGE THE RETURNED ELEMENT CAME FROM, measured rather than spelled.
      * Node 0 of the sketch IS what the component returns, and the reader stamped its
@@ -474,7 +486,7 @@ sxSpacing) {
                         ? (sketch?.[node.at]?.classes ?? "")
                         : "";
                 const classes = raw.split(/\s+/).filter(Boolean);
-                const t = transcribe(classes, declared);
+                const t = withGlobal(transcribe(classes, declared), classes, globals);
                 /**
                  * A PROP DE ESTILO DESTE NÓ, sob a classe dele.
                  *
@@ -618,7 +630,7 @@ sxSpacing) {
      * otherwise. So a drawn root sends nothing here at all.
      */
     const rootStyle = rootPainted
-        ? transcribe(rootPainted.split(/\s+/).filter(Boolean), declared)
+        ? withGlobal(transcribe(rootPainted.split(/\s+/).filter(Boolean), declared), rootPainted.split(/\s+/).filter(Boolean), globals)
         : null;
     const paints = rootStyle && Object.keys(rootStyle.base).length > 0
         ? { style: rootStyle.base }
@@ -710,13 +722,16 @@ sxSpacing) {
  * correctly, and the absence of a tree means the preview lays them out in a row
  * exactly as it did before.
  */
-export function resolveFlatParts(read, declared) {
+export function resolveFlatParts(read, declared, 
+/** As classes da folha global dele - ver `wearGlobal`. */
+globals) {
     const parts = {};
     for (const part of read) {
         const name = safePartName(String(part?.name ?? ""));
         if (!name || typeof part.classes !== "string")
             continue;
-        const t = transcribe(part.classes.split(/\s+/).filter(Boolean), declared);
+        const partClasses = part.classes.split(/\s+/).filter(Boolean);
+        const t = withGlobal(transcribe(partClasses, declared), partClasses, globals);
         parts[name] = { base: t.base, dark: t.dark, states: t.states };
     }
     return { parts, tree: [], composes: [], external: [], notes: [], partAt: {} };

package/dist/commands/import.js

@@ -40,7 +40,9 @@ import { keyframesInSheets } from "../global-keyframes.js";
 import { withLibraryStructure } from "../library-structure.js";
 import { mergeCensus } from "../merge-census.js";
 import { claimName } from "../name-claim.js";
+import { mergeNamespacePairs } from "../namespace-pairs.js";
 import { namingQueue } from "../naming-queue.js";
+import { notExpressed } from "../not-expressed.js";
 import { body, paint, section } from "../output.js";
 import { outsideScope } from "../outside-scope.js";
 import { phase, startProgress } from "../progress.js";
@@ -367,6 +369,8 @@ function screenOf(rel) {
     const after = parts.slice(i + 1).filter((p) => !p.startsWith("("));
     return `${parts[i]}/${after.slice(0, 2).join("/")}`;
 }
+/** Quantas classes da folha global viajam no censo. Ver o aviso em `takeCensus`. */
+const MAX_GLOBAL_CLASSES = 300;
 export async function takeCensus(root, opts) {
     /**
      * O RELATÓRIO SÓ SAI QUANDO ALGUÉM O PEDIU - `say` cala quando o chamador é uma RE-medição.
@@ -450,6 +454,17 @@ export async function takeCensus(root, opts) {
      * porque é isso que o juiz do ledger precisa para chamar a classe e a regra de LIDAS.
      */
     const globalClasses = readGlobalClasses(globalSheets, declaredValues);
+    /**
+     * TETO DAS CLASSES GLOBAIS QUE VIAJAM NO CENSO - e quando ele corta, ele fala.
+     *
+     * Medido nas três populações: 24 classes na folha do `codelevel-ui`, 22 na nossa, 0 no
+     * `apps/web-dashboard` do repo real, que é CSS Modules. O teto é para a folha de um app que
+     * escreva utilitário por atacado, e existe porque um censo que dobra de tamanho em silêncio é o
+     * tipo de surpresa que ninguém pede.
+     */
+    if (globalClasses.size > MAX_GLOBAL_CLASSES) {
+        console.log(body(paint.faint(`${globalClasses.size} classes in your global sheet, and ${globalClasses.size - MAX_GLOBAL_CLASSES} of them are not travelling with this census - the first ${MAX_GLOBAL_CLASSES} are.`)));
+    }
     /**
      * OS KEYFRAMES DA FOLHA DELE, colhidos onde as folhas globais já estão na mão.
      *
@@ -735,16 +750,18 @@ export async function takeCensus(root, opts) {
                             /**
                              * Ver `CensusLook.aside` - o segundo componente do arquivo também.
                              *
-                             * AQUI OS EIXOS NÃO SÃO CONHECIDOS: `transcribeVariants` roda para o primeiro
-                             * componente do arquivo, e este é o segundo. Passar `undefined` é dizer a verdade
-                             * ("não sei se declara"), e não uma omissão - e é por isso que o veto final, em
-                             * `exclusive-contract.ts`, pergunta pelos eixos em vez de confiar só neste campo.
+                             * E COM OS EIXOS QUE O TIPO DELE DECLARA. `transcribeVariants` roda para o primeiro
+                             * componente do arquivo, então aqui não há tabela de variantes - mas `extra.axes` é a
+                             * declaração da interface, lida por `scanDefinitions` para TODA definição do arquivo.
+                             * Era `undefined`, e isso pôs de lado o `ToastIcon` dele: terceiro componente do
+                             * `Toast.tsx`, cinco tons declarados no tipo, um gradiente para cada. Ver
+                             * `classifyAside`.
                              */
-                            ...(classifyAside({ name: extra.name, declaredAxes: undefined })
+                            ...(classifyAside({ name: extra.name, declaredAxes: extra.axes })
                                 ? {
                                     aside: classifyAside({
                                         name: extra.name,
-                                        declaredAxes: undefined,
+                                        declaredAxes: extra.axes,
                                     }),
                                 }
                                 : {}),
@@ -782,7 +799,7 @@ export async function takeCensus(root, opts) {
                  * for the result, which is the "valid and unread" failure this pipeline has
                  * paid for twice already.
                  */
-                const v = transcribeVariants(src, declaredValues);
+                const v = transcribeVariants(src, declaredValues, globalClasses);
                 /**
                  * THE RESTING OPTION, from the definition itself. `cva` says it in
                  * `defaultVariants`; a lookup-record component says it in the destructuring -
@@ -1040,14 +1057,20 @@ export async function takeCensus(root, opts) {
                         /**
                          * Ver `CensusLook.aside`: o fato viaja, a regra fica de um lado só.
                          *
-                         * `v.axes` é a DECLARAÇÃO de variação deste componente, e é ela que separa um glifo de
-                         * um componente cujo nome só parece com um. Ver `classifyAside`.
+                         * AS DUAS FONTES DE EIXO, e é a mesma decisão do autor nas duas. `found[0].axes` é o que
+                         * o TIPO declara (`interface ToastIconProps { tone?: "gold" | "cool" }`); `v.axes` é o
+                         * que a TABELA declara (`cva({ variants: … })`). Consultar só a segunda pôs de lado um
+                         * componente que pinta por `Record<tone, gradiente>` - forma que a tabela não vê.
+                         * Ver `classifyAside`.
                          */
-                        ...(classifyAside({ name: found[0].name, declaredAxes: v.axes })
+                        ...(classifyAside({
+                            name: found[0].name,
+                            declaredAxes: { ...found[0].axes, ...v.axes },
+                        })
                             ? {
                                 aside: classifyAside({
                                     name: found[0].name,
-                                    declaredAxes: v.axes,
+                                    declaredAxes: { ...found[0].axes, ...v.axes },
                                 }),
                             }
                             : {}),
@@ -1864,7 +1887,14 @@ export async function takeCensus(root, opts) {
             list.push(kebab(pair.child));
         companionsOf.set(pair.component, list);
     }
-    const components = merged.map((c) => ({
+    /**
+     * `Modal.Header` E `ModalHeader` CONTADOS UMA VEZ - ver `mergeNamespacePairs`.
+     *
+     * Antes do enriquecimento porque veredito, leis e companheiros são indexados por NOME: fundir
+     * depois deixaria metade do que se sabe sobre a peça pendurado no nome que deixou de existir.
+     */
+    const paired = mergeNamespacePairs(merged, new Set(defined.map((d) => d.name)));
+    const components = paired.map((c) => ({
         ...c,
         ...(verdicts.get(idOf(c)) ?? {}),
         ...(laws.has(c.name) ? { laws: laws.get(c.name) } : {}),
@@ -2071,6 +2101,25 @@ export async function takeCensus(root, opts) {
             }
             : {}),
         ...(conventions.length > 0 ? { conventions } : {}),
+        /**
+         * AS CLASSES DA FOLHA GLOBAL DELE - ver `Census.globalClasses`.
+         *
+         * TODAS AS QUE A FOLHA DECLARA, e não só as que a raiz vestiu. A primeira tentativa levou apenas
+         * as reivindicadas por `globalWear`, que só roda na raiz do componente - e as utilities usadas
+         * numa tabela de variantes ou num nó filho, que são a maioria, ficavam de fora justamente do
+         * campo que existe para alcançá-las. Duas de 24 chegavam.
+         *
+         * O CUSTO ESTÁ MEDIDO: a folha do `codelevel-ui` declara 24 classes, a nossa 22, e o
+         * `apps/web-dashboard` do repo real declara 0 - ele é CSS Modules. Nas três populações isso é
+         * ruído no tamanho do censo. O teto de `MAX_GLOBAL_CLASSES` existe para a folha de um app que
+         * escreva utilitário por atacado, e quando ele corta, o número cortado é DITO em vez de
+         * desaparecer.
+         */
+        ...(globalClasses.size > 0
+            ? {
+                globalClasses: Object.fromEntries([...globalClasses.entries()].slice(0, MAX_GLOBAL_CLASSES)),
+            }
+            : {}),
         classStyle,
         ...(Object.keys(looks).length > 0 ? { looks } : {}),
         ...(naming.components > 0 ? { naming } : {}),
@@ -3166,6 +3215,16 @@ export function rootBehaviour(tag, sketch) {
 export async function resolveReadParts(census, root, 
 /** `true` numa re-medição: o resumo desta etapa fica para o `sync --full` - ver `say`. */
 quiet = false) {
+    /**
+     * AS CLASSES DA FOLHA GLOBAL DELE, DO CENSO - ver `Census.globalClasses`.
+     *
+     * Esta etapa roda depois da medição, e também no `sync` e do lado da plataforma, sobre censo já
+     * guardado - então ela não tem como voltar à folha no disco. Vindo do censo, uma utility que ele
+     * escreve num NÓ FILHO chega ao look: o `LeaderboardRow` põe `text-grad-xp` num `<span>` dentro de
+     * um ternário, e é aqui que aquele nó é lido.
+     */
+    const globalClasses = new Map(Object.entries(census
+        .globalClasses ?? {}));
     const say = quiet
         ? () => { }
         : (line) => {
@@ -3278,13 +3337,13 @@ quiet = false) {
             ? 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)
+            looks[component]?.sketch, census.sxSpacing, globalClasses)
             : patched
-                ? resolveAnatomy(patched.read, declared, deps, resolveRef, entry?.root, looks[component]?.sketch, census.sxSpacing)
+                ? resolveAnatomy(patched.read, declared, deps, resolveRef, entry?.root, looks[component]?.sketch, census.sxSpacing, globalClasses)
                 : derived && derived.read.length > 0
-                    ? resolveAnatomy(derived.read, declared, deps, resolveRef, entry?.root, looks[component]?.sketch, census.sxSpacing)
+                    ? resolveAnatomy(derived.read, declared, deps, resolveRef, entry?.root, looks[component]?.sketch, census.sxSpacing, globalClasses)
                     : Array.isArray(entry?.parts) && entry.parts.length > 0
-                        ? resolveFlatParts(entry.parts, declared)
+                        ? resolveFlatParts(entry.parts, declared, globalClasses)
                         : null;
         if (!resolved)
             continue;
@@ -3699,6 +3758,23 @@ export async function runImport(opts) {
     const out = opts.census ?? join(root, "_synthesisui", "census.json");
     await mkdir(dirname(out), { recursive: true });
     await writeFile(out, `${JSON.stringify(census, null, 2)}\n`, "utf8");
+    /**
+     * O QUE NÃO CHEGOU, DECLARADO PELA ESTEIRA - ver `notExpressed`.
+     *
+     * Escrito ao lado do censo e na mesma rodada, porque a lacuna e a medição são a mesma verdade
+     * vista dos dois lados. Era o agente que escrevia este arquivo, instruído por uma frase dentro da
+     * descrição de uma tool - e em 23/08 o mesmo repositório foi importado duas vezes, a primeira
+     * declarando 37 linhas de lacuna e a segunda nenhuma, com as lacunas todas no lugar. Um pedido a
+     * um modelo não é um artefato.
+     *
+     * O agente ainda ACRESCENTA o que só ele vê. O piso deixou de depender dele.
+     */
+    const gaps = notExpressed(census);
+    if (gaps) {
+        const gapFile = join(dirname(out), "not-expressed.md");
+        await writeFile(gapFile, gaps, "utf8");
+        console.log(body(`Gaps written to ${paint.strong(relative(root, gapFile))}`));
+    }
     console.log("");
     console.log(body(`Written to ${paint.strong(relative(root, out))}`));
     if (opts.dry) {

package/dist/doctor/broken-refs.js

@@ -19,6 +19,8 @@
  */
 import { frontierKind } from "../frontier-kind.js";
 import { importMap } from "./imports.js";
+/** Quantos lugares viajam por referência quebrada. Ver `BrokenRef.at`. */
+const MAX_PLACES = 3;
 /** `var(--x)`, including inside a Tailwind arbitrary value: `bg-[var(--x)]`. */
 const VAR_REF = /var\(\s*(--[a-zA-Z0-9_-]+)/g;
 /**
@@ -96,9 +98,20 @@ export function findBrokenRefs(sources, declared) {
                 continue;
             if (runtime && (RUNTIME_ANCHOR.has(name) || RUNTIME_PREFIX.test(name)))
                 continue;
-            const hit = seen.get(name) ?? { count: 0, files: new Set() };
+            const hit = seen.get(name) ?? {
+                count: 0,
+                files: new Set(),
+                at: [],
+            };
             hit.count += 1;
             hit.files.add(file);
+            /** A linha contada do índice do match - ver `BrokenRef.at` para o teto. */
+            if (hit.at.length < MAX_PLACES) {
+                hit.at.push({
+                    file,
+                    line: source.slice(0, m.index ?? 0).split("\n").length,
+                });
+            }
             seen.set(name, hit);
         }
     }
@@ -111,6 +124,7 @@ export function findBrokenRefs(sources, declared) {
             count: hit.count,
             files: hit.files.size,
             ...(meant ? { meant } : {}),
+            ...(hit.at.length > 0 ? { at: hit.at } : {}),
         });
     }
     // A broken reference somebody typed nine times is worse than one typed once,

package/dist/doctor/component-gate.js

@@ -61,6 +61,8 @@ const PROVIDER_SUFFIX = /(Provider|Providers|Context|Boundary|Guard|Wrapper)$/;
 /** Any JSX at all in the file. A capitalised export with none is a constant, a
  *  config object or a helper - `export const ROUTES = {…}` is not a component. */
 const HAS_JSX = /<[A-Za-z][^>]*>|<>/;
+/** `ICON_SIZE`, `AURORA_PALETTES`, `ARTICLE_TAB` - a convenção universal para valor, não para peça. */
+const SCREAMING_SNAKE = /^[A-Z][A-Z0-9]*(_[A-Z0-9]+)+$/;
 /**
  * Any sign that this file decides how something LOOKS.
  *
@@ -71,7 +73,30 @@ const HAS_JSX = /<[A-Za-z][^>]*>|<>/;
 const HAS_STYLING = /className|class=|style=|styled[.(]|css`|cva\(|\btv\(|makeStyles|sx=|tw`/;
 /** `createContext` + a `.Provider` in the return is a provider whatever it is
  *  called - `RootWrapper` and `CommonProviders` both read this way. */
-const IS_CONTEXT = /createContext\s*[<(]/;
+/**
+ * QUEM RECEBE O `createContext` - o nome, e não o arquivo em volta dele.
+ *
+ * O QUE O CLIENTE PERDIA: o `Tabs` inteiro. `Tabs.tsx` declara `const TabsCtx = createContext(…)`, e
+ * a pergunta era se o ARQUIVO tem contexto - então `Tabs`, `TabsList`, `TabsTrigger` e `TabsPanel`
+ * saíram juntos, com `cn("flex flex-col gap-4")` escrito neles (`codelevel-ui`, 23/08). Composto com
+ * contexto é o padrão dominante de React - Tabs, Accordion, Select, Dropdown -, então recusar o
+ * arquivo recusa a família toda.
+ *
+ * É a mesma falha de forma que `HAS_JSX` já cometeu do outro lado: uma pergunta sobre o arquivo
+ * respondendo sobre o export. Um provider é UM nome; os vizinhos respondem por si.
+ *
+ * Medido em três populações - `codelevel-ui` recupera 4, o dashboard do `frontend-hub` recupera 7
+ * (o `Pagination` inteiro), e os 6 que terminam em `Provider` continuam fora pelo sufixo.
+ */
+const CONTEXT_OWNER = /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::[^=]*)?=\s*(?:React\.)?createContext\s*[<(]/g;
+/** Os nomes que ESTE arquivo atribui a um `createContext`. */
+function contextNames(source) {
+    CONTEXT_OWNER.lastIndex = 0;
+    const out = new Set();
+    for (const m of source.matchAll(CONTEXT_OWNER))
+        out.add(m[1]);
+    return out;
+}
 /** A lowercase JSX tag: an html element this file renders ITSELF. */
 const OWN_ELEMENT = /<(?:[a-z][a-z0-9]*)(\s|>|\/)/;
 /** Every capitalised JSX tag the file opens, dots included. */
@@ -205,7 +230,7 @@ export function gateComponent(input) {
             because: `\`${name}\` names a screen, and composes ${shape.composes} piece${shape.composes === 1 ? "" : "s"} across ${shape.nodes} element${shape.nodes === 1 ? "" : "s"} - too thin to be a template of yours. A design system is made of the pieces a screen is built FROM`,
         };
     }
-    if (PROVIDER_SUFFIX.test(name) || IS_CONTEXT.test(source)) {
+    if (PROVIDER_SUFFIX.test(name) || contextNames(source).has(name)) {
         return {
             ok: false,
             why: "provider",
@@ -232,6 +257,38 @@ export function gateComponent(input) {
      */
     if (STYLED_FACTORY.test(source))
         return { ok: true };
+    /**
+     * UMA CONSTANTE NÃO É COMPONENTE, e o arquivo em volta dela não muda isso.
+     *
+     * O QUE O CLIENTE VIA: `ICON_SIZE` e `AURORA_PALETTES` ocupando vaga na vitrine do
+     * `codelevel-ui`, e uma delas com forma desenhada - um mapa de tamanhos renderizado como se fosse
+     * peça. Ele contava 59 componentes no design system dele e dois não existiam.
+     *
+     * O teste de markup logo abaixo já recusa constante, e ele pergunta pelo ARQUIVO INTEIRO:
+     * `ICON_SIZE` mora dentro do `Icon.tsx`, que tem JSX de sobra, então ela entrava pela porta do
+     * vizinho. Vem ANTES dele por isso - é a mesma falha de forma que o teste de contexto acima
+     * corrigiu do outro lado.
+     *
+     * MEDIDO EM QUATRO POPULAÇÕES, e as três encontradas são objeto literal no código real:
+     *
+     *     codelevel-ui packages/ui         75 nomes ·  2  (ICON_SIZE, AURORA_PALETTES)
+     *     frontend-hub packages/ui         69 nomes ·  0
+     *     frontend-hub apps/web-dashboard 526 nomes ·  1  (ARTICLE_TAB, um enum de aba)
+     *     synthesisui apps/web                       ·  0
+     *
+     * Nenhum componente das quatro usa este formato de nome - JSX escreve `<Button>` e nunca
+     * `<ICON_SIZE>` -, então a regra não recusa peça de ninguém. E ela só pôde entrar junto com o
+     * leitor de `export default` em linha própria: sozinha, ela deixava órfãs as 294 declarações de
+     * CSS Modules do único arquivo do dashboard onde a constante era a ÚNICA coisa que o leitor via.
+     * O dono daquele arquivo é o `CurateContentSection`, que agora é lido.
+     */
+    if (SCREAMING_SNAKE.test(name)) {
+        return {
+            ok: false,
+            why: "config",
+            because: `\`${name}\` is spelled as a constant - a value the code reads, not a component anything renders`,
+        };
+    }
     if (!HAS_JSX.test(source)) {
         return {
             ok: false,

package/dist/doctor/css-modules.js

@@ -38,6 +38,7 @@
  * and both branches naming a class in this file. Exactly one is a ternary between two
  * string literals. So this reader covers a family I had written off as impossible.
  */
+import { tokenRefFor } from "../token-ref.js";
 /** A CSS pseudo-class or attribute, mapped to the state name the contract uses. */
 const STATE_OF = [
     [/:hover\b/, "hover"],
@@ -58,8 +59,19 @@ const STATE_OF = [
     [/:last-child\b/, "last"],
     [/:empty\b/, "empty"],
 ];
-/** `[data-theme="dark"]`, `.dark`, `[data-scheme=dark]` - how a project says dark. */
-const DARK = /\[data-theme=["']?dark["']?\]|\[data-scheme=["']?dark["']?\]|(^|\s)\.dark(\s|$)/;
+/**
+ * `[data-theme="dark"]`, `.dark`, `html.dark`, `[data-scheme=dark]` - como um projeto diz escuro.
+ *
+ * O QUE O CLIENTE PERDIA: o esquema escuro escrito na folha dele. O padrão exigia que `.dark`
+ * viesse no início do seletor ou depois de um espaço, e ele escreve `html.dark .stroke-text` - a
+ * classe colada na tag, que é a forma que o Tailwind com `darkMode: "class"` produz quando o
+ * atributo vive no `<html>`. Cinco classes da folha dele caíam nisso, entre elas o `stroke-text` e o
+ * `holo-card`, e a regra escura delas era lida como se fosse a regra de repouso: o contorno claro do
+ * texto vinha pintado com a cor do tema escuro.
+ *
+ * `(?![\w-])` para não casar `.darkroom`, que é uma classe de alguém e não um esquema.
+ */
+const DARK = /\[data-theme=["']?dark["']?\]|\[data-scheme=["']?dark["']?\]|(?:^|[\s>+~]|[a-zA-Z0-9\]])\.dark(?![\w-])/;
 /** `kebab-case` → `camelCase`, which is the only spelling the contract accepts. */
 export function camel(prop) {
     return prop.trim().replace(/-([a-z])/g, (_, c) => c.toUpperCase());
@@ -274,7 +286,21 @@ export function readModuleCss(css) {
             const selector = one.trim();
             if (!selector)
                 continue;
-            const names = classesIn(selector);
+            /**
+             * O SELETOR DE ESQUEMA NÃO É UM ANCESTRAL DE ANATOMIA - e era registrado como um.
+             *
+             * `html.dark .stroke-text` tem duas classes, e a leitura tomava `dark` como PAI de
+             * `stroke-text`. Duas consequências, as duas na tela dele: a classe entrava na lista de
+             * "filho que só existe num contexto" e era descartada inteira - `stroke-text`,
+             * `stroke-text-soft`, `stroke-text-grad`, `stage-3d` e `holo-card`, cinco das 24 da folha
+             * dele -, e a árvore ganhava um nó chamado `dark` que não existe em marcação nenhuma.
+             *
+             * `.dark` é COMO o projeto diz escuro, não onde um elemento mora. Tirado dos nomes antes de
+             * decidir alvo e pai; o `isDark` abaixo continua lendo o seletor inteiro e mandando o bloco
+             * para `dark`, que é onde ele pertence.
+             */
+            const scheme = DARK.test(selector);
+            const names = classesIn(selector).filter((n) => !(scheme && (n === "dark" || n === "light")));
             if (names.length === 0) {
                 // An element or `:root` selector styles something this reader cannot attach to
                 // a component. Said out loud rather than dropped.
@@ -283,6 +309,9 @@ export function readModuleCss(css) {
             }
             const target = names[names.length - 1];
             const entry = out.classes[target] ?? emptyClass();
+            /** Alvo sozinho no seletor: é regra dela, e não regra dentro de outra. Ver `ModuleClass.own`. */
+            if (names.length === 1)
+                entry.own = true;
             out.classes[target] = entry;
             // A descendant selector records the RELATION as well as the styles: `.panel
             // .title` says title lives inside panel, which is the anatomy for free.
@@ -296,7 +325,7 @@ export function readModuleCss(css) {
             const block = declarations(rule.body);
             if (Object.keys(block).length === 0)
                 continue;
-            const isDark = DARK.test(selector);
+            const isDark = scheme;
             const state = STATE_OF.find(([re]) => re.test(selector))?.[1] ?? null;
             const width = minWidthOf(rule.media);
             if (width) {
@@ -526,7 +555,7 @@ export function transcribeModule(read, usage, declared) {
     const resolve = (block) => {
         const out = {};
         for (const [prop, value] of Object.entries(block)) {
-            out[prop] = value.replace(/var\(\s*(--[a-zA-Z0-9_-]+)\s*(?:,[^)]*)?\)/g, (whole, name) => declared.has(name) ? tokenRefFor(name) : whole);
+            out[prop] = value.replace(/var\(\s*(--[a-zA-Z0-9_-]+)\s*(?:,[^)]*)?\)/g, (whole, name) => declared.has(name) ? tokenRefFor(name, declared) : whole);
         }
         return out;
     };
@@ -645,44 +674,6 @@ function formFor(tag) {
  * A declared custom property as a token ref in the document's namespace. Their name is
  * the path, which is "your names travel unchanged" one level deeper.
  */
-function tokenRefFor(name) {
-    const bare = name.replace(/^--/, "");
-    if (bare.startsWith("color-")) {
-        const rest = bare.slice("color-".length);
-        const m = /^(.*)-(\d{2,4})$/.exec(rest);
-        return m ? `{color.${m[1]}.${m[2]}}` : `{color.${rest}}`;
-    }
-    if (bare.startsWith("radius-"))
-        return `{radius.${bare.slice(7)}}`;
-    if (bare.startsWith("spacing-"))
-        return `{spacing.${bare.slice(8)}}`;
-    if (bare.startsWith("shadow-"))
-        return `{shadow.${bare.slice(7)}}`;
-    if (bare.startsWith("background-image-gradient-")) {
-        return `{gradients.${bare.slice("background-image-gradient-".length)}}`;
-    }
-    if (bare.startsWith("gradient-"))
-        return `{gradients.${bare.slice(9)}}`;
-    if (bare.startsWith("text-")) {
-        // The companion token: `--text-body-s--line-height` names the line-height OF a
-        // step, and a double dash inside a ref is a grammar nothing accepts (test13).
-        const companion = /^text-(.+?)--(line-height|letter-spacing|font-weight)$/.exec(bare);
-        if (companion) {
-            const prop = {
-                "line-height": "lineHeight",
-                "letter-spacing": "letterSpacing",
-                "font-weight": "weight",
-            }[companion[2]];
-            return `{typography.scale.${companion[1]}.${prop}}`;
-        }
-        if (bare.slice(5).includes("--"))
-            return `var(${name})`;
-        return `{typography.scale.${bare.slice(5)}.fontSize}`;
-    }
-    if (bare.startsWith("font-"))
-        return `{typography.families.${bare.slice(5)}}`;
-    return `var(${name})`;
-}
 /**
  * AS REGRAS DE CLASSE DE UMA FOLHA GLOBAL, prontas para o componente que as veste.
  *
@@ -700,21 +691,60 @@ function tokenRefFor(name) {
  * descendente (`.a .b` - o contexto é do pai) e seletor composto, que `readModuleCss`
  * já reporta em `unslotted`.
  */
+/**
+ * `@utility x { … }` LIDA COMO `.x { … }` - a porta que o Tailwind v4 abriu, e nada mais.
+ *
+ * O QUE O CLIENTE PERDIA: as utilities ASSINATURA dele. No `codelevel-ui` são 23, e entre elas
+ * `text-grad`, `text-grad-fire`, `text-grad-xp` e `text-grad-gold` - os gradientes de texto que dão
+ * a cara do produto. O componente que escreve `text-grad` viajava sem o gradiente e o título dele
+ * chegava em cor lisa; das 198 declarações do `globals.css` que não alcançavam receita nenhuma, é
+ * aqui que a maior parte morava.
+ *
+ * É NORMALIZAÇÃO DE SINTAXE, E NÃO MOTOR NOVO. Uma `@utility` é uma classe com outro nome de porta:
+ * mesmo corpo, mesmas declarações, mesmo cascade. A máquina que resolve o `var()` dele para o token
+ * que ELE nomeou, que lê estado e `dark`, e que veste a classe na raiz do componente já existe
+ * inteira - só não conhecia a porta.
+ *
+ * MEDIDO EM TRÊS POPULAÇÕES: `codelevel-ui` 23 em 6 folhas, `synthesisui/web` 7 em 1 folha
+ * (`bg-ember`, `text-ember`, `mask-fade-x`…), `frontend-hub` 0 em 722 - ele é CSS Modules e não usa
+ * a sintaxe. Duas populações independentes com a forma, e uma sem, que é o que prova que a régua não
+ * assume o formato de um repositório só.
+ *
+ * A FUNCIONAL FICA DE FORA, e é o único caso: `@utility tab-* { tab-size: --value(integer) }` tem
+ * molde no lugar do nome, então não há classe fixa que uma marcação possa vestir. Nenhuma das 30
+ * medidas é funcional, e quando uma for, ela cai nas sobras com arquivo e linha, que é a resposta
+ * honesta.
+ */
+function asClasses(body) {
+    return body.replace(/@utility\s+([a-zA-Z][\w-]*)(\s*\{)/g, (_whole, name, brace) => `.${name}${brace}`);
+}
 export function readGlobalClasses(globals, declared) {
     const resolve = (block) => {
         const out = {};
         for (const [prop, value] of Object.entries(block)) {
-            out[prop] = value.replace(/var\(\s*(--[a-zA-Z0-9_-]+)\s*(?:,[^)]*)?\)/g, (whole, name) => declared.has(name) ? tokenRefFor(name) : whole);
+            out[prop] = value.replace(/var\(\s*(--[a-zA-Z0-9_-]+)\s*(?:,[^)]*)?\)/g, (whole, name) => declared.has(name) ? tokenRefFor(name, declared) : whole);
         }
         return out;
     };
     const out = new Map();
     for (const sheet of globals) {
-        const read = readModuleCss(sheet.body);
+        const read = readModuleCss(asClasses(sheet.body));
         const dependent = new Set(Object.values(read.classes).flatMap((c) => c.children));
         for (const [name, cls] of Object.entries(read.classes)) {
-            /** O filho de `.a .b` só existe naquele contexto - vesti-lo solto pintaria errado. */
-            if (dependent.has(name))
+            /**
+             * O filho de `.a .b` só existe naquele contexto - vesti-lo solto pintaria errado. MAS uma
+             * classe que também tem REGRA PRÓPRIA não é um filho: é uma classe com variação contextual, e
+             * descartá-la joga fora a regra base junto.
+             *
+             * O QUE ISSO CUSTAVA: cinco das 24 classes da folha dele, entre elas `stroke-text` e
+             * `holo-card` - o contorno de texto e a borda holográfica. A causa era uma linha de tema,
+             * `html.dark .stroke-text { … }`, que fazia a classe aparecer como filha em algum lugar.
+             *
+             * O PADRÃO É UNIVERSAL, e é isso que torna o conserto necessário e não específico: `html.dark
+             * .x` é como se escreve tema em CSS e `.parent:hover .child` é como se escreve estado. Medido
+             * em duas folhas independentes - 5 de 24 na dele, 2 de 22 na nossa.
+             */
+            if (dependent.has(name) && !cls.own)
                 continue;
             const states = {};
             for (const [state, block] of Object.entries(cls.states))

package/dist/doctor/definitions-scan.js

@@ -51,7 +51,50 @@ export function tierOf(file) {
     return undefined;
 }
 /** `export function X`, `export default function X`, `export const X =`. */
-const EXPORTED = /export\s+(?:default\s+)?(?:async\s+)?(?:function\s+([A-Z][A-Za-z0-9_]*)|const\s+([A-Z][A-Za-z0-9_]*)\s*[:=])/g;
+const EXPORTED = /export\s+(?:default\s+)?(?:async\s+)?(?:function\s+([A-Z][A-Za-z0-9_]*)|const\s+([A-Z][A-Za-z0-9_]*)\s*[:=]|class\s+([A-Z][A-Za-z0-9_]*))/g;
+/**
+ * O `export default` QUE NOMEIA A PEÇA EM OUTRA LINHA - e é assim que metade da indústria escreve.
+ *
+ * O QUE O CLIENTE PERDIA: 108 componentes do dashboard dele, o kit de mídia inteiro entre eles
+ * (`Media`, `MediaHeader`, `MediaTitle`, `MediaFooter`, `MediaDescription`), mais o `SelectItem` e o
+ * `CurateContentSection`. Nenhum no censo, nenhum aviso: o leitor exigia a palavra `export` na MESMA
+ * linha da declaração. `export default function Media()` era lido, e
+ * `function Media() {…}` + `export default Media;` no fim do arquivo, não - a mesma peça, com a
+ * exportação numa linha própria.
+ *
+ * MEDIDO EM QUATRO POPULAÇÕES, e é o que decide o que cobrir:
+ *
+ *     forma                              codelevel  fh/ui  fh/dashboard  synthesisui
+ *     export default function Name               0      0           519           73
+ *     export default Name;                       0      0           110            0
+ *     export default memo/forwardRef(…)          0      0             1            0
+ *     export { Name as default }                 0      0             0            0
+ *     export default class Name                  0      0             0            0
+ *     export default () => / function()          0      0             0            0
+ *
+ * As formas com zero entram de propósito: são o que a LINGUAGEM oferece, e uma régua que só cobre a
+ * forma do repositório que eu tenho na mão é uma régua que quebra no próximo cliente.
+ *
+ * O ANÔNIMO FICA DE FORA, declarado: em `export default () => …` não existe nome para ler. O único
+ * candidato seria o nome do arquivo, e batizar peça alheia é supor - o que este censo não faz.
+ */
+const DEFAULT_NAMED = [
+    /** `export default Media;` e `export default memo(forwardRef(Media))`, com ou sem `React.` */
+    /export\s+default\s+(?:(?:React\.)?(?:memo|forwardRef)\s*\(\s*)*([A-Z][A-Za-z0-9_]*)/g,
+    /** `export { Media as default }` - a forma canônica do ES, e ela aceita vizinhos na mesma chave */
+    /export\s*\{[^}]*?\b([A-Z][A-Za-z0-9_]*)\s+as\s+default\b/g,
+];
+/**
+ * O NOME PRECISA SER DECLARADO AQUI, e é isto que separa uma definição de um repasse.
+ *
+ * `import Button from "@acme/ui"; export default Button;` é um re-export: a peça é de outra pessoa e
+ * reivindicá-la faria o censo listar como dele um componente que ele só encaminha. A pergunta é se
+ * ESTE arquivo constrói o nome - `function X`, `const X =`, `class X`.
+ */
+function declaresName(source, name) {
+    const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`(?:^|\\n)\\s*(?:export\\s+)?(?:default\\s+)?(?:async\\s+)?(?:function|class|const|let|var)\\s+${escaped}\\b`).test(source);
+}
 /** `type ButtonProps = { … }` or `interface ButtonProps { … }`, to its closing
  *  brace, wherever it sits.
  *
@@ -102,8 +145,21 @@ export function scanDefinitions(file, source) {
     const out = [];
     const seen = new Set();
     EXPORTED.lastIndex = 0;
-    for (const m of source.matchAll(EXPORTED)) {
-        const name = m[1] ?? m[2];
+    /**
+     * A EXPORTAÇÃO EM LINHA PRÓPRIA ENTRA NA MESMA FILA - ver `DEFAULT_NAMED`.
+     *
+     * Reunidas antes do laço para que a deduplicação por `seen` valha para as duas origens: um
+     * arquivo que escreve `export default function Card()` casa nos dois padrões e a peça é uma só.
+     */
+    const names = [...source.matchAll(EXPORTED)].map((m) => m[1] ?? m[2] ?? m[3] ?? "");
+    for (const rx of DEFAULT_NAMED) {
+        rx.lastIndex = 0;
+        for (const m of source.matchAll(rx)) {
+            if (m[1] && declaresName(source, m[1]))
+                names.push(m[1]);
+        }
+    }
+    for (const name of names) {
         if (!name || seen.has(name))
             continue;
         seen.add(name);

package/dist/doctor/transcribe.js

@@ -42,6 +42,7 @@
  *     hover:shadow-md           → states.hover
  *     data-[checked]:bg-ocean-50 → states.checked
  */
+import { tokenRefFor } from "../token-ref.js";
 /**
  * Utility prefix → the property name THE DOCUMENT USES, which is camelCase.
  *
@@ -1218,7 +1219,11 @@ function readUtilityCore(utility, declared) {
     if (themeProperty && rest) {
         const own = `--${prefix}-${rest}`;
         if (declared.has(own)) {
-            return { property: themeProperty, value: tokenRefFor(own), token: own };
+            return {
+                property: themeProperty,
+                value: tokenRefFor(own, declared),
+                token: own,
+            };
         }
     }
     return null;
@@ -1310,7 +1315,7 @@ function resolveArbitrary(inner, declared) {
         if (raw.startsWith("--")) {
             const name = raw.split(",")[0].trim();
             return declared.has(name)
-                ? { value: tokenRefFor(name), token: name }
+                ? { value: tokenRefFor(name, declared), token: name }
                 : null;
         }
         // A literal in brackets is still a real value somebody typed.
@@ -1318,7 +1323,7 @@ function resolveArbitrary(inner, declared) {
     }
     const name = v[1];
     if (declared.has(name))
-        return { value: tokenRefFor(name), token: name };
+        return { value: tokenRefFor(name, declared), token: name };
     /**
      * A `var()` THEY NEVER DECLARED, WHEN THEY DECLARED IT UNDER ITS NAMESPACE.
      *
@@ -1338,7 +1343,7 @@ function resolveArbitrary(inner, declared) {
      */
     const meant = MEANT_NAMESPACES.map((ns) => `--${ns}-${name.slice(2)}`).find((candidate) => declared.has(candidate));
     if (meant)
-        return { value: tokenRefFor(meant), token: meant };
+        return { value: tokenRefFor(meant, declared), token: meant };
     return { value: raw };
 }
 /**
@@ -1362,53 +1367,6 @@ const MEANT_NAMESPACES = [
  * `--text-body-s` → `{typography.scale.body-s.fontSize}`. Their name is the path,
  * which is the whole "your names travel unchanged" promise applied one level deeper.
  */
-function tokenRefFor(name) {
-    const bare = name.replace(/^--/, "");
-    if (bare.startsWith("color-"))
-        return refFor(bare.slice("color-".length));
-    if (bare.startsWith("radius-"))
-        return `{radius.${bare.slice(7)}}`;
-    if (bare.startsWith("spacing-"))
-        return `{spacing.${bare.slice(8)}}`;
-    if (bare.startsWith("shadow-"))
-        return `{shadow.${bare.slice(7)}}`;
-    // `--gradient-ui` and `--background-image-gradient-ui` are one token in two
-    // spellings - Tailwind v4's utility namespace wraps the first. Both reach
-    // `{gradients.ui}`, which is where the census files them.
-    if (bare.startsWith("background-image-gradient-")) {
-        return `{gradients.${bare.slice("background-image-gradient-".length)}}`;
-    }
-    if (bare.startsWith("gradient-"))
-        return `{gradients.${bare.slice(9)}}`;
-    if (bare.startsWith("text-")) {
-        /**
-         * THE COMPANION TOKEN. Tailwind v4 spells "the line-height OF text-body-s" as
-         * `--text-body-s--line-height` - a double dash inside one name. Read as a step name
-         * it produced `{typography.scale.body-s--line-height.fontSize}`, whose double dash
-         * no ref grammar accepts, and the whole recipe was REFUSED at validation (test13,
-         * 01/08). The suffix names the property; the middle names the step.
-         */
-        const companion = /^text-(.+?)--(line-height|letter-spacing|font-weight)$/.exec(bare);
-        if (companion) {
-            const prop = {
-                "line-height": "lineHeight",
-                "letter-spacing": "letterSpacing",
-                "font-weight": "weight",
-            }[companion[2]];
-            return `{typography.scale.${companion[1]}.${prop}}`;
-        }
-        // Any other double dash is a name this grammar cannot hold - the literal var()
-        // still resolves against their own stylesheet, and an invalid ref helps nobody.
-        if (bare.slice(5).includes("--"))
-            return `var(${name})`;
-        return `{typography.scale.${bare.slice(5)}.fontSize}`;
-    }
-    if (bare.startsWith("font-"))
-        return `{typography.families.${bare.slice(5)}}`;
-    // A namespace we do not model. The literal `var()` is still correct CSS against
-    // their own stylesheet, and inventing a ref would point at nothing.
-    return `var(${name})`;
-}
 function refFor(name) {
     const m = /^(.*)-(\d{2,4})$/.exec(name);
     if (!m)

package/dist/doctor/variant-read.js

@@ -30,6 +30,7 @@
  * property resolve in their app by position in the string; a recipe resolves by
  * position in `layers`. They agree only if the reader inserts in the order it read.
  */
+import { wearGlobal, withGlobal } from "../global-wear.js";
 import { parseClass, transcribe } from "./transcribe.js";
 /**
  * A Tailwind modifier, mapped to the condition it IS.
@@ -136,8 +137,7 @@ export function conditionOf(modifiers) {
              * condição do DOM dele, escrita por extenso - descartá-la porque a nossa tabela não a lista
              * seria a tabela decidindo o que o código dele pode dizer. `lost` fica para o que não dá para
              * ler, não para o que a gente não previu.
-             */
-            else if (nome)
+             */ else if (nome)
                 out.state = camel(nome);
             else
                 out.lost = true;
@@ -954,7 +954,19 @@ export function readClassTernaries(source) {
  * `declared` is their own custom properties, so `bg-ocean-950` comes out as a ref to
  * the token they declared rather than as a hex we looked up.
  */
-export function transcribeVariants(source, declared) {
+export function transcribeVariants(source, declared, 
+/**
+ * AS CLASSES QUE A FOLHA GLOBAL DELE DECLARA - obrigatório, e por um motivo medido.
+ *
+ * O import vestia a regra global na RAIZ do componente e só ali. Uma utility escrita dentro da
+ * TABELA DE VARIANTES - que é onde o `Typography` do `codelevel-ui` põe `text-grad-fire` - vinha
+ * por aqui, e este caminho não conhecia folha nenhuma: o título dele saía em cor lisa, e nada
+ * dizia que o gradiente tinha sido perdido.
+ *
+ * Sem default de propósito. Um `Map` vazio é a resposta de quem não tem folha global, e ela se
+ * escreve em voz alta; um parâmetro que se pode esquecer é o defeito que isto está desfazendo.
+ */
+globals) {
     const reads = readVariants(source);
     const fromRecords = {};
     const unslotted = [];
@@ -1048,7 +1060,21 @@ export function transcribeVariants(source, declared) {
          */
         const bare = layer.classes.map((cls) => parseClass(cls).utility);
         const t = transcribe(bare, declared);
-        const style = { ...t.base, ...t.dark };
+        /**
+         * A REGRA GLOBAL QUE ESTA CAMADA VESTE - ver `wearGlobal`.
+         *
+         * Antes da transcrição no objeto final, e não depois: uma utility da folha dele e uma utility
+         * da Tailwind pintando a mesma propriedade resolvem pelo cascade, e o cascade diz que a
+         * última classe escrita ganha. `transcribe` já respeita essa ordem entre as dela; aqui a
+         * folha entra como a camada de baixo, que é onde o CSS a coloca.
+         */
+        const wornHere = wearGlobal(bare, globals);
+        const style = {
+            ...wornHere.base,
+            ...wornHere.dark,
+            ...t.base,
+            ...t.dark,
+        };
         return {
             ...(layer.when ? { when: layer.when } : {}),
             ...(layer.at ? { at: layer.at } : {}),
@@ -1063,7 +1089,7 @@ export function transcribeVariants(source, declared) {
         defaults,
         layers,
         raw: allLayers,
-        base: transcribe(baseClasses, declared),
+        base: withGlobal(transcribe(baseClasses, declared), baseClasses, globals),
         unslotted,
         notes,
     };

package/dist/global-wear.js

@@ -0,0 +1,44 @@
+import { parseClass } from "./doctor/transcribe.js";
+export function wearGlobal(classes, globals, 
+/** Registra quais classes a folha global reivindicou, para o juiz de duplicidade. */
+claimed) {
+    const worn = { base: {}, dark: {}, states: {} };
+    for (const cls of classes) {
+        const rule = globals.get(cls);
+        if (!rule)
+            continue;
+        claimed?.add(cls);
+        Object.assign(worn.base, rule.base);
+        Object.assign(worn.dark, rule.dark);
+        for (const [state, block] of Object.entries(rule.states))
+            worn.states[state] = { ...worn.states[state], ...block };
+    }
+    return worn;
+}
+/** Tem alguma declaração? Uma camada vazia não vira camada. */
+export function wornAnything(worn) {
+    return (Object.keys(worn.base).length > 0 ||
+        Object.keys(worn.dark).length > 0 ||
+        Object.keys(worn.states).length > 0);
+}
+/**
+ * A TRANSCRIÇÃO COM A FOLHA GLOBAL DELE POR BAIXO.
+ *
+ * A folha é a camada de baixo porque é onde o CSS a coloca: uma utility da Tailwind escrita no mesmo
+ * elemento ganha da classe da folha quando as duas pintam a mesma propriedade.
+ */
+export function withGlobal(t, classes, 
+/** Ausente é a resposta de quem não tem folha global: a transcrição volta intacta. */
+globals) {
+    if (!globals || globals.size === 0)
+        return t;
+    const worn = wearGlobal(classes.map((cls) => parseClass(cls).utility), globals);
+    if (!wornAnything(worn))
+        return t;
+    return {
+        ...t,
+        base: { ...worn.base, ...t.base },
+        dark: { ...worn.dark, ...t.dark },
+        states: Object.fromEntries([...new Set([...Object.keys(worn.states), ...Object.keys(t.states)])].map((k) => [k, { ...worn.states[k], ...t.states[k] }])),
+    };
+}

package/dist/install-marks.js

@@ -253,7 +253,7 @@ export const CHECKER_SINCE = "0.16.250";
  * publicado antes deste código existir, e uma marca nele calaria o aviso para quem o instalou. Mesma
  * lição de algumas horas antes, na mesma sessão.
  */
-export const READER_SINCE = "0.16.274";
+export const READER_SINCE = "0.16.288";
 /**
  * O QUE ESTÁ INSTALADO AQUI FICOU PARA TRÁS - e as DUAS condições que fazem isso ser verdade.
  *

package/dist/namespace-pairs.js

@@ -0,0 +1,80 @@
+/**
+ * `Modal.Header` E `ModalHeader` SÃO UMA PEÇA - e a vitrine dele mostrava duas.
+ *
+ * O QUE O CLIENTE VIA: o design system dele contando 75 componentes quando ele escreveu 68. Sete
+ * pares apareciam duas vezes - `Modal.Header` + `ModalHeader`, `Modal.Body` + `ModalBody`,
+ * `Modal.Footer` + `ModalFooter`, `Toast.Icon` + `ToastIcon`, `Toast.Body` + `ToastBody`,
+ * `Tooltip.Content` + `TooltipContent`, `PillNav.Link` + `PillNavLink` - porque as duas grafias são
+ * a mesma coisa dita de dois jeitos: `export const ModalHeader` é a DECLARAÇÃO, e
+ * `Modal.Header = ModalHeader` é o açúcar de namespace que o React deixa escrever.
+ *
+ * A DECLARAÇÃO GANHA, e é a mesma regra que o resto do censo já segue: uso é o que alguém escolheu,
+ * declaração é o que o autor desenhou. O nome que sobrevive é o que ele exportou.
+ *
+ * MEDIDO NAS DUAS POPULAÇÕES, e a segunda é a que prova que a régua não é sobre um repositório:
+ *
+ *     codelevel-ui    75 no inventário · 11 nomes com ponto ·  7 pares
+ *     frontend-hub   302 no inventário · 23 nomes com ponto ·  0 pares
+ *
+ * No `frontend-hub` `Card.Root` e `Icon.ChevronUp` não têm um `CardRoot` nem um `IconChevronUp`
+ * declarado ao lado - são namespaces de verdade, e continuam como estão. É a EXISTÊNCIA da
+ * declaração plana que faz o par, nunca a grafia com ponto por si.
+ */
+export function mergeNamespacePairs(components, 
+/** O que este escopo DECLARA. Sem isso, um par não pode ser provado - ver `Census.defined`. */
+declared) {
+    const byName = new Map(components.map((c) => [c.name, c]));
+    const absorbed = new Set();
+    const out = [];
+    for (const c of components) {
+        if (absorbed.has(c.name))
+            continue;
+        if (!c.name.includes(".")) {
+            out.push(c);
+            continue;
+        }
+        const flat = c.name.split(".").join("");
+        const twin = byName.get(flat);
+        /** Só quando o nome plano EXISTE no inventário e é declarado por este escopo. */
+        if (!twin || !declared.has(flat)) {
+            out.push(c);
+            continue;
+        }
+        absorbed.add(c.name);
+        absorbed.add(flat);
+        out.push(fuse(twin, c));
+    }
+    /** Os planos que foram absorvidos já entraram fundidos; os outros seguem na ordem. */
+    return out;
+}
+/**
+ * As duas linhas somadas sob o nome declarado.
+ *
+ * `count` soma - são usos distintos no código dele. `files` fica no MAIOR dos dois em vez de somar:
+ * as duas grafias costumam aparecer nos mesmos arquivos, e somar diria que o componente vive em mais
+ * lugares do que vive. Um número inflado é pior que um número conservador, porque ele decide
+ * prioridade.
+ */
+function fuse(flat, dotted) {
+    const props = { ...flat.props };
+    for (const [p, values] of Object.entries(dotted.props ?? {})) {
+        props[p] = [...new Set([...(props[p] ?? []), ...values])];
+    }
+    const propFiles = { ...(flat.propFiles ?? {}) };
+    for (const [p, n] of Object.entries(dotted.propFiles ?? {})) {
+        propFiles[p] = Math.max(propFiles[p] ?? 0, n);
+    }
+    return {
+        ...flat,
+        count: flat.count + dotted.count,
+        files: Math.max(flat.files, dotted.files),
+        props,
+        ...(Object.keys(propFiles).length > 0 ? { propFiles } : {}),
+        /** Os eixos que qualquer uma das duas grafias declarou - é a mesma declaração. */
+        ...(flat.declaredAxes || dotted.declaredAxes
+            ? {
+                declaredAxes: { ...dotted.declaredAxes, ...flat.declaredAxes },
+            }
+            : {}),
+    };
+}

package/dist/not-expressed.js

@@ -0,0 +1,76 @@
+/**
+ * O QUE ESTA LEITURA NÃO CONSEGUIU SEGURAR, escrito pela esteira e não pedido a ninguém.
+ *
+ * O QUE O CLIENTE GANHA: ele sabe, no minuto do import, o que não chegou - com o número do
+ * repositório dele e o arquivo e a linha de cada caso. É a lei 8 do método: o cliente perdoa o que
+ * a gente diz que não faz, e não perdoa descobrir sozinho.
+ *
+ * POR QUE ISTO EXISTE. O arquivo era escrito pelo AGENTE, instruído por três frases dentro das
+ * descrições das tools do MCP. Em 23/08 o mesmo repositório foi importado duas vezes: a primeira
+ * rodada escreveu 37 linhas de lacunas declaradas, a segunda escreveu nenhuma. As lacunas
+ * continuaram todas lá - 198 declarações de CSS sem leitor, 5 `var()` que não pintam nada -, e só o
+ * aviso desapareceu. Um pedido em texto a um modelo é uma sugestão, e nada percebia quando ela não
+ * era seguida.
+ *
+ * O PISO É DETERMINÍSTICO, e todo dado que ele usa já estava medido no censo. O agente continua
+ * livre para ACRESCENTAR o que só ele viu; o que ele não pode mais é ser a única testemunha.
+ *
+ * `null` quando não há lacuna nenhuma: um arquivo vazio dizendo "nada a declarar" é ruído, e a
+ * ausência do arquivo já é a resposta.
+ */
+export function notExpressed(census) {
+    const ledger = census.ledger;
+    const unread = ledger?.unread ?? [];
+    const broken = census.brokenRefs ?? [];
+    const skipped = census.skipped ?? [];
+    if (unread.length === 0 && broken.length === 0 && skipped.length === 0)
+        return null;
+    const out = [];
+    const scope = census.scope ? ` of \`${census.scope}\`` : "";
+    out.push(`# What this reading could not hold`);
+    out.push("");
+    out.push(`Measured by synthesisui \`${ledger?.cli ?? "unknown"}\`${scope}. Every number here is from` +
+        ` your files. This file is written by the pipeline on every import - what it lists is what` +
+        ` did NOT reach a recipe.`);
+    if (unread.length > 0) {
+        out.push("");
+        out.push("## Style your files hold and no recipe received");
+        for (const group of unread) {
+            out.push("");
+            out.push(`### ${group.uses} ${group.shape} declaration${group.uses === 1 ? "" : "s"}` +
+                ` across ${group.files} file${group.files === 1 ? "" : "s"} - ${group.reason}`);
+            out.push("");
+            out.push(group.because);
+            out.push("");
+            for (const ex of group.examples ?? [])
+                out.push(`    ${ex.file}:${ex.line}   ${ex.text}`);
+        }
+    }
+    if (broken.length > 0) {
+        out.push("");
+        out.push("## Variables referenced and never declared");
+        out.push("");
+        out.push("These do not paint a different colour - they paint nothing. They are yours to fix, in your" +
+            " own words. Up to three places are listed for each; the count says how many there are in" +
+            " total.");
+        out.push("");
+        for (const ref of broken) {
+            out.push(`    ${ref.name}   ${ref.count} reference${ref.count === 1 ? "" : "s"}` +
+                ` in ${ref.files} file${ref.files === 1 ? "" : "s"}`);
+            for (const place of ref.at ?? [])
+                out.push(`        ${place.file}:${place.line}`);
+        }
+    }
+    if (skipped.length > 0) {
+        out.push("");
+        out.push("## Exports the gate left out, and why");
+        out.push("");
+        out.push("Nothing here was dropped in silence. If one of these IS a component of your system, that is" +
+            " a reading to correct - and the reason below is the one to argue with.");
+        out.push("");
+        for (const s of skipped)
+            out.push(`    ${s.name}${s.file ? `  (${s.file})` : ""}\n        ${s.because}`);
+    }
+    out.push("");
+    return `${out.join("\n")}\n`;
+}

package/dist/token-ref.js

@@ -0,0 +1,93 @@
+/**
+ * O NOME QUE UM TOKEN DELE TEM DENTRO DO DOCUMENTO - uma regra, num lugar só.
+ *
+ * O QUE O CLIENTE GANHA: mudar um valor no Studio repinta o componente que o usa. Um ref liga os
+ * dois; um `var()` literal não liga nada - ele renderiza certo hoje e fica órfão da edição.
+ *
+ * ESTA FUNÇÃO EXISTIA DUAS VEZES, em `transcribe.ts` e em `css-modules.ts`, e as duas divergiam: a
+ * segunda não conhecia `--font-*`, então a família de fonte dele virava referência quando lida de uma
+ * classe e `var()` quando lida de uma folha - a mesma decisão dele com dois destinos, dependendo de
+ * onde a esteira olhou. Gêmeo não declarado sempre acaba assim.
+ *
+ * E O GRADIENTE ERA DECIDIDO PELO NOME. A regra reconhecia `--gradient-*`; o cliente escreveu
+ * `--grad-cool`. O escritor da plataforma reconhece pelo VALOR - `linear-gradient(…)` - e guarda em
+ * `foundations.gradients.grad-cool`, então o token TINHA casa no documento e a classe que o usa
+ * apontava para o vazio. É a lei 13 aplicada a token: a origem decide, e aqui a origem é o valor.
+ *
+ * Medido: `--grad-*` são 5 no `codelevel-ui`, `--gradient-*` são 3 no `frontend-hub`, e as duas
+ * grafias passam a chegar onde o documento as guarda.
+ */
+export function tokenRefFor(name, 
+/**
+ * O que cada token DELE vale. O mapa é o que permite reconhecer um gradiente pela forma em vez do
+ * nome; vazio, a decisão volta a ser só pelo nome, que é o comportamento de quem não tem o valor
+ * em mãos.
+ */
+declared) {
+    const bare = name.replace(/^--/, "");
+    if (bare.startsWith("color-"))
+        return refFor(bare.slice("color-".length));
+    if (bare.startsWith("radius-"))
+        return `{radius.${bare.slice(7)}}`;
+    if (bare.startsWith("spacing-"))
+        return `{spacing.${bare.slice(8)}}`;
+    if (bare.startsWith("shadow-"))
+        return `{shadow.${bare.slice(7)}}`;
+    // `--gradient-ui` e `--background-image-gradient-ui` são um token em duas grafias - o namespace de
+    // utility do Tailwind v4 embrulha o primeiro. Os dois chegam a `{gradients.ui}`.
+    if (bare.startsWith("background-image-gradient-")) {
+        return `{gradients.${bare.slice("background-image-gradient-".length)}}`;
+    }
+    if (bare.startsWith("gradient-"))
+        return `{gradients.${bare.slice(9)}}`;
+    if (bare.startsWith("text-")) {
+        /**
+         * O TOKEN COMPANHEIRO. O Tailwind v4 escreve "a altura de linha DE text-body-s" como
+         * `--text-body-s--line-height` - um duplo hífen dentro de um nome. Lido como nome de passo ele
+         * produzia `{typography.scale.body-s--line-height.fontSize}`, cujo duplo hífen nenhuma gramática
+         * de ref aceita, e a receita inteira era RECUSADA na validação (test13, 01/08). O sufixo nomeia a
+         * propriedade; o meio nomeia o passo.
+         */
+        const companion = /^text-(.+?)--(line-height|letter-spacing|font-weight)$/.exec(bare);
+        if (companion) {
+            const prop = {
+                "line-height": "lineHeight",
+                "letter-spacing": "letterSpacing",
+                "font-weight": "weight",
+            }[companion[2]];
+            return `{typography.scale.${companion[1]}.${prop}}`;
+        }
+        // Qualquer outro duplo hífen é um nome que esta gramática não segura - o `var()` literal ainda
+        // resolve contra a folha dele, e um ref inválido não ajuda ninguém.
+        if (bare.slice(5).includes("--"))
+            return `var(${name})`;
+        return `{typography.scale.${bare.slice(5)}.fontSize}`;
+    }
+    if (bare.startsWith("font-"))
+        return `{typography.families.${bare.slice(5)}}`;
+    /**
+     * O GRADIENTE PELA FORMA DO VALOR, e é a última pergunta e não a primeira.
+     *
+     * Os namespaces acima são vocabulário conhecido e ganham deste teste - `--color-brand` que valha um
+     * `linear-gradient` continua sendo cor pelo nome que ele deu. Aqui embaixo estão os nomes que a
+     * gente NÃO modela, e é onde `--grad-cool` cai. A chave é o nome dele inteiro, que é exatamente o
+     * que `gradientsFromCensus` guarda no documento.
+     */
+    const value = declared.get(name);
+    if (value && /\b(?:linear|radial|conic)-gradient\(/.test(value)) {
+        return `{gradients.${bare}}`;
+    }
+    // Um namespace que não modelamos. O `var()` literal continua sendo CSS correto contra a folha
+    // dele, e inventar um ref apontaria para nada.
+    return `var(${name})`;
+}
+/**
+ * `ocean-500` → `{color.ocean.500}`. O passo é o número final; o que vem antes é a família, hífens
+ * intactos, porque `royal-blue-500` é uma família chamada `royal-blue`.
+ */
+function refFor(name) {
+    const m = /^(.*)-(\d{2,4})$/.exec(name);
+    if (!m)
+        return `{color.${name}}`;
+    return `{color.${m[1]}.${m[2]}}`;
+}

package/package.json

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