@krapwoo/ds-viewer 0.10.0 → 0.12.0

package/native/catalog/SectionBlock.tsx

@@ -1,5 +1,5 @@
 import React, { useEffect, useMemo, useState } from 'react';
-import { View, Text, Pressable, StyleSheet, type LayoutChangeEvent } from 'react-native';
+import { View, Text, Pressable, StyleSheet, type LayoutChangeEvent, type TextStyle } from 'react-native';
 import { CATALOG_COLOR, CATALOG_LAYOUT, CATALOG_RADIUS, CATALOG_SPACE, CATALOG_TEXT } from './tokens';
 import { ComparisonGrid } from './ComparisonGrid';
 import { ComparisonGroups } from './ComparisonGroups';
@@ -53,7 +53,7 @@ export interface SectionPager<TId extends string> {
   labelOf?: (id: TId) => string;
 }
 
-function PagerButton<TId extends string>({
+export function PagerButton<TId extends string>({
   direction,
   targetId,
   onNavigate,
@@ -209,7 +209,40 @@ function placementBlock(block: PresentationBlock, height: number): PlacementBloc
  * are never recorded while side by side, so the decision never feeds on its own result; a width
  * change returns to stacked and decides again.
  */
-function Blocks<TId extends string>({ blocks, def, surface }: { blocks: PresentationBlock[]; def: SectionDef<TId>; surface: SpecimenSurfaceKind }) {
+/** The previous/next pager buttons, in their row — shared by `SectionBlock` and `FamilyPage` so a
+ *  family page's own page head gets the same pager chrome as every other page. */
+export function SectionPagerRow<TId extends string>({ pager }: { pager: SectionPager<TId> }) {
+  return (
+    <View style={styles.pager}>
+      <PagerButton direction="previous" targetId={pager.previousId} onNavigate={pager.onNavigate} labelOf={pager.labelOf} />
+      <PagerButton direction="next" targetId={pager.nextId} onNavigate={pager.onNavigate} labelOf={pager.labelOf} />
+    </View>
+  );
+}
+
+/** The page's specimen blocks (grid, grouped rows, list, or preview), stacked or side by side —
+ *  exported so `FamilyPage` can render a member's own specimens through the exact same placement
+ *  logic a normal page's blocks use, rather than a second copy of it. */
+export function Blocks<TId extends string>({
+  blocks,
+  def,
+  surface,
+  showLabels = true,
+  trimOuterMargin = false,
+}: {
+  blocks: PresentationBlock[];
+  def: SectionDef<TId>;
+  surface: SpecimenSurfaceKind;
+  /** V2b item 4: a family member's own specimens render with no uppercase "Variants" / "States /
+   *  configurations" block label — v8 has none inside a member block. A page's own `SectionBlock`
+   *  keeps its labels (the default, unchanged). */
+  showLabels?: boolean;
+  /** V2b item 5: drops this component's own page-level `marginBottom` — `FamilyPage`'s own
+   *  wrapper (`memberSpecimens`) supplies the exact spacing a member block needs instead, so the
+   *  two never double-stack. A page's own `SectionBlock` keeps the margin (the default,
+   *  unchanged). */
+  trimOuterMargin?: boolean;
+}) {
   const [available, setAvailable] = useState(0);
   const [heights, setHeights] = useState<number[]>([]);
   const [placement, setPlacement] = useState<'side' | 'stacked'>('stacked');
@@ -248,15 +281,22 @@ function Blocks<TId extends string>({ blocks, def, surface }: { blocks: Presenta
 
   const side = placement === 'side';
   return (
-    <View onLayout={onContainerLayout} style={[styles.blocks, side && styles.blocksSide]}>
+    <View onLayout={onContainerLayout} style={[styles.blocks, side && styles.blocksSide, trimOuterMargin && styles.blocksNoMargin]}>
       {blocks.map((block, i) => (
         <View
-          key={block.title || block.kind}
+          // A4: keyed by index, not `block.title || block.kind` — a member that sets the same
+          // `axis` on both `variants` and `states` now produces two blocks with identical titles,
+          // which would otherwise collide as React keys (as the family-section list already keys
+          // by index for the same reason — FamilyPage.tsx).
+          key={`${block.kind}-${i}`}
           onLayout={onBlockLayout(i)}
           // Side by side, each block fills its own half: a card always fills the column it is given.
           style={side ? styles.blockFill : undefined}
         >
-          {block.title ? <Text style={styles.blockLabel}>{block.title}</Text> : null}
+          {/* A3: `axis` now reaches grid/grouped blocks too (not only list), so any block kind
+              carrying one shows its (already informative) title on a family page, which otherwise
+              hides every generic block label via `showLabels={false}`. */}
+          {(showLabels && block.title) || ('axis' in block && block.axis) ? <Text style={styles.blockLabel}>{('axis' in block && block.axis) || block.title}</Text> : null}
           <BlockContent block={block} def={def} surface={surface} />
         </View>
       ))}
@@ -318,12 +358,7 @@ export function SectionBlock<TId extends string>({
           )}
           <Text style={styles.desc}>{def.description}</Text>
         </View>
-        {pager && (
-          <View style={styles.pager}>
-            <PagerButton direction="previous" targetId={pager.previousId} onNavigate={pager.onNavigate} labelOf={pager.labelOf} />
-            <PagerButton direction="next" targetId={pager.nextId} onNavigate={pager.onNavigate} labelOf={pager.labelOf} />
-          </View>
-        )}
+        {pager && <SectionPagerRow pager={pager} />}
       </View>
 
       {blocks.length > 0 && <Blocks blocks={blocks} def={def} surface={surface} />}
@@ -356,7 +391,15 @@ const styles = StyleSheet.create({
     backgroundColor: CATALOG_COLOR.surface,
   },
   osBadgeText: { ...CATALOG_TEXT.microLabel, color: CATALOG_COLOR.text },
-  title: { ...CATALOG_TEXT.pageTitle, color: CATALOG_COLOR.text, marginBottom: 5 },
+  // `wordBreak` isn't declared on React Native's own `TextStyle` (react-native-web's own
+  // `Text/types.js` declares it; a browser applies any valid CSS property name it recognizes
+  // regardless — same caveat ReferenceDetails.tsx's own `mono` style documents), so this is cast
+  // the same way. Without it, an unbroken page title (a component identifier with no spaces,
+  // e.g. `TranscriptVideoPreviewPlayerView`) has no space for the browser's default line-breaking
+  // to use: it stays one unbroken run at its full intrinsic width — wide enough to push past
+  // `titleText`'s own column and into the pager — instead of wrapping inside the column like any
+  // title with spaces already does.
+  title: { ...CATALOG_TEXT.pageTitle, color: CATALOG_COLOR.text, marginBottom: 5, wordBreak: 'break-word' } as TextStyle,
   desc: { ...CATALOG_TEXT.body, color: CATALOG_COLOR.textMuted, maxWidth: 700 },
   pager: { flexDirection: 'row', gap: 6, flexShrink: 0 },
   pagerButton: {
@@ -375,6 +418,7 @@ const styles = StyleSheet.create({
   pagerGlyph: { ...CATALOG_TEXT.icon, color: CATALOG_COLOR.text },
   pagerGlyphDisabled: { color: CATALOG_COLOR.textMuted },
   blocks: { gap: CATALOG_LAYOUT.blockGap, marginBottom: CATALOG_LAYOUT.blockGap },
+  blocksNoMargin: { marginBottom: 0 },
   blocksSide: { flexDirection: 'row', alignItems: 'flex-start' },
   blockFill: { flex: 1, minWidth: 0 },
   // Centred in the card, like every other example (a single phone-width frame used to sit left).

package/native/catalog/catalogNavigation.ts

@@ -3,7 +3,7 @@
  * runner. CatalogShell, CatalogSidebar, and SectionBlock all derive page order from here, so the
  * sidebar order, previous/next order, and fragment fallback can never drift apart.
  */
-import type { NavGroup, UpdateNotice, VersionStatus } from './types.ts';
+import type { NavGroup, SectionDef, UpdateNotice, VersionStatus } from './types.ts';
 
 /** THE canonical within-group ordering of section ids. */
 export function sortIds<TId extends string>(ids: readonly TId[]): TId[] {
@@ -47,18 +47,25 @@ export function neighbors<TId extends string>(
   };
 }
 
-/** Sidebar filter: case-insensitive substring match, sorted ids, empty groups removed. */
+/** Sidebar filter: case-insensitive substring match, sorted ids, empty groups removed. A page
+ *  matches on its id, its title, or (spec §5.3) any of its family's member ids or aliases. */
 export function filterGroups<TId extends string>(
   groups: readonly NavGroup<TId>[],
   query: string,
   /** Display titles by id; a page matches on its id or its title. */
   labels?: ReadonlyMap<string, string>,
+  /** Every member id/alias a family page's members use, by page id. */
+  memberIds?: ReadonlyMap<string, readonly string[]>,
 ): NavGroup<TId>[] {
   const q = query.trim().toLowerCase();
   return groups
     .map((group) => ({
       label: group.label,
-      ids: sortIds(q ? group.ids.filter((id) => id.toLowerCase().includes(q) || (labels?.get(id)?.toLowerCase().includes(q) ?? false)) : group.ids),
+      ids: sortIds(q ? group.ids.filter((id) =>
+        id.toLowerCase().includes(q)
+        || (labels?.get(id)?.toLowerCase().includes(q) ?? false)
+        || (memberIds?.get(id)?.some((memberId) => memberId.toLowerCase().includes(q)) ?? false),
+      ) : group.ids),
     }))
     .filter((group) => group.ids.length > 0);
 }
@@ -131,6 +138,85 @@ export function resolveActiveFromHash<TId extends string>(
   return idFromHash(hash, order);
 }
 
+/** Where an alias or member id resolves: the family page `pageId`, and — unless it names the
+ *  whole itself — the specific `memberId` within it. Built by `aliasTargets`. */
+export interface AliasTarget {
+  pageId: string;
+  memberId?: string;
+}
+
+/** Every member id other than the whole, every member alias, and every family page's own
+ *  (page-level) alias, mapped to where it resolves (spec §5.3 "Old addresses"). Pages without a
+ *  `family` contribute nothing. */
+export function aliasTargets<TId extends string>(sections: readonly SectionDef<TId>[]): Map<string, AliasTarget> {
+  const targets = new Map<string, AliasTarget>();
+  for (const section of sections) {
+    const family = section.family;
+    if (!family) continue;
+    for (const member of family.members) {
+      if (member.id === family.whole) continue;
+      targets.set(member.id, { pageId: section.id, memberId: member.id });
+      for (const alias of member.aliases ?? []) targets.set(alias, { pageId: section.id, memberId: member.id });
+    }
+    for (const alias of family.aliases ?? []) targets.set(alias, { pageId: section.id });
+  }
+  return targets;
+}
+
+/** Where a URL fragment should take the viewer (spec §5.3). Unlike `resolveActiveFromHash`
+ *  (kept, unchanged, for existing callers), this never silently falls back to the first page: an
+ *  unknown or malformed fragment is reported as `notFound` instead. */
+export type Route<TId extends string> =
+  | { kind: 'page'; id: TId }
+  | { kind: 'member'; pageId: TId; memberId: string }
+  | { kind: 'update' }
+  | { kind: 'notFound'; raw: string }
+  | { kind: 'empty' };
+
+export function resolveRoute<TId extends string>(
+  hash: string,
+  order: readonly TId[],
+  aliases: ReadonlyMap<string, AliasTarget>,
+): Route<TId> {
+  const raw = hash.startsWith('#') ? hash.slice(1) : hash;
+  if (raw === '') return { kind: 'empty' };
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(raw);
+  } catch {
+    return { kind: 'notFound', raw };
+  }
+  if (decoded === UPDATE_PAGE_ID) return { kind: 'update' };
+  if ((order as readonly string[]).includes(decoded)) return { kind: 'page', id: decoded as TId };
+  const target = aliases.get(decoded);
+  if (target) {
+    if (target.memberId !== undefined) return { kind: 'member', pageId: target.pageId as TId, memberId: target.memberId };
+    return { kind: 'page', id: target.pageId as TId };
+  }
+  return { kind: 'notFound', raw: decoded };
+}
+
+/** One member search candidate: a family page's member, with its owning page and family title. */
+export interface MemberSearchEntry<TId extends string> {
+  pageId: TId;
+  memberId: string;
+  aliases?: readonly string[];
+  familyTitle: string;
+}
+
+/** Member search hits (spec §5.3 "Search"): every entry whose member id or alias contains the
+ *  query, case-insensitively. The label is always the member id — the Swift declaration name. */
+export function searchResults<TId extends string>(
+  entries: readonly MemberSearchEntry<TId>[],
+  query: string,
+): Array<{ pageId: TId; memberId: string; label: string; familyTitle: string }> {
+  const q = query.trim().toLowerCase();
+  if (!q) return [];
+  return entries
+    .filter((entry) => entry.memberId.toLowerCase().includes(q) || (entry.aliases ?? []).some((alias) => alias.toLowerCase().includes(q)))
+    .map((entry) => ({ pageId: entry.pageId, memberId: entry.memberId, label: entry.memberId, familyTitle: entry.familyTitle }));
+}
+
 /** Design §5: "Major: ... dismissible per version; the footer line remains." `dismissedVersion`
  *  is whatever a previous dismissal recorded (`CatalogShell`'s own `localStorage` read, Task 14) —
  *  any value other than the *current* `update.latest` (including `null`, or an older dismissed

package/native/catalog/comparison.ts

@@ -250,9 +250,9 @@ export interface ListGroup {
 }
 
 export type PresentationBlock =
-  | { kind: 'grid'; title: string; size: SpecimenSize; comparison: ComparisonDef }
-  | { kind: 'grouped'; title: string; size: SpecimenSize; groups: ListGroup[] }
-  | { kind: 'list'; title: string; size: SpecimenSize; items: ListItem[]; maxColumns?: 1 | 2 | 3 | 4 | 5 }
+  | { kind: 'grid'; title: string; size: SpecimenSize; comparison: ComparisonDef; axis?: string }
+  | { kind: 'grouped'; title: string; size: SpecimenSize; groups: ListGroup[]; axis?: string }
+  | { kind: 'list'; title: string; size: SpecimenSize; items: ListItem[]; maxColumns?: 1 | 2 | 3 | 4 | 5; axis?: string }
   | { kind: 'preview'; title: string; widths: PreviewWidths; layout?: 'frames' | 'table' }
   | { kind: 'tokenSections'; title: string; sections: TokenSection[]; columns: 1 | 2 | 3 }
   | { kind: 'empty'; title: string; message: string };
@@ -340,16 +340,26 @@ export function presentationBlocks<TId extends string>(def: SectionDef<TId>, opt
         title: `${def.comparison.rowLabel} × ${def.comparison.columnLabel}`,
         size: def.comparison.size ?? def.specimenSize ?? 'regular',
         comparison: def.comparison,
+        // A3: `comparison` replaces the Variants list, but `def.variants.axis` (if still set) is
+        // the only axis label a grid has to carry onto a family page, which hides generic titles.
+        ...(def.variants?.axis ? { axis: def.variants.axis } : {}),
       });
     } else if (grouped && def.variants) {
       // Grouped rows place several cells beside a row header, so full-width (itemsFill) slots do
       // not force 402px cells here; a cell's own `fill` still stretches its specimen.
-      blocks.push({ kind: 'grouped', title: 'Variant × configuration', size: def.specimenSize ?? 'regular', groups: grouped.groups });
+      blocks.push({
+        kind: 'grouped',
+        title: 'Variant × configuration',
+        size: def.specimenSize ?? 'regular',
+        groups: grouped.groups,
+        ...(def.variants.axis ? { axis: def.variants.axis } : {}),
+      });
       states = grouped.leftovers;
     } else if (def.variants) {
       blocks.push({
         kind: 'list',
-        title: 'Variants',
+        title: def.variants.axis ?? 'Variants',
+        ...(def.variants.axis ? { axis: def.variants.axis } : {}),
         size: slotSize(def, def.variants),
         items: slotItems(def.variants, 'variants', def.specimenSize === 'page'),
         ...slotColumnCap(def.variants),
@@ -363,7 +373,8 @@ export function presentationBlocks<TId extends string>(def: SectionDef<TId>, opt
     const secondary = blocks.length > 0 && blocks[0].kind !== 'list';
     blocks.push({
       kind: 'list',
-      title: secondary ? 'Other configurations' : 'States / configurations',
+      title: states.axis ?? (secondary ? 'Other configurations' : 'States / configurations'),
+      ...(states.axis ? { axis: states.axis } : {}),
       size: slotSize(def, states),
       items: slotItems(states, 'states', def.specimenSize === 'page'),
       ...slotColumnCap(states),

package/native/catalog/familyModel.ts

@@ -0,0 +1,192 @@
+/**
+ * Pure family-page UI logic (spec §5.1–§5.2) — no React or React Native imports, so it runs under
+ * Node's test runner. `FamilyPage.tsx` builds on this module rather than duplicating its own tree
+ * building, disclosure content, and link/pin lookups. Outline numbering (`numberFor`) and family
+ * validation (`validateFamily`) live in `pageApi.ts` instead — see that file's own comments.
+ */
+import type { CatalogMember, CatalogMemberSection, PropDef } from './types.ts';
+
+/** One node of a `blocks` section's own Part tree (Slice D1 item 7 "Tree line"). */
+export interface PartTreeEntry {
+  id: string;
+  children: PartTreeEntry[];
+}
+
+/** E1: moved from `FamilyPage.tsx` so it runs under Node's test runner — pure logic that alone
+ *  decides how a `blocks` section's own members nest and in what order its Parts render.
+ *  Reconstructs parentage mechanically from the already-computed `numberFor` outline (a child's
+ *  number is its parent's number plus one more `.` segment), scoped to the member ids given, not a
+ *  second copy of `numberFor`'s own nesting decision. Scoping to one section's own ids (rather than
+ *  every member of the page) is how family data is authored — a section's `members` already lists
+ *  a full parent/children subtree together — so a parent belonging to a *different* section is
+ *  simply absent from `memberIds`, and the would-be child becomes a root of this tree instead of
+ *  nesting under a part this call never sees. */
+export function buildPartTree(memberIds: readonly string[], outline: ReadonlyMap<string, { number: string; level: number }>): PartTreeEntry[] {
+  const idByNumber = new Map<string, string>();
+  for (const id of memberIds) {
+    const number = outline.get(id)?.number;
+    if (number) idByNumber.set(number, id);
+  }
+  const childrenOf = new Map<string, string[]>();
+  const roots: string[] = [];
+  for (const id of memberIds) {
+    const number = outline.get(id)?.number;
+    const parentNumber = number?.includes('.') ? number.slice(0, number.lastIndexOf('.')) : undefined;
+    const parentId = parentNumber ? idByNumber.get(parentNumber) : undefined;
+    if (parentId) childrenOf.set(parentId, [...(childrenOf.get(parentId) ?? []), id]);
+    else roots.push(id);
+  }
+  const build = (id: string): PartTreeEntry => ({ id, children: (childrenOf.get(id) ?? []).map(build) });
+  return roots.map(build);
+}
+
+/** Slice D1 item 5: an anatomy pin's number and style, looked up by member id — the pure lookup
+ *  behind `AnatomyPin` (which reads this through React context so a page's `anatomy.picture` never
+ *  hardcodes a number). `undefined` for an unknown member, or one with no number (outside any
+ *  `inWhole` section, or under an unnumbered parent — `numberFor` never assigns those one;
+ *  `validateFamily`'s D2 item A2 now reports any anatomy item naming such a member, but this stays
+ *  defensive for a caller outside the anatomy legend/picture, which that rule doesn't cover). A
+ *  dashed pin marks a `documentation-only` member — spec: "no area of their own". */
+export function anatomyPinFor(
+  memberId: string,
+  members: ReadonlyMap<string, Pick<CatalogMember, 'fidelity'>>,
+  outline: ReadonlyMap<string, { number: string }>,
+): { number: string; dashed: boolean } | undefined {
+  const member = members.get(memberId);
+  if (!member) return undefined;
+  const entry = outline.get(memberId);
+  if (!entry) return undefined;
+  return { number: entry.number, dashed: member.fidelity === 'documentation-only' };
+}
+
+/** Distributes a legend's groups into up to `maxColumns` columns so the columns end as close to
+ *  level as possible: each group, in authored order, goes into the column that is currently
+ *  shortest (the leftmost on a tie). A group's height is its items plus one row for its label. A
+ *  group never splits across columns, and the groups in each column keep their authored order. */
+export function anatomyColumns<T extends { items: ReadonlyArray<unknown> }>(groups: readonly T[], maxColumns = 3): T[][] {
+  if (groups.length === 0) return [];
+  const columnCount = Math.min(maxColumns, groups.length);
+  const columns: T[][] = Array.from({ length: columnCount }, () => []);
+  const heights = new Array<number>(columnCount).fill(0);
+  for (const group of groups) {
+    let shortest = 0;
+    for (let i = 1; i < columnCount; i += 1) if (heights[i] < heights[shortest]) shortest = i;
+    columns[shortest].push(group);
+    heights[shortest] += group.items.length + 1;
+  }
+  return columns;
+}
+
+/** `aria-level` for a member at a given outline level: the page title is 1, so every outline
+ *  level is shifted down by one, capped at 6 (spec §5.2 "Heading semantics"). The whole (outline
+ *  level 1) and section labels both land on 2 this way too. */
+export function ariaLevelFor(level: number): number {
+  return Math.min(level + 1, 6);
+}
+
+/** The disclosure's closed-state summary label (spec §5.2). V2b item 9: "Swift API" is Hermex
+ *  wording and must not be hardcoded in a generic viewer — `apiLabel` is the page's own label
+ *  (default `'API'`), and `hasProps` is whether the member has resolved props to show (the same
+ *  condition `disclosureContent` uses for its own "props" part). V2d item 2: `composedOf` ("Uses")
+ *  counts the same way `notes` already does here — either one alone (or together) gives "Notes"
+ *  alone, or combines with api/props into "Notes and ${apiLabel}". */
+export function disclosureLabel(member: CatalogMember, apiLabel = 'API', hasProps = false): string {
+  const hasNotesOrUses = Boolean(member.notes && member.notes.length > 0) || Boolean(member.composedOf && member.composedOf.length > 0);
+  const hasApiOrProps = Boolean(member.api) || hasProps;
+  if (hasNotesOrUses && hasApiOrProps) return `Notes and ${apiLabel}`;
+  if (hasApiOrProps) return apiLabel;
+  if (hasNotesOrUses) return 'Notes';
+  return 'Details';
+}
+
+export type DisclosurePart = 'notes' | 'uses' | 'whenToUse' | 'a11y' | 'props' | 'api';
+
+/** The disclosure's content, in order (spec §5.2 "Disclosure", V2d item 2): notes, then Uses
+ *  (`composedOf`, non-empty only), then Guidance (`whenToUse`), then Accessibility (`a11y`, unless
+ *  `hide.accessibility`), then the generated Props table (unless `hide.props`), then the Swift
+ *  excerpt (`api`). Omits any part whose data is absent. Errata 6: `props` is listed only when the
+ *  caller actually has resolved props to show — `resolvedProps` is the member's own generated
+ *  `props` (from its `component`, if any) — never merely because `hide.props` is unset; a
+ *  documentation-only member with no component has no props to omit from, so it never shows an
+ *  (empty) Props table. */
+export function disclosureContent(member: CatalogMember, resolvedProps?: readonly PropDef[]): DisclosurePart[] {
+  const parts: DisclosurePart[] = [];
+  if (member.notes && member.notes.length > 0) parts.push('notes');
+  if (member.composedOf && member.composedOf.length > 0) parts.push('uses');
+  if (member.whenToUse) parts.push('whenToUse');
+  if (member.a11y && !member.hide?.accessibility) parts.push('a11y');
+  if (resolvedProps && resolvedProps.length > 0 && !member.hide?.props) parts.push('props');
+  if (member.api) parts.push('api');
+  return parts;
+}
+
+/** The section a member id belongs to, or `undefined` for the whole (which is in no section) or an
+ *  unknown id. Used to decide whether addressing a member should open a folded row (its section's
+ *  `kind` is `'list'`). */
+export function sectionFor(sections: readonly CatalogMemberSection[], memberId: string): CatalogMemberSection | undefined {
+  return sections.find((section) => section.members.includes(memberId));
+}
+
+/** N7: the whole member, resolved from `family.whole` against `family.members` — `undefined` for
+ *  bad data (a `whole` that isn't one of its own members, already reported by `validateFamily`),
+ *  so `FamilyPage` can skip rendering the whole block instead of crashing on an absent member.
+ *  Generic over the member's own shape so `FamilyPage` keeps its resolved `props`/`path` fields
+ *  (`FamilyDef.members`'s own type) through the lookup. */
+export function resolveWhole<T>(members: ReadonlyMap<string, T>, whole: string): T | undefined {
+  return members.get(whole);
+}
+
+/** V2c item 1 (one-shot jump) + item 11 (repeat activation): in-flight state for a member-address
+ *  scroll/focus jump, reset fresh on every new activation (`FamilyPage`'s own effect, keyed by a
+ *  nonce from `CatalogShell` so a repeat activation of the SAME member still counts as new).
+ *  `passesLeft` starts at 2 for a folded (`list`) row — the row's first, still-closed layout, then
+ *  its second, now-open one (V2b item 8) — or 1 for a block member, which has only one layout to
+ *  scroll against. */
+export interface MemberJumpState {
+  memberId: string;
+  passesLeft: number;
+}
+
+/** Whether a member-address scroll/focus pass should run right now: only while `state` still
+ *  belongs to the member currently addressed and still has a pass left. Once every pass for the
+ *  current activation has run, toggling an unrelated (or even the same) row afterwards — which
+ *  changes nothing this state tracks — must never make this true again. */
+export function shouldRunMemberJump(state: MemberJumpState | undefined, memberId: string): boolean {
+  return state !== undefined && state.memberId === memberId && state.passesLeft > 0;
+}
+
+/** One segment of a `related` sentence (spec §5.2): plain text, or a member id that should render
+ *  as a link to that member's address (`RelatedSegment.memberId` is also that member's display
+ *  name — see `CatalogMember.id`'s own doc comment). */
+export interface RelatedSegment {
+  text: string;
+  memberId?: string;
+}
+
+/** Escapes a string for literal use inside a `RegExp` (the characters the regex engine would
+ *  otherwise treat as metacharacters). A Swift declaration name never contains any of these, but
+ *  this keeps `linkifyRelated` correct even if one ever did. */
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** Splits a `related` sentence (spec §5.1 `CatalogMember.related`) into segments, turning every
+ *  whole-word occurrence of another member's id into a linked segment; every other run of text is
+ *  a plain segment. Matches the longest id first, so a shorter id that is a prefix of a longer one
+ *  (e.g. "BotAvatarView" inside "BotAvatarViewLegacy") never splits the longer one apart. Returns
+ *  the whole text as one plain segment when there are no ids, or no match. */
+export function linkifyRelated(text: string, memberIds: readonly string[]): RelatedSegment[] {
+  if (memberIds.length === 0) return [{ text }];
+  const ids = [...memberIds].sort((a, b) => b.length - a.length);
+  const pattern = new RegExp(`\\b(?:${ids.map(escapeRegExp).join('|')})\\b`, 'g');
+  const segments: RelatedSegment[] = [];
+  let lastIndex = 0;
+  let match: RegExpExecArray | null;
+  while ((match = pattern.exec(text))) {
+    if (match.index > lastIndex) segments.push({ text: text.slice(lastIndex, match.index) });
+    segments.push({ text: match[0], memberId: match[0] });
+    lastIndex = match.index + match[0].length;
+  }
+  if (lastIndex < text.length) segments.push({ text: text.slice(lastIndex) });
+  return segments.length > 0 ? segments : [{ text }];
+}

package/native/catalog/index.ts

@@ -15,7 +15,9 @@
 export { CatalogShell } from './CatalogShell';
 export { CatalogSidebar } from './CatalogSidebar';
 export { CatalogSearchInput } from './CatalogSearchInput';
-export { SectionBlock } from './SectionBlock';
+export { SectionBlock, PagerButton, SectionPagerRow } from './SectionBlock';
+export type { SectionPager } from './SectionBlock';
+export { FamilyPage, AnatomyPin } from './FamilyPage';
 export { ComparisonGrid } from './ComparisonGrid';
 export { grid, axisItems, axisProp } from './comparison';
 export { ComparisonGroups } from './ComparisonGroups';
@@ -46,7 +48,8 @@ export { defineCatalogPage, buildCatalogSections } from './pageApi';
 export type { CatalogPage, CatalogPageInput, GeneratedComponent, GeneratedPropRecord } from './pageApi';
 export type {
   PropDef, SectionDef, NavGroup, SpecimenSize, SpecimenSurfaceKind, ComparisonDef, ComparisonCell, ComparisonAxisItem, GridAxis,
-  PreviewWidths, TokenSection, ComposedOfEntry,
+  PreviewWidths, TokenSection, ComposedOfEntry, CatalogMember, CatalogMemberSection, FamilyDef,
+  CatalogAnatomy, CatalogAnatomyGroup, CatalogAnatomyItem,
 } from './types';
 export { UpdatePanel } from './UpdatePanel';
 export { UPDATE_PAGE_ID } from './catalogNavigation';

package/native/catalog/overlayViewport.ts

@@ -6,7 +6,7 @@
  * render) resolves an address back to the `node` it names.
  */
 import type React from 'react';
-import type { SectionDef } from './types.ts';
+import type { ComparisonDef, SectionDef, VariantSlot } from './types.ts';
 
 /** Which block on a page an addressed specimen's `node` lives in — see `findOverlayNode`. */
 export type OverlaySlot = 'variants' | 'states' | 'comparison' | 'preview';
@@ -109,19 +109,39 @@ export function resolveOverlayViewport(args: {
   return { mode: 'frame', href: `${args.pathname}${overlayViewportHrefSuffix(args.address)}` };
 }
 
+/** The slots `findOverlayNode` reads — shared by a top-level `SectionDef` and a family member
+ *  (`CatalogMember`), which carry the exact same `variants`/`states`/`comparison`/`render` shape. */
+interface SpecimenSource {
+  variants?: VariantSlot;
+  states?: VariantSlot;
+  comparison?: ComparisonDef;
+  render?: () => React.ReactNode;
+}
+
+function readSpecimenSlot(source: SpecimenSource, address: OverlayAddress): React.ReactNode | undefined {
+  if (address.slot === 'variants') return source.variants?.items.find((item) => item.key === address.itemKey)?.node;
+  if (address.slot === 'states') return source.states?.items.find((item) => item.key === address.itemKey)?.node;
+  // A `render()` page's preview (one per page; `itemKey` is always 'preview').
+  if (address.slot === 'preview') return source.render?.();
+  // Matched by recomputing each cell's own canonical key, never by splitting `address.itemKey` —
+  // a row/column key may itself contain any delimiter this module could pick.
+  return source.comparison?.cells.find((cell) => comparisonCellItemKey(cell.rowKey, cell.columnKey) === address.itemKey)?.node;
+}
+
 /** The authored `node` an `OverlayAddress` points at, or `undefined` for a stale/unknown address
  *  (a removed example, a renamed key, a typo) — `CatalogShell`'s chromeless selected-document
- *  render shows an honest "unavailable" recovery rather than rendering nothing silently. */
+ *  render shows an honest "unavailable" recovery rather than rendering nothing silently.
+ *  V2c item 3: a specimen built inside a family member (`SectionBlock.tsx`'s `memberAsSectionDef`)
+ *  addresses itself with the member's own id as `pageId` — that never matches a top-level
+ *  `SectionDef.id`, so this also searches every family page's own `family.members` for it. */
 export function findOverlayNode(sections: readonly SectionDef<string>[], address: OverlayAddress): React.ReactNode | undefined {
   const def = sections.find((section) => section.id === address.pageId);
-  if (!def) return undefined;
-  if (address.slot === 'variants') return def.variants?.items.find((item) => item.key === address.itemKey)?.node;
-  if (address.slot === 'states') return def.states?.items.find((item) => item.key === address.itemKey)?.node;
-  // A `render()` page's preview (one per page; `itemKey` is always 'preview').
-  if (address.slot === 'preview') return def.render?.();
-  // Matched by recomputing each cell's own canonical key, never by splitting `address.itemKey` —
-  // a row/column key may itself contain any delimiter this module could pick.
-  return def.comparison?.cells.find((cell) => comparisonCellItemKey(cell.rowKey, cell.columnKey) === address.itemKey)?.node;
+  if (def) return readSpecimenSlot(def, address);
+  for (const section of sections) {
+    const member = section.family?.members.find((m) => m.id === address.pageId);
+    if (member) return readSpecimenSlot(member, address);
+  }
+  return undefined;
 }
 
 /** The canonical, unambiguous `itemKey` for one comparison cell's row+column — this module's own