synthesisui 0.16.401 → 0.16.403

package/dist/commands/add.js

@@ -8,6 +8,7 @@ import { lockReference } from "../group-role.js";
 import { buildGuide } from "../guide.js";
 import { censusScope } from "../measured-scope.js";
 import { recallAvailable } from "../memory/availability.js";
+import { nextFontFacts } from "../next-font-weights.js";
 import { body as line, section, snippet } from "../output.js";
 import { fetchDesignSystem } from "../registry.js";
 import { repoStateOf } from "../repo-state.js";
@@ -233,7 +234,16 @@ export async function add(slug, opts) {
      * função responde: cortar sem caminho de volta trocaria contexto por ignorância.
      */
     const tools = await recallAvailable(projectRoot);
-    await writeFile(join(versionDir, "GUIDE.md"), buildGuide(payload, tools.available), "utf8");
+    /**
+     * OS PESOS DAS FAMÍLIAS, LIDOS UMA VEZ - ver `next-font-weights.ts`.
+     *
+     * Aqui, e não junto do passo 3 do setup, porque o GUIA também imprime o bloco do `next/font`
+     * para o cliente colar: dois leitores do mesmo manifesto poderiam discordar, e o guia é o
+     * arquivo que o agente dele lê antes de escrever. `null` em projeto que não é Next é a resposta
+     * certa, não uma falha - lá não existe `next/font` para ter peso nenhum.
+     */
+    const fontFacts = await nextFontFacts(projectRoot);
+    await writeFile(join(versionDir, "GUIDE.md"), buildGuide(payload, tools.available, fontFacts), "utf8");
     // 4. stable root re-exports for each CSS artifact → always the active version,
     //    so the consumer's @import path never changes across updates
     const cssArtifacts = Object.keys(payload.artifacts).filter((f) => f.endsWith(".css") && !(f === "shadcn.css" && !wantsShadcn));
@@ -671,9 +681,71 @@ export async function add(slug, opts) {
     //    "blink". The Google Fonts <link> stays as the framework-agnostic path.
     const families = payload.document.foundations.typography.families;
     const fontsHref = googleFontsHref(families);
-    const nextFonts = projectConfig.target === "next"
-        ? nextFontSnippet(families, payload.slug, appDir, payload.fontSeam)
+    /**
+     * OS PESOS QUE AS FAMÍLIAS TÊM NO PROJETO DELE - ver `next-font-weights.ts`.
+     *
+     * Lido UMA vez e passado adiante: o manifesto tem 1942 famílias, e reabri-lo por app de um
+     * monorepo seria a mesma leitura repetida com liberdade de discordar de si mesma.
+     */
+    const fontPlan = projectConfig.target === "next"
+        ? nextFontSnippet({
+            families,
+            slug: payload.slug,
+            appDir,
+            seam: payload.fontSeam,
+            facts: fontFacts,
+            declaredWeights: payload.document.foundations.typography.weights,
+        })
         : null;
+    const nextFonts = fontPlan?.ok ? fontPlan : null;
+    /**
+     * A LACUNA DE PESO, DITA EM VOZ ALTA (lei 8) - e ela é o oposto de um arquivo escrito errado.
+     *
+     * Sem o manifesto do `next/font` ao alcance, emitir `weight` seria adivinhar, e a adivinhação
+     * derrubou o `next build` de um projeto real em 08/09. Então o arquivo não sai, e o cliente
+     * recebe o motivo mais o caminho que funciona.
+     */
+    /**
+     * A LACUNA DE FONTE, DITA COM A CAUSA CERTA (lei 8) - e as duas causas pedem frases diferentes.
+     *
+     * Sem manifesto, não sabemos os pesos de NENHUMA família e emiti-los seria adivinhar - a
+     * adivinhação derrubou o `next build` de um projeto real em 08/09. Com manifesto legível e
+     * família desconhecida, o diagnóstico é outro: aquela fonte não é do Google Fonts, e nem o
+     * `next/font/google` nem o `<link>` a servem. Dizer a primeira frase no segundo caso é um
+     * diagnóstico falso, e manda a pessoa para um caminho que não existe para ela.
+     *
+     * SEM NÚMERO, de propósito: o passo 3 é impresso logo abaixo, e dois blocos numerados "3." na
+     * mesma tela é a família de defeito que este PR conserta.
+     */
+    if (fontPlan && !fontPlan.ok && fontPlan.why === "manifest-unreadable") {
+        console.log("");
+        console.log(line(`next/font: ${appDir}/fonts.ts was NOT written - this project's next/font manifest`));
+        console.log(line(`is not readable from here, so the weights ${fontPlan.families.join(", ")} actually`));
+        console.log(line(`${fontPlan.families.length === 1 ? "ships" : "ship"} cannot be read - and asking for a weight a family does not ship fails`));
+        console.log(line(`\`next build\`. Step 3 below works everywhere; add next/font yourself if you`));
+        console.log(line(`want it self-hosted.`));
+    }
+    if (fontPlan && !fontPlan.ok && fontPlan.why === "family-unknown") {
+        console.log("");
+        console.log(line(`next/font: ${appDir}/fonts.ts was NOT written - Google Fonts has no ${fontPlan.families.join(", ")},`));
+        console.log(line(`so neither next/font/google nor the link below can serve ${fontPlan.families.length === 1 ? "it" : "them"}. ${fontPlan.families.length === 1 ? "This is" : "These are"} yours to`));
+        console.log(line(`load - a licensed or self-hosted face, most likely - and the token names are`));
+        console.log(line(`already in tokens.css waiting for ${fontPlan.families.length === 1 ? "it" : "them"}.`));
+    }
+    /**
+     * E A FAMÍLIA QUE FICOU DE FORA DO ARQUIVO É NOMEADA - ver `unknown` em `fonts.ts`.
+     *
+     * Com duas famílias e só uma no manifesto, a segunda saía do `fonts.ts`, do `layout` e do mapa de
+     * CSS sem uma palavra: o token dela continua no `tokens.css` e o texto sai no fallback do
+     * navegador. Este módulo já dizia isso sobre o caso vizinho - *"um token que aponta para uma
+     * fonte que ninguém carregou é pior que um token ausente"*.
+     */
+    if (nextFonts && nextFonts.unknown.length > 0) {
+        console.log("");
+        console.log(line(`next/font: ${nextFonts.unknown.join(", ")} ${nextFonts.unknown.length === 1 ? "is" : "are"} NOT in ${appDir}/fonts.ts - Google Fonts`));
+        console.log(line(`has no such family, so ${nextFonts.unknown.length === 1 ? "it is" : "they are"} yours to load. The token${nextFonts.unknown.length === 1 ? "" : "s"} for ${nextFonts.unknown.length === 1 ? "it" : "them"} ${nextFonts.unknown.length === 1 ? "is" : "are"}`));
+        console.log(line(`already in tokens.css, waiting.`));
+    }
     if (nextFonts) {
         /**
          * UM `fonts.ts` POR APP, e não só no primeiro - lacuna do próprio conserto de 22/08.
@@ -694,9 +766,17 @@ export async function add(slug, opts) {
                 continue;
             if (!(await exists(join(projectRoot, ...dir.split("/")))))
                 continue;
-            const snippet = nextFontSnippet(families, payload.slug, dir, payload.fontSeam);
-            if (!snippet)
+            const plan = nextFontSnippet({
+                families,
+                slug: payload.slug,
+                appDir: dir,
+                seam: payload.fontSeam,
+                facts: fontFacts,
+                declaredWeights: payload.document.foundations.typography.weights,
+            });
+            if (!plan.ok)
                 continue;
+            const snippet = plan;
             const header = [
                 `// Self-hosted type for the "${payload.slug}" design system (via next/font -`,
                 `// preloaded, no font flash). Generated by \`synthesisui add\`; edit freely.`,

package/dist/commands/component.js

@@ -2,8 +2,9 @@ import { existsSync } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { emitCn, readVocabulary } from "../cn-codegen.js";
-import { generateComponentFiles } from "../component-codegen.js";
+import { generateComponentFiles, } from "../component-codegen.js";
 import { readProjectConfig, resolveRegistry } from "../config.js";
+import { detectAppDirs } from "../global-sheet.js";
 import { hasInteractiveTemplate, interactiveTemplate, } from "../interactive-templates.js";
 import { body, section, snippet } from "../output.js";
 import { findCollision, installedThemeVars, reactMajorOf, readInstalledConvention, readInstalledScheme, } from "../project-facts.js";
@@ -12,6 +13,7 @@ import { installedThemeCss, whatOnlyTheSheetResolves, } from "../sheet-needed.js
 import { flavourResolver } from "../styles-flavour.js";
 import { inTheirTongue, projectTongue, sumSpoken, } from "../their-tongue.js";
 import { readCensus, unreadComment, unreadForComponent, } from "../unread-for-component.js";
+import { readWiring } from "../wiring-read.js";
 import { editedSinceWritten, readWritten, recordWritten } from "../written.js";
 /**
  * Writes the shared `cn.ts` next to the components, built from THIS project's
@@ -69,6 +71,18 @@ export function localName(blueprint, asked) {
  * The component's styles reference the DS tokens, so the system itself must be
  * installed (`synthesisui add <slug>`) for `tokens.css`/`theme.css` to resolve.
  */
+/**
+ * O QUE NESTE ARQUIVO PRECISA DA FOLHA, dito uma vez.
+ *
+ * A frase aparece nos três desfechos do bloco de setup (está aí · está no repo · falta), e três
+ * redações da mesma medição são três respostas no dia em que uma for editada.
+ */
+function whatNeedsIt(need) {
+    const some = (list) => `${list.slice(0, 3).join(", ")}${list.length > 3 ? `, +${list.length - 3}` : ""}`;
+    return need.variables.length > 0
+        ? some(need.variables)
+        : `the ${some(need.classes)} ${need.classes.length === 1 ? "utility" : "utilities"}`;
+}
 export async function component(slug, name, opts) {
     const base = resolveRegistry(opts.registry);
     const root = opts.dir ?? process.cwd();
@@ -118,6 +132,14 @@ export async function component(slug, name, opts) {
      * recipe, ou sobre o css antes da tradução, seria responder sobre um arquivo que ninguém abriu.
      */
     let writtenSource = "";
+    /**
+     * O VEREDITO DA RAIZ - ver `GeneratedRoot` em `component-codegen.ts`.
+     *
+     * `null` no caminho do template interativo, e isso é uma resposta: ali o `.tsx` é curado à mão e
+     * já nasce com o elemento operável certo, então não há nada a avisar. Um `false` inventado aqui
+     * faria o comando calar por engano no caminho que ele deveria cobrir.
+     */
+    let root_ = null;
     const artifactsAreTheProduct = opts.artifactsOnly === true || config.target !== "next";
     if (artifactsAreTheProduct) {
         const dir = join(root, "_synthesisui", "ds", slug, "components");
@@ -332,7 +354,7 @@ export async function component(slug, name, opts) {
             filenames = written.map((f) => f.filename);
         }
         else {
-            const { files, spoken: said } = generateComponentFiles(slug, res.name, res.recipe, res.css, res.version, flavour, await reactMajorOf(root), 
+            const { files, spoken: said, root: generatedRoot, } = generateComponentFiles(slug, res.name, res.recipe, res.css, res.version, flavour, await reactMajorOf(root), 
             /**
              * THE SPELLING, FROM THE VERSION WE JUST FETCHED.
              *
@@ -353,6 +375,7 @@ export async function component(slug, name, opts) {
              */
             local, await readInstalledScheme(root, slug), tongue, await installedThemeVars(root, slug));
             spoken = said;
+            root_ = generatedRoot;
             /**
              * AS DECLARAÇÕES DO ARQUIVO DELE QUE O INTERPRETADOR NÃO LEU - ver `unread-for-component.ts`.
              *
@@ -449,7 +472,50 @@ export async function component(slug, name, opts) {
      * junto a única linha que diz COMO importar o componente. Dizer "está isolado" e sonegar o
      * `import { ButtonSample }` troca um defeito por outro.
      */
-    if (need.needed) {
+    /**
+     * A FIAÇÃO JÁ ESTÁ AQUI? - ver `wiring-read.ts`, a MESMA leitura que o `doctor` usa.
+     *
+     * MEDIDO em 08/09, nos dois apps do ato 2B: com os dois `@import` colados e o
+     * `data-ds="<slug>"` no `<body>`, este comando ainda imprimia os passos 1 e 2 para colar de
+     * novo. Ele perguntava se o arquivo PRECISA da folha e nunca se a folha já estava lá.
+     *
+     * As duas perguntas continuam sendo feitas, e nesta ordem: `need` decide se o setup é
+     * necessário, `wiring` decide se ele ainda está pendente.
+     */
+    const wiring = need.needed ? await readWiring(root, slug) : null;
+    /**
+     * O ADAPTADOR CONTA quando o que precisa da folha são UTILITÁRIOS - eles só existem pelo
+     * `@theme` do `theme.css`. Dizer "está tudo aí" com o `tokens.css` sozinho declararia resolvido
+     * exatamente o que continua faltando.
+     */
+    const sheetsThere = wiring?.imported === true && (!tailwind || wiring?.themed === true);
+    /**
+     * E A RESPOSTA É DO PROJETO, NÃO DO APP - então num repositório com mais de um app ela não
+     * decide, e o comando diz isso em vez de afirmar (`INV-VOLTA-12`: monorepo é a forma comum).
+     *
+     * `readWiring` varre a partir da raiz e responde "existe, em algum lugar daqui". Com dois apps
+     * servidos, um fiado e o outro não, um responderia pelo outro - e o arquivo que este comando
+     * acabou de escrever vai para uma pasta só de componentes, que não desambigua qual app o usa.
+     */
+    const appDirs = await detectAppDirs(root, config.pagesDir ?? "app");
+    const oneApp = appDirs.length <= 1;
+    const alreadyWired = sheetsThere && wiring?.scoped === true;
+    if (need.needed && alreadyWired && !oneApp) {
+        console.log(section(`This file needs the sheet - and this repo has it`));
+        console.log(body(`What needs it: ${whatNeedsIt(need)}.`));
+        console.log(body(`Measured across this repository, not per app: ${slug}'s sheet is imported and`));
+        console.log(body(`data-ds="${slug}" is set somewhere in it. There ${appDirs.length === 2 ? "are two apps" : `are ${appDirs.length} apps`} here (${appDirs.slice(0, 2).join(", ")}${appDirs.length > 2 ? ", …" : ""}),`));
+        console.log(body(`so if this file lands in one that does not carry them, run \`doctor\` inside it.`));
+    }
+    if (need.needed && alreadyWired && oneApp) {
+        console.log(section(`This file needs the sheet - and it is already there`));
+        console.log(body(`What needs it: ${whatNeedsIt(need)}.`));
+        console.log(body(`This project already imports ${slug}'s ${tailwind ? "tokens.css and theme.css" : "tokens.css"} and carries data-ds="${slug}",`));
+        console.log(body(wiring?.fontsMapped
+            ? `and its type is mapped onto the system's family tokens. Nothing to set up.`
+            : `so nothing to set up here. \`doctor\` says whether the type is mapped too.`));
+    }
+    if (need.needed && !alreadyWired) {
         console.log(section(`One-time setup (once per app, for "${slug}")`));
         console.log(body(need.variables.length > 0
             ? `(what still needs the sheet here: ${need.variables.slice(0, 3).join(", ")}${need.variables.length > 3 ? `, +${need.variables.length - 3}` : ""} - your code names no value for ${need.variables.length === 1 ? "it" : "them"})`
@@ -466,6 +532,40 @@ export async function component(slug, name, opts) {
         console.log("");
         console.log(body(`(If you haven't installed the system yet, run: synthesisui add ${slug})`));
     }
+    /**
+     * O ELEMENTO QUE SAIU NÃO ATIVA O QUE A RECEITA PEDE - e isso se diz, em vez de sumir (lei 8).
+     *
+     * O QUE O CLIENTE VIA (medido em 08/09): `<Button>Ship it</Button>` renderizou um `<div>`. Sem
+     * foco, sem teclado, sem `role` - e as declarações de `:focus-visible` e `:disabled` da própria
+     * receita inertes, porque um `div` não recebe foco nem fica desabilitado.
+     *
+     * A RAIZ NÃO-OPERÁVEL ESTÁ CORRETA: a receita não declara papel de ação, e a lei 10 manda não
+     * inventar semântica que o contrato dele não tem - um `role="button"` + `tabIndex` supostos
+     * seriam acessibilidade que a gente adivinhou, o que é pior que não fazer. O que faltava era a
+     * segunda metade: DIZER.
+     *
+     * E A MEDIÇÃO VEM DE QUEM DECIDIU - ver `GeneratedRoot`. A primeira versão deste bloco lia o
+     * texto emitido com um regex (`const Tag = (as ?? "div|span")` + `focus-visible:` na fonte), e a
+     * revisão mediu as duas cegueiras: a grafia de variante do Tailwind não existe numa folha, então
+     * o aviso morria em `styles: css`; e `(div|span)` não alcançava o `article` que o guard da lei 10
+     * devolve quando o topo tem heading - o caso mais citado neste repositório.
+     */
+    const inertRoot = root_ != null && !root_.operable;
+    /**
+     * OS ESTADOS COM O NOME QUE O CSS DELE USA - o contrato os guarda em camelCase (`focusVisible`),
+     * e é `:focus-visible` que ele vai procurar no arquivo. A conversão é de LEITURA, para o texto
+     * falar a língua da folha e não a do nosso schema.
+     */
+    const interactiveStates = (root_?.interactiveStates ?? []).map((state) => state.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`));
+    if (interactiveStates.length > 0 && inertRoot) {
+        console.log(section("It renders a container, not a control"));
+        console.log(body(`This recipe declares no action role, so the root is a <${root_?.tag}> - we do not`));
+        console.log(body(`invent semantics your contract does not have. But it styles ${interactiveStates.join(", ")},`));
+        console.log(body(`and a <${root_?.tag}> reaches none of them: no focus, no keyboard, nothing announced.`));
+        console.log("");
+        console.log(body(`If it is interactive, the file takes the element as a prop - \`as="button"\`,`));
+        console.log(body(`\`as="a"\`, whatever it really is. Which one it is, is yours to say.`));
+    }
     console.log(section("Use it"));
     if (!opts.artifactsOnly && config.target === "next") {
         /**

package/dist/commands/doctor.js

@@ -16,7 +16,6 @@ import { diagnose, nameToWrite, scanSource, siblingTokens, } from "../doctor/sca
 import { findSelfConflicts, forbiddenProps, isReset, propMatchesLabel, } from "../doctor/self-conflict.js";
 import { withTheirNames } from "../doctor/their-names.js";
 import { buildTable, EMPTY_TABLE, nearestToken, } from "../doctor/tokens.js";
-import { FAMILY_SEAM_PREFIX } from "../fonts.js";
 import { detectAppDirs, globalSheetOf, prefixFrom } from "../global-sheet.js";
 import { groupRole } from "../group-role.js";
 import { actingSlug, describeScope, measuredScope, scopePaths, } from "../measured-scope.js";
@@ -26,6 +25,7 @@ import { installedThemeCss, whatOnlyTheSheetResolves, } from "../sheet-needed.js
 import { resolveDeps } from "../stack.js";
 import { projectTongue } from "../their-tongue.js";
 import { danglingTheirVars } from "../their-vars.js";
+import { readWiring } from "../wiring-read.js";
 /**
  * `synthesisui doctor` - the check nobody else ships.
  *
@@ -542,78 +542,6 @@ function verdict(d, hasSystem, overruled, conflicts) {
     }
     return lines;
 }
-/**
- * Wiring is a property of the PROJECT, never of the scope being read.
- *
- * This ran inside the scoped walk, so `doctor app/login` read only that folder
- * - and the import lives in `app/globals.css`. It concluded "installed, but not
- * wired up yet" about a project that was perfectly wired (my-test4, 27/07).
- *
- * Which would be a mild annoyance, except the managed block now tells the agent
- * to run `doctor <the file you just wrote>` after every edit. The false alarm
- * fires on every loop, and an agent that believes the system is unwired starts
- * repairing wiring that was already correct - editing the one file we most need
- * it to leave alone.
- *
- * The system itself was always resolved from the root. So is this now.
- */
-async function readWiring(root, slug) {
-    const w = {
-        imported: false,
-        scoped: false,
-        /** `init` wrote a fonts file for this project (Next targets only). */
-        fontsWritten: false,
-        /** …and the stylesheet actually maps it onto the system's type tokens. */
-        fontsMapped: false,
-        /**
-         * THE FEATURE NOBODY KNEW WE SHIPPED.
-         *
-         * Every system compiles a `shadcn.css` mapping shadcn's whole variable
-         * contract onto its own tokens, so shadcn components wear the system instead
-         * of shadcn's defaults. It has been generated into every project since it
-         * was built, and until 28/07 nothing mentioned it: not `add`, not the
-         * managed block, not the GUIDE except as a filename in a list. The only
-         * documentation was a comment inside the file, which is the same as none.
-         *
-         * The person it mattered most to is the one who asked "I don't get the use
-         * case, I can just build a design system with shadcn" - and the answer was
-         * sitting unimported in his own repo.
-         *
-         * Reported only when the project HAS shadcn. Telling everybody about a
-         * bridge they will never use is how a report earns the skim.
-         */
-        hasShadcn: false,
-        bridged: false,
-    };
-    if (!slug)
-        return w;
-    w.hasShadcn = await readFile(join(root, "components.json"), "utf8").then(() => true, () => false);
-    for await (const file of walk(root)) {
-        const src = await readFile(file, "utf8").catch(() => "");
-        if (!src)
-            continue;
-        if (src.includes(`_synthesisui/ds/${slug}/tokens.css`))
-            w.imported = true;
-        if (src.includes(`_synthesisui/ds/${slug}/shadcn.css`))
-            w.bridged = true;
-        if (src.includes(`data-ds="${slug}"`))
-            w.scoped = true;
-        // The requirement that stayed invisible. `init` writes a fonts file and
-        // asks for two more edits; an agent told to check only the first two did
-        // exactly that, stopped, and left the project rendering in the framework's
-        // default face (my-test2, 27/07). What the checker checks is what gets done.
-        if (src.includes("--font-ds-") && /next\/font/.test(src))
-            w.fontsWritten = true;
-        /** O prefixo vem da const única da costura - um literal aqui divergiria em silêncio (26/08). */
-        if (new RegExp(`${FAMILY_SEAM_PREFIX}\\w+\\s*:\\s*var\\(\\s*--font-ds-`).test(src))
-            w.fontsMapped = true;
-        // The bridge joins the early exit, otherwise the walk can stop before the
-        // stylesheet that imports it and report a wired project as unbridged.
-        if (w.imported && w.scoped && w.fontsMapped && (!w.hasShadcn || w.bridged))
-            break;
-    }
-    return w;
-}
 /** Onde o retrato mora por default: dentro do que a esteira já escreve, e commitável. */
 const DEFAULT_BASELINE = "_synthesisui/drift-baseline.json";
 /**

package/dist/commands/list.js

@@ -22,6 +22,8 @@ export async function list(opts) {
         }
         console.log("Your design systems:\n");
         const width = Math.max(...mine.map((s) => s.slug.length));
+        /** Algum sistema tem rascunho à frente do que o `add` entrega? Só então a legenda tem serventia. */
+        let anyDraftAhead = false;
         for (const s of mine) {
             /**
              * O GRUPO ENTRE PARÊNTESES, e "invited" quando ele não é dela - as duas
@@ -30,7 +32,27 @@ export async function list(opts) {
             const group = s.group
                 ? `${s.group}${s.mine ? "" : ", invited"}`
                 : "no group";
-            console.log(`  ${s.slug.padEnd(width)}  ${s.name}  (v${s.version}) · ${group}`);
+            /**
+             * O NÚMERO QUE ELE RECEBE VEM PRIMEIRO, e o rascunho aparece como rascunho.
+             *
+             * O DEFEITO (medido em 08/09, num projeto novo): esta linha imprimia `codelevel (v3)` e o
+             * `add` instalava `CodeLevel v2`. A listagem mostrava a linha mais nova, que é o rascunho do
+             * Studio; o `add` serve a última publicada. Duas verdades sobre coisas diferentes, e nenhuma
+             * palavra separando as duas - então o cliente lia um número e recebia outro.
+             *
+             * Sem `installable` (registry antigo) nada muda: um número só, como antes.
+             */
+            const installable = s.installable ?? s.version;
+            const draftAhead = s.version > installable;
+            if (draftAhead)
+                anyDraftAhead = true;
+            const versions = draftAhead
+                ? `v${installable} · v${s.version} draft`
+                : `v${installable}`;
+            console.log(`  ${s.slug.padEnd(width)}  ${s.name}  (${versions}) · ${group}`);
+        }
+        if (anyDraftAhead) {
+            console.log("\n`add` installs the published version; the draft is what the Studio is editing.");
         }
         console.log('\nWork in one with:  synthesisui use <slug> "<what you are building>"');
         return;

package/dist/component-codegen.js

@@ -1,6 +1,25 @@
 import { emittableAttrs } from "./attr-shape.js";
 import { inTheirTongue, sumSpoken, } from "./their-tongue.js";
 import { PHRASING_FORMS, } from "./types.js";
+/**
+ * OS ELEMENTOS QUE SÃO OPERÁVEIS POR NATUREZA - a lista vem do HTML, e é por isso que ela é uma
+ * regra e não uma foto: nenhum repositório de cliente a muda.
+ *
+ * A pergunta que ela responde é a do avesso: uma tag FORA desta lista não recebe foco de teclado
+ * nem fica desabilitada, então toda declaração de `:focus-visible` e `:disabled` que a receita
+ * carrega fica inerte nela.
+ */
+const OPERABLE_ELEMENTS = new Set([
+    "button",
+    "a",
+    "input",
+    "select",
+    "textarea",
+    "summary",
+    "details",
+    "label",
+    "option",
+]);
 export const DEFAULT_CONVENTION = {
     prefix: "ds-",
     partSeparator: "-",
@@ -49,6 +68,32 @@ const camel = (name) => {
 export function partIsInteractive(part) {
     return Object.keys(part.states ?? {}).some((s) => /^(focus|focusVisible|focus-visible|disabled)$/i.test(s));
 }
+/**
+ * OS ESTADOS OPERÁVEIS QUE A RECEITA DECLARA - nas DUAS formas em que uma receita os declara.
+ *
+ * O DEFEITO QUE ISTO CONSERTA, medido no `button` do `codelevel` em 08/09: a primeira versão lia
+ * `recipe.states`, que é a forma das receitas que a PLATAFORMA GERA. Numa receita LIDA do
+ * repositório do cliente o mesmo fato mora em `layers[].when.state` - `recipe.states` vem vazio -,
+ * então o aviso deixou de sair exatamente no caso que o originou.
+ *
+ * É a mesma lição que `rootAxes` já carrega: *"axesOf alone keeps an axis only when the option's
+ * own block carries declarations - true for a recipe we generated, and false for every recipe we
+ * READ"*. Um leitor que conhece uma forma só atende metade da população, e a metade que ele perde é
+ * justamente a do cliente.
+ */
+export function interactiveStatesOf(recipe) {
+    const OPERABLE_STATE = /^(focus|focusVisible|focus-visible|disabled)$/i;
+    const found = new Set();
+    for (const state of Object.keys(recipe.states ?? {}))
+        if (OPERABLE_STATE.test(state))
+            found.add(state);
+    for (const layer of recipe.layers ?? []) {
+        const state = layer.when?.state;
+        if (state && OPERABLE_STATE.test(state))
+            found.add(state);
+    }
+    return [...found];
+}
 /** Intrinsic element + extra attrs per component, chosen like the platform
  *  renderer does (name first, then preview.kind). Fallback: div + children. */
 function elementFor(name, recipe) {
@@ -941,6 +986,30 @@ function treeParts(nodes, out = []) {
     }
     return out;
 }
+/**
+ * A ÁRVORE JÁ TEM ONDE O CONTEÚDO DELE ENTRA?
+ *
+ * O QUE O CLIENTE VIA (medido em 08/09, num `create-next-app` com o `codelevel`): ele escreveu
+ * `<Button>Ship it</Button>` e a tela mostrou **"Ship it" duas vezes** - duas ocorrências dentro do
+ * `<main>` servido, não uma.
+ *
+ * A CAUSA: a árvore do recipe tem um nó `as: "slot"`, e `emitTree` emite `{children}` nele - é o
+ * lugar do conteúdo, dentro da parte que o desenha. A raiz emitia `{children}` OUTRA VEZ, logo
+ * depois da árvore. Não é um caso do `button`: vale para toda receita cuja árvore tenha slot.
+ *
+ * ENTÃO A PERGUNTA PASSA A SER FEITA. Com slot na árvore, o conteúdo já tem endereço e a raiz não
+ * o repete; sem slot, a raiz continua sendo o único lugar onde ele pode entrar - e sonegá-lo ali
+ * seria trocar um defeito por outro, um componente que ignora o que o cliente escreveu dentro.
+ */
+function treeHasSlot(nodes) {
+    for (const node of nodes ?? []) {
+        if (node.as === "slot")
+            return true;
+        if (node.children && treeHasSlot(node.children))
+            return true;
+    }
+    return false;
+}
 /**
  * THE COMPOSITION, EMITTED AS JSX RATHER THAN DESCRIBED IN A COMMENT.
  *
@@ -1114,8 +1183,13 @@ localName = name) {
         "...props",
     ].join(", ");
     const rootOpen = `    <${el.jsxTag}${el.jsxAttrs}\n      className={${joinCls([`"${elementClass(name, convention)}"`, "className"])}}\n${dataAttrLines(axes)}${axes.length ? "\n" : ""}      {...props}\n    `;
+    /**
+     * O CONTEÚDO DELE ENTRA UMA VEZ - ver `treeHasSlot`. Com slot na árvore, o `{children}` da raiz
+     * duplicava na tela o que o cliente escreveu.
+     */
+    const rootTakesChildren = hasShape && !treeHasSlot(tree);
     const rootJsx = hasShape
-        ? `${rootOpen}>\n${emitTree(tree, comp, "      ")}\n      {children}\n    </${el.jsxTag}>`
+        ? `${rootOpen}>\n${emitTree(tree, comp, "      ")}${rootTakesChildren ? "\n      {children}" : ""}\n    </${el.jsxTag}>`
         : `${rootOpen}/>`;
     // Tree order first, because that is the order somebody reads them in the file;
     // anything the tree does not mention still gets its component.
@@ -1296,8 +1370,7 @@ ${el.setup}  return (
 ${hasShape
         ? `${rootOpen}  {...props}
     >
-${emitTree(tree, comp, "      ")}
-      {children}
+${emitTree(tree, comp, "      ")}${treeHasSlot(tree) ? "" : "\n      {children}"}
     </${el.jsxTag}>`
         : `${rootOpen}  {...props}
     />`}
@@ -1461,7 +1534,20 @@ themeVars) {
         filename: "index.ts",
         code: `export * from "./${localName}";\n`,
     });
-    return speak(files, tongue, styles === "tailwind" ? "tailwind-class" : "stylesheet");
+    /**
+     * O VEREDITO DA RAIZ SAI DAQUI, de `elementFor` e do contrato - ver `GeneratedRoot`.
+     *
+     * `interactiveStates` lê `recipe.states`, que é o mesmo dado nas duas línguas; a alternativa que
+     * a revisão derrubou lia a grafia de variante do Tailwind na fonte emitida e ficava cega em
+     * `styles: css`.
+     */
+    const rootEl = elementFor(name, recipe);
+    const root = {
+        tag: rootEl.tag,
+        interactiveStates: interactiveStatesOf(recipe),
+        operable: OPERABLE_ELEMENTS.has(rootEl.tag),
+    };
+    return speak(files, tongue, styles === "tailwind" ? "tailwind-class" : "stylesheet", root);
 }
 /**
  * A TRADUÇÃO, SOBRE OS BYTES, UMA VEZ - e o destino é de quem GEROU o texto, não da extensão.
@@ -1475,14 +1561,14 @@ themeVars) {
  * `index.ts` é um re-export e não carrega estilo, mas passa pela mesma porta: um arquivo isento por
  * lista é a lista que alguém esquece de atualizar.
  */
-function speak(files, tongue, tsxDestination) {
+function speak(files, tongue, tsxDestination, root) {
     if (!tongue)
-        return { files, spoken: null };
+        return { files, spoken: null, root };
     const reports = [];
     const said = files.map((file) => {
         const spoken = inTheirTongue(file.code, tongue, file.filename.endsWith(".css") ? "stylesheet" : tsxDestination);
         reports.push(spoken);
         return { filename: file.filename, code: spoken.css };
     });
-    return { files: said, spoken: sumSpoken(reports) };
+    return { files: said, spoken: sumSpoken(reports), root };
 }

package/dist/font-facts.spec-input.js

@@ -0,0 +1,24 @@
+/**
+ * UM `FontFacts` COMPLETO A PARTIR DO QUE VOCÊ QUER DIZER - a porta que faltava fechar.
+ *
+ * O SUFIXO `.spec-input` DECLARA A INTENÇÃO NO PONTO DE IMPORTAÇÃO - ver `reachable.spec.ts`: este
+ * módulo existe só para alimentar spec, e é uma CATEGORIA, não uma órfã que alguém esqueceu de
+ * ligar. Ele nunca entra em código de produto.
+ *
+ * `buildGuide` e `nextFontSnippet` fecharam "esquecer o ARGUMENTO"; ficou aberto "esquecer um CAMPO
+ * dele", e isso custou 35 testes: quando `subsetsOf` nasceu, as fixtures escritas à mão em dez
+ * lugares não a tinham, o `guide.spec.ts` parou de CARREGAR, e a suíte seguiu verde com o arquivo
+ * inteiro fora da contagem. Só o `tsc` pegava, e o `tsc` dos specs não é o portão de cada rodada.
+ *
+ * Quem escreve um teste diz só o que importa para ele; os outros campos vêm completos por
+ * construção, e um campo novo neste tipo passa a chegar em toda fixture sozinho.
+ */
+export function factsOf(over = {}) {
+    const weights = over.weights ?? ["400", "500", "600"];
+    const subsets = over.subsets ?? ["latin"];
+    return {
+        weightsOf: () => weights,
+        nameOf: (family) => over.names?.[family] ?? family,
+        subsetsOf: () => subsets,
+    };
+}

package/dist/fonts.js

@@ -1,3 +1,4 @@
+import { subsetsToEmit, weightsToEmit, } from "./next-font-weights.js";
 // Fallbacks genéricos do CSS - não são webfonts.
 const GENERIC_FAMILIES = new Set([
     "sans-serif",
@@ -87,61 +88,156 @@ export function googleFontsHref(families) {
  * batiza em `fontSeamOf`. Payload novo dispensa a convenção: o dado vence.
  */
 export const FAMILY_SEAM_PREFIX = "--ds-typography-families-";
-export function nextFontSnippet(families, slug, appDir = "app", 
-/**
- * A COSTURA SERVIDA PELO PAYLOAD (papel → nome do token no tokens.css) - ver `fontSeam` em
- * `types.ts`. Presente, o bloco de mapa fala os nomes que o ARTEFATO declara, por construção;
- * ausente (payload antigo), a composição por convenção continua valendo.
- */
-seam) {
+export function nextFontSnippet(input) {
+    const { families, slug, appDir = "app", seam, facts, declaredWeights, } = input;
+    /**
+     * A ORDEM É DETERMINÍSTICA e os duplicados saem: isto vira uma linha de arquivo gerado, e um
+     * conjunto que muda de ordem entre rodadas produz diff onde nada mudou.
+     */
+    const wanted = declaredWeights
+        ? [...new Set(Object.values(declaredWeights).map(String))].sort()
+        : ["400", "500", "600"];
     /** Toda vaga que o documento tem, não só as nossas três - ver `customFontFamilies`. */
     const roles = familySlots(families).filter((role) => {
         const name = firstFamily(families[role] ?? "");
         return name && !GENERIC_FAMILIES.has(name.toLowerCase());
     });
+    const named = [
+        ...new Set(roles.map((role) => firstFamily(families[role] ?? ""))),
+    ];
     if (roles.length === 0)
-        return null;
-    const importName = (name) => firstFamily(name).replace(/ /g, "_");
-    const seen = new Map(); // family name -> const name
+        return { ok: false, why: "generic-only", families: [] };
+    /**
+     * SEM MANIFESTO, NADA É EMITIDO - e o motivo viaja para quem chama.
+     *
+     * A alternativa seria emitir os três degraus "porque quase sempre existem", que é exatamente a
+     * suposição que derrubou o build de um projeto real em 08/09. Um arquivo não escrito custa uma
+     * frase ao cliente; um arquivo escrito errado custa o build dele.
+     */
+    if (!facts)
+        return { ok: false, why: "manifest-unreadable", families: named };
+    /**
+     * O IDENTIFICADOR SAI DA GRAFIA DO MANIFESTO, nunca de uma regra nossa - ver `FontFacts.nameOf`.
+     *
+     * A versão anterior fazia `replace(/ /g, "_")` sobre o nome como o documento DELE o escreve, e um
+     * `font-family: instrument serif` produzia `import { instrument_serif }`, que não existe. Uma
+     * capitalização "por palavra" trocaria esse defeito por outro: `IBM Plex Mono` sairia
+     * `Ibm_Plex_Mono`.
+     *
+     * E NÃO HÁ FALLBACK, de propósito. Uma família sem grafia conhecida é uma família que o manifesto
+     * não conhece, e ela segue o mesmo caminho de sempre: sai em `unknown`, sem linha escrita. Manter
+     * a heurística como último recurso deixaria a porta aberta para reescrever exatamente o import
+     * que quebra o build dele - vigiar em vez de fechar.
+     */
+    const importName = (canonical) => canonical.replace(/ /g, "_");
+    /**
+     * A DEDUPLICAÇÃO É PELA GRAFIA CANÔNICA, e não pelo texto dele - a porta que a canonização
+     * ABRIU, achada pela revisão deste PR.
+     *
+     * Medido: um documento com `display: "Geist"` e `body: "geist, sans-serif"` - dois papéis
+     * chegando à mesma família com caixa diferente, que é o normal quando o CSS dele foi escrito por
+     * mãos e épocas distintas - produzia
+     *
+     *     import { Geist, Geist } from "next/font/google";
+     *     SyntaxError: Identifier 'Geist' has already been declared
+     *
+     * Enquanto o identificador era composto do texto dele, as duas grafias davam dois nomes
+     * diferentes (`geist` e `Geist`) - inválidos, mas distintos. Canonizar o nome sem canonizar a
+     * CHAVE trocou "dois imports errados" por "um arquivo que não parseia": o mesmo EXIT=1 da
+     * `INV-VOLTA-16`, pela porta que este próprio conserto criou.
+     *
+     * A chave é a grafia do manifesto - a mesma resposta para as duas escritas dele.
+     */
+    const seen = new Map(); // canonical family -> const name
     const importNames = [];
     const consts = [];
+    /** Família cujos pesos o manifesto não conhece: não se inventa peso para ela. */
+    const unknown = [];
     for (const role of roles) {
         const name = firstFamily(families[role] ?? "");
-        if (!seen.has(name)) {
-            seen.set(name, role);
-            importNames.push(importName(name));
-            consts.push(`export const ${seen.get(name)} = ${importName(name)}({`, `  subsets: ["latin"],`, 
-            // WEIGHTS ARE ALWAYS SPELLED OUT, because next/font only allows
-            // omitting them for VARIABLE fonts - and plenty of Google families
-            // ship as static cuts (IBM Plex Mono, for one). The generated file
-            // assumed variable and broke the consumer's first `next build`; an
-            // agent caught it in the field (test03, 29/07) and had to repair our
-            // output by hand. Explicit weights are valid for BOTH kinds, so
-            // emitting them always can never break - and these three are the
-            // steps every generated system actually uses (regular/medium/
-            // semibold), so no static cut is downloaded for nothing.
-            `  weight: ["400", "500", "600"],`, `  variable: "--font-ds-${seen.get(name)}",`, `});`);
+        const canonical = facts.nameOf(name);
+        if (!canonical || !seen.has(canonical)) {
+            const available = facts.weightsOf(name);
+            const emit = available ? weightsToEmit(available, wanted) : [];
+            if (emit.length === 0 || !canonical) {
+                if (!unknown.includes(name))
+                    unknown.push(name);
+                continue;
+            }
+            /**
+             * OS SUBSETS TAMBÉM SÃO LIDOS - ver `subsetsToEmit`. Era `["latin"]` fixo, e o `next` reprova
+             * subset inexistente na MESMA função em que reprova peso inexistente: 121 das 1911 famílias
+             * do manifesto não têm `latin`, então a terceira porta deste módulo levava ao mesmo EXIT=1.
+             *
+             * Lista vazia significa que a família não declara subset nenhum, e aí a chave não é escrita:
+             * o `next` desliga o preload sozinho, e escrever `["latin"]` seria afirmar o que ela não tem.
+             */
+            const subsets = subsetsToEmit(facts.subsetsOf(name) ?? []);
+            seen.set(canonical, role);
+            importNames.push(importName(canonical));
+            consts.push(`export const ${role} = ${importName(canonical)}({`, ...(subsets.length > 0
+                ? [`  subsets: [${subsets.map((x) => `"${x}"`).join(", ")}],`]
+                : []), 
+            /**
+             * OS PESOS SÃO OS QUE A FAMÍLIA TEM - ver `next-font-weights.ts`.
+             *
+             * Escrevê-los é obrigatório: `next/font` só aceita omissão para fonte VARIÁVEL, e muita
+             * família do Google é entregue em cortes estáticos (IBM Plex Mono, entre outras) - o
+             * arquivo gerado assumia variável e quebrava o primeiro `next build` do cliente (29/07).
+             *
+             * E escrevê-los FIXOS quebra o outro lado: `Instrument Serif` tem um único peso, e o
+             * `["400","500","600"]` de antes derrubou um `create-next-app` inteiro em 08/09. Os dois
+             * defeitos são o mesmo erro - afirmar sobre a fonte dele em vez de ler.
+             */
+            `  weight: [${emit.map((w) => `"${w}"`).join(", ")}],`, `  variable: "--font-ds-${role}",`, `});`);
         }
     }
+    /** Nenhuma família sobreviveu: o manifesto existe e não conhece nenhuma delas. */
+    if (importNames.length === 0)
+        return { ok: false, why: "family-unknown", families: unknown };
     const fontsFile = [
         `// ${appDir}/fonts.ts`,
         `import { ${importNames.join(", ")} } from "next/font/google";`,
         ...consts,
     ];
-    const roleVar = (role) => {
+    /**
+     * A CONST QUE ESTE PAPEL USA - uma resposta só, e é o que impede as três leituras de divergirem.
+     *
+     * O `layout`, o mapa de CSS e o `roleVar` recompunham a chave cada um do seu jeito a partir do
+     * texto dele; com a deduplicação passando a ser canônica, três recomposições são três chances de
+     * uma delas citar uma const que o arquivo não exporta.
+     */
+    const constOf = (role) => {
         const name = firstFamily(families[role] ?? "");
-        return `--font-ds-${seen.get(name)}`;
+        const canonical = facts.nameOf(name);
+        return canonical ? seen.get(canonical) : undefined;
     };
+    const roleVar = (role) => `--font-ds-${constOf(role)}`;
+    /**
+     * SÓ AS VAGAS QUE VIRARAM CÓDIGO - uma família descartada por peso desconhecido não pode aparecer
+     * no `layout` nem no mapa de CSS: o import citaria uma const que o `fonts.ts` não exporta, e o
+     * projeto dele deixaria de compilar por causa da linha que a gente mandou colar.
+     */
+    const emitted = roles.filter((role) => constOf(role) !== undefined);
     const layout = [
         `// ${appDir}/layout.tsx`,
-        `import { ${[...new Set(roles.map((r) => seen.get(firstFamily(families[r] ?? ""))))].join(", ")} } from "./fonts";`,
-        `<body data-ds="${slug}" className={\`${[...new Set(roles.map((r) => `\${${seen.get(firstFamily(families[r] ?? ""))}.variable}`))].join(" ")}\`}>`,
+        `import { ${[...new Set(emitted.map(constOf))].join(", ")} } from "./fonts";`,
+        `<body data-ds="${slug}" className={\`${[...new Set(emitted.map((r) => `\${${constOf(r)}.variable}`))].join(" ")}\`}>`,
     ];
     const css = [
         `/* ${appDir}/globals.css - AFTER the tokens.css import */`,
         `[data-ds="${slug}"] {`,
-        ...roles.map((role) => `  ${seam?.[role] ?? `${FAMILY_SEAM_PREFIX}${role}`}: var(${roleVar(role)});`),
+        ...emitted.map((role) => `  ${seam?.[role] ?? `${FAMILY_SEAM_PREFIX}${role}`}: var(${roleVar(role)});`),
         `}`,
     ];
-    return { fontsFile, layout, css };
+    /**
+     * E A FAMÍLIA QUE FICOU DE FORA VIAJA - lei 8, e este módulo já dizia isto sobre o caso vizinho:
+     * *"um token que aponta para uma fonte que ninguém carregou é pior que um token ausente - o
+     * ausente pelo menos aparece na conta"*.
+     *
+     * Com duas famílias e só uma no manifesto, a outra saía do `fonts.ts`, do `layout` e do mapa de
+     * CSS sem uma palavra: o token dela continua no `tokens.css`, e o texto sai no fallback do
+     * navegador sem ninguém saber por quê.
+     */
+    return { ok: true, fontsFile, layout, css, unknown };
 }

package/dist/guide.js

@@ -279,7 +279,21 @@ export function buildGuide(payload,
  * `false` mantém o guia inteiro, que é o comportamento de todo repositório sem o servidor
  * registrado.
  */
-toolsReachable = false) {
+toolsReachable = false, 
+/**
+ * OS PESOS QUE AS FAMÍLIAS TÊM NO PROJETO DELE - ver `next-font-weights.ts`.
+ *
+ * Vem de fora pela mesma razão que `toolsReachable`: quem sabe é quem leu o disco dele. `null`
+ * significa "não deu para ler", e o guia então OMITE o bloco do `next/font` em vez de imprimir
+ * pesos supostos - um trecho colado com peso que a família não tem faz o `next build` falhar.
+ *
+ * OBRIGATÓRIO, e a razão é o `fixReach`: um argumento opcional aqui é um argumento que um
+ * chamador novo esquece, e o esquecimento faz o bloco do `next/font` DESAPARECER do único
+ * GUIDE.md do produto - em silêncio, com tsc, vitest e build passando. `nextFontSnippet` fechou
+ * essa porta; deixá-la entreaberta um nível acima seria vigiá-la em vez de fechá-la
+ * (CLAUDE.md, Parte I, seção 6).
+ */
+fontFacts) {
     const { document: doc, slug, name, version } = payload;
     const { meta, foundations, motion, components } = doc;
     const semanticRoles = Object.keys(foundations.color.semantic);
@@ -316,7 +330,22 @@ toolsReachable = false) {
             .join("&")}&display=swap`
         : null;
     /** A costura vem do payload quando o servidor a fala - o dado vence a convenção (T18-par). */
-    const nextFonts = nextFontSnippet(foundations.typography.families, slug, undefined, payload.fontSeam);
+    /**
+     * OS PESOS VÊM DE FORA (ver `next-font-weights.ts`), porque quem sabe é quem leu o projeto dele.
+     *
+     * `null` aqui NÃO é um esquecimento: o guia é escrito no `add`, que já leu o manifesto. Sem ele,
+     * o bloco do `next/font` não entra - um trecho para colar com um peso que a família não tem
+     * derruba o `next build` de quem colar, e o `<link>` abaixo funciona em qualquer framework.
+     */
+    const fontPlan = nextFontSnippet({
+        families: foundations.typography.families,
+        slug,
+        seam: payload.fontSeam,
+        facts: fontFacts,
+        /** Os pesos que ELE declara - ver `declaredWeights`. O guia é o arquivo que o agente dele cola. */
+        declaredWeights: foundations.typography.weights,
+    });
+    const nextFonts = fontPlan.ok ? fontPlan : null;
     const fontsSection = fontsHref
         ? `
 ## Fonts

package/dist/install-marks.js

@@ -170,7 +170,7 @@
  * O que o cliente ganha ao rodar `upgrade`: o agente dele no Codex passa a poder PERGUNTAR ao
  * sistema, em vez de só receber as regras e adivinhar o resto.
  */
-export const MATERIALISER_SINCE = "0.16.390";
+export const MATERIALISER_SINCE = "0.16.403";
 /**
  * A ÚLTIMA VERSÃO EM QUE O QUE O HOOK RODA MUDOU.
  *

package/dist/next-font-weights.js

@@ -0,0 +1,140 @@
+/**
+ * OS PESOS QUE CADA FAMÍLIA REALMENTE TEM - lidos do projeto DELE, nunca de uma tabela nossa.
+ *
+ * O QUE O CLIENTE GANHA: o `npm run build` dele para de falhar por causa de um arquivo que a
+ * plataforma escreveu.
+ *
+ * O DEFEITO, medido em 08/09 num `create-next-app` recém-criado com o `codelevel` instalado pelo
+ * binário 0.16.401:
+ *
+ *     Unknown weight 500 for font Instrument Serif.
+ *     Available weights: 400
+ *     Import trace: ./app/fonts.ts -> ./app/layout.tsx
+ *
+ * `next build` terminou em **EXIT=1**. O app não compila, e o arquivo que o derruba foi escrito
+ * pelo `add`. É o mesmo desfecho de `wired-slugs.ts`: a esteira existe para devolver o código dele
+ * funcionando, e entregou um repositório que não constrói.
+ *
+ * A CAUSA ERA UMA SUPOSIÇÃO ESCRITA EM COMENTÁRIO. O gerador fixava `weight: ["400","500","600"]`
+ * para TODA família, e o comentário afirmava que emitir sempre *"can never break"*. A afirmação
+ * nasceu do conserto de 29/07 - antes disso o arquivo omitia os pesos e quebrava para as fontes
+ * estáticas - e ela cobre metade do problema: omitir quebra para a fonte estática, e afirmar
+ * quebra para a fonte que não tem aquele corte. `Instrument Serif` tem exatamente um peso.
+ *
+ * ONDE MORA A RESPOSTA, e por isso ela não é nossa: o próprio `next` que o projeto dele instalou
+ * carrega o manifesto que o `next/font` usa para VALIDAR. *MEDIÇÃO, e a população é a versão do
+ * `next` que o projeto instalou: **1942 famílias** no `create-next-app` de 08/09, **1911** no
+ * `next` 16.2.0 deste repositório.* Cada uma com os pesos, estilos e subsets que existem. Ler dali significa que o que a gente
+ * emite é exatamente o que o compilador dele aceita - e que uma família nova do Google chega junto
+ * com o `npm update` dele, sem release nosso.
+ *
+ * `null` QUANDO NÃO DÁ PARA SABER. Sem manifesto legível, este módulo não adivinha: quem chama
+ * decide, e a decisão do produto é não escrever o arquivo e dizer o motivo (lei 8). O `<link>` do
+ * Google Fonts continua sendo o caminho que funciona - medido em 08/09, ele responde HTTP 200
+ * mesmo quando a URL pede um peso que a família não tem, porque aquela API ignora o que não existe.
+ */
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+/**
+ * Os lugares onde o manifesto do `next/font` já morou. Mais de um de propósito: o caminho é interno
+ * ao Next, então uma versão que o mova não pode virar um build quebrado - vira `null`, e o produto
+ * diz que não conseguiu ler.
+ */
+const MANIFEST_PATHS = [
+    "dist/compiled/@next/font/dist/google/font-data.json",
+    "dist/compiled/@next/font/google/font-data.json",
+    "font/dist/google/font-data.json",
+];
+/**
+ * O manifesto do projeto DELE, resolvido pela mesma regra que o `import` dele usa.
+ *
+ * `createRequire` a partir da raiz do projeto respeita o hoisting do monorepo: o `next` de um app
+ * pode estar na raiz do workspace, e uma busca por caminho fixo em `node_modules/` acharia nada
+ * exatamente nos repositórios grandes, que são os que mais precisam disto.
+ */
+async function loadManifest(projectRoot) {
+    for (const pkg of ["next/package.json", "@next/font/package.json"]) {
+        let base;
+        try {
+            const require = createRequire(join(projectRoot, "package.json"));
+            base = dirname(require.resolve(pkg));
+        }
+        catch {
+            continue;
+        }
+        for (const rel of MANIFEST_PATHS) {
+            try {
+                const raw = await readFile(join(base, ...rel.split("/")), "utf8");
+                const parsed = JSON.parse(raw);
+                if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
+                    return parsed;
+            }
+            catch {
+                // próximo caminho - um manifesto ausente não é erro, é uma resposta
+            }
+        }
+    }
+    return null;
+}
+/**
+ * O leitor de pesos deste projeto, ou `null` quando o manifesto não está ao alcance.
+ *
+ * A busca do nome é case-insensitive porque o documento guarda o nome como ele aparece no CSS dele
+ * (`"instrument serif"` de um `font-family` em minúsculas é a mesma família), e o manifesto guarda
+ * a grafia do Google.
+ */
+export async function nextFontFacts(projectRoot) {
+    const manifest = await loadManifest(projectRoot);
+    if (!manifest)
+        return null;
+    const weights = new Map();
+    const names = new Map();
+    const subsets = new Map();
+    for (const [family, entry] of Object.entries(manifest)) {
+        const key = family.toLowerCase();
+        weights.set(key, (entry?.weights ?? []).filter((w) => /^\d+$/.test(w)));
+        names.set(key, family);
+        subsets.set(key, entry?.subsets ?? []);
+    }
+    const key = (family) => family.trim().toLowerCase();
+    return {
+        weightsOf: (family) => weights.get(key(family)) ?? null,
+        nameOf: (family) => names.get(key(family)) ?? null,
+        subsetsOf: (family) => subsets.get(key(family)) ?? null,
+    };
+}
+/**
+ * OS PESOS A EMITIR para uma família, dados os que o gerador quer e os que existem.
+ *
+ * `wanted` são os três degraus que todo sistema gerado usa de fato - regular, medium, semibold. A
+ * saída é a interseção, na ordem dos disponíveis, e nunca o conjunto vazio: uma família que não tem
+ * nenhum dos três (só 200/300, por exemplo) recebe o peso mais próximo de 400 que ela tem, porque
+ * emitir lista vazia é `weight: []`, que o `next/font` recusa tanto quanto o peso inexistente.
+ */
+export function weightsToEmit(available, wanted = ["400", "500", "600"]) {
+    const have = available.filter((w) => /^\d+$/.test(w));
+    if (have.length === 0)
+        return [];
+    const kept = have.filter((w) => wanted.includes(w));
+    if (kept.length > 0)
+        return kept;
+    const nearest = [...have].sort((a, b) => Math.abs(Number(a) - 400) - Math.abs(Number(b) - 400))[0];
+    return [nearest];
+}
+/**
+ * OS SUBSETS A PEDIR para uma família, dados os que ela tem.
+ *
+ * `latin` quando ela o tem - é o que o texto dele usa, e pedir mais baixaria arquivo para nada.
+ * Sem `latin` mas com outros, os que ela tem: as 11 famílias nessa situação têm exatamente um
+ * (`Chenla` e `Content` são `["khmer"]`), então pedir a lista dela é pedir o único que existe.
+ *
+ * `[]` quando ela não tem subset nenhum, e aí a chave NÃO é escrita: o `next` desliga o preload
+ * sozinho nesse caso, e escrever `["latin"]` seria afirmar sobre a fonte dele um subset que ela não
+ * declara - a afirmação que este módulo existe para não fazer.
+ */
+export function subsetsToEmit(available) {
+    if (available.includes("latin"))
+        return ["latin"];
+    return [...available];
+}

package/dist/wiring-read.js

@@ -0,0 +1,113 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { walk } from "./commands/doctor.js";
+import { FAMILY_SEAM_PREFIX } from "./fonts.js";
+/**
+ * A FIAÇÃO DESTE PROJETO, MEDIDA - e a mesma medição para todos os comandos que a citam.
+ *
+ * O QUE O CLIENTE VIA (medido em 08/09, nos dois apps do ato 2B): ele colou os dois `@import` no
+ * `globals.css`, pôs `data-ds="codelevel"` no `<body>`, mapeou as quatro famílias - e o
+ * `component` terminou imprimindo **One-time setup**, com os passos 1 e 2 para colar de novo. O
+ * comando media "este arquivo PRECISA da folha?" (`sheet-needed.ts`) e nunca "a folha JÁ está
+ * aqui?".
+ *
+ * As duas perguntas são diferentes e as duas importam: a primeira decide se o setup é necessário, e
+ * a segunda decide se ele ainda está PENDENTE. Cobrar o que já foi feito gasta a confiança de quem
+ * fez - ele fica sem saber se errou algo, e o texto que deveria orientar passa a ser ruído.
+ *
+ * POR QUE ESTE MÓDULO EXISTE, em vez de o `component` medir por conta: esta leitura já existia
+ * dentro do `doctor`, com o histórico inteiro dela. Uma segunda medição da mesma coisa é uma
+ * segunda medição livre de discordar da primeira - dois comandos dizendo coisas opostas sobre o
+ * mesmo repositório é exatamente o defeito que este PR conserta.
+ */
+/**
+ * Wiring is a property of the PROJECT, never of the scope being read.
+ *
+ * This ran inside the scoped walk, so `doctor app/login` read only that folder
+ * - and the import lives in `app/globals.css`. It concluded "installed, but not
+ * wired up yet" about a project that was perfectly wired (my-test4, 27/07).
+ *
+ * Which would be a mild annoyance, except the managed block now tells the agent
+ * to run `doctor <the file you just wrote>` after every edit. The false alarm
+ * fires on every loop, and an agent that believes the system is unwired starts
+ * repairing wiring that was already correct - editing the one file we most need
+ * it to leave alone.
+ *
+ * The system itself was always resolved from the root. So is this now.
+ */
+export async function readWiring(root, slug) {
+    const w = {
+        imported: false,
+        /**
+         * O ADAPTADOR DO TAILWIND, e ele é uma pergunta SEPARADA de `imported`.
+         *
+         * O DEFEITO QUE ISTO CONSERTA, apontado na revisão deste PR: `imported` olha só o
+         * `tokens.css`, e o bloco que consulta esta leitura fala dos UTILITÁRIOS - que só o `@theme`
+         * do `theme.css` gera. Num projeto com um import e não o outro, o comando nomeava a falta
+         * (`what needs it: the bg-canvas utility`) e na linha seguinte declarava que não faltava nada.
+         *
+         * Um falso silêncio é pior que o falso alarme que este PR veio consertar: o cliente cola o
+         * componente, vê um bloco sem tipografia e sem sombra, e o comando acabou de dizer que estava
+         * tudo certo.
+         */
+        themed: false,
+        scoped: false,
+        /** `init` wrote a fonts file for this project (Next targets only). */
+        fontsWritten: false,
+        /** …and the stylesheet actually maps it onto the system's type tokens. */
+        fontsMapped: false,
+        /**
+         * THE FEATURE NOBODY KNEW WE SHIPPED.
+         *
+         * Every system compiles a `shadcn.css` mapping shadcn's whole variable
+         * contract onto its own tokens, so shadcn components wear the system instead
+         * of shadcn's defaults. It has been generated into every project since it
+         * was built, and until 28/07 nothing mentioned it: not `add`, not the
+         * managed block, not the GUIDE except as a filename in a list. The only
+         * documentation was a comment inside the file, which is the same as none.
+         *
+         * The person it mattered most to is the one who asked "I don't get the use
+         * case, I can just build a design system with shadcn" - and the answer was
+         * sitting unimported in his own repo.
+         *
+         * Reported only when the project HAS shadcn. Telling everybody about a
+         * bridge they will never use is how a report earns the skim.
+         */
+        hasShadcn: false,
+        bridged: false,
+    };
+    if (!slug)
+        return w;
+    w.hasShadcn = await readFile(join(root, "components.json"), "utf8").then(() => true, () => false);
+    for await (const file of walk(root)) {
+        const src = await readFile(file, "utf8").catch(() => "");
+        if (!src)
+            continue;
+        if (src.includes(`_synthesisui/ds/${slug}/tokens.css`))
+            w.imported = true;
+        if (src.includes(`_synthesisui/ds/${slug}/theme.css`))
+            w.themed = true;
+        if (src.includes(`_synthesisui/ds/${slug}/shadcn.css`))
+            w.bridged = true;
+        if (src.includes(`data-ds="${slug}"`))
+            w.scoped = true;
+        // The requirement that stayed invisible. `init` writes a fonts file and
+        // asks for two more edits; an agent told to check only the first two did
+        // exactly that, stopped, and left the project rendering in the framework's
+        // default face (my-test2, 27/07). What the checker checks is what gets done.
+        if (src.includes("--font-ds-") && /next\/font/.test(src))
+            w.fontsWritten = true;
+        /** O prefixo vem da const única da costura - um literal aqui divergiria em silêncio (26/08). */
+        if (new RegExp(`${FAMILY_SEAM_PREFIX}\\w+\\s*:\\s*var\\(\\s*--font-ds-`).test(src))
+            w.fontsMapped = true;
+        // The bridge joins the early exit, otherwise the walk can stop before the
+        // stylesheet that imports it and report a wired project as unbridged.
+        if (w.imported &&
+            w.themed &&
+            w.scoped &&
+            w.fontsMapped &&
+            (!w.hasShadcn || w.bridged))
+            break;
+    }
+    return w;
+}

package/package.json

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