themelia-react-ui 2.0.3 → 2.0.5

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

@@ -1,3 +1,5 @@
+import {validateMappings} from './composition-schema.mjs';
+
 export const layers = ['foundations', 'base', 'layout', 'blocks', 'features'];
 const requireFormat = (condition, message) => { if (!condition) throw new Error(`Invalid discovery index: ${message}`); };
 const stringList = value => Array.isArray(value) && value.every(item => typeof item === 'string');
@@ -9,6 +11,16 @@ const searchable = value => words(value).join(' ');
 const containsTerms = (value, terms) => { const tokens = new Set(words(value)); return terms.every(term => tokens.has(term)); };
 const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
 
+/** The same bounded context shape is used by authored routes and portable indexes. */
+export function validateComposition(composition) {
+  requireFormat(composition !== null && typeof composition === 'object' && !Array.isArray(composition), 'invalid composition object');
+  requireFormat(Object.keys(composition).every(field => ['owns', 'parentOwns', 'page', 'embedded', 'mappings'].includes(field)), 'unknown composition field');
+  for (const field of ['owns', 'parentOwns']) requireFormat(stringList(composition[field]) && composition[field].length <= 3 && composition[field].every(text), `invalid composition ${field}; use at most three nonempty responsibilities`);
+  for (const field of ['page', 'embedded']) if (composition[field] !== undefined) requireFormat(text(composition[field]), `invalid composition ${field}`);
+  if (composition.mappings !== undefined) validateMappings(composition.mappings);
+  return composition;
+}
+
 export function validateIndex(index) {
   requireFormat(index?.schemaVersion === 1 && index?.discoveryVersion === 1, 'unsupported schema/format; expected schemaVersion 1 and discoveryVersion 1');
   requireFormat(text(index.package) && text(index.version) && Array.isArray(index.families), 'package, version and families are required');
@@ -40,6 +52,8 @@ export function validateIndex(index) {
       requireFormat(guide.browse.domain === undefined || typeof guide.browse.domain === 'string', 'invalid guidance browse domain');
       for (const field of ['chooseWhen', 'avoidWhen', 'appOwned', 'jobs', 'tags', 'aliases', 'alternatives']) requireFormat(stringList(guide[field]), `invalid guidance ${field}`);
       requireFormat(Array.isArray(guide.sections) && guide.sections.every(section => text(section?.title) && stringList(section.symbols)), 'invalid guidance sections');
+      if (guide.composition !== undefined) validateComposition(guide.composition);
+      for (const mapping of guide.composition?.mappings ?? []) requireFormat(family.symbols.includes(mapping.symbol) && !Object.hasOwn(family.deprecated ?? {}, mapping.symbol), `invalid composition mapping public symbol: ${family.import}#${mapping.symbol}`);
     }
   }
   for (const family of index.families) for (const guide of family.guidance) for (const alternative of guide.alternatives) requireFormat(seen.has(alternative), `unpublished alternative ${alternative}`);
@@ -71,7 +85,9 @@ export function parseArguments(args) {
   return { query, ...options };
 }
 
