@krapwoo/ds-viewer 0.6.11 → 0.8.0

package/README.md

@@ -63,8 +63,43 @@ npm run ds-viewer dev    # opens the catalog in a browser, re-syncing on every f
 npm run ds-viewer sync   # regenerates component/token/page data without starting a server
 npm run ds-viewer doctor   # checks every page for drift and coverage gaps (--json, --ci)
 npm run ds-viewer explain <Page>   # prints why a page's specimens are laid out the way they are
+npm run ds-viewer explain --all   # every page's geometry as JSON, to diff across versions
+npm run ds-viewer layout-diff before.json after.json   # what an upgrade changed about your layout
 ```
 
+### Seeing what an upgrade changes
+
+Layout rules live in this package and reach your catalog on `update`, while your page files never
+change. So a new version can reshape a page with nothing in your repository to explain it. Snapshot
+before and after, and the change becomes something you can read:
+
+```
+npx ds-viewer explain --all > before.json   # on the version you have
+# ...upgrade...
+npx ds-viewer explain --all > after.json
+npx ds-viewer layout-diff before.json after.json
+```
+
+```
+0.6.11 → 0.7.0, measured at 952px
+
+Layout changes on 3 pages: Banner, EmptyState, Shimmer.
+
+Banner
+  its two blocks can no longer share a row
+```
+
+The snapshot holds what can be decided without a browser: each block's kind and minimum width;
+list blocks add specimen size, item count, and column×row geometry at full and half width, while
+token-section blocks add section count and their responsive column×row geometry. For a two-block
+page, `sideEligible` records every gate known before measurement: both blocks must keep their minimum
+width and both must still fit one row at half width. Eligibility is not the outcome — placement also
+weighs a single tall specimen and the height actually saved, and neither is knowable without measuring
+a real render.
+
+Snapshots taken at different widths refuse to compare, since geometry at 952px and 1112px
+legitimately differs and diffing them would report changes that never happened.
+
 Only one `dev` serves a project at a time. A second one refuses, naming the port the first is on,
 because both would generate into the same `.ds-viewer/` and overwrite each other's files — the
 loser then serves a workspace that no longer describes it, which Expo reports as an unresolvable
@@ -81,13 +116,19 @@ file that is fine and that you never touched:
 Something outside this server deleted package.json, app.json, tsconfig.json, metro.config.js,
 entry.tsx from .ds-viewer/. Rewriting them — your project is fine, this is the catalog's own
 generated workspace. If the catalog looks broken, reload the page.
+Restarting Metro so the catalog picks the files back up — the page reloads itself in a few seconds.
 ```
 
