synthesisui 0.16.82 → 0.16.84

package/dist/commands/import.js

@@ -5,17 +5,20 @@ import { readCredentials, readToken, resolveRegistry, sameRegistry, } from "../c
 import { architectureRule, describeArchitecture, describeChoice, detectArchitectures, } from "../doctor/architecture.js";
 import { findBrokenRefs } from "../doctor/broken-refs.js";
 import { nestingRules, propRules, readDefinitionProps, readNesting, } from "../doctor/call-sites.js";
+import { asCatalogueTable, describeFallback, fetchCatalogue, } from "../doctor/catalogue-fetch.js";
 import { describeClassStyle, detectClassStyle, } from "../doctor/class-style.js";
 import { isNearDuplicate, isNeutral, lightness, } from "../doctor/color-distance.js";
-import { describeGate, gateComponent, groupSkips, } from "../doctor/component-gate.js";
+import { describeGate, gateComponent, groupSkips, SCREENS_FOR_SYSTEM, } from "../doctor/component-gate.js";
 import { emptyTally, internalSpecifiers, scanComponentsInto, tallyToInventory, } from "../doctor/components-scan.js";
-import { crosswalk, isLibrary, observedRules } from "../doctor/crosswalk.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 { reconcile, scanDefinitions, } from "../doctor/definitions-scan.js";
 import { describeConvention, describeRemainder, detectConventions, } from "../doctor/idiom.js";
 import { diagnose, scanSource } from "../doctor/scan.js";
 import { parseSchemeBlocks } from "../doctor/scheme-blocks.js";
 import { buildTable } from "../doctor/tokens.js";
-import { rootClasses, rootTag, transcribe, } from "../doctor/transcribe.js";
+import { readInlineStyle, rootClasses, rootTag, transcribe, } from "../doctor/transcribe.js";
 import { transcribeVariants } from "../doctor/variant-read.js";
 import { body, paint, section } from "../output.js";
 import { startProgress } from "../progress.js";
@@ -212,8 +215,36 @@ function distinctValues(d) {
     }
     return kept.sort((a, b) => b.count - a.count || a.value.localeCompare(b.value));
 }
