themelia-react-ui 0.0.0-stage → 1.0.0

package/docs/consumer-skill/references/theming.md

@@ -0,0 +1,56 @@
+# Theme adoption and extension
+
+The [design contract](design-contract.md) records which geometry changes together
+and which variant choices remain independent. Retheme shared responsibilities;
+avoid overriding individual components to imitate another density or inset.
+
+Use shadcn semantic surfaces/foregrounds: background, card, popover, primary, secondary, muted, accent, destructive, border, input, ring, charts and sidebar. Central success/info/warning foreground pairs express states; never overload primary or statuses as decoration.
+
+tokens.json distinguishes 23 structural roots, advanced typography/status settings, and derived utility spellings. A utility is not another public variable. Keep overrides in one stylesheet at root or ThemeScope, without copying computed CSS into JavaScript.
+
+Default --radius is 1rem (16px). rounded-radius is the default throughout the package. rounded-inner is opt-in for nested bodies/items and derives at 0.6× (9.6px). Do not invent an outer/surface radius or enlarge an individual card based on padding. Circular avatars/dots remain intentional shapes.
+
+```css
+/* After themelia-react-ui/style.css; no Tailwind build needed for overrides. */
+:root {
+  --radius: 1rem;
+  --height-action: 2.5rem;
+  --height-control: 2.5rem;
+  --surface-x: 1rem;
+  --surface-y: 1rem;
+}
+```
+
+Action and editable-control heights are separate roles; keep roots equal for adjoining alignment. `--space-scale` multiplies structural gaps, inline insets and surface padding. `--density-scale` multiplies action/control height and collection block padding. Roots are unscaled measurements; do not pre-multiply and then apply the utility again.
+
+| Shared geometry | Root / derivation |
+| --- | --- |
+| Actions versus fields | `--height-action` versus `--height-control`; default size uses the root times density-scale |
+| Native field text inset | `--control-x` times space-scale; icons/add-ons use shared derived clearance |
+| Collection inline inset | `--row-x` times space-scale |
+| Collection block inset | `--row-y` times density-scale; compact/comfortable use 0.75/1.25 multipliers |
+| Default / compact surfaces | `--surface-x` / `--surface-y`, times space-scale; compact uses half |
+| Menu header/footer inline inset | Half surface-x plus row-x, then space-scale; no additional public token |
+
+Use discrete inset, density and size props for the component responsibility described in [composition](composition.md). CSS scales are independent continuous theme settings. Primary row text does not shrink to xs merely because a density is compact. Public Input and Command search retain normal desktop editable text; coarse-pointer devices use text-base at mobile and tablet widths. Typography components remain margin-free.
+
+Root overrides reach body portals. Scoped themes use ThemeScope from ui-provider. Advanced editing uses the theme-tweaker public API, editing CSS rather than adding another JavaScript styling system.
+
+Explicit portal containers take precedence over the nearest ThemeScope. Place those containers inside the intended theme boundary; a portal deliberately moved outside it cannot inherit that boundary automatically. Test the opened popup, not only its trigger.
+
+Apps using semantic utilities in their own JSX process themelia-react-ui/theme.css after Tailwind in a Tailwind v4 stylesheet. Compiled style.css styles shipped components but does not compile arbitrary app utility names. Keep app-owned classes namespaced and layout-focused.
+
+## Extend without drift
+
+Reuse existing color, text, action/control, row, surface or shell responsibilities first. An app token stays app-owned, not a package knob. New package tokens require multiple consumers, one owner/default/purpose, contract/docs updates and scoped behavior verification. Never expand the budget to fix one preview.
+
+Use public structures/utilities for custom composition. Missing API seams should be additive props/slots rather than copies of private code. Review light/dark foregrounds and opened portals. CSS owns theming, UIProvider stable display defaults, callbacks app state.
+
+
+## Copy rhythm
+
+Normal title/description gaps use `--gap-normal` (0.5rem); dense row and menu
+copy uses `--gap-dense` (0.25rem). Both multiply once by `--space-scale` and
+inherit through ThemeScope and portaled surfaces. Control heights and insets
+remain separate. Use `textGap="normal" | "dense"` on headed surfaces and
+`gap="normal" | "dense"` on Stack/Grid instead of adding a description margin.

