@krapwoo/ds-viewer 0.4.7 → 0.4.8

package/README.md

@@ -92,9 +92,15 @@ npm run kit:dev          # builds the CLI, then opens the starter kit's own cata
 npm run check:catalog    # the same headless check CI runs — every page, zero console errors
 ```
 
-`kit-host/` also hosts `viewer-pages/` — standalone catalog pages (not shipped in the package)
-documenting the viewer framework's own pieces (`CatalogShell`, `SectionBlock`, `ComparisonGrid`,
-…), shown under a "Viewer" group alongside the starter kit's own pages.
+The viewer's own building blocks (`CatalogShell`, `SectionBlock`, `ComparisonGrid`, the catalog's
+own colours and type, …) are documented in a separate catalog for people working on ds-viewer
+itself, so the starter kit's catalog shows only what a project using the kit gets:
+
+```bash
+npm run viewer:dev       # opens viewer-host/, the DS Viewer internals catalog (not shipped)
+```
+
+`check:catalog`, `check:doctor` and `check:types` cover both catalogs.
 
 ## Contributing
 
@@ -259,6 +265,15 @@ actually apply:
   the one child document that the address itself selects, `children` render inline with no
   boundary — never read either case as native containment parity.
 - `previewWidths: [402, 320]` — extra preview widths for a `render()` page (each capped at 402).
+  Add a second width only when the component looks different there (labels truncate, a row
+  wraps); otherwise it's the same picture twice. Leave it out by default.
+- **`PhoneFrame`** — wrap a demo that is a whole screen or opens an overlay (a sheet, a dialog, a
+  toast sliding in, a dropdown's picker) in `<PhoneFrame>`. It is a real device: the demo lays out
+  in an iPhone SE viewport (375 × 667 points), scaled down only when its cell is narrower. In the
+  browser viewer it opens that example in its own device-sized document, so overlays that portal
+  to the page (React Native's `Modal`) open inside the phone, not over the catalog.
+- Full-width (`itemsFill`) variants and states wrap at most **3** across; set `maxColumns` to
+  change that. A filled example that keeps its own fixed width is centred in its cell.
   Default to one preview; add a second width only when a narrower (or wider) viewport actually
   changes something worth comparing — wrapping, truncation, or reflow — not just to show the same,
   identically-laid-out content twice. `CatalogShell`'s `defaultPreviewWidths="full"` keeps a
@@ -308,9 +323,9 @@ path. For anything beyond a single list of tokens, use the token-page layouts be
   `Components`. A page's `group` is a plain string shown as its sidebar section label;
   `groupOrder` (e.g. `['Tokens', 'Components', 'Patterns', 'Recipes', 'Experiences']`) only
   controls which order those sections appear in, top to bottom — any group not listed sorts
-  alphabetically after the ones that are. This starter kit's own two groups (`Tokens`, then
-  `Components`) are one valid shape, not the only one: a larger catalog might add `Patterns`
-  (reusable combinations like a settings row), `Recipes` (worked end-to-end screens), or
+  alphabetically after the ones that are. The starter kit uses `Tokens`, then every
+  component under `Components`, then `Patterns` (whole screens built from the kit, such as
+  SavedTrips) and `Reference` (the generated manifest). A larger catalog might add `Recipes` or
   `Experiences` (full flows) alongside them. Pages sort A–Z inside each group regardless of how
   many groups you have. Avoid splitting `Components` into finer categories such as "Actions" or
   "Status" purely to browse by — that makes readers guess where a component lives; search and A–Z

package/dist/cli/doctor.js

@@ -480,7 +480,9 @@ export function checkPageTypeErrors(pages, options = {}) {
     // `createComponentReader` (where a mismatch only degrades prop reading silently; here it would
     // produce CI-failing errors the host's own `tsc` would never raise). Only `noEmit`,
     // `skipLibCheck`, and the merged `paths` are forced on top.
-    const host = readHostTsconfigOptions(pageFiles[0]);
+    // `readHostTsconfigOptions` searches upward from the given file's folder; a file name inside
+    // `hostRoot` starts that search at the host's own root.
+    const host = readHostTsconfigOptions(options.hostRoot ? path.join(options.hostRoot, 'ds-viewer.config.ts') : pageFiles[0]);
     const compilerOptions = {
         ...host.options,
         noEmit: true,
@@ -569,7 +571,7 @@ export function runDoctor(config) {
         : undefined;
     let issues = [
         ...collectIssues(pages, components),
-        ...checkPageTypeErrors(pages, { fallbackPaths }),
+        ...checkPageTypeErrors(pages, { fallbackPaths, hostRoot: config.projectRoot }),
         ...collectGlobalIssues({ syncWarnings: syncResult.warnings, tokenFileCount }),
     ];
     // Design's own `--json` example gives a project-relative `file`; `StaticPage.file` is absolute

package/dist/cli/init.js

@@ -141,14 +141,11 @@ function ensureSharedProjectFiles(projectRoot) {
     return written;
 }
 const KIT_REQUIRED_PACKAGES = ['react-native-svg', 'react-native-safe-area-context'];
-/** The starter kit's own intended sidebar order (the same list kit-host/ds-viewer.config.ts
- *  declares, minus "Viewer" — that group only holds kit-host's own framework-docs pages under
- *  `viewer-pages/`, which `init --new` never copies). Written into a fresh project's config so its
- *  sidebar isn't left alphabetical (controller end-to-end finding E3). */
-const KIT_GROUP_ORDER = [
-    'Actions', 'Surfaces', 'Inputs', 'Controls', 'Selection', 'Feedback', 'Navigation',
-    'Overlays', 'Layout', 'Sub-Parts', 'Recipes', 'Tokens', 'Reference',
-];
+/** The starter kit's own sidebar order (the same list kit-host/ds-viewer.config.ts declares),
+ *  written into a fresh project's config. Follows the README's "Organising the catalog": Tokens,
+ *  then every component in one A–Z group, then the non-component kinds of page (Patterns: whole
+ *  screens built from the kit; Reference: the generated manifest). */
+const KIT_GROUP_ORDER = ['Tokens', 'Components', 'Patterns', 'Reference'];
 /** Default `installer` — a real `npx expo install`, run only for whichever of
  *  `KIT_REQUIRED_PACKAGES` the project doesn't already depend on. Test-injected in every unit test
  *  (this plan's Global Constraints: never run a real `expo install` in tests). */

package/dist/native/catalog/comparison.js

@@ -189,10 +189,19 @@ export function remainingStates(states, comparison) {
 export function slotSize(def, slot) {
     return def.specimenSize ?? (slot.itemsFill ? 'wide' : 'regular');
 }
-function slotItems(slot) {
+/** 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) {
+    if (slot.maxColumns !== undefined)
+        return { maxColumns: slot.maxColumns };
+    return slot.itemsFill ? { maxColumns: FILLED_SLOT_MAX_COLUMNS } : {};
+}
+function slotItems(slot, from) {
     // 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. */
 function previewWidths(requested, fallback) {
@@ -212,8 +221,8 @@ function groupStates(variants, states) {
     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', label: s.name, node: s.node, fill: fill(s, states), surface: s.surface, align: s.align }))
+            : [{ key: variant.key, slot: 'variants', 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));
@@ -260,8 +269,8 @@ export function presentationBlocks(def, options = {}) {
                 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) {
@@ -274,8 +283,8 @@ export function presentationBlocks(def, options = {}) {
             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),
         });
     }
     if (blocks.length === 0 && !hide.variants && !hide.states) {

package/native/catalog/CatalogShell.tsx

@@ -7,6 +7,7 @@ import { SectionBlock } from './SectionBlock';
 import { UpdatePanel } from './UpdatePanel';
 import { DS_VIEWER_SECRET_HEADER, footerLink, groupLabelFor, hashForId, neighbors, orderedIds, resolveActiveFromHash, shouldShowMajorBanner, UPDATE_PAGE_ID } from './catalogNavigation';
 import { findOverlayNode, overlayAddressFromSearch } from './overlayViewport';
+import { SpecimenAddressProvider } from './SpecimenAddress';
 import type { NavGroup, PreviewWidths, SectionDef, UpdateNotice, VersionStatus } from './types';
 
 /** `active` can be a real page id, or the reserved update-page id — never both a generic `TId`
@@ -255,7 +256,10 @@ export function CatalogShell<TId extends string>({
   if (overlayAddress) {
     return (
       <View style={styles.overlayDocumentRoot}>
-        {overlayNode ?? <Text style={styles.overlayUnavailable}>This example is no longer available.</Text>}
+        {/* The addressed example's own device frame recognises this document as its viewport. */}
+        <SpecimenAddressProvider address={overlayAddress}>
+          {overlayNode ?? <Text style={styles.overlayUnavailable}>This example is no longer available.</Text>}
+        </SpecimenAddressProvider>
       </View>
     );
   }

package/native/catalog/ComparisonGrid.tsx

@@ -3,6 +3,8 @@ import { View, Text, ScrollView, StyleSheet } from 'react-native';
 import { CATALOG_COLOR, CATALOG_RADIUS, CATALOG_TYPE } from './tokens';
 import { COLUMN_MIN_WIDTH, MATRIX_LAYOUT, axisItems, cellKey, gridWidthBounds, indexCells, validateComparison } from './comparison';
 import { SpecimenContent, SpecimenSurface } from './SpecimenSurface';
+import { SpecimenAddressProvider } from './SpecimenAddress';
+import { comparisonCellItemKey } from './overlayViewport';
 import { DEFAULT_SPECIMEN_SURFACE } from './specimenSurfaceStyle';
 import type { ComparisonDef, SpecimenSize, SpecimenSurfaceKind } from './types';
 
@@ -66,7 +68,9 @@ export function ComparisonGrid({
               return (
                 cell?.node !== undefined ? (
                   <SpecimenSurface key={c.key} role="cell" surface={cell.surface ?? surface} style={[styles.cell, column, styles.bodyRow, styles.specimenCell, ci === lastColumn && styles.lastColumn]}>
-                    <SpecimenContent fill={cell.fill} align={cell.align}>{cell.node}</SpecimenContent>
+                    <SpecimenAddressProvider address={{ pageId: sectionId, slot: 'comparison', itemKey: comparisonCellItemKey(row.key, c.key) }}>
+                      <SpecimenContent fill={cell.fill} align={cell.align}>{cell.node}</SpecimenContent>
+                    </SpecimenAddressProvider>
                   </SpecimenSurface>
                 ) : (
                   <View key={c.key} role="cell" style={[styles.cell, column, styles.bodyRow, styles.specimenCell, ci === lastColumn && styles.lastColumn]}>

package/native/catalog/ComparisonGroups.tsx

@@ -3,6 +3,7 @@ import { View, Text, ScrollView, StyleSheet } from 'react-native';
 import { CATALOG_COLOR, CATALOG_RADIUS, CATALOG_TYPE } from './tokens';
 import { COLUMN_MIN_WIDTH, MATRIX_LAYOUT, type ListGroup } from './comparison';
 import { SpecimenContent, SpecimenSurface } from './SpecimenSurface';
+import { SpecimenAddressProvider } from './SpecimenAddress';
 import { DEFAULT_SPECIMEN_SURFACE } from './specimenSurfaceStyle';
 import type { SpecimenSize, SpecimenSurfaceKind } from './types';
 
@@ -18,10 +19,13 @@ export function ComparisonGroups({
   size,
   label,
   surface = DEFAULT_SPECIMEN_SURFACE,
+  pageId,
 }: {
   groups: ListGroup[];
   size: SpecimenSize;
   label: string;
+  /** The page these examples belong to, so a device frame inside one can address it. */
+  pageId?: string;
   surface?: SpecimenSurfaceKind;
 }) {
   const columns = Math.max(1, ...groups.map((g) => g.items.length));
@@ -48,7 +52,9 @@ export function ComparisonGroups({
                       <Text style={styles.captionText}>{item.label}</Text>
                     </View>
                     <SpecimenSurface surface={item.surface ?? surface} style={styles.specimen}>
-                      <SpecimenContent fill={item.fill} align={item.align}>{item.node as React.ReactNode}</SpecimenContent>
+                      <SpecimenAddressProvider address={pageId && item.slot ? { pageId, slot: item.slot, itemKey: item.key } : undefined}>
+                        <SpecimenContent fill={item.fill} align={item.align}>{item.node as React.ReactNode}</SpecimenContent>
+                      </SpecimenAddressProvider>
                     </SpecimenSurface>
                   </View>
                 );

package/native/catalog/ComparisonList.tsx

@@ -3,6 +3,7 @@ import { View, Text, StyleSheet, type LayoutChangeEvent } from 'react-native';
 import { CATALOG_COLOR, CATALOG_RADIUS, CATALOG_TYPE } from './tokens';
 import { MATRIX_LAYOUT, listGeometry, type ListItem } from './comparison';
 import { SpecimenContent, SpecimenSurface } from './SpecimenSurface';
+import { SpecimenAddressProvider } from './SpecimenAddress';
 import { DEFAULT_SPECIMEN_SURFACE } from './specimenSurfaceStyle';
 import type { SpecimenSize, SpecimenSurfaceKind } from './types';
 
@@ -19,10 +20,13 @@ export function ComparisonList({
   label,
   maxColumns,
   surface = DEFAULT_SPECIMEN_SURFACE,
+  pageId,
 }: {
   items: ListItem[];
   size: SpecimenSize;
   label: string;
+  /** The page these examples belong to, so a device frame inside one can address it. */
+  pageId?: string;
   maxColumns?: 1 | 2 | 3 | 4 | 5;
   surface?: SpecimenSurfaceKind;
 }) {
@@ -62,7 +66,9 @@ export function ComparisonList({
                     <Text style={styles.captionText}>{item.label}</Text>
                   </View>
                   <SpecimenSurface surface={item.surface ?? surface} style={styles.specimen}>
-                    <SpecimenContent fill={item.fill} align={item.align}>{item.node as React.ReactNode}</SpecimenContent>
+                    <SpecimenAddressProvider address={pageId && item.slot ? { pageId, slot: item.slot, itemKey: item.key } : undefined}>
+                      <SpecimenContent fill={item.fill} align={item.align}>{item.node as React.ReactNode}</SpecimenContent>
+                    </SpecimenAddressProvider>
                   </SpecimenSurface>
                 </View>
               );

package/native/catalog/PhoneFrame.tsx

@@ -1,36 +1,100 @@
-import React from 'react';
-import { View, StyleSheet } from 'react-native';
-import { CATALOG_RADIUS, CATALOG_COLOR } from './tokens';
+import React, { useState } from 'react';
+import { Platform, StyleSheet, Text, View, type LayoutChangeEvent } from 'react-native';
+import { CATALOG_COLOR, CATALOG_RADIUS, CATALOG_TYPE } from './tokens';
+import { DEVICE_FRAME, deviceFrameScale } from './deviceFrame';
+import { resolveOverlayViewport } from './overlayViewport';
+import { useSpecimenAddress } from './SpecimenAddress';
 
-const WIDTH_CAP = 280;
-const HEIGHT = 480;
+function isWeb(): boolean {
+  return Platform.OS === 'web' && typeof window !== 'undefined';
+}
 
 /**
- * A bounded "phone screen" preview frame — contains a live demo (e.g. a BottomSheet or Dropdown's
- * picker) inside a fixed-size box instead of letting its absolutely-positioned overlay cover the
- * whole documentation page. Purely a documentation device: a real app screen never needs to fake
- * being a phone screen inside itself, since the actual device viewport already does that job — that's
- * why this lives in the catalog framework (like VariantGroup/TokenRow) rather than the host app's
- * own component library (a downstream app would never import this file).
+ * A real phone screen for a live demo: a screen, a sheet, a dialog, a toast sliding in.
  *
- * `width: '100%'` capped at 280 (not a fixed width) — a fixed px width could exceed the card's real
- * content width once the surrounding column shrinks below its own max-width cap (it does at common
- * viewport sizes), overflowing past the card's edge since the card itself doesn't clip.
+ * - **Real dimensions.** The demo lays out in a viewport of exactly `DEVICE_FRAME` (iPhone SE,
+ *   375 × 667 points). A cell narrower than that scales the whole device down rather than
+ *   squeezing its layout.
+ * - **A real viewport on the web.** Inside a catalog example, the frame opens that one example in
+ *   its own child document at device size (the same mechanism as `BoundedOverlayViewport`). Its
+ *   window is the device: anything that portals to the document body, such as React Native's
+ *   `Modal`, opens inside the phone instead of over the whole catalog, and the window reports the
+ *   device's size.
+ * - **Elsewhere** (native, or a frame outside a catalog example) it renders inline at the same
+ *   size; overlays that portal to the body are then not contained.
  *
- * `alignSelf: 'center'` is this frame's own responsibility, not its `SpecimenContent` wrapper's:
- * a `fill` specimen's wrapper now stretches by default (preserving an unrelated full-width
- * auto-sized specimen elsewhere), which leaves a capped-width child like this one flush to one
- * side instead of centered — see `specimenContentAlignItems` in `specimenSurfaceStyle.ts`.
+ * Centred in its cell by its own full-width measuring wrapper, whatever the cell's alignment.
+ * Purely a documentation device: a real app screen never frames itself, so this lives in the
+ * catalog framework rather than in an app's component library.
  */
 export function PhoneFrame({ children }: { children: React.ReactNode }) {
-  return <View style={styles.frame}>{children}</View>;
+  const address = useSpecimenAddress();
+  const [available, setAvailable] = useState(0);
+  const [status, setStatus] = useState<'loading' | 'ready' | 'unavailable'>('loading');
+  const onLayout = (event: LayoutChangeEvent) => {
+    const width = Math.floor(event.nativeEvent.layout.width);
+    if (width > 0 && width !== available) setAvailable(width);
+  };
+  const scale = deviceFrameScale(available);
+  // Until the cell is measured, fit it at the device's proportions rather than drawing at full size
+  // for a frame (which would briefly overflow a cell narrower than the device).
+  const box = available > 0
+    ? { width: DEVICE_FRAME.width * scale, height: DEVICE_FRAME.height * scale }
+    : { width: '100%' as const, maxWidth: DEVICE_FRAME.width, aspectRatio: DEVICE_FRAME.width / DEVICE_FRAME.height };
+
+  if (isWeb() && address) {
+    const decision = resolveOverlayViewport({
+      address,
+      isWeb: true,
+      currentSearch: window.location.search,
+      pathname: window.location.pathname,
+    });
+    // This document is the device itself: fill it edge to edge.
+    if (decision.mode === 'inline') return <View style={styles.screenFill}>{children}</View>;
+    return (
+      <View style={styles.measure} onLayout={onLayout}>
+        <View style={[styles.device, box]}>
+          {status !== 'ready' && (
+            <Text style={styles.status}>{status === 'unavailable' ? 'This example is unavailable right now.' : 'Loading…'}</Text>
+          )}
+          {
+            // react-native-web has no iframe primitive; this is a plain same-origin iframe.
+            React.createElement('iframe' as unknown as string, {
+              src: decision.href,
+              title: `${address.pageId} on ${DEVICE_FRAME.name} (${DEVICE_FRAME.width} × ${DEVICE_FRAME.height})`,
+              style: {
+                position: 'absolute',
+                top: 0,
+                left: 0,
+                width: DEVICE_FRAME.width,
+                height: DEVICE_FRAME.height,
+                border: 0,
+                transform: `scale(${scale})`,
+                transformOrigin: '0 0',
+                visibility: status === 'ready' ? 'visible' : 'hidden',
+              },
+              onLoad: () => setStatus('ready'),
+              onError: () => setStatus('unavailable'),
+            })
+          }
+        </View>
+      </View>
+    );
+  }
+
+  return (
+    <View style={styles.measure} onLayout={onLayout}>
+      <View style={[styles.device, box]}>
+        <View style={[styles.screenInline, { transform: [{ scale }], transformOrigin: 'top left' } as object]}>{children}</View>
+      </View>
+    </View>
+  );
 }
 
 const styles = StyleSheet.create({
-  frame: {
-    width: '100%',
-    maxWidth: WIDTH_CAP,
-    height: HEIGHT,
+  // Spans the cell so the device can be measured against it and centred in it.
+  measure: { width: '100%', alignItems: 'center' },
+  device: {
     borderRadius: CATALOG_RADIUS.md,
     borderWidth: StyleSheet.hairlineWidth,
     borderColor: CATALOG_COLOR.border,
@@ -38,6 +102,26 @@ const styles = StyleSheet.create({
     overflow: 'hidden',
     alignItems: 'center',
     justifyContent: 'center',
-    alignSelf: 'center',
   },
+  screenInline: {
+    width: DEVICE_FRAME.width,
+    height: DEVICE_FRAME.height,
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    alignItems: 'center',
+    justifyContent: 'center',
+    overflow: 'hidden',
+  },
+  // The child document's whole window is the device screen: exactly the device's height, never
+  // more, so a `flex: 1` scroll area inside a demo shrinks to fit and scrolls instead of growing.
+  screenFill: {
+    width: '100%',
+    height: DEVICE_FRAME.height,
+    backgroundColor: CATALOG_COLOR.surfacePressed,
+    alignItems: 'center',
+    justifyContent: 'center',
+    overflow: 'hidden',
+  },
+  status: { position: 'absolute', fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted },
 });

package/native/catalog/ReferenceDetails.tsx

@@ -86,10 +86,18 @@ export function ReferenceDetails<TId extends string>({ def }: { def: SectionDef<
     if (next > 0 && next !== width) setWidth(next);
   };
   if (def.tokenGallery) {
+    // Full-width pages with no component API (token galleries, and whole screens such as a
+    // starter kit's Patterns) still disclose what they're built from when they say so.
     return (
       <View style={styles.card}>
         <Text role="heading" {...HEADING_LEVEL_2} style={styles.heading}>Quick reference</Text>
         {def.path && <Fact label="Source" value={def.path} mono />}
+        {def.composedOf && def.composedOf.length > 0 && (
+          <>
+            <Text style={styles.subheading}>Composition</Text>
+            <CompositionFacts composedOf={def.composedOf} />
+          </>
+        )}
       </View>
     );
   }

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.