npm - synthesisui - Versions diffs - 0.16.101 → 0.16.102 - Mend

synthesisui 0.16.101 → 0.16.102

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/dist/anatomy-from-sketch.js +492 -0
package/dist/anatomy-read.js +27 -3
package/dist/commands/import.js +71 -6
package/dist/doctor/imports.js +73 -0
package/dist/doctor/sketch.js +18 -0
package/dist/frontier-kind.js +200 -0
package/package.json +1 -1

package/dist/anatomy-from-sketch.js ADDED Viewed

@@ -0,0 +1,492 @@
+/**
+ * THE SKETCH BECOMES THE ANATOMY, WITHOUT ASKING ANYBODY.
+ *
+ * Measured on the owner's own census (dono, 02/08):
+ *
+ *      medido      36/36 (100%)   sketch with tag + depth + classes, 259 nodes
+ *                                 carrying a class string
+ *      convertido   0/36 (  0%)   `preview.parts` empty on every single recipe
+ *
+ * The tree only ever existed when the SKILL authored `reading.components[X].anatomy`
+ * by hand, one component at a time. A run that did not do that - which is every
+ * automated run - produced 35 recipes holding nothing but the root's own
+ * declarations. For `Modal` that is literally nothing: its root is a
+ * `<BaseDialog.Root>` with no classes, and its whole appearance (backdrop, popup,
+ * close) sits three levels down, measured, in the census, and thrown away.
+ *
+ * So this derives the anatomy from the sketch. Every input is a FACT the census
+ * already holds - the tag, the nesting depth, the class string, the package the
+ * tag was imported from - and nothing here is inferred from a component's name.
+ *
+ * IT EMITS THE SKILL'S OWN INPUT SHAPE (`AnatomyRead[]`), on purpose: `resolveAnatomy`
+ * then does the part naming, the transcription, the crosswalk, the frontier
+ * bookkeeping and the budget exactly as it does for an authored read. One new
+ * producer, no new consumer, and an authored read still wins where one exists.
+ *
+ * Classes travel by `at` (the sketch INDEX) rather than being copied out: a
+ * retyped ten-class string is where a `hover:` goes missing, and six components
+ * lost their states to exactly that (audit, dono, 01/08).
+ */
+import { frontierOf, rendersNothing, } from "./frontier-kind.js";
+/** An svg's insides are geometry, not anatomy: the glyph is the node. */
+const SVG_INTERNALS = new Set([
+    "path",
+    "circle",
+    "rect",
+    "line",
+    "polyline",
+    "polygon",
+    "ellipse",
+    "g",
+    "defs",
+    "lineargradient",
+    "radialgradient",
+    "stop",
+    "clippath",
+    "mask",
+    "use",
+    "symbol",
+    "text",
+    "tspan",
+    "filter",
+    "feblend",
+    "animate",
+]);
+/** Not a visual node at all: a script or style island, and `<head>` furniture. */
+const NOT_VISUAL = new Set(["style", "script", "noscript", "template", "head"]);
+/**
+ * The HTML tag → form table, and the name a tag earns.
+ *
+ * Both come from the element's own content model, which is why they can be a
+ * table: an `<h3>` is a heading in any library, and a `<td>` is a cell. The
+ * name is what the part is CALLED in the stylesheet, so it uses the vocabulary
+ * their own markup used rather than a word we picked.
+ */
+const BY_TAG = {
+    img: { as: "image", name: "image" },
+    picture: { as: "image", name: "image" },
+    video: { as: "image", name: "media" },
+    canvas: { as: "image", name: "canvas" },
+    svg: { as: "icon", name: "icon" },
+    h1: { as: "heading", name: "title" },
+    h2: { as: "heading", name: "title" },
+    h3: { as: "heading", name: "title" },
+    h4: { as: "heading", name: "title" },
+    h5: { as: "heading", name: "title" },
+    h6: { as: "heading", name: "title" },
+    p: { as: "text", name: "text" },
+    small: { as: "text", name: "caption" },
+    strong: { as: "text", name: "text" },
+    em: { as: "text", name: "text" },
+    code: { as: "text", name: "code" },
+    pre: { as: "text", name: "code" },
+    blockquote: { as: "text", name: "quote" },
+    label: { as: "text", name: "label" },
+    legend: { as: "text", name: "legend" },
+    button: { as: "button", name: "action" },
+    a: { as: "button", name: "link" },
+    summary: { as: "button", name: "summary" },
+    input: { as: "field", name: "input" },
+    textarea: { as: "field", name: "input" },
+    select: { as: "field", name: "input" },
+    option: { as: "text", name: "option" },
+    table: { as: "stack", name: "table" },
+    thead: { as: "stack", name: "head" },
+    tbody: { as: "stack", name: "body" },
+    tfoot: { as: "stack", name: "foot" },
+    tr: { as: "row", name: "row" },
+    td: { as: "text", name: "cell" },
+    th: { as: "text", name: "column" },
+    caption: { as: "text", name: "caption" },
+    ul: { as: "stack", name: "list" },
+    ol: { as: "stack", name: "list" },
+    li: { as: "text", name: "item" },
+    dl: { as: "stack", name: "list" },
+    dt: { as: "text", name: "term" },
+    dd: { as: "text", name: "definition" },
+    form: { as: "stack", name: "form" },
+    fieldset: { as: "stack", name: "group" },
+    header: { as: "stack", name: "header" },
+    footer: { as: "stack", name: "footer" },
+    main: { as: "stack", name: "body" },
+    nav: { as: "row", name: "nav" },
+    aside: { as: "stack", name: "aside" },
+    section: { as: "stack" },
+    article: { as: "stack" },
+    details: { as: "stack", name: "details" },
+    figure: { as: "stack", name: "figure" },
+    figcaption: { as: "text", name: "caption" },
+    hr: { as: "icon", name: "divider" },
+    span: { as: "text", name: "text" },
+    div: { as: "stack" },
+};
+/**
+ * WHAT THE CALLER PUTS IN A SLOT, from the parent's content model.
+ *
+ * `expects` is meant to be their words, and a derived read has none - but an
+ * HTML content model is not a guess: the children of a `<tr>` ARE cells and the
+ * children of a `<tbody>` ARE rows. Where the model says nothing general, this
+ * says nothing rather than inventing a description.
+ */
+const EXPECTS = {
+    tr: "the cells",
+    thead: "the rows",
+    tbody: "the rows",
+    table: "the rows",
+    ul: "the items",
+    ol: "the items",
+    dl: "the terms",
+    select: "the options",
+    optgroup: "the options",
+    nav: "the links",
+};
+/**
+ * Tags with no direction of their own: the client's classes decide.
+ *
+ * A `<tr>` is a row and a `<tbody>` is a stack whatever anybody writes on them -
+ * that is the table model, not a style. A `<div>` is neither until its own
+ * `flex-col` says so, and reading that from the class list is the whole reason
+ * `arranged` outranks any shape we would infer.
+ */
+const NEUTRAL = new Set([
+    "div",
+    "section",
+    "article",
+    "form",
+    "fieldset",
+    "header",
+    "footer",
+    "main",
+    "aside",
+    "figure",
+    "nav",
+    "details",
+]);
+/** `flex-col`, `grid` and `block` arrange DOWN; a bare `flex` arranges ACROSS. */
+function arrangement(classes) {
+    const list = ` ${classes ?? ""} `;
+    if (/\s(flex-col|flex-col-reverse|grid|block|table)\s/.test(list))
+        return "stack";
+    if (/\s(flex|inline-flex|flex-row|flex-row-reverse)\s/.test(list))
+        return "row";
+    return "stack";
+}
+/** `ChevronDown` → `chevron-down`; `BaseDialog.Popup` → `popup`. */
+function nameOfTag(tag) {
+    const member = tag.includes(".") ? (tag.split(".").pop() ?? tag) : tag;
+    return member
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "");
+}
+/**
+ * A HEADLESS PRIMITIVE'S OWN MEMBER NAME, when it says what the thing is.
+ *
+ * `Root`, `Trigger`, `Popup`, `Panel`, `Backdrop`, `Item`, `Indicator`, `Thumb`
+ * is the shared vocabulary of every headless library, and it is the client's own
+ * word for that element - so it makes a better part name than anything we would
+ * pick, and a better form than "div with children".
+ */
+const MEMBER_FORM = {
+    trigger: "button",
+    close: "button",
+    submit: "button",
+    arrow: "icon",
+    indicator: "icon",
+    thumb: "icon",
+    icon: "icon",
+    separator: "icon",
+    label: "text",
+    value: "text",
+    description: "text",
+    title: "heading",
+    input: "field",
+    control: "field",
+    text: "text",
+    caption: "text",
+    option: "text",
+    image: "image",
+    avatar: "image",
+    track: "stack",
+    range: "icon",
+    bar: "icon",
+    handle: "icon",
+    checkbox: "icon",
+    radio: "icon",
+    tab: "button",
+    backdrop: "stack",
+    overlay: "stack",
+    popup: "stack",
+    panel: "stack",
+    content: "stack",
+    list: "stack",
+    viewport: "stack",
+    group: "stack",
+    item: "row",
+    row: "row",
+};
+/**
+ * Derive the anatomy of ONE component from its sketch.
+ *
+ * `defines` is the census crosswalk (their name → the slug it reaches), used to
+ * tell their own library imported through an alias from a third party the table
+ * has never seen. See `frontierOf`.
+ *
+ * Node 0 is skipped: it is the element the component RETURNS, its classes are
+ * already the recipe's `base`, and emitting it again would draw the component
+ * inside a copy of itself.
+ */
+export function anatomyFromSketch(sketch, defines,
+/**
+ * Their manifest: a package name → the range they pinned. This is what tells
+ * `@frontend-hub/ui: workspace:*` (their own library, one folder over) apart
+ * from `recharts: ^2.12.0`, since both are spelled the same way. See
+ * `frontierOf`.
+ */
+versionOf) {
+    const notes = [];
+    const libraries = [];
+    if (!Array.isArray(sketch) || sketch.length === 0)
+        return { read: [], notes, libraries };
+    /** Children of each index, from the depth column. */
+    const kids = sketch.map(() => []);
+    const roots = [];
+    const stack = [];
+    for (let i = 0; i < sketch.length; i++) {
+        const depth = Number(sketch[i]?.depth ?? 0);
+        while (stack.length > depth)
+            stack.pop();
+        const parent = stack.length > 0 ? stack[stack.length - 1] : -1;
+        if (parent >= 0)
+            kids[parent].push(i);
+        else
+            roots.push(i);
+        stack.push(i);
+    }
+    const build = (index, depth) => {
+        const node = sketch[index];
+        if (!node)
+            return [];
+        const tag = String(node.tag ?? "");
+        const lower = tag.toLowerCase();
+        const classes = node.classes?.trim() || undefined;
+        /**
+         * THE CHILDREN THAT DRAW SOMETHING. An `<svg>` full of `<path>`s is a glyph,
+         * not a stack of two shapes, and counting its geometry as content turned every
+         * inline icon into a container - their Tooltip's arrow previewed as a box
+         * holding a box (probe, 02/08).
+         */
+        const children = (kids[index] ?? []).filter((child) => {
+            const tag = String(sketch[child]?.tag ?? "").toLowerCase();
+            return !SVG_INTERNALS.has(tag) && !NOT_VISUAL.has(tag);
+        });
+        if (NOT_VISUAL.has(lower)) {
+            notes.push(`\`<${tag}>\` is a ${lower} island - its rules are real and this contract has no form that holds them`);
+            return [];
+        }
+        // An svg's insides are geometry: the glyph is the node, and it stops here.
+        if (SVG_INTERNALS.has(lower))
+            return [];
+        const capitalised = /^[A-Z]/.test(tag);
+        const kind = capitalised
+            ? frontierOf(tag, node.from, defines, versionOf)
+            : "own";
+        // The dependency, whatever we decide to draw - see `DerivedAnatomy.libraries`.
+        if (node.from &&
+            kind !== "own" &&
+            !libraries.some((l) => l.from === node.from))
+            libraries.push({ from: node.from, kind });
+        /**
+         * DECLARED IN THIS FILE, so there is no package and no recipe to point at.
+         *
+         * 20 of 181 capitalised nodes in the owner's library are this: `ToolbarButton`,
+         * `Shimmer`, `CustomLegend`. They are the client's own markup wearing the
+         * client's own classes, so they are DRAWN - the opposite of a frontier. The
+         * crosswalk would happily resolve `ToolbarButton` to `button` and turn a local
+         * helper into a reference to a component it is not.
+         */
+        const local = capitalised && !node.from;
+        /**
+         * A WRAPPER THAT RENDERS NOTHING passes its children up in its own place: a
+         * portal teleports and a provider is context. Keeping it would draw a box
+         * that does not exist in the client's output.
+         */
+        if ((kind === "motion" || kind === "headless") &&
+            rendersNothing(tag, classes)) {
+            return children.flatMap((child) => build(child, depth));
+        }
+        // `<AnimatePresence>` and friends: no element of their own.
+        if (kind === "motion" && !classes && children.length > 0) {
+            return children.flatMap((child) => build(child, depth));
+        }
+        const descend = () => children.flatMap((child) => build(child, depth + 1));
+        /**
+         * THEIR OWN COMPONENT, and a library that draws itself: a reference, and it
+         * stops. What their code nests INSIDE it is that component's content, which
+         * the frontier has no field for - counted rather than silently dropped.
+         */
+        if (kind === "own" && capitalised && !local) {
+            return [
+                {
+                    as: "component",
+                    ref: tag,
+                    ...(classes ? { at: index } : {}),
+                    ...(children.length > 0 ? { children: descend() } : {}),
+                },
+            ];
+        }
+        if (kind === "opaque") {
+            /**
+             * An opaque library draws its own insides, so anything nested under it in
+             * their code is a CHILD they passed to it - a legend, an axis, a fallback -
+             * and it is theirs. What we do not claim is the drawing.
+             */
+            return [
+                {
+                    as: "external",
+                    from: String(node.from ?? tag),
+                    ...(classes ? { at: index } : {}),
+                    ...(children.length > 0 ? { children: descend() } : {}),
+                },
+            ];
+        }
+        if (kind === "icon") {
+            return [{ as: "icon", name: nameOfTag(tag), at: index }];
+        }
+        /**
+         * EVERYTHING ELSE IS DRAWN: plain HTML, a headless primitive, and a
+         * component the file declares itself. All three wear the client's classes
+         * and all three are ours to reproduce.
+         */
+        const member = tag.includes(".")
+            ? (tag.split(".").pop() ?? "").toLowerCase()
+            : "";
+        const byTag = BY_TAG[lower];
+        const hasKids = children.length > 0;
+        let as;
+        let name;
+        if (capitalised) {
+            // A primitive's member name is the client's own word for the element.
+            name = nameOfTag(tag);
+            /**
+             * THE LAST WORD OF THE MEMBER IS THE NOUN. `ItemText` is text, `ItemIndicator`
+             * is an indicator, `ScrollUpArrow` is an arrow - every headless library
+             * compounds its member names the same way, and reading only the whole string
+             * made a Select's item label preview as a glyph (probe, 02/08).
+             */
+            const noun = name.split("-").pop() ?? name;
+            const form = MEMBER_FORM[member] ?? MEMBER_FORM[name] ?? MEMBER_FORM[noun];
+            if (form === "row" || form === "stack")
+                as = arrangement(classes);
+            else if (form)
+                as = form;
+            else
+                as = hasKids ? arrangement(classes) : node.text ? "text" : "icon";
+        }
+        else if (byTag) {
+            name = byTag.name;
+            if (NEUTRAL.has(lower)) {
+                /**
+                 * A leaf box with no content of its own is a drawn SHAPE - a dot, a
+                 * track, a divider - and `icon` is the form for "a bare shape with no
+                 * text". An empty `stack` would preview as nothing at all.
+                 */
+                as =
+                    hasKids || node.slot
+                        ? arrangement(classes)
+                        : node.text
+                            ? "text"
+                            : "icon";
+            }
+            else
+                as = byTag.as;
+        }
+        else {
+            as = hasKids ? arrangement(classes) : "icon";
+        }
+        /**
+         * ANYTHING HOLDING ELEMENTS ARRANGES THEM - the contract gives children to
+         * `row` and `stack` only, and a leaf that has some gets them hoisted out to
+         * become its siblings, which destroys the nesting the client wrote.
+         *
+         * This is the same law the usage generator applies one level up: a trigger
+         * that wraps a heading is not a `<button>`, because a button may not contain
+         * one. The part is still called `trigger`, which is what carries the role.
+         */
+        if (hasKids && as !== "row" && as !== "stack")
+            as = arrangement(classes);
+        // A plain structural box earns a name only when it carries decisions - and
+        // it must earn one, because the name is what the class string travels on.
+        if (!name && classes)
+            name = "box";
+        /**
+         * A NODE WHOSE CONTENT IS THE CALLER'S is a slot, and it keeps its own name
+         * and classes - the border and the hover on a `<tr>{children}</tr>` are real
+         * and belong on that element.
+         */
+        if (node.slot && !hasKids) {
+            const only = EXPECTS[lower];
+            return [
+                {
+                    as: "slot",
+                    ...(name ? { name } : {}),
+                    at: index,
+                    ...(only ? { expects: only } : {}),
+                },
+            ];
+        }
+        const built = {
+            as,
+            ...(name ? { name } : {}),
+            ...(classes ? { at: index } : {}),
+            ...(node.text ? { text: node.text } : {}),
+        };
+        const inside = hasKids ? descend() : [];
+        /**
+         * MIXED CONTENT IS BOTH: their markup AND the caller's. A panel that renders
+         * a header and then `{children}` has two kinds of content and dropping either
+         * one is a hole somebody has to explain.
+         */
+        const expects = EXPECTS[lower];
+        const withSlot = node.slot
+            ? [...inside, { as: "slot", ...(expects ? { expects } : {}) }]
+            : inside;
+        if (withSlot.length > 0) {
+            built.children = withSlot;
+            if (as !== "row" && as !== "stack")
+                built.as = arrangement(classes);
+        }
+        return [built];
+    };
+    /**
+     * The component's own root is node 0 and its classes are the recipe's `base`.
+     * A root that renders nothing (a portal, a provider) hands its children over,
+     * which is how a Tooltip's popup reaches the tree at all.
+     *
+     * A component returning a FRAGMENT has several depth-0 elements and only the
+     * first one's classes became `base`, so the rest are emitted as siblings
+     * instead of being dropped with the fragment.
+     */
+    const top = roots.length > 0 ? roots[0] : 0;
+    const read = [
+        ...(kids[top] ?? []).flatMap((child) => build(child, 0)),
+        ...roots.slice(1).flatMap((sibling) => build(sibling, 0)),
+    ];
+    /**
+     * THE ROOT'S OWN `{children}` - the component whose entire content is the
+     * caller's.
+     *
+     * `<tr className="border-b hover:bg-ocean-50/30">{children}</tr>` is the whole
+     * of a real DataTableRow, and skipping node 0 skips the one thing it holds. Six
+     * components in the owner's library are exactly this shape, and they previewed
+     * as empty boxes: a Chat that says nothing about messages reads as a component
+     * we failed to extract (dono, 01/08).
+     */
+    const rootNode = sketch[top];
+    if (rootNode?.slot) {
+        const only = EXPECTS[String(rootNode.tag ?? "").toLowerCase()];
+        read.push({ as: "slot", ...(only ? { expects: only } : {}) });
+    }
+    return { read, notes, libraries };
+}

