synthesisui 0.16.269 → 0.16.270

package/dist/claude-md.js

@@ -312,8 +312,35 @@ async function readInterfaceLanguage(projectRoot) {
     return null;
 }
 async function renderRegion(projectRoot, installed) {
+    /**
+     * AINDA NÃO EXISTE SISTEMA, E O BLOCO PASSA A DIZER ISSO - antes ele saía vazio.
+     *
+     * Medido no repo do dono (21/08): 52 bytes, só o par de marcadores. A informação existia por três
+     * canais e os três dependem de execução - as skills e o MCP exigem REABRIR a sessão, e o
+     * `SessionStart` exige `npx ... align` rodar. O CLAUDE.md é o único que não depende de nada, e era
+     * justamente o calado: se o SessionStart falhar, o agente abre sem saber que há algo a fazer aqui.
+     *
+     * UMA LINHA, NÃO UM MANUAL, e nada sobre token ou componente: um bloco que falasse de
+     * `--ds-color-*` num repo sem sistema mandaria o agente escrever refs que não resolvem. O erro
+     * oposto é pior que o silêncio.
+     */
     if (installed.length === 0) {
-        return `${START}\n${END}`;
+        return [
+            START,
+            "## Design system",
+            "",
+            "This project is wired to synthesisui and has **no design system yet** - so there is",
+            "no token vocabulary to follow, and nothing here to obey.",
+            "",
+            "To turn this repository into one, run `/sui-import-ds` and I will read what is",
+            "already in the code: the colours, the type, the shapes and the components. Nothing",
+            "is invented, and nothing is copied out.",
+            "",
+            "The `synthesisui` MCP server is registered, so ASK it instead of guessing - it",
+            "answers what exists and what does not. This block fills itself in once a system is",
+            "installed.",
+            END,
+        ].join("\n");
     }
     /**
      * A CAPACIDADE, MEDIDA UMA VEZ POR ARQUIVO - ver `recallAvailable`.

package/dist/commands/add.js

@@ -41,6 +41,27 @@ const IGNORED = [
 const IGNORE_HEADER = "# Managed by synthesisui. The identity and the CSS are committed so a fresh\n" +
     "# clone is governed; the measurement and the local record are not, because\n" +
     "# both are rewritten in full on every run and would conflict on every merge.\n";
+/**
+ * A CASA DO REGISTRO LOCAL, ABERTA ANTES DE ALGUÉM ESCREVER NELA.
+ *
+ * Medido no repo do dono em 21/08, depois de apagar tudo e rodar só o `connect`: `.claude/`,
+ * `.mcp.json` e `CLAUDE.md` nasceram, e `_synthesisui/` não. `appendEvent` grava com `appendFile` e
+ * nunca cria diretório - sem a pasta é `ENOENT`, e o `catch` dele engole em silêncio. Então TODO
+ * evento entre o `connect` e o primeiro `import` se perdia: o `run` do próprio connect, e cada check
+ * do hook depois de cada escrita.
+ *
+ * POR QUE AQUI E NÃO NO `appendEvent`: fazer o gravador criar a pasta faria um `npx synthesisui list`
+ * de curiosidade plantar `_synthesisui/` no repo de quem só estava olhando - e aquele `catch` existe
+ * exatamente para esse caso. O `connect` é o comando que INSTALA, e é o único lugar onde abrir a casa
+ * é uma decisão que a pessoa tomou.
+ *
+ * A casa nasce com o `.gitignore`, senão o primeiro `ledger.jsonl` aparece no `git status` dele antes
+ * de o `add` rodar - a diferença entre um registro local e um arquivo que ele commita por engano.
+ */
+export async function ensureGovernanceHome(projectRoot) {
+    await mkdir(join(projectRoot, "_synthesisui"), { recursive: true });
+    await writeGovernanceIgnore(projectRoot);
+}
 async function writeGovernanceIgnore(projectRoot) {
     const path = join(projectRoot, "_synthesisui", ".gitignore");
     const existing = await readFile(path, "utf8").catch(() => null);

package/dist/commands/connect.js

@@ -7,7 +7,7 @@ import { body, paint, section, snippet } from "../output.js";
 import { readShellAnswer, rememberShellNo } from "../shell-answer.js";
 import { existingRc, hasHook, pinnedInHook, rcPathFor, shellFrom, shellSnippet, withHook, } from "../shell-hook.js";
 import { SKILLS } from "../skills.js";
-import { add } from "./add.js";
+import { add, ensureGovernanceHome } from "./add.js";
 import { reportWhatIsLeft } from "./align.js";
 import { ci } from "./ci.js";
 import { MCP_TOOL_COUNT } from "./mcp.js";
@@ -209,6 +209,14 @@ export async function connect(opts) {
      * `syncClaudeMd` abaixo tem que ser o último a falar sobre ele.
      */
     const refreshed = await refreshInstall(root, opts.version, opts.registry).catch(() => null);
+    /**
+     * A CASA DO REGISTRO LOCAL, ANTES DA PRIMEIRA ESCRITA - ver `ensureGovernanceHome`.
+     *
+     * Aqui e não depois: o `wireAgent` já é um comando que roda, e o `run` desta própria execução é
+     * gravado no fim pelo wrapper do `index.ts`. Sem a pasta ele cai num `catch` silencioso, junto com
+     * todo check do hook até o primeiro `import` - medido no repo do dono em 21/08.
+     */
+    await ensureGovernanceHome(root);
     const wired = await wireAgent(root, opts.version, want);
     // The block reads the settings we just wrote, so it must be regenerated
     // after them, not before.
@@ -299,9 +307,20 @@ export async function connect(opts) {
         const moved = contract.changed.includes(home);
         console.log(body(`${moved ? "✓" : "·"} ${home.padEnd(22)} ${moved
             ? home === "CLAUDE.md"
-                ? "rewritten for what is installed"
+                ? /**
+                   * A FRASE DIZ O QUE O BLOCO CARREGA, e ela descrevia um conteúdo que não existia.
+                   *
+                   * Num repo sem sistema o bloco saía vazio e esta linha dizia "rewritten for what is
+                   * installed" - nada estava instalado, e nada foi escrito. Agora o bloco diz o que
+                   * fazer, e a linha diz qual dos dois ele é (dono, 21/08).
+                   */
+                    contract.count === 0
+                        ? "how to turn this repo into your system"
+                        : "rewritten for what is installed"
                 : "the same rules, where this agent reads them"
-            : "already says what is installed"}`));
+            : contract.count === 0
+                ? "already says how to start"
+                : "already says what is installed"}`));
     }
     /**
      * The fourth layer, and the one that had no installer at all: the import

package/dist/commands/import.js

@@ -35,6 +35,7 @@ import { buildTable } from "../doctor/tokens.js";
 import { definitionSpan, parseClass, readInlineStyle, rootClasses, rootTag, transcribe, } from "../doctor/transcribe.js";
 import { transcribeVariants } from "../doctor/variant-read.js";
 import { frontierKind, packageRoot } from "../frontier-kind.js";
+import { keyframesInSheets } from "../global-keyframes.js";
 import { withLibraryStructure } from "../library-structure.js";
 import { mergeCensus } from "../merge-census.js";
 import { claimName } from "../name-claim.js";
@@ -435,6 +436,18 @@ export async function takeCensus(root, opts) {
      * porque é isso que o juiz do ledger precisa para chamar a classe e a regra de LIDAS.
      */
     const globalClasses = readGlobalClasses(globalSheets, declaredValues);
+    /**
+     * OS KEYFRAMES DA FOLHA DELE, colhidos onde as folhas globais já estão na mão.
+     *
+     * Eram 35 dos 84 tokens declarados do codelevel - 42% do vocabulário - e o censo saía com
+     * `keyframes: undefined`, porque o leitor só olhava CSS Module e `<style>` island. Ver
+     * `global-keyframes.ts` para o porquê e para o que o valor de cada `--animate-*` carrega.
+     *
+     * Aqui e não dentro de `harvestOwnCss` porque aquela função é o laço de COLHEITA, e esta é uma
+     * leitura sobre o que ela colheu - a mesma divisão que `readGlobalClasses` já respeita, uma linha
+     * acima.
+     */
+    const globalKeyframes = keyframesInSheets(globalSheets);
     const globalClassesClaimed = new Set();
     /** Por arquivo, as classes cuja regra a `<style>` island já entregou - ver o juiz. */
     const islandClassesRead = new Map();
@@ -1952,7 +1965,17 @@ export async function takeCensus(root, opts) {
                 : {}),
         },
         declared: Object.fromEntries(table.byName),
-        ...(Object.keys(keyframes).length > 0 ? { keyframes } : {}),
+        /**
+         * A FOLHA DELE ENTRA POR ÚLTIMO, e a ordem é a resposta a quem manda.
+         *
+         * `keyframes` já traz o que veio de CSS Module e de `<style>` island - definições de COMPONENTE.
+         * A folha global é a base do app, então ela preenche o que falta e não sobrescreve o que um
+         * componente declarou para si. Sem esta linha o codelevel saía com `keyframes: undefined` e 35 dos
+         * 84 tokens dele - 42% do vocabulário - não chegavam a lugar nenhum.
+         */
+        ...(Object.keys({ ...globalKeyframes, ...keyframes }).length > 0
+            ? { keyframes: { ...globalKeyframes, ...keyframes } }
+            : {}),
         ...(animations.size > 0 ? { animations: [...animations].sort() } : {}),
         ...(brokenRefs.length > 0 ? { brokenRefs } : {}),
         /**

package/dist/global-keyframes.js

@@ -0,0 +1,46 @@
+import { keyframeOffsets, readModuleCss } from "./doctor/css-modules.js";
+/**
+ * OS KEYFRAMES QUE A FOLHA DELE DECLARA - e eram 42% do vocabulário do codelevel.
+ *
+ * O leitor colhia keyframes de duas fontes: o CSS Module de um componente e o `<style>` island. Não da
+ * folha GLOBAL, que é exatamente onde um projeto Tailwind v4 com `@theme` os escreve. Medido no censo
+ * do dono (21/08): 35 dos 84 tokens declarados são `--animate-*`, e o censo saía com
+ * `keyframes: undefined`.
+ *
+ * O valor de cada atalho carrega tudo o que importa, e nada disso chegava:
+ *
+ *     --animate-fade-slide-in: fade-slide-in 1s var(--ease-out-soft) both
+ *                              ^ o keyframe   ^ dur ^ o easing DELE  ^ fill
+ *
+ * E a consequência não era só perder token. `unknownAnimations` crescia: o documento recusava definir
+ * quatro animações que os componentes dele nomeiam - a nota dizia "a plugin's own" - quando a definição
+ * estava na folha dele, a um parser de distância.
+ *
+ * NADA AQUI É PARSER NOVO. `readModuleCss` já extrai `@keyframes` de qualquer CSS e `keyframeOffsets`
+ * já vira o corpo cru na forma que o documento quer (offset → declarações). Só ninguém os chamava para
+ * a folha global. É o mesmo defeito de forma que apareceu seis vezes nesta rodada: a varredura
+ * enumerando as fontes que já conhecia.
+ *
+ * MATERIALISER - um cliente pinado recebe diferente? Não: isto muda o CENSO, e o que cai na pasta dele
+ * vem do documento que o servidor compila depois. Ele só vê a diferença após um re-import, e é por isso
+ * que esta é a única entrega da rodada que exige um.
+ */
+export function keyframesInSheets(sheets) {
+    const out = {};
+    for (const sheet of sheets) {
+        if (!sheet.body.includes("@keyframes"))
+            continue;
+        const read = readModuleCss(sheet.body);
+        for (const [name, body] of Object.entries(read.keyframes)) {
+            /** A PRIMEIRA declaração vence, como em todo leitor daqui: duas folhas com o mesmo nome é
+             *  theming por área, e escolher a última faria a ordem de caminhada decidir o resultado. */
+            if (out[name])
+                continue;
+            const offsets = keyframeOffsets(body);
+            /** Um nome sem corpo legível viraria uma referência que não anima nada. */
+            if (Object.keys(offsets).length > 0)
+                out[name] = offsets;
+        }
+    }
+    return out;
+}

package/dist/install-marks.js

@@ -115,7 +115,20 @@
  * O índice de componentes é BYTE-IDÊNTICO nos dois caminhos - mesma fonte canônica, mesmos nomes,
  * mesma quantidade (`claude-md.f0.spec.ts`). O corte troca uma frase, nunca o inventário.
  */
-export const MATERIALISER_SINCE = "0.16.269";
+/**
+ * 0.16.269 -> 0.16.270 em 21/08, e a correção é de uma ARMADILHA que vai repetir.
+ *
+ * A marca foi escrita como "0.16.269" porque era o que o `package.json` dizia naquele instante. Só que
+ * o dono PUBLICOU o 0.16.269 antes de o código entrar - o pacote no npm saiu 17:46 e o PR foi mergeado
+ * 18:53. Então a marca apontava para uma versão que existe e NÃO tem a mudança, e o efeito era o pior
+ * possível: `installedBehind("0.16.269", "0.16.270", "0.16.269")` é FALSO, então o cliente que instalou
+ * aquele 0.16.269 nunca seria avisado.
+ *
+ * A REGRA, para não repetir: a marca aponta para a versão que vai ser PUBLICADA COM a mudança, e essa
+ * é sempre o bump deste PR - nunca o número que o `package.json` já carrega, porque alguém pode
+ * publicar no meio.
+ */
+export const MATERIALISER_SINCE = "0.16.270";
 /**
  * A ÚLTIMA VERSÃO EM QUE O QUE O HOOK RODA MUDOU.
  *
@@ -217,7 +230,21 @@ export const CHECKER_SINCE = "0.16.250";
  *               (era 53% no melhor caminho; o derivado dava 38%). Um censo medido antes disto não
  *               tem versão nenhuma - e o mapa de blueprints por versão não tem o que consultar.
  */
-export const READER_SINCE = "0.16.261";
+/**
+ * `0.16.261` -> `0.16.269` em 21/08: os keyframes que a folha GLOBAL dele declara passaram a ser
+ * lidos - ver `global-keyframes.ts`.
+ *
+ * O portão desta marca é o corpus dourado, e ele NÃO cobrou: o censo dos treze apps saiu idêntico,
+ * porque nenhuma das treze fixtures escreve `@keyframes` em folha global. A marca sobe por decisão,
+ * não por vermelho - e o número que justifica está no repo real: 35 dos 84 tokens declarados do
+ * codelevel são `--animate-*`, o censo dele saía com `keyframes: undefined`, e agora sai com 35.
+ *
+ * Sem subir, o `align` nunca diria a quem já importou que vale remedir - que é a única coisa que esta
+ * marca existe para fazer.
+ */
+/** 0.16.269 -> 0.16.270 pelo mesmo motivo do MATERIALISER acima: o 0.16.269 foi publicado sem o
+ *  leitor de keyframes globais, e uma marca que aponta para ele cala o aviso para quem o instalou. */
+export const READER_SINCE = "0.16.270";
 /**
  * O QUE ESTÁ INSTALADO AQUI FICOU PARA TRÁS - e as DUAS condições que fazem isso ser verdade.
  *

package/package.json

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