synthesisui 0.16.130 → 0.16.132

package/dist/anatomy-from-sketch.js

@@ -467,9 +467,16 @@ versionOf) {
          */
         if (hasKids && as !== "row" && as !== "stack")
             as = arrangement(classes);
-        // A plain structural box earns a name only when it carries decisions - and
-        // it must earn one, because the name is what the class string travels on.
-        if (!name && classes)
+        /**
+         * A plain structural box earns a name only when it carries decisions - and it must earn
+         * one, because the name is what the class string travels on.
+         *
+         * UMA CLASSE DE MODULE TAMBÉM É DECISÃO. Num app de CSS Modules o elemento veste
+         * `className={styles.content}` e nenhuma string: sem isto o nó não ganhava nome, não virava
+         * part, e o bloco de 16 declarações lido do module não tinha onde pousar. O Tooltip dele
+         * chegava com 2 das 35 (04/08).
+         */
+        if (!name && (classes || node.moduleClass))
             name = "box";
         /**
          * A NODE WHOSE CONTENT IS THE CALLER'S is a slot, and it keeps its own name

package/dist/commands/import.js

@@ -17,6 +17,7 @@ import { keyframeOffsets, moduleImports, readModuleCss, readModuleUsage, transcr
 import { dataContract } from "../doctor/data-contract.js";
 import { reconcile, scanDefinitions, } from "../doctor/definitions-scan.js";
 import { describeConvention, describeRemainder, detectConventions, } from "../doctor/idiom.js";
+import { pageLaws } from "../doctor/page-laws.js";
 import { callSiteNode, placeLayers, } from "../doctor/place-layers.js";
 import { publicApi, requiredProps } from "../doctor/public-api.js";
 import { diagnose, scanSource } from "../doctor/scan.js";
@@ -263,6 +264,10 @@ export async function takeCensus(root, opts) {
     const defined = [];
     /** Nome → arquivo e fonte, para toda leitura por componente - ver o preenchimento abaixo. */
     const sourceOf = new Map();
+    /** Nome → o que a peça é, quando o portão soube dizer. Ver `CensusLook.kind`. */
+    const kindOf = new Map();
+    /** A raiz e a composição de cada página, para as leis - ver `pageLaws`. */
+    const pages = [];
     /** What the gate turned away, with the reason. Never dropped in silence. */
     const skips = [];
     // Kept for the reference check below, which needs every file at once: a name
@@ -391,9 +396,33 @@ export async function takeCensus(root, opts) {
                     internal,
                 });
                 if (verdict.ok) {
-                    found.push(d);
+                    /**
+                     * O QUE A PEÇA É viaja com ela - ver `GateVerdict.kind`. Um template decide arranjo e
+                     * não aparência, e três superfícies precisam saber disso para não cobrar cor de quem
+                     * nunca prometeu cor.
+                     */
+                    found.push(verdict.kind ? { ...d, kind: verdict.kind } : d);
                     continue;
                 }
