synthesisui 0.16.284 → 0.16.286

package/dist/commands/add.js

@@ -490,20 +490,39 @@ export async function add(slug, opts) {
         ? nextFontSnippet(families, payload.slug, appDir)
         : null;
     if (nextFonts) {
-        const fontsPath = join(projectRoot, ...appDir.split("/"), "fonts.ts");
-        let wroteFonts = false;
-        if (!(await exists(fontsPath)) &&
-            (await exists(join(projectRoot, ...appDir.split("/"))))) {
+        /**
+         * UM `fonts.ts` POR APP, e não só no primeiro - lacuna do próprio conserto de 22/08.
+         *
+         * Aquele conserto ensinou o `add` a ENCONTRAR os apps de um monorepo e a NOMEAR todos eles, e
+         * depois escrevia em um só. Metade da fiação entregue é a metade que engana: o cliente lê que
+         * dois apps foram encontrados, vê o arquivo aparecer, e descobre que o segundo ficou sem quando
+         * a tipografia dele não carrega.
+         *
+         * Cada app tem o seu, porque `next/font` é por app: o `layout.tsx` de cada um importa do próprio
+         * `fonts.ts`. Um arquivo compartilhado atravessaria a fronteira do workspace.
+         */
+        const wroteIn = [];
+        for (const dir of appDirs.length > 0 ? appDirs : [appDir]) {
+            const fontsPath = join(projectRoot, ...dir.split("/"), "fonts.ts");
+            /** Arquivo dele que já existe nunca é reescrito - o setup impresso diz o que ele deve exportar. */
+            if (await exists(fontsPath))
+                continue;
+            if (!(await exists(join(projectRoot, ...dir.split("/")))))
+                continue;
+            const snippet = nextFontSnippet(families, payload.slug, dir);
+            if (!snippet)
+                continue;
             const header = [
                 `// Self-hosted type for the "${payload.slug}" design system (via next/font -`,
                 `// preloaded, no font flash). Generated by \`synthesisui add\`; edit freely.`,
             ];
-            await writeFile(fontsPath, `${[...header, ...nextFonts.fontsFile.slice(1)].join("\n")}\n`, "utf8");
-            wroteFonts = true;
+            await writeFile(fontsPath, `${[...header, ...snippet.fontsFile.slice(1)].join("\n")}\n`, "utf8");
+            wroteIn.push(`${dir}/fonts.ts`);
         }
+        const wroteFonts = wroteIn.length > 0;
         console.log("");
         if (wroteFonts) {
-            console.log(line(`3. ✓ wrote ${appDir}/fonts.ts - self-hosted type via next/font (preloaded, no font flash).`));
+            console.log(line(`3. ✓ wrote ${wroteIn.join(", ")} - self-hosted type via next/font (preloaded, no font flash).`));
             console.log(line("   Finish the wiring with two small edits:"));
         }
         else {

package/dist/commands/import.js

@@ -732,9 +732,21 @@ export async function takeCensus(root, opts) {
                     if (esize > 0 || etag || esketch.length > 0) {
                         looks[extra.name] = {
                             ...(esketch.length > 0 ? { sketch: esketch } : {}),
-                            /** Ver `CensusLook.aside` - o segundo componente do arquivo também. */
-                            ...(classifyAside(extra.name)
-                                ? { aside: classifyAside(extra.name) }
+                            /**
+                             * 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.
+                             */
+                            ...(classifyAside({ name: extra.name, declaredAxes: undefined })
+                                ? {
+                                    aside: classifyAside({
+                                        name: extra.name,
+                                        declaredAxes: undefined,
+                                    }),
+                                }
                                 : {}),
                             ...et,
                             ...(etag ? { rootTag: etag } : {}),
@@ -1025,9 +1037,19 @@ export async function takeCensus(root, opts) {
                 if (size > 0 || tag) {
                     looks[found[0].name] = {
                         ...(sketch.length > 0 ? { sketch } : {}),
-                        /** Ver `CensusLook.aside`: o fato viaja, a regra fica de um lado só. */
-                        ...(classifyAside(found[0].name)
-                            ? { aside: classifyAside(found[0].name) }
+                        /**
+                         * 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`.
+                         */
+                        ...(classifyAside({ name: found[0].name, declaredAxes: v.axes })
+                            ? {
+                                aside: classifyAside({
+                                    name: found[0].name,
+                                    declaredAxes: v.axes,
+                                }),
+                            }
                             : {}),
                         ...withoutDark,
                         base,
@@ -2848,6 +2870,23 @@ export function ladderReach(declared) {
     }
     return { light, dark };
 }
+/**
+ * QUEM DÁ NOME AO SISTEMA, e o cliente para de ganhar um sistema morto.
+ *
+ * O QUE ELE VIVEU EM 23/08: respondeu "CodeLevel" à pergunta do nome, o agente escreveu isso em
+ * `reading.name` - o campo certo -, e o sistema nasceu como `repo-ui`, tirado do `@repo/ui` do
+ * `package.json`. O slug não muda depois de criado, então corrigir custou um segundo import e ele
+ * ficou com dois sistemas para uma biblioteca, um deles morto, e nenhum caminho de volta que não
+ * seja apagar à mão.
+ *
+ * A ORDEM É A MESMA DO `scheme`, dez linhas abaixo de onde isto é chamado: a flag é uma decisão
+ * digitada agora, a leitura é uma resposta que alguém já deu, e a pergunta é o último recurso.
+ * `null` quer dizer "ninguém disse" - o ÚNICO caso em que se pergunta - e é o que fecha a porta:
+ * não há como esta função devolver um palpite quando existe uma resposta.
+ */
+export function chosenName(input) {
+    return input.flag?.trim() || input.read?.trim() || null;
+}
 export function deriveName(pkgName, dirName) {
     const raw = (pkgName ?? "").trim();
     const scoped = /^@([^/]+)\/(.+)$/.exec(raw);
@@ -3671,7 +3710,8 @@ export async function runImport(opts) {
         return;
     }
     const suggested = deriveName(census.project.name, basename(root) || "system");
-    const chosen = opts.name?.trim() || (await askName(suggested));
+    const chosen = chosenName({ flag: opts.name, read: census.reading?.name }) ??
+        (await askName(suggested));
     const reach = ladderReach(census.declared);
     // An explicit flag is a decision already made. Otherwise the person answers,
     // starting from the agent's reading if there is one and from the ladder's own

package/dist/commands/sync.js

@@ -150,7 +150,24 @@ export async function sync(opts) {
     const requests = await readRequests(root);
     /** O que ele declarou sobre as formas dele - ver `declared-forms.ts`. */
     const forms = await readDeclaredForms(root);
-    if (events.length === 0 && requests.length === 0) {
+    /**
+     * O REGISTRO ESTAR VAZIO NÃO É MOTIVO PARA NÃO ENVIAR NADA - e era, e isso custou uma promessa.
+     *
+     * O QUE O CLIENTE PERDIA. O estado do repositório - em que versão ele está, com qual CLI - viaja no
+     * MESMO pacote que o registro de checagens. Este `return` acontecia antes do envio, e ele dispara
+     * exatamente no estado de quem acabou de instalar: o hook nunca rodou, então não há evento nenhum.
+     *
+     * Resultado medido em 22/08: `repo_state` nulo em 25 dos 26 sistemas em produção. A tela nunca
+     * conseguiu dizer *"você está na v1 e existe a v2"*, para ninguém, desde que a coluna existe.
+     *
+     * A ROTA JÁ ESTAVA PRONTA, e é isso que faz disto meia jornada e não uma feature faltando:
+     * `api/ledger` grava o estado antes dos eventos e diz por quê - *"gravá-lo não depende de haver
+     * evento nenhum"*. Os dois lados concordavam; o cliente é que voltava antes de falar.
+     *
+     * A frase continua sendo dita - ela é verdade e é útil. O que muda é que ela para de ser uma saída.
+     */
+    const emptyLedger = events.length === 0 && requests.length === 0;
+    if (emptyLedger && !repo && forms.length === 0) {
         console.log(section("Sync"));
         console.log(body("Nothing recorded yet. The record fills as the hook checks writes and doctor runs."));
         return;
@@ -209,7 +226,15 @@ export async function sync(opts) {
      */
     const gained = await inherit(root, out.inheritedForms ?? []);
     console.log(section("Sync"));
-    console.log(body(`${out.eventsReceived} checks sent, ${out.eventsNew} new. ${out.requestsNow} open request${out.requestsNow === 1 ? "" : "s"}.`));
+    /**
+     * "0 CHECKS SENT" NÃO É O QUE ACONTECEU quando o registro está vazio e o estado do repo foi.
+     *
+     * A frase antiga contava eventos; num repositório recém-instalado ela leria "0 checks sent, 0 new"
+     * e esconderia a única coisa que realmente subiu. Quem lê "0" conclui que o comando não fez nada.
+     */
+    console.log(body(emptyLedger
+        ? `No checks recorded here yet - the record fills as the hook checks writes and doctor runs.${repo ? " This repo's installed version was sent, so the platform can tell you when a newer one exists." : ""}`
+        : `${out.eventsReceived} checks sent, ${out.eventsNew} new. ${out.requestsNow} open request${out.requestsNow === 1 ? "" : "s"}.`));
     if (gained > 0) {
         console.log("");
         console.log(body(`${gained} form${gained === 1 ? "" : "s"} your team already taught the pipeline now apply here too - the next measurement reads them without you declaring anything.`));

package/dist/doctor/crosswalk.js

@@ -293,10 +293,36 @@ export function axisOverlap(a, b) {
  */
 const IS_ICON = /(^Icon|Icon$)/;
 const IS_PROVIDER = /(Provider|Context)$/;
-export function classifyAside(name) {
-    if (IS_ICON.test(name))
+/**
+ * O QUE O CLIENTE GANHA: o componente dele para de desaparecer por causa do nome.
+ *
+ * Um glifo é modelado como biblioteca de ícones e não como receita - decisão de produto, e ela
+ * continua valendo. O que mudou é QUEM decide. O nome decidia sozinho, e em 23/08 isso custou o
+ * `IconButton` do `codelevel-ui`: três eixos declarados (`glow`, `size`, `variant`), a forma
+ * aninhada já derivada, e nenhuma linha no design system dele. Quem abrisse o Studio pediria um
+ * botão de ícone e ouviria que o sistema não tem - com o componente pronto no código.
+ *
+ * A lei 13 diz que a origem decide e não o nome, e um regex sobre o nome é exatamente o caso
+ * especial que ela proíbe. O discriminante estava no dado, e foi medido nas DUAS populações:
+ *
+ *     frontend-hub    43 nomes casam o regex ·  0 declaram eixos
+ *     codelevel-ui     3 nomes casam o regex ·  2 declaram eixos
+ *
+ * UM GLIFO NÃO DECLARA VARIAÇÃO - é um desenho, e desenho não tem `variant`. Quem declara eixos
+ * escreveu um contrato, e contrato é receita. Nenhum dos 43 do repositório real muda de lado, então
+ * a regra não afrouxou: ela passou a perguntar a coisa certa.
+ *
+ * `props` NÃO serve para isto, e a diferença é o caso do `Icon` dele: recebe `size` e `color` no uso
+ * e não declara nem um nem outro. Uso é o que alguém escolheu; declaração é o que o autor desenhou.
+ *
+ * A FORMA VEM INTEIRA, e não como segundo parâmetro opcional (§6): um argumento que pode ser
+ * esquecido é o defeito que este conserto está desfazendo, e não há como chamar isto pela metade.
+ */
+export function classifyAside(shape) {
+    const declares = Object.keys(shape.declaredAxes ?? {}).length > 0;
+    if (IS_ICON.test(shape.name) && !declares)
         return "icon";
-    if (IS_PROVIDER.test(name))
+    if (IS_PROVIDER.test(shape.name))
         return "provider";
     return null;
 }
@@ -429,7 +455,10 @@ opts) {
     }
     return mine
         .map((component) => {
-        const aside = classifyAside(component.name);
+        const aside = classifyAside({
+            name: component.name,
+            declaredAxes: component.declaredAxes,
+        });
         if (aside) {
             return {
                 component,

package/dist/doctor/transcribe.js

@@ -357,10 +357,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 +1189,63 @@ 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), 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.
  *

package/dist/install-marks.js

@@ -128,7 +128,7 @@
  * é sempre o bump deste PR - nunca o número que o `package.json` já carrega, porque alguém pode
  * publicar no meio.
  */
-export const MATERIALISER_SINCE = "0.16.284";
+export const MATERIALISER_SINCE = "0.16.285";
 /**
  * A ÚLTIMA VERSÃO EM QUE O QUE O HOOK RODA MUDOU.
  *

package/package.json

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