@krapwoo/ds-viewer 0.4.7 → 0.4.9

package/native/catalog/SectionBlock.tsx

@@ -6,6 +6,7 @@ import { ComparisonGroups } from './ComparisonGroups';
 import { ComparisonList } from './ComparisonList';
 import { ReferenceDetails } from './ReferenceDetails';
 import { SpecimenSurface } from './SpecimenSurface';
+import { SpecimenAddressProvider } from './SpecimenAddress';
 import { DEFAULT_SPECIMEN_SURFACE } from './specimenSurfaceStyle';
 import { TokenSections } from './TokenLayouts';
 import { MATRIX_LAYOUT, choosePlacement, listGeometry, presentationBlocks, type PresentationBlock } from './comparison';
@@ -169,15 +170,19 @@ function BlockContent<TId extends string>({ block, def, surface }: { block: Pres
     case 'grid':
       return <ComparisonGrid def={block.comparison} size={block.size} sectionId={def.id} surface={surface} />;
     case 'grouped':
-      return <ComparisonGroups groups={block.groups} size={block.size} label={def.id} surface={surface} />;
+      return <ComparisonGroups groups={block.groups} size={block.size} label={def.id} surface={surface} pageId={def.id} />;
     case 'list':
-      return <ComparisonList items={block.items} size={block.size} label={`${def.id}: ${block.title}`} maxColumns={block.maxColumns} surface={surface} />;
+      return <ComparisonList items={block.items} size={block.size} label={`${def.id}: ${block.title}`} maxColumns={block.maxColumns} surface={surface} pageId={def.id} />;
     case 'preview':
       // A token gallery's `preview` block shows full-width raw token data, not a component
       // specimen — it keeps its current, unstaged presentation.
       // `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;
+      return def.render ? (
+        <SpecimenAddressProvider address={{ pageId: def.id, slot: 'preview', itemKey: 'preview' }}>
+          <Preview render={def.render} widths={block.widths} surface={def.tokenGallery ? undefined : surface} layout={def.previewLayout === 'table' ? 'table' : undefined} />
+        </SpecimenAddressProvider>
+      ) : null;
     case 'tokenSections':
       return <TokenSections sections={block.sections} columns={block.columns} />;
     default:
@@ -369,7 +374,8 @@ const styles = StyleSheet.create({
   blocks: { gap: CATALOG_LAYOUT.blockGap, marginBottom: CATALOG_LAYOUT.blockGap },
   blocksSide: { flexDirection: 'row', alignItems: 'flex-start' },
   blockFill: { flex: 1, minWidth: 0 },
-  frames: { flexDirection: 'row', flexWrap: 'wrap', gap: CATALOG_SPACE.xl, alignItems: 'flex-start' },
+  // Centred in the card, like every other example (a single phone-width frame used to sit left).
+  frames: { flexDirection: 'row', flexWrap: 'wrap', gap: CATALOG_SPACE.xl, alignItems: 'flex-start', justifyContent: 'center' },
   frame: { maxWidth: '100%', gap: CATALOG_SPACE.sm },
   frameLabel: {
     fontSize: CATALOG_TYPE.tableHeader,

package/native/catalog/SpecimenAddress.tsx

@@ -0,0 +1,15 @@
+import React, { createContext, useContext } from 'react';
+import type { OverlayAddress } from './overlayViewport';
+
+const SpecimenAddressContext = createContext<OverlayAddress | undefined>(undefined);
+
+/** Tells the example rendered inside it which catalog example it is (page, slot, item key), so a
+ *  `PhoneFrame` in it can open that one example in its own device-sized document. Set by the
+ *  catalog's own list, grid and preview renderers, and by the child document itself. */
+export function SpecimenAddressProvider({ address, children }: { address: OverlayAddress | undefined; children: React.ReactNode }) {
+  return <SpecimenAddressContext.Provider value={address}>{children}</SpecimenAddressContext.Provider>;
+}
+
+export function useSpecimenAddress(): OverlayAddress | undefined {
+  return useContext(SpecimenAddressContext);
+}

package/native/catalog/SpecimenSurface.tsx

@@ -1,7 +1,11 @@
 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, specimenContentAlignItems, specimenContentBoundedStyle } from './specimenSurfaceStyle';
+import {
+  DEFAULT_SPECIMEN_SURFACE, SPECIMEN_SURFACE_WIDTH_STYLE, overflowsCell, paintedExtent, shouldCenterFilledContent, specimenContentAlignItems,
+  specimenContentBoundedStyle, visibleBoxes, type LayoutBox,
+} from './specimenSurfaceStyle';
+import { useSpecimenAddress } from './SpecimenAddress';
 import { blendsIntoCell, measurePaintedBoxes } from './specimenFill';
 import type { SpecimenAlign, SpecimenSurfaceKind } from './types';
 
@@ -75,12 +79,70 @@ export function SpecimenSurface({
  *  (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. */
+type MeasurableNode = {
+  getBoundingClientRect: () => { left: number; right: number; width: number };
+  children: ArrayLike<MeasurableNode>;
+  childElementCount: number;
+  tagName: string;
+};
+
+/** The example's element tree as `LayoutBox`es (up to 400 elements), so `visibleBoxes` can skip
+ *  what scrolling or clipping containers hide. */
+function readTree(root: MeasurableNode, browser: Browser): LayoutBox {
+  let budget = 400;
+  const read = (el: MeasurableNode): LayoutBox => {
+    const rect = el.getBoundingClientRect();
+    const style = browser.getComputedStyle!(el) as unknown as { backgroundColor: string; borderTopWidth: string; visibility: string; overflowX: string };
+    const kids: LayoutBox[] = [];
+    const children = el.children;
+    for (let i = 0; i < children.length && budget > 0; i++) {
+      budget -= 1;
+      const child = children[i];
+      if (child.getBoundingClientRect().width < 1) continue;
+      kids.push(read(child));
+    }
+    return {
+      left: rect.left,
+      right: rect.right,
+      painted:
+        style.visibility !== 'hidden' &&
+        (el.childElementCount === 0 || el.tagName === 'svg' || el.tagName === 'IFRAME' ||
+          style.backgroundColor !== 'rgba(0, 0, 0, 0)' || parseFloat(style.borderTopWidth) > 0),
+      clips: style.overflowX === 'hidden' || style.overflowX === 'auto' || style.overflowX === 'scroll' || style.overflowX === 'clip',
+      children: kids,
+    };
+  };
+  return read(root);
+}
+
 export function SpecimenContent({ fill, align, children }: { fill?: boolean; align?: SpecimenAlign; children: React.ReactNode }) {
+  // After layout (browser only): a `fill` example whose visible content is narrower than the cell
+  // (a fixed-width skeleton, a tooltip around a small trigger) is centred instead of sitting
+  // against the leading edge; an explicit `align` always wins. And in development, an example
+  // wider than its cell logs a warning naming a wider `specimenSize`.
+  const address = useSpecimenAddress();
+  const ref = useRef<View>(null);
+  const [centerNarrow, setCenterNarrow] = useState(false);
+  const warned = useRef(false);
+  const measure = useCallback(() => {
+    const browser = globalThis as unknown as Browser;
+    const node = ref.current as unknown as MeasurableNode | null;
+    if (!browser.Element || !browser.getComputedStyle || !node?.getBoundingClientRect) return;
+    const wrapperWidth = node.getBoundingClientRect().width;
+    const visible = paintedExtent(visibleBoxes(readTree(node, browser)));
+    if (fill && align === undefined && !centerNarrow && shouldCenterFilledContent(visible, wrapperWidth)) setCenterNarrow(true);
+    if ((globalThis as { __DEV__?: boolean }).__DEV__ && !warned.current && overflowsCell(visible, wrapperWidth)) {
+      warned.current = true;
+      console.warn(
+        `[Catalog] ${address ? `${address.pageId} (${address.itemKey})` : 'An example'} is ${Math.round(visible)}px wide in a ${Math.round(wrapperWidth)}px cell, so it's cut off. Give the page a wider specimenSize ('regular' or 'wide').`,
+      );
+    }
+  }, [fill, align, centerNarrow, address]);
   if (fill) {
-    const alignItems = specimenContentAlignItems(fill, align);
-    return <View style={[SPECIMEN_SURFACE_WIDTH_STYLE, { alignItems }]}>{children}</View>;
+    const alignItems = centerNarrow ? 'center' : specimenContentAlignItems(fill, align);
+    return <View ref={ref} onLayout={measure} style={[SPECIMEN_SURFACE_WIDTH_STYLE, { alignItems }]}>{children}</View>;
   }
-  return <View style={specimenContentBoundedStyle(align)}>{children}</View>;
+  return <View ref={ref} onLayout={measure} style={specimenContentBoundedStyle(align)}>{children}</View>;
 }
 
 // 'dark' reuses CATALOG_COLOR.text (the catalog's own darkest token); there is no dark-surface token.

package/native/catalog/UpdatePanel.tsx

@@ -3,7 +3,7 @@ import { ActivityIndicator, Platform, Pressable, ScrollView, StyleSheet, Switch,
 import { CATALOG_COLOR, CATALOG_LAYOUT, CATALOG_RADIUS, CATALOG_SPACE, CATALOG_TYPE } from './tokens';
 import { DS_VIEWER_SECRET_HEADER } from './catalogNavigation';
 import {
-  autoCheckHelp, bumpLabel, checkedAgoLabel, daysAgoLabel, isAlreadyUpToDateError, resolvePanelPhase, versionOverview, type UpdatePlanView, type UpdateStatusView,
+  autoCheckHelp, bumpLabel, checkedAgoLabel, resultNote, daysAgoLabel, isAlreadyUpToDateError, resolvePanelPhase, versionOverview, type UpdatePlanView, type UpdateStatusView,
 } from './updatePanelState';
 import type { UpdateNotice, VersionStatus } from './types';
 
@@ -51,20 +51,6 @@ function FilesList({ files }: { files: UpdatePlanView['files'] }) {
   );
 }
 
-/** Same shape as `FilesList`, but with no right-hand reason column — the `success` phase's
- *  `status.files` carries plain paths, never a reason (Task 16 Step 2 table: a dedicated,
- *  smaller render here is simplest rather than over-generalizing `FilesList` for one caller). */
-function PlainFilesList({ files }: { files: string[] }) {
-  return (
-    <View style={styles.filesBox}>
-      {files.map((path, i) => (
-        <View key={path} style={[styles.fileRow, i > 0 && styles.fileRowBorder]}>
-          <Text style={styles.filePath}>{path}</Text>
-        </View>
-      ))}
-    </View>
-  );
-}
 
 const NOTE_BOX_VARIANT = {
   muted: { box: { backgroundColor: CATALOG_COLOR.surfaceMuted }, text: { color: CATALOG_COLOR.text } },
@@ -139,59 +125,66 @@ function Code({ children }: { children: string }) {
   return <Text style={styles.code}>{children}</Text>;
 }
 
-/** The `success` phase's content, shared between the `update === null` path (Errata 1c — the
- *  normal case, since `update.json` becomes `null` once latest equals current) and the defensive
- *  `update` still non-null path. Reads `status.latest`/`status.files`/`status.doctorSummary`,
- *  never `update.latest`/`plan.files` — `plan` is gone by the time this renders (the page has
- *  reloaded onto the new version). */
-function SuccessContent({ status }: { status: Extract<UpdateStatusView, { phase: 'success' }> }) {
+
+
+/**
+ * The result of the last update, as a note at the top of the update page (approved mockup
+ * 2026-10-11): a bold header, a description, one detail line, and a bottom-left button in the
+ * note's colour. The rest of the page stays usable below it.
+ */
+function ResultNoteBox({
+  status,
+  current,
+  latest,
+  busy,
+  onAction,
+}: {
+  status: Extract<UpdateStatusView, { phase: 'success' | 'failure' }>;
+  current: string;
+  latest?: string;
+  busy: boolean;
+  onAction: (kind: 'dismiss' | 'retry' | 'resume') => void;
+}) {
+  const [showLog, setShowLog] = useState(false);
+  const note = resultNote(status, current, latest);
+  const ok = note.tone === 'ok';
+  const tone = ok ? CATALOG_COLOR.success : CATALOG_COLOR.danger;
   return (
-    <>
-      <View style={styles.versionsRow}>
-        <Text style={styles.versionsText}>{status.latest}</Text>
-        <View style={[styles.pill, styles.pillSuccess]}>
-          <Text style={[styles.pillText, styles.pillTextSuccess]}>Updated</Text>
-        </View>
-      </View>
-      <NoteBox variant="ok">
-        <Text style={styles.noteBoxBold}>{`Updated to ${status.latest}.`}</Text>
-        {' Changes are not committed — review them in your editor.'}
-      </NoteBox>
-      <View style={styles.block}>
-        <Text style={styles.h3}>Changed</Text>
-        <PlainFilesList files={status.files} />
-      </View>
-      <View style={styles.block}>
-        <Text style={styles.h3}>Doctor</Text>
-        <Text style={styles.muted}>{status.doctorSummary}</Text>
+    <View style={[styles.resultNote, ok ? styles.resultNoteOk : styles.resultNoteErr]} role="status">
+      <Text style={[styles.resultTitle, { color: tone }]}>{note.title}</Text>
+      <Text style={[styles.resultDescription, { color: tone }]}>{note.description}</Text>
+      <Text style={[styles.resultDetail, { color: tone }]}>
+        {note.command ? (
+          <>
+            {'You can also run '}
+            <Code>{note.command}</Code>
+            {' in your terminal.'}
+          </>
+        ) : (
+          note.detail
+        )}
+      </Text>
+      <View style={styles.resultRow}>
+        <Pressable
+          onPress={() => onAction(note.action.kind)}
+          disabled={busy}
+          accessibilityRole="button"
+          accessibilityState={{ disabled: busy }}
+          style={({ pressed }) => [styles.resultButton, { backgroundColor: tone }, (pressed || busy) && styles.resultButtonPressed]}
+        >
+          <Text style={styles.resultButtonText}>{note.action.label}</Text>
+        </Pressable>
+        {note.hasLog && status.phase === 'failure' && (
+          <Pressable onPress={() => setShowLog((v) => !v)} accessibilityRole="button" accessibilityState={{ expanded: showLog }}>
+            <Text style={[styles.resultLink, { color: tone }]}>{showLog ? 'Hide log' : 'Show log'}</Text>
+          </Pressable>
+        )}
       </View>
-    </>
+      {showLog && status.phase === 'failure' && <LogBlock>{status.log}</LogBlock>}
+    </View>
   );
 }
 
-/** The `failure` phase's headline/body copy, keyed off which step failed — `runUpdate`/
- *  `performUpdate` each name their own distinct recovery command (Important finding, Fable
- *  correction pass: one hardcoded headline/body for every failure was wrong for two of the
- *  three). */
-function failureCopy(failedStep: string, current: string): { headline: string; body: React.ReactNode } {
-  if (/install/i.test(failedStep)) {
-    return {
-      headline: 'The update stopped while installing.',
-      body: <>Your files weren’t migrated. Recover with <Code>npx ds-viewer update</Code> in your terminal.</>,
-    };
-  }
-  if (/migrat/i.test(failedStep)) {
-    return {
-      headline: 'The update installed, but migrating failed.',
-      body: <>Recover with <Code>{`npx ds-viewer migrate --from ${current}`}</Code> in your terminal.</>,
-    };
-  }
-  return {
-    headline: 'The update installed and migrated, but doctor failed to run.',
-    body: <>Recover with <Code>npx ds-viewer doctor</Code> in your terminal.</>,
-  };
-}
-
 /**
  * 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
@@ -202,10 +195,13 @@ function VersionDetails({
   status,
   endpoint,
   onStatus,
+  onCheck,
 }: {
   status: VersionStatus;
   endpoint?: Endpoint;
   onStatus: (next: VersionStatus) => void;
+  /** Called as Check now starts (clears an update result note). */
+  onCheck?: () => void;
 }) {
   const [checking, setChecking] = useState(false);
   const [justChecked, setJustChecked] = useState(false);
@@ -217,6 +213,7 @@ function VersionDetails({
 
   const checkNow = async () => {
     if (!endpoint || checking) return;
+    onCheck?.();
     setChecking(true);
     setJustChecked(false);
     setLocalError(undefined);
@@ -395,7 +392,20 @@ export function UpdatePanel({
     });
   }, [fetchStatus, fetchPlan, update]);
 
-  const phase = resolvePanelPhase(status, planResult);
+  // A finished update (success or failure) shows as a note at the top; the page under it behaves
+  // as if idle, so Check now, the switch and a newer update all keep working.
+  const result = status.phase === 'success' || status.phase === 'failure' ? status : undefined;
+  const phase = resolvePanelPhase(result ? { phase: 'idle' } : status, planResult);
+  const [noteBusy, setNoteBusy] = useState(false);
+  const dismissResult = useCallback(async () => {
+    if (!endpoint || !isWeb()) return;
+    try {
+      const res = await authedFetch(endpoint, '/update/dismiss', { method: 'POST' });
+      if (res.ok) setStatus((await res.json()) as UpdateStatusView);
+    } catch {
+      // The note stays; the next status poll or reload settles it.
+    }
+  }, [endpoint]);
 
   // Polls `/update/status` at a plain interval while an update is in flight — design §5 never
   // asks for push/websocket progress, only "the panel shows progress."
@@ -463,14 +473,14 @@ export function UpdatePanel({
   if (!update) {
     // Errata 1c: no update known (disabled, offline, or genuinely up to date). `status` still
     // reflects a just-finished update read from the (surviving) endpoint across the reload.
-    content =
-      status.phase === 'success' ? (
-        <SuccessContent status={status} />
-      ) : versionStatus ? (
-        <VersionDetails status={versionStatus} endpoint={endpoint} onStatus={onVersionStatus ?? (() => {})} />
+    content = versionStatus ? (
+        <VersionDetails status={versionStatus} endpoint={endpoint} onStatus={onVersionStatus ?? (() => {})} onCheck={result ? dismissResult : undefined} />
       ) : (
         <NoteBox variant="ok">You’re already up to date.</NoteBox>
       );
+  } else if (result?.phase === 'failure') {
+    // The failure note's own button is the recovery; don't offer Update now twice.
+    content = <VersionsHeader current={update.current} latest={update.latest} breaking={update.breaking} releasedAt={update.releasedAt} />;
   } else if (phase === 'ready' && plan) {
     content = (
       <>
@@ -587,40 +597,7 @@ export function UpdatePanel({
         <Text style={styles.muted}>If it doesn’t come back, run <Code>npx ds-viewer dev</Code> in your terminal.</Text>
       </>
     );
-  } else if (phase === 'success' && status.phase === 'success') {
-    content = <SuccessContent status={status} />;
-  } else if (phase === 'failure' && status.phase === 'failure') {
-    const { headline, body } = failureCopy(status.failedStep, update.current);
-    const failedLabel = `${status.failedStep} failed`;
-    content = (
-      <>
-        <VersionsHeader current={update.current} latest={update.latest} breaking={update.breaking} releasedAt={update.releasedAt} />
-        <NoteBox variant="err">
-          <Text style={styles.noteBoxBold}>{headline}</Text>
-          {' '}
-          {body}
-        </NoteBox>
-        <Steps
-          steps={[
-            { label: `Downloaded ${update.latest}`, state: 'done' },
-            { label: failedLabel, state: 'todo' },
-          ]}
-          failedStep={failedLabel}
-        />
-        <LogBlock>{status.log}</LogBlock>
-        <View style={styles.actions}>
-          <Pressable
-            onPress={() => {
-              if (isWeb()) navigator.clipboard?.writeText(status.log);
-            }}
-            accessibilityRole="button"
-            style={styles.secondaryButton}
-          >
-            <Text style={styles.secondaryButtonText}>Copy log</Text>
-          </Pressable>
-        </View>
-      </>
-    );
+
   }
 
   return (
@@ -631,6 +608,28 @@ export function UpdatePanel({
       <View ref={headingRef} tabIndex={-1} role="heading" {...({ 'aria-level': 1 } as Record<string, unknown>)} style={styles.headingTarget}>
         <Text style={styles.title}>DS Viewer updates</Text>
       </View>
+      {result && (
+        <ResultNoteBox
+          status={result}
+          current={update?.current ?? versionStatus?.current ?? ''}
+          latest={update?.latest}
+          busy={noteBusy || starting}
+          onAction={async (kind) => {
+            if (!endpoint) return;
+            setNoteBusy(true);
+            try {
+              if (kind === 'dismiss') await dismissResult();
+              else if (kind === 'retry') await startUpdate();
+              else {
+                await authedFetch(endpoint, '/update/resume', { method: 'POST' });
+                await fetchStatus();
+              }
+            } finally {
+              setNoteBusy(false);
+            }
+          }}
+        />
+      )}
       {content}
     </View>
   );
@@ -638,6 +637,18 @@ export function UpdatePanel({
 
 const styles = StyleSheet.create({
   wrap: { maxWidth: CATALOG_LAYOUT.updateContentMaxWidth },
+  resultNote: { borderRadius: CATALOG_RADIUS.md, padding: 14, marginTop: 12, marginBottom: 18, gap: 4 },
+  resultNoteOk: { backgroundColor: CATALOG_COLOR.successSubtle },
+  resultNoteErr: { backgroundColor: CATALOG_COLOR.dangerSubtle, borderWidth: 1, borderColor: CATALOG_COLOR.dangerBorder },
+  resultTitle: { fontSize: CATALOG_TYPE.lg, fontWeight: '800' },
+  resultDescription: { fontSize: CATALOG_TYPE.panelHeading, lineHeight: 19 },
+  resultDetail: { fontSize: CATALOG_TYPE.sm, lineHeight: 18 },
+  resultRow: { flexDirection: 'row', alignItems: 'center', gap: CATALOG_SPACE.md, marginTop: 8 },
+  // The catalog's smallest control size (the major banner's close button), filled in the note's colour.
+  resultButton: { height: 32, paddingHorizontal: 14, borderRadius: 16, alignItems: 'center', justifyContent: 'center' },
+  resultButtonPressed: { opacity: 0.8 },
+  resultButtonText: { color: '#ffffff', fontSize: CATALOG_TYPE.sm, fontWeight: '700' },
+  resultLink: { fontSize: CATALOG_TYPE.panelHeading, fontWeight: '700', textDecorationLine: 'underline' },
   crumb: { fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted },
   headingTarget: { marginTop: 4, marginBottom: 6 },
   title: { fontSize: CATALOG_TYPE.pageTitle, fontWeight: '800', color: CATALOG_COLOR.text },

package/native/catalog/comparison.ts

@@ -229,6 +229,9 @@ 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;
@@ -265,10 +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[] {
+/** 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, label: item.name, node: item.node, fill: item.fill ?? slot.itemsFill, surface: item.surface, align: item.align }));
+  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. */
@@ -289,8 +302,8 @@ function groupStates(variants: VariantSlot, states: VariantSlot): { groups: List
   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), 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 }];
+      ? 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));
@@ -337,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) });
@@ -351,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),
     });
   }
 

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/overlayViewport.ts

@@ -9,7 +9,7 @@ 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';
+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
@@ -23,7 +23,7 @@ export interface OverlayAddress {
   itemKey: string;
 }
 
-const OVERLAY_SLOTS: readonly OverlaySlot[] = ['variants', 'states', 'comparison'];
+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
@@ -117,6 +117,8 @@ export function findOverlayNode(sections: readonly SectionDef<string>[], address
   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;

package/native/catalog/specimenSurfaceStyle.ts

@@ -88,3 +88,57 @@ export function specimenContentBoundedStyle(align: SpecimenAlign | undefined) {
 /** 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;
+}