synthesisui 0.16.78 → 0.16.79

package/dist/anatomy-read.js

@@ -95,7 +95,11 @@ function formOf(node) {
  * `declared` is their own tokens, so a `bg-ocean-500` on a nested part resolves
  * to the name they gave it rather than to a literal.
  */
-export function resolveAnatomy(read, declared, deps) {
+export function resolveAnatomy(read, declared, deps, 
+/** Their name → the slug it reaches in this system. See `RefResolver`. */
+resolve, 
+/** What the component returns, when the skill said and it is not a plain tag. */
+root) {
     const parts = {};
     const composes = [];
     const external = [];
@@ -147,12 +151,22 @@ export function resolveAnatomy(read, declared, deps) {
             // on one would be us claiming styles that belong to somebody else.
             if (FRONTIERS.has(as)) {
                 if (as === "component") {
-                    const ref = String(node.ref ?? "").trim();
-                    if (!ref)
+                    const name = String(node.ref ?? "").trim();
+                    if (!name)
                         continue;
-                    if (!composes.includes(ref))
-                        composes.push(ref);
-                    out.push({ as, ref });
+                    if (!composes.includes(name))
+                        composes.push(name);
+                    /**
+                     * THE CROSSWALK DECIDES WHAT THIS REACHES.
+                     *
+                     * `Tag` is bucketed `nearly` with canonical `badge`; kebab-casing it
+                     * looks for `ds-tag` and finds nothing. Without a resolver we keep the
+                     * kebab, which is what a system generated by us would want anyway.
+                     */
+                    const slug = resolve?.(name) ?? safePartName(name);
+                    out.push(slug && slug !== safePartName(name)
+                        ? { as, ref: slug, refName: name }
+                        : { as, ref: slug || safePartName(name) });
                     continue;
                 }
                 const from = String(node.from ?? "").trim();
@@ -202,13 +216,40 @@ export function resolveAnatomy(read, declared, deps) {
         return out;
     };
     const tree = walk(top, 0);
+    /**
+     * THE ROOT, RESOLVED THE SAME WAY.
+     *
+     * A dotted capitalised name is somebody else's namespace - `Radio.Root`,
+     * `BaseDialog.Root` - so there is nothing of theirs to reach and the honest
+     * answer is to name the library. Anything else is a component of theirs and goes
+     * through the crosswalk exactly like a child frontier does.
+     */
+    let rootOut;
+    const rootRaw = String(root ?? "").trim();
+    if (rootRaw && /^[A-Z]/.test(rootRaw)) {
+        if (rootRaw.includes(".")) {
+            rootOut = { from: rootRaw };
+        }
+        else {
+            const slug = resolve?.(rootRaw) ?? safePartName(rootRaw);
+            if (slug)
+                rootOut = { ref: slug, name: rootRaw };
+        }
+    }
     if (coerced > 0) {
         notes.push(`${coerced} node${coerced === 1 ? "" : "s"} named a form that does not exist - kept, drawn as what ${coerced === 1 ? "it holds" : "they hold"}`);
     }
     if (budget <= 0) {
         notes.push(`the anatomy was longer than ${MAX_NODES} nodes - the rest is layout, and it is not read`);
     }
-    return { parts, tree, composes, external, notes };
+    return {
+        parts,
+        tree,
+        composes,
+        external,
+        notes,
+        ...(rootOut ? { root: rootOut } : {}),
+    };
 }
 /**
  * The OLD flat form, folded into the same result shape.

package/dist/commands/component.js

@@ -5,7 +5,7 @@ import { generateComponentFiles } from "../component-codegen.js";
 import { readProjectConfig, resolveRegistry } from "../config.js";
 import { hasInteractiveTemplate, interactiveTemplate, } from "../interactive-templates.js";
 import { body, section, snippet } from "../output.js";
-import { reactMajorOf, readInstalledConvention } from "../project-facts.js";
+import { findCollision, reactMajorOf, readInstalledConvention, } from "../project-facts.js";
 import { fetchComponent, RegistryError } from "../registry.js";
 /**
  * Writes the shared `cn.ts` next to the components, built from THIS project's
@@ -68,6 +68,43 @@ export async function component(slug, name, opts) {
     const config = await readProjectConfig(root);
     const wantInteractive = opts.interactive && hasInteractiveTemplate(res.name);
     if (!opts.artifactsOnly && config.target === "next") {
+        /**
+         * WE DO NOT TAKE A NAME THEY ARE USING.
+         *
+         * This wrote with a bare `writeFile`, so it overwrote whatever was there - and
+         * a project that already has its own `Button` is the normal case. The
+         * crosswalk makes it sharper: their `ToolbarButton` resolves to `button`, so
+         * asking for one hands back a `Button`, which is a different component.
+         *
+         * Re-materializing something WE generated is almost always what they meant, so
+         * that keeps going. Shadowing a component of theirs stops and asks.
+         */
+        const pascalName = res.name
+            .split(/[^a-zA-Z0-9]+/)
+            .filter(Boolean)
+            .map((p) => p[0].toUpperCase() + p.slice(1))
+            .join("");
+        const clash = await findCollision(root, config.componentsDir, res.name, pascalName);
+        if (!opts.force && (clash.exported || (clash.file && !clash.ours))) {
+            console.log(section("This name is already taken in your project"));
+            if (clash.exported) {
+                console.log(body(`\`${pascalName}\` is already exported from ${clash.exported}.`));
+            }
+            if (clash.file && !clash.ours) {
+                console.log(body(`${clash.file} exists and we did not write it.`));
+            }
+            console.log("");
+            console.log(body("The recipe and the compiled CSS are on disk either way - only the .tsx was not written. Your options:"));
+            console.log("");
+            console.log(snippet([
+                `npx synthesisui component ${slug} ${res.name} --force`,
+                `# or bring it under a name of your own:`,
+                `npx synthesisui component ${slug} ${res.name} --as my-${res.name}`,
+            ]));
+            console.log("");
+            console.log(body("Nothing of yours was touched. Which name it takes is your call, not ours."));
+            return;
+        }
         const compDir = join(root, config.componentsDir, res.name);
         await mkdir(compDir, { recursive: true });
         let filenames;

package/dist/commands/import.js

@@ -1,6 +1,6 @@
 import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { basename, dirname, join, relative } from "node:path";
-import { resolveAnatomy, resolveFlatParts, } from "../anatomy-read.js";
+import { resolveAnatomy, resolveFlatParts, safePartName, } from "../anatomy-read.js";
 import { readCredentials, readToken, resolveRegistry, sameRegistry, } from "../config.js";
 import { findBrokenRefs } from "../doctor/broken-refs.js";
 import { describeClassStyle, detectClassStyle, } from "../doctor/class-style.js";
@@ -924,10 +924,28 @@ async function resolveReadParts(census, root) {
     let edges = 0;
     const libs = new Set();
     const notes = new Set();
+    /**
+     * WHAT A NAME IN THEIR CODE REACHES IN THE SYSTEM - from the crosswalk.
+     *
+     * The census already decided this for every component it read: `Tag` is
+     * `nearly`, canonical `badge`; `ToolbarButton` is `nearly`, canonical `button`;
+     * `Card` `exists` as `card`. The first version of the frontier kebab-cased the
+     * name and looked for `ds-tag`, which does not exist - so a component whose
+     * recipe was sitting right there drew as a grey chip (dono, 01/08).
+     */
+    const crosswalked = new Map();
+    for (const c of census.components ?? []) {
+        if (c.from)
+            continue; // a package's component is not one of theirs
+        const target = c.canonical ?? (c.bucket === "exclusive" ? c.name : null);
+        if (target)
+            crosswalked.set(c.name, safePartName(target));
+    }
+    const resolveRef = (name) => crosswalked.get(name) ?? null;
     for (const [component, entry] of Object.entries(read)) {
         const anatomy = entry?.anatomy;
         const resolved = Array.isArray(anatomy) && anatomy.length > 0
-            ? resolveAnatomy(anatomy, declared, deps)
+            ? resolveAnatomy(anatomy, declared, deps, resolveRef, entry?.root)
             : Array.isArray(entry?.parts) && entry.parts.length > 0
                 ? resolveFlatParts(entry.parts, declared)
                 : null;
@@ -942,6 +960,7 @@ async function resolveReadParts(census, root) {
             ...(resolved.tree.length > 0 ? { tree: resolved.tree } : {}),
             ...(resolved.composes.length > 0 ? { composes: resolved.composes } : {}),
             ...(resolved.external.length > 0 ? { external: resolved.external } : {}),
+            ...(resolved.root ? { root: resolved.root } : {}),
         };
         looks[component] = look
             ? {

package/dist/commands/mcp.js

@@ -65,6 +65,20 @@ const TOOLS = [
         description: "The components this design system defines, with what each is for. Look here BEFORE writing any UI element from scratch - if something covers the purpose, materialize it with add_component instead.",
         inputSchema: { type: "object", properties: {} },
     },
+    {
+        name: "describe_component",
+        description: "Everything the system knows about ONE component: what it is made of, what it composes, WHICH LIBRARIES IT NEEDS, and the rules that govern it. Call this before writing code that uses a component - `list_components` gives you a name and a sentence, and a name does not tell you that the editor needs @tiptap/react or that a card is built out of a metric card.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: {
+                    type: "string",
+                    description: "Component name from list_components.",
+                },
+            },
+            required: ["name"],
+        },
+    },
     {
         name: "add_component",
         description: "Materialize a component from the design system as real typed code in this project, ready to import and extend. Use it yourself - the person who asked for a feature should never have to know component names.",
@@ -191,6 +205,109 @@ async function listComponents(root) {
         ...rows.sort(),
     ].join("\n");
 }
+/**
+ * ONE COMPONENT, IN FULL - the round trip that did not exist.
+ *
+ * `list_components` returns a name and a description, so an agent building with
+ * `ds-text-editor` had no way to know it needs `@tiptap/react` before writing the
+ * first line. The anatomy, the composition chain and the required libraries are all
+ * in the installed contract; nothing was asking for them.
+ *
+ * It is also the confirmation the skill never had. After an import, reading this
+ * back says what the platform UNDERSTOOD - so a reading that came out thin is
+ * visible instead of being discovered later in a preview.
+ */
+async function describeComponent(root, name) {
+    const { documents, requires } = await loadSystem(root);
+    let recipe;
+    for (const doc of documents) {
+        const d = doc;
+        recipe = d.components?.[name] ?? d.blocks?.[name];
+        if (recipe)
+            break;
+    }
+    if (!recipe) {
+        return `This system has no component called "${name}". Run list_components to see what it does have - and if nothing covers what you need, file request_component rather than writing one from scratch.`;
+    }
+    const out = [
+        `${name}${recipe.description ? ` - ${recipe.description}` : ""}`,
+    ];
+    // WHAT IT SITS ON. 17 of 23 components in a real library carry no surface of
+    // their own, because the surface belongs to what they return.
+    const p = recipe.preview;
+    if (p?.rootRef) {
+        out.push("", `Sits on: ${p.rootRef}${p.rootName && p.rootName !== p.rootRef ? ` (your ${p.rootName})` : ""} - its background, border and radius come from there, not from this component.`);
+    }
+    else if (p?.rootFrom) {
+        out.push("", `Sits on: ${p.rootFrom} - a third-party root. Its markup and behaviour are that library's.`);
+    }
+    // WHAT IT IS MADE OF, and where it ends.
+    const composes = [];
+    const libs = [];
+    const shape = [];
+    const walk = (nodes, depth) => {
+        for (const raw of nodes) {
+            const n = raw;
+            const pad = "  ".repeat(depth + 1);
+            if (n.as === "component" && n.ref) {
+                shape.push(`${pad}<${n.ref}>${n.refName && n.refName !== n.ref ? `  (your ${n.refName})` : ""}`);
+                if (!composes.includes(n.ref))
+                    composes.push(n.ref);
+            }
+            else if (n.as === "external" && n.from) {
+                shape.push(`${pad}${n.from}  (third party - not ours to render)`);
+                if (!libs.includes(n.from))
+                    libs.push(n.from);
+            }
+            else {
+                shape.push(`${pad}${n.as}${n.part ? ` .${name}-${n.part}` : ""}`);
+            }
+            if (Array.isArray(n.children))
+                walk(n.children, depth + 1);
+        }
+    };
+    if (Array.isArray(p?.parts) && p.parts.length > 0) {
+        walk(p.parts, 0);
+        out.push("", "Made of:", ...shape);
+    }
+    else if (recipe.parts && Object.keys(recipe.parts).length > 0) {
+        out.push("", `Parts: ${Object.keys(recipe.parts).join(", ")} - compose them inside it.`);
+    }
+    if (composes.length > 0) {
+        out.push("", `Built out of: ${composes.join(", ")}. Change one of those in one place rather than reproducing it here, and call describe_component on it before you do.`);
+    }
+    /**
+     * WHAT IT NEEDS INSTALLED - the whole reason this tool earns its place.
+     *
+     * From `requires.json`, filtered by the stack at install time, so the answer is
+     * about THIS project. Never installs: a dependency has a licence, a bundle cost
+     * and a maintainer attached, so the agent reports and the person decides.
+     */
+    const needed = requires.filter((r) => (r.applies ?? []).includes(name));
+    if (needed.length > 0 || libs.length > 0) {
+        const named = [
+            ...new Set([...needed.map((r) => r.requires), ...libs]),
+        ];
+        out.push("", `Needs installed: ${named.join(", ")}.`, "Check the manifest before you write against it. If it is missing, say so and ASK - do not install it yourself.");
+        for (const r of needed) {
+            if (r.pinned)
+                out.push(`  ${r.requires}  ${r.pinned}`);
+        }
+    }
+    // THE RULES, scoped. A relation names both, which is what an agent needs in
+    // order not to assemble it wrongly.
+    const laws = [...(recipe.usage ?? [])];
+    if (laws.length > 0) {
+        out.push("", "Rules for this component:", ...laws.map((l) => `  ${l}`));
+    }
+    if (needed.length > 0) {
+        out.push(...needed.map((r) => `  ${r.text}`));
+    }
+    if (laws.length === 0 && needed.length === 0) {
+        out.push("", "No rules govern this component yet. Build with it, and if you find yourself working around it, file request_component with the reasoning.");
+    }
+    return out.join("\n");
+}
 async function addComponent(root, name) {
     const { table } = await loadSystem(root);
     if (!table.slug)
@@ -207,6 +324,8 @@ async function callTool(root, name, args) {
             return text(await findToken(root, String(args.value ?? "")));
         case "list_components":
             return text(await listComponents(root));
+        case "describe_component":
+            return text(await describeComponent(root, String(args.name ?? "")));
         case "add_component":
             return text(await addComponent(root, String(args.name ?? "")));
         case "request_component": {

package/dist/component-codegen.js

@@ -207,7 +207,19 @@ const colorKey = (v) => {
         return `series-${series}`;
     return null;
 };
-/** "{typography.scale.sm.fontSize}" → "sm" (the --text-<key> utility). */
+/**
+ * "{typography.scale.sm.fontSize}" → "sm" (the --text-<key> utility).
+ *
+ * A STEP maps to a utility; a ROLE deliberately does not.
+ *
+ * `typography.scale.<step>` names a step the system actually has, and a step it
+ * got from THEIR declaration is bridged into Tailwind's namespace - so `text-h1`
+ * exists and is the prettier output. `typography.role.<slot>` is one of our seven
+ * slots, and the bridge only ever claims a name they gave us: `text-base` may not
+ * exist in an imported system at all. So a role falls through to
+ * `var(--ds-typography-role-base-font-size)`, which is always emitted and can
+ * never dangle.
+ */
 const scaleKey = (v) => {
     const m = v.match(/^\{typography\.scale\.([a-zA-Z0-9-]+)\.fontSize\}$/);
     return m ? kebab(m[1]) : null;
@@ -640,11 +652,13 @@ function partTagFor(part, form) {
         voidEl: Boolean(mapped.voidEl),
     };
 }
-function emitCssMode(slug, name, recipe, version, props, convention) {
+function emitCssMode(slug, name, recipe, version, props, convention, 
+/** The name it takes in THEIR project. The class stays the system's. */
+localName = name) {
     const { tag, attrs, voidEl } = elementFor(name, recipe);
     const el = asElement(tag, attrs, voidEl);
     const axes = axesOf(recipe.variants);
-    const comp = pascal(name);
+    const comp = pascal(localName);
     const propNames = axes.map((a) => a.prop);
     const tree = recipe.preview?.parts ?? [];
     // With a shape the root RENDERS its children, so it needs `children` in the
@@ -713,7 +727,7 @@ ${dataAttrLines(partAxes)}${partAxes.length ? "\n" : ""}      {...props}
     });
     const needsElementType = el.offersAs || Object.keys(recipe.parts ?? {}).length > 0;
     return `${header(slug, name, version, "css")}
-import "./${name}.css";
+import "./${localName}.css";
 
 import type { ${needsElementType ? `ElementType, ${props}` : props} } from "react";
 
@@ -727,11 +741,13 @@ ${rootJsx}
 }
 ${parts.filter(Boolean).join("\n")}`;
 }
-function emitTailwindMode(slug, name, recipe, version, props) {
+function emitTailwindMode(slug, name, recipe, version, props, 
+/** The name it takes in THEIR project. The utilities stay the system's. */
+localName = name) {
     const { tag, attrs, voidEl } = elementFor(name, recipe);
     const el = asElement(tag, attrs, voidEl);
     const axes = axesOf(recipe.variants);
-    const comp = pascal(name);
+    const comp = pascal(localName);
     const variantConsts = axes
         .filter((a) => !a.boolean)
         .map((a) => {
@@ -878,27 +894,37 @@ reactMajor = null,
  * every caller that predates the convention being the user's - and getting this
  * wrong shipped a component wearing classes its own stylesheet never emits.
  */
-convention = DEFAULT_CONVENTION) {
-    const comp = pascal(name);
+convention = DEFAULT_CONVENTION, 
+/**
+ * THE NAME IT TAKES IN THEIR PROJECT, when it cannot take its own.
+ *
+ * A project that already exports `Button` should not have to give the name up to
+ * install ours - we adapt to what they built. So the FILE and the EXPORT can be
+ * renamed while the CLASS stays the design system's: the recipe compiles
+ * `.ds-button`, and a `<MySystemButton>` wearing it is styled correctly and
+ * shadows nothing of theirs.
+ *
+ * Absent means the component keeps its own name, which is every caller today.
+ */
+localName = name) {
     const files = [];
     const props = propsTypeName(reactMajor);
     if (styles === "css") {
         files.push({
-            filename: `${name}.tsx`,
-            code: `${emitCssMode(slug, name, recipe, version, props, convention)}\n`,
+            filename: `${localName}.tsx`,
+            code: `${emitCssMode(slug, name, recipe, version, props, convention, localName)}\n`,
         });
-        files.push({ filename: `${name}.css`, code: `${css}\n` });
+        files.push({ filename: `${localName}.css`, code: `${css}\n` });
     }
     else {
         files.push({
-            filename: `${name}.tsx`,
-            code: `${emitTailwindMode(slug, name, recipe, version, props)}\n`,
+            filename: `${localName}.tsx`,
+            code: `${emitTailwindMode(slug, name, recipe, version, props, localName)}\n`,
         });
     }
     files.push({
         filename: "index.ts",
-        code: `export * from "./${name}";\n`,
+        code: `export * from "./${localName}";\n`,
     });
-    void comp;
     return files;
 }

package/dist/project-facts.js

@@ -13,8 +13,8 @@
  * handed somebody a React component wearing classes their own stylesheet never
  * emits. It renders completely unstyled, and nothing anywhere reports a problem.
  */
-import { readFile } from "node:fs/promises";
-import { join } from "node:path";
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative } from "node:path";
 import { DEFAULT_CONVENTION, } from "./component-codegen.js";
 /**
  * Which React the consumer is on, for the ref-carrying prop type.
@@ -38,6 +38,62 @@ export async function reactMajorOf(root) {
         return null;
     }
 }
+export async function findCollision(root, componentsDir, name, pascal) {
+    const target = join(root, componentsDir, name, `${name}.tsx`);
+    const head = await readFile(target, "utf8")
+        .then((t) => t.slice(0, 300))
+        .catch(() => null);
+    const ours = head?.includes("Generated by SynthesisUI") ?? false;
+    /**
+     * Their own export of that name, searched where a component library lives.
+     *
+     * Deliberately shallow: `src`, `app`, `components`, `packages` and the
+     * configured folder, skipping anything generated. A deep walk of a monorepo to
+     * answer one question is not worth the seconds.
+     */
+    const pattern = new RegExp(`export\\s+(?:default\\s+)?(?:function|const|class)\\s+${pascal}\\b`);
+    const roots = [
+        componentsDir,
+        "src/components",
+        "components",
+        "src/ui",
+        "packages",
+    ];
+    let exported = null;
+    for (const rel of roots) {
+        if (exported)
+            break;
+        for await (const file of walkShallow(join(root, rel), 3)) {
+            if (!/\.(tsx|jsx|ts)$/.test(file))
+                continue;
+            if (file === target)
+                continue;
+            const source = await readFile(file, "utf8").catch(() => "");
+            if (source.includes("Generated by SynthesisUI"))
+                continue;
+            if (pattern.test(source)) {
+                exported = relative(root, file);
+                break;
+            }
+        }
+    }
+    return { file: head == null ? null : relative(root, target), exported, ours };
+}
+/** Files under `dir`, at most `depth` levels down, skipping the usual noise. */
+async function* walkShallow(dir, depth) {
+    if (depth < 0)
+        return;
+    const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+        if (entry.name.startsWith(".") || entry.name === "node_modules")
+            continue;
+        const full = join(dir, entry.name);
+        if (entry.isDirectory())
+            yield* walkShallow(full, depth - 1);
+        else
+            yield full;
+    }
+}
 /** The pinned version of an installed system, from its `.lock`. */
 async function pinnedVersion(dir) {
     const raw = await readFile(join(dir, ".lock"), "utf8").catch(() => "");

package/dist/skill-import.js

@@ -133,6 +133,7 @@ Open the project and answer the questions below. Then add a \`reading\` object t
   "themes": { "default": "dark", "has": ["dark"] },
   "roles": { "canvas": "#050505", "foreground": "#f9fafb", "primary": "#4A90E2" },
   "fonts": { "display": "Inter", "body": "Inter" },
+  "typeRoles": { "base": "body-m", "display": "h1", "xs": "caption" },
   "concept": "one paragraph on what this product is",
   "rules": [
     {
@@ -149,6 +150,13 @@ Open the project and answer the questions below. Then add a \`reading\` object t
       "kind": "limit",
       "files": 1,
       "evidence": "one dashboard page; may just be how it happened"
+    },
+    {
+      "text": "TextEditor's editable region is <EditorContent> - never render children into it directly",
+      "applies": ["TextEditor"],
+      "kind": "implementation",
+      "fact": true,
+      "evidence": "read in TextEditor itself: useEditor() feeds a single <EditorContent>"
     }
   ],
   "components": {
@@ -167,6 +175,7 @@ Open the project and answer the questions below. Then add a \`reading\` object t
       ]
     },
     "ArticleCard": {
+      "root": "Card",
       "anatomy": [
         { "as": "image", "name": "cover", "classes": "aspect-video w-full rounded-t-lg" },
         { "as": "heading", "name": "title", "classes": "text-lg font-semibold" },
@@ -184,7 +193,12 @@ Open the project and answer the questions below. Then add a \`reading\` object t
     },
     "TextEditor": {
       "anatomy": [
-        { "as": "row", "name": "toolbar", "classes": "flex gap-1 border-b p-2" },
+        {
+          "as": "row",
+          "name": "toolbar",
+          "classes": "flex gap-1 border-b p-2",
+          "children": [{ "as": "component", "ref": "ToolbarButton" }]
+        },
         { "as": "external", "from": "@tiptap/react" }
       ]
     }
@@ -221,6 +235,26 @@ about which one is the page. Read a screen and see.
 **\`fonts\` and \`concept\`** - the voice, and one paragraph on what this product is. The concept
 feeds every recommendation downstream, so a real one beats a generic one by a wide margin.
 
+**\`typeRoles\` - which of THEIR type steps plays each of our seven slots.**
+
+Their scale arrives under their own names now - \`h1\`, \`body-m\`, \`caption\`, \`overline\` - read
+straight off their \`--text-*\` declarations. What arithmetic cannot know is which of those steps
+is *body copy* and which is *the display size*, and our own components ask for it by slot:
+
+\`\`\`json
+"typeRoles": {
+  "xs": "caption", "sm": "body-s", "base": "body-m", "lg": "body-l",
+  "xl": "h3", "2xl": "h2", "display": "h1"
+}
+\`\`\`
+
+Leave it out and we pick by size, which is usually right and occasionally silly - a project whose
+\`overline\` is tiny and whose \`caption\` is tinier gets them the wrong way round. One line from you
+fixes it, and a person can correct it later in the studio either way.
+
+**Do not rename their steps to match ours.** \`h1\` stays \`h1\`. The whole point is that editing
+\`body-m\` in the studio moves the text in their app.
+
 **\`rules\` - how this company BUILDS, which is half of what they actually made.**
 
 A design system that arrives as tokens and recipes is only the vocabulary. The other half is the
@@ -258,12 +292,39 @@ Use it only when the rule genuinely depends on the environment. Most rules do no
 a Sidebar loose"* is true about their design regardless of framework, and pinning it to \`next\`
 would quietly drop it the day they add a second app.
 
-**Report \`files\` honestly - it decides whether the rule governs.** Three or more files is a
-habit and the rule arrives active; one file is a coincidence and it arrives as a candidate,
+**Report \`files\` honestly - it decides whether an OBSERVED rule governs.** Three or more files
+is a habit and the rule arrives active; one file is a coincidence and it arrives as a candidate,
 inactive, waiting for the person to promote it. You do not make that call; you report the
 evidence and a threshold makes it. So a pattern you saw once should say \`"files": 1\` even when
 you are confident - being wrong about a law is worse than being slow about one.
 
+**\`fact: true\` - for a rule you read in the DEFINITION, where counting is the wrong question.**
+
+Three of these were reported as \`files: 1\` and arrived inactive, which was correct arithmetic on
+the wrong kind of claim (dono, 01/08):
+
+\`\`\`
+the editable region is <EditorContent>
+toolbar actions go through editor.chain().focus()
+extensions are configured at construction
+\`\`\`
+
+None of those is a coincidence waiting for a second sighting. They are how the component IS
+built, read off its own source, and they are true the moment somebody wrote it. Counting how many
+files agree would leave every construction law in the codebase inactive forever.
+
+So the test is **where you read it**, not how sure you feel:
+
+\`\`\`
+fact: true    you read it inside the component's own definition - its imports, its
+              JSX, how its state is wired. True by construction.
+files: N      you inferred it from how the component is USED across the project.
+              An observation, and the count is what makes it a habit.
+\`\`\`
+
+A rule can carry \`fact\` OR \`files\`, never both. If you find yourself wanting both, it is an
+observation - use \`files\`.
+
 **Write \`evidence\` as what you actually saw.** "All three app shells wrap them; none renders
 them loose" lets somebody disagree with a fact. "Best practice" lets them disagree only with
 you.
@@ -302,6 +363,41 @@ an EXTERNAL  a third-party library       we do not have it and never will → bl
 component or a library, stop there, and record the edge. That is why no parameter tells you how
 deep to go: a \`Divider\` is one node deep and a dashboard shell is five, and both are complete.
 
+**You decide the depth, and nothing downstream caps it.** The platform follows a
+\`component\` edge into that component's own anatomy, and then into ITS edges, as far as the chain
+goes - \`Chat → Message → TypingIndicator\` renders all three. So a frontier is not a dead end you
+are apologising for; it is how the chain gets walked. Record the edge and stop, and the whole
+depth appears anyway.
+
+### The ROOT is a frontier too
+
+\`\`\`json
+"components": {
+  "ArticleCard": {
+    "root": "Card",
+    "anatomy": [ … ]
+  },
+  "Modal": {
+    "root": "BaseDialog.Root",
+    "anatomy": [ … ]
+  }
+}
+\`\`\`
+
+**Say what the component RETURNS when it is not a plain tag.** Measured on a real library
+(dono, 01/08): 14 of 23 components return one of their own - \`ArticleCard\` returns a \`<Card>\`,
+\`Button\` and \`Text\` return a \`<Component>\` - and 17 of 23 have no style of their own at all,
+because the surface belongs to the root.
+
+Without \`root\`, an \`ArticleCard\` previewed as floating text: the background, the border, the
+radius and the padding had nowhere to come from. With it, the card wears \`Card\`'s recipe as its
+shell and its own parts inside.
+
+- **their component** - the name, as their code spells it: \`"root": "Card"\`
+- **a library** - the dotted namespace, verbatim: \`"root": "Radio.Root"\`,
+  \`"root": "BaseDialog.Root"\`, \`"root": "Popover.Root"\`
+- **a plain tag** - leave it out. \`<div>\`, \`<td>\`, \`<button>\` are not frontiers.
+
 ### The nine forms
 
 \`as\` says what a node IS, and the renderer draws that. Nothing else is accepted:
@@ -379,9 +475,15 @@ Send an anatomy for **every component with visible structure**, which is nearly
 \`CircularProgress\` has a track and a fill. Sending none is right only for something genuinely
 undivided - a \`Divider\`, a \`Spacer\`.
 
-Three to six nodes is a recognisable component. Twelve is a transcription of their DOM, and
-nobody needs the layout divs - collapse a wrapper whose only job is \`flex\` into the \`row\` it
-already is.
+**There is no node budget, and the one I gave you was wrong.** "Three to six nodes is a
+recognisable component" cost a real \`ArticleCard\` most of itself: it has a carousel with arrows,
+three image buttons, a source chip, a refresh, a rich body, a source line and a "Similar
+published content" region with two selects and two buttons - about fourteen regions - and the
+reading came back with six because the guidance said so (dono, 01/08).
+
+**One node per region a person can point at.** If they can say "that part", it is a node. What
+you still collapse is a wrapper whose only job is \`flex\` - fold it into the \`row\` it already is,
+because that is not a region, it is plumbing.
 
 The cost of sending none is not neutral. A component with no anatomy previews as a grey box with
 a sentence in it, or - if its kind is \`indicator\` - as a small blank shape. A component with a

package/package.json

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