themelia-react-ui 2.0.2 → 2.0.4

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,23 @@ 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) };
 }
+
+export function findComponents(index, options) {
+  validateIndex(index);
+  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 exact-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,138 @@
+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, prop: null, 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;
+  }
+  requireFormat(!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;
+ }
+ requireFormat(text(options[token ? 'query' : 'symbol']), `A nonempty ${token ? 'token query' : 'exact symbol'} is required`);
+ return options;
+}
+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),
+  ...(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) {
+ 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 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));
+ 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'));
+ 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: Object.keys(inherited).slice(0, 20), omittedInheritedNames: Math.max(0, Object.keys(inherited).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.'};
+}
+
+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.innerUtility ? {formula: index.radius.innerFormula} : {})})),
+ ];
+ 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,76 @@
+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'];
+export const sharedSkillName = 'themelia-react-ui-consumer';
+
+/** One metadata/example copy, three 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 });
+}
+
+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 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));
+  } catch (error) { console.error(error.message); process.exitCode = 1; }
+}

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

@@ -0,0 +1,30 @@
+---
+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.
+---
+
+# 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.
+
+## Discover and inspect
+
+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.
+
+```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
+```
+
+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.
+
+## Integrate the contract
+
+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`.
+
+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.
+
+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 **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.

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

@@ -0,0 +1,35 @@
+---
+name: themelia-composition
+description: Map responsibilities to exact Themelia components and supported compositions, then build and polish business interfaces, shells, public sites and workflows with verified hierarchy and interactions.
+---
+
+# Themelia composition
+
+## Start from the business task
+
+Identify the user, decision/action, essential facts, editable state and supporting history. Prioritize what must be compared together and what can be selected, disclosed or routed. App-specific business components are expected; public owners supply geometry and behavior.
+
+Use the [mapper](../../consumer-skill/references/composition-mapping.md) for executable role selection and supported nesting:
+
+```sh
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/map-composition.mjs --roles
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/map-composition.mjs --pattern record-detail --main invoice-lines --aside facts
+```
+
+Verify installed/copied guidance with **themelia-components** first. Read coverage, unresolved needs, surface warnings, family peers and focused API/recipe reads. Resolve ambiguity with a specific role or qualified import/symbol. The plan is advisory; unmapped components can still be valid. Inspect unfamiliar APIs before wiring them. Use the [archetype matrix](../../consumer-skill/references/screen-archetypes.md) and matching blueprints as evidence. Prefer a complete feature when its lifecycle fits.
+
+## Assign ownership and build
+
+Use Page for route identity/commands, AuthShell for authentication, Container/Section for content sites. Shell hosts route children; route owns its Page/h1. Page owns gutters and direct-subject gaps; TwoColumnLayout owns column/subject gaps. Stack/Grid arrange nested groups; Card owns framing/insets; features own interactions. Read [composition](../../consumer-skill/references/composition.md) and page/embedded guidance. Give each space, header and command one owner.
+
+Implement the responsibility map with app state. Avoid a Card for every field or automatic KPI rows/tabs/icons. Main/support regions clarify responsibilities. Adapt to parent width, preserve DOM/focus order and constrain scrolling/overflow. Continuous documents are valid; tabs select separate sections.
+
+Choose gaps by [shared relationships](../../consumer-skill/references/design-contract.md#semantic-roles), not whichever utility fits one screenshot. Page/subject/copy/action rhythm differs from surface insets and row density. Use Heading/Text and semantic value primitives; title badges use titleSuffix. Reusable content stays card-free until its boundary. Supported flat/none anatomy prevents doubled insets inside a padded host. Use **themelia-tokenization** for coherent theme changes.
+
+See [template boundaries](../../../templates/README.md) for domain blueprints and [typed form workflows](../../consumer-skill/references/rhf-workflows.md) for editing. Transport, permissions, routing and translations belong to the app. Dialogs/drawers/confirmations use `features/overlays` at the composing app/feature boundary.
+
+## Inspect, repair and deliver
+
+Run the [composition checker](../../consumer-skill/references/review.md) and app type/lint/test checks. Fix errors; judge warnings in context rather than removing valid composition to silence them. Open the actual screen at narrow/wide parent widths and both themes. Inspect hierarchy, wrapping, alignment, corners, control consistency and quiet space; repair the highest-impact weakness at its owner.
+
+Execute relevant keyboard/focus, selection, validation, failure/retry, cancellation and accepted-save paths. Report source, inspected appearance and interactions separately. A renderable route or clean checker does not establish a useful screen. For requested publication use the app's actual build/deploy configuration and target; no Themelia publish CLI exists. Library npm release is maintainer work. Hand back the working result and verified limits.

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

@@ -0,0 +1,12 @@
+---
+name: themelia-forms
+description: Compatibility route for older Themelia form-skill instructions; use themelia-components for exact bindings and themelia-composition for complete edit/create workflows.
+---
+
+# Themelia forms compatibility route
+
+Use [themelia-components](../themelia-components/SKILL.md) to inspect actual value/event, callback, ref and controlled-state contracts. Use [themelia-composition](../themelia-composition/SKILL.md) for complete edit pages and overlay workflows.
+
+The full [RHF workflows](../../consumer-skill/references/rhf-workflows.md), [typed bindings](../../consumer-skill/examples/rhf-bindings.tsx), [edit page](../../consumer-skill/examples/rhf-edit-page.tsx) and [overlay form](../../consumer-skill/examples/rhf-overlay-form.tsx) remain shared resources. Validation, dirty state, arrays, async transport, failure drafts, accepted-value reset and focus restoration retain their contracts.
+
+This package path is retained for existing instructions. Install the complete current bundle through [installation](../../consumer-skill/references/installation.md); separately installed skills are not replaced automatically.

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

@@ -0,0 +1,14 @@
+---
+name: themelia-foundation
+description: Compatibility route for older Themelia instructions naming themelia-foundation; use the current components, tokenization and composition capabilities for new work.
+---
+
+# Themelia foundation compatibility route
+
+The canonical capability split is now:
+
+- [themelia-components](../themelia-components/SKILL.md): installed setup, owner discovery, exact API inspection and framework integration.
+- [themelia-tokenization](../themelia-tokenization/SKILL.md): CSS/theme setup, semantic roots, typography and scoped themes.
+- [themelia-composition](../themelia-composition/SKILL.md): shell/route ownership, screen hierarchy and delivery.
+
+Follow the matching capability. [Installation](../../consumer-skill/references/installation.md) explains the complete current bundle. This package path is retained for existing instructions; separately installed skills are not replaced automatically.

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

@@ -0,0 +1,35 @@
+---
+name: themelia-tokenization
+description: Theme and polish themelia-react-ui apps through semantic colors, typography, structural roots, density and scoped portal themes; inspect supported tokens and correct visual drift without restyling component anatomy.
+---
+
+# Themelia tokenization
+
+Translate the intended visual change into a shared responsibility before changing CSS. Use the installed version's [design contract](../../consumer-skill/references/design-contract.md), [theme guide](../../consumer-skill/references/theming.md) and generated token metadata. **themelia-components** owns API integration; **themelia-composition** owns task hierarchy and region placement.
+
+## Inspect the customization surface
+
+Resolve package identity and the active CSS path through [installation](../../consumer-skill/references/installation.md). Compiled component CSS and app-authored semantic Tailwind utilities have different setup requirements. Keep overrides in one app stylesheet after package styles, or at a real ThemeScope boundary.
+
+```sh
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/inspect-tokens.mjs surface --limit 8
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/inspect-tokens.mjs radius --limit 5
+```
+
+Lookup distinguishes structural roots, advanced settings and derived utility spellings. Only supported settings are overrides. Generated `--spacing-*`, `--radius-*` or `--container-*` aliases are not public knobs. If a query lacks a semantic color value, read the installed theme and guide; do not invent a root or claim an unreported light/dark default.
+
+## Choose the role
+
+- Brand/surface changes use existing shadcn semantic surface/foreground pairs. State uses success/info/warning/destructive pairs; categories and counts stay neutral. Keep input boundaries, dividers and focus distinct.
+- Typography changes use supported text/font roles and provider defaults. Visual size stays separate from heading level. Density does not reduce primary copy to compact metadata.
+- `--space-scale` changes gaps/insets; `--density-scale` changes control/row heights. Action/control sizes, row density, copy gaps and surface insets remain independent. Use the [relationship table](../../consumer-skill/references/design-contract.md#semantic-roles) to select public gaps.
+- Surface insets belong to Card/overlay anatomy; page gutters belong to layout. Change the appropriate owner/root instead of accumulating wrappers or padding resets.
+- The single radius root drives outer shells and height-bounded inner controls. Physical nesting does not choose the role. Icons, avatars and shell dimensions have their own existing roots.
+
+Apply the smallest coherent theme change to related owners. Preserve supported variants and app placement; do not compensate for one control with a copied implementation, raw palette, extra opacity scale, local focus treatment or per-component token.
+
+## Verify the effect
+
+Check both themes on actual surfaces, including primary/secondary/status text, boundaries and focused/invalid/disabled states. Open a real picker/menu/overlay in a scoped theme and verify its portal shares the scope. Change spacing and density independently with other roots held fixed; inspect adjoining heights, baselines, corners and clipping as well as computed values. A capture before popup presence settles is not open-state proof.
+
+Use available browser/contrast tooling and the [review contract](../../consumer-skill/references/review.md); do not invent a Themelia theme-publishing or audit CLI. Run app checks and execute keyboard use. Deliver the stylesheet, affected role explanation, inspected widths/themes and behavior evidence. Report unexercised states as unverified.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "themelia-react-ui",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "description": "A composable React UI library for modern admin applications, built on Base UI and Tailwind with shadcn-compatible themes, shared design tokens, reusable layouts, blocks and workflows.",
   "publishConfig": {
     "access": "public",
@@ -30,6 +30,8 @@
     "README.md",
     "CHANGELOG.md",
     "docs/consumer-skill",
+    "docs/consumer-skills",
+    "templates",
     "THIRD_PARTY_NOTICES.md"
   ],
   "sideEffects": [
@@ -477,11 +479,11 @@
     "check:maps": "node scripts/test-client-boundaries.mjs --built",
     "build:docs": "node scripts/build-static-docs.mjs",
     "check:static-docs": "node scripts/check-static-docs.mjs",
-    "check:agent": "node --test scripts/test-consumer-discovery.mjs scripts/test-consumer-composition.mjs scripts/test-consumer-evals.mjs scripts/test-button-codemod.mjs scripts/test-consumer-skill-assets.mjs scripts/test-static-docs.mjs scripts/test-fixture-install.mjs && npm run check:skill",
+    "check:agent": "node --test scripts/test-consumer-discovery.mjs scripts/test-consumer-inspection.mjs scripts/test-consumer-mapper.mjs scripts/test-composition-metadata.mjs scripts/test-consumer-composition.mjs scripts/test-consumer-evals.mjs scripts/test-button-codemod.mjs scripts/test-consumer-skill-assets.mjs scripts/test-static-docs.mjs scripts/test-fixture-install.mjs && npm run check:skill",
     "check:release": "npm run check:all && npm run check:agent && npm run build:docs && npm run check:static-docs"
   },
   "peerDependencies": {
-    "@base-ui/react": "1.8.0-kpo.2",
+    "@base-ui/react": "^1.9.0",
     "@dnd-kit/core": "^6.0.0",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.0.0",
@@ -523,7 +525,7 @@
     "zustand": "^5.0.12"
   },
   "devDependencies": {
-    "@base-ui/react": "file:./base-ui-react-1.8.0-kpo.2.tgz",
+    "@base-ui/react": "^1.9.0",
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",

package/templates/README.md

@@ -0,0 +1,39 @@
+# Admin composition examples
+
+These shipped, copyable application blueprints demonstrate `themelia-react-ui` through its public imports. Open `/?page=templates` after `npm run dev` for the shared shell, or use the individual catalogue pages under Templates. They ship in `node_modules/themelia-react-ui/templates/` as source assets, not additional npm entrypoints. Copy and adapt them into the application.
+
+The examples use local, in-memory records. A reload resets them. Connect your app's data loading, persistence, authorization, notification delivery and navigation at the shown callbacks; no backend or authentication service is included. Publishing settings and permissions here describe sample state, not server enforcement.
+
+For production create/edit workflows, adapt the [RHF edit page](../docs/consumer-skill/examples/rhf-edit-page.tsx) and [RHF overlay form](../docs/consumer-skill/examples/rhf-overlay-form.tsx) to these domain screens. Replace their local draft state with RHF values, validation, arrays and dirty tracking, and await the app's complete transport before accepting a saved baseline. The [forms workflow guide](../docs/consumer-skill/references/rhf-workflows.md) supplies typed control bindings and Inertia/TanStack integration seams.
+
+| File | Export | Composition demonstrated |
+| --- | --- | --- |
+| [admin-shell-template.tsx](admin-shell-template.tsx) | `AdminStarterShell`, `AdminTemplatesShowcase` | UIProvider defaults, all five AppLayout presets, AppSidebar, workspace context, breadcrumbs, notifications and account/settings menus |
+| [orders-template.tsx](orders-template.tsx) | `OrdersAdminTemplate` | Page with a fulfillment primary command, TwoColumnLayout, Card, lifecycle-grouped Item rows, MetadataList, Money, AddressCard, PaymentMethod, ActivityLog and refund/tracking/note dialogs |
+| [products-template.tsx](products-template.tsx) | `ProductsAdminTemplate` | ProductVariantsManager, ProductVariantDetails/Editor, SeoListingCard, publishing/organization forms and variant duplication |
+| [customers-template.tsx](customers-template.tsx) | `CustomersAdminTemplate` | MetricBar, DataTable order history, MetadataList, AddressCard, ActivityLog, contact drafts and validated store-credit submission |
+| [user-permissions-template.tsx](user-permissions-template.tsx) | `UserPermissionsTemplate` | FormField, DirtyStateBanner, role-based Page save and confirmed suspend commands, role presets and editable permission groups with a saved/discard baseline |
+| [analytics-operations-template.tsx](analytics-operations-template.tsx) | `AnalyticsOperationsTemplate` | Numeric MetricBar KPIs, MetricComparison, ActivityHeatmap, UsageCard and an app-owned operations list |
+
+For layout selection, read the [owner map](../docs/consumer-skill/references/composition.md#structure-and-spacing) and [typed layout-block recipe](../docs/consumer-skill/examples/layout-blocks.tsx). Use horizontal Stack for rows, Grid/GridCell for prescribed columns and spans, AdaptiveGrid for parent-driven equal tiles, and TwoColumnLayout for a main/support split.
+
+## Boundaries to preserve when adapting
+
+- `AdminTemplatesShowcase` supplies UIProvider defaults; embedded preview pages inherit the catalogue's provider. `AdminStarterShell` inherits the application's provider. `defaultDensity` belongs to the standalone showcase.
+- Page owns gutters and the default resource measure, TwoColumnLayout owns the main/aside split, and Stack/Grid own peer gaps. These record and overview routes keep the default measure; only a wide directory or comparison opts into `maxWidth="full"`. Ordinary Cards retain the default padding. Compact control density does not shrink Cards. Peer Card stacks use `gap="2xl"`, matching Page and TwoColumnLayout’s 24px default rhythm in both axes; copy and form groups keep their own gaps.
+- A headed address, payment, SEO or variants panel uses its own `surface="card"`. It delegates to Card's aligned header/body anatomy and inherits provider separators. Do not wrap it in an untitled padded Card. Omitted surface keeps these blocks unframed for embedding; an embedded header does not inherit an unintended Card separator.
+- Put page commands in Page's header as `primaryAction` (one) and ordered
+  `secondaryActions`; the header owns their treatment, overflow and narrow-width
+  collapse. A destructive command is a `destructive: true` secondary action that
+  opens ConfirmDialog. Put subject commands in Card's header. Status/count badges use `titleSuffix`;
+  a status shown in the page header is not repeated in a card or fact list. Spacing separates a card's header, body and footer; a body separator is appropriate only between distinct body sections.
+- Metrics use numeric values and formatting hints. Context such as “12 orders” belongs in a subtitle; it is not a directional trend. The analytics period changes the KPI strip; comparisons, heatmap and quota data are separately described monthly/current snapshots.
+- Overlay edits start from a snapshot and update committed display state only on Save. Native forms use `formId` so required fields and submission ownership are preserved. App persistence should use the overlay's async contract with pending/error/retry handling before committing; do not bind a draft editor directly to committed record data.
+- Local sidebar navigation preserves native link modifiers and closes the mobile drawer. Replace the local route map with your router adapter and record-aware destinations. Sample records across these pages are independent; a customer route is not an order's customer resolver.
+- Choose the component that fits the subject. A lifecycle-specific order item group can use Item; editable permission groups can use ToggleField. Do not replace them with an unrelated block merely to increase the component count.
+
+## Checks
+
+`npm run typecheck`, `npm run lint` and `npm run check:design-lint` include `templates/`. `npm run check:package` also typechecks these sources against the installed tarball, from the installed tarball, alongside the shipped consumer-skill recipes. `node docs/consumer-skill/scripts/check-composition.mjs templates` is a supplementary static review; unresolved dynamic spreads still need source and interaction review.
+
+`tests/browser/templates.spec.ts` covers Card boundaries at desktop/mobile widths in both themes, mobile navigation and contact/credit submission. The dated verification report records the images actually inspected and the checks executed. Static checks and screenshots do not establish backend integration.