@codepress/design-kit 0.5.0 → 0.7.0

package/README.md

@@ -252,7 +252,12 @@ temporary folder that is removed afterwards.
 - `viewport`: each story's first capture, unless the story sets
   `parameters.viewport.defaultViewport` (default 1280×800).
 - `widths`: more captures for stories whose title matches the `titles`
-  regular expression.
+  regular expression. A story that only works at some widths (a phone-only
+  drawer whose `play` opens what the desktop layout never shows) lists its
+  own with `parameters: { designKit: { widths: [390] } }` (numbers or
+  `{width, height}`): it is captured at exactly those, and a width it leaves
+  out is neither a row nor a gap. A failure at a width it lists is still a
+  gap, and an empty or malformed list is ignored.
 - `fonts`: `{dir, faces: [{family, file, weight?, style?, variable?,
 fallback?}]}` gives every story these faces (`file` is a name glob in `dir`;
   `variable` sets a CSS variable on `:root` for apps that read their font from
@@ -261,6 +266,11 @@ fallback?}]}` gives every story these faces (`file` is a name glob in `dir`;
 - `fixedTime`: the instant `Date` returns (default `2026-01-01T12:00:00.000Z`).
 - `gaps`: lists the component files no story covers in `gaps.json`.
   `componentGlob` is relative to `root`; stories, tests and specs never count.
+  A file with nothing to show (a context provider, a controller, a hook
+  wrapper) says so with a comment, `// design-kit: no-story <reason>` (a block
+  or JSX comment works too): its row has reason `exempt` and the reason as
+  `detail`, so a report can list it apart. A marker with no reason exempts
+  nothing; the row stays `no story`.
 
 ### `pages`
 
@@ -362,12 +372,15 @@ both with the same `--out`.
 Exit codes: 0 done, 1 a capture could not run (no Storybook build, the app
 did not start, a forbidden string) or `init` found the repository already set
 up, 2 a config or usage error. A story or page that fails is a
-`gaps.json` row and does not fail the run.
+`gaps.json` row and does not fail the run. That includes a story that holds
+the page's main thread: every wait on its page has a timer outside the page,
+so it becomes a `timeout` gap instead of stalling the run.
 
 Operational knobs: `DESIGN_KIT_CONCURRENCY` (browser pages at once, default
 4), `DESIGN_KIT_STORY_TIMEOUT_MS` (render and, separately, settle budget per
 story, default 15000), `DESIGN_KIT_QUIET_MS` (how long the DOM must stay
-unchanged, default 600), `DESIGN_KIT_TIMINGS_FILE` (per-phase capture times),
+unchanged, default 600), `DESIGN_KIT_PARAMS_READ_MS` (how long a failed capture
+waits to read the story's `designKit.widths`, default 1000), `DESIGN_KIT_TIMINGS_FILE` (per-phase capture times),
 `DESIGN_KIT_STOP_TIMEOUT_MS` (how long stopping the app may take).
 
 ## Capture rules
@@ -378,7 +391,10 @@ unchanged, default 600), `DESIGN_KIT_TIMINGS_FILE` (per-phase capture times),
 - A story is captured after Storybook's `storyRendered` event (its `play`
   function has finished), fonts, frame and image loads, no request in flight,
   and six frames plus `DESIGN_KIT_QUIET_MS` with no DOM change. A story that
-  throws, never renders or never stops changing is a gap.
+  throws, never renders or never stops changing is a gap. A story driven by a
+  live timer or a looping script can tell it is being captured from
+  `window.__DESIGN_KIT_CAPTURE__ === true`, set before any page script runs,
+  and render one still state of it instead.
 - Attributes are serialized in sorted order, and React `useId` values are
   renumbered in pages, so the markup depends on the final state, not on timing.
 - Story captures only reach the local Storybook server. Same-origin images
@@ -392,6 +408,7 @@ design-kit/
   manifest.json   {kit_version, sha, built_at, counts, sources, theme?, css?}
   index.json      story rows, sorted by id
   routes.json     page rows
