synthesisui 0.16.497 → 0.16.499

package/dist/commands/add.js

@@ -21,7 +21,7 @@ import { describeFiltered, ruleApplies, rulesForProject, } from "../rule-filter.
 import { detectStack, resolveDeps } from "../stack.js";
 import { onlyWhatMatched } from "../their-theme.js";
 import { tongueOf } from "../their-tongue.js";
-import { pointTokensAtTheirNames } from "../their-vars.js";
+import { namesTheyDeclare, pointTokensAtTheirNames } from "../their-vars.js";
 import { tracksAnyOf } from "../tracked.js";
 /**
  * QUAL METADE DESTA PASTA UM TIME COMMITA.
@@ -252,6 +252,22 @@ export async function add(slug, opts) {
     const theirVars = await pointTokensAtTheirNames(projectRoot, payload, 
     /** O que um build anterior provou - ver `provenBefore`. Sem build aqui, é a melhor prova que há. */
     (prev?.tokenMap ?? []).map((p) => p.theirs));
+    /**
+     * O PAR QUE O `init` DECLAROU CONTINUA (jornada "o pedido livre sai mastigado", 15/10).
+     *
+     * Num projeto novo o `init` escreve os nomes do sistema no `@theme` dele e grava cada par no `.lock`. O `connect`, logo
+     * em seguida, passa por aqui - e o cruzamento acima só reconhece o nome de mesmo formato (`--ds-color-sand-50` com
+     * `--color-sand-50`), não o papel (`--ds-color-semantic-primary` com `--color-primary`). O mapa caía de 91 para 27 pares,
+     * e o template voltava a 40 valores crus no hero. O par anterior fica enquanto o CSS dele ainda declara aquele nome: o
+     * nome sumiu, o par some junto.
+     */
+    const reproved = new Set(theirVars.pairs.map((p) => p.ours));
+    const before = (prev?.tokenMap ?? []).filter((p) => !reproved.has(p.ours));
+    const stillDeclared = await namesTheyDeclare(projectRoot, before.map((p) => p.theirs));
+    const tokenMap = [
+        ...theirVars.pairs,
+        ...before.filter((p) => stillDeclared.has(p.theirs)),
+    ];
     /**
      * O `theme.css` ALINHA ONDE HÁ O QUE ALINHAR - ver `onlyWhatMatched`.
      *
@@ -416,7 +432,7 @@ export async function add(slug, opts) {
          */
         ...(theirVars.pointed > 0 ? { theirVars: theirVars.pointed } : {}),
         /** Ver `RootLock.tokenMap`: o fato, ao lado do número que ele produz. */
-        ...(theirVars.pairs.length > 0 ? { tokenMap: theirVars.pairs } : {}),
+        ...(tokenMap.length > 0 ? { tokenMap } : {}),
         ...(scope ? { scope } : {}),
         ...(systems.length > 0 ? { scopes: systems } : {}),
         ...(usage.length > 0 ? { usage } : {}),

package/dist/commands/doctor.js

@@ -2,7 +2,8 @@ import { describeDistinct, describeDistinctVerbose, distinctValues } from "../do
 import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { readStyleSheet, scssVariables } from "../doctor/scss-lens.js";
 import { THEME_SOURCE, tsTokenObjects, tsTokensAsVars } from "../doctor/ts-tokens-lens.js";
-import { dirname, join, relative, resolve } from "node:path";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { SET_PROPERTY } from "../doctor/broken-refs.js";
 import { describeIntent, intentOf, readProjectConfig } from "../config.js";
 import { describeFix, planFix, readerFor, writeFix, } from "../doctor/apply-fix.js";
 import { baselineOf, compareToBaseline, describeVerdict, githubAnnotations, sarifOf, } from "../doctor/ci-format.js";
