@krapwoo/ds-viewer 0.4.9 → 0.6.0

package/dist/cli/render.js

@@ -0,0 +1,338 @@
+// cli/render.ts — `doctor --render`: open every catalog page in a headless browser and report what
+// only a real render shows (console errors, pages that fail to render, the viewer's own [Catalog]
+// layout warnings). The browser is resolved from the project; ds-viewer never installs one.
+import { spawn, spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const OVERFLOW = /is \d+px wide in a \d+px cell/;
+/**
+ * Turns one page's console output into doctor findings. Console errors and a missing heading are
+ * errors. The viewer's own `[Catalog]` warnings are warnings: `render-layout` for an example that
+ * overflows its cell, `render-catalog-warning` for anything else. Other console noise (React Native
+ * web deprecations, logs) is ignored. `seen` is shared across the whole run, so a warning the
+ * catalog logs on every page (a duplicate id, an unknown `composedOf` name) is reported once.
+ */
+export function issuesFromPage(page, messages, hasHeading, seen = new Set()) {
+    const ref = { page: page.id, ...(page.file ? { file: page.file } : {}) };
+    const issues = [];
+    if (!hasHeading) {
+        issues.push({ id: 'render-no-heading', severity: 'error', ...ref, message: 'The page rendered without its heading, so it probably failed to render.', fix: 'Open the page in `ds-viewer dev` and check the browser console.' });
+    }
+    const pageErrors = new Set();
+    for (const m of messages) {
+        const first = m.text.split('\n')[0];
+        if (m.type === 'error' || m.type === 'pageerror') {
+            if (pageErrors.has(first))
+                continue;
+            pageErrors.add(first);
+            issues.push({ id: 'render-error', severity: 'error', ...ref, message: `Console error while rendering: ${first}`, fix: 'Open the page in `ds-viewer dev` and fix the error in the browser console.' });
+        }
+        else if ((m.type === 'warn' || m.type === 'warning') && first.startsWith('[Catalog] ')) {
+            const text = first.slice('[Catalog] '.length);
+            if (seen.has(text))
+                continue;
+            seen.add(text);
+            issues.push(OVERFLOW.test(text)
+                ? { id: 'render-layout', severity: 'warning', ...ref, message: text, fix: 'Give the page a wider specimenSize; see the README page guide.' }
+                : { id: 'render-catalog-warning', severity: 'warning', ...ref, message: text, fix: 'Follow the message; the static doctor rule of the same name has the details.' });
+        }
+    }
+    return issues;
+}
+/**
+ * Runs in the browser: finds any two examples in the same list card whose specimens render
+ * identically. A variant's name is a claim that something differs; two cells that render the same
+ * teach the reader nothing and usually mean the difference needs a wider cell (a column count in a
+ * cell too narrow to show it) or was never wired up.
+ *
+ * The fingerprint covers each specimen's whole subtree — tag, box size, colours, radius and text —
+ * but never the caption strip that carries the variant's own name, which always differs. Colour is
+ * part of it, so a "default vs disabled" pair that differs only in tone is not reported.
+ */
+export const IDENTICAL_VARIANTS_SCRIPT = `(() => {
+  const doc = document;
+  const fingerprint = (root) => {
+    const out = [];
+    const base = root.getBoundingClientRect();
+    const walk = (el) => {
+      // PhoneFrame renders its example into a same-origin child document, so without reaching in
+      // every phone looks like an identical empty box.
+      if (el.tagName === 'IFRAME') {
+        try {
+          const body = el.contentDocument && el.contentDocument.body;
+          if (body) { out.push('IFRAME'); walk(body); return; }
+        } catch (error) { out.push('IFRAME|unreadable'); return; }
+      }
+      const box = el.getBoundingClientRect();
+      const style = getComputedStyle(el);
+      out.push([
+        el.tagName,
+        Math.round(box.width), Math.round(box.height),
+        Math.round(box.left - base.left), Math.round(box.top - base.top),
+        style.color, style.backgroundColor, style.borderColor, style.borderRadius,
+        style.fontSize, style.fontWeight, style.opacity, style.visibility,
+        // An icon page's variants are same-sized SVGs that differ only in geometry; a card page's
+        // in shadow; a text page's in style, decoration or alignment.
+        style.fill, style.stroke, style.boxShadow, style.fontStyle, style.textDecorationLine, style.textAlign,
+        el.getAttribute && (el.getAttribute('d') || el.getAttribute('points') || ''),
+        el.currentSrc || (el.getAttribute && el.getAttribute('src')) || '',
+        el.children.length === 0 ? (el.textContent || '') : '',
+        // A field's visible text is its value, not its textContent, which is always empty.
+        el.value === undefined ? '' : String(el.value),
+        el.placeholder || '', el.disabled ? 'disabled' : '',
+      ].join('|'));
+      for (const child of el.children) walk(child);
+    };
+    walk(root);
+    return out.join('\\n');
+  };
+  const pairs = [];
+  for (const card of doc.querySelectorAll('[role=list][aria-label]')) {
+    // ComparisonList and ComparisonGroups label their card "<page id>: <block title>". Anything
+    // else with role=list is a consumer's own component inside a specimen, not a card of examples.
+    if (!/^[^:]+: .+/.test(card.getAttribute('aria-label') || '')) continue;
+    const cells = [...card.querySelectorAll('[role=listitem]')].filter((c) => c.closest('[role=list]') === card);
+    const byPrint = new Map();
+    for (const cell of cells) {
+      // children[0] is the caption strip (the variant's own name); the specimen follows it.
+      const specimen = cell.children.length > 1 ? cell.children[1] : cell.children[0];
+      if (!specimen) continue;
+      const name = (cell.children[0] ? cell.children[0].textContent : '') || '';
+      const print = fingerprint(specimen);
+      if (!print.trim()) continue;
+      const first = byPrint.get(print);
+      if (first === undefined) byPrint.set(print, name);
+      else pairs.push({ card: card.getAttribute('aria-label') || '', names: [first, name] });
+    }
+  }
+  return pairs;
+})()`;
+/** Turns the browser's findings into doctor issues, one per identical pair. */
+export function identicalVariantIssues(page, pairs) {
+    const ref = { page: page.id, ...(page.file ? { file: page.file } : {}) };
+    return pairs.map((pair) => ({
+        id: 'identical-variants',
+        severity: 'warning',
+        ...ref,
+        message: `"${pair.names[0]}" and "${pair.names[1]}" render identically in ${pair.card || 'the same card'}.`,
+        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.",
+    }));
+}
+/** The project's own puppeteer, or `undefined` when it isn't installed. */
+export function loadProjectPuppeteer(projectRoot) {
+    try {
+        return createRequire(path.join(path.resolve(projectRoot), 'package.json'))('puppeteer');
+    }
+    catch {
+        return undefined;
+    }
+}
+export const RENDER_UNAVAILABLE = {
+    id: 'render-unavailable',
+    severity: 'error',
+    message: "`doctor --render` needs a headless browser, and puppeteer isn't installed in this project.",
+    fix: 'npm install --save-dev puppeteer (then run doctor --render again).',
+};
+const DEV_START_TIMEOUT_MS = 120_000;
+const FIRST_LOAD_TIMEOUT_MS = 300_000;
+const PAGE_TIMEOUT_MS = 120_000;
+const SETTLE_MS = 900;
+/** Stops `dev` and everything it started (Expo/Metro): the whole process tree on Windows, the
+ *  whole process group elsewhere (Expo stops through dev's own signal handler). Releases the pipes
+ *  so this process can exit. `os` is injectable for tests. */
+export function stopDev(child, os = {}) {
+    const platform = os.platform ?? process.platform;
+    if (child.pid) {
+        try {
+            if (platform === 'win32')
+                (os.spawnSync ?? spawnSync)('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' });
+            else
+                (os.kill ?? ((pid, signal) => process.kill(pid, signal)))(-child.pid, 'SIGTERM');
+        }
+        catch {
+            // Already exited.
+        }
+    }
+    child.stdout?.destroy();
+    child.stderr?.destroy();
+    child.unref();
+}
+/** The last few KB of dev's output, so a failed start can say why. */
+function outputTail() {
+    let tail = '';
+    return {
+        push: (data) => {
+            tail = (tail + String(data)).slice(-4000);
+        },
+        text: () => {
+            const lines = tail.trim().split('\n').slice(-8).join('\n');
+            return lines ? `\n${lines}` : '';
+        },
+    };
+}
+/** Starts the project's own `dev` in its own process group. `onSpawn` receives the child at once,
+ *  so a signal during startup can still stop it. */
+function startDev(projectRoot, onSpawn) {
+    const main = path.join(path.dirname(fileURLToPath(import.meta.url)), 'main.js');
+    return new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, [main, 'dev'], {
+            cwd: projectRoot,
+            env: { ...process.env, CI: '1', DS_VIEWER_NO_UPDATE_CHECK: '1' },
+            detached: process.platform !== 'win32',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        onSpawn(child);
+        const output = outputTail();
+        let done = false;
+        const fail = (message) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            stopDev(child);
+            reject(new Error(`${message}${output.text()}`));
+        };
+        const timer = setTimeout(() => fail('Timed out waiting for ds-viewer dev to start.'), DEV_START_TIMEOUT_MS);
+        // Read continuously (so Metro's output never fills the pipe) and keep the tail for errors.
+        child.stderr?.on('data', output.push);
+        child.stdout?.on('data', (data) => {
+            output.push(data);
+            const match = String(data).match(/Starting the catalog at http:\/\/localhost:(\d+)/);
+            if (match && !done) {
+                done = true;
+                clearTimeout(timer);
+                resolve({ child, port: Number(match[1]) });
+            }
+        });
+        child.on('exit', (code) => fail(`ds-viewer dev exited early (code ${code}).`));
+    });
+}
+const SIGNAL_EXIT_CODES = { SIGINT: 130, SIGTERM: 143, SIGHUP: 129 };
+/** A sidebar href's page id; a malformed escape falls back to the raw text (like `idFromHash`). */
+function idFromHref(href) {
+    const raw = href.slice(1);
+    try {
+        return decodeURIComponent(raw);
+    }
+    catch {
+        return raw;
+    }
+}
+/** Opens every sidebar page and returns its findings. `files` maps page ids to project-relative
+ *  page files, for the findings' `file`. `log` receives progress lines (stderr in the CLI). `deps`
+ *  replaces the browser, dev process control and exit for tests. */
+export async function renderCheck(projectRoot, options = {}) {
+    projectRoot = path.resolve(projectRoot);
+    const deps = options.deps ?? {};
+    const puppeteer = (deps.puppeteer ?? loadProjectPuppeteer(projectRoot));
+    if (!puppeteer)
+        return [RENDER_UNAVAILABLE];
+    const stop = deps.stopDev ?? ((child) => stopDev(child));
+    const exit = deps.exit ?? ((code) => process.exit(code));
+    const log = options.log ?? (() => { });
+    // Set as soon as dev is spawned, before it's ready, so a signal during startup still stops it.
+    let devChild;
+    let port = 0;
+    let browser;
+    // Ctrl-C or a CI cancel must still stop Metro: `dev` runs in its own process group, so the
+    // terminal's signal never reaches it. Registered before the browser launches, so it runs ahead
+    // of puppeteer's own handler.
+    const handlers = Object.keys(SIGNAL_EXIT_CODES).map((signal) => {
+        const handler = () => {
+            if (devChild)
+                stop(devChild);
+            exit(SIGNAL_EXIT_CODES[signal]);
+        };
+        process.on(signal, handler);
+        return [signal, handler];
+    });
+    try {
+        // The browser first: a missing browser download shouldn't start Metro for nothing.
+        try {
+            browser = await puppeteer.launch({ headless: true });
+        }
+        catch (error) {
+            return [{ ...RENDER_UNAVAILABLE, message: `Couldn't start the headless browser: ${error.message.split('\n')[0]}`, fix: 'npx puppeteer browsers install chrome' }];
+        }
+        ({ port } = await (deps.startDev ?? startDev)(projectRoot, (child) => {
+            devChild = child;
+        }));
+        const home = await browser.newPage();
+        const deadline = Date.now() + FIRST_LOAD_TIMEOUT_MS;
+        for (;;) {
+            try {
+                await home.goto(`http://localhost:${port}`, { waitUntil: 'networkidle0', timeout: FIRST_LOAD_TIMEOUT_MS });
+                break;
+            }
+            catch (error) {
+                if (!String(error).includes('ERR_CONNECTION_REFUSED') || Date.now() > deadline)
+                    throw error;
+                await new Promise((r) => setTimeout(r, 1000));
+            }
+        }
+        // Runs in the browser; `document` is typed loosely because the CLI compiles without DOM types.
+        const hrefs = await home.evaluate(() => {
+            const doc = globalThis.document;
+            return [...new Set(Array.from(doc.querySelectorAll('a[href^="#"]')).map((a) => a.getAttribute('href') ?? ''))];
+        });
+        await home.close();
+        const ids = hrefs.map(idFromHref).filter(Boolean);
+        if (ids.length === 0) {
+            return [{ id: 'render-failed', severity: 'error', message: 'The catalog rendered no sidebar links, so it probably failed to render at all.', fix: 'Run `ds-viewer dev` and check the browser console.' }];
+        }
+        log(`Rendering ${ids.length} pages…`);
+        const seen = new Set();
+        const issues = [];
+        for (const id of ids) {
+            // One page failing (a navigation timeout) is that page's finding; the others still run.
+            let page;
+            try {
+                page = await browser.newPage();
+                await page.setViewport({ width: 1280, height: 800 });
+                const messages = [];
+                page.on('console', (m) => messages.push({ type: m.type(), text: m.text() }));
+                page.on('pageerror', (e) => messages.push({ type: 'pageerror', text: String(e) }));
+                await page.goto(`http://localhost:${port}/#${encodeURIComponent(id)}`, { waitUntil: 'networkidle0', timeout: PAGE_TIMEOUT_MS });
+                await new Promise((r) => setTimeout(r, options.settleMs ?? SETTLE_MS));
+                const hasHeading = await page.evaluate(() => {
+                    const doc = globalThis.document;
+                    return Boolean(doc.querySelector('[role="heading"]')?.textContent?.trim());
+                });
+                issues.push(...issuesFromPage({ id, file: options.files?.get(id) }, messages, hasHeading, seen));
+                // Advisory: a script failure (a detached child document mid-navigation, an element whose
+                // `value` getter throws) must not become this page's render-error, so it has its own catch
+                // rather than falling into the one below.
+                let identical;
+                try {
+                    identical = (await page.evaluate(IDENTICAL_VARIANTS_SCRIPT));
+                }
+                catch {
+                    identical = undefined;
+                }
+                if (Array.isArray(identical))
+                    issues.push(...identicalVariantIssues({ id, file: options.files?.get(id) }, identical));
+                await page.close();
+            }
+            catch (error) {
+                // A stuck page's tab is closed, so it doesn't keep loading next to the remaining pages.
+                await page?.close().catch(() => { });
+                const file = options.files?.get(id);
+                issues.push({ id: 'render-error', severity: 'error', page: id, ...(file ? { file } : {}), message: `Couldn't open the page: ${error.message.split('\n')[0]}`, fix: 'Open the page in `ds-viewer dev`; it may be very slow to load or stuck.' });
+            }
+        }
+        log(`Checked ${ids.length} pages.`);
+        return issues;
+    }
+    catch (error) {
+        return [{ id: 'render-failed', severity: 'error', message: `Couldn't render the catalog: ${error.message}`, fix: "Run `ds-viewer dev` to see why the catalog doesn't start." }];
+    }
+    finally {
+        for (const [signal, handler] of handlers)
+            process.off(signal, handler);
+        if (browser)
+            await browser.close().catch(() => { });
+        if (devChild)
+            stop(devChild);
+    }
+}