+                /**
+                 * A RAIZ DE UMA PÁGINA E O QUE ELA COMPÕE, para as leis - ver `pageLaws`.
+                 *
+                 * Uma rota individualmente não vale receita: 5 elementos de média e a raiz repetindo o
+                 * que outras oito já disseram. Juntas elas dizem como é a casca deste projeto, que é o
+                 * que falta para alguém escrever a próxima (04/08).
+                 */
+                if (verdict.why === "route" || verdict.why === "screen") {
+                    const sketch = sketchOf(src, d.name);
+                    const root = sketch[0];
+                    pages.push({
+                        root: root?.classes
+                            ? transcribe(root.classes.split(/\s+/).filter(Boolean), declaredValues).base
+                            : {},
+                        composes: sketch
+                            .filter((n) => /^[A-Z]/.test(n.tag))
+                            .map((n) => n.tag.split(".")[0]),
+                    });
+                }
                 skips.push({
                     name: d.name,
                     file: rel,
@@ -426,8 +455,12 @@ export async function takeCensus(root, opts) {
              * numa lista feita para biblioteca. O look já nasce aqui, com o arquivo e a fonte na mão,
              * e é aqui que a leitura tem que se pendurar.
              */
-            for (const d of found)
+            for (const d of found) {
                 sourceOf.set(d.name, { file: rel, source: src });
+                /** O que a peça É, do portão - ver `GateVerdict.kind` e `CensusLook.kind`. */
+                if (d.kind)
+                    kindOf.set(d.name, d.kind);
+            }
             // THE LOOK, from their own class names. One transcription per file, keyed
             // by the component it defines - the root element's classes are the
             // component's own look, and everything below it is a part this slice does
@@ -733,6 +766,18 @@ export async function takeCensus(root, opts) {
     if (hasScreens) {
         const keep = [];
         for (const d of defined) {
+            /**
+             * UM TEMPLATE VIVE NUMA TELA SÓ POR DEFINIÇÃO - ele É a tela.
+             *
+             * A regra de duas telas existe para separar "decisão que o produto compartilha" de
+             * "markup daquela tela", e está certa para uma PEÇA. Aplicada a um template ela recusa
+             * exatamente o que o portão acabou de aceitar: as 16 telas do dashboard dele passavam o
+             * portão como `template` e caíam aqui, aparecendo no relatório como `feature` (04/08).
+             */
+            if (d.kind === "template") {
+                keep.push(d);
+                continue;
+            }
             const screens = screensOf.get(d.name)?.size ?? 0;
             if (screens >= SCREENS_FOR_SYSTEM) {
                 keep.push(d);
@@ -1126,6 +1171,19 @@ export async function takeCensus(root, opts) {
      * The skill asks which has priority; the chosen one becomes a system-wide rule that
      * reaches CLAUDE.md, so every prompt after this respects where a new component goes.
      */
+    /**
+     * AS LEIS DAS PÁGINAS, ditas onde a arquitetura já é dita - governam o sistema, não uma peça,
+     * então `applies` é vazio e elas chegam a todo prompt. Ver `pageLaws`.
+     */
+    const pageRules = pageLaws(pages);
+    if (pageRules.length > 0) {
+        console.log("");
+        console.log(section("What your pages agree on"));
+        for (const law of pageRules) {
+            console.log(body(law.text));
+            console.log(body(paint.faint(`  ${law.evidence}`)));
+        }
+    }
     if (architectures.length > 0) {
         console.log("");
         console.log(section("How this project is organised"));
@@ -1332,8 +1390,12 @@ export async function takeCensus(root, opts) {
         if (c)
             c.api = stamped;
         const look = looks[name];
-        if (look)
+        if (look) {
             look.api = stamped;
+            const kind = kindOf.get(name);
+            if (kind)
+                look.kind = kind;
+        }
     }
     const brokenRefs = findBrokenRefs(sources, declaredNames);
     const conventions = detectConventions(sources);
@@ -2174,6 +2236,43 @@ async function resolveReadParts(census, root) {
             }
             target.base = { ...style, ...target.base };
         }
+        /**
+         * O QUE UM CSS MODULE DECLAROU, ONTO THE PART THAT WEARS THAT CLASS.
+         *
+         * Num app de CSS Modules a classe do module é a identidade do elemento, e a anatomia dá
+         * outro nome ao mesmo nó - o `content` do Tooltip dele vira `text` pelo papel. As duas
+         * listas nunca se encontravam, porque a junção era por NOME: o módulo entregava
+         * `parts.content` com 16 declarações e a anatomia substituía tudo por `parts.text` vazia.
+         * As 35 declarações do Tooltip chegavam como 2 (04/08).
+         *
+         * A junção é por CLASSE, que é um dado do próprio nó - ver `SketchNode.moduleClass`. Uma
+         * classe cujo nó a anatomia não nomeia é dita em voz alta, nunca empurrada para a raiz.
+         */
+        const sketch = (look?.sketch ?? []);
+        const fromModule = look?.parts ?? {};
+        for (const [index, node] of sketch.entries()) {
+            const cls = node.moduleClass;
+            if (!cls)
+                continue;
+            const block = fromModule[cls];
+            if (!block)
+                continue;
+            const part = partAt[index];
+            const target = part ? resolved.parts[part] : undefined;
+            if (!target) {
+                notes.add(`\`.${cls}\` in a CSS module styles an element the anatomy does not name, so it is not applied - putting it on the component would paint the wrong thing`);
+                continue;
+            }
+            /** O que a class string já disse ganha: um utilitário no mesmo elemento é mais recente. */
+            target.base = { ...block.base, ...target.base };
+            if (Object.keys(block.dark ?? {}).length > 0)
+                target.dark = { ...block.dark, ...target.dark };
+            for (const [state, decls] of Object.entries(block.states ?? {}))
+                target.states = {
+                    ...target.states,
+                    [state]: { ...decls, ...(target.states?.[state] ?? {}) },
+                };
+        }
         /**
          * REPLACED, NOT APPENDED - because this runs more than once.
          *

package/dist/doctor/component-gate.js

@@ -43,6 +43,19 @@ const RESERVED_FILE_OTHER = /(^|[/\\])(\+page|\+layout|\+server|_app|_document|_
  * hundred libraries. It only counts when the file itself is a route.
  */
 const SCREEN_SUFFIX = /(Page|Screen|Route|Template|Layout)$/;
+/**
+ * Quantos elementos uma tela tem e quantos deles são peça de alguém - o que separa um template
+ * de uma casca. Contado no arquivo, sem sketch: este portão roda antes de qualquer leitura.
+ */
+function screenShape(source, name) {
+    const at = source.indexOf(name);
+    const body = at === -1 ? source : source.slice(at);
+    const tags = [...body.matchAll(/<([A-Za-z][\w.]*)/g)].map((m) => m[1]);
+    return {
+        nodes: tags.length,
+        composes: new Set(tags.filter((t) => /^[A-Z]/.test(t)).map((t) => t.split(".")[0])).size,
+    };
+}
 /** Something that carries context down the tree rather than drawing. */
 const PROVIDER_SUFFIX = /(Provider|Providers|Context|Boundary|Guard|Wrapper)$/;
 /** Any JSX at all in the file. A capitalised export with none is a constant, a
@@ -174,11 +187,22 @@ export function gateComponent(input) {
             because: `\`${file}\` is a file name the framework reserves - it is a route, not a component somebody can import`,
         };
     }
+    /**
+     * UMA TELA ENTRA COMO TEMPLATE, e o que decide é o que ela FAZ.
+     *
+     * O nome é a pista (`…Template`, `…Screen`, `…Page`) e não a prova: uma tela que compõe três
+     * ou mais peças numa árvore de dez ou mais nós é uma decisão de arranjo que vale receita -
+     * `CurateTemplate` tem 89 nós e 237 declarações. Uma que não alcança isso é casca, e casca é
+     * lei, não peça.
+     */
     if (SCREEN_SUFFIX.test(name)) {
+        const shape = screenShape(source, name);
+        if (shape.composes >= 3 && shape.nodes >= 10)
+            return { ok: true, kind: "template" };
         return {
             ok: false,
             why: "screen",
-            because: `\`${name}\` names a whole screen or the frame around one. A design system is made of the pieces a screen is built FROM`,
+            because: `\`${name}\` names a screen, and composes ${shape.composes} piece${shape.composes === 1 ? "" : "s"} across ${shape.nodes} element${shape.nodes === 1 ? "" : "s"} - too thin to be a template of yours. A design system is made of the pieces a screen is built FROM`,
         };
     }
     if (PROVIDER_SUFFIX.test(name) || IS_CONTEXT.test(source)) {

package/dist/doctor/css-modules.js

@@ -83,7 +83,19 @@ function rules(css, media = null, out = []) {
         const open = css.indexOf("{", i);
         if (open === -1)
             break;
-        const head = css.slice(i, open).trim();
+        /**
+         * O SELETOR É O QUE VEM DEPOIS DA ÚLTIMA DECLARAÇÃO, não o texto todo até a chave.
+         *
+         * Num CSS plano o cabeçalho de uma regra já vem limpo, e por isso isto passou. Num `.scss`
+         * aninhado não: o corpo de `.content` é
+         *
+         *     background-color: …;  border-radius: 4px;  .header {
+         *
+         * e o cabeçalho da regra do `.header` saía com as duas declarações grudadas na frente.
+         * `classesIn` então achava fragmentos como `0` (de `opacity: 0`) e 12 seletores por arquivo
+         * iam para `unslotted` (04/08).
+         */
+        const head = css.slice(i, open).split(/[;}]/).pop()?.trim() ?? "";
         // Balance to the matching close, because an at-rule contains whole rules.
         let depth = 0;
         let close = -1;
@@ -113,6 +125,33 @@ function rules(css, media = null, out = []) {
         }
         else if (head) {
             out.push({ selector: head, body, media });
+            /**
+             * UM BLOCO ANINHADO É UMA REGRA, e não texto do pai.
+             *
+             * Esta varredura era plana, e num `.scss` isso significa que
+             *
+             *     [data-theme="light"] { .container { .content { background } } }
+             *
+             * produzia UMA regra: seletor `[data-theme="light"]`, sem classe nenhuma, então
+             * `unslotted` - e o bloco inteiro ia para o lixo. Já a versão sem tema produzia
+             * `.container` com TODAS as declarações de todos os níveis, porque `declarations()`
+             * varre o corpo e o corpo é o arquivo. Medido no repo dele (04/08): 196 de 200 modules
+             * usam aninhamento, o Tooltip saiu com 19 declarações na raiz e 4 classes perdidas, 969
+             * de 1637 parts vieram vazias, e 109 blocos dark viraram 5.
+             *
+             * Descer com o seletor do pai na mão resolve os três de uma vez: o filho passa a ter
+             * seletor completo, `classesIn` acha a classe certa, a relação pai-filho é registrada, e
+             * `[data-theme="dark"] .x` casa o teste de tema. O `&` do Sass é resolvido contra o pai,
+             * que é o que ele significa.
+             */
+            for (const nested of rules(body, media)) {
+                out.push({
+                    ...nested,
+                    selector: nested.selector.includes("&")
+                        ? nested.selector.replace(/&/g, head)
+                        : `${head} ${nested.selector}`,
+                });
+            }
         }
         i = close + 1;
     }
@@ -121,8 +160,22 @@ function rules(css, media = null, out = []) {
 /** `prop: value;` pairs, in the camelCase the contract uses. */
 function declarations(body) {
     const out = {};
-    // Only the top level: a nested rule's declarations belong to that rule.
-    const flat = body.replace(/\{[^{}]*\}/g, "").replace(/[^;]*\{/g, "");
+    /**
+     * SÓ O NÍVEL DE CIMA - e "só" exige repetir, porque um module aninha mais de um nível.
+     *
+     * Uma passada tira o bloco mais interno e deixa o do meio aberto, então as declarações do
+     * meio vazavam para o pai: `.card { padding; .title { font-size; > h3 { margin } } }` dava
+     * `font-size` ao card e `margin` ao title. Com 196 de 200 modules dele aninhando e a maioria
+     * em três níveis, é o vazamento que fazia a raiz vestir o module inteiro (04/08).
+     */
+    let flat = body;
+    for (let guard = 0; guard < 12; guard++) {
+        const next = flat.replace(/\{[^{}]*\}/g, "");
+        if (next === flat)
+            break;
+        flat = next;
+    }
+    flat = flat.replace(/[^;{}]*\{/g, "");
     for (const piece of flat.split(";")) {
         const colon = piece.indexOf(":");
         if (colon === -1)

package/dist/doctor/page-laws.js

@@ -0,0 +1,106 @@
+/**
+ * O QUE AS PÁGINAS DE UM APP CONCORDAM, quando nenhuma delas vale uma receita.
+ *
+ * As 129 rotas do dashboard dele têm média de 5 elementos e 2 peças compostas, e a raiz de uma
+ * repete o que outras oito já disseram. Cada uma individualmente não tem o que uma receita
+ * carrega - virar 129 entradas na vitrine seria o problema de escala sem o benefício.
+ *
+ * Mas juntas elas dizem uma coisa que hoje não existe em lugar nenhum do sistema. Medido nas 129
+ * (04/08):
+ *
+ *     width: 100%              12 páginas
+ *     position: sticky          8      ┐
+ *     top: 0                    8      ├ juntos: o cabeçalho fixo de página
+ *     z-index: 50               8      ┘
+ *     padding: 1rem             8
+ *     min-height: 100vh         6        a casca da página
+ *     ContentWrapper           22 páginas compõem
+ *     PageHeader               14
+ *
+ * Três ou mais arquivos concordando é hábito - a mesma escada que o resto da esteira usa. E uma
+ * lei com a contagem atrás vale mais que a receita de qualquer uma das 129, porque é isso que
+ * alguém precisa saber para escrever a 130ª.
+ *
+ * O QUE ELA NUNCA FAZ: propor. Uma lei aqui é a descrição do que eles já fazem, com o número, e
+ * o que NÃO se repete não vira lei - duas páginas concordando é coincidência, e chamar isso de
+ * convenção do projeto seria inventar uma decisão que ninguém tomou.
+ */
+/** O mínimo para um hábito, e é o mesmo número que o resto da esteira usa. */
+const AGREE = 3;
+/** Propriedades que descrevem a MOLDURA de uma página, e não a aparência de uma peça. */
+const SHELL = /^(minHeight|height|width|maxWidth|padding|paddingTop|paddingBottom|margin|marginTop|display|gridTemplateColumns|gap|position|top|zIndex|overflow|justifyContent|alignItems)$/;
+/**
+ * As leis que as páginas de um escopo concordam, ou nada quando não concordam.
+ *
+ * `pages` é uma entrada por página: o que a RAIZ dela declara e quais peças ela compõe. Quem
+ * chama já leu as duas coisas para o relatório do portão, então isto não abre nenhum arquivo.
+ */
+export function pageLaws(pages) {
+    if (pages.length < AGREE)
+        return [];
+    const values = new Map();
+    const composed = new Map();
+    for (const page of pages) {
+        for (const [prop, value] of Object.entries(page.root)) {
+            if (!SHELL.test(prop))
+                continue;
+            const key = `${prop}: ${value}`;
+            values.set(key, (values.get(key) ?? 0) + 1);
+        }
+        for (const name of new Set(page.composes))
+            composed.set(name, (composed.get(name) ?? 0) + 1);
+    }
+    const agreed = [...values.entries()]
+        .filter(([, n]) => n >= AGREE)
+        .sort((a, b) => b[1] - a[1]);
+    const laws = [];
+    /**
+     * A CASCA: o que a raiz de uma página deste projeto declara. Uma altura mínima de viewport e um
+     * padding de container não são a aparência de uma peça - são a moldura, e é o que falta a quem
+     * vai escrever a próxima página.
+     */
+    const shell = agreed.filter(([key]) => !/^(position|top|zIndex):/.test(key));
+    if (shell.length > 0) {
+        laws.push({
+            text: `A page of this project is ${shell
+                .slice(0, 4)
+                .map(([key]) => `\`${key}\``)
+                .join(", ")}` +
+                `${composed.size > 0 && (composed.get(topOf(composed)) ?? 0) >= AGREE ? ` and puts its content inside \`${topOf(composed)}\`` : ""}` +
+                `. Write the next one the same way, or change all of them.`,
+            applies: [],
+            kind: "implementation",
+            evidence: shell
+                .slice(0, 4)
+                .map(([key, n]) => `${key} in ${n} of ${pages.length} pages`)
+                .join("; "),
+        });
+    }
+    /**
+     * O CABEÇALHO FIXO: os três juntos são um padrão, e separados não dizem nada. Só vale como lei
+     * quando os três concordam, porque `position: sticky` sozinho pode ser qualquer coisa.
+     */
+    const sticky = agreed.filter(([key]) => /^(position: sticky|top: 0|zIndex:)/.test(key));
+    if (sticky.length >= 3) {
+        const header = [...composed.entries()]
+            .filter(([name, n]) => n >= AGREE && /header/i.test(name))
+            .sort((a, b) => b[1] - a[1])[0];
+        laws.push({
+            text: `The header of a page is ${sticky
+                .map(([key]) => `\`${key}\``)
+                .join(", ")}` +
+                `${header ? ` and it is \`${header[0]}\`` : ""}` +
+                `. A second sticky element at another z-index is how two headers end up fighting.`,
+            applies: [],
+            kind: "implementation",
+            evidence: sticky
+                .map(([key, n]) => `${key} in ${n} of ${pages.length} pages`)
+                .join("; "),
+        });
+    }
+    return laws;
+}
+/** O nome mais composto, que é o candidato a "onde o conteúdo vai". */
+function topOf(composed) {
+    return [...composed.entries()].sort((a, b) => b[1] - a[1])[0]?.[0] ?? "";
+}

package/dist/doctor/sketch.js

@@ -427,6 +427,11 @@ function closeOf(source, open) {
     }
     return -1;
 }
+/**
+ * `className={styles.content}` e `className={s.content}` - a forma que um app de CSS Modules
+ * usa em todo elemento. O identificador é o import do module, e a propriedade é a classe.
+ */
+const MODULE_CLASS = /className=\{\s*([A-Za-z_$][\w$]*)\.([A-Za-z_$][\w$]*)\s*\}/;
 export function sketchOf(source, name) {
     /**
      * READ THE IMPORTS BEFORE SLICING - they live at the top of the file, and the
@@ -519,6 +524,10 @@ export function sketchOf(source, name) {
         const list = repeatOf(source, event.at);
         if (list)
             node.repeats = list;
+        /** A classe de module que ele veste - ver `moduleClass`. */
+        const mod = MODULE_CLASS.exec(event.body);
+        if (mod)
+            node.moduleClass = mod[2];
         // What has to be true for this element to exist at all - see `guardAt`.
         const guard = guardAt(source, event.at);
         if (guard) {

package/package.json

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