themelia-react-ui 2.0.4 → 2.0.6

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],
@@ -57,7 +58,7 @@ export function checkCopiedConsumerBundle({ packageRoot, destination }) {
 
 export function copyConsumerBundle({ packageRoot, destination }) {
   const files = consumerBundleFiles(packageRoot, destination);
-  for (const name of [sharedSkillName, ...focusedSkills]) assert(!fs.existsSync(path.join(destination, name)), `Destination exists: ${name}. Preserve or move the previous skill before copying.`);
+  assertSkillDestination(destination);
   for (const { target, content } of files) {
     fs.mkdirSync(path.dirname(target), { recursive: true });
     fs.writeFileSync(target, content);
@@ -65,12 +66,83 @@ export function copyConsumerBundle({ packageRoot, destination }) {
   return checkCopiedConsumerBundle({ packageRoot, destination });
 }
 
+function assertSkillDestination(destination) {
+  assertDirectoryPath(destination);
+  for (const name of [sharedSkillName, ...focusedSkills]) assert(!pathExists(path.join(destination, name)), `Destination exists: ${name}. Preserve or move the previous skill before copying.`);
+}
+
+function pathExists(target) {
+  try { fs.lstatSync(target); return true; }
+  catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+}
+
+function assertDirectoryPath(destination) {
+  let directory = path.resolve(destination);
+  while (!pathExists(directory)) directory = path.dirname(directory);
+  assert(fs.statSync(directory).isDirectory(), `Destination is not a directory: ${directory}`);
+}
+
+/** 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);
+  assertAgentDestination(files);
+  fs.mkdirSync(destination, { recursive: true });
+  for (const { target, content } of files) fs.writeFileSync(target, content);
+  return checkCopiedAgents({ packageRoot, destination });
+}
+
+function assertAgentDestination(files) {
+  for (const { target } of files) {
+    assertDirectoryPath(path.dirname(target));
+    assert(!pathExists(target), `Destination exists: ${path.basename(target)}. Preserve or move the previous agent before copying.`);
+  }
+}
+
 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 <markdown-agent-directory> | --no-agents]';
+    const [mode, ...rest] = process.argv.slice(2);
+    const options = {};
+    for (let index = 0; index < rest.length; index++) {
+      const flag = rest[index];
+      assert(!(flag in options), usage);
+      if (flag === '--no-agents') { options[flag] = true; continue; }
+      assert(['--destination', '--agents'].includes(flag) && rest[index + 1] && !rest[index + 1].startsWith('--'), usage);
+      options[flag] = path.resolve(rest[++index]);
+    }
+    assert(['--copy', '--check'].includes(mode) && (options['--destination'] || options['--agents']) && !(options['--agents'] && options['--no-agents']), 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 destination = options['--destination'];
+    // `.agents/skills` is shared by Codex and Antigravity. It cannot identify
+    // a Markdown-agent host; Codex custom agents have a different TOML format.
+    const claudeSkills = destination && path.basename(destination) === 'skills' && path.basename(path.dirname(destination)) === '.claude';
+    const agentsDestination = options['--agents'] ?? (!options['--no-agents'] && claudeSkills ? path.join(path.dirname(destination), 'agents') : undefined);
+    // Validate every source and destination first: an agent conflict must not
+    // leave a newly copied skill bundle behind after reporting failure.
+    if (copy) {
+      if (destination) { consumerBundleFiles(packageRoot, destination); assertSkillDestination(destination); }
+      if (agentsDestination) assertAgentDestination(agentBundleFiles(packageRoot, agentsDestination));
+    }
+    const result = {};
+    if (destination) Object.assign(result, (copy ? copyConsumerBundle : checkCopiedConsumerBundle)({ packageRoot, destination }), { destination });
+    if (agentsDestination) Object.assign(result, (copy ? copyAgents : checkCopiedAgents)({ packageRoot, destination: agentsDestination }), { agentsDestination });
+    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) {

package/docs/consumer-skills/themelia-components/SKILL.md

@@ -1,30 +1,31 @@
 ---
 name: themelia-components
-description: Discover, inspect and integrate themelia-react-ui controls, value primitives, blocks and complete features in React apps, including typed forms, callbacks and framework adapters; not library internals or visual theme design.
+description: Use when finding or integrating themelia-react-ui components, compound parts, blocks, features or typed forms in React apps; not library maintenance.
 ---
 
 # Themelia components
 
-Use the installed package as the API authority. Resolve its root/version with [installation](../../consumer-skill/references/installation.md); verify a copied bundle before using it. Follow that setup only when CSS, required peers or UIProvider are missing. One shared asset bundle serves all three skills; no global CLI or MCP server is required.
+Installed types own the API. Resolve package/version and copied-skill freshness through [installation](../../consumer-skill/references/installation.md). Set up CSS, peers and UIProvider when missing. Skills share assets.
 
-## Discover and inspect
+## Find and verify
 
-Split a business request into responsibilities: identity/facts, selection, editing, collection, navigation or a complete workflow. Search each separately. When strict results are empty, inspect related suggestions and their unmatched terms; they cover only part of the request. Shorten to a responsibility, try an exact symbol or remove the layer filter as needed. Read [discovery](../../consumer-skill/references/discovery.md) for query behavior and copied paths.
+Split the task into responsibilities: facts, selection, editing, collection, disclosure or navigation. Search each separately. Empty strict results do not establish missing support; inspect related suggestions and unmatched terms, then shorten the query. See [discovery](../../consumer-skill/references/discovery.md).
 
 ```sh
-node node_modules/themelia-react-ui/docs/consumer-skill/scripts/find-components.mjs "record facts" --limit 3
-node node_modules/themelia-react-ui/docs/consumer-skill/scripts/inspect-component.mjs DataTable --import themelia-react-ui/features/table
-node node_modules/themelia-react-ui/docs/consumer-skill/scripts/inspect-component.mjs DataTable --import themelia-react-ui/features/table --prop onRowSelectionChange
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/find-components.mjs "expandable form sections" --limit 3
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/inspect-component.mjs AccordionContent --import themelia-react-ui/base/accordion --prop keepMounted
 ```
 
-Read choose/avoid, ownership, peers and the small reading path. Listed peers cover the whole imported family, including type-only exports. Inspect the exact selected export before wiring it. Qualify ambiguous names: basic `ThemeScope` from `ui-provider` and advanced `features/theme-tweaker` scope differ. Inspector omissions and unresolved named types lead to the installed declaration; they are not permission to guess. Preserve discriminated modes, generic row types and overloads. An undocumented default is unknown. Use the canonical owner rather than a deprecated migration name or unrelated aggregate entrypoint.
+Imports keep each family's published spelling (`base/cards`, `base/buttons`, `base/chart`); a near miss reports `importResolution`. Read choose/avoid, ownership and peers for the exact export. Qualify ambiguous names. Default inspection includes relevant inherited behavior; --prop retrieves exact callbacks/slots, and installed declarations cover omitted types/overloads. Unknown defaults stay unknown. Preserve generic/discriminated contracts and prefer canonical exports over migration names.
 
-## Integrate the contract
+Search task-specific subjects/workflows as well as controls: options, variant editing and attached media have dedicated owners. Before rebuilding, compare their data contract, controlled/default state, mounting, callbacks, refs and render seams. A missing prop on a convenience wrapper can exist on its public parts. A custom badge/retained field does not establish a disclosure gap. See [capability comparison](../../consumer-skill/references/custom-composition.md).
 
-Prefer a complete feature when its state/lifecycle matches the task; otherwise compose public owners into an app-specific component. Check actual value/event types, controlled versus default state, callback timing, native attributes/refs, strings, slots and render composition. Do not rebuild routine menu/listbox/overlay behavior from generic elements or cast mismatched bindings to `any`.
+## Wire the selected owner
 
-For forms read [typed bindings and transport](../../consumer-skill/references/rhf-workflows.md) and the matching [recipe](../../consumer-skill/examples/manifest.json). RHF recipes cover validation, arrays, dirty state and async submission; an existing controller can use supported native/controlled contracts. Checkbox state, input events, dates, selection and arrays differ. Keep drafts on failure, await the complete transport, and accept authoritative saved values before reset. Read [workflows](../../consumer-skill/references/workflows.md) only for the chosen feature.
+- Routes use Page from layout/page for title, responsive commands, lifecycle and gutters. Back navigation and tabs are optional; choose them for an actual journey/section need. Use narrow for one column, aside for context; explicit maxWidth wins. Header actions defaultContent retains command behavior. See [composition](../../consumer-skill/references/composition.md).
+- Server indexes use FilterProvider → DataTable, with FilterLayout in topbarContent. DataTable owns its surface. App query transport retains fixed scope, applies criteria and supplies authoritative rows/pagination. See [scoped directory](../../consumer-skill/examples/scoped-directory.tsx).
+- Forms use typed RHF bindings with ControlledFormField and FormSection. Page forms can use FormActionsBar; overlay forms normally use the overlay's formId/loading/strings footer contract. Await transport, retain failed drafts and reset to accepted values. Inertia needs its onFinish bridge. Read [typed workflows](../../consumer-skill/references/rhf-workflows.md) and [recipes](../../consumer-skill/examples/manifest.json).
 
-The app supplies data, routing, permission and translation. Use [integration](../../consumer-skill/references/integration.md) for framework adapters and client boundaries. Dialogs, drawers and confirmations use `features/overlays`; open them at the app/feature boundary through callbacks. Never invent a framework-specific package API.
+Use a fitting complete feature; otherwise compose public owners. Base controls and blocks already own local interaction/accessibility. Features coordinate a complete workflow. Data, routing, permissions and translations stay app-owned; see [integration](../../consumer-skill/references/integration.md). Dialogs/drawers/confirmations use features/overlays at the app/feature boundary.
 
-Use **themelia-tokenization** for shared visual changes and **themelia-composition** for hierarchy, shells and regions. Finish the component's real loading/empty/error/disabled/async paths and keyboard/focus behavior, then run app checks and [composition review](../../consumer-skill/references/review.md). Report behavior separately from source and inspected appearance.
+Use **themelia-composition** for hierarchy and custom composites, **themelia-tokenization** for theme roles and token-backed app geometry, and **themelia-design** for data-led view specs and rendered critique. Run app checks and [review](../../consumer-skill/references/review.md); execute relevant focus, validation and failure/retry paths. Report source, inspected appearance and executed behavior separately.