synthesisui 0.16.412 → 0.16.413

package/dist/commands/component.js

@@ -536,6 +536,17 @@ export async function component(slug, name, opts) {
             (await installedThemeCss(root, slug)),
         /** O vocabulário DELE sai da conta - ver `theirNames`. O mapa do `.lock` é a via mais barata. */
         theirNames: tongue?.names ? [...tongue.names.values()] : [],
+        /**
+         * A TERCEIRA FONTE NÃO É MEDIDA AQUI, e o vazio é a resposta EXPLÍCITA disso.
+         *
+         * As classes de receita que a folha declara entrariam nesta conta se esta linha entregasse o
+         * `tokens.css` instalado - e o efeito está medido em `steps/11-fora-do-escopo.md`: este comando
+         * diz *"This file needs nothing else… It is yours."* sobre um componente cujo estilo inteiro vem
+         * de `.ds-button`. Ligar a medição aqui é mudar o que este comando promete, com o bloco de setup
+         * dele para redesenhar: é etapa própria. O que o argumento obrigatório garante é que a omissão
+         * está ESCRITA, e não escondida num parâmetro que ninguém passou.
+         */
+        sheetCss: "",
     });
     if (!need.needed) {
         console.log(section("This file needs nothing else"));

package/dist/commands/doctor.js

@@ -916,6 +916,13 @@ export async function doctor(opts) {
         source: scannedSource,
         themeCss,
         theirNames: installed.theirs.byName.keys(),
+        /**
+         * A TERCEIRA FONTE NÃO É MEDIDA AQUI - ver o mesmo comentário em `component.ts` e o número em
+         * `steps/11-fora-do-escopo.md`. Este comando decide `unwired` e `blocked` por `needed`, então
+         * ligar a medição muda o veredito do `doctor` num repositório real: é etapa própria, e o vazio
+         * deixa a omissão escrita em vez de escondida.
+         */
+        sheetCss: "",
     });
     /**
      * BLOQUEADO SÓ QUANDO A FOLHA É NECESSÁRIA - a mesma pergunta que decide `unwired`.

package/dist/commands/hook.js

@@ -57,6 +57,20 @@ async function report(root, filePath) {
     const rel = relative(root, filePath);
     const d = diagnose([scanSource(rel, src, table)]);
     const named = d.findings.filter((f) => nameToWrite(f));
+    /**
+     * O VALOR QUE NADA NOMEIA - dito, e nunca batizado (A1 da etapa 11, escolha dele em 10/09).
+     *
+     * ERA SILÊNCIO, e o silêncio era a única resposta errada disponível. O comentário que estava aqui
+     * dizia que a deriva sem nome "não vale interromper, porque o único conselho honesto é pergunte a
+     * uma pessoa" - e a conclusão não segue da premissa: quem lê um relatório que só fala de valores
+     * nomeáveis não tem como distinguir "não sobrou nada" de "sobrou, e nós engolimos".
+     *
+     * ENTÃO ELE DIZ O VALOR E A LINHA, E PARA AÍ. Nenhum nome nosso é proposto: `--ds-<algo>`
+     * inventado aqui entraria no código dele sem uma pessoa ter decidido, e este comando roda depois
+     * de CADA escrita do agente - é o pior lugar do produto para inventar vocabulário. A seção 0 da
+     * jornada é literal: sem nome no sistema DELE, o valor fica onde está.
+     */
+    const unnamed = d.findings.filter((f) => !nameToWrite(f));
     const phantoms = d.files.flatMap((f) => f.phantoms ?? []);
     // Every check leaves one line in the ledger - INCLUDING the clean ones,
     // because a fix is itself a write, so the clean re-check of a file that was
@@ -70,21 +84,60 @@ async function report(root, filePath) {
         named: named.length,
         phantoms: phantoms.length,
     });
-    // Unnamed drift alone is deliberately NOT worth interrupting for. There is
-    // no token to move to, so the only honest advice is "ask a person" - and
-    // saying that after every edit trains the reader to skip the block.
-    if (named.length === 0 && phantoms.length === 0)
+    if (named.length === 0 && phantoms.length === 0 && unnamed.length === 0)
         return greet(root, rel);
     // A report IS the evidence the greeting exists to provide, so it counts as the
     // introduction. Otherwise a project whose first file had drift would get the
     // "it is live" sentence afterwards, telling somebody who just watched it work.
     await markGreeted(root);
