synthesisui 0.16.116 → 0.16.118

package/dist/commands/import.js

@@ -13,7 +13,7 @@ import { describeGate, gateComponent, groupSkips, SCREENS_FOR_SYSTEM, } from "..
 import { emptyTally, internalSpecifiers, scanComponentsInto, tallyToInventory, } from "../doctor/components-scan.js";
 import { countShape, describeCoverage, summarizeCoverage, } from "../doctor/coverage.js";
 import { crosswalk, floorSize, isLibrary, observedRules, useLiveCatalogue, } from "../doctor/crosswalk.js";
-import { moduleImports, readModuleCss, readModuleUsage, transcribeModule, } from "../doctor/css-modules.js";
+import { keyframeOffsets, moduleImports, readModuleCss, readModuleUsage, transcribeModule, } from "../doctor/css-modules.js";
 import { reconcile, scanDefinitions, } from "../doctor/definitions-scan.js";
 import { describeConvention, describeRemainder, detectConventions, } from "../doctor/idiom.js";
 import { callSiteNode, placeLayers, } from "../doctor/place-layers.js";
@@ -22,9 +22,11 @@ import { diagnose, scanSource } from "../doctor/scan.js";
 import { parseSchemeBlocks } from "../doctor/scheme-blocks.js";
 import { describeSignals, emptySignals, finishSignals, readSignalsInto, } from "../doctor/signals.js";
 import { sketchOf } from "../doctor/sketch.js";
+import { describeForeign, readStyleIslands, } from "../doctor/style-island.js";
 import { buildTable } from "../doctor/tokens.js";
 import { readInlineStyle, rootClasses, rootTag, transcribe, } from "../doctor/transcribe.js";
 import { transcribeVariants } from "../doctor/variant-read.js";
+import { frontierKind } from "../frontier-kind.js";
 import { withLibraryStructure } from "../library-structure.js";
 import { body, paint, section } from "../output.js";
 import { phase, startProgress } from "../progress.js";
