@krapwoo/ds-viewer 0.4.6 → 0.4.8

package/dist/cli/staticPage.js

@@ -140,7 +140,7 @@ function readStaticPage(file) {
         else
             page.checkable = false;
     }
-    const variants = readSlotItems(findProp(pageObject, 'variants'), consts);
+    const variants = readSlotItems(findProp(pageObject, 'variants'), consts, page.component, sourceFile);
     if (!variants.checkable)
         page.checkable = false;
     else {
@@ -148,7 +148,7 @@ function readStaticPage(file) {
         page.variantsItemsFill = variants.itemsFill;
         page.variantsMaxColumns = variants.maxColumns;
     }
-    const states = readSlotItems(findProp(pageObject, 'states'), consts);
+    const states = readSlotItems(findProp(pageObject, 'states'), consts, page.component, sourceFile);
     if (!states.checkable)
         page.checkable = false;
     else {
@@ -156,8 +156,42 @@ function readStaticPage(file) {
         page.statesItemsFill = states.itemsFill;
         page.statesMaxColumns = states.maxColumns;
     }
+    const composedOfProp = findProp(pageObject, 'composedOf');
+    page.hasComposedOf = composedOfProp !== undefined;
+    if (composedOfProp)
+        page.composedOf = readComposedOf(composedOfProp.initializer, consts);
+    const intentionalStaticPreviewProp = findProp(pageObject, 'intentionalStaticPreview');
+    if (intentionalStaticPreviewProp) {
+        const resolved = resolve(intentionalStaticPreviewProp.initializer, consts, new Set());
+        if (ts.isObjectLiteralExpression(resolved)) {
+            const reasonProp = findProp(resolved, 'reason');
+            if (reasonProp)
+                page.intentionalStaticPreviewReason = stringLiteral(resolve(reasonProp.initializer, consts, new Set()));
+        }
+    }
     return page;
 }
+/** A literal array of `ComposedOfEntry`-shaped object literals, read down to just `component`
+ *  (design §4: role/relationship are authored prose `doctor` never needs for its missing-
+ *  composition comparison). Undefined — not an empty array — for anything that isn't itself a
+ *  literal array, or whose element isn't an object literal with a literal `component`: `doctor`
+ *  must never mistake "couldn't read this" for "author declared no composition here". */
+function readComposedOf(node, consts) {
+    const resolved = resolve(node, consts, new Set());
+    if (!ts.isArrayLiteralExpression(resolved))
+        return undefined;
+    const entries = [];
+    for (const element of resolved.elements) {
+        const resolvedElement = resolve(element, consts, new Set());
+        if (!ts.isObjectLiteralExpression(resolvedElement))
+            return undefined;
+        const component = propertyStringLiteral(resolvedElement, 'component', consts);
+        if (component === undefined)
+            return undefined;
+        entries.push({ component });
+    }
+    return entries;
+}
 /** Local name -> imported name, for every named import from `moduleSpecifier`. */
 function importedNames(sourceFile, moduleSpecifier) {
     const names = new Map();
@@ -219,6 +253,20 @@ function resolve(node, consts, seen) {
 function stringLiteral(node) {
     return ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node) ? node.text : undefined;
 }
+/** `true`/`false` only from a known `true`/`false` literal; any other expression (a variable, a
+ *  computed value) stays `undefined` rather than being misread as `false`. Unlike the page's own
+ *  `hide.*`/`tokenGallery`/`itemsFill`/`wide` booleans — which intentionally treat "not literally
+ *  `true`" as `false`, since those already default to `false` when omitted — `fill`'s own default
+ *  is inherited (`SpecimenPresentation.fill` defaults to the slot's `itemsFill`, not to `false`),
+ *  so a non-literal value here must stay honestly unknown instead of claiming "not filling". */
+function literalBooleanOrUnknown(node, consts) {
+    const resolved = resolve(node, consts, new Set());
+    if (resolved.kind === ts.SyntaxKind.TrueKeyword)
+        return true;
+    if (resolved.kind === ts.SyntaxKind.FalseKeyword)
+        return false;
+    return undefined;
+}
 function propertyName(name) {
     return ts.isIdentifier(name) || ts.isStringLiteral(name) ? name.text : name.getText();
 }
@@ -271,6 +319,34 @@ function readAxis(node, consts) {
     }
     return undefined;
 }
+/** A literal array of `ComparisonCell`-shaped object literals: `rowKey`/`columnKey` required
+ *  (string literals only), `surface`/`align`/`fill` read the same per-field-lenient way
+ *  `readListItems` reads them. `node`/`unavailableReason` are never inspected — design §4 never
+ *  evaluates a cell's specimen node. Undefined (no cell metadata at all, not "every field unset")
+ *  for anything that isn't itself a literal array, or whose element isn't itself an object literal
+ *  with literal `rowKey`/`columnKey` — a `.flatMap()`-built `cells` array (the starter kit's own
+ *  convention for a `grid()`-free literal comparison) stays unrepresented rather than guessed at. */
+function readComparisonCells(node, consts) {
+    const resolved = resolve(node, consts, new Set());
+    if (!ts.isArrayLiteralExpression(resolved))
+        return undefined;
+    const cells = [];
+    for (const element of resolved.elements) {
+        const resolvedElement = resolve(element, consts, new Set());
+        if (!ts.isObjectLiteralExpression(resolvedElement))
+            return undefined;
+        const rowKey = propertyStringLiteral(resolvedElement, 'rowKey', consts);
+        const columnKey = propertyStringLiteral(resolvedElement, 'columnKey', consts);
+        if (rowKey === undefined || columnKey === undefined)
+            return undefined;
+        const surface = propertyStringLiteral(resolvedElement, 'surface', consts);
+        const align = propertyStringLiteral(resolvedElement, 'align', consts);
+        const fillProp = findProp(resolvedElement, 'fill');
+        const fill = fillProp ? literalBooleanOrUnknown(fillProp.initializer, consts) : undefined;
+        cells.push({ rowKey, columnKey, surface, align, fill });
+    }
+    return cells;
+}
 /** A page's `comparison` field: either a direct `ComparisonDef`-shaped object literal, or (the
  *  starter kit's own convention since Task 1/2) a call to this package's own `grid()` helper — the
  *  one call shape this reader specially recognizes, reading its `rows`/`columns` arguments and
@@ -305,12 +381,14 @@ function readComparison(node, consts, gridNames) {
         const rowLabelProp = findProp(resolved, 'rowLabel');
         const columnLabelProp = findProp(resolved, 'columnLabel');
         const sizeProp = findProp(resolved, 'size');
+        const cellsProp = findProp(resolved, 'cells');
         return {
             rowLabel: rowLabelProp ? stringLiteral(resolve(rowLabelProp.initializer, consts, new Set())) : undefined,
             columnLabel: columnLabelProp ? stringLiteral(resolve(columnLabelProp.initializer, consts, new Set())) : undefined,
             rows,
             columns,
             size: sizeProp ? stringLiteral(resolve(sizeProp.initializer, consts, new Set())) : undefined,
+            cells: cellsProp ? readComparisonCells(cellsProp.initializer, consts) : undefined,
         };
     }
     return undefined;
@@ -318,7 +396,7 @@ function readComparison(node, consts, gridNames) {
 /** A literal array of list-item object literals — `key`/`name` required; `props` (read as a flat
  *  literal map, non-literal values simply omitted) and `group` optional. Each item's `node` field
  *  (always present, always JSX) is never inspected — reading the sibling fields never depends on it. */
-function readListItems(node, consts) {
+function readListItems(node, consts, componentName, sourceFile) {
     const resolved = resolve(node, consts, new Set());
     if (!ts.isArrayLiteralExpression(resolved))
         return undefined;
@@ -333,10 +411,154 @@ function readListItems(node, consts) {
             return undefined;
         const group = propertyStringLiteral(resolvedElement, 'group', consts);
         const propsProp = findProp(resolvedElement, 'props');
-        items.push({ key, name, group, props: propsProp ? readLiteralProps(propsProp.initializer, consts) : undefined });
+        const fillProp = findProp(resolvedElement, 'fill');
+        const fill = fillProp ? literalBooleanOrUnknown(fillProp.initializer, consts) : undefined;
+        const surface = propertyStringLiteral(resolvedElement, 'surface', consts);
+        const align = propertyStringLiteral(resolvedElement, 'align', consts);
+        const nodeProp = findProp(resolvedElement, 'node');
+        const nodeExample = nodeProp ? readNodeExample(nodeProp.initializer, consts, componentName, sourceFile) : {};
+        items.push({
+            key, name, group, props: propsProp ? readLiteralProps(propsProp.initializer, consts) : undefined, fill, surface, align,
+            ...nodeExample,
+        });
     }
     return items;
 }
+/** Generic, additive reading of one item's own `node:` JSX (design §3, plan Task 3) — used only by
+ *  `cli/doctor.ts`'s interactive-preview advisory. Never evaluates `node`; only reads its literal
+ *  AST shape. `node` matching `componentName` by plain tag-name text (not module resolution — this
+ *  reader never resolves imports) means "a direct instance of the documented component": its own
+ *  JSX attributes are read generically (`nodeAttributes`). Any other JSX tag is checked only for
+ *  whether it's a confidently-identified, genuinely stateful same-file wrapper
+ *  (`nodeStatefulWrapper`) — never asserted one way or the other when that can't be confirmed.
+ *  Anything that isn't a direct JSX element at all (`null`, a conditional, a function call, …)
+ *  leaves every field unset. */
+function readNodeExample(node, consts, componentName, sourceFile) {
+    const resolved = resolve(node, consts, new Set());
+    let element;
+    if (ts.isJsxSelfClosingElement(resolved))
+        element = resolved;
+    else if (ts.isJsxElement(resolved))
+        element = resolved.openingElement;
+    if (!element || !ts.isIdentifier(element.tagName))
+        return {};
+    const tagText = element.tagName.text;
+    if (componentName !== undefined && tagText === componentName) {
+        const nodeAttributes = {};
+        for (const attribute of element.attributes.properties) {
+            // Skips a spread attribute ({...rest}) and a namespaced name (xml:lang) — unreadable,
+            // never a reason to reject the whole item.
+            if (!ts.isJsxAttribute(attribute) || !ts.isIdentifier(attribute.name))
+                continue;
+            nodeAttributes[attribute.name.text] = readJsxAttributeValue(attribute, consts);
+        }
+        return { nodeDirectComponent: tagText, nodeAttributes };
+    }
+    return { nodeStatefulWrapper: sameFileWrapperHasUseState(sourceFile, tagText) ? true : undefined };
+}
+/** One JSX attribute's value, as a `StaticAttributeValue`. A shorthand attribute (`disabled`, no
+ *  `initializer` at all — equivalent to `disabled={true}`) is a literal `true`. */
+function readJsxAttributeValue(attribute, consts) {
+    if (!attribute.initializer)
+        return { kind: 'literal', value: true };
+    if (ts.isStringLiteral(attribute.initializer))
+        return { kind: 'literal', value: attribute.initializer.text };
+    if (!ts.isJsxExpression(attribute.initializer) || !attribute.initializer.expression)
+        return { kind: 'unknown' };
+    const resolved = resolve(attribute.initializer.expression, consts, new Set());
+    if (ts.isStringLiteral(resolved) || ts.isNoSubstitutionTemplateLiteral(resolved))
+        return { kind: 'literal', value: resolved.text };
+    if (ts.isNumericLiteral(resolved))
+        return { kind: 'literal', value: Number(resolved.text) };
+    if (resolved.kind === ts.SyntaxKind.TrueKeyword)
+        return { kind: 'literal', value: true };
+    if (resolved.kind === ts.SyntaxKind.FalseKeyword)
+        return { kind: 'literal', value: false };
+    if (ts.isIdentifier(resolved) && resolved.text === 'undefined')
+        return { kind: 'no-op-callback' };
+    if ((ts.isArrowFunction(resolved) || ts.isFunctionExpression(resolved)) && isEmptyFunctionBody(resolved.body)) {
+        return { kind: 'no-op-callback' };
+    }
+    return { kind: 'unknown' };
+}
+function isEmptyFunctionBody(body) {
+    return ts.isBlock(body) && body.statements.length === 0;
+}
+/** True only when `sourceFile` declares a top-level function (declaration, or a `const`/`let`
+ *  initialized with a function/arrow expression) named `tagName` whose own body contains a call to
+ *  a *source-backed* React `useState`/`React.useState` — a confidently-identified, genuinely
+ *  stateful wrapper. Walking only that one function's own body (never the whole file) keeps this
+ *  scoped the same way `cli/props.ts`'s composedOfCandidate reader scopes its own JSX walk to one
+ *  implementation. */
+function sameFileWrapperHasUseState(sourceFile, tagName) {
+    const bindings = reactUseStateBindings(sourceFile);
+    for (const statement of sourceFile.statements) {
+        let body;
+        if (ts.isFunctionDeclaration(statement) && statement.name?.text === tagName)
+            body = statement.body;
+        else if (ts.isVariableStatement(statement)) {
+            for (const declaration of statement.declarationList.declarations) {
+                if (ts.isIdentifier(declaration.name) && declaration.name.text === tagName && declaration.initializer &&
+                    (ts.isArrowFunction(declaration.initializer) || ts.isFunctionExpression(declaration.initializer))) {
+                    body = declaration.initializer.body;
+                }
+            }
+        }
+        if (body && containsUseStateCall(body, bindings))
+            return true;
+    }
+    return false;
+}
+/** This file's own top-level `import ... from 'react'` bindings relevant to recognizing a genuine
+ *  `useState` call — never a type-checker resolution, only the same-file import syntax, matching
+ *  this reader's existing "never resolves imports across files" contract. `namedUseState` holds
+ *  every local name bound to the real named `useState` export (an alias, e.g. `import { useState as
+ *  useReactState }`, included); `reactNamespace` holds every local name bound to the whole `react`
+ *  module (a default or `* as` import) that a `React.useState(...)` call could be written through.
+ *  A locally-defined `useState` (no matching import) or an unrelated object's own `.useState` method
+ *  binds to neither set and so is never counted — left uncheckable, never asserted stateful. */
+function reactUseStateBindings(sourceFile) {
+    const namedUseState = new Set();
+    const reactNamespace = new Set();
+    for (const statement of sourceFile.statements) {
+        if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier) || statement.moduleSpecifier.text !== 'react')
+            continue;
+        const clause = statement.importClause;
+        if (!clause)
+            continue;
+        if (clause.name)
+            reactNamespace.add(clause.name.text);
+        if (clause.namedBindings && ts.isNamespaceImport(clause.namedBindings))
+            reactNamespace.add(clause.namedBindings.name.text);
+        else if (clause.namedBindings && ts.isNamedImports(clause.namedBindings)) {
+            for (const element of clause.namedBindings.elements) {
+                if ((element.propertyName ?? element.name).text === 'useState')
+                    namedUseState.add(element.name.text);
+            }
+        }
+    }
+    return { namedUseState, reactNamespace };
+}
+function containsUseStateCall(node, bindings) {
+    let found = false;
+    const visit = (n) => {
+        if (found)
+            return;
+        if (ts.isCallExpression(n)) {
+            const callee = n.expression;
+            const isNamedUseState = ts.isIdentifier(callee) && bindings.namedUseState.has(callee.text);
+            const isReactNamespaceUseState = ts.isPropertyAccessExpression(callee) && callee.name.text === 'useState' &&
+                ts.isIdentifier(callee.expression) && bindings.reactNamespace.has(callee.expression.text);
+            if (isNamedUseState || isReactNamespaceUseState) {
+                found = true;
+                return;
+            }
+        }
+        ts.forEachChild(n, visit);
+    };
+    visit(node);
+    return found;
+}
 function readLiteralProps(node, consts) {
     const resolved = resolve(node, consts, new Set());
     if (!ts.isObjectLiteralExpression(resolved))
@@ -365,14 +587,14 @@ function readLiteralProps(node, consts) {
  *  literal — like `previewWidths`/`fullWidthLabel`, it isn't in the original literal-checkable
  *  list, so a non-literal `itemsFill` is simply left unset. `maxColumns` does affect the geometry
  *  `explain` reports, so it must be a literal integer from 1–5 or the page is not checkable. */
-function readSlotItems(prop, consts) {
+function readSlotItems(prop, consts, componentName, sourceFile) {
     if (!prop)
         return { checkable: true };
     const resolved = resolve(prop.initializer, consts, new Set());
     const itemsProp = ts.isObjectLiteralExpression(resolved) ? findProp(resolved, 'items') : undefined;
     if (!itemsProp)
         return { checkable: false };
-    const items = readListItems(itemsProp.initializer, consts);
+    const items = readListItems(itemsProp.initializer, consts, componentName, sourceFile);
     if (!items)
         return { checkable: false };
     const itemsFillProp = ts.isObjectLiteralExpression(resolved) ? findProp(resolved, 'itemsFill') : 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[]`
@@ -183,8 +189,19 @@ export function remainingStates(states, comparison) {
 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 }));
+/** 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, 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) {
@@ -198,12 +215,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, 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));
@@ -250,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) {
@@ -264,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) {
@@ -297,3 +316,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

@@ -6,6 +6,8 @@ import { CatalogSidebar } from './CatalogSidebar';
 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`
@@ -142,6 +144,15 @@ export function CatalogShell<TId extends string>({
    *  **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]);
@@ -242,6 +253,17 @@ export function CatalogShell<TId extends string>({
   // the approved mockup's own `frame()`: the banner only ever renders when `!isPanel`).
   const showBanner = active !== UPDATE_PAGE_ID && shouldShowMajorBanner(effectiveUpdate, dismissedMajor);
 
+  if (overlayAddress) {
+    return (
+      <View style={styles.overlayDocumentRoot}>
+        {/* 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>
+    );
+  }
+
   return (
     <View style={styles.root}>
       <CatalogSidebar logo={appName} logoImageSource={logoImageSource} caption={title} groups={groups} labels={labels} active={active} onPress={select} footer={footer} />
@@ -284,6 +306,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/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';
 
@@ -65,8 +67,10 @@ 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]}>
+                    <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));
@@ -47,8 +51,10 @@ 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}>
+                      <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>
                 );