+    /**
+     * QUANDO NÃO HÁ NADA A FAZER NAQUELE ARQUIVO, O RELATÓRIO É DE DUAS LINHAS - e isto é o que
+     * mantém o comando instalado.
+     *
+     * MEDIDO pela revisão de DX no fecho da etapa 11, rodando o scanner deste binário sobre os 38
+     * arquivos de uma biblioteca real com o vocabulário mais generoso possível (as 94 custom
+     * properties que o próprio repositório declara): **20 arquivos (53%) disparam pelo menos um
+     * achado sem nome, e 18 desses 20 têm ZERO achado nomeado** - o relatório inteiro seria o bloco
+     * novo. O cabeçalho deste arquivo é explícito sobre o risco: *"a hook that speaks on every edit
+     * is noise, and noise is what gets a hook removed"*.
+     *
+     * Então a MESMA informação sai em duas formas. Sozinha, ela é uma frase - o valor, a linha, e a
+     * ação, que é não agir. Ao lado de algo acionável, ela é um bloco, porque aí o contraste com a
+     * seta do bloco de cima é o que ensina a diferença entre os dois conjuntos.
+     *
+     * O que NÃO está resolvido, e é decisão dele: a REPETIÇÃO no tempo. Um valor cuja resposta certa
+     * é "deixe como está" volta a ser dito na próxima escrita naquele arquivo, porque não existe
+     * memória por linha e criar uma é comportamento novo. Está medido em `steps/11-fora-do-escopo.md`.
+     */
+    const sample = unnamed
+        .slice(0, 3)
+        .map((f) => `line ${f.line} ${f.literal}`)
+        .join(", ");
+    if (named.length === 0 && phantoms.length === 0)
+        return [
+            `${rel} - ${unnamed.length} value${unnamed.length === 1 ? "" : "s"} here ${unnamed.length === 1 ? "has" : "have"} no name in this system, and nothing to replace ${unnamed.length === 1 ? "it" : "them"} with: ${sample}${unnamed.length > 3 ? `, +${unnamed.length - 3} more` : ""}.`,
+            "Do not invent a name - leave them, or ask the person what they would call it.",
+        ].join("\n");
     const lines = [`${rel} - checked against ${table.name ?? table.slug}.`];
     if (named.length > 0) {
         lines.push("", "Values written by hand that this system already has a name for:", ...named
             .slice(0, 20)
             .map((f) => `  line ${f.line}  ${f.literal} → ${nameToWrite(f)}`), "", "Replace them now, while you still have this file in mind.");
     }
+    if (unnamed.length > 0) {
+        /**
+         * O TÍTULO CARREGA A PROIBIÇÃO, e não a terceira frase de um parágrafo - achado da revisão de
+         * DX: a lista tinha a MESMA forma da lista acionável de cima (`Values written by hand that…`,
+         * uma linha por achado), e um agente que acabou de aprender *"lista de valores → proponha o
+         * token"* recebia aqui uma lista igual com a única frase que interrompe esse reflexo escondida
+         * no fim.
+         */
+        lines.push("", "Not yet named - do NOT invent a name for these:", ...unnamed.slice(0, 20).map((f) => `  line ${f.line}  ${f.literal}`), 
+        /** O QUE FOI CORTADO É DITO - medido num `.css` real: 20 de 252, e as 232 sumiam caladas. */
+        ...(unnamed.length > 20
+            ? [`  … and ${unnamed.length - 20} more in this file`]
+            : []), "", "This system declares no name for them, so there is nothing to replace them with.", "Leave them as they are, or tell the person the value and what THEY would call it.");
+    }
     if (phantoms.length > 0) {
         lines.push("", "Names this system does not declare. These look tokenized and apply nothing at all:", ...phantoms.slice(0, 20).map((p) => `  line ${p.line}  ${p.name}`), "", "Use a name the system has, or say which value you need and what you would call it. Do NOT invent a token.");
     }

package/dist/commands/template.js

@@ -2,8 +2,36 @@ import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, join, relative } from "node:path";
 import { readProjectConfig, resolveRegistry } from "../config.js";
 import { fetchTemplate } from "../registry.js";