-Metro picks the files back up without a restart. The repair is capped at five per run: if
-something is deleting continuously, repairing forever would only hide it, so past the cap the
-server stops and keeps reporting. If you ever see that message, what else was running at the time
-would be useful on [issue #41](https://github.com/krapwoo/design-system-viewer/issues/41) — the
-cause is not yet identified.
+Metro is restarted as part of the repair, because rewriting the files is not enough on its own: it
+keeps serving the module map it cached before they went missing, and answers every request with
+`Unable to resolve "expo" from "entry.tsx"` until it starts again. The server stays up and the page
+reloads itself.
+
+The repair is capped at five per run: if something is deleting continuously, repairing forever
+would only hide it, so past the cap the server stops and keeps reporting. If you ever see that
+message, what else was running at the time would be useful on
+[issue #41](https://github.com/krapwoo/design-system-viewer/issues/41) — the cause is not yet
+identified.
 
 `ds-viewer.config.ts` fields: `name`, `logo` (optional — a path to an image asset, shown in the
 sidebar beside the name, or in place of it for a wide wordmark; validated at `sync`/`dev` time
@@ -561,12 +602,28 @@ and adds what only a real render shows:
   prop that was never wired up. The fingerprint reads each specimen's whole subtree (including a
   PhoneFrame's child document and a field's value) but not the caption carrying the variant's own
   name, so two examples differing only in colour are not reported.
+- `specimen-clipped` (warning): an example in a list card painting past the left or right of its
+  cell, where it is cut off rather than contained. Content the specimen holds itself is not
+  reported — anything inside something that scrolls (`auto`/`scroll`, so the reader can reach it)
+  or clips (`hidden`/`clip`) is treated as the specimen's own containment. That last one is a
+  trade-off worth knowing: a full-width component clipping its own corners hides a genuinely
+  too-narrow cell from this rule, so `hidden` buys quiet for carousels and shimmer sweeps at the
+  cost of that case. Only horizontal crossings in `role=list` cells are measured — a cell's width
+  is what the page allocates, while its height grows with content, and matrix (`ComparisonGrid`)
+  cells are not visited at all. Usually fixed with a wider `specimenSize`, by stacking the blocks so
+  the example gets the full row, or by dropping `itemsFill` from a small instance that should sit
+  centered.
 - `render-unavailable` / `render-failed` (errors): no browser, or the catalog didn't start.
 
 It needs `puppeteer` in your project (`npm install --save-dev puppeteer`); ds-viewer doesn't
 install a browser. It takes about two minutes for 50 pages and works with `--json` (progress
 goes to stderr), `--ci` and `doctor.strict`, so CI can run `npx ds-viewer doctor --render --ci`.
 
+It starts its own catalog on the first free port from 5181. `--port <n>` pins it instead, which
+you want when something else already holds that range — another project's catalog, or a second
+`dev`. The check cannot tell a stranger's server on its port from its own, so a collision reports
+that server's pages as your project's failures.
+
 It starts its own `dev` server, with `--no-update-endpoint` and its own generated directory
 (`.ds-viewer-render/`, gitignored by `init` alongside `.ds-viewer/`). Nothing it generates touches
 the workspace a running `dev` owns, so you can run it beside a catalog you already have open and

package/dist/cli/dev.js

@@ -535,12 +535,19 @@ export async function dev(initialConfig, devOptions = {}) {
     for (const watcher of watchers) {
         watcher.on('error', (error) => console.warn(`File watcher error: ${error.message}`));
     }
-    child = spawn('npx', ['expo', 'start', '--web', '--host', 'localhost', '--port', String(port)], {
+    const spawnMetro = () => spawn('npx', ['expo', 'start', '--web', '--host', 'localhost', '--port', String(port)], {
         cwd: workspace,
         stdio: 'inherit',
         shell: process.platform === 'win32',
         detached: true,
     });
+    // Set while this process is deliberately replacing Metro, so the exit handler below respawns it
+    // instead of running the shutdown path. Restoring the files is not enough on its own: Metro has
+    // already cached a module map that no longer matches the directory, and it answers every request
+    // with `Unable to resolve "expo" from "entry.tsx"` until it is restarted. Observed four times —
+    // the files came back and the catalog stayed blank.
+    let restartingMetro = false;
+    child = spawnMetro();
     // This process owns its workspace: nothing else should remove the files that define it. When
     // they vanish anyway, Metro reports it as `Cannot resolve entry file: the 'main' field defined
     // in your package.json points to an unresolvable or non-existent path` — which names the
@@ -572,7 +579,7 @@ export async function dev(initialConfig, devOptions = {}) {
             // `updateEndpoint` is passed through, never rebuilt: the endpoint listens on its own
             // ephemeral port, so deriving one from Metro's port here would repair the files and break
             // the update panel in the same breath.
-            repairWorkspaceIfMissing({
+            const { repaired } = repairWorkspaceIfMissing({
                 config, updateEndpoint, versionStatus: version.getVersionStatus, sync,
                 // Only if no one else took it meanwhile: between losing the lock and this tick, a second
                 // `dev` can legitimately have started and be serving the directory. Overwriting its lock
@@ -586,24 +593,64 @@ export async function dev(initialConfig, devOptions = {}) {
                     writeDevLock(config, { pid: process.pid, port });
                 },
             });
+            // Rewritten files are not enough: Metro keeps serving the module map it cached before they
+            // went missing. Restarting it is the only thing that gets the catalog back, and the repair
+            // cap bounds how often this can happen.
+            if (repaired && !restartingMetro) {
+                console.warn('Restarting Metro so the catalog picks the files back up — the page reloads itself in a few seconds.');
+                restartingMetro = true;
+                killGroup(child, 'SIGTERM');
+            }
         }
         catch (error) {
             console.warn(`Could not rewrite the workspace: ${error.message}`);
         }
     }, WORKSPACE_WATCH_INTERVAL_MS);
     workspaceWatch.unref?.();
-    child.on('error', (error) => console.warn(`Could not start Expo: ${error.message}`));
-    child.on('exit', (code) => {
-        clearInterval(workspaceWatch);
-        for (const watcher of watchers)
-            watcher.close();
-        endpointServer?.close();
-        // Released so the next `dev` is not refused by a lock naming a process that has gone.
-        // `liveDevLock` already ignores a dead pid, so this is tidiness, not correctness — it keeps a
-        // stale file out of a directory a developer may well read.
-        clearDevLock(config);
-        process.exitCode = code ?? 0;
-    });
+    const bindChild = () => {
+        child.on('error', (error) => console.warn(`Could not start Expo: ${error.message}`));
+        child.on('exit', (code) => {
+            // A Metro we killed on purpose: respawn it on the same port rather than tearing the server
+            // down, once the port it held is actually free again.
+            if (restartingMetro) {
+                // The flag stays set for the whole restart, not just until this handler returns. Clearing
+                // it before the wait left a window where the repair timer could ask for another restart,
+                // find no live child to kill, and leave the flag set with nothing pending — after which
+                // the next genuine Metro crash would be mistaken for a deliberate restart and silently
+                // respawn, skipping the shutdown path that releases the watchers and the dev lock.
+                // `repairWorkspaceIfMissing`'s caller already checks this flag, so holding it also stops a
+                // second repair stacking a restart on top of this one.
+                //
+                // The port is not free the instant this child exits: `performRestart` waits for the same
+                // reason, and Errata 7c records that Metro listens on `[::1]`, so a naive probe reports
+                // free while it is still bound. Respawning early lets Expo find its own port taken and
+                // either prompt — giving up with "Skipping dev server" in a non-interactive shell — or move
+                // to another port, leaving the catalog where the dev lock does not name.
+                void waitForPortFree(port, defaultProbePortFree)
+                    .catch(() => {
+                    // Still spawn: a catalog that tried and failed to come back is recoverable, one that
+                    // silently never tries is not. Expo reports the port conflict itself if there is one.
+                    console.warn(`Port ${port} was still held after the wait; starting Metro anyway.`);
+                })
+                    .then(() => {
+                    child = spawnMetro();
+                    bindChild();
+                    restartingMetro = false;
+                });
+                return;
+            }
+            clearInterval(workspaceWatch);
+            for (const watcher of watchers)
+                watcher.close();
+            endpointServer?.close();
+            // Released so the next `dev` is not refused by a lock naming a process that has gone.
+            // `liveDevLock` already ignores a dead pid, so this is tidiness, not correctness — it keeps a
+            // stale file out of a directory a developer may well read.
+            clearDevLock(config);
+            process.exitCode = code ?? 0;
+        });
+    };
+    bindChild();
     // Node's default SIGTERM/SIGINT/SIGHUP behavior exits this process without touching its
     // children — left alone, a signal sent only to `dev`'s own pid (not its process group) would
     // leave the spawned `expo start` running, still bound to its port (Important finding, Fable

package/dist/cli/explain.js

@@ -35,7 +35,7 @@ function cellOverrideNote(cells) {
  *  look at it; only the counts/keys/sizes they do look at are carried over. Every field Task 3
  *  reads is carried through here, including `previewWidths`/`fullWidthLabel`/`hide`/`itemsFill`/
  *  `maxColumns` — dropping any of them makes `explain` report different geometry than the viewer. */
-function toSectionDef(page) {
+export function toSectionDef(page) {
     const comparison = page.comparison && {
         rowLabel: page.comparison.rowLabel ?? '',
         columnLabel: page.comparison.columnLabel ?? '',
@@ -125,12 +125,11 @@ function toPlacementBlock(block, height) {
         ? { ...base, itemCount: block.items.length, size: block.size, maxColumns: block.maxColumns }
         : base;
 }
-/** Finds `pageId` among every page `cli/doctor.ts`'s own `discoverAllPageFiles` would find, builds
- *  its throwaway `SectionDef`, and asks the viewer's own pure layout functions for each block's
- *  decision — undefined when no page resolves to that id. */
-export function explainPage(config, pageId, options = {}) {
-    // Same exclusion `cli/doctor.ts`'s `runDoctor` applies (mirroring `sync`) — an excluded folder's
-    // page should never resolve here either.
+/** Every page `cli/doctor.ts`'s own `discoverAllPageFiles` would find, with the same exclusions
+ *  `runDoctor` applies (mirroring `sync`), so an excluded folder's page never resolves. Shared with
+ *  `cli/layout.ts` rather than copied: a snapshot built from a different page set than `explain`
+ *  reads would diff pages the viewer does not have. */
+export function discoverStaticPages(config) {
     const excluded = new Set((config.exclude ?? []).flatMap((pattern) => resolveGlob(config.projectRoot, pattern)));
     const componentFolders = [
         ...new Set(config.components
@@ -139,7 +138,13 @@ export function explainPage(config, pageId, options = {}) {
             .map((file) => path.dirname(file))),
     ];
     const pageFiles = discoverAllPageFiles({ componentFolders, standalonePageGlobs: config.pages ?? [], projectRoot: config.projectRoot });
-    const page = readStaticPages(pageFiles).find((p) => resolvePageId(p, p.file) === pageId);
+    return readStaticPages(pageFiles);
+}
+/** Finds `pageId` among every page `cli/doctor.ts`'s own `discoverAllPageFiles` would find, builds
+ *  its throwaway `SectionDef`, and asks the viewer's own pure layout functions for each block's
+ *  decision — undefined when no page resolves to that id. */
+export function explainPage(config, pageId, options = {}) {
+    const page = discoverStaticPages(config).find((p) => resolvePageId(p, p.file) === pageId);
     if (!page)
         return undefined;
     // Important finding 4 (Fable's review): a page whose layout data isn't a literal (or that has a

package/dist/cli/layout.js

@@ -0,0 +1,267 @@
+// cli/layout.ts — `explain --all` and `layout-diff`: capture every page's geometry as data,
+// and report what a version changed.
+//
+// Layout rules live in this package and reach every consuming project on `update`, while their page
+// files never change. So a release can reshape a catalog with nothing in the consumer's repository
+// to explain it — 0.7.0 moved three pages from side-by-side to stacked, and the only trace was a
+// changelog paragraph. This turns that into a measured artifact: snapshot before, snapshot after,
+// diff the two.
+import { resolvePageId } from "./pageIndex.js";
+import { discoverStaticPages } from "./explain.js";
+import { blockMinWidth, fitsOneRow, listGeometry, presentationBlocks, MATRIX_LAYOUT, } from "../native/catalog/comparison.js";
+import { CATALOG_LAYOUT } from "../native/catalog/tokens.js";
+import { sectionColumns } from "../native/catalog/tokenLayout.js";
+import { toSectionDef } from "./explain.js";
+function tokenSectionGeometry(block, width) {
+    const columns = sectionColumns(width, block.columns);
+    let rows = 0;
+    let used = 0;
+    let fillers = 0;
+    const closePartialRow = () => {
+        if (used === 0)
+            return;
+        rows += 1;
+        fillers += columns - used;
+        used = 0;
+    };
+    for (const section of block.sections) {
+        if (section.wide) {
+            closePartialRow();
+            rows += 1;
+            continue;
+        }
+        used += 1;
+        if (used === columns)
+            closePartialRow();
+    }
+    closePartialRow();
+    return { columns, rows, fillers };
+}
+function geometryFor(block, width) {
+    if (block.kind === 'list') {
+        const { columns, rows, fillers } = listGeometry(block.items.length, width, block.size, block.maxColumns);
+        return { columns, rows, fillers };
+    }
+    if (block.kind === 'tokenSections')
+        return tokenSectionGeometry(block, width);
+    return undefined;
+}
+function snapshotMinWidth(block) {
+    const width = blockMinWidth(block);
+    return Number.isFinite(width) ? width : null;
+}
+/** One page's geometry, from the same static read `explain` uses. */
+export function pageSnapshot(page, pageId) {
+    if (!page.checkable)
+        return { page: pageId, blocks: [], notCheckable: true };
+    const blocks = presentationBlocks(toSectionDef(page), { defaultPreviewWidths: [402] });
+    const full = MATRIX_LAYOUT.laptopContentWidth;
+    const half = Math.floor((full - CATALOG_LAYOUT.blockGap) / 2);
+    const snapshot = {
+        page: pageId,
+        blocks: blocks.map((block) => {
+            const fullGeometry = geometryFor(block, full);
+            const halfGeometry = geometryFor(block, half);
+            return {
+                title: block.kind === 'tokenSections' ? 'Token sections' : block.title,
+                kind: block.kind,
+                ...(block.kind === 'list' ? { size: block.size, items: block.items.length } : {}),
+                ...(block.kind === 'tokenSections' ? { items: block.sections.length } : {}),
+                minWidth: snapshotMinWidth(block),
+                ...(fullGeometry ? { full: fullGeometry } : {}),
+                ...(halfGeometry ? { half: halfGeometry } : {}),
+            };
+        }),
+    };
+    if (blocks.length === 2) {
+        const [first, second] = blocks;
+        const firstMin = blockMinWidth(first);
+        const secondMin = blockMinWidth(second);
+        const asPlacement = (b) => ({
+            kind: b.kind, height: 0, minWidth: blockMinWidth(b),
+            ...(b.kind === 'list' ? { itemCount: b.items.length, size: b.size, maxColumns: b.maxColumns } : {}),
+        });
+        // This is every static gate that runs before measured height enters choosePlacement. Omitting
+        // the min-width check made Avatar claim eligibility even though its 600px grid can never fit the
+        // 462px half-row; a later fitsOneRow change would then fabricate a placement change for it.
+        snapshot.sideEligible = half > 0 && firstMin <= half && secondMin <= half
+            && fitsOneRow(asPlacement(first), half) && fitsOneRow(asPlacement(second), half);
+    }
+    return snapshot;
+}
+/** Every page's geometry, ordered by page id so two snapshots diff line for line. */
+export function layoutSnapshot(config, version) {
+    const staticPages = discoverStaticPages(config);
+    const ids = staticPages.map((page) => resolvePageId(page, page.file));
+    const duplicates = [...new Set(ids.filter((id, index) => ids.indexOf(id) !== index))];
+    if (duplicates.length > 0) {
+        throw new Error(`Cannot snapshot duplicate page id${duplicates.length === 1 ? '' : 's'}: ${duplicates.join(', ')}. Run ds-viewer doctor and give each page a unique id.`);
+    }
+    const pages = staticPages
+        .map((page, index) => pageSnapshot(page, ids[index]))
+        // Code-point order is stable across machines; localeCompare can produce different snapshot text
+        // under different host locales, defeating a committed artifact's textual review.
+        .sort((a, b) => (a.page < b.page ? -1 : a.page > b.page ? 1 : 0));
+    return { version, width: MATRIX_LAYOUT.laptopContentWidth, pages };
+}
+function describeGeometry(g) {
+    return g ? `${g.columns}×${g.rows}` : '—';
+}
+function describeMinWidth(width) {
+    return width === null ? 'a full row' : `${width}px`;
+}
+function blockKeys(blocks) {
+    const seen = new Map();
+    const totals = new Map();
+    for (const block of blocks)
+        totals.set(block.title, (totals.get(block.title) ?? 0) + 1);
+    return blocks.map((block) => {
+        const occurrence = (seen.get(block.title) ?? 0) + 1;
+        seen.set(block.title, occurrence);
+        return {
+            key: `${block.title}\u0000${occurrence}`,
+            label: (totals.get(block.title) ?? 0) > 1 ? `${block.title} (${occurrence})` : block.title,
+        };
+    });
+}
+/** What changed between two snapshots. Pure, so it is the part worth testing.
+ *
+ *  Blocks are matched by title, not by position. Comparing by index means a block inserted at the
+ *  front diffs every later block against its neighbour: a page that gained an intro block reported
+ *  four changes, including a brand-new block "changing" from a geometry it never had and an
+ *  untouched block changing to its neighbour's. A tool whose output is meant to be believed cannot
+ *  invent changes that did not happen. */
+export function diffLayouts(before, after) {
+    const changes = [];
+    const beforePages = new Map(before.pages.map((p) => [p.page, p]));
+    const afterPages = new Map(after.pages.map((p) => [p.page, p]));
+    for (const page of before.pages) {
+        if (!afterPages.has(page.page))
+            changes.push({ page: page.page, kind: 'removed', detail: 'the page is gone' });
+    }
+    for (const page of after.pages) {
+        const was = beforePages.get(page.page);
+        if (!was) {
+            changes.push({ page: page.page, kind: 'added', detail: 'a new page' });
+            continue;
+        }
+        if (Boolean(was.notCheckable) !== Boolean(page.notCheckable)) {
+            changes.push({
+                page: page.page, kind: 'checkable',
+                detail: page.notCheckable ? 'its layout is no longer statically readable' : 'its layout became statically readable',
+            });
+            continue;
+        }
+        // Title is a block's identity here. Two blocks on one page sharing a title would be
+        // indistinguishable, so those fall back to their position *within that title* — which keeps a
+        // page with two "Variants" blocks comparing like for like instead of silently dropping one.
+        const index = (blocks) => {
+            const map = new Map();
+            for (const block of blocks) {
+                const list = map.get(block.title) ?? [];
+                list.push(block);
+                map.set(block.title, list);
+            }
+            return map;
+        };
+        const oldBlocks = index(was.blocks);
+        const newBlocks = index(page.blocks);
+        for (const [title, list] of oldBlocks) {
+            const now = newBlocks.get(title) ?? [];
+            for (let i = now.length; i < list.length; i += 1) {
+                changes.push({ page: page.page, kind: 'blocks', detail: `"${title}" is gone` });
+            }
+        }
+        for (const [title, list] of newBlocks) {
+            const before_ = oldBlocks.get(title) ?? [];
+            for (const [i, block] of list.entries()) {
+                const old = before_[i];
+                if (!old) {
+                    changes.push({ page: page.page, kind: 'blocks', detail: `"${title}" is new` });
+                    continue;
+                }
+                if (old.kind !== block.kind) {
+                    changes.push({ page: page.page, kind: 'blocks', detail: `"${block.title}" is a ${block.kind} block, was ${old.kind}` });
+                    continue;
+                }
+                if (old.minWidth !== block.minWidth) {
+                    changes.push({
+                        page: page.page,
+                        kind: 'geometry',
+                        detail: `"${block.title}" needs ${describeMinWidth(block.minWidth)}, was ${describeMinWidth(old.minWidth)}`,
+                    });
+                }
+                for (const width of ['full', 'half']) {
+                    const a = old[width];
+                    const b = block[width];
+                    if (describeGeometry(a) !== describeGeometry(b)) {
+                        changes.push({
+                            page: page.page, kind: 'geometry',
+                            detail: `"${block.title}" at ${width} width: ${describeGeometry(a)} → ${describeGeometry(b)}`,
+                        });
+                    }
+                }
+            }
+        }
+        // Compare relative order among blocks that exist on both sides. Inserting a new block at the
+        // front does not falsely say every existing block moved, but swapping two existing blocks does
+        // remain visible rather than disappearing behind title-based identity.
+        const oldKeyed = blockKeys(was.blocks);
+        const newKeyed = blockKeys(page.blocks);
+        const oldSet = new Set(oldKeyed.map(({ key }) => key));
+        const newSet = new Set(newKeyed.map(({ key }) => key));
+        const oldCommon = oldKeyed.filter(({ key }) => newSet.has(key));
+        const newCommon = newKeyed.filter(({ key }) => oldSet.has(key));
+        const oldPositions = new Map(oldCommon.map(({ key }, index) => [key, index]));
+        for (const [index, { key, label }] of newCommon.entries()) {
+            const oldIndex = oldPositions.get(key);
+            if (oldIndex !== undefined && oldIndex !== index) {
+                changes.push({
+                    page: page.page,
+                    kind: 'blocks',
+                    detail: `"${label}" moved from block ${oldIndex + 1} to ${index + 1}`,
+                });
+            }
+        }
+        if (typeof was.sideEligible === 'boolean' && typeof page.sideEligible === 'boolean' && was.sideEligible !== page.sideEligible) {
+            changes.push({
+                page: page.page, kind: 'placement',
+                detail: page.sideEligible
+                    ? 'its two blocks can now share a row'
+                    : 'its two blocks can no longer share a row',
+            });
+        }
+    }
+    return changes;
+}
+/** True when two snapshots were measured at the same width, and so can be compared at all.
+ *  Geometry at 952px and at 1112px legitimately differs; diffing across them reports rule changes
+ *  that never happened. Exported because every caller needs the guard, not just the one that
+ *  prints prose. */
+export function comparableWidths(before, after) {
+    return before.width === after.width;
+}
+/** Human output. Silence is the useful answer, so it says so explicitly rather than printing
+ *  nothing and leaving the reader to wonder whether it ran. */
+export function formatLayoutDiff(before, after, changes) {
+    const header = `${before.version} → ${after.version}, measured at ${after.width}px`;
+    if (before.width !== after.width) {
+        return `${header}\n\nThese snapshots were taken at different widths (${before.width}px and ${after.width}px), so their geometry is not comparable.`;
+    }
+    if (changes.length === 0)
+        return `${header}\n\nNo page changes layout.`;
+    const byPage = new Map();
+    for (const change of changes) {
+        const list = byPage.get(change.page) ?? [];
+        list.push(change);
+        byPage.set(change.page, list);
+    }
+    const pages = [...byPage.keys()];
+    const lines = [header, '', `Layout changes on ${pages.length} page${pages.length === 1 ? '' : 's'}: ${pages.join(', ')}.`, ''];
+    for (const [page, list] of byPage) {
+        lines.push(`${page}`);
+        for (const change of list)
+            lines.push(`  ${change.detail}`);
+    }
+    return lines.join('\n');
+}