@codepress/design-kit 0.4.2 → 0.6.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`
 
@@ -275,6 +285,15 @@ export returns (`async ({ browser, baseUrl, config }) => state`).
   `slots` names the regions a mockup replaces: the first selector that matches
   a visible, non-empty element gets `data-kit-slot="<name>"`, and `main` is
   required. A page without a `main` slot is a gap, not a frame.
+- `source`: names this config's pages when more than one config captures
+  pages into one kit, such as a web app and a desktop app's windows. A capture
+  with a `source` rewrites only its own pages' frames and gap rows and leaves
+  every other source's in place; its stylesheet is `css/routes--<source>.css`.
+  Without one (the default), a capture replaces every page in the kit. Page
+  names must be unique across sources: a name another source already captured
+  into the kit is a config error that names both sources (exit 2), checked
+  before the capture starts and again before it writes. To move a page from
+  one source to another, rebuild the kit without the old source's rows.
 - `widths`: the sizes every page is captured at (default 1280×800 and 390×844).
 - `shellReady`: a selector the app's frame shows before any page content.
 - `layout`: `{selector, attribute, default?}` reads the layout the app chose,
@@ -288,8 +307,10 @@ value>]` then replaces `slots`.
   kit's `fonts/` folder (`copyFonts: false` keeps them out); `fontsPath` says
   which URL path holds them when not every font file is one.
 - `hooks`: a module exporting `context(context, info)` (may return a cleanup)
-  and `page(page, info)` (may return `{readyFailed, beforeSerialize}`), for
-  routing mock data or adding checks.
+  and `page(page, info)` (runs before the page opens; may return
+  `{beforeReady, readyFailed, beforeSerialize}`), for routing mock data,
+  clicking through to a view (`beforeReady` runs once `shellReady` shows,
+  before `ready` is awaited) or adding checks.
 - `timeoutMs`, `startTimeoutMs`, `fixedTime`.
 
 ## Commands
@@ -351,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
@@ -367,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
@@ -384,17 +411,21 @@ design-kit/
   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
+  css/routes--<source>.css  the same, for the pages of one page source
   fonts/          the fonts both use
-  gaps.json       [{id|component|route, reason, detail?}]
+  gaps.json       [{id|component|route, reason, detail?, source?}]
   kit.mjs         the tool, copied into every kit so tool and data match
 ```
 
 A row is `{id, kind: "story"|"route", title, component?, file, width, height,
-bytes, slots?, source_file?, body_class?, html_attrs?, body_attrs?}`. Ids are
+bytes, slots?, source_file?, source?, css?, body_class?, html_attrs?,
+body_attrs?}`; a page row from a page source carries `source` and its
+stylesheet in `css`. Ids are
 `story:<storybook-id>@<width>` and `route:<name>@<width>`; file names use `--`
 instead of `:`, so the kit uploads as a CI artifact as it is. Always find a
 row's markup through its `file`. `manifest.css` may name another stylesheet
-per source (`{stories, routes}`).
+per source (`{stories, routes}`). With page sources, `manifest.sources.routes`
+keeps the kit's totals and adds `page_sources.<source>` with each one's own.
 
 ## `kit.mjs`
 
