themelia-react-ui 0.0.0-stage → 1.0.1

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

@@ -0,0 +1,135 @@
+# 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 an independent Accounts subject; the nested table uses `surface="flat"`. For a primary route collection use its own native table surface, as in the scoped directory below. 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.
+
+## Scoped directory
+
+[ScopedDirectory](../examples/scoped-directory.tsx) demonstrates a primary route
+collection. Page owns Contacts, the fixed business context and the explicit
+primary New contact command. DataTable owns the surface; FilterLayout occupies
+`topbarContent`, optional export occupies `topbarEnd`, and Open contact is a row
+action. ResourceCell owns identity, shared small secondary Text supplies role,
+and Email owns formatting. Other operational facts belong in the contact detail
+reached by `onOpen`; the example does not append every fact to compact identity.
+
+The optional `compact` prop is an app presentation decision from available parent
+width. It keeps email reach in the identity cell and omits the comparison Email
+column, preserving one copy and reachable row actions. This deliberately retains
+one task-critical fact; other metadata stays in detail. Choose the threshold
+from actual content and work-region measurements, not a universal library setting.
+
+The app supplies `scope`, discriminated `state`, controlled `filters`, navigation
+and loading callbacks. `onQueryChange({ scopeId, filters })` preserves fixed
+business context even when criteria clear. It does not request records itself.
+The recipe removes a blank `q` search criterion without normalizing unrelated
+filter types. Native search can emit an empty string; the app owns query meaning.
+The app updates filters/state, ignores stale responses and preserves scope/query
+in pagination URLs. A criteria-driven business selector would be a different
+product contract. The recipe's English labels are example copy: adapt labels,
+criteria and component `strings` for app translation and permissions.
+
+Strict imported declarations require the manifest's optional peers. DataTable
+sorting is disabled because the app's server owns query order. Loading/error
+feedback occupies the empty result region while query context remains mounted;
+accepted records replace it. Use the public loading/preview owner if retaining
+previous results is required by your app. Avoid stale pagination metadata during
+loading/errors. Run the same query with loading, failure, retry and empty results.
+
+Verify one contextual lead, primary command, query/clear scope retention,
+row-menu navigation, server page callbacks and long-name/mobile containment.
+Opening a record preserves access to supporting facts. Integrated queries and
+separate query regions are both supported; choose by task and keep one owner.
+
+Keep DataTable column/action definitions stable when unrelated parent feedback
+changes. Changing a cell renderer's identity can remount its menu trigger and
+lose return focus. This recipe memoizes row actions by `onOpen`; the app keeps
+that callback stable when its meaning is unchanged. Stabilize these lifecycle
+inputs deliberately, not every object. A real record/scope change can replace
+definitions; the app then chooses appropriate destination focus.
+
+## 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.
+
+## Task summaries, usage and inline editing
+
+[Workspace summary](../examples/planning-usage-edit.tsx) composes three focused
+owners. `TaskCard` from `themelia-react-ui/blocks/planning` owns the explicit Card
+surface, completion summary, disclosure and controlled subtask proposals.
+Update `items` after `onItemCompletedChange`; supply each item's `busy` or
+`error` from your persistence lifecycle. Workflow status, due-date formatting,
+assignment and Open navigation remain application data/callbacks.
+
+Click passive header content or use the native caret (pointer, Enter or Space)
+to request expansion. Both respect `expanded`/`onExpandedChange` and `disabled`;
+header clicks focus the caret. Subtask and footer actions remain independent.
+The block owns the segmented progress drawing, completion strikethrough and
+compact checklist insets. Its progress value follows accepted `items`, including
+undo; workflow status stays separate. Reduced motion disables the ring animation.
+
+`UsageCard` from `themelia-react-ui/blocks/analytics/usage-card` is a standalone
+quota/analytics composition with no optional chart dependency. Supply matching
+`data`, `period` and `status` after `onPeriodChange`; cancel or ignore stale
+application requests. `limit: null` means unlimited, omitted limits or values
+mean unavailable, and zero is real data. Category percentages describe shares
+of reported usage; bounded graphics never hide actual over-quota amounts.
+Daily data is chronological application data with text equivalents. The block
+owns no subscription or billing requests; `footerAction` is application content.
+
+`InlineEdit` from `themelia-react-ui/base/inline-edit` uses our native Input or
+Textarea. Supply `onSave(value, { signal })` for asynchronous persistence and
+update a controlled saved value through `onValueChange`. Required/validation
+checks apply when saving a draft. Parent forms serialize the committed value
+through `name`; they own validation of their complete stored data. Enter saves
+a single line, Control/Command Enter saves multiline text, and Escape cancels.
+Cancellation invalidates late UI results and aborts the supplied signal; the
+application owns actual transport and server effects. Read-only display stays
+passive. Use Card at a composition boundary for a framed field section.
+
+Display and editing share the Input frame and `size`, `invalid`, `loading`,
+`clearable`, `onClear` and `showCharacterCount` APIs. The stable field/action
+grid transitions width and honors reduced motion; multiline actions form a
+centered column. Use `inputProps`/`textareaProps` for native editor attributes,
+adornments, resizing and control-specific strings. State/value/ref/form ownership
+stays with InlineEdit. Native constraints run on Save; uncommitted controls are
+isolated from the parent form. External loading retains a draft while disabling
+edits/save, and leaves cancellation available.
+
+The field/action gap uses the existing `lg` spacing step; the action group uses
+`xs`. Single-line actions form a horizontal pair and multiline actions a centered
+column. Keep these library-owned controls and geometry instead of replacing
+them with app-styled fields. Verify cancellation during persistence, retained
+drafts after rejection, native constraints, committed FormData, controlled
+expansion, checkbox/Open independence and async period retry in your app.