package/docs/consumer-skill/references/tokens.json

@@ -0,0 +1,422 @@
+{
+  "package": "themelia-react-ui",
+  "version": "1.0.0",
+  "structural": [
+    {
+      "name": "--space-scale",
+      "default": "1",
+      "purpose": "Multiplies gaps and padding without changing control heights."
+    },
+    {
+      "name": "--density-scale",
+      "default": "1",
+      "purpose": "Multiplies controls, actions, rows, and other density-sensitive geometry."
+    },
+    {
+      "name": "--gap-normal",
+      "default": "0.5rem",
+      "purpose": "Vertical rhythm between titles and structural descriptions."
+    },
+    {
+      "name": "--gap-dense",
+      "default": "0.25rem",
+      "purpose": "Vertical rhythm between row titles and compact supporting copy."
+    },
+    {
+      "name": "--height-action",
+      "default": "2.25rem",
+      "purpose": "Default button and action-trigger height."
+    },
+    {
+      "name": "--height-control",
+      "default": "2.25rem",
+      "purpose": "Default input, select, and field-control height."
+    },
+    {
+      "name": "--control-x",
+      "default": "0.75rem",
+      "purpose": "Default inline padding for buttons and field controls."
+    },
+    {
+      "name": "--row-x",
+      "default": "0.75rem",
+      "purpose": "Shared inline inset for list, menu, command, and table rows."
+    },
+    {
+      "name": "--row-y",
+      "default": "0.5rem",
+      "purpose": "Default vertical row inset with an 8px breathing floor."
+    },
+    {
+      "name": "--surface-x",
+      "default": "1rem",
+      "purpose": "Default inline inset for cards and multi-content surfaces."
+    },
+    {
+      "name": "--surface-y",
+      "default": "1rem",
+      "purpose": "Default block inset for cards and multi-content surfaces."
+    },
+    {
+      "name": "--icon",
+      "default": "1rem",
+      "purpose": "Default interface icon size."
+    },
+    {
+      "name": "--avatar",
+      "default": "2rem",
+      "purpose": "Default avatar used in standard rows and cards."
+    },
+    {
+      "name": "--shell-header-height",
+      "default": "4.5rem",
+      "purpose": "Minimum height of the application header shell."
+    },
+    {
+      "name": "--shell-sidebar-width",
+      "default": "16rem",
+      "purpose": "Default expanded sidebar content width."
+    },
+    {
+      "name": "--content-width-sm",
+      "default": "40rem",
+      "purpose": "Compact centered content measure."
+    },
+    {
+      "name": "--content-width-md",
+      "default": "48rem",
+      "purpose": "Medium centered content measure."
+    },
+    {
+      "name": "--content-width-lg",
+      "default": "64rem",
+      "purpose": "Default readable page content measure."
+    },
+    {
+      "name": "--content-width-xl",
+      "default": "80rem",
+      "purpose": "Wide application content measure."
+    },
+    {
+      "name": "--content-width-2xl",
+      "default": "96rem",
+      "purpose": "Maximum standard application content measure."
+    },
+    {
+      "name": "--adaptive-grid-min-sm",
+      "default": "12rem",
+      "purpose": "Compact minimum width for adaptive peer columns."
+    },
+    {
+      "name": "--adaptive-grid-min-md",
+      "default": "16rem",
+      "purpose": "Default minimum width for adaptive peer columns."
+    },
+    {
+      "name": "--adaptive-grid-min-lg",
+      "default": "20rem",
+      "purpose": "Spacious minimum width for adaptive peer columns."
+    }
+  ],
+  "radius": {
+    "name": "--radius",
+    "default": "1rem",
+    "purpose": "Default corners throughout the package; opt-in nested corners derive from this root.",
+    "defaultUtility": "rounded-radius",
+    "innerUtility": "rounded-inner",
+    "innerFormula": "calc(var(--radius) * 0.6)"
+  },
+  "advanced": [
+    "--font-heading",
+    "--font-sans",
+    "--font-serif",
+    "--font-mono",
+    "--text-xxs",
+    "--text-xxs--line-height",
+    "--text-xs",
+    "--text-xs--line-height",
+    "--text-pxs",
+    "--text-pxs--line-height",
+    "--text-sm",
+    "--text-sm--line-height",
+    "--text-base",
+    "--text-base--line-height",
+    "--text-lg",
+    "--text-lg--line-height",
+    "--text-xl",
+    "--text-xl--line-height",
+    "--text-2xl",
+    "--text-2xl--line-height",
+    "--text-3xl",
+    "--text-3xl--line-height",
+    "--text-4xl",
+    "--text-4xl--line-height",
+    "--text-5xl",
+    "--text-5xl--line-height",
+    "--text-6xl",
+    "--text-6xl--line-height",
+    "--text-7xl",
+    "--text-7xl--line-height",
+    "--text-8xl",
+    "--text-8xl--line-height",
+    "--text-9xl",
+    "--text-9xl--line-height",
+    "--success",
+    "--success-foreground",
+    "--info",
+    "--info-foreground",
+    "--link-color",
+    "--primary-accent",
+    "--warning",
+    "--warning-foreground",
+    "--warning-accent",
+    "--inverse-background",
+    "--inverse-foreground",
+    "--inverse-muted",
+    "--inverse-subtle",
+    "--inverse-disabled",
+    "--inverse-surface",
+    "--inverse-surface-strong",
+    "--inverse-border",
+    "--inverse-decoration",
+    "--overlay-backdrop"
+  ],
+  "utilities": {
+    "foundation": [
+      "font-heading",
+      "font-sans",
+      "font-serif",
+      "font-mono",
+      "text-xxs",
+      "text-xs",
+      "text-pxs",
+      "text-sm",
+      "text-base",
+      "text-lg",
+      "text-xl",
+      "text-2xl",
+      "text-3xl",
+      "text-4xl",
+      "text-5xl",
+      "text-6xl",
+      "text-7xl",
+      "text-8xl",
+      "text-9xl",
+      "gap-space-2xs",
+      "gap-space-xs",
+      "gap-space-sm",
+      "gap-space-md",
+      "gap-space-lg",
+      "gap-space-xl",
+      "gap-space-2xl",
+      "gap-x-space-2xs",
+      "gap-x-space-xs",
+      "gap-x-space-sm",
+      "gap-x-space-md",
+      "gap-x-space-lg",
+      "gap-x-space-xl",
+      "gap-x-space-2xl",
+      "gap-y-space-2xs",
+      "gap-y-space-xs",
+      "gap-y-space-sm",
+      "gap-y-space-md",
+      "gap-y-space-lg",
+      "gap-y-space-xl",
+      "gap-y-space-2xl",
+      "p-space-2xs",
+      "p-space-xs",
+      "p-space-sm",
+      "p-space-md",
+      "p-space-lg",
+      "p-space-xl",
+      "p-space-2xl",
+      "px-space-2xs",
+      "px-space-xs",
+      "px-space-sm",
+      "px-space-md",
+      "px-space-lg",
+      "px-space-xl",
+      "px-space-2xl",
+      "py-space-2xs",
+      "py-space-xs",
+      "py-space-sm",
+      "py-space-md",
+      "py-space-lg",
+      "py-space-xl",
+      "py-space-2xl",
+      "space-y-space-2xs",
+      "space-y-space-xs",
+      "space-y-space-sm",
+      "space-y-space-md",
+      "space-y-space-lg",
+      "space-y-space-xl",
+      "space-y-space-2xl",
+      "gap-normal",
+      "gap-dense",
+      "gap-x-normal",
+      "gap-x-dense",
+      "gap-y-normal",
+      "gap-y-dense"
+    ],
+    "states": [
+      "text-link-color",
+      "text-primary-accent",
+      "border-primary-accent",
+      "fill-primary-accent",
+      "stroke-primary-accent",
+      "bg-success",
+      "border-success",
+      "text-success",
+      "text-success-foreground",
+      "bg-info",
+      "border-info",
+      "text-info",
+      "text-info-foreground",
+      "bg-warning",
+      "border-warning",
+      "text-warning",
+      "text-warning-foreground",
+      "text-warning-accent",
+      "border-warning-accent",
+      "fill-warning-accent",
+      "stroke-warning-accent",
+      "bg-inverse-background",
+      "text-inverse-foreground",
+      "text-inverse-muted",
+      "text-inverse-subtle",
+      "text-inverse-disabled",
+      "bg-inverse-surface",
+      "bg-inverse-surface-strong",
+      "bg-inverse-decoration",
+      "border-inverse-border"
+    ],
+    "primitives": [
+      "rounded-radius-xs",
+      "rounded-radius-sm",
+      "rounded-radius-md",
+      "rounded-radius",
+      "rounded-radius-lg",
+      "rounded-radius-xl",
+      "h-action-xs",
+      "h-action-sm",
+      "h-action",
+      "h-action-lg",
+      "top-action-xs-center",
+      "top-action-sm-center",
+      "top-action-center",
+      "top-action-lg-center",
+      "size-action-xs",
+      "size-action-sm",
+      "size-action",
+      "size-action-lg",
+      "h-control-sm",
+      "h-control",
+      "h-control-lg",
+      "min-h-control-sm",
+      "min-h-control",
+      "min-h-control-lg",
+      "w-control-sm",
+      "w-control",
+      "w-control-lg",
+      "size-control-sm",
+      "size-control",
+      "size-control-lg",
+      "px-control-xs",
+      "px-control-sm",
+      "px-control",
+      "ps-control-xs",
+      "ps-control-sm",
+      "ps-control",
+      "pe-control-xs",
+      "pe-control-sm",
+      "pe-control",
+      "ps-control-icon-sm",
+      "ps-control-icon",
+      "pe-control-icon-sm",
+      "pe-control-icon",
+      "ps-control-addon-sm",
+      "ps-control-addon",
+      "pe-control-addon-sm",
+      "pe-control-addon",
+      "pe-control-count-sm",
+      "pe-control-count",
+      "pe-control-actions-sm",
+      "pe-control-actions",
+      "size-control-clear",
+      "size-control-clear-icon",
+      "w-control-clear",
+      "h-control-file",
+      "min-h-textarea-sm",
+      "min-h-textarea",
+      "py-control-y-offset",
+      "top-control-y-offset",
+      "right-control-px",
+      "size-icon-sm",
+      "size-icon-md",
+      "size-icon",
+      "size-icon-lg",
+      "size-avatar-sm",
+      "size-avatar",
+      "size-avatar-lg",
+      "size-upload-avatar-small",
+      "size-upload-avatar",
+      "size-upload-avatar-large",
+      "rounded-inner"
+    ],
+    "layout": [
+      "h-shell-header",
+      "min-h-shell-header",
+      "size-shell-header-control",
+      "w-shell-sidebar",
+      "w-shell-sidebar-icon-padded",
+      "shell-sidebar-vars",
+      "shell-sidebar-icon-current",
+      "shell-sidebar-offcanvas-current",
+      "shell-grid-left",
+      "shell-grid-right",
+      "max-w-content-sm",
+      "max-w-content-md",
+      "max-w-content-lg",
+      "max-w-content-xl",
+      "max-w-content-2xl"
+    ],
+    "components": [
+      "px-row-x",
+      "ps-row-x",
+      "pe-row-x",
+      "pl-row-x",
+      "pr-row-x",
+      "py-row-y-sm",
+      "py-row-y",
+      "py-row-y-lg",
+      "p-surface-xs",
+      "p-surface",
+      "p-surface-lg",
+      "px-surface-xs",
+      "px-surface",
+      "px-surface-lg",
+      "py-surface-xs",
+      "py-surface",
+      "py-surface-lg",
+      "pt-surface-xs",
+      "pt-surface",
+      "pt-surface-lg",
+      "pb-surface-xs",
+      "pb-surface",
+      "pb-surface-lg",
+      "ps-surface-xs",
+      "ps-surface",
+      "ps-surface-lg",
+      "pe-surface-xs",
+      "pe-surface",
+      "pe-surface-lg",
+      "pl-surface-xs",
+      "pl-surface",
+      "pl-surface-lg",
+      "pr-surface-xs",
+      "pr-surface",
+      "pr-surface-lg"
+    ]
+  },
+  "rule": "Derived utilities and implementation aliases are not public override roots."
+}