@@ -777,6 +778,28 @@ export async function doctor(opts) {
     for await (const file of walkAll([root]))
         if (THEME_SOURCE.test(file) && !/\.d\.ts$/.test(file))
             tsObjects.push(...tsTokenObjects(await readFile(file, "utf8").catch(() => "")));
+    /**
+     * O QUE O JAVASCRIPT DELE MEDE, por pasta - ver `TokenTable.measuredInJs` (aula 01, 15/10). A reserva de
+     * `var(--sui-hero-name, clamp(...))` sai da conta só quando a pasta do CSS é a que grava a variável.
+     */
+    const measuredInJs = new Map();
+    for await (const file of walkAll([root])) {
+        if (!/\.(tsx|jsx|ts|js|mjs)$/.test(file) || /\.d\.ts$/.test(file))
+            continue;
+        const text = await readFile(file, "utf8").catch(() => "");
+        if (!text.includes("setProperty"))
+            continue;
+        const rel = relative(root, file);
+        const dir = rel.includes(sep) ? rel.slice(0, rel.lastIndexOf(sep)).split(sep).join("/") : "";
+        for (const m of text.matchAll(SET_PROPERTY)) {
+            const name = m[1].toLowerCase();
+            const dirs = measuredInJs.get(name) ?? [];
+            if (!dirs.includes(dir))
+                measuredInJs.set(name, [...dirs, dir]);
+        }
+    }
+    if (measuredInJs.size > 0)
+        table = { ...table, measuredInJs };
     const tally = emptyTally();
     const internalSpecs = await internalSpecifiers(root);
     for await (const file of scopes.length > 0

package/dist/commands/init.js

@@ -1,13 +1,12 @@
-import { DEFAULT_CONFIG, writeProjectConfig } from "../config.js";
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { DEFAULT_CONFIG, resolveRegistry, writeProjectConfig, } from "../config.js";
+import { readProjectTheme, writeBesideTheirs, writeNewProjectRoot, writeNewProjectTheme, } from "../new-project-theme.js";
 import { body, section, snippet } from "../output.js";
+import { fetchDesignSystem } from "../registry.js";
 import { resolveDeps, stylesFor, tailwindMajor } from "../stack.js";
 import { formMix, measuredStyle } from "../styles-flavour.js";
-import { readFile } from "node:fs/promises";
-import { join } from "node:path";
-import { readProjectTheme, writeBesideTheirs, writeNewProjectRoot, writeNewProjectTheme } from "../new-project-theme.js";
 import { add } from "./add.js";
-import { resolveRegistry } from "../config.js";
-import { fetchDesignSystem } from "../registry.js";
 const whereOf = (answer) => answer === "file" || answer === "1"
     ? "file"
     : answer === "separate" || answer === "2"
@@ -195,9 +194,13 @@ export async function init(opts) {
             const tokens = version !== null
                 ? await readFile(join(slugDir, `v${version}`, "tokens.css"), "utf8").catch(() => "")
                 : "";
-            const plan = tokens ? await readProjectTheme(root, tokens, opts.ds) : null;
+            const plan = tokens
+                ? await readProjectTheme(root, tokens, opts.ds)
+                : null;
             if (plan?.kind === "new" && version !== null) {
                 const theme = await writeNewProjectTheme(root, tokens, opts.ds, version);
+                if (theme.written)
+                    await recordDeclaredNames(slugDir, theme.pairs ?? []);
                 if (theme.written) {
                     console.log("");
                     console.log(`✓ ${theme.written}: ${theme.count} names of ${opts.ds} declared in your own @theme, with the values written - your project had none of its own. They are yours: bg-accent, p-md and rounded-lg now paint the system. Fonts come from the GUIDE's next/font recipe; the alternate scheme is not wired.`);
@@ -235,8 +238,14 @@ export async function init(opts) {
             const slugDir = join(root, "_synthesisui", "ds", opts.ds);
             const lock = JSON.parse(await readFile(join(slugDir, ".lock"), "utf8").catch(() => "{}"));
             const version = typeof lock.version === "number" ? lock.version : null;
-            const tokens = version !== null ? await readFile(join(slugDir, `v${version}`, "tokens.css"), "utf8").catch(() => "") : "";
-            const theme = tokens && version !== null ? await writeNewProjectRoot(root, tokens, opts.ds, version) : null;
+            const tokens = version !== null
+                ? await readFile(join(slugDir, `v${version}`, "tokens.css"), "utf8").catch(() => "")
+                : "";
+            const theme = tokens && version !== null
+                ? await writeNewProjectRoot(root, tokens, opts.ds, version)
+                : null;
+            if (theme?.written)
+                await recordDeclaredNames(slugDir, theme.pairs ?? []);
             if (theme?.written) {
                 console.log("");
                 console.log(`✓ ${theme.written}: ${theme.count} names of ${opts.ds} declared in your own :root, with the values written - your project had none of its own. They are yours: var(--color-primary) and var(--spacing-md) now paint the system.`);
@@ -267,3 +276,24 @@ export async function init(opts) {
     console.log("  • synthesisui add <slug>              bring a design system in");
     console.log("  • synthesisui template <slug> <name>  materialize a full page");
 }
+/**
+ * O QUE O `init` ACABOU DE DECLARAR VAI PARA O `.lock` (jornada "o pedido livre sai mastigado", 15/10).
+ *
+ * O `add` roda ANTES de o tema ser escrito, quando o projeto novo ainda não nomeia nada, e grava o `tokenMap` vazio. O
+ * `template` e o `component` traduzem pela mesma `tongue` que lê esse mapa - então a primeira landing de um projeto novo
+ * vinha com ~260 valores à mão (medido na rodada com agente de 15/10: "0 references now speak the name YOUR code gives
+ * the value, and 44 carry the value"), e o agente gastava rodadas convertendo-os de volta. Os pares aqui não são palpite:
+ * são os nomes que o próprio `init` escreveu, um a um, com o valor de cada um. O que o mapa já tinha continua.
+ */
+async function recordDeclaredNames(slugDir, pairs) {
+    if (pairs.length === 0)
+        return;
+    const path = join(slugDir, ".lock");
+    const lock = JSON.parse(await readFile(path, "utf8").catch(() => "{}"));
+    const known = new Set((lock.tokenMap ?? []).map((p) => p.ours));
+    const tokenMap = [
+        ...(lock.tokenMap ?? []),
+        ...pairs.filter((p) => !known.has(p.ours)),
+    ];
+    await writeFile(path, `${JSON.stringify({ ...lock, tokenMap }, null, 2)}\n`, "utf8");
+}

package/dist/doctor/broken-refs.js

@@ -40,7 +40,7 @@ const VAR_REF = /var\(\s*(--[a-zA-Z0-9_-]+)\s*(,)?/g;
  * Medido em quatro populações: 2 nomes no `codelevel-ui`, 0 no `packages/ui` do `frontend-hub`, 2 no
  * dashboard dele e 3 no nosso próprio app. Três de quatro escrevem variável por JS.
  */
-const SET_PROPERTY = /setProperty\(\s*['"`](--[a-zA-Z0-9_-]+)/g;
+export const SET_PROPERTY = /setProperty\(\s*['"`](--[a-zA-Z0-9_-]+)/g;
 /**
  * VARIABLES A HEADLESS LIBRARY SETS AT RUNTIME, which no stylesheet can declare.
  *

package/dist/doctor/scan.js

@@ -174,6 +174,15 @@ const SPACING_DECL = new RegExp(`(?:padding|margin|gap)(?:[A-Z][a-z]+|(?:-[a-z]+
 const SPACING_UTIL = /(?:\b[pmg](?:[trblxy])?-\[|gap-\[)([^\]]*)/g;
 /** A font stack written by hand rather than taken from the type scale. */
 const FONT = /font-family\s*:\s*([^;}\n]+)/g;
+/**
+ * O TAMANHO DE TEXTO ESCRITO À MÃO (defeito 3 da aula 01, 15/10) - `font-size: 14px`, `fontSize: "1rem"`,
+ * `[font-size:0.875rem]`. Não havia leitor nenhum: `distinct-values` contava esses valores como "by hand" e a cobertura,
+ * na mesma tela, não, então o `--fix` não tinha o que trocar com `--text-sm` declarado no projeto. A família é `font`,
+ * porque é a palavra que os nomes de escala de tipo carregam (`--text-sm`, `--ds-typography-...`).
+ */
+const FONT_SIZE_DECL = new RegExp(`font-?[Ss]ize${DECL_VALUE}`, "g");
+/** `text-[14px]` - o valor entre colchetes; `text-[#111]` não tem comprimento e não rende nada. */
+const FONT_SIZE_UTIL = /\btext-\[([^\]]*)/g;
 /**
  * MOTION, the family the scan never read (item 12, F3).
  *
@@ -351,6 +360,38 @@ function fallbackSpans(line, table) {
     }
     return out;
 }
+/** `var(--x, clamp(4rem, 17vw, 16rem))` - o nome e a reserva INTEIRA, com os parênteses de dentro contados. */
+function fallbacksOf(line) {
+    const out = [];
+    for (const m of line.matchAll(VAR_WITH_FALLBACK)) {
+        const start = (m.index ?? 0) + m[0].length;
+        let depth = 1;
+        let end = start;
+        for (; end < line.length && depth > 0; end++) {
+            if (line[end] === "(")
+                depth++;
+            else if (line[end] === ")")
+                depth--;
+        }
+        if (depth === 0)
+            out.push({ name: m[1].toLowerCase(), span: [start, end - 1] });
+    }
+    return out;
+}
+/**
+ * A RESERVA DE UM TAMANHO QUE O COMPONENTE MEDE SOZINHO - ver `TokenTable.measuredInJs` (aula 01, 15/10).
+ *
+ * Só quando um arquivo da MESMA pasta grava a variável: um `var(--qualquer, 18px)` que nada grava continua acusado, senão
+ * a reserva vira esconderijo de valor à mão.
+ */
+function measuredSpans(file, line, table) {
+    if (!table.measuredInJs?.size)
+        return [];
+    const dir = file.includes("/") ? file.slice(0, file.lastIndexOf("/")) : "";
+    return fallbacksOf(line)
+        .filter((f) => table.measuredInJs?.get(f.name)?.includes(dir))
+        .map((f) => f.span);
+}
 /**
  * ONDE A CASCATA DO APP NÃO ALCANÇA - e trocar por `var()` ali APAGA a cor.
  *
@@ -754,6 +795,8 @@ function scanCore(file, source, table) {
         const declared = declarationSpans(line, inTokenBlock && !opensTokenBlock);
         const inDeclaration = (at) => declared.some(([a, b]) => at >= a && at < b);
         const spans = fallbackSpans(line, table);
+        const measured = measuredSpans(file, line, table);
+        const inMeasured = (at) => measured.some(([a, b]) => at >= a && at <= b);
         const inFallback = (at) => spans.some(([a, b]) => at >= a && at <= b);
         /** Ver `markupTextSpans`: HTML montado como texto sai do alcance da folha do app. */
         const markup = markupTextSpans(file, line);
@@ -770,6 +813,10 @@ function scanCore(file, source, table) {
             /** A definição do token não é drift - ver `declarationSpans`. */
             if (col >= 0 && inDeclaration(col))
                 return;
+            if (col >= 0 && inMeasured(col)) {
+                setAside("the fallback of a size the component measures itself");
+                return;
+            }
             if (col >= 0 && inFallback(col)) {
                 setAside("a token's own fallback");
                 return;
@@ -800,14 +847,20 @@ function scanCore(file, source, table) {
             seen.add(key);
             // The kind is already known here, and without passing it the lookup
             // answers a `gap` with a radius token.
-            const match = tokenMatch(table, literal, kind);
+            /**
+             * O `_` DA CLASSE ARBITRÁRIA É O ESPAÇO DO TAILWIND (aula 01, 15/10). O achado guarda o valor como ESTÁ ESCRITO -
+             * `Anton,_sans-serif` -, porque é nessa grafia que o `--fix` acha a coluna para trocar; só a busca do nome lê o `_`
+             * como espaço, que é como o token declara a pilha.
+             */
+            const lookup = kind === "font" ? literal.replace(/_/g, " ") : literal;
+            const match = tokenMatch(table, lookup, kind);
             /**
              * O NOME DELE VEM DA MESMA CHAVE QUE A NOSSA FAMÍLIA VALIDOU - ver `theirNames`.
              *
              * A chave carrega o `kind` porque o valor sozinho não decide: `4px` é `--radius-xs` e
              * `--spacing` no vocabulário dele, e qual dos dois está certo depende de onde o literal está.
              */
-            const aliased = table.aliases.get(`${kind}:${normalizeValue(literal, table.rootPx)}`);
+            const aliased = table.aliases.get(`${kind}:${normalizeValue(lookup, table.rootPx)}`);
             /** O valor igual não basta - o papel também, ver `roleFits` (r13 e r14, 28/09). */
             const theirs = aliased && roleFits(propertyAt(line, col), aliased.name) ? aliased : undefined;
             /** A procedência do `token`, lida da tabela que o achou - ver `tokenIsTheirs`. */
@@ -896,8 +949,19 @@ function scanCore(file, source, table) {
             pushLengths("spacing", m);
         for (const m of line.matchAll(SPACING_DECL))
             pushLengths("spacing", m);
+        for (const m of line.matchAll(FONT_SIZE_UTIL))
+            pushLengths("font", m);
+        for (const m of line.matchAll(FONT_SIZE_DECL))
+            pushLengths("font", m);
         for (const m of line.matchAll(FONT)) {
-            const stack = m[1].trim();
+            /**
+             * A CLASSE ARBITRÁRIA DO TAILWIND TERMINA NO `]` (pedido da aula 01, 15/10). Em `[font-family:Inter,_sans-serif]
+             * font-medium ...` a regra de CSS - que só para em `;`, `}` ou fim de linha - engolia o resto da string de classes, e
+             * o `--verbose` mostrava `Inter,_sans-serif] font-medium [white-space:nowrap] ...` como uma família. Dentro do
+             * colchete o valor vai até o `]`; o `_` fica como está escrito, e quem o lê como espaço é a busca do nome, em `push`.
+             */
+            const inBrackets = line[(m.index ?? 0) - 1] === "[";
+            const stack = (inBrackets ? (m[1].split("]")[0] ?? "") : m[1]).trim();
             // A stack already reading from the system is the point, not a problem.
             if (stack.startsWith("var("))
                 continue;

package/dist/install-marks.js

@@ -333,7 +333,18 @@
  * servidor diz que uma landing pedida em palavras livres passa primeiro pelo `landing`. Uma pasta escrita antes deixa o
  * agente decidir a página inteira sozinho.
  */
-export const MATERIALISER_SINCE = "0.16.497";
+/**
+ * 0.16.497 -> 0.16.498 em 15/10, e o passo 1 dá **SIM** (o pedido livre sai mastigado, a otimização): o `init` de um projeto
+ * novo grava no `.lock` os nomes que acabou de declarar, e o `template` e o `component` passam a escrevê-los - 51 nomes e 3
+ * valores crus no hero, contra 0 e 54 antes. Uma pasta escrita antes traz a landing com os valores à mão.
+ */
+/**
+ * 0.16.498 -> 0.16.499 em 15/10, e o passo 1 dá **SIM** (o defeito 1 da aula 01): o tamanho de texto pedido pelo PAPEL
+ * (`--ds-typography-role-sm-font-size`) passa a sair com o nome do degrau que vale o mesmo, quando o projeto o declara -
+ * `[font-size:var(--text-sm)]` em vez de `[font-size:0.875rem]`. Um componente escrito antes traz os tamanhos à mão. No
+ * mesmo PR, o `init` declara a largura da página (`--container-page`) e a seção a escreve pelo nome, não como `1440px`.
+ */
+export const MATERIALISER_SINCE = "0.16.499";
 /**
  * A ÚLTIMA VERSÃO EM QUE O QUE O HOOK RODA MUDOU.
  *
@@ -546,7 +557,12 @@ export const COUNTED_DIFFERENTLY = "this run counts a value as named only when Y
  * à que tem o nome dele. Medido no `codelevel`: 33 checagens do componente mais checado chegavam sem componente. Um
  * hook anterior continua mandando essas checagens sem dono, e elas não contam para o degrau.
  */
-export const CHECKER_SINCE = "0.16.487";
+/**
+ * 0.16.487 -> 0.16.499 em 15/10, e o passo 1 dá **SIM** (os defeitos 2 e 3 da aula 01): a checagem passa a acusar o tamanho
+ * de texto escrito à mão (`font-size`, `[font-size:X]`, `text-[X]`), e a família de fonte no colchete do Tailwind deixa de
+ * engolir o resto da linha. Um hook anterior diz "limpo" sobre um `[font-size:0.875rem]` com `--text-sm` declarado.
+ */
+export const CHECKER_SINCE = "0.16.499";
 /**
  * A ÚLTIMA VERSÃO EM QUE OS LEITORES PASSARAM A PRODUZIR UM CENSO DIFERENTE.
  *
@@ -1022,7 +1038,11 @@ export const CHECKER_SINCE = "0.16.487";
  * mostra quando duas folhas brigam, deixa de fora a folha que ninguém carrega, conta o pages router como rota e diz os
  * componentes em Vue, Svelte, Astro e Angular. Um censo lido antes guardou "names no token yet" onde havia tokens.
  */
-export const READER_SINCE = "0.16.485";
+/**
+ * 0.16.485 -> 0.16.499 em 15/10, e o passo 1 dá **SIM** (o defeito 3 da aula 01): a varredura lê o tamanho de texto escrito
+ * à mão, e o censo passa a gravá-lo. Um censo lido antes não tem os tamanhos na fila de trabalho dele.
+ */
+export const READER_SINCE = "0.16.499";
 /**
  * O QUE ESTÁ INSTALADO AQUI FICOU PARA TRÁS - e as DUAS condições que fazem isso ser verdade.
  *

package/dist/new-project-theme.js

@@ -12,7 +12,15 @@ const BOILERPLATE = new Set([
     "--font-geist-sans",
     "--font-geist-mono",
 ]);
-const SKIP = new Set(["node_modules", ".next", "dist", "build", "out", "_synthesisui", "coverage"]);
+const SKIP = new Set([
+    "node_modules",
+    ".next",
+    "dist",
+    "build",
+    "out",
+    "_synthesisui",
+    "coverage",
+]);
 const TAILWIND_IMPORT = /@import\s+[\x22\x27]tailwindcss[\x22\x27]/;
 /**
  * O COMENTÁRIO DO CSS SE ESCREVE COM `\u002a` NO FONTE, e não com o asterisco - a guarda de
@@ -78,7 +86,9 @@ export async function writeNewProjectTheme(root, tokensCss, slug, version) {
         const withoutOurs = css.replace(END_RE(slug), "\n");
         for (const m of withoutOurs.matchAll(/(?:^|[{;\s])(--[a-zA-Z0-9_-]+)\s*:/g)) {
             const name = m[1];
-            if (!name.startsWith("--ds-") && !name.startsWith("--tw-") && !BOILERPLATE.has(name))
+            if (!name.startsWith("--ds-") &&
+                !name.startsWith("--tw-") &&
+                !BOILERPLATE.has(name))
                 own.add(name);
         }
     }
@@ -112,7 +122,11 @@ export async function writeNewProjectTheme(root, tokensCss, slug, version) {
     ].join("\n");
     const base = css.replace(END_RE(slug), "\n").replace(/\n*$/, "\n");
     await writeFile(path, `${base}\n${block}\n`, "utf8");
-    return { written: relative(root, path).split("\\").join("/"), count: lines.length };
+    return {
+        written: relative(root, path).split("\\").join("/"),
+        count: lines.length,
+        pairs: systemPairs(tokensCss, (await readTheirs(root, slug)).every),
+    };
 }
 /**
  * O VOCABULÁRIO DELE E O CSS GLOBAL, para quem escreve nomes fora do `init` - o `colours` (etapa 05, 28/09). A mesma
@@ -176,11 +190,17 @@ export async function writeNewProjectRoot(root, tokensCss, slug, version) {
     ].join("\n");
     const base = css.replace(END_RE(slug), "\n").replace(/\n*$/, "\n");
     await writeFile(path, `${base}\n${block}\n`, "utf8");
-    return { written: relative(root, path).split("\\").join("/"), count: lines.length };
+    return {
+        written: relative(root, path).split("\\").join("/"),
+        count: lines.length,
+        pairs: systemPairs(tokensCss, r.every),
+    };
 }
 const importLine = (slug) => `@import "./${slug}.css";`;
 /** O CSS dele sem nada nosso: sem o bloco e sem a linha que importa o arquivo à parte. */
-const withoutOurs = (css, slug) => css.replace(END_RE(slug), "\n").replace(new RegExp(`^${escape(importLine(slug))}\\n`, "m"), "");
+const withoutOurs = (css, slug) => css
+    .replace(END_RE(slug), "\n")
+    .replace(new RegExp(`^${escape(importLine(slug))}\\n`, "m"), "");
 async function readTheirs(root, slug) {
     const sheets = await sheetsOf(root);
     const raw = new Map();
@@ -228,10 +248,13 @@ async function readTheirs(root, slug) {
     const everyRaw = new Map(raw);
     for (const full of sheets.values())
         for (const m of full.matchAll(/(?:^|[{;\s])(--[a-zA-Z0-9_-]+)\s*:\s*([^;}]+)/g))
-            if (!everyRaw.has(m[1]) && !m[1].startsWith("--ds-"))
+            if (!everyRaw.has(m[1]) &&
+                !m[1].startsWith("--ds-"))
                 everyRaw.set(m[1], m[2].trim());
     const every = resolved(everyRaw);
-    const entries = [...sheets].filter(([, css]) => TAILWIND_IMPORT.test(css)).map(([p]) => p);
+    const entries = [...sheets]
+        .filter(([, css]) => TAILWIND_IMPORT.test(css))
+        .map(([p]) => p);
     const rel = (p) => relative(root, p).split("\\").join("/");
     const top = [...counts].sort((a, b) => b[1] - a[1])[0];
     const entry = entries.length === 1 ? entries[0] : null;
@@ -254,6 +277,32 @@ async function readTheirs(root, slug) {
  * criou (`--ds-color-amber-400: var(--color-amber-400)`). Pular essas linhas encolhia o bloco na segunda
  * rodada: medido na prova de 27/09, 82 nomes viraram 38.
  */
+/** Os mesmos nomes de `systemNames`, com a variável nossa ao lado - o par que o `.lock` guarda. */
+/**
+ * A LARGURA DA PÁGINA - a régua em que as seções do catálogo param o conteúdo (defeito 4 da aula 01, 15/10).
+ *
+ * Ela não é token do sistema: é a régua do catálogo (`apps/web/src/lib/catalog/page-width.ts`, pedido dele em 14/10), e as
+ * seções a escrevem como `var(--ds-layout-page-width, 1440px)`. Aqui ela ganha o nome que o Tailwind v4 lê
+ * (`--container-*`), e o par vai para o `.lock`: a seção materializada escreve `var(--container-page)`, e a pessoa muda a
+ * largura num lugar só. O valor é o MESMO do catálogo - `page-width-twin.spec.ts` compara os dois.
+ */
+export const PAGE_WIDTH = { ours: "--ds-layout-page-width", theirs: "--container-page", value: "1440px" };
+function systemPairs(tokensCss, lookup = new Map()) {
+    const { names, values } = tongueOf([], tokensCss);
+    const out = [];
+    for (const ours of new Set([...values.keys(), ...names.keys()])) {
+        const theirs = theirNameFor(ours);
+        if (!theirs)
+            continue;
+        const pointed = names.get(ours);
+        const value = pointed ? lookup.get(pointed) : values.get(ours);
+        if (value && !value.includes("var(--ds-"))
+            out.push({ ours, theirs, value });
+    }
+    if (out.length > 0)
+        out.push({ ...PAGE_WIDTH });
+    return out;
+}
 function systemNames(tokensCss, lookup = new Map()) {
     const { names, values } = tongueOf([], tokensCss);
     const out = [];
@@ -266,6 +315,8 @@ function systemNames(tokensCss, lookup = new Map()) {
         if (value && !value.includes("var(--ds-"))
             out.push([theirs, value]);
     }
+    if (out.length > 0)
+        out.push([PAGE_WIDTH.theirs, PAGE_WIDTH.value]);
     return out;
 }
 const same = (a, b) => a.trim().toLowerCase() === b.trim().toLowerCase();
@@ -273,7 +324,9 @@ export async function readProjectTheme(root, tokensCss, slug) {
     const r = await readTheirs(root, slug);
     const base = { entry: r.entry, tokensFile: r.tokensFile };
     const colourValues = [
-        ...new Set(systemNames(tokensCss, r.every).filter(([n]) => n.startsWith("--color-")).map(([, v]) => v.toLowerCase())),
+        ...new Set(systemNames(tokensCss, r.every)
+            .filter(([n]) => n.startsWith("--color-"))
+            .map(([, v]) => v.toLowerCase())),
     ];
     const held = new Set([...r.values.values()].map((v) => v.trim().toLowerCase()));
     const matched = colourValues.filter((v) => held.has(v)).length;
@@ -284,7 +337,11 @@ export async function readProjectTheme(root, tokensCss, slug) {
         return { kind: "many-tailwind-entries", ...counts, ...base };
     if (r.own.size === 0)
         return { kind: "new", ...counts, ...base };
-    return { kind: matched * 2 >= colourValues.length && matched > 0 ? "matches" : "differs", ...counts, ...base };
+    return {
+        kind: matched * 2 >= colourValues.length && matched > 0 ? "matches" : "differs",
+        ...counts,
+        ...base,
+    };
 }
 /**
  * O BLOCO DO SISTEMA AO LADO DO DELE - o terceiro caso.
@@ -305,7 +362,9 @@ export async function readProjectTheme(root, tokensCss, slug) {
 export async function writeBesideTheirs(root, tokensCss, slug, version, where) {
     const r = await readTheirs(root, slug);
     const entryPath = r.entry ? join(root, r.entry) : null;
-    const separatePath = entryPath ? join(dirname(entryPath), `${slug}.css`) : null;
+    const separatePath = entryPath
+        ? join(dirname(entryPath), `${slug}.css`)
+        : null;
     /** Tira de todo lugar o que é nosso, antes de escrever no lugar escolhido. */
     const cleaned = new Map();
     for (const [path, css] of r.sheets) {
@@ -317,7 +376,9 @@ export async function writeBesideTheirs(root, tokensCss, slug, version, where) {
         for (const [path, css] of cleaned)
             if (css !== r.sheets.get(path))
                 await writeFile(path, css, "utf8");
-        if (separatePath && r.sheets.get(separatePath)?.startsWith(begin(slug)) && where !== "separate")
+        if (separatePath &&
+            r.sheets.get(separatePath)?.startsWith(begin(slug)) &&
+            where !== "separate")
             await rm(separatePath, { force: true });
     };
     const empty = { written: null, collisions: [], throughInline: [], added: 0 };
@@ -332,7 +393,9 @@ export async function writeBesideTheirs(root, tokensCss, slug, version, where) {
     }
     const missing = system.filter(([n]) => !r.own.has(n) && !r.values.has(n));
     const collisions = system
-        .filter(([n, v]) => r.values.has(n) && !r.inline.has(n) && !same(r.values.get(n), v))
+        .filter(([n, v]) => r.values.has(n) &&
+        !r.inline.has(n) &&
+        !same(r.values.get(n), v))
         .map(([n]) => n);
     const throughInline = [];
     const scoped = system.map(([n, v]) => {
@@ -346,7 +409,9 @@ export async function writeBesideTheirs(root, tokensCss, slug, version, where) {
     const block = [
         begin(slug),
         open(`${slug} v${version}, beside your own tokens. The @theme adds only the names your project did not have; inside the data-theme selector below every value is the system's, including the names you already use, which keep their value everywhere else. Written by \`init\`, where you chose.`),
-        ...(missing.length > 0 ? ["@theme {", ...missing.map(([n, v]) => `  ${n}: ${v};`), "}", ""] : []),
+        ...(missing.length > 0
+            ? ["@theme {", ...missing.map(([n, v]) => `  ${n}: ${v};`), "}", ""]
+            : []),
         `[data-theme="${slug}"] {`,
         ...scoped,
         "}",

package/dist/their-tongue.js

@@ -71,7 +71,8 @@ export function inTheirTongue(css, tongue, destination = "stylesheet") {
             inlined += 1;
             if (tongue.frozen.has(name))
                 froze += 1;
-            const font = destination === "stylesheet" ? viaNextFont(name, value, tongue) : null;
+            /** Nas duas saídas - a classe do Tailwind também (defeito 1 da aula 01, 15/10); `write` escapa o espaço. */
+            const font = viaNextFont(name, value, tongue);
             return write(font ?? value);
         }
         /**
@@ -155,6 +156,8 @@ artifacts) {
  */
 export function tongueOf(map, installedCss) {
     const names = new Map(map.map((p) => [p.ours, p.theirs]));
+    /** O valor que o `.lock` mediu para cada par - a folha reescrita já não o declara (`var(--text-sm)`). */
+    const pairValue = new Map(map.flatMap((p) => (p.value ? [[p.ours, p.value]] : [])));
     const values = new Map();
     /**
      * O que cada variável nossa declara na folha, antes de qualquer indireção ser seguida.
@@ -226,6 +229,32 @@ export function tongueOf(map, installedCss) {
         else
             values.set(ours, destination.value);
     }
+    /**
+     * O PAPEL DE TIPO FALA O NOME DO DEGRAU QUE VALE O MESMO (defeito 1 da aula 01, 15/10).
+     *
+     * O componente pede o tamanho pelo PAPEL (`--ds-typography-role-sm-font-size`), e o nome dele só existe para o DEGRAU da
+     * escala (`--ds-typography-scale-sm-font-size` -> `--text-sm`). O papel saía como `[font-size:0.875rem]` num projeto
+     * que declara `--text-sm: 0.875rem`, e o `doctor` acusava na hora um valor com nome esperando.
+     *
+     * Só quando o MESMO degrau (`role-sm` -> `scale-sm`) JÁ tem nome dele e vale exatamente o mesmo, na mesma propriedade -
+     * é a troca que o `--fix` faria depois. O papel nunca vira um degrau que o projeto não declara: sem nome, continua o valor.
+     */
+    for (const [ours, value] of values) {
+        const role = /^--ds-typography-role-(.+)-(font-size|line-height|letter-spacing)$/.exec(ours);
+        if (!role)
+            continue;
+        /** O MESMO degrau, nunca outro que por acaso vale o mesmo: `role-sm` -> `scale-sm` (prova de 15/10). */
+        const step = `--ds-typography-scale-${role[1]}-${role[2]}`;
+        const theirName = names.get(step);
+        if (!theirName)
+            continue;
+        const written = declared.get(step);
+        const stepValue = written?.startsWith("var(") ? pairValue.get(step) : written;
+        if (stepValue === undefined || stepValue.trim().toLowerCase() !== value.trim().toLowerCase())
+            continue;
+        names.set(ours, theirName);
+        values.delete(ours);
+    }
     /**
      * AS QUE MUDAM ENTRE ESQUEMAS E VIRAM LITERAL - o subconjunto que congela.
      *

package/dist/their-vars.js

@@ -1,6 +1,6 @@
 import { readdir, readFile } from "node:fs/promises";
-import { readStyleSheet } from "./doctor/scss-lens.js";
 import { join } from "node:path";
+import { readStyleSheet } from "./doctor/scss-lens.js";
 import { theirNames } from "./doctor/their-names.js";
 import { buildTable, normalizeValue, } from "./doctor/tokens.js";
 import { FAMILY_SEAM_PREFIX } from "./fonts.js";
@@ -268,3 +268,13 @@ export function danglingTheirVars(installedCss, theirs) {
     }
     return out;
 }
+/**
+ * OS NOMES QUE O CSS DELE AINDA DECLARA, dentre os pedidos - para o `add` não apagar o par que o `init` gravou
+ * (jornada "o pedido livre sai mastigado", 15/10). Ver o uso em `commands/add.ts`.
+ */
+export async function namesTheyDeclare(root, names) {
+    if (names.length === 0)
+        return new Set();
+    const theirs = await harvestTheirCss(root);
+    return new Set(names.filter((n) => theirs.byName.has(n)));
+}

package/package.json

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