synthesisui 0.16.77 → 0.16.79

package/dist/project-facts.js

@@ -0,0 +1,145 @@
+/**
+ * TWO FACTS ABOUT THE PROJECT THE CODEGEN CANNOT GUESS.
+ *
+ * Both were being read by exactly one of the four commands that generate code, so
+ * the other three emitted something subtly wrong and nothing failed:
+ *
+ *   the React major     decides whether a component can take a `ref`
+ *   the class convention decides whether its classes exist at all
+ *
+ * The second is the serious one. A compiled class attaches to THEIR markup, so an
+ * imported system keeps its own spelling - `.metric-card__title`, not
+ * `.ds-metric-card-title`. The codegen hardcoded ours, so `synthesisui component`
+ * handed somebody a React component wearing classes their own stylesheet never
+ * emits. It renders completely unstyled, and nothing anywhere reports a problem.
+ */
+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.
+ *
+ * From 19 a `ref` is an ordinary prop; before it a function component needs
+ * `forwardRef`. Guessing high on an older project would emit a type that accepts a
+ * ref React then silently drops, so anything unreadable falls back to the
+ * ref-less type.
+ */
+export async function reactMajorOf(root) {
+    const raw = await readFile(join(root, "package.json"), "utf8").catch(() => "");
+    if (!raw)
+        return null;
+    try {
+        const pkg = JSON.parse(raw);
+        const spec = pkg.dependencies?.react ?? pkg.devDependencies?.react;
+        const major = /(\d+)/.exec(spec ?? "")?.[1];
+        return major ? Number(major) : null;
+    }
+    catch {
+        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(() => "");
+    if (!raw)
+        return null;
+    try {
+        const lock = JSON.parse(raw);
+        return typeof lock.version === "number" ? lock.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * HOW THE INSTALLED SYSTEM SPELLS A CLASS, read off the document on disk.
+ *
+ * The document is the same one the compiled CSS came from, so this can never
+ * disagree with the stylesheet sitting next to it - which is the property that
+ * matters. A response field would be fresher, and a caller that has one should
+ * prefer it; this is what every other caller can rely on.
+ *
+ * Absent, unreadable or never declared all mean OURS, to the character, so no
+ * project that exists has to change.
+ */
+export async function readInstalledConvention(root, slug) {
+    const dir = join(root, "_synthesisui", "ds", slug);
+    const version = await pinnedVersion(dir);
+    const raw = version
+        ? await readFile(join(dir, `v${version}`, "design-system.json"), "utf8").catch(() => "")
+        : "";
+    if (!raw)
+        return DEFAULT_CONVENTION;
+    try {
+        const doc = JSON.parse(raw);
+        const declared = doc.meta?.classNames;
+        if (!declared ||
+            typeof declared.prefix !== "string" ||
+            typeof declared.partSeparator !== "string") {
+            return DEFAULT_CONVENTION;
+        }
+        return {
+            prefix: declared.prefix,
+            partSeparator: declared.partSeparator,
+        };
+    }
+    catch {
+        return DEFAULT_CONVENTION;
+    }
+}

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,14 +150,56 @@ 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": {
     "MetricCard": {
-      "parts": [
-        { "name": "icon", "classes": "size-8 text-ocean-500" },
-        { "name": "label", "classes": "text-xs uppercase text-lightgray-500" },
-        { "name": "value", "classes": "text-2xl font-bold" }
+      "anatomy": [
+        { "as": "icon", "name": "icon", "classes": "size-8 text-ocean-500" },
+        {
+          "as": "stack",
+          "name": "body",
+          "classes": "flex flex-col gap-1",
+          "children": [
+            { "as": "text", "name": "label", "classes": "text-xs uppercase text-lightgray-500" },
+            { "as": "heading", "name": "value", "classes": "text-2xl font-bold" }
+          ]
+        }
+      ]
+    },
+    "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" },
+        { "as": "component", "ref": "TextEditor" },
+        {
+          "as": "row",
+          "name": "footer",
+          "classes": "flex items-center gap-2 border-t p-3",
+          "children": [
+            { "as": "button", "name": "publish", "classes": "btn btn-primary" },
+            { "as": "button", "name": "discard", "classes": "btn btn-ghost" }
+          ]
+        }
+      ]
+    },
+    "TextEditor": {
+      "anatomy": [
+        {
+          "as": "row",
+          "name": "toolbar",
+          "classes": "flex gap-1 border-b p-2",
+          "children": [{ "as": "component", "ref": "ToolbarButton" }]
+        },
+        { "as": "external", "from": "@tiptap/react" }
       ]
     }
   },
