@krapwoo/ds-viewer 0.4.5 → 0.4.7

package/dist/native/catalog/catalogNavigation.js

@@ -129,3 +129,14 @@ export function footerLabel(update) {
         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, status) {
+    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/dist/native/catalog/comparison.js

@@ -15,6 +15,12 @@ export const PLACEMENT_MIN_SAVING = 120;
 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 = { compact: 160, regular: 240, wide: 402 };
 /** `Array.isArray`'s built-in type guard narrows to a mutable `any[]`, which a `readonly T[]`
@@ -184,7 +190,9 @@ export function slotSize(def, slot) {
     return def.specimenSize ?? (slot.itemsFill ? 'wide' : 'regular');
 }
 function slotItems(slot) {
-    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. */
 function previewWidths(requested, fallback) {
@@ -198,12 +206,14 @@ function groupStates(variants, states) {
     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, slot) => item.fill || slot.itemsFill;
+    // Nullish, not `||` — same reasoning as `slotItems`: an explicit `fill: false` must win over an
+    // inherited `itemsFill: true`.
+    const fill = (item, slot) => 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));
@@ -297,3 +307,18 @@ export function choosePlacement({ available, gap, first, second }) {
 export function propsColumns(count, width) {
     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, hasComposition) {
+    const fits = (n) => 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/BoundedOverlayViewport.tsx

@@ -0,0 +1,112 @@
+import React, { useState } from 'react';
+import { Platform, StyleSheet, Text, View } from 'react-native';
+import { CATALOG_COLOR, CATALOG_TYPE } from './tokens';
+import { isFiniteOverlaySize, overlayStageDimensions, resolveOverlayViewport, type OverlaySlot } from './overlayViewport';
+
+function isWeb(): boolean {
+  return Platform.OS === 'web' && typeof window !== 'undefined';
+}
+
+export interface BoundedOverlayViewportProps {
+  /** This specimen's own page id — `SectionDef.id`. */
+  pageId: string;
+  /** Which block the demo wrapped here is authored in. */
+  slot: OverlaySlot;
+  /** That item's own key: `VariantExample.key` for `'variants'`/`'states'`, or
+   *  `overlayViewport.ts`'s own `comparisonCellItemKey(rowKey, columnKey)` for a `'comparison'`
+   *  cell — never inferred. */
+  itemKey: string;
+  /** `height` is the child document's exact usable viewport height, in CSS pixels — never
+   *  renegotiated. `width` is only a MAXIMUM: this component adds no border or padding of its own
+   *  (unlike `PhoneFrame`'s cosmetic hairline border), so this is the outer stage's widest possible
+   *  size, but the stage still fills and shrinks to whatever its real owning specimen cell actually
+   *  gives it at narrower widths — a fixed pixel width previously let the stage overflow a
+   *  narrower owner and get silently clipped by it (see `overlayStageDimensions`). Both must be
+   *  finite and strictly positive (`isFiniteOverlaySize`); an invalid value renders an honest
+   *  unavailable state instead of an iframe sized to a meaningless bound. */
+  width: number;
+  height: number;
+  /** The real, unmodified demo — the same node that would otherwise render directly on the page. */
+  children: React.ReactNode;
+}
+
+/**
+ * An opt-in, bounded browsing context for a specimen whose demo opens a modal/sheet/portal that
+ * would otherwise escape its own card and cover the whole catalog page (RNW's Modal portals into
+ * `document.body`, so no styled wrapper or `overflow: hidden` can give it a different boundary —
+ * see the design's §5 "Bounded overlay viewport"). Opens a same-origin child document that boots
+ * the SAME app entry/module/provider tree this catalog page itself runs under, sized to
+ * `width`×`height`, so the demo's own overlay opens inside that rectangle instead of the outer
+ * document's body — the real production component, unmodified: no renderer is copied, no prop is
+ * mutated, no callback/source string is serialized or evaluated.
+ *
+ * Opt-in and additive: a page that never imports this renders exactly as it did before. Purely a
+ * documentation device, like `PhoneFrame` — a real app screen never frames its own overlays this
+ * way, since the actual device viewport already is the boundary.
+ *
+ * Browser-only containment: there is no native equivalent (React Native has no child-document
+ * boundary to open), so on a native runtime this renders `children` directly, with no boundary.
+ * Call sites must not read that fallback as native parity for the contained behavior.
+ */
+export function BoundedOverlayViewport({ pageId, slot, itemKey, width, height, children }: BoundedOverlayViewportProps) {
+  const [status, setStatus] = useState<'loading' | 'ready' | 'unavailable'>('loading');
+  const web = isWeb();
+  const decision = resolveOverlayViewport({
+    address: { pageId, slot, itemKey },
+    isWeb: web,
+    currentSearch: web ? window.location.search : '',
+    pathname: web ? window.location.pathname : '',
+  });
+
+  // Not web, or this document IS the selected child for this exact address: render the real demo
+  // directly — on native there is no containment to offer, and in the selected child document
+  // framing again would recurse into another, identical child document forever.
+  if (decision.mode === 'inline') return <>{children}</>;
+
+  // An invalid bound (not finite, zero, negative — a measurement that hasn't settled yet, a
+  // miscomputed layout value, an author typo) must never reach the iframe below: an honest
+  // unavailable state, not a frame opened at some browser-decided fallback size.
+  if (!isFiniteOverlaySize(width, height)) {
+    return (
+      <View style={styles.stage}>
+        <Text style={styles.status}>This example is unavailable right now.</Text>
+      </View>
+    );
+  }
+
+  return (
+    <View style={[styles.stage, overlayStageDimensions(width, height)]}>
+      {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 the one place this component
+        // reaches past it for a genuine same-origin child document. `as unknown as string` only
+        // bypasses React Native's own JSX.IntrinsicElements typing (which never declares host-web
+        // tags) — the element itself, and every prop it's given, is still a plain, real iframe.
+        React.createElement('iframe' as unknown as string, {
+          src: decision.href,
+          title: `${pageId}: ${itemKey}`,
+          style: { ...StyleSheet.flatten(styles.frame), display: status === 'unavailable' ? 'none' : undefined },
+          onLoad: () => setStatus('ready'),
+          onError: () => setStatus('unavailable'),
+        })
+      }
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  stage: {
+    backgroundColor: CATALOG_COLOR.surfacePressed,
+    alignSelf: 'center',
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  frame: {
+    width: '100%',
+    height: '100%',
+    borderWidth: 0,
+  },
+  status: { position: 'absolute', fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted },
+});

package/native/catalog/CatalogShell.tsx

@@ -5,8 +5,9 @@ import { CATALOG_COLOR, CATALOG_LAYOUT, CATALOG_MAX_CONTENT_WIDTH, CATALOG_RADIU
 import { CatalogSidebar } from './CatalogSidebar';
 import { SectionBlock } from './SectionBlock';
 import { UpdatePanel } from './UpdatePanel';
-import { groupLabelFor, hashForId, neighbors, orderedIds, resolveActiveFromHash, shouldShowMajorBanner, footerLabel, UPDATE_PAGE_ID } from './catalogNavigation';
-import type { NavGroup, PreviewWidths, SectionDef, UpdateNotice } from './types';
+import { DS_VIEWER_SECRET_HEADER, footerLink, groupLabelFor, hashForId, neighbors, orderedIds, resolveActiveFromHash, shouldShowMajorBanner, UPDATE_PAGE_ID } from './catalogNavigation';
+import { findOverlayNode, overlayAddressFromSearch } from './overlayViewport';
+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`
  *  constraint and a hardcoded string literal type at once, which is why this is its own alias. */
@@ -111,6 +112,7 @@ export function CatalogShell<TId extends string>({
   sections,
   defaultPreviewWidths,
   update,
+  versionStatus,
   updateEndpoint,
 }: {
   /** Short product/app name — the sidebar logo and the breadcrumb root. */
@@ -129,12 +131,27 @@ export function CatalogShell<TId extends string>({
    *  or already up to date; the viewer treats all three identically: no footer, no banner, no
    *  update page content). */
   update?: UpdateNotice | null;
+  /** The installed version, whether automatic checks are on (and why), and the last check —
+   *  `dev` writes it at startup (`.ds-viewer/version.json`), and the shell refreshes it from the
+   *  local endpoint. With it, the sidebar always shows a version line and the update page offers
+   *  **Check now** and the automatic-check switch. Without it (an older generated workspace), the
+   *  footer appears only when an update is known, as before. */
+  versionStatus?: VersionStatus | null;
   /** The local endpoint's base URL and per-run secret — `dev` generates both (Task 18) and
    *  `writeWorkspace`'s generated entry file bakes them in (Task 17). Absent in a build that
    *  disables the endpoint entirely — `UpdatePanel` degrades to showing the plan/notice with no
    *  **Update now** button when this is missing. */
   updateEndpoint?: { baseUrl: string; secret: string };
 }) {
+  // A `BoundedOverlayViewport`'s own child document (design §5): render ONLY the one authored
+  // node this document's URL addresses, with no sidebar/breadcrumb/title/pager — never the whole
+  // page, since that page's other examples (and this same example's own viewport wrapper, now
+  // recognizing itself as the selected address) would otherwise render alongside it for nothing.
+  // Read once per mount, like `active`'s own initial read below: this mode is only ever entered by
+  // a fresh document load, never a same-document transition.
+  const overlayAddress = useMemo(() => (isWeb() ? overlayAddressFromSearch(window.location.search) : undefined), []);
+  const overlayNode = useMemo(() => (overlayAddress ? findOverlayNode(sections, overlayAddress) : undefined), [overlayAddress, sections]);
+
   const sectionsById = useMemo(() => new Map(sections.map((def) => [def.id, def])), [sections]);
   const labels = useMemo(() => new Map(sections.filter((def) => def.title).map((def) => [def.id as string, def.title as string])), [sections]);
   const order = useMemo(() => orderedIds(groups, new Set(sectionsById.keys())), [groups, sectionsById]);
@@ -198,28 +215,64 @@ export function CatalogShell<TId extends string>({
 
   const activeDef = active !== undefined && active !== UPDATE_PAGE_ID ? sectionsById.get(active) : undefined;
 
+  // The live version status: starts from what `dev` wrote at startup, then follows the local
+  // endpoint (a reload after **Check now** must not fall back to the startup snapshot).
+  const [liveStatus, setLiveStatus] = useState<VersionStatus | null>(versionStatus ?? null);
+  useEffect(() => {
+    if (!updateEndpoint || !isWeb()) return;
+    let cancelled = false;
+    fetch(`${updateEndpoint.baseUrl}/version`, { headers: { [DS_VIEWER_SECRET_HEADER]: updateEndpoint.secret } })
+      .then((res) => (res.ok ? (res.json() as Promise<VersionStatus>) : undefined))
+      .then((next) => {
+        if (next && !cancelled) setLiveStatus(next);
+      })
+      .catch(() => {
+        // The startup snapshot stays; the endpoint may be restarting.
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [updateEndpoint]);
+  // With a live status, it is the truth (it includes a **Check now** result); otherwise the
+  // startup notice, as before.
+  const effectiveUpdate: UpdateNotice | null = liveStatus ? liveStatus.update : update ?? null;
+
   const [dismissedMajor, setDismissedMajor] = useState<string | null>(() =>
     isWeb() ? window.localStorage.getItem('ds-viewer-dismissed-major') : null,
   );
   const dismissMajorBanner = useCallback(() => {
-    if (!update) return;
-    if (isWeb()) window.localStorage.setItem('ds-viewer-dismissed-major', update.latest);
-    setDismissedMajor(update.latest);
-  }, [update]);
-  const footer = footerLabel(update)
-    ? { label: footerLabel(update)!, active: active === UPDATE_PAGE_ID, onPress: () => select(UPDATE_PAGE_ID) }
-    : undefined;
+    if (!effectiveUpdate) return;
+    if (isWeb()) window.localStorage.setItem('ds-viewer-dismissed-major', effectiveUpdate.latest);
+    setDismissedMajor(effectiveUpdate.latest);
+  }, [effectiveUpdate]);
+  const link = footerLink(effectiveUpdate, liveStatus);
+  const footer = link ? { ...link, active: active === UPDATE_PAGE_ID, onPress: () => select(UPDATE_PAGE_ID) } : undefined;
   // Design: the banner shows on every *normal* page; once you're already looking at the update
   // page there is nothing left for "Review update" to do, so it's hidden there (confirmed against
   // the approved mockup's own `frame()`: the banner only ever renders when `!isPanel`).
-  const showBanner = active !== UPDATE_PAGE_ID && shouldShowMajorBanner(update, dismissedMajor);
+  const showBanner = active !== UPDATE_PAGE_ID && shouldShowMajorBanner(effectiveUpdate, dismissedMajor);
+
+  if (overlayAddress) {
+    return (
+      <View style={styles.overlayDocumentRoot}>
+        {overlayNode ?? <Text style={styles.overlayUnavailable}>This example is no longer available.</Text>}
+      </View>
+    );
+  }
 
   return (
     <View style={styles.root}>
       <CatalogSidebar logo={appName} logoImageSource={logoImageSource} caption={title} groups={groups} labels={labels} active={active} onPress={select} footer={footer} />
       <ScrollView ref={scrollRef} style={styles.main} contentContainerStyle={styles.mainContent}>
         {active === UPDATE_PAGE_ID ? (
-          <UpdatePanel update={update ?? null} endpoint={updateEndpoint} appName={appName} headingRef={headingRef} />
+          <UpdatePanel
+            update={effectiveUpdate}
+            versionStatus={liveStatus}
+            onVersionStatus={setLiveStatus}
+            endpoint={updateEndpoint}
+            appName={appName}
+            headingRef={headingRef}
+          />
         ) : activeDef ? (
           <SectionBlock
             key={activeDef.id}
@@ -229,7 +282,7 @@ export function CatalogShell<TId extends string>({
             // The approved mockup's own `PAGE_BG` order: crumb, then banner, then title — the
             // banner used to render above the breadcrumb instead (Important finding, Fable
             // correction pass).
-            banner={showBanner && update ? <MajorBanner update={update} onReviewUpdate={() => select(UPDATE_PAGE_ID)} onDismiss={dismissMajorBanner} /> : undefined}
+            banner={showBanner && effectiveUpdate ? <MajorBanner update={effectiveUpdate} onReviewUpdate={() => select(UPDATE_PAGE_ID)} onDismiss={dismissMajorBanner} /> : undefined}
             pager={{
               previousId: neighbors(order, activeDef.id).previous,
               nextId: neighbors(order, activeDef.id).next,
@@ -249,6 +302,10 @@ export function CatalogShell<TId extends string>({
 
 const styles = StyleSheet.create({
   root: { flex: 1, flexDirection: 'row', backgroundColor: CATALOG_COLOR.pageBackground },
+  // A `BoundedOverlayViewport` child document's own root: no sidebar/chrome, just the one
+  // addressed node — sized by whatever that node itself renders, not the catalog's own layout.
+  overlayDocumentRoot: { flex: 1 },
+  overlayUnavailable: { fontSize: CATALOG_TYPE.md, color: CATALOG_COLOR.textMuted, padding: CATALOG_SPACE.lg },
   main: { flex: 1 },
   mainContent: {
     width: '100%',

package/native/catalog/CatalogSidebar.tsx

@@ -43,7 +43,7 @@ function NavItem<TId extends string>({ id, label, active, onPress }: { id: TId;
   );
 }
 
-function FooterLink({ label, active, onPress }: { label: string; active: boolean; onPress: () => void }) {
+function FooterLink({ label, kind, active, onPress }: { label: string; kind: 'update' | 'version'; active: boolean; onPress: () => void }) {
   const [hovered, setHovered] = useState(false);
   const [focused, setFocused] = useState(false);
   return (
@@ -63,7 +63,8 @@ function FooterLink({ label, active, onPress }: { label: string; active: boolean
         focused && styles.focusRing,
       ]}
     >
-      <View style={styles.footerDot} />
+      {/* The dot marks an available update; the everyday version line is quiet. */}
+      {kind === 'update' && <View style={styles.footerDot} />}
       <Text style={[styles.footerLabel, active && styles.footerLabelActive]}>{label}</Text>
     </Pressable>
   );
@@ -96,10 +97,10 @@ export function CatalogSidebar<TId extends string>({
   labels?: ReadonlyMap<string, string>;
   active: string | undefined;
   onPress: (id: TId) => void;
-  /** The quiet update-notice link below the nav list (design §5's footer line), or `undefined`
-   *  when there is no update to show. `active` is true while the update page itself is open — it
-   *  gets the same active styling a selected nav item would. */
-  footer?: { label: string; active: boolean; onPress: () => void };
+  /** The link below the nav list that opens the update page: the installed version (`'version'`),
+   *  or the update notice with a dot (`'update'`, design §5's footer line). `active` is true while
+   *  the update page itself is open — it gets the same active styling a selected nav item would. */
+  footer?: { label: string; kind?: 'update' | 'version'; active: boolean; onPress: () => void };
 }) {
   const [query, setQuery] = useState('');
   // A bundled local image (the only kind `cli/workspace.ts` ever produces — see its doc comment
@@ -201,7 +202,7 @@ export function CatalogSidebar<TId extends string>({
       </ScrollView>
       {footer && (
         <View style={styles.footerContainer}>
-          <FooterLink label={footer.label} active={footer.active} onPress={footer.onPress} />
+          <FooterLink label={footer.label} kind={footer.kind ?? 'update'} active={footer.active} onPress={footer.onPress} />
         </View>
       )}
     </View>

package/native/catalog/ComparisonGrid.tsx

@@ -65,8 +65,8 @@ export function ComparisonGrid({
               const cell = cells.get(cellKey(row.key, c.key));
               return (
                 cell?.node !== undefined ? (
-                  <SpecimenSurface key={c.key} role="cell" surface={surface} style={[styles.cell, column, styles.bodyRow, styles.specimenCell, ci === lastColumn && styles.lastColumn]}>
-                    <SpecimenContent fill={cell.fill}>{cell.node}</SpecimenContent>
+                  <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>
                   </SpecimenSurface>
                 ) : (
                   <View key={c.key} role="cell" style={[styles.cell, column, styles.bodyRow, styles.specimenCell, ci === lastColumn && styles.lastColumn]}>

package/native/catalog/ComparisonGroups.tsx

@@ -47,8 +47,8 @@ export function ComparisonGroups({
                     <View style={styles.caption}>
                       <Text style={styles.captionText}>{item.label}</Text>
                     </View>
-                    <SpecimenSurface surface={surface} style={styles.specimen}>
-                      <SpecimenContent fill={item.fill}>{item.node as React.ReactNode}</SpecimenContent>
+                    <SpecimenSurface surface={item.surface ?? surface} style={styles.specimen}>
+                      <SpecimenContent fill={item.fill} align={item.align}>{item.node as React.ReactNode}</SpecimenContent>
                     </SpecimenSurface>
                   </View>
                 );

package/native/catalog/ComparisonList.tsx

@@ -61,8 +61,8 @@ export function ComparisonList({
                   <View style={styles.caption}>
                     <Text style={styles.captionText}>{item.label}</Text>
                   </View>
-                  <SpecimenSurface surface={surface} style={styles.specimen}>
-                    <SpecimenContent fill={item.fill}>{item.node as React.ReactNode}</SpecimenContent>
+                  <SpecimenSurface surface={item.surface ?? surface} style={styles.specimen}>
+                    <SpecimenContent fill={item.fill} align={item.align}>{item.node as React.ReactNode}</SpecimenContent>
                   </SpecimenSurface>
                 </View>
               );

package/native/catalog/PhoneFrame.tsx

@@ -16,6 +16,11 @@ const HEIGHT = 480;
  * `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.
+ *
+ * `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`.
  */
 export function PhoneFrame({ children }: { children: React.ReactNode }) {
   return <View style={styles.frame}>{children}</View>;
@@ -33,5 +38,6 @@ const styles = StyleSheet.create({
     overflow: 'hidden',
     alignItems: 'center',
     justifyContent: 'center',
+    alignSelf: 'center',
   },
 });

package/native/catalog/ReferenceDetails.tsx

@@ -1,9 +1,9 @@
 import React, { useState } from 'react';
-import { View, Text, StyleSheet, type LayoutChangeEvent } from 'react-native';
+import { View, Text, StyleSheet, type LayoutChangeEvent, type TextStyle } from 'react-native';
 import { CATALOG_COLOR, CATALOG_LAYOUT, CATALOG_RADIUS, CATALOG_SPACE, CATALOG_TYPE } from './tokens';
 import { PropsTable } from './PropsTable';
-import { propsColumns } from './comparison';
-import type { SectionDef } from './types';
+import { propsColumns, referenceColumns } from './comparison';
+import type { ComposedOfEntry, SectionDef } from './types';
 
 // react-native-web reads `aria-level`; React Native's prop types do not declare it.
 const HEADING_LEVEL_2 = { 'aria-level': 2 } as Record<string, unknown>;
@@ -40,13 +40,51 @@ function PropsBox<TId extends string>({ def }: { def: SectionDef<TId> }) {
   );
 }
 
+// `built-in` is composition's assumed default relationship, so spelling it out reads redundantly
+// (e.g. "TrainArrivalRemainingTime · built-in"); `slot`/`related` still need their own suffix to
+// stay distinguishable from a plain built-in entry.
+function compositionLabel(entry: ComposedOfEntry): string {
+  return entry.relationship === 'built-in' ? entry.component : `${entry.component} · ${entry.relationship}`;
+}
+
+function CompositionFacts({ composedOf }: { composedOf: ComposedOfEntry[] }) {
+  return (
+    <>
+      {composedOf.map((entry, i) => (
+        <Fact key={`${entry.component}-${entry.relationship}-${i}`} label={compositionLabel(entry)} value={entry.role} />
+      ))}
+    </>
+  );
+}
+
 /**
- * Always-visible reference below a page's specimens: a card with Guidance and Quick reference
- * (source path, accessibility), then Props in their own box. Token galleries show only Quick
- * reference with the source path. No collapse control by design.
+ * Always-visible reference below a page's specimens: a card with Guidance, Quick reference
+ * (source path, accessibility), and — only when the page has confirmed composition to disclose —
+ * Composition, then Props in their own box. Token galleries show only Quick reference with the
+ * source path. No collapse control by design.
+ *
+ * Guidance/Quick reference/Composition lay out from the card's own measured INNER width
+ * (`referenceColumns`), not viewport width alone: three columns only when there is confirmed
+ * composition and the card is wide enough for all three (Composition gets its own column only
+ * then — otherwise it stays nested under Quick reference, as it always has); two when there's
+ * room for Guidance and Quick reference side by side; one (stacked, full document order, nothing
+ * dropped) when the card is too narrow even for two. `minWidth: 0` on every column lets its facts
+ * and source path actually shrink and wrap at that width instead of pushing the card wider than
+ * its own container.
+ *
+ * `onLayout` sits on the `columns` row itself, not the padded/bordered `card` around it:
+ * `referenceColumns` fits each column against `REFERENCE_MIN_COLUMN_WIDTH`, an INNER measurement —
+ * the card's own padding (`panelPadding`) and 1px border never belong in that budget. Measuring the
+ * outer card previously fed `referenceColumns` an outer width up to ~42px wider than what the three
+ * columns' content actually has, which can report a column count the inner content doesn't fit.
  */
 export function ReferenceDetails<TId extends string>({ def }: { def: SectionDef<TId> }) {
   const hide = def.hide ?? {};
+  const [width, setWidth] = useState(0);
+  const onLayout = (event: LayoutChangeEvent) => {
+    const next = Math.round(event.nativeEvent.layout.width);
+    if (next > 0 && next !== width) setWidth(next);
+  };
   if (def.tokenGallery) {
     return (
       <View style={styles.card}>
@@ -55,27 +93,37 @@ export function ReferenceDetails<TId extends string>({ def }: { def: SectionDef<
       </View>
     );
   }
+  const hasComposition = Boolean(def.composedOf && def.composedOf.length > 0);
+  const columns = referenceColumns(width, hasComposition);
+  const stacked = columns === 1;
+  const compositionIsOwnColumn = columns === 3 && hasComposition;
+  const columnStyle = stacked ? styles.columnStacked : styles.column;
+
   return (
     <View style={styles.stack}>
       <View style={styles.card}>
-        <View style={styles.columns}>
-          <View style={styles.column}>
+        <View style={[styles.columns, stacked && styles.columnsStacked]} onLayout={onLayout}>
+          <View style={columnStyle}>
             <Text role="heading" {...HEADING_LEVEL_2} style={styles.heading}>Guidance</Text>
             <Text style={styles.body}>{def.whenToUse ?? 'No usage guidance documented.'}</Text>
           </View>
-          <View style={styles.column}>
+          <View style={columnStyle}>
             <Text role="heading" {...HEADING_LEVEL_2} style={styles.heading}>Quick reference</Text>
             {def.path && <Fact label="Source" value={def.path} mono />}
             {!hide.accessibility && <Fact label="Accessibility" value={def.a11y ?? 'No accessibility notes documented.'} />}
-            {def.composedOf && def.composedOf.length > 0 && (
+            {!compositionIsOwnColumn && hasComposition && def.composedOf && (
               <>
                 <Text style={styles.subheading}>Composition</Text>
-                {def.composedOf.map((entry, i) => (
-                  <Fact key={`${entry.component}-${entry.relationship}-${i}`} label={`${entry.component} · ${entry.relationship}`} value={entry.role} />
-                ))}
+                <CompositionFacts composedOf={def.composedOf} />
               </>
             )}
           </View>
+          {compositionIsOwnColumn && def.composedOf && (
+            <View style={columnStyle}>
+              <Text role="heading" {...HEADING_LEVEL_2} style={styles.heading}>Composition</Text>
+              <CompositionFacts composedOf={def.composedOf} />
+            </View>
+          )}
         </View>
       </View>
       {!hide.props && <PropsBox def={def} />}
@@ -93,7 +141,9 @@ const styles = StyleSheet.create({
     padding: CATALOG_LAYOUT.panelPadding,
   },
   columns: { flexDirection: 'row', gap: CATALOG_SPACE['2xl'] },
-  column: { flex: 1 },
+  columnsStacked: { flexDirection: 'column' },
+  column: { flex: 1, minWidth: 0 },
+  columnStacked: { minWidth: 0 },
   heading: {
     fontSize: CATALOG_TYPE.panelHeading,
     fontWeight: '700',
@@ -111,15 +161,20 @@ const styles = StyleSheet.create({
     marginBottom: CATALOG_SPACE.xs,
   },
   fact: {
-    flexDirection: 'row',
-    justifyContent: 'space-between',
-    gap: CATALOG_SPACE.lg,
+    flexDirection: 'column',
+    gap: CATALOG_SPACE.xs,
     paddingVertical: CATALOG_LAYOUT.factPaddingY,
     borderBottomWidth: 1,
     borderBottomColor: CATALOG_COLOR.borderSubtle,
   },
-  factLabel: { fontSize: CATALOG_TYPE.md, fontWeight: '700', color: CATALOG_COLOR.text },
-  factValue: { flex: 1, fontSize: CATALOG_TYPE.md, lineHeight: 20, textAlign: 'right', color: CATALOG_COLOR.textMuted },
-  mono: { fontFamily: CATALOG_COLOR.code },
+  factLabel: { flexShrink: 1, minWidth: 0, fontSize: CATALOG_TYPE.md, fontWeight: '700', color: CATALOG_COLOR.text },
+  factValue: { minWidth: 0, fontSize: CATALOG_TYPE.md, lineHeight: 20, textAlign: 'left', color: CATALOG_COLOR.textMuted },
+  // `wordBreak` isn't in the installed `TextStyle` type (RN's own, not RNW's — RNW's own
+  // `Text/types.js` declares it; a browser applies any valid CSS property name it recognizes
+  // regardless), so a bare literal here would report an unknown property under `--noEmit` even
+  // though it genuinely works: a long unbroken token (a source path with no spaces, e.g.
+  // `AnimatedChevron.tsx`) has no space for the browser's default line-breaking to use, so without
+  // this it stays one unbroken run and overflows a narrow card instead of wrapping at its '/'s.
+  mono: { fontFamily: CATALOG_COLOR.code, wordBreak: 'break-word' } as TextStyle,
   empty: { fontSize: CATALOG_TYPE.sm, fontStyle: 'italic', color: CATALOG_COLOR.textMuted },
 });