@codepress/design-kit 0.11.0 → 0.13.0

package/README.md

@@ -392,6 +392,7 @@ design-kit init            [--root dir] [--dry-run] [--force] [--workflow-only]
 design-kit upload          --dir kit [--config f] [--branch b] [--sha commit]
 design-kit fetch           [--branch b] [--out dir] [--config f] [--repo owner/name]
                            [--token-file f]
+design-kit fetch           --url download-url --sha commit [--branch b] [--out dir]
 design-kit latest          [--branch b] [--config f] [--repo owner/name] [--token-file f]
 design-kit capture stories [--config f] [--out dir] [--storybook-dir dir]
                            [--only id,... | --only-file f] [--base previous-kit]
@@ -411,8 +412,19 @@ design-kit storybook-guide
 kit (`codepress`, `s3` and `r2`; with `github` it exits 2, since the
 workflow's upload step does it). `fetch` downloads the newest kit once per
 commit, into `$TMPDIR/design-kit-<sha>` unless `--out` says otherwise, and
-prints `path=`, `sha=` and `branch=`; a second `fetch` of the same commit
-downloads nothing. `latest` prints the newest kit's `sha=` and `created=`.
+prints `path=`, `sha=`, `branch=` and the kit's summary line (as `kit info`
+prints it); a second `fetch` of the same commit downloads nothing.
+`fetch --url <download_url> --sha <commit>` needs no key and no config: it
+installs from a download URL already looked up (with `codepress` storage, the
+`download_url` of the latest route, read through the CodePress Platform MCP)
+into the same cache folder, which it reuses when complete. It streams the zip to
+a scratch folder beside the target, unzips it there, checks that
+`manifest.json` names `--sha`, and renames it into place, so a refused or
+expired URL (`forbidden`), a broken zip (`bad_archive`) or another commit's kit
+(`sha_mismatch`) exits 1 with one line and leaves nothing behind, as does an
+`--out` folder that holds files but no kit (`out_not_empty`, left untouched). Of two
+fetches racing for one commit, the loser keeps the winner's folder. The URL's
+query string is never printed. `latest` prints the newest kit's `sha=` and `created=`.
 Without `--branch` they read the default branch. A store's refusal keeps its
 name (`forbidden`, `no_kit`, `repo_not_connected`, …), a store that cannot be
 reached is `kit_storage_unavailable`, and both exit 1.
@@ -521,23 +533,53 @@ 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] [--css pruned|full] --out page.html
+node kit.mjs figure --img shot.png [--href '#cp-page:<key>'] [--caption text] \
+  [--alt text] [--width px] --out figure.html
 ```
 
-`find` lists the rows holding every word of the query in their id, title,
+`figure` needs no kit: it writes a self-contained `<figure>` fragment with
+the `.png`, `.jpg` or `.webp` image as a data URI, inside a link when `--href`
+is given (a fragment such as `#cp-page:<key>`, which links a plan page to a
+screen page, or a relative link), and the caption and alt text escaped. It
+warns on stderr when the image is over 1 MB.
+
+`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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codepress/design-kit",
-  "version": "0.11.0",
+  "version": "0.13.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/cli.mjs

@@ -35,9 +35,13 @@ const USAGE = `usage: design-kit <command> [options]
                     (codepress, s3 or r2; github uploads in the workflow)
       --dir <kit> [--config <file>] [--branch <name>] [--sha <commit>]
   fetch             download the newest kit, once per commit (cached under
-                    $TMPDIR/design-kit-<sha>); prints path=, sha= and branch=
+                    $TMPDIR/design-kit-<sha>); prints path=, sha=, branch=
+                    and the kit's summary line
       [--branch <name>] [--out <dir>] [--config <file>] [--repo <owner/name>]
       [--token-file <path>]   codepress: the API key, if not CODEPRESS_API_KEY
+      --url <download_url> --sha <commit> [--branch <name>] [--out <dir>]
+                    install from the download_url of the latest route (read
+                    through the Platform MCP): no key and no config needed
   latest            print the newest kit's sha= and created=
       [--branch <name>] [--config <file>] [--repo <owner/name>]
       [--token-file <path>]