-const guideText = guide => searchable([guide.title, guide.description, ...Object.values(guide.browse), ...guide.jobs, ...guide.tags, ...guide.aliases, ...guide.chooseWhen, ...guide.appOwned, ...guide.sections.flatMap(section => [section.title, ...section.symbols])].join(' '));
+// Owned capabilities recommend this owner. Parent responsibilities and contextual
+// comparisons can name other owners, so they are returned as guidance only.
+const guideText = guide => searchable([guide.title, guide.description, ...Object.values(guide.browse), ...guide.jobs, ...guide.tags, ...guide.aliases, ...guide.chooseWhen, ...guide.appOwned, ...(guide.composition?.owns ?? []), ...guide.sections.flatMap(section => [section.title, ...section.symbols])].join(' '));
 const guideSymbols = (guide, family) => [...new Set(guide.sections.flatMap(section => section.symbols))].filter(symbol => family.symbols.includes(symbol));
 
 function relevantGuidance(family, needle, terms, matchedSymbols, exactImport) {
@@ -90,10 +106,9 @@ function relevantGuidance(family, needle, terms, matchedSymbols, exactImport) {
   return (selected.length || !exactImport ? selected : ranked).slice(0, 3).map(item => item.guide);
 }
 
-export function findComponents(index, { query, layer = null, limit = 5 }) {
-  validateIndex(index);
+function rankComponents(index, { query, layer = null, limit = 5 }, partial = false) {
   const needle = normalized(query);
-  const terms = [...new Set(words(query))];
+  const queryTerms = [...new Set(words(query))];
   const key = symbolKey(query);
   // Cased API names and explicit imports request a precise contract. Ordinary
   // nouns such as table/empty remain task searches with richer alternatives.
@@ -105,11 +120,13 @@ export function findComponents(index, { query, layer = null, limit = 5 }) {
     const exactImport = normalized(family.import) === needle;
     const matchedSymbols = family.symbols.filter(symbol => symbolKey(symbol) === key);
     const documented = new Set(family.guidance.flatMap(guide => guideSymbols(guide, family)));
+    const capabilities = searchable([family.responsibility, ...documented, ...family.jobs, ...family.tags, ...family.aliases, ...family.sections, ...family.guidance.map(guideText)].join(' '));
+    const haystack = searchable([family.import, capabilities].join(' '));
+    // Related owners need capability evidence: package/path vocabulary alone
+    // cannot recommend them. Strict matching still requires every query term.
+    const terms = partial ? queryTerms.filter(term => containsTerms(capabilities, [term])) : queryTerms;
+    if ((partial && !terms.length) || (!partial && !exactImport && !matchedSymbols.length && !containsTerms(haystack, terms))) continue;
     const focusedSymbols = [...documented].filter(symbol => containsTerms(symbol, terms));
-    const haystack = searchable([family.import, family.responsibility, ...documented, ...family.jobs, ...family.tags, ...family.aliases, ...family.sections, ...family.guidance.map(guideText)].join(' '));
-    // AND matching prevents a familiar term from inventing results for an
-    // otherwise unknown query. Avoidance/alternatives do not recommend owners.
-    if (!exactImport && !matchedSymbols.length && !containsTerms(haystack, terms)) continue;
     // A dedicated, documented owner precedes an aggregate re-export of the
     // same symbol. Explicit import queries still select the requested family.
     const documentedSymbol = matchedSymbols.some(symbol => documented.has(symbol));
@@ -137,8 +154,77 @@ export function findComponents(index, { query, layer = null, limit = 5 }) {
       references: [...new Set([...(family.references ?? []), ...recipes.flatMap(recipe => recipe.references)])].sort(compare),
       examples: recipes.map(({ file, exports, symbols, optionalPeers = [] }) => ({ file, exports, symbols: symbols.filter(symbol => relevantSymbols.includes(symbol)), optionalPeers })),
     };
-    ranked.push({ score, import: family.import, declaration: family.declaration, layer: family.layer, responsibility: family.responsibility, optionalPeers: family.optionalPeers, match: exactImport ? 'import' : matchedSymbols.length ? 'symbol' : 'intent', matchedSymbols, relevantSymbols, ...(Object.keys(deprecated).length ? { deprecated } : {}), nextReads, guidance });
+    ranked.push({ score, import: family.import, declaration: family.declaration, layer: family.layer, responsibility: family.responsibility, optionalPeers: family.optionalPeers, match: partial ? 'partial' : exactImport ? 'import' : matchedSymbols.length ? 'symbol' : 'intent', ...(partial ? { matchedTerms: terms, unmatchedTerms: queryTerms.filter(term => !terms.includes(term)) } : {}), matchedSymbols, relevantSymbols, ...(Object.keys(deprecated).length ? { deprecated } : {}), nextReads, guidance });
   }
-  ranked.sort((a, b) => b.score - a.score || compare(a.import, b.import));
+  ranked.sort((a, b) => (partial ? b.matchedTerms.length - a.matchedTerms.length : 0) || b.score - a.score || compare(a.import, b.import));
   return { package: index.package, version: index.version, query, layer, limit, total: ranked.length, results: ranked.slice(0, limit) };
 }
+
+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.
+  const query = options.query.trim();
+  if (result.total || !/\s/.test(query) || /[\\/]|[a-z0-9][A-Z]|[A-Z]{2}/.test(query) || new Set(words(query)).size < 2) return result;
+  const related = rankComponents(index, options, true);
+  return related.total ? { ...result, related: {
+    explanation: 'No family matched every query term. These suggestions cover incomplete context; unmatched terms remain unverified. Read the owner guidance before choosing.',
+    total: related.total,
+    results: related.results,
+  } } : result;
+}

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

@@ -0,0 +1,11 @@
+import fs from 'node:fs';
+import {inspectComponent, parseComponentArguments} from './inspection.mjs';
+
+try {
+ const read = name => JSON.parse(fs.readFileSync(new URL(`../references/${name}`, import.meta.url), 'utf8'));
+ 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 name[,name]]... [--limit 1..100]\n`);
+ process.exitCode = 1;
+}

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

@@ -0,0 +1,11 @@
+import fs from 'node:fs';
+import {inspectTokens, parseTokenArguments} from './inspection.mjs';
+
+try {
+ const index = JSON.parse(fs.readFileSync(new URL('../references/tokens.json', import.meta.url), 'utf8'));
+ const publicIndex = JSON.parse(fs.readFileSync(new URL('../references/public-api.json', import.meta.url), 'utf8'));
+ process.stdout.write(JSON.stringify(inspectTokens(index, parseTokenArguments(process.argv.slice(2)), publicIndex), null, 2) + '\n');
+} catch (error) {
+ process.stderr.write(`inspect-tokens: ${error.message}\nUsage: node inspect-tokens.mjs <root-or-role-query> [--limit 1..100]\n`);
+ process.exitCode = 1;
+}

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

@@ -0,0 +1,193 @@
+const requireFormat = (condition, message) => {if (!condition) throw new Error(message);};
+const text = value => typeof value === 'string' && value.length > 0;
+const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+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, props: [], limit: 12};
+ const seen = new Set();
+ const allowed = token ? ['--limit'] : ['--import', '--prop', '--limit'];
+ for (let index = 0; index < args.length; index++) {
+  const arg = args[index];
+  if (!allowed.includes(arg)) {
+   if (!token && arg.startsWith('-')) throw new Error(`Unknown argument: ${arg}`);
+   const key = token ? 'query' : 'symbol';
+   requireFormat(!options[key] && text(arg), `Use one exact ${key}; quote a multiword token query`);
+   options[key] = arg;
+   continue;
+  }
+  // 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 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`);
+ // `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);
+
+export function validateComponentContracts(index, publicIndex) {
+ requireFormat(record(index) && index.schemaVersion === 1, 'Unsupported component contract schema; refresh the complete skill bundle');
+ requireFormat(text(index.package) && text(index.version) && Array.isArray(index.contracts) && record(index.nativeProfiles), 'Invalid component contract identity/data');
+ requireFormat(index.nativeProperties === undefined || record(index.nativeProperties), 'Invalid native property registry');
+ if (publicIndex) requireFormat(index.package === publicIndex.package && index.version === publicIndex.version, 'Component contract package/version identity mismatch; refresh the complete bundle');
+ const seen = new Set();
+ const validateProp = (name, prop) => {
+  requireFormat(record(prop) && prop.name === name && text(prop.type) && typeof prop.required === 'boolean' && typeof prop.description === 'string' && record(prop.default) && ['unknown', 'documented'].includes(prop.default.status), `Invalid prop contract: ${name}`);
+  if (prop.variants !== undefined) requireFormat(Array.isArray(prop.variants) && prop.variants.every(variant => Number.isInteger(variant.branch) && Number.isInteger(variant.signature) && typeof variant.required === 'boolean' && text(variant.type) && (variant.discriminants === undefined || record(variant.discriminants))), `Invalid branch contract: ${name}`);
+  if (prop.callbackSignatures !== undefined) requireFormat(Array.isArray(prop.callbackSignatures) && prop.callbackSignatures.every(callback => Number.isInteger(callback.branch) && Number.isInteger(callback.signature) && Array.isArray(callback.signatures) && callback.signatures.length > 0 && callback.signatures.every(text) && (callback.discriminants === undefined || record(callback.discriminants))), `Invalid callback contract: ${name}`);
+ };
+ for (const prop of Object.values(index.nativeProperties ?? {})) validateProp(prop?.name, prop);
+ for (const props of Object.values(index.nativeProfiles)) {
+  requireFormat(record(props), 'Invalid native profile');
+  for (const [name, reference] of Object.entries(props)) {
+   if (typeof reference === 'string') requireFormat(Object.hasOwn(index.nativeProperties ?? {}, reference), `Missing native property reference: ${reference}`);
+   validateProp(name, typeof reference === 'string' ? index.nativeProperties[reference] : reference);
+  }
+ }
+ for (const contract of index.contracts) {
+  requireFormat(record(contract) && text(contract.import) && text(contract.symbol) && /^dist\/[\w./-]+\.d\.ts$/.test(contract.declaration) && !contract.declaration.split('/').includes('..') && Array.isArray(contract.callSignatures) && contract.callSignatures.every(text) && record(contract.props), 'Invalid component contract');
+  const identity = `${contract.import}#${contract.symbol}`;
+  requireFormat(!seen.has(identity), `Duplicate component contract: ${identity}`); seen.add(identity);
+  requireFormat(contract.inheritedProfile === null || Object.hasOwn(index.nativeProfiles, contract.inheritedProfile), `Missing inherited profile for ${identity}`);
+  for (const [name, prop] of Object.entries(contract.props)) validateProp(name, prop);
+  if (publicIndex) {
+   const family = publicIndex.families?.find(family => family.import === contract.import);
+   requireFormat(family?.declaration === contract.declaration && family.symbols.includes(contract.symbol), `Contract is absent from matching public index: ${identity}`);
+  }
+ }
+ return index;
+}
+
+function displayProp(prop, origin) {
+ const type = boundedText(prop.type, 2000);
+ const description = boundedText(prop.description, 800);
+ const variants = prop.variants?.slice(0, 12).map(variant => {
+  const value = boundedText(variant.type, 2000);
+  return {...variant, type: value.text, typeComplete: value.complete, omittedTypeCharacters: value.omittedCharacters};
+ });
+ const callbacks = prop.callbackSignatures?.slice(0, 12).map(callback => ({...callback,
+  signatures: callback.signatures.slice(0, 4).map(signature => boundedText(signature, 2000)), omittedSignatures: Math.max(0, callback.signatures.length - 4)}));
+ return {...prop, origin, type: type.text, typeComplete: type.complete, omittedTypeCharacters: type.omittedCharacters,
+  description: description.text, omittedDescriptionCharacters: description.omittedCharacters,
+  ...(variants ? {variants, omittedVariants: prop.variants.length - variants.length} : {}),
+  ...(callbacks ? {callbackSignatures: callbacks, omittedCallbackBranches: prop.callbackSignatures.length - callbacks.length} : {})};
+}
+
+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, 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 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])) : {};
+ // 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 (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} : {}),
+  description: description.text, omittedDescriptionCharacters: description.omittedCharacters,
+  callSignatures: contract.callSignatures.slice(0, 4).map((signature, signatureIndex) => ({index: signatureIndex, ...boundedText(signature, 4000)})),
+  props: selected,
+  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: 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> (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) {
+ requireFormat(record(index) && text(index.package) && text(index.version) && Array.isArray(index.structural) && record(index.radius) && Array.isArray(index.advanced) && record(index.utilities), 'Invalid token metadata; refresh the complete bundle');
+ requireFormat(text(query) && Number.isInteger(limit) && limit >= 1 && limit <= 100, 'Use a token query and limit 1..100');
+ if (publicIndex) requireFormat(index.package === publicIndex.package && index.version === publicIndex.version, 'Token metadata package/version identity mismatch; refresh the complete bundle');
+ const words = value => value.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+ const terms = words(query);
+ const values = [
+  ...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.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),
+  coverage: 'Structural/radius roots, advanced root names and derived utility spellings. Semantic shadcn light/dark color values are not indexed here; read the installed theme stylesheet and theming reference.',
+  rule: index.rule, nextReads: ['references/theming.md', 'references/design-contract.md', 'references/tokens.json'], themeStylesheets: publicIndex?.stylesheets ?? []};
+}

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

