synthesisui 0.16.77 → 0.16.79

package/dist/component-codegen.js

@@ -1,4 +1,12 @@
+export const DEFAULT_CONVENTION = {
+    prefix: "ds-",
+    partSeparator: "-",
+};
 const kebab = (v) => v.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+/** `metric-card` → `ds-metric-card`, or `metric-card`, or `sui-metric-card`. */
+const elementClass = (name, c) => `${c.prefix}${kebab(name)}`;
+/** `metric-card` + `title` → `ds-metric-card-title`, or `metric-card__title`. */
+const partClassName = (name, part, c) => `${elementClass(name, c)}${c.partSeparator}${kebab(part)}`;
 const pascal = (name) => name
     .split(/[^a-zA-Z0-9]+/)
     .filter(Boolean)
@@ -199,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;
@@ -478,10 +498,91 @@ const joinCls = (parts) => `[${parts.join(", ")}].filter(Boolean).join(" ")`;
  * applies, which is what the call site reads like.
  */
 const resolveCls = (parts) => `cn(${parts.join(", ")})`;
+/**
+ * WHAT ELEMENT EACH FORM IS, and this is where the anatomy stops being a picture.
+ *
+ * Every part came out as a `<div>` - a title, a value, a cover image, all divs -
+ * because a flat list of names cannot say what a part IS. The tree says, so a
+ * heading generates an `<h3>`, an image an `<img>`, a field an `<input>`. That is
+ * not cosmetic: it decides what a screen reader announces and what a browser lets
+ * you tab to.
+ */
+const FORM_TAG = {
+    image: { tag: "img", voidEl: true },
+    heading: { tag: "h3" },
+    text: { tag: "span" },
+    button: { tag: "button" },
+    field: { tag: "input", voidEl: true },
+    icon: { tag: "span" },
+    row: { tag: "div" },
+    stack: { tag: "div" },
+};
+/** Only these two arrange; the rest are leaves. */
+const ARRANGES = new Set(["row", "stack"]);
+/** Every part the tree names, in tree order - so the generated part components
+ *  come out in the order somebody reading the file expects to find them. */
+function treeParts(nodes, out = []) {
+    for (const node of nodes ?? []) {
+        if (node.part && !out.includes(node.part))
+            out.push(node.part);
+        if (node.children)
+            treeParts(node.children, out);
+    }
+    return out;
+}
+/**
+ * THE COMPOSITION, EMITTED AS JSX RATHER THAN DESCRIBED IN A COMMENT.
+ *
+ * This is the third thing the anatomy was supposed to buy, in the owner's own
+ * words: speed, and fewer tokens spent in Claude Code. `<ArticleCard />` used to
+ * render an empty shell, and assembling it meant an agent reading a JSDoc example
+ * and writing the tree by hand - every time, for every component. Now the tree is
+ * in the file.
+ *
+ * A frontier is a COMMENT, never invented markup. A component of theirs has a
+ * recipe of its own and the generated sibling may not exist yet; a third-party
+ * library is not ours to render. Both say what belongs there and leave the slot
+ * open, which is the honest instruction.
+ */
+function emitTree(nodes, comp, indent) {
+    const lines = [];
+    for (const node of nodes) {
+        if (node.as === "component") {
+            lines.push(`${indent}{/* your <${pascal(node.ref ?? "")} /> goes here - it has a recipe of its own, so it is not inlined */}`);
+            continue;
+        }
+        if (node.as === "external") {
+            lines.push(`${indent}{/* ${node.from} renders here - a third party's component, so its markup is theirs */}`);
+            continue;
+        }
+        if (!node.part) {
+            // Pure structure with no styles of its own: keep the arrangement, skip the
+            // element - a div that carries nothing is a div nobody needs.
+            if (node.children)
+                lines.push(emitTree(node.children, comp, indent));
+            continue;
+        }
+        const partComp = `${comp}${pascal(node.part)}`;
+        if (ARRANGES.has(node.as) && node.children && node.children.length > 0) {
+            lines.push(`${indent}<${partComp}>`);
+            lines.push(emitTree(node.children, comp, `${indent}  `));
+            lines.push(`${indent}</${partComp}>`);
+            continue;
+        }
+        const { voidEl } = FORM_TAG[node.as] ?? {};
+        if (voidEl) {
+            lines.push(`${indent}<${partComp} />`);
+            continue;
+        }
+        lines.push(`${indent}<${partComp}>${node.text ?? `{/* ${node.part} */}`}</${partComp}>`);
+    }
+    return lines.filter(Boolean).join("\n");
+}
 /** JSDoc showing how to compose the component with its parts + content, so the
  *  materialized code doesn't read as "a bare shell renders nothing" (dogfood
  *  #5). Built from the recipe's parts. */
 function compositionHint(comp, name, recipe, voidEl = false) {
+    const tree = recipe.preview?.parts;
     const partNames = Object.keys(recipe.parts ?? {});
     // An `<input>` or `<hr>` takes no children, and telling somebody to put
     // content inside one is an instruction that throws. With parts, the element
@@ -489,6 +590,16 @@ function compositionHint(comp, name, recipe, voidEl = false) {
     if (voidEl) {
         return `/** Wears the "${name}" recipe. Takes no children - it renders a single void element. */`;
     }
+    if (tree && tree.length > 0) {
+        // The shape is IN the file below, so the comment stops teaching assembly and
+        // starts saying what is already there and how to change it.
+        return `/**
+ * Wears the "${name}" recipe, composed as your own code composes it - the shape
+ * below was read out of your JSX, so it renders as the component rather than as
+ * an empty shell. Replace the placeholders with your content; every part is also
+ * exported on its own if you need a different arrangement.
+ */`;
+    }
     if (partNames.length === 0) {
         return `/** Wears the "${name}" recipe. Put your content inside: <${comp}>…</${comp}>. */`;
     }
@@ -503,37 +614,112 @@ ${inner}
  *   </${comp}>
  */`;
 }
-function emitCssMode(slug, name, recipe, version, props) {
+/**
+ * WHICH TAG A PART GETS, and the tree is what finally lets this be right.
+ *
+ * A part that styles focus is a control and has always been promoted to a button
+ * - that check stays and still wins, because a focus ring is a stronger statement
+ * than a name. Below it, the tree's `as` decides: a heading is an `<h3>`, an image
+ * an `<img>`, a field an `<input>`. Without a tree everything falls back to `div`,
+ * which is exactly what every part used to be.
+ */
+function partTagFor(part, form) {
+    if (partIsInteractive(part)) {
+        return { tag: "button", attrs: ' type="button"', voidEl: false };
+    }
+    const mapped = form ? FORM_TAG[form] : undefined;
+    if (!mapped)
+        return { tag: "div", attrs: "", voidEl: false };
+    return {
+        tag: mapped.tag,
+        /**
+         * `type="button"` IS NOT OPTIONAL ON A BUTTON.
+         *
+         * A `<button>` with no type defaults to `submit`, so the moment one of these
+         * parts sits inside a form, clicking it submits the form. `asElement` already
+         * knows how to carry this through the `as` escape hatch - it just needs to be
+         * told, and the interactive branch above was the only caller telling it.
+         *
+         * An `<img>` with no `alt` is an accessibility failure the generator would be
+         * authoring, so it ships with an empty one: decorative by default, and the
+         * caller overrides it through `...props` the moment it carries meaning.
+         */
+        attrs: mapped.tag === "button"
+            ? ' type="button"'
+            : mapped.tag === "img"
+                ? ' alt=""'
+                : "",
+        voidEl: Boolean(mapped.voidEl),
+    };
+}
+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
+    // destructure and a real closing tag rather than a self-closing one.
+    const hasShape = tree.length > 0 && !voidEl;
     const destructure = [
         ...propNames,
         ...(el.offersAs ? ["as"] : []),
+        ...(hasShape ? ["children"] : []),
         "className",
         "...props",
     ].join(", ");
-    const rootJsx = `    <${el.jsxTag}${el.jsxAttrs}\n      className={${joinCls([`"ds-${name}"`, "className"])}}\n${dataAttrLines(axes)}${axes.length ? "\n" : ""}      {...props}\n    />`;
-    const parts = Object.entries(recipe.parts ?? {}).map(([partName, part]) => {
+    const rootOpen = `    <${el.jsxTag}${el.jsxAttrs}\n      className={${joinCls([`"${elementClass(name, convention)}"`, "className"])}}\n${dataAttrLines(axes)}${axes.length ? "\n" : ""}      {...props}\n    `;
+    const rootJsx = hasShape
+        ? `${rootOpen}>\n${emitTree(tree, comp, "      ")}\n      {children}\n    </${el.jsxTag}>`
+        : `${rootOpen}/>`;
+    // Tree order first, because that is the order somebody reads them in the file;
+    // anything the tree does not mention still gets its component.
+    const ordered = [
+        ...treeParts(recipe.preview?.parts).filter((p) => recipe.parts?.[p]),
+        ...Object.keys(recipe.parts ?? {}).filter((p) => !treeParts(recipe.preview?.parts).includes(p)),
+    ];
+    const formOf = new Map();
+    const collect = (nodes) => {
+        for (const node of nodes) {
+            if (node.part)
+                formOf.set(node.part, node.as);
+            if (node.children)
+                collect(node.children);
+        }
+    };
+    collect(tree);
+    const parts = ordered.map((partName) => {
+        const part = recipe.parts?.[partName];
+        if (!part)
+            return "";
         const partAxes = axesOf(part.variants ?? {});
         const partComp = `${comp}${pascal(partName)}`;
-        const control = partIsInteractive(part);
-        const partTag = control ? "button" : "div";
-        const partEl = asElement(partTag, control ? ' type="button"' : "", false);
+        const { tag: partTag, attrs: partAttrs, voidEl: partVoid, } = partTagFor(part, formOf.get(partName));
+        const partEl = asElement(partTag, partAttrs, partVoid);
+        /**
+         * `as` ONLY WHERE THE ELEMENT HONOURS IT.
+         *
+         * A void element ignores it - `asElement` says so with `offersAs: false` - so
+         * typing and destructuring it anyway would declare a prop that silently does
+         * nothing. This file already paid for that exact shape once, on a different
+         * prop, and no part could be void until the tree started naming images and
+         * fields.
+         */
         const partDestructure = [
             ...partAxes.map((a) => a.prop),
-            "as",
+            ...(partEl.offersAs ? ["as"] : []),
             "className",
             "...props",
         ].join(", ");
         return `
-/** Part "${partName}" of ${comp} - compose it inside <${comp}>. */
-export function ${partComp}({ ${partDestructure} }: ${propsType(partAxes, partTag, props, true)}) {
+/** Part "${partName}" of ${comp}${formOf.get(partName) ? ` (${formOf.get(partName)})` : ""} - compose it inside <${comp}>. */
+export function ${partComp}({ ${partDestructure} }: ${propsType(partAxes, partTag, props, partEl.offersAs)}) {
 ${partEl.setup}  return (
     <${partEl.jsxTag}${partEl.jsxAttrs}
-      className={${joinCls([`"ds-${name}-${kebab(partName)}"`, "className"])}}
+      className={${joinCls([`"${partClassName(name, partName, convention)}"`, "className"])}}
 ${dataAttrLines(partAxes)}${partAxes.length ? "\n" : ""}      {...props}
     />
   );
@@ -541,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";
 
@@ -553,13 +739,15 @@ ${el.setup}  return (
 ${rootJsx}
   );
 }
-${parts.join("\n")}`;
+${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) => {
@@ -584,13 +772,37 @@ function emitTailwindMode(slug, name, recipe, version, props) {
             : `${a.prop} ? ${a.prop.toUpperCase()}[${a.prop}] : ${fallbackFor(a)}`),
         "className",
     ];
+    const tree = recipe.preview?.parts ?? [];
+    // Same as css mode: with a shape the root renders its children, so it needs
+    // `children` and a real closing tag. The CLASSES differ between flavours; the
+    // SHAPE is the same fact about their component either way.
+    const hasShape = tree.length > 0 && !voidEl;
     const destructure = [
         ...axes.map((a) => a.prop),
         ...(el.offersAs ? ["as"] : []),
+        ...(hasShape ? ["children"] : []),
         "className",
         "...props",
     ].join(", ");
     const needsElementType = el.offersAs || Object.keys(recipe.parts ?? {}).length > 0;
+    const formOf = new Map();
+    const collect = (nodes) => {
+        for (const node of nodes) {
+            if (node.part)
+                formOf.set(node.part, node.as);
+            if (node.children)
+                collect(node.children);
+        }
+    };
+    collect(tree);
+    const treeOrder = treeParts(recipe.preview?.parts);
+    const orderedParts = [
+        ...treeOrder.filter((p) => recipe.parts?.[p]),
+        ...Object.keys(recipe.parts ?? {}).filter((p) => !treeOrder.includes(p)),
+    ];
+    const rootOpen = `    <${el.jsxTag}${el.jsxAttrs}
+      className={${resolveCls(clsParts)}}
+${dataAttrLines(axes)}${axes.length ? "\n" : ""}    `;
     return `${header(slug, name, version, "tailwind")}
 
 import type { ${needsElementType ? `ElementType, ${props}` : props} } from "react";
@@ -604,19 +816,25 @@ type ${comp}Props = ${propsType(axes, tag, props, el.offersAs)};
 ${compositionHint(comp, name, recipe, voidEl)}
 export function ${comp}({ ${destructure} }: ${comp}Props) {
 ${el.setup}  return (
-    <${el.jsxTag}${el.jsxAttrs}
-      className={${resolveCls(clsParts)}}
-${dataAttrLines(axes)}${axes.length ? "\n" : ""}      {...props}
-    />
+${hasShape
+        ? `${rootOpen}  {...props}
+    >
+${emitTree(tree, comp, "      ")}
+      {children}
+    </${el.jsxTag}>`
+        : `${rootOpen}  {...props}
+    />`}
   );
 }
-${Object.entries(recipe.parts ?? {})
-        .map(([partName, part]) => {
+${orderedParts
+        .map((partName) => {
+        const part = recipe.parts?.[partName];
+        if (!part)
+            return "";
         const partComp = `${comp}${pascal(partName)}`;
         const partAxes = axesOf(part.variants ?? {});
-        const control = partIsInteractive(part);
-        const partTag = control ? "button" : "div";
-        const partEl = asElement(partTag, control ? ' type="button"' : "", false);
+        const { tag: partTag, attrs: partAttrs, voidEl: partVoid, } = partTagFor(part, formOf.get(partName));
+        const partEl = asElement(partTag, partAttrs, partVoid);
         /**
          * THE STATE THE CATALOGUE DOCUMENTS, DELIVERED (1kro2o, 29/07).
          *
@@ -637,15 +855,24 @@ ${Object.entries(recipe.parts ?? {})
         const partCls = [tailwindClassList(part), ...partVariantClasses]
             .filter(Boolean)
             .join(" ");
+        /**
+         * `as` ONLY WHERE THE ELEMENT HONOURS IT.
+         *
+         * A void element ignores it - `asElement` says so with `offersAs: false` - so
+         * typing and destructuring it anyway would declare a prop that silently does
+         * nothing. This file already paid for that exact shape once, on a different
+         * prop, and no part could be void until the tree started naming images and
+         * fields.
+         */
         const partDestructure = [
             ...partAxes.map((a) => a.prop),
-            "as",
+            ...(partEl.offersAs ? ["as"] : []),
             "className",
             "...props",
         ].join(", ");
         return `
-/** Part "${partName}" of ${comp} - compose it inside <${comp}>. */
-export function ${partComp}({ ${partDestructure} }: ${propsType(partAxes, partTag, props, true)}) {
+/** Part "${partName}" of ${comp}${formOf.get(partName) ? ` (${formOf.get(partName)})` : ""} - compose it inside <${comp}>. */
+export function ${partComp}({ ${partDestructure} }: ${propsType(partAxes, partTag, props, partEl.offersAs)}) {
 ${partEl.setup}  return (
     <${partEl.jsxTag}${partEl.jsxAttrs}
       className={${resolveCls([JSON.stringify(partCls), "className"])}}
@@ -654,33 +881,50 @@ ${dataAttrLines(partAxes)}${partAxes.length ? "\n" : ""}      {...props}
   );
 }`;
     })
+        .filter(Boolean)
         .join("\n")}`;
 }
 /** All files for one component, under `<componentsDir>/<name>/`. */
 export function generateComponentFiles(slug, name, recipe, css, version, styles, 
 /** Consumer's React major, read from its package.json. Null = unknown, which
  *  keeps the ref-less type rather than guessing in the unsafe direction. */
-reactMajor = null) {
-    const comp = pascal(name);
+reactMajor = null, 
+/**
+ * HOW THE SYSTEM SPELLS A CLASS, from the registry. Absent = ours, which is
+ * 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, 
+/**
+ * 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)}\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/doctor/dependencies.js

@@ -0,0 +1,90 @@
+/**
+ * THE LIBRARIES THE SYSTEM SAYS YOU NEED, CHECKED AGAINST WHAT YOU HAVE.
+ *
+ * Some of somebody's components are built on a third-party library - a
+ * `TextEditor` on tiptap, a chart on recharts. We do not have that library, will
+ * never have it, and cannot draw it, so the anatomy stops at the frontier and the
+ * value moves into a RULE: `TextEditor requires @tiptap/react`.
+ *
+ * A rule nobody checks is a sentence. This is the half that makes it governance:
+ * the rule carries the package name as a field, and here we read the consumer's
+ * own manifest and say what is missing.
+ *
+ * TWO THINGS IT DELIBERATELY DOES NOT DO.
+ *
+ * It never installs. Installing a package on somebody's behalf is exactly the
+ * class of thing this product does not do - the agent reports and ASKS, because a
+ * dependency is a decision with a licence, a bundle cost and a maintainer
+ * attached (dono, 01/08).
+ *
+ * It never checks a VERSION. The rule carries the name and the evidence carries
+ * the range their own project pinned - `^2.1.0 in packages/ui` - which is
+ * information, not a requirement. Turning it into one would mean failing somebody
+ * for upgrading a library we do not ship, and the range would be stale the day
+ * after it was measured.
+ */
+/**
+ * Every required package this project does not have.
+ *
+ * `deps` is the merged dependencies + devDependencies of the nearest manifests -
+ * `resolveDeps` in `stack.ts`, the same reader the stack detection uses, so a
+ * monorepo's root and package manifests both count.
+ *
+ * A package needed by three components is ONE finding with three names on it, not
+ * three findings: the action is a single install, and repeating it would make a
+ * well-factored system look like it has more problems than a badly factored one.
+ */
+export function missingDependencies(rules, deps) {
+    const byName = new Map();
+    for (const rule of rules) {
+        const name = rule.requires?.trim();
+        if (!name)
+            continue;
+        // Present is present. We do not compare ranges - see the note above.
+        if (Object.hasOwn(deps, name))
+            continue;
+        const held = byName.get(name);
+        // The component the rule is about, which is what the reader needs in order to
+        // decide whether they even use that part of the system.
+        const owners = (rule.applies ?? []).filter(Boolean);
+        if (held) {
+            for (const owner of owners) {
+                if (!held.neededBy.includes(owner))
+                    held.neededBy.push(owner);
+            }
+            held.pinned ??= rule.pinned;
+            continue;
+        }
+        byName.set(name, {
+            name,
+            neededBy: [...new Set(owners)],
+            ...(rule.pinned ? { pinned: rule.pinned } : {}),
+        });
+    }
+    return [...byName.values()];
+}
+/**
+ * What the doctor prints, and the wording is the point.
+ *
+ * This is not drift and it is not a mistake: the author's own project has the
+ * library, and the project being checked is a DIFFERENT one that has not installed
+ * it yet. So it reads as a prerequisite, names who needs it, and stops - the
+ * install command is offered, never run.
+ */
+export function describeMissing(missing) {
+    const lines = [];
+    for (const dep of missing) {
+        const who = dep.neededBy.length > 0
+            ? `${dep.neededBy.map((n) => `ds-${n}`).join(", ")} need${dep.neededBy.length === 1 ? "s" : ""} it`
+            : "part of this system needs it";
+        lines.push(`${dep.name}  not in your manifest - ${who}${dep.pinned ? ` (${dep.pinned})` : ""}`);
+    }
+    return lines;
+}
+/** The one sentence above the list, once. */
+export function summarizeMissing(missing) {
+    if (missing.length === 0)
+        return null;
+    const n = missing.length;
+    return `${n} librar${n === 1 ? "y this system needs is" : "ies this system needs are"} not installed here. ${n === 1 ? "It is" : "They are"} a third party's, not ours - so nothing was installed for you, and the components that need ${n === 1 ? "it" : "them"} will not render until you decide.`;
+}

package/dist/doctor/transcribe.js

@@ -123,6 +123,58 @@ const TAILWIND_COLOR = {
     "neutral-900": "#171717",
     "neutral-950": "#0a0a0a",
 };
+/**
+ * TYPOGRAPHY, and the reason it is here at all.
+ *
+ * Colour, spacing and radius were read and type was not, so every text part of
+ * every imported component arrived with an EMPTY style block. Structurally the
+ * anatomy was right and a card's title still previewed at body size - which is
+ * the same "it is not a version of the component" complaint one layer down, and
+ * the spec view's whole `type` line never fired because there was nothing to
+ * report (dono, 01/08).
+ *
+ * Same argument as the tables above: Tailwind's type scale is fixed and
+ * published, so reading it is arithmetic rather than a guess. Their own
+ * `--text-*` and `--font-weight-*` tokens win, exactly as with colour.
+ */
+const FONT_SIZE = {
+    xs: "0.75rem",
+    sm: "0.875rem",
+    base: "1rem",
+    lg: "1.125rem",
+    xl: "1.25rem",
+    "2xl": "1.5rem",
+    "3xl": "1.875rem",
+    "4xl": "2.25rem",
+    "5xl": "3rem",
+    "6xl": "3.75rem",
+    "7xl": "4.5rem",
+};
+const FONT_WEIGHT = {
+    thin: "100",
+    extralight: "200",
+    light: "300",
+    normal: "400",
+    medium: "500",
+    semibold: "600",
+    bold: "700",
+    extrabold: "800",
+    black: "900",
+};
+/** The three family slots the document actually has. Nothing else may be a ref. */
+const FAMILY_SLOT = {
+    sans: "body",
+    serif: "display",
+    mono: "mono",
+};
+/** Type utilities with no scale behind them - a fact, not a decision deferred. */
+const TYPE_KEYWORD = {
+    uppercase: { property: "textTransform", value: "uppercase" },
+    lowercase: { property: "textTransform", value: "lowercase" },
+    capitalize: { property: "textTransform", value: "capitalize" },
+    italic: { property: "fontStyle", value: "italic" },
+    underline: { property: "textDecoration", value: "underline" },
+};
 /** States we recognise. Anything else is skipped rather than invented. */
 const STATE = /^(hover|focus|focus-visible|active|disabled|checked)$/;
 const DATA_STATE = /^data-\[([a-z-]+)\]$/;
@@ -164,6 +216,11 @@ export function readUtility(utility, declared) {
     // would mean computing a colour they never wrote. The property still belongs
     // in the recipe, so the base colour travels and the alpha does not.
     const [core] = utility.split("/");
+    // A bare keyword carries a declaration with no scale behind it, so it is read
+    // before the dash split that everything else needs.
+    const keyword = TYPE_KEYWORD[core];
+    if (keyword)
+        return keyword;
     const dash = core.indexOf("-");
     if (dash === -1)
         return null;
@@ -180,6 +237,66 @@ export function readUtility(utility, declared) {
         const builtin = TAILWIND_COLOR[rest];
         if (builtin)
             return { property: colorProp, value: builtin };
+        /**
+         * `text-` IS AMBIGUOUS, and only this branch knows it failed.
+         *
+         * `text-white` is a colour and `text-2xl` is a size, and both arrive with the
+         * same prefix. Returning null here dropped every font size in the codebase in
+         * silence - so a `text` that resolved to no colour falls through to the type
+         * scale instead of ending the read.
+         */
+        if (prefix !== "text")
+            return null;
+    }
+    if (prefix === "text") {
+        /**
+         * A SIZE TRAVELS AS A LITERAL, and that is not a shortcut.
+         *
+         * The document holds `typography.scale` as named STYLES (size plus line
+         * height plus weight), not as a flat table of lengths - so there is no ref a
+         * `font-size` can point at, and inventing `{typography.sizes.lg}` would emit
+         * a token that resolves to nothing. That renders as no size at all, which is
+         * worse than the literal and reads as a missing style.
+         *
+         * So the value they wrote travels, and the spec view marks it as an open
+         * decision - which is exactly what it is: a real length with no step of
+         * theirs to land on yet. That is the v2's to propose, not ours to fabricate.
+         */
+        const own = `--text-${rest}`;
+        const theirs = declared.get(own);
+        // Their own declaration outranks Tailwind's default for the same name.
+        if (theirs)
+            return { property: "fontSize", value: theirs, token: own };
+        if (FONT_SIZE[rest])
+            return { property: "fontSize", value: FONT_SIZE[rest] };
+        return null;
+    }
+    if (prefix === "font") {
+        // A family (`font-sans`) and a weight (`font-bold`) share this prefix, and
+        // the weight table is what tells them apart.
+        if (FONT_WEIGHT[rest]) {
+            /**
+             * ALSO A LITERAL, for a reason worth writing down: a weight ref is a valid
+             * SHAPE and still not safe. `{typography.weights.bold}` dangles on a system
+             * whose document declares `regular / medium / semibold` - and this side has
+             * no document to ask, because the CLI runs before one exists. A number
+             * renders correctly everywhere and the spec view marks it as the open
+             * decision it is.
+             */
+            return { property: "fontWeight", value: FONT_WEIGHT[rest] };
+        }
+        // A family DOES have a safe ref: the document's `families` is a fixed
+        // display/body/mono, so only those three map and anything else is skipped
+        // rather than pointed at a slot that does not exist.
+        const slot = FAMILY_SLOT[rest];
+        const family = `--font-${rest}`;
+        if (slot && declared.has(family)) {
+            return {
+                property: "fontFamily",
+                value: `{typography.families.${slot}}`,
+                token: family,
+            };
+        }
         return null;
     }
     const spaceProp = SPACING_PROPERTY[prefix];