@krapwoo/ds-viewer 0.6.11 → 0.8.0

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";
@@ -34,10 +36,17 @@ Commands:
            --json          print the machine-readable report instead
            --ci            exit 1 when any error was found (never on a warning alone)
            --render        also open every page in a headless browser (needs puppeteer)
+           --port <n>      pin the render server's port (with --render), for when something
+                           else already holds the range it would pick from
   explain <Page>
            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>
@@ -128,7 +137,23 @@ export async function runDoctorCommand(projectRoot, rest, options = {}) {
     // Progress goes to stderr, so `--json` output stays pure JSON.
     if (rest.includes('--render')) {
         const files = result.pageFiles;
-        const rendered = await (options.renderCheck ?? renderCheck)(config.projectRoot, { files, log: (line) => process.stderr.write(`${line}\n`) });
+        // `--port <n>`: pin the render server instead of taking the first free port from 5181. Needed
+        // when something else already holds that range (another project's catalog, a second `dev`),
+        // because the check cannot tell a stranger's server on its port from its own and would report
+        // that server's pages as this project's failures.
+        const portFlag = rest.indexOf('--port');
+        let renderPort;
+        if (portFlag !== -1) {
+            const raw = rest[portFlag + 1];
+            renderPort = Number(raw);
+            if (!raw || !Number.isInteger(renderPort) || renderPort < 1 || renderPort > 65535) {
+                // Refused rather than quietly falling back to a port it picked itself: a check that
+                // ignores the port you gave it would render against whatever else is there and report a
+                // stranger's pages as this project's failures.
+                return { output: `doctor --render --port needs a port between 1 and 65535, not ${raw ?? '(nothing)'}.`, exitCode: 1 };
+            }
+        }
+        const rendered = await (options.renderCheck ?? renderCheck)(config.projectRoot, { files, log: (line) => process.stderr.write(`${line}\n`), ...(renderPort ? { port: renderPort } : {}) });
         result = withExtraIssues(result, rendered, Boolean(config.doctor?.strict));
     }
     // Design §4 "`--ci`: ... no update check." — `--ci` skips this whole block even when
@@ -153,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;
@@ -167,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();
@@ -201,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/cli/render.js

@@ -121,6 +121,79 @@ export function identicalVariantIssues(page, pairs) {
         fix: "Make the difference visible — a wider specimenSize when the cell is too narrow to show it, or the prop the name claims — or drop one of the two examples.",
     }));
 }
