themelia-ui 3.1.0 → 3.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "themelia-ui",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "private": false,
   "description": "Themelia UI is a production-ready, composable React component system with CSS-first theming.",
   "keywords": [
@@ -38,6 +38,9 @@
     "scripts/consumer/install-skill.mjs",
     "scripts/consumer/find-component.mjs",
     "scripts/consumer/codemod.mjs",
+    "scripts/consumer/diagnose.mjs",
+    "scripts/consumer/contract-reader.mjs",
+    "scripts/consumer/css-scan.mjs",
     "docs/README.md",
     "docs/learn",
     "docs/generated",

package/scripts/consumer/codemod.mjs

@@ -10,8 +10,9 @@
  * stylesheet references requiring manual review.
  */
 import { existsSync, readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from 'node:fs'
-import { dirname, join, relative, resolve } from 'node:path'
+import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { loadMigrationMaps } from './contract-reader.mjs'
 
 const HERE = dirname(fileURLToPath(import.meta.url))
 const GENERATED = resolve(HERE, '..', '..', 'docs', 'generated')
@@ -23,29 +24,7 @@ const MARKUP = /\.(?:html|vue|svelte|astro|mdx)$/
 const escape = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
 
 /** The two published maps, indexed for the rewrites below. */
-export function loadMaps(dir = GENERATED) {
-  const read = (file) => {
-    const path = resolve(dir, file)
-    if (!existsSync(path)) throw new Error(`the packaged migration map is missing at ${path}`)
-    return JSON.parse(readFileSync(path, 'utf8'))
-  }
-  const codemod = read('migration-codemod.json')
-  const broad = read('migration-broad-imports.json')
-  const root = resolve(dir, '..', '..')
-  const pkg = JSON.parse(readFileSync(resolve(root, 'package.json'), 'utf8'))
-  return {
-    /* Where a reader finds the rest, as a path from wherever the codemod was run. */
-    doc: relative(process.cwd(), resolve(dir, 'migration.md')),
-    name: pkg.name,
-    moves: new Map(Object.entries(codemod.moves ?? {})),
-    tokens: new Map(Object.entries(codemod.tokens ?? {})),
-    classes: new Map(Object.entries(codemod.classes ?? {})),
-    reviewClasses: new Map(Object.entries(codemod.reviewClasses ?? {})),
-    broad: new Set([...(broad.removedSubpaths ?? [])]),
-    owner: broad.symbols ?? {},
-    ambiguous: new Set(Object.keys(broad.ambiguous ?? {})),
-  }
-}
+export const loadMaps = (dir = GENERATED) => loadMigrationMaps(dir)
 
 /*
  * A whole property name: the lookbehind keeps `i--` and `a--b` out; greedy, so a name

package/scripts/consumer/contract-reader.mjs

@@ -0,0 +1,42 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { relative, resolve } from 'node:path'
+
+export function loadMigrationMaps(dir) {
+  const read = (file) => {
+    const path = resolve(dir, file)
+    if (!existsSync(path)) throw new Error(`the packaged migration map is missing at ${path}`)
+    return JSON.parse(readFileSync(path, 'utf8'))
+  }
+  const codemod = read('migration-codemod.json')
+  const broad = read('migration-broad-imports.json')
+  const root = resolve(dir, '..', '..')
+  const pkg = JSON.parse(readFileSync(resolve(root, 'package.json'), 'utf8'))
+  return {
+    /* Where a reader finds the rest, as a path from wherever the codemod was run. */
+    doc: relative(process.cwd(), resolve(dir, 'migration.md')),
+    name: pkg.name,
+    moves: new Map(Object.entries(codemod.moves ?? {})),
+    tokens: new Map(Object.entries(codemod.tokens ?? {})),
+    classes: new Map(Object.entries(codemod.classes ?? {})),
+    reviewClasses: new Map(Object.entries(codemod.reviewClasses ?? {})),
+    broad: new Set([...(broad.removedSubpaths ?? [])]),
+    owner: broad.symbols ?? {},
+    ambiguous: new Set(Object.keys(broad.ambiguous ?? {})),
+  }
+}
+
+
+/** Read generated package facts; absent or incompatible metadata is an incomplete analysis. */
+export function loadConsumerContract(packageRoot) {
+  const pkg=JSON.parse(readFileSync(resolve(packageRoot,'package.json'),'utf8'))
+  const metadata=resolve(packageRoot,'docs/generated/consumer-contract.json')
+  if(!existsSync(metadata)) throw new Error(`consumer contract is missing at ${metadata}`)
+  const contract=JSON.parse(readFileSync(metadata,'utf8'))
+  if(contract.schemaVersion!==1 || !contract.publicExports || !contract.privateStyleNames || !Array.isArray(contract.privateStyleNames.variables) || !Array.isArray(contract.privateStyleNames.classes)) throw new Error('unsupported consumer contract schema')
+  if(contract.packageVersion!==pkg.version) throw new Error('consumer contract version differs from installed package')
+  for(const [specifier,entry] of Object.entries(contract.publicExports)) {
+    if(!(specifier===pkg.name||specifier.startsWith(`${pkg.name}/`)) || !['javascript','stylesheet','json'].includes(entry.kind) || !Array.isArray(entry.symbols)) throw new Error('invalid public export metadata')
+    if(entry.targets?.some(target=>!target.startsWith('./')||target.split('/').includes('..')||!existsSync(resolve(packageRoot,target)))) throw new Error(`installed package export target is missing: ${specifier}`)
+  }
+  return {...contract,name:pkg.name,packageRoot,migration:loadMigrationMaps(resolve(packageRoot,'docs/generated'))}
+}