package/dist/anatomy-read.js CHANGED Viewed

@@ -56,7 +56,17 @@ const STRUCTURAL = /^(root|wrapper|base|el|outer)$/i;
 /** A pathological transcription of somebody's DOM, bounded. Six levels reaches
  *  any real component; past that it is layout divs all the way down. */
 const MAX_DEPTH = 6;
-const MAX_NODES = 48;
+/**
+ * The same ceiling the sketch measured, for the same reason.
+ *
+ * 48 was the budget for an anatomy somebody TYPED, where 48 nodes is a very long
+ * message. A DERIVED anatomy is as long as their component is, and the sketch
+ * already measured that ceiling on a real library: exactly one component passes
+ * 60 nodes (`TextEditor`, 67) and nothing passes 150. At 48 that component lost
+ * its editable region - the whole point of it - which is the same truncation the
+ * sketch cap was raised to stop (dono, 02/08).
+ */
+const MAX_NODES = 150;
 /**
  * `Actions.Generate` → `actions-generate`, and never `actions.generate`.
  *
@@ -182,9 +192,21 @@ sketch) {
             const { as, coerced: wasCoerced } = formOf(node);
             if (wasCoerced)
                 coerced += 1;
-            // A FRONTIER carries a reference and nothing else. A name or a class list
-            // on one would be us claiming styles that belong to somebody else.
+            /**
+             * A FRONTIER carries a reference, not a name and not a style block: the
+             * appearance there belongs to somebody else's recipe.
+             *
+             * WHAT IT DOES CARRY IS WHAT THEIR CODE PUTS INSIDE IT. `<Card>` wrapping a
+             * header and a chart is the parent's markup, wearing the parent's classes,
+             * and stopping at the name dropped 55 of 369 elements across a real library
+             * - 15% of its markup, including the whole visible content of two charts
+             * (probe, 02/08).
+             */
             if (FRONTIERS.has(as)) {
+                const held = Array.isArray(node.children)
+                    ? walk(node.children, depth + 1)
+                    : [];
+                const holds = held.length > 0 ? { children: held } : {};
                 if (as === "component") {
                     const name = String(node.ref ?? "").trim();
                     if (!name)
@@ -204,6 +226,7 @@ sketch) {
                         ref: slug || safePartName(name),
                         ...(slug && slug !== safePartName(name) ? { refName: name } : {}),
                         ...frontierClasses(node, sketch),
+                        ...holds,
                     });
                     continue;
                 }
