@codepress/design-kit 0.10.0 → 0.12.0

package/README.md

@@ -521,23 +521,45 @@ keeps the kit's totals and adds `page_sources.<source>` with each one's own.
 The tool needs only Node: no install and no network.
 
 ```bash
-node kit.mjs info                    # the manifest
-node kit.mjs find button             # ≤ 30 lines: id, kind, width, bytes, title
+node kit.mjs info [--json]           # one line: sha, build time, counts (--json: the manifest)
+node kit.mjs find button             # ≤ 30 lines: id (widths grouped), size, title
 node kit.mjs find "transfer app"     # the words on screen work too
 node kit.mjs show <id> [--full]      # path, size and an outline (≤ 2 KB) or the markup
 node kit.mjs compose --frame route:dashboard@1280 --slot main=new.html \
-  [--theme light|dark] [--show-new] --out page.html
+  [--theme light|dark] [--show-new] [--css pruned|full] --out page.html
 ```
 
-`find` lists the rows holding every word of the query in their id, title,
+`info` prints one line, such as
+`480e11d built 2026-11-15T18:58:59.954Z · stories 12821 · routes 133 · failed 13`,
+and names the failed ids from `gaps.json` when there are five or fewer;
+`info --json` prints `manifest.json` as it is.
+
+`find` prints one line per frame: rows that differ only by `@<width>` share
+it, with the widths in braces and one size per width (or one size when they
+print the same), for example
+`route:orchestrator@{1280,390}  131/136 KB  Orchestrator project`. A frame
+captured at one width prints its plain id. The title is left out when it only
+restates the id (`Chat/SubAgentBlock/Orchestrator Row` for
+`story:chat-subagentblock--orchestrator-row`), and a route's trailing
+` (1280)` is dropped; a frame whose widths have different titles prints each,
+separated by `|`. `find` lists the rows holding every word of the query in their id, title,
 component, source file or visible text. Rows with the words in the id come
 first, then the title, component or source file, then the text only; among
 rows that tie, one whose text holds the whole query comes first. A row found
 only through its text ends with a quoted excerpt of about 60 characters
 around the words, so you see why it matched. When more rows match than the
 30 lines hold, rows found by name fill the list but its last 5 lines are kept
-for rows found by text, and the closing line counts what each left out
-(`+37 more by name, +3 more by on-screen text; narrow the query`). The text
+for rows found by text, and the closing line counts the rows each left out
+(`+37 more by name, +3 more by on-screen text; narrow the query`). The
+formatter is exported as `findMatchLines(matches)` from
+`@codepress/design-kit/kit`, so the cloud Orchestrator's `design_kit_find`
+prints the same lines.
+
+`show` prints the row's header (id, kind and size, title, file, source,
+slots) and an outline of at most 2 KB: one line per element down to depth 4,
+a run of identical siblings (each with what is nested under it) printed once
+with `×N`, and generated ids (`radix-…`, React's `_r…_` and the capture's
+renumbered `_k…_`) left out. `show --full` prints the markup. The text
 is `text.json`, built
 whenever a capture writes the kit: each row's markup without its scripts,
 styles, SVG, head and templates, tags and attribute values dropped, entities
@@ -568,6 +590,23 @@ fragments included. `--theme dark` applies the manifest's theme. Elements marked
 or snippet id exits 2, naming near matches. `--kit <dir>` (or
 `DESIGN_KIT_DIR`) points at a kit other than the tool's own folder.
 