@@ -245,7 +249,9 @@ export async function main(argv = process.argv.slice(2), env = process.env) {
         ...(command === "upload"
           ? { dir: "value", sha: "value" }
           : { "token-file": "value" }),
-        ...(command === "fetch" ? { out: "value" } : {}),
+        ...(command === "fetch"
+          ? { out: "value", url: "value", sha: "value" }
+          : {}),
       };
       const options = parse(argv.slice(1), spec);
       const storage = await import("./storage/index.mjs");

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;
 
@@ -126,3 +134,27 @@ export function run(
 
 /** Whether this file is the script node was started with. */
 export function isMain(moduleUrl?: string, script?: string): boolean;
+
+/**
+ * The kit's one-line summary, as `kit info` prints it:
+ * `sha7 built <iso> · stories N · routes N · failed N` (the failed ids when
+ * there are five or fewer).
+ */
+export function kitSummaryLine(kit: Kit): string;
+
+/** Image bytes above which `kit figure` warns: 1 MB. */
+export const FIGURE_WARN_BYTES: number;
+
+/**
+ * `kit figure`'s fragment: a `<figure>` with the image as a data URI, inside
+ * `<a href>` when `href` is given (a fragment such as `#cp-page:<key>` or a
+ * relative link), and the caption escaped. `width` is CSS pixels.
+ */
+export function figureHtml(options: {
+  image: Uint8Array;
+  type: "image/png" | "image/jpeg" | "image/webp";
+  href?: string;
+  caption?: string;
+  alt?: string;
+  width?: string | number;
+}): string;

package/src/kit.mjs

@@ -3,11 +3,13 @@
  * 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] [--css pruned|full] --out <file>
+ *   node kit.mjs figure --img <file> [--href <#cp-page:key>] [--caption <text>]
+ *                       [--alt <text>] [--width <px>] --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.
@@ -1834,10 +1836,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 ?? "")
@@ -1848,10 +1856,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) {
@@ -1936,32 +2005,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),
@@ -1970,19 +2110,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);
@@ -2003,23 +2157,149 @@ 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 [];
+  }
+}
+
+/**
+ * The kit's one-line summary: `sha7 built <iso> · stories N · routes N ·
+ * failed N`, with the failed ids when there are five or fewer. `kit info`
+ * prints it, and so does `design-kit fetch` after `path=`.
+ */
+export function kitSummaryLine(kit) {
+  const manifest = kit.manifest ?? {};
   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(" · ");
+}
+
+/** `info`: the summary line; `json` prints manifest.json. */
+function infoText(kit, json) {
+  if (json)
+    return JSON.stringify(
+      kit.manifest ?? { missing: "manifest.json" },
+      null,
+      2,
+    );
+  return kitSummaryLine(kit);
+}
+
+// ── figure ──────────────────────────────────────────────────────────────────
+
+/** Image types `figure` embeds, by file extension. */
+const FIGURE_TYPES = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+};
+
+/** Above this many image bytes `figure` warns: the page carries them all. */
+export const FIGURE_WARN_BYTES = 1024 * 1024;
+
+function escapeHtml(value) {
+  return String(value)
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}
+
+/**
+ * A self-contained `<figure>`: the image as a data URI, inside a link when
+ * `href` is given, with an escaped caption. `href` must be a fragment or a
+ * relative link (`#cp-page:<key>` links plan pages); `width` is CSS pixels.
+ */
+export function figureHtml({ image, type, href, caption, alt, width }) {
+  if (
+    href !== undefined &&
+    (!href || !isSafeUrl(href) || /^data:/i.test(href.trim()))
+  )
+    throw new KitError(
+      `--href ${href}: use a fragment such as '#cp-page:<key>' or a relative link`,
+    );
+  let style = "max-width:100%;height:auto;display:block";
+  if (width !== undefined) {
+    const px = Number(width);
+    if (!(Number.isFinite(px) && px > 0))
+      throw new KitError(
+        `--width ${width}: use a positive number of CSS pixels`,
+      );
+    style = `width:${px}px;${style}`;
+  }
+  const src = `data:${type};base64,${image.toString("base64")}`;
+  let img = `<img src="${src}" alt="${escapeHtml(alt ?? caption ?? "")}" style="${style}">`;
+  if (href !== undefined) img = `<a href="${escapeHtml(href)}">${img}</a>`;
+  const figcaption =
+    caption === undefined
+      ? ""
+      : `\n  <figcaption>${escapeHtml(caption)}</figcaption>`;
+  return `<figure style="margin:0">\n  ${img}${figcaption}\n</figure>\n`;
+}
+
+/** `figure --img <file> --out <file>`: writes the fragment; no kit needed. */
+function figureCommand(options, io) {
+  if (!options.img)
+    throw new KitError("figure needs --img <file.png|jpg|webp>");
+  if (!options.out) throw new KitError("figure needs --out <file>");
+  const file = resolve(options.img);
+  const type = FIGURE_TYPES[extname(file).toLowerCase()];
+  if (!type)
+    throw new KitError(`--img ${options.img}: use a .png, .jpg or .webp file`);
+  if (!existsSync(file))
+    throw new KitError(`--img ${options.img}: no such file`);
+  const image = readFileSync(file);
+  const html = figureHtml({
+    image,
+    type,
+    href: options.href,
+    caption: options.caption,
+    alt: options.alt,
+    width: options.width,
+  });
+  if (image.length > FIGURE_WARN_BYTES)
+    io.err(
+      `kit: warning: ${options.img} is ${formatBytes(image.length)}; the page carries it all (shrink it below 1 MB)`,
+    );
+  const out = resolve(options.out);
+  writeFileSync(out, html);
+  io.out(`${out}  ${formatBytes(Buffer.byteLength(html))}`);
 }
 
 // ── 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] [--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`;