package/docs/consumer-skill/scripts/check-composition.mjs

@@ -0,0 +1,31 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { validateIndex } from './discovery.mjs';
+import { analyzeComposition } from './composition-policy.mjs';
+
+try {
+  const targets = process.argv.slice(2);
+  if (!targets.length || targets.some(target => target.startsWith('-'))) throw new Error('Pass explicit source files/directories; no flags or automatic app-wide scan.');
+  const requireFromApp = createRequire(path.join(process.cwd(), 'package.json'));
+  const ts = requireFromApp('typescript');
+  const index = validateIndex(JSON.parse(fs.readFileSync(new URL('../references/public-api.json', import.meta.url), 'utf8')));
+  const files = new Set();
+  function collect(target) {
+    const info = fs.lstatSync(target);
+    if (info.isSymbolicLink()) throw new Error(`Use a real source path instead of a symlink: ${target}`);
+    if (info.isDirectory()) {
+      for (const entry of fs.readdirSync(target).sort()) if (!['node_modules', '.git', 'dist', 'build'].includes(entry)) collect(path.join(target, entry));
+    } else if (/\.[jt]sx?$/.test(target) && !/\.d\.ts$/.test(target)) files.add(path.resolve(target));
+  }
+  targets.forEach(collect);
+  if (!files.size) throw new Error('No supported source files found in the supplied paths.');
+  const reports = [...files].sort().map(filename => analyzeComposition(fs.readFileSync(filename, 'utf8'), { filename, index, ts }));
+  const findings = reports.flatMap(report => report.findings);
+  const errors = findings.filter(finding => finding.severity === 'error').length;
+  process.stdout.write(JSON.stringify({ package: index.package, version: index.version, files: files.size, errors, warnings: findings.length - errors, findings, unresolved: reports.flatMap(report => report.unresolved), limits: 'Direct public imports and same-file static JSX only; external CSS, cross-file wrappers and dynamic values require review.' }, null, 2) + '\n');
+  process.exitCode = errors ? 1 : 0;
+} catch (error) {
+  process.stderr.write(`check-composition: ${error.message}\nRun from the consumer app with its TypeScript development dependency installed.\n`);
+  process.exitCode = 1;
+}

package/docs/consumer-skill/scripts/composition-policy.mjs