+`compose` inlines only the CSS the page can use. Once the body is final, it
+collects every class and id on the page's elements (hidden ones and
+`<template>` content included), every word in your inline scripts (so a class
+a script adds keeps its rules) and the theme classes. A style rule is dropped
+only when every selector in its list needs a class or id the page lacks;
+pseudo-classes, pseudo-elements, attribute parts and the arguments of `:is`,
+`:where`, `:has` and `:not` never count, and escapes (`hover\:bg-muted`,
+`w-\[38px\]`) are read as the browser reads them. Rules inside `@media`,
+`@supports`, `@layer`, `@container` and `@scope` are pruned the same way and
+an emptied block goes (a named `@layer` stays, since it sets the layer
+order). `@font-face`, `@keyframes`, `@property`, other at-rules and rules with
+no class or id are kept as written. A rule repeated in the same at-rule
+context is written once, its last copy. A composed screen drops from
+megabytes to a few hundred KB with identical pixels. A class your script
+builds from pieces (`"is-" + state`) is not seen; `--css full` (option
+`css: "full"`) keeps every rule, as before 0.11.
+
 ### Clickable mockups
 
 A composed page can switch tabs, open and close menus and swap between a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codepress/design-kit",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Capture your Storybook and real app pages as a static design kit, and compose self-contained mockups from it",
   "type": "module",
   "bin": {

package/src/kit.d.ts

@@ -51,6 +51,14 @@ export function findMatches(kit: Kit, query: string): KitMatch[];
 /** The rows of `findMatches`, in the same order. */
 export function find(kit: Kit, query: string): KitRow[];
 
+/**
+ * `kit find`'s lines for `findMatches` results, at most 30: rows that differ
+ * only by width share one line (`route:x@{1280,390}  131/136 KB  Title`), a
+ * title that only restates the id is left out, and when the matches do not
+ * fit, a last line counts the rows not shown.
+ */
+export function findMatchLines(matches: KitMatch[]): string[];
+
 /** Characters of visible text text.json keeps per row: 600. */
 export const TEXT_LIMIT: number;
 
@@ -95,9 +103,21 @@ export function compose(
     showNew?: boolean;
     /** Bytes of markup the page may grow to through snippets. */
     maxBytes?: number;
+    /**
+     * `pruned` (the default) keeps only the CSS rules the page's classes and
+     * ids can use, each repeated rule once; `full` keeps every rule.
+     */
+    css?: "pruned" | "full";
   },
 ): string;
 
+/**
+ * The stylesheet without the style rules that need a class or id missing
+ * from `names`, and with each rule repeated in the same at-rule context
+ * written once (its last copy).
+ */
+export function pruneCss(css: string, names: Set<string>): string;
+
 /** The default `maxBytes` of `compose`: 32 MB. */
 export const COMPOSE_MAX_BYTES: number;
 

package/src/kit.mjs

@@ -3,11 +3,11 @@
  * The design kit's own tool. It ships inside every kit, so tool and data
  * always match. Pure Node: no dependencies, no network.
  *
- *   node kit.mjs info
+ *   node kit.mjs info [--json]
  *   node kit.mjs find <query>        (ids, titles and the words on screen)
  *   node kit.mjs show <id> [--full]
  *   node kit.mjs compose --frame <id> [--slot <name>=<file>]… [--theme light|dark]
- *                        [--show-new] --out <file>
+ *                        [--show-new] [--css pruned|full] --out <file>
  *
  * `--kit <dir>` (or DESIGN_KIT_DIR) points at a kit; the default is the
  * folder this file sits in. Format: the @codepress/design-kit README.
@@ -993,6 +993,348 @@ function restoreAuthorScripts(html, key, held) {
   );
 }
 