+import { installedThemeCss, installedTokensCss, whatOnlyTheSheetResolves, } from "../sheet-needed.js";
 import { inTheirTongue, projectTongue } from "../their-tongue.js";
 import { keptLine, recordWritten, editedHere as theirEdits, } from "../written.js";
+/**
+ * O QUE O ARQUIVO DIZ TAMBÉM É COBRANÇA - e ela é a metade que FICA no repositório dele.
+ *
+ * O DEFEITO, achado pela revisão de DX no fecho da etapa 11: o fecho no terminal parou de mandar
+ * instalar a folha quando a tradução a tornou desnecessária, e o `.tsx` que acabou de ser escrito
+ * continuava abrindo com *"Ensure the DS tokens.css is imported"* e *"Keep the … ds-* classes
+ * (on-system…)"*. O terminal role uma vez; o comentário fica no arquivo que o time dele abre
+ * depois, sem o terminal por perto para desmentir. É a mesma contradição de duas frases que o
+ * critério conserta, um arquivo adiante.
+ *
+ * QUEM SABE A RESPOSTA É ESTE LADO, e é por isso que a linha sai aqui e não no servidor: a
+ * pergunta é *"o REPOSITÓRIO dele ainda precisa da folha?"*, e o codegen do servidor não conhece o
+ * repositório dele. Lá o header é escrito completo, que é a resposta certa para quem não traduziu
+ * nada.
+ *
+ * E O PAR NÃO É VIGIADO POR ACIDENTE: `apps/web/src/lib/ds/the-page-header-can-be-uncharged.spec.ts`
+ * assere que o header do servidor traz exatamente estas duas marcas. Se alguém reescrever a frase
+ * lá, aquele spec fica VERMELHO - em vez de este filtro passar a não casar em silêncio, que é
+ * exatamente como um `replace` por string falha aqui.
+ */
+const SHEET_INSTRUCTION = /tokens\.css is imported|\(on-system/;
+function withoutTheSheetInstruction(code) {
+    return code
+        .split("\n")
+        .filter((line) => !SHEET_INSTRUCTION.test(line))
+        .join("\n");
+}
 /**
  * Materializes a whole page from a DS template into the project (hybrid
  * codegen-first): the server codegens deterministic files, we write them, and
@@ -70,36 +98,75 @@ export async function template(slug, name, opts) {
     let named = 0;
     let inlined = 0;
     const still = new Set();
-    await mkdir(pageDir, { recursive: true });
-    /** OS BYTES QUE FORAM A DISCO, para o fingerprint lembrar EXATAMENTE o que escrevemos. */
-    const landed = [];
-    const spokenPage = speak(pageFile.code);
-    if (spokenPage) {
-        named += spokenPage.named;
-        inlined += spokenPage.inlined;
-        for (const l of spokenPage.left)
+    /**
+     * TRADUZ TUDO ANTES DE ESCREVER NADA, porque a pergunta *"esta pagina precisa da nossa folha?"*
+     * se responde sobre os bytes TRADUZIDOS - e a resposta decide o que vai a disco, nao so' o que o
+     * terminal diz.
+     *
+     * A ordem anterior escrevia e depois media. Funcionava enquanto a medicao servia so' ao fecho no
+     * terminal; no momento em que ela passou a decidir uma linha do ARQUIVO, escrever primeiro era
+     * gravar a decisao errada e corrigi-la na frase seguinte.
+     */
+    const pieces = [];
+    const translate = (code) => {
+        const spoken = speak(code);
+        if (!spoken)
+            return code;
+        named += spoken.named;
+        inlined += spoken.inlined;
+        for (const l of spoken.left)
             still.add(l);
-    }
-    const pageContent = spokenPage ? spokenPage.css : pageFile.code;
-    await writeFile(join(root, pageRel), pageContent, "utf8");
-    landed.push({
+        return spoken.css;
+    };
+    pieces.push({
+        rel: pageRel,
         filename: pageRel.split(/[\\/]/).pop() ?? pageFile.filename,
-        content: pageContent,
+        content: translate(pageFile.code),
     });
-    console.log(`✓ wrote ${pageRel}  (${slug} v${generated.version})`);
-    for (const f of siblings) {
-        const rel = join(dirname(pageRel), f.filename);
-        const spoken = speak(f.code);
-        if (spoken) {
-            named += spoken.named;
-            inlined += spoken.inlined;
-            for (const l of spoken.left)
-                still.add(l);
-        }
-        const content = spoken ? spoken.css : f.code;
-        await writeFile(join(root, rel), content, "utf8");
-        landed.push({ filename: f.filename, content });
-        console.log(`✓ wrote ${rel}`);
+    for (const f of siblings)
+        pieces.push({
+            rel: join(dirname(pageRel), f.filename),
+            filename: f.filename,
+            content: translate(f.code),
+        });
+    /**
+     * A FOLHA SÓ É COBRADA QUANDO ESTA PÁGINA PRECISA DELA (A2 da etapa 11) - ver
+     * `sheet-needed.ts`, a mesma porta que o `component` usa.
+     *
+     * O DEFEITO, medido em 10/09: o comando já contava em `still` quantas referências sobraram
+     * apontando para a nossa folha depois da tradução, imprimia o número, e três linhas abaixo
+     * mandava instalar a folha e colar um `@import` - inclusive quando o número era ZERO. Uma página
+     * que renderiza igual sem os dois passava a pedi-los, e pedir cria exatamente a dependência que
+     * a plataforma promete não criar: a gente é referência, não dependência.
+     *
+     * E A PERGUNTA É MAIOR QUE `still`, que é por que ela não é feita com ele: a folha entrega as
+     * variáveis, as classes que só o `@theme` gera E as classes das receitas (`.ds-hero`). Uma
+     * página veste as três, e cortar o setup contando só as variáveis entregaria uma página pelada.
+     *
+     * SEM TRADUÇÃO, NADA MUDA: sem o mapa do `.lock` o `--ds-*` cru está no arquivo, a folha é o
+     * caminho, e a cobrança sai inteira como sempre saiu.
+     */
+    const need = tongue
+        ? whatOnlyTheSheetResolves({
+            source: pieces.map((f) => f.content).join("\n"),
+            themeCss: await installedThemeCss(root, slug),
+            sheetCss: await installedTokensCss(root, slug),
+            theirNames: [...tongue.names.values()],
+        })
+        : null;
+    const chargesTheSheet = !need || need.needed;
+    await mkdir(pageDir, { recursive: true });
+    /** OS BYTES QUE FORAM A DISCO, para o fingerprint lembrar EXATAMENTE o que escrevemos. */
+    const landed = [];
+    for (const piece of pieces) {
+        const content = chargesTheSheet
+            ? piece.content
+            : withoutTheSheetInstruction(piece.content);
+        await writeFile(join(root, piece.rel), content, "utf8");
+        landed.push({ filename: piece.filename, content });
+        console.log(piece.rel === pageRel
+            ? `✓ wrote ${piece.rel}  (${slug} v${generated.version})`
+            : `✓ wrote ${piece.rel}`);
     }
     /**
      * E O REGISTRO E' GRAVADO - a outra metade da guarda, e sem ela a primeira nunca dispara.
@@ -120,8 +187,28 @@ export async function template(slug, name, opts) {
     console.log("Next steps:");
     console.log(`  • use it in a route, e.g. ${join(config.pagesDir, "page.tsx")}:`);
     console.log(`      import Page from "@/${defaultDir.replace(/\\/g, "/")}/${pageFile.filename.replace(/\.tsx$/, "")}";`);
-    console.log(`  • ensure the DS is installed: synthesisui add ${slug} (provides tokens.css)`);
-    console.log(`  • @import "_synthesisui/ds/${slug}/tokens.css" in your global CSS`);
+    if (chargesTheSheet) {
+        /** E ELE DIZ O QUE PEDE A FOLHA - um setup cobrado sem motivo dito ensina a ignorar o próximo. */
+        if (need)
+            console.log(`  • what still needs the sheet here: ${[...need.recipeClasses, ...need.classes, ...need.variables].slice(0, 3).join(", ")}`);
+        console.log(`  • ensure the DS is installed: synthesisui add ${slug} (provides tokens.css)`);
+        console.log(`  • @import "_synthesisui/ds/${slug}/tokens.css" in your global CSS`);
+    }
+    else {
+        console.log(`  • nothing to install: every value in this page is a name YOUR code declares, so it renders without our stylesheet`);
+    }
     console.log("  • refine the file: wire real data, split into components, swap placeholders");
-    console.log(`  • keep the data-ds="${slug}" wrapper and the ds-* / layout classes (stays on-system)`);
+    /**
+     * E A LINHA DO ESCOPO SÓ SAI ONDE ELA É VERDADE - medido rodando o comando em 10/09.
+     *
+     * Ela mandava *"keep the data-ds wrapper and the ds-* classes (stays on-system)"* sempre, e no
+     * caminho isolado a saída ficava contradizendo a linha logo acima: *"nothing to install… it
+     * renders without our stylesheet"* e, uma linha depois, uma instrução para manter um escopo que
+     * não resolve nada naquele arquivo. É o mesmo defeito que este bloco existe para consertar - duas
+     * frases que não podem ser verdadeiras ao mesmo tempo -, e a medição já responde qual das duas é:
+     * chegar aqui com `chargesTheSheet` falso significa zero variável nossa e zero classe nossa no
+     * que acabou de ser escrito.
+     */
+    if (chargesTheSheet)
+        console.log(`  • keep the data-ds="${slug}" wrapper and the ds-* / layout classes (stays on-system)`);
 }

package/dist/doctor/ci-format.js

@@ -23,7 +23,7 @@
  * checagem que telefona para casa é uma checagem que alguém desinstala.
  */
 import { isOlderCli } from "../cli-version.js";
-import { CHECKER_SINCE } from "../install-marks.js";
+import { COUNTED_DIFFERENTLY, COUNTED_DIFFERENTLY_SINCE, } from "../install-marks.js";
 const byFileOf = (d) => {
     const out = {};
     for (const f of d.files)
@@ -75,10 +75,12 @@ export function compareToBaseline(d, base, now) {
      * prometia o contrário desde o primeiro dia (*"um número que sobe porque o leitor melhorou não é
      * regressão"*), e `incomparable` existia para exatamente isto.
      *
-     * A RÉGUA É A MARCA QUE JÁ EXISTE: `CHECKER_SINCE` é a última versão em que a leitura que o CI
-     * compara mudou de resposta, e ela sobe no mesmo PR que muda a leitura. Nada de limiar novo.
+     * A RÉGUA É `COUNTED_DIFFERENTLY_SINCE`, em `install-marks.ts`: a última versão em que a CONTAGEM
+     * que o CI compara mudou de resposta. Ela mora na casa das outras marcas porque é lá que está a
+     * disciplina de mantê-las - uma marca à mão sem portão é uma marca errada esperando a hora -, e
+     * não é a MESMA das outras: emprestar `CHECKER_SINCE` foi exatamente o defeito que a criou.
      */
-    const readerMoved = base.cli !== undefined && isOlderCli(base.cli, CHECKER_SINCE);
+    const readerMoved = base.cli !== undefined && isOlderCli(base.cli, COUNTED_DIFFERENTLY_SINCE);
     return {
         worse: !scopeChanged &&
             !readerMoved &&
@@ -95,7 +97,7 @@ export function compareToBaseline(d, base, now) {
             }
             : readerMoved
                 ? {
-                    incomparable: `the baseline was written by CLI ${base.cli}, and this run counts every length in a shorthand - that version counted only the first. The rise is in the reading, not in your code. Rewrite the line before comparing: npx synthesisui doctor --write-baseline`,
+                    incomparable: `the baseline was written by CLI ${base.cli}, and ${COUNTED_DIFFERENTLY}. The rise is in the reading, not in your code. Rewrite the line before comparing: npx synthesisui doctor --write-baseline`,
                 }
                 : {}),
     };

package/dist/install-marks.js

@@ -275,7 +275,37 @@ export const MATERIALISER_SINCE = "0.16.412";
  * não via, 14% e 16% das declarações de espaço/raio. Um hook pinado antes desta versão aconselha
  * MENOS, que é a régua desta marca.
  */
-export const CHECKER_SINCE = "0.16.408";
+/**
+ * A ÚLTIMA VERSÃO EM QUE A CONTAGEM QUE O CI COMPARA MUDOU DE RESPOSTA - a régua da catraca, e ela
+ * mora aqui porque é onde a disciplina mora.
+ *
+ * ELA ERA `CHECKER_SINCE`, e as duas perguntas não são a mesma. Aquela significa *"o que o hook
+ * ENTREGA mudou"*, e sobe também quando ele passa a DIZER algo novo sobre os mesmos achados - o que
+ * aconteceu em 10/09. Com a régua emprestada, aquela subida declararia INCOMPARÁVEL todo baseline
+ * gravado entre as duas versões: a catraca pararia de reprovar regressão de verdade até o time
+ * regravar a linha, e a frase abaixo diria a ele um motivo que não é o dele. Foi o caso negativo do
+ * `doctor/ci-format.spec.ts` que acendeu isso, sozinho.
+ *
+ * A PERGUNTA DO PASSO 1 GANHA UMA SEGUNDA METADE por causa dela, e as duas se fazem no mesmo
+ * vermelho do fingerprint do CHECKER (que já inclui `doctor/scan.ts`, quem conta):
+ *
+ *     o hook aconselha diferente?  -> `CHECKER_SINCE`
+ *     a CONTAGEM mudou de valor?   -> `COUNTED_DIFFERENTLY_SINCE`, e a FRASE junto
+ *
+ * A frase viaja ao lado da versão porque as duas são uma coisa só: quem move a marca troca a
+ * explicação no mesmo lugar, em vez de deixar o CI citando a causa da marca anterior.
+ */
+export const COUNTED_DIFFERENTLY_SINCE = "0.16.408";
+export const COUNTED_DIFFERENTLY = "this run counts every length in a shorthand - that version counted only the first";
+/**
+ * 0.16.408 -> 0.16.413 em 10/09: o hook passa a DIZER o valor que nada nomeia. Ele silenciava toda
+ * deriva sem token de destino - a decisão estava escrita como "não vale interromper, porque o único
+ * conselho honesto é pergunte a uma pessoa" -, e o silêncio é a única resposta errada disponível:
+ * quem lê um relatório que só fala de valores nomeáveis não distingue "não sobrou nada" de "sobrou,
+ * e nós engolimos". Agora sai `line 12  #ff00aa`, sem uma única proposta de nome nosso. Um hook
+ * pinado antes desta versão aconselha MENOS, que é a régua desta marca.
+ */
+export const CHECKER_SINCE = "0.16.413";
 /**
  * A ÚLTIMA VERSÃO EM QUE OS LEITORES PASSARAM A PRODUZIR UM CENSO DIFERENTE.
  *

package/dist/sheet-needed.js

@@ -1,6 +1,74 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { TAILWIND_THEME_VARS } from "./tailwind-theme-vars.js";
+/**
+ * AS CLASSES QUE A FOLHA COMPILADA DECLARA COMO RECEITA - o nome, não o prefixo.
+ *
+ * A convenção viaja com o sistema (`ds-`, `sui-`, o que o projeto dele usa), então perguntar pelo
+ * prefixo seria fixar a forma de um repositório. O que é estrutural é onde a regra MORA: o
+ * compilador emite uma regra por receita dentro de `@layer components`, e é só essa camada que a
+ * folha traz e o projeto dele não tem.
+ *
+ * A PRIMEIRA VERSÃO VARRIA O TEXTO INTEIRO, e a revisão do fecho mediu o preço na folha viva do
+ * `codelevel` (143.409 bytes, versão instalada): **147 nomes extraídos, 3 deles não são receita** -
+ * `dark`, que é a classe DELE em `@layer base`; `layer-3d`, um utilitário DELE espelhado em
+ * `@layer utilities`; e `background`, que aparecia como VALOR de uma declaração e nem seletor era.
+ * Rodada sobre o repositório dele, a função devolvia `["layer-3d", "dark"]` - duas classes DELE
+ * sustentando a cobrança da NOSSA folha. É o defeito de 07/09 voltando pela porta do balde novo, e
+ * o oposto exato do que esta medição existe para permitir.
+ *
+ * O ESCAPE CONTA como parte do nome, porque no CSS ele é como se escreve um caractere que o
+ * seletor não aceita cru: `.ds-w-\[10px\]` é a classe `ds-w-[10px]`, e `.sm\:ds-hero` é a variante
+ * `sm:` da classe `ds-hero` - que é como o código dele a escreve. Truncar no `\` produziria os
+ * nomes `ds-w-` e `sm`, que ninguém escreve: uma dependência real deixaria de ser contada, e esse é
+ * o único lado do erro que o cabeçalho deste módulo declara inaceitável.
+ */
+export function classesTheSheetDeclares(css) {
+    const out = new Set();
+    for (const body of layerBodies(css, "components"))
+        for (const prelude of selectorPreludes(body))
+            for (const m of prelude.matchAll(/\.((?:\\.|[\w-])+)/g)) {
+                const bare = m[1].replace(/\\(.)/g, "$1");
+                /** A MESMA normalização que `classesIn` aplica ao que ele ESCREVE - `sm:ds-hero` é `ds-hero`. */
+                out.add((bare.split(":").pop() ?? bare).replace(/^[!-]/, ""));
+            }
+    return [...out];
+}
+/** O corpo de cada `@layer <nome> { … }`, com as chaves de dentro contadas. */
+function layerBodies(css, name) {
+    const out = [];
+    for (const m of css.matchAll(new RegExp(`@layer\\s+${name}\\s*\\{`, "g"))) {
+        let depth = 1;
+        let i = (m.index ?? 0) + m[0].length;
+        const start = i;
+        for (; i < css.length && depth > 0; i += 1) {
+            const c = css[i];
+            if (c === "{")
+                depth += 1;
+            else if (c === "}")
+                depth -= 1;
+        }
+        out.push(css.slice(start, i - 1));
+    }
+    return out;
+}
+/**
+ * O PRELÚDIO DE CADA REGRA - o texto entre o fim da regra anterior e a `{` desta.
+ *
+ * É o que separa um SELETOR de um valor de declaração: `background: p.background` mora depois da
+ * `{`, e nunca chega aqui. Um prelúdio que começa com `@` é uma regra de agrupamento (`@media`,
+ * `@supports`) e não declara classe nenhuma - o corpo dela é varrido pela mesma volta do laço.
+ */
+function selectorPreludes(body) {
+    const out = [];
+    const parts = body.split("{");
+    for (const part of parts.slice(0, -1)) {
+        const tail = part.slice(part.lastIndexOf("}") + 1).trim();
+        if (tail && !tail.startsWith("@"))
+            out.push(tail);
+    }
+    return out;
+}
 /** `--animate-shimmer` no `@theme` -> o nome `shimmer`, que é o que uma classe carrega. */
 function themeNames(themeCss) {
     const out = new Set();
@@ -207,14 +275,33 @@ export function whatOnlyTheSheetResolves(input) {
     const classes = [
         ...new Set([...written].filter((c) => names.some((n) => c === n || c.endsWith(`-${n}`)))),
     ];
+    /** As classes que a folha declara e que ESTE texto veste - ver `recipeClasses`. */
+    const declared = new Set(classesTheSheetDeclares(input.sheetCss));
+    const recipeClasses = [
+        ...new Set([...written].filter((c) => declared.has(c))),
+    ];
     return {
         variables,
         classes,
-        needed: variables.length > 0 || classes.length > 0,
+        recipeClasses,
+        needed: variables.length > 0 || classes.length > 0 || recipeClasses.length > 0,
     };
 }
+/** A folha compilada da versão instalada - as receitas moram nela, não no `theme.css`. */
+export async function installedTokensCss(root, slug) {
+    return installedSheet(root, slug, "tokens.css");
+}
 /** O `theme.css` da versão instalada - a folha da raiz é um re-export de uma linha. */
 export async function installedThemeCss(root, slug) {
+    return installedSheet(root, slug, "theme.css");
+}
+/**
+ * UM ARQUIVO DA VERSÃO PINADA - o `.lock` diz qual é, e a folha da raiz é um re-export de uma linha.
+ *
+ * Uma leitura só para as duas folhas: duas cópias da mesma decisão de versão é a forma de uma delas
+ * ficar atrás no dia em que o formato do `.lock` mudar.
+ */
+async function installedSheet(root, slug, filename) {
     const dir = join(root, "_synthesisui", "ds", slug);
     const lock = await readFile(join(dir, ".lock"), "utf8").catch(() => null);
     let version = 0;
@@ -226,5 +313,5 @@ export async function installedThemeCss(root, slug) {
             version = 0;
         }
     }
-    return readFile(join(dir, `v${version}`, "theme.css"), "utf8").catch(() => "");
+    return readFile(join(dir, `v${version}`, filename), "utf8").catch(() => "");
 }

package/package.json

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