@krapwoo/ds-viewer 0.1.1 → 0.3.0

package/native/catalog/CatalogSidebar.tsx

@@ -1,6 +1,8 @@
 import { useState } from 'react';
-import { View, Text, ScrollView, Pressable, StyleSheet } from 'react-native';
-import { CATALOG_COLOR, CATALOG_LAYOUT, CATALOG_RADIUS, CATALOG_TYPE } from './tokens';
+import { View, Text, ScrollView, Pressable, StyleSheet, Image } from 'react-native';
+import type { ImageSourcePropType, LayoutChangeEvent, NativeSyntheticEvent, ImageLoadEventData } from 'react-native';
+import { CATALOG_COLOR, CATALOG_LAYOUT, CATALOG_RADIUS, CATALOG_SPACE, CATALOG_TYPE } from './tokens';
+import { logoLayout } from './logoLayout';
 import { filterGroups, hashForId } from './catalogNavigation';
 import type { NavGroup } from './types';
 import { CatalogSearchInput } from './CatalogSearchInput';
@@ -48,25 +50,108 @@ function NavItem<TId extends string>({ id, active, onPress }: { id: TId; active:
  */
 export function CatalogSidebar<TId extends string>({
   logo,
+  logoImageSource,
   caption,
   groups,
   active,
   onPress,
 }: {
   logo: string;
+  /** Optional logo image, validated and bundled by `cli/workspace.ts` from the project's `logo`
+   *  config field. Visual spec: docs/design/2026-10-08-ds-viewer-sidebar-logo-approved.html
+   *  ("C · Adaptive", approved 2026-10-08) — a mark (aspect ratio ≤ 2) sits beside the name; a
+   *  wordmark (> 2) replaces the name text, carrying it as its own accessible label instead. */
+  logoImageSource?: ImageSourcePropType;
   caption: string;
   groups: NavGroup<TId>[];
   active: TId | undefined;
   onPress: (id: TId) => void;
 }) {
   const [query, setQuery] = useState('');
+  // A bundled local image (the only kind `cli/workspace.ts` ever produces — see its doc comment
+  // above) already carries its own `width`/`height` on the required module object, both on native
+  // and on react-native-web (confirmed by reading `AssetRegistry`/Metro's asset plugin output) — no
+  // need to wait for a load event for the common case. `onLoad` below is kept only as a fallback for
+  // a source with no static dimensions (e.g. a bare `{ uri }`); the mock prober stops rendering as
+  // soon as either resolves an aspect.
+  const staticSource = typeof logoImageSource === 'object' && logoImageSource !== null && !Array.isArray(logoImageSource)
+    ? (logoImageSource as { width?: number; height?: number })
+    : undefined;
+  const staticAspect = staticSource?.width && staticSource?.height ? staticSource.width / staticSource.height : undefined;
+  const [loadedAspect, setLoadedAspect] = useState<number | undefined>(undefined);
+  const [logoFailed, setLogoFailed] = useState(false);
+  const [nameWrapped, setNameWrapped] = useState(false);
   const filtered = filterGroups(groups, query);
 
+  const logoAspect = staticAspect ?? loadedAspect;
+  const attemptingLogo = Boolean(logoImageSource) && !logoFailed;
+  const header = attemptingLogo ? logoLayout(logoAspect) : 'text';
+
+  // Fallback only (see the comment above `staticSource`) — and native-only in practice: on web,
+  // `ImageLoader.load`'s `onLoad` fires after `HTMLImageElement.decode()` resolves, by which point
+  // Chrome has already nulled the underlying DOM event's `target`, so `native.source` below reads
+  // `undefined` on react-native-web (confirmed empirically — `event.target` reads non-null only
+  // when read synchronously inside `onload`, before any `await`) and this handler never sets
+  // `loadedAspect` there. Native's real `Image` reports `source.{width,height}` on its `onLoad`
+  // nativeEvent instead, which this still reads correctly. Kept rather than removed (Minor finding,
+  // Fable's implementation review) because a non-bundled source with no static dimensions (e.g. a
+  // bare `{ uri }`) is still possible on native, even though `cli/workspace.ts` only ever generates
+  // a bundled `require()` today.
+  const onLogoLoad = (e: NativeSyntheticEvent<ImageLoadEventData>) => {
+    const native = e.nativeEvent as unknown as { source?: { width: number; height: number } };
+    const width = native.source?.width;
+    const height = native.source?.height;
+    if (width && height) setLoadedAspect(width / height);
+  };
+  const onLogoError = () => setLogoFailed(true);
+  // Wrap detection for the "mark" row: the name Text's own measured height, not `onTextLayout`
+  // (react-native-web's `Text` doesn't implement it) and not a character-count heuristic (wraps at
+  // a different length per name). More than one line of `CATALOG_TYPE.brand` means it wrapped.
+  const NAME_LINE_HEIGHT = Math.round(CATALOG_TYPE.brand * 1.3);
+  const onNameLayout = (e: LayoutChangeEvent) => {
+    setNameWrapped(e.nativeEvent.layout.height > NAME_LINE_HEIGHT * 1.5);
+  };
+
   return (
     <View role="navigation" aria-label="Catalog pages" style={styles.sidebar}>
       <ScrollView style={styles.scroll} contentContainerStyle={styles.content} showsVerticalScrollIndicator={false}>
-        <Text style={styles.logo}>{logo}</Text>
-        <Text style={styles.subtitle}>{caption}</Text>
+        <View style={styles.header}>
+          {/* Invisible — exists only so a configured logo's `onLoad`/`onError` can fire at all
+              while `header` is still `'text'` (the aspect isn't known yet). Once `logoAspect`
+              resolves (or the image fails), `header` switches and this prober stops rendering. */}
+          {attemptingLogo && logoAspect === undefined && (
+            <Image source={logoImageSource} style={styles.logoProbe} onLoad={onLogoLoad} onError={onLogoError} />
+          )}
+          {header === 'wordmark' && (
+            <>
+              <Image
+                source={logoImageSource}
+                accessibilityRole="image"
+                accessibilityLabel={logo}
+                resizeMode="contain"
+                style={[styles.wordmark, { width: Math.min(CATALOG_LAYOUT.logoWordmarkHeight * (logoAspect ?? 0), 228) }]}
+                onLoad={onLogoLoad}
+                onError={onLogoError}
+              />
+              <Text style={[styles.subtitle, styles.subtitleAfterWordmark]}>{caption}</Text>
+            </>
+          )}
+          {header === 'mark' && (
+            <View style={[styles.inlineHeader, nameWrapped && styles.inlineHeaderTop]}>
+              <Image source={logoImageSource} resizeMode="contain" style={styles.mark} onLoad={onLogoLoad} onError={onLogoError} />
+              <View style={styles.inlineText}>
+                <Text style={styles.logo} onLayout={onNameLayout}>{logo}</Text>
+                <Text style={styles.subtitle}>{caption}</Text>
+              </View>
+            </View>
+          )}
+          {header === 'text' && (
+            <>
+              <Text style={styles.logo}>{logo}</Text>
+              <Text style={styles.subtitle}>{caption}</Text>
+            </>
+          )}
+        </View>
 
         <CatalogSearchInput value={query} onChangeText={setQuery} placeholder="Filter components…" />
 
@@ -97,8 +182,16 @@ const styles = StyleSheet.create({
     paddingHorizontal: CATALOG_LAYOUT.sidebarPaddingX,
     paddingBottom: CATALOG_LAYOUT.sidebarPaddingTop,
   },
+  header: { marginBottom: 20 },
   logo: { fontSize: CATALOG_TYPE.brand, fontWeight: '800', color: CATALOG_COLOR.text },
-  subtitle: { fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted, marginTop: 2, marginBottom: 20 },
+  subtitle: { fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted, marginTop: 2 },
+  subtitleAfterWordmark: { marginTop: CATALOG_LAYOUT.logoCaptionGap },
+  mark: { width: CATALOG_LAYOUT.logoMark, height: CATALOG_LAYOUT.logoMark },
+  wordmark: { height: CATALOG_LAYOUT.logoWordmarkHeight, alignSelf: 'flex-start' },
+  logoProbe: { position: 'absolute', width: 1, height: 1, opacity: 0 },
+  inlineHeader: { flexDirection: 'row', alignItems: 'center', gap: CATALOG_SPACE.md },
+  inlineHeaderTop: { alignItems: 'flex-start' },
+  inlineText: { flex: 1, minWidth: 0 },
   empty: { fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted, paddingHorizontal: CATALOG_LAYOUT.navItemPaddingX, paddingVertical: 8 },
   groupLabel: {
     fontSize: CATALOG_TYPE.xs,

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/TokenRow.tsx

@@ -4,8 +4,9 @@ import { CATALOG_TYPE, CATALOG_COLOR, CATALOG_SPACE } from './tokens';
 
 /**
  * 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 CatalogExample.tsx
- * and CatalogFrameworkExample.tsx. The row's own content (a spacing bar, a type sample, …) is
+ * 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.
  *
  * Draws a 1px `CATALOG_COLOR.border` bottom divider by default (the same divider PropsTable's rows use) so a stack of TokenRows

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

@@ -6,17 +6,18 @@
  * token group, each with a `render()` that uses that app's real components) and a `NavGroup[]`
  * (how to bucket those sections in the sidebar), then render a single `<CatalogShell />`.
  *
- * See ./CatalogExample.tsx ("Native App DS Template") for a full worked example, built from this
- * template's own components. See ./CatalogFrameworkExample.tsx ("Design System DS Catalog") for a
- * worked example documenting this framework's own eleven pieces — the same catalog shape, one level
- * up. Neither is re-exported here, on purpose: this barrel stays free of any specific component
- * (including its own) so it can be copied into a different app's repo as-is.
+ * A page is written with `defineCatalogPage()` from this barrel and placed next to its component
+ * (or standalone, for tokens/recipes) — see the starter kit under `starter-kit/` for worked
+ * examples, and `kit-host/viewer-pages/` for pages documenting this framework's own pieces. This
+ * barrel itself stays free of any specific component (including its own) so it can be copied into
+ * a different app's repo as-is.
  */
 export { CatalogShell } from './CatalogShell';
 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,8 @@ 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,
   CATALOG_TYPE_USE,

package/native/catalog/logoLayout.ts

@@ -0,0 +1,12 @@
+/** Sidebar logo header layout (design `docs/design/2026-10-08-ds-viewer-sidebar-logo-approved.html`,
+ *  "C · Adaptive", approved 2026-10-08): the configured logo image's own aspect ratio decides the
+ *  layout — no config field chooses it. An unknown or invalid aspect falls back to the safer
+ *  text-only header rather than guessing (`CatalogSidebar.tsx` renders this case until the image's
+ *  `onLoad` reports a real size, and whenever there is no logo, it failed to load, or its file is
+ *  missing). */
+export const LOGO_WORDMARK_MIN_ASPECT = 2;
+
+export function logoLayout(aspect: number | undefined): 'text' | 'mark' | 'wordmark' {
+  if (aspect === undefined || !Number.isFinite(aspect) || aspect <= 0) return 'text';
+  return aspect > LOGO_WORDMARK_MIN_ASPECT ? 'wordmark' : 'mark';
+}

package/native/catalog/pageApi.ts

@@ -59,16 +59,25 @@ export interface GeneratedComponent {
 }
 
 function mergePropNotes(component: GeneratedComponent, propNotes: Record<string, string> | undefined): PropDef[] {
-  return component.props.map((prop) => ({
+  const own = component.props.map((prop) => ({
     name: prop.name,
     type: prop.type,
     required: prop.required,
     default: prop.default,
     desc: propNotes?.[prop.name] ? `${prop.desc} ${propNotes[prop.name]}`.trim() : prop.desc,
   }));
+  // Design §3: props inherited from node_modules (e.g. `extends TextInputProps`) are summarised as
+  // one row per source instead of being listed individually.
+  const inherited = component.inheritedFrom.map((source) => ({
+    name: `${source} props`,
+    type: 'inherited',
+    required: true,
+    desc: `Plus all ${source} props, not listed individually.`,
+  }));
+  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()];
@@ -94,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);
@@ -127,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/tokens.ts

@@ -58,6 +58,11 @@ export const CATALOG_LAYOUT = {
   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,
 } as const;
 
 /** Max width of the main content column. */

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';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krapwoo/ds-viewer",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "license": "MIT",
   "type": "module",
   "description": "A browsable, always-current catalog for an Expo / React Native design system.",
@@ -25,11 +25,11 @@
   },
   "files": [
     "native/catalog",
-    "!native/catalog/CatalogExample.tsx",
-    "!native/catalog/CatalogFrameworkExample.tsx",
     "!native/catalog/**/__tests__",
+    "starter-kit",
     "dist/cli",
     "dist/config",
+    "dist/native",
     "config/index.ts",
     "README.md",
     "LICENSE"
@@ -39,8 +39,8 @@
     "react": "*",
     "react-dom": "*",
     "react-native": "*",
-    "react-native-web": "*",
-    "react-native-safe-area-context": "*"
+    "react-native-safe-area-context": "*",
+    "react-native-web": "*"
   },
   "peerDependenciesMeta": {
     "react-native-safe-area-context": {
@@ -51,12 +51,18 @@
     "typescript": "^6.0.0"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0"
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "puppeteer": "^25.12.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "test": "node --experimental-strip-types --test 'cli/**/*.test.ts' 'config/**/*.test.ts' 'native/catalog/__tests__/*.test.ts'",
     "typecheck": "tsc -p tsconfig.json --noEmit",
+    "kit:dev": "npm run build && cd kit-host && node node_modules/@krapwoo/ds-viewer/dist/cli/main.js dev",
+    "check:catalog": "npm run build && node scripts/checkCatalogConsole.mjs kit-host",
+    "check:doctor": "npm run build && cd kit-host && node node_modules/@krapwoo/ds-viewer/dist/cli/main.js doctor --ci",
+    "check:types": "tsc --noEmit -p kit-host",
     "release": "node scripts/release.mjs"
   }
 }