@@ -0,0 +1,155 @@
+import { surfaceParts, surfaceForwarders, paddingClass, paddingProperty, utility } from './surface-policy.mjs';
+
+const controlNames = /^(?:Base)?(?:Button|ButtonLink|IconButton)$|^(Input|InputGroupInput|Textarea|SelectTrigger|ComboboxTrigger)$/;
+const controlFamilies = new Set(['buttons', 'text-inputs', 'choice-inputs', 'combobox']);
+const fixedControlClass = /^(?:h|min-h|size|p[xytrblse]?)-|^rounded-(?:xs|sm|md|lg|xl|[2-9]xl|\[)|^text-(?:xs|sm|base|lg|xl|[2-9]xl|\[(?:length:|[\d.]+(?:px|rem|em)))|^(?:font|leading|tracking)-/;
+const controlStyle = /^(height|minHeight|fontSize|fontWeight|lineHeight|letterSpacing|borderRadius)$/;
+
+/** Small static review: TypeScript is supplied by the app, never a runtime peer. */
+export function analyzeComposition(text, { filename, index, ts }) {
+  const kind = /\.jsx?$/.test(filename) ? ts.ScriptKind.JSX : filename.endsWith('.tsx') ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
+  const source = ts.createSourceFile(filename, text, ts.ScriptTarget.Latest, true, kind);
+  const families = new Map(index.families.map(owner => [owner.import, owner]));
+  const bindings = new Map();
+  const namespaces = new Map();
+  const declarations = new Map();
+  const findings = [];
+  const unresolved = [];
+  const seen = new Set();
+  const add = (node, rule, severity, message) => {
+    const position = source.getLineAndCharacterOfPosition(node.getStart(source));
+    const key = `${node.pos}:${rule}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    findings.push({ file: filename, line: position.line + 1, column: position.character + 1, rule, severity, message });
+  };
+  const unknown = node => {
+    const key = `${node.pos}:unresolved`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    const position = source.getLineAndCharacterOfPosition(node.getStart(source));
+    unresolved.push({ file: filename, line: position.line + 1, expression: node.getText(source).slice(0, 120) });
+  };
+  const resolve = (node, visiting = new Set()) => {
+    if (!node || visiting.has(node)) return undefined;
+    visiting.add(node);
+    if (ts.isIdentifier(node)) return resolve(declarations.get(node.text), visiting);
+    if (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isSatisfiesExpression(node)) return resolve(node.expression, visiting);
+    return node;
+  };
+  const properties = (expression, mark = true, visited = new Set()) => {
+    const node = resolve(expression);
+    if (!node || !ts.isObjectLiteralExpression(node) || visited.has(node)) {
+      if (mark && expression) unknown(expression);
+      return [];
+    }
+    visited.add(node);
+    return node.properties.flatMap(property => {
+      if (ts.isSpreadAssignment(property)) return properties(property.expression, mark, visited);
+      const name = property.name;
+      const key = ts.isComputedPropertyName(name) ? resolve(name.expression) : name;
+      if (!key || !(ts.isIdentifier(key) || ts.isStringLiteralLike(key))) {
+        if (mark) unknown(property);
+        return [];
+      }
+      return [[key.text, ts.isShorthandPropertyAssignment(property) ? property.name : property.initializer]];
+    });
+  };
+  const classStrings = (expression, visited = new Set()) => {
+    const node = resolve(expression);
+    if (!node || visited.has(node)) { if (expression) unknown(expression); return []; }
+    visited.add(node);
+    if (ts.isStringLiteralLike(node)) return [node.text];
+    if (ts.isConditionalExpression(node)) return [...classStrings(node.whenTrue, visited), ...classStrings(node.whenFalse, visited)];
+    if (ts.isBinaryExpression(node) && [ts.SyntaxKind.AmpersandAmpersandToken, ts.SyntaxKind.BarBarToken, ts.SyntaxKind.QuestionQuestionToken].includes(node.operatorToken.kind)) return classStrings(node.right, visited);
+    if (ts.isArrayLiteralExpression(node)) return node.elements.flatMap(item => classStrings(item, visited));
+    if (ts.isCallExpression(node) && /^(cn|clsx|classNames|twMerge)$/.test(node.expression.getText(source))) return node.arguments.flatMap(item => classStrings(item, visited));
+    if ([ts.SyntaxKind.FalseKeyword, ts.SyntaxKind.TrueKeyword, ts.SyntaxKind.NullKeyword].includes(node.kind)) return [];
+    unknown(expression);
+    return [];
+  };
+  const literal = expression => {
+    const node = resolve(expression);
+    return node && ts.isStringLiteralLike(node) ? node.text : undefined;
+  };
+  function importOwner(node, specifier) {
+    if (specifier !== index.package && !specifier.startsWith(index.package + '/')) return;
+    if (index.stylesheets?.includes(specifier)) return;
+    const family = families.get(specifier);
+    if (!family) { add(node, 'public-import', 'error', `No published owner for ${specifier}; discover the version-matched public entrypoint.`); return; }
+    const names = ts.isImportDeclaration(node) ? node.importClause?.namedBindings : node.exportClause;
+    if (ts.isImportDeclaration(node) && node.importClause?.name && !family.symbols.includes('default')) add(node.importClause.name, 'public-symbol', 'error', `${specifier} has no default export; use its named public symbols.`);
+    const elements = names && (ts.isNamedImports(names) || ts.isNamedExports(names)) ? names.elements : [];
+    for (const item of elements) {
+      const symbol = (item.propertyName ?? item.name).text;
+      if (!family.symbols.includes(symbol)) add(item, 'public-symbol', 'error', `${specifier} does not export ${symbol}; inspect its declaration.`);
+      if (ts.isImportDeclaration(node)) bindings.set(item.name.text, { symbol, import: specifier });
+    }
+    if (names && ts.isNamespaceImport(names)) namespaces.set(names.name.text, specifier);
+  }
+  function gather(node) {
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer) declarations.set(node.name.text, node.initializer);
+    if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && ts.isStringLiteralLike(node.moduleSpecifier)) importOwner(node, node.moduleSpecifier.text);
+    if (ts.isImportTypeNode(node) && ts.isLiteralTypeNode(node.argument) && ts.isStringLiteralLike(node.argument.literal)) importOwner(node, node.argument.literal.text);
+    if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword && ts.isStringLiteralLike(node.arguments[0])) importOwner(node, node.arguments[0].text);
+    ts.forEachChild(node, gather);
+  }
+  gather(source);
+  for (const diagnostic of source.parseDiagnostics) add(source, 'syntax', 'error', ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n'));
+  const ownerFor = tag => {
+    if (bindings.has(tag)) return bindings.get(tag);
+    const [namespace, symbol] = tag.split('.');
+    const specifier = namespaces.get(namespace);
+    return specifier && symbol ? { symbol, import: specifier } : undefined;
+  };
+  const attributes = node => node.attributes.properties.flatMap(attribute => {
+    if (ts.isJsxSpreadAttribute(attribute)) return properties(attribute.expression);
+    if (!attribute.initializer) return [[attribute.name.getText(source), undefined]];
+    const expression = ts.isJsxExpression(attribute.initializer) ? attribute.initializer.expression : attribute.initializer;
+    return [[attribute.name.getText(source), expression]];
+  });
+  function visit(node, parents = []) {
+    if (ts.isJsxElement(node)) {
+      const element = node.openingElement;
+      const context = inspect(element, parents);
+      for (const child of node.children) visit(child, context ? [...parents, context] : parents);
+      // JSX in props is a separate region, not a child frame.
+      for (const attribute of element.attributes.properties) ts.forEachChild(attribute, child => visit(child, parents));
+      return;
+    }
+    if (ts.isJsxSelfClosingElement(node)) inspect(node, parents);
+    ts.forEachChild(node, child => visit(child, parents));
+  }
+  function inspect(node, parents) {
+    const owner = ownerFor(node.tagName.getText(source));
+    if (!owner) return;
+    if (!families.get(owner.import)?.symbols.includes(owner.symbol)) {
+      add(node, 'public-symbol', 'error', `${owner.import} does not export ${owner.symbol}.`);
+      return;
+    }
+    const props = new Map(attributes(node));
+    const family = owner.import.split('/base/')[1];
+    const anatomy = surfaceParts[family]?.test(owner.symbol);
+    const forwarder = surfaceForwarders[family] === owner.symbol;
+    const control = controlFamilies.has(family) && controlNames.test(owner.symbol);
+    for (const name of ['className', 'contentClassName']) {
+      if (!props.has(name)) continue;
+      const classes = classStrings(props.get(name)).flatMap(value => value.split(/\s+/)).map(utility);
+      if ((anatomy || forwarder && name === 'contentClassName') && classes.some(value => paddingClass.test(value))) add(node, 'surface-padding', 'error', `${owner.symbol}: use inset/type/density and public regions; padding overrides replace owned anatomy.`);
+      if (control && name === 'className' && classes.some(value => fixedControlClass.test(value))) add(node, 'control-anatomy', 'error', `${owner.symbol}: use its size/variant props; preserve shared control height, inset, corners and typography.`);
+    }
+    if (props.has('style')) for (const [name] of properties(props.get('style'))) {
+      if (anatomy && paddingProperty.test(name)) add(node, 'surface-padding', 'error', `${owner.symbol}: ${name} replaces the region inset; use its public surface props.`);
+      if (control && (paddingProperty.test(name) || controlStyle.test(name))) add(node, 'control-anatomy', 'error', `${owner.symbol}: ${name} belongs to shared control geometry/typography.`);
+    }
+    if (['SmartCard', 'ContentBlock'].includes(owner.symbol)) add(node, 'deprecated-owner', 'warning', `${owner.symbol} is a migration owner; prefer Card for new compositions.`);
+    const framed = ['Card', 'SmartCard', 'ContentBlock', 'DataTable', 'DataView'].includes(owner.symbol) && literal(props.get('surface')) !== 'flat';
+    if (framed && parents.some(parent => parent.framed)) add(node, 'nested-surface', 'warning', `${owner.symbol} is inside a framed owner. Review subject boundaries; use surface="flat" when the parent owns the frame.`);
+    const header = properties(props.get('header'), false);
+    const title = literal(props.get('title')) ?? literal(new Map(header).get('title'));
+    if (title && parents.some(parent => parent.title === title)) add(node, 'duplicate-heading', 'warning', `The heading "${title}" repeats its ancestor. Keep one route/subject title unless a distinct task warrants repetition.`);
+    return { framed, title };
+  }
+  visit(source);
+  return { findings, unresolved };
+}

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

@@ -0,0 +1,84 @@
+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');
+  if (index.stylesheets !== undefined) requireFormat(stringList(index.stylesheets) && index.stylesheets.every(file => file.startsWith(index.package + '/') && file.endsWith('.css') && !file.includes('..')), 'invalid public stylesheets');
+  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;
+    // A dedicated, documented owner precedes an aggregate re-export of the
+    // same symbol. Explicit import queries still select the requested family.
+    const documentedSymbol = family.guidance.some(guide => guide.sections.some(section => section.symbols.some(symbol => normalized(symbol) === needle)));
+    const exactIntent = family.aliases.some(alias => normalized(alias) === needle);
+    const score = exactImport ? 10000 : matchedSymbols.length ? 9000 + Number(documentedSymbol) : exactIntent ? 8000 : 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;
+}

package/docs/consumer-skill/scripts/surface-policy.mjs

@@ -0,0 +1,22 @@
+// One public anatomy vocabulary, shared by repository and opt-in consumer checks.
+export const surfaceParts = {
+  popover: /^(PopoverContent|PopoverHeader|PopoverFooter)$/,
+  command: /^Command(Input|List|Group|Item|Empty|Separator)?$/,
+  navigation: /^DropdownMenu(Content|SubContent|Label|Item|LinkItem|SubTrigger|CheckboxItem|RadioItem|Separator)$/,
+  'choice-inputs': /^SelectPopup(Content|Group|Item|Label|Separator)?$/,
+  combobox: /^Combobox(Popup|Content|List|Item|GroupLabel|Separator)$/,
+};
+export const surfaceForwarders = { 'choice-inputs': 'Select', 'popover-menu': 'PopoverMenu', 'action-menu': 'ActionMenu' };
+export const paddingClass = /^(?:p[xytrblse]?|p(?:bs|be)|padding)-|^\[padding/;
+export const paddingProperty = /^padding(?:Inline|Block)?(?:Start|End)?$|^padding(?:Top|Right|Bottom|Left)$|^padding-(?:(?:inline|block)(?:-(?:start|end))?|top|right|bottom|left)$/;
+
+export function utility(token) {
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < token.length; i++) {
+    if (token[i] === '[' || token[i] === '(') depth++;
+    if (token[i] === ']' || token[i] === ')') depth--;
+    if (token[i] === ':' && depth === 0) start = i + 1;
+  }
+  return token.slice(start).replace(/^!|!$/g, '');
+}