@krapwoo/ds-viewer 0.2.0 → 0.3.0

package/dist/native/catalog/comparison.js

@@ -0,0 +1,283 @@
+/** Approved geometry. `cellPadding` equals CATALOG_SPACE.lg (asserted in tests). The laptop
+ *  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,
+};
+/** Component previews never render wider than a phone. */
+export const PREVIEW_MAX_WIDTH = 402;
+/** Two blocks share a row only when that saves at least this much page height. */
+export const PLACEMENT_MIN_SAVING = 120;
+/** A Props column is never narrower than this; below it the Props box uses one column. */
+export const PROPS_MIN_COLUMN_WIDTH = 360;
+/** Gap between the two Props columns (CATALOG_SPACE['2xl']). */
+export const PROPS_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 };
+/** `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
+ *  predicate sidesteps that (never caught before Task 4: this file had never been typechecked by
+ *  `tsc` until `cli/doctor.ts`'s import pulled it into the root `tsconfig.json`'s program). */
+function isBoundAxis(axis) {
+    return !Array.isArray(axis);
+}
+/** A `GridAxis`'s own items, whether it's a plain array or bound to a prop — every reader of
+ *  `ComparisonDef.rows`/`columns` goes through this (never `Array.isArray` directly), so a future
+ *  third axis shape only needs to change this one function. */
+export function axisItems(axis) {
+    return isBoundAxis(axis) ? [...axis.items] : [...axis];
+}
+/** The prop name a `GridAxis` is bound to, or undefined for a plain, unbound axis. */
+export function axisProp(axis) {
+    return isBoundAxis(axis) ? axis.prop : undefined;
+}
+/**
+ * Shared page-authoring helper (design §1 "Page shape", §4 "Binding examples to props"). Every
+ * grid comparison in the starter kit builds its `ComparisonDef` with this instead of its own local
+ * copy, so `cli/staticPage.ts`'s static reader has exactly one call shape to recognize anywhere a
+ * page's `comparison` field is produced by a function call rather than written as a plain object
+ * literal. `rows`/`columns` accept either a plain item array (unbound) or `{ prop, items }` (bound)
+ * — the cell grid itself is unaffected either way, since cells are always keyed by each axis's own
+ * items regardless of whether that axis names a prop. Lives here, beside `axisItems`/`axisProp`,
+ * rather than in its own `grid.ts` — every other file in this module has only *type-only* relative
+ * imports; a bare, no-extension value import would be the first of its kind in `native/catalog`.
+ *
+ * Each cell is a real instance with exactly the props its row and column name. Never build these by
+ * multiplying `variants` with `states` — those are pre-rendered nodes and cannot be combined.
+ */
+export function grid(rowLabel, columnLabel, rows, columns, cell, size) {
+    const rowItems = axisItems(rows);
+    const columnItems = axisItems(columns);
+    return {
+        rowLabel,
+        columnLabel,
+        rows,
+        columns,
+        cells: rowItems.flatMap((row) => columnItems.map((column) => ({ rowKey: row.key, columnKey: column.key, node: cell(row.key, column.key) }))),
+        size,
+    };
+}
+/** How many grid columns fit beside the row header on a 1280px laptop without scrolling. */
+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,
+    };
+}
+/** 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
+ *  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. */
+export function listGeometry(itemCount, availableWidth, size) {
+    if (itemCount <= 0)
+        return { columns: 0, rows: 0, fillers: 0, cellWidth: 0, containerWidth: 0 };
+    const inner = Math.max(0, availableWidth - 2);
+    const min = COLUMN_MIN_WIDTH[size];
+    const maxColumns = Math.max(1, Math.min(itemCount, Math.floor(inner / min)));
+    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));
+    return {
+        columns,
+        rows,
+        fillers: rows * columns - itemCount,
+        cellWidth,
+        containerWidth: columns * cellWidth + 2,
+    };
+}
+export function cellKey(rowKey, columnKey) {
+    return `${rowKey}\u0000${columnKey}`;
+}
+export function indexCells(def) {
+    const index = new Map();
+    for (const cell of def.cells) {
+        const key = cellKey(cell.rowKey, cell.columnKey);
+        if (!index.has(key))
+            index.set(key, cell);
+    }
+    return index;
+}
+/** Human-readable problems in a stable order: axis duplicates, column fit, each cell in
+ *  declaration order, then missing coordinates in row-major order. Empty when valid. */
+export function validateComparison(def) {
+    const rowItems = axisItems(def.rows);
+    const columnItems = axisItems(def.columns);
+    if (rowItems.length === 0 || columnItems.length === 0) {
+        return ['Comparison needs at least one row and one column.'];
+    }
+    const issues = [];
+    const rowKeys = new Set();
+    for (const row of rowItems) {
+        if (rowKeys.has(row.key))
+            issues.push(`Duplicate row key "${row.key}".`);
+        rowKeys.add(row.key);
+    }
+    const columnKeys = new Set();
+    for (const column of columnItems) {
+        if (columnKeys.has(column.key))
+            issues.push(`Duplicate column key "${column.key}".`);
+        columnKeys.add(column.key);
+    }
+    const size = def.size ?? 'regular';
+    const limit = gridColumnLimit(size);
+    if (columnKeys.size > limit) {
+        issues.push(`Grid has ${columnKeys.size} columns; at most ${limit} ${size} columns fit a 1280px laptop. Swap the axes or use two lists.`);
+    }
+    const seen = new Set();
+    for (const cell of def.cells) {
+        const key = cellKey(cell.rowKey, cell.columnKey);
+        if (seen.has(key)) {
+            issues.push(`Duplicate cell for row "${cell.rowKey}" and column "${cell.columnKey}".`);
+            continue;
+        }
+        seen.add(key);
+        if (!rowKeys.has(cell.rowKey)) {
+            issues.push(`Cell references undeclared row "${cell.rowKey}".`);
+            continue;
+        }
+        if (!columnKeys.has(cell.columnKey)) {
+            issues.push(`Cell references undeclared column "${cell.columnKey}".`);
+            continue;
+        }
+        const hasNode = cell.node !== undefined;
+        const hasReason = typeof cell.unavailableReason === 'string' && cell.unavailableReason.length > 0;
+        if (hasNode === hasReason) {
+            issues.push(`Cell for row "${cell.rowKey}" and column "${cell.columnKey}" must provide exactly one of node or unavailableReason.`);
+        }
+    }
+    for (const rowKey of rowKeys) {
+        for (const columnKey of columnKeys) {
+            if (!seen.has(cellKey(rowKey, columnKey))) {
+                issues.push(`Missing cell for row "${rowKey}" and column "${columnKey}".`);
+            }
+        }
+    }
+    return issues;
+}
+/** `states` minus items whose key is already a grid row or column. */
+export function remainingStates(states, comparison) {
+    if (!states)
+        return undefined;
+    if (!comparison)
+        return states;
+    const covered = new Set([...axisItems(comparison.rows).map((row) => row.key), ...axisItems(comparison.columns).map((column) => column.key)]);
+    const items = states.items.filter((item) => !covered.has(item.key));
+    return items.length > 0 ? { ...states, items } : undefined;
+}
+/** Specimen size for a one-axis slot: the section's explicit size, else wide for full-width
+ *  (itemsFill) slots, else regular. */
+export function slotSize(def, slot) {
+    return def.specimenSize ?? (slot.itemsFill ? 'wide' : 'regular');
+}
+function slotItems(slot) {
+    return slot.items.map((item) => ({ key: item.key, label: item.name, node: item.node, fill: item.fill || slot.itemsFill }));
+}
+/** Preview widths, each capped at phone width. 'full' is kept for catalog chrome and token pages. */
+function previewWidths(requested, fallback) {
+    const widths = requested ?? fallback ?? [PREVIEW_MAX_WIDTH];
+    return widths === 'full' ? 'full' : widths.map((w) => Math.min(w, PREVIEW_MAX_WIDTH));
+}
+/** Grouped rows when at least one state names a variant through `group`. Every variant gets a row:
+ *  its grouped states, or the variant's own example when it has none. States without a matching
+ *  group are returned as leftovers for "Other configurations". */
+function groupStates(variants, states) {
+    const variantKeys = new Set(variants.items.map((v) => v.key));
+    if (!states.items.some((s) => s.group !== undefined && variantKeys.has(s.group)))
+        return undefined;
+    const fill = (item, slot) => item.fill || slot.itemsFill;
+    const groups = variants.items.map((variant) => {
+        const own = states.items.filter((s) => s.group === variant.key);
+        const items = own.length > 0
+            ? own.map((s) => ({ key: s.key, label: s.name, node: s.node, fill: fill(s, states) }))
+            : [{ key: variant.key, label: variant.name, node: variant.node, fill: fill(variant, variants) }];
+        return { key: variant.key, label: variant.name, items };
+    });
+    const rest = states.items.filter((s) => s.group === undefined || !variantKeys.has(s.group));
+    for (const s of rest) {
+        if (s.group !== undefined && globalThis.__DEV__) {
+            console.warn(`[Catalog] state "${s.key}" names group "${s.group}", which matches no variant key; it is shown under "Other configurations".`);
+        }
+    }
+    return { groups, leftovers: rest.length > 0 ? { ...states, items: rest } : undefined };
+}
+/** The visual blocks of one page, in reading order. Reference details are not included. A page
+ *  never shows an empty block next to a real one; with nothing documented at all it shows one
+ *  "No examples documented." block. */
+export function presentationBlocks(def, options = {}) {
+    if (def.tokenGallery) {
+        const title = def.fullWidthLabel ?? 'Tokens';
+        return [def.render ? { kind: 'preview', title, widths: 'full' } : { kind: 'empty', title, message: 'Nothing to preview.' }];
+    }
+    const hide = def.hide ?? {};
+    const blocks = [];
+    let states = hide.states ? undefined : remainingStates(def.states, def.comparison);
+    if (!hide.variants) {
+        const grouped = !def.comparison && def.variants && states ? groupStates(def.variants, states) : undefined;
+        if (def.comparison) {
+            blocks.push({
+                kind: 'grid',
+                title: `${def.comparison.rowLabel} × ${def.comparison.columnLabel}`,
+                size: def.comparison.size ?? def.specimenSize ?? 'regular',
+                comparison: def.comparison,
+            });
+        }
+        else if (grouped && def.variants) {
+            // Grouped rows place several cells beside a row header, so full-width (itemsFill) slots do
+            // not force 402px cells here; a cell's own `fill` still stretches its specimen.
+            blocks.push({ kind: 'grouped', title: 'Variant × configuration', size: def.specimenSize ?? 'regular', groups: grouped.groups });
+            states = grouped.leftovers;
+        }
+        else if (def.variants) {
+            blocks.push({ kind: 'list', title: 'Variants', size: slotSize(def, def.variants), items: slotItems(def.variants) });
+        }
+        else if (def.render) {
+            blocks.push({ kind: 'preview', title: 'Preview', widths: previewWidths(def.previewWidths, options.defaultPreviewWidths) });
+        }
+    }
+    if (states) {
+        const secondary = blocks.length > 0 && blocks[0].kind !== 'list';
+        blocks.push({
+            kind: 'list',
+            title: secondary ? 'Other configurations' : 'States / configurations',
+            size: slotSize(def, states),
+            items: slotItems(states),
+        });
+    }
+    if (blocks.length === 0 && !hide.variants && !hide.states) {
+        blocks.push({ kind: 'empty', title: 'Examples', message: 'No examples documented.' });
+    }
+    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. */
+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)
+        return 'stacked';
+    const room = available - firstWidth - gap;
+    const minCell = second.size === 'wide' ? MATRIX_LAYOUT.columnMaxWidth : COLUMN_MIN_WIDTH[second.size];
+    if (room < minCell + 2)
+        return 'stacked';
+    const stackedRows = listGeometry(second.itemCount, available, second.size).rows;
+    const sideRows = listGeometry(second.itemCount, room, second.size).rows;
+    const rowHeight = second.height / Math.max(1, stackedRows);
+    const sideHeight = Math.max(first.height, sideRows * rowHeight);
+    const stackedHeight = first.height + gap + second.height;
+    return sideHeight <= stackedHeight - PLACEMENT_MIN_SAVING ? 'side' : 'stacked';
+}
+/** Props box columns: two, filled across first, for 4+ props when each column keeps its minimum. */
+export function propsColumns(count, width) {
+    return count >= 4 && width >= 2 * PROPS_MIN_COLUMN_WIDTH + PROPS_COLUMN_GAP ? 2 : 1;
+}