package/docs/consumer-skill/references/workflows.md

@@ -0,0 +1,39 @@
+# Callback-driven workflows
+
+Copy the relevant recipe into your app and import its exported component locally. Each source uses only public `themelia-react-ui` imports and React. Load `themelia-react-ui/style.css` once and use your app's provider/theme boundary. These are small workflow compositions; there is no bundled router, store or backend. Read the version-matched family declarations before adapting a recipe.
+
+The [example manifest](../examples/manifest.json) owns filenames, exported components and dependency phases for both installed-package checks and portable documentation. `basic` recipes need only the package's required peers; `optional` lists additional peers needed by every imported family's declarations under strict `skipLibCheck: false`. Resolve peer ranges from the [public index](public-api.json). Tree shaking can make runtime requirements smaller than whole-family declaration requirements.
+
+## Index and navigation
+
+[AccountIndex](../examples/index-table.tsx) exports `AccountIndex`, `AccountIndexProps`, `AccountRow` and `AccountIndexState`. Props are `state`, `onRetry`, `hrefFor(record)` and `onNavigate(href)`. The app drives the discriminated state: `loading`, `error` with a message, or `ready` with records. An empty ready collection renders the table's empty state. `onRetry` starts your loader; it must update app state through loading to ready/error. Stable row IDs belong to the records.
+
+This recipe uses `themelia-react-ui/features/table`, so install `@tanstack/react-table` as an optional peer. Card frames the page; the nested table uses `surface="flat"`. A row action calls your navigation callback with your URL; `href` alone on a table action does not navigate. Supply your router callback or ordinary browser navigation. The library neither requests records nor chooses routes.
+
+Verify loading, empty refresh, failure/retry and ready records. Open the row menu with pointer and keyboard, activate Open account, and assert the requested URL. Check narrow overflow and email-link behavior. If you need a presentational table without TanStack features, discover `themelia-react-ui/base/table` and inspect its separate declaration.
+
+## Detail and framing
+
+[AccountDetail](../examples/detail.tsx) exports `AccountDetail`, `AccountDetailProps` and `AccountDetailRecord`. Supply `account`, `onEdit(id)` and `onBack()`. Card owns the frame/header/body/footer; Name, Email, Date, Money and Value own formatting and missing-value fallbacks. `balanceMinor` uses `Money unit="minor"`; currency and date values come from the app.
+
+No optional peers are needed. The app supplies the loaded record and owns navigation, locale/provider defaults and permissions. Verify missing email/date/balance, a real minor-unit amount, Edit/Back callbacks, and the one-column mobile/two-column desktop composition in light/dark themes.
+
+## Validated editing
+
+[AccountEdit](../examples/edit.tsx) exports `AccountEdit`, `AccountEditProps` and `AccountEditValue`. Supply `initial`, `onSave(value): Promise<AccountEditValue>` and `onCancel()`. Mount with `key={initial.id}` when switching records. The draft is local to that mount; resetting the same record's draft deliberately also requires a new key or your own controlled adaptation.
+
+`FormField` is presentation chrome, but its exact published family `themelia-react-ui/base/forms` also exports React Hook Form integration. Strict whole-family declaration checking therefore requires the optional `react-hook-form` peer. This recipe does not use that integration or require a form framework at runtime; it still belongs in the optional declaration phase. Input comes from `themelia-react-ui/base/text-inputs`.
+
+Submit trims and validates at least two characters, focuses the invalid input, associates its supporting text, and blocks duplicate/pending submission. `onSave` must persist and update app data, then resolve with the authoritative value. Reject on failure. A rejection retains the draft and offers retry; resolution shows success and the returned name. A status message is only feedback for the callback outcome. Cancel requests app navigation and is disabled while saving.
+
+Verify invalid input sends no callback, input focus/ARIA error, pending controls, rejection with retained draft, retry, returned server value and success, and Cancel. Use a deferred callback to observe pending state instead of an artificial delay.
+
+## Destructive confirmation
+
+[DeleteAccount](../examples/destructive-confirm.tsx) exports `DeleteAccount` and `DeleteAccountProps`. Supply `account`, `onDelete(id): Promise<void>` and optional `onCancel()`. Mount with an account-specific key when changing targets. There are no optional peers. The library ConfirmDialog owns modal focus, confirm pending presentation, rejection recovery and close-on-success. The recipe guards pending dismissal and hides Cancel while the irreversible request is underway; Cancel and Escape remain available before the request and after failure.
+
+Your delete callback owns persistence and record removal. Reject failures instead of catching them and returning success: ConfirmDialog must see the rejection to leave the dialog open and call `onError`. The recipe clears the previous error on retry, shows recovery text, and marks completion only after resolution. Keep this owner and its trigger mounted through dialog closure; the completed trigger remains focusable with `aria-disabled` so focus can return, and the controlled open guard prevents another deletion. If app navigation removes the owner, explicitly choose the destination focus in your app.
+
+Verify open/title/description, trapped keyboard focus, Cancel/Escape without a deletion callback, pending dismissal prevention, rejected callback with an open error, retry and successful closure, exactly one backend effect, and trigger focus restoration. Check the opened error dialog in dark/mobile as well as light/desktop. Do not infer these interactions from typechecking or screenshots.
+
+The existing [AccountComposition](../examples/composition.tsx) remains a basic Card/ActionDialog composition with `save(name): Promise<void>`. Its callback must reject on failure; the app owns persistence. The four recipes above add progressive collection/detail/edit/delete ownership without changing that example's contract.

