@weft-js/cli 0.0.0-stage → 0.1.0

package/src/style.mjs

@@ -0,0 +1,320 @@
+// `weft style find|explain|matrix` and the style D-codes (research 23 §2.4, §3). The matrix comes from the installed
+// weft (`@weft-js/core/style/matrix`): the project is scanned with its compiler, so the CLI, the MCP tools and the Vite
+// plugin's `.weft/styles.json` agree. D020 (class soup) is found here, on the source text: groups never write a class.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { diagnostic, locate, positions } from './diag.mjs'
+import { discover } from './files.mjs'
+import { loadConfig } from './load-config.mjs'
+import { isTestFile } from './tests.mjs'
+import { loadCompiler, resolveWeft } from './weft.mjs'
+
+const usageError = message => Object.assign(new Error(message), { code: 'E_USAGE' })
+
+/** The installed weft's matrix module, or null when this weft has no style groups. */
+export async function styleModule(weft) {
+  const target = weft.pkg.exports?.['./style/matrix']
+  if (typeof target !== 'string') return null
+  return import(pathToFileURL(join(weft.dir, target)).href)
+}
+
+/** Source files that can define or use groups: components and plain modules, not tests. */
+export function styleFiles(root, config = {}) {
+  const exclude = [...(config.check?.exclude ?? []), ...(config.scope?.forbid ?? [])]
+  return discover(root, { include: ['**/*.{ts,tsx,jsx,mts}'], exclude }).filter(f => !isTestFile(f) && !f.endsWith('.d.ts'))
+}
+
+/**
+ * Scan the project and build the matrix. `write`: also write `.weft/styles.json` (when the project has groups, or the
+ * file is already there).
+ */
+export async function styleMatrix(root, { write = false } = {}) {
+  const weft = resolveWeft(root)
+  const mod = await styleModule(weft)
+  if (!mod) throw Object.assign(new Error(`weft@${weft.version} has no style groups (@weft-js/core/style/matrix)`), { code: 'E_NO_STYLE' })
+  const { config } = await loadConfig(root)
+  const compiler = loadCompiler(weft)
+  const scan = mod.scanProject(root, styleFiles(root, config), (...a) => compiler.transform(...a))
+  const matrix = mod.buildMatrix(scan.groups, scan.uses)
+  const file = join(root, '.weft', 'styles.json')
+  if (write && (scan.groups.length || existsSync(file))) writeMatrixFile(root, matrix)
+  return { matrix, scan, mod, file }
+}
+
+export function writeMatrixFile(root, matrix) {
+  const file = join(root, '.weft', 'styles.json')
+  const text = `${JSON.stringify(matrix, null, 2)}\n`
+  if (existsSync(file) && readFileSync(file, 'utf8') === text) return false
+  mkdirSync(join(root, '.weft'), { recursive: true })
+  writeFileSync(file, text)
+  return true
+}
+
+const words = s => s.toLowerCase().split(/[\s\-_.:/=,]+|(?<=[a-z])(?=[A-Z])/).filter(Boolean)
+
+/** Edit distance with adjacent swaps as one edit (`ordre` → `order`). */
+function distance(a, b) {
+  const d = Array.from({ length: a.length + 1 }, (_, i) => Array.from({ length: b.length + 1 }, (__, j) => (i ? (j ? 0 : i) : j)))
+  for (let i = 1; i <= a.length; i++)
+    for (let j = 1; j <= b.length; j++) {
+      d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1))
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) d[i][j] = Math.min(d[i][j], d[i - 2][j - 2] + 1)
+    }
+  return d[a.length][b.length]
+}
+
+/** The names closest to `word` (edit distance within a third of its length, or containing it). */
+export function closest(word, names, n = 3) {
+  const w = word.toLowerCase()
+  const limit = Math.max(1, Math.floor(w.length / 3))
+  return names
+    .map(x => [distance(w, x.toLowerCase()), x])
+    .filter(([d, x]) => d <= limit || x.toLowerCase().includes(w) || w.includes(x.toLowerCase()))
+    .sort((a, b) => a[0] - b[0])
+    .slice(0, n)
+    .map(([, x]) => x)
+}
+
+/**
+ * `weft style find <query>`: the groups that fit, best first. Every word of the query must hit the group's name,
+ * doc, parts, axes, values, states or tokens (a name word one typo off counts); with no such group, groups that hit
+ * any word.
+ */
+export function findGroups(matrix, query) {
+  const terms = words(query ?? '')
+  if (!terms.length) throw usageError('weft style find <query>: say what the thing is (`card`, `status badge`, `critical`)')
+  const score = (name, g) => {
+    const fields = [
+      [words(name), 30],
+      [words(g.doc ?? ''), 10],
+      [[...g.parts, ...g.states, ...Object.keys(g.axes)].flatMap(words), 8],
+      [Object.values(g.axes).flatMap(v => (Array.isArray(v) ? v : [])).flatMap(words), 6],
+      [g.tokens.flatMap(words), 4],
+    ]
+    let total = name === query ? 100 : 0
+    const matched = []
+    let hits = 0
+    for (const t of terms) {
+      let best = 0
+      let why = null
+      for (const [ws, weight] of fields) {
+        for (const w of ws) {
+          const s = w === t ? weight : w.startsWith(t) || (t.length > 3 && w.includes(t)) ? weight * 0.7 : weight >= 30 && t.length > 3 && distance(w, t) === 1 ? weight * 0.5 : 0
+          if (s > best) [best, why] = [s, w]
+        }
+      }
+      if (best) {
+        hits++
+        matched.push(why)
+      }
+      total += best
+    }
+    return { total, hits, matched: [...new Set(matched)] }
+  }
+  const all = Object.entries(matrix.groups).map(([name, g]) => ({ name, g, ...score(name, g) })).filter(x => x.total > 0)
+  const full = all.filter(x => x.hits === terms.length)
+  const ranked = (full.length ? full : all).sort((a, b) => b.total - a.total || a.name.localeCompare(b.name))
+  // A name or doc hit outranks groups that only share a token (`row` → product-row, not every `layout: row`).
+  const picked = ranked.filter(x => x.total >= (ranked[0]?.total ?? 0) / 4)
+  return {
+    query,
+    groups: picked.map(({ name, g, total, matched }) => ({
+      name,
+      score: Math.round(total),
+      matched,
+      doc: g.doc,
+      file: g.file,
+      import: g.binding && g.exported ? { name: g.binding, from: g.file.replace(/:\d+$/, '') } : null,
+      axes: g.axes,
+      defaults: g.defaults,
+      parts: g.parts,
+      states: g.states,
+      uses: g.used.length,
+      similar: matrix.similar.filter(s => s[0] === name || s[1] === name).map(s => (s[0] === name ? s[1] : s[0])),
+    })),
+    partial: !full.length && all.length > 0,
+    total: Object.keys(matrix.groups).length,
+  }
+}
+
+const ARIA = new Set(['selected', 'pressed', 'checked', 'expanded', 'current', 'invalid', 'busy'])
+
+/**
+ * Read `order-card`, `order-card.title`, `order-card[status=late][selected]`, or a DOM selector
+ * (`[data-g="order-card"][data-status="late"] [data-part="title"]`, `[aria-selected="true"]`, `[data-accent~="radius:round"]`).
+ */
+export function parseTarget(target) {
+  const t = (target ?? '').trim()
+  if (!t) throw usageError('weft style explain <group|selector>: a group name (`order-card`), `order-card.title`, or a selector')
+  const out = { group: null, part: null, axes: {}, states: [], accent: {} }
+  const head = /^([a-z][\w-]*)(?:\.([\w-]+))?/i.exec(t)
+  if (head && !t.startsWith('[')) {
+    out.group = head[1]
+    out.part = head[2] ?? null
+  }
+  for (const m of t.matchAll(/\[\s*([\w-]+)\s*(?:[~|^$*]?=\s*(?:"([^"]*)"|'([^']*)'|([^\]\s]*)))?\s*\]/g)) {
+    const [, attr, ...vals] = m
+    const value = vals.find(v => v !== undefined)
+    if (attr === 'data-g') out.group = value
+    else if (attr === 'data-part') out.part = value
+    else if (attr === 'data-accent') for (const w of (value ?? '').split(/\s+/).filter(Boolean)) { const [k, v] = w.split(':'); out.accent[k] = v }
+    else if (attr.startsWith('aria-')) { if (value !== 'false') out.states.push(attr.slice(5)) }
+    else {
+      const name = attr.replace(/^data-/, '')
+      if (value === undefined || value === '') out.states.push(name)
+      else out.axes[name] = value
+    }
+  }
+  if (!out.group) throw usageError(`weft style explain: no group in \`${t}\``)
+  return out
+}
+
+/**
+ * `weft style explain <target>`: the group, and for the selection (defaults filled in) every declaration on the root
+ * and its parts in cascade order, with where each came from, plus the CSS that selection emits.
+ * @param {{ axes?: Record<string, string>, states?: string[], accent?: Record<string, string>, part?: string }} [extra]
+ */
+export function explainTarget({ matrix, scan, mod }, target, extra = {}) {
+  const t = parseTarget(target)
+  const g = matrix.groups[t.group]
+  if (!g) {
+    const near = closest(t.group, Object.keys(matrix.groups))
+    throw Object.assign(new Error(`D025 no group \`${t.group}\`${near.length ? `; did you mean ${near.map(n => `\`${n}\``).join(' or ')}?` : ''} (\`weft style find\` searches by what it is)`), { code: 'E_UNKNOWN_GROUP' })
+  }
+  const source = scan.groups.find(s => s.name === t.group)
+  // A state written as data-x="…" in a selector, or an axis passed as --x: sort them by what the group has.
+  const axes = { ...t.axes, ...extra.axes }
+  const states = [...t.states, ...(extra.states ?? [])]
+  for (const [k, v] of Object.entries(axes)) if (!(k in g.axes) && g.states.includes(k) && (v === 'true' || v === '')) { delete axes[k]; states.push(k) }
+  const selection = { axes, states: [...new Set(states)],accent: { ...t.accent, ...extra.accent }, part: extra.part ?? t.part ?? undefined }
+  let explained
+  try {
+    explained = mod.explainGroup(source, selection)
+  } catch (e) {
+    if (e.constructor?.name === 'GroupError') throw Object.assign(new Error(`D025 ${e.message}`), { code: 'E_UNKNOWN_NAME' })
+    throw e
+  }
+  const sel = explained.selection
+  const sites = g.used.filter(u => !u.part && Object.entries(sel.axes).every(([a, v]) => !u.axes[a] || u.axes[a] === 'dynamic' || u.axes[a].includes(v)))
+  return {
+    group: t.group,
+    doc: g.doc,
+    file: g.file,
+    axes: g.axes,
+    defaults: g.defaults,
+    parts: g.parts,
+    states: g.states,
+    contextTone: g.contextTone,
+    selection: sel,
+    attributes: attributesOf(t.group, sel, selection.part),
+    elements: explained.elements,
+    css: explained.css,
+    sites,
+    accents: g.accents,
+    similar: matrix.similar.filter(s => s[0] === t.group || s[1] === t.group),
+  }
+}
+
+/** What the selection looks like in the DOM, as a person would find it in devtools. */
+function attributesOf(group, sel, part) {
+  const root = [`data-g="${group}"`, ...Object.entries(sel.axes).map(([a, v]) => `data-${a}="${v}"`), ...sel.states.map(s => (ARIA.has(s) ? `aria-${s}="true"` : `data-${s}`))]
+  const accent = Object.entries(sel.accent).sort(([a], [b]) => (a < b ? -1 : 1)).map(([k, v]) => `${k}:${v}`).join(' ')
+  if (accent) root.push(`data-accent="${accent}"`)
+  return { root: root.join(' '), ...(part ? { part: `data-part="${part}"` } : {}) }
+}
+
+export function formatFind(r) {
+  if (!r.groups.length) return `no group fits "${r.query}" (${r.total} groups). Define one with group() from @weft-js/core/style; \`weft docs style\` has the rules.`
+  const lines = r.groups.map(g => {
+    const axes = Object.entries(g.axes).map(([a, v]) => `${a}: ${Array.isArray(v) ? v.join('|') : v}`).join(' · ')
+    return `${g.name.padEnd(18)} ${g.file}${g.doc ? `\n    ${g.doc}` : ''}\n    ${[axes, g.parts.length ? `parts: ${g.parts.join(', ')}` : '', g.states.length ? `states: ${g.states.join(', ')}` : '', `${g.uses} uses`].filter(Boolean).join(' · ')}`
+  })
+  return (r.partial ? `no group matches every word of "${r.query}"; closest:\n` : '') + lines.join('\n')
+}
+
+export function formatExplain(r) {
+  const out = [`${r.group}  ${r.file}${r.doc ? `  — ${r.doc}` : ''}`, `  <el ${r.attributes.root}>${r.attributes.part ? `  part: <el ${r.attributes.part}>` : ''}`]
+  for (const el of r.elements) {
+    if (!el.decls.length) continue
+    out.push(`  ${el.element}:`)
+    for (const d of el.decls) out.push(`    ${d.overridden ? '~' : ' '} ${`${d.prop}: ${d.value}`.padEnd(64)} ← ${d.from} (${d.at})${d.overridden ? ', overridden' : ''}`)
+  }
+  out.push('', r.css.trimEnd())
+  if (r.contextTone) out.push('', 'Reads its tone from the nearest data-tone (warp context tone).')
+  return out.join('\n')
+}
+
+/** Long class lists are how Tailwind is written, so D020 stays out of an app that chose it. */
+export function usesTailwind(root) {
+  const file = join(root, 'package.json')
+  if (!existsSync(file)) return false
+  const { dependencies, devDependencies } = JSON.parse(readFileSync(file, 'utf8'))
+  return 'tailwindcss' in { ...dependencies, ...devDependencies }
+}
+
+/**
+ * D020: class soup. A static `class`/`className` with more than 8 classes, or one class list (4+ classes, any order)
+ * in two or more places. The fix names a group after the component and element.
+ * @param {{ rel: string, text: string }[]} files
+ */
+export function classSoup(files) {
+  const out = []
+  const lists = new Map()
+  const attr = /\b(class|className)\s*=\s*(?:"([^"]*)"|'([^']*)'|\{\s*(["'`])([^"'`$]*)\4\s*\})/g
+  for (const { rel, text } of files) {
+    const pos = positions(text)
+    const named = new Map()
+    for (const m of text.matchAll(attr)) {
+      const value = m[2] ?? m[3] ?? m[5] ?? ''
+      const classes = value.split(/\s+/).filter(Boolean)
+      if (!classes.length) continue
+      const before = text.slice(0, m.index)
+      const component = [...before.matchAll(/(?:function\s+([A-Z]\w*)|(?:const|let)\s+([A-Z]\w*)\s*=)/g)].at(-1)
+      const tag = [...before.matchAll(/<([a-z][\w-]*)\b/g)].at(-1)?.[1] ?? 'div'
+      const base = component ? (component[1] ?? component[2]).replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase() : rel.replace(/^.*\//, '').replace(/\.\w+$/, '').toLowerCase()
+      const n = (named.get(base) ?? 0) + 1
+      named.set(base, n)
+      const name = n === 1 ? base : `${base}-${tag}`
+      const at = { span: pos.span(m.index, m.index + m[0].length), offset: [m.index, m.index + m[0].length] }
+      const site = { rel, at, name, count: classes.length }
+      if (classes.length > 8) out.push(diagnostic({ code: 'D020', severity: 'warning', file: rel, ...at, why: `<${tag}> carries ${classes.length} classes: nobody can read what it is or which variation it's in.`, help: groupHelp(name) }))
+      if (classes.length >= 4) {
+        const key = [...classes].sort().join(' ')
+        lists.set(key, [...(lists.get(key) ?? []), site])
+      }
+    }
+  }
+  for (const sites of lists.values()) {
+    if (sites.length < 2) continue
+    for (const s of sites.slice(1)) {
+      const first = sites[0]
+      out.push(diagnostic({
+        code: 'D020', severity: 'warning', file: s.rel, ...s.at,
+        why: `The same ${s.count} classes are written in ${sites.length} places (first at ${first.rel}:${first.at.span[0]}): one look, copied by hand.`,
+        help: groupHelp(first.name),
+        related: sites.filter(x => x !== s).map(x => ({ file: x.rel, span: x.at.span })),
+      }))
+    }
+  }
+  return out
+}
+
+const groupHelp = name => `Extract a group: \`export const ${name.replace(/-(\w)/g, (_, c) => c.toUpperCase())} = group('${name}', { base: { … } })\` and spread it (\`{...${name.replace(/-(\w)/g, (_, c) => c.toUpperCase())}()}\`). \`weft style find\` first: one may already fit.`
+
+/** Matrix diagnostics (D021–D025) as `weft check` diagnostics, located on the group or the site. */
+export function matrixDiagnostics(root, matrix) {
+  const texts = new Map()
+  const text = file => {
+    if (!texts.has(file)) texts.set(file, existsSync(join(root, file)) ? readFileSync(join(root, file), 'utf8') : '')
+    return texts.get(file)
+  }
+  return matrix.diagnostics.map(d => {
+    const lines = text(d.file).split('\n')
+    const line = Math.max(1, Math.min(d.line, lines.length))
+    const col = (lines[line - 1]?.search(/\S/) ?? 0) + 1
+    const loc = d.line ? { span: [line, col, line, (lines[line - 1]?.length ?? 0) + 1] } : locate(text(d.file), d.group)
+    return diagnostic({ code: d.code, severity: d.severity, file: d.file, ...loc, why: d.message, help: d.help })
+  })
+}