package/dist/native/catalog/tokens.js

@@ -0,0 +1,119 @@
+/**
+ * Catalog-only design tokens — the visual system of the catalog interface itself.
+ *
+ * Deliberately independent of any host app's design-system tokens (DS_SEMANTIC / DS_PALETTE /
+ * DS_SPACING): the catalog documents a design system, it does not consume one. Keeping its chrome
+ * on its own tokens means a change to the host app's tokens never restyles the catalog, and this
+ * folder can be copied into another app's repo unchanged.
+ *
+ * Values match the approved Studio Matrix references
+ * (docs/design/2026-10-06-catalog-studio-matrix-*.html), with one deliberate exception:
+ * `textMuted` stays #666666 because the references' #777777 fails WCAG AA contrast.
+ */
+export const CATALOG_TYPE = {
+    xs: 10,
+    tableHeader: 11,
+    sm: 12,
+    panelHeading: 13,
+    md: 14,
+    lg: 16,
+    brand: 17,
+    xl: 20,
+    '2xl': 24,
+    pageTitle: 28,
+    '3xl': 32,
+    '4xl': 40,
+};
+export const CATALOG_SPACE = {
+    xs: 4,
+    sm: 8,
+    md: 12,
+    lg: 16,
+    xl: 24,
+    '2xl': 32,
+    '3xl': 40,
+};
+export const CATALOG_RADIUS = {
+    sm: 8,
+    control: 9,
+    md: 12,
+    card: 14,
+};
+/** Exact chrome measurements from the approved references that are not spacing-scale steps. */
+export const CATALOG_LAYOUT = {
+    sidebarWidth: 264,
+    sidebarPaddingTop: 24,
+    sidebarPaddingX: 18,
+    mainPaddingTop: 28,
+    mainPaddingX: 32,
+    controlSize: 44,
+    focusRingWidth: 3,
+    navItemPaddingY: 8,
+    navItemPaddingX: 10,
+    panelPadding: 20,
+    factPaddingY: 9,
+    blockLabelGap: 14,
+    blockGap: 28,
+    /** Sidebar logo header (design `docs/design/2026-10-08-ds-viewer-sidebar-logo-approved.html`,
+     *  "C · Adaptive", approved 2026-10-08) — see `native/catalog/logoLayout.ts`. */
+    logoMark: 32,
+    logoWordmarkHeight: 28,
+    logoCaptionGap: 6,
+};
+/** Max width of the main content column. */
+export const CATALOG_MAX_CONTENT_WIDTH = 1200;
+/** When to reach for each catalog-chrome type size. Rendered in the framework catalog's Type
+ *  Scale page. */
+export const CATALOG_TYPE_USE = {
+    xs: 'Sidebar group labels (uppercase); a prop\'s type annotation.',
+    tableHeader: 'Grid column headers and list cell captions (uppercase).',
+    sm: 'Breadcrumb, catalog caption, block labels, prop names and descriptions.',
+    panelHeading: 'Reference-panel headings: Guidance, Quick reference, Props (uppercase).',
+    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.',
+    pageTitle: 'The selected page\'s title.',
+    '3xl': 'Reserved — no current consumer.',
+    '4xl': 'Reserved — no current consumer.',
+};
+/** When to reach for each catalog-chrome spacing step. Rendered in the framework catalog's
+ *  Spacing page. */
+export const CATALOG_SPACE_USE = {
+    xs: 'Tight gap — e.g. between a token\'s rendered value and its use-note.',
+    sm: 'Small gap — below the filter field; between a preview frame\'s label and its demo.',
+    md: 'Medium gap — between a card\'s contents; token-row divider padding.',
+    lg: 'Grid and list cell padding (16px); row gap in scale galleries.',
+    xl: 'Preview-card padding; gap between preview frames.',
+    '2xl': 'Gap between the reference panel\'s Guidance and Quick reference columns.',
+    '3xl': 'Bottom padding of the main column.',
+};
+export const CATALOG_COLOR = {
+    text: '#181818',
+    // #666666, not the references' #777777: #777 is 4.14–4.48:1 on this file's surfaces (WCAG AA
+    // needs 4.5:1); #666 is 5.3–5.7:1.
+    textMuted: '#666666',
+    /** Dividers inside grids, lists, props tables, token rows. */
+    border: '#e4e4e4',
+    /** Sidebar edge, reference card, filter field. */
+    borderHairline: '#dddddd',
+    /** Grid, list, and preview cards; pager buttons. */
+    borderStrong: '#d7d7d7',
+    /** Quick-reference row dividers. */
+    borderSubtle: '#eeeeee',
+    surface: '#ffffff',
+    /** Table headers, row headers, cell captions, filter field. */
+    surfaceMuted: '#fafafa',
+    /** Hover and pressed feedback on nav rows and buttons. */
+    surfacePressed: '#f1f3f8',
+    pageBackground: '#f6f6f4',
+    chip: '#eeeeee',
+    /** Active nav label, prop types, scale bars. */
+    accent: '#174dc6',
+    /** Active nav row background. */
+    accentSubtle: '#e9efff',
+    /** 3px keyboard focus ring on every catalog control. */
+    focusRing: '#c9d7ff',
+    code: 'Menlo',
+};

