synthesisui 0.16.96 → 0.16.97

package/dist/anatomy-read.js

@@ -96,6 +96,30 @@ 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.
  */
+/**
+ * WHAT THE PARENT PAINTS ON A FRONTIER, kept as written.
+ *
+ * A `component` or `external` node names another component and stops - and what
+ * the parent adds at the call site is the PARENT's decision, which had nowhere
+ * to go. Measured (not-expressed.md, dono, 01/08): `MetricCard` composes
+ * `<Card className="flex-1 dark:bg-darkgray-300">` and the dark override was
+ * lost, so the preview drew the wrong dark; `Paginate` lost a `min-w-[120px]`
+ * floor on both its buttons.
+ *
+ * Kept as the raw string rather than transcribed: this is an override on top of
+ * a recipe we do not own, and the renderer applies it as a class. Reading it into
+ * declarations would mean deciding which of the two wins, which is the compiler's
+ * job and not this module's.
+ */
+function frontierClasses(node, sketch) {
+    const raw = typeof node.classes === "string"
+        ? node.classes
+        : typeof node.at === "number"
+            ? sketch?.[node.at]?.classes
+            : undefined;
+    const trimmed = raw?.trim();
+    return trimmed ? { classes: trimmed } : {};
+}
 export function resolveAnatomy(read, declared, deps, 
 /** Their name → the slug it reaches in this system. See `RefResolver`. */
 resolve, 
@@ -168,9 +192,12 @@ sketch) {
                      * 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) });
+                    out.push({
+                        as,
+                        ref: slug || safePartName(name),
+                        ...(slug && slug !== safePartName(name) ? { refName: name } : {}),
+                        ...frontierClasses(node, sketch),
+                    });
                     continue;
                 }
                 const from = String(node.from ?? "").trim();
@@ -179,7 +206,12 @@ sketch) {
                 const version = deps?.[from];
                 if (!external.some((e) => e.from === from))
                     external.push({ from, version });
-                out.push(version ? { as, from, version } : { as, from });
+                out.push({
+                    as,
+                    from,
+                    ...(version ? { version } : {}),
+                    ...frontierClasses(node, sketch),
+                });
                 continue;
             }
             const node_ = { as };

package/dist/commands/import.js