+/**
+ * Runs in the browser: finds specimen content that paints outside its cell and cannot be reached.
+ *
+ * A cell is the width the page gives an example. Content wider than it is either clipped — the
+ * reader sees a cut-off component and no indication anything is missing — or drawn over its
+ * neighbour. Either way the page is showing something other than the component.
+ *
+ * Scrollable content is deliberately not reported, and so is content a component clips itself:
+ * both are decisions the specimen made, not width the page failed to give it. `PillRow`'s "Many
+ * pills (scrollable)" paints 220px outside its cell at 1280 and is correct; a shimmer sweep or a
+ * carousel that hides its own overflow is equally deliberate.
+ *
+ * The containment walk stops at the cell. Looking past it was wrong: `ComparisonGroups` wraps every
+ * grouped card in a horizontal `ScrollView`, which react-native-web renders as `overflow-x: auto`,
+ * so a walk to the document root found that scroller above every grouped cell and exempted all of
+ * them — the rule covered plain list blocks only, while its calibration claimed the whole corpus.
+ * What matters is whether the *specimen* contains its own overflow, which is a question about the
+ * ancestors inside the cell.
+ *
+ * Only horizontal crossings are measured. A cell's width is what the page allocates and what
+ * `specimenSize` controls; its height grows with content.
+ */
+export const CLIPPED_SPECIMEN_SCRIPT = `(() => {
+  const doc = document;
+  const CONTAINS = /^(auto|scroll|hidden|clip)$/;
+  const out = [];
+  for (const card of doc.querySelectorAll('[role=list][aria-label]')) {
+    if (!/^[^:]+: .+/.test(card.getAttribute('aria-label') || '')) continue;
+    for (const cell of card.querySelectorAll('[role=listitem]')) {
+      if (cell.closest('[role=list]') !== card) continue;
+      const box = cell.getBoundingClientRect();
+      if (box.width < 2) continue;
+      let worst = 0;
+      let side = 'right';
+      for (const el of cell.querySelectorAll('*')) {
+        const r = el.getBoundingClientRect();
+        if (r.width < 2 || r.height < 2) continue;
+        const over = Math.max(box.left - r.left, r.right - box.right);
+        if (over <= worst) continue;
+        // Invisible content, including anything inside an invisible or offscreen wrapper: an exit
+        // animation mid-flight, or a visually-hidden node parked at a large negative offset.
+        let hidden = false;
+        let contained = false;
+        for (let p = el; p && p !== cell; p = p.parentElement) {
+          const style = getComputedStyle(p);
+          if (style.visibility === 'hidden' || style.opacity === '0' || style.display === 'none') { hidden = true; break; }
+          // Anything between the content and the cell that handles its own overflow — scrolling it
+          // or clipping it — is the specimen's own decision, not the page denying it width.
+          if (p !== el && CONTAINS.test(style.overflowX)) { contained = true; break; }
+        }
+        if (hidden || contained) continue;
+        worst = over;
+        side = box.left - r.left >= r.right - box.right ? 'left' : 'right';
+      }
+      if (worst > 1) {
+        const caption = cell.children[0] ? (cell.children[0].textContent || '') : '';
+        out.push({ name: caption.trim(), overflow: Math.round(worst), side });
+      }
+    }
+  }
+  return out;
+})()`;
+/** Turns the browser's findings into doctor issues, one per clipped example. */
+export function clippedSpecimenIssues(page, clipped) {
+    const ref = { page: page.id, ...(page.file ? { file: page.file } : {}) };
+    return clipped.map((c) => ({
+        id: 'specimen-clipped',
+        severity: 'warning',
+        ...ref,
+        message: `${c.name ? `"${c.name}"` : 'An example'} paints ${c.overflow}px past the ${c.side} of its cell, where it is cut off rather than scrollable.`,
+        fix: 'Give the page a wider specimenSize, stack the blocks so the example gets the full row, or drop `itemsFill` if the example is a small instance that should sit centered.',
+    }));
+}
 /** The project's own puppeteer, or `undefined` when it isn't installed. */
 export function loadProjectPuppeteer(projectRoot) {
     try {
@@ -195,14 +268,14 @@ async function waitForServer(port, timeoutMs = DEV_START_TIMEOUT_MS) {
         await new Promise((resolve) => setTimeout(resolve, 250));
     }
 }
-function startDev(projectRoot, onSpawn) {
+function startDev(projectRoot, onSpawn, pinnedPort) {
     const main = path.join(path.dirname(fileURLToPath(import.meta.url)), 'main.js');
     return new Promise((resolve, reject) => {
         // Its own workspace directory and no update endpoint: this server exists to render pages, and
         // every file it generates would otherwise overwrite the ones an already-running `dev` is
         // serving — including that developer's endpoint, pointing their open catalog at a port that
         // dies with this check.
-        const child = spawn(process.execPath, [main, 'dev', '--no-update-endpoint', '--workspace-dir', RENDER_WORKSPACE_DIR], {
+        const child = spawn(process.execPath, [main, 'dev', '--no-update-endpoint', '--workspace-dir', RENDER_WORKSPACE_DIR, ...(pinnedPort ? ['--port', String(pinnedPort)] : [])], {
             cwd: projectRoot,
             env: { ...process.env, CI: '1', DS_VIEWER_NO_UPDATE_CHECK: '1' },
             detached: process.platform !== 'win32',
@@ -289,7 +362,7 @@ export async function renderCheck(projectRoot, options = {}) {
         }
         ({ port } = await (deps.startDev ?? startDev)(projectRoot, (child) => {
             devChild = child;
-        }));
+        }, options.port));
         const home = await browser.newPage();
         const deadline = Date.now() + FIRST_LOAD_TIMEOUT_MS;
         for (;;) {
@@ -352,6 +425,17 @@ export async function renderCheck(projectRoot, options = {}) {
                 }
                 if (Array.isArray(identical))
                     issues.push(...identicalVariantIssues({ id, file: options.files?.get(id) }, identical));
+                // Advisory for the same reason as the pass above, and kept separate so one failing script
+                // does not cost the other its findings.
+                let clipped;
+                try {
+                    clipped = (await page.evaluate(CLIPPED_SPECIMEN_SCRIPT));
+                }
+                catch {
+                    clipped = undefined;
+                }
+                if (Array.isArray(clipped))
+                    issues.push(...clippedSpecimenIssues({ id, file: options.files?.get(id) }, clipped));
                 await page.close();
             }
             catch (error) {

package/dist/native/catalog/comparison.js

@@ -337,16 +337,49 @@ function heightAtWidth(block, width, available) {
     const rows = listGeometry(block.itemCount, width, block.size, block.maxColumns).rows;
     return (block.height / Math.max(1, stackedRows)) * rows;
 }
-/** Side by side or stacked, for a page with exactly two blocks. Side by side splits the row into
- *  two equal columns and each block fills its own, so it is only possible when both blocks keep
- *  their minimum width in half a row; it is only taken when it saves at least PLACEMENT_MIN_SAVING
- *  against stacking, measuring each block at the width it would actually have. */
+/** Whether a block still fits on a single row in half the width. Deliberately stricter than "the
+ *  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. */
+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;
+}
+/** Side by side or stacked, for a page with exactly two blocks.
+ *
+ *  **Stacked is the default.** A page reads top to bottom, each block gets the whole row, and every
+ *  specimen keeps the width its component is actually used at. Side by side halves that width, so
+ *  it has to earn the space rather than be taken whenever it happens to save height — which is how
+ *  `Banner` ended up showing five full-width banners in a 462px column.
+ *
+ *  Two things earn it:
+ *
+ *  - **A single tall specimen.** One specimen taller than the column is wide leaves a long empty
+ *    strip beside it (an open `Dropdown` is 738px tall in a 462px column), and the other block
+ *    fits there for free.
+ *  - **Both still fit one row.** Specimens small enough that each block is a single row in half
+ *    the width lose nothing by sharing it.
+ *
+ *  Both still require each block to keep its minimum width in half a row, and the result to save
+ *  at least `PLACEMENT_MIN_SAVING` of height — side by side that saves nothing is just a narrower
+ *  page. */
 export function choosePlacement({ available, gap, first, second }) {
     const half = Math.floor((available - gap) / 2);
     if (half <= 0)
         return 'stacked';
     if ((first.minWidth ?? Infinity) > half || (second.minWidth ?? Infinity) > half)
         return 'stacked';
+    // Measured at the width it would have: a specimen is "tall" when it runs longer than the column
+    // it would sit in, which is what leaves room beside it.
+    // Either block can be the tall one. Checking `first` alone made placement depend on the order the
+    // page happens to declare its blocks in, so the same two blocks laid out variants-then-states and
+    // states-then-variants got different answers — and the rule says "a single specimen taller than
+    // its column", which says nothing about order.
+    const singleTallSpecimen = (first.itemCount === 1 && first.height > half) || (second.itemCount === 1 && second.height > half);
+    const bothFitOneRow = fitsOneRow(first, half) && fitsOneRow(second, half);
+    if (!singleTallSpecimen && !bothFitOneRow)
+        return 'stacked';
     const sideHeight = Math.max(heightAtWidth(first, half, available), heightAtWidth(second, half, available));
     const stackedHeight = first.height + gap + second.height;
     return sideHeight <= stackedHeight - PLACEMENT_MIN_SAVING ? 'side' : 'stacked';

package/native/catalog/SpacingScaleGallery.tsx

@@ -1,5 +1,5 @@
 import { View, Text, StyleSheet } from 'react-native';
-import { TokenRow } from './TokenRow';
+import { TokenRow, TokenRowGroup } from './TokenRow';
 import { CATALOG_TYPE, CATALOG_COLOR, CATALOG_SPACE, CATALOG_RADIUS } from './tokens';
 
 /**
@@ -18,11 +18,11 @@ export function SpacingScaleGallery<TStep extends string | number>({
   useNotes: Record<TStep, string>;
 }) {
   return (
-    <View style={styles.tokenStack}>
+    <TokenRowGroup><View style={styles.tokenStack}>
       {steps.map((step, i) => {
         const px = values[step];
         return (
-          <TokenRow key={String(step)} use={useNotes[step]} last={i === steps.length - 1}>
+          <TokenRow key={String(step)} use={useNotes[step]} last={i === steps.length - 1} notePlacement="right">
             <View style={styles.row}>
               <Text style={styles.label}>{String(step)}</Text>
               <View style={[styles.bar, { width: Math.max(px, 1) }]} />
@@ -31,7 +31,7 @@ export function SpacingScaleGallery<TStep extends string | number>({
           </TokenRow>
         );
       })}
-    </View>
+    </View></TokenRowGroup>
   );
 }
 

package/native/catalog/TokenRow.tsx

@@ -1,18 +1,45 @@
-import React from 'react';
-import { View, Text, StyleSheet } from 'react-native';
+import React, { createContext, useCallback, useContext, useMemo, useState } from 'react';
+import { View, Text, StyleSheet, type LayoutChangeEvent } from 'react-native';
 import { CATALOG_TYPE, CATALOG_COLOR, CATALOG_SPACE } from './tokens';
 
+type Lane = { width: number; report: (width: number) => void };
+
+const LaneContext = createContext<Lane | undefined>(undefined);
+
 /**
- * Wraps one token's rendered example with a grounded "when to use this" note beneath it — the
- * shared shape behind every token-gallery row (Spacing, Type Scale, …) in both the starter kit's
- * own token pages and the catalog framework's own `kit-host/viewer-pages/` pages. The row's own
- * content (a spacing bar, a type sample, …) is
- * freeform `children`; only the value-plus-use-note stacking is standardized here.
+ * Gives a stack of `notePlacement="right"` rows one shared sample column, measured from the widest
+ * sample actually in the stack.
+ *
+ * A fixed column has to be wide enough for the biggest sample a page might hold, which strands
+ * every smaller one: a `normal 400` weight sample is ~110px, and in a column sized for an 88px
+ * display sample its note sat 700px away from it. Measuring instead means the Font page's column
+ * is as wide as a font weight, and the Type scale's is as wide as `display` — each page tight to
+ * its own content, with the notes still aligned in a single column to read down.
  *
- * Draws a 1px `CATALOG_COLOR.border` bottom divider by default (the same divider PropsTable's rows use) so a stack of TokenRows
- * reads as a list, not a loose pile of paragraphs. Pass `last` on the final row in a stack to drop
- * the divider, matching PropsTable's own `rowLast` convention. Balanced `CATALOG_SPACE.md` padding
- * sits above and below both the content and its use-note, so a stack of rows breathes evenly
+ * The width only ever grows, so it settles after the first layout: once the column is the widest
+ * natural sample, no sample can report wider than it and nothing re-measures. Rows sit at their
+ * natural width for that first frame.
+ */
+export function TokenRowGroup({ children }: { children: React.ReactNode }) {
+  const [width, setWidth] = useState(0);
+  const report = useCallback((next: number) => {
+    setWidth((current) => (next > current ? next : current));
+  }, []);
+  const value = useMemo(() => ({ width, report }), [width, report]);
+  return <LaneContext.Provider value={value}>{children}</LaneContext.Provider>;
+}
+
+/**
+ * Wraps one token's rendered example with a grounded "when to use this" note — the shared shape
+ * behind every token-gallery row (Spacing, Type Scale, …) in both the starter kit's own token pages
+ * and the catalog framework's own `viewer-pages/` pages. The row's own content (a spacing bar, a
+ * type sample, …) is freeform `children`; only the value-plus-use-note arrangement is standardized
+ * here.
+ *
+ * Draws a 1px `CATALOG_COLOR.border` bottom divider by default (the same divider PropsTable's rows
+ * use) so a stack of TokenRows reads as a list, not a loose pile of paragraphs. Pass `last` on the
+ * final row in a stack to drop the divider, matching PropsTable's own `rowLast` convention.
+ * Balanced `CATALOG_SPACE.md` padding sits above and below, so a stack of rows breathes evenly
  * instead of only the divider-adjacent gap existing.
  */
 export function TokenRow({
@@ -25,15 +52,36 @@ export function TokenRow({
   children: React.ReactNode;
   use: string;
   last?: boolean;
-  /** `'right'` puts the note beside a narrow sample (icon sizes, spacing, control heights) so each
-   *  token is one line; the sample keeps `sampleWidth` and the note takes the rest. */
+  /** `'right'` puts the note beside the sample (font weights, spacing, type sizes) so each token is
+   *  one line. Inside a `TokenRowGroup` the sample column is measured from the widest sample in the
+   *  stack; a `TokenRowGroup`'s measured column wins when there is one, and `sampleWidth`
+   *  (default 280) is the fallback for a row standing on its own. Keeping the default matters for
+   *  rows outside a group: without it every row sizes to its own sample and the notes stop lining
+   *  up in a column, which is the thing `notePlacement="right"` exists to do. */
   notePlacement?: 'below' | 'right';
   sampleWidth?: number;
 }) {
+  const lane = useContext(LaneContext);
+
   if (notePlacement === 'right') {
+    const measured = lane && lane.width > 0 ? lane.width : undefined;
+    // Inside a group the lane governs, and only the lane: falling back to `sampleWidth` on the
+    // first frame would pin the sample to 280 before anything is measured, and the measurement
+    // taken through that constraint can never report wider than 280 — capping a lane that exists
+    // precisely to grow to the widest sample (a type scale's `display` needs ~470).
+    // `sampleWidth` is for a row standing on its own, where there is nothing to measure against.
+    const column = lane ? measured : sampleWidth;
+    const onLayout = lane
+      ? (event: LayoutChangeEvent) => lane.report(Math.ceil(event.nativeEvent.layout.width))
+      : undefined;
     return (
       <View style={[styles.itemRight, !last && styles.itemDivider]}>
-        <View style={{ width: sampleWidth, flexShrink: 0 }}>{children}</View>
+        {/* While measuring, the inner view sits at its natural width so it reports what the sample
+            actually takes. Standing alone there is nothing to report, so it stretches to the column
+            instead — otherwise a sample sized as a percentage would collapse to nothing. */}
+        <View style={[styles.sample, column !== undefined && { width: column }]}>
+          <View style={onLayout ? styles.natural : undefined} onLayout={onLayout}>{children}</View>
+        </View>
         {use ? <Text style={[styles.use, styles.useRight]}>{use}</Text> : null}
       </View>
     );
@@ -49,6 +97,8 @@ export function TokenRow({
 const styles = StyleSheet.create({
   item: { gap: CATALOG_SPACE.xs, paddingVertical: CATALOG_SPACE.md },
   itemRight: { flexDirection: 'row', alignItems: 'center', gap: CATALOG_SPACE.xl, paddingVertical: CATALOG_SPACE.md },
+  sample: { flexShrink: 0 },
+  natural: { alignSelf: 'flex-start' },
   useRight: { flex: 1 },
   itemDivider: {
     borderBottomWidth: 1,

package/native/catalog/TypeScaleGallery.tsx

@@ -1,5 +1,5 @@
 import { View, Text, StyleSheet, type TextStyle } from 'react-native';
-import { TokenRow } from './TokenRow';
+import { TokenRow, TokenRowGroup } from './TokenRow';
 import { CATALOG_TYPE, CATALOG_COLOR, CATALOG_SPACE } from './tokens';
 
 /**
@@ -22,9 +22,9 @@ export function TypeScaleGallery<TStep extends string>({
   useNotes: Record<TStep, string>;
 }) {
   return (
-    <View style={styles.tokenStack}>
+    <TokenRowGroup><View style={styles.tokenStack}>
       {steps.map((step, i) => (
-        <TokenRow key={String(step)} use={useNotes[step]} last={i === steps.length - 1}>
+        <TokenRow key={String(step)} use={useNotes[step]} last={i === steps.length - 1} notePlacement="right">
           <View style={styles.row}>
             <Text style={[sampleStyle(step), styles.sample]} numberOfLines={1}>
               {String(step)}
@@ -33,7 +33,7 @@ export function TypeScaleGallery<TStep extends string>({
           </View>
         </TokenRow>
       ))}
-    </View>
+    </View></TokenRowGroup>
   );
 }
 

package/native/catalog/comparison.ts

@@ -437,14 +437,48 @@ function heightAtWidth(block: PlacementBlock, width: number, available: number):
   return (block.height / Math.max(1, stackedRows)) * rows;
 }
 
-/** Side by side or stacked, for a page with exactly two blocks. Side by side splits the row into
- *  two equal columns and each block fills its own, so it is only possible when both blocks keep
- *  their minimum width in half a row; it is only taken when it saves at least PLACEMENT_MIN_SAVING
- *  against stacking, measuring each block at the width it would actually have. */
+/** Whether a block still fits on a single row in half the width. Deliberately stricter than "the
+ *  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. */
+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;
+}
+
+/** Side by side or stacked, for a page with exactly two blocks.
+ *
+ *  **Stacked is the default.** A page reads top to bottom, each block gets the whole row, and every
+ *  specimen keeps the width its component is actually used at. Side by side halves that width, so
+ *  it has to earn the space rather than be taken whenever it happens to save height — which is how
+ *  `Banner` ended up showing five full-width banners in a 462px column.
+ *
+ *  Two things earn it:
+ *
+ *  - **A single tall specimen.** One specimen taller than the column is wide leaves a long empty
+ *    strip beside it (an open `Dropdown` is 738px tall in a 462px column), and the other block
+ *    fits there for free.
+ *  - **Both still fit one row.** Specimens small enough that each block is a single row in half
+ *    the width lose nothing by sharing it.
+ *
+ *  Both still require each block to keep its minimum width in half a row, and the result to save
+ *  at least `PLACEMENT_MIN_SAVING` of height — side by side that saves nothing is just a narrower
+ *  page. */
 export function choosePlacement({ available, gap, first, second }: { available: number; gap: number; first: PlacementBlock; second: PlacementBlock }): 'side' | 'stacked' {
   const half = Math.floor((available - gap) / 2);
   if (half <= 0) return 'stacked';
   if ((first.minWidth ?? Infinity) > half || (second.minWidth ?? Infinity) > half) return 'stacked';
+
+  // Measured at the width it would have: a specimen is "tall" when it runs longer than the column
+  // it would sit in, which is what leaves room beside it.
+  // Either block can be the tall one. Checking `first` alone made placement depend on the order the
+  // page happens to declare its blocks in, so the same two blocks laid out variants-then-states and
+  // states-then-variants got different answers — and the rule says "a single specimen taller than
+  // its column", which says nothing about order.
+  const singleTallSpecimen = (first.itemCount === 1 && first.height > half) || (second.itemCount === 1 && second.height > half);
+  const bothFitOneRow = fitsOneRow(first, half) && fitsOneRow(second, half);
+  if (!singleTallSpecimen && !bothFitOneRow) return 'stacked';
+
   const sideHeight = Math.max(heightAtWidth(first, half, available), heightAtWidth(second, half, available));
   const stackedHeight = first.height + gap + second.height;
   return sideHeight <= stackedHeight - PLACEMENT_MIN_SAVING ? 'side' : 'stacked';

package/native/catalog/index.ts

@@ -23,7 +23,7 @@ export { ComparisonList } from './ComparisonList';
 export { ReferenceDetails } from './ReferenceDetails';
 export { PropsTable } from './PropsTable';
 export { VariantGroup } from './VariantGroup';
-export { TokenRow } from './TokenRow';
+export { TokenRow, TokenRowGroup } from './TokenRow';
 export { MotionSpecimen } from './MotionSpecimen';
 export type { MotionSpecimenProps, MotionSpecimenSpringConfig } from './MotionSpecimen';
 export { SpecimenSurface } from './SpecimenSurface';

package/package.json

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

package/starter-kit/components/Tooltip/Tooltip.catalog.tsx

@@ -51,7 +51,10 @@ export default defineCatalogPage({
     ],
   },
   states: {
-    itemsFill: true,
+    // No `itemsFill`: these specimens are a small icon trigger with a floating bubble, not a
+    // block-level component that wants the row's width. Filling pins the trigger to the cell's
+    // left edge (a filled specimen aligns to start, which is right for a Banner and wrong here),
+    // and the bubble — which centres on its trigger — then overflows the cell and is clipped.
     items: [
       {
         key: 'bottom',