@@ -306,7 +308,20 @@ export async function takeCensus(root, opts) {
     /** How much came out of CSS Modules, for the coverage report. */
     let moduleFiles = 0;
     let moduleDeclarations = 0;
-    const moduleKeyframes = {};
+    /**
+     * THE KEYFRAMES THE READING NEEDS, by name - and this was collected and dropped.
+     *
+     * Nothing read `moduleKeyframes`: an app whose animation lives in a CSS module lost it
+     * in silence, and the four Tailwind ships had nowhere to travel either, so
+     * `animation: var(--animate-spin)` would have pointed at a keyframe the system does not
+     * define (dono, 04/08). The document's shape is offset → declarations, which is what
+     * `keyframeOffsets` turns their raw body into and what `BUILTIN_KEYFRAMES` already is.
+     */
+    const keyframes = {};
+    /** Names their `animate-*` utilities point at - see `Transcription.animations`. */
+    const animations = new Set();
+    /** Per component, the rules a `<style>` island aims at somebody else's markup. */
+    const islands = new Map();
     /** How each component expresses style, so the census can state its own coverage. */
     const shapes = new Map();
     /** Component FILES the gate accepted - the honest denominator for coverage. A first
@@ -484,8 +499,9 @@ export async function takeCensus(root, opts) {
                     moduleFiles += 1;
                     moduleDeclarations += readModule.read;
                     for (const [name, frames] of Object.entries(readModule.keyframes)) {
-                        if (!moduleKeyframes[name])
-                            moduleKeyframes[name] = frames;
+                        const offsets = keyframeOffsets(frames);
+                        if (!keyframes[name] && Object.keys(offsets).length > 0)
+                            keyframes[name] = offsets;
                     }
                     // One module per component is the shape every one of the 530 follows.
                     break;
@@ -527,6 +543,83 @@ export async function takeCensus(root, opts) {
                  * the owner's rule, adopted verbatim (dono, 01/08).
                  */
                 const sketch = sketchOf(src, found[0].name);
+                /**
+                 * THE CSS THE COMPONENT CARRIES INSIDE ITSELF.
+                 *
+                 * Their `TypingIndicator` styles with a `<style>` element and nothing else: read as
+                 * utilities it arrived with three declarations and no animation, so the component
+                 * that IS an animation previewed as three static circles (dono, 04/08). Three kinds
+                 * of content, three destinations - see `readStyleIslands`.
+                 */
+                const writes = new Set();
+                for (const node of sketch)
+                    for (const cls of (node.classes ?? "").split(/\s+/))
+                        if (cls)
+                            writes.add(cls);
+                const island = readStyleIslands(src, writes);
+                /** Sketch index → what the island declares for that element. */
+                const islandStyle = {};
+                for (const [name, frames] of Object.entries(island.keyframes)) {
+                    keyframes[name] ??= frames;
+                    animations.add(name);
+                }
+                /**
+                 * A PATCH OVER SOMEBODY ELSE'S MARKUP IS A LAW, never a part: giving
+                 * `.sketch-picker input` a part of ours would claim we drew a colour wheel.
+                 */
+                /**
+                 * A RULE ON A CLASS THEY WRITE IS THE LOOK OF THE PART THAT WEARS IT.
+                 *
+                 * Their three dots are three sketch nodes all carrying `class="dot"`, and the
+                 * anatomy already named them `dot`, `dot-2`, `dot-3` - three parts with EMPTY
+                 * bases, because a utility reader has nothing to read on them. The island's `.dot`
+                 * rule is their shared look and `:nth-child(1..3)` is the delay that makes the
+                 * wave, one per part, in the order the nodes appear.
+                 *
+                 * Carried on the look and merged when the anatomy resolves, which is the only
+                 * moment a class maps to a part name - the same seam the per-part layers use.
+                 */
+                if (island.own.length > 0) {
+                    const seen = new Map();
+                    for (const [index, node] of sketch.entries()) {
+                        for (const cls of (node.classes ?? "").split(/\s+/)) {
+                            if (!cls)
+                                continue;
+                            const nth = (seen.get(cls) ?? 0) + 1;
+                            seen.set(cls, nth);
+                            const mine = island.own.filter((rule) => rule.class === cls && (rule.nth ?? nth) === nth);
+                            if (mine.length === 0)
+                                continue;
+                            islandStyle[index] = Object.assign(islandStyle[index] ?? {}, ...mine.map((rule) => rule.declarations));
+                        }
+                    }
+                }
+                if (island.foreign.length > 0) {
+                    /**
+                     * WHOSE MARKUP IS BEING PATCHED, measured rather than guessed: the opaque
+                     * package this component composes. A headless one renders no markup of its own
+                     * to patch.
+                     */
+                    const drawn = sketch.find((node) => node.from && frontierKind(node.from) === "opaque")?.from;
+                    islands.set(found[0].name, { foreign: island.foreign, drawn });
+                }
+                /**
+                 * THE ANIMATIONS THIS COMPONENT NAMES, from the whole sketch rather than from the
+                 * root's transcription - an `animate-ping` lives on a part three levels down and
+                 * the resolver that reads a part does not report back up.
+                 *
+                 * The NAME only. The platform owns a library of frames and gives each one this
+                 * system's own clock; a name it cannot define becomes a dangling reference the
+                 * screen already knows how to say out loud, which beats a silent `animation` that
+                 * animates nothing.
+                 */
+                for (const node of sketch) {
+                    for (const raw of (node.classes ?? "").split(/\s+/)) {
+                        const named = /^(?:[\w-]+:)*animate-([a-z][\w-]*)$/.exec(raw);
+                        if (named && named[1] !== "none")
+                            animations.add(named[1]);
+                    }
+                }
                 /**
                  * A PER-PART LAYER FINDS ITS NODE, by the class string of the call site that
                  * consumes the field. See `ReadLayer.onClasses`: the reader knows a
@@ -567,6 +660,7 @@ export async function takeCensus(root, opts) {
                         ...(tag ? { rootTag: tag } : {}),
                         ...rootPackage(tag, sketch),
                         ...(placed.length > 0 ? { layers: placed } : {}),
+                        ...(Object.keys(islandStyle).length > 0 ? { islandStyle } : {}),
                         ...(v.unslotted.length > 0
                             ? { unplaced: [...new Set(v.unslotted)] }
                             : {}),
@@ -1014,6 +1108,19 @@ export async function takeCensus(root, opts) {
      * happens, which is the whole reason `--usage` exists.
      */
     const laws = new Map();
+    /**
+     * A PATCH OVER SOMEBODY ELSE'S MARKUP IS A LAW, and it is written here because this is
+     * where laws are collected - giving `.sketch-picker input` a part of ours would claim we
+     * drew a colour wheel. See `readStyleIslands`.
+     */
+    for (const [name, read] of islands) {
+        const line = describeForeign(read.foreign, read.drawn);
+        if (!line)
+            continue;
+        const own = laws.get(name) ?? [];
+        own.push(line);
+        laws.set(name, own);
+    }
     for (const r of observedRules(merged)) {
         laws.set(r.component, [...(laws.get(r.component) ?? []), r.text]);
     }
@@ -1127,6 +1234,8 @@ export async function takeCensus(root, opts) {
         census: 1,
         project: { name, stack: await detectStack(root) },
         declared: Object.fromEntries(table.byName),
+        ...(Object.keys(keyframes).length > 0 ? { keyframes } : {}),
+        ...(animations.size > 0 ? { animations: [...animations].sort() } : {}),
         ...(brokenRefs.length > 0 ? { brokenRefs } : {}),
         ...(conventions.length > 0 ? { conventions } : {}),
         classStyle,
@@ -1903,6 +2012,26 @@ async function resolveReadParts(census, root) {
         const split = placeLayers((look?.layers ?? []), partAt, (look?.sketch ?? []));
         for (const line of split.unplaced)
             notes.add(line);
+        /**
+         * WHAT A `<style>` ISLAND DECLARED, ONTO THE PART THAT WEARS IT.
+         *
+         * Their three dots share `class="dot"` and the anatomy named them `dot`, `dot-2`,
+         * `dot-3` - three parts with empty bases, because a utility reader has nothing to read
+         * on a component that styles itself in CSS. This is the first moment an index maps to a
+         * part name, which is why it happens here and not where the island was read.
+         *
+         * A utility of theirs on the same element still wins: the island only fills what the
+         * class string did not already say.
+         */
+        for (const [index, style] of Object.entries(look?.islandStyle ?? {})) {
+            const part = partAt[Number(index)];
+            const target = part ? resolved.parts[part] : undefined;
+            if (!target) {
+                notes.add("a `<style>` element declares a look for an element the anatomy does not name - it is not applied, because that would paint the wrong thing");
+                continue;
+            }
+            target.base = { ...style, ...target.base };
+        }
         /**
          * REPLACED, NOT APPENDED - because this runs more than once.
          *

package/dist/doctor/css-modules.js

@@ -74,7 +74,7 @@ export function partName(authored) {
         .replace(/^-|-$/g, "");
 }
 /** Comments out, so a `{` inside one cannot end a block early. */
-function stripCssComments(css) {
+export function stripCssComments(css) {
     return css.replace(/\/\*[\s\S]*?\*\//g, "");
 }
 function rules(css, media = null, out = []) {
@@ -168,6 +168,40 @@ function emptyClass() {
  * same way the utility reader does - so the value travels as `{radius.md}` rather than
  * as a literal, and the recipe re-themes.
  */
+/**
+ * A KEYFRAME'S OWN OFFSETS, so the document can hold it.
+ *
+ * `keyframes` carried the body as raw CSS text and it was collected and then dropped -
+ * `moduleKeyframes` in `import.ts` had no reader at all, so an app whose animation lives
+ * in a CSS module lost it in silence (dono, 04/08). The document's shape is offset →
+ * declarations, which is the same rule parser one level down.
+ */
+export function keyframeOffsets(body) {
+    const out = {};
+    for (const rule of rules(stripCssComments(body))) {
+        /**
+         * `0%,\n  100%` is one offset written across two lines. Kept verbatim it becomes a
+         * selector with a newline in it, which the compiler emits and the browser ignores.
+         */
+        const offset = rule.selector.replace(/\s+/g, " ").trim();
+        if (!offset)
+            continue;
+        const block = {};
+        for (const line of rule.body.split(";")) {
+            const at = line.indexOf(":");
+            if (at === -1)
+                continue;
+            const prop = line.slice(0, at).trim();
+            const value = line.slice(at + 1).trim();
+            if (!prop || !value)
+                continue;
+            block[prop.replace(/-([a-z])/g, (_, c) => c.toUpperCase())] = value;
+        }
+        if (Object.keys(block).length > 0)
+            out[offset] = block;
+    }
+    return out;
+}
 export function readModuleCss(css) {
     const out = { classes: {}, keyframes: {}, unslotted: [] };
     const clean = stripCssComments(css);

package/dist/doctor/style-island.js

@@ -0,0 +1,143 @@
+/**
+ * THE CSS A COMPONENT CARRIES INSIDE ITSELF.
+ *
+ * Some components do not style with utilities at all - they render a `<style>` element
+ * with real CSS in it. Their `TypingIndicator` is the whole case: three dots, one
+ * `@keyframes wave-bounce`, and a `.dot` rule with a per-dot delay. Read as utilities it
+ * arrived with three declarations and no animation, so the component that IS an animation
+ * previewed as three static circles (dono, 04/08).
+ *
+ * Measured across their repository: 2 islands, both in `packages/ui`, and none in any of
+ * the three apps - 1 keyframe, 6 rules on classes the component itself writes, 3 on a
+ * third party's internals, and 12 `!important`.
+ *
+ * THREE KINDS OF CONTENT, THREE DESTINATIONS, and telling them apart is the whole job:
+ *
+ *     @keyframes                     the system's motion vocabulary, by name
+ *     a rule on a class THEY write   the look of the part that wears that class
+ *     a rule on somebody else's      a patch over a third party: prose, never a look
+ *
+ * The last one is the line. `.sketch-picker input { background: … !important }` is not
+ * their component's anatomy - it is a re-skin of `react-color`'s own markup - and giving
+ * it a part would claim we drew something we did not. It travels as a law instead, with
+ * the package named and the `!important` said out loud.
+ */
+import { keyframeOffsets, readModuleCss, stripCssComments, } from "./css-modules.js";
+/** `<style>{`…`}</style>` and `<style>…</style>` - the two spellings in JSX. */
+const ISLAND = /<style[^>]*>\s*\{?\s*(?:`([\s\S]*?)`|([\s\S]*?))\s*\}?\s*<\/style>/g;
+/** `.dot:nth-child(2)` → the class and which one. A compound selector is foreign. */
+const OWN_SELECTOR = /^\.([\w-]+)(?::nth-child\((\d+)\))?$/;
+/**
+ * The CSS a component keeps inside itself, split by where each rule belongs.
+ *
+ * `writes` is the set of classes the component's own markup carries - from the sketch,
+ * which measured them. A selector naming one of those is about an element we know; any
+ * other selector is about markup somebody else renders.
+ */
+export function readStyleIslands(source, writes) {
+    const out = { keyframes: {}, own: [], foreign: [] };
+    ISLAND.lastIndex = 0;
+    for (const island of source.matchAll(ISLAND)) {
+        const raw = island[1] ?? island[2] ?? "";
+        if (!raw.trim())
+            continue;
+        /**
+         * COMMENTS OUT FIRST. Their `.dot` rule carries `/* Cor ocean-600 *``/` between two
+         * declarations, and the split-on-semicolon read it as part of the NEXT property's
+         * name - so `borderRadius` arrived as `/* Cor … *``/\n borderRadius`.
+         */
+        const body = stripCssComments(raw);
+        const read = readModuleCss(body);
+        for (const [name, frames] of Object.entries(read.keyframes)) {
+            const offsets = keyframeOffsets(frames);
+            if (Object.keys(offsets).length > 0)
+                out.keyframes[name] ??= offsets;
+        }
+        /**
+         * `readModuleCss` files a rule under each class it names, which is what a CSS module
+         * needs - a class there IS the export. Here the SELECTOR decides, because
+         * `.dark .sketch-picker span` names a class we write (`dark`) and is still about
+         * somebody else's span. So the rules are re-read off the body.
+         */
+        for (const rule of body.matchAll(/([^{}]+)\{([^{}]*)\}/g)) {
+            const selector = rule[1].trim().split("\n").pop()?.trim() ?? "";
+            if (!selector || selector.startsWith("@"))
+                continue;
+            // An offset inside a keyframe body is not a rule about an element.
+            if (/^(?:from|to|\d+%)(?:\s*,\s*(?:from|to|\d+%))*$/.test(selector))
+                continue;
+            const declarations = {};
+            let important = 0;
+            for (const line of rule[2].split(";")) {
+                const at = line.indexOf(":");
+                if (at === -1)
+                    continue;
+                const property = line.slice(0, at).trim();
+                let value = line.slice(at + 1).trim();
+                if (!property || !value)
+                    continue;
+                if (/!important$/.test(value)) {
+                    important += 1;
+                    value = value.replace(/\s*!important$/, "");
+                }
+                declarations[property.replace(/-([a-z])/g, (_m, c) => c.toUpperCase())] = value;
+            }
+            if (Object.keys(declarations).length === 0)
+                continue;
+            /**
+             * THEIR `animation: wave-bounce 1s infinite` NAMES A KEYFRAME THE SYSTEM OWNS.
+             *
+             * The compiler scopes every keyframe and mints `--animate-<name>` for it, so a raw
+             * name in a recipe points at nothing. The reference replaces the name and their own
+             * timing stays as longhands beside it - which is what makes the wave a wave.
+             */
+            if (declarations.animation) {
+                const named = /^([\w-]+)\s*(.*)$/.exec(declarations.animation.trim());
+                if (named && out.keyframes[named[1]]) {
+                    declarations.animation = `var(--animate-${named[1]})`;
+                    for (const part of named[2].split(/\s+/).filter(Boolean)) {
+                        if (/^\d+(?:\.\d+)?m?s$/.test(part))
+                            declarations.animationDuration ??= part;
+                        else if (part === "infinite" || /^\d+$/.test(part))
+                            declarations.animationIterationCount ??= part;
+                        else if (/^(linear|ease|ease-in|ease-out|ease-in-out|steps\(|cubic-bezier\()/.test(part))
+                            declarations.animationTimingFunction ??= part;
+                    }
+                }
+            }
+            const own = OWN_SELECTOR.exec(selector);
+            if (own && writes.has(own[1])) {
+                out.own.push({
+                    class: own[1],
+                    ...(own[2] ? { nth: Number(own[2]) } : {}),
+                    declarations,
+                });
+                continue;
+            }
+            out.foreign.push({
+                selector,
+                declarations: Object.keys(declarations).length,
+                important,
+            });
+        }
+    }
+    return out;
+}
+/**
+ * What a patch over somebody else's component is, said in one line.
+ *
+ * A law rather than a look: an agent reading this system needs to know the re-skin exists
+ * and that it leans on `!important`, and no part of ours should claim to have drawn it.
+ */
+export function describeForeign(rules, library) {
+    if (rules.length === 0)
+        return null;
+    const declarations = rules.reduce((n, r) => n + r.declarations, 0);
+    const important = rules.reduce((n, r) => n + r.important, 0);
+    const selectors = [...new Set(rules.map((r) => r.selector))].slice(0, 3);
+    return (`This component re-skins ${library ?? "a third party's markup"} from the inside: ` +
+        `${declarations} declaration${declarations === 1 ? "" : "s"} across ${rules.length} rule${rules.length === 1 ? "" : "s"} ` +
+        `in a \`<style>\` element it renders itself, on selectors that are not ours ` +
+        `(${selectors.join(", ")})${important > 0 ? `, ${important} of them \`!important\`` : ""}. ` +
+        `Those are not part styles and editing this system's tokens will not move them.`);
+}

package/dist/doctor/transcribe.js

@@ -449,6 +449,36 @@ const PLACE_KEYWORD = {
         value: "overflow:hidden|textOverflow:ellipsis|whiteSpace:nowrap",
     },
 };
+/**
+ * MOVEMENT IS A DECLARATION TOO, and 91 utilities of it were being dropped.
+ *
+ * Measured across their 36 components (dono, 04/08): 34 `transition-*` in 20 components,
+ * 23 `duration-*` in 16, 2 `ease-*`, 18 `animate-*` in 10. Their chevron turns over 300ms
+ * and their spinner spins - and the recipe said neither, so a rebuilt component snapped
+ * between states and sat still where it should turn.
+ *
+ * READ AS THE FOUR LONGHANDS, never as the shorthand. `transition-colors duration-200
+ * ease-out` is three utilities and three properties: composing them into one `transition`
+ * would mean guessing what the other two will be, and whichever landed last would erase
+ * the others. Longhands compose the way their own utilities do.
+ */
+const TRANSITION_PROPERTY = {
+    all: "all",
+    none: "none",
+    colors: "color, background-color, border-color, text-decoration-color, fill, stroke",
+    opacity: "opacity",
+    shadow: "box-shadow",
+    transform: "transform, translate, scale, rotate",
+    // Tailwind's bare `transition` is this set, and it is what 16 of theirs write.
+    "": "color, background-color, border-color, text-decoration-color, fill, stroke, opacity, box-shadow, transform, filter, backdrop-filter",
+};
+/** Tailwind's easing scale, verbatim - a curve nobody should retype. */
+const EASING = {
+    linear: "linear",
+    in: "cubic-bezier(0.4, 0, 1, 1)",
+    out: "cubic-bezier(0, 0, 0.2, 1)",
+    "in-out": "cubic-bezier(0.4, 0, 0.2, 1)",
+};
 /** `justify-between` → `space-between`, and the four that are not a straight copy. */
 const ALIGNMENT = {
     start: "flex-start",
@@ -616,6 +646,49 @@ function readUtilityCore(utility, declared) {
             }
             : { property: "borderRadius", value: "0.25rem" };
     }
+    /**
+     * TRANSITION, DURATION, EASING, DELAY - four utilities, four properties.
+     *
+     * 59 of these across their library, and the recipe carried none: a rebuilt component
+     * snapped between every state their own code eases through (dono, 04/08).
+     */
+    const bareTransition = /^transition(?:-(.+))?$/.exec(core);
+    if (bareTransition) {
+        const arg = bareTransition[1] ?? "";
+        const arbitrary = /^\[(.+)\]$/.exec(arg);
+        const value = arbitrary
+            ? arbitrary[1].replace(/_/g, " ")
+            : TRANSITION_PROPERTY[arg];
+        if (value)
+            return { property: "transitionProperty", value };
+    }
+    const ms = /^(duration|delay)-(\d+)$/.exec(core);
+    if (ms) {
+        return {
+            property: ms[1] === "duration" ? "transitionDuration" : "transitionDelay",
+            value: `${ms[2]}ms`,
+        };
+    }
+    const ease = /^ease-(.+)$/.exec(core);
+    if (ease && EASING[ease[1]]) {
+        return { property: "transitionTimingFunction", value: EASING[ease[1]] };
+    }
+    /**
+     * `animate-spin` - the animation, by the name the system defines it under.
+     *
+     * `var(--animate-spin)` rather than a shorthand of ours: the compiler mints that
+     * variable from the document's own keyframes and gives it this system's clock. The
+     * frames themselves travel beside the reading - see `BUILTIN_KEYFRAMES` - because a
+     * recipe cannot point at a keyframe the system does not define.
+     */
+    const animate = /^animate-([a-z][\w-]*)$/.exec(core);
+    if (animate && animate[1] !== "none") {
+        return {
+            property: "animation",
+            value: `var(--animate-${animate[1]})`,
+            keyframe: animate[1],
+        };
+    }
     /**
      * ALIGNMENT - `justify-between`, `items-center`, `self-end`.
      *
@@ -1552,6 +1625,11 @@ export function transcribe(classes, declared) {
                 out.fromLiteral += 1;
             continue;
         }
+        if (decl.keyframe) {
+            out.animations ??= [];
+            if (!out.animations.includes(decl.keyframe))
+                out.animations.push(decl.keyframe);
+        }
         if (target[decl.property] != null)
             continue;
         target[decl.property] = decl.value;

package/package.json

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