@@ -0,0 +1,12 @@
+import fs from 'node:fs';
+import {mapComposition, parseCompositionArguments} from './composition.mjs';
+
+try {
+ const options = parseCompositionArguments(process.argv.slice(2));
+ const read = file => JSON.parse(fs.readFileSync(new URL(`../references/${file}`, import.meta.url), 'utf8'));
+ const result = mapComposition(read('public-api.json'), read('component-contracts.json'), options);
+ process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+} catch (error) {
+ process.stderr.write(`map-composition: ${error.message}\nUsage: node map-composition.mjs --roles | --role <role or import#symbol> | --pattern record-detail|collection|edit|analytics|embedded [--main <need>] [--aside <need>] [--parent <symbol> --import <import>] [--limit 1..10]\n`);
+ process.exitCode = 1;
+}

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

@@ -0,0 +1,111 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+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, four small discoverable entrypoints, and real templates. */
+export function consumerBundleFiles(packageRoot, destination) {
+  const mappings = [
+    ['docs/consumer-skill', sharedSkillName],
+    ...focusedSkills.map(name => [`docs/consumer-skills/${name}`, name]),
+    ['templates', `${sharedSkillName}/templates`],
+  ].map(([source, target]) => ({ source: path.resolve(packageRoot, source), target: path.resolve(destination, target) }));
+  function mapped(file) {
+    const mapping = mappings.find(item => file === item.source || file.startsWith(item.source + path.sep));
+    assert(mapping, `Reference outside shipped consumer bundle: ${file}`);
+    return path.join(mapping.target, path.relative(mapping.source, file));
+  }
+  const files = [];
+  function walk(directory) {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      if (entry.name === '.DS_Store') continue;
+      const source = path.join(directory, entry.name);
+      assert(!fs.lstatSync(source).isSymbolicLink(), `Symlink in consumer bundle: ${source}`);
+      if (entry.isDirectory()) walk(source);
+      else {
+        const target = mapped(source);
+        let content = fs.readFileSync(source);
+        if (source.endsWith('.md')) {
+          content = Buffer.from(content.toString().replace(/(\]\(|^\s*\[[^\]]+\]:\s*)([^\s)]+)(?=\)|\s|$)/gm, (match, prefix, raw) => {
+            if (/^(?:[a-z][a-z\d+.-]*:|#|\/)/i.test(raw)) return match;
+            const [link, anchor = ''] = raw.split(/(?=[?#])/);
+            const resolved = path.resolve(path.dirname(source), decodeURIComponent(link));
+            assert(fs.existsSync(resolved), `Missing consumer bundle reference: ${source} → ${link}`);
+            const relative = path.relative(path.dirname(target), mapped(resolved)).split(path.sep).join('/');
+            return prefix + relative + anchor;
+          }));
+        }
+        files.push({ source, target, content });
+      }
+    }
+  }
+  for (const mapping of mappings) walk(mapping.source);
+  return files;
+}
+
+export function checkCopiedConsumerBundle({ packageRoot, destination }) {
+  const files = consumerBundleFiles(packageRoot, destination);
+  for (const { target, content } of files) {
+    assert(fs.existsSync(target) && !fs.lstatSync(target).isSymbolicLink(), `Copied consumer bundle is stale: missing or linked asset ${target}`);
+    assert(content.equals(fs.readFileSync(target)), `Copied consumer bundle is stale: refresh the whole bundle (${target})`);
+  }
+  return { skills: [sharedSkillName, ...focusedSkills], assets: files.length };
+}
+
+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.`);
+  for (const { target, content } of files) {
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, content);
+  }
+  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 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 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) {

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

@@ -0,0 +1,31 @@
+---
+name: themelia-components
+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
+
+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.
+
+## Find and verify
+
+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 "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
+```
+
+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.
+
+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).
+
+## Wire the selected owner
+
+- 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).
+
+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-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.

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

