themelia-ui 3.0.0 → 3.2.0

package/scripts/consumer/codemod.mjs

@@ -3,13 +3,16 @@
  * Rewrites a consumer's source for a themelia-ui upgrade, from the migration maps shipped in
  * docs/generated/. Preview with --dry-run, then apply (in this repo: `npm run codemod`):
  *   node node_modules/themelia-ui/scripts/consumer/codemod.mjs [--dry-run] src/
- * Rewrites moved subpaths, removed-barrel imports, renamed tokens and utility classes.
+ * Rewrites moved subpaths, removed-barrel imports, renamed tokens and utility classes, and
+ * removes obsolete kit stylesheet imports, which components now bring themselves.
  * Reports without editing: removed tokens, overrides where old names merged (so one rule
- * may now set --radius twice), utilities whose meaning changed, ambiguous symbols.
+ * may now set --radius twice), utilities whose meaning changed, ambiguous symbols, and kit
+ * 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')
@@ -21,33 +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 pkg = JSON.parse(readFileSync(resolve(dir, '..', '..', 'package.json'), 'utf8'))
-  /* A moved family's stylesheet moves with it, where the new one is published. */
-  const sheets = new Map()
-  for (const [from, to] of Object.entries(codemod.moves ?? {})) {
-    const subpath = `.${to.slice(pkg.name.length)}.css`
-    if (from.startsWith(`${pkg.name}/`) && pkg.exports?.[subpath]) sheets.set(`${from}.css`, `${to}.css`)
-  }
-  return {
-    /* Where a reader finds the rest, as a path from wherever the codemod was run. */
-    doc: relative(process.cwd(), resolve(dir, 'migration.md')),
-    moves: new Map([...Object.entries(codemod.moves ?? {}), ...sheets]),
-    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
@@ -100,6 +77,38 @@ export function rewriteSource(text, file, maps) {
     }
   }
 
