@krapwoo/ds-viewer 0.4.6 → 0.4.8

package/native/catalog/comparison.ts

@@ -8,7 +8,9 @@
  * 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 { ComparisonAxisItem, ComparisonDef, GridAxis, PreviewWidths, SectionDef, SpecimenSize, TokenSection, VariantSlot } from './types.ts';
+import type {
+  ComparisonAxisItem, ComparisonDef, GridAxis, PreviewWidths, SectionDef, SpecimenAlign, SpecimenSize, SpecimenSurfaceKind, TokenSection, VariantSlot,
+} from './types.ts';
 import type React from 'react';
 
 /** Approved geometry. `cellPadding` equals CATALOG_SPACE.lg (asserted in tests). The laptop
@@ -33,6 +35,14 @@ export const PROPS_MIN_COLUMN_WIDTH = 360;
 /** Gap between the two Props columns (CATALOG_SPACE['2xl']). */
 export const PROPS_COLUMN_GAP = 32;
 
+/** A reference column (Guidance, Quick reference, or Composition) is never narrower than this;
+ *  below it, `referenceColumns` drops to fewer columns. */
+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: Record<SpecimenSize, number> = { compact: 160, regular: 240, wide: 402 };
 
@@ -219,9 +229,18 @@ export function remainingStates(states: VariantSlot | undefined, comparison: Com
 
 export interface ListItem {
   key: string;
+  /** Which authored slot this item came from, so a device frame inside it can address it
+   *  (`overlayViewport.ts`). */
+  slot?: 'variants' | 'states';
   label: string;
   node: unknown;
   fill?: boolean;
+  /** This item's own `specimenSurface` override — see `SpecimenPresentation`. Omit to inherit the
+   *  surface already in effect (the slot's/page's `specimenSurface`, else `'auto'`). */
+  surface?: SpecimenSurfaceKind;
+  /** This item's own cross-axis alignment override — see `SpecimenPresentation.align`. Omit to
+   *  inherit the established default (centered, or stretched when `fill` is set). */
+  align?: SpecimenAlign;
 }
 
 export interface ListGroup {
@@ -249,8 +268,20 @@ export function slotSize<TId extends string>(def: SectionDef<TId>, slot: Variant
   return def.specimenSize ?? (slot.itemsFill ? 'wide' : 'regular');
 }
 
-function slotItems(slot: VariantSlot): ListItem[] {
-  return slot.items.map((item) => ({ key: item.key, label: item.name, node: item.node, fill: item.fill || slot.itemsFill }));
+/** Full-width (filled) examples are block components (cards, banners, rows): narrower than about a
+ *  third of a laptop's content width they stop reading as themselves, so they wrap at most 3
+ *  across unless the page sets its own `maxColumns`. Small centred examples wrap freely. */
+export const FILLED_SLOT_MAX_COLUMNS = 3;
+
+function slotColumnCap(slot: VariantSlot): { maxColumns?: 1 | 2 | 3 | 4 | 5 } {
+  if (slot.maxColumns !== undefined) return { maxColumns: slot.maxColumns };
+  return slot.itemsFill ? { maxColumns: FILLED_SLOT_MAX_COLUMNS } : {};
+}
+
+function slotItems(slot: VariantSlot, from: 'variants' | 'states'): ListItem[] {
+  // 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 }));
 }
 
 /** Preview widths, each capped at phone width. 'full' is kept for catalog chrome and token pages. */
@@ -265,12 +296,14 @@ function previewWidths(requested: PreviewWidths | undefined, fallback: PreviewWi
 function groupStates(variants: VariantSlot, states: VariantSlot): { groups: ListGroup[]; leftovers: VariantSlot | undefined } | undefined {
   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: VariantSlot['items'][number], slot: VariantSlot) => item.fill || slot.itemsFill;
+  // Nullish, not `||` — same reasoning as `slotItems`: an explicit `fill: false` must win over an
+  // inherited `itemsFill: true`.
+  const fill = (item: VariantSlot['items'][number], slot: VariantSlot) => 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) }];
+      ? own.map((s) => ({ key: s.key, slot: 'states' as const, label: s.name, node: s.node, fill: fill(s, states), surface: s.surface, align: s.align }))
+      : [{ key: variant.key, slot: 'variants' as const, label: variant.name, node: variant.node, fill: fill(variant, variants), surface: variant.surface, align: variant.align }];
     return { key: variant.key, label: variant.name, items };
   });
   const rest = states.items.filter((s) => s.group === undefined || !variantKeys.has(s.group));
@@ -317,8 +350,8 @@ export function presentationBlocks<TId extends string>(def: SectionDef<TId>, opt
         kind: 'list',
         title: 'Variants',
         size: slotSize(def, def.variants),
-        items: slotItems(def.variants),
-        ...(def.variants.maxColumns !== undefined ? { maxColumns: def.variants.maxColumns } : {}),
+        items: slotItems(def.variants, 'variants'),
+        ...slotColumnCap(def.variants),
       });
     } else if (def.render) {
       blocks.push({ kind: 'preview', title: 'Preview', widths: previewWidths(def.previewWidths, options.defaultPreviewWidths) });
@@ -331,8 +364,8 @@ export function presentationBlocks<TId extends string>(def: SectionDef<TId>, opt
       kind: 'list',
       title: secondary ? 'Other configurations' : 'States / configurations',
       size: slotSize(def, states),
-      items: slotItems(states),
-      ...(states.maxColumns !== undefined ? { maxColumns: states.maxColumns } : {}),
+      items: slotItems(states, 'states'),
+      ...slotColumnCap(states),
     });
   }
 
@@ -377,3 +410,17 @@ export function choosePlacement({ available, gap, first, second }: { available:
 export function propsColumns(count: number, width: number): 1 | 2 {
   return count >= 4 && width >= 2 * PROPS_MIN_COLUMN_WIDTH + PROPS_COLUMN_GAP ? 2 : 1;
 }
+
+/** How many columns the reference card's Guidance / Quick reference / Composition panel uses at a
+ *  given measured inner card width: 3 only when there is confirmed composition to show as its own
+ *  column AND the card is wide enough for three REFERENCE_MIN_COLUMN_WIDTH columns; 2 when wide
+ *  enough for two (any composition then stays nested under Quick reference, as it always has been);
+ *  1 (stacked, full content in document order — nothing dropped) when even two columns wouldn't
+ *  each keep their minimum. An unmeasured width (`<= 0`) stacks, so the first frame before layout
+ *  settles never overflows. */
+export function referenceColumns(width: number, hasComposition: boolean): 1 | 2 | 3 {
+  const fits = (n: number) => width >= n * REFERENCE_MIN_COLUMN_WIDTH + (n - 1) * REFERENCE_COLUMN_GAP;
+  if (hasComposition && fits(3)) return 3;
+  if (fits(2)) return 2;
+  return 1;
+}

package/native/catalog/deviceFrame.ts

@@ -0,0 +1,14 @@
+/**
+ * The device every `PhoneFrame` shows: a real phone's viewport, in points, at the small end of
+ * current phones (iPhone SE, 3rd generation). Examples lay out at exactly these dimensions; a cell
+ * narrower than the device scales the whole viewport down instead of squeezing its layout. Kept
+ * free of runtime imports so `node --test` can check it.
+ */
+export const DEVICE_FRAME = { name: 'iPhone SE', width: 375, height: 667 } as const;
+
+/** How much to scale the device so it fits `availableWidth` (never enlarged). An unmeasured cell
+ *  (0) renders at full size rather than collapsing. */
+export function deviceFrameScale(availableWidth: number): number {
+  if (!(availableWidth > 0)) return 1;
+  return Math.min(1, availableWidth / DEVICE_FRAME.width);
+}

package/native/catalog/index.ts

@@ -31,6 +31,10 @@ export { TokenSections, TokenGrid, TokenTile } from './TokenLayouts';
 export { DividedStack } from './DividedStack';
 export { Swatch } from './Swatch';
 export { PhoneFrame } from './PhoneFrame';
+export { BoundedOverlayViewport } from './BoundedOverlayViewport';
+export type { BoundedOverlayViewportProps } from './BoundedOverlayViewport';
+export { comparisonCellItemKey } from './overlayViewport';
+export type { OverlayAddress, OverlaySlot } from './overlayViewport';
 export { SpacingScaleGallery } from './SpacingScaleGallery';
 export { TypeScaleGallery } from './TypeScaleGallery';
 export { buildComponentManifest } from './manifest';

package/native/catalog/overlayViewport.ts

@@ -0,0 +1,158 @@
+/**
+ * Pure logic behind `BoundedOverlayViewport.tsx` — no React/React Native imports, so it runs
+ * under Node's test runner the same way `catalogNavigation.ts` does for `CatalogShell`. Addresses
+ * one specific authored specimen, decides whether an instance should frame itself in a bounded
+ * child document or render inline, and (for `CatalogShell`'s own chromeless selected-document
+ * render) resolves an address back to the `node` it names.
+ */
+import type React from 'react';
+import type { SectionDef } from './types.ts';
+
+/** Which block on a page an addressed specimen's `node` lives in — see `findOverlayNode`. */
+export type OverlaySlot = 'variants' | 'states' | 'comparison' | 'preview';
+
+/** Identifies exactly one authored specimen: a page id (`SectionDef.id`), which block it lives
+ *  in, and that item's own key — `VariantExample.key` for `'variants'`/`'states'`, or this
+ *  module's own `comparisonCellItemKey(rowKey, columnKey)` for a `'comparison'` cell (NOT an ad
+ *  hoc `"<rowKey>:<columnKey>"` join — a plain colon join is ambiguous whenever a row or column
+ *  key contains a colon itself). Always an existing author-assigned identifier, never inferred
+ *  from pixels, source strings, or a DOM selector. */
+export interface OverlayAddress {
+  pageId: string;
+  slot: OverlaySlot;
+  itemKey: string;
+}
+
+const OVERLAY_SLOTS: readonly OverlaySlot[] = ['variants', 'states', 'comparison', 'preview'];
+
+/** `encodeURIComponent` leaves `.` untouched (it's an unreserved character), which would let a
+ *  literal `.` inside a segment collide with the `.`-joined encoding below; escape it too so
+ *  splitting on `.` is always safe. `decodeURIComponent` already reverses `%2E` with no special
+ *  casing needed. */
+function encodeSegment(segment: string): string {
+  return encodeURIComponent(segment).replace(/\./g, '%2E');
+}
+
+/** The query param a `BoundedOverlayViewport`'s child document is opened with — distinct from
+ *  `CatalogShell`'s own page-routing hash (`#PageId`), which the child document's URL also keeps
+ *  (see `overlayViewportHrefSuffix`) so the SAME app entry still resolves the right page/providers
+ *  before the viewport component itself ever runs. */
+export const OVERLAY_ADDRESS_PARAM = 'ds-viewer-overlay';
+
+/** `pageId.slot.itemKey`, each segment percent-encoded — one URL-safe token for a query value. */
+export function encodeOverlayAddress(address: OverlayAddress): string {
+  return [address.pageId, address.slot, address.itemKey].map(encodeSegment).join('.');
+}
+
+/** The inverse of `encodeOverlayAddress` — `undefined` for anything that isn't exactly three
+ *  non-empty segments with a recognized slot: the same "malformed means absent" recovery
+ *  `catalogNavigation.ts`'s `idFromHash` uses for an unknown page fragment, rather than guessing
+ *  at a partial or corrupted address. */
+export function decodeOverlayAddress(value: string): OverlayAddress | undefined {
+  const parts = value.split('.');
+  if (parts.length !== 3) return undefined;
+  let decoded: string[];
+  try {
+    decoded = parts.map((part) => decodeURIComponent(part));
+  } catch {
+    return undefined;
+  }
+  const [pageId, slot, itemKey] = decoded;
+  if (!pageId || !itemKey) return undefined;
+  if (!OVERLAY_SLOTS.includes(slot as OverlaySlot)) return undefined;
+  return { pageId, slot: slot as OverlaySlot, itemKey };
+}
+
+/** Reads `OVERLAY_ADDRESS_PARAM` out of a URL search string (e.g. `window.location.search`);
+ *  `undefined` when the param is absent or its value doesn't decode. A trailing `#fragment` is
+ *  dropped first — `URLSearchParams` has no notion of a URL fragment, so without this a caller
+ *  that (like `overlayViewportHrefSuffix`'s own combined query+hash string) passes one along
+ *  would see it swallowed into the last param's value instead of ignored. */
+export function overlayAddressFromSearch(search: string): OverlayAddress | undefined {
+  const raw = new URLSearchParams(search.split('#')[0]).get(OVERLAY_ADDRESS_PARAM);
+  return raw ? decodeOverlayAddress(raw) : undefined;
+}
+
+export function overlayAddressesEqual(a: OverlayAddress, b: OverlayAddress): boolean {
+  return a.pageId === b.pageId && a.slot === b.slot && a.itemKey === b.itemKey;
+}
+
+/** The query + hash suffix that boots the SAME app entry directly into this address's
+ *  selected-document mode: the overlay param (so the `BoundedOverlayViewport` instance that
+ *  matches this address renders its children inline instead of framing itself again) plus the
+ *  page's own routing hash (so `CatalogShell`'s existing hash-based routing still resolves the
+ *  right `SectionDef`/providers before `findOverlayNode` narrows further). */
+export function overlayViewportHrefSuffix(address: OverlayAddress): string {
+  return `?${OVERLAY_ADDRESS_PARAM}=${encodeURIComponent(encodeOverlayAddress(address))}#${encodeURIComponent(address.pageId)}`;
+}
+
+/** `'inline'`: render the wrapped demo directly, no frame — either this isn't a web runtime (no
+ *  same-origin child-document mechanism to offer; see `BoundedOverlayViewport`'s own doc comment)
+ *  or `currentSearch` already names this exact address, meaning this instance IS the selected
+ *  child document's own addressed specimen and must not frame itself again (recursion guard).
+ *  `'frame'`: open `href` — the current pathname plus this address's query+hash — in a bounded
+ *  child document. */
+export type OverlayViewportDecision = { mode: 'inline' } | { mode: 'frame'; href: string };
+
+export function resolveOverlayViewport(args: {
+  address: OverlayAddress;
+  isWeb: boolean;
+  /** The hosting document's current `location.search` (e.g. `window.location.search`). */
+  currentSearch: string;
+  /** The hosting document's current `location.pathname` — same pathname the child document loads,
+   *  since this viewer is a single-page app whose page lives in the hash, not the path. */
+  pathname: string;
+}): OverlayViewportDecision {
+  if (!args.isWeb) return { mode: 'inline' };
+  const current = overlayAddressFromSearch(args.currentSearch);
+  if (current && overlayAddressesEqual(current, args.address)) return { mode: 'inline' };
+  return { mode: 'frame', href: `${args.pathname}${overlayViewportHrefSuffix(args.address)}` };
+}
+
+/** The authored `node` an `OverlayAddress` points at, or `undefined` for a stale/unknown address
+ *  (a removed example, a renamed key, a typo) — `CatalogShell`'s chromeless selected-document
+ *  render shows an honest "unavailable" recovery rather than rendering nothing silently. */
+export function findOverlayNode(sections: readonly SectionDef<string>[], address: OverlayAddress): React.ReactNode | undefined {
+  const def = sections.find((section) => section.id === address.pageId);
+  if (!def) return undefined;
+  if (address.slot === 'variants') return def.variants?.items.find((item) => item.key === address.itemKey)?.node;
+  if (address.slot === 'states') return def.states?.items.find((item) => item.key === address.itemKey)?.node;
+  // A `render()` page's preview (one per page; `itemKey` is always 'preview').
+  if (address.slot === 'preview') return def.render?.();
+  // Matched by recomputing each cell's own canonical key, never by splitting `address.itemKey` —
+  // a row/column key may itself contain any delimiter this module could pick.
+  return def.comparison?.cells.find((cell) => comparisonCellItemKey(cell.rowKey, cell.columnKey) === address.itemKey)?.node;
+}
+
+/** The canonical, unambiguous `itemKey` for one comparison cell's row+column — this module's own
+ *  counterpart to `comparison.ts`'s `cellKey` (not imported from there: a VALUE import between two
+ *  pure `.ts` logic modules here can't carry the `.ts` extension that both Node's direct test run
+ *  and `kit-host`'s bundler-mode typechecker require/reject at once — `import type` is exempt
+ *  since it is fully erased, which is why `./types.ts` above is fine). Exported so a `.tsx` call
+ *  site building a `'comparison'` `OverlayAddress` constructs the exact same key this module looks
+ *  it up by — a plain `"${rowKey}:${columnKey}"` join is ambiguous whenever a row or column key
+ *  contains a colon itself. */
+export function comparisonCellItemKey(rowKey: string, columnKey: string): string {
+  return `${rowKey}${columnKey}`;
+}
+
+/** Usable CSS pixel dimensions for a bounded overlay viewport: finite and strictly positive.
+ *  `NaN`/`Infinity`/zero/negative (a measurement that hasn't settled yet, a miscomputed layout
+ *  value, an author typo) must never reach `BoundedOverlayViewport`'s iframe — an iframe sized to
+ *  a meaningless bound is worse than no iframe, since it still renders (and can still mount the
+ *  wrapped demo's overlay) at some browser-decided fallback size instead of honestly reporting
+ *  unavailable. */
+export function isFiniteOverlaySize(width: number, height: number): boolean {
+  return Number.isFinite(width) && width > 0 && Number.isFinite(height) && height > 0;
+}
+
+/** The framed stage's own box dimensions. `height` is exact — the production overlay's full
+ *  usable height is never renegotiated by its owner. `width` is only a MAXIMUM: `'100%'` lets the
+ *  stage fill and shrink to whatever its real owning specimen cell actually gives it, capped at
+ *  `width` when the owner has at least that much room. A fixed pixel width here previously let the
+ *  stage overflow a narrower owner (e.g. a 240px comparison cell at a narrow browser width) while
+ *  that owner's own `overflow: hidden` silently clipped the excess — a passing-looking but false
+ *  containment, not the honest unavailable/shrink this design requires. */
+export function overlayStageDimensions(width: number, height: number): { width: '100%'; maxWidth: number; height: number } {
+  return { width: '100%', maxWidth: width, height };
+}

package/native/catalog/pageApi.ts

@@ -31,8 +31,12 @@ export interface CatalogPageInput<TId extends string = string> {
   specimenSize?: SpecimenSize;
   specimenSurface?: SpecimenSurfaceKind;
   previewWidths?: PreviewWidths;
+  /** See `SectionDef.previewLayout`. */
+  previewLayout?: 'frames' | 'table';
   hide?: SectionDef['hide'];
   composedOf?: ComposedOfEntry[];
+  /** See `SectionDef.intentionalStaticPreview`. */
+  intentionalStaticPreview?: { reason: string };
   /** Export name this page documents; defaults to `id` for component pages. */
   component?: string;
   /** Sidebar group label. */
@@ -168,8 +172,10 @@ export function buildCatalogSections<TId extends string>(
       specimenSize: page.specimenSize,
       specimenSurface: page.specimenSurface,
       previewWidths: page.previewWidths,
+      previewLayout: page.previewLayout,
       hide: component ? page.hide : { ...page.hide, props: true },
       composedOf: page.composedOf,
+      intentionalStaticPreview: page.intentionalStaticPreview,
     };
   });
 

package/native/catalog/specimenSurfaceStyle.ts

@@ -1,4 +1,4 @@
-import type { SpecimenSurfaceKind } from './types.ts';
+import type { SpecimenAlign, SpecimenSurfaceKind } from './types.ts';
 
 /**
  * The example wrapper's width policy inside a cell, kept free of any `react-native` import so
@@ -16,6 +16,129 @@ export const SPECIMEN_SURFACE_WIDTH_STYLE = {
   alignSelf: 'stretch',
 } as const;
 
+/**
+ * Centers a non-`fill` specimen horizontally inside its (now full-width) wrapper — unchanged,
+ * bounded (non-`fill`) specimens stay centered by default. See `SpecimenSurface.tsx`'s
+ * `SpecimenContent`, the one place every presentation shape (list/grouped/grid) wraps a specimen
+ * before handing it to its cell.
+ */
+export const SPECIMEN_CONTENT_CENTER_STYLE = {
+  ...SPECIMEN_SURFACE_WIDTH_STYLE,
+  alignItems: 'center',
+} as const;
+
+/**
+ * A `fill` specimen's content stretches instead of centering: `alignItems: 'center'` on this
+ * wrapper previously applied to `fill` specimens too, which collapses an auto-sized, already
+ * full-width child (e.g. NextTrainInfo's row) down to its own intrinsic content width instead of
+ * leaving it at the wrapper's full width — `alignItems: 'center'` resolves a child with no definite
+ * cross-axis size to its content size, the opposite of what `fill` promises. A `fill` specimen
+ * whose own size is capped below the wrapper's width (e.g. a phone-frame preview's `maxWidth`) is
+ * expected to center itself (`alignSelf: 'center'`, see `PhoneFrame.tsx`) rather than lean on this
+ * wrapper's `alignItems` — the same way `alignItems: 'stretch'` already behaves like `flex-start`,
+ * not an actual stretch, for any child with a definite cross-axis size (a set width/maxWidth) per
+ * the flexbox spec. An explicit `align` (see `specimenContentAlignItems`) still overrides this.
+ */
+export const SPECIMEN_CONTENT_FILL_STYLE = {
+  ...SPECIMEN_SURFACE_WIDTH_STYLE,
+  alignItems: 'stretch',
+} as const;
+
+const ALIGN_ITEMS_BY_SPECIMEN_ALIGN: Record<SpecimenAlign, 'flex-start' | 'center' | 'flex-end'> = {
+  start: 'flex-start',
+  center: 'center',
+  end: 'flex-end',
+};
+
+/** The `SpecimenContent` wrapper's `alignItems`: an explicit `align` (`SpecimenPresentation.align`)
+ *  always wins over `fill`. Omitted, `fill` decides the established default — `'stretch'` (preserve
+ *  a full-width auto-sized child) when true, `'center'` (unchanged) otherwise. */
+export function specimenContentAlignItems(fill: boolean | undefined, align: SpecimenAlign | undefined): 'flex-start' | 'center' | 'flex-end' | 'stretch' {
+  if (align !== undefined) return ALIGN_ITEMS_BY_SPECIMEN_ALIGN[align];
+  return fill ? 'stretch' : 'center';
+}
+
+/** A non-fill specimen's horizontal position, as `justifyContent` on `SpecimenContent`'s own row
+ *  main axis rather than `alignItems` on a column: `alignItems` only sets a child's *default*
+ *  `alignSelf`, which the specimen's own root can — and does, e.g. Badge's `alignSelf:
+ *  'flex-start'` — override outright, leaning the whole grid left regardless of the wrapper's
+ *  intent. `justifyContent` positions along the main axis directly and cannot be overridden by a
+ *  child's `alignSelf`, which only ever targets the cross axis (vertical, on a row). Reuses
+ *  `ALIGN_ITEMS_BY_SPECIMEN_ALIGN`'s mapping — `flex-start`/`center`/`flex-end` are valid values
+ *  for both `alignItems` and `justifyContent`. */
+export function specimenContentJustifyContent(align: SpecimenAlign | undefined): 'flex-start' | 'center' | 'flex-end' {
+  return align !== undefined ? ALIGN_ITEMS_BY_SPECIMEN_ALIGN[align] : 'center';
+}
+
+/** The non-fill `SpecimenContent` wrapper's own style: still full-width (`SPECIMEN_SURFACE_WIDTH_STYLE`,
+ *  so a percentage-width child keeps resolving against it), but a row main axis so
+ *  `justifyContent` — not `alignItems` — decides horizontal placement (see
+ *  `specimenContentJustifyContent`). Vertical cross-axis stays centered, as it already did. Only
+ *  for non-`fill` specimens; `fill` keeps the existing column + `alignItems` stretch behavior
+ *  (`specimenContentAlignItems`), unchanged. */
+export function specimenContentBoundedStyle(align: SpecimenAlign | undefined) {
+  return {
+    ...SPECIMEN_SURFACE_WIDTH_STYLE,
+    flexDirection: 'row' as const,
+    justifyContent: specimenContentJustifyContent(align),
+    alignItems: 'center' as const,
+  };
+}
+
 /** Each example's cell turns gray only when its example would vanish against white (see
  *  `specimenFill.ts`). A page can force a fill with `specimenSurface`. */
 export const DEFAULT_SPECIMEN_SURFACE: SpecimenSurfaceKind = 'auto';
+
+/** A `fill` example stretches to its cell, but one with its own fixed width (a 160-point skeleton
+ *  bar) stays that width; it should then sit in the middle of the cell, not against its leading
+ *  edge. True when the measured example is narrower than its wrapper (by more than rounding). */
+export function shouldCenterFilledContent(contentWidth: number, wrapperWidth: number): boolean {
+  if (!(contentWidth > 0) || !(wrapperWidth > 0)) return false;
+  return contentWidth < wrapperWidth - 1;
+}
+
+/** The width of what's actually visible in an example: from the leftmost to the rightmost painted
+ *  box (text, an icon, anything with a fill), ignoring transparent layout wrappers that may span
+ *  the whole cell. */
+export function paintedExtent(boxes: readonly { left: number; right: number; painted: boolean }[]): number {
+  let left = Infinity;
+  let right = -Infinity;
+  for (const box of boxes) {
+    if (!box.painted || box.right <= box.left) continue;
+    left = Math.min(left, box.left);
+    right = Math.max(right, box.right);
+  }
+  return Number.isFinite(left) ? right - left : 0;
+}
+
+/** True when an example is wider than its cell (beyond rounding): its edges are cut off or touch
+ *  the neighbouring cell, so the page should use a wider `specimenSize`. */
+export function overflowsCell(contentWidth: number, cellWidth: number): boolean {
+  return contentWidth > 0 && cellWidth > 0 && contentWidth > cellWidth + 1;
+}
+
+/** One element of an example as measured in the browser. `clips` is true for a container that
+ *  hides or scrolls its overflow (a scrolling row, a device frame). */
+export interface LayoutBox {
+  left: number;
+  right: number;
+  painted: boolean;
+  clips: boolean;
+  children: LayoutBox[];
+}
+
+/** The boxes a reader can actually see: a clipping container counts as its own box, and what it
+ *  hides or scrolls inside it is skipped. */
+export function visibleBoxes(root: LayoutBox): { left: number; right: number; painted: boolean }[] {
+  const out: { left: number; right: number; painted: boolean }[] = [];
+  const walk = (box: LayoutBox, isRoot: boolean) => {
+    if (!isRoot && box.clips) {
+      out.push({ left: box.left, right: box.right, painted: true });
+      return;
+    }
+    if (!isRoot) out.push({ left: box.left, right: box.right, painted: box.painted });
+    for (const child of box.children) walk(child, false);
+  };
+  walk(root, true);
+  return out;
+}

package/native/catalog/types.ts

@@ -12,21 +12,39 @@ export interface PropDef {
   desc: string;
 }
 
+/** How a specimen's content is cross-axis aligned inside its (already full-width) wrapper —
+ *  `start`/`center`/`end` map to `flex-start`/`center`/`flex-end`. Omit to inherit the established
+ *  default: `center` when `fill` is false/omitted (unchanged), or the wrapper's own full-width
+ *  stretch when `fill` is true — a capped-width `fill` specimen (e.g. a phone-frame preview) that
+ *  still wants centering sets `align: 'center'` explicitly rather than relying on `fill` alone; see
+ *  `specimenContentAlignItems` in `specimenSurfaceStyle.ts`. */
+export type SpecimenAlign = 'start' | 'center' | 'end';
+
+/** Per-specimen presentation, layered under whatever a slot or page already decides: this one
+ *  specimen's own background (`surface`, overriding the slot's/page's `specimenSurface` — omit to
+ *  inherit it), whether its wrapper stretches to the row's full width instead of shrinking to its
+ *  own content width (`fill`, for a single wide-format instance, e.g. a `fullWidth` Button, sitting
+ *  among otherwise compact, centered siblings — independent of a slot's own `itemsFill`, which
+ *  applies to every item uniformly), and how its content cross-axis aligns inside that wrapper
+ *  (`align` — see `SpecimenAlign`). Shared by `VariantExample` (list/grouped items) and
+ *  `ComparisonCell` (grid cells) so the same knobs mean the same thing in every presentation shape
+ *  ds-viewer renders a specimen in; an explicit `surface` here always bypasses `'auto'`'s own fill
+ *  heuristic (`specimenFill.ts`), the same way a slot's/page's own explicit surface already does. */
+export interface SpecimenPresentation {
+  /** @default false */
+  fill?: boolean;
+  surface?: SpecimenSurfaceKind;
+  align?: SpecimenAlign;
+}
+
 /** One individual example inside a variant/state cluster — e.g. one Button instance. */
-export interface VariantExample {
+export interface VariantExample extends SpecimenPresentation {
   /** React key; keep stable and unique within its group. */
   key: string;
   /** Shown as a small caption under this item — the actual variant/state value it demonstrates
    *  (e.g. "Primary", "Icon-only"), not a generic label like "Example 1". */
   name: string;
   node: React.ReactNode;
-  /** Stretch *this item's* wrapper to the row's full width, instead of shrinking to its own content
-   *  width — for a single wide-format instance (e.g. a `fullWidth` Button) sitting among otherwise
-   *  compact, centered siblings in the same slot. Without this, a `fullWidth`/stretch-based prop on
-   *  the instance itself has nothing to stretch into — its wrapper still shrinks to content, so the
-   *  instance renders at its natural size regardless of the prop. Independent of the slot's own
-   *  `itemsFill` (which applies to every item uniformly); this is a per-item override. @default false */
-  fill?: boolean;
   /** Which real prop value(s) this instance demonstrates, e.g. `{ variant: 'primary' }` or
    *  `{ size: 'large', disabled: true }` — mirrors the actual props passed to `node`. Optional and
    *  additive: SectionBlock only cross-checks a section's enum props against this metadata once at
@@ -99,14 +117,13 @@ export interface ComparisonAxisItem {
 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 {
+ *  documented component) or `unavailableReason` (the combination genuinely does not exist). See
+ *  `SpecimenPresentation` for `fill`/`surface`. */
+export interface ComparisonCell extends SpecimenPresentation {
   rowKey: string;
   columnKey: string;
   node?: React.ReactNode;
   unavailableReason?: string;
-  /** Stretch this specimen to the cell width. @default false */
-  fill?: boolean;
 }
 
 /** A grid of two props that combine freely. Every row × column pair is authored — never inferred
@@ -222,6 +239,13 @@ export interface SectionDef<TId extends string = string> {
   /** Widths for this page's `render()` preview, e.g. `[402, 320]` to add a small-phone example.
    *  Defaults to the catalog's default (CatalogShell `defaultPreviewWidths`), else `[402]`. */
   previewWidths?: PreviewWidths;
+  /** Presentation for this page's numeric-width component Preview (guided intelligence,
+   *  "Collapsible Preview table"): `'frames'` (default, unchanged) — one borderless-card frame per
+   *  width, side by side. `'table'` — the widths share one `ComparisonList`-style card, each with
+   *  its own muted caption strip above its live body; still an independent, stateful instance per
+   *  width. Has no effect on a `'full'` preview width (catalog chrome) or a token gallery — those
+   *  always render as `'frames'` regardless of this field. */
+  previewLayout?: 'frames' | 'table';
   /** Remove specific parts of the page — for sections with no meaningful states, props, or
    *  accessibility story (e.g. a framework's own building-block pages). `variants` removes the
    *  first specimen block (grid, Variants list, or Preview); `states` removes the States /
@@ -237,6 +261,12 @@ export interface SectionDef<TId extends string = string> {
    *  Quick reference. See `ComposedOfEntry`. Omit when the component has no meaningful composition
    *  to disclose (most leaf components). */
   composedOf?: ComposedOfEntry[];
+  /** Explicit author declaration (guided intelligence design §3) that this page's examples are
+   *  intentionally static despite the documented component having a controlled state/event pair —
+   *  suppresses `cli/doctor.ts`'s `missing-working-preview` advisory. `reason` is a short, bounded
+   *  sentence explaining why (not free-form prose) — e.g. "Selection is already demonstrated by X's
+   *  working preview." Omit when no such declaration applies; the advisory then runs normally. */
+  intentionalStaticPreview?: { reason: string };
 }
 
 /** A labeled group of section ids in the sidebar (e.g. "Components" vs "Tokens"). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krapwoo/ds-viewer",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "license": "MIT",
   "type": "module",
   "description": "A browsable, always-current catalog for an Expo / React Native design system.",
@@ -65,9 +65,10 @@
     "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",
+    "viewer:dev": "npm run build && cd viewer-host && node node_modules/@krapwoo/ds-viewer/dist/cli/main.js dev",
+    "check:catalog": "npm run build && node scripts/checkCatalogConsole.mjs kit-host && node scripts/checkCatalogConsole.mjs viewer-host",
+    "check:doctor": "npm run build && cd kit-host && node node_modules/@krapwoo/ds-viewer/dist/cli/main.js doctor --ci && cd ../viewer-host && node node_modules/@krapwoo/ds-viewer/dist/cli/main.js doctor --ci",
+    "check:types": "tsc --noEmit -p kit-host && tsc --noEmit -p viewer-host",
     "release": "node scripts/release.mjs"
   }
 }

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

@@ -5,7 +5,7 @@ import { DS_SEMANTIC } from '../../tokens';
 
 export default defineCatalogPage({
   component: 'AnimatedChevron',
-  group: 'Sub-Parts',
+  group: 'Components',
   description: 'A chevron that morphs between down (collapsed) and up (expanded) — flipping vertically in place instead of rotating through a sideways-pointing angle, and instead of swapping icons. The morph Banner\'s own collapsible header uses for its disclosure indicator. Not commonly used on its own; exported for building a custom disclosure/accordion toggle.',
   a11y: 'Purely decorative — no accessibility role of its own. Wrap it in an accessible parent (the way Banner\'s own header Pressable does) if the toggle needs to be announced.',
   variants: {

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

@@ -31,7 +31,7 @@ const AVATAR_COMPARISON = grid(
 
 export default defineCatalogPage({
   component: 'Avatar',
-  group: 'Surfaces',
+  group: 'Components',
   specimenSize: 'compact',
   comparison: AVATAR_COMPARISON,
   description: 'A circular image, or an initials fallback on a solid fill when there\'s no image (or it fails to load).',

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

@@ -51,7 +51,7 @@ const BADGE_COMPARISON = grid(
 
 export default defineCatalogPage({
   component: 'Badge',
-  group: 'Surfaces',
+  group: 'Components',
   specimenSize: 'compact',
   comparison: BADGE_COMPARISON,
   description: 'A small status chip — five semantic variants, with optional leading/trailing icons or icon-only.',

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

@@ -4,7 +4,11 @@ import { Banner } from './Banner';
 
 export default defineCatalogPage({
   component: 'Banner',
-  group: 'Surfaces',
+  group: 'Components',
+  specimenSize: 'regular',
+  composedOf: [
+    { component: 'AnimatedChevron', role: "The expand/collapse chevron in the header of a collapsible banner.", relationship: 'built-in' },
+  ],
   description: 'An inline callout for status/announcements — five semantic variants, optional collapsible body, inline link, and action button.',
   whenToUse: "Persistent and in-flow, describing a standing condition about the screen's content. For a transient, self-contained event notification, use Toast instead.",
   a11y: 'When onPress/action is set the header/button are Pressables; the collapsible header toggles the description with a chevron affordance.',