@@ -0,0 +1,34 @@
+---
+name: themelia-composition
+description: Use when composing or repairing Themelia screens, shells, public sites, data-led domain components and workflows, including owner selection, hierarchy, responsive regions and compound APIs.
+---
+
+# Themelia composition
+
+Start with the user's decision, representative records, related entities and editable state. Use **themelia-components** for installed identity/APIs, **themelia-tokenization** for shared visual roles and app geometry, and **themelia-design** to read records into a view spec and score the rendered view.
+
+Before JSX, settle task, reading priority, action scope and inset owners. Read [screen decisions](../../consumer-skill/references/screen-decisions.md) for new screens/repairs. Optional props are capabilities, not reasons to add navigation, cards or commands.
+
+## Let the data shape the subject
+
+Discover task-specific owners before choosing custom markup: product options, variant editing and attached media have different owners from generic controls. Compare their data/state/render seams; use a fitting owner or its parts. Custom JSX shapes additional relationships without requiring an API gap. Read [capability comparison and domain coverage](../../consumer-skill/references/custom-composition.md). More data and a new component name do not establish better composition.
+
+## Choose the seam
+
+A feature coordinates workflows; blocks present subjects; base owns controls/disclosure/structures; layout owns app/page regions; primitives format values. Each can have local interaction. Combine these owners and compound parts.
+
+Inspect an existing owner's behavior before replacing it: a badge or retained field does not establish an API limit. Card owns framing; Accordion owns labeled disclosure; Collapsible supports a custom single disclosure. Rich slot content retains the owner's typography role.
+
+Use the [mapper](../../consumer-skill/references/composition-mapping.md) with --roles or a pattern/subject query. Read coverage, unresolved needs and nextReads. Unmapped does not mean unsupported. [Archetypes](../../consumer-skill/references/screen-archetypes.md) are starting responsibilities, not layouts to reproduce; orders and invoices have an [owner map](../../consumer-skill/references/commerce-composition.md).
+
+## Assign geometry once
+
+Page narrow centers one-column forms/details at 48rem; aside infers xl/80rem. Explicit TwoColumnLayout needs Page maxWidth="xl". Collections default to lg/64rem. Settings use Page → SettingsShell → FormSection.
+
+Explicit maxWidth wins, then narrow, then aside width. Page owns h1, commands, lifecycle, gutters and subject gaps. AuthShell owns auth; Container/Section own sites. Header actions defaultContent preserves responsive commands. Loading precedes error then empty; supply copy/onRetry. Resource shells are migration APIs.
+
+Stack/Grid/AdaptiveGrid own peer relationships; Card owns frame/insets. Card flat removes chrome, not padding; use none under an existing inset owner. Blocks stay card-free unless their purpose is a card. Tailwind owns app-specific tracks/queries/overflow; read [domain structures](../../consumer-skill/references/domain-structures.md).
+
+Indexes use DataView or FilterProvider → DataTable with FilterLayout in topbarContent; exports in topbarEnd, selection in bulkActions, record commands in rowActions. Table owns its surface. Keep fixed scope distinct from filters. Apps own transport, permissions, routing and translations; read [forms](../../consumer-skill/references/rhf-workflows.md).
+
+Rank commands by scope/frequency/consequence; use overflow for secondary item actions when visible buttons compete with identity. Add back navigation only for a real return journey. Preserve narrow DOM priority, not just column stacking. Run app checks and [review](../../consumer-skill/references/review.md); inspect actual narrow/wide appearance and opened/error/accepted states. Valid API usage is not product quality.