@codepress/design-kit 0.4.1 → 0.5.0

package/README.md

@@ -275,6 +275,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 +297,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
@@ -384,17 +395,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 +455,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.1",
+  "version": "0.5.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

@@ -10,6 +10,7 @@
  * Needs Playwright's Chromium (`npx playwright install chromium`).
  */
 import { execFileSync, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import {
   copyFileSync,
   createReadStream,
@@ -62,6 +63,28 @@ export const kitId = (storyId, width) => `story:${storyId}@${width}`;
 export const kitFile = (id) => `html/${id.replace(/^story:/, "story--")}.html`;
 export const storyIdOf = (id) => id.replace(/^story:/, "").replace(/@\d+$/, "");
 
+/**
+ * Holds each distinct sheet once. A capture's sheets come back as shared
+ * `{key, rules}` entries: an equal key and equal rules give the same entry,
+ * so a run keeps one copy of the CSS nearly every story loads instead of one
+ * per capture. A linked sheet is keyed by its path, so two captures can share
+ * a key with different rules; each keeps its own, and the kit chooses between
+ * them exactly as it did before.
+ */
+export function sheetStore() {
+  const byKey = new Map(); // key -> Map(rules digest -> entry)
+  return (sheets) =>
+    sheets.map(({ key, rules }) => {
+      const digest = createHash("sha256")
+        .update(JSON.stringify(rules))
+        .digest("base64");
+      let variants = byKey.get(key);
+      if (!variants) byKey.set(key, (variants = new Map()));
+      if (!variants.has(digest)) variants.set(digest, { key, rules });
+      return variants.get(digest);
+    });
+}
+
 /**
  * Sheets in a cascade-respecting order: each capture's sheets keep their
  * document order, and a sheet first seen later is placed after the sheet
@@ -974,6 +997,15 @@ export async function captureStories(config, options = {}) {
     const captures = new Map(); // kit id -> {story, viewport, result}
     const failures = [];
     const attempts = []; // every capture's timing, kept or not
+    // Nearly every story loads the same sheets, a few hundred KB of rules
+    // each; kept results share one copy of each (see sheetStore).
+    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 };
+      attempts.push(record);
+      return record;
+    };
     let done = 0;
     await pool(targets, concurrency, async (story) => {
       const first = await captureOne({
@@ -986,7 +1018,7 @@ export async function captureStories(config, options = {}) {
         families,
         fixedTime,
       });
-      attempts.push(first);
+      const firstAttempt = attempt(first);
       let viewports = plannedViewports(story.title, null, planning);
       const results = new Map([[planning.viewport.width, first]]);
       if (first.result) {
@@ -994,7 +1026,7 @@ export async function captureStories(config, options = {}) {
         viewports = plannedViewports(story.title, declared, planning);
         if (declared) {
           results.delete(planning.viewport.width);
-          first.discarded = true;
+          firstAttempt.discarded = true;
         }
       }
       for (const viewport of viewports) {
@@ -1009,7 +1041,7 @@ export async function captureStories(config, options = {}) {
             families,
             fixedTime,
           });
-          attempts.push(capture);
+          attempt(capture);
           results.set(viewport.width, capture);
         }
         const capture = results.get(viewport.width);
@@ -1017,7 +1049,14 @@ export async function captureStories(config, options = {}) {
         if (capture.failure) {
           failures.push({ id, ...capture.failure });
         } else {
-          captures.set(id, { story, viewport, result: capture.result });
+          captures.set(id, {
+            story,
+            viewport,
+            result: {
+              ...capture.result,
+              sheets: keepSheetsOnce(capture.result.sheets),
+            },
+          });
         }
       }
       done += 1;

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 } : {}),
   };
 }