package/dist/native/catalog/types.js

@@ -0,0 +1 @@
+export {};

package/native/catalog/ComparisonGrid.tsx

@@ -1,7 +1,7 @@
 import React from 'react';
 import { View, Text, ScrollView, StyleSheet } from 'react-native';
 import { CATALOG_COLOR, CATALOG_RADIUS, CATALOG_TYPE } from './tokens';
-import { COLUMN_MIN_WIDTH, MATRIX_LAYOUT, cellKey, gridWidthBounds, indexCells, validateComparison } from './comparison';
+import { COLUMN_MIN_WIDTH, MATRIX_LAYOUT, axisItems, cellKey, gridWidthBounds, indexCells, validateComparison } from './comparison';
 import type { ComparisonDef, SpecimenSize } from './types';
 
 /**
@@ -14,7 +14,9 @@ export function ComparisonGrid({ def, size, sectionId }: { def: ComparisonDef; s
     for (const issue of validateComparison({ ...def, size })) console.warn(`[Catalog] ${sectionId}: ${issue}`);
   }
   const cells = indexCells(def);
-  const bounds = gridWidthBounds(def.columns.length, size);
+  const rows = axisItems(def.rows);
+  const columns = axisItems(def.columns);
+  const bounds = gridWidthBounds(columns.length, size);
   const column = {
     flexGrow: 1,
     flexShrink: 1,
@@ -22,7 +24,7 @@ export function ComparisonGrid({ def, size, sectionId }: { def: ComparisonDef; s
     minWidth: COLUMN_MIN_WIDTH[size],
     maxWidth: MATRIX_LAYOUT.columnMaxWidth,
   };
-  const lastColumn = def.columns.length - 1;
+  const lastColumn = columns.length - 1;
 
   return (
     <ScrollView horizontal style={styles.scroller} contentContainerStyle={styles.scrollContent}>
@@ -35,18 +37,18 @@ export function ComparisonGrid({ def, size, sectionId }: { def: ComparisonDef; s
           <View role="columnheader" style={[styles.cell, styles.rowHeader, styles.headerCell]}>
             <Text style={styles.headerText}>{def.rowLabel}</Text>
           </View>
-          {def.columns.map((c, ci) => (
+          {columns.map((c, ci) => (
             <View key={c.key} role="columnheader" style={[styles.cell, column, styles.headerCell, ci === lastColumn && styles.lastColumn]}>
               <Text style={styles.headerText}>{c.label}</Text>
             </View>
           ))}
         </View>
-        {def.rows.map((row, ri) => (
-          <View key={row.key} role="row" style={[styles.row, ri === def.rows.length - 1 && styles.lastRow]}>
+        {rows.map((row, ri) => (
+          <View key={row.key} role="row" style={[styles.row, ri === rows.length - 1 && styles.lastRow]}>
             <View role="rowheader" style={[styles.cell, styles.rowHeader, styles.bodyRow]}>
               <Text style={styles.rowHeaderText}>{row.label}</Text>
             </View>
-            {def.columns.map((c, ci) => {
+            {columns.map((c, ci) => {
               const cell = cells.get(cellKey(row.key, c.key));
               return (
                 <View key={c.key} role="cell" style={[styles.cell, column, styles.bodyRow, styles.specimenCell, ci === lastColumn && styles.lastColumn]}>

package/native/catalog/SpacingScaleGallery.tsx

@@ -8,7 +8,7 @@ import { CATALOG_TYPE, CATALOG_COLOR, CATALOG_SPACE, CATALOG_RADIUS } from './to
  * framework's own, and any host app's). Generic over the step-name type so it works for any scale
  * (the host app's `DS_SPACING`, this framework's own `CATALOG_SPACE`, or a third-party one).
  */