package/dist/cli/staticPage.js

@@ -42,6 +42,7 @@ function readStaticPage(file) {
     }
     const sourceFile = ts.createSourceFile(file, text, ts.ScriptTarget.ES2022, true, ts.ScriptKind.TSX);
     const imports = importedNames(sourceFile, '@krapwoo/ds-viewer');
+    const viewerImports = [...new Set(imports.values())];
     const defineCatalogPageNames = localNamesFor(imports, 'defineCatalogPage');
     const gridNames = localNamesFor(imports, 'grid');
     const call = defaultExportCall(sourceFile);
@@ -49,13 +50,13 @@ function readStaticPage(file) {
         // Not a recognized `defineCatalogPage(...)` default export — e.g. a hand-written object, or a
         // shadowed/renamed import this reader can't trace. Not a parse error: the file is valid
         // TypeScript, just not literal-checkable.
-        return { file, checkable: false };
+        return { file, checkable: false, viewerImports };
     }
     const consts = topLevelConsts(sourceFile);
     const pageObject = resolve(call.arguments[0], consts, new Set());
     if (!ts.isObjectLiteralExpression(pageObject))
-        return { file, checkable: false };
-    const page = { file, checkable: true };
+        return { file, checkable: false, viewerImports };
+    const page = { file, checkable: true, viewerImports };
     const idProp = findProp(pageObject, 'id');
     const componentProp = findProp(pageObject, 'component');
     const groupProp = findProp(pageObject, 'group');