+                               keeps only rules the page's classes and ids can use
+  figure --img <file.png|jpg|webp> [--href '#cp-page:<key>'] [--caption <text>] [--alt <text>] [--width <px>] --out <file>
+                               a self-contained <figure>: the image as a data URI, linked when
+                               --href is given, the caption escaped (no kit needed)`;
 
 function parseArgs(argv) {
   const options = { slots: [], positional: [] };
@@ -2037,7 +2317,13 @@ function parseArgs(argv) {
     else if (arg === "--theme") options.theme = value();
     else if (arg === "--out") options.out = value();
     else if (arg === "--css") options.css = value();
+    else if (arg === "--img") options.img = value();
+    else if (arg === "--href") options.href = value();
+    else if (arg === "--caption") options.caption = value();
+    else if (arg === "--alt") options.alt = value();
+    else if (arg === "--width") options.width = 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}`);
@@ -2060,10 +2346,15 @@ export function run(
       io.out(USAGE);
       return command || options.help ? 0 : 2;
     }
+    if (command === "figure") {
+      if (rest.length) throw new KitError(`figure takes no ${rest[0]}`);
+      figureCommand(options, io);
+      return 0;
+    }
     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"));

package/src/storage/index.mjs

@@ -6,6 +6,8 @@
  *     upload({dir, branch, sha}) → {sha, branch, sizeBytes}
  *     fetch({branch, out})      → {path, sha, branch, cached}
  *
+ * `fetchFromUrl` (url.mjs) installs a kit from a download URL with no store.
+ *
  * `github` (the default) is a GitHub Actions artifact; `codepress` is
  * CodePress; `s3` and `r2` are the user's own bucket. The commands
  * `design-kit upload`, `fetch` and `latest` are here too.
@@ -18,6 +20,8 @@ import { bucketStorage } from "./bucket.mjs";
 import { codepressStorage } from "./codepress.mjs";
 import { findRepo, originDefaultBranch } from "./common.mjs";
 import { githubStorage } from "./github.mjs";
+import { fetchFromUrl } from "./url.mjs";
+import { kitSummaryLine, loadKit } from "../kit.mjs";
 
 export { StorageError } from "./common.mjs";
 
