themelia-react-ui 2.0.4 → 2.0.5

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

@@ -124,7 +124,13 @@ back navigation, content bounds, commands and section tabs. Pass the record's
 main command as `header.primaryAction`, supporting commands as
 `header.secondaryActions` and separately selected/routed sections as `header.tabs`;
 continuous sections can stay in the body. One status badge goes in
-`header.titleBadges`. `PageHeader` serves a custom shell; `PageActions` is
+`header.slots.titleSuffix` as a composed Badge. Place supporting facts in
+`header.slots.afterDescription` as a MetadataList when useful. The four header
+slots (`beforeTitle`, `titleSuffix`, `afterDescription`, `actions`) accept content
+or a callback receiving `{ renderLink, defaultContent }`; an actions callback
+can wrap or return `defaultContent` to retain responsive commands. A replacement
+owns its behavior. Below 40rem of actual header width, all commands, including
+primary, share one More actions trigger. `PageHeader` serves a custom shell; `PageActions` is
 deprecated. The [layout recipe](../examples/app-layout.tsx) demonstrates that
 route boundary; the [detail recipe](../examples/detail.tsx) demonstrates the
 record route and an independently framed subject with MetadataList and value

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

@@ -184,6 +184,25 @@ export function analyzeComposition(text, { filename, index, ts }) {
     if (ts.isJsxElement(element.parent)) element.parent.children.forEach(collect);
     return found;
   };