package/src/surface-checks.mjs

@@ -0,0 +1,218 @@
+// Surfaces in `weft check` (research 33 §8): X002 and X009–X012 for surfaces and their text, X040 and X041 for per-glyph
+// markup, and P101 for a surface that needs a slot nothing provides. X001, X003 and X004 need the live mirror, so
+// @weft-js/core/surface reports those in dev. `listSurfaces` is the catalog behind `weft surfaces` and the MCP tool.
+
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import ts from 'typescript'
+import { diagnostic, positions } from './diag.mjs'
+import { discover } from './files.mjs'
+import { scanJsx } from './jsx-scan.mjs'
+
+const CODE = /\.[cm]?[jt]sx?$/
+const SYSTEM = /(^|,)\s*["']?(system-ui|-apple-system|BlinkMacSystemFont)["']?\s*(,|$)/i
+const GENERIC_ONLY = /^\s*(serif|sans-serif|monospace|cursive|fantasy)\s*$/i
+const GLYPHS = 200
+
+const parse = (rel, text) => ts.createSourceFile(rel, text, ts.ScriptTarget.Latest, true, /\.[jt]sx$/.test(rel) ? ts.ScriptKind.TSX : ts.ScriptKind.TS)
+
+const prop = (object, name) => object.properties.find(p => (ts.isPropertyAssignment(p) || ts.isMethodDeclaration(p) || ts.isShorthandPropertyAssignment(p)) && p.name.getText() === name)
+const stringOf = node => (node && (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) ? node.text : undefined)
+
+function walk(node, visit) {
+  visit(node)
+  ts.forEachChild(node, c => walk(c, visit))
+}
+
+/** Every `defineSurface({ ... })` call in a file: the call, its options and the name of `setup`'s `s`. */
+function surfaceCalls(sf) {
+  const out = []
+  walk(sf, node => {
+    if (!ts.isCallExpression(node) || node.expression.getText() !== 'defineSurface') return
+    const def = node.arguments[0]
+    if (!def || !ts.isObjectLiteralExpression(def)) return
+    const setup = prop(def, 'setup')
+    const fn = setup && (ts.isMethodDeclaration(setup) ? setup : setup.initializer)
+    out.push({ node, def, fn, param: fn?.parameters?.[0]?.name.getText() })
+  })
+  return out
+}
+
+function propNames(call) {
+  const schema = prop(call.def, 'props')?.initializer
+  if (schema && ts.isCallExpression(schema) && schema.expression.getText().endsWith('.object') && ts.isObjectLiteralExpression(schema.arguments[0] ?? schema)) return schema.arguments[0].properties.map(p => p.name.getText())
+  const type = call.node.typeArguments?.[0]
+  if (type && ts.isTypeLiteralNode(type)) return type.members.map(m => m.name?.getText()).filter(Boolean)
+  return []
+}
+
+/** What the project's `defineSurface` calls declare, read statically: nothing needs to build. */
+export function listSurfaces(root, { exclude = [] } = {}) {
+  const out = []
+  for (const rel of discover(root, { include: ['src/**/*.{ts,tsx,js,jsx}'], exclude })) {
+    const text = readFileSync(join(root, rel), 'utf8')
+    if (!text.includes('defineSurface')) continue
+    const sf = parse(rel, text)
+    for (const call of surfaceCalls(sf)) {
+      const line = sf.getLineAndCharacterOfPosition(call.node.getStart(sf)).line + 1
+      out.push({ name: stringOf(prop(call.def, 'name')?.initializer) ?? null, kind: stringOf(prop(call.def, 'kind')?.initializer) ?? null, props: propNames(call), file: rel, line, ...(prop(call.def, 'pixel') ? { pixel: true } : {}) })
+    }
+  }
+  return out.sort((a, b) => String(a.name).localeCompare(String(b.name)))
+}
+
+/** `[...x]`, `x.split('')` or `Array.from(x)`: the string being spread, or undefined. */
+function glyphSource(node) {
+  if (ts.isArrayLiteralExpression(node) && node.elements.length === 1 && ts.isSpreadElement(node.elements[0])) return node.elements[0].expression
+  if (!ts.isCallExpression(node)) return undefined
+  const callee = node.expression.getText()
+  if (callee === 'Array.from' && node.arguments.length === 1 && !ts.isObjectLiteralExpression(node.arguments[0])) return node.arguments[0]
+  if (ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === 'split' && stringOf(node.arguments[0]) === '') return node.expression.expression
+  return undefined
+}
+
+/** The first `<span>` a `.map` callback returns. */
+function returnedSpan(fn) {
+  let span
+  walk(fn.body, n => {
+    if (span) return
+    const open = ts.isJsxElement(n) ? n.openingElement : ts.isJsxSelfClosingElement(n) ? n : undefined
+    if (open?.tagName.getText() === 'span') span = open
+  })
+  return span
+}
+
+const attrOf = (open, name) => open.attributes.properties.some(p => !ts.isJsxSpreadAttribute(p) && p.name.getText() === name)
+const spreads = open => open.attributes.properties.some(ts.isJsxSpreadAttribute)
+
+/** The JSX element a child expression sits in. */
+function jsxParent(node) {
+  for (let n = node.parent; n; n = n.parent) if (ts.isJsxElement(n)) return n.openingElement
+  return undefined
+}
+
+/** A string literal, or a `const` in this file holding one. */
+function knownString(sf, node) {
+  const direct = stringOf(node)
+  if (direct !== undefined) return direct
+  if (!ts.isIdentifier(node)) return undefined
+  let found
+  walk(sf, n => {
+    if (ts.isVariableDeclaration(n) && n.name.getText() === node.text && ts.isVariableDeclarationList(n.parent) && n.parent.flags & ts.NodeFlags.Const) found ??= stringOf(n.initializer)
+  })
+  return found
+}
+
+function glyphChecks(sf, report) {
+  walk(sf, node => {
+    if (!ts.isCallExpression(node) || !ts.isPropertyAccessExpression(node.expression) || node.expression.name.text !== 'map') return
+    const source = glyphSource(node.expression.expression)
+    const fn = node.arguments[0]
+    if (!source || !fn || !(ts.isArrowFunction(fn) || ts.isFunctionExpression(fn))) return
+    const span = returnedSpan(fn)
+    if (!span) return
+    const text = knownString(sf, source)
+    const count = text === undefined ? 0 : Array.from(text).length
+    if (count > GLYPHS) report('X040', node, `Per-grapheme spans over ${count} graphemes: each is a DOM node, a style and a composited layer once it animates. Use word-level motion or a Surface.`)
+    const hidden = attrOf(span, 'aria-hidden') || spreads(span)
+    const parent = jsxParent(node)
+    const named = !parent || attrOf(parent, 'aria-label') || attrOf(parent, 'aria-labelledby') || spreads(parent)
+    if (!hidden || !named) report('X041', span, `Per-character spans read as separate letters to a screen reader${hidden ? '' : ': add `aria-hidden` to each span'}${named ? '' : `${hidden ? ':' : ', and'} give the parent an \`aria-label\` with the whole text`}.`)
+  })
+}
+
+function surfaceFileChecks(sf, slots, report) {
+  const calls = surfaceCalls(sf)
+  if (!calls.length) return
+  const decorative = new Set()
+  walk(sf, n => {
+    if (ts.isCallExpression(n) && ts.isPropertyAccessExpression(n.expression) && n.expression.name.text === 'decorative') decorative.add(n)
+  })
+  const inside = n => { for (let p = n.parent; p; p = p.parent) if (decorative.has(p)) return true; return false }
+  walk(sf, n => {
+    if (!ts.isCallExpression(n) || !ts.isPropertyAccessExpression(n.expression)) return
+    const method = n.expression.name.text
+    if ((method === 'fillText' || method === 'strokeText') && !inside(n)) report('X010', n, `\`${method}\` in a surface draws text only the canvas knows about: no selection, find, translation or screen reader. Use \`s.text()\`, or \`s.decorative()\` for text that is truly decoration.`)
+    if (method === 'setAttribute' && stringOf(n.arguments[0]) === 'aria-hidden' && n.expression.expression.getText().endsWith('.el')) report('X011', n, 'This hides the surface or its text mirror from assistive tech. Leave the mirror to weft.')
+  })
+  for (const call of calls) {
+    const kindNode = prop(call.def, 'kind')?.initializer
+    const kind = stringOf(kindNode)
+    if (kind && slots && slots['surface.renderer'] && !slots['surface.renderer'][kind]) report('P101', kindNode, `Surface kind \`${kind}\` has no provider: add the plugin that provides it to \`plugins\` in weft.config.ts.`)
+    if (!call.param || !call.fn) continue
+    walk(call.fn, n => {
+      if (!ts.isCallExpression(n) || n.expression.getText() !== `${call.param}.text`) return
+      const options = n.arguments[1]
+      const font = options && ts.isObjectLiteralExpression(options) ? stringOf(prop(options, 'font')?.initializer) : undefined
+      const family = font?.replace(/^.*?\d[\d.]*px(\/\S+)?\s*/, '')
+      if (family !== undefined && (SYSTEM.test(family) || GENERIC_ONLY.test(family))) report('X002', n.arguments[1], `\`${font}\` can't be measured safely: \`system-ui\`, \`-apple-system\` and generic-only families resolve differently in canvas and CSS. Name a family.`)
+      if (kind === 'canvas2d' && slots && slots['text.measure'] === null) report('P101', n, 'Canvas `s.text()` needs `text.measure`, and nothing provides it: add `text()` from `@weft-js/text` to `plugins` in weft.config.ts.')
+    })
+  }
+}
+
+const HIDES = /(?:display\s*:\s*none|visibility\s*:\s*hidden)/
+
+/** X011/X012 in a stylesheet: rules aimed at the host or the mirror. */
+function cssChecks(file, report) {
+  const css = file.text.replace(/\/\*[\s\S]*?\*\//g, m => m.replace(/[^\n]/g, ' '))
+  const rule = /([^{}]*\[data-surface(-text)?\b[^{}]*)\{([^}]*)\}/g
+  for (const m of css.matchAll(rule)) {
+    const at = m.index + m[0].indexOf('[data-surface')
+    const before = css.slice(0, m.index)
+    const open = before.lastIndexOf('@media')
+    const inPrint = open >= 0 && /^@media[^{]*\bprint\b/.test(before.slice(open)) && (before.slice(open).match(/\{/g) ?? []).length > (before.slice(open).match(/\}/g) ?? []).length
+    if (/forced-color-adjust\s*:\s*none/.test(m[3])) report('X012', at, at + 13, '`forced-color-adjust: none` on a surface keeps its author colours in forced-colours mode, where the mirror must take over.')
+    else if (inPrint && HIDES.test(m[3])) report('X012', at, at + 13, 'This hides surface text when printing, where the mirror is the only copy that prints sharply.')
+    else if (m[2] && HIDES.test(m[3])) report('X011', at, at + 18, 'This hides the text mirror from assistive tech, and it is the only copy a screen reader can read. Leave the mirror to weft.')
+  }
+}
+
+/**
+ * @param {string} root
+ * @param {{ files: { rel: string, text: string }[], exclude?: string[], slots?: Record<string, any> }} options
+ */
+export function surfaceChecks(root, { files, exclude = [], slots }) {
+  const out = []
+  const reporter = file => {
+    const pos = positions(file.text)
+    return (code, start, end, why) => out.push(diagnostic({ code, file: file.rel, span: pos.span(start, end), offset: [start, end], why }))
+  }
+  const sources = new Map(files.filter(f => CODE.test(f.rel)).map(f => [f.rel, f]))
+  for (const rel of discover(root, { include: ['src/**/*.{ts,tsx,js,jsx}'], exclude })) {
+    if (!sources.has(rel)) sources.set(rel, { rel, text: readFileSync(join(root, rel), 'utf8') })
+  }
+  for (const f of sources.values()) {
+    const glyphs = /\.[jt]sx$/.test(f.rel) && /\.map\(/.test(f.text) && /<span\b/.test(f.text)
+    const surfaces = f.text.includes('@weft-js/core/surface')
+    if (!glyphs && !surfaces) continue
+    let sf
+    try {
+      sf = parse(f.rel, f.text)
+    } catch {
+      continue
+    }
+    const raw = reporter(f)
+    const report = (code, node, why) => raw(code, node.getStart(sf), node.end, why)
+    if (glyphs) glyphChecks(sf, report)
+    if (!surfaces) continue
+    surfaceFileChecks(sf, slots, report)
+    if (!/\.[jt]sx$/.test(f.rel)) continue
+    const scan = scanJsx(f.text, f.rel)
+    const local = scan.imports.find(i => i.source === '@weft-js/core/surface' && i.imported === 'Surface')?.local
+    for (const el of scan.elements) {
+      if (el.name !== local) continue
+      const spread = el.attrs.some(a => a.kind === 'spread')
+      if (!el.attr('label') && !el.attr('decorative') && !spread) raw('X009', el.start, el.tagEnd, `<${el.name}> has no accessible name: a screen reader finds an unnamed image. Add \`label\`, or \`decorative\` if it shows nothing a reader needs.`)
+      const hidden = el.attr('aria-hidden')
+      if (hidden && hidden.value !== 'false') raw('X011', hidden.start, hidden.end, 'This hides the surface and its text mirror from assistive tech. For a surface with nothing to read use `decorative`, which leaves mirrors alone.')
+      const style = el.attr('style')
+      if (style && /forced-color-adjust\s*:\s*none|forcedColorAdjust\s*:\s*['"]none/.test(style.value ?? style.expr ?? '')) raw('X012', style.start, style.end, '`forced-color-adjust: none` on a surface keeps its author colours in forced-colours mode, where the mirror must take over.')
+    }
+  }
+  for (const rel of discover(root, { include: ['**/*.css'], exclude })) {
+    const text = readFileSync(join(root, rel), 'utf8')
+    if (text.includes('data-surface')) cssChecks({ rel, text }, reporter({ rel, text }))
+  }
+  return out
+}

package/src/tailwind.mjs

@@ -0,0 +1,22 @@
+// Tailwind v4 for a weft app (research 34 §5). `create-weft --ui tailwind` and `weft add tailwind` write the same files,
+// and a create-weft test holds them equal, because create-weft can't depend on the CLI.
+
+export const packages = { tailwindcss: '4.3.3', '@tailwindcss/vite': '4.3.3' }
+
+export const viteConfig = `import tailwindcss from '@tailwindcss/vite'
+
+export default { plugins: [tailwindcss()] }
+`
+
+/**
+ * The top of the app's CSS. With warp, Tailwind's reset stays out: its `base` layer comes after `warp`, so it would
+ * beat every warp component. warp brings its own base. Layer order has to be declared before any import.
+ */
+export const cssEntry = warp => (warp
+  ? `@layer warp, theme, base, components, utilities;
+@import "tailwindcss/theme.css" layer(theme);
+@import "tailwindcss/utilities.css" layer(utilities);
+@import "@weft-js/warp/tailwind.css";
+`
+  : `@import "tailwindcss";
+`)

package/src/tasks.mjs

@@ -0,0 +1,99 @@
+// `weft tasks`: the single list of what can be run (PLAN §7b). Built-ins first, then the project's `tasks`.
+
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { join, relative, resolve } from 'node:path'
+import { z } from 'zod'
+import { loadConfig } from './load-config.mjs'
+
+const files = { type: 'array', items: { type: 'string' }, description: 'Files relative to the project root; default: the whole project' }
+
+/** `available: false` marks commands PLAN names that this CLI does not ship yet; `stack` ones ship for apps with src/routes. */
+export const builtins = [
+  { name: 'check', description: 'Compile every component in check mode and report W- and P-diagnostics with fixes', args: { type: 'object', properties: { files } }, sideEffects: [], available: true },
+  { name: 'tasks', description: 'List every command and project task with args, side effects and environments', args: { type: 'object', properties: {} }, sideEffects: [], available: true },
+  { name: 'docs', description: 'Print a docs topic or a diagnostic code (`weft docs W014`)', args: { type: 'object', properties: { topic: { type: 'string' } } }, sideEffects: [], available: true },
+  { name: 'agents-md', description: 'Regenerate AGENTS.md (`--check` fails if stale)', args: { type: 'object', properties: { check: { type: 'boolean' } } }, sideEffects: ['fs:AGENTS.md'], available: true },
+  { name: 'mcp', description: 'These commands as MCP tools (stdio)', args: { type: 'object', properties: {} }, sideEffects: [], available: true, longRunning: true },
+  { name: 'style', description: 'Style groups: `find <query>`, `explain <group|selector>`, `matrix` (writes .weft/styles.json)', args: { type: 'object', properties: { subcommand: { type: 'string', enum: ['find', 'explain', 'matrix'] }, query: { type: 'string' }, target: { type: 'string' } } }, sideEffects: ['fs:.weft/styles.json'], available: true },
+  { name: 'map', description: 'Write `.weft/map.md`: a matrix of what to call in this app', args: { type: 'object', properties: {} }, sideEffects: ['fs:.weft/map.*'], available: true },
+  { name: 'add', description: 'Install a plugin and wire it into the config (`--dry-run` shows the changes)', args: { type: 'object', properties: { plugin: { type: 'string' }, 'dry-run': { type: 'boolean' } } }, sideEffects: ['fs:weft.config.*', 'fs:package.json', 'network:install'], available: true },
+  { name: 'dev', description: 'Dev server', sideEffects: ['network:listen'], available: false, stack: true, longRunning: true },
+  { name: 'build', description: 'Production build and contract', sideEffects: ['fs:.output/**'], available: false, stack: true },
+  { name: 'start', description: 'Serve the build', sideEffects: ['network:listen'], available: false, stack: true, longRunning: true },
+  { name: 'db', description: '`generate`: new migrations', sideEffects: ['fs:drizzle/**', 'fs:migrations/**', 'fs:prisma/**'], available: false, stack: true },
+  { name: 'test', description: 'The test gate on the diff (`--gate`)', args: { type: 'object', properties: { gate: { type: 'boolean' }, base: { type: 'string' }, budget: { type: 'number' }, refactor: { type: 'boolean' } } }, sideEffects: ['fs:.weft/gate'], available: true },
+  { name: 'fix', description: 'Apply the safe autofixes from `weft check`', args: { type: 'object', properties: { files } }, sideEffects: ['fs:scope.write'], available: true },
+  { name: 'tokens', description: "warp's resolved tokens as DTCG 2025.10 in `.weft/tokens/` (Figma, Style Dictionary, Terrazzo)", args: { type: 'object', properties: {} }, sideEffects: ['fs:.weft/tokens/**'], available: true },
+  { name: 'browser', description: 'Drive the running app in any open browser by role/label/text (`weft browser help`)', args: { type: 'object', properties: { command: { type: 'string' } } }, sideEffects: ['network:dev-server', 'fs:.weft/browser'], available: true },
+  { name: 'run', description: 'Run a project task by name', args: { type: 'object', properties: { name: { type: 'string' } } }, sideEffects: ['task'], available: true },
+  { name: 'create', description: 'Scaffold a weft app', sideEffects: ['fs'], available: false },
+  { name: 'surfaces', description: "List the project's surfaces: name, kind, props and file", sideEffects: [], available: true },
+  { name: 'plugins', description: 'List and explain plugins and slot bindings; `sync` regenerates .weft/slots and plugin tokens; `audit` and `approve` check and write the permissions lock', args: { type: 'object', properties: { subcommand: { type: 'string', enum: ['list', 'explain', 'sync', 'audit', 'approve'] }, slot: { type: 'string' }, all: { type: 'boolean' } } }, sideEffects: ['fs:.weft/**', 'fs:.gitignore'], available: true },
+]
+
+function jsonSchema(args) {
+  if (!args) return { type: 'object', properties: {} }
+  if ('_zod' in args || '~standard' in args) {
+    try {
+      return z.toJSONSchema(args)
+    } catch {
+      return { type: 'object', description: 'Zod schema that has no JSON Schema form' }
+    }
+  }
+  return args
+}
+
+/** `weft run <name>`: the task's command in a shell at the project root, its output yours. Resolves with its exit code. */
+export async function runTask(root, name) {
+  root = resolve(root)
+  const { config } = await loadConfig(root)
+  const task = config.tasks?.[name]
+  if (!task) throw Object.assign(new Error(`no task "${name}" (tasks: ${Object.keys(config.tasks ?? {}).join(', ') || 'none'})`), { code: 'E_USAGE' })
+  return new Promise((ok, fail) => {
+    const child = spawn(task.run, { cwd: root, shell: true, stdio: 'inherit' })
+    child.on('error', fail)
+    child.on('close', code => ok(code ?? 1))
+  })
+}
+
+/** Everything `weft` can run here: the built-ins and the project's own tasks, with the config's diagnostics. */
+export async function tasks(root) {
+  root = resolve(root)
+  const { file, config, diagnostics } = await loadConfig(root)
+  const environments = Object.keys(config.environments ?? {})
+  const stack = existsSync(join(root, 'src', 'routes'))
+  const list = builtins.map(b => ({
+    name: b.name,
+    kind: 'builtin',
+    command: { check: 'weft check --json', tasks: 'weft tasks --json', docs: 'weft docs <topic>' }[b.name] ?? `weft ${b.name}`,
+    description: b.description,
+    args: b.args ?? { type: 'object', properties: {} },
+    sideEffects: b.sideEffects,
+    env: environments,
+    available: b.available || (b.stack && stack),
+    ...(b.longRunning && { longRunning: true }),
+  }))
+  for (const [name, t] of Object.entries(config.tasks ?? {})) {
+    list.push({
+      name,
+      kind: 'project',
+      command: `weft run ${name}`,
+      description: t.description ?? null,
+      args: jsonSchema(t.args),
+      sideEffects: t.sideEffects ?? null,
+      env: t.env ?? environments,
+      available: true,
+    })
+  }
+  return {
+    version: 1,
+    ok: !diagnostics.some(d => d.severity === 'error'),
+    root,
+    config: file ? relative(root, file).split('\\').join('/') : null,
+    tasks: list,
+    scope: { write: config.scope?.write ?? null, read: config.scope?.read ?? null, forbid: config.scope?.forbid ?? [] },
+    environments,
+    diagnostics: diagnostics.filter(d => ['P003', 'P004', 'P007'].includes(d.code)),
+  }
+}