+  /*
+   * Components bring their own CSS in a bundler. Side-effect script imports go; module CSS
+   * paths are no longer published, so plain CSS @imports go too. A directly linked page uses
+   * style.css instead. Complex references are reported for manual review.
+   */
+  const sheet = `${escape(maps.name)}/(?!core\\.css["']|tailwind\\.css["'])[^"']+\\.css`
+  const moduleSheet = `${escape(maps.name)}/(?:primitives|(?:base|layout|features|blocks|patterns|admin)/[^"']+)\\.css`
+  if (isScript) {
+    next = next.replace(new RegExp(`^[ \\t]*import\\s*(["'])(${sheet})\\1;?[ \\t]*\\r?\\n?`, 'gm'), (line, quote, specifier) => {
+      changes.push(`stylesheet      ${file}  removed ${specifier} — components bring their own CSS`)
+      return ''
+    })
+    for (const match of next.matchAll(new RegExp(`(["'])(${moduleSheet})\\1`, 'g'))) {
+      notes.push(`stylesheet      ${file}  ${match[2]} — this module stylesheet is no longer published; remove the import`)
+    }
+  }
+  if (isStyle) {
+    next = next.replace(new RegExp(`^[ \\t]*@import\\s*(["'])(${moduleSheet})\\1\\s*;?[ \\t]*(?:\\r?\\n|$)`, 'gm'), (line, quote, specifier) => {
+      changes.push(`stylesheet      ${file}  removed ${specifier} — module CSS is no longer published`)
+      notes.push(`stylesheet      ${file}  if this page has no bundler, link ${maps.name}/style.css instead`)
+      return ''
+    })
+  }
+  if (isStyle || isMarkup) {
+    for (const match of next.matchAll(new RegExp(`(["'])(${sheet})\\1`, 'g'))) {
+      notes.push(`stylesheet      ${file}  ${match[2]} — in a bundled app this loads CSS twice; direct links without a bundler use ${maps.name}/style.css`)
+    }
+  }
+  if (isStyle && new RegExp(`@import\\s*(["'])${escape(maps.name)}/core\\.css\\1`).test(next)) {
+    notes.push(`stylesheet      ${file}  ${maps.name}/core.css — the components import core.css themselves; an @import here inlines a second copy`)
+  }
+
   if (isScript) {
     /* A named import from a removed barrel becomes one import per owning subpath. */
     next = next.replace(
@@ -215,7 +224,11 @@ export function runCodemod(argv = process.argv.slice(2), { maps = loadMaps(), lo
 
   const changes = []
   const notes = []
-  for (const file of targets.flatMap((target) => walk(target))) {
+  /* A listed path the project does not have is reported, so one command can cover several layouts. */
+  const found = targets.filter((target) => existsSync(target))
+  for (const target of targets.filter((target) => !existsSync(target))) log(`  not found       ${target} — skipped`)
+  if (!found.length) return 1
+  for (const file of found.flatMap((target) => walk(target))) {
     const original = readFileSync(file, 'utf8')
     const result = rewriteSource(original, file, maps)
     changes.push(...result.changes)
@@ -226,10 +239,15 @@ export function runCodemod(argv = process.argv.slice(2), { maps = loadMaps(), lo
   const uniqueNotes = [...new Set(notes)].sort()
   for (const line of changes.sort()) log(`  ${line}`)
   for (const line of uniqueNotes) log(`  ${line}`)
+  const removedSheets = changes.some((line) => line.startsWith('stylesheet'))
   log(
     `\n${dryRun ? 'would apply' : 'applied'} ${changes.length} rewrite(s)` +
       (uniqueNotes.length ? `, left ${uniqueNotes.length} for you` : '') +
-      `.\n\nNot attempted: \`asChild\` → \`render\`, the provider changes, and the CSS split. See\n${maps.doc}.`,
+      `.\n\nNot attempted: \`asChild\` → \`render\` and the provider changes. See\n${maps.doc}.` +
+      (removedSheets
+        ? '\n\nComponents now bring their own CSS. If the app renders on the server with Vite (Astro, React Router,\n' +
+          'TanStack Start, Vike), add themelia-ui to `ssr.noExternal`, or the server render has no kit CSS.'
+        : ''),
   )
   return 0
 }

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

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /*
- * Finds which themelia-ui component to use, with its exact JS and CSS imports, from the
+ * Finds which themelia-ui component to use, with its exact import, from the
  * catalogue shipped in this package (offline). `--help` lists the filters.
  *   node node_modules/themelia-ui/scripts/consumer/find-component.mjs "bulk selection"
  *   node node_modules/themelia-ui/scripts/consumer/find-component.mjs --tier=base --json
@@ -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) => ({
@@ -19,7 +20,6 @@ const toRecord = (entry) => ({
   profile: entry.profile,
   status: entry.status,
   publicImport: entry.import,
-  cssImport: entry.css,
   publicSymbols: entry.symbols,
   components: entry.components,
   componentGuidance: entry.componentGuidance,
@@ -37,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 ?? ''))
@@ -88,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 = []
@@ -105,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
     }
@@ -124,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 = [
@@ -152,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
@@ -181,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
@@ -188,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) {
@@ -208,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) {
@@ -230,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]]),
   )
@@ -257,16 +266,20 @@ export function renderMatch(record) {
     `${record.module}  (${record.tier} · ${record.profile}${record.status ? ` · ${record.status}` : ''})`,
     `  import   ${record.publicImport}`,
   ]
-  if (record.cssImport ?? record.css) lines.push(`  css      ${record.cssImport ?? record.css}`)
   if (record.apiDoc) lines.push(`  api      node_modules/themelia-ui/docs/generated/${record.apiDoc}`)
   if (record.chooseWhen) lines.push(`  choose   ${text(record.chooseWhen)}`)
   if (record.avoidWhen) lines.push(`  avoid    ${text(record.avoidWhen)}`)
-  if (record.composeWith?.length) lines.push(`  with     ${text(record.composeWith)} — import its JS and CSS too`)
+  if (record.composeWith?.length) lines.push(`  with     ${text(record.composeWith)} — import it too`)
   if (record.alternatives?.length) lines.push(`  instead  ${text(record.alternatives)}`)
   if (record.match) {
     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')