@@ -192,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
@@ -229,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.
@@ -250,40 +340,160 @@ Things worth looking for, none of them guessable from tokens:
 If you cannot say where a rule came from, do not send it. An invented law is worse than a
 missing one, because it will be obeyed.
 
-**\`components[Name].parts\` - what each component is MADE OF.** This is the field that decides
-whether a component previews as itself or as a grey box with a sentence in it, and only you can
-fill it.
+**\`components[Name].anatomy\` - what each component is MADE OF, and in what shape.** This is the
+field that decides whether a component previews as itself or as a grey box with a sentence in it,
+and only you can fill it.
 
 The census reads the ROOT element's classes and stops there, on purpose: descending a fixed
-number of levels picks a layout wrapper as often as a semantic part. **You decide how far down a
-part lives**, because you read the component. Send a name and the classes on it; the CLI turns
-those classes into declarations and the platform turns declarations into roles.
+number of levels picks a layout wrapper as often as a semantic part. **You read the component, so
+you decide the shape.** Send a tree; the CLI turns the classes into declarations and the platform
+turns declarations into roles.
+
+### The three frontiers
+
+Every node you send is one of three things, and knowing which is the whole job:
+
+\`\`\`
+a PART       an element of theirs        it has styles, and we draw it
+a COMPONENT  a component of theirs       it has a recipe of its own → named block + a RULE
+an EXTERNAL  a third-party library       we do not have it and never will → block + rules
+\`\`\`
+
+**Depth is not a number, it is where the frontier sits.** Descend until you meet another
+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.
 
-**The name is load-bearing, not a label.** The renderer infers a part's role from it:
+**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.
 
-- \`root\`, \`wrapper\`, \`container\`, \`base\`, \`content\` - the element itself, and **skipped**. Do not
-  send these; their styles already sit on the component.
-- anything matching \`icon\`, \`dot\`, \`indicator\`, \`bar\`, \`avatar\`, \`media\`, \`swatch\` - renders as a
-  bare span, sized and coloured by its own styles
-- anything matching \`button\`, \`action\`, \`cta\` - renders as a real button carrying the label
-- everything else - carries text
+### The ROOT is a frontier too
 
-So a part named \`div2\` previews as a text node reading "Div2". Name what it IS: \`label\`, \`value\`,
-\`delta\`, \`icon\`, \`action\`, \`title\`, \`meta\`.
+\`\`\`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:
+
+\`\`\`
+image     a picture region: cover, thumbnail, media
+heading   the title line
+text      body copy, a label, a value
+button    an action
+field     an input somebody types into
+icon      a glyph, or a bare shape with no text
+row       arranges its children ACROSS
+stack     arranges its children DOWN
+component their component  → needs "ref": the name as their code spells it
+external  a library        → needs "from": the package name
+\`\`\`
+
+Only \`row\` and \`stack\` take \`children\`. Everything else is a leaf.
+
+**\`name\` is the part name**, and it is what carries the styles - flat, lowercase, kebab. Never
+nested: \`"actions.generate"\` compiles to two CSS classes and is invalid, so name it
+\`"generate-action"\`. Name what it IS - \`label\`, \`value\`, \`delta\`, \`cover\`, \`toolbar\` - because the
+name becomes a class in their stylesheet and \`div2\` is a name somebody has to live with.
+
+\`root\`, \`wrapper\`, \`container\`, \`base\` and \`content\` are the element itself: **do not send them as
+nodes.** Their styles already sit on the component, and a node for them draws a box inside its own
+box.
+
+A node with no \`classes\` is fine - it still carries structure, which is most of the value. A
+\`component\` or \`external\` node takes no \`name\` and no \`classes\`: the styles there are not theirs
+to hold.
 
-Send them **in the order they appear**, because that is the order they render. Three or four
-named parts is a recognisable component; twelve is a transcription of their DOM, and nobody
-needs the layout divs.
+### A component of theirs is a NAMED BLOCK, not an expansion
 
-**Send parts for every component that has visible structure**, which is nearly all of them. A
+When you hit \`<TextEditor>\` inside \`<ArticleCard>\`, send
+\`{ "as": "component", "ref": "TextEditor" }\` and **stop**. Do not inline what TextEditor is made
+of. It previews as a block carrying its name, and it becomes a **rule** - \`ArticleCard\` +
+\`TextEditor\`, a relation, which is the one thing a flat list of prose could never say.
+
+That edge is a **fact, not a habit**: you saw it in the definition, so it is true once and for
+all, and it arrives active without waiting for a third sighting.
+
+Two things that are NOT edges, and sending them as such would be wrong:
+
+- \`motion.div\`, \`Dialog.Root\`, \`Radio.Item\` - a library's namespace, not a component of theirs
+- an HTML element with a capital in a variable name
+
+If the component came from a package, it is \`external\`, not \`component\`.
+
+### An external dependency does not render, and that is the answer
+
+A \`TextEditor\` built on tiptap cannot be previewed: the editable region is tiptap's, and drawing
+a fake one would be inventing. So it previews as a block naming the package, and the value moves
+into the **rules** - which is where an agent will read it anyway.
+
+A library is never one rule, it is a family, and you are reading the file so you can see all of
+them. Send them as normal \`rules\` with \`applies: ["TextEditor"]\` and
+\`kind: "implementation"\`:
+
+\`\`\`
+requires @tiptap/react
+the editable region is <EditorContent> - never render children into it directly
+toolbar buttons go through editor.chain().focus()
+extensions are configured at construction, not toggled later
+\`\`\`
+
+**Name the package in the rule; leave the version to the evidence.** The CLI reads the version out
+of their manifest and attaches it (\`"^2.1.0 in packages/ui"\`), so the rule does not go stale the
+day they upgrade and the information is not lost either.
+
+### How much to send
+
+Send an anatomy for **every component with visible structure**, which is nearly all of them. A
 \`Chat\` has a message list and a composer; a \`MetricCard\` has a label and a value; a
-\`CircularProgress\` has a track and a fill. Sending none is the right answer only for something
-genuinely undivided - a \`Divider\`, a \`Spacer\`.
+\`CircularProgress\` has a track and a fill. Sending none is right only for something genuinely
+undivided - a \`Divider\`, a \`Spacer\`.
+
+**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
+real tree previews as itself, and its spec view shows what the system understood. That is the
+whole reason this field exists, and skipping it quietly is how a real library came back looking
+empty (dono, 01/08).
 
-The cost of sending none is not neutral. A component with no parts previews as a grey box with a
-sentence in it, or - if its anatomy is \`indicator\` - as a small blank shape. A component with
-three named parts previews as itself. That difference is the whole reason this field exists, and
-skipping it quietly is how a real library came back looking empty (dono, 01/08).
+The older flat form - \`"parts": [{ "name": "label", "classes": "..." }]\` - still works and still
+styles correctly. It just carries no shape, so the preview lays the parts out in a row and the
+spec view has no nesting to draw.
 
 ### 3. Walk them through the decisions, one at a time
 
@@ -411,10 +621,15 @@ proposal. Say all of this in your own words - do not just print the link:
 
 - the scheme it opens in, and whether a second one was built
 - their ramps under their own family names
-- their exclusive components as contracts - **axes declared, every style block empty.** Say
-  this out loud, because a component list full of blank recipes looks like a failure until
-  someone explains it was deliberate. The platform shows them as *Not written yet*, not as a
+- their exclusive components as contracts - **the axes their types declare, the look transcribed
+  out of their own class names where it was readable, and the anatomy you sent.** Say what is
+  still empty out loud, because a half-written recipe looks like a failure until someone explains
+  which half was deliberate: nothing was invented, so a component whose classes named no token
+  arrives with structure and no colour. The platform shows that as *Not written yet*, not as a
   zero.
+- **the shape of each component**, if you sent one: its parts nested as they nest in their code,
+  the components of theirs it composes, and the libraries it needs. Each edge is also a rule now,
+  which is what makes it survive being looked at once.
 
 **What is waiting in v2**, which only they can approve: near-duplicate colours collapsed,
 unnamed heavy hitters given a place. Point at the link the CLI printed and name the two or
@@ -444,8 +659,10 @@ The user should end up with a system that reads like theirs and not like ours:
 - **their names travel** - \`vivid-pink\`, \`darkgray-900\`, whatever they called it
 - **their default face** - a dark product opens dark
 - **no borrowed colour** - if it is in the system, it is in their code
-- **their exclusive components arrive as contracts** - axes declared, every style block empty,
-  because a contract says what may vary and a recipe would be us redesigning their component
+- **their exclusive components arrive as contracts** - the axes declared, the look transcribed and
+  never invented, and the anatomy read out of their own JSX
+- **a component previews as itself** - an \`ArticleCard\` shows a cover, a title and a footer of
+  buttons, and says out loud that the editor in the middle is their \`TextEditor\` on tiptap
 - **the duplicates are named out loud** - three components that all read as a badge, a brand
   colour painted 275 times with no token
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synthesisui",
-  "version": "0.16.77",
+  "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": {