synthesisui 0.16.215 → 0.16.217

package/dist/guide.js

@@ -1,6 +1,13 @@
 import { nextFontSnippet } from "./fonts.js";
 import { animationShorthand, classifyKeyframe, describeKeyframe, isFullRotation, } from "./motion.js";
 const kebab = (v) => v.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+/**
+ * O NOME CSS DE UMA PROPRIEDADE DO DOCUMENTO - e o hífen do prefixo de fornecedor faz parte dele.
+ *
+ * `WebkitFontSmoothing` é `-webkit-font-smoothing` no CSS, e sem o hífen inicial o agente copia uma
+ * propriedade que não existe. `kebab` sozinho começa a palavra em `webkit`.
+ */
+const cssProp = (v) => (/^[A-Z]/.test(v) ? "-" : "") + kebab(v);
 const list = (items) => items.length ? items.map((i) => `\`${i}\``).join(", ") : "_(none)_";
 const dataAttrs = (variants) => Object.entries(variants).map(([axis, opts]) => `data-${kebab(axis)}="${Object.keys(opts).join("|")}"`);
 // Famílias genéricas do CSS - fallbacks, não webfonts a carregar.
@@ -375,6 +382,66 @@ ${depLines.join("\n")}
         return `- ${usage} - ${INTENT_LINE[intent]} (${describeKeyframe(kf)})`;
     });
     const patternLines = Object.entries(motion.patterns ?? {}).map(([pname, p]) => `- **${pname}** (on ${p.trigger}): ${p.description}`);
+    /**
+     * O QUE ESTE SISTEMA AINDA NÃO DECIDIU - e o agente precisa saber ANTES de compor contra ele.
+     *
+     * Um valor cru que o código dele dá a um papel entra no sistema exato, num degrau colocado por
+     * proximidade na família dele. A cor está garantida; o NOME daquele degrau é uma decisão que
+     * ninguém tomou ainda. Sem esta seção o agente lê o degrau como vocabulário estabelecido e escreve
+     * o próximo componente contra ele - e o retrabalho, quando alguém decidir, é tudo que foi escrito
+     * nesse meio tempo.
+     *
+     * A prosa vem PRONTA do registry (ver `RegistryPayload.pending`): medir aqui seria uma segunda
+     * cópia da regra, do lado que não tem a procedência dos caminhos.
+     */
+    /**
+     * A PÁGINA DELE, DITA AO AGENTE - e sem esta seção a adoção escrevia um registro que ninguém lia.
+     *
+     * O QUÊ: as regras de elemento da folha global dele que ele adotou no sistema - `body { margin: 0 }`,
+     * `a { text-decoration-line: underline }`, `h1 { font-size: {typography.scale.h1} }`.
+     *
+     * POR QUÊ: a oferta que as adota promete, com todas as letras, *"your agent stops guessing at the
+     * page"*. Elas viajam no `design-system.json` desde o primeiro dia e o GUIDE - o arquivo que o
+     * agente é MANDADO ler primeiro - nunca as mencionou. Seis regras adotadas no sistema real em
+     * 12/08, e nenhum agente do mundo as encontraria (medido no repo dele, no `v6/GUIDE.md`).
+     *
+     * O que ele ganha ao ler: a página já tem base, então o próximo componente não redecide `margin`,
+     * `box-sizing` nem a família do heading - e não briga com o que a folha dele já faz.
+     */
+    const pageBase = Object.entries(foundations.base ?? {});
+    const pageBaseSection = pageBase.length === 0
+        ? ""
+        : `
+---
+
+## The page this system sits on
+
+Their global stylesheet already dresses the page before any component runs, and the system carries
+it. **Do not re-declare these, and do not fight them** - compose on top:
+
+${pageBase
+            .map(([element, props]) => `- \`${element}\` - ${Object.entries(props)
+            .map(([prop, at]) => `${cssProp(prop)}: ${at.value}`)
+            .join("; ")}`)
+            .join("\n")}
+
+A value in braces is a token of theirs: it re-themes with the system, so the page follows the same
+edit the components do.
+`;
+    const pending = payload.pending ?? [];
+    const pendingSection = pending.length === 0
+        ? ""
+        : `
+---
+
+## Open in this system (${pending.length}) - decided by you, not by me
+
+${pending.length === 1 ? "One thing in this system carries a name nobody chose" : `${pending.length} things in this system carry names nobody chose`}. ${pending.length === 1 ? "It is" : "They are"} not broken and ${pending.length === 1 ? "does" : "do"} not block you - but treat ${pending.length === 1 ? "it" : "them"} as provisional: prefer a role that is settled when you have the choice, and do not build a new vocabulary on top of ${pending.length === 1 ? "this one" : "these"}.
+
+${pending
+            .map((p) => `- ${p.what}\n  - **Why:** ${p.why}\n  - **Settle it:** ${p.fix}`)
+            .join("\n")}
+`;
     // Engagement blocks (gamification library) - category apart from core components.
     const blockEntries = Object.entries(doc.blocks ?? {});
     const blockLines = blockEntries.map(([bname, recipe]) => componentEntry(bname, recipe));
@@ -624,7 +691,7 @@ ${hasTailwind
   **Motion vocabulary** below; never hand-roll \`@keyframes\` or raw durations.
 - When **creating a new component** the DS does not cover yet: compose it from these semantic
   tokens to inherit the system's identity; do not invent colors/measures outside the scale.
-${keyframeLines.length > 0
+${pageBaseSection}${pendingSection}${keyframeLines.length > 0
         ? `
 ---
 

package/dist/install-marks.js

@@ -54,7 +54,18 @@
  *
  * O resto da pasta vem do servidor e já é coberto pela versão do DS.
  */
-export const MATERIALISER_SINCE = "0.16.204";
+/**
+ * 0.16.204 -> 0.16.216 em 12/08, e a resposta do passo 1 foi SIM pela primeira vez desde que o
+ * portão existe: o `GUIDE.md` que cai na pasta ganhou a seção "Open in this system", com o que o
+ * sistema ainda não decidiu. Um install anterior a esta versão materializa um guia que não diz ao
+ * agente dele quais nomes são provisórios - bytes diferentes, e diferença que muda o que ele lê.
+ *
+ * 0.16.216 -> 0.16.217 no mesmo dia, e SIM de novo: o guia passou a imprimir a PÁGINA que o sistema
+ * carrega - as regras de elemento da folha global dele. Elas viajavam no `design-system.json` desde
+ * sempre e o arquivo que o agente é mandado ler não as citava, então seis regras adotadas no sistema
+ * real eram invisíveis para quem ia escrever a próxima tela.
+ */
+export const MATERIALISER_SINCE = "0.16.217";
 /**
  * A ÚLTIMA VERSÃO EM QUE O QUE O HOOK RODA MUDOU.
  *

package/package.json

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