synthesisui 0.16.285 → 0.16.289

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.
  *
@@ -357,10 +358,29 @@ const FONT_WEIGHT = {
     black: "900",
 };
 /** The three family slots the document actually has. Nothing else may be a ref. */
+/**
+ * O NOME DELE JÁ É O SLOT, e por isso esta tabela tem seis linhas e não três.
+ *
+ * O QUE O CLIENTE VIA: `--font-display: "Bricolage Grotesque"` declarado no `@theme`, a utility
+ * `font-display` escrita no `ModalHeader` e no `Typography` inteiro, e a leitura devolvendo nada -
+ * então o título dele chega no Studio na fonte do corpo (`codelevel-ui`, 23/08).
+ *
+ * As três primeiras traduzem o vocabulário da TAILWIND para o do documento (`font-sans` é o corpo).
+ * As duas últimas são o vocabulário do documento dito por ELE: quem declara `--font-display` não
+ * está pedindo tradução nenhuma, está nomeando o slot. Recusar isso era exigir que ele chamasse a
+ * fonte de display de `serif` para ser ouvido.
+ *
+ * E SÓ OS NOMES LITERAIS DO SLOT - `heading` fica de fora, e a tentação de incluí-lo é o erro que
+ * esta tabela evita. Um projeto pode declarar `--font-heading` E `--font-display` com fontes
+ * diferentes; mapear sinônimo colapsaria as duas em uma e apagaria uma decisão que ele escreveu.
+ * `font-heading` continua não lida, com o motivo no relatório, que é a resposta honesta.
+ */
 const FAMILY_SLOT = {
     sans: "body",
     serif: "display",
     mono: "mono",
+    display: "display",
+    body: "body",
 };
 /** Type utilities with no scale behind them - a fact, not a decision deferred. */
 const TYPE_KEYWORD = {
@@ -1170,8 +1190,67 @@ function readUtilityCore(utility, declared) {
         if (RADIUS[rest])
             return { property: "borderRadius", value: RADIUS[rest] };
     }
+    /**
+     * A UTILITY QUE O `@theme` DELE CRIOU - o último recurso, e é mecanismo, não caso.
+     *
+     * O QUE O CLIENTE VÊ SEM ISTO: o título do `ModalHeader` dele usa `font-display` e
+     * `tracking-tightest`, os dois declarados no `@theme` como `--font-display: "Bricolage
+     * Grotesque"` e `--tracking-tightest: -0.06em`. A leitura devolvia "não resolve nada" para
+     * ambos, então o título chega no Studio na fonte do corpo e sem o aperto de letra que ele
+     * escolheu - e o relatório afirma que a decisão não existe, com ela escrita no código
+     * (`codelevel-ui`, 23/08).
+     *
+     * NO TAILWIND V4 TODO TOKEN DE UM NAMESPACE DO `@theme` CRIA A UTILITY DE MESMO NOME. As tabelas
+     * acima conhecem as escalas que a Tailwind PUBLICA - `tracking-tight`, `text-2xl` -, então toda
+     * escala própria de todo cliente caía neste buraco. A régua aqui não cita um nome de token: ela
+     * pergunta se ELE declarou aquele nome.
+     *
+     * DEPOIS DE TUDO, e não antes: `tracking-tight` continua vindo da tabela fixa, e nenhuma leitura
+     * que já funcionava muda de resposta. Medido nas duas populações: 2 classes resgatadas de 163
+     * não lidas no `codelevel-ui`, 0 de 837 no `frontend-hub`, que não declara namespace próprio.
+     *
+     * SÓ OS NAMESPACES DE ATRIBUIÇÃO DIRETA. `--blur-*` e `--perspective-*` viram
+     * `filter: blur(…)`/`transform`, e escrever a propriedade crua com o valor dentro produziria CSS
+     * inválido - pior que não ler. Ver `tokenRefFor` para como o valor viaja: com ref de documento
+     * onde existe grammar (`{typography.families.display}`) e como `var()` onde não existe, que é
+     * CSS correto contra a folha dele.
+     */
+    const themeProperty = THEME_NAMESPACE[prefix];
+    if (themeProperty && rest) {
+        const own = `--${prefix}-${rest}`;
+        if (declared.has(own)) {
+            return {
+                property: themeProperty,
+                value: tokenRefFor(own, declared),
+                token: own,
+            };
+        }
+    }
     return null;
 }
+/**
+ * Namespace do `@theme` → a propriedade CSS que a utility de mesmo nome escreve.
+ *
+ * Só atribuição direta: cada uma destas escreve `<propriedade>: var(--<namespace>-<nome>)` e nada
+ * mais. `--blur-*` e `--perspective-*` ficam fora porque viram `filter: blur(…)`/`transform`, e a
+ * propriedade crua com o valor dentro seria CSS inválido - pior que não ler.
+ *
+ * QUATRO LINHAS, E NÃO SETE. `text`, `shadow` e `animate` estavam aqui e foram REMOVIDOS depois de
+ * medidos: os ramos acima já os resolvem, então a linha nunca era alcançada. Uma entrada que nada
+ * alcança é a mesma dívida que os specs de alcance existem para impedir - conferido com
+ * `--text-hero`, `--shadow-lifted` e `--animate-drift`, que continuam lidos sem elas.
+ */
+const THEME_NAMESPACE = {
+    /**
+     * `font` NÃO ENTRA AQUI de propósito: o ramo de `font` acima decide sozinho e retorna, então uma
+     * linha para ele seria código que nada alcança. A família dele é resolvida por `FAMILY_SLOT`,
+     * que é onde o slot do documento mora.
+     */
+    tracking: "letterSpacing",
+    leading: "lineHeight",
+    ease: "transitionTimingFunction",
+    aspect: "aspectRatio",
+};
 /**
  * A colour token ref in the document's own spelling.
  *
@@ -1236,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.
@@ -1244,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.
      *
@@ -1264,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 };
 }
 /**
@@ -1288,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 },
+            }
+            : {}),
+    };
+}