+  // Static region children only: inspect known passive wrappers and providers,
+  // never assume an opaque app component renders its lexical children.
+  const regionElements = (opening, deep = false) => {
+    const found = [];
+    const collect = (child, scope = opening, subject) => {
+      if (ts.isJsxFragment(child)) { child.children.forEach(item => collect(item, scope, subject)); return; }
+      if (ts.isJsxExpression(child)) { const value = resolve(child.expression); if (value) collect(value, scope, subject); return; }
+      const node = ts.isJsxElement(child) ? child.openingElement : ts.isJsxSelfClosingElement(child) ? child : undefined;
+      if (!node) return;
+      const owner = ownerFor(node.tagName);
+      found.push({node, owner, tag: node.tagName.getText(source), scope, subject});
+      const provider = isOwner(owner, 'features/filters', ['FilterProvider']);
+      const card = isOwner(owner, 'base/cards', ['Card', 'SmartCard']);
+      // Cards delimit independent subjects; providers delimit query state.
+      if (deep && ts.isJsxElement(child) && (/^(div|section|form)$/.test(node.tagName.getText(source)) || isOwner(owner, 'base/structure', ['Stack', 'Grid', 'AdaptiveGrid', 'GridCell']) || card || provider)) child.children.forEach(item => collect(item, provider ? node : scope, card ? node : subject));
+    };
+    if (ts.isJsxElement(opening.parent)) opening.parent.children.forEach(child => collect(child));
+    return found;
+  };
   const renderedText = element => ts.isJsxElement(element) ? element.children.map(child => ts.isJsxText(child) ? child.text : ts.isJsxExpression(child) ? literal(child.expression) ?? '' : '').join(' ').trim() : '';
   const slotBadge = expression => {
     const node = resolve(expression);
@@ -342,7 +361,7 @@ export function analyzeComposition(text, { filename, index, ts }) {
       if (modalRole || scrim) add(node, 'raw-overlay-primitive', 'warning', `A hand-rolled ${modalRole ? 'dialog' : 'full-screen layer'} must own focus, dismissal, pending state and theming itself. ${overlayRemedy}`);
       if (/^(?:input|textarea)$/.test(node.tagName.getText(source))) {
         const props = new Map(attributes(node));
-        if (props.has('className') && classStrings(props.get('className')).flatMap(value=>value.split(/\s+/)).some(value=>replacesSharedRadius(value,'inner'))) add(node,'shared-radius','error','Native editable controls follow bounded rounded-inner; change the global theme root, not per-field corners.');
+        if (props.has('className') && classStrings(props.get('className')).flatMap(value=>value.split(/\s+/)).some(value=>replacesSharedRadius(value,'radius'))) add(node,'shared-radius','error','Native editable controls follow bounded rounded-radius; change the global theme root, not per-field corners.');
         if (props.has('style') && properties(props.get('style')).some(([name])=>radiusProperty.test(name))) add(node,'shared-radius','error','Native editable corners belong to the global radius root, not inline styles.');
       }
       if (nativeDisplayNames.test(node.tagName.getText(source))) {
@@ -375,7 +394,7 @@ export function analyzeComposition(text, { filename, index, ts }) {
       const focusDrift = focusRingDrift(tokens);
       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 ((name === 'className' && (control || sharedCorners) || name === 'contentClassName' && forwarder) && classes.some(value=>replacesSharedRadius(value, control && name === 'className' ? 'inner' : cornerRole(family,owner.symbol)))) add(node,'shared-radius','error',`${owner.symbol}: outer shells use rounded-radius; controls and collection rows use bounded rounded-inner. Preserve the owning role and joined-edge resets.`);
+      if ((name === 'className' && (control || sharedCorners) || name === 'contentClassName' && forwarder) && classes.some(value=>replacesSharedRadius(value, control && name === 'className' ? 'radius' : cornerRole(family,owner.symbol)))) add(node,'shared-radius','error',`${owner.symbol}: outer shells use rounded-surface; controls and collection rows use bounded rounded-radius. Preserve the owning role and joined-edge resets.`);
       if (display && classes.some(addsCopyMargin)) add(node,'copy-margin','error',`${owner.symbol}: typography is margin-free; use textGap on the headed owner or gap on Stack/Grid.`);
       if (textContent && name === 'className' && tokens.some(token=>fadedText(token)||textOpacityDrift(token))) add(node,'faded-text','error',`${owner.symbol}: use its semantic type instead of adding an opacity tier to the text. Presence endpoints and shared disabled state remain valid.`);
       if ((control || family === 'buttons' && owner.symbol === 'TextButton') && name === 'className' && focusDrift.length) add(node, 'focus-ring-recipe', 'error', `${owner.symbol}: keep the shared focus indicator (a ring-3 halo of ring-ring/50 around a full-strength ring edge); ${[...new Set(focusDrift)].join(', ')} redraws it.`);
@@ -404,6 +423,23 @@ export function analyzeComposition(text, { filename, index, ts }) {
     }
     if (isOwner(owner, 'base/feedback', ['Empty'])) add(node, 'reinvented-empty-state', 'warning', 'Empty exposes lower-level anatomy. Compare EmptyState from blocks/data-display for a routine no-data/no-results region; keep Empty when custom anatomy is required.');
     if (isOwner(owner, 'base/sheet', ['Sheet', 'SheetContent']) || isOwner(owner, 'base/display', ['Dialog', 'DialogContent', 'AlertDialog', 'AlertDialogContent'])) add(node, 'raw-overlay-primitive', 'warning', 'This lower-level modal needs application lifecycle coordination. Prefer ActionDialog, ConfirmDialog or ActionDrawer from features/overlays when their workflow fits.');
+    if (isOwner(owner, 'features/table', ['DataTable'])) {
+      const parent = parents.at(-1);
+      let ancestor = ts.isJsxOpeningElement(node) ? node.parent.parent : node.parent;
+      while (ancestor && !ts.isJsxElement(ancestor)) ancestor = ancestor.parent;
+      const directOwner = ancestor && ownerFor(ancestor.openingElement.tagName);
+      if (isOwner(directOwner, 'base/cards', ['Card', 'SmartCard']) && isOwner(parent?.owner, 'base/cards', ['Card', 'SmartCard']) && literal(parent.props.get('padding')) !== 'none' && !parent.unknownProps) add(node, 'uncontained-table-in-card', 'warning', 'DataTable owns its surface, topbar and edge-to-edge header band. Render it directly in Page or a layout region; a deliberate Card host must use padding="none".');
+    }
+    const routeOwner = isOwner(owner, 'layout/page', ['Page']) || isOwner(owner, 'layout', ['Page']);
+    if (routeOwner) {
+      const children = regionElements(node);
+      const contents = regionElements(node, true);
+      const tables = contents.filter(child => isOwner(child.owner, 'features/table', ['DataTable']));
+      for (const child of contents) if (isOwner(child.owner, 'features/filters', ['FilterLayout']) && tables.some(table => table.scope === child.scope && (!child.subject || table.subject === child.subject))) add(child.node, 'detached-filter-layout', 'warning', 'Pass FilterLayout into DataTable topbarContent with variant="compact", or use DataView so filters and table chrome share one surface.');
+      const hasAsideSlot = properties(props.get('slots'), false).some(([name]) => name === 'aside');
+      const onlyForms = children.length > 0 && children.every(child => child.tag === 'form' || isOwner(child.owner, 'base/forms', ['FormSection']));
+      if (onlyForms && !unknownProps && !['narrow', 'maxWidth', 'aside'].some(name => props.has(name)) && !hasAsideSlot) add(node, 'wide-single-column-form', 'warning', 'A single-column form should use Page narrow (48rem centered), an explicit maxWidth, or a supporting aside so fields do not stretch across the default route measure.');
+    }
     if (owner.symbol === 'Page' && literal(props.get('gutter')) === 'none' && !parents.some(parent => parent.framed)) add(node, 'page-gutter', 'warning', 'Page gutter="none" delegates inline padding to a real parent. PageViewport owns scrolling, not padding; verify the parent inset.');
     if (owner.symbol === 'Card' && framed && literal(props.get('padding')) === 'sm' && !parents.some(parent => parent.framed)) add(node, 'compact-card', 'warning', 'Standalone Card padding="sm" halves the normal inset. Omit padding for ordinary subjects; retain sm only for an intentional compact composition.');
     const peers = parents.findLast(parent => parent.structure);
@@ -432,7 +468,7 @@ export function analyzeComposition(text, { filename, index, ts }) {
     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.`);
     const structure = owner.import === `${index.package}/base/structure` && Object.hasOwn(structureDefaults, owner.symbol);
-    return { framed, title, structure, cards: structure ? peerCards(node) : new Set(), smallGap: structure ? smallGap(props, owner.symbol, unknownProps) : false };
+    return { owner, props, unknownProps, framed, title, structure, cards: structure ? peerCards(node) : new Set(), smallGap: structure ? smallGap(props, owner.symbol, unknownProps) : false };
   }
   visit(source);
   return { findings, unresolved };

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

@@ -4,7 +4,7 @@ const name = value => typeof value === 'string' && /^[A-Za-z][A-Za-z0-9]*$/.test
 const uniqueList = (value, valid, maximum) => Array.isArray(value) && value.length <= maximum && value.every(valid) && new Set(value).size === value.length;
 const scalar = value => value === null || typeof value === 'boolean' || (typeof value === 'string' && value.length <= 500) || (typeof value === 'number' && Number.isFinite(value));
 const kinds = ['shell', 'page', 'layout', 'surface', 'content', 'workflow'];
-const placements = ['region', 'cell', 'overlay'];
+const placements = ['region', 'toolbar', 'cell', 'overlay'];
 const surfaces = ['none', 'parent', 'self', 'variant'];
 
 /** One literal metadata shape shared by authored catalogue and copied tools. */

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

@@ -8,6 +8,19 @@ const unique = values => [...new Set(values)].sort(compare);
 const patterns = ['record-detail', 'collection', 'edit', 'analytics', 'embedded'];
 const roleKey = value => value.trim().toLowerCase().replace(/\s+/g, '-');
 const identity = mapping => `${mapping.import}#${mapping.symbol}`;
+const stopWords = new Set(['and', 'for', 'the', 'with', 'from', 'into', 'show', 'list', 'page']);
+const roleTokens = value => value.toLowerCase().split(/[^a-z0-9]+/).filter(token => token.length > 2 && !stopWords.has(token)).map(token => token.length > 3 && token.endsWith('s') ? token.slice(0, -1) : token);
+
+/** Nearby mapped roles for a phrase that matched none. Hints only: the need stays unresolved. */
+function suggestRoles(mappings, request, limit = 5) {
+ if (/^[A-Z][A-Za-z0-9]*$/.test(request) || /[\/#]/.test(request)) return [];
+ const wanted = new Set(roleTokens(request));
+ return unique(mappings.flatMap(mapping => mapping.roles))
+  .map(role => ({role, shared: roleTokens(role).filter(token => wanted.has(token)).length}))
+  .filter(candidate => candidate.shared > 0)
+  .sort((a, b) => b.shared - a.shared || a.role.length - b.role.length || compare(a.role, b.role))
+  .slice(0, limit).map(candidate => candidate.role);
+}
 
 function publicProps(contract, contracts) {
  const inherited = contracts.nativeProfiles[contract.inheritedProfile] ?? {};
@@ -107,8 +120,10 @@ export function mapComposition(index, contracts, rawOptions) {
  }
  if (options.role !== undefined) {
   const found = matches(options.role);
+  const suggestions = found.length ? [] : suggestRoles(mappings, options.role);
   return {...base, mode: 'lookup', status: found.length ? 'mapped' : 'unresolved', query: options.role, total: found.length,
-   results: found.slice(0, options.limit).map(candidate), omittedResults: Math.max(0, found.length - options.limit)};
+   results: found.slice(0, options.limit).map(candidate), omittedResults: Math.max(0, found.length - options.limit),
+   ...(suggestions.length ? {suggestedRoles: suggestions} : {})};
  }
 
  const unresolved = [], warnings = [], selected = [];
@@ -117,9 +132,14 @@ export function mapComposition(index, contracts, rawOptions) {
   return {import: mapping.import, symbol: mapping.symbol, kind: mapping.kind, surface: mapping.surface,
    surfaceDecision: decision, props: {...mapping.props}, slots: {}};
  };
- const issue = (request, region, reason, found = []) => unresolved.push({request, region, reason, totalCandidates: found.length, candidates: found.slice(0, options.limit).map(candidate)});
+ const issue = (request, region, reason, found = [], suggest = false) => {
+  // Only a phrase that matched no role gets hints; structural failures of a
+  // mapped role already name their candidates.
+  const suggestions = suggest ? suggestRoles(mappings, request) : [];
+  unresolved.push({request, region, reason, totalCandidates: found.length, candidates: found.slice(0, options.limit).map(candidate), ...(suggestions.length ? {suggestedRoles: suggestions} : {})});
+ };
  const resolve = (request, region, found = matches(request)) => {
-  if (found.length !== 1) { issue(request, region, found.length ? 'Role is ambiguous; select an exact import#symbol or a more specific mapped role.' : 'No exact mapping covers this requirement. Use --roles or the component finder; do not infer an API.', found); return null; }
+  if (found.length !== 1) { issue(request, region, found.length ? 'Role is ambiguous; select an exact import#symbol or a more specific mapped role.' : 'No exact mapping covers this requirement. Retry with one of suggestedRoles when it names the same job, or use --roles or the component finder; do not infer an API.', found, !found.length); return null; }
   return found[0];
  };
  const insertion = (mapping, slot, request, region) => {
@@ -148,9 +168,15 @@ export function mapComposition(index, contracts, rawOptions) {
   } else warnings.push({code: 'host-ownership-unverified', message: 'Embedded requirements retain the caller\'s host. Confirm its insertion slot, framing, padding and gaps; no Page or new surface was added.'});
  } else {
   rootMapping = structure('route', 'page', ['children']);
-  if (rootMapping) root = host = node(rootMapping);
+  if (rootMapping) {
+   root = host = node(rootMapping);
+   if (!options.aside.length && ['edit', 'record-detail'].includes(options.pattern)) {
+    const contract = contracts.contracts.find(contract => identity(contract) === identity(rootMapping));
+    if (publicProps(contract, contracts).narrow) root.props.narrow = true;
+   }
+  }
   mainSlot = 'children';
-  if (rootMapping && options.aside.length) {
+  if (rootMapping && options.aside.length && !(rootMapping.slots ?? []).includes('aside')) {
    const layout = structure('main-support-layout', 'layout', ['main', 'aside']);
    if (layout && insertion(rootMapping, 'children', 'main-support-layout', 'structure')) {
     host = node(layout); root.slots.children = [host]; rootMapping = layout; mainSlot = 'main';
@@ -160,9 +186,11 @@ export function mapComposition(index, contracts, rawOptions) {
 
  let resolved = 0;
  const regions = {main: [], aside: []};
+ const toolbars = [], placements = [], contextualized = new Set();
  for (const region of ['main', 'aside']) for (const request of options[region]) {
   const mapping = resolve(request, region);
   if (!mapping) continue;
+  if (mapping.placement === 'toolbar') { toolbars.push({mapping, request, region}); continue; }
   if (mapping.placement !== 'region') { issue(request, region, mapping.placement === 'cell' ? 'This owner belongs in a table/collection renderer, not directly in a subject region.' : 'This owner belongs at the app/feature overlay boundary; open it through callbacks.', [mapping]); continue; }
   const slot = region === 'main' ? mainSlot : asideSlot;
   if (['page', 'shell'].includes(mapping.kind) && !(options.pattern === 'embedded' && rootMapping?.routeSlot === slot && mapping.kind === 'page')) { issue(request, region, 'A page or shell is not an independent content subject. Only an explicit route-host slot may receive a Page; keep one route title/gutter owner.', [mapping]); continue; }
@@ -182,10 +210,38 @@ export function mapComposition(index, contracts, rawOptions) {
   if (mapping.surface === 'parent' && options.pattern === 'embedded' && host && !insideSurface) warnings.push({code: 'host-surface-unverified', request, region, message: 'The explicit host does not establish a known surface boundary. Confirm its ancestors before adding framing; no extra Card was added.'});
   if (insideSurface && mapping.surface === 'self') warnings.push({code: 'nested-surface-review', request, region, message: `${mapping.symbol} already owns a surface. Review its supported embedded variant or use an unframed host; no props were guessed.`});
   else if (rootMapping?.surface === 'variant' && mapping.surface === 'self') warnings.push({code: 'nested-surface-review', request, region, message: `${mapping.symbol} owns a surface and its host may also frame it. Inspect both variants before keeping nested surfaces; no embedded props were guessed.`});
+  placements.push({mapping, child, region, slot});
   regions[region].push(child);
   if (host) (host.slots[slot] ??= []).push(child);
   resolved++;
  }
+ // Toolbars are placed after subjects so request order cannot affect the tree.
+ // FilterLayout's context and the table seam are both authored, validated APIs.
+ for (const {mapping, request, region} of toolbars) {
+  const targets = placements.filter(item => item.region === region && item.mapping.roles.includes('comparison-table') && (item.mapping.slots ?? []).includes('topbarContent'));
+  if (targets.length !== 1) { issue(request, region, 'A toolbar needs exactly one mapped comparison table with a topbarContent slot in this region.', targets.map(item => item.mapping)); continue; }
+  const target = targets[0];
+  let provider;
+  if (mapping.symbol === 'FilterLayout') {
+   const contexts = mappings.filter(row => row.import === mapping.import && row.symbol === 'FilterProvider' && row.roles.includes('filter-context'));
+   if (contexts.length !== 1 || contexts[0].kind !== 'layout' || contexts[0].placement !== 'region' || !(contexts[0].slots ?? []).includes('children')) {
+    issue(request, region, 'FilterLayout needs its mapped FilterProvider context with a children insertion contract.', contexts); continue;
+   }
+   provider = contexts[0];
+  }
+  const toolbar = node(mapping, 'uses-parent');
+  (target.child.slots.topbarContent ??= []).push(toolbar);
+  if (provider && !contextualized.has(target.child)) {
+   contextualized.add(target.child);
+   const wrapped = node(provider, 'context-provider');
+   wrapped.slots.children = [target.child];
+   const replace = children => { const position = children.indexOf(target.child); if (position >= 0) children[position] = wrapped; };
+   replace(regions[region]);
+   if (host) replace(host.slots[target.slot] ?? []);
+   // Keep subsequent toolbar insertion addressed to the table, not its context.
+  }
+  resolved++;
+ }
  const requested = options.main.length + options.aside.length;
  const selectedMappings = [...new Map(selected.map(mapping => [identity(mapping), mapping])).values()];
  if (options.pattern === 'edit') warnings.push({code: 'native-form-required', message: 'Provide the application-owned native form, validation and awaited submit/save/discard lifecycle. This structural plan does not create form state or transport.'});

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

@@ -160,8 +160,62 @@ function rankComponents(index, { query, layer = null, limit = 5 }, partial = fal
   return { package: index.package, version: index.version, query, layer, limit, total: ranked.length, results: ranked.slice(0, limit) };
 }
 
+const singularPlural = segment => segment.endsWith('ies') ? [segment.slice(0, -3) + 'y'] : segment.endsWith('s') ? [segment.slice(0, -1)] : [segment + 's', ...(segment.endsWith('y') ? [segment.slice(0, -1) + 'ies'] : [])];
+
+// An unpublished import path resolves only through deterministic evidence: the
+// missing package prefix, a catalogue path alias, the family's singular/plural
+// spelling, or a trailing segment that names one exported component. Anything
+// else keeps the precise empty result instead of a guessed owner.
+export function resolveImport(index, query) {
+  const requested = query.trim();
+  if (!/^[\w@.-]+(?:\/[\w.-]+)+$/.test(requested) || index.families.some(family => family.import === requested)) return null;
+  const path = requested.startsWith(`${index.package}/`) ? requested.slice(index.package.length + 1) : requested;
+  const byPath = new Map(index.families.map(family => [family.import === index.package ? '' : family.import.slice(index.package.length + 1), family]));
+  const segments = path.split('/');
+  const key = symbolKey(segments.at(-1));
+  const named = family => family.symbols.find(symbol => /^[A-Z]/.test(symbol) && symbolKey(symbol) === key && !Object.hasOwn(family.deprecated ?? {}, symbol));
+  const only = (families, reason, symbol) => families.length === 1 ? { requested, import: families[0].import, reason, ...(symbol ? { symbol } : {}) } : null;
+  if (byPath.has(path)) return only([byPath.get(path)], 'Public imports include the package name.');
+  const aliased = index.families.filter(family => family.aliases.includes(path));
+  if (aliased.length) {
+    // A route alias ("blocks/commerce/invoice-table") names its documented owner.
+    const routeSymbols = aliased.length === 1 ? [...new Set(aliased[0].guidance.filter(guide => guide.aliases.includes(path)).flatMap(guide => guideSymbols(guide, aliased[0])))] : [];
+    return only(aliased, 'Catalogue path alias for this family.', aliased.length === 1 ? named(aliased[0]) ?? (routeSymbols.length === 1 ? routeSymbols[0] : undefined) : undefined);
+  }
+  const parent = segments.slice(0, -1).join('/');
+  const spelled = singularPlural(segments.at(-1)).map(segment => byPath.get([...segments.slice(0, -1), segment].join('/'))).filter(Boolean);
+  if (spelled.length) return only(spelled, 'Family names keep their published singular or plural spelling.', spelled.length === 1 ? named(spelled[0]) : undefined);
+  // "blocks/commerce/order-header" names OrderHeader in blocks/commerce;
+  // "features/data-table" names DataTable, exported by one features family.
+  // An aggregate such as `layout` re-exports its sub-families, so the most
+  // specific exporting family answers, then the one that documents the
+  // component. Several equal owners keep ordinary search instead of a guess.
+  const within = prefix => index.families.filter(family => family.import === `${index.package}/${prefix}` || family.import.startsWith(`${index.package}/${prefix}/`)).filter(named);
+  const exporting = byPath.has(parent) && within(parent).length ? within(parent) : within(segments[0]);
+  const owners = exporting.filter(family => !exporting.some(other => other !== family && other.import.startsWith(`${family.import}/`)));
+  const documented = owners.filter(family => family.guidance.some(guide => guideSymbols(guide, family).includes(named(family))));
+  const chosen = owners.length === 1 ? owners : documented.length === 1 ? documented : [];
+  if (chosen.length) return only(chosen, 'The trailing path segment names a component exported by this family.', named(chosen[0]));
+  // A deprecated re-export ("blocks/data-display/metadata-value") points to
+  // the one family that owns the current export, whatever its layer.
+  const parentFamily = byPath.get(parent);
+  const retired = parentFamily?.symbols.find(symbol => symbolKey(symbol) === key && Object.hasOwn(parentFamily.deprecated ?? {}, symbol));
+  if (!retired) return null;
+  const current = index.families.filter(family => family.import !== index.package && named(family) === retired);
+  const currentOwners = current.filter(family => !current.some(other => other !== family && other.import.startsWith(`${family.import}/`)));
+  return only(currentOwners, `${retired} is deprecated in ${parentFamily.import}; this family owns the current export.`, retired);
+}
+
 export function findComponents(index, options) {
   validateIndex(index);
+  const resolution = resolveImport(index, options.query);
+  if (resolution) {
+    // Answer with the canonical owner, keeping the request visible.
+    // Rank every owner before bounding the output, so `limit` cannot drop it.
+    const canonical = rankComponents(index, { ...options, query: resolution.symbol ?? resolution.import, limit: 100 });
+    const results = canonical.results.filter(result => result.import === resolution.import);
+    if (results.length) return { ...canonical, query: options.query, limit: options.limit ?? 5, total: results.length, results: results.slice(0, options.limit ?? 5), importResolution: resolution };
+  }
   const result = rankComponents(index, options);
   // Only natural-language requests recover automatically. API-like names and
   // explicit paths keep precise failure semantics rather than guessed owners.

package/docs/consumer-skill/scripts/inspect-component.mjs

@@ -6,6 +6,6 @@ try {
  const result = inspectComponent(read('component-contracts.json'), parseComponentArguments(process.argv.slice(2)), read('public-api.json'));
  process.stdout.write(JSON.stringify(result, null, 2) + '\n');
 } catch (error) {
- process.stderr.write(`inspect-component: ${error.message}\nUsage: node inspect-component.mjs <ExactSymbol> [--import exact-public-import] [--prop exact-name] [--limit 1..100]\n`);
+ process.stderr.write(`inspect-component: ${error.message}\nUsage: node inspect-component.mjs <ExactSymbol> [--import exact-public-import] [--prop name[,name]]... [--limit 1..100]\n`);
  process.exitCode = 1;
 }

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

@@ -5,7 +5,7 @@ const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
 const boundedText = (value, limit) => ({text: value.slice(0, limit), complete: value.length <= limit, omittedCharacters: Math.max(0, value.length - limit)});
 
 function parse(args, token = false) {
- const options = token ? {query: '', limit: 12} : {symbol: '', publicImport: null, prop: null, limit: 12};
+ const options = token ? {query: '', limit: 12} : {symbol: '', publicImport: null, props: [], limit: 12};
  const seen = new Set();
  const allowed = token ? ['--limit'] : ['--import', '--prop', '--limit'];
  for (let index = 0; index < args.length; index++) {
@@ -17,15 +17,21 @@ function parse(args, token = false) {
    options[key] = arg;
    continue;
   }
-  requireFormat(!seen.has(arg), `Duplicate argument: ${arg}`); seen.add(arg);
+  // Several props may be read at once: repeat --prop or separate names with commas.
+  requireFormat(arg === '--prop' || !seen.has(arg), `Duplicate argument: ${arg}`); seen.add(arg);
   const value = args[++index];
   requireFormat(text(value) && !value.startsWith('--'), `Missing value for ${arg}`);
   if (arg === '--limit') {
    requireFormat(/^[1-9]\d*$/.test(value) && Number(value) <= 100, 'Invalid limit: use 1..100'); options.limit = Number(value);
-  } else options[arg === '--import' ? 'publicImport' : 'prop'] = value;
+  } else if (arg === '--prop') {
+   const names = value.split(',').map(name => name.trim());
+   requireFormat(names.every(text), `Missing value for ${arg}`);
+   for (const name of names) if (!options.props.includes(name)) options.props.push(name);
+  } else options.publicImport = value;
  }
  requireFormat(text(options[token ? 'query' : 'symbol']), `A nonempty ${token ? 'token query' : 'exact symbol'} is required`);
- return options;
+ // `prop` keeps the single-prop field earlier programmatic callers read.
+ return token ? options : {symbol: options.symbol, publicImport: options.publicImport, prop: options.props[0] ?? null, props: options.props, limit: options.limit};
 }
 export const parseComponentArguments = args => parse(args);
 export const parseTokenArguments = args => parse(args, true);
@@ -82,29 +88,78 @@ function displayGuidance(guide) {
  const list = value => (Array.isArray(value) ? value : []).slice(0, 3).map(value => boundedText(value, 600));
  const composition = guide.composition;
  return {title: boundedText(guide.title ?? '', 150), chooseWhen: list(guide.chooseWhen), avoidWhen: list(guide.avoidWhen),
+  alternatives: list(guide.alternatives), omittedAlternatives: Math.max(0, (guide.alternatives?.length ?? 0) - 3),
   ...(composition ? {composition: {owns: list(composition.owns), parentOwns: list(composition.parentOwns),
    ...(composition.page ? {page: boundedText(composition.page, 600)} : {}),
    ...(composition.embedded ? {embedded: boundedText(composition.embedded, 600)} : {})}} : {})};
 }
 
 /** Exact API inspection is deliberately separate from task/intent discovery. */
-export function inspectComponent(index, {symbol, publicImport = null, prop = null, limit = 12}, publicIndex) {
+export function inspectComponent(index, {symbol, publicImport = null, prop = null, props = [], limit = 12}, publicIndex) {
  validateComponentContracts(index, publicIndex);
  requireFormat(text(symbol) && Number.isInteger(limit) && limit >= 1 && limit <= 100, 'Use an exact symbol and limit 1..100');
- const matches = index.contracts.filter(contract => contract.symbol === symbol && (!publicImport || contract.import === publicImport));
- requireFormat(matches.length > 0, `No contract for ${symbol}${publicImport ? ` from ${publicImport}` : ''}; use the finder and read the matching published declaration. Coverage: ${index.coverage ?? 'published uppercase callable exports'}`);
- requireFormat(matches.length === 1, `Ambiguous symbol ${symbol}; qualify with --import: ${matches.map(contract => contract.import).join(', ')}`);
+ const requestedProps = [...new Set([...(prop ? [prop] : []), ...props])];
+ const owners = index.contracts.filter(contract => contract.symbol === symbol);
+ // Hooks, helpers and types are public too, but have no component contract:
+ // name the declaration that holds their signature instead of a generic miss.
+ const exporters = owners.length ? [] : (publicIndex?.families ?? []).filter(family => family.symbols.includes(symbol) && (!publicImport || family.import === publicImport));
+ requireFormat(!exporters.length, `${symbol} is a public ${/^use[A-Z]/.test(symbol) ? 'hook' : 'export'} without a component contract. Read its signature in ${exporters.slice(0, 3).map(family => `${family.declaration} (import from ${family.import})`).join('; ')}${exporters.length > 3 ? `; ${exporters.length - 3} more` : ''}.`);
+ const matches = owners.filter(contract => !publicImport || contract.import === publicImport);
+ // An exact symbol can recover from a guessed path without fuzzy matching or
+ // silently selecting another owner. Bound both recovery and ambiguity output.
+ const imports = owners.map(contract => contract.import).sort(compare);
+ const ownerChoices = `${imports.slice(0, 3).join(', ')}. Omitted imports: ${Math.max(0, imports.length - 3)}.`;
+ requireFormat(matches.length > 0, `No contract for ${symbol}${publicImport ? ` from ${publicImport}` : ''}; ${owners.length ? `Available imports (--import): ${ownerChoices} ` : ''}Use the finder and read the matching published declaration. Coverage: ${index.coverage ?? 'published uppercase callable exports'}`);
+ requireFormat(matches.length === 1, `Ambiguous symbol ${symbol}; qualify with --import: ${ownerChoices}`);
  const contract = matches[0];
  const local = Object.values(contract.props);
  const inherited = contract.inheritedProfile ? Object.fromEntries(Object.entries(index.nativeProfiles[contract.inheritedProfile]).map(([name, reference]) => [name, typeof reference === 'string' ? index.nativeProperties[reference] : reference])) : {};
- const priority = value => Number(value.required) * 100 + Number(/^(?:value|defaultValue|checked|defaultChecked|open|defaultOpen|on[A-Z])/.test(value.name)) * 10;
- local.sort((a, b) => priority(b) - priority(a) || compare(a.name, b.name));
+ // Anatomy is the first decision when composing; callbacks remain exactly
+ // inspectable without displacing every insertion seam in a large API.
+ const anatomy = ['title', 'description', 'header', 'aside', 'toolbar', 'tabs', 'items', 'fields', 'filters', 'activeFilters', 'primaryAction', 'secondaryActions', 'topbarContent', 'topbarEnd', 'rowActions', 'pagination', 'footer', 'footerSlot', 'titleSuffix', 'headerAction', 'surface', 'padding', 'narrow', 'maxWidth', 'loading', 'error', 'empty', 'slots'];
+ const ownerAnatomy = {
+  Page: ['header', 'aside', 'toolbar', 'narrow', 'maxWidth', 'loading', 'error', 'empty', 'onRetry', 'slots', 'beforeHeader', 'afterHeader'],
+  Card: ['title', 'description', 'titleSuffix', 'headerAction', 'footerSlot', 'surface', 'padding', 'children', 'contentGap', 'headerPlacement', 'actions', 'slots'],
+  DataTable: ['columns', 'data', 'topbarContent', 'topbarEnd', 'rowActions', 'pagination', 'surface', 'emptyStateMessage', 'emptyStateAction', 'bulkActions', 'loading', 'getRowId'],
+  ActionDialog: ['title', 'description', 'children', 'formId', 'loading', 'strings', 'open', 'onOpenChange', 'onAsyncConfirm', 'alertMessage', 'initialFocusRef', 'footer'],
+  ActionDrawer: ['title', 'description', 'children', 'formId', 'loading', 'strings', 'open', 'onOpenChange', 'onAsyncConfirm', 'alertMessage', 'initialFocusRef', 'footer'],
+  ProductVariantsManager: ['optionGroups', 'variants', 'editingOptionId', 'defaultEditingOptionId', 'onEditingOptionIdChange', 'onSaveEditingOption', 'onCancelEditingOption', 'onError', 'renderValue', 'visibleColumns', 'selectionMode', 'onSelectVariant'],
+  MediaResourceGallery: ['items', 'accessors', 'primaryId', 'onPrimaryChange', 'onReorder', 'onRemove', 'onAdd', 'readOnly', 'renderItem', 'layout', 'density', 'maxItems'],
+  ProductOptionsMatrix: ['optionGroups', 'editingOptionId', 'defaultEditingOptionId', 'onEditingOptionIdChange', 'onSaveEditingOption', 'onCancelEditingOption', 'onError', 'renderValue', 'renderOptionActions', 'collapsedOptionIds', 'onCollapsedOptionIdsChange', 'onAddValue'],
+  ProductVariantEditor: ['value', 'defaultValue', 'onValueChange', 'optionFields', 'statusOptions', 'visibleFields', 'children', 'onSubmit', 'submitting', 'disabled', 'onError', 'onCancel', 'footerSlot', 'strings'],
+  ProductVariantDetails: ['variant', 'metadata', 'media', 'optionItems', 'renderMetadata', 'renderOption', 'renderActions', 'onEditVariant', 'onSelectVariant', 'onBack', 'footerSlot', 'empty'],
+ }[symbol] ?? [];
+ // Upstream control contracts share inherited profiles with HTML attributes.
+ // Keep cross-family state, mounting and render seams discoverable without
+ // treating every native DOM event as component anatomy.
+ const behavior = new Set(['children', 'render', 'value', 'defaultValue', 'checked', 'defaultChecked', 'open', 'defaultOpen', 'expanded', 'defaultExpanded', 'pressed', 'defaultPressed', 'onChange', 'onValueChange', 'onCheckedChange', 'onOpenChange', 'onExpandedChange', 'onPressedChange', 'multiple', 'keepMounted', 'hiddenUntilFound', 'disabled', 'orientation', 'loopFocus', 'modal']);
+ const hasProp = name => Object.hasOwn(contract.props, name) || Object.hasOwn(inherited, name);
+ const inheritedBehavior = value => behavior.has(value.name)
+  // React's HTMLAttributes includes these defaults even on div-like surfaces.
+  && (value.name !== 'defaultValue' || hasProp('value'))
+  && (value.name !== 'defaultChecked' || hasProp('checked'))
+  && (value.name !== 'onChange' || hasProp('value') || hasProp('checked'));
+ const priority = value => {
+  if (/(?:^className$|ClassName$|^style$|^(?:BottomSlot|TopSlot)$)/.test(value.name) || value.deprecated || /@deprecated|^Deprecated[.: ]/i.test(value.description)) return -100;
+  const position = ownerAnatomy.indexOf(value.name);
+  return Number(value.required) * 1000 + (position >= 0 ? 300 - position : anatomy.includes(value.name) ? 100 : /^(?:value|defaultValue|checked|defaultChecked|open|defaultOpen)$/.test(value.name) ? 50 : behavior.has(value.name) ? 40 : /^on[A-Z]/.test(value.name) ? 20 : 0);
+ };
+ const compareProps = (a, b) => priority(b) - priority(a) || compare(a.name, b.name);
+ local.sort(compareProps);
+ const inheritedValues = Object.values(inherited).sort((a, b) => Number(inheritedBehavior(b)) - Number(inheritedBehavior(a)) || compareProps(a, b));
  let selected;
- if (prop) {
-  const value = contract.props[prop] ?? inherited[prop];
-  requireFormat(value, `Unknown prop ${prop} on ${symbol} from ${contract.import}; inspect its declaration or omit --prop for the bounded prop index`);
-  selected = [displayProp(value, Object.hasOwn(contract.props, prop) ? 'local' : 'inherited')];
- } else selected = local.slice(0, limit).map(value => displayProp(value, 'local'));
+ if (requestedProps.length) {
+  const unknown = requestedProps.filter(name => !(contract.props[name] ?? inherited[name]));
+  requireFormat(!unknown.length, `Unknown prop ${unknown.join(', ')} on ${symbol} from ${contract.import}; inspect its declaration or omit --prop for the bounded prop index`);
+  selected = requestedProps.map(name => displayProp(contract.props[name] ?? inherited[name], Object.hasOwn(contract.props, name) ? 'local' : 'inherited'));
+ } else {
+  const candidates = [
+   ...local.map(value => ({value, origin: 'local'})),
+   ...inheritedValues.filter(value => inheritedBehavior(value) && priority(value) >= 0 && !Object.hasOwn(contract.props, value.name)).map(value => ({value, origin: 'inherited'})),
+  ];
+  candidates.sort((a, b) => compareProps(a.value, b.value));
+  selected = candidates.slice(0, limit).map(({value, origin}) => displayProp(value, origin));
+ }
  const description = boundedText(contract.description ?? '', 1000);
  return {package: index.package, version: index.version, import: contract.import, symbol: contract.symbol, declaration: contract.declaration,
   ...(contract.optionalPeers ? {optionalPeers: contract.optionalPeers} : {}),
@@ -114,9 +169,9 @@ export function inspectComponent(index, {symbol, publicImport = null, prop = nul
   omissions: {localProps: local.length - selected.filter(value => value.origin === 'local').length,
    inheritedProps: Object.keys(inherited).length - selected.filter(value => value.origin === 'inherited').length,
    callSignatures: Math.max(0, contract.callSignatures.length - 4)},
-  propNames: {local: local.map(value => value.name).slice(0, 100), omittedLocalNames: Math.max(0, local.length - 100), inherited: Object.keys(inherited).slice(0, 20), omittedInheritedNames: Math.max(0, Object.keys(inherited).length - 20)},
+  propNames: {local: local.map(value => value.name).slice(0, 100), omittedLocalNames: Math.max(0, local.length - 100), inherited: inheritedValues.slice(0, 20).map(value => value.name), omittedInheritedNames: Math.max(0, inheritedValues.length - 20)},
   ...(contract.guidance?.length ? {guidance: contract.guidance.slice(0, 1).map(displayGuidance), omittedGuidance: Math.max(0, contract.guidance.length - 1)} : {}),
-  next: 'Use --prop <exact-name> for one local or inherited contract. Read declaration for full types, omitted overloads or truncated fields. Defaults marked unknown are not inferred.'};
+  next: 'Use --prop <exact-name> (repeat it, or separate names with commas) for local or inherited contracts. Read declaration for full types, omitted overloads or truncated fields. Defaults marked unknown are not inferred.'};
 }
 
 export function inspectTokens(index, {query, limit = 12}, publicIndex) {
@@ -129,7 +184,7 @@ export function inspectTokens(index, {query, limit = 12}, publicIndex) {
   ...index.structural.map(root => ({...root, default: {status: 'recorded', value: root.default}, kind: 'structural-root', overrideRoot: true})),
   {...index.radius, default: {status: 'recorded', value: index.radius.default}, kind: 'radius-root', overrideRoot: true},
   ...index.advanced.map(name => ({name, kind: 'advanced-root', overrideRoot: true, default: {status: 'not-recorded'}})),
-  ...[...new Set(Object.values(index.utilities).flat())].map(name => ({name, kind: 'derived-utility', overrideRoot: false, default: {status: 'not-applicable'}, ...(name === index.radius.innerUtility ? {formula: index.radius.innerFormula} : {})})),
+  ...[...new Set(Object.values(index.utilities).flat())].map(name => ({name, kind: 'derived-utility', overrideRoot: false, default: {status: 'not-applicable'}, ...(name === index.radius.surfaceUtility ? {formula: index.radius.surfaceFormula} : {})})),
  ];
  const matches = values.filter(value => terms.every(term => words([value.name, value.purpose ?? ''].join(' ')).some(word => word === term))).sort((a, b) => Number(b.name === query) - Number(a.name === query) || Number(b.overrideRoot) - Number(a.overrideRoot) || compare(a.name, b.name));
  return {package: index.package, version: index.version, query, total: matches.length, results: matches.slice(0, limit), omitted: Math.max(0, matches.length - limit),

package/docs/consumer-skill/scripts/setup-skills.mjs

@@ -3,10 +3,11 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-export const focusedSkills = ['themelia-components', 'themelia-tokenization', 'themelia-composition'];
+export const focusedSkills = ['themelia-components', 'themelia-tokenization', 'themelia-composition', 'themelia-design'];
 export const sharedSkillName = 'themelia-react-ui-consumer';
+export const agentFiles = ['themelia-ui-designer.md'];
 
-/** One metadata/example copy, three small discoverable entrypoints, and real templates. */
+/** One metadata/example copy, four small discoverable entrypoints, and real templates. */
 export function consumerBundleFiles(packageRoot, destination) {
   const mappings = [
     ['docs/consumer-skill', sharedSkillName],
@@ -65,12 +66,46 @@ export function copyConsumerBundle({ packageRoot, destination }) {
   return checkCopiedConsumerBundle({ packageRoot, destination });
 }
 
+/** Agent definitions are single files copied into an agents directory, such as `.claude/agents`. */
+function agentBundleFiles(packageRoot, destination) {
+  return agentFiles.map(name => {
+    const source = path.resolve(packageRoot, 'docs/consumer-skill/agents', name);
+    return { source, target: path.resolve(destination, name), content: fs.readFileSync(source) };
+  });
+}
+
+export function checkCopiedAgents({ packageRoot, destination }) {
+  const files = agentBundleFiles(packageRoot, destination);
+  for (const { target, content } of files) {
+    assert(fs.existsSync(target) && !fs.lstatSync(target).isSymbolicLink(), `Copied agent is stale: missing or linked ${target}`);
+    assert(content.equals(fs.readFileSync(target)), `Copied agent is stale: copy it again (${target})`);
+  }
+  return { agents: files.map(file => path.basename(file.target, '.md')) };
+}
+
+export function copyAgents({ packageRoot, destination }) {
+  const files = agentBundleFiles(packageRoot, destination);
+  for (const { target } of files) assert(!fs.existsSync(target), `Destination exists: ${path.basename(target)}. Preserve or move the previous agent before copying.`);
+  fs.mkdirSync(destination, { recursive: true });
+  for (const { target, content } of files) fs.writeFileSync(target, content);
+  return checkCopiedAgents({ packageRoot, destination });
+}
+
 if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
   try {
-    const args = process.argv.slice(2);
-    assert(args.length === 3 && ['--copy', '--check'].includes(args[0]) && args[1] === '--destination' && args[2], 'Usage: node setup-skills.mjs --copy|--check --destination <agent-skills-directory>');
+    const usage = 'Usage: node setup-skills.mjs --copy|--check [--destination <agent-skills-directory>] [--agents <agent-definitions-directory>]';
+    const [mode, ...rest] = process.argv.slice(2);
+    const options = {};
+    for (let index = 0; index < rest.length; index += 2) {
+      assert(['--destination', '--agents'].includes(rest[index]) && rest[index + 1] && !(rest[index] in options), usage);
+      options[rest[index]] = path.resolve(rest[index + 1]);
+    }
+    assert(['--copy', '--check'].includes(mode) && Object.keys(options).length, usage);
     const packageRoot = fileURLToPath(new URL('../../..', import.meta.url));
-    const result = (args[0] === '--copy' ? copyConsumerBundle : checkCopiedConsumerBundle)({ packageRoot, destination: path.resolve(args[2]) });
-    console.log(JSON.stringify({ ...result, destination: path.resolve(args[2]) }, null, 2));
+    const copy = mode === '--copy';
+    const result = {};
+    if (options['--destination']) Object.assign(result, (copy ? copyConsumerBundle : checkCopiedConsumerBundle)({ packageRoot, destination: options['--destination'] }), { destination: options['--destination'] });
+    if (options['--agents']) Object.assign(result, (copy ? copyAgents : checkCopiedAgents)({ packageRoot, destination: options['--agents'] }), { agentsDestination: options['--agents'] });
+    console.log(JSON.stringify(result, null, 2));
   } catch (error) { console.error(error.message); process.exitCode = 1; }
 }

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

@@ -31,11 +31,11 @@ export const marginProperty = /^margin(?:Inline|Block)?(?:Start|End)?$|^margin(?
 export const radiusProperty = /^border(?:(?:Top|Bottom)(?:Left|Right)|(?:Start|End)(?:Start|End))?Radius$|^border-(?:(?:top|bottom)-(?:left|right)-|(?:start|end)-(?:start|end)-)?radius$/;
 
 export function cornerRole(family, symbol) {
-  if (family === 'item' && symbol === 'Item' || family === 'navigation' && /^(?:TabsList|TabsTrigger)$/.test(symbol)) return 'inner';
-  return sharedCornerParts[family]?.test(symbol) && /(?:Item|SubTrigger)$/.test(symbol) ? 'inner' : 'radius';
+  if (family === 'item' && symbol === 'Item' || family === 'navigation' && /^(?:TabsList|TabsTrigger)$/.test(symbol)) return 'radius';
+  return sharedCornerParts[family]?.test(symbol) && /(?:Item|SubTrigger)$/.test(symbol) ? 'radius' : 'surface';
 }
 
-export function replacesSharedRadius(token, role = 'radius') {
+export function replacesSharedRadius(token, role = 'surface') {
   const value = utility(token);
   if (new RegExp(`^rounded(?:-[trblse]{1,2})?-(?:${role}|none)$`).test(value)) return false;
   return /^rounded(?:-|$)/.test(value) || /^\[border-(?:(?:top|bottom)-(?:left|right)-|(?:start|end)-(?:start|end)-)?radius:/.test(value);
@@ -159,8 +159,8 @@ export function stateMotionDrift(classes) {
   return resting.filter(token => /^duration-(?!150$|0$)/.test(utility(token)) || /^ease-/.test(utility(token)));
 }
 
-// Corners take a role derived from --radius: rounded-radius (outer shells) and
-// rounded-inner (controls, rows, nested bodies), plus rounded-full, rounded-none
+// Corners take a role derived from --radius: rounded-radius (controls, badges,
+// rows, nested bodies) and rounded-surface (outer shells), plus rounded-full, rounded-none
 // and the root-derived rounded-radius-* steps. Bare rounded is a fixed 4px that
 // ignores the theme root, and the t-shirt steps are a second scale.
 export function radiusRoleDrift(token) {