package/scripts/consumer/css-scan.mjs

@@ -0,0 +1,51 @@
+/** Bounded plain-CSS observations. Unsupported input is explicit, never a regex pass. */
+const decodeEscapes = value => value
+  .replace(/\\(?:\r\n|[\n\r\f])/g, '')
+  .replace(/\\([0-9a-fA-F]{1,6})(?:\r\n|[ \n\r\t\f])?|\\(.)/g, (_, hex, char) => {
+    if (!hex) return char
+    const point = parseInt(hex, 16)
+    return point === 0 || point > 0x10ffff || (point >= 0xd800 && point <= 0xdfff) ? '\uFFFD' : String.fromCodePoint(point)
+  })
+export function scanCss(source, file = 'input.css') {
+  const classes = [], variables = [], imports = [], unsupported = []
+  const locate = at => { const before=source.slice(0,at); return { line:before.split('\n').length,column:at-(before.lastIndexOf('\n')+1)+1 } }
+  if (!file.endsWith('.css')) return { classes, variables, imports, unsupported:[{...locate(0),reason:'Only plain CSS is supported'}] }
+  const chars=source.split('')
+  for(let i=0;i<source.length;i++) {
+    if(source.slice(i,i+2)==='/*') {
+      const end=source.indexOf('*/',i+2)
+      if(end<0) { unsupported.push({...locate(i),reason:'Unclosed comment'}); break }
+      for(let j=i;j<end+2;j++) if(chars[j]!=='\n') chars[j]=' '
+      i=end+1
+    } else if(source[i]==='"'||source[i]==="'") {
+      const start=i, quote=source[i]; let closed=false
+      for(i++;i<source.length;i++) { if(source[i]==='\\') {i++;continue} if(source[i]===quote) {closed=true;break} }
+      if(!closed) unsupported.push({...locate(start),reason:'Unclosed string'})
+      const value=source.slice(start+1,i)
+      if(/@import\s+(?:url\(\s*)?$/i.test(chars.slice(0,start).join(''))) imports.push({specifier:decodeEscapes(value),...locate(start)})
+      for(let j=start;j<=i && j<chars.length;j++) if(chars[j]!=='\n') chars[j]=' '
+    }
+  }
+  const clean=chars.join(''); let from=0, depth=0
+  for (const hit of clean.matchAll(/@import\s+url\(\s*([^\s)][^)]*?)\s*\)/gi)) {
+    const value=decodeEscapes(hit[1])
+    imports.push({specifier:value,...locate(hit.index)})
+  }
+  for(let i=0;i<clean.length;i++) {
+    if(clean[i]==='{') {
+      const prelude=clean.slice(from,i)
+      for(const hit of prelude.matchAll(/\.((?:\\[0-9a-fA-F]{1,6}\s?|\\.|[\w-])+)/g)) {
+        const name=decodeEscapes(hit[1])
+        classes.push({name,...locate(from+hit.index)})
+      }
+      depth++;from=i+1
+    } else if(clean[i]===';'||clean[i]==='}') { if(clean[i]==='}') depth--;from=i+1 }
+  }
+  if(depth!==0) unsupported.push({...locate(source.length),reason:'Unbalanced CSS blocks'})
+  for(const hit of clean.matchAll(/--[A-Za-z_][\w-]*/g)) {
+    const after=clean.slice(hit.index+hit[0].length), before=clean.slice(0,hit.index)
+    if(/^\s*:/.test(after)||/var\(\s*$/.test(before)) variables.push({name:hit[0],kind:/^\s*:/.test(after)?'declaration':'read',...locate(hit.index)})
+  }
+  if(/(?:^|[;{}])\s*\$|@(?:mixin|include|extend)\b/.test(clean)) unsupported.push({...locate(0),reason:'Preprocessor syntax is unsupported'})
+  return { classes, variables, imports, unsupported }
+}