+/**
+ * WHICH SCREEN A FILE BELONGS TO.
+ *
+ * The route segment, because that is what a framework already decided: everything under
+ * `app/dashboard/audience` is one screen however deep the folder goes. Route GROUPS are
+ * skipped - `(dashboard)` is an organisational parenthesis, not a place a person visits.
+ *
+ * For a project with no `app/` or `pages/`, the first two folders are the closest honest
+ * answer, and a library never reaches this because the test is skipped there.
+ */
+function screenOf(rel) {
+    const parts = rel.split("/");
+    const i = parts.findIndex((p) => p === "app" || p === "pages");
+    if (i === -1)
+        return parts.slice(0, 2).join("/");
+    const after = parts.slice(i + 1).filter((p) => !p.startsWith("("));
+    return `${parts[i]}/${after.slice(0, 2).join("/")}`;
+}
 export async function takeCensus(root, opts) {
     const scopeLabel = opts?.scopeLabel;
+    /**
+     * THE LIVE CATALOGUE, once, before anything is matched.
+     *
+     * The written table had 26 names against a catalogue of 41, so twenty of our own
+     * components were invisible to matching and their `Textarea` did not meet our
+     * `textarea` (dono, 01/08). Fetched rather than shipped, and the fallback is announced
+     * with what it costs - a smaller answer is fine, a silently smaller one is not.
+     */
+    const fetched = await fetchCatalogue(opts?.registry);
+    useLiveCatalogue(fetched.ok ? asCatalogueTable(fetched.index) : null);
     const css = await harvestOwnCss(root);
     const table = buildTable({ css, source: "yours" });
     const schemes = parseSchemeBlocks(css);
@@ -243,8 +274,24 @@ export async function takeCensus(root, opts) {
     const nesting = new Map();
     /** Component → what its own definition names and whether it forwards the rest. */
     const propsOf = new Map();
+    /**
+     * Component → the distinct SCREENS that compose it, which is what separates a design
+     * system from a folder: 242 of 271 in a real app live on one screen or none, and
+     * filtering them takes the vitrine from 271 to 29 (dono, 01/08).
+     */
+    const screensOf = new Map();
     /** Component → the axes its own `cva` declares. See `variant-read.ts`. */
     const variantAxes = new Map();
+    /** How much came out of CSS Modules, for the coverage report. */
+    let moduleFiles = 0;
+    let moduleDeclarations = 0;
+    const moduleKeyframes = {};
+    /** 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
+     *  version used the whole inventory, which includes everything they compose from a
+     *  package, and reported 128 for a library of 36 (probe, 01/08). */
+    let componentFiles = 0;
     /**
      * A census over a real monorepo reads 2797 files, and the terminal said nothing for
      * most of it. Twenty silent minutes is indistinguishable from twenty broken ones
@@ -287,6 +334,14 @@ export async function takeCensus(root, opts) {
             // HOW IT IS USED, not only what it is: which props people pass, what it passes
             // on, and what shows up inside it. See `call-sites.ts`.
             readNesting(rel, src, nesting);
+            // Which screen this file belongs to, and what it composes. One pass, and the
+            // answer is a count of PLACES rather than of occurrences - a loop is one place.
+            const screen = screenOf(rel);
+            for (const m of src.matchAll(/<([A-Z][A-Za-z0-9_]*)/g)) {
+                const at = screensOf.get(m[1]) ?? new Set();
+                at.add(screen);
+                screensOf.set(m[1], at);
+            }
             const found = [];
             for (const d of scanDefinitions(rel, src)) {
                 const verdict = gateComponent({
@@ -309,6 +364,10 @@ export async function takeCensus(root, opts) {
             for (const d of found) {
                 propsOf.set(d.name, readDefinitionProps(d.name, src));
             }
+            if (found.length > 0) {
+                countShape(src, found[0].name, shapes);
+                componentFiles += 1;
+            }
             defined.push(...found);
             // THE LOOK, from their own class names. One transcription per file, keyed
             // by the component it defines - the root element's classes are the
@@ -330,20 +389,77 @@ export async function takeCensus(root, opts) {
                  * paid for twice already.
                  */
                 const v = transcribeVariants(src, declaredValues);
-                const base = { ...v.base.base, ...t.base };
-                const states = { ...v.base.states, ...t.states };
+                /**
+                 * THE CSS MODULE, if this component styles that way.
+                 *
+                 * 239 of 317 components in a real app do, and they arrived with ZERO
+                 * declarations - 5,777 real CSS declarations sat in 530 stylesheets nobody
+                 * read (dono, 01/08). Read here rather than in a pass of its own so a
+                 * component that uses BOTH a module and utilities comes out as one look.
+                 */
+                const modules = moduleImports(src);
+                let fromModule = null;
+                for (const mod of modules) {
+                    const cssPath = join(dirname(file), mod.specifier);
+                    const moduleCss = await readFile(cssPath, "utf8").catch(() => "");
+                    if (!moduleCss)
+                        continue;
+                    const usage = readModuleUsage(src, mod.local);
+                    if (usage.length === 0)
+                        continue;
+                    const readModule = transcribeModule(readModuleCss(moduleCss), usage, declaredValues);
+                    if (readModule.read === 0)
+                        continue;
+                    fromModule = readModule;
+                    moduleFiles += 1;
+                    moduleDeclarations += readModule.read;
+                    for (const [name, frames] of Object.entries(readModule.keyframes)) {
+                        if (!moduleKeyframes[name])
+                            moduleKeyframes[name] = frames;
+                    }
+                    // One module per component is the shape every one of the 530 follows.
+                    break;
+                }
+                // The MODULE first and the utilities on top: a component that has both is
+                // adding a utility to a module-styled element, not the other way round.
+                /**
+                 * `style={{ }}` UNDER everything: a literal is the weakest source, so a class or
+                 * a module rule that names the same property wins. It travels rather than being
+                 * dropped because the alternative is the component arriving empty, and empty is
+                 * not more honest than literal - v1 mirrors, v2 normalises.
+                 */
+                const inlineStyle = readInlineStyle(src);
+                const base = {
+                    ...inlineStyle,
+                    ...fromModule?.base,
+                    ...v.base.base,
+                    ...t.base,
+                };
+                const states = {
+                    ...fromModule?.states,
+                    ...v.base.states,
+                    ...t.states,
+                };
+                const dark = { ...fromModule?.dark, ...t.dark };
+                const layers = [...(fromModule?.layers ?? []), ...v.layers];
+                const parts = { ...fromModule?.parts, ...t.parts };
+                const tree = fromModule?.tree ?? [];
                 const size = Object.keys(base).length +
-                    Object.keys(t.dark).length +
+                    Object.keys(dark).length +
                     Object.keys(states).length +
-                    v.layers.length;
+                    Object.keys(parts).length +
+                    layers.length;
                 const tag = rootTag(src);
                 if (size > 0 || tag) {
                     looks[found[0].name] = {
                         ...t,
                         base,
                         states,
+                        dark,
+                        ...(Object.keys(parts).length > 0 ? { parts } : {}),
+                        ...(tree.length > 0 ? { tree } : {}),
                         ...(tag ? { rootTag: tag } : {}),
-                        ...(v.layers.length > 0 ? { layers: v.layers } : {}),
+                        ...(layers.length > 0 ? { layers } : {}),
                         ...(Object.keys(v.axes).length > 0 ? { declaredAxes: v.axes } : {}),
                         ...(Object.keys(v.defaults).length > 0
                             ? { defaults: v.defaults }
@@ -367,6 +483,51 @@ export async function takeCensus(root, opts) {
     })));
     const d = diagnose(reports);
     const allComposed = tallyToInventory(tally, 400);
+    /**
+     * THE FEATURE FILTER, after the walk - because the count needs every file.
+     *
+     * A component composed on one screen is that screen's own markup; two screens is a
+     * decision the product shares. Measured on a real app: 242 of 271 live on one screen or
+     * none, and filtering them takes the vitrine from 271 to 29 - `Table`, `Tag`, `Tooltip`,
+     * `Button`, `Loader`, `Header` (dono, 01/08).
+     *
+     * SKIPPED FOR A LIBRARY, and this is the whole reason the test is here rather than in
+     * the walk: a library composes nothing inside itself, so every export would read as
+     * used on no screen. Measured the same way `isLibrary` measures it, from the tally
+     * rather than from a second opinion.
+     */
+    /**
+     * NO SCREENS MEANS NO TEST, and this is the guard rather than a component count.
+     *
+     * A first version required four components before calling something a library, and a
+     * scope with three had every export filtered as a feature - which is the failure this
+     * test was built to prevent, arriving from the other side (spec, 01/08).
+     *
+     * The honest question is simpler: does this scope HAVE screens? A `packages/ui` has no
+     * `app/` and no `pages/`, so there is nothing to count and the count would be zero for
+     * everything. An app has them, and then the number means something.
+     */
+    const hasScreens = [...screensOf.values()].some((at) => [...at].some((s) => s.startsWith("app/") || s.startsWith("pages/")));
+    if (hasScreens) {
+        const keep = [];
+        for (const d of defined) {
+            const screens = screensOf.get(d.name)?.size ?? 0;
+            if (screens >= SCREENS_FOR_SYSTEM) {
+                keep.push(d);
+                continue;
+            }
+            skips.push({
+                name: d.name,
+                file: d.file,
+                why: "feature",
+                because: screens === 0
+                    ? `\`${d.name}\` is composed on no screen at all - it is markup nothing reaches yet`
+                    : `\`${d.name}\` is composed on one screen only, so it is that screen's own markup rather than a decision the product shares. Two screens is the line, and the count is from your files`,
+            });
+        }
+        defined.length = 0;
+        defined.push(...keep);
+    }
     /**
      * THE EVIDENCE PASS - a second walk that touches ONE reading.
      *
@@ -577,6 +738,41 @@ export async function takeCensus(root, opts) {
             console.log(body(paint.faint(`(${theirsOnly.length} component${theirsOnly.length === 1 ? "" : "s"} live there and not in the system - ${shown.join(", ")}${theirsOnly.length > shown.length ? ", …" : ""}. Left out on purpose: the system is one place, and a union of two codebases is not a system. Point --scope at them if they belong in it.)`)));
         }
     }
+    /**
+     * WHAT THIS VERSION CAN AND CANNOT READ, on their files.
+     *
+     * Before this, importing a CSS-Modules app produced 283 components with no
+     * declarations and said nothing about why - and a person seeing that concludes the
+     * product is broken, reasoning correctly from what they were shown. The gap was never
+     * the defect; the silence was (dono, 01/08).
+     */
+    const coverage = summarizeCoverage(shapes, componentFiles, Object.keys(looks).length, Object.values(looks).reduce((n, look) => n +
+        Object.keys(look.base).length +
+        Object.keys(look.dark).length +
+        Object.values(look.states).reduce((m, block) => m + Object.keys(block).length, 0) +
+        // The LAYERS count: the record and ternary readers produce layers rather than a
+        // base, so leaving them out reported a Tag with eight colours as three
+        // declarations (probe, 01/08).
+        (look.layers ?? []).reduce((m, layer) => m + Object.keys(layer.style).length, 0) +
+        Object.values(look.parts ?? {}).reduce((m, part) => m +
+            Object.keys(part.base).length +
+            Object.keys(part.dark).length +
+            Object.values(part.states).reduce((k, block) => k + Object.keys(block).length, 0), 0), 0));
+    if (fetched.ok) {
+        console.log("");
+        console.log(body(paint.faint(`Matched against the live catalogue - ${fetched.index.count} components.`)));
+    }
+    else {
+        console.log("");
+        console.log(body(describeFallback(fetched, floorSize())));
+    }
+    const coverageLines = describeCoverage(coverage);
+    if (coverageLines.length > 0) {
+        console.log("");
+        console.log(section("What this version reads, on your files"));
+        for (const line of coverageLines)
+            console.log(body(line));
+    }
     /**
      * WHAT THE GATE TURNED AWAY - said out loud, grouped, with the reason.
      *
@@ -695,6 +891,21 @@ export async function takeCensus(root, opts) {
          * printed it, and never turned it into a rule is a feature that does nothing (dono,
          * 01/08).
          */
+        ...(coverage.components > 0
+            ? {
+                coverage: {
+                    components: coverage.components,
+                    read: coverage.read,
+                    declarations: coverage.declarations,
+                    shapes: coverage.counts.map((c) => ({
+                        key: c.shape.key,
+                        label: c.shape.label,
+                        reads: c.shape.reads,
+                        files: c.files,
+                    })),
+                },
+            }
+            : {}),
         ...(architectures.length > 0
             ? {
                 architectures: architectures.slice(0, 6).map((a) => ({

package/dist/commands/mcp.js

@@ -1,5 +1,6 @@
 import { readFile } from "node:fs/promises";
 import { relative, resolve } from "node:path";
+import { readToken, resolveRegistry } from "../config.js";
 import { fileRequest } from "../doctor/requests.js";
 import { diagnose, scanSource } from "../doctor/scan.js";
 import { nearestToken, tokenFor } from "../doctor/tokens.js";
@@ -93,6 +94,29 @@ const TOOLS = [
             required: ["name"],
         },
     },
+    {
+        name: "recipe_vocabulary",
+        description: "What a recipe CAN hold: every state that compiles, every preview form, the floor per kind, and the rules a media region needs. Call this BEFORE writing a recipe, not after - the reader that skipped it sent a `dark:` inside a variant and a state the compiler cannot spell, and both were dropped in silence. Served from the catalogue, so it grows as the contract grows.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "validate_recipe",
+        description: "Would this recipe survive being sent? Answers with what would NOT - the properties held by the schema and dropped by the compiler, and what is missing before it can be drawn at all - by name, with the reason. Never a boolean: a boolean tells you to try again, a list tells you what to fix. Call it on every recipe before sending, and write what it returns into `_synthesisui/not-expressed.md`.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: {
+                    type: "string",
+                    description: "The component name, for the report.",
+                },
+                recipe: {
+                    type: "object",
+                    description: "The candidate recipe, in the document's own shape.",
+                },
+            },
+            required: ["recipe"],
+        },
+    },
     {
         name: "request_component",
         description: "File a component request when nothing in the catalogue covers what you need. This is the OTHER HALF of the refusal rule: you already say which entry you considered and why it did not fit - said in chat, that reasoning evaporates; filed here, it becomes the queue the system's author works from. File it at the moment you build the workaround, while the reasoning is still yours.",
@@ -217,6 +241,126 @@ async function listComponents(root) {
  * back says what the platform UNDERSTOOD - so a reading that came out thin is
  * visible instead of being discovered later in a preview.
  */
+/**
+ * WHAT A RECIPE CAN HOLD - served, not written here.
+ *
+ * The reader had no way to ask, so it sent what it found and the parts we could not hold
+ * were dropped in silence: a state the compiler cannot spell, a `dark:` inside a variant,
+ * a part name with a dot in it. Four times in one day (dono, 01/08).
+ *
+ * Fetched rather than embedded, and the owner's reason is the one that decides it: "the
+ * properties need to be dynamic - the more we map, the more precision". A list written
+ * into a published package is a list that stops matching the contract.
+ */
+async function recipeVocabulary() {
+    const answer = await askCatalogue("vocabulary");
+    if (!answer.ok)
+        return answer.because;
+    const v = answer.body;
+    const lines = [
+        "WHAT A RECIPE CAN HOLD",
+        "",
+        `properties: any CSS property, camelCase. Part names match ${v.partName} - flat and kebab-case, because a nested name compiles to two classes and is invalid CSS.`,
+        "",
+        `states that compile (${v.states.length}): ${v.states.join(", ")}`,
+        `preview forms: ${v.forms.join(", ")}`,
+        `a layer's conditions: ${v.layerConditions.join(", ")} - and they combine, so a ghost button's hover at the md breakpoint is one layer`,
+        "",
+        "THE FLOOR - below this a preview cannot be told apart from the page:",
+        ...Object.entries(v.floor).map(([kind, needs]) => `  ${kind}: ${needs.join("; ")}`),
+        "",
+        "WHAT TO GO LOOK FOR, per kind - work the list and say which ones their code answers:",
+        ...Object.entries(v.checklist).map(([kind, items]) => `  ${kind}:\n${items.map((i) => `    - ${i}`).join("\n")}`),
+        "",
+        "A MEDIA REGION cannot be used without these, and four of the five are about what happens when the picture is not there:",
+        ...v.media.map((m) => `  ${m.need} - ${m.why}`),
+    ];
+    return lines.join("\n");
+}
+/**
+ * WOULD THIS RECIPE SURVIVE? - the handshake that makes a loss visible when it happens.
+ *
+ * Nothing validated a recipe before it was sent: zero mentions of `validate` in the entire
+ * import path. So the reader sent, the document held half of it, and nobody noticed until
+ * somebody looked at a blank component weeks later.
+ */
+async function validateRecipe(name, recipe) {
+    const answer = await askCatalogue("validate", { name, recipe });
+    if (!answer.ok)
+        return answer.because;
+    const v = answer.body;
+    if (v.ok) {
+        return `${name}: everything you sent would survive. Send it.`;
+    }
+    const lines = [`${name}: this would NOT arrive whole.`, ""];
+    if (v.rejected.length > 0) {
+        lines.push("REFUSED by the contract - fix these or the whole recipe is dropped:");
+        for (const r of v.rejected)
+            lines.push(`  ${r.at}: ${r.why}`);
+        lines.push("");
+    }
+    if (v.lost.length > 0) {
+        lines.push("HELD BY THE SCHEMA AND DROPPED BY THE COMPILER - the silent half, which is the", "one worth fixing before sending:");
+        for (const l of v.lost)
+            lines.push(`  ${l}`);
+        lines.push("");
+    }
+    if (v.missing.length > 0) {
+        lines.push("BELOW THE FLOOR - it would arrive and not be drawable:");
+        for (const m of v.missing)
+            lines.push(`  ${m}`);
+        lines.push("");
+    }
+    if (v.checklist.length > 0) {
+        lines.push("Go looking for these before you send it again:");
+        for (const c of v.checklist)
+            lines.push(`  - ${c}`);
+    }
+    lines.push("", "Write this into `_synthesisui/not-expressed.md` - what we cannot hold is the list", "the system's author works from, and said only in chat it evaporates.");
+    return lines.join("\n");
+}
+/**
+ * The catalogue's door, with the session the device login already granted.
+ *
+ * Served rather than shipped for the two reasons the owner gave (dono, 01/08): a table in
+ * a published package can be read by anyone, and it goes stale - the crosswalk's own copy
+ * had 26 names against a catalogue of 41.
+ */
+async function askCatalogue(want, post) {
+    const token = await readToken();
+    if (!token) {
+        return {
+            ok: false,
+            because: "Not signed in, so the catalogue could not answer. Run `synthesisui login` in the terminal and call this again - this one needs a session, unlike `doctor`.",
+        };
+    }
+    const base = resolveRegistry();
+    try {
+        const res = await fetch(`${base}/api/catalogue${post ? "" : `?want=${want}`}`, post
+            ? {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    "content-type": "application/json",
+                },
+                body: JSON.stringify(post),
+            }
+            : { headers: { Authorization: `Bearer ${token}` } });
+        if (!res.ok) {
+            return {
+                ok: false,
+                because: `The catalogue answered ${res.status}. ${res.status === 401 ? "Run `synthesisui login` and try again." : "Nothing was sent."}`,
+            };
+        }
+        return { ok: true, body: await res.json() };
+    }
+    catch {
+        return {
+            ok: false,
+            because: "No network, so the catalogue could not answer. Everything else in this server works offline; this one does not, and pretending otherwise would mean answering from a stale copy.",
+        };
+    }
+}
 async function describeComponent(root, name) {
     const { documents, requires } = await loadSystem(root);
     let recipe;
@@ -337,6 +481,10 @@ async function callTool(root, name, args) {
             return text(await describeComponent(root, String(args.name ?? "")));
         case "add_component":
             return text(await addComponent(root, String(args.name ?? "")));
+        case "recipe_vocabulary":
+            return text(await recipeVocabulary());
+        case "validate_recipe":
+            return text(await validateRecipe(String(args.name ?? "this component"), args.recipe));
         case "request_component": {
             const r = await fileRequest(root, {
                 kind: "component",

package/dist/doctor/catalogue-fetch.js

@@ -0,0 +1,88 @@
+/**
+ * THE CATALOGUE, FETCHED - because a table written into a published package goes stale
+ * and can be read by anyone.
+ *
+ * The crosswalk's own copy was written by hand and had 26 names against a catalogue of 41
+ * (dono, 01/08). Twenty of OUR OWN components were invisible to matching - `Textarea`,
+ * `Sidebar`, `Menu`, `Stepper`, `EmptyState` and fifteen more - and five names in it no
+ * longer existed. Their `Textarea` did not match our `textarea`. At 300 components that
+ * gap is 280, and closing it by hand means a version bump and a publish for every
+ * component we add. That was forgotten twice in one day.
+ *
+ * THE FLOOR STAYS. The written table is not deleted: it is what answers when there is no
+ * session and no network, which is a real state a person can be in. What changes is that
+ * it stops being the truth and starts being the fallback - and the run SAYS when it fell
+ * back, with the number that costs, because a silently smaller answer is the thing this
+ * whole pipeline keeps being punished for.
+ */
+import { readToken, resolveRegistry } from "../config.js";
+/**
+ * One call, at the start of a run.
+ *
+ * Not per component: a handshake for each of 362 components would be 362 round trips to
+ * answer a question one table answers. The index is 60 tokens a component and the caller
+ * matches locally against it.
+ */
+export async function fetchCatalogue(registryFlag) {
+    const token = await readToken();
+    if (!token) {
+        return {
+            ok: false,
+            why: "no-session",
+            because: "no session, so the catalogue could not be fetched - `synthesisui login` and re-run to match against the full list",
+        };
+    }
+    const base = resolveRegistry(registryFlag);
+    try {
+        const res = await fetch(`${base}/api/catalogue?want=index`, {
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        if (!res.ok) {
+            return {
+                ok: false,
+                why: res.status === 401 ? "no-session" : "refused",
+                because: res.status === 401
+                    ? "the session was refused - `synthesisui login` and re-run"
+                    : `the catalogue answered ${res.status}`,
+            };
+        }
+        const index = (await res.json());
+        if (!Array.isArray(index?.components)) {
+            return {
+                ok: false,
+                why: "refused",
+                because: "the catalogue answered in a shape this version does not know",
+            };
+        }
+        return { ok: true, index };
+    }
+    catch {
+        return {
+            ok: false,
+            why: "offline",
+            because: "no network, so the catalogue could not be fetched",
+        };
+    }
+}
+/**
+ * The fetched index as the crosswalk's own table: canonical name → the words it answers
+ * to, plus the axes, which is what `axisOverlap` compares against.
+ */
+export function asCatalogueTable(index) {
+    const synonyms = {};
+    const axes = {};
+    for (const entry of index.components) {
+        synonyms[entry.name] = entry.also;
+        axes[entry.name] = entry.axes;
+    }
+    return { synonyms, axes };
+}
+/**
+ * What falling back COST, said with the number.
+ *
+ * "20 of our own components could not be matched" is a sentence somebody can act on;
+ * "using the built-in list" is not.
+ */
+export function describeFallback(result, floorSize) {
+    return `${result.because}. Matching used the ${floorSize} names built into this CLI instead of the live catalogue, so a component of yours that lines up with something we added recently will read as exclusively yours. That is a smaller answer, not a wrong one - re-run with a session to get the full one.`;
+}

package/dist/doctor/component-gate.js

@@ -136,6 +136,35 @@ function adapterFor(source, internal) {
     }
     return seen > 0 ? theirs : null;
 }
+/**
+ * HOW MANY SCREENS USE IT - the question that separates a design system from a folder.
+ *
+ * The gate took a real app from 704 to 271, and 271 names in a vitrine is the same
+ * problem with different numbers. `RegisterMultipleCSV`, `FeatureFlagUpdateForm`,
+ * `BoxHeaderInfo`, `SendProgressModal` are exclusive, correctly gated, and not design
+ * system: they are pieces of one screen.
+ *
+ * Enumerated before it was built, which is why the threshold is what it is (dono, 01/08):
+ *
+ *      42  used on NO screen        BoxHeaderInfo, Register, Search, Switcher
+ *     200  used on ONE screen       FeatureFlagUpdateForm, RegisterMultipleCSV
+ *      20  used on two screens      SkeletonLoader, Group, Header, UploadButton
+ *       2  used on three            ConfirmButton, Box
+ *       7  used on four or more     Table, Tag, Tooltip, Button, Loader
+ *
+ * 242 of 271 (89%) live on one screen or none. Filtering them takes the vitrine from 271
+ * to 29 - and the 29 are `Table`, `Tag`, `Tooltip`, `Button`, `Loader`, `Header`, which is
+ * what a design system is.
+ *
+ * TWO SCREENS IS THE LINE, and the distribution is why: the drop from 200 to 20 happens
+ * exactly there. A component two screens share is a decision about the product; a
+ * component one screen has is that screen's own markup.
+ *
+ * NOT APPLIED TO A LIBRARY. A library composes nothing inside itself, so every export
+ * would read as used on no screen - the same mistake library mode was built to stop. The
+ * caller passes the counts only when it has them, and absent means the test is skipped.
+ */
+export const SCREENS_FOR_SYSTEM = 2;
 export function gateComponent(input) {
     const { name, file, source } = input;
     if (RESERVED_FILE.test(file) || RESERVED_FILE_OTHER.test(file)) {
@@ -174,6 +203,15 @@ export function gateComponent(input) {
             because: `\`${name}\` is a capitalised export in a file with no markup - a constant, a config object or a helper`,
         };
     }
+    if (input.screens != null && input.screens < SCREENS_FOR_SYSTEM) {
+        return {
+            ok: false,
+            why: "feature",
+            because: input.screens === 0
+                ? `\`${name}\` is composed on no screen at all - it is a piece of markup nothing reaches yet`
+                : `\`${name}\` is composed on one screen only, so it is that screen's own markup rather than a decision the product shares. Two screens is the line, and the count is from your files`,
+        };
+    }
     if (!HAS_STYLING.test(source)) {
         return {
             ok: false,
@@ -195,6 +233,7 @@ export const SKIP_LABEL = {
     screen: "whole screens, and the frames around them",
     provider: "providers, contexts and wrappers",
     adapter: "adapters for another library's components",
+    feature: "pieces of one screen, not of the system",
     config: "constants, config and helpers",
     "no-jsx": "capitalised exports with no markup",
     "no-styling": "components that decide nothing about how anything looks",
@@ -204,6 +243,7 @@ export function groupSkips(skips) {
         "screen",
         "route",
         "provider",
+        "feature",
         "adapter",
         "no-styling",
         "config",