@@ -218,6 +241,7 @@ sketch) {
                     from,
                     ...(version ? { version } : {}),
                     ...frontierClasses(node, sketch),
+                    ...holds,
                 });
                 continue;
             }

package/dist/commands/import.js CHANGED Viewed

@@ -1,5 +1,6 @@
 import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
 import { basename, dirname, join, relative } from "node:path";
+import { anatomyFromSketch } from "../anatomy-from-sketch.js";
 import { resolveAnatomy, resolveFlatParts, safePartName, } from "../anatomy-read.js";
 import { readCredentials, readToken, resolveRegistry, sameRegistry, } from "../config.js";
 import { architectureRule, describeArchitecture, describeChoice, detectArchitectures, } from "../doctor/architecture.js";
@@ -421,6 +422,7 @@ export async function takeCensus(root, opts) {
                             ...(esketch.length > 0 ? { sketch: esketch } : {}),
                             ...et,
                             ...(etag ? { rootTag: etag } : {}),
+                            ...rootPackage(etag, esketch),
                         };
                     }
                 }
@@ -526,6 +528,7 @@ export async function takeCensus(root, opts) {
                         ...(Object.keys(parts).length > 0 ? { parts } : {}),
                         ...(tree.length > 0 ? { tree } : {}),
                         ...(tag ? { rootTag: tag } : {}),
+                        ...rootPackage(tag, sketch),
                         ...(layers.length > 0 ? { layers } : {}),
                         ...(Object.keys(v.axes).length > 0 ? { declaredAxes: v.axes } : {}),
                         ...(Object.keys(defaults).length > 0 ? { defaults } : {}),
@@ -1624,6 +1627,23 @@ function sayReach(c) {
  * Their declared tokens come from the census itself, so a run that only sends a
  * file it was handed still resolves a `bg-ocean-500` by their own name.
  */
+/**
+ * THE PACKAGE THE ROOT TAG CAME FROM, read off the sketch that just measured it.
+ *
+ * The sketch stamps every capitalised tag with its own import specifier, and node
+ * 0 IS the returned element - so this costs a lookup rather than a second parse.
+ * The tag guard is there because a component whose root the sketch could not reach
+ * (a return the scanner did not follow) must say nothing rather than borrow the
+ * first node's package.
+ */
+function rootPackage(tag, sketch) {
+    if (!tag || !/^[A-Z]/.test(tag))
+        return {};
+    const first = sketch[0];
+    return first && first.tag === tag && first.from
+        ? { rootFrom: first.from }
+        : {};
+}
 async function resolveReadParts(census, root) {
     const read = census.reading?.components;
     if (!read)
@@ -1658,27 +1678,72 @@ async function resolveReadParts(census, root) {
             crosswalked.set(c.name, safePartName(target));
     }
     const resolveRef = (name) => crosswalked.get(name) ?? null;
-    for (const [component, entry] of Object.entries(read)) {
+    for (const component of Object.keys(looks)) {
+        const entry = read[component];
         const anatomy = entry?.anatomy;
+        /**
+         * THE SKETCH IS THE ANATOMY WHEN NOBODY AUTHORED ONE.
+         *
+         * Measured on the owner's census before this existed: 36 of 36 components had
+         * a sketch, 259 of their nodes carried a class string, and 0 of 36 recipes
+         * carried a tree - because a tree only appeared when the skill wrote one out
+         * component by component. `Modal` therefore shipped with an empty recipe: its
+         * root is an unstyled `BaseDialog.Root` and its backdrop, popup and close
+         * button are three levels below it (dono, 02/08).
+         *
+         * An AUTHORED read still wins. The skill can see the props, the prop types
+         * and the call sites, so its names beat derived ones - this only fills the
+         * silence, which was total.
+         */
+        const derived = Array.isArray(anatomy) && anatomy.length > 0
+            ? null
+            : anatomyFromSketch(looks[component]?.sketch, resolveRef, (pkg) => deps[pkg]);
+        if (derived?.read.length) {
+            for (const note of derived.notes)
+                notes.add(note);
+        }
         const resolved = Array.isArray(anatomy) && anatomy.length > 0
             ? resolveAnatomy(anatomy, declared, deps, resolveRef, entry?.root,
             // The component's own sketch, so a node naming itself by index reads
             // the exact class string the census measured (dono, 01/08).
             looks[component]?.sketch)
-            : Array.isArray(entry?.parts) && entry.parts.length > 0
-                ? resolveFlatParts(entry.parts, declared)
-                : null;
+            : derived && derived.read.length > 0
+                ? resolveAnatomy(derived.read, declared, deps, resolveRef, entry?.root, looks[component]?.sketch)
+                : Array.isArray(entry?.parts) && entry.parts.length > 0
+                    ? resolveFlatParts(entry.parts, declared)
+                    : null;
         if (!resolved)
             continue;
         const hasParts = Object.keys(resolved.parts).length > 0;
         if (!hasParts && resolved.tree.length === 0)
             continue;
         const look = looks[component];
+        /**
+         * THE DEPENDENCIES, INCLUDING THE ONES WE DRAW OURSELVES.
+         *
+         * A headless primitive is drawn rather than named - right for the appearance,
+         * a lie about the dependency. Their Modal reconstructed as divs looks the same
+         * and has no focus trap and no escape key, so the package is declared with the
+         * split said out loud: the pixels are theirs, the behaviour is the library's.
+         */
+        const pinned = deps ?? {};
+        const libraries = [
+            ...resolved.external,
+            ...(derived?.libraries ?? [])
+                .filter((lib) => !resolved.external.some((e) => e.from === lib.from))
+                .map((lib) => ({
+                from: lib.from,
+                ...(pinned[lib.from] ? { version: pinned[lib.from] } : {}),
+                ...(lib.kind === "headless" || lib.kind === "icon"
+                    ? { kind: lib.kind }
+                    : {}),
+            })),
+        ];
         const carried = {
             ...(hasParts ? { parts: resolved.parts } : {}),
             ...(resolved.tree.length > 0 ? { tree: resolved.tree } : {}),
             ...(resolved.composes.length > 0 ? { composes: resolved.composes } : {}),
-            ...(resolved.external.length > 0 ? { external: resolved.external } : {}),
+            ...(libraries.length > 0 ? { external: libraries } : {}),
             ...(resolved.root ? { root: resolved.root } : {}),
         };
         looks[component] = look
@@ -1704,7 +1769,7 @@ async function resolveReadParts(census, root) {
         if (resolved.tree.length > 0)
             shaped += 1;
         edges += resolved.composes.length;
-        for (const e of resolved.external)
+        for (const e of libraries)
             libs.add(e.from);
         for (const n of resolved.notes)
             notes.add(n);

package/dist/doctor/imports.js ADDED Viewed

@@ -0,0 +1,73 @@
+/**
+ * WHERE EACH NAME IN A FILE CAME FROM.
+ *
+ * The sketch recorded `tag: "Dialog.Root"` and threw away the one fact that says
+ * what it is. `Dialog.Root` out of `@base-ui/react` is an unstyled div waiting
+ * for the client's classes; `Dialog.Root` out of a styled kit draws itself. Same
+ * identifier, opposite handling - so the package has to travel with the node, and
+ * the reader already has the file open when it could be stamping it.
+ *
+ * Regex over the import statements rather than a parse: an import is one of five
+ * shapes, all of them flat, and the reader is deliberately AST-free everywhere
+ * else in this module for the same reason (speed on a repo of 704 files).
+ */
+/**
+ * `import X, { a, b as c } from "pkg"` / `import * as NS from "pkg"`.
+ *
+ * The two clause slots are the default and the named block, in either order, and
+ * `type` imports are skipped by the caller's own filter below - a type never
+ * appears as a tag.
+ */
+const IMPORT = /import\s+(?!type\s)([\w$]+|\*\s+as\s+[\w$]+|\{[^}]*\})(?:\s*,\s*(\{[^}]*\}|[\w$]+))?\s+from\s*["']([^"']+)["']/g;
+/**
+ * Every local name this file binds, mapped to the specifier it came from.
+ *
+ * An alias is stored under the LOCAL name, because the local name is what the
+ * JSX says: `import { Select as BaseSelect }` means the sketch's `BaseSelect.Item`
+ * has to find `@base-ui/react/select`.
+ */
+export function importMap(source) {
+    const out = {};
+    IMPORT.lastIndex = 0;
+    let match = IMPORT.exec(source);
+    while (match) {
+        const pkg = match[3];
+        for (const clause of [match[1], match[2]]) {
+            if (!clause)
+                continue;
+            if (clause.startsWith("*")) {
+                const ns = clause.split(/\s+as\s+/)[1]?.trim();
+                if (ns)
+                    out[ns] = pkg;
+                continue;
+            }
+            if (!clause.startsWith("{")) {
+                out[clause.trim()] = pkg;
+                continue;
+            }
+            for (const raw of clause.slice(1, -1).split(",")) {
+                const entry = raw.trim().replace(/^type\s+/, "");
+                if (!entry)
+                    continue;
+                const [, local] = entry.split(/\s+as\s+/);
+                const name = (local ?? entry).trim();
+                if (name)
+                    out[name] = pkg;
+            }
+        }
+        match = IMPORT.exec(source);
+    }
+    return out;
+}
+/**
+ * The specifier a TAG resolves to, or undefined when the file declares it itself.
+ *
+ * Undefined is a real answer and not a failure: 20 of 181 capitalised nodes in
+ * the owner's library are declared in the same file (`ToolbarButton`, `Shimmer`,
+ * `CustomLegend`), and those are the client's own markup wearing the client's own
+ * classes - which is the opposite of a third party.
+ */
+export function packageOfTag(tag, imports) {
+    const head = tag.includes(".") ? tag.split(".")[0] : tag;
+    return imports[head];
+}

package/dist/doctor/sketch.js CHANGED Viewed

@@ -19,7 +19,10 @@
  * same in an atomic library, a feature-foldered app, or a single flat directory.
  */
 import { scanTags } from "./css-modules.js";
+import { importMap, packageOfTag } from "./imports.js";
 import { definitionSpan } from "./transcribe.js";
+/** `{children}` / `{props.children}` - the caller's content, spelled either way. */
+const CHILDREN = /\{\s*(?:props\.)?children\s*\}/;
 /**
  * Past this a component is a page in disguise, and the gate already said no.
  *
@@ -114,6 +117,12 @@ function staticCallClasses(body) {
  * and the slot form already says so.
  */
 export function sketchOf(source, name) {
+    /**
+     * READ THE IMPORTS BEFORE SLICING - they live at the top of the file, and the
+     * span below cuts them off. One map per file, so a 16-node component costs one
+     * pass over the header rather than sixteen lookups into the disk.
+     */
+    const imports = importMap(source);
     /**
      * ONE COMPONENT'S MARKUP, when the file declares more than one.
      *
@@ -141,6 +150,12 @@ export function sketchOf(source, name) {
         if (out.length >= MAX_NODES)
             break;
         const node = { tag: event.tag, depth };
+        // What a capitalised tag IS, from the file's own imports - see `SketchNode.from`.
+        if (/^[A-Z]/.test(event.tag)) {
+            const pkg = packageOfTag(event.tag, imports);
+            if (pkg)
+                node.from = pkg;
+        }
         const cls = CLASS_ATTR.exec(event.body);
         if (cls?.[1].trim())
             node.classes = cls[1].trim();
@@ -162,6 +177,9 @@ export function sketchOf(source, name) {
                 !between.includes("<")) {
                 node.text = between;
             }
+            // The caller's content, as a fact - see `SketchNode.slot`.
+            if (CHILDREN.test(between))
+                node.slot = true;
         }
         out.push(node);
         depth += 1;

package/dist/frontier-kind.js ADDED Viewed

@@ -0,0 +1,200 @@
+/**
+ * WHAT A PACKAGE IS, SO A NODE KNOWS WHETHER WE CAN DRAW IT.
+ *
+ * The reader had exactly two answers for a capitalised element: `component` (one
+ * of theirs) or `external` (somebody else's, drawn as a named block and stopped).
+ * Measured across the owner's library - 372 sketch nodes, resolved against each
+ * file's own imports (dono, 02/08):
+ *
+ *    191 (51%)  HTML
+ *     69 (18%)  headless primitives  @base-ui/react/*        36 carry classes
+ *     35 ( 9%)  one of theirs        @ui/lib/SignalUI/*      32 carry classes
+ *     34 ( 9%)  icon glyphs          lucide-react            13 carry classes
+ *     20 ( 5%)  local to the file    ToolbarButton, Shimmer   4 carry classes
+ *     20 ( 5%)  genuinely opaque     recharts, tiptap         5 carry classes
+ *      3 ( 0%)  motion wrappers      AnimatePresence          0 carry classes
+ *
+ * 122 of 372 nodes - a third of the library's markup - fell into `external` and
+ * stopped there. Seven components (20% of the library) had a headless primitive
+ * as their ROOT, so `collapsible-card` and `radio-card` carried six and eight
+ * real declarations behind a "3rd-party" badge and a chrome box.
+ *
+ * THE DISTINCTION IS NOT COSMETIC. A headless library ships behaviour and no
+ * appearance: every pixel of a Base-UI dialog is in the CLIENT's class list, so
+ * the whole visual truth is ours to read and draw. An opaque library ships the
+ * appearance itself: `<SketchPicker>` draws a colour wheel we cannot reproduce
+ * from a class string, and pretending otherwise would be inventing it.
+ *
+ * DECIDED BY PACKAGE, NEVER BY COMPONENT NAME. `Dialog.Root` from
+ * `@base-ui/react` and `Dialog.Root` from a styled kit are the same identifier
+ * and opposite answers, so the identifier cannot be the input. Nothing here
+ * matches a component name, which is what keeps it working on a library nobody
+ * here has seen.
+ */
+/**
+ * Behaviour without appearance. Matched as a PREFIX, so `@base-ui/react/dialog`
+ * and `@radix-ui/react-dialog` both land without an entry each.
+ */
+const HEADLESS = [
+    "@base-ui/react",
+    "@base-ui-components/react",
+    "@mui/base",
+    "radix-ui",
+    "@radix-ui/react-",
+    "@headlessui/",
+    "react-aria",
+    "@react-aria/",
+    "@react-stately/",
+    "@ariakit/",
+    "ariakit",
+    "@reach/",
+    "@zag-js/",
+    "@ark-ui/",
+    "vaul",
+    "cmdk",
+    "downshift",
+    "@tanstack/react-table",
+    "@tanstack/react-virtual",
+];
+/** Glyph packages: one element, one path, a size and a colour. */
+const ICONS = [
+    "lucide-react",
+    "lucide-preact",
+    "react-icons",
+    "react-feather",
+    "@radix-ui/react-icons",
+    "@heroicons/",
+    "@tabler/icons",
+    "@mui/icons-material",
+    "@ant-design/icons",
+    "@phosphor-icons/",
+    "phosphor-react",
+    "@fortawesome/",
+    "react-bootstrap-icons",
+    "@iconify/",
+    "iconoir-react",
+];
+/** Animation wrappers whose own element is either absent or a plain div. */
+const MOTION = [
+    "framer-motion",
+    "motion",
+    "@react-spring/",
+    "react-transition-group",
+];
+/**
+ * A relative or aliased specifier is the client's own code, whatever it is
+ * called. `@/`, `~/` and `#` are the three alias spellings a bundler hands out.
+ */
+function isPath(pkg) {
+    return (pkg.startsWith(".") ||
+        pkg.startsWith("/") ||
+        pkg.startsWith("@/") ||
+        pkg.startsWith("~") ||
+        pkg.startsWith("#"));
+}
+const startsWithAny = (pkg, list) => list.some((entry) => pkg === entry || pkg.startsWith(entry));
+/**
+ * The kind of a package specifier, from the table and nothing else.
+ *
+ * An UNKNOWN bare specifier answers `opaque`, because that is what it is: a
+ * third-party package we have no reason to believe we can draw. Their own
+ * library imported through a tsconfig alias (`@ui/lib/SignalUI/atoms/Card`) also
+ * lands here, and the caller corrects it with the one fact that settles it - the
+ * census crosswalk already knows whether the NAME is a component they define.
+ * See `frontierOf`.
+ */
+export function frontierKind(pkg) {
+    const id = (pkg ?? "").trim();
+    if (!id)
+        return "own";
+    if (isPath(id))
+        return "own";
+    if (startsWithAny(id, ICONS))
+        return "icon";
+    if (startsWithAny(id, HEADLESS))
+        return "headless";
+    if (startsWithAny(id, MOTION))
+        return "motion";
+    return "opaque";
+}
+/** `@scope/name/sub` → `@scope/name`; `name/sub` → `name`. */
+function packageRoot(pkg) {
+    const parts = pkg.split("/");
+    return pkg.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0];
+}
+/**
+ * A range that means "this is in this repository": a workspace sibling, a linked
+ * folder, a tarball on disk. The one fact that tells their own published library
+ * apart from a third party, since both are spelled `@scope/name`.
+ */
+const LOCAL_RANGE = /^(workspace:|file:|link:|portal:)/;
+/**
+ * The kind of ONE ELEMENT: the table, then their manifest, then the crosswalk.
+ *
+ * ORDER IS THE WHOLE TRICK, and getting it wrong is a bug a spec caught here
+ * before a person did. `Tooltip` is a component they define AND a component
+ * `recharts` exports, and their PieChart imports the recharts one - so a
+ * crosswalk consulted too early claims a third-party chart tooltip as theirs.
+ *
+ * So the question the manifest answers comes first: is this specifier a package
+ * they installed, or a path into their own source? `recharts: ^2.12.0` is a third
+ * party; `@frontend-hub/ui: workspace:*` is their own library one folder over;
+ * `@ui/lib/SignalUI/atoms/Card` is not in the manifest at all, because it is a
+ * tsconfig alias. Only then does the crosswalk get asked.
+ *
+ * `defines` is the census's crosswalk: their name → the slug it reaches, or null.
+ * `versionOf` is their manifest: a package name → the range they pinned.
+ */
+export function frontierOf(tag, pkg, defines, versionOf) {
+    const kind = frontierKind(pkg);
+    if (kind !== "opaque" || !pkg)
+        return kind;
+    const head = tag.includes(".") ? tag.split(".")[0] : tag;
+    const version = versionOf?.(packageRoot(pkg));
+    if (version)
+        return LOCAL_RANGE.test(version) ? "own" : "opaque";
+    /**
+     * NO MANIFEST ANSWER, so the specifier's own shape is what is left. An alias
+     * into their source addresses a FILE (`@ui/lib/SignalUI/atoms/Card`); a package
+     * they never declared addresses a package (`recharts`, `@scope/name`). Asking
+     * the crosswalk only for the first shape is what keeps `Tooltip` honest when
+     * the manifest was unreadable.
+     */
+    const deep = pkg.split("/").length > (pkg.startsWith("@") ? 2 : 1);
+    return deep && defines?.(head) ? "own" : "opaque";
+}
+/**
+ * Members of a headless namespace that render NOTHING - a portal, a positioner,
+ * a context provider.
+ *
+ * This is the one place a member NAME is read, and it is the shared vocabulary
+ * of every headless library rather than one library's private spelling: Base-UI,
+ * Radix, Ark and Ariakit all spell a portal `Portal`. It is also gated on the
+ * node carrying no classes at all, so a `Positioner` the client styled survives
+ * as a real box - which is exactly what happens in their Select.
+ */
+const NON_RENDERING = new Set([
+    "portal",
+    "positioner",
+    "provider",
+    "presence",
+    "animatepresence",
+    "anchor",
+    "fragment",
+    /**
+     * `Root` earns its place here only when it carries nothing. A headless `Root`
+     * is sometimes the visible surface - their `Collapsible.Root` holds the card's
+     * six declarations - and sometimes a bare context wrapper, as their
+     * `BaseSelect.Root` is. The class list is what separates the two, and the gate
+     * above reads exactly that: styled roots survive, empty ones step aside rather
+     * than becoming a part literally named `root`.
+     */
+    "root",
+]);
+/** `BaseDialog.Portal` → true. `BaseSelect.Positioner` with `z-50 pt-1` → false. */
+export function rendersNothing(tag, classes) {
+    if (classes?.trim())
+        return false;
+    const member = tag.includes(".") ? tag.split(".").pop() : tag;
+    return NON_RENDERING.has((member ?? "").toLowerCase());
+}

package/package.json CHANGED Viewed

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