@krapwoo/ds-viewer 0.10.0 → 0.11.0

package/native/catalog/pageApi.ts

@@ -1,5 +1,5 @@
 import type React from 'react';
-import type { ComparisonDef, ComposedOfEntry, NavGroup, PreviewWidths, PropDef, SectionDef, SpecimenSize, SpecimenSurfaceKind, TokenSection, VariantSlot } from './types';
+import type { CatalogAnatomy, CatalogMember, CatalogMemberSection, ComparisonDef, ComposedOfEntry, NavGroup, PreviewWidths, PropDef, SectionDef, SpecimenSize, SpecimenSurfaceKind, TokenSection, VariantSlot } from './types.ts';
 
 /** `SectionDef` without the derived fields (`id`/`path`/`props` come from detection and
  *  generated props), plus the three fields design §1 "Page shape" adds. */
@@ -46,6 +46,35 @@ export interface CatalogPageInput<TId extends string = string> {
   /** Extra text per prop, appended to its generated description. A note naming a prop that no
    *  longer exists is a `doctor` error from 0.3 — 0.1 has no `doctor`, so it is silently unused. */
   propNotes?: Record<string, string>;
+  /** Spec §5.1: documents a family of related declarations on one page instead of a single
+   *  component. When set, the page's own `component`/`whenToUse`/`a11y`/specimens are not used —
+   *  those live on the members (the whole is a member too) — and the viewer renders a `FamilyPage`
+   *  (`SectionDef.family`) rather than the normal single-component layout. Requires `whole` and
+   *  `sections`; validated by this file's own `validateFamily`. */
+  members?: CatalogMember[];
+  /** The family's whole: a member id, required when `members` is set. Its own id must equal this
+   *  page's `id`. */
+  whole?: string;
+  /** How the family's non-whole members are grouped and rendered, required when `members` is set.
+   *  Ordering only — numbering follows each member's own `parent` (`numberFor`); a Related member
+   *  (outside every `inWhole` section) is never numbered. */
+  sections?: CatalogMemberSection[];
+  /** Extra names for the page itself (its whole) — e.g. retired page ids that are not member ids.
+   *  Included in uniqueness validation, routing and search alongside `members[].aliases`. V2c item
+   *  15: only takes effect on a page with `members` (a family page) — accepted but unused on a
+   *  normal page, which never resolves it to anywhere. */
+  aliases?: string[];
+  /** Family-level "Not shown in the browser" line, under the page head. V2c item 15: only takes
+   *  effect on a page with `members` — unused on a normal page. */
+  notShown?: string;
+  /** Label for the disclosure's API part (spec V2b item 9), e.g. `'Swift API'`. Defaults to
+   *  `'API'` when absent — a generic viewer must never hardcode a host app's own wording. V2c
+   *  item 15: only takes effect on a page with `members` — unused on a normal page. */
+  apiLabel?: string;
+  /** Slice D1 item 1: the anatomy box `FamilyPage` renders first, right after the page head —
+   *  a picture of the whole with numbered pins and a legend. Only takes effect on a page with
+   *  `members`. */
+  anatomy?: CatalogAnatomy;
 }
 
 export interface CatalogPage<TId extends string = string> extends CatalogPageInput<TId> {
@@ -95,17 +124,237 @@ function mergePropNotes(component: GeneratedComponent, propNotes: Record<string,
   return [...own, ...inherited];
 }
 
-/** Human-readable problems with a page's `composedOf`, in declaration order: one line per entry
- *  whose `component` isn't in `knownNames` (every real component name, documented or not, plus
- *  every page id — the full catalog inventory `buildCatalogSections` already has on hand). Empty
- *  when every name resolves, including when `composedOf` itself is omitted. */
-export function validateComposedOf(composedOf: ComposedOfEntry[] | undefined, knownNames: ReadonlySet<string>): string[] {
+/** Human-readable problems with a page's (or, V2d, a family member's own) `composedOf`, in
+ *  declaration order: one line per entry whose `component` isn't in `knownNames` (every real
+ *  component name, documented or not, plus every page id and family member id — the full catalog
+ *  inventory `buildCatalogSections` already has on hand). Empty when every name resolves,
+ *  including when `composedOf` itself is omitted. Takes only the `component` field (never the
+ *  narrower `ComposedOfEntry[]` type) so `cli/doctor.ts`'s own statically-read `{ component:
+ *  string }[]` shape — which never carries `role`/`relationship` — satisfies it too. */
+export function validateComposedOf(composedOf: { component: string }[] | undefined, knownNames: ReadonlySet<string>): string[] {
   if (!composedOf) return [];
   return composedOf
     .filter((entry) => !knownNames.has(entry.component))
     .map((entry) => `composedOf references unknown component "${entry.component}".`);
 }
 
+/** The subset of a family page's shape `validateFamily` and `numberFor` need. The real page
+ *  carries full `CatalogMember` records; these functions only ever read `id`/`parent`/`aliases`. */
+export interface FamilyOutlineInput {
+  whole?: string;
+  sections?: CatalogMemberSection[];
+  members?: Array<Pick<CatalogMember, 'id' | 'parent'>>;
+}
+
+export interface FamilyPageLike extends FamilyOutlineInput {
+  id: string;
+  /** N6: `hasSpecimens` is not a `CatalogMember` field — each caller computes it (a non-empty
+   *  `variants`/`states`/`comparison` at runtime, `StaticMember.hasExamples` in `doctor`) so
+   *  `validateFamily` can flag a `list`-section member authored with a specimen that `FoldedRow`
+   *  never renders. */
+  members?: Array<Pick<CatalogMember, 'id' | 'parent' | 'aliases'> & { hasSpecimens?: boolean }>;
+  aliases?: string[];
+  /** Slice D1 item 3: the minimal shape `validateFamily` needs from `CatalogPageInput.anatomy` —
+   *  decoupled from the full `CatalogAnatomy` type (which carries a `picture` React node this pure
+   *  module never touches). */
+  anatomy?: FamilyAnatomyLike;
+}
+
+/** Slice D1 item 3. */
+export interface FamilyAnatomyLike {
+  groups: ReadonlyArray<{ label: string; items: ReadonlyArray<{ member: string } | { other: string }> }>;
+}
+
+/** Validates a family page (spec §5.1): exactly one whole belonging to no section; every other
+ *  member in exactly one section; every parent resolving within the page with no cycles; member
+ *  and alias ids unique catalog-wide and never colliding with a page id, except the whole (whose
+ *  id equals its own page's id). Returns `[]` for a page without `members`. `allPageIds` and
+ *  `otherMemberIds` are the ids used by every *other* page/member in the catalog. */
+export function validateFamily(page: FamilyPageLike, allPageIds: ReadonlySet<string>, otherMemberIds: ReadonlySet<string>): string[] {
+  const { members } = page;
+  if (!members || members.length === 0) return [];
+  const issues: string[] = [];
+
+  if (!page.whole || !page.sections) {
+    issues.push(`Family "${page.id}": "members" requires both "whole" and "sections".`);
+    return issues;
+  }
+  const whole = page.whole;
+  const byId = new Map(members.map((m) => [m.id, m]));
+
+  if (!byId.has(whole)) {
+    issues.push(`Family "${page.id}": whole "${whole}" is not one of its members.`);
+  }
+  if (whole !== page.id) {
+    issues.push(`Family "${page.id}": whole "${whole}" must have the same id as the page.`);
+  }
+
+  // V2c item 2: a section listing an id that is not one of the page's own members — reported
+  // here, rather than left to crash the renderer or silently occupy authored order in `numberFor`.
+  // N6: a `list`-section member authored with a specimen — `FoldedRow` never renders one, so this
+  // degrades to a silently dropped specimen rather than a crash, same as the unknown-id case.
+  for (const section of page.sections) {
+    for (const id of section.members) {
+      const resolved = byId.get(id);
+      if (!resolved) {
+        issues.push(`Family "${page.id}": section "${section.label}" lists "${id}", which is not a member of this page.`);
+        continue;
+      }
+      if (section.kind === 'list' && resolved.hasSpecimens) {
+        issues.push(`Family "${page.id}": "${id}" has specimens, but list sections show members as folded rows without specimens.`);
+      }
+    }
+  }
+
+  const sectionCountById = new Map<string, number>();
+  for (const section of page.sections) {
+    for (const id of section.members) sectionCountById.set(id, (sectionCountById.get(id) ?? 0) + 1);
+  }
+  if (sectionCountById.has(whole)) {
+    issues.push(`Family "${page.id}": the whole "${whole}" must not appear in any section.`);
+  }
+  for (const m of members) {
+    if (m.id === whole) continue;
+    const count = sectionCountById.get(m.id) ?? 0;
+    if (count === 0) issues.push(`Family "${page.id}": member "${m.id}" is not in any section.`);
+    else if (count > 1) issues.push(`Family "${page.id}": member "${m.id}" is in more than one section.`);
+  }
+
+  for (const m of members) {
+    if (m.parent === undefined) continue;
+    if (!byId.has(m.parent)) {
+      issues.push(`Family "${page.id}": member "${m.id}" has an unknown parent "${m.parent}".`);
+      continue;
+    }
+    const seen = new Set([m.id]);
+    let current: string | undefined = m.parent;
+    let cycle = false;
+    while (current !== undefined) {
+      if (seen.has(current)) {
+        cycle = true;
+        break;
+      }
+      seen.add(current);
+      current = byId.get(current)?.parent;
+    }
+    if (cycle) issues.push(`Family "${page.id}": member "${m.id}" has a parent cycle.`);
+  }
+
+  const seenInPage = new Set<string>();
+  const checkId = (id: string, isWhole: boolean) => {
+    if (seenInPage.has(id)) issues.push(`Family "${page.id}": id "${id}" is used more than once on this page.`);
+    seenInPage.add(id);
+    if (isWhole) return;
+    if (allPageIds.has(id)) issues.push(`Family "${page.id}": id "${id}" collides with another page's id.`);
+    if (otherMemberIds.has(id)) issues.push(`Family "${page.id}": id "${id}" collides with another member or alias elsewhere in the catalog.`);
+  };
+  for (const m of members) {
+    checkId(m.id, m.id === whole);
+    for (const alias of m.aliases ?? []) checkId(alias, false);
+  }
+  for (const alias of page.aliases ?? []) checkId(alias, false);
+
+  // Slice D1 item 3: an anatomy `member` item must name a real, non-whole member of this page, and
+  // each member may be pinned to the picture's legend at most once.
+  // D2 item A2: a member item whose member has no number — outside every `inWhole` section, or
+  // under a parent that isn't itself numbered — must also be reported; left unchecked, it renders
+  // a blank 34px pin slot in the legend and nothing at all from `AnatomyPin` in the picture.
+  if (page.anatomy) {
+    const numbered = numberFor(page);
+    const seenAnatomyMembers = new Set<string>();
+    for (const group of page.anatomy.groups) {
+      for (const item of group.items) {
+        if (!('member' in item)) continue;
+        if (item.member === whole) {
+          issues.push(`Family "${page.id}": anatomy item "${item.member}" names the whole.`);
+          continue;
+        }
+        if (!byId.has(item.member)) {
+          issues.push(`Family "${page.id}": anatomy item "${item.member}" is not a member of this page.`);
+          continue;
+        }
+        if (seenAnatomyMembers.has(item.member)) {
+          issues.push(`Family "${page.id}": anatomy lists member "${item.member}" more than once.`);
+          continue;
+        }
+        seenAnatomyMembers.add(item.member);
+        if (!numbered.has(item.member)) {
+          issues.push(`Family "${page.id}": anatomy item "${item.member}" has no number.`);
+        }
+      }
+    }
+  }
+
+  return issues;
+}
+
+/** Slice D1 item 2: anatomy-first numbering — the only numbering rule for every family page (not
+ *  only one with `anatomy` set; it superseded the earlier whole-and-letters rule outright). The
+ *  whole gets no number. A **top-level part** is any member of an `inWhole` section whose `parent`
+ *  is the whole, or who has no `parent` at all (an in-whole root with no Swift parent edge is still
+ *  top-level) — numbered `1`, `2`, `3`… in authored order (the order a member first appears
+ *  scanning `inWhole` sections, in section order). A child takes its parent's number plus `.1`,
+ *  `.2`, … in authored order. Members outside any `inWhole` section (Related) get no number at
+ *  all. Returns an empty map for a page without members. */
+export function numberFor(page: FamilyOutlineInput): Map<string, { number: string; level: number }> {
+  const outline = new Map<string, { number: string; level: number }>();
+  const { whole, sections, members } = page;
+  if (!whole || !sections || !members) return outline;
+
+  const memberIds = new Set(members.map((m) => m.id));
+  // Only `inWhole` sections contribute to numbering — a Related section's members are never
+  // top-level parts, and never occupy authored order (so they can't be skipped-over roots either).
+  const authoredOrder: string[] = [];
+  const seen = new Set<string>();
+  for (const section of sections) {
+    if (!section.inWhole) continue;
+    for (const id of section.members) {
+      if (!seen.has(id) && memberIds.has(id)) {
+        seen.add(id);
+        authoredOrder.push(id);
+      }
+    }
+  }
+
+  const parentOf = new Map(members.map((m) => [m.id, m.parent]));
+  const childrenOf = new Map<string, string[]>();
+  for (const id of authoredOrder) {
+    const parent = parentOf.get(id);
+    if (parent === undefined) continue;
+    childrenOf.set(parent, [...(childrenOf.get(parent) ?? []), id]);
+  }
+
+  // V2c item 14's cycle guard: bad data already reported by `validateFamily` must degrade to a
+  // partial outline, never an infinite recursion.
+  const assignChildren = (parentId: string, parentNumber: string, level: number, visited: Set<string>) => {
+    const kids = childrenOf.get(parentId) ?? [];
+    kids.forEach((childId, index) => {
+      if (visited.has(childId)) return;
+      visited.add(childId);
+      const number = `${parentNumber}.${index + 1}`;
+      outline.set(childId, { number, level: level + 1 });
+      assignChildren(childId, number, level + 1, visited);
+    });
+  };
+
+  const visited = new Set<string>([whole]);
+  const topLevel = authoredOrder.filter((id) => {
+    const parent = parentOf.get(id);
+    return parent === undefined || parent === whole;
+  });
+  let next = 0;
+  for (const id of topLevel) {
+    if (visited.has(id)) continue;
+    visited.add(id);
+    next += 1;
+    const number = String(next);
+    outline.set(id, { number, level: 2 });
+    assignChildren(id, number, 2, visited);
+  }
+
+  return outline;
+}
+
 function orderGroups<TId extends string>(groupIds: Map<string, TId[]>, groupOrder: string[] | undefined): NavGroup<TId>[] {
   const listed = groupOrder ?? [];
   const labels = [...groupIds.keys()];
@@ -128,13 +377,47 @@ export function buildCatalogSections<TId extends string>(
   groupOrder?: string[],
 ): { sections: SectionDef<TId>[]; groups: NavGroup<TId>[] } {
   const componentByName = new Map(components.map((c) => [c.name, c]));
-  const documented = new Set(pages.map((page) => page.component ?? page.id));
+  // A page with `members` documents every member's own `component` instead of `page.component ??
+  // page.id` — that fallback never applies to a family page (spec §5.1).
+  const documented = new Set<string>();
+  for (const page of pages) {
+    if (page.members && page.members.length > 0) {
+      for (const member of page.members) if (member.component) documented.add(member.component);
+    } else {
+      documented.add(page.component ?? page.id);
+    }
+  }
   const groupIds = new Map<string, TId[]>();
   const addToGroup = (group: string, id: TId) => groupIds.set(group, [...(groupIds.get(group) ?? []), id]);
-  // Every name a page's `composedOf` could legitimately point at: every real component (documented
-  // or not — an undocumented one is still a real part of the design system) plus every page id
-  // (token pages, standalone recipes, …).
-  const knownComposedOfNames = new Set<string>([...componentByName.keys(), ...pages.map((page) => page.id)]);
+  // Every name a page's (or, V2d, a family member's own) `composedOf` could legitimately point
+  // at: every real component (documented or not — an undocumented one is still a real part of the
+  // design system), every page id (token pages, standalone recipes, …), every family member id
+  // (a member's composedOf may point at a sibling member, or a member of another family), and —
+  // N8 — every member alias and page-level alias: `FamilyPage`'s own `resolvesAddress` already
+  // treats these as working links (`aliasTargets`), so this warning must accept the same names.
+  const knownComposedOfNames = new Set<string>([
+    ...componentByName.keys(),
+    ...pages.map((page) => page.id),
+    ...pages.flatMap((page) => (page.members ?? []).map((member) => member.id)),
+    ...pages.flatMap((page) => (page.members ?? []).flatMap((member) => member.aliases ?? [])),
+    ...pages.flatMap((page) => page.aliases ?? []),
+  ]);
+
+  // Every id/alias a family page's own `members` and `aliases` use, keyed by page id — gathered up
+  // front so `validateFamily` (above) can check catalog-wide uniqueness against every *other*
+  // page's ids.
+  const allPageIds = new Set(pages.map((page) => page.id));
+  const familyIdsByPage = new Map<TId, Set<string>>();
+  for (const page of pages) {
+    if (!page.members) continue;
+    const ids = new Set<string>();
+    for (const member of page.members) {
+      ids.add(member.id);
+      for (const alias of member.aliases ?? []) ids.add(alias);
+    }
+    for (const alias of page.aliases ?? []) ids.add(alias);
+    familyIdsByPage.set(page.id, ids);
+  }
 
   // Design §4 "duplicate-page-id" rule's viewer-side equivalent — this is the one place in the
   // whole viewer that already resolves every page's id to build sections/groups, so it costs
@@ -142,14 +425,63 @@ export function buildCatalogSections<TId extends string>(
   // `CatalogShell.tsx` would otherwise just let the last one silently win).
   const seenIds = new Set<TId>();
   const sections: SectionDef<TId>[] = pages.map((page) => {
+    // N2: `seenIds` must be populated (and consulted, below in the undocumented-component loop)
+    // regardless of `__DEV__` — only the `console.warn` calls are development-only diagnostics;
+    // a production bundle (Metro's `__DEV__ = false`) still needs the stub-skip to work.
+    if (seenIds.has(page.id)) {
+      if ((globalThis as { __DEV__?: boolean }).__DEV__) {
+        console.warn(`[Catalog] Page id "${page.id}" is used by more than one page; only the last one will show. Give one of them its own "id".`);
+      }
+    }
+    seenIds.add(page.id);
     if ((globalThis as { __DEV__?: boolean }).__DEV__) {
-      if (seenIds.has(page.id)) console.warn(`[Catalog] Page id "${page.id}" is used by more than one page; only the last one will show. Give one of them its own "id".`);
-      seenIds.add(page.id);
       for (const issue of validateComposedOf(page.composedOf, knownComposedOfNames)) console.warn(`[Catalog] ${page.id}: ${issue}`);
+      // V2d item 4: the same validation, per family member's own `composedOf`.
+      for (const member of page.members ?? []) {
+        for (const issue of validateComposedOf(member.composedOf, knownComposedOfNames)) {
+          console.warn(`[Catalog] ${page.id}.${member.id}: ${issue}`);
+        }
+      }
     }
-    const componentName = page.component ?? page.id;
-    const component = componentByName.get(componentName);
+    const isFamily = page.members !== undefined && page.members.length > 0;
+    const componentName = isFamily ? undefined : (page.component ?? page.id);
+    const component = componentName ? componentByName.get(componentName) : undefined;
     addToGroup(page.group, page.id);
+
+    let family: SectionDef<TId>['family'];
+    if (isFamily) {
+      const otherPageIds = new Set([...allPageIds].filter((id) => id !== page.id));
+      const otherMemberIds = new Set<string>();
+      for (const [id, ids] of familyIdsByPage) if (id !== page.id) for (const memberId of ids) otherMemberIds.add(memberId);
+      // `hasSpecimens` is computed here, as doctor does, so the list-section rule also fires in
+      // the development console, not only in `ds-viewer doctor`.
+      const members = page.members!.map((member) => ({
+        ...member,
+        hasSpecimens: Boolean(member.variants?.items?.length || member.states?.items?.length || member.comparison),
+      }));
+      const issues = validateFamily({ ...page, members, anatomy: page.anatomy }, otherPageIds, otherMemberIds);
+      if ((globalThis as { __DEV__?: boolean }).__DEV__) {
+        for (const issue of issues) console.error(`[Catalog] ${issue}`);
+      }
+      family = {
+        whole: page.whole!,
+        sections: page.sections!,
+        outline: numberFor(page),
+        notShown: page.notShown,
+        aliases: page.aliases,
+        apiLabel: page.apiLabel,
+        anatomy: page.anatomy,
+        members: page.members!.map((member) => {
+          const memberComponent = member.component ? componentByName.get(member.component) : undefined;
+          return {
+            ...member,
+            props: memberComponent ? mergePropNotes(memberComponent, undefined) : undefined,
+            path: memberComponent?.file ?? member.source,
+          };
+        }),
+      };
+    }
+
     // Important finding 4: a standalone page (no matching component record) has no props to show
     // and nothing to say "This component takes no props" about — hide the Props box, and fall back
     // to the page's own file as its Source instead of an empty path.
@@ -179,12 +511,22 @@ export function buildCatalogSections<TId extends string>(
       composedOf: page.composedOf,
       internalProps: page.internalProps,
       intentionalStaticPreview: page.intentionalStaticPreview,
+      family,
     };
   });
 
   const undocumented = components.filter((component) => !documented.has(component.name)).sort((a, b) => a.name.localeCompare(b.name));
   for (const component of undocumented) {
     const id = component.name as TId;
+    // V2c item 7: a component with no page of its own, whose name happens to collide with an
+    // authored page's own id (most likely a family page, which never resolves `documented` via the
+    // `page.component ?? page.id` fallback) — its stub must never win that id in `sections`.
+    if (seenIds.has(id)) {
+      if ((globalThis as { __DEV__?: boolean }).__DEV__) {
+        console.warn(`[Catalog] Component "${id}" has no catalog page of its own, and "${id}" is already used by another page's id; skipping its stub.`);
+      }
+      continue;
+    }
     sections.push({ id, description: 'No examples documented.', path: component.file, props: mergePropNotes(component, undefined) });
     addToGroup('Components', id);
   }

package/native/catalog/tokens.ts

@@ -183,6 +183,13 @@ export const CATALOG_COLOR = {
   accentSubtle: '#e9efff',
   /** 3px keyboard focus ring on every catalog control. */
   focusRing: '#c9d7ff',
+  /** Family-page Part tree connector line (Slice D1/D2) — the approved reference's own line color
+   *  has no match among the other tokens above. */
+  treeLine: '#a9bdf0',
+  /** Family-page API code block: a dark surface and its text, the one place the catalog shows a
+   *  member's raw API signature. Dark on purpose so it reads as code, not as catalog chrome. */
+  codeSurface: '#1d1d1f',
+  codeOnSurface: '#e8e8e8',
   /** @deprecated kept for the public API; re-points at `CATALOG_FONT.code` so there is one source
    *  of truth. New code should reach for `CATALOG_FONT.code` (or a `CATALOG_TEXT` `code*` role)
    *  instead. */

package/native/catalog/types.ts

@@ -72,6 +72,9 @@ export interface VariantSlot {
    *  it only ever lowers the natural, width-based column count, never raises it. Omit to let the
    *  slot's specimen size and available width decide alone (today's behavior, unchanged). */
   maxColumns?: 1 | 2 | 3 | 4 | 5;
+  /** Names the one property this grid varies (e.g. "Expression", "Shape"). Shown as the grid's
+   *  label, including on family pages, which otherwise hide block labels. */
+  axis?: string;
   items: VariantExample[];
 }
 
@@ -274,6 +277,9 @@ export interface SectionDef<TId extends string = string> {
    *  so the exemption is a visible declaration in the page rather than a silent gap — write an
    *  example instead whenever the reader really does choose the value. */
   internalProps?: Record<string, string>;
+  /** Set when the authored page has `members`: the viewer renders a `FamilyPage` instead of the
+   *  normal single-component layout. See `CatalogPageInput.members` and `FamilyDef`. */
+  family?: FamilyDef;
 }
 
 /** A labeled group of section ids in the sidebar (e.g. "Components" vs "Tokens"). */
@@ -313,6 +319,106 @@ export interface VersionStatus {
   update: UpdateNotice | null;
 }
 
+/** One documented declaration on a family page (spec §5.1): its name, source location, fidelity,
+ *  specimens or reference text, and API. The whole (the page's own `id`) is a member too. */
+export interface CatalogMember {
+  id: string;
+  /** A detected component export. Its generated props go in the disclosure, and its stub page is
+   *  suppressed. Omit for a documentation-only member with no rendered specimen. */
+  component?: string;
+  /** The native source shown in the line below the specimens, `path:line`. */
+  source: string;
+  fidelity: 'replicated' | 'approximated' | 'documentation-only';
+  /** For example "Anatomy", "Native integration", "Helper". Slice D1 removed the below-specimens
+   *  line's own relationship/section-label display entirely (the anatomy box replaced it); kept as
+   *  authored data for your own reference, but not read by the renderer. */
+  relationship: string;
+  /** The member that contains or uses this one. Omitted on the whole and on related roots. */
+  parent?: string;
+  /** Short sentence for members outside the whole (e.g. "Wraps BotAvatarView"). Member names
+   *  inside it become links to that member's address. */
+  related?: string;
+  description: string;
+  variants?: VariantSlot;
+  states?: VariantSlot;
+  comparison?: ComparisonDef;
+  /** Bullets inside the disclosure. */
+  notes?: string[];
+  whenToUse?: string;
+  a11y?: string;
+  /** Swift declaration excerpt, generated by the host app's scanner, shown in the disclosure. */
+  api?: string;
+  /** What this member is built from or composed with — same meaning as `SectionDef.composedOf`,
+   *  shown in the disclosure as one "Uses …" line (`disclosureContent`'s `'uses'` part). */
+  composedOf?: ComposedOfEntry[];
+  notShown?: string;
+  /** Display only, same meaning as `SectionDef.hide` — not a doctor exemption. */
+  hide?: { accessibility?: boolean; props?: boolean };
+  /** Extra names (e.g. retired page ids) that resolve to this member. */
+  aliases?: string[];
+  /** Same meaning as `SectionDef.osComponent` — rendered as the same small badge in the member
+   *  header. */
+  osComponent?: 'full' | 'partial';
+  previewWidths?: PreviewWidths;
+  previewLayout?: 'frames' | 'table';
+  specimenSize?: SpecimenSize;
+  specimenSurface?: SpecimenSurfaceKind;
+  /** Same meaning as `SectionDef.intentionalStaticPreview` — accepted per member, but not yet
+   *  consumed by anything (neither the viewer nor `doctor`'s member-level checks read it). */
+  intentionalStaticPreview?: { reason: string };
+}
+
+/** One section of a family page (spec §5.1): `kind` alone decides full blocks versus the folded
+ *  list card. `inWhole` sections come right after the whole; the others come after them — ordering
+ *  only, numbering follows each member's own `parent` (see `numberFor`); a Related (non-`inWhole`)
+ *  member is never numbered. */
+export interface CatalogMemberSection {
+  label: string;
+  kind: 'blocks' | 'list';
+  inWhole: boolean;
+  members: string[];
+}
+
+/** Slice D1: one row of a family page's anatomy legend — either a `member` of this page (numbered,
+ *  linked to that member's address) or a component `other`wise documented elsewhere (never
+ *  numbered; linked only when the name resolves to a real catalog address). `description` is this
+ *  legend row's own text, independent of the member's own `description`. */
+export type CatalogAnatomyItem = ({ member: string } | { other: string }) & { description: string };
+
+/** One labeled group of anatomy legend rows (e.g. "In this picture", "No area of their own",
+ *  "From other pages") — a group never splits across legend columns (`AnatomyPin`/`FamilyPage`). */
+export interface CatalogAnatomyGroup {
+  label: string;
+  items: CatalogAnatomyItem[];
+}
+
+/** Slice D1 item 1: the anatomy box at the top of a family page — a picture of the whole with
+ *  numbered pins (via `AnatomyPin`, looked up through context so the picture never hardcodes a
+ *  number), and a legend beside it (six items or fewer) or below it in up to three balanced
+ *  columns. Omit for a family page with no anatomy picture. */
+export interface CatalogAnatomy {
+  picture?: React.ReactNode;
+  groups: CatalogAnatomyGroup[];
+}
+
+/** A family page's members with resolved props and paths, the whole, sections, and the computed
+ *  outline — set on `SectionDef.family` by `buildCatalogSections` when a page has `members`. */
+export interface FamilyDef {
+  whole: string;
+  members: Array<CatalogMember & { props?: PropDef[]; path: string }>;
+  sections: CatalogMemberSection[];
+  outline: Map<string, { number: string; level: number }>;
+  notShown?: string;
+  /** Extra names for the page itself (its whole) — e.g. retired page ids. See
+   *  `CatalogPageInput.aliases`. */
+  aliases?: string[];
+  /** Label for the disclosure's API part (`disclosureLabel`). See `CatalogPageInput.apiLabel`.
+   *  Defaults to `'API'` when absent. */
+  apiLabel?: string;
+  /** Slice D1 item 1. See `CatalogPageInput.anatomy`. */
+  anatomy?: CatalogAnatomy;
+}
+
 /** One titled card on a token page (`SectionDef.tokenSections`). */
 export interface TokenSection {
   /** The kind of token this card holds, e.g. "Semantic colours", "Palette", "Body". */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krapwoo/ds-viewer",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "license": "MIT",
   "type": "module",
   "description": "A browsable, always-current catalog for an Expo / React Native design system.",