@@ -440,7 +471,11 @@ await capturePages(config, {
 
 `capturePages` also takes `forbidStrings` and `stripOrigins` (more origins to
 remove from markup, such as a mock API's) and a `session` object whose
-`interrupted` flag stops it between pages.
+`interrupted` flag stops it between pages. A harness that starts its own
+servers or builds before calling `capturePages` can call
+`assertPageSources(config, out)` first: it throws the same `ConfigError`
+(`exitCode` 2) for a page another source already captured into `out`, before
+anything starts.
 
 ## Contributing and license
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codepress/design-kit",
-  "version": "0.4.2",
+  "version": "0.6.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/schema/design-kit.config.schema.json

@@ -245,6 +245,11 @@
       "required": ["pages"],
       "description": "`design-kit capture pages`: real pages of the running app, through Playwright.",
       "properties": {
+        "source": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9-]*$",
+          "description": "Names this page source (such as \"web\" or \"terminal\") so several apps capture into one kit: a capture then rewrites only its own source's frames, rows, stylesheet (css/routes--<source>.css) and gap rows. Page names must be unique across sources; a name another source already captured into the kit is a config error. Without it, a capture replaces every page in the kit."
+        },
         "baseUrl": {
           "type": "string",
           "pattern": "^https?://",
@@ -282,7 +287,7 @@
         "hooks": {
           "type": "string",
           "minLength": 1,
-          "description": "A module exporting optional `context(context, info)` and `page(page, info)` hooks."
+          "description": "A module exporting optional `context(context, info)` and `page(page, info)` hooks. `page` may return `{ beforeReady, readyFailed, beforeSerialize }`: `beforeReady()` runs after the shell shows and before the ready selector is awaited, for a page reached by a click."
         },
         "widths": {
           "type": "array",

package/src/capture-pages.mjs

@@ -32,9 +32,14 @@ import {
   kitRouteId,
   mergeGaps,
   mergeManifest,
+  mergeRoutes,
   normalizeReactIds,
+  ownsRouteRow,
   rewriteCssUrls,
+  routeCssFile,
+  routeRowPage,
   selectPages,
+  sourceCollisions,
 } from "./pages.mjs";
 import { ConfigError } from "./config.mjs";
 import { loadPlaywright } from "./playwright.mjs";
@@ -310,6 +315,9 @@ async function capturePage(context, page, viewport, run) {
         .first()
         .waitFor({ state: "visible" });
     }
+    // A page reached by a click or a key, not by its path alone (a settings
+    // panel, a drawer), gets there here.
+    await pageHooks.beforeReady?.();
     const ready = tab.locator(page.ready).first();
     try {
       await ready.waitFor({ state: "visible" });
@@ -366,6 +374,47 @@ function themeClassesOf(theme) {
   return theme?.light ? [dark, theme.light] : [dark, "light"];
 }
 
+/**
+ * Throws a ConfigError (exit 2) when a page the config declares is already in
+ * the kit at `out` (a routes.json row or a gaps.json page row) from another
+ * page source. Page names are unique across sources, and every declared page
+ * counts, whatever `--only` selects. `capturePages` calls it before starting
+ * anything; a harness that starts its own servers first can call it earlier.
+ *
+ * @param {object} config A loaded config (`loadConfig`).
+ * @param {string} out The kit folder.
+ */
+export function assertPageSources(config, out) {
+  const settings = config.pages;
+  if (!settings) return;
+  const source = settings.source ?? null;
+  const pageNames = new Set(settings.pages.map((page) => page.name));
+  const clashes = sourceCollisions(
+    [
+      ...asArray(readJson(path.join(out, "routes.json"))),
+      ...asArray(readJson(path.join(out, "gaps.json"))),
+    ],
+    { source, pageNames },
+  );
+  if (clashes.length) {
+    throw new ConfigError(
+      clashes
+        .map(
+          ({ name, other }) =>
+            `page "${name}" is declared by page source "${source}" (${config.file}) and source "${other}" already captured it into ${out}; page names must be unique across sources`,
+        )
+        .join("\n"),
+    );
+  }
+}
+
+/** A page's markup carries a forbidStrings value. */
+class ForbiddenStringError extends Error {
+  constructor() {
+    super("the page's markup carries a forbidStrings value");
+  }
+}
+
 /**
  * Captures the configured pages into `out`.
  *
@@ -382,13 +431,6 @@ function themeClassesOf(theme) {
  * Returns 0, or 130 when interrupted (nothing is written then). Throws,
  * writing nothing, when any page's markup carries a forbidStrings value.
  */
-/** A page's markup carries a forbidStrings value. */
-class ForbiddenStringError extends Error {
-  constructor() {
-    super("the page's markup carries a forbidStrings value");
-  }
-}
-
 export async function capturePages(config, options = {}) {
   const settings = config.pages;
   if (!settings) {
@@ -411,6 +453,11 @@ export async function capturePages(config, options = {}) {
     only: options.only,
     ready: options.ready,
   });
+  // Before anything starts: a page this source declares that the kit already
+  // holds from another source.
+  assertPageSources(config, out);
+  const source = settings.source ?? null;
+  const pageNames = new Set(settings.pages.map((page) => page.name));
   if (!options.baseUrl && !settings.baseUrl && !settings.startCommand) {
     throw new ConfigError(
       "pages.baseUrl, or pages.startCommand with pages.waitUrl, is required (or pass --base-url)",
@@ -610,6 +657,7 @@ export async function capturePages(config, options = {}) {
             bytes: Buffer.byteLength(html),
             slots: [...capture.slots].sort(),
             ...(page.sourceFile ? { source_file: page.sourceFile } : {}),
+            ...(source ? { source, css: routeCssFile(source) } : {}),
             path: page.path,
             body_class: capture.bodyAttrs.class ?? "",
             html_attrs: capture.htmlAttrs,
@@ -628,7 +676,12 @@ export async function capturePages(config, options = {}) {
             .split("\n")
             .slice(0, 3)
             .join(" ");
-          gaps.push({ id, route: page.name, reason });
+          gaps.push({
+            id,
+            route: page.name,
+            ...(source ? { source } : {}),
+            reason,
+          });
           log(`gap ${id}: ${reason}`);
         } finally {
           await cleanup?.().catch?.(() => {});
@@ -661,6 +714,8 @@ export async function capturePages(config, options = {}) {
     fonts: fontFiles,
     theme: config.theme,
     configDir: config.configDir,
+    source,
+    pageNames,
   });
   timings.total_s = (performance.now() - startedAt) / 1000;
   const cpu = process.cpuUsage();
@@ -674,21 +729,89 @@ export async function capturePages(config, options = {}) {
   return 0;
 }
 
-function writePagesKit(
+/**
+ * Writes this capture into the kit at `out`. Without a `source` it replaces
+ * every route file, row and gap row (the stories' stay). With one it
+ * replaces only what `ownsRouteRow` gives it, so another page source's
+ * frames, rows, stylesheet and gap rows stay.
+ */
+export function writePagesKit(
   out,
-  { rows, files, css, gaps, needles, pages, widths, fonts, theme, configDir },
+  {
+    rows,
+    files,
+    css,
+    gaps,
+    needles,
+    pages,
+    widths,
+    fonts,
+    theme,
+    configDir,
+    source = null,
+    pageNames = new Set(pages.map((page) => page.name)),
+  },
 ) {
+  const owns = (row) => ownsRouteRow(row, { source, pageNames });
+  const routesPath = path.join(out, "routes.json");
+  const existingRows = readJson(routesPath);
+  // Checked again before anything is removed: another capture may have
+  // written the kit since this one started (captures into one kit are meant
+  // to run one after another).
+  const late = sourceCollisions(
+    [
+      ...asArray(existingRows),
+      ...asArray(readJson(path.join(out, "gaps.json"))),
+    ],
+    { source, pageNames },
+  );
+  if (late.length)
+    throw new ConfigError(
+      late
+        .map(
+          ({ name, other }) =>
+            `page "${name}" was captured into ${out} by page source "${other}" while source "${source}" was capturing; nothing was written`,
+        )
+        .join("\n"),
+    );
   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.
-  for (const name of fs.readdirSync(path.join(out, "html")))
-    if (isRouteHtmlFile(name)) fs.rmSync(path.join(out, "html", name));
+  // This half's files only: earlier page captures go, story files stay. A
+  // sourced capture removes only the files of the rows it replaces.
+  if (!source) {
+    for (const name of fs.readdirSync(path.join(out, "html")))
+      if (isRouteHtmlFile(name)) fs.rmSync(path.join(out, "html", name));
+    for (const name of fs.readdirSync(path.join(out, "css")))
+      if (/^routes--.+\.css$/.test(name))
+        fs.rmSync(path.join(out, "css", name));
+  } else {
+    const stale = new Set(
+      (Array.isArray(existingRows) ? existingRows : [])
+        .filter((row) => row && typeof row === "object" && owns(row))
+        .map((row) => row.file)
+        .filter(
+          (file) =>
+            typeof file === "string" &&
+            /^html\/route[-:]/.test(file) &&
+            !file.includes(".."),
+        ),
+    );
+    // A file of one of this source's pages with no row (a kit cut short).
+    for (const name of fs.readdirSync(path.join(out, "html"))) {
+      if (!isRouteHtmlFile(name)) continue;
+      const page = name
+        .replace(/^route(?:--|:)/, "")
+        .replace(/@\d+\.html$/, "");
+      if (pageNames.has(page)) stale.add(`html/${name}`);
+    }
+    for (const file of stale) fs.rmSync(path.join(out, file), { force: true });
+  }
 
-  const sortedRows = [...rows].sort(byKey((row) => row.id));
+  const sortedRows = mergeRoutes(existingRows, rows, owns);
   const written = [
     ...[...files.entries()].sort(byKey(([file]) => file)),
     ["routes.json", kitJson(sortedRows)],
-    ["css/routes.css", css],
+    [routeCssFile(source), css],
   ];
   for (const [file, text] of written) {
     if (findForbidden(text, needles))
@@ -710,24 +833,40 @@ function writePagesKit(
     fs.copyFileSync(new URL("./kit.mjs", import.meta.url), tool);
 
   const gapsPath = path.join(out, "gaps.json");
-  fs.writeFileSync(
-    gapsPath,
-    kitJson(mergeGaps(readJson(gapsPath), gaps.filter(isRouteGap))),
+  const mergedGaps = mergeGaps(
+    readJson(gapsPath),
+    gaps.filter(isRouteGap),
+    owns,
   );
+  fs.writeFileSync(gapsPath, kitJson(mergedGaps));
 
+  const routeGaps = mergedGaps.filter(isRouteGap);
   const manifestPath = path.join(out, "manifest.json");
   const manifest = mergeManifest(readJson(manifestPath), {
     sha: gitSha(configDir),
     builtAt: new Date().toISOString(),
-    captured: sortedRows.length,
+    captured: rows.length,
     failed: gaps.length,
     pages: pages.map((page) => page.name),
     widths: widths.map((viewport) => viewport.width),
     theme,
+    source,
+    total: {
+      captured: sortedRows.length,
+      failed: routeGaps.length,
+      pages: [
+        ...new Set([...sortedRows, ...routeGaps].map(routeRowPage)),
+      ].sort(),
+      widths: [
+        ...new Set(sortedRows.map((row) => row.width).filter(Number.isInteger)),
+      ].sort((a, b) => b - a),
+    },
   });
   fs.writeFileSync(manifestPath, kitJson(manifest));
 }
 
+const asArray = (value) => (Array.isArray(value) ? value : []);
+
 function readJson(file) {
   try {
     return JSON.parse(fs.readFileSync(file, "utf8"));

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`).
  */
@@ -45,6 +46,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 +184,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 +344,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 +365,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 +416,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 +532,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 +668,7 @@ async function extract() {
     html,
     sheets,
     declared,
+    widths,
     bodyClass,
     empty: !rootHasContent && !portalHasContent,
   };
@@ -638,7 +730,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 +756,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 +784,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 +844,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 +859,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 +884,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 +902,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 +995,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 +1042,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 +1192,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 +1213,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 +1252,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 {
@@ -1236,6 +1443,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 +1463,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/config.mjs

@@ -237,6 +237,7 @@ export function resolveConfig(raw, path) {
   if (raw.pages) {
     const p = raw.pages;
     config.pages = {
+      source: p.source ?? null,
       baseUrl: p.baseUrl,
       startCommand: p.startCommand,
       waitUrl: p.waitUrl,

package/src/index.d.ts

@@ -36,6 +36,8 @@ export interface DesignKitConfig {
   };
   stories?: Record<string, unknown>;
   pages?: {
+    /** The page source this config captures; null replaces every page. */
+    source: string | null;
     baseUrl?: string;
     fixedTime: string;
     widths: Size[];
@@ -63,8 +65,10 @@ export function captureStories(
   },
 ): Promise<{ out: string; rows: number; failed: number }>;
 
-/** Returned by a `page` hook; both run inside the capture of one page. */
+/** Returned by a `page` hook; each runs inside the capture of one page. */
 export interface PageHookResult {
+  /** After the shell shows, before the ready selector: reach the page by a click. */
+  beforeReady?(): void | Promise<void>;
   /** The ready selector never appeared; may throw a clearer error. */
   readyFailed?(): void | Promise<void>;
   /** Runs just before serialization, in place of the optional screenshot. */
@@ -112,6 +116,13 @@ export function capturePages(
   options?: CapturePagesOptions,
 ): Promise<number>;
 
+/**
+ * Throws a ConfigError (exitCode 2) when a page the config declares is already
+ * in the kit at `out` from another page source. `capturePages` calls it before
+ * starting anything; a harness that starts its own servers can call it first.
+ */
+export function assertPageSources(config: DesignKitConfig, out: string): void;
+
 /** What to look for per forbidden value: as written, a token's long segments, and escaped. */
 export function forbiddenNeedles(values: string[]): string[];
 /** The first needle `text` contains, or null. */

package/src/index.mjs

@@ -12,6 +12,6 @@ export {
   validate,
 } from "./config.mjs";
 export { captureStories, playwrightVersion } from "./capture-stories.mjs";
-export { capturePages } from "./capture-pages.mjs";
+export { assertPageSources, capturePages } from "./capture-pages.mjs";
 export { findForbidden, forbiddenNeedles } from "./pages.mjs";
 export { compose, find, loadKit, run as runKit } from "./kit.mjs";

package/src/kit.mjs

@@ -67,6 +67,21 @@ function cssFile(kit, source) {
     : `css/${source}.css`;
 }
 
+/**
+ * The stylesheet a row needs: a route row of a page source names its own
+ * (`css`, inside the kit's css folder), any other row its source's.
+ */
+function rowCssFile(kit, row) {
+  const source = rowSource(row);
+  if (
+    source === "routes" &&
+    typeof row.css === "string" &&
+    /^css\/[^/]+\.css$/.test(row.css)
+  )
+    return row.css;
+  return cssFile(kit, source);
+}
+
 /** A row's markup, found only through its `file` (never derived from the id). */
 function snippetPath(kit, row) {
   if (typeof row.file !== "string" || !row.file) {
@@ -693,7 +708,7 @@ function expandSnippets(kit, html, used, budget, depth = 0) {
     const id = element.attrs.id;
     if (!id) throw new KitError("<kit-snippet> without an id attribute");
     const row = requireRow(kit, id, "<kit-snippet id>");
-    used.add(rowSource(row));
+    used.add(rowCssFile(kit, row));
     let markup = readSnippet(kit, row);
     budget.left -= markup.length;
     if (budget.left < 0) {
@@ -839,17 +854,20 @@ export function compose(
   if (theme !== "light" && theme !== "dark") {
     throw new KitError(`unknown theme "${theme}". Use light or dark.`);
   }
-  const used = new Set([rowSource(row)]);
+  const used = new Set([rowCssFile(kit, row)]);
   const filled = fillSlots(kit, row, readSnippet(kit, row), slots);
   const body = expandSnippets(kit, filled, used, {
     left: maxBytes - filled.length,
     max: maxBytes,
   });
 
-  const css = ["stories", "routes"]
-    .filter((source) => used.has(source))
-    .map((source) => {
-      const name = cssFile(kit, source);
+  // Stories' sheet first, then the route sheets, as before page sources.
+  const storiesCss = cssFile(kit, "stories");
+  const css = [...used]
+    .sort((a, b) =>
+      a === storiesCss ? -1 : b === storiesCss ? 1 : a < b ? -1 : a > b ? 1 : 0,
+    )
+    .map((name) => {
       const file = join(kit.dir, name);
       if (!existsSync(file)) {
         throw new KitError(`the kit has no ${name} for ${frame}`);

package/src/pages.mjs

@@ -9,8 +9,16 @@
  *                                    (id `route:<name>@<width>`; no ":" in paths)
  *   routes.json                      one row per capture
  *   css/routes.css                   every rule the captured pages loaded, deduped
+ *                                    (css/routes--<source>.css for a page source)
  *   gaps.json                        shared; this half owns rows with `route`
  *                                    or an id starting `route:`
+ *
+ * Page sources: a config whose `pages.source` names one (such as `web` or
+ * `terminal`) rewrites only its own rows, files, stylesheet and gap rows, so
+ * several apps capture into one kit. Its rows carry `source` and `css`. Rows
+ * with no `source` (a capture without one, or a kit from before sources)
+ * belong to a sourced capture only when it declares their page name. A
+ * capture without a source owns every route row, as before sources existed.
  */
 
 export function kitRouteId(name, width) {
@@ -228,19 +236,75 @@ export function isRouteGap(row) {
   return row.route != null || (row.id ?? "").startsWith("route:");
 }
 
-/** Replaces this half's rows in an existing gaps.json, keeping the stories'. */
-export function mergeGaps(existing, mine) {
-  const kept = Array.isArray(existing)
-    ? existing.filter(
-        (row) => row && typeof row === "object" && !isRouteGap(row),
-      )
+/** The page a route row or route gap row is for. */
+export function routeRowPage(row) {
+  if (row.route != null) return String(row.route);
+  return String(row.id ?? "")
+    .replace(/^route:/, "")
+    .replace(/@\d+$/, "");
+}
+
+/** The stylesheet a page source's rows use: `css/routes.css` without one. */
+export function routeCssFile(source) {
+  return source ? `css/routes--${source}.css` : "css/routes.css";
+}
+
+/**
+ * Whether a capture replaces an existing route row (or route gap row): a
+ * capture without a source replaces every one; a sourced capture replaces
+ * its own source's rows and unsourced rows of a page it declares.
+ */
+export function ownsRouteRow(row, { source = null, pageNames = new Set() }) {
+  if (!source) return true;
+  if (row.source != null) return row.source === source;
+  return pageNames.has(routeRowPage(row));
+}
+
+/**
+ * Pages this capture declares that the kit already holds from another
+ * source, as `{ name, other }` (one per page): page names are unique across
+ * sources, since a row id is `route:<name>@<width>` whatever its source.
+ */
+export function sourceCollisions(rows, { source = null, pageNames }) {
+  if (!source) return [];
+  const found = new Map();
+  for (const row of rows) {
+    if (!row || typeof row !== "object" || row.source == null) continue;
+    if (row.source === source) continue;
+    const name = routeRowPage(row);
+    if (pageNames.has(name) && !found.has(name))
+      found.set(name, String(row.source));
+  }
+  return [...found].map(([name, other]) => ({ name, other }));
+}
+
+/**
+ * Replaces this half's rows in an existing gaps.json, keeping the stories'
+ * and, for a sourced capture, other sources' route rows (`owns` says which
+ * route rows this capture replaces; default every one).
+ */
+export function mergeGaps(existing, mine, owns = () => true) {
+  const rows = Array.isArray(existing)
+    ? existing.filter((row) => row && typeof row === "object")
     : [];
+  const kept = rows.filter((row) => !isRouteGap(row));
+  const otherRoutes = rows.filter((row) => isRouteGap(row) && !owns(row));
   return [
     ...kept,
-    ...[...mine].sort(byKey((row) => row.id ?? row.route ?? "")),
+    ...[...otherRoutes, ...mine].sort(
+      byKey((row) => row.id ?? row.route ?? ""),
+    ),
   ];
 }
 
+/** routes.json after a capture: other sources' rows kept, this run's added, by id. */
+export function mergeRoutes(existing, mine, owns = () => true) {
+  const kept = Array.isArray(existing)
+    ? existing.filter((row) => row && typeof row === "object" && !owns(row))
+    : [];
+  return [...kept, ...mine].sort(byKey((row) => row.id ?? ""));
+}
+
 const asObject = (value) =>
   value && typeof value === "object" && !Array.isArray(value) ? value : {};
 
@@ -249,18 +313,30 @@ const asObject = (value) =>
  * `sources.routes` and `counts.routes` are replaced, the other sources are
  * kept, `counts.failed` is the sum of every source's `failed`, and
  * `sha`/`built_at` (and `theme`, when configured) go to the last writer.
+ *
+ * A sourced capture (`run.source`) records its own numbers under
+ * `sources.routes.page_sources[<source>]`, keeps the other page sources'
+ * entries, and makes `sources.routes` the whole kit's: `run.total` gives the
+ * captured and failed counts, pages and widths across every page source.
  */
 export function mergeManifest(existing, run) {
   const manifest = asObject(existing);
-  const sources = {
-    ...asObject(manifest.sources),
-    routes: {
-      captured: run.captured,
-      failed: run.failed,
-      pages: run.pages,
-      widths: run.widths,
-    },
+  const own = {
+    captured: run.captured,
+    failed: run.failed,
+    pages: run.pages,
+    widths: run.widths,
   };
+  const routes = run.source
+    ? {
+        ...(run.total ?? own),
+        page_sources: {
+          ...asObject(asObject(asObject(manifest.sources).routes).page_sources),
+          [run.source]: own,
+        },
+      }
+    : own;
+  const sources = { ...asObject(manifest.sources), routes };
   const failed = Object.values(sources).reduce(
     (sum, source) => sum + (Number(asObject(source).failed) || 0),
     0,
@@ -271,7 +347,7 @@ export function mergeManifest(existing, run) {
     sha: run.sha,
     built_at: run.builtAt,
     sources,
-    counts: { ...asObject(manifest.counts), routes: run.captured, failed },
+    counts: { ...asObject(manifest.counts), routes: routes.captured, failed },
     ...(run.theme ? { theme: run.theme } : {}),
   };
 }