@krapwoo/ds-viewer 0.10.0 → 0.12.0

package/README.md

@@ -445,6 +445,88 @@ path. For anything beyond a single list of tokens, use the token-page layouts be
   declared in another component's folder, such as a shared `IconName`, is that component's
   options, so a Banner page never needs one example per icon.
 
+### Family pages
+
+A page can document a family of related declarations — a view and its internal parts, or a
+pattern and the pieces it's built from — on one page instead of scattering them across separate
+catalog pages, each member getting its own address and search entry. Give it `members`, `whole`
+and `sections` instead of `component`/`whenToUse`/`a11y`/specimens, which live on the members (the
+whole is a member too):
+
+```tsx
+export default defineCatalogPage({
+  id: 'Toast', group: 'Patterns', description: 'How a Toast is assembled from a Banner.',
+  whole: 'Toast',
+  sections: [
+    { label: 'Parts', kind: 'blocks', inWhole: true, members: ['ToastBanner'] },
+    { label: 'Related', kind: 'blocks', inWhole: false, members: ['ToastStandaloneBanner'] },
+  ],
+  members: [
+    { id: 'Toast', source: 'components/Toast/Toast.tsx:1', fidelity: 'documentation-only', relationship: 'Main pattern', description: '...' },
+    {
+      id: 'ToastBanner', component: 'Banner', parent: 'Toast',
+      source: 'components/Banner/Banner.tsx:28', fidelity: 'replicated', relationship: 'Anatomy', description: '...',
+      whenToUse: '...', a11y: '...', variants: { items: [/* ... */] },
+    },
+    {
+      id: 'ToastStandaloneBanner', source: 'components/Banner/Banner.tsx:28', fidelity: 'documentation-only', relationship: 'Related',
+      related: 'Wraps ToastBanner directly when a notice should stay until dismissed.', description: '...', aliases: ['BannerStandalone'],
+    },
+  ],
+});
+```
+
+- **`whole`** is a member id, and must equal the page's own `id`. It renders first, with no header
+  of its own (the page title already names it) and no number.
+- **`sections`** (`{ label, kind: 'blocks' | 'list', inWhole, members }`) group the rest: `blocks`
+  renders each member as its own full block (specimens and all); `list` renders one card of folded
+  rows, each a toggle that expands in place. `inWhole` sections render under the page's one
+  "Parts" label; the rest render under its one "Related" label — the only two section labels the
+  page ever shows; each section's own `label` stays in the data (for the anatomy legend and your
+  own reference) but is never rendered. Numbering follows each member's own `parent` (below), not
+  this ordering.
+- **`parent`** nests a member under another (e.g. a subview under its view). A top-level part (an
+  `inWhole` member whose `parent` is the whole, or who has no `parent` at all) is numbered `1`,
+  `2`, `3`… in the order it's first listed across `sections`; a child takes its parent's number
+  plus `.1`, `.2`, … the same way. A Related member (outside every `inWhole` section) gets no
+  number at all.
+- **`anatomy`** (page-level) is the first box after the page head, labeled “Anatomy” like the
+  specimen grids: `{ picture, groups }`, where each group is
+  `{ label, items: [{ member, description } | { other, description }] }`. A `member` item names one
+  of this page's own members (not the whole) and is numbered to match its Part; an `other` item
+  names a component documented elsewhere, shows an unnumbered ↗ pin, and links only when the name
+  resolves to a real catalog address. With six items or fewer the legend sits beside `picture`;
+  with more it goes below it in up to three columns, each group placed in the currently shortest
+  column so the columns end nearly level (a group never splits). Mark `picture` with
+  `<AnatomyPin member="ThatMemberId" />` (its number and style come from the page, so `picture`
+  never hardcodes one) or `<AnatomyPin other="ThatComponent" />`.
+- **`axis`** on a `variants` or `states` slot names the one property that grid varies (e.g.
+  `'Expression'`) and shows as the grid's label. Family pages hide the generic block labels, so
+  give each grid an `axis` there.
+- **`fidelity`** (`'replicated' | 'approximated' | 'documentation-only'`) shows as a small badge.
+  Use `'documentation-only'` for a member with no rendered specimen (no native counterpart to show,
+  or nothing meaningfully different to render).
+- **`related`** is a short sentence for a member outside the whole (e.g. "Wraps X directly …");
+  another member's name inside it becomes a link to that member's own address. **`aliases`** (on a
+  member, or on the page itself) resolve old/retired ids to the right address, for both routing and
+  search — on the page itself, this only takes effect when the page also has `members`; it's
+  accepted but unused on a normal (single-component) page.
+- **`composedOf`** on a member — same shape and meaning as the page-level field above — shows as
+  one "Uses …" line inside the member's own disclosure, after any notes. A name links when it
+  resolves to a real catalog address (a page, another member, or an alias — in this family or any
+  other), otherwise it shows in code; an unknown name logs a `[Catalog]` warning the same way the
+  page-level field's does.
+- **`notShown`** (page-level) is a short "Not shown in the browser: …" line under the page head,
+  for behavior a web catalog can't demonstrate (a timer, a native gesture). A member's own
+  `notShown` works the same way, under its specimens. Like `aliases`, the page-level field only
+  takes effect on a page with `members`.
+- **`apiLabel`** (default `'API'`) renames the disclosure's reference-excerpt part for a host app
+  that generates one (e.g. `'Swift API'`) — never hardcode a specific language's wording. Also
+  only takes effect on a page with `members`.
+- Every component-bound member (one with `component` set) wants a real `whenToUse`, a real `a11y`,
+  and at least one specimen, the same as a normal page's component — `doctor` checks each one.
+  See `viewer-host/viewer-pages/FamilyPage.catalog.tsx` in this repo for a complete, worked example.
+
 ### Token pages
 
 A token page shows each token at its real value with its role. Pick the layout by the token's
@@ -613,10 +695,22 @@ and adds what only a real render shows:
   cells are not visited at all. Usually fixed with a wider `specimenSize`, by stacking the blocks so
   the example gets the full row, or by dropping `itemsFill` from a small instance that should sit
   centered.
+- `page-head-overlap` (error): something is painting on top of a page's own heading. This is the
+  one check measured at **800x600** — Puppeteer's default viewport, and so the size a smoke check
+  judges your catalog at — because the overlap it catches does not appear at 1280 at all: a page
+  title that is a single unbroken identifier (a long Swift type name, say) has no break
+  opportunity for the browser to use, so it keeps its full intrinsic width and paints past its own
+  column into the previous/next buttons. It measures every leaf element carrying text, clips each
+  rect to any ancestor that scrolls or clips (so something scrolled out of view is not reported as
+  covering anything), and reports a pair only when it overlaps the heading by more than 1px in
+  both directions, so a shared edge between neighbours is not a finding. Only the heading is
+  checked: specimens legitimately stack text, and reporting those would bury the one overlap that
+  is always a defect.
 - `render-unavailable` / `render-failed` (errors): no browser, or the catalog didn't start.
 
 It needs `puppeteer` in your project (`npm install --save-dev puppeteer`); ds-viewer doesn't
-install a browser. It takes about two minutes for 50 pages and works with `--json` (progress
+install a browser. It takes about two minutes for 50 pages — plus a moment per page for the
+narrow-viewport heading pass — and works with `--json` (progress
 goes to stderr), `--ci` and `doctor.strict`, so CI can run `npx ds-viewer doctor --render --ci`.
 
 It starts its own catalog on the first free port from 5181. `--port <n>` pins it instead, which

package/dist/cli/doctor.js

@@ -7,6 +7,7 @@ import { importedNames, readStaticPages } from "./staticPage.js";
 import { resolveGlob } from "./glob.js";
 import { sync } from "./sync.js";
 import { gridColumnLimit } from "../native/catalog/comparison.js";
+import { validateComposedOf, validateFamily } from "../native/catalog/pageApi.js";
 function issue(fields) {
     return fields;
 }
@@ -18,9 +19,14 @@ function pageRef(page) {
  *  own file (design §2; the viewer already applies this same default via `page.component ??
  *  page.id`, and the generated page index already defaults a missing `id` to the file stem). A
  *  page from a standalone `pages` glob is never touched — `componentFolders` only ever contains
- *  folders resolved from `config.components`, so a standalone page's own folder is never a member. */
+ *  folders resolved from `config.components`, so a standalone page's own folder is never a member.
+ *  A family page (non-empty `members`) is also never touched — same exemption the runtime applies
+ *  at `pageApi.ts`'s `buildCatalogSections` (`page.members && page.members.length > 0` skips the
+ *  `page.component ?? page.id` fallback entirely): a family's own guidance/examples always live on
+ *  its members, never on the page itself, so a documentation-only whole (its file stem naming no
+ *  real component export) must never be assigned one here either. */
 export function applyComponentDefaults(pages, componentFolders) {
-    return pages.map((page) => page.component === undefined && componentFolders.has(path.dirname(page.file))
+    return pages.map((page) => page.component === undefined && componentFolders.has(path.dirname(page.file)) && !(page.members && page.members.length > 0)
         ? { ...page, component: resolvePageId(page, page.file) }
         : page);
 }
@@ -59,12 +65,22 @@ function pageHasExamples(page) {
 }
 function checkComponentNoExamples(pages, components) {
     const byComponent = new Map();
+    // Plan V3: "a component documented only as a member counts as documented" — any family member
+    // naming a component (regardless of which page, or whether that specific member has its own
+    // examples — a member with none gets its own `component-no-examples` from `checkFamilyMembers`
+    // instead) is enough to clear the component-wide "no catalog page at all" half of this rule.
+    const documentedByMember = new Set();
     for (const page of pages) {
         if (page.component)
             byComponent.set(page.component, [...(byComponent.get(page.component) ?? []), page]);
+        for (const member of page.members ?? [])
+            if (member.component)
+                documentedByMember.add(member.component);
     }
     return components
         .filter((c) => {
+        if (documentedByMember.has(c.name))
+            return false;
         const componentPages = byComponent.get(c.name) ?? [];
         // A not-statically-checkable page is given the benefit of the doubt here — it might have
         // real examples this reader simply couldn't read (Global Constraint: never a partial read;
@@ -83,6 +99,152 @@ function checkComponentNoExamples(pages, components) {
         });
     });
 }
+/** Plan V3: the same two advisories `checkComponentPages` gives a page-level `component` —
+ *  missing guidance/accessibility, and no examples — evaluated per component-bound member of a
+ *  family page instead, with the member id in the message. A documentation-only member (no
+ *  `component`) is exempt from all three. V2c item 9: a member whose `component` no longer
+ *  resolves to a real export gets its own `component-export-removed` error here (below), naming
+ *  the member, instead of being silently exempted. */
+function checkFamilyMembers(pages, components) {
+    const componentsByName = new Map(components.map((c) => [c.name, c]));
+    const issues = [];
+    for (const page of pages) {
+        // V2c item 6: the same "is this really a family page" predicate the runtime uses
+        // (`pageApi.ts`'s `page.members && page.members.length > 0`) — an empty `members` array is a
+        // normal, single-component page, never a family.
+        if (!page.members || page.members.length === 0 || !page.checkable)
+            continue; // never a partial read — see checkGridAxisKeys's own note.
+        const ref = pageRef(page);
+        // Members in a `list` section render as folded rows without specimens, so asking them for
+        // examples would contradict `family-invalid`'s list-section rule.
+        const listMemberIds = new Set((page.sections ?? []).filter((s) => s.kind === 'list').flatMap((s) => s.members));
+        for (const member of page.members) {
+            if (!member.component)
+                continue; // documentation-only — exempt.
+            // V2c item 9: a member naming a component that no longer exists — reported here rather than
+            // silently exempted from every advisory (its props would also silently vanish at runtime).
+            if (!componentsByName.has(member.component)) {
+                issues.push(issue({
+                    id: 'component-export-removed', severity: 'error', ...ref,
+                    message: `Member "${member.id}" documents "${member.component}", which no longer exists as a component export.`,
+                    fix: `Delete this member, or update its "component" to the export's new name.`,
+                }));
+                continue;
+            }
+            if (!member.hasWhenToUse) {
+                issues.push(issue({
+                    id: 'missing-guidance-or-a11y', severity: 'warning', ...ref,
+                    message: `Member "${member.id}": no "whenToUse" guidance documented.`,
+                    fix: `Add a one-sentence whenToUse note for "${member.id}", or omit it only when there genuinely is none.`,
+                }));
+            }
+            if (!member.hasA11y) {
+                issues.push(issue({
+                    id: 'missing-guidance-or-a11y', severity: 'warning', ...ref,
+                    message: `Member "${member.id}": no "a11y" notes documented.`,
+                    fix: `Add a one-sentence a11y note for "${member.id}", grounded in its real behavior.`,
+                }));
+            }
+            if (!member.hasExamples && !listMemberIds.has(member.id)) {
+                issues.push(issue({
+                    id: 'component-no-examples', severity: 'warning', ...ref,
+                    message: `Member "${member.id}" ("${member.component}") has no variants, states, or comparison — it will show no specimen.`,
+                    fix: `Add variants/states/comparison to the "${member.id}" member.`,
+                }));
+            }
+        }
+    }
+    return issues;
+}
+/** Plan V3's `family-invalid`: reuses `native/catalog/pageApi.ts`'s own `validateFamily` —
+ *  the exact same rule `pageApi.ts`'s `buildCatalogSections` runs at runtime — against every
+ *  checkable family page, with the same catalog-wide "every other page/member id" contract that
+ *  function already takes. N3: `StaticPage.sections` already carries each section's real
+ *  `label`/`kind`, so `validateFamily`'s messages name the real section (never an empty label),
+ *  and its N6 list-section rule can tell a `list` section from a `blocks` one. */
+function checkFamilyValidity(pages) {
+    // V2c item 6: `members.length > 0`, the same predicate the runtime uses — an empty array is not
+    // a family page.
+    const familyPages = pages.filter((p) => p.members && p.members.length > 0 && p.checkable);
+    const allPageIds = new Set(pages.map((p) => resolvePageId(p, p.file)));
+    const familyIdsByPageId = new Map();
+    for (const page of familyPages) {
+        const id = resolvePageId(page, page.file);
+        const ids = new Set();
+        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);
+        familyIdsByPageId.set(id, ids);
+    }
+    const issues = [];
+    for (const page of familyPages) {
+        const id = resolvePageId(page, page.file);
+        const otherPageIds = new Set([...allPageIds].filter((pageId) => pageId !== id));
+        const otherMemberIds = new Set();
+        for (const [pageId, ids] of familyIdsByPageId)
+            if (pageId !== id)
+                for (const memberId of ids)
+                    otherMemberIds.add(memberId);
+        const pageLike = {
+            id,
+            whole: page.whole,
+            // `inWhole` is never read by `validateFamily` — only `label`/`kind`/`members` matter here.
+            sections: page.sections?.map((s) => ({ ...s, inWhole: true })),
+            members: (page.members ?? []).map((m) => ({ id: m.id, parent: m.parent, aliases: m.aliases, hasSpecimens: m.hasExamples })),
+            aliases: page.aliases,
+        };
+        for (const message of validateFamily(pageLike, otherPageIds, otherMemberIds)) {
+            issues.push(issue({ id: 'family-invalid', severity: 'error', ...pageRef(page), message, fix: 'Fix the family\'s members/whole/sections to satisfy the rule above.' }));
+        }
+    }
+    return issues;
+}
+/** V2d item 5: resolves each family member's own `composedOf` the same way `buildCatalogSections`
+ *  resolves it at runtime (`native/catalog/pageApi.ts`'s own `validateComposedOf`, imported
+ *  directly — the subpath-import boundary that once made importing that file from `dist/cli/`
+ *  unsafe is gone), against the same known-name universe `checkFamilyValidity` already builds for
+ *  member ids — every real component name, every page id, and every member id across the whole
+ *  catalog — so an unknown name is reported here too, not only ever silently warned in a browser
+ *  console (`npm run check:catalog`). A member whose `composedOf` wasn't itself literally readable
+ *  (`undefined`) has nothing to check — the same "never a partial read" leniency the page-level
+ *  field already gets. Always a warning, the same severity the runtime's own console warning
+ *  carries, never an error. N8: also accepts a member alias and a page-level alias — the same
+ *  universe `FamilyPage`'s own link resolution (`aliasTargets`) already accepts. */
+function checkMemberComposedOf(pages, components) {
+    const knownNames = new Set(components.map((c) => c.name));
+    for (const page of pages)
+        knownNames.add(resolvePageId(page, page.file));
+    for (const page of pages)
+        for (const member of page.members ?? [])
+            knownNames.add(member.id);
+    for (const page of pages)
+        for (const member of page.members ?? [])
+            for (const alias of member.aliases ?? [])
+                knownNames.add(alias);
+    for (const page of pages)
+        for (const alias of page.aliases ?? [])
+            knownNames.add(alias);
+    const issues = [];
+    for (const page of pages) {
+        if (!page.members || page.members.length === 0 || !page.checkable)
+            continue; // V2c item 6's own predicate.
+        const ref = pageRef(page);
+        for (const member of page.members) {
+            for (const message of validateComposedOf(member.composedOf, knownNames)) {
+                issues.push(issue({
+                    id: 'composed-of-unknown', severity: 'warning', ...ref,
+                    message: `Member "${member.id}": ${message}`,
+                    fix: 'Correct the name, or add { component: \'...\', role: \'...\', relationship: \'...\' } for a component/page/member that really does exist.',
+                }));
+            }
+        }
+    }
+    return issues;
+}
 function checkDuplicatePageId(pages) {
     const byId = new Map();
     for (const page of pages) {
@@ -225,7 +387,14 @@ function importsModal(file) {
 }
 /** `overlay-without-device-frame`: a page whose component opens a React Native `Modal` (which
  *  portals to the document body on the web, covering the whole catalog) but whose page imports no
- *  device frame. A page whose imports couldn't be read is skipped, never assumed unframed. */
+ *  device frame. A page whose imports couldn't be read is skipped, never assumed unframed.
+ *  V2c item 3 (CLI side): deliberately exempts a family member's own `component` — this check
+ *  keys off `page.component`/`page.viewerImports` (the page file's own top-level imports), neither
+ *  of which a family page sets; a member naming a Modal-opening component would need its OWN
+ *  device-frame-import evidence, which `cli/staticPage.ts`'s member reader doesn't currently carry.
+ *  Left as a gap rather than guessed at — a family member wrapping a Modal in a device frame is
+ *  rare enough (and the resulting miss only an advisory, never an error) that this is the smallest
+ *  honest fix here. */
 export function checkOverlaysFramed(pages, components, projectRoot) {
     const byName = new Map(components.map((c) => [c.name, c]));
     const issues = [];
@@ -342,6 +511,13 @@ function checkComponentPages(pages, components) {
     for (const page of pages) {
         if (!page.component)
             continue;
+        // Plan V3: a family page's own guidance always lives on its members, never on the page
+        // itself — even if `applyComponentDefaults` (or, in principle, the author) ends up giving it
+        // a page-level `component` matching a real export, this page-level advisory must still defer
+        // entirely to `checkFamilyMembers`'s own per-member one. V2c item 6: `members.length > 0`,
+        // the same predicate the runtime uses — an empty array is not a family page.
+        if (page.members && page.members.length > 0)
+            continue;
         if (!page.checkable)
             continue; // never a partial read — see checkGridAxisKeys's own note.
         const component = componentsByName.get(page.component);
@@ -519,6 +695,9 @@ export function collectIssues(pages, components) {
         ...checkMissingComposition(pages, components),
         ...checkMissingWorkingPreview(pages, components),
         ...checkPreviewOnlyPages(pages),
+        ...checkFamilyMembers(pages, components),
+        ...checkFamilyValidity(pages),
+        ...checkMemberComposedOf(pages, components),
     ];
 }
 /** Issues that aren't tied to one page: `sync`'s own "Could not read" warnings, and a configured

package/dist/cli/render.js

@@ -121,6 +121,83 @@ export function identicalVariantIssues(page, pairs) {
         fix: "Make the difference visible — a wider specimenSize when the cell is too narrow to show it, or the prop the name claims — or drop one of the two examples.",
     }));
 }
+/**
+ * The width the heading check measures at. 800x600 is Puppeteer's own default viewport, which is
+ * what a consumer's smoke check uses unless it says otherwise, so it is the width their catalog is
+ * judged at. Every other check here runs at 1280x800, where this class of overlap does not appear
+ * at all — which is exactly why issue #51 reached a release.
+ */
+export const NARROW_VIEWPORT = { width: 800, height: 600 };
+/**
+ * Runs in the browser: finds anything painting on top of the page's own heading.
+ *
+ * The page head puts the title in a `flex: 1` column beside a non-shrinking pager row. A title
+ * that is one unbroken identifier — a Swift type name, say — has no space for the browser's
+ * default line breaking to use, so without an explicit break opportunity it keeps its full
+ * intrinsic width and paints straight through the column into the pager (issue #51:
+ * `TranscriptMediaUnavailableChip` covered the `←` button by 14x22 at an 800px window). The
+ * reader sees the title and the control drawn over each other, and the title is the page's own
+ * heading, so it is the one thing on the page that must stay readable.
+ *
+ * Measured the way a consumer's own smoke check measures it: every leaf element that carries
+ * text, its rect clipped to each ancestor that handles its own overflow (so a scrolled-away rect
+ * is not reported as covering anything), and a pair counted only when it overlaps by more than
+ * 1px in BOTH directions — a shared edge or a single-pixel seam between neighbours is not an
+ * overlap.
+ *
+ * Only the heading is checked, not every pair on the page. Host specimens legitimately stack text
+ * — a badge over a thumbnail, a caption over a surface — and reporting those would bury the one
+ * overlap that is always a defect. The heading's own descendants are skipped for the same reason:
+ * a heading's `<Text>` child sits inside its `<View>` by construction.
+ */
+export const HEAD_OVERLAP_SCRIPT = `(() => {
+  const doc = document;
+  const CONTAINS = /^(auto|scroll|hidden|clip)$/;
+  const heading = doc.querySelector('[role="heading"]');
+  if (!heading) return [];
+  const clip = (el) => {
+    const r = el.getBoundingClientRect();
+    let x1 = r.left, y1 = r.top, x2 = r.right, y2 = r.bottom;
+    for (let n = el.parentElement; n; n = n.parentElement) {
+      const cs = getComputedStyle(n);
+      if (CONTAINS.test(cs.overflowX) || CONTAINS.test(cs.overflowY)) {
+        const b = n.getBoundingClientRect();
+        if (b.left > x1) x1 = b.left;
+        if (b.top > y1) y1 = b.top;
+        if (b.right < x2) x2 = b.right;
+        if (b.bottom < y2) y2 = b.bottom;
+      }
+    }
+    return { x1: x1, y1: y1, x2: x2, y2: y2 };
+  };
+  const head = clip(heading);
+  if (head.x2 - head.x1 <= 0 || head.y2 - head.y1 <= 0) return [];
+  const out = [];
+  for (const el of doc.querySelectorAll('*')) {
+    if (el.children.length) continue;
+    if (el === heading || heading.contains(el)) continue;
+    const text = (el.textContent || '').trim();
+    if (!text) continue;
+    const r = el.getBoundingClientRect();
+    if (r.width <= 0 || r.height <= 0) continue;
+    const b = clip(el);
+    if (b.x2 - b.x1 <= 0 || b.y2 - b.y1 <= 0) continue;
+    const w = Math.min(head.x2, b.x2) - Math.max(head.x1, b.x1);
+    const h = Math.min(head.y2, b.y2) - Math.max(head.y1, b.y1);
+    if (w > 1 && h > 1) out.push({ other: text.slice(0, 40), w: Math.round(w), h: Math.round(h) });
+  }
+  return out;
+})()`;
+export function headOverlapIssues(ref, overlaps) {
+    return overlaps.map((o) => ({
+        id: 'page-head-overlap',
+        severity: 'error',
+        page: ref.id,
+        ...(ref.file ? { file: ref.file } : {}),
+        message: `At ${NARROW_VIEWPORT.width}px the page heading is covered by "${o.other}" over ${o.w}x${o.h}px.`,
+        fix: 'Let the heading wrap or truncate inside its own column, or move or clip whatever paints over it.',
+    }));
+}
 /**
  * Runs in the browser: finds specimen content that paints outside its cell and cannot be reached.
  *
@@ -213,6 +290,8 @@ const DEV_START_TIMEOUT_MS = 120_000;
 const FIRST_LOAD_TIMEOUT_MS = 300_000;
 const PAGE_TIMEOUT_MS = 120_000;
 const SETTLE_MS = 900;
+/** After a viewport change, long enough for react-native-web to reflow before anything is measured. */
+const RESIZE_SETTLE_MS = 250;
 /** Stops `dev` and everything it started (Expo/Metro): the whole process tree on Windows, the
  *  whole process group elsewhere (Expo stops through dev's own signal handler). Releases the pipes
  *  so this process can exit. `os` is injectable for tests. */
@@ -436,6 +515,20 @@ export async function renderCheck(projectRoot, options = {}) {
                 }
                 if (Array.isArray(clipped))
                     issues.push(...clippedSpecimenIssues({ id, file: options.files?.get(id) }, clipped));
+                // Last, because it is the only check that changes the viewport: the overlap it guards
+                // appears only at a narrow width, and every check above is calibrated at 1280. Advisory
+                // like the two passes above — a failing script must not cost this page its other findings.
+                let headOverlaps;
+                try {
+                    await page.setViewport({ width: NARROW_VIEWPORT.width, height: NARROW_VIEWPORT.height });
+                    await new Promise((r) => setTimeout(r, RESIZE_SETTLE_MS));
+                    headOverlaps = (await page.evaluate(HEAD_OVERLAP_SCRIPT));
+                }
+                catch {
+                    headOverlaps = undefined;
+                }
+                if (Array.isArray(headOverlaps))
+                    issues.push(...headOverlapIssues({ id, file: options.files?.get(id) }, headOverlaps));
                 await page.close();
             }
             catch (error) {

package/dist/cli/staticPage.js

@@ -200,8 +200,137 @@ function readStaticPage(file) {
                 page.internalProps = names;
         }
     }
+    const membersProp = findProp(pageObject, 'members');
+    if (membersProp) {
+        const members = readFamilyMembers(membersProp.initializer, consts, gridNames, sourceFile);
+        if (!members)
+            page.checkable = false;
+        else
+            page.members = members;
+    }
+    const wholeProp = findProp(pageObject, 'whole');
+    if (wholeProp) {
+        const whole = stringLiteral(resolve(wholeProp.initializer, consts, new Set()));
+        if (whole === undefined)
+            page.checkable = false;
+        else
+            page.whole = whole;
+    }
+    const sectionsProp = findProp(pageObject, 'sections');
+    if (sectionsProp) {
+        const sectionsRead = readSections(sectionsProp.initializer, consts);
+        if (!sectionsRead)
+            page.checkable = false;
+        else
+            page.sections = sectionsRead;
+    }
+    const aliasesProp = findProp(pageObject, 'aliases');
+    if (aliasesProp) {
+        const aliases = readStringLiteralArray(aliasesProp.initializer, consts);
+        if (!aliases)
+            page.checkable = false;
+        else
+            page.aliases = aliases;
+    }
     return page;
 }
+/** A literal array of string literals (or same-file `const` references to one) — undefined for
+ *  anything else, including an array containing even one non-literal element. */
+function readStringLiteralArray(node, consts) {
+    const resolved = resolve(node, consts, new Set());
+    if (!ts.isArrayLiteralExpression(resolved))
+        return undefined;
+    const items = [];
+    for (const element of resolved.elements) {
+        const value = stringLiteral(resolve(element, consts, new Set()));
+        if (value === undefined)
+            return undefined;
+        items.push(value);
+    }
+    return items;
+}
+/** Plan V3 / V2c item 5: a literal array of `CatalogMember`-shaped object literals, down to just
+ *  the five fields `cli/doctor.ts` needs (`StaticMember`). Undefined for anything that isn't
+ *  itself a literal array, or whose element isn't an object literal with a literal `id` — the
+ *  same "never a partial read" contract every other array reader here already follows.
+ *  `hasExamples` reuses the same item-reading helpers (`readSlotItems`/`readComparison`) the
+ *  page level uses, rather than a presence-only check — a member authored with `variants: {
+ *  items: [] }` has no real specimen to show, the same way a page-level empty list doesn't.
+ *  N1: a member's own `variants`/`states`/`comparison` follows the exact same "never a partial
+ *  read" contract the page level already does (`readStaticPage`'s own `page.checkable = false`
+ *  for the same three fields) — a non-literal slot or an unreadable comparison makes the whole
+ *  members array (and so the whole page) not checkable, rather than silently reading as "no
+ *  specimen" and firing a confidently false `component-no-examples`. */
+function readFamilyMembers(node, consts, gridNames, sourceFile) {
+    const resolved = resolve(node, consts, new Set());
+    if (!ts.isArrayLiteralExpression(resolved))
+        return undefined;
+    const members = [];
+    for (const element of resolved.elements) {
+        const resolvedElement = resolve(element, consts, new Set());
+        if (!ts.isObjectLiteralExpression(resolvedElement))
+            return undefined;
+        const id = propertyStringLiteral(resolvedElement, 'id', consts);
+        if (id === undefined)
+            return undefined;
+        const component = propertyStringLiteral(resolvedElement, 'component', consts);
+        const parent = propertyStringLiteral(resolvedElement, 'parent', consts);
+        const aliasesProp = findProp(resolvedElement, 'aliases');
+        const aliases = aliasesProp ? readStringLiteralArray(aliasesProp.initializer, consts) : undefined;
+        const composedOfProp = findProp(resolvedElement, 'composedOf');
+        const composedOf = composedOfProp ? readComposedOf(composedOfProp.initializer, consts) : undefined;
+        const variants = readSlotItems(findProp(resolvedElement, 'variants'), consts, component, sourceFile);
+        if (!variants.checkable)
+            return undefined;
+        const states = readSlotItems(findProp(resolvedElement, 'states'), consts, component, sourceFile);
+        if (!states.checkable)
+            return undefined;
+        const comparisonProp = findProp(resolvedElement, 'comparison');
+        let comparison;
+        if (comparisonProp) {
+            comparison = readComparison(comparisonProp.initializer, consts, gridNames);
+            if (!comparison)
+                return undefined;
+        }
+        members.push({
+            id,
+            component,
+            parent,
+            aliases,
+            composedOf,
+            hasWhenToUse: findProp(resolvedElement, 'whenToUse') !== undefined,
+            hasA11y: findProp(resolvedElement, 'a11y') !== undefined,
+            hasExamples: Boolean(variants.items?.length) || Boolean(states.items?.length) || Boolean(comparison),
+        });
+    }
+    return members;
+}
+/** Plan V3 / N3: `CatalogPageInput.sections`, read down to `label`/`kind`/`members` — undefined
+ *  (not checkable) for anything that isn't itself a literal array, or whose element isn't an
+ *  object literal with a literal `label`, a literal `kind` of `'blocks'`/`'list'`, and a literal
+ *  `members` array. */
+function readSections(node, consts) {
+    const resolved = resolve(node, consts, new Set());
+    if (!ts.isArrayLiteralExpression(resolved))
+        return undefined;
+    const sections = [];
+    for (const element of resolved.elements) {
+        const resolvedElement = resolve(element, consts, new Set());
+        if (!ts.isObjectLiteralExpression(resolvedElement))
+            return undefined;
+        const label = propertyStringLiteral(resolvedElement, 'label', consts);
+        const kindProp = findProp(resolvedElement, 'kind');
+        const kind = kindProp ? stringLiteral(resolve(kindProp.initializer, consts, new Set())) : undefined;
+        const membersProp = findProp(resolvedElement, 'members');
+        if (label === undefined || (kind !== 'blocks' && kind !== 'list') || !membersProp)
+            return undefined;
+        const members = readStringLiteralArray(membersProp.initializer, consts);
+        if (!members)
+            return undefined;
+        sections.push({ label, kind, members });
+    }
+    return sections;
+}
 /** 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