@@ -99,25 +103,47 @@ export async function uploadCommand(
 /**
  * `design-kit fetch [--branch b] [--out dir]`: downloads the newest kit
  * (once per commit: it is cached under $TMPDIR/design-kit-<sha>) and prints
- * `path=`, `sha=` and `branch=`.
+ * `path=`, `sha=`, `branch=` and the kit's summary line.
+ *
+ * `--url <download_url> --sha <commit>` installs from a download URL already
+ * looked up (no credential, no config): same cache, same output.
  */
 export async function fetchCommand(
   options,
   { env = process.env, gh, aws } = {},
 ) {
-  const config = loadConfig(options.config);
-  const storage = storageOf(config);
-  const store = storageFor(
-    storage,
-    contextFor(options, config, { env, gh, aws }),
-  );
-  const kit = await store.fetch({
-    branch: readBranch(options, storage, config.configDir),
-    out: options.out,
-  });
+  let kit;
+  if (options.url !== undefined || options.sha !== undefined) {
+    if (!options.url || !options.sha)
+      throw new ConfigError("fetch --url <download_url> needs --sha <commit>");
+    for (const name of ["config", "repo", "token-file"])
+      if (options[name] !== undefined)
+        throw new ConfigError(
+          `fetch --url takes no --${name}: it reads no store`,
+        );
+    kit = await fetchFromUrl({
+      url: options.url,
+      sha: options.sha,
+      branch: options.branch,
+      out: options.out,
+      env,
+    });
+  } else {
+    const config = loadConfig(options.config);
+    const storage = storageOf(config);
+    const store = storageFor(
+      storage,
+      contextFor(options, config, { env, gh, aws }),
+    );
+    kit = await store.fetch({
+      branch: readBranch(options, storage, config.configDir),
+      out: options.out,
+    });
+  }
   console.log(`path=${kit.path}`);
   console.log(`sha=${kit.sha}`);
   if (kit.branch) console.log(`branch=${kit.branch}`);
+  console.log(kitSummaryLine(loadKit(kit.path)));
   return 0;
 }
 

package/src/storage/url.mjs

@@ -0,0 +1,174 @@
+/**
+ * `design-kit fetch --url <download_url> --sha <commit>`: installs a kit
+ * from a download URL someone else already looked up (the `download_url` of
+ * `GET /design-kits/repos/{owner}/{repo}/latest`, read through the Platform
+ * MCP), with no credential and no config.
+ *
+ * The kit lands where the key path puts it, `$TMPDIR/design-kit-<sha>`, and a
+ * complete folder there is reused without downloading. Otherwise the zip is
+ * streamed to a scratch folder beside the target, unzipped there with the
+ * package's own reader, checked (its manifest.json must name `sha`), and
+ * renamed into place in one step. A fetch that loses a race to another for
+ * the same commit keeps the winner's folder. A failure leaves nothing behind.
+ */
+import {
+  createWriteStream,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+} from "node:fs";
+import http from "node:http";
+import https from "node:https";
+import { dirname, join, resolve } from "node:path";
+import { pipeline } from "node:stream/promises";
+
+import { StorageError, checkSha, isKit, kitCacheDir } from "./common.mjs";
+import { unzipTo } from "./zip.mjs";
+
+/** How long the download may stall before it counts as failed. */
+const DOWNLOAD_TIMEOUT_MS = Number(
+  process.env.DESIGN_KIT_REQUEST_TIMEOUT_MS || 120_000,
+);
+
+/** What an S3- or R2-style refusal is called, by status. */
+const REFUSED = {
+  400: "bad_request",
+  401: "unauthorized",
+  403: "forbidden",
+  404: "not_found",
+  410: "expired",
+};
+
+/** The query string of a URL replaced by `?…`, so a signature never prints. */
+export function redactUrl(url) {
+  return String(url).replace(/\?.*$/s, "?…");
+}
+
+/** Streams `url` into `file`. A non-2xx answer or a broken stream throws. */
+function download(url, file) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new StorageError("invalid_url", "--url is not a URL");
+  }
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:")
+    throw new StorageError(
+      "invalid_url",
+      "--url must be an https: download URL",
+    );
+  const client = parsed.protocol === "http:" ? http : https;
+  return new Promise((resolvePromise, reject) => {
+    const req = client.get(parsed, { timeout: DOWNLOAD_TIMEOUT_MS }, (res) => {
+      const status = res.statusCode ?? 0;
+      if (status < 200 || status >= 300) {
+        res.resume();
+        const code =
+          REFUSED[status] ??
+          (status >= 500 ? "kit_storage_unavailable" : `http_${status}`);
+        const hint =
+          status === 403 || status === 400 || status === 410
+            ? "; the download URL may have expired, so ask for a fresh one"
+            : "";
+        reject(
+          new StorageError(
+            code,
+            `downloading ${redactUrl(url)} was refused (${status})${hint}`,
+          ),
+        );
+        return;
+      }
+      pipeline(res, createWriteStream(file)).then(resolvePromise, (error) =>
+        reject(
+          new StorageError(
+            "download_failed",
+            `downloading ${redactUrl(url)} broke off (${error.code ?? error.message})`,
+          ),
+        ),
+      );
+    });
+    req.on("timeout", () => req.destroy(new Error("no answer in time")));
+    req.on("error", (error) =>
+      reject(
+        new StorageError(
+          "kit_storage_unavailable",
+          `could not reach ${parsed.host} (${error.code ?? error.message})`,
+        ),
+      ),
+    );
+  });
+}
+
+/** Nothing when manifest.json's `sha` starts with `sha`, else a StorageError. */
+function checkManifestSha(dir, sha) {
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(join(dir, "manifest.json"), "utf8"));
+  } catch {
+    throw new StorageError(
+      "not_a_kit",
+      "the download has no readable manifest.json",
+    );
+  }
+  const named =
+    typeof manifest?.sha === "string" ? manifest.sha.toLowerCase() : "";
+  const wanted = sha.toLowerCase();
+  // A short --sha may name the manifest's full sha, never the other way round.
+  if (!named || !named.startsWith(wanted))
+    throw new StorageError(
+      "sha_mismatch",
+      `the downloaded kit is of ${named.slice(0, 12) || "no commit"}, not ${wanted.slice(0, 12)}`,
+    );
+}
+
+/**
+ * Installs the kit of commit `sha` from `url` into `out` (default
+ * `$TMPDIR/design-kit-<sha>`): `{path, sha, branch, cached}`.
+ */
+export async function fetchFromUrl({
+  url,
+  sha,
+  branch,
+  out,
+  env = process.env,
+}) {
+  if (!url)
+    throw new StorageError("invalid_url", "--url needs the kit's download URL");
+  checkSha(sha, "--sha");
+  const path = resolve(out ?? kitCacheDir(sha, env));
+  const result = { path, sha, branch };
+  if (isKit(path)) return { ...result, cached: true };
+  mkdirSync(dirname(path), { recursive: true });
+  const scratch = mkdtempSync(`${path}.partial-`);
+  try {
+    const zipFile = join(scratch, "kit.zip");
+    const unpacked = join(scratch, "kit");
+    await download(url, zipFile);
+    try {
+      unzipTo(readFileSync(zipFile), unpacked);
+    } catch (error) {
+      throw new StorageError(
+        "bad_archive",
+        `the download is not a whole kit zip (${error.message})`,
+      );
+    }
+    checkManifestSha(unpacked, sha);
+    try {
+      renameSync(unpacked, path);
+    } catch (error) {
+      // Another fetch of the same commit got there first: keep its folder.
+      if (isKit(path)) return { ...result, cached: true };
+      if (error.code === "ENOTEMPTY" || error.code === "EEXIST")
+        throw new StorageError(
+          "out_not_empty",
+          `${path} exists and is not a kit; choose another --out`,
+        );
+      throw error;
+    }
+    return { ...result, cached: false };
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+}

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
 ```