+  text.json       {id: the row's visible text, first 600 characters}
   html/story--<id>@<w>.html, html/route--<name>@<w>.html
   css/stories.css every rule the Storybook preview loaded, deduplicated
   css/routes.css  every rule the captured pages loaded, deduplicated
@@ -418,11 +435,31 @@ 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 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
 ```
 
+`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
+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
+decoded and whitespace collapsed, with the row's `data-kit-slot` regions
+first (so a page's own words come ahead of the navigation every page
+repeats), cut to 600 characters. Rows an incremental build copies from its
+base get text too, and a page capture refuses a `text.json` holding a
+`forbidStrings` value as it does the markup. A kit without `text.json` finds
+by id, title, component and source file only.
+
 `compose` writes one self-contained page: the frame's markup with slots
 filled and every `<kit-snippet id="…">` expanded, its CSS inlined, every
 relative `url()` that names a file in the kit (fonts included) as a data URI,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codepress/design-kit",
-  "version": "0.5.0",
+  "version": "0.7.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/capture-pages.mjs

@@ -42,6 +42,7 @@ import {
   sourceCollisions,
 } from "./pages.mjs";
 import { ConfigError } from "./config.mjs";
+import { kitText, kitTextJson, visibleText } from "./kit.mjs";
 import { loadPlaywright } from "./playwright.mjs";
 
 const STOP_TIMEOUT_MS =
@@ -601,6 +602,8 @@ export async function capturePages(config, options = {}) {
           const found = findForbidden(
             [
               html,
+              // The words text.json will hold, entities decoded.
+              visibleText(html),
               JSON.stringify(capture.htmlAttrs),
               JSON.stringify(capture.bodyAttrs),
             ].join("\n"),
@@ -774,6 +777,20 @@ export function writePagesKit(
         )
         .join("\n"),
     );
+  const sortedRows = mergeRoutes(existingRows, rows, owns);
+  // text.json covers the whole kit, stories included, and is checked for
+  // forbidden values before anything is removed or written.
+  const text = kitTextJson(
+    kitText(
+      [...asArray(readJson(path.join(out, "index.json"))), ...sortedRows],
+      (file) =>
+        files.get(file) ?? fs.readFileSync(path.join(out, file), "utf8"),
+    ),
+  );
+  if (findForbidden(text, needles))
+    throw new Error(
+      "text.json carries a forbidStrings value; refusing to write the kit",
+    );
   fs.mkdirSync(path.join(out, "html"), { recursive: true });
   fs.mkdirSync(path.join(out, "css"), { recursive: true });
   // This half's files only: earlier page captures go, story files stay. A
@@ -807,11 +824,11 @@ export function writePagesKit(
     for (const file of stale) fs.rmSync(path.join(out, file), { force: true });
   }
 
-  const sortedRows = mergeRoutes(existingRows, rows, owns);
   const written = [
     ...[...files.entries()].sort(byKey(([file]) => file)),
     ["routes.json", kitJson(sortedRows)],
     [routeCssFile(source), css],
+    ["text.json", text],
   ];
   for (const [file, text] of written) {
     if (findForbidden(text, needles))

package/src/capture-stories.mjs

@@ -6,6 +6,7 @@
  * DESIGN_KIT_CONCURRENCY caps the browser pages working at once (default 4);
  * DESIGN_KIT_STORY_TIMEOUT_MS bounds each capture (default 15000);
  * DESIGN_KIT_QUIET_MS is how long the DOM must stay unchanged (default 600);
+ * DESIGN_KIT_PARAMS_READ_MS bounds reading a failed story's widths (default 1000);
  * DESIGN_KIT_TIMINGS_FILE, when set, receives the per-phase time breakdown.
  * Needs Playwright's Chromium (`npx playwright install chromium`).
  */
@@ -29,6 +30,7 @@ import { extname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { globToRegExp, matchFile } from "./glob.mjs";
+import { writeKitText } from "./kit.mjs";
 import { loadPlaywright, playwrightVersion } from "./playwright.mjs";
 
 export { playwrightVersion };
@@ -45,6 +47,38 @@ const QUIET_FRAMES = 6;
  */
 const quietMs =
   Number.parseInt(process.env.DESIGN_KIT_QUIET_MS ?? "600", 10) || 0;
+/**
+ * DESIGN_KIT_PARAMS_READ_MS: how long a failed capture waits to read the
+ * story's `designKit.widths` from the preview (default 1000).
+ */
+const paramsReadMs =
+  Number.parseInt(process.env.DESIGN_KIT_PARAMS_READ_MS ?? "1000", 10) || 1000;
+
+/**
+ * The console prefix a story's page announces its own widths with at
+ * storyPrepared. A console message reaches node even when the story holds
+ * the main thread right after, which a read of the page never would.
+ */
+const WIDTHS_ANNOUNCEMENT = "design-kit:widths ";
+
+/** A page that stopped answering: its main thread is held by the story. */
+class Unresponsive extends Error {}
+
+/**
+ * Settles with `promise`, or rejects with Unresponsive after `ms`.
+ * Playwright's evaluate has no timeout, and one set in the page cannot fire
+ * while a story holds the page's main thread, so every wait on a story's
+ * page goes through this node-side timer. The timer is cleared either way.
+ */
+function bounded(promise, ms, detail) {
+  let timer;
+  return Promise.race([
+    promise,
+    new Promise((_, fail) => {
+      timer = setTimeout(() => fail(new Unresponsive(detail)), ms);
+    }),
+  ]).finally(() => clearTimeout(timer));
+}
 
 /** Storybook's built-in viewport names (minimal set plus the iPhones in use). */
 const NAMED_VIEWPORTS = {
@@ -151,15 +185,50 @@ export function mergeManifest(existing, { sha, builtAt, stories, theme }) {
   };
 }
 
+/**
+ * A story's own widths, from `parameters.designKit.widths`: numbers or
+ * `{width, height}` entries. Anything else, or an empty list, is no list,
+ * so a malformed parameter never drops a story.
+ */
+export function ownWidths(raw) {
+  if (!Array.isArray(raw)) return null;
+  const list = [];
+  for (const entry of raw) {
+    const width = typeof entry === "number" ? entry : entry?.width;
+    const height = typeof entry === "number" ? undefined : entry?.height;
+    if (!Number.isInteger(width) || width <= 0) continue;
+    if (list.some((planned) => planned.width === width)) continue;
+    list.push(
+      Number.isInteger(height) && height > 0 ? { width, height } : { width },
+    );
+  }
+  return list.length ? list : null;
+}
+
 /**
  * Which captures a story gets: its declared viewport or the default, plus
  * each configured width whose `titles` pattern matches the story's title.
+ * A story that lists its own widths (`parameters.designKit.widths`, see
+ * ownWidths) gets exactly those, each with its listed height, else the
+ * height the declared viewport, default or a configured width has for it,
+ * else the default height.
  */
 export function plannedViewports(
   title,
   declared,
   { viewport = DEFAULT_VIEWPORT, widths = [] } = {},
+  own = null,
 ) {
+  if (own?.length) {
+    const known = [declared, viewport, ...widths].filter(Boolean);
+    return own.map(({ width, height }) => ({
+      width,
+      height:
+        height ??
+        known.find((size) => size.width === width && size.height)?.height ??
+        viewport.height,
+    }));
+  }
   const first = declared ?? viewport;
   const list = [first];
   for (const extra of widths) {
@@ -276,7 +345,7 @@ export function fontCss(base, fonts, files = fontFiles(fonts)) {
 }
 
 /** Runs before any page script: a seeded Math.random, the font CSS, and a channel tap. */
-function pageInit({ css, families }) {
+function pageInit({ css, families, width, announcement }) {
   let seed = 0x2f6b9a1d;
   Math.random = () => {
     seed = (seed + 0x6d2b79f5) | 0;
@@ -297,6 +366,9 @@ function pageInit({ css, families }) {
   }
   const kit = { outcome: null, detail: "", pending: 0 };
   window.__kit = kit;
+  // Public: a story with live data or a running animation can render a
+  // still state of it when this is set (README "Capture rules").
+  window.__DESIGN_KIT_CAPTURE__ = true;
   // In-flight requests, so settling can wait for them rather than a timer.
   const track = (promise) => {
     kit.pending += 1;
@@ -345,6 +417,25 @@ function pageInit({ css, families }) {
         finish("threw", `play: ${describe(e)}`),
       );
       value.on("storyMissing", () => finish("missing"));
+      // A story that lists its own widths and leaves this one out is not
+      // captured here: no render, no play, no gap (ownWidths).
+      value.on("storyPrepared", (event) => {
+        const own = event?.parameters?.designKit?.widths;
+        if (!Array.isArray(own)) return;
+        kit.widths = own;
+        try {
+          console.debug(`${announcement}${JSON.stringify(own)}`);
+        } catch {
+          // A list that cannot be serialized is read from __kit instead.
+        }
+        // The same rule as ownWidths: positive integer widths only, and no
+        // usable width means no list, so a malformed one never skips.
+        const listed = own
+          .map((entry) => (typeof entry === "number" ? entry : entry?.width))
+          .filter((value) => Number.isInteger(value) && value > 0);
+        if (listed.length && !listed.includes(width))
+          finish("skipped", `not listed in designKit.widths`);
+      });
     },
   });
   window.__kitLoaded = new WeakSet();
@@ -442,6 +533,7 @@ async function extract() {
     ".sb-preparing-story,.sb-preparing-docs,.sb-nopreview,.sb-errordisplay,#storybook-docs,script,noscript,template,link,[data-kit-inject]";
   const story = window.__STORYBOOK_PREVIEW__?.currentRender?.story;
   const parameters = story?.parameters ?? {};
+  const widths = parameters.designKit?.widths ?? null;
   const viewport = parameters.viewport ?? {};
   let declared = null;
   const name = viewport.defaultViewport;
@@ -577,6 +669,7 @@ async function extract() {
     html,
     sheets,
     declared,
+    widths,
     bodyClass,
     empty: !rootHasContent && !portalHasContent,
   };
@@ -638,7 +731,12 @@ async function freshPage({
   const page = await context.newPage();
   page.on("pageerror", () => {});
   await page.clock.setFixedTime(new Date(fixedTime));
-  await page.addInitScript(pageInit, { css, families });
+  await page.addInitScript(pageInit, {
+    css,
+    families,
+    width: viewport.width,
+    announcement: WIDTHS_ANNOUNCEMENT,
+  });
   return { context, page, cdp: await context.newCDPSession(page) };
 }
 
@@ -659,6 +757,20 @@ async function captureTimed(
     }));
   const { context, page, cdp } = slot;
   let reusable = false;
+  // The widths this story announced, heard even if its page then stops
+  // answering (WIDTHS_ANNOUNCEMENT).
+  let announced;
+  const hear = (message) => {
+    if (message.type() !== "debug") return;
+    const text = message.text();
+    if (!text.startsWith(WIDTHS_ANNOUNCEMENT)) return;
+    try {
+      announced = JSON.parse(text.slice(WIDTHS_ANNOUNCEMENT.length));
+    } catch {
+      // Not ours after all; the bounded read below still runs.
+    }
+  };
+  page.on("console", hear);
   try {
     await cdp.send("Storage.clearDataForOrigin", {
       origin,
@@ -673,18 +785,50 @@ async function captureTimed(
       `${origin}/iframe.html?id=${encodeURIComponent(story.id)}&viewMode=story&globals=a11y.manual:!true`,
       { waitUntil: "domcontentloaded", timeout },
     );
-    const outcome = await page
-      .waitForFunction(() => window.__kit?.outcome, null, {
-        timeout: Math.max(1000, deadline - Date.now()),
-        polling: 50,
-      })
-      .then(() => page.evaluate(() => ({ ...window.__kit })))
-      .catch(() => ({
-        outcome: "timeout",
-        detail: `no storyRendered within ${timeout}ms`,
-      }));
+    // The node-side timer bounds the wait too: Playwright's own timeout never
+    // fires while a story holds the page's main thread.
+    const notRendered = {
+      outcome: "timeout",
+      detail: `no storyRendered within ${timeout}ms`,
+    };
+    const outcome = await bounded(
+      page
+        .waitForFunction(() => window.__kit?.outcome, null, {
+          timeout: Math.max(1000, deadline - Date.now()),
+          polling: 50,
+        })
+        .then(() => page.evaluate(() => ({ ...window.__kit }))),
+      Math.max(1000, deadline - Date.now()) + 1000,
+    ).catch(() => notRendered);
     if (outcome.outcome !== "rendered") {
+      // The story's own widths: from storyPrepared, or read from the preview
+      // when this Storybook sends no parameters with it.
+      // Bounded: a story that holds the main thread (the usual reason for a
+      // timeout) would never answer, and the lane would never finish.
+      const own = ownWidths(
+        outcome.widths ??
+          announced ??
+          (await bounded(
+            page.evaluate(
+              () =>
+                window.__STORYBOOK_PREVIEW__?.currentRender?.story?.parameters
+                  ?.designKit?.widths ?? null,
+            ),
+            paramsReadMs,
+          ).catch(() => null)),
+      );
+      // Left out of the story's own widths: not a capture and not a gap.
+      // Any other failure stays one.
+      if (
+        outcome.outcome === "skipped" ||
+        (own && !own.some((entry) => entry.width === viewport.width))
+      ) {
+        // A page that timed out may still be held: never park it.
+        reusable = outcome.outcome !== "timeout";
+        return { skipped: true, widths: own };
+      }
       return {
+        widths: own,
         failure: {
           reason: outcome.outcome === "missing" ? "missing" : outcome.outcome,
           detail: outcome.detail,
@@ -701,7 +845,12 @@ async function captureTimed(
     // guests one after another. Settle the guests, then the host, until a
     // round brings no new frame and no host change.
     const settleBy = Date.now() + timeout;
-    let settled = (await page.evaluate(settle, quiet)).settled;
+    // `settle` gives up in the page after `timeout`; a second more covers the
+    // round trip, so only a page that stopped answering reaches the bound.
+    const unanswered = `page stopped answering after storyRendered (${timeout}ms)`;
+    const settleOn = (target) =>
+      bounded(target.evaluate(settle, quiet), timeout + 1000, unanswered);
+    let settled = (await settleOn(page)).settled;
     let known = new Set();
     while (settled) {
       const guests = page
@@ -711,12 +860,16 @@ async function captureTimed(
       if (!fresh && known.size === 0) break;
       known = new Set(guests);
       const results = await Promise.all(
-        // A frame that navigated away or detached has nothing left to wait for.
+        // A frame that navigated away or detached has nothing left to wait
+        // for; one that stopped answering is a timeout like its host.
         guests.map((frame) =>
-          frame.evaluate(settle, quiet).catch(() => ({ settled: true })),
+          settleOn(frame).catch((error) => {
+            if (error instanceof Unresponsive) throw error;
+            return { settled: true };
+          }),
         ),
       );
-      const host = await page.evaluate(settle, quiet);
+      const host = await settleOn(page);
       settled =
         results.every((result) => result.settled) &&
         host.settled &&
@@ -732,7 +885,11 @@ async function captureTimed(
       };
     }
     step("serialize");
-    const result = await page.evaluate(extract);
+    const result = await bounded(
+      page.evaluate(extract),
+      timeout,
+      `page stopped answering while serializing (${timeout}ms)`,
+    );
     // An inline sheet is keyed by its text, which resolved its url()s against
     // this run's server; the port must not reach the kit.
     for (const sheet of result.sheets)
@@ -746,38 +903,48 @@ async function captureTimed(
       };
     }
     reusable = true;
-    return { result };
+    return { result, widths: ownWidths(result.widths ?? outcome.widths) };
   } catch (error) {
     return {
       failure: {
-        reason: /Timeout/i.test(String(error)) ? "timeout" : "threw",
+        reason:
+          error instanceof Unresponsive || /Timeout/i.test(String(error))
+            ? "timeout"
+            : "threw",
         detail: String(error?.message ?? error)
           .split("\n")[0]
           .slice(0, 500),
       },
     };
   } finally {
+    page.off("console", hear);
     step("close");
     const parked =
       reusable &&
       parkedCount() < parkLimit &&
-      (await page
-        // Session storage lives with the tab, not the origin's data, so it
-        // is cleared on the story's own page before leaving it.
-        .evaluate(() => sessionStorage.clear())
-        .then(() => page.goto("about:blank"))
-        .then(() =>
-          page.evaluate(() => {
-            window.name = "";
-          }),
-        )
+      (await bounded(
+        page
+          // Session storage lives with the tab, not the origin's data, so it
+          // is cleared on the story's own page before leaving it.
+          .evaluate(() => sessionStorage.clear())
+          .then(() => page.goto("about:blank", { timeout }))
+          .then(() =>
+            page.evaluate(() => {
+              window.name = "";
+            }),
+          ),
+        timeout,
+      )
         .then(() => true)
         .catch(() => false));
     if (parked) {
       const list = idlePages.get(key) ?? [];
       list.push(slot);
       idlePages.set(key, list);
-    } else await context.close().catch(() => {});
+    } else {
+      // A context whose page is held is left to browser.close() at the end.
+      await bounded(context.close(), timeout).catch(() => {});
+    }
   }
 }
 
@@ -829,11 +996,32 @@ function storybookStories(buildDir) {
     .sort((a, b) => (a.id < b.id ? -1 : 1));
 }
 
+/**
+ * The reason a `design-kit: no-story <reason>` comment gives (a `//`, block or
+ * JSX comment anywhere in the file), or null when there is none or its reason
+ * is empty: a bare marker exempts nothing.
+ */
+export function noStoryReason(source) {
+  const marker =
+    /(?:\/\/|\/\*|^[ \t]*\*)[ \t]*design-kit:[ \t]*no-story\b([^\n]*)/gm;
+  for (const match of String(source).matchAll(marker)) {
+    const reason = match[1]
+      .replace(/\*\/.*$/, "")
+      .replace(/[}\s]+$/, "")
+      .trim();
+    if (reason) return reason;
+  }
+  return null;
+}
+
 /**
  * Component files nothing documents: files under `gaps.sourceRoot` whose path
  * from the Storybook project matches `gaps.componentGlob`, minus stories,
  * tests and specs, that no story names as its component or import. Paths in
- * the rows are relative to the config file's folder.
+ * the rows are relative to the config file's folder. A file carrying a
+ * `design-kit: no-story <reason>` comment (a context, a controller, a hook
+ * wrapper) is an `exempt` row with that reason as its detail, listed apart
+ * so a person can check the reason; with an empty reason it stays `no story`.
  */
 export function componentsWithoutStories(stories, { gaps, root, configDir }) {
   const documented = new Set(
@@ -855,10 +1043,13 @@ export function componentsWithoutStories(stories, { gaps, root, configDir }) {
       } else if (!/\.(stories|test|spec)\.[cm]?[jt]sx?$/.test(name.name)) {
         const rel = relative(root, path).split(sep).join("/");
         if (matchFile(pattern, rel) && !documented.has(rel)) {
-          out.push({
-            component: relative(configDir, path).split(sep).join("/"),
-            reason: "no story",
-          });
+          const component = relative(configDir, path).split(sep).join("/");
+          const exempt = noStoryReason(readFileSync(path, "utf8"));
+          out.push(
+            exempt
+              ? { component, reason: "exempt", detail: exempt }
+              : { component, reason: "no story" },
+          );
         }
       }
     }
@@ -1002,7 +1193,11 @@ export async function captureStories(config, options = {}) {
     const keepSheetsOnce = sheetStore();
     // What the timings report needs from a capture, without its result.
     const attempt = (capture) => {
-      const record = { timing: capture.timing, failure: capture.failure };
+      const record = {
+        timing: capture.timing,
+        failure: capture.failure,
+        skipped: capture.skipped,
+      };
       attempts.push(record);
       return record;
     };
@@ -1019,16 +1214,28 @@ export async function captureStories(config, options = {}) {
         fixedTime,
       });
       const firstAttempt = attempt(first);
-      let viewports = plannedViewports(story.title, null, planning);
-      const results = new Map([[planning.viewport.width, first]]);
-      if (first.result) {
-        const declared = viewportFor(first.result.declared);
-        viewports = plannedViewports(story.title, declared, planning);
-        if (declared) {
-          results.delete(planning.viewport.width);
-          firstAttempt.discarded = true;
-        }
-      }
+      // The story's declared viewport and own widths are known once it has
+      // loaded at the default one; that first capture is kept only when the
+      // plan still has the default viewport in it.
+      const declared = first.result ? viewportFor(first.result.declared) : null;
+      const viewports = plannedViewports(
+        story.title,
+        declared,
+        planning,
+        first.widths,
+      );
+      const results = new Map();
+      if (
+        !first.skipped &&
+        !declared &&
+        viewports.some(
+          (viewport) =>
+            viewport.width === planning.viewport.width &&
+            viewport.height === planning.viewport.height,
+        )
+      ) {
+        results.set(planning.viewport.width, first);
+      } else if (!first.skipped) firstAttempt.discarded = true;
       for (const viewport of viewports) {
         if (!results.has(viewport.width)) {
           const capture = await captureOne({
@@ -1046,6 +1253,7 @@ export async function captureStories(config, options = {}) {
         }
         const capture = results.get(viewport.width);
         const id = kitId(story.id, viewport.width);
+        if (capture.skipped) continue;
         if (capture.failure) {
           failures.push({ id, ...capture.failure });
         } else {
@@ -1179,6 +1387,9 @@ export async function captureStories(config, options = {}) {
       join(out, "index.json"),
       `${JSON.stringify(rows, null, 1)}\n`,
     );
+    // Every row's on-screen words for `kit find`, rows kept from the base
+    // and the pages' rows included, so an incremental build is complete.
+    writeKitText(out);
 
     const storyGaps = [
       ...failures,
@@ -1236,6 +1447,7 @@ export async function captureStories(config, options = {}) {
     const timings = {
       ...timingBreakdown(attempts),
       discarded: attempts.filter((a) => a.discarded).length,
+      skipped: attempts.filter((a) => a.skipped).length,
       lanes: concurrency,
       quiet_ms: quietMs,
       timeout_ms: timeout,
@@ -1255,6 +1467,9 @@ export async function captureStories(config, options = {}) {
     return { out, rows: rows.length, failed: storyGaps.length };
   } finally {
     await browser?.close().catch(() => {});
+    // Parked pages belong to this browser; a later capture in the same
+    // process must not pick one up.
+    idlePages.clear();
     server?.close();
     if (ownedBuild) rmSync(ownedBuild, { recursive: true, force: true });
   }

package/src/kit.d.ts

@@ -30,13 +30,48 @@ export interface Kit {
   manifest: KitManifest | null;
   rows: KitRow[];
   byId: Map<string, KitRow>;
+  /** Each row's visible text by id, from text.json; absent in older kits. */
+  text?: Map<string, string>;
 }
 
 export function loadKit(dir: string): Kit;
 
-/** Rows whose id, title, component or source file holds every word. */
+/** One `find` result; `excerpt` is set when a word matched only the row's text. */
+export interface KitMatch {
+  row: KitRow;
+  excerpt?: string;
+}
+
+/**
+ * Rows whose id, title, component, source file or visible text holds every
+ * word: id matches first, then title, component or source file, then text.
+ */
+export function findMatches(kit: Kit, query: string): KitMatch[];
+
+/** The rows of `findMatches`, in the same order. */
 export function find(kit: Kit, query: string): KitRow[];
 
+/** Characters of visible text text.json keeps per row: 600. */
+export const TEXT_LIMIT: number;
+
+/**
+ * A row's on-screen words: text outside scripts, styles, SVG, the head and
+ * templates, entities decoded, whitespace collapsed, at most `limit` characters.
+ */
+export function visibleText(html: string, limit?: number): string;
+
+/** text.json's content for `rows`, reading each row's markup by its `file`. */
+export function kitText(
+  rows: KitRow[],
+  read: (file: string) => string,
+): Record<string, string>;
+
+/** text.json as written. */
+export function kitTextJson(text: Record<string, string>): string;
+
+/** Rebuilds `dir`/text.json from the rows and markup already in the kit. */
+export function writeKitText(dir: string): string;
+
 /** Up to five candidates, closest first. */
 export function nearMatches(wanted: string, candidates: string[]): string[];
 

package/src/kit.mjs

@@ -4,7 +4,7 @@
  * always match. Pure Node: no dependencies, no network.
  *
  *   node kit.mjs info
- *   node kit.mjs find <query>
+ *   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>
@@ -17,6 +17,8 @@ import { basename, dirname, extname, join, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 const FIND_LIMIT = 30;
+/** Of FIND_LIMIT, the lines kept for rows found by on-screen text. */
+const FIND_TEXT_LINES = 5;
 const SHOW_LIMIT = 2048;
 const SNIPPET_DEPTH = 8;
 /**
@@ -35,7 +37,10 @@ function readJson(file, fallback) {
   return JSON.parse(readFileSync(file, "utf8"));
 }
 
-/** Story rows from index.json plus route rows from routes.json, by id. */
+/**
+ * Story rows from index.json plus route rows from routes.json, by id, and
+ * each row's visible text from text.json when the kit has one.
+ */
 export function loadKit(dir) {
   const manifest = readJson(join(dir, "manifest.json"), null);
   const rows = new Map();
@@ -50,7 +55,15 @@ export function loadKit(dir) {
   const sorted = [...rows.values()].sort((a, b) =>
     a.id < b.id ? -1 : a.id > b.id ? 1 : 0,
   );
-  return { dir, manifest, rows: sorted, byId: new Map(rows) };
+  const text = readText(dir);
+  return {
+    dir,
+    manifest,
+    rows: sorted,
+    byId: new Map(rows),
+    // Only a kit with text.json has it, so an older kit loads as before.
+    ...(text ? { text } : {}),
+  };
 }
 
 function rowSource(row) {
@@ -179,19 +192,24 @@ function parseAttributes(source) {
 
 /** Tokens with offsets: open / close / text / comment. */
 export function tokenize(html) {
-  const tokens = [];
+  return [...scan(html)];
+}
+
+/** `tokenize`, one token at a time, so a reader can stop early. */
+function* scan(html) {
+  let lower = null;
   let i = 0;
   while (i < html.length) {
     const lt = html.indexOf("<", i);
     if (lt < 0) {
-      tokens.push({ type: "text", start: i, end: html.length });
+      yield { type: "text", start: i, end: html.length };
       break;
     }
-    if (lt > i) tokens.push({ type: "text", start: i, end: lt });
+    if (lt > i) yield { type: "text", start: i, end: lt };
     if (html.startsWith("<!--", lt)) {
       const close = html.indexOf("-->", lt + 4);
       const end = close < 0 ? html.length : close + 3;
-      tokens.push({ type: "comment", start: lt, end });
+      yield { type: "comment", start: lt, end };
       i = end;
       continue;
     }
@@ -200,7 +218,7 @@ export function tokenize(html) {
       html.slice(lt + (closing ? 2 : 1), lt + 200),
     );
     if (!nameMatch) {
-      tokens.push({ type: "text", start: lt, end: lt + 1 });
+      yield { type: "text", start: lt, end: lt + 1 };
       i = lt + 1;
       continue;
     }
@@ -217,29 +235,29 @@ export function tokenize(html) {
     const end = Math.min(j + 1, html.length);
     const name = nameMatch[0].toLowerCase();
     if (closing) {
-      tokens.push({ type: "close", name, start: lt, end });
+      yield { type: "close", name, start: lt, end };
       i = end;
       continue;
     }
     const inner = html.slice(lt + 1 + nameMatch[0].length, end - 1);
     const selfClosing = /\/\s*$/.test(inner);
-    tokens.push({
+    yield {
       type: "open",
       name,
       attrs: parseAttributes(inner.replace(/\/\s*$/, "")),
       start: lt,
       end,
       selfClosing: selfClosing || VOID.has(name),
-    });
+    };
     i = end;
     if (RAW.has(name) && !selfClosing) {
-      const closeAt = html.toLowerCase().indexOf(`</${name}`, end);
+      lower ??= html.toLowerCase();
+      const closeAt = lower.indexOf(`</${name}`, end);
       const stop = closeAt < 0 ? html.length : closeAt;
-      if (stop > end) tokens.push({ type: "text", start: end, end: stop });
+      if (stop > end) yield { type: "text", start: end, end: stop };
       i = stop;
     }
   }
-  return tokens;
 }
 
 /** Each element with its inner range: [{name, attrs, start, end, innerStart, innerEnd, depth}]. */
@@ -912,6 +930,174 @@ ${sanitizeMarkup(body)}
   return page;
 }
 
+// ── visible text (text.json) ────────────────────────────────────────────────
+
+/** Characters of visible text text.json keeps per row. */
+export const TEXT_LIMIT = 600;
+/** Characters of a `find` excerpt. */
+const EXCERPT_CHARS = 60;
+/** Elements whose content is never read on screen as text. */
+const HIDDEN_CONTENT = new Set([
+  "script",
+  "style",
+  "svg",
+  "head",
+  "template",
+  "noscript",
+  "title",
+]);
+/** Phrasing elements that sit inside a word; every other tag separates words. */
+const INLINE = new Set(
+  "a abbr b bdi bdo cite code data dfn em i kbd mark q s samp small strong sub sup time u var wbr".split(
+    " ",
+  ),
+);
+
+/** Each `data-kit-slot` element's inner range, for slot-first text. */
+function slotRanges(html) {
+  if (!html.includes("data-kit-slot")) return [];
+  return elements(html)
+    .filter((element) => element.attrs["data-kit-slot"] !== undefined)
+    .map((element) => [element.innerStart, element.innerEnd]);
+}
+
+/**
+ * The words a row shows: text content outside scripts, styles, SVG, the head
+ * and templates, entities decoded and whitespace collapsed, at most `limit`
+ * characters. Attribute values are never text. The text of the row's slots
+ * (a page's `main`) comes first and the rest of the markup after it, so a
+ * page's own words are kept ahead of the navigation and top bar every page
+ * repeats.
+ */
+export function visibleText(html, limit = TEXT_LIMIT) {
+  const ranges = slotRanges(html);
+  const lastSlotEnd = Math.max(0, ...ranges.map(([, end]) => end));
+  const inSlot = (at) => ranges.some(([from, to]) => at >= from && at < to);
+  // [slot text, the rest]
+  const parts = ["", ""];
+  const add = (at, words) => {
+    const part = inSlot(at) ? 0 : 1;
+    if (words === " " && (parts[part] === "" || parts[part].endsWith(" ")))
+      return;
+    parts[part] += words;
+  };
+  let hidden = null;
+  let depth = 0;
+  for (const token of scan(html)) {
+    if (hidden) {
+      if (token.name !== hidden) continue;
+      if (token.type === "open" && !token.selfClosing) depth += 1;
+      else if (token.type === "close" && (depth -= 1) === 0) hidden = null;
+      continue;
+    }
+    if (token.type === "open" || token.type === "close") {
+      if (
+        token.type === "open" &&
+        HIDDEN_CONTENT.has(token.name) &&
+        !token.selfClosing
+      ) {
+        hidden = token.name;
+        depth = 1;
+      } else if (!INLINE.has(token.name)) {
+        add(token.start, " ");
+      }
+      continue;
+    }
+    if (token.type !== "text") continue;
+    add(
+      token.start,
+      decodeEntities(html.slice(token.start, token.end)).replace(/\s+/g, " "),
+    );
+    // Enough collected: a row's text is a search aid, not its content.
+    const [slot, rest] = parts;
+    if (slot.length > limit * 2 && slot.trim().length > limit) break;
+    if (
+      token.end >= lastSlotEnd &&
+      slot.length + rest.length > limit * 2 &&
+      `${slot} ${rest}`.trim().length > limit
+    )
+      break;
+  }
+  return [...`${parts[0]} ${parts[1]}`.replace(/\s+/g, " ").trim()]
+    .slice(0, limit)
+    .join("");
+}
+
+/**
+ * text.json's content: each row's visible text by id, from its markup.
+ * `read(file)` returns a row's markup by its kit-relative `file`; a row
+ * whose file is missing or leaves the kit has no entry. The first row of an
+ * id wins, as in `loadKit`.
+ */
+export function kitText(rows, read) {
+  const text = {};
+  const seen = new Set();
+  for (const row of rows) {
+    if (!row || typeof row.id !== "string" || seen.has(row.id)) continue;
+    seen.add(row.id);
+    const file = row.file;
+    if (typeof file !== "string" || !file || file.split(/[\\/]/).includes(".."))
+      continue;
+    let html;
+    try {
+      html = read(file);
+    } catch {
+      continue;
+    }
+    if (typeof html !== "string") continue;
+    const words = visibleText(html);
+    if (words) text[row.id] = words;
+  }
+  return Object.fromEntries(
+    Object.entries(text).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)),
+  );
+}
+
+/** text.json as written: stable keys, one row per line. */
+export function kitTextJson(text) {
+  return `${JSON.stringify(text, null, 1)}\n`;
+}
+
+/** Rebuilds `dir`/text.json from the rows and markup already in the kit. */
+export function writeKitText(dir) {
+  const kit = loadKit(dir);
+  const json = kitTextJson(
+    kitText(kit.rows, (file) => readFileSync(join(dir, file), "utf8")),
+  );
+  writeFileSync(join(dir, "text.json"), json);
+  return json;
+}
+
+/** text.json, if the kit has a readable one: id → visible text. */
+function readText(dir) {
+  const file = join(dir, "text.json");
+  if (!existsSync(file)) return undefined;
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    // An optional search aid: a broken one leaves find as it is without it.
+    return undefined;
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+    return undefined;
+  const text = new Map();
+  for (const [id, words] of Object.entries(parsed))
+    if (typeof words === "string") text.set(id, words);
+  return text;
+}
+
+/** About EXCERPT_CHARS of `words` around `at`, cut words marked with "…". */
+function excerpt(words, at, length) {
+  const chars = [...words];
+  // `at` counts UTF-16 units; recount it in characters.
+  const from = [...words.slice(0, at)].length;
+  let start = Math.max(0, from - Math.floor((EXCERPT_CHARS - length) / 2));
+  const end = Math.min(chars.length, start + EXCERPT_CHARS);
+  start = Math.max(0, end - EXCERPT_CHARS);
+  return `${start > 0 ? "…" : ""}${chars.slice(start, end).join("").trim()}${end < chars.length ? "…" : ""}`;
+}
+
 // ── show / find / info ──────────────────────────────────────────────────────
 
 export function outline(html, limit = SHOW_LIMIT) {
@@ -948,8 +1134,17 @@ function formatBytes(bytes) {
   return bytes >= 1024 ? `${(bytes / 1024).toFixed(1)} KB` : `${bytes} B`;
 }
 
-export function find(kit, query) {
+/**
+ * Rows holding every word of `query` in their id, title, component, source
+ * file or visible text (text.json), best first: a word in the id ranks
+ * above one in the title, component or source file, which ranks above one
+ * only in the text, and among rows that tie, one whose text holds the whole
+ * query as written comes first. A row a word matched only through its text
+ * carries an `excerpt` around that phrase, or else the first such word.
+ */
+export function findMatches(kit, query) {
   const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+  const phrase = terms.join(" ");
   const scored = [];
   for (const row of kit.rows) {
     const id = row.id.toLowerCase();
@@ -957,20 +1152,59 @@ export function find(kit, query) {
       .filter(Boolean)
       .join(" ")
       .toLowerCase();
-    if (!terms.every((term) => hay.includes(term))) continue;
-    const score = terms.reduce(
-      (sum, term) => sum + (id.includes(term) ? 0 : 1),
-      0,
-    );
-    scored.push({ row, score });
+    const words = kit.text?.get(row.id) ?? "";
+    let lowered = null;
+    let score = 0;
+    let textHit = null;
+    let matched = true;
+    for (const term of terms) {
+      if (id.includes(term)) continue;
+      if (hay.includes(term)) {
+        score += 1;
+        continue;
+      }
+      lowered ??= words.toLowerCase();
+      const at = lowered.indexOf(term);
+      if (at < 0) {
+        matched = false;
+        break;
+      }
+      score += 2;
+      textHit ??= { at, length: term.length };
+    }
+    if (!matched) continue;
+    // The whole query as written, in the text: the excerpt shows it, and it
+    // ranks first among rows that tie.
+    const at = textHit && terms.length > 1 ? lowered.indexOf(phrase) : -1;
+    if (at >= 0) textHit = { at, length: phrase.length };
+    scored.push({
+      row,
+      score,
+      phrase: at >= 0 ? 0 : 1,
+      ...(textHit
+        ? { excerpt: excerpt(words, textHit.at, textHit.length) }
+        : {}),
+    });
   }
-  scored.sort((a, b) => a.score - b.score || (a.row.id < b.row.id ? -1 : 1));
-  return scored.map(({ row }) => row);
+  scored.sort(
+    (a, b) =>
+      a.score - b.score ||
+      a.phrase - b.phrase ||
+      (a.row.id < b.row.id ? -1 : 1),
+  );
+  return scored.map(({ row, excerpt: cut }) =>
+    cut === undefined ? { row } : { row, excerpt: cut },
+  );
+}
+
+/** Rows holding every word of `query`, best first (see findMatches). */
+export function find(kit, query) {
+  return findMatches(kit, query).map(({ row }) => row);
 }
 
 function findLines(kit, query) {
-  const rows = find(kit, query);
-  if (!rows.length) {
+  const matches = findMatches(kit, query);
+  if (!matches.length) {
     const near = nearMatches(
       query,
       kit.rows.map((row) => row.id),
@@ -979,15 +1213,40 @@ function findLines(kit, query) {
       `nothing matches "${query}".${near.length ? ` Near: ${near.join(", ")}` : ""}`,
     );
   }
-  const shown = rows.length > FIND_LIMIT ? rows.slice(0, FIND_LIMIT - 1) : rows;
-  const lines = shown.map(
-    (row) =>
-      `${row.id}  ${row.kind ?? rowSource(row)}  ${row.width ?? "?"}w  ${formatBytes(row.bytes ?? 0)}  ${row.title ?? ""}`,
-  );
-  if (rows.length > shown.length) {
-    lines.push(`… ${rows.length - shown.length} more; add a word to narrow it`);
+  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;
+  // A row with an excerpt was found by on-screen text; any other, by name.
+  const byText = matches.filter((match) => match.excerpt !== undefined);
+  if (!byText.length) {
+    return [
+      ...matches.slice(0, room).map(line),
+      `… ${matches.length - room} more; add a word to narrow it`,
+    ];
   }
-  return lines;
+  // 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),
+  );
+  const names = byName.slice(0, room - textRoom);
+  const texts = byText.slice(0, room - names.length);
+  const left = [
+    ...(byName.length > names.length
+      ? [`+${byName.length - names.length} more by name`]
+      : []),
+    ...(byText.length > texts.length
+      ? [`+${byText.length - texts.length} more by on-screen text`]
+      : []),
+  ];
+  return [
+    ...names.map(line),
+    ...texts.map(line),
+    `${left.join(", ")}; narrow the query`,
+  ];
 }
 
 function showText(kit, id, full) {
@@ -1022,7 +1281,7 @@ function infoText(kit) {
 
 const USAGE = `usage: kit.mjs [--kit <dir>] <command>
   info                         print the manifest
-  find <query>                 list up to ${FIND_LIMIT} matching ids
+  find <query>                 list up to ${FIND_LIMIT} rows whose id, title or on-screen text holds every word
   show <id> [--full]           path, size and an outline (--full: the markup)
   compose --frame <id> [--slot <name>=<file>]… [--theme light|dark] [--show-new] --out <file>`;