@@ -409,11 +409,16 @@ export async function takeCensus(root, opts) {
                 for (const extra of found.slice(1)) {
                     const et = transcribe(rootClasses(src, extra.name), declaredValues);
                     const etag = rootTag(src, extra.name);
+                    // ITS OWN MARKUP, sliced at the definition boundary - the whole file's
+                    // sketch belonged to the first component and the second read an empty
+                    // one (not-expressed.md, dono, 01/08).
+                    const esketch = sketchOf(src, extra.name);
                     const esize = Object.keys(et.base).length +
                         Object.keys(et.dark).length +
                         Object.keys(et.states).length;
-                    if (esize > 0 || etag) {
+                    if (esize > 0 || etag || esketch.length > 0) {
                         looks[extra.name] = {
+                            ...(esketch.length > 0 ? { sketch: esketch } : {}),
                             ...et,
                             ...(etag ? { rootTag: etag } : {}),
                         };
@@ -510,7 +515,7 @@ export async function takeCensus(root, opts) {
                  * and a file read whose content is here is a pipeline optimization failure -
                  * the owner's rule, adopted verbatim (dono, 01/08).
                  */
-                const sketch = sketchOf(src);
+                const sketch = sketchOf(src, found[0].name);
                 if (size > 0 || tag) {
                     looks[found[0].name] = {
                         ...(sketch.length > 0 ? { sketch } : {}),

package/dist/commands/mcp.js

@@ -368,10 +368,90 @@ async function validateRecipe(name, recipe) {
  * what would NOT survive. A list of 30 "this one is fine" lines is a wall the
  * reader has to skim to find the two that matter.
  */
-async function validateRecipes(entries) {
+/**
+ * RESOLVE `at` BEFORE VALIDATING - the validator never sees the census.
+ *
+ * A node styled by `at` carries no `classes`, so it looks EMPTY to the validator
+ * and complete to the importer: four recipes came back BELOW THE FLOOR on a real
+ * run and all four were whole, because their pixels live in parts the sketch
+ * holds and the validator could not reach (not-expressed.md, dono, 01/08). The
+ * verdict was a false accusation about our own optimisation.
+ *
+ * This side HAS the census - the same file the lock and the sketch come from - so
+ * the index is resolved here, once, and the validator judges the recipe somebody
+ * is actually about to send. `classes` already present wins, exactly as the
+ * importer resolves it.
+ */
+async function resolveAtNodes(root, entries) {
+    let looks = {};
+    try {
+        const raw = await readFile(join(root, "_synthesisui", "census.json"), "utf8");
+        looks = JSON.parse(raw).looks ?? {};
+    }
+    catch {
+        // No census: nothing to resolve, and validating the recipe as sent is still
+        // better than refusing to validate at all.
+        return entries;
+    }
+    /** Their spelling → the sketch, matched the way the contract kebabs a name. */
+    const sketchFor = (name) => {
+        if (looks[name]?.sketch)
+            return looks[name].sketch;
+        const slug = name.replace(/[^a-z0-9]/gi, "").toLowerCase();
+        for (const [theirs, look] of Object.entries(looks)) {
+            if (theirs.replace(/[^a-z0-9]/gi, "").toLowerCase() === slug)
+                return look.sketch;
+        }
+        return undefined;
+    };
+    return entries.map((entry) => {
+        const sketch = sketchFor(String(entry.name ?? ""));
+        if (!sketch)
+            return entry;
+        const walk = (nodes) => {
+            if (!Array.isArray(nodes))
+                return nodes;
+            return nodes.map((raw) => {
+                const node = raw;
+                const at = typeof node.at === "number" ? node.at : null;
+                const classes = typeof node.classes === "string"
+                    ? node.classes
+                    : at != null
+                        ? sketch[at]?.classes
+                        : undefined;
+                return {
+                    ...node,
+                    ...(classes ? { classes } : {}),
+                    ...(node.children ? { children: walk(node.children) } : {}),
+                };
+            });
+        };
+        const recipe = entry.recipe;
+        if (!recipe)
+            return entry;
+        const anatomy = recipe.anatomy ??
+            recipe.preview?.parts;
+        if (!Array.isArray(anatomy))
+            return entry;
+        return {
+            ...entry,
+            recipe: recipe.anatomy
+                ? { ...recipe, anatomy: walk(recipe.anatomy) }
+                : {
+                    ...recipe,
+                    preview: {
+                        ...recipe.preview,
+                        parts: walk(recipe.preview.parts),
+                    },
+                },
+        };
+    });
+}
+async function validateRecipes(root, entries) {
     if (entries.length === 0)
         return "Send at least one recipe: { recipes: [{ name, recipe }] }.";
-    const answer = await askCatalogue("validate", { recipes: entries });
+    const resolved = await resolveAtNodes(root, entries);
+    const answer = await askCatalogue("validate", { recipes: resolved });
     if (!answer.ok)
         return answer.because;
     const body = answer.body;
@@ -662,10 +742,16 @@ async function callTool(root, name, args) {
             return text(await addComponent(root, String(args.name ?? "")));
         case "recipe_vocabulary":
             return text(await recipeVocabulary());
-        case "validate_recipe":
-            return text(await validateRecipe(String(args.name ?? "this component"), args.recipe));
+        case "validate_recipe": {
+            // Same resolution as the batch: an `at` the validator cannot see reads as
+            // an empty node and earns a false floor verdict (dono, 01/08).
+            const [only] = await resolveAtNodes(root, [
+                { name: String(args.name ?? "this component"), recipe: args.recipe },
+            ]);
+            return text(await validateRecipe(String(args.name ?? "this component"), only?.recipe ?? args.recipe));
+        }
         case "validate_recipes":
-            return text(await validateRecipes(Array.isArray(args.recipes)
+            return text(await validateRecipes(root, Array.isArray(args.recipes)
                 ? args.recipes
                 : []));
         case "request_component": {

package/dist/doctor/sketch.js

@@ -19,6 +19,7 @@
  * same in an atomic library, a feature-foldered app, or a single flat directory.
  */
 import { scanTags } from "./css-modules.js";
+import { definitionSpan } from "./transcribe.js";
 /**
  * Past this a component is a page in disguise, and the gate already said no.
  *
@@ -96,7 +97,22 @@ function staticCallClasses(body) {
  * sitting directly between an open and its close - dynamic children are the caller's,
  * and the slot form already says so.
  */
-export function sketchOf(source) {
+export function sketchOf(source, name) {
+    /**
+     * ONE COMPONENT'S MARKUP, when the file declares more than one.
+     *
+     * `RadioCard.tsx` declares `RadioCard` and `RadioCardGroup`, and this used to
+     * hand all sixteen nodes to whoever asked first - node 15 being
+     * `<RadioGroup className="flex flex-col gap-3">`, the OTHER component's root.
+     * So one component read a sketch with a stranger's markup in it and the other
+     * read an empty one (not-expressed.md, dono, 01/08).
+     *
+     * A name that is not in the file, or one whose body has no braces, reads the
+     * whole file - which is right for the 34 files that declare one component.
+     */
+    const span = name ? definitionSpan(source, name) : null;
+    if (span)
+        source = source.slice(span.from, span.to);
     const events = scanTags(source);
     const out = [];
     let depth = 0;

package/dist/doctor/transcribe.js

@@ -146,6 +146,34 @@ const SIZE_KEYWORD = {
     px: "1px",
     "0": "0",
 };
+/**
+ * `max-w-*` HAS ITS OWN RAMP - and it is not the spacing scale.
+ *
+ * Tailwind gives max-width a named ladder of its own (`xs` 20rem through `7xl`
+ * 80rem, plus `none` and `prose`), and the reader only knew the spacing scale
+ * and the keyword sizes - so `max-w-2xl` resolved to nothing and was reported as
+ * a class that "starts like a design decision and resolves to nothing"
+ * (not-expressed.md, dono, 01/08). It resolves to 42rem, and the class was fine;
+ * the table was short.
+ *
+ * Scoped to `max-w`/`max-h` on purpose: `w-2xl` is not a utility, and `p-2xl`
+ * means the spacing scale. A ramp applied on the wrong axis would invent a width.
+ */
+const MAX_WIDTH = {
+    none: "none",
+    xs: "20rem",
+    sm: "24rem",
+    md: "28rem",
+    lg: "32rem",
+    xl: "36rem",
+    "2xl": "42rem",
+    "3xl": "48rem",
+    "4xl": "56rem",
+    "5xl": "64rem",
+    "6xl": "72rem",
+    "7xl": "80rem",
+    prose: "65ch",
+};
 /** Axis-dependent: `w-screen` is 100vw and `h-screen` is 100vh. */
 const SCREEN = {
     w: "100vw",
@@ -635,6 +663,10 @@ export function readUtility(utility, declared) {
             /^(w|h|min-w|min-h|max-w|max-h|size)$/.test(sizePrefix)) {
             return { property: spaceProp, value: SIZE_KEYWORD[sizeRest] };
         }
+        /** `max-w-2xl` - max-width's own named ramp, on its own axis only. */
+        if (MAX_WIDTH[sizeRest] && /^(max-w|max-h)$/.test(sizePrefix)) {
+            return { property: spaceProp, value: MAX_WIDTH[sizeRest] };
+        }
     }
     if (prefix === "rounded") {
         /**
@@ -1107,14 +1139,159 @@ function returnAt(source, name) {
     if (name) {
         const decl = new RegExp(`(?:function|const|let|var)\\s+${name}\\b|${name}\\s*[:=]\\s*(?:function|\\()`).exec(source);
         if (decl) {
-            const from = source.slice(decl.index);
-            const ret = from.search(/return\s*\(/);
-            if (ret !== -1)
-                return decl.index + ret;
+            const own = ownReturn(source, decl.index);
+            if (own !== -1)
+                return own;
+            /**
+             * A BRACE-LESS ARROW returns its JSX straight after `=>`, so there is no
+             * body and no `return` to find - `const X = () => (<div/>)`. That is a
+             * real shape and it gets the concise position.
+             */
+            const arrow = /=>\s*\(/.exec(source.slice(decl.index, decl.index + 400));
+            if (arrow)
+                return decl.index + arrow.index;
+            /**
+             * FOUND THE NAME AND IT RETURNS NO JSX IN PARENTHESES - so say nothing.
+             *
+             * The lexical fallback used to run here and it borrowed the NEXT
+             * component's return: a `Helper` that returns a number handed back a
+             * sibling's `<div className="p-2">`. That is the same defect the charts
+             * had, one shape along - and my own spec caught it (dono, 01/08).
+             */
+            return -1;
         }
     }
     return source.search(/return\s*\(/);
 }
+/**
+ * THE COMPONENT'S OWN `return (`, not the first one after its name.
+ *
+ * Scoping by name was half the answer and the charts proved it: `LineChart` is
+ * declared on line 99, and the first `return (` after that is on line 158 -
+ * inside `CustomTooltip`, a closure NESTED IN ITS BODY. So all three charts
+ * arrived with the tooltip's surface as their base: `bg-white/90 backdrop-blur-md
+ * p-3 rounded-xl shadow-2xl` on what should be a card (not-expressed.md, dono,
+ * 01/08).
+ *
+ * A function's own return sits at the body's OWN brace depth. So: walk from the
+ * declaration, find the body's opening brace, then take the first `return (`
+ * that appears while depth is exactly one - anything deeper belongs to a closure
+ * this component happens to contain.
+ *
+ * Quote-aware, because a brace inside a string is not a brace. An arrow body
+ * with no braces at all (`const X = () => (<div/>)`) has no depth to track and
+ * falls through to the caller's lexical search, which is right for it.
+ */
+/**
+ * WHERE ONE COMPONENT'S CODE STARTS AND STOPS, by name.
+ *
+ * A file that declares two components used to hand both bodies to whatever read
+ * it first: `RadioCard.tsx` declares `RadioCard` and `RadioCardGroup`, and the
+ * sketch attributed all sixteen nodes to `RadioCard` - node 15 being
+ * `<RadioGroup className="flex flex-col gap-3">`, which is the OTHER component's
+ * root (not-expressed.md, dono, 01/08).
+ *
+ * Returns null when the name is not in the file or has no braced body, and the
+ * caller then reads the whole file - which is right for the 34 files that
+ * declare one component.
+ */
+export function definitionSpan(source, name) {
+    const decl = new RegExp(`(?:function|const|let|var)\\s+${name}\\b|${name}\\s*[:=]\\s*(?:function|\\()`).exec(source);
+    if (!decl)
+        return null;
+    const brace = bodyBrace(source, decl.index);
+    if (brace === -1)
+        return null;
+    const end = matchingBrace(source, brace);
+    return { from: decl.index, to: end === -1 ? source.length : end + 1 };
+}
+/** The `{` that opens a function body declared at `declAt`, or -1. */
+function bodyBrace(source, declAt) {
+    let i = declAt;
+    let paren = 0;
+    let opened = false;
+    for (; i < source.length; i++) {
+        const ch = source[i];
+        if (ch === "(") {
+            paren += 1;
+            opened = true;
+        }
+        else if (ch === ")") {
+            paren -= 1;
+            if (opened && paren <= 0) {
+                i += 1;
+                break;
+            }
+        }
+        else if (ch === "{" && !opened) {
+            return -1; // `const X = { … }` is an object, not a body
+        }
+    }
+    return source.indexOf("{", i);
+}
+/** The `}` that closes the brace at `open`, quote-aware. */
+function matchingBrace(source, open) {
+    let depth = 0;
+    let quote = null;
+    for (let j = open; j < source.length; j++) {
+        const ch = source[j];
+        if (quote) {
+            if (ch === "\\")
+                j += 1;
+            else if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'" || ch === "`") {
+            quote = ch;
+            continue;
+        }
+        if (ch === "{")
+            depth += 1;
+        else if (ch === "}") {
+            depth -= 1;
+            if (depth === 0)
+                return j;
+        }
+    }
+    return -1;
+}
+function ownReturn(source, declAt) {
+    const brace = bodyBrace(source, declAt);
+    if (brace === -1)
+        return -1;
+    let depth = 0;
+    let quote = null;
+    for (let j = brace; j < source.length; j++) {
+        const ch = source[j];
+        if (quote) {
+            if (ch === "\\")
+                j += 1;
+            else if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'" || ch === "`") {
+            quote = ch;
+            continue;
+        }
+        if (ch === "{")
+            depth += 1;
+        else if (ch === "}") {
+            depth -= 1;
+            // Out of the body without finding one: this component returns no JSX in
+            // parentheses, and guessing from a sibling would be worse than nothing.
+            if (depth === 0)
+                return -1;
+        }
+        else if (depth === 1 &&
+            ch === "r" &&
+            /^return\s*\(/.test(source.slice(j))) {
+            return j;
+        }
+    }
+    return -1;
+}
 export function rootTag(source, name) {
     const ret = returnAt(source, name);
     if (ret === -1)

package/dist/skill-import.js

@@ -711,6 +711,21 @@ of. It previews as a block carrying its name, and it becomes a **rule** - \`Arti
 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.
 
+**Send what the PARENT paints on it.** A frontier node takes \`at\` (or \`classes\`) like any other,
+and it means something different there: not the child's look, which has a recipe of its own, but
+the override the parent applies where it composes the child. Measured on a real library, four of
+these were being lost:
+
+\`\`\`
+Paginate     <Button className="min-w-[120px] dark:bg-ocean-800 …">   a 120px floor
+MetricCard   <Card className="flex-1 dark:bg-darkgray-300">           overrides Card's dark
+ArticleCard  <Tag className="w-fit">
+Message      <ReactMarkdown className="text-royal-blue-500 underline …">
+\`\`\`
+
+The MetricCard one is the sharpest: losing that override means the preview draws the wrong dark.
+Same for an \`external\` node - a library's component still wears what their code puts on it.
+
 Three 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

package/package.json

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