@@ -169,6 +170,23 @@ function readStaticPage(file) {
                 page.intentionalStaticPreviewReason = stringLiteral(resolve(reasonProp.initializer, consts, new Set()));
         }
     }
+    const internalPropsProp = findProp(pageObject, 'internalProps');
+    if (internalPropsProp) {
+        const resolved = resolve(internalPropsProp.initializer, consts, new Set());
+        if (ts.isObjectLiteralExpression(resolved)) {
+            const names = [];
+            for (const prop of resolved.properties) {
+                if (!ts.isPropertyAssignment(prop))
+                    continue;
+                const name = ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name) ? prop.name.text : undefined;
+                const reason = stringLiteral(resolve(prop.initializer, consts, new Set()));
+                if (name && reason)
+                    names.push(name);
+            }
+            if (names.length > 0)
+                page.internalProps = names;
+        }
+    }
     return page;
 }
 /** A literal array of `ComposedOfEntry`-shaped object literals, read down to just `component`
@@ -193,16 +211,21 @@ function readComposedOf(node, consts) {
     return entries;
 }
 /** Local name -> imported name, for every named import from `moduleSpecifier`. */
-function importedNames(sourceFile, moduleSpecifier) {
+export function importedNames(sourceFile, moduleSpecifier) {
     const names = new Map();
     for (const statement of sourceFile.statements) {
         if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier) || statement.moduleSpecifier.text !== moduleSpecifier) {
             continue;
         }
+        // Type-only imports bring no runtime value (`import type { X }`, `import { type X }`).
+        if (statement.importClause?.isTypeOnly)
+            continue;
         const bindings = statement.importClause?.namedBindings;
         if (!bindings || !ts.isNamedImports(bindings))
             continue;
         for (const element of bindings.elements) {
+            if (element.isTypeOnly)
+                continue;
             names.set(element.name.text, element.propertyName ? element.propertyName.text : element.name.text);
         }
     }