+// ── CSS pruning ─────────────────────────────────────────────────────────────
+//
+// A composed page carries the kit's whole stylesheets, megabytes of rules for
+// classes the page never names. compose keeps only the rules a page can use:
+// a style rule goes only when every selector in its list needs a class or id
+// the page lacks, and of rules repeated in the same at-rule context only the
+// last stays (it is the one the cascade uses). Everything else (@font-face,
+// @keyframes, @property, rules with no class or id) stays as written.
+
+/** At-rules whose blocks hold rules that are pruned like the top level. */
+const CSS_WRAPPERS = new Set([
+  "media",
+  "supports",
+  "layer",
+  "container",
+  "scope",
+]);
+
+const CSS_IDENT_CHAR = /[A-Za-z0-9_\-\u0080-￿]/;
+
+/**
+ * Where the CSS token at `i` ends when it is one whose characters never count
+ * as structure (an escape, a comment, a string or an unquoted `url(…)`);
+ * otherwise -1.
+ */
+function cssSkip(css, i) {
+  const ch = css[i];
+  if (ch === "\\") return Math.min(i + 2, css.length);
+  if (ch === "/" && css[i + 1] === "*") {
+    const end = css.indexOf("*/", i + 2);
+    return end < 0 ? css.length : end + 2;
+  }
+  if (ch === '"' || ch === "'") {
+    let j = i + 1;
+    while (j < css.length) {
+      const c = css[j];
+      if (c === "\\") j += 2;
+      else if (c === ch) return j + 1;
+      // An unterminated string ends at the line's end, as the browser reads it.
+      else if (c === "\n") return j;
+      else j += 1;
+    }
+    return css.length;
+  }
+  if (
+    (ch === "u" || ch === "U") &&
+    (i === 0 || !CSS_IDENT_CHAR.test(css[i - 1])) &&
+    /^url\(\s*[^\s"')]/i.test(css.slice(i, i + 64))
+  ) {
+    let j = css.indexOf("(", i) + 1;
+    while (j < css.length && css[j] !== ")") j += css[j] === "\\" ? 2 : 1;
+    return Math.min(j + 1, css.length);
+  }
+  return -1;
+}
+
+/** The first `{`, `;` or `}` outside brackets from `i`, or `end`. */
+function cssPreludeEnd(css, i, end) {
+  let nested = 0;
+  while (i < end) {
+    const skip = cssSkip(css, i);
+    if (skip >= 0) {
+      i = skip;
+      continue;
+    }
+    const ch = css[i];
+    if (ch === "(" || ch === "[") nested += 1;
+    else if ((ch === ")" || ch === "]") && nested > 0) nested -= 1;
+    else if (!nested && (ch === "{" || ch === ";" || ch === "}")) return i;
+    i += 1;
+  }
+  return end;
+}
+
+/** Just past the `}` that closes the block opening at `open`, or -1. */
+function cssBlockEnd(css, open, end) {
+  let depth = 0;
+  let i = open;
+  while (i < end) {
+    const skip = cssSkip(css, i);
+    if (skip >= 0) {
+      i = skip;
+      continue;
+    }
+    if (css[i] === "{") depth += 1;
+    else if (css[i] === "}" && --depth === 0) return i + 1;
+    i += 1;
+  }
+  return -1;
+}
+
+/**
+ * A list of rules as nodes: `rule` (a style rule, kept or dropped whole),
+ * `wrapper` (an at-rule from CSS_WRAPPERS, pruned inside) and `keep`
+ * (everything else, written back as it was). Comments between rules go.
+ */
+function parseCssList(css, start, end) {
+  const nodes = [];
+  let i = start;
+  while (i < end) {
+    const ch = css[i];
+    if (/\s/.test(ch)) {
+      i += 1;
+      continue;
+    }
+    if (ch === "/" && css[i + 1] === "*") {
+      i = cssSkip(css, i);
+      continue;
+    }
+    const stop = cssPreludeEnd(css, i, end);
+    if (stop >= end || css[stop] !== "{") {
+      // A statement (`@layer a, b;`) or junk the browser skips: as written.
+      const through = Math.min(stop + 1, end);
+      nodes.push({ type: "keep", text: css.slice(i, through) });
+      i = through;
+      continue;
+    }
+    const closedAt = cssBlockEnd(css, stop, end);
+    const closed = closedAt >= 0;
+    const blockEnd = closed ? closedAt : end;
+    const prelude = css.slice(i, stop);
+    const atRule = /^@([A-Za-z-]+)/.exec(prelude);
+    const name = atRule?.[1].toLowerCase();
+    if (name && CSS_WRAPPERS.has(name)) {
+      const layerName = prelude.slice(atRule[0].length).trim();
+      nodes.push({
+        type: "wrapper",
+        head: css.slice(i, stop + 1),
+        // A named layer's first block sets the layer order, so even an
+        // emptied one stays; each unnamed layer is a layer of its own.
+        named: name === "layer" && layerName !== "",
+        anonymous: name === "layer" && layerName === "",
+        children: parseCssList(css, stop + 1, closed ? blockEnd - 1 : blockEnd),
+      });
+    } else if (name) {
+      nodes.push({ type: "keep", text: css.slice(i, blockEnd) });
+    } else {
+      nodes.push({ type: "rule", prelude, text: css.slice(i, blockEnd) });
+    }
+    i = blockEnd;
+  }
+  return nodes;
+}
+
+/**
+ * A rule's text with comments gone and whitespace outside strings collapsed,
+ * so the same rule written by two sheets compares equal.
+ */
+function cssKey(text) {
+  let out = "";
+  // Whether `out` ends in an escape, string or url(): its last character is
+  // then not the punctuation it looks like (`.\\{ .a` keeps its space).
+  let quoted = false;
+  let i = 0;
+  while (i < text.length) {
+    const skip = cssSkip(text, i);
+    if (skip >= 0) {
+      if (text[i] !== "/") {
+        out += text.slice(i, skip);
+        quoted = true;
+      }
+      i = skip;
+      continue;
+    }
+    if (/\s/.test(text[i])) {
+      while (i < text.length && /\s/.test(text[i])) i += 1;
+      const afterPunctuation = !quoted && /[{};,]$/.test(out);
+      if (!afterPunctuation && !/^[{};,]/.test(text[i] ?? "")) out += " ";
+      continue;
+    }
+    out += text[i];
+    quoted = false;
+    i += 1;
+  }
+  return out.trim();
+}
+
+/** The parts of a selector list, split on commas outside brackets. */
+function selectorParts(prelude) {
+  const parts = [];
+  let nested = 0;
+  let from = 0;
+  let i = 0;
+  while (i < prelude.length) {
+    const skip = cssSkip(prelude, i);
+    if (skip >= 0) {
+      i = skip;
+      continue;
+    }
+    const ch = prelude[i];
+    if (ch === "(" || ch === "[") nested += 1;
+    else if ((ch === ")" || ch === "]") && nested > 0) nested -= 1;
+    else if (ch === "," && !nested) {
+      parts.push(prelude.slice(from, i));
+      from = i + 1;
+    }
+    i += 1;
+  }
+  parts.push(prelude.slice(from));
+  return parts;
+}
+
+/** Just past the bracket closing the one at `i`. */
+function closeBracket(text, i) {
+  let depth = 0;
+  while (i < text.length) {
+    const skip = cssSkip(text, i);
+    if (skip >= 0) {
+      i = skip;
+      continue;
+    }
+    const ch = text[i];
+    if (ch === "(" || ch === "[") depth += 1;
+    else if ((ch === ")" || ch === "]") && --depth === 0) return i + 1;
+    i += 1;
+  }
+  return text.length;
+}
+
+/** The identifier at `i`, escapes resolved, and where it ends. */
+function readCssIdent(text, i) {
+  let j = i;
+  while (j < text.length) {
+    if (text[j] === "\\" && j + 1 < text.length && text[j + 1] !== "\n") {
+      const hex = /^[0-9a-fA-F]{1,6}\s?/.exec(text.slice(j + 1, j + 8));
+      j += 1 + (hex ? hex[0].length : 1);
+    } else if (CSS_IDENT_CHAR.test(text[j])) j += 1;
+    else break;
+  }
+  return [unescapeCss(text.slice(i, j)), j];
+}
+
+/**
+ * Whether one selector can match on the page: every class and id it needs is
+ * there. Attribute parts and the arguments of functional pseudo-classes and
+ * pseudo-elements (`:is`, `:where`, `:has`, `:not`, `::part`, …) never count.
+ */
+function selectorCanMatch(selector, names) {
+  let i = 0;
+  while (i < selector.length) {
+    const ch = selector[i];
+    if (ch === "[" || ch === "(") {
+      i = closeBracket(selector, i);
+      continue;
+    }
+    const skip = cssSkip(selector, i);
+    if (skip >= 0) {
+      i = skip;
+      continue;
+    }
+    if (ch === "." || ch === "#") {
+      const [name, next] = readCssIdent(selector, i + 1);
+      if (name && !names.has(name)) return false;
+      i = Math.max(next, i + 1);
+      continue;
+    }
+    if (CSS_IDENT_CHAR.test(ch)) {
+      // A tag name or pseudo name: read whole, so a `.` cannot start inside.
+      i = readCssIdent(selector, i)[1];
+      continue;
+    }
+    i += 1;
+  }
+  return true;
+}
+
+/**
+ * Kept rules as text, last-first so the last copy of a repeated rule is the
+ * one kept. `context` names the at-rules around them; `seen` is shared.
+ */
+function prunedCss(nodes, names, context, seen, counter) {
+  const out = [];
+  for (let n = nodes.length - 1; n >= 0; n -= 1) {
+    const node = nodes[n];
+    if (node.type === "rule") {
+      if (
+        !selectorParts(node.prelude).some((part) =>
+          selectorCanMatch(part, names),
+        )
+      )
+        continue;
+      const key = `${context}\u0000${cssKey(node.text)}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push(node.text);
+    } else if (node.type === "wrapper") {
+      const inner = prunedCss(
+        node.children,
+        names,
+        `${context}\u0001${cssKey(node.head)}${node.anonymous ? `#${(counter.n += 1)}` : ""}`,
+        seen,
+        counter,
+      );
+      if (!inner.length && !node.named) continue;
+      out.push(`${node.head}\n${inner.join("\n")}\n}`);
+    } else {
+      out.push(node.text);
+    }
+  }
+  return out.reverse();
+}
+
+/**
+ * The stylesheet with every style rule no element can match removed and
+ * repeated rules written once (see the section comment). `names` holds every
+ * class and id the page can have.
+ */
+export function pruneCss(css, names) {
+  return prunedCss(parseCssList(css, 0, css.length), names, "", new Set(), {
+    n: 0,
+  }).join("\n");
+}
+
+/**
+ * Every class and id a composed page can show: those on its elements (hidden
+ * ones and <template> content included), every word in the author's own
+ * scripts (one may add a class), and the theme classes.
+ */
+function pageNames(elementList, scripts, theme) {
+  const names = new Set(["dark", "light"]);
+  if (theme.attribute === "class") {
+    for (const value of [theme.dark, theme.light]) if (value) names.add(value);
+  }
+  for (const element of elementList) {
+    const { class: classes, id } = element.attrs;
+    if (classes) {
+      for (const name of decodeEntities(classes).split(/[\t\n\f\r ]+/)) {
+        if (name) names.add(name);
+      }
+    }
+    if (id) names.add(decodeEntities(id));
+  }
+  for (const script of scripts) {
+    for (const word of script.split(/[\s"'`]+/)) {
+      if (!word) continue;
+      names.add(word);
+      names.add(word.replace(/^[.#]+/, ""));
+    }
+  }
+  return names;
+}
+
 // ── compose ─────────────────────────────────────────────────────────────────
 
 /**
@@ -1185,7 +1527,9 @@ function attributes(captured, extraClass, theme, choice, target, fixed) {
 /**
  * One self-contained page: the frame's markup with slots filled and
  * snippets expanded, its CSS (and that of any other source a snippet came
- * from) inlined with fonts as data URIs, and no remote URLs. The only
+ * from) inlined with fonts as data URIs, and no remote URLs. Only the rules
+ * the page's classes and ids can use are kept, each once (see pruneCss);
+ * `css: "full"` keeps every rule. The only
  * scripts are the inline ones the slot fragments brought and, when the page
  * uses a behaviour attribute, the behaviour layer; nothing executable from
  * the kit's own markup survives.
@@ -1198,12 +1542,16 @@ export function compose(
     theme = "light",
     showNew = false,
     maxBytes = COMPOSE_MAX_BYTES,
+    css: cssMode = "pruned",
   },
 ) {
   const row = requireRow(kit, frame, "frame");
   if (theme !== "light" && theme !== "dark") {
     throw new KitError(`unknown theme "${theme}". Use light or dark.`);
   }
+  if (cssMode !== "pruned" && cssMode !== "full") {
+    throw new KitError(`unknown css "${cssMode}". Use pruned or full.`);
+  }
   const used = new Set([rowCssFile(kit, row)]);
   // The author's inline scripts sit out the sanitizer; everything else in
   // the fragments (handlers, remote scripts, snippets) goes through it.
@@ -1272,6 +1620,23 @@ export function compose(
     "body",
     {},
   );
+  // The kit's CSS, cut to the rules this page's classes and ids can use
+  // (`css: "full"` keeps every rule).
+  const safeCss = sanitizeCss(css);
+  const pageCss =
+    cssMode === "full"
+      ? safeCss
+      : pruneCss(
+          safeCss,
+          pageNames(
+            [
+              ...bodyElements,
+              ...elements(`<html${htmlAttrs}><body${bodyAttrs}>`),
+            ],
+            heldScripts,
+            switcher,
+          ),
+        );
   // What this page used, for whoever wants to count it later. Recorded in
   // the page only; kit.mjs never sends it anywhere.
   const usage = {
@@ -1288,7 +1653,7 @@ export function compose(
 <meta name="design-kit-usage" content="${escapeAttr(JSON.stringify(usage))}">
 <title>${escapeAttr(row.title ?? frame)}</title>
 <style>
-${sanitizeCss(css)}${showNewCss}
+${pageCss}${showNewCss}
 </style>
 </head>
 <body${bodyAttrs}>
@@ -1469,10 +1834,16 @@ function excerpt(words, at, length) {
 
 // ── show / find / info ──────────────────────────────────────────────────────
 
-export function outline(html, limit = SHOW_LIMIT) {
-  const lines = [];
-  let size = 0;
-  let truncated = false;
+/**
+ * An id attribute a library or React generated (`radix-…`, React's `useId`
+ * values as the capture renumbers them): it changes between builds and says
+ * nothing about the element, so the outline leaves it out.
+ */
+const GENERATED_ID = /^radix-|_r_?[0-9a-z]+_|_k\d+_|:r[0-9a-z]+:/;
+
+/** One outline line per element down to depth 4, with its depth. */
+function outlineEntries(html) {
+  const entries = [];
   for (const element of elements(html)) {
     if (element.depth > 4) continue;
     const classes = (element.attrs.class ?? "")
@@ -1483,10 +1854,71 @@ export function outline(html, limit = SHOW_LIMIT) {
       .join("");
     const marks = ["id", "role", "data-kit-slot", "aria-label", "data-testid"]
       .filter((name) => element.attrs[name])
+      .filter((name) => name !== "id" || !GENERATED_ID.test(element.attrs.id))
       .map((name) => `[${name}=${element.attrs[name].slice(0, 40)}]`)
       .join("");
     const text = element.text.replace(/\s+/g, " ").trim().slice(0, 40);
-    const line = `${"  ".repeat(element.depth)}<${element.name}${classes}${marks}>${text ? ` "${text}"` : ""}`;
+    entries.push({
+      depth: element.depth,
+      line: `${"  ".repeat(element.depth)}<${element.name}${classes}${marks}>${text ? ` "${text}"` : ""}`,
+    });
+  }
+  return entries;
+}
+
+/**
+ * Runs of identical siblings, each with the lines nested under it, printed
+ * once with `×N` after the first line.
+ */
+function collapseRuns(entries) {
+  // ends[i]: the index after the last line nested under line i.
+  const ends = new Array(entries.length).fill(entries.length);
+  const open = [];
+  entries.forEach((entry, i) => {
+    while (open.length && entries[open.at(-1)].depth >= entry.depth)
+      ends[open.pop()] = i;
+    open.push(i);
+  });
+  const same = (a, b, length) => {
+    for (let k = 0; k < length; k += 1)
+      if (entries[a + k].line !== entries[b + k].line) return false;
+    return true;
+  };
+  const lines = [];
+  const walk = (from, to) => {
+    let i = from;
+    while (i < to) {
+      const length = ends[i] - i;
+      let next = ends[i];
+      let count = 1;
+      while (
+        next < to &&
+        entries[next].depth === entries[i].depth &&
+        ends[next] - next === length &&
+        same(i, next, length)
+      ) {
+        count += 1;
+        next = ends[next];
+      }
+      lines.push(`${entries[i].line}${count > 1 ? ` ×${count}` : ""}`);
+      walk(i + 1, ends[i]);
+      i = next;
+    }
+  };
+  walk(0, entries.length);
+  return lines;
+}
+
+/**
+ * A markup outline of at most `limit` bytes: one line per element down to
+ * depth 4, identical sibling runs collapsed to one line with `×N`, and
+ * generated ids left out.
+ */
+export function outline(html, limit = SHOW_LIMIT) {
+  const lines = [];
+  let size = 0;
+  let truncated = false;
+  for (const line of collapseRuns(outlineEntries(html))) {
     // The limit is bytes: an outline line can carry non-ASCII text.
     const bytes = Buffer.byteLength(line) + 1;
     if (size + bytes > limit) {
@@ -1571,32 +2003,103 @@ export function find(kit, query) {
   return findMatches(kit, query).map(({ row }) => row);
 }
 
-function findLines(kit, query) {
-  const matches = findMatches(kit, query);
-  if (!matches.length) {
-    const near = nearMatches(
-      query,
-      kit.rows.map((row) => row.id),
-    );
-    throw new KitError(
-      `nothing matches "${query}".${near.length ? ` Near: ${near.join(", ")}` : ""}`,
-    );
+/** Letters and digits only, lowercased: how a title can restate an id. */
+function flat(text) {
+  return text.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+
+/** `story:x@1280` → `story:x`: the id without its width. */
+function baseId(id) {
+  return id.replace(/@\d+$/, "");
+}
+
+/** The width an id ends in, as written. */
+function idWidth(id) {
+  return /@(\d+)$/.exec(id)?.[1] ?? null;
+}
+
+/** Sizes of a width group: `131/136 KB`, `443 B/1.2 KB`, or `4.9 KB` when they print the same. */
+function groupBytes(rows) {
+  const sizes = rows.map((row) => row.bytes ?? 0);
+  const kb = (bytes) =>
+    bytes >= 10 * 1024
+      ? `${Math.round(bytes / 1024)}`
+      : `${(bytes / 1024).toFixed(1)}`;
+  // Widths that print the same size print it once.
+  const once = (values) => [...new Set(values)].join("/");
+  if (sizes.every((bytes) => bytes >= 1024)) return `${once(sizes.map(kb))} KB`;
+  return once(
+    sizes.map((bytes) => (bytes >= 1024 ? `${kb(bytes)} KB` : `${bytes} B`)),
+  );
+}
+
+/**
+ * Matches gathered into lines: rows that differ only by `@<width>` and found
+ * the same way (the same excerpt, or none) share one line, at the place of
+ * the first of them.
+ */
+function widthGroups(matches) {
+  const groups = new Map();
+  for (const match of matches) {
+    // An id without a width never shares a line.
+    const id = match.row.id;
+    const key = `${idWidth(id) ? baseId(id) : `${id}\0`}\0${match.excerpt ?? ""}`;
+    const group = groups.get(key);
+    if (group) group.rows.push(match.row);
+    else groups.set(key, { rows: [match.row], excerpt: match.excerpt });
   }
-  const line = ({ row, excerpt: cut }) =>
-    `${row.id}  ${row.kind ?? rowSource(row)}  ${row.width ?? "?"}w  ${formatBytes(row.bytes ?? 0)}  ${row.title ?? ""}${cut === undefined ? "" : `  "${cut}"`}`;
-  if (matches.length <= FIND_LIMIT) return matches.map(line);
-  const room = FIND_LIMIT - 1;
+  return [...groups.values()];
+}
+
+/** One find line: id (with its widths), sizes, title unless it restates the id, excerpt. */
+function groupLine({ rows, excerpt: cut }) {
+  const base = baseId(rows[0].id);
+  const widths = rows.map((row) => idWidth(row.id));
+  const id = rows.length === 1 ? rows[0].id : `${base}@{${widths.join(",")}}`;
+  const name = flat(base.replace(/^[a-z]+:/, ""));
+  const titles = [];
+  for (const row of rows) {
+    const title = (row.title ?? "").replace(/\s*\(\d+\)$/, "").trim();
+    if (title && flat(title) !== name && !titles.includes(title))
+      titles.push(title);
+  }
+  return [
+    id,
+    groupBytes(rows),
+    ...(titles.length ? [titles.join(" | ")] : []),
+    ...(cut === undefined ? [] : [`"${cut}"`]),
+  ].join("  ");
+}
+
+/**
+ * `kit find`'s lines for `findMatches` results, at most FIND_LIMIT: rows that
+ * differ only by width share a line (`route:x@{1280,390}`), a title that only
+ * restates the id is left out, and a last line counts the rows not shown.
+ * Rows found by name come first, but a few lines are kept for rows found only
+ * by their on-screen text.
+ */
+export function findMatchLines(matches) {
+  const count = (groups) =>
+    groups.reduce((sum, group) => sum + group.rows.length, 0);
   // A row with an excerpt was found by on-screen text; any other, by name.
-  const byText = matches.filter((match) => match.excerpt !== undefined);
+  const byName = widthGroups(
+    matches.filter((match) => match.excerpt === undefined),
+  );
+  const byText = widthGroups(
+    matches.filter((match) => match.excerpt !== undefined),
+  );
+  // Keep the order findMatches ranked them in when everything fits.
+  if (byName.length + byText.length <= FIND_LIMIT)
+    return widthGroups(matches).map(groupLine);
+  const room = FIND_LIMIT - 1;
   if (!byText.length) {
     return [
-      ...matches.slice(0, room).map(line),
-      `… ${matches.length - room} more; add a word to narrow it`,
+      ...byName.slice(0, room).map(groupLine),
+      `… ${count(byName.slice(room))} more; add a word to narrow it`,
     ];
   }
   // Names fill the list first, but the last lines are kept for text hits,
   // so an agent sees them even when names alone would fill it.
-  const byName = matches.filter((match) => match.excerpt === undefined);
   const textRoom = Math.min(
     byText.length,
     Math.max(FIND_TEXT_LINES, room - byName.length),
@@ -1605,19 +2108,33 @@ function findLines(kit, query) {
   const texts = byText.slice(0, room - names.length);
   const left = [
     ...(byName.length > names.length
-      ? [`+${byName.length - names.length} more by name`]
+      ? [`+${count(byName.slice(names.length))} more by name`]
       : []),
     ...(byText.length > texts.length
-      ? [`+${byText.length - texts.length} more by on-screen text`]
+      ? [`+${count(byText.slice(texts.length))} more by on-screen text`]
       : []),
   ];
   return [
-    ...names.map(line),
-    ...texts.map(line),
+    ...names.map(groupLine),
+    ...texts.map(groupLine),
     `${left.join(", ")}; narrow the query`,
   ];
 }
 
+function findLines(kit, query) {
+  const matches = findMatches(kit, query);
+  if (!matches.length) {
+    const near = nearMatches(
+      query,
+      kit.rows.map((row) => row.id),
+    );
+    throw new KitError(
+      `nothing matches "${query}".${near.length ? ` Near: ${near.join(", ")}` : ""}`,
+    );
+  }
+  return findMatchLines(matches);
+}
+
 function showText(kit, id, full) {
   const row = requireRow(kit, id, "id");
   const html = readSnippet(kit, row);
@@ -1638,21 +2155,53 @@ function showText(kit, id, full) {
   return [head, ...lines, ...(truncated ? [tail] : [])].join("\n");
 }
 
-function infoText(kit) {
+/** gaps.json's ids: the frames a capture failed on. */
+function failedIds(dir) {
+  try {
+    const gaps = JSON.parse(readFileSync(join(dir, "gaps.json"), "utf8"));
+    if (!Array.isArray(gaps)) return [];
+    return gaps.map((gap) => gap?.id).filter((id) => typeof id === "string");
+  } catch {
+    // Optional: info prints the count without the ids.
+    return [];
+  }
+}
+
+/**
+ * One line: `sha7 built <iso> · stories N · routes N · failed N`, with the
+ * failed ids when there are five or fewer. `json` prints manifest.json.
+ */
+function infoText(kit, json) {
+  const manifest = kit.manifest ?? { missing: "manifest.json" };
+  if (json) return JSON.stringify(manifest, null, 2);
   const routes = kit.rows.filter((row) => rowSource(row) === "routes").length;
+  const sha = typeof manifest.sha === "string" ? manifest.sha.slice(0, 7) : "";
+  const built =
+    typeof manifest.built_at === "string" ? `built ${manifest.built_at}` : "";
+  const ids = failedIds(kit.dir);
+  const counted = manifest.counts?.failed;
+  const failed = typeof counted === "number" ? counted : ids.length;
+  const head = kit.manifest
+    ? [sha, built].filter(Boolean).join(" ") || "manifest.json"
+    : "no manifest.json";
   return [
-    JSON.stringify(kit.manifest ?? { missing: "manifest.json" }, null, 2),
-    `rows: ${kit.rows.length} (stories ${kit.rows.length - routes}, routes ${routes})`,
-  ].join("\n");
+    head,
+    `stories ${kit.rows.length - routes}`,
+    `routes ${routes}`,
+    `failed ${failed}${failed > 0 && failed <= 5 && ids.length ? ` (${ids.join(", ")})` : ""}`,
+  ].join(" · ");
 }
 
 // ── CLI ─────────────────────────────────────────────────────────────────────
 
 const USAGE = `usage: kit.mjs [--kit <dir>] <command>
-  info                         print the manifest
-  find <query>                 list up to ${FIND_LIMIT} rows whose id, title or on-screen text holds every word
+  info [--json]                sha, build time and counts (--json: the manifest)
+  find <query>                 up to ${FIND_LIMIT} lines of rows whose id, title or on-screen text holds
+                               every word; widths of one frame share a line: id@{1280,390}
   show <id> [--full]           path, size and an outline (--full: the markup)
-  compose --frame <id> [--slot <name>=<file>]… [--theme light|dark] [--show-new] --out <file>`;
+  compose --frame <id> [--slot <name>=<file>]… [--theme light|dark] [--show-new] [--css pruned|full] --out <file>
+                               --css full keeps every rule of the kit's CSS; the default
+                               keeps only rules the page's classes and ids can use`;
 
 function parseArgs(argv) {
   const options = { slots: [], positional: [] };
@@ -1669,7 +2218,9 @@ function parseArgs(argv) {
     else if (arg === "--slot") options.slots.push(value());
     else if (arg === "--theme") options.theme = value();
     else if (arg === "--out") options.out = value();
+    else if (arg === "--css") options.css = value();
     else if (arg === "--full") options.full = true;
+    else if (arg === "--json") options.json = true;
     else if (arg === "--show-new") options.showNew = true;
     else if (arg === "--help" || arg === "-h") options.help = true;
     else if (arg.startsWith("--")) throw new KitError(`unknown option ${arg}`);
@@ -1695,7 +2246,7 @@ export function run(
     const dir = resolve(options.kit ?? env.DESIGN_KIT_DIR ?? defaultDir);
     const kit = loadKit(dir);
     if (command === "info") {
-      io.out(infoText(kit));
+      io.out(infoText(kit, options.json));
     } else if (command === "find") {
       if (!rest.length) throw new KitError("find needs a query");
       io.out(findLines(kit, rest.join(" ")).join("\n"));
@@ -1718,6 +2269,7 @@ export function run(
         slots,
         theme: options.theme ?? "light",
         showNew: options.showNew,
+        css: options.css ?? "pruned",
       });
       writeFileSync(resolve(options.out), page);
       io.out(

package/src/templates/design-kit-skill.md

@@ -71,7 +71,7 @@ is missing.
 ## 3. Find what is real
 
 ```bash
-node "$KIT/kit.mjs" find button          # ≤ 30 lines: id, kind, width, bytes, title
+node "$KIT/kit.mjs" find button          # ≤ 30 lines: id (widths grouped), size, title
 node "$KIT/kit.mjs" show route:home@1280 # path, size and an outline with slots
 ```