@usableapp/cardds 0.7.71 → 0.7.73

package/dist/choice/Calendar.d.ts

@@ -12,11 +12,13 @@ export interface CalendarProps extends Omit<ComponentProps<'div'>, 'title' | 'on
     defaultSelected?: number;
     /** a day was tapped */
     onSelect?: (day: number) => void;
-    /** the head's two buttons: the app turns the month (it owns `title`, `days`, `start`) */
+    /** the previous-month button was tapped: the app turns the month (it owns `title`, `days`, `start`) */
     onPrev?: () => void;
+    /** the next-month button was tapped: the app turns the month, as with `onPrev` */
     onNext?: () => void;
-    /** their accessible names */
+    /** the previous button's accessible name (default "Previous", by `<html lang>`) */
     prevLabel?: string;
+    /** the next button's accessible name (default "Next", by `<html lang>`) */
     nextLabel?: string;
     /** softly marked days */
     marks?: number[];

package/dist/choice/DayStrip.d.ts

@@ -8,6 +8,7 @@ export interface DayProps extends Omit<ComponentProps<'button'>, 'name'> {
     name: ReactNode;
     /** the date number */
     num: ReactNode;
+    /** this day is the picked one (aria-selected; the app keeps which) */
     selected?: boolean;
     /** a mark under the number (something is on) */
     dot?: boolean;

package/dist/choice/Mood.d.ts

@@ -7,6 +7,7 @@ export interface MoodProps extends Omit<ComponentProps<'fieldset'>, 'onChange' |
     value?: MoodValue;
     /** UNCONTROLLED: the dot picked on arrival; the Mood then keeps its own */
     defaultValue?: MoodValue;
+    /** the group's accessible name (default "Mood", by `<html lang>`) */
     label?: string;
     /** the dot the member tapped */
     onChange?: (value: MoodValue) => void;

package/dist/choice/Slider.d.ts

@@ -4,7 +4,9 @@ export interface SliderProps extends Omit<ComponentProps<'input'>, 'className' |
     label?: ReactNode;
     /** one sample letter IN the knob, at the type size the slider sets (a text-size slider's ก) */
     glyph?: ReactNode;
+    /** classes for the slider's label wrapper — the range input itself takes none */
     className?: string;
+    /** inline style for the label wrapper, not the range input */
     style?: React.CSSProperties;
 }
 /** Slider — one value along a hairline rail with a 48px knob; the whole range is thumb-tall. */

package/dist/forms/Composer.d.ts

@@ -6,7 +6,9 @@ export interface ComposerProps extends Omit<ComponentProps<'textarea'>, 'classNa
     lead?: ReactNode;
     /** the right button of the bar (an `IconBtn invert` — send) */
     send?: ReactNode;
+    /** classes for the composer's wrapper, not the textarea */
     className?: string;
+    /** inline style for the wrapper, not the textarea */
     style?: React.CSSProperties;
 }
 /** Composer — a big write-in area (display type) with a bottom bar: icon · hint · send. The write-in step's sheet content. */

package/dist/forms/Field.d.ts

@@ -24,7 +24,9 @@ export interface FieldProps extends Omit<ComponentProps<'input'>, 'className' |
      *  → 081-234-5678). Only digits are kept; a mark comes only once a digit follows it, so Backspace never sticks on a dash. The
      *  app's `onChange` reads the shaped value (the digits alone: `value.replace(/\D/g, '')`). Lh 2026-09-25 */
     mask?: string;
+    /** classes for the field's label wrapper, not the input */
     className?: string;
+    /** inline style for the label wrapper, not the input */
     style?: React.CSSProperties;
 }
 /** the digits of `v`, written into `mask`; a mark is written only when a digit comes after it */

package/dist/forms/FileBtn.d.ts

@@ -8,6 +8,7 @@ export interface FileBtnProps extends Omit<ComponentProps<'input'>, 'type' | 'cl
     block?: boolean;
     /** the button's words (and an Icon, if any) */
     children?: ReactNode;
+    /** classes for the button (the label around the hidden file input) */
     className?: string;
 }
 /**

package/dist/journey/NoteRow.d.ts

@@ -1,6 +1,7 @@
 import type { ComponentProps } from 'react';
 import { type IconName } from '../type/Icon.js';
 export interface NoteRowProps extends ComponentProps<'div'> {
+    /** the icon before the words (default clock) */
     icon?: IconName;
 }
 /** NoteRow — icon + caption: transit hints, fine print. */

package/dist/journey/Route.d.ts

@@ -9,7 +9,9 @@ export interface RoutePoint {
     time: ReactNode;
 }
 export interface RouteProps extends ComponentProps<'div'> {
+    /** where it starts: place · code · time */
     from: RoutePoint;
+    /** where it ends: place · code · time */
     to: RoutePoint;
     /** the icon on the dotted connector (plane by default) */
     via?: IconName;

package/dist/layover/Callout.d.ts

@@ -1,9 +1,12 @@
 import type { ComponentProps, ReactNode } from 'react';
 export interface CalloutProps extends Omit<ComponentProps<'div'>, 'title'> {
+    /** the callout's first line (a place, a name) */
     title: ReactNode;
+    /** a second, smaller line under the title */
     sub?: ReactNode;
-    /** position over the stage background (CSS lengths / percentages) */
+    /** the callout's top edge, over the stage background (a CSS length / percentage) */
     top?: string;
+    /** the callout's centre line, from the left of the stage background (a CSS length / percentage) */
     left?: string;
 }
 /** Callout — a small card with a tail, pinned over a map or a media. */

package/dist/lists/Kv.d.ts

@@ -19,8 +19,11 @@ export interface KvGridProps extends ComponentProps<'div'> {
 /** KvGrid — value-over-label cells split by a rule (Sex | Weight); children are KVCells. */
 export declare function KvGrid({ className, ...rest }: KvGridProps): import("react").JSX.Element;
 export interface KvCellProps extends ComponentProps<'div'> {
+    /** an icon before the value */
     icon?: IconName;
+    /** the big value */
     value: ReactNode;
+    /** the caption under the value */
     label: ReactNode;
 }
 /** KvCell — an icon, a big value, a caption label. */

package/dist/lists/Row.d.ts

@@ -13,8 +13,9 @@ export interface RowProps extends Omit<ComponentProps<'div'>, 'title'> {
     body?: ReactNode;
     /** the trailing control: an IconBtn, a Chip, a Check, a Toggle, a caption */
     end?: ReactNode;
-    /** a trailing value + caption, right-aligned */
+    /** a trailing value, right-aligned (title type) */
     endValue?: ReactNode;
+    /** the muted caption under `endValue` */
     endCaption?: ReactNode;
     /** menu row: more air, a bigger title */
     lg?: boolean;
@@ -22,6 +23,7 @@ export interface RowProps extends Omit<ComponentProps<'div'>, 'title'> {
     done?: boolean;
     /** div (default), a link, a label wrapping a Check/Toggle, li */
     as?: 'div' | 'a' | 'label' | 'li';
+    /** makes the row a link (an `a`); not with `more`, whose row is a summary */
     href?: string;
     /** what the row EXPANDS to show under itself (who liked, the rest of a list): the row becomes a `<details>`' summary */
     more?: ReactNode;

package/dist/media/Mosaic.d.ts

@@ -1,10 +1,12 @@
 import type { ComponentProps } from 'react';
 export interface MosaicProps extends ComponentProps<'div'> {
+    /** the photos' one accessible name — the mosaic is a single `img` (default "Photos", by `<html lang>`) */
     label?: string;
 }
 /** Mosaic — one big photo + two small in a card (three Placeholders or imgs). */
 export declare function Mosaic({ label, className, ...rest }: MosaicProps): import("react").JSX.Element;
 export interface WaveProps extends ComponentProps<'span'> {
+    /** the waveform's accessible name (default "Voice note", by `<html lang>`) */
     label?: string;
     /** the bars' heights, 0–1, left to right — a real recording's levels; default: a mock-up shape */
     levels?: number[];

package/dist/media/Postcard.d.ts

@@ -2,6 +2,7 @@ import { type ComponentProps, type ReactNode } from 'react';
 export interface PostcardProps extends ComponentProps<'div'> {
     /** the photo on the front; none = the wireframe box */
     photo?: string | null;
+    /** the photo's alt text; with no photo, the wireframe box's accessible name */
     alt?: string;
     /** whose card it is — the big line of the band */
     name: ReactNode;
@@ -21,8 +22,11 @@ export interface PostcardProps extends ComponentProps<'div'> {
     liked?: boolean;
     /** the heart was tapped: the state it asks for. No `liked` and no `onLike` = no heart */
     onLike?: (liked: boolean) => void;
+    /** the heart's accessible name (default "ถูกใจ") */
     likeLabel?: string;
+    /** the accessible name of the front's turn-over button (default "พลิกดูด้านหลัง") */
     frontLabel?: string;
+    /** the accessible name of the back's turn-over button (default "พลิกดูด้านหน้า") */
     backLabel?: string;
 }
 /**

package/dist/media/Tile.d.ts

@@ -3,6 +3,7 @@ import { type IconName } from '../type/Icon.js';
 export interface TileGridProps extends ComponentProps<'div'> {
     /** three across on a phone (attachments, upload kinds) */
     cols3?: boolean;
+    /** the grid takes the card's side padding back and runs to its edges (`.bleed`, card.css) */
     bleed?: boolean;
 }
 /** TileGrid — big square Tiles in a responsive grid. */
@@ -18,10 +19,15 @@ export interface TileProps extends Omit<ComponentProps<'div'>, 'onChange'> {
     sub?: ReactNode;
     /** a pick tile: a checkbox (or radio) inside, filled when checked */
     pick?: boolean;
+    /** what the pick tile's input is: checkbox (default) for pick-many, radio for pick-one */
     type?: 'checkbox' | 'radio';
+    /** the input's name (a pick tile): the radios of one choice share it (that is what makes them one group); a checkbox's is its form field */
     name?: string;
+    /** CONTROLLED: picked (a pick tile). The app owns it — pair it with `onChange` */
     checked?: boolean;
+    /** UNCONTROLLED: picked on arrival; the input then keeps its own */
     defaultChecked?: boolean;
+    /** the native input's change event: the tile was picked, or (checkbox) toggled */
     onChange?: React.ChangeEventHandler<HTMLInputElement>;
     /** filled accent (a static "on" tile) */
     on?: boolean;

package/dist/numbers/Bars.d.ts

@@ -6,6 +6,7 @@ export interface BarsProps extends ComponentProps<'div'> {
 /** Bars — three or four bars with a count on top, the glance chart; children are Bar. */
 export declare function Bars({ max, className, style, ...rest }: BarsProps): import("react").JSX.Element;
 export interface BarProps extends ComponentProps<'div'> {
+    /** the bar's height, against `Bars max` (the tallest bar's value) */
     value: number;
     /** the highlighted bar (accent, its count in a pill) */
     on?: boolean;

package/dist/numbers/DotGrid.d.ts

@@ -6,6 +6,7 @@ export interface DotGridProps extends ComponentProps<'div'> {
     done: number;
     /** dots per row (12) */
     cols?: number;
+    /** the grid's accessible name (default "{done} of {total}") */
     label?: string;
 }
 /** DotGrid — progress over time as a grid of dots, one element and three numbers (`--total`, `--done`, `--cols`). */

package/dist/numbers/Picker.d.ts

@@ -8,6 +8,7 @@ export interface PickerProps extends Omit<ComponentProps<'div'>, 'onChange' | 'd
     onChange?: (value: string) => void;
     /** the unit under the rail ("hours") */
     unit?: ReactNode;
+    /** the picker's accessible name (aria-label) */
     label?: string;
 }
 /**

package/dist/numbers/Track.d.ts

@@ -1,5 +1,6 @@
 import type { ComponentProps } from 'react';
 export interface TrackProps extends ComponentProps<'ol'> {
+    /** the track's accessible name (default "Progress", by `<html lang>`) */
     label?: string;
 }
 /** Track — step progress in a dark pill: done · done · todo; children are TrackSteps holding an Icon each. */

package/dist/people/Avatar.d.ts

@@ -15,10 +15,13 @@ export interface AvatarProps extends ComponentProps<'span'> {
     center?: boolean;
     /** a photo instead of initials */
     src?: string;
+    /** the photo's alt text; empty (the default) = decorative */
     alt?: string;
     /** an icon instead of initials */
     icon?: IconName;
+    /** the element: span (default), a when it has an `href`, or button for a tap target */
     as?: 'span' | 'a' | 'button';
+    /** makes the avatar a link (an `a`) */
     href?: string;
     /** the initials */
     children?: ReactNode;
@@ -310,6 +313,8 @@ export declare function Avatar({ size, outline, add, on, halo, center, src, alt,
     className: string;
 }, HTMLSpanElement>;
 export interface AvatarStackProps extends ComponentProps<'span'> {
+    /** the count that trails the stack ("+9"): plain text, no round, no fill, in title type — it reads at arm's length. Use it for a stack of Stamps or when the count is the point; a count that should look like one more head is `<Avatar size="sm" on>+7</Avatar>` as the last child */
+    more?: ReactNode;
 }
-/** AvatarStack — overlapping small Avatars with an optional `on` "+N" tail. */
-export declare function AvatarStack({ className, ...rest }: AvatarStackProps): import("react").JSX.Element;
+/** AvatarStack — overlapping small Avatars, or small Stamps (`bare`), side by side; a trailing count is `more` (or an `on` Avatar as the last child). */
+export declare function AvatarStack({ more, className, children, ...rest }: AvatarStackProps): import("react").JSX.Element;

package/dist/people/Avatar.js

@@ -1,4 +1,4 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { createElement } from 'react';
 import { cx } from '../cx.js';
 import { Icon } from '../type/Icon.js';
@@ -7,7 +7,7 @@ export function Avatar({ size, outline, add, on, halo, center, src, alt = '', ic
     const el = as ?? (href ? 'a' : 'span');
     return createElement(el, { href, type: el === 'button' ? 'button' : undefined, className: cx('avatar', size && `avatar--${size}`, outline && 'avatar--outline', add && 'avatar--add', on && 'avatar--on', halo && 'avatar--halo', center && 'avatar--center', className), ...rest }, src ? _jsx("img", { src: src, alt: alt }) : icon ? _jsx(Icon, { name: icon }) : children);
 }
-/** AvatarStack — overlapping small Avatars with an optional `on` "+N" tail. */
-export function AvatarStack({ className, ...rest }) {
-    return _jsx("span", { className: cx('avatar-stack', className), ...rest });
+/** AvatarStack — overlapping small Avatars, or small Stamps (`bare`), side by side; a trailing count is `more` (or an `on` Avatar as the last child). */
+export function AvatarStack({ more, className, children, ...rest }) {
+    return (_jsxs("span", { className: cx('avatar-stack', className), ...rest, children: [children, more != null && _jsx("span", { className: "avatar-stack__more", children: more })] }));
 }

package/dist/people/AvatarPick.d.ts

@@ -2,6 +2,7 @@ import type { ComponentProps, ReactNode } from 'react';
 export interface AvatarPickProps extends ComponentProps<'div'> {
     /** run the strip to the card's edges */
     bleed?: boolean;
+    /** the strip's accessible name (aria-label) */
     label?: string;
 }
 /** AvatarPick — the chooser row: big heads with name and role under, scrolling sideways; children are AvatarPickItems. */

package/dist/post/PostLetter.d.ts

@@ -36,8 +36,9 @@ export interface PostLetterProps extends ComponentProps<'div'> {
     backLabel?: string;
     /** the tab's words while the back is in front */
     pictureLabel?: string;
-    /** the play control's names */
+    /** the play control's name while the note is paused (default "Play", by `<html lang>`) */
     playLabel?: string;
+    /** the play control's name while the note plays (default "Pause", by `<html lang>`) */
     pauseLabel?: string;
     /** the small word before the name (default "To", by `<html lang>`) */
     toLabel?: ReactNode;

package/dist/scaffold/LayerHistory.d.ts

@@ -14,6 +14,7 @@ export interface LayerHistoryProps {
     replace: (state: EntryState, search?: LayerSearch) => void;
     /** back by this many entries (`navigate(-entries)`) */
     back: (entries: number) => void;
+    /** the app's screens: whatever calls `useLayer` / `useLayers` stands under it */
     children?: ReactNode;
 }
 /**

package/dist/scaffold/Screen.d.ts

@@ -5,6 +5,7 @@ export interface ScreenProps extends ComponentProps<'div'> {
     fill?: boolean;
     /** a colour preset from palette.css; omit for the black-and-white wireframe */
     palette?: Palette;
+    /** the element: div (default), main for the page's landmark, or section */
     as?: 'div' | 'main' | 'section';
     /** TOP: a `TopBar` / `AppBar`, or `"lead"` — no bar, the content starts `--screen-lead` (15% of the screen) down */
     top?: ReactNode | 'lead';

package/dist/sheets/StackSheet.d.ts

@@ -23,7 +23,9 @@ export interface StackSheetProps extends Omit<ComponentProps<'article'>, 'title'
     tabs?: StackSheetTab[];
     /** CONTROLLED: the tab shown (its id) — with `onTabChange`; or `defaultTab` (default: the first) */
     tab?: string;
+    /** UNCONTROLLED: the tab shown first (its id, default the first); the sheet then keeps its own. Pair of `tab` */
     defaultTab?: string;
+    /** a tab was tapped: its id */
     onTabChange?: (tab: string) => void;
     /** the SHEET FOOT: the CTA at the sheet's bottom (one row) */
     foot?: ReactNode;

package/dist/stamp/StampBook.d.ts

@@ -4,9 +4,11 @@ export interface StampBookProps extends ComponentProps<'div'> {
     places?: number;
     /** ONE line of small stamps that scrolls sideways, no ground — the tray a member picks from */
     strip?: boolean;
+    /** the page with NO ground — no fill, no padding, no round: three stamps across fill the whole width of what holds the book, each the full width of its third (the Stamp's width cap is lifted) with the least gap that keeps them apart. Put the name INSIDE the stamp (`Stamp name`), not under it */
+    bare?: boolean;
 }
 /** StampBook — the album page: StampCells three across on an album ground, the free places drawn empty up to `places`. */
-export declare function StampBook({ places, strip, className, children, ...rest }: StampBookProps): import("react").JSX.Element;
+export declare function StampBook({ places, strip, bare, className, children, ...rest }: StampBookProps): import("react").JSX.Element;
 export interface StampCellProps extends Omit<ComponentProps<'span'>, 'onClick'> {
     /** a short line under the stamp — who it is from */
     label?: ReactNode;

package/dist/stamp/StampBook.js

@@ -4,9 +4,9 @@ import { cx } from '../cx.js';
 import { Icon } from '../type/Icon.js';
 import { StampPlace } from './Stamp.js';
 /** StampBook — the album page: StampCells three across on an album ground, the free places drawn empty up to `places`. */
-export function StampBook({ places = 0, strip, className, children, ...rest }) {
+export function StampBook({ places = 0, strip, bare, className, children, ...rest }) {
     const free = Math.max(0, places - Children.count(children));
-    return (_jsxs("div", { className: cx('stamp-book', strip && 'stamp-book--strip', className), ...rest, children: [children, Array.from({ length: free }, (_, i) => _jsx(StampPlace, { faint: true, "aria-hidden": "true" }, i))] }));
+    return (_jsxs("div", { className: cx('stamp-book', strip && 'stamp-book--strip', bare && 'stamp-book--bare', className), ...rest, children: [children, Array.from({ length: free }, (_, i) => _jsx(StampPlace, { faint: true, "aria-hidden": "true" }, i))] }));
 }
 /** StampCell — one place of a StampBook: a Stamp (the child) and a short label under it. */
 export function StampCell({ label, onClick, on, className, children, ...rest }) {

package/dist/templates/CallSheet.d.ts

@@ -39,7 +39,9 @@ export interface CallSheetProps extends Omit<ComponentProps<typeof Screen>, 'chi
     ways?: CallSheetWay[];
     /** CONTROLLED: which way's sheet is up — an index, or null for none (`true` = the first); with `onOpenChange`; or `defaultOpen` */
     open?: number | boolean | null;
+    /** UNCONTROLLED: the way whose sheet is up on arrival (an index, `true` = the first, null = none); the template then keeps its own. Pair of `open` */
     defaultOpen?: number | boolean | null;
+    /** a sheet came up or went away: whether one is up, and which way's (its index, or null) */
     onOpenChange?: (open: boolean, way: number | null) => void;
     /** the sheets' resting states once up (default "peek full") */
     states?: string;

package/dist/templates/Home.d.ts

@@ -29,7 +29,9 @@ export interface HomeProps extends Omit<ComponentProps<typeof Screen>, 'children
     sheets: HomeSheet[];
     /** CONTROLLED: the open sheet's index, or null — with `onOpenChange`; or `defaultOpen` */
     open?: number | null;
+    /** UNCONTROLLED: the sheet open on arrival (its index), or null for none; the Home then keeps its own. Pair of `open` */
     defaultOpen?: number | null;
+    /** a sheet asks to come up or fold: the index it asks for, or null for none */
     onOpenChange?: (open: number | null) => void;
     /** the open sheet's scroller was already at the top and the finger pulled down past the commit. The stack asks with that index. It does not fetch. Omit it and a pull in the body only scrolls */
     onRefresh?: (index: number) => void;

package/dist/templates/Walkthrough.d.ts

@@ -15,10 +15,13 @@ export interface WalkthroughCta {
     go: (to: number) => void;
 }
 export interface WalkthroughProps extends Omit<ComponentProps<typeof Screen>, 'children' | 'fill' | 'top' | 'bottom'> {
+    /** the pages in order — a picture, a heading and the words each */
     pages: WalkthroughPage[];
     /** the page shown (0-based), controlled — with `onAtChange`; or `defaultAt` */
     at?: number;
+    /** UNCONTROLLED: the page shown on arrival (0-based, default 0); the walk then keeps its own. Pair of `at` */
     defaultAt?: number;
+    /** a page was turned to: its index */
     onAtChange?: (at: number) => void;
     /** the ONE row of the bottom panel. Omitted: the round pager (back · next). A function gets `{ at, count, go }`,
      *  e.g. the pager until the last page, then one wide Btn. */
@@ -29,8 +32,9 @@ export interface WalkthroughProps extends Omit<ComponentProps<typeof Screen>, 'c
     ctaLink?: ReactNode;
     /** layers over the screen: the app's `SheetStage dim` + `Modal` that a link or button opens (the app wires it) */
     children?: ReactNode;
-    /** the pager's labels */
+    /** the pager's back button name (default "Back", by `<html lang>`) */
     backLabel?: string;
+    /** the pager's next button name (default "Next", by `<html lang>`) */
     nextLabel?: string;
 }
 /**

package/lib/catalog.mjs

@@ -0,0 +1,203 @@
+// lib/catalog.mjs — what an AI session asks of the catalog (dist/catalog.json, built by scripts/build-catalog.mjs) instead of reading src/.
+// Pure functions over the loaded catalog, no dependency beyond node: `npx cardds list|get|find|scaffold` and `npx cardds mcp` (lib/mcp.mjs) are two doors to these.
+// Shipped in the package. The order of a session: find (has a screen like this been drawn?) → scaffold it, or get the components → check.
+import { existsSync, readFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { checkSource } from '../lint/rules.mjs';
+import { SHAPES, KINDS, shapeOf, interactOf } from './role.mjs';
+
+const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
+const CSS = 'node_modules/@usableapp/cardds/dist/cardds.css';
+const OTHERS = 5; // stories of OTHER components that show one in use: how many come with their code (`Btn` is in 117)
+
+/** the catalog of the package, or of a live repo at `root` (rebuilt first, so it is never stale) */
+export function load({ root } = {}) {
+  if (root && existsSync(join(root, 'scripts', 'build-catalog.mjs'))) {
+    execFileSync(process.execPath, [join(root, 'scripts', 'build-catalog.mjs'), root], { stdio: ['ignore', 'ignore', 'inherit'] });
+  }
+  const file = join(root ?? PKG, 'dist', 'catalog.json');
+  if (!existsSync(file)) throw new Error(`no catalog at ${file} — \`npm run build\` in the cardds repo makes it`);
+  return JSON.parse(readFileSync(file, 'utf8'));
+}
+
+export { SHAPES, KINDS };
+
+// `represents` is the concept (person · group · time…) or, for a control that stands for no one thing, the KIND of data it carries (words · number · picture · signal); `—` is none, so []
+const representsOf = ({ represents }) => represents.filter((v) => v !== '—');
+
+/** the names only — the first call of nearly every session, so it stays small. `group` is the src folder; `represents`, `shape` and `interact` say what it is for */
+export const list = (cat) => cat.components.map(({ name, group, role }) => ({ name, group, represents: representsOf(role), shape: shapeOf(role), interact: interactOf(role) }));
+
+const sentence = (text) => {
+  const flat = text.replace(/\s+/g, ' ').trim();
+  const one = flat.match(/^.*?[.!?](?=\s|$)/)?.[0] ?? flat;
+  return one.length > 160 ? `${one.slice(0, 157)}…` : one;
+};
+const isSlot = (type) => /\bReactNode\b/.test(type);
+
+function distance(a, b) {
+  const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    let prev = row[0];
+    row[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const keep = row[j];
+      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+      prev = keep;
+    }
+  }
+  return row[b.length];
+}
+const closest = (names, wanted) => {
+  const w = wanted.toLowerCase();
+  const rank = (n) => (n.toLowerCase().includes(w) || w.includes(n.toLowerCase()) ? 0 : 100) + distance(n.toLowerCase(), w);
+  return [...names].sort((a, b) => rank(a) - rank(b)).slice(0, 5);
+};
+
+/** one component: its props (a ReactNode prop is a slot) and its variations — the stories of its own file first, then a few that use it */
+export function get(cat, name, { html = false, all = false } = {}) {
+  const c = cat.components.find((x) => x.name.toLowerCase() === String(name).toLowerCase());
+  if (!c) return { error: `no component "${name}"`, closest: closest(cat.components.map((x) => x.name), String(name)) };
+  const show = (s) => ({ id: s.id, description: s.description, tsx: s.tsx, ...(html && { html: s.html }) });
+  const own = cat.stories.filter((s) => s.file === c.name);
+  const elsewhere = cat.stories.filter((s) => s.file !== c.name && s.uses.includes(c.name));
+  const shown = all ? elsewhere : [...elsewhere].sort((a, b) => a.tsx.length - b.tsx.length).slice(0, OTHERS);
+  return {
+    name: c.name,
+    group: c.group,
+    description: c.description,
+    ...(c.role && { role: c.role }),
+    element: c.element,
+    props: c.props.map((p) => ({ ...p, ...(isSlot(p.type) && { slot: true }) })),
+    variations: [...own, ...elsewhere.filter((s) => shown.includes(s))].map(show),
+    ...(elsewhere.length > shown.length && { alsoUsedIn: elsewhere.filter((s) => !shown.includes(s)).map((s) => s.id) }),
+  };
+}
+
+const words = (text) => text.replace(/([a-z\d])([A-Z])/g, '$1 $2').toLowerCase().match(/[\p{L}\p{M}\p{N}]+/gu) ?? [];
+const STOP = new Set(['the', 'and', 'for', 'with', 'from', 'that', 'this', 'into', 'of', 'to', 'in', 'on', 'an', 'a']);
+const tokens = (query) => [...new Set(words(String(query)).filter((t) => t.length > 1 && !STOP.has(t)))];
+const stem = (t) => (t.length > 3 && t.endsWith('s') ? t.slice(0, -1) : t);
+const hits = (text, token) => words(text).some((w) => w.startsWith(token) || w.startsWith(stem(token)));
+
+const TOP = 8; // answers per kind; the components that match every axis are never cut
+
+/** the closed vocabulary of the axes `find` takes, `represents` read from the catalog's own roles (docs/roles.md does not ship). `group` = either group shape */
+export const vocabulary = (cat) => ({
+  represents: [...new Set(cat.components.flatMap((c) => representsOf(c.role)))].sort(),
+  shape: ['one', 'group-brief', 'group-detail', 'group'],
+  interact: KINDS,
+});
+const roleOf = (c) => ({ represents: representsOf(c.role), shape: shapeOf(c.role), interact: interactOf(c.role) });
+
+/** the axes a caller gave, checked against the vocabulary: `{ error }`, or only the ones in force (an empty list is no axis) */
+function wanted(cat, { represents, shape, interact } = {}) {
+  const many = (v) => (v === undefined ? [] : [v].flat());
+  const vocab = vocabulary(cat);
+  const kinds = interact === false ? false : many(interact);
+  const unknown = (axis, given, allowed) => given.filter((v) => !allowed.includes(v)).map((v) => `${axis} "${v}" (one of: ${allowed.join(' · ')})`);
+  const errors = [...unknown('represents', many(represents), vocab.represents), ...unknown('shape', many(shape), vocab.shape), ...unknown('interact', kinds || [], vocab.interact)];
+  if (errors.length) return { error: `no such value — ${errors.join('; ')}` };
+  return { want: { ...(many(represents).length && { represents: many(represents) }), ...(shape && { shape }), ...((kinds === false || kinds.length) && { interact: kinds }) } };
+}
+/** a role matches when it matches EVERY axis in force: holds every `represents` asked, is the shape, has every kind of interaction asked (`false` = only shows) */
+const matches = (role, want) => !!role
+  && (!want.represents || want.represents.every((v) => role.represents.includes(v)))
+  && (!want.shape || (want.shape === 'group' ? role.shape.startsWith('group') : role.shape === want.shape))
+  && (want.interact === undefined || (want.interact === false ? role.interact === false : want.interact.every((k) => role.interact && role.interact.includes(k))));
+
+/** a screen is a composition, its axes spread over its parts: for each axis SOME used component answers it (represents: holds any value asked, the looser reading
+ *  — a part that holds every one is the stronger match, which `matches` finds; shape: has it; interact: has every kind asked, or for `none` every part only shows) */
+const matchesUnion = (roles, want) => roles.length > 0
+  && (!want.represents || roles.some((r) => want.represents.some((v) => r.represents.includes(v))))
+  && (!want.shape || roles.some((r) => matches(r, { shape: want.shape })))
+  && (want.interact === undefined || (want.interact === false ? roles.every((r) => r.interact === false) : roles.some((r) => matches(r, { interact: want.interact }))));
+
+/** short ranked answer to "what is there for this?". `axes` ({ represents?, shape?, interact? } — what it represents, how many, what the member can do with it) are
+ *  asked first: whatever matches every one of them (a component, or a screen where one component does, then a screen whose parts do between them) ranks above whatever matches only words;
+ *  with axes and no words they are the whole answer. Among screens that tie on words, the one whose description says the axes comes first, then the one where a single component matches them all.
+ *  Then the words: screens already drawn, then components, then what they are used with.
+ *  A query that matches nothing (another language, say) returns `fallback: true`, a hint and how many screens are drawn — not their ids:
+ *  they did not help to choose; ask again in English or by the axes, or `scaffold` with no id lists them. */
+export function find(cat, query, axes = {}) {
+  const asked = wanted(cat, axes);
+  if (asked.error) return asked;
+  const active = Object.keys(asked.want).length > 0;
+  const roles = new Map(cat.components.map((c) => [c.name, roleOf(c)]));
+  const toks = tokens(query);
+  const axisWords = [...(asked.want.represents ?? []), ...(asked.want.interact || [])]; // the axis values as words: a screen's own description may say them
+  const rank = (items, fields, level, said = () => 0) => {
+    const scored = items.map((item) => {
+      let matched = 0, score = 0;
+      for (const t of toks) {
+        const w = fields(item).filter(([text]) => hits(text, t)).reduce((sum, [, weight]) => sum + weight, 0);
+        if (w) { matched++; score += w; }
+      }
+      return { item, matched, score, level: active ? level(item) : 0, said: active ? said(item) : 0 };
+    });
+    const byWords = (a, b) => b.matched - a.matched || b.score - a.score;
+    const byAxes = (a, b) => b.said - a.said || b.level - a.level; // among equal words: the screen that says the axes itself, then one component over several
+    return { axis: scored.filter((r) => r.level).sort((a, b) => byWords(a, b) || byAxes(a, b)), rest: scored.filter((r) => r.matched && !r.level).sort(byWords) };
+  };
+  const tier = ({ axis, rest }, cap) => [axis.slice(0, cap), rest.slice(0, Math.max(0, cap - axis.length))];
+  const screenOf = ({ item: s }) => ({ kind: 'screen', id: s.id, summary: sentence(s.description) });
+  const componentOf = ({ item: c }) => ({ kind: 'component', name: c.name, summary: sentence(c.description), role: roles.get(c.name) });
+  const screens = cat.stories.filter((s) => s.screen);
+  const level = (s) => { // 2: one component of the screen matches every axis; 1: its parts do between them
+    const parts = s.uses.map((u) => roles.get(u)).filter(Boolean);
+    return !matchesUnion(parts, asked.want) ? 0 : parts.some((r) => matches(r, asked.want)) ? 2 : 1; // `none` is about the whole screen: one show-only part is not enough
+  };
+  const said = (s) => axisWords.filter((v) => hits(s.description, v)).length;
+  const [screenAxis, screenRest] = tier(rank(screens, (s) => [[s.id, 5], [s.description, 3], [s.uses.join(' '), 1]], level, said), TOP);
+  const components = rank(cat.components, (c) => [[c.name, 6], [c.description, 2], [c.props.map((p) => p.name).join(' '), 1]], (c) => Number(matches(roles.get(c.name), asked.want)));
+  const [componentAxis, componentRest] = tier(components, Math.max(TOP, components.axis.length));
+  const ranked = [...screenAxis.map(screenOf), ...componentAxis.map(componentOf), ...screenRest.map(screenOf), ...componentRest.map(componentOf)];
+  if (!ranked.length && active && !toks.length) return { query, results: [], hint: 'no component or screen has that role: drop an axis, or add English words' };
+  if (!ranked.length) return { query, fallback: true, hint: 'the names and descriptions are English: ask again in English words, or by the axes (represents · shape · interact); `scaffold` with no id lists the screens', screens: screens.length };
+
+  const matched = new Set(ranked.filter((r) => r.kind === 'component').map((r) => r.name));
+  const together = new Map();
+  for (const s of cat.stories) if (s.uses.some((u) => matched.has(u))) for (const u of s.uses) if (!matched.has(u)) together.set(u, (together.get(u) ?? 0) + 1);
+  const usedTogether = [...together].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, 8).map(([name, stories]) => ({ name, stories }));
+  return { query, results: ranked, usedTogether };
+}
+
+// the parts that put themselves where they belong by JS at runtime — over the content, open, at the edge: the static html shows them in the wrong place
+const PLACED_BY_JS = ['Sheet', 'SheetStack', 'SheetSteps', 'SheetStage', 'Step', 'Modal', 'Menu', 'Dropdown', 'Snackbar', 'FloatBar'];
+
+/** no id: the screens already drawn. With one: a file to start from — `tsx` (the code, a string) or `html` (the look, static: `{ html, warning? }`, the warning when the picture lies) */
+export function scaffold(cat, id, { format = 'tsx', css = CSS } = {}) {
+  if (!id) return cat.stories.filter((s) => s.screen).map((s) => ({ id: s.id, summary: sentence(s.description) }));
+  const s = cat.stories.find((x) => x.id.toLowerCase() === String(id).toLowerCase());
+  if (!s) return { error: `no story "${id}"`, closest: closest(cat.stories.map((x) => x.id), String(id)) };
+  if (format === 'html') {
+    if (!s.html) return { error: `${s.id} has no rendered html: ${s.htmlError ?? 'it did not render'}` };
+    const placed = [...new Set(s.uses.filter((u) => PLACED_BY_JS.includes(u)))];
+    const warning = placed.length ? `${placed.join(', ')} ${placed.length > 1 ? 'are' : 'is'} placed by JS at runtime, so this static picture is NOT the layout (a sheet over the content, a menu not open): use format tsx to see it live` : undefined;
+    return { html: `<!doctype html>${warning ? `\n<!-- ${warning} -->` : ''}
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover, interactive-widget=resizes-content">
+<title>${s.id}</title>
+<link rel="stylesheet" href="${css}">
+</head>
+<body>
+<!-- ${s.id}, rendered once: the look only, no behaviour. \`scaffold ${s.id}\` (tsx) is the working code -->
+${s.html}
+</body>
+</html>
+`, ...(warning && { warning }) };
+  }
+  const glue = [...s.imports.matchAll(/import (.+?) from '\.\/_[^']*';/g)]
+    .flatMap((m) => m[1].replace(/[{}]/g, '').split(',').map((n) => n.trim().replace(/^type /, '').split(/ as /).pop()).filter(Boolean));
+  const taken = /\bScreen\b/.test(s.imports) || /^(?:function|const|class|type|interface) Screen\b/m.test(s.tsx);
+  const as = taken ? 'MyScreen' : 'Screen';
+  const note = glue.length ? `// story glue from ./_*, not part of the package — replace or drop: ${glue.join(', ')}\n` : '';
+  return `${note}${s.imports}\n\n${s.tsx.replace(new RegExp(`^function ${s.name}\\b`, 'm'), `export default function ${as}`)}\n`;
+}
+
+/** the rules of lint/rules.mjs over a piece of code */
+export const check = (code, filename = 'screen.tsx') => checkSource(code, filename);