package/scripts/consumer/diagnose.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+/** Read-only observations of explicit consumer files against the installed package. */
+import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, relative, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { loadConsumerContract } from './contract-reader.mjs'
+import { scanCss } from './css-scan.mjs'
+import { checkSkill } from './install-skill.mjs'
+
+const DOC='node_modules/themelia-ui/docs/learn/'
+const SCRIPT=/\.(?:[cm]?[jt]sx?)$/
+const EXCLUDED=new Set(['node_modules','.git','dist','build'])
+const inside=(root,path)=>{const rel=relative(root,path);return rel!== '..'&&!rel.startsWith('../')&&!rel.startsWith('..\\')}
+export async function diagnoseProject({project='.',paths=[],contract,checkSkills=true}={}) {
+ const root=realpathSync(resolve(project)), require=createRequire(resolve(root,'package.json'))
+ const report={schemaVersion:1,packageVersion:null,checkedRules:[],skippedChecks:[],checkedFiles:[],skippedFiles:[],findings:[]}
+ const skip=(ruleId,reason)=>report.skippedChecks.push({ruleId,reason})
+ if(!contract) {
+  try {contract=loadConsumerContract(dirname(require.resolve('themelia-ui/package.json')))}
+  catch(error) {skip('package-contract',error.message);return {...report,exitCode:2}}
+ }
+ report.packageVersion=contract.packageVersion
+ const files=new Set()
+ const skipped=(file,reason)=>report.skippedFiles.push({file:relative(root,file),reason})
+ const walk=path=>{
+  if(!inside(root,path)||relative(root,path).split(/[\\/]/).some(part=>EXCLUDED.has(part))) {skipped(path,'Outside explicit project source boundary');return}
+  if(!existsSync(path)) {skipped(path,'Missing path');return}
+  if(!inside(root,realpathSync(path))) {skipped(path,'Resolved path escapes the project through a symlink');return}
+  const stat=lstatSync(path)
+  if(stat.isSymbolicLink()) {skipped(path,'Symlinks are not followed');return}
+  if(stat.isDirectory()) {for(const entry of readdirSync(path).sort()) if(!EXCLUDED.has(entry)) walk(resolve(path,entry));return}
+  if(SCRIPT.test(path)||/\.(?:css|scss|sass|less|vue|svelte|astro|mdx)$/.test(path)) files.add(path)
+  else skipped(path,'Unsupported source format')
+ }
+ if(!paths.length) skip('explicit-paths','Supply explicit source paths to analyze')
+ for(const path of paths) walk(resolve(root,path))
+ const scripts=[...files].filter(path=>SCRIPT.test(path))
+ let ts, program, checker
+ if(scripts.length) {
+  try {ts=require('typescript');program=ts.createProgram(scripts,{noResolve:true,noLib:true,types:[],target:ts.ScriptTarget.Latest,jsx:ts.JsxEmit.Preserve});checker=program.getTypeChecker()}
+  catch(error) {skip('script-parser',`Install TypeScript in this consumer project: ${error.message}`)}
+ }
+ const finding=(ruleId,severity,file,location,evidence,explanation,documentation='troubleshooting.md')=>report.findings.push({ruleId,severity,file:relative(root,file),line:location.line,column:location.column,evidence,explanation,documentation:DOC+documentation})
+ const exportEntry=specifier=>contract.publicExports[specifier]
+ const imports=(specifier,names,file,loc)=>{
+  if(!(specifier===contract.name||specifier.startsWith(`${contract.name}/`))) return
+  const entry=exportEntry(specifier)
+  if(!entry) {
+   const moved=contract.migration?.moves?.get(specifier)
+   const alternatives=names.map(name=>contract.migration?.owner?.[name]).filter(Boolean)
+   finding('unpublished-import','error',file,loc,specifier,`This exact import is not published.${moved?` Use ${moved}.`:alternatives.length?` Use ${[...new Set(alternatives)].join(', ')}.`:/\.css$/.test(specifier)?' Components bring their own CSS; remove obsolete module stylesheet imports.':' Consult the exact import catalogue.'}`,'composition.md');return
+  }
+  if(entry.kind==='javascript') for(const name of names) if(!entry.symbols.includes(name)) finding('missing-symbol','error',file,loc,`${specifier}: ${name}`,'This symbol is absent from the installed public declaration; consult the module API.','composition.md')
+ }
+ if(ts) report.checkedRules.push('unpublished-import','missing-symbol','duplicate-owner','nested-surface')
+ for(const file of scripts) {
+  if(!ts) {skipped(file,'TypeScript parser unavailable');continue}
+  const source=program.getSourceFile(file)
+  if(!source || source.parseDiagnostics.length) {skipped(file,'Source parse failed');continue}
+  report.checkedFiles.push(relative(root,file));const bindings=new Map(), namespaces=new Map()
+  const loc=node=>{const p=source.getLineAndCharacterOfPosition(node.getStart(source));return {line:p.line+1,column:p.character+1}}
+  const bind=(node,symbol,specifier)=>{const identity=checker.getSymbolAtLocation(node);if(identity) bindings.set(identity,{symbol,specifier})}
+  for(const node of source.statements) {
+   if(ts.isImportDeclaration(node)&&ts.isStringLiteral(node.moduleSpecifier)) {
+    const specifier=node.moduleSpecifier.text, clause=node.importClause, names=[]
+    if(clause?.name) {names.push('default');bind(clause.name,'default',specifier)}
+    const named=clause?.namedBindings
+    if(named&&ts.isNamedImports(named)) for(const element of named.elements) {const name=element.propertyName?.text??element.name.text;names.push(name);bind(element.name,name,specifier)}
+    if(named&&ts.isNamespaceImport(named)) namespaces.set(checker.getSymbolAtLocation(named.name),specifier)
+    imports(specifier,names,file,loc(node.moduleSpecifier))
+   } else if(ts.isExportDeclaration(node)&&node.moduleSpecifier&&ts.isStringLiteral(node.moduleSpecifier)) imports(node.moduleSpecifier.text,node.exportClause&&ts.isNamedExports(node.exportClause)?node.exportClause.elements.map(item=>item.propertyName?.text??item.name.text):[],file,loc(node.moduleSpecifier))
+  }
+  const owner=tag=>{
+   if(ts.isIdentifier(tag)) return bindings.get(checker.getSymbolAtLocation(tag))
+   if(ts.isPropertyAccessExpression(tag)) {const specifier=namespaces.get(checker.getSymbolAtLocation(tag.expression));if(specifier) return {specifier,symbol:tag.name.text}}
+  }
+  const native=tag=>{const value=owner(tag.tagName);return value&&exportEntry(value.specifier)?.symbols.includes(value.symbol)?value.symbol:null}
+  const title=tag=>{const attr=tag.attributes.properties.find(item=>ts.isJsxAttribute(item)&&['title','label'].includes(item.name.getText(source)));return attr?.initializer&&ts.isStringLiteral(attr.initializer)?attr.initializer.text:undefined}
+  const visit=node=>{
+   if(ts.isCallExpression(node)&&node.arguments[0]&&ts.isStringLiteral(node.arguments[0])&&(node.expression.kind===ts.SyntaxKind.ImportKeyword||(ts.isIdentifier(node.expression)&&node.expression.text==='require'&&!checker.getSymbolAtLocation(node.expression)))) imports(node.arguments[0].text,[],file,loc(node.arguments[0]))
+   const member=ts.isPropertyAccessExpression(node)?{base:node.expression,name:node.name.text}
+    :ts.isQualifiedName(node)?{base:node.left,name:node.right.text}
+    :ts.isElementAccessExpression(node)&&node.argumentExpression&&(ts.isStringLiteral(node.argumentExpression)||ts.isNoSubstitutionTemplateLiteral(node.argumentExpression))?{base:node.expression,name:node.argumentExpression.text}:null
+   if(member) {
+    const specifier=namespaces.get(checker.getSymbolAtLocation(member.base))
+    if(specifier) imports(specifier,[member.name],file,loc(node))
+   }
+   const tag=ts.isJsxElement(node)?node.openingElement:ts.isJsxSelfClosingElement(node)?node:null
+   if(tag) {
+    const symbol=native(tag)
+    if(symbol) for(let ancestor=node.parent;ancestor;ancestor=ancestor.parent) {
+     if(!ts.isJsxElement(ancestor)) continue
+     const parent=native(ancestor.openingElement);if(!parent) continue
+     if(title(tag)&&title(tag)===title(ancestor.openingElement)) finding('duplicate-owner','warning',file,loc(tag),`${parent} / ${symbol}: ${title(tag)}`,'Repeated literal names may duplicate a subject or field owner. Confirm distinct subjects and accessible names.','composition.md')
+     if(symbol==='Card'&&parent==='Card') finding('nested-surface','warning',file,loc(tag),'Card inside Card','Confirm the child is an independent subject. ContentBlock or flat FormSection may express an existing-surface region.','composition.md')
+     break
+    }
+   }
+   ts.forEachChild(node,visit)
+  };visit(source)
+ }
+ report.checkedRules.push('private-variable','private-selector','migration-token','stylesheet-import')
+ for(const file of [...files].filter(path=>!SCRIPT.test(path))) {
+  const observations=scanCss(readFileSync(file,'utf8'),file)
+  if(observations.unsupported.length) {skipped(file,observations.unsupported.map(item=>item.reason).join('; '));continue}
+  report.checkedFiles.push(relative(root,file))
+  for(const item of observations.imports) imports(item.specifier,[],file,item)
+  for(const item of observations.classes) if(contract.privateStyleNames.classes.includes(item.name)) finding('private-selector','warning',file,item,item.name,'This selector matches a verified CSS Module hash in this package build. Use documented hooks or public tokens.')
+  for(const item of observations.variables) {
+   if(contract.privateStyleNames.variables.includes(item.name)) finding('private-variable','warning',file,item,item.name,'This package-private variable is not a supported override. Use a documented public token.')
+   if(contract.migration?.tokens?.has(item.name)) finding('migration-token','warning',file,item,item.name,`Historical token; ${contract.migration.tokens.get(item.name)?`review ${contract.migration.tokens.get(item.name)}`:'no successor is declared'}.`,'migration.md')
+  }
+ }
+ if(checkSkills) {
+  if(!contract.packageRoot) skip('skill-freshness','Installed package root unavailable')
+  else {
+   const freshness=checkSkill({project:root,source:resolve(contract.packageRoot,'.agents/skills/themelia-ui')})
+   if(freshness.exitCode===2) skip('skill-freshness',freshness.error)
+   else {report.checkedRules.push('skill-freshness');for(const target of freshness.targets) if(target.status!=='current') finding('skill-freshness','warning',resolve(root,`.${target.target==='agents'?'agents':'claude'}/skills/themelia-ui/SKILL.md`),{line:1,column:1},`${target.target}: ${target.status}; installed ${target.installedVersion??'unknown'}, expected ${freshness.packageVersion}`,`Review modified content and preserve application policy. Run install-skill.mjs --check --json, then reinstall only the generated copy you intend to replace. Unmanaged skills are never overwritten.`,'verification.md')}
+  }
+ }
+ const incomplete=report.skippedChecks.length||report.skippedFiles.length
+ return {...report,exitCode:incomplete?2:report.findings.some(item=>item.severity==='error')?1:0}
+}
+
+export async function runDiagnoseCli(args=process.argv.slice(2),io=console) {
+ let project='.',json=false;const paths=[]
+ for(const arg of args) {if(arg==='--json') json=true;else if(arg.startsWith('--project=')) project=arg.slice(10);else if(arg.startsWith('--')) {io.error('usage: diagnose.mjs --project=<directory> [--json] <paths...>');return 2}else paths.push(arg)}
+ let result
+ try {result=await diagnoseProject({project,paths})} catch(error) {io.error(`Incomplete diagnosis: ${error.message}`);return 2}
+ if(json) io.log(JSON.stringify(result,null,2))
+ else {io.log(`themelia-ui ${result.packageVersion??'unknown'}: ${result.checkedFiles.length} files, ${result.findings.length} findings`);for(const item of result.findings) io.log(`${item.severity} ${item.file}:${item.line}:${item.column} ${item.ruleId}: ${item.explanation}`);for(const item of [...result.skippedChecks,...result.skippedFiles]) io.log(`incomplete ${item.ruleId??item.file}: ${item.reason}`)}
+ return result.exitCode
+}
+if(process.argv[1]&&realpathSync(process.argv[1])===realpathSync(fileURLToPath(import.meta.url))) process.exitCode=await runDiagnoseCli()

