@krapwoo/ds-viewer 0.4.6 → 0.4.8

package/README.md

@@ -92,9 +92,15 @@ npm run kit:dev          # builds the CLI, then opens the starter kit's own cata
 npm run check:catalog    # the same headless check CI runs — every page, zero console errors
 ```
 
-`kit-host/` also hosts `viewer-pages/` — standalone catalog pages (not shipped in the package)
-documenting the viewer framework's own pieces (`CatalogShell`, `SectionBlock`, `ComparisonGrid`,
-…), shown under a "Viewer" group alongside the starter kit's own pages.
+The viewer's own building blocks (`CatalogShell`, `SectionBlock`, `ComparisonGrid`, the catalog's
+own colours and type, …) are documented in a separate catalog for people working on ds-viewer
+itself, so the starter kit's catalog shows only what a project using the kit gets:
+
+```bash
+npm run viewer:dev       # opens viewer-host/, the DS Viewer internals catalog (not shipped)
+```
+
+`check:catalog`, `check:doctor` and `check:types` cover both catalogs.
 
 ## Contributing
 
@@ -154,7 +160,13 @@ work. Desktop and laptop screens only. `SectionBlock` renders one page: breadcru
 description, previous/next, then the specimens, then always-visible
 **Guidance** and **Quick reference** (source path, accessibility), then **Props** in their own box
 (two columns, filled across first, when there are 4+ props and room). Token pages show only
-Quick reference with the source path. The specimens use one of four layouts:
+Quick reference with the source path. Guidance, Quick reference, and — only for a page with
+confirmed `composedOf` entries — Composition lay out from the reference card's own measured inner
+width, not viewport width alone: three columns side by side only when there's confirmed composition
+*and* the card is wide enough for all three (Composition gets its own column only then; otherwise
+it stays nested under Quick reference, as it always has), two when there's room for Guidance and
+Quick reference side by side, or one stacked column — in full document order, nothing dropped —
+when the card is too narrow even for two. The specimens use one of four layouts:
 - **Grid** — two props that combine freely, from an explicit `comparison` (e.g. Button's
   Variant × State).
 - **Grouped rows** — one row per variant holding that variant's own configurations (e.g.
@@ -199,6 +211,17 @@ actually apply:
   cell gray, `'white'` or `'transparent'` keeps them all white, and `'dark'` checks a light
   component on a dark fill. Detection runs in the browser viewer; elsewhere cells stay white.
   Token galleries and sections are never filled.
+- A `variants`/`states` item's own `fill`/`surface`/`align` — override the page's `specimenSurface`
+  (above), stretch just *this* item's wrapper to the row's full width, or change how its content
+  aligns inside that wrapper, for one instance that needs any of the three independently of its
+  siblings (e.g. a single `fullWidth` Button among otherwise compact, centered ones, or one
+  white-on-white example that needs its own gray backing even though the page's guess is right for
+  every other item). Omit any of them to inherit the slot's/page's own default: `fill` inherits the
+  slot's `itemsFill` (an explicit `fill: false` still overrides an inherited `itemsFill: true`), and
+  `align` defaults to centered, or to a stretched, full-width fill specimen's own content when
+  `fill` is set — a capped-width `fill` specimen that still wants centering (e.g. a phone-frame
+  preview) sets `align: 'center'` explicitly. The same `fill`/`surface`/`align` fields exist on each
+  authored `comparison` cell too, independently per cell, for exactly the same reasons.
 - `variants`/`states`' own `maxColumns: 1 | 2 | 3 | 4 | 5` — caps how many columns that slot's list
   ever wraps into (e.g. a 3-item size scale that should always read as one row of exactly 3, never
   more just because a laptop is wide). A narrow window still drops below the cap when it has to —
@@ -206,29 +229,89 @@ actually apply:
 - `group` on a `states` item — the `variants` key it belongs to (a size that only exists for one
   variant). Grouped states render one row per variant; ungrouped ones go to "Other configurations".
 - `composedOf: [{ component, role, relationship }]` — what this component is built from or
-  composed with, shown as a "Composition" subsection in Quick reference. `relationship` is
-  `'built-in'` for a component always present inside this one (e.g. Toast is built from a Banner),
-  `'slot'` for an optional caller-supplied child (e.g. a `leadingIcon` prop), or `'related'` for a
-  component commonly used alongside this one without either containing the other. `component` should be
-  a real component or page id: while you browse the catalog in development, an unknown name logs a
-  `[Catalog]` warning in the browser console. `doctor` doesn't check it, and it never fails a
-  build — e.g.
+  composed with, shown in Composition (its own column when space permits, otherwise under Quick reference). `relationship` is
+  `'built-in'` for a component that's part of this one's own implementation — always rendered, or
+  rendered only for some of its variants/states (e.g. Toast is built from a Banner),
+  `'slot'` for an optional caller-supplied child (e.g. a `leadingIcon`
+  prop), or `'related'` for a component commonly used alongside this one without either containing
+  the other. `component` should be a real component or page id: while you browse the catalog in
+  development, an unknown name logs a `[Catalog]` warning in the browser console. `doctor` doesn't
+  check it, and it never fails a build — e.g.
   `composedOf: [{ component: 'Icon', role: 'Leading glyph', relationship: 'slot' }]`.
+- `BoundedOverlayViewport` — wrap one demo whose own modal/sheet/portal would otherwise escape its
+  card and cover the whole catalog page (React Native Web's `Modal` portals into `document.body`;
+  no wrapper or `overflow: hidden` gives it a different boundary). Opt in per item, never per page:
+  ```tsx
+  import { BoundedOverlayViewport, comparisonCellItemKey } from '@krapwoo/ds-viewer';
+
+  { key: 'full-height', name: 'Full height', node: (
+    <BoundedOverlayViewport pageId="Sheet" slot="states" itemKey="full-height" width={360} height={600}>
+      <MyOverlayDemo />
+    </BoundedOverlayViewport>
+  ) }
+  ```
+  Here `MyOverlayDemo` is your existing stateful wrapper around the real component, not a viewer
+  export. `itemKey` is that item's own `VariantExample.key` for a `variants`/`states` item, or
+  `comparisonCellItemKey(rowKey, columnKey)` (import it — never join the two keys yourself; a plain
+  `${rowKey}:${columnKey}` is ambiguous whenever either key already contains a colon) for a
+  `comparison` cell. `width` is only a maximum — the stage still shrinks to whatever its real
+  owning cell actually has at a narrower width — and `height` is the child document's exact usable
+  height, never renegotiated; both must be finite and strictly positive or the specimen shows an
+  honest "This example is unavailable right now." instead of an iframe sized to a meaningless
+  bound. Browser-only: it opens a same-origin child document that boots this catalog's own app
+  entry/module/provider tree, so the wrapped demo's overlay opens inside that document's own
+  viewport instead of the outer page's `document.body`; the two documents stay independently
+  owned, with no shared memory or provider identity between them. On a native runtime, and inside
+  the one child document that the address itself selects, `children` render inline with no
+  boundary — never read either case as native containment parity.
 - `previewWidths: [402, 320]` — extra preview widths for a `render()` page (each capped at 402).
-  `CatalogShell`'s `defaultPreviewWidths="full"` keeps a catalog's previews full width.
+  Add a second width only when the component looks different there (labels truncate, a row
+  wraps); otherwise it's the same picture twice. Leave it out by default.
+- **`PhoneFrame`** — wrap a demo that is a whole screen or opens an overlay (a sheet, a dialog, a
+  toast sliding in, a dropdown's picker) in `<PhoneFrame>`. It is a real device: the demo lays out
+  in an iPhone SE viewport (375 × 667 points), scaled down only when its cell is narrower. In the
+  browser viewer it opens that example in its own device-sized document, so overlays that portal
+  to the page (React Native's `Modal`) open inside the phone, not over the catalog.
+- Full-width (`itemsFill`) variants and states wrap at most **3** across; set `maxColumns` to
+  change that. A filled example that keeps its own fixed width is centred in its cell.
+  Default to one preview; add a second width only when a narrower (or wider) viewport actually
+  changes something worth comparing — wrapping, truncation, or reflow — not just to show the same,
+  identically-laid-out content twice. `CatalogShell`'s `defaultPreviewWidths="full"` keeps a
+  catalog's previews full width.
+- `previewLayout: 'table'` — opt in to one shared, bordered card for a `render()` page's widths,
+  instead of the default `'frames'` (one bordered frame per width, side by side; unchanged unless
+  you set this). Each width keeps its own caption and stays an independent, stateful live instance
+  either way — `'table'` only changes how they're grouped visually. Widths that don't fit the
+  available space side by side wrap to stacked columns, each still captioned, rather than scrolling
+  or shrinking below their requested size. Has no effect on a `'full'` preview width (catalog
+  chrome) or a token gallery — those always render as `'frames'`.
 - `variants: { desc?, align?, itemsFill?, items: [{ key, name, node }] }` — one item per prop enum
   value (e.g. every `variant`). If the component has no `variant`-like prop at all, still include one
-  item named `"Default"` showing its plain look — the Variants column should never be empty.
+  item named `"Default"` showing its plain look — a page that documents its component through a
+  `variants` list should never leave that column empty. This doesn't mean every page must use
+  `variants`: a page that reaches for `render()` instead (see below) has no Variants column to fill
+  in the first place.
 - `states: { desc?, align?, itemsFill?, items: [{ key, name, node }] }` — one item per meaningfully
   distinct boolean state (`loading`, `disabled`, icon-only, …). Fine to omit if there are none.
 
 Every item's `name` is shown as its cell caption (e.g. `"Primary"`, `"Icon-only"`) — use the
 actual variant/state value, not a generic label. Omit `states` when there are none — the page simply
-shows no States block; don't invent items just to fill it. Set `itemsFill: true` on a slot whose
-items are wide, block-level components (Banner, Card, Toast, InputField) rather than small ones meant
-to sit centered (Button, Badge, Pill). Reach for `render()` instead of `variants` only when the
-content isn't a simple list of instances (a live demo with local state, a wrapping grid); its output
-renders in a Preview card (phone width for components). For a token-gallery section with no component API at all (raw token
+shows no States block; don't invent items just to fill it. Avoid a static prop matrix (a `states`
+item, or a `comparison` cell, for every combination) when two configurations only actually look
+different mid-transition and render identically at rest, or when the "closed" side of a toggle is
+just a redundant blank cell next to its "open" counterpart — show that behavior with one interactive
+example instead, with its own working toggle, rather than several now-identical static ones. Set
+`itemsFill: true` on a slot whose items are wide, block-level components (Banner, Card, Toast,
+InputField) rather than small ones meant to sit centered (Button, Badge, Pill).
+
+A `variants`/`states` item's `node` can be a plain instance, or a small stateful wrapper component
+(its own `useState` and all) that renders the real component live — a toggle demo for a
+`Collapsible`, say. That local state belongs to the item's own node, not to the page; it doesn't by
+itself mean the page needs `render()`. Reach for `render()` instead of `variants`/`states` only for a
+genuine custom composition that doesn't fit a list of independent instances at all — several demos
+sharing one measured layout, a wrapping grid, a token gallery — not merely because an item has local
+state. `render()`'s output renders in a Preview card (phone width for components). For a
+token-gallery section with no component API at all (raw token
 data, not a component — see `ColorsGallery`/`SpacingGallery`/`TypographyGallery`), set
 `tokenGallery: true` instead of `props`/`a11y`/`states` — `SectionBlock` then renders `render()`'s
 output full width under a "Tokens" label and shows only a Quick reference card with the source
@@ -240,9 +323,9 @@ path. For anything beyond a single list of tokens, use the token-page layouts be
   `Components`. A page's `group` is a plain string shown as its sidebar section label;
   `groupOrder` (e.g. `['Tokens', 'Components', 'Patterns', 'Recipes', 'Experiences']`) only
   controls which order those sections appear in, top to bottom — any group not listed sorts
-  alphabetically after the ones that are. This starter kit's own two groups (`Tokens`, then
-  `Components`) are one valid shape, not the only one: a larger catalog might add `Patterns`
-  (reusable combinations like a settings row), `Recipes` (worked end-to-end screens), or
+  alphabetically after the ones that are. The starter kit uses `Tokens`, then every
+  component under `Components`, then `Patterns` (whole screens built from the kit, such as
+  SavedTrips) and `Reference` (the generated manifest). A larger catalog might add `Recipes` or
   `Experiences` (full flows) alongside them. Pages sort A–Z inside each group regardless of how
   many groups you have. Avoid splitting `Components` into finer categories such as "Actions" or
   "Status" purely to browse by — that makes readers guess where a component lives; search and A–Z
@@ -363,6 +446,23 @@ Button
 - `--ci` exits 1 only when an error was found — a warning alone never fails CI, and `--ci` never makes a network call.
 - `doctor.strict: true` in `ds-viewer.config.ts` promotes every warning to an error, for both the summary counts and `--ci`'s exit code.
 - A page whose layout data (`specimenSize`, `group`, grid `rows`/`columns`, list items' `key`/`name`/`props`/`group`, `propNotes` keys) isn't a literal — written as something other than a literal value, array, object, or a same-file `const` reference — gets one "page not statically checkable" warning. A page file that fails to parse *or typecheck* is `page-parse-error` instead: every page file is also run through the TypeScript type checker (the same way a component file already is), so a genuine syntax or type error in a page is reported with its line.
+- Three further rules are conservative source-backed *suggestions*, warnings by default
+  (the existing `doctor.strict` option still promotes them), never authoritative over what a page authors:
+  - `missing-composition-suggestion` — a component's own real JSX source evidence names another
+    known component its page's `composedOf` doesn't. The message states only that candidate's
+    `component`/`file`/`line`, never an invented role or relationship; add it to `composedOf`
+    yourself if it reflects real composition, or leave it as-is if it's incidental.
+  - `degenerate-grid-axis` — an authored `comparison` grid's row or column axis has exactly one
+    item, so it reads as a one-axis list rather than a real two-axis matrix. Never rewrites the
+    grid; an intentional single-value axis is left exactly as authored.
+  - `missing-working-preview` — a component has a controlled value/change pair (`value`/`onChange`,
+    or `x`/`onXChange`) but every example that renders it passes a fixed value with no working
+    callback. Add `intentionalStaticPreview: { reason: '...' }` to the page to suppress it when the
+    static examples are deliberate.
+  The analyzer follows supported aliases and resolved exports, but uncertain wrappers or
+  dynamically-constructed references remain uncheckable rather than being guessed at. A
+  declared `intentionalStaticPreview` is taken as the author's own call, not independently
+  verified; only a real browser check confirms actual behavior.
 
 ## Known gaps
 

package/dist/cli/doctor.js

@@ -145,6 +145,140 @@ function checkGridColumnLimit(pages) {
     }
     return issues;
 }
+/** Guided intelligence design §2 / plan Task 3 — `degenerate-grid-axis`: warns (never errors) when
+ *  a grid's row or column axis has exactly one item — it then reads as a one-axis list, not a real
+ *  two-axis comparison. Deliberately its own, separate advisory from the existing hard grid-validity
+ *  errors above (`grid-axis-key-invalid`, `grid-column-limit`): authors keep full authority to leave
+ *  it as authored; this never silently rewrites the matrix and never promotes to an error. */
+function checkDegenerateGridAxis(pages) {
+    const issues = [];
+    for (const page of pages) {
+        if (!page.checkable || !page.comparison)
+            continue; // never a partial read — see checkGridAxisKeys's own note.
+        const { rows, columns } = page.comparison;
+        for (const [axisName, axis] of [['row', rows], ['column', columns]]) {
+            if (axis.items.length === 1) {
+                issues.push(issue({
+                    id: 'degenerate-grid-axis', severity: 'warning', ...pageRef(page),
+                    message: `This grid's ${axisName} axis has only 1 item; it reads as a one-axis list, not a two-axis comparison.`,
+                    fix: `If this axis genuinely only ever has one value, consider a Variants/States list instead; otherwise add more items to it.`,
+                }));
+            }
+        }
+    }
+    return issues;
+}
+/** Guided intelligence design §4 / plan Task 3 — `missing-composition-suggestion`: compares each
+ *  documented component's optional, additive `composedOfCandidates` (`cli/props.ts`, real JSX
+ *  source evidence) against the page's own authored `composedOf` names, and suggests — never
+ *  confirms — a candidate the author hasn't named. Conservative by construction: a candidate's own
+ *  `component`/`file`/`line` is all the message ever states, never an invented role or relationship
+ *  (that stays the author's own call via `composedOf`). Never fires when `composedOf` was authored
+ *  but isn't itself literally readable (`page.hasComposedOf && page.composedOf === undefined`) —
+ *  the candidate might already be named there; this rule must never risk a false "missing" claim.
+ *  Only suggests a name the viewer itself would accept in `composedOf` — a detected component or a
+ *  page id (`buildCatalogSections`' own check); anything else (a plain helper such as a starter
+ *  kit's `Icon`) would only trade this warning for an "unknown component" one. One issue per
+ *  component per page, citing its first call site. */
+function checkMissingComposition(pages, components) {
+    const componentsByName = new Map(components.map((c) => [c.name, c]));
+    const knownNames = new Set([...componentsByName.keys(), ...pages.map((p) => p.id).filter((id) => Boolean(id))]);
+    const issues = [];
+    for (const page of pages) {
+        if (!page.component || !page.checkable)
+            continue;
+        if (page.hasComposedOf && page.composedOf === undefined)
+            continue;
+        const component = componentsByName.get(page.component);
+        const candidates = component?.composedOfCandidates;
+        if (!candidates || candidates.length === 0)
+            continue;
+        const authored = new Set((page.composedOf ?? []).map((entry) => entry.component));
+        const seen = new Set();
+        for (const candidate of candidates) {
+            if (authored.has(candidate.component) || !knownNames.has(candidate.component) || seen.has(candidate.component))
+                continue;
+            seen.add(candidate.component);
+            issues.push(issue({
+                id: 'missing-composition-suggestion', severity: 'warning', ...pageRef(page),
+                message: `"${component.name}" renders "${candidate.component}" (${candidate.file}:${candidate.line}), which composedOf doesn't name.`,
+                fix: `Add { component: '${candidate.component}', ... } to composedOf with the role/relationship you choose, if this reflects real composition — or leave it if it's incidental.`,
+            }));
+        }
+    }
+    return issues;
+}
+/** A function-typed prop's printed type always contains `=>` (`cli/props.ts`'s own displayed type
+ *  strings — "(value: string) => void", "() => void", …); a plain data prop's never does. */
+function isFunctionPropType(type) {
+    return type.includes('=>');
+}
+/** Guided intelligence design §3 / plan Task 3 — finds a component's controlled state/event pair:
+ *  a non-function prop `x` paired with a function-typed prop named `onXChange` (PascalCase), or the
+ *  universal `value`/`onChange` pair. "Confidently identifiable" by naming convention alone — never
+ *  a claim about actual behavior (that's `checkMissingWorkingPreview`'s own job, from the page's
+ *  examples). Undefined when no such pair exists. */
+function findControlledPair(component) {
+    for (const prop of component.props) {
+        if (isFunctionPropType(prop.type))
+            continue;
+        const expectedChangeProp = prop.name === 'value' ? 'onChange' : `on${prop.name.charAt(0).toUpperCase()}${prop.name.slice(1)}Change`;
+        const changeProp = component.props.find((p) => p.name === expectedChangeProp);
+        if (changeProp && isFunctionPropType(changeProp.type))
+            return { valueProp: prop.name, changeProp: changeProp.name };
+    }
+    return undefined;
+}
+/** Guided intelligence design §3 / plan Task 3 — `missing-working-preview`: recommends a real,
+ *  stateful preview only when BOTH hold: the documented component has a controlled state/event pair
+ *  (`findControlledPair`), AND every example that directly renders it (`nodeDirectComponent`)
+ *  confidently demonstrates a fixed value with a no-op/omitted callback. Conservative by
+ *  construction — never fires when:
+ *   - the page already has its own `render()` (design's own escape hatch for live demos, never
+ *     statically inspectable here);
+ *   - the author declared `intentionalStaticPreview` with a reason (tolerated, not overridden);
+ *   - any example is a confidently-identified genuine stateful wrapper (`nodeStatefulWrapper`) —
+ *     positive evidence the page is already interactive;
+ *   - no example directly renders the component at all, or any direct example's value/callback is
+ *     `'unknown'` — genuinely uncheckable, and "uncheckable" must never be reported as "inert".
+ *  Never a newly-fatal gate: always a warning, same as every other advisory in this file. */
+function checkMissingWorkingPreview(pages, components) {
+    const componentsByName = new Map(components.map((c) => [c.name, c]));
+    const issues = [];
+    for (const page of pages) {
+        if (!page.component || !page.checkable || page.hasRender)
+            continue;
+        if (page.intentionalStaticPreviewReason)
+            continue;
+        const component = componentsByName.get(page.component);
+        if (!component)
+            continue;
+        const pair = findControlledPair(component);
+        if (!pair)
+            continue;
+        const items = [...(page.variantsItems ?? []), ...(page.statesItems ?? [])];
+        if (items.some((i) => i.nodeStatefulWrapper))
+            continue;
+        const directItems = items.filter((i) => i.nodeDirectComponent === component.name);
+        if (directItems.length === 0)
+            continue;
+        const allStaticInert = directItems.every((i) => {
+            const valueAttr = i.nodeAttributes?.[pair.valueProp];
+            const changeAttr = i.nodeAttributes?.[pair.changeProp];
+            return valueAttr?.kind === 'literal' && (changeAttr === undefined || changeAttr.kind === 'no-op-callback');
+        });
+        if (!allStaticInert)
+            continue;
+        issues.push(issue({
+            id: 'missing-working-preview', severity: 'warning', ...pageRef(page),
+            message: `"${component.name}" has a controlled "${pair.valueProp}"/"${pair.changeProp}" pair, but every example passes a fixed "${pair.valueProp}" ` +
+                'with no working callback.',
+            fix: `Add a working example using local state (useState) that wires "${pair.valueProp}" to "${pair.changeProp}", ` +
+                'or declare intentionalStaticPreview with a reason if the examples are deliberately static.',
+        }));
+    }
+    return issues;
+}
 /** Everything that needs a page's own matching `ComponentRecord` to check: `propNotes`, bound
  *  axes, tagged list items, coverage, grouped-state matching, and guidance/a11y presence. One
  *  function because every one of these checks shares the same per-page `component`/`propsByName`
@@ -305,7 +439,10 @@ export function collectIssues(pages, components) {
         ...checkDuplicatePageId(pages),
         ...checkGridAxisKeys(pages),
         ...checkGridColumnLimit(pages),
+        ...checkDegenerateGridAxis(pages),
         ...checkComponentPages(pages, components),
+        ...checkMissingComposition(pages, components),
+        ...checkMissingWorkingPreview(pages, components),
     ];
 }
 /** Issues that aren't tied to one page: `sync`'s own "Could not read" warnings, and a configured
@@ -343,7 +480,9 @@ export function checkPageTypeErrors(pages, options = {}) {
     // `createComponentReader` (where a mismatch only degrades prop reading silently; here it would
     // produce CI-failing errors the host's own `tsc` would never raise). Only `noEmit`,
     // `skipLibCheck`, and the merged `paths` are forced on top.
-    const host = readHostTsconfigOptions(pageFiles[0]);
+    // `readHostTsconfigOptions` searches upward from the given file's folder; a file name inside
+    // `hostRoot` starts that search at the host's own root.
+    const host = readHostTsconfigOptions(options.hostRoot ? path.join(options.hostRoot, 'ds-viewer.config.ts') : pageFiles[0]);
     const compilerOptions = {
         ...host.options,
         noEmit: true,
@@ -432,7 +571,7 @@ export function runDoctor(config) {
         : undefined;
     let issues = [
         ...collectIssues(pages, components),
-        ...checkPageTypeErrors(pages, { fallbackPaths }),
+        ...checkPageTypeErrors(pages, { fallbackPaths, hostRoot: config.projectRoot }),
         ...collectGlobalIssues({ syncWarnings: syncResult.warnings, tokenFileCount }),
     ];
     // Design's own `--json` example gives a project-relative `file`; `StaticPage.file` is absolute

package/dist/cli/explain.js

@@ -6,7 +6,29 @@ import { axisItems, choosePlacement, gridColumnLimit, listGeometry, presentation
 import { CATALOG_LAYOUT } from "../native/catalog/tokens.js";
 import { sectionColumns } from "../native/catalog/tokenLayout.js";
 function placeholderItem(item) {
-    return { key: item.key, name: item.name, node: null, group: item.group };
+    return {
+        key: item.key, name: item.name, node: null, group: item.group,
+        fill: item.fill, surface: item.surface, align: item.align,
+    };
+}
+/** How many of a block's entries (list/grouped items, or grid cells, named by `noun`) override a
+ *  given `SpecimenPresentation` field, as a trailing sentence fragment — empty when none do, so an
+ *  unremarkable block's reason stays unchanged. Shared by every one of the four override-note
+ *  functions below so a list item's and a grid cell's own surface/alignment override are reported
+ *  identically. */
+function overrideNote(entries, field, label, noun) {
+    const overridden = entries.filter((entry) => entry[field] !== undefined).length;
+    return overridden > 0 ? ` ${overridden} ${noun}${overridden === 1 ? '' : 's'} override${overridden === 1 ? 's' : ''} the ${label}.` : '';
+}
+function surfaceOverrideNote(items) {
+    return overrideNote(items, 'surface', 'surface', 'item');
+}
+function alignOverrideNote(items) {
+    return overrideNote(items, 'align', 'alignment', 'item');
+}
+/** Same pair of override notes, worded for a grid's cells rather than a list's items. */
+function cellOverrideNote(cells) {
+    return overrideNote(cells, 'surface', 'surface', 'cell') + overrideNote(cells, 'align', 'alignment', 'cell');
 }
 /** A throwaway `SectionDef` built from a `StaticPage` (Task 3) — every specimen's `node` is `null`
  *  (design §4: specimen nodes are never evaluated), since none of the layout functions below ever
@@ -19,7 +41,13 @@ function toSectionDef(page) {
         columnLabel: page.comparison.columnLabel ?? '',
         rows: page.comparison.rows.prop !== undefined ? { prop: page.comparison.rows.prop, items: page.comparison.rows.items } : page.comparison.rows.items,
         columns: page.comparison.columns.prop !== undefined ? { prop: page.comparison.columns.prop, items: page.comparison.columns.items } : page.comparison.columns.items,
-        cells: [],
+        // Present only for a direct object-literal `comparison` (never a `grid()` call, whose `cell`
+        // callback is unevaluated) whose `cells` array was itself literal — see `StaticComparison.cells`.
+        // `node: null` the same way every other placeholder specimen here is never evaluated.
+        cells: (page.comparison.cells ?? []).map((cell) => ({
+            rowKey: cell.rowKey, columnKey: cell.columnKey, node: null,
+            fill: cell.fill, surface: cell.surface, align: cell.align,
+        })),
         size: page.comparison.size,
     };
     return {
@@ -47,7 +75,7 @@ function explainBlock(block) {
         return {
             kind: 'grid', title: block.title,
             reason: `${rows} rows × ${columns} columns (${block.size}); ${columns} of ${limit} max ${block.size} columns used — ` +
-                `${columns <= limit ? 'fits' : 'does NOT fit'} a 1280px laptop.`,
+                `${columns <= limit ? 'fits' : 'does NOT fit'} a 1280px laptop.` + cellOverrideNote(block.comparison.cells),
         };
     }
     if (block.kind === 'list') {
@@ -55,11 +83,16 @@ function explainBlock(block) {
         return {
             kind: 'list', title: block.title,
             reason: `${block.items.length} items (${block.size}) → ${geometry.columns} columns × ${geometry.rows} row${geometry.rows === 1 ? '' : 's'}` +
-                (geometry.fillers > 0 ? ` (${geometry.fillers} filler${geometry.fillers === 1 ? '' : 's'})` : '') + '.',
+                (geometry.fillers > 0 ? ` (${geometry.fillers} filler${geometry.fillers === 1 ? '' : 's'})` : '') + '.' +
+                surfaceOverrideNote(block.items) + alignOverrideNote(block.items),
         };
     }
     if (block.kind === 'grouped') {
-        return { kind: 'grouped', title: block.title, reason: `${block.groups.length} variant row(s), each with its own configurations.` };
+        const items = block.groups.flatMap((group) => group.items);
+        return {
+            kind: 'grouped', title: block.title,
+            reason: `${block.groups.length} variant row(s), each with its own configurations.${surfaceOverrideNote(items)}${alignOverrideNote(items)}`,
+        };
     }
     if (block.kind === 'preview') {
         const widths = block.widths === 'full' ? 'full width' : `${block.widths.join('/')}px`;
@@ -145,7 +178,7 @@ export function explainPage(config, pageId, options = {}) {
             };
         }
     }
-    return { pageId, blocks: explained, placement };
+    return { pageId, blocks: explained, placement, intentionalStaticPreviewReason: page.intentionalStaticPreviewReason };
 }
 export function formatExplain(result) {
     if (result.notCheckable) {
@@ -160,6 +193,11 @@ export function formatExplain(result) {
     if (result.placement) {
         lines.push('Placement');
         lines.push(`  ${result.placement.reason}`);
+        lines.push('');
+    }
+    if (result.intentionalStaticPreviewReason) {
+        lines.push('Intentionally static preview');
+        lines.push(`  ${result.intentionalStaticPreviewReason}`);
     }
     return lines.join('\n').replace(/\n+$/, '');
 }

package/dist/cli/init.js

@@ -141,14 +141,11 @@ function ensureSharedProjectFiles(projectRoot) {
     return written;
 }
 const KIT_REQUIRED_PACKAGES = ['react-native-svg', 'react-native-safe-area-context'];
-/** The starter kit's own intended sidebar order (the same list kit-host/ds-viewer.config.ts
- *  declares, minus "Viewer" — that group only holds kit-host's own framework-docs pages under
- *  `viewer-pages/`, which `init --new` never copies). Written into a fresh project's config so its
- *  sidebar isn't left alphabetical (controller end-to-end finding E3). */
-const KIT_GROUP_ORDER = [
-    'Actions', 'Surfaces', 'Inputs', 'Controls', 'Selection', 'Feedback', 'Navigation',
-    'Overlays', 'Layout', 'Sub-Parts', 'Recipes', 'Tokens', 'Reference',
-];
+/** The starter kit's own sidebar order (the same list kit-host/ds-viewer.config.ts declares),
+ *  written into a fresh project's config. Follows the README's "Organising the catalog": Tokens,
+ *  then every component in one A–Z group, then the non-component kinds of page (Patterns: whole
+ *  screens built from the kit; Reference: the generated manifest). */
+const KIT_GROUP_ORDER = ['Tokens', 'Components', 'Patterns', 'Reference'];
 /** Default `installer` — a real `npx expo install`, run only for whichever of
  *  `KIT_REQUIRED_PACKAGES` the project doesn't already depend on. Test-injected in every unit test
  *  (this plan's Global Constraints: never run a real `expo install` in tests). */

package/dist/cli/props.js

@@ -185,7 +185,86 @@ function readComponentRecord(checker, name, type, declaration, optionRoots, comp
         }
     }
     const inheritedFrom = propsType ? nodeModulesHeritageNames(checker, propsType.isUnion() ? propsType.types : [propsType]) : [];
-    return { name, file: path.relative(process.cwd(), sourceFile.fileName), props, inheritedFrom };
+    const composedOfCandidates = readComposedOfCandidates(checker, declaration);
+    return {
+        name,
+        file: path.relative(process.cwd(), sourceFile.fileName),
+        props,
+        inheritedFrom,
+        ...(composedOfCandidates.length > 0 ? { composedOfCandidates } : {}),
+    };
+}
+/** Optional, additive source evidence (guided-intelligence design §4, plan Task 3): every other
+ *  known, project-local component this component's own implementation renders as a literal JSX
+ *  tag. Scoped to exactly the implementation function's own body (the same function
+ *  `defaultsFromImplementation` already unwraps through `React.memo`/`forwardRef`) — a same-file
+ *  helper's own JSX, or a different export's JSX, is never walked at all, since traversal never
+ *  starts there. Only a JSX tag that is a bare identifier resolving (through import aliases and
+ *  barrel re-exports) to an exported symbol satisfying `isComponentType` becomes a candidate; a
+ *  type-only import can never reach here (it cannot be used as a JSX tag at all), an import that is
+ *  never written as a JSX tag is never visited, and a locally-computed/conditional tag identifier
+ *  (not itself an import alias) is left uncertain rather than guessed at. A `node_modules`
+ *  declaration (a framework primitive, not a project component) is excluded — "known canonical
+ *  component export" means part of this project's own component surface. */
+function readComposedOfCandidates(checker, declaration) {
+    const startNode = ts.isVariableDeclaration(declaration) && declaration.initializer ? declaration.initializer : declaration;
+    const fn = resolveFunctionLike(startNode, new Set());
+    if (!fn?.body)
+        return [];
+    const candidates = [];
+    const visit = (node) => {
+        // A nested named helper (a local `function foo() {}` declaration, or a `const foo = () => {}`/
+        // `function expression` assignment) defines its own scope: its JSX belongs to it, not to this
+        // component, even when this component calls it as an ordinary function — so its body is never
+        // walked at all, matching the top-level sibling-helper behavior this already preserved.
+        if (isNestedNamedHelper(node))
+            return;
+        if ((ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) && ts.isIdentifier(node.tagName)) {
+            const candidate = resolveComposedOfCandidate(checker, node.tagName);
+            if (candidate)
+                candidates.push(candidate);
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(fn.body);
+    return candidates;
+}
+function isNestedNamedHelper(node) {
+    if (ts.isFunctionDeclaration(node) && node.name)
+        return true;
+    return (ts.isVariableDeclaration(node) &&
+        ts.isIdentifier(node.name) &&
+        node.initializer !== undefined &&
+        (ts.isArrowFunction(node.initializer) || ts.isFunctionExpression(node.initializer)));
+}
+/** Resolves one JSX tag identifier to a composedOfCandidate, or undefined when it isn't a known,
+ *  project-local component export reached through an import alias (directly or through one or more
+ *  barrel re-exports). */
+function resolveComposedOfCandidate(checker, tagName) {
+    let symbol = checker.getSymbolAtLocation(tagName);
+    if (!symbol)
+        return undefined;
+    // Only a tag identifier that is itself bound to an import (an Alias symbol) counts — a locally
+    // computed/conditional identifier (e.g. `const Comp = cond ? A : B`) is left uncertain even if its
+    // inferred type happens to satisfy `isComponentType`.
+    if (!(symbol.flags & ts.SymbolFlags.Alias))
+        return undefined;
+    const seen = new Set();
+    while (symbol.flags & ts.SymbolFlags.Alias && !seen.has(symbol)) {
+        seen.add(symbol);
+        symbol = checker.getAliasedSymbol(symbol);
+    }
+    const resolvedDeclaration = symbol.valueDeclaration;
+    if (!resolvedDeclaration)
+        return undefined;
+    const declarationFile = resolvedDeclaration.getSourceFile().fileName;
+    if (declarationFile.includes('node_modules'))
+        return undefined;
+    const type = checker.getTypeOfSymbolAtLocation(symbol, resolvedDeclaration);
+    if (!isComponentType(checker, type))
+        return undefined;
+    const { line } = tagName.getSourceFile().getLineAndCharacterOfPosition(tagName.getStart());
+    return { component: symbol.getName(), file: path.relative(process.cwd(), tagName.getSourceFile().fileName), line: line + 1 };
 }
 /** Design §3 — "Type column: keeps alias names, not expanded unions." An optional prop's type
  *  (as read via its symbol) includes `undefined` — printed as `"T | undefined"` when `T` has no