synthesisui 0.16.416 → 0.16.418

package/dist/anatomy-from-sketch.js

@@ -212,6 +212,23 @@ function nameOfTag(tag) {
         .replace(/[^a-z0-9]+/g, "-")
         .replace(/^-|-$/g, "");
 }
+/**
+ * A PROP QUE ALIMENTA O ELEMENTO, na mesma grafia dos outros nomes de part.
+ *
+ * `contentFrom` é a expressão verbatim que o JSX escreve, então ela pode ser um identificador
+ * simples (`label`), um acesso (`item.title`) ou uma chamada. Só o que é um nome simples vira
+ * nome de part: um pedaço de expressão viraria uma classe ilegível no CSS compilado, e o nó cai
+ * em `box` como antes. Medido nos dois censos: os 19 do `codelevel-ui` são todos identificadores
+ * simples, e dos 534 do `frontend-hub` a maioria também.
+ */
+function nameOfProp(expression) {
+    const clean = expression.trim();
+    if (!/^[A-Za-z_$][\w$]*$/.test(clean))
+        return undefined;
+    const name = nameOfTag(clean);
+    /** `children` é a palavra do React, não do design dele - ali o nó é um slot, não uma part. */
+    return name && name !== "children" ? name : undefined;
+}
 /**
  * O NOME QUE ELE MESMO DEU AO ELEMENTO - a classe do CSS Module.
  *
@@ -535,6 +552,31 @@ consumedAt) {
         const hasKids = children.length > 0;
         let as;
         let name;
+        /**
+         * O CONTEÚDO QUE VEM DE UMA PROP DELE É CONTEÚDO - A1 da etapa 15 (dono, 11/09).
+         *
+         * O QUE ELE VIA: o `CapabilityCard` dele desenhado como três losangos `✧` soltos, e o `Beam`
+         * como um `✧`. A pergunta dele foi a certa: *"mesmo tendo a receita vindo de um componente
+         * funcionando, não consigo entender o motivo"*.
+         *
+         * A SUPOSIÇÃO QUE ERRAVA estava escrita três linhas abaixo, em voz alta: *"a leaf box with no
+         * content of its own is a drawn SHAPE (...) `icon` is the form for 'a bare shape with no
+         * text'"*. Em React o texto quase nunca é literal no JSX - ele vem de `{label}`, `{children}`,
+         * `{value}`. **"Sem texto literal" não significa "sem conteúdo": significa "o conteúdo vem de
+         * fora".**
+         *
+         * E O COLETOR JÁ SABIA. `contentFrom` é a expressão que aquele elemento escreve, e o contrato
+         * a descreve como *"a evidência de QUAL prop alimenta este elemento"*. A derivação nunca a
+         * consultava. MEDIDO nos dois censos congelados: **19 nós** no `codelevel-ui` e **534** no
+         * `frontend-hub` - e no sistema dele isso era 36 dos 94 nós chegando como `icon`, 20 deles
+         * sem ser glifo nenhum (`label`, `value`, `title`, `eyebrow`, `meta`).
+         *
+         * É EVIDÊNCIA, NUNCA EXECUÇÃO: em outro projeto a prop tem outro nome, e o que atravessa é
+         * que ESTE elemento é onde o conteúdo entra. Por isso a regra lê a PRESENÇA do campo, e a
+         * palavra dele só vira o nome da part.
+         */
+        const writesContent = typeof node.contentFrom === "string" &&
+            node.contentFrom.trim().length > 0;
         if (capitalised) {
             // A primitive's member name is the client's own word for the element.
             name = nameOfTag(tag);
@@ -551,10 +593,25 @@ consumedAt) {
             else if (form)
                 as = form;
             else
-                as = hasKids ? arrangement(classes) : node.text ? "text" : "icon";
+                as = hasKids
+                    ? arrangement(classes)
+                    : node.text || writesContent
+                        ? "text"
+                        : "icon";
         }
         else if (byTag) {
-            name = byTag.name;
+            /**
+             * A PALAVRA DELE VENCE O NOME QUE A TAG SUGERE (A5 da etapa 15).
+             *
+             * `BY_TAG` dá a um `<span>` o nome `text` e a um `<div>` nada - nomes corretos e MUDOS,
+             * que dizem o que a tag é e nada sobre o papel daquele nó no componente dele. Quando o
+             * JSX escreve `<span>{eyebrow}</span>`, `eyebrow` é a palavra que ele usa para aquilo, e
+             * é ela que precisa chegar na tela e no seletor. Perde só para um nome que também é dele
+             * e mais específico: uma classe de module, ou o membro de um componente que ele escreveu.
+             */
+            name =
+                (writesContent ? nameOfProp(String(node.contentFrom)) : undefined) ??
+                    byTag.name;
             if (NEUTRAL.has(lower)) {
                 /**
                  * A leaf box with no content of its own is a drawn SHAPE - a dot, a
@@ -564,7 +621,7 @@ consumedAt) {
                 as =
                     hasKids || node.slot
                         ? arrangement(classes)
-                        : node.text
+                        : node.text || writesContent
                             ? "text"
                             : "icon";
             }
@@ -572,7 +629,7 @@ consumedAt) {
                 as = byTag.as;
         }
         else {
-            as = hasKids ? arrangement(classes) : "icon";
+            as = hasKids ? arrangement(classes) : writesContent ? "text" : "icon";
         }
         /**
          * ANYTHING HOLDING ELEMENTS ARRANGES THEM - the contract gives children to
@@ -598,9 +655,16 @@ consumedAt) {
             /**
              * `box` VIROU A ÚLTIMA OPÇÃO, não a primeira - ver `nameOfModule`. Um nó com
              * classe de module tem nome, e o nome é dele.
+             *
+             * E A PROP QUE ALIMENTA O ELEMENTO VEM ANTES DE `box` (A5 da etapa 15). Os dois nós de
+             * texto do `CapabilityCard` dele chegavam como `box` e `box` - dois irmãos com o mesmo
+             * nome, que é o mesmo que não ter nome. `contentFrom: "label"` é a palavra que o CÓDIGO
+             * DELE escreve, e ela é melhor que qualquer coisa que a gente derivasse da tag.
              */
             name =
-                nameOfModule(node.moduleClass) ?? "box";
+                nameOfModule(node.moduleClass) ??
+                    (writesContent ? nameOfProp(String(node.contentFrom)) : undefined) ??
+                    "box";
         /**
          * A NODE WHOSE CONTENT IS THE CALLER'S is a slot, and it keeps its own name
          * and classes - the border and the hover on a `<tr>{children}</tr>` are real

package/dist/commands/add.js

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { agentsToMaintain } from "../agents-chosen.js";
 import { syncClaudeMd } from "../claude-md.js";
 import { readProjectConfig, readToken, resolveRegistry } from "../config.js";
+import { parseRules } from "../doctrine.js";
 import { customFontFamilies, googleFontsHref, nextFontSnippet, } from "../fonts.js";
 import { detectAppDirs, globalSheetOf, prefixFrom } from "../global-sheet.js";
 import { lockReference } from "../group-role.js";
@@ -375,9 +376,17 @@ export async function add(slug, opts) {
      * registry working unchanged.
      */
     const stack = await detectStack(projectRoot);
+    /**
+     * AS DUAS ENTRADAS VIRAM A MESMA FORMA ANTES DE TOCAR O DISCO.
+     *
+     * `ruleSet` vem estruturado e `rules` vem como frase - e enquanto a segunda caía direto no
+     * arquivo, o disco dele podia receber uma lista mista sem nada reclamar. `parseRules` normaliza
+     * as duas para `{ text, applies }`, e desfaz o prefixo `ds-a + ds-b:` da forma antiga no
+     * caminho, então um registry que ainda manda frase não perde o alcance da regra.
+     */
     const rules = payload.ruleSet && payload.ruleSet.length > 0
         ? rulesForProject(payload.ruleSet, stack)
-        : (payload.rules ?? []);
+        : parseRules(payload.rules ?? []);
     const leftOut = payload.ruleSet
         ? describeFiltered(payload.ruleSet, stack)
         : null;

package/dist/commands/doctor.js

@@ -16,6 +16,7 @@ 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 { parseRules } from "../doctrine.js";
 /**
  * `detectAppDirs` SAIU DESTE IMPORT em 09/09: quem pergunta "quais pastas são app?" agora é
  * `readWiringPerApp`, que responde a fiação de cada uma. O comando não escolhe mais um app.
@@ -320,13 +321,23 @@ measured) {
         if (doctrineRaw) {
             try {
                 const parsed = JSON.parse(doctrineRaw);
-                if (Array.isArray(parsed.rules))
+                /**
+                 * AS DUAS FORMAS DO DISCO, lidas pela mesma porta (`parseRules`).
+                 *
+                 * Este filtro era `typeof r === "string"`, e com a regra passando a viajar como dado ele
+                 * DESCARTARIA calado toda regra de uma instalação nova - o pior resultado possível para
+                 * uma doutrina, que é sumir sem ninguém saber. E a leitura pela porta única também
+                 * devolve o alcance às instalações ANTIGAS: o prefixo `ds-a + ds-b:` é desfeito ali, sem
+                 * reimportar nada.
+                 */
+                const parsedRules = parseRules(parsed.rules);
+                if (parsedRules.length > 0)
                     doctrines.push({
                         ...(typeof parsed.version === "number"
                             ? { version: parsed.version }
                             : {}),
                         ...(typeof parsed.name === "string" ? { name: parsed.name } : {}),
-                        rules: parsed.rules.filter((r) => typeof r === "string"),
+                        rules: parsedRules,
                     });
             }
             catch {

package/dist/commands/mcp.js

@@ -12,6 +12,7 @@ import { readEvents } from "../doctor/ledger.js";
 import { fileRequest } from "../doctor/requests.js";
 import { diagnose, nameToWrite, scanSource } from "../doctor/scan.js";
 import { nearestToken, normalizeValue, tokenFor } from "../doctor/tokens.js";
+import { ruleLine } from "../doctrine.js";
 import { fromCensus } from "../memory/observation.js";
 import { handleRecall, handleRemember, MEMORY_TOOLS } from "../memory/tools.js";
 import { readInstalledConvention } from "../project-facts.js";
@@ -523,7 +524,13 @@ async function systemDoctrine(root) {
         rules.length > 0
             ? `# Rules - maximum authority, ${rules.length} of them${pinned ? `, as of v${pinned}` : ""}`
             : "",
-        ...rules.map((r) => `- ${r}`),
+        /**
+         * `ruleLine` É O QUE MANTÉM ESTA SAÍDA IDÊNTICA. A regra passou a viajar como dado
+         * (`{ text, applies }`), e interpolar o objeto aqui imprimiria `[object Object]` sem o `tsc`
+         * reclamar - um template literal aceita qualquer coisa. O alcance volta a ser prefixo na hora
+         * de MOSTRAR, que é onde ele sempre esteve para quem lê.
+         */
+        ...rules.map((r) => `- ${ruleLine(r)}`),
     ].filter(Boolean);
     const pulse = await sessionPulse(root, pinned);
     return [
@@ -1706,7 +1713,7 @@ cli) {
             const plan = composePlan({
                 documents,
                 table,
-                rules: doctrines.flatMap((d) => d.rules),
+                rules: doctrines.flatMap((d) => d.rules).map(ruleLine),
                 /**
                  * A regra tem a FRASE e o PACOTE em campos separados (`text`,
                  * `requires`) - mandar a frase sozinha esconderia o que instalar, e

package/dist/doctrine.js

@@ -0,0 +1,96 @@
+/**
+ * A REGRA DO SISTEMA DELE, COMO DADO - e não como frase.
+ *
+ * ═══ O QUE ABRIU ESTE ARQUIVO, medido em 12/09 ═══
+ *
+ * O agente dele apagou a serif itálica de seis lugares da landing do `codelevel`, e nada avisou.
+ * A regra existia, instalada, em disco, no `doctrine.json` daquele projeto - a décima de vinte e
+ * cinco, verbatim:
+ *
+ *     "A display headline breaks onto a line set in the serif, italic - that line carries the
+ *      emphasis of the sentence, never the whole headline."
+ *
+ * O conhecimento estava a dois diretórios de distância da edição e ninguém o entregou. Palavras
+ * dele: *"o sistema fala antes do dano"*.
+ *
+ * ═══ A CAUSA, e ela é de uma linha ═══
+ *
+ * Do NOSSO lado a regra é estruturada: `applies` diz quais componentes ela governa, e
+ * `rules-for-component.ts` casa por esse campo há semanas. No caminho até o disco dele,
+ * `rulesForProject` achatava a estrutura num PREFIXO DE PROSA - `ds-button + ds-icon-button: <o
+ * texto>` - e a partir dali nada mais podia perguntar *"esta regra vale para o arquivo que está
+ * sendo escrito?"*. A resposta existia e era jogada fora na exportação.
+ *
+ * ═══ POR QUE UM MÓDULO, e não um `JSON.parse` em cada leitor ═══
+ *
+ * O `doctrine.json` é lido em três lugares - o doctor, o `system_doctrine` do MCP e o compositor
+ * de plano -, e a partir de agora existem DUAS formas no disco do mundo: a nova, estruturada, e a
+ * antiga, em string, que está instalada em todo projeto que rodou `connect` antes de hoje. Três
+ * leitores decidindo sozinhos o que fazer com duas formas são três chances de discordar sobre a
+ * mesma regra.
+ *
+ * ═══ E A FORMA ANTIGA NÃO PERDE O ALCANCE ═══
+ *
+ * O prefixo era um achatamento REVERSÍVEL: `ds-card + ds-noise-overlay: <texto>` carrega os dois
+ * nomes, só que em prosa. `parseRule` desfaz isso na leitura, então uma instalação antiga ganha o
+ * alcance de volta sem reimportar nada - que é a diferença entre uma correção que alcança quem já
+ * é cliente e uma que só alcança quem instalar amanhã.
+ */
+/**
+ * O PREFIXO QUE A FORMA ANTIGA USA: `ds-card + ds-noise-overlay: `.
+ *
+ * Ancorado no começo e exigindo o `ds-` em cada nome, porque uma frase pode conter dois pontos -
+ * *"Dark is a class, never the OS preference: @custom-variant dark"* é a segunda regra real do
+ * sistema dele, e sem a âncora ela viraria um componente chamado `Dark is a class, never the OS
+ * preference`.
+ */
+const LEGACY_SCOPE = /^((?:ds-[a-z0-9-]+)(?:\s*\+\s*ds-[a-z0-9-]+)*)\s*:\s*/;
+/** Uma regra vinda do disco, em qualquer das duas formas - ou `null` quando não há frase. */
+export function parseRule(raw) {
+    if (typeof raw === "string") {
+        const text = raw.trim();
+        if (!text)
+            return null;
+        const m = LEGACY_SCOPE.exec(text);
+        if (!m)
+            return { text, applies: [] };
+        return {
+            text: text.slice(m[0].length).trim(),
+            applies: m[1].split("+").map((n) => n.trim().replace(/^ds-/, "")),
+        };
+    }
+    if (!raw || typeof raw !== "object")
+        return null;
+    const r = raw;
+    const text = typeof r.text === "string" ? r.text.trim() : "";
+    if (!text)
+        return null;
+    const applies = Array.isArray(r.applies)
+        ? r.applies.filter((a) => typeof a === "string" && !!a.trim())
+        : [];
+    return { text, applies: applies.map((a) => a.trim().replace(/^ds-/, "")) };
+}
+/** Todas as regras de um `doctrine.json`, nas duas formas, sem as ilegíveis. */
+export function parseRules(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const entry of raw) {
+        const rule = parseRule(entry);
+        if (rule)
+            out.push(rule);
+    }
+    return out;
+}
+/**
+ * A REGRA COMO ALGUÉM A LÊ - a mesma frase que o disco carregava antes.
+ *
+ * O alcance volta a ser prefixo AQUI, na hora de mostrar, e não no dado. Quem imprime continua
+ * imprimindo o que sempre imprimiu; quem PERGUNTA passa a ter o campo.
+ */
+export function ruleLine(rule) {
+    const scope = rule.applies.length > 0
+        ? `${rule.applies.map((a) => `ds-${a}`).join(" + ")}: `
+        : "";
+    return `${scope}${rule.text}`;
+}

package/dist/install-marks.js

@@ -793,7 +793,7 @@ export const CHECKER_SINCE = "0.16.413";
  * deveriam estar lá. Quem tem censo gravado precisa de um `sync` para a fila de trabalho dele ser a
  * real; ver o livro-razão de `corpus.spec.ts`.
  */
-export const READER_SINCE = "0.16.408";
+export const READER_SINCE = "0.16.417";
 /**
  * O QUE ESTÁ INSTALADO AQUI FICOU PARA TRÁS - e as DUAS condições que fazem isso ser verdade.
  *

package/dist/rule-filter.js

@@ -1,18 +1,3 @@
-/**
- * WHICH RULES BELONG IN *THIS* PROJECT.
- *
- * A rule travels with the design system, and the system gets installed places it
- * was never written for. "The state arrives through this hook" is true about Next
- * and actively wrong about Vue - so a rule carries the environments it holds in,
- * and the filtering happens HERE, because the consumer's stack is the one thing
- * the platform cannot know (dono, 01/08).
- *
- * THE DEFAULT WHEN WE CANNOT TELL IS TO KEEP IT. A rule whose condition does not
- * match is removed, because obeying it would be a mistake. A rule we cannot
- * evaluate - the stack came back empty, or it names something we do not detect -
- * stays, because a rule nobody can judge is safer present than silently gone.
- * Those are two different situations and they get two different answers.
- */
 const norm = (v) => v.trim().toLowerCase();
 /**
  * True when this rule holds in a project built with `stack`.
@@ -45,10 +30,18 @@ export function rulesForProject(rules, stack) {
         const text = rule.text?.trim();
         if (!text)
             continue;
-        const scope = rule.applies?.length > 0
-            ? `${rule.applies.map((a) => `ds-${a}`).join(" + ")}: `
-            : "";
-        out.push(`${scope}${text}`);
+        /**
+         * O ALCANCE SAI DAQUI COMO CAMPO, e não mais como prefixo de prosa.
+         *
+         * Esta função achatava `applies` em `ds-a + ds-b: <texto>` e era o último ponto onde a
+         * estrutura existia: do disco em diante, nada mais podia perguntar se a regra vale para o
+         * arquivo que está sendo escrito. Foi assim que a regra da serif do `codelevel` - a décima
+         * de vinte e cinco, instalada, correta - não disse nada quando um agente a apagou de seis
+         * lugares (12/09).
+         *
+         * A frase não mudou: `ruleLine` volta a montar o prefixo na hora de MOSTRAR.
+         */
+        out.push({ text, applies: (rule.applies ?? []).map((a) => a.trim()) });
     }
     return out;
 }

package/package.json

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