package/scripts/consumer/find-component.mjs

@@ -11,6 +11,7 @@ import { fileURLToPath } from 'node:url'
 
 const HERE = dirname(fileURLToPath(import.meta.url))
 export const INDEX_PATH = resolve(HERE, '..', '..', 'docs/generated/component-index.json')
+export const CONTEXTS = ['existing-surface', 'editable', 'read-only', 'server-collection', 'nested-overlay', 'changing-scope']
 
 /** One catalogue entry in the shape the finder searches and `--json` prints. */
 const toRecord = (entry) => ({
@@ -36,7 +37,9 @@ const toRecord = (entry) => ({
 
 export function loadIndex(path = INDEX_PATH) {
   if (!existsSync(path)) throw new Error(`the packaged component index is missing at ${path}`)
-  return Object.values(JSON.parse(readFileSync(path, 'utf8')).modules).map(toRecord)
+  const index = JSON.parse(readFileSync(path, 'utf8'))
+  if (!Number.isInteger(index.schemaVersion) || index.schemaVersion < 1 || index.schemaVersion > 4 || !index.modules) throw new Error('unsupported component index schema; use the finder shipped with the installed package')
+  return Object.values(index.modules).map(toRecord)
 }
 
 const text = (value) => (Array.isArray(value) ? value.join(' ') : String(value ?? ''))
@@ -87,9 +90,11 @@ const STOPWORDS = new Set([
  * which beats positive guidance and recipes. `avoidWhen` text never counts as a match.
  */
 export function findComponents(modules, query, filters = {}) {
+  const contexts = filters.context ?? []
+  if (!Array.isArray(contexts) || contexts.some(value => !CONTEXTS.includes(value))) throw new Error(`unknown context; expected ${CONTEXTS.join(', ')}`)
   const needle = query.trim().toLowerCase()
   const hasFilter = ['tier', 'profile', 'status', 'module', 'peer', 'route', 'symbol']
-    .some((name) => Boolean(filters[name]))
+    .some((name) => Boolean(filters[name])) || contexts.length > 0
   if (!needle && !hasFilter) return []
 
   const scored = []
@@ -104,7 +109,7 @@ export function findComponents(modules, query, filters = {}) {
     const symbols = (record.publicSymbols ?? []).map((s) => String(s).toLowerCase())
     if (filters.symbol && !symbols.includes(filters.symbol.toLowerCase())) continue
 
-    if (!needle) {
+    if (!needle && !contexts.length) {
       scored.push({ record, score: 0 })
       continue
     }
@@ -123,8 +128,8 @@ export function findComponents(modules, query, filters = {}) {
     )
     if (normalizedSymbols.includes(phrase)) score = 100
     else if (normalizedModule === phrase) score = 90
-    else if (normalizedSymbols.some((symbol) => symbol.includes(phrase))) score = 75
-    else if (normalizedModule.includes(phrase)) score = 70
+    else if (phrase && normalizedSymbols.some((symbol) => symbol.includes(phrase))) score = 75
+    else if (phrase && normalizedModule.includes(phrase)) score = 70
     else if (queryTerms.length > 1 && identityWholeMatch) score = 65
     else {
       const positive = [
@@ -151,16 +156,17 @@ export function findComponents(modules, query, filters = {}) {
     }
     for (const entry of record.componentGuidance ?? []) {
       const curated = entry.guidanceSource === 'component'
-      const corpus = [entry.symbol, entry.description, curated ? entry.chooseWhen : '', ...(entry.capabilities ?? [])].join(' ')
+      const matchedContexts = contexts.filter(value => entry.contexts?.includes(value))
+      const corpus = [entry.symbol, entry.description, curated ? entry.chooseWhen : '', ...(entry.capabilities ?? []), ...matchedContexts].join(' ')
       const hits = termHits(queryTerms, corpus)
       const exact = normalizedWords(entry.symbol).join(' ') === phrase
-      if (exact || (queryTerms.length && hits * 2 >= queryTerms.length)) {
-        const componentScore = exact ? 100 : Math.min(curated ? 64 : 34, (curated ? 39 : 10) + Math.round(25 * hits / queryTerms.length))
-        componentMatches.push({ ...entry, score: componentScore, matchedTerms: queryTerms.filter((term) => termHits([term], corpus)) })
+      if (exact || (queryTerms.length && hits * 2 >= queryTerms.length) || (!needle && matchedContexts.length)) {
+        const componentScore = exact ? 100 : Math.min(curated ? 74 : 34, (curated ? 39 : 10) + (queryTerms.length ? Math.round(25 * hits / queryTerms.length) : 0) + matchedContexts.length * 5)
+        componentMatches.push({ ...entry, score: componentScore, matchedContexts, contextCoverage: entry.contexts ? 'curated' : 'unknown', matchedTerms: queryTerms.filter((term) => termHits([term], corpus)) })
         score = Math.max(score, componentScore)
       }
     }
-    if (score > 0) scored.push({ record: filters.explain ? { ...record, match: { score, components: componentMatches.sort((a, b) => b.score - a.score), reason: componentMatches.length ? 'Public component name, description or positive usage guidance' : 'Module identity, positive guidance or attributed recipe' } } : record, score })
+    if (score > 0 || !needle) scored.push({ record: filters.explain ? { ...record, match: { score, contexts, contextCoverage: (record.componentGuidance ?? []).some(entry => entry.contexts) ? 'curated' : 'unknown', components: componentMatches.sort((a, b) => b.score - a.score), reason: componentMatches.length ? 'Public component name, description, positive usage guidance or applicable context' : 'Module identity, positive guidance or attributed recipe; uncurated contexts remain unknown' } } : record, score })
   }
 
   return scored
@@ -180,6 +186,7 @@ Options:
   --symbol=<Name>       exact public export name
   --peer=<package>      modules that require this optional peer
   --route=</path>       modules represented on this live preview route
+  --context=<context>  repeatable: ${CONTEXTS.join(', ')}
   --limit=<N>           return at most N matches (default 8)
   --explain             include matched components, reasons and API anchors
   --json                emit complete machine-readable records
@@ -187,7 +194,7 @@ Options:
 
 A text query is optional when at least one catalogue filter is present.`
 
-const VALUE_FLAGS = new Set(['tier', 'profile', 'status', 'module', 'symbol', 'peer', 'route', 'limit'])
+const VALUE_FLAGS = new Set(['tier', 'profile', 'status', 'module', 'symbol', 'peer', 'route', 'limit', 'context'])
 const BOOLEAN_FLAGS = new Set(['json', 'help', 'explain'])
 
 export function parseFinderArgs(args) {
@@ -207,7 +214,10 @@ export function parseFinderArgs(args) {
     if (!VALUE_FLAGS.has(rawName)) throw new Error(`unknown option --${rawName}`)
     const value = rest.join('=')
     if (!value) throw new Error(`--${rawName} requires a value written as --${rawName}=...`)
-    options[rawName] = value
+    if (rawName === 'context') {
+      if (!CONTEXTS.includes(value)) throw new Error(`unknown context ${value}; expected ${CONTEXTS.join(', ')}`)
+      options.context = [...(options.context ?? []), value]
+    } else options[rawName] = value
   }
   const limit = options.limit === undefined ? 8 : Number(options.limit)
   if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
@@ -229,7 +239,7 @@ export function runFinderCli(args = process.argv.slice(2), io = console) {
     return 0
   }
   const filters = Object.fromEntries(
-    ['tier', 'profile', 'status', 'module', 'symbol', 'peer', 'route']
+    ['tier', 'profile', 'status', 'module', 'symbol', 'peer', 'route', 'context']
       .filter((name) => parsed.options[name])
       .map((name) => [name, parsed.options[name]]),
   )
@@ -265,6 +275,11 @@ export function renderMatch(record) {
     lines.push(`  match    ${record.match.reason}`)
     for (const entry of record.match.components.slice(0, 3)) {
       lines.push(`  ${entry.symbol} — ${entry.chooseWhen}`, `    api    ${entry.apiDoc}`, `    compose ${entry.composition}`)
+      lines.push(`    guidance ${entry.guidanceSource === 'component' ? 'component' : 'module fallback'}`)
+      lines.push(`    context ${entry.contextCoverage ?? 'unknown'}${entry.matchedContexts?.length ? `: ${entry.matchedContexts.join(', ')}` : ''}`)
+      const unmatched = (record.match.contexts ?? []).filter(context => !entry.matchedContexts?.includes(context))
+      if (unmatched.length) lines.push(`    unmatched ${unmatched.join(', ')}`)
+      for (const workflow of entry.workflows ?? []) lines.push(`    source node_modules/themelia-ui/docs/generated/${workflow.source}`)
     }
   }
   return lines.join('\n')

package/scripts/consumer/install-skill.mjs

@@ -2,14 +2,15 @@
 /*
  * Installs the themelia-ui agent skill (which component to use, its exact import, what to
  * avoid) into a project's .agents/ and/or .claude/ skills. Offline: reads the copy shipped
- * in this package. Replaces a previous install atomically; never a hand-written skill.
+ * in this package. Stages replacements and rolls back caught write failures; never replaces a hand-written skill.
  *   node node_modules/themelia-ui/scripts/consumer/install-skill.mjs --project=. [--target=agents|claude|both]
  */
 import {
   cpSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync,
-  statSync,
+  lstatSync,
 } from 'node:fs'
-import { dirname, join, relative, resolve } from 'node:path'
+import { createHash } from 'node:crypto'
+import { dirname, join, relative, resolve, sep } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 const HERE = dirname(fileURLToPath(import.meta.url))
@@ -30,17 +31,78 @@ export const TARGET_DIRECTORIES = {
 
 /** Whether a destination may be replaced: absent, or carrying our marker. */
 export function mayOverwrite(destination) {
+  if (existsSync(destination) && lstatSync(destination).isSymbolicLink()) return false
   const skill = join(destination, 'SKILL.md')
-  if (!existsSync(skill)) return true
+  if (!existsSync(skill)) return !existsSync(destination) || readdirSync(destination).length === 0
   return readFileSync(skill, 'utf8').includes(GENERATED_MARKER)
 }
 
-export function installSkill({ project = '.', target = 'both', source = SOURCE } = {}) {
+const hashFile = (file) => createHash('sha256').update(readFileSync(file)).digest('hex')
+const inside = (root, file) => {
+  const path = relative(realpathSync(root), realpathSync(file))
+  return path !== '..' && !path.startsWith('../') && !path.startsWith('..\\')
+}
+
+/** A manifest is data, never permission to read paths outside the skill directory. */
+export function readSkillManifest(root) {
+  const manifest = JSON.parse(readFileSync(join(root, 'manifest.json'), 'utf8'))
+  if (manifest.schemaVersion !== 1 || typeof manifest.packageVersion !== 'string' || !manifest.files || typeof manifest.files !== 'object' || Array.isArray(manifest.files)) throw new Error('unsupported skill manifest')
+  if (!manifest.files['SKILL.md']) throw new Error('skill manifest has no SKILL.md')
+  for (const [path, hash] of Object.entries(manifest.files)) {
+    if (!path || path === 'manifest.json' || path.startsWith('/') || path.includes('\\') || path.split('/').some((part) => !part || part === '.' || part === '..') || !/^[a-f0-9]{64}$/.test(hash)) throw new Error(`invalid skill manifest path or hash: ${path}`)
+  }
+  return manifest
+}
+
+/** Inspect installed copies without changing application policy or generated bytes. */
+export function checkSkill({ project = '.', target = 'both', source = SOURCE } = {}) {
+  const names = target === 'both' ? ['agents', 'claude'] : [target]
+  if (names.some((name) => !(name in TARGET_DIRECTORIES))) throw new Error(`unknown --target=${target}; expected agents, claude or both`)
+  let expected
+  try {
+    expected = readSkillManifest(source)
+    const recorded = Object.keys(expected.files).sort()
+    const actual = listFiles(source).filter(file => file !== 'manifest.json')
+    if (JSON.stringify(recorded) !== JSON.stringify(actual)) throw new Error('packaged skill inventory differs from its manifest')
+    for (const [file, hash] of Object.entries(expected.files)) {
+      const path = join(source, file)
+      if (!inside(source, path) || hashFile(path) !== hash) throw new Error(`packaged skill differs from its manifest: ${file}`)
+    }
+  } catch (error) { return { packageVersion: null, targets: [], error: error.message, exitCode: 2 } }
+  const targets = names.map((name) => {
+    const destination = resolve(project, TARGET_DIRECTORIES[name])
+    const item = { target: name, status: 'missing', installedVersion: null, changedFiles: [], locallyModifiedFiles: [] }
+    if (!existsSync(destination)) return item
+    if (!mayOverwrite(destination)) return { ...item, status: 'unmanaged' }
+    let installed
+    try { installed = readSkillManifest(destination) } catch {
+      item.locallyModifiedFiles = listFiles(destination).filter(file => file !== 'manifest.json').filter(file => {
+        try { return !expected.files[file] || !inside(destination, join(destination, file)) || hashFile(join(destination, file)) !== expected.files[file] } catch { return true }
+      })
+      return { ...item, status: 'stale', changedFiles: ['manifest.json', ...item.locallyModifiedFiles] }
+    }
+    item.installedVersion = installed.packageVersion
+    item.locallyModifiedFiles = [...new Set([...Object.keys(installed.files), ...listFiles(destination).filter(file => file !== 'manifest.json')])].filter(file => {
+      try { return !installed.files[file] || !inside(destination, join(destination, file)) || hashFile(join(destination, file)) !== installed.files[file] } catch { return true }
+    }).sort()
+    const files = new Set([...Object.keys(expected.files), ...listFiles(destination).filter(file => file !== 'manifest.json')])
+    item.changedFiles = [...files].filter((file) => {
+      try { return !expected.files[file] || !inside(destination, join(destination, file)) || hashFile(join(destination, file)) !== expected.files[file] } catch { return true }
+    }).sort()
+    if (JSON.stringify(installed.files) !== JSON.stringify(expected.files)) item.changedFiles.push('manifest.json')
+    item.status = installed.packageVersion !== expected.packageVersion ? 'stale' : item.changedFiles.length ? 'modified' : 'current'
+    return item
+  })
+  return { packageVersion: expected.packageVersion, targets, exitCode: targets.every((item) => item.status === 'current') ? 0 : 1 }
+}
+
+export function installSkill({ project = '.', target = 'both', source = SOURCE, overwriteModified = false } = {}) {
   const targets = target === 'both' ? ['agents', 'claude'] : [target]
   if (targets.some((name) => !(name in TARGET_DIRECTORIES))) {
     throw new Error(`unknown --target=${target}; expected agents, claude or both`)
   }
   if (!existsSync(source)) throw new Error(`the packaged skill is missing at ${source}`)
+  for (const file of listFiles(source)) if (lstatSync(join(source, file)).isSymbolicLink()) throw new Error(`skill source contains a symlink: ${file}`)
 
   const nonce = `${process.pid}-${Date.now()}`
   const destinations = targets.map((name, index) => {
@@ -67,6 +129,10 @@ export function installSkill({ project = '.', target = 'both', source = SOURCE }
       )
     }
   }
+  const freshness = checkSkill({ project, target, source })
+  if (freshness.exitCode === 2) throw new Error(`invalid packaged skill metadata: ${freshness.error}`)
+  const modified = freshness.targets.filter(item => item.locallyModifiedFiles?.length)
+  if (modified.length && !overwriteModified) throw new Error(`modified generated files: ${modified.map(item => `${item.target}: ${item.locallyModifiedFiles.join(', ')}`).join('; ')}. Review these changes and preserve application policy separately; --overwrite-modified explicitly replaces them.`)
 
   try {
     for (const item of destinations) {
@@ -78,8 +144,6 @@ export function installSkill({ project = '.', target = 'both', source = SOURCE }
       renameSync(item.stage, item.destination)
       item.committed = true
     }
-    for (const item of destinations) rmSync(item.backup, { recursive: true, force: true })
-    return destinations.map(({ destination }) => destination)
   } catch (error) {
     for (const item of [...destinations].reverse()) {
       rmSync(item.stage, { recursive: true, force: true })
@@ -88,6 +152,12 @@ export function installSkill({ project = '.', target = 'both', source = SOURCE }
     }
     throw error
   }
+  // Commit is complete; discarded backups cannot support a later rollback.
+  for (const item of destinations) {
+    try { rmSync(item.backup, { recursive: true, force: true }) }
+    catch (error) { throw new Error(`Skill copies installed; backup cleanup failed at ${item.backup}: ${error.message}`) }
+  }
+  return destinations.map(({ destination }) => destination)
 }
 
 /** Every file under a directory, relative and sorted — for tests and for the summary. */
@@ -96,8 +166,8 @@ export function listFiles(root) {
   const walk = (dir) => {
     for (const entry of readdirSync(dir)) {
       const full = join(dir, entry)
-      if (statSync(full).isDirectory()) walk(full)
-      else out.push(relative(root, full))
+      if (lstatSync(full).isDirectory()) walk(full)
+      else out.push(relative(root, full).split(sep).join('/'))
     }
   }
   if (existsSync(root)) walk(root)
@@ -122,10 +192,13 @@ function runFromCommandLine(moduleUrl) {
 
 const invokedDirectly = runFromCommandLine(import.meta.url)
 if (invokedDirectly) {
-  const USAGE = `usage: install-skill.mjs [--project=<directory>] [--target=agents|claude|both]
+  const USAGE = `usage: install-skill.mjs [--project=<directory>] [--target=agents|claude|both] [--check] [--json] [--overwrite-modified]
 
 Copies the packaged themelia-ui consumer skill into a project. Existing generated
-copies are replaced atomically; a same-named hand-written skill is never overwritten.`
+copies are staged before replacement; caught write failures restore their backups.
+A same-named hand-written skill is never overwritten.
+--check is read-only: 0 current, 1 missing/drift/unmanaged, 2 invalid package metadata.
+--overwrite-modified replaces reviewed local changes in a generated copy; unmanaged skills remain protected.`
   try {
     const options = { project: '.', target: 'both' }
     for (const argument of process.argv.slice(2)) {
@@ -133,10 +206,19 @@ copies are replaced atomically; a same-named hand-written skill is never overwri
         console.log(USAGE)
         process.exit(0)
       }
+      if (argument === '--check' || argument === '--json') { options[argument.slice(2)] = true; continue }
+      if (argument === '--overwrite-modified') { options.overwriteModified = true; continue }
       const match = argument.match(/^--(project|target)=(.+)$/)
       if (!match) throw new Error(`unknown argument ${argument}\n\n${USAGE}`)
       options[match[1]] = match[2]
     }
+    if (options.json && !options.check) throw new Error('--json requires --check')
+    if (options.check) {
+      const report = checkSkill(options)
+      console.log(options.json ? JSON.stringify(report, null, 2) : report.error ?? report.targets.map(item => `${item.target}: ${item.status} (installed ${item.installedVersion ?? 'unknown'}, package ${report.packageVersion})${item.changedFiles.length ? ` — ${item.changedFiles.join(', ')}` : ''}`).join('\n'))
+      if (report.exitCode === 1 && !options.json) console.log('Review modified/unmanaged copies; reinstall generated copies with install-skill.mjs --project=<directory>. Application policy stays in a separate skill.')
+      process.exit(report.exitCode)
+    }
     const installed = installSkill(options)
     for (const destination of installed) {
       console.log(`installed ${listFiles(destination).length} file(s) into ${relative(process.cwd(), destination) || '.'}`)

package/src/styles/TOKENS.md

@@ -2,9 +2,10 @@
 
 The theme is `src/styles/theme/*.css`: about eighty variables, declared once at `:root`. Every
 colour is `light-dark(light, dark)`, and the element's `color-scheme` (set by `.light`,
-`.dark`, `data-theme` or the operating system) picks the half. Nothing below `:root`
-declares a theme variable again, so a value set anywhere reaches every reader below it, and
-a dark region inside a light page needs no second set of values.
+`.dark`, `data-theme` or the operating system) picks the half. Component styles inherit
+theme defaults rather than redeclaring them. Explicit scope overrides and density presets
+replace the corresponding inherited values on their regions. A dark region inside a light
+page needs no second set of colour declarations.
 
 Components read the theme and compute the rest in the rule that uses it. The package's checks
 fail on a `var()` nothing defines, a literal colour, radius, spacing or hairline in a