-export function SpacingScaleGallery<TStep extends string>({
+export function SpacingScaleGallery<TStep extends string | number>({
   steps,
   values,
   useNotes,

package/native/catalog/catalogNavigation.ts

@@ -3,7 +3,7 @@
  * runner. CatalogShell, CatalogSidebar, and SectionBlock all derive page order from here, so the
  * sidebar order, previous/next order, and fragment fallback can never drift apart.
  */
-import type { NavGroup } from './types';
+import type { NavGroup } from './types.ts';
 
 /** THE canonical within-group ordering of section ids. */
 export function sortIds<TId extends string>(ids: readonly TId[]): TId[] {

package/native/catalog/comparison.ts

@@ -8,7 +8,8 @@
  * It also decides whether two blocks sit side by side (choosePlacement) and how many columns the
  * Props box uses (propsColumns). ComparisonGrid, ComparisonGroups, and ComparisonList render it.
  */
-import type { ComparisonDef, PreviewWidths, SectionDef, SpecimenSize, VariantSlot } from './types';
+import type { ComparisonAxisItem, ComparisonDef, GridAxis, PreviewWidths, SectionDef, SpecimenSize, VariantSlot } from './types.ts';
+import type React from 'react';
 
 /** Approved geometry. `cellPadding` equals CATALOG_SPACE.lg (asserted in tests). The laptop
  *  content width is a 1280px viewport minus the 264px sidebar and 32px side padding. */
@@ -35,6 +36,61 @@ export const PROPS_COLUMN_GAP = 32;
 /** Smallest column or cell width per specimen size. Wide specimens are fixed at phone width. */
 export const COLUMN_MIN_WIDTH: Record<SpecimenSize, number> = { compact: 160, regular: 240, wide: 402 };
 
+/** `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
+ *  predicate sidesteps that (never caught before Task 4: this file had never been typechecked by
+ *  `tsc` until `cli/doctor.ts`'s import pulled it into the root `tsconfig.json`'s program). */
+function isBoundAxis(axis: GridAxis): axis is { prop: string; items: readonly ComparisonAxisItem[] } {
+  return !Array.isArray(axis);
+}
+
+/** A `GridAxis`'s own items, whether it's a plain array or bound to a prop — every reader of
+ *  `ComparisonDef.rows`/`columns` goes through this (never `Array.isArray` directly), so a future
+ *  third axis shape only needs to change this one function. */
+export function axisItems(axis: GridAxis): ComparisonAxisItem[] {
+  return isBoundAxis(axis) ? [...axis.items] : [...axis];
+}
+
+/** The prop name a `GridAxis` is bound to, or undefined for a plain, unbound axis. */
+export function axisProp(axis: GridAxis): string | undefined {
+  return isBoundAxis(axis) ? axis.prop : undefined;
+}
+
+/**
+ * Shared page-authoring helper (design §1 "Page shape", §4 "Binding examples to props"). Every
+ * grid comparison in the starter kit builds its `ComparisonDef` with this instead of its own local
+ * copy, so `cli/staticPage.ts`'s static reader has exactly one call shape to recognize anywhere a
+ * page's `comparison` field is produced by a function call rather than written as a plain object
+ * literal. `rows`/`columns` accept either a plain item array (unbound) or `{ prop, items }` (bound)
+ * — the cell grid itself is unaffected either way, since cells are always keyed by each axis's own
+ * items regardless of whether that axis names a prop. Lives here, beside `axisItems`/`axisProp`,
+ * rather than in its own `grid.ts` — every other file in this module has only *type-only* relative
+ * imports; a bare, no-extension value import would be the first of its kind in `native/catalog`.
+ *
+ * Each cell is a real instance with exactly the props its row and column name. Never build these by
+ * multiplying `variants` with `states` — those are pre-rendered nodes and cannot be combined.
+ */
+export function grid(
+  rowLabel: string,
+  columnLabel: string,
+  rows: GridAxis,
+  columns: GridAxis,
+  cell: (row: string, column: string) => React.ReactNode,
+  size?: SpecimenSize,
+): ComparisonDef {
+  const rowItems = axisItems(rows);
+  const columnItems = axisItems(columns);
+  return {
+    rowLabel,
+    columnLabel,
+    rows,
+    columns,
+    cells: rowItems.flatMap((row) => columnItems.map((column) => ({ rowKey: row.key, columnKey: column.key, node: cell(row.key, column.key) }))),
+    size,
+  };
+}
+
 /** How many grid columns fit beside the row header on a 1280px laptop without scrolling. */
 export function gridColumnLimit(size: SpecimenSize): number {
   return Math.floor((MATRIX_LAYOUT.laptopContentWidth - MATRIX_LAYOUT.rowHeaderWidth) / COLUMN_MIN_WIDTH[size]);
@@ -94,17 +150,19 @@ export function indexCells(def: ComparisonDef): Map<string, ComparisonDef['cells
 /** Human-readable problems in a stable order: axis duplicates, column fit, each cell in
  *  declaration order, then missing coordinates in row-major order. Empty when valid. */
 export function validateComparison(def: ComparisonDef): string[] {
-  if (def.rows.length === 0 || def.columns.length === 0) {
+  const rowItems = axisItems(def.rows);
+  const columnItems = axisItems(def.columns);
+  if (rowItems.length === 0 || columnItems.length === 0) {
     return ['Comparison needs at least one row and one column.'];
   }
   const issues: string[] = [];
   const rowKeys = new Set<string>();
-  for (const row of def.rows) {
+  for (const row of rowItems) {
     if (rowKeys.has(row.key)) issues.push(`Duplicate row key "${row.key}".`);
     rowKeys.add(row.key);
   }
   const columnKeys = new Set<string>();
-  for (const column of def.columns) {
+  for (const column of columnItems) {
     if (columnKeys.has(column.key)) issues.push(`Duplicate column key "${column.key}".`);
     columnKeys.add(column.key);
   }
@@ -149,7 +207,7 @@ export function validateComparison(def: ComparisonDef): string[] {
 export function remainingStates(states: VariantSlot | undefined, comparison: ComparisonDef | undefined): VariantSlot | undefined {
   if (!states) return undefined;
   if (!comparison) return states;
-  const covered = new Set([...comparison.rows.map((row) => row.key), ...comparison.columns.map((column) => column.key)]);
+  const covered = new Set([...axisItems(comparison.rows).map((row) => row.key), ...axisItems(comparison.columns).map((column) => column.key)]);
   const items = states.items.filter((item) => !covered.has(item.key));
   return items.length > 0 ? { ...states, items } : undefined;
 }

package/native/catalog/index.ts

@@ -17,6 +17,7 @@ export { CatalogSidebar } from './CatalogSidebar';
 export { CatalogSearchInput } from './CatalogSearchInput';
 export { SectionBlock } from './SectionBlock';
 export { ComparisonGrid } from './ComparisonGrid';
+export { grid, axisItems, axisProp } from './comparison';
 export { ComparisonGroups } from './ComparisonGroups';
 export { ComparisonList } from './ComparisonList';
 export { ReferenceDetails } from './ReferenceDetails';
@@ -32,7 +33,7 @@ export { buildComponentManifest } from './manifest';
 export type { ComponentManifestEntry, ManifestExample } from './manifest';
 export { defineCatalogPage, buildCatalogSections } from './pageApi';
 export type { CatalogPage, CatalogPageInput, GeneratedComponent, GeneratedPropRecord } from './pageApi';
-export type { PropDef, SectionDef, NavGroup, SpecimenSize, ComparisonDef, ComparisonCell, ComparisonAxisItem, PreviewWidths } from './types';
+export type { PropDef, SectionDef, NavGroup, SpecimenSize, ComparisonDef, ComparisonCell, ComparisonAxisItem, GridAxis, PreviewWidths } from './types';
 export type { ListGroup, ListItem } from './comparison';
 export {
   CATALOG_TYPE,

package/native/catalog/pageApi.ts

@@ -77,7 +77,7 @@ function mergePropNotes(component: GeneratedComponent, propNotes: Record<string,
   return [...own, ...inherited];
 }
 
-function orderGroups(groupIds: Map<string, string[]>, groupOrder: string[] | undefined): { label: string; ids: string[] }[] {
+function orderGroups<TId extends string>(groupIds: Map<string, TId[]>, groupOrder: string[] | undefined): NavGroup<TId>[] {
   const listed = groupOrder ?? [];
   const labels = [...groupIds.keys()];
   const ordered = [...listed.filter((label) => groupIds.has(label)), ...labels.filter((label) => !listed.includes(label)).sort()];
@@ -103,7 +103,16 @@ export function buildCatalogSections<TId extends string>(
   const groupIds = new Map<string, TId[]>();
   const addToGroup = (group: string, id: TId) => groupIds.set(group, [...(groupIds.get(group) ?? []), id]);
 
+  // Design §4 "duplicate-page-id" rule's viewer-side equivalent — this is the one place in the
+  // whole viewer that already resolves every page's id to build sections/groups, so it costs
+  // nothing extra to also notice two pages claiming the same one (`sectionsById` in
+  // `CatalogShell.tsx` would otherwise just let the last one silently win).
+  const seenIds = new Set<TId>();
   const sections: SectionDef<TId>[] = pages.map((page) => {
+    if ((globalThis as { __DEV__?: boolean }).__DEV__) {
+      if (seenIds.has(page.id)) console.warn(`[Catalog] Page id "${page.id}" is used by more than one page; only the last one will show. Give one of them its own "id".`);
+      seenIds.add(page.id);
+    }
     const componentName = page.component ?? page.id;
     const component = componentByName.get(componentName);
     addToGroup(page.group, page.id);
@@ -136,5 +145,5 @@ export function buildCatalogSections<TId extends string>(
     addToGroup('Components', id);
   }
 
-  return { sections, groups: orderGroups(groupIds, groupOrder) as NavGroup<TId>[] };
+  return { sections, groups: orderGroups(groupIds, groupOrder) };
 }

package/native/catalog/types.ts

@@ -65,6 +65,13 @@ export interface ComparisonAxisItem {
   label: string;
 }
 
+/** A grid axis's rows or columns: a plain list of items (today's shape, unchanged), or items bound
+ *  to a real prop so `doctor` can check each item's key against that prop's actual options (design
+ *  §4 "Binding examples to props"). Only a prop typed as a string-literal union can be bound —
+ *  binding any other prop is a `doctor` error, never a runtime check here (the viewer renders a
+ *  bound and an unbound axis identically; see `native/catalog/comparison.ts`'s `axisItems`). */
+export type GridAxis = readonly ComparisonAxisItem[] | { prop: string; items: readonly ComparisonAxisItem[] };
+
 /** One authored row × column specimen. Provide exactly one of `node` (a real instance of the
  *  documented component) or `unavailableReason` (the combination genuinely does not exist). */
 export interface ComparisonCell {
@@ -83,8 +90,8 @@ export interface ComparisonDef {
   rowLabel: string;
   /** Names the column axis (e.g. "State"). */
   columnLabel: string;
-  rows: ComparisonAxisItem[];
-  columns: ComparisonAxisItem[];
+  rows: GridAxis;
+  columns: GridAxis;
   cells: ComparisonCell[];
   /** Defaults to the section's `specimenSize`, then 'regular'. */
   size?: SpecimenSize;
@@ -188,7 +195,3 @@ export interface NavGroup<TId extends string = string> {
   label: string;
   ids: readonly TId[];
 }
-
-/** Canonical within-group ordering — implemented in ./catalogNavigation (pure, unit-tested) and
- *  re-exported here so existing imports keep working. */
-export { sortIds } from './catalogNavigation';