package/dist/native/catalog/comparison.js

@@ -2,7 +2,6 @@
  *  content width is a 1280px viewport minus the 264px sidebar and 32px side padding. */
 export const MATRIX_LAYOUT = {
     rowHeaderWidth: 120,
-    columnMaxWidth: 402,
     cellPadding: 16,
     rowMinHeight: 150,
     laptopContentWidth: 952,
@@ -21,8 +20,9 @@ export const REFERENCE_MIN_COLUMN_WIDTH = 280;
 /** Gap between reference columns (CATALOG_SPACE['2xl'], the same token the card's columns already
  *  use). */
 export const REFERENCE_COLUMN_GAP = 32;
-/** Smallest column or cell width per specimen size. Wide specimens are fixed at phone width. */
-export const COLUMN_MIN_WIDTH = { compact: 160, regular: 240, wide: 402 };
+/** Smallest column or cell width per specimen size. `wide` is phone width as a minimum, not a
+ *  maximum: cells share their container equally above it. */
+export const COLUMN_MIN_WIDTH = { compact: 160, regular: 240, wide: 402, page: 512 };
 /** `Array.isArray`'s built-in type guard narrows to a mutable `any[]`, which a `readonly T[]`
  *  union member is never assignable to — so the `else` branch of `Array.isArray(axis) ? ... :
  *  ...` keeps `axis`'s full union type instead of narrowing away the array member. This explicit
@@ -71,15 +71,15 @@ export function grid(rowLabel, columnLabel, rows, columns, cell, size) {
 export function gridColumnLimit(size) {
     return Math.floor((MATRIX_LAYOUT.laptopContentWidth - MATRIX_LAYOUT.rowHeaderWidth) / COLUMN_MIN_WIDTH[size]);
 }
-export function gridWidthBounds(columnCount, size) {
-    const n = Math.max(0, columnCount);
-    return {
-        minWidth: MATRIX_LAYOUT.rowHeaderWidth + n * COLUMN_MIN_WIDTH[size],
-        maxWidth: MATRIX_LAYOUT.rowHeaderWidth + n * MATRIX_LAYOUT.columnMaxWidth,
-    };
+/** The narrowest a grid card may be: the row header plus every column at its minimum. A card wider
+ *  than its container scrolls inside itself; above this width the columns share the container
+ *  equally, because the phone-width cap belongs to the specimen inside a cell, not to the column. */
+export function gridMinWidth(columnCount, size) {
+    return MATRIX_LAYOUT.rowHeaderWidth + Math.max(0, columnCount) * COLUMN_MIN_WIDTH[size];
 }
 /** Balanced wrapping for a one-axis list inside a single bordered card (1px outer border). Each
- *  cell's 1px divider sits inside its own width, so no cell is ever wider than 402px. Uses as few
+ *  cell's 1px divider sits inside its own width. Cells share the container equally — phone width
+ *  caps the specimen inside a cell, not the cell. Uses as few
  *  rows as fit, then spreads items evenly across them so a short last row leaves as little empty
  *  space as possible. `fillers` blank cells complete the last row. `columnCap` (from
  *  `VariantSlot.maxColumns`) only ever lowers the natural, width-based column count — a narrow
@@ -96,7 +96,7 @@ export function listGeometry(itemCount, availableWidth, size, columnCap) {
     const rows = Math.ceil(itemCount / maxColumns);
     const columns = Math.ceil(itemCount / rows);
     const fitted = Math.floor(inner / columns);
-    const cellWidth = size === 'wide' ? MATRIX_LAYOUT.columnMaxWidth : Math.max(min, Math.min(MATRIX_LAYOUT.columnMaxWidth, fitted));
+    const cellWidth = Math.max(min, fitted);
     return {
         columns,
         rows,
@@ -198,10 +198,11 @@ function slotColumnCap(slot) {
         return { maxColumns: slot.maxColumns };
     return slot.itemsFill ? { maxColumns: FILLED_SLOT_MAX_COLUMNS } : {};
 }
-function slotItems(slot, from) {
+function slotItems(slot, from, fillByDefault = false) {
     // Nullish, not `||`: an item's own explicit `fill: false` must override an inherited
     // `itemsFill: true`, which `false || slot.itemsFill` would silently discard.
-    return slot.items.map((item) => ({ key: item.key, slot: from, label: item.name, node: item.node, fill: item.fill ?? slot.itemsFill, surface: item.surface, align: item.align }));
+    // Page-width examples (layouts wider than a phone) fill their cell unless they say otherwise.
+    return slot.items.map((item) => ({ key: item.key, slot: from, label: item.name, node: item.node, fill: item.fill ?? slot.itemsFill ?? (fillByDefault || undefined), surface: item.surface, align: item.align }));
 }
 /** Preview widths, each capped at phone width. 'full' is kept for catalog chrome and token pages. */
 function previewWidths(requested, fallback) {
@@ -269,12 +270,12 @@ export function presentationBlocks(def, options = {}) {
                 kind: 'list',
                 title: 'Variants',
                 size: slotSize(def, def.variants),
-                items: slotItems(def.variants, 'variants'),
+                items: slotItems(def.variants, 'variants', def.specimenSize === 'page'),
                 ...slotColumnCap(def.variants),
             });
         }
         else if (def.render) {
-            blocks.push({ kind: 'preview', title: 'Preview', widths: previewWidths(def.previewWidths, options.defaultPreviewWidths) });
+            blocks.push({ kind: 'preview', title: 'Preview', widths: previewWidths(def.previewWidths, options.defaultPreviewWidths), ...(def.previewLayout ? { layout: def.previewLayout } : {}) });
         }
     }
     if (states) {
@@ -283,7 +284,7 @@ export function presentationBlocks(def, options = {}) {
             kind: 'list',
             title: secondary ? 'Other configurations' : 'States / configurations',
             size: slotSize(def, states),
-            items: slotItems(states, 'states'),
+            items: slotItems(states, 'states', def.specimenSize === 'page'),
             ...slotColumnCap(states),
         });
     }
@@ -292,23 +293,61 @@ export function presentationBlocks(def, options = {}) {
     }
     return blocks;
 }
-/** Side by side or stacked, for a page with exactly two blocks. Tries both and keeps the shorter;
- *  stays stacked unless side by side saves at least PLACEMENT_MIN_SAVING. Only a list can move
- *  beside a first block that hugs its content, and only when its cells keep their minimum width. */
+/** The narrowest a block renders at. Every card fills the column it is given, so this is a floor,
+ *  not the width it will take: below it a grid scrolls inside itself and a list would push its
+ *  cells under their minimum. `Infinity` means the block can only have a whole row. */
+/** What a preview card adds around its frames: `padding` (CATALOG_SPACE.xl) and a 1px border on
+ *  each side. `blockMinWidth` must add it, or a preview is offered a half-row that fits its frame
+ *  only after the card has taken its share, and the frame silently renders under phone width.
+ *  SectionBlock's `previewCard` style is built from these, so the two cannot drift. */
+export const PREVIEW_CARD_CHROME = { padding: 24, border: 1 };
+/** The same for a `previewLayout: 'table'` card: no outer padding, a 1px border, and each cell
+ *  carries `cellPadding` on both sides of its frame. */
+export const TABLE_PREVIEW_CHROME = { padding: MATRIX_LAYOUT.cellPadding, border: 1 };
+/** Total horizontal chrome for one preview frame in either card. */
+export function previewChrome(layout) {
+    const chrome = layout === 'table' ? TABLE_PREVIEW_CHROME : PREVIEW_CARD_CHROME;
+    return 2 * chrome.padding + 2 * chrome.border;
+}
+export function blockMinWidth(block) {
+    switch (block.kind) {
+        case 'grid':
+            return gridMinWidth(axisItems(block.comparison.columns).length, block.size);
+        case 'grouped':
+            return MATRIX_LAYOUT.rowHeaderWidth + Math.max(1, ...block.groups.map((g) => g.items.length)) * COLUMN_MIN_WIDTH[block.size] + 2;
+        case 'list':
+            // One column: a list always wraps further rather than going below its size's minimum.
+            return COLUMN_MIN_WIDTH[block.size] + 2;
+        case 'preview':
+            // A 'full' preview is the row. Otherwise the *widest* frame sets the minimum: the frames wrap,
+            // so each one sits on its own row and `maxWidth: '100%'` would squeeze any frame wider than
+            // the card. The card's own chrome counts too — a frame keeps its width only if the row also
+            // covers the padding and border around it.
+            return block.widths === 'full' ? Infinity : Math.max(...block.widths) + previewChrome(block.layout);
+        default:
+            return Infinity;
+    }
+}
+/** The height a block takes at `width`, from the height measured while stacked at `available`.
+ *  Only a list reflows: its rows change with the width, and every row is the same height. */
+function heightAtWidth(block, width, available) {
+    if (block.kind !== 'list' || !block.itemCount || !block.size)
+        return block.height;
+    const stackedRows = listGeometry(block.itemCount, available, block.size, block.maxColumns).rows;
+    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. */
 export function choosePlacement({ available, gap, first, second }) {
-    if (second.kind !== 'list' || !second.itemCount || !second.size)
-        return 'stacked';
-    const firstWidth = first.width ?? available;
-    if (firstWidth > available * 0.7)
+    const half = Math.floor((available - gap) / 2);
+    if (half <= 0)
         return 'stacked';
-    const room = available - firstWidth - gap;
-    const minCell = second.size === 'wide' ? MATRIX_LAYOUT.columnMaxWidth : COLUMN_MIN_WIDTH[second.size];
-    if (room < minCell + 2)
+    if ((first.minWidth ?? Infinity) > half || (second.minWidth ?? Infinity) > half)
         return 'stacked';
-    const stackedRows = listGeometry(second.itemCount, available, second.size, second.maxColumns).rows;
-    const sideRows = listGeometry(second.itemCount, room, second.size, second.maxColumns).rows;
-    const rowHeight = second.height / Math.max(1, stackedRows);
-    const sideHeight = Math.max(first.height, sideRows * rowHeight);
+    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/dist/native/catalog/tokens.js

@@ -10,15 +10,17 @@
  * (docs/design/2026-10-06-catalog-studio-matrix-*.html), with one deliberate exception:
  * `textMuted` stays #666666 because the references' #777777 fails WCAG AA contrast.
  */
+/** Owner decision 2026-10-11: only 10, 12, 14, 16, 18, 24, 28, 32 and 40. Named roles share a
+ *  step (tableHeader and panelHeading are 12, brand is 18). */
 export const CATALOG_TYPE = {
     xs: 10,
-    tableHeader: 11,
+    tableHeader: 12,
     sm: 12,
-    panelHeading: 13,
+    panelHeading: 12,
     md: 14,
     lg: 16,
-    brand: 17,
-    xl: 20,
+    brand: 18,
+    xl: 18,
     '2xl': 24,
     pageTitle: 28,
     '3xl': 32,
@@ -76,8 +78,8 @@ export const CATALOG_TYPE_USE = {
     md: 'Default body text: descriptions, nav links, grid row headers, quick-reference rows, the filter field.',
     lg: 'Pager arrows and the filter field\'s clear (×) glyph.',
     brand: 'The app name at the top of the sidebar.',
-    xl: 'Reserved — no current consumer.',
-    '2xl': 'Reserved — no current consumer.',
+    xl: "The major-update banner's close (×) glyph.",
+    '2xl': "The update page's version numbers and the arrow between them.",
     pageTitle: 'The selected page\'s title.',
     '3xl': 'Reserved — no current consumer.',
     '4xl': 'Reserved — no current consumer.',

package/native/catalog/CatalogButton.tsx

@@ -0,0 +1,47 @@
+import React, { forwardRef, useState } from 'react';
+import { Pressable, StyleSheet, Text, type View } from 'react-native';
+import { CATALOG_COLOR, CATALOG_LAYOUT, CATALOG_RADIUS, CATALOG_TYPE } from './tokens';
+
+/** The viewer's own button, for catalog chrome and demo triggers (not an app component): a rounded
+ *  rectangle, primary in the accent blue, secondary outlined. */
+export const CatalogButton = forwardRef<View, {
+  label: string;
+  onPress: () => void;
+  variant?: 'primary' | 'secondary';
+  accessibilityLabel?: string;
+}>(function CatalogButton({ label, onPress, variant = 'primary', accessibilityLabel }, ref) {
+  const [focused, setFocused] = useState(false);
+  const primary = variant === 'primary';
+  return (
+    <Pressable
+      ref={ref}
+      onPress={onPress}
+      onFocus={() => setFocused(true)}
+      onBlur={() => setFocused(false)}
+      accessibilityRole="button"
+      accessibilityLabel={accessibilityLabel ?? label}
+      style={({ pressed }) => [
+        styles.base,
+        primary ? styles.primary : styles.secondary,
+        pressed && (primary ? styles.primaryPressed : styles.secondaryPressed),
+        focused && styles.focus,
+      ]}
+    >
+      <Text style={[styles.label, primary ? styles.labelPrimary : styles.labelSecondary]}>{label}</Text>
+    </Pressable>
+  );
+});
+
+const styles = StyleSheet.create({
+  // A rounded rectangle (owner decision 2026-10-11); primary in the catalog's accent blue.
+  base: { height: CATALOG_LAYOUT.controlSize, paddingHorizontal: 18, borderRadius: CATALOG_RADIUS.control, alignItems: 'center', justifyContent: 'center', alignSelf: 'center' },
+  primary: { backgroundColor: CATALOG_COLOR.accent },
+  primaryPressed: { opacity: 0.85 },
+  secondary: { borderWidth: 1, borderColor: CATALOG_COLOR.borderStrong, backgroundColor: CATALOG_COLOR.surface },
+  secondaryPressed: { backgroundColor: CATALOG_COLOR.surfacePressed },
+  // Same ring as the sidebar's: an outline, so focusing never shifts the layout.
+  focus: { outlineWidth: CATALOG_LAYOUT.focusRingWidth, outlineStyle: 'solid', outlineColor: CATALOG_COLOR.focusRing } as object,
+  label: { fontSize: CATALOG_TYPE.md, fontWeight: '700' },
+  labelPrimary: { color: '#ffffff' },
+  labelSecondary: { color: CATALOG_COLOR.text },
+});