@krapwoo/ds-viewer 0.4.5 → 0.4.7

package/native/catalog/SectionBlock.tsx

@@ -8,7 +8,7 @@ import { ReferenceDetails } from './ReferenceDetails';
 import { SpecimenSurface } from './SpecimenSurface';
 import { DEFAULT_SPECIMEN_SURFACE } from './specimenSurfaceStyle';
 import { TokenSections } from './TokenLayouts';
-import { choosePlacement, listGeometry, presentationBlocks, type PresentationBlock } from './comparison';
+import { MATRIX_LAYOUT, choosePlacement, listGeometry, presentationBlocks, type PresentationBlock } from './comparison';
 import type { PreviewWidths, SectionDef, SpecimenSurfaceKind } from './types';
 
 // Matches a quoted-string-literal union type, e.g. "'primary' | 'secondary' | 'tertiary'" — anything
@@ -103,11 +103,14 @@ function frameLabel(width: number): string {
 
 /** A component preview: one frame per width (each at most phone width), or full width for catalog
  *  chrome and token galleries. Every frame is its own live instance with its own state. `surface`
- *  is omitted for token galleries, which keep their current, unstaged presentation. */
-function Preview({ render, widths, surface }: { render: () => React.ReactNode; widths: PreviewWidths; surface?: SpecimenSurfaceKind }) {
+ *  is omitted for token galleries, which keep their current, unstaged presentation. `layout: 'table'`
+ *  (only ever set for a numeric-width preview — see `presentationBlocks`) renders `TablePreview`
+ *  instead; omitted/`'frames'` keeps this exact, unchanged presentation. */
+function Preview({ render, widths, surface, layout }: { render: () => React.ReactNode; widths: PreviewWidths; surface?: SpecimenSurfaceKind; layout?: 'table' }) {
   // Token galleries pass no surface: their card stays white.
   const kind = surface ?? 'transparent';
   if (widths === 'full') return <SpecimenSurface surface={kind} style={styles.previewCard}>{render()}</SpecimenSurface>;
+  if (layout === 'table') return <TablePreview render={render} widths={widths} surface={kind} />;
   return (
     <View style={styles.previewCard}>
       <View style={styles.frames}>
@@ -128,6 +131,39 @@ function Preview({ render, widths, surface }: { render: () => React.ReactNode; w
   );
 }
 
+/** `layout: 'table'` presentation for a numeric-width Preview: every width shares ONE
+ *  `ComparisonList`-style card (same caption typography, muted caption strip, border/radius/surface
+ *  tokens) instead of each width getting its own bordered frame-card. Each width keeps its own
+ *  caption strip directly above its own live body, in a single flex-wrapped row — one stable parent
+ *  with keyed cells, so a viewport resize that wraps the row to stacked columns reflows in place
+ *  rather than remounting any demo. A cell's body carries the same `MATRIX_LAYOUT.cellPadding`
+ *  `ComparisonList`'s own cells use; the requested width instead reaches the demo untouched through
+ *  an inner width-qualified viewport nested inside that padded body (capped only by
+ *  `maxWidth: '100%'`, the same cap `Preview`'s own frames already use), so a cell's `flexBasis`
+ *  reserving `width + 2 * cellPadding` leaves the padded body exactly enough room for it, with no
+ *  blank trailing slack. The row's cells share 1px gutters (a `gap` on a bordered backing) for
+ *  dividers, in both the side-by-side and stacked-wrap arrangements. */
+function TablePreview({ render, widths, surface }: { render: () => React.ReactNode; widths: readonly number[]; surface: SpecimenSurfaceKind }) {
+  return (
+    <View style={styles.tableCard}>
+      <View style={styles.tableRow}>
+        {widths.map((width, i) => (
+          <View key={`${width}-${i}`} style={[styles.tableCell, { flexBasis: width + 2 * MATRIX_LAYOUT.cellPadding }]}>
+            <View style={styles.tableCaption}>
+              <Text style={styles.tableCaptionText}>{frameLabel(width)}</Text>
+            </View>
+            <SpecimenSurface surface={surface} style={styles.tableBody}>
+              <View role="group" aria-label={frameLabel(width)} style={[styles.tableBodyViewport, { width }]}>
+                {render()}
+              </View>
+            </SpecimenSurface>
+          </View>
+        ))}
+      </View>
+    </View>
+  );
+}
+
 function BlockContent<TId extends string>({ block, def, surface }: { block: PresentationBlock; def: SectionDef<TId>; surface: SpecimenSurfaceKind }) {
   switch (block.kind) {
     case 'grid':
@@ -139,7 +175,9 @@ function BlockContent<TId extends string>({ block, def, surface }: { block: Pres
     case 'preview':
       // A token gallery's `preview` block shows full-width raw token data, not a component
       // specimen — it keeps its current, unstaged presentation.
-      return def.render ? <Preview render={def.render} widths={block.widths} surface={def.tokenGallery ? undefined : surface} /> : null;
+      // `Preview`'s own `widths === 'full'` check already excludes a full-width or token-gallery
+      // preview from ever reaching the table layout, regardless of `def.previewLayout`.
+      return def.render ? <Preview render={def.render} widths={block.widths} surface={def.tokenGallery ? undefined : surface} layout={def.previewLayout === 'table' ? 'table' : undefined} /> : null;
     case 'tokenSections':
       return <TokenSections sections={block.sections} columns={block.columns} />;
     default:
@@ -356,5 +394,29 @@ const styles = StyleSheet.create({
     padding: CATALOG_SPACE.xl,
     gap: CATALOG_SPACE.md,
   },
+  // `ComparisonList`'s own card/caption tokens, reused so a 'table' preview reads as the same shared
+  // surface — no outer `previewCard` padding/chrome around it (that card provides its own).
+  tableCard: {
+    backgroundColor: CATALOG_COLOR.surface,
+    borderWidth: 1,
+    borderColor: CATALOG_COLOR.borderStrong,
+    borderRadius: CATALOG_RADIUS.card,
+    overflow: 'hidden',
+  },
+  // 1px gutters between cells: a gap over a bordered backing, so dividers read correctly whether
+  // cells sit side by side or wrap into stacked rows.
+  tableRow: { flexDirection: 'row', flexWrap: 'wrap', gap: 1, backgroundColor: CATALOG_COLOR.border },
+  tableCell: { backgroundColor: CATALOG_COLOR.surface, flexGrow: 1, minWidth: 0, maxWidth: '100%' },
+  tableCaption: {
+    padding: MATRIX_LAYOUT.cellPadding,
+    backgroundColor: CATALOG_COLOR.surfaceMuted,
+    borderBottomWidth: 1,
+    borderBottomColor: CATALOG_COLOR.border,
+  },
+  tableCaptionText: { fontSize: CATALOG_TYPE.tableHeader, fontWeight: '800', letterSpacing: 0.44, color: CATALOG_COLOR.text },
+  // Same cell padding `ComparisonList` uses: the requested width instead reaches the live demo
+  // untouched through `tableBodyViewport`, the inner width-qualified group nested inside this body.
+  tableBody: { padding: MATRIX_LAYOUT.cellPadding, flexGrow: 1, alignItems: 'center', justifyContent: 'flex-start' },
+  tableBodyViewport: { maxWidth: '100%' },
   emptyText: { fontSize: CATALOG_TYPE.sm, fontStyle: 'italic', color: CATALOG_COLOR.textMuted },
 });

package/native/catalog/SpecimenSurface.tsx

@@ -1,9 +1,9 @@
 import React, { useCallback, useEffect, useRef, useState } from 'react';
 import { View, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
 import { CATALOG_COLOR } from './tokens';
-import { DEFAULT_SPECIMEN_SURFACE, SPECIMEN_SURFACE_WIDTH_STYLE } from './specimenSurfaceStyle';
+import { DEFAULT_SPECIMEN_SURFACE, SPECIMEN_SURFACE_WIDTH_STYLE, specimenContentAlignItems, specimenContentBoundedStyle } from './specimenSurfaceStyle';
 import { blendsIntoCell, measurePaintedBoxes } from './specimenFill';
-import type { SpecimenSurfaceKind } from './types';
+import type { SpecimenAlign, SpecimenSurfaceKind } from './types';
 
 type Browser = {
   getComputedStyle?: (element: unknown) => never;
@@ -65,9 +65,22 @@ export function SpecimenSurface({
 }
 
 /** Wraps one example inside its cell: full cell width (so a percentage-width example resolves
- *  against the cell), centered unless the example fills the cell. */
-export function SpecimenContent({ fill, children }: { fill?: boolean; children: React.ReactNode }) {
-  return <View style={fill ? styles.fill : styles.center}>{children}</View>;
+ *  against the cell). `fill` changes whether the example itself also stretches to that width
+ *  (default) or keeps its own content size — a non-`fill` specimen centers by default; a `fill`
+ *  one stretches by default instead, preserving an auto-sized full-width child (see
+ *  `specimenContentAlignItems`). `align` always overrides that default explicitly.
+ *
+ *  A non-`fill` specimen uses a row main axis (`specimenContentBoundedStyle`) so `justifyContent`
+ *  positions it horizontally — a column + `alignItems` left the specimen's own root `alignSelf`
+ *  (e.g. Badge's `alignSelf: 'flex-start'`) free to override that positioning outright, since
+ *  `alignItems` only sets a child's *default* `alignSelf`. `fill` keeps the existing column +
+ *  `alignItems` stretch behavior, unchanged. */
+export function SpecimenContent({ fill, align, children }: { fill?: boolean; align?: SpecimenAlign; children: React.ReactNode }) {
+  if (fill) {
+    const alignItems = specimenContentAlignItems(fill, align);
+    return <View style={[SPECIMEN_SURFACE_WIDTH_STYLE, { alignItems }]}>{children}</View>;
+  }
+  return <View style={specimenContentBoundedStyle(align)}>{children}</View>;
 }
 
 // 'dark' reuses CATALOG_COLOR.text (the catalog's own darkest token); there is no dark-surface token.
@@ -77,8 +90,3 @@ const FILL = StyleSheet.create({
   dark: { backgroundColor: CATALOG_COLOR.text },
   transparent: {},
 });
-
-const styles = StyleSheet.create({
-  center: { ...SPECIMEN_SURFACE_WIDTH_STYLE, alignItems: 'center' },
-  fill: { ...SPECIMEN_SURFACE_WIDTH_STYLE },
-});

package/native/catalog/UpdatePanel.tsx

@@ -1,9 +1,11 @@
 import React, { useCallback, useEffect, useRef, useState } from 'react';
-import { Platform, Pressable, ScrollView, StyleSheet, Text, View } from 'react-native';
+import { ActivityIndicator, Platform, Pressable, ScrollView, StyleSheet, Switch, Text, View } from 'react-native';
 import { CATALOG_COLOR, CATALOG_LAYOUT, CATALOG_RADIUS, CATALOG_SPACE, CATALOG_TYPE } from './tokens';
 import { DS_VIEWER_SECRET_HEADER } from './catalogNavigation';
-import { daysAgoLabel, isAlreadyUpToDateError, resolvePanelPhase, type UpdatePlanView, type UpdateStatusView } from './updatePanelState';
-import type { UpdateNotice } from './types';
+import {
+  autoCheckHelp, bumpLabel, checkedAgoLabel, daysAgoLabel, isAlreadyUpToDateError, resolvePanelPhase, versionOverview, type UpdatePlanView, type UpdateStatusView,
+} from './updatePanelState';
+import type { UpdateNotice, VersionStatus } from './types';
 
 function isWeb(): boolean {
   return Platform.OS === 'web' && typeof window !== 'undefined';
@@ -25,7 +27,7 @@ function VersionsHeader({ current, latest, breaking, releasedAt }: { current: st
         <Text style={styles.arrow}>→</Text>
         <Text style={styles.versionsText}>{latest}</Text>
         <View style={[styles.pill, breaking && styles.pillMajor]}>
-          <Text style={[styles.pillText, breaking && styles.pillTextMajor]}>{breaking ? 'Major' : 'Minor'}</Text>
+          <Text style={[styles.pillText, breaking && styles.pillTextMajor]}>{bumpLabel(current, latest, breaking)}</Text>
         </View>
       </View>
       <Text style={styles.muted}>{`You’re on ${current}.${releasedAt ? ` ${daysAgoLabel(releasedAt, Date.now())}` : ''}`}</Text>
@@ -190,6 +192,140 @@ function failureCopy(failedStep: string, current: string): { headline: string; b
   };
 }
 
+/**
+ * The update page when no newer version is known (approved mockup
+ * docs/design/2026-10-10-ds-viewer-update-page-always-approved.html, states 3, 4, 6, 7 and 8): the
+ * installed version and which situation applies, when it last checked, the automatic-check
+ * switch, and **Check now**. Without an endpoint (a static build) it shows the status only.
+ */
+function VersionDetails({
+  status,
+  endpoint,
+  onStatus,
+}: {
+  status: VersionStatus;
+  endpoint?: Endpoint;
+  onStatus: (next: VersionStatus) => void;
+}) {
+  const [checking, setChecking] = useState(false);
+  const [justChecked, setJustChecked] = useState(false);
+  const [saving, setSaving] = useState(false);
+  const [localError, setLocalError] = useState<string | undefined>(undefined);
+  const live = Boolean(endpoint) && isWeb();
+  const overview = versionOverview(status, justChecked, Date.now());
+  const help = autoCheckHelp(status.autoCheck);
+
+  const checkNow = async () => {
+    if (!endpoint || checking) return;
+    setChecking(true);
+    setJustChecked(false);
+    setLocalError(undefined);
+    try {
+      const res = await authedFetch(endpoint, '/version/check', { method: 'POST' });
+      if (!res.ok) throw new Error(String(res.status));
+      const next = (await res.json()) as VersionStatus;
+      // A newer version moves the whole page into the update flow (the parent re-renders with it).
+      setJustChecked(next.lastOutcome === 'ok' && !next.update);
+      onStatus(next);
+    } catch {
+      setLocalError('Couldn’t reach the viewer’s local server. If this keeps happening, restart npx ds-viewer dev.');
+    } finally {
+      setChecking(false);
+    }
+  };
+
+  const setAutoCheck = async (enabled: boolean) => {
+    if (!endpoint || saving) return;
+    setSaving(true);
+    setLocalError(undefined);
+    try {
+      const res = await authedFetch(endpoint, '/version/auto-check', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ enabled }),
+      });
+      if (!res.ok) throw new Error(String(res.status));
+      onStatus((await res.json()) as VersionStatus);
+    } catch {
+      setLocalError('Couldn’t save the setting. Try again.');
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const unreachable = status.lastOutcome === 'unreachable';
+  return (
+    <>
+      <View style={styles.versionsRow}>
+        <Text style={styles.versionsText}>{status.current}</Text>
+        {overview.pill === 'latest' && (
+          <View style={[styles.pill, styles.pillSuccess]}>
+            <Text style={[styles.pillText, styles.pillTextSuccess]}>Latest</Text>
+          </View>
+        )}
+        {overview.pill === 'off' && (
+          <View style={[styles.pill, styles.pillOff]}>
+            <Text style={[styles.pillText, styles.pillTextOff]}>Checks off</Text>
+          </View>
+        )}
+      </View>
+      <Text style={styles.muted}>{overview.line}</Text>
+      {overview.note && (
+        <NoteBox variant={overview.note.variant}>
+          {overview.note.bold ? <Text style={styles.noteBoxBold}>{overview.note.bold}</Text> : null}
+          {overview.note.text}
+        </NoteBox>
+      )}
+      {!unreachable && (
+        <View style={styles.facts}>
+          <View style={styles.factRow}>
+            <Text style={styles.factLabel}>Last checked</Text>
+            <Text style={styles.factValue}>{checkedAgoLabel(status.lastCheckedAt, Date.now())}</Text>
+          </View>
+          <View style={styles.factRow}>
+            <View style={styles.switchText}>
+              <Text style={styles.switchLabel}>Check for updates automatically</Text>
+              <Text style={styles.switchHelp}>{help.text}</Text>
+            </View>
+            <Switch
+              value={status.autoCheck.enabled}
+              onValueChange={setAutoCheck}
+              disabled={!live || help.locked || saving || checking}
+              // React Native web passes only the label to the real input (no description), so the
+              // helper text rides in the accessible name: a screen reader hears why it's on or off.
+              accessibilityLabel={`Check for updates automatically. ${help.text}`}
+              trackColor={{ false: '#c9c9c9', true: CATALOG_COLOR.accent }}
+              thumbColor="#ffffff"
+              // The approved mockup's 44 × 26 switch; React Native web's default is 40 × 20, below
+              // the 24px minimum hit target.
+              style={styles.switch}
+              {...({ activeThumbColor: '#ffffff' } as Record<string, unknown>)}
+            />
+          </View>
+        </View>
+      )}
+      {localError && <NoteBox variant="err">{localError}</NoteBox>}
+      {live && (
+        <View style={styles.actions}>
+          <Pressable
+            onPress={checkNow}
+            disabled={checking}
+            accessibilityRole="button"
+            accessibilityState={{ disabled: checking, busy: checking }}
+            style={[styles.secondaryButton, styles.buttonRow, checking && styles.busyButton]}
+          >
+            {checking && <ActivityIndicator size="small" color={CATALOG_COLOR.textMuted} />}
+            <Text style={[styles.secondaryButtonText, checking && styles.busyButtonText]}>
+              {checking ? 'Checking…' : overview.action === 'retry' ? 'Try again' : 'Check now'}
+            </Text>
+          </Pressable>
+          {unreachable && !checking && <Text style={styles.muted}>or run <Code>npm view @krapwoo/ds-viewer version</Code></Text>}
+        </View>
+      )}
+    </>
+  );
+}
+
 /**
  * Design §5's update page (`#ds-viewer-update`), approved mockup direction "C · Update page".
  * Fetches `/update/status` once on mount, then `/plan` — `resolvePanelPhase` (Task 15) picks which
@@ -203,11 +339,16 @@ function failureCopy(failedStep: string, current: string): { headline: string; b
  */
 export function UpdatePanel({
   update,
+  versionStatus,
+  onVersionStatus,
   endpoint,
   appName,
   headingRef,
 }: {
   update: UpdateNotice | null;
+  /** When present, the no-update view shows the version, the switch and **Check now**. */
+  versionStatus?: VersionStatus | null;
+  onVersionStatus?: (next: VersionStatus) => void;
   endpoint?: Endpoint;
   appName: string;
   headingRef?: React.Ref<View>;
@@ -325,6 +466,8 @@ export function UpdatePanel({
     content =
       status.phase === 'success' ? (
         <SuccessContent status={status} />
+      ) : versionStatus ? (
+        <VersionDetails status={versionStatus} endpoint={endpoint} onStatus={onVersionStatus ?? (() => {})} />
       ) : (
         <NoteBox variant="ok">You’re already up to date.</NoteBox>
       );
@@ -486,7 +629,7 @@ export function UpdatePanel({
       {/* react-native-web reads `aria-level`; React Native's own prop types do not declare it —
        *  the same cast `SectionBlock.tsx`'s own heading target already uses. */}
       <View ref={headingRef} tabIndex={-1} role="heading" {...({ 'aria-level': 1 } as Record<string, unknown>)} style={styles.headingTarget}>
-        <Text style={styles.title}>Update DS Viewer</Text>
+        <Text style={styles.title}>DS Viewer updates</Text>
       </View>
       {content}
     </View>
@@ -517,6 +660,19 @@ const styles = StyleSheet.create({
   pillText: { fontSize: CATALOG_TYPE.sm, fontWeight: '700', color: CATALOG_COLOR.accent },
   pillTextMajor: { color: CATALOG_COLOR.warning },
   pillTextSuccess: { color: CATALOG_COLOR.success },
+  pillOff: { backgroundColor: CATALOG_COLOR.chip },
+  pillTextOff: { color: CATALOG_COLOR.textMuted },
+  facts: { marginTop: 18, borderTopWidth: 1, borderTopColor: CATALOG_COLOR.border },
+  factRow: { flexDirection: 'row', alignItems: 'center', justifyContent: 'space-between', gap: CATALOG_SPACE.md, paddingVertical: 10, borderBottomWidth: 1, borderBottomColor: CATALOG_COLOR.border },
+  factLabel: { fontSize: CATALOG_TYPE.md, color: CATALOG_COLOR.textMuted },
+  factValue: { fontSize: CATALOG_TYPE.md, color: CATALOG_COLOR.text },
+  switchText: { flex: 1, gap: 2 },
+  switchLabel: { fontSize: CATALOG_TYPE.md, fontWeight: '700', color: CATALOG_COLOR.text },
+  switch: { width: 44, height: 26 },
+  switchHelp: { fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted },
+  buttonRow: { flexDirection: 'row', gap: CATALOG_SPACE.sm },
+  busyButton: { borderColor: CATALOG_COLOR.border },
+  busyButtonText: { color: CATALOG_COLOR.textMuted },
   muted: { fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted, marginTop: 4 },
   block: { marginTop: 18 },
   h3: { fontSize: CATALOG_TYPE.panelHeading, textTransform: 'uppercase', letterSpacing: 0.5, color: CATALOG_COLOR.text, marginBottom: 8 },

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, UpdateNotice } from './types.ts';
+import type { NavGroup, UpdateNotice, VersionStatus } from './types.ts';
 
 /** THE canonical within-group ordering of section ids. */
 export function sortIds<TId extends string>(ids: readonly TId[]): TId[] {
@@ -149,3 +149,16 @@ export function footerLabel(update: UpdateNotice | null | undefined): string | u
   if (!update || !isNewerVersion(update.latest, update.current)) return undefined;
   return `Update available · ${update.latest}`;
 }
+
+/** The sidebar's footer line: the blue "Update available" notice when a newer version is known
+ *  (from startup or **Check now**), else the installed version, quietly. `undefined` only for a
+ *  workspace generated before version status existed, which keeps the old notice-only footer. */
+export function footerLink(
+  update: UpdateNotice | null | undefined,
+  status: VersionStatus | null | undefined,
+): { label: string; kind: 'update' | 'version' } | undefined {
+  const notice = footerLabel(update) ?? footerLabel(status?.update);
+  if (notice) return { label: notice, kind: 'update' };
+  if (status) return { label: `DS Viewer ${status.current}`, kind: 'version' };
+  return undefined;
+}

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 };
 
@@ -222,6 +232,12 @@ export interface ListItem {
   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 {
@@ -250,7 +266,9 @@ export function slotSize<TId extends string>(def: SectionDef<TId>, slot: Variant
 }
 
 function slotItems(slot: VariantSlot): ListItem[] {
-  return slot.items.map((item) => ({ key: item.key, label: item.name, node: item.node, fill: item.fill || slot.itemsFill }));
+  // 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, 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 +283,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, label: s.name, node: s.node, fill: fill(s, states), surface: s.surface, align: s.align }))
+      : [{ key: variant.key, 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));
@@ -377,3 +397,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/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,156 @@
+/**
+ * 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';
+
+/** 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'];
+
+/** `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;
+  // 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 };
+}