package/docs/consumer-skill/scripts/discovery.mjs

@@ -0,0 +1,79 @@
+export const layers = ['foundations', 'base', 'layout', 'blocks', 'features'];
+const requireFormat = (condition, message) => { if (!condition) throw new Error(`Invalid discovery index: ${message}`); };
+const stringList = value => Array.isArray(value) && value.every(item => typeof item === 'string');
+const text = value => typeof value === 'string' && value.trim().length > 0;
+const normalized = value => value.toLowerCase();
+const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+
+export function validateIndex(index) {
+  requireFormat(index?.schemaVersion === 1 && index?.discoveryVersion === 1, 'unsupported schema/format; expected schemaVersion 1 and discoveryVersion 1');
+  requireFormat(text(index.package) && text(index.version) && Array.isArray(index.families), 'package, version and families are required');
+  const seen = new Set();
+  for (const family of index.families) {
+    requireFormat(text(family?.import) && (family.import === index.package || family.import.startsWith(`${index.package}/`)) && !/[\\\s]|(?:^|\/)\.\.(?:\/|$)/.test(family.import), 'invalid public import');
+    requireFormat(!seen.has(family.import), `duplicate import ${family.import}`);
+    seen.add(family.import);
+    requireFormat(text(family.declaration) && /^dist\/[\w./-]+\.d\.ts$/.test(family.declaration) && !family.declaration.split('/').includes('..'), `invalid declaration ${family.declaration}`);
+    requireFormat(layers.includes(family.layer) && text(family.responsibility), `missing layer/responsibility for ${family.import}`);
+    for (const field of ['symbols', 'jobs', 'tags', 'aliases', 'sections', 'optionalPeers']) requireFormat(stringList(family[field]), `invalid ${field} for ${family.import}`);
+    requireFormat(family.optionalPeers.every(peer => index.peers?.some(owner => owner.name === peer && owner.optional)), `unknown optional peer for ${family.import}`);
+    requireFormat(Array.isArray(family.guidance), `invalid guidance for ${family.import}`);
+    for (const guide of family.guidance) {
+      requireFormat(text(guide?.title) && typeof guide.description === 'string' && typeof guide.section === 'string', 'invalid guidance title/description/section');
+      requireFormat(guide.browse && ['category', 'group', 'collection'].every(field => typeof guide.browse[field] === 'string'), 'invalid guidance browse context');
+      requireFormat(guide.browse.domain === undefined || typeof guide.browse.domain === 'string', 'invalid guidance browse domain');
+      for (const field of ['chooseWhen', 'avoidWhen', 'appOwned', 'jobs', 'tags', 'aliases', 'alternatives']) requireFormat(stringList(guide[field]), `invalid guidance ${field}`);
+      requireFormat(Array.isArray(guide.sections) && guide.sections.every(section => text(section?.title) && stringList(section.symbols)), 'invalid guidance sections');
+    }
+  }
+  for (const family of index.families) for (const guide of family.guidance) for (const alternative of guide.alternatives) requireFormat(seen.has(alternative), `unpublished alternative ${alternative}`);
+  return index;
+}
+
+export function parseArguments(args) {
+  const words = [];
+  const options = { layer: null, limit: 5 };
+  const seen = new Set();
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!arg.startsWith('-')) { words.push(arg); continue; }
+    if (!['--layer', '--limit'].includes(arg)) throw new Error(`Unknown argument: ${arg}`);
+    if (seen.has(arg)) throw new Error(`Duplicate argument: ${arg}`);
+    seen.add(arg);
+    const value = args[++i];
+    if (!value || value.startsWith('-')) throw new Error(`Missing value for ${arg}`);
+    if (arg === '--layer') {
+      if (!layers.includes(value)) throw new Error(`Invalid layer: ${value}; choose ${layers.join(', ')}`);
+      options.layer = value;
+    } else {
+      if (!/^[1-9]\d*$/.test(value) || Number(value) > 100) throw new Error('Invalid limit: use an integer from 1 to 100');
+      options.limit = Number(value);
+    }
+  }
+  const query = words.join(' ').trim();
+  if (!query) throw new Error('A nonempty query is required');
+  return { query, ...options };
+}
+
+const guideText = guide => normalized([guide.title, guide.description, ...Object.values(guide.browse), ...guide.jobs, ...guide.tags, ...guide.aliases, ...guide.chooseWhen, ...guide.appOwned, ...guide.sections.flatMap(section => [section.title, ...section.symbols])].join(' '));
+
+export function findComponents(index, { query, layer = null, limit = 5 }) {
+  validateIndex(index);
+  const needle = normalized(query);
+  const terms = [...new Set(needle.split(/\s+/).filter(Boolean))];
+  const ranked = [];
+  for (const family of index.families) {
+    if (layer && layer !== family.layer) continue;
+    const exactImport = normalized(family.import) === needle;
+    const matchedSymbols = family.symbols.filter(symbol => normalized(symbol) === needle);
+    const haystack = normalized([family.import, family.responsibility, ...family.symbols, ...family.jobs, ...family.tags, ...family.aliases, ...family.sections, ...family.guidance.map(guideText)].join(' '));
+    // AND matching prevents a familiar term from inventing results for an
+    // otherwise unknown query. Avoidance/alternatives do not recommend owners.
+    if (!exactImport && !matchedSymbols.length && !terms.every(term => haystack.includes(term))) continue;
+    const score = exactImport ? 10000 : matchedSymbols.length ? 9000 : terms.reduce((sum, term) => sum + (family.guidance.some(guide => normalized(guide.title).includes(term)) ? 20 : family.tags.some(tag => normalized(tag).includes(term)) ? 10 : 1), 0);
+    const guidance = family.guidance.map(guide => ({ guide, score: terms.filter(term => guideText(guide).includes(term)).length })).sort((a, b) => b.score - a.score || compare(a.guide.title, b.guide.title)).slice(0, 3).map(({ guide }) => guide);
+    ranked.push({ score, import: family.import, declaration: family.declaration, layer: family.layer, responsibility: family.responsibility, optionalPeers: family.optionalPeers, match: exactImport ? 'import' : matchedSymbols.length ? 'symbol' : 'intent', matchedSymbols, guidance });
+  }
+  ranked.sort((a, b) => b.score - a.score || compare(a.import, b.import));
+  return { package: index.package, version: index.version, query, layer, limit, total: ranked.length, results: ranked.slice(0, limit) };
+}

package/docs/consumer-skill/scripts/find-components.mjs

@@ -0,0 +1,11 @@
+import fs from 'node:fs';
+import { findComponents, parseArguments } from './discovery.mjs';
+
+try {
+  const options = parseArguments(process.argv.slice(2));
+  const index = JSON.parse(fs.readFileSync(new URL('../references/public-api.json', import.meta.url), 'utf8'));
+  process.stdout.write(JSON.stringify(findComponents(index, options), null, 2) + '\n');
+} catch (error) {
+  process.stderr.write(`find-components: ${error.message}\nUsage: node find-components.mjs <query terms> [--layer foundations|base|layout|blocks|features] [--limit 1..100]\n`);
+  process.exitCode = 1;
+}