@krapwoo/ds-viewer 0.7.0 → 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

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');
+}

package/dist/cli/main.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import path from 'node:path';
+import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { resolveConfig } from "./config.js";
 import { initExistingProject, initNewProject, promptInitMode } from "./init.js";
@@ -9,6 +10,7 @@ import { formatHuman, runDoctor, toDoctorJson, withExtraIssues } from "./doctor.
 import { renderCheck } from "./render.js";
 import { RENDER_WORKSPACE_DIR } from "./types.js";
 import { explainPage, formatExplain, parseHeights } from "./explain.js";
+import { comparableWidths, diffLayouts, formatLayoutDiff, layoutSnapshot } from "./layout.js";
 import { readOwnVersion } from "./packageVersion.js";
 import { checkForUpdate, defaultPreferencesDir, readPersonalAutoCheck, resolveAutoCheck } from "./updateCheck.js";
 import { runKitDiffCommand } from "./kitDiff.js";
@@ -40,6 +42,11 @@ Commands:
            Print why a page's specimens are laid out the way they are
            --heights <first>,<second>  check side-by-side placement with these measured heights
            --json          print the machine-readable report instead
+           --all           every page's geometry as JSON, for layout-diff
+  layout-diff <before.json> <after.json>
+           What changed about every page's layout between two explain --all snapshots, so a
+           viewer upgrade that reshapes your catalog is visible rather than silent
+           --json          print the changes as JSON
   kit diff <Component>
            Show the user's kit file(s) for <Component> against the installed kit's copy
   migrate --from <version>
@@ -171,8 +178,21 @@ export async function runDoctorCommand(projectRoot, rest, options = {}) {
 }
 /** Same "testable without spawning" shape as `runDoctorCommand` above. */
 export function runExplainCommand(projectRoot, pageId, rest) {
+    // `--all`: every page's geometry as one JSON document, for `layout-diff` to compare across
+    // versions. It takes no page id, and it is JSON only — the whole point is a machine-readable
+    // artifact, and a prose dump of 50 pages would be read by nobody.
+    if (pageId === '--all' || rest.includes('--all')) {
+        const config = resolveConfig(projectRoot);
+        const version = readOwnVersion(path.dirname(fileURLToPath(import.meta.url)));
+        try {
+            return { output: JSON.stringify(layoutSnapshot(config, version), null, 2), exitCode: 0 };
+        }
+        catch (error) {
+            return { output: error.message, exitCode: 1 };
+        }
+    }
     if (!pageId)
-        return { output: 'Usage: ds-viewer explain <Page> [--heights <first>,<second>] [--json]', exitCode: 1 };
+        return { output: 'Usage: ds-viewer explain <Page> [--heights <first>,<second>] [--json], or explain --all for every page as JSON', exitCode: 1 };
     const heightsIndex = rest.indexOf('--heights');
     const heightsRaw = heightsIndex !== -1 ? rest[heightsIndex + 1] : undefined;
     const heights = heightsRaw ? parseHeights(heightsRaw) : undefined;
@@ -185,6 +205,104 @@ export function runExplainCommand(projectRoot, pageId, rest) {
         return { output: `No page named "${pageId}" was found.`, exitCode: 1 };
     return { output: rest.includes('--json') ? JSON.stringify(result, null, 2) : formatExplain(result), exitCode: 0 };
 }
+function isFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+function isGeometry(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const geometry = value;
+    return Number.isInteger(geometry.columns) && geometry.columns >= 0
+        && Number.isInteger(geometry.rows) && geometry.rows >= 0
+        && Number.isInteger(geometry.fillers) && geometry.fillers >= 0;
+}
+function isLayoutSnapshot(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const snapshot = value;
+    if (typeof snapshot.version !== 'string' || !isFiniteNumber(snapshot.width) || snapshot.width <= 0 || !Array.isArray(snapshot.pages))
+        return false;
+    const ids = new Set();
+    for (const entry of snapshot.pages) {
+        if (!entry || typeof entry !== 'object')
+            return false;
+        const page = entry;
+        if (typeof page.page !== 'string' || page.page.length === 0 || ids.has(page.page) || !Array.isArray(page.blocks))
+            return false;
+        ids.add(page.page);
+        if (page.sideEligible !== undefined && typeof page.sideEligible !== 'boolean')
+            return false;
+        if (page.notCheckable !== undefined && page.notCheckable !== true)
+            return false;
+        for (const entryBlock of page.blocks) {
+            if (!entryBlock || typeof entryBlock !== 'object')
+                return false;
+            const block = entryBlock;
+            if (typeof block.title !== 'string' || !['grid', 'grouped', 'list', 'preview', 'tokenSections', 'empty'].includes(String(block.kind)))
+                return false;
+            if (!(block.minWidth === null || isFiniteNumber(block.minWidth)))
+                return false;
+            if (block.items !== undefined && (!Number.isInteger(block.items) || block.items < 0))
+                return false;
+            if (block.size !== undefined && typeof block.size !== 'string')
+                return false;
+            if (block.full !== undefined && !isGeometry(block.full))
+                return false;
+            if (block.half !== undefined && !isGeometry(block.half))
+                return false;
+        }
+    }
+    return true;
+}
+/** `layout-diff <before.json> <after.json>`: what a version changed about every page's geometry. */
+export function runLayoutDiffCommand(args, deps = {}) {
+    const [beforePath, afterPath] = args.filter((a) => !a.startsWith('--'));
+    if (!beforePath || !afterPath) {
+        return { output: 'Usage: ds-viewer layout-diff <before.json> <after.json>\n\nBoth are written by `ds-viewer explain --all`.', exitCode: 1 };
+    }
+    const read = deps.readFile ?? ((file) => readFileSync(file, 'utf8'));
+    const load = (file) => {
+        let raw;
+        try {
+            raw = read(file);
+        }
+        catch {
+            return `Could not read ${file}.`;
+        }
+        try {
+            const parsed = JSON.parse(raw);
+            // Refuse plausible-but-incomplete JSON before the diff touches it. Treating an absent block
+            // array as empty reports invented removals; dereferencing it reports a raw TypeError instead
+            // of telling the user they selected the wrong file.
+            if (!isLayoutSnapshot(parsed)) {
+                return `${file} is not a layout snapshot. Write one with \`ds-viewer explain --all\`.`;
+            }
+            return parsed;
+        }
+        catch {
+            return `${file} is not valid JSON.`;
+        }
+    };
+    const before = load(beforePath);
+    if (typeof before === 'string')
+        return { output: before, exitCode: 1 };
+    const after = load(afterPath);
+    if (typeof after === 'string')
+        return { output: after, exitCode: 1 };
+    // Before diffing, not only before printing: the guard used to live in `formatLayoutDiff`, so
+    // `--json` — the path most likely to be automated in CI — returned a confident list of changes
+    // computed across incomparable widths.
+    if (!comparableWidths(before, after)) {
+        return {
+            output: `These snapshots were taken at different widths (${before.width}px and ${after.width}px), so their geometry is not comparable. The two viewer versions use different catalog content widths; compare releases whose snapshot widths match.`,
+            exitCode: 1,
+        };
+    }
+    const changes = diffLayouts(before, after);
+    if (args.includes('--json'))
+        return { output: JSON.stringify(changes, null, 2), exitCode: 0 };
+    return { output: formatLayoutDiff(before, after, changes), exitCode: 0 };
+}
 async function main() {
     const [command, ...rest] = process.argv.slice(2);
     const projectRoot = process.cwd();
@@ -219,6 +337,13 @@ async function main() {
             process.exitCode = exitCode;
         return;
     }
+    if (command === 'layout-diff') {
+        const { output, exitCode } = runLayoutDiffCommand(rest);
+        console.log(output);
+        if (exitCode)
+            process.exitCode = exitCode;
+        return;
+    }
     if (command === 'explain') {
         const [pageId, ...explainRest] = rest;
         const { output, exitCode } = runExplainCommand(projectRoot, pageId, explainRest);

package/dist/native/catalog/comparison.js

@@ -341,7 +341,7 @@ function heightAtWidth(block, width, available) {
  *  same number of rows as a full row would give": a column cap can already force a block to wrap
  *  at full width, and two wrapped rows staying two wrapped rows is not a reason to halve every
  *  specimen on the page. One row is the case where sharing genuinely costs nothing. */
-function fitsOneRow(block, half) {
+export function fitsOneRow(block, half) {
     if (block.kind !== 'list' || !block.itemCount || !block.size)
         return true;
     return listGeometry(block.itemCount, half, block.size, block.maxColumns).rows <= 1;

package/native/catalog/comparison.ts

@@ -441,7 +441,7 @@ function heightAtWidth(block: PlacementBlock, width: number, available: number):
  *  same number of rows as a full row would give": a column cap can already force a block to wrap
  *  at full width, and two wrapped rows staying two wrapped rows is not a reason to halve every
  *  specimen on the page. One row is the case where sharing genuinely costs nothing. */
-function fitsOneRow(block: PlacementBlock, half: number): boolean {
+export function fitsOneRow(block: PlacementBlock, half: number): boolean {
   if (block.kind !== 'list' || !block.itemCount || !block.size) return true;
   return listGeometry(block.itemCount, half, block.size, block.maxColumns).rows <= 1;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krapwoo/ds-viewer",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "license": "MIT",
   "type": "module",
   "description": "A browsable, always-current catalog for an Expo / React Native design system.",