@weft-js/cli 0.0.0-stage → 0.1.0

package/src/audit.mjs

@@ -0,0 +1,333 @@
+// `weft audit` and the last step of `weft build`: the built pages in a clean headless Chrome, at a phone's width and a
+// desktop's, read the way a crawler, a screen reader and Lighthouse read them. `weft check` reads source; some failures
+// only exist once CSS and a breakpoint have had their say (a button whose text a phone hides has no name), so this
+// looks at the rendered page. No automation library: the DevTools protocol over the WebSocket Node already has.
+//
+// L001–L004 axe-core's rules, the ones Lighthouse grades (names, images, contrast, the rest), L010–L013 console and issues,
+// L020–L025 the head a crawler reads, L030–L031 sideways scroll on a phone and layout shift.
+
+import { spawn } from 'node:child_process'
+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync } from 'node:fs'
+import { createServer } from 'node:http'
+import { tmpdir } from 'node:os'
+import { extname, join, relative, resolve, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { findChrome } from './browser/client.mjs'
+import { diagnostic } from './diag.mjs'
+
+/** The two widths Lighthouse's defaults stand for: its mobile run (a Moto G Power) and its desktop run. */
+export const FORMS = {
+  phone: { width: 412, height: 823, deviceScaleFactor: 1.75, mobile: true },
+  desktop: { width: 1350, height: 940, deviceScaleFactor: 1, mobile: false },
+}
+
+/**
+ * axe-core is what Lighthouse runs for Accessibility and for Agentic Browsing's accessibility tree: the WCAG 2 A and AA
+ * rules, and the best-practice ones Lighthouse also grades. `region` (all content in landmarks) Lighthouse leaves out.
+ */
+const AXE = {
+  runOnly: { type: 'tag', values: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa'] },
+  rules: { 'heading-order': { enabled: true }, 'empty-heading': { enabled: true }, 'tabindex': { enabled: true }, 'duplicate-id-aria': { enabled: true }, 'image-redundant-alt': { enabled: true }, 'skip-link': { enabled: true }, 'landmark-one-main': { enabled: true }, 'list': { enabled: true }, 'listitem': { enabled: true }, 'region': { enabled: false } },
+  resultTypes: ['violations'],
+}
+/** What a rule means in a warp app, where warp is how it usually happens. */
+const WARP = {
+  'heading-order': "warp's titled parts (Accordion, Chart, ActivityFeed) are h3, for a page section under an h2: one placed elsewhere takes `level`, or the place gets the heading it lacks. ",
+}
+
+/** axe rules with a code of their own; every other violation is L004, with the rule's id. */
+const RULES = {
+  ...Object.fromEntries(['button-name', 'link-name', 'input-button-name', 'label', 'select-name', 'aria-command-name', 'aria-input-field-name', 'aria-toggle-field-name', 'aria-progressbar-name', 'aria-meter-name', 'aria-tooltip-name', 'aria-treeitem-name', 'aria-dialog-name', 'frame-title', 'summary-name'].map(r => [r, 'L001'])),
+  ...Object.fromEntries(['image-alt', 'role-img-alt', 'svg-img-alt', 'input-image-alt', 'object-alt', 'area-alt'].map(r => [r, 'L002'])),
+  'color-contrast': 'L003',
+}
+let axe
+const axeSource = () => (axe ??= readFileSync(fileURLToPath(import.meta.resolve('axe-core/axe.min.js')), 'utf8'))
+/** The issue types Lighthouse's `inspector-issues` audit counts (low contrast is axe's, as L003). */
+const ISSUES = new Set(['MixedContentIssue', 'CookieIssue', 'BlockedByResponseIssue', 'HeavyAdIssue', 'ContentSecurityPolicyIssue', 'SharedArrayBufferIssue', 'CorsIssue', 'AttributionReportingIssue', 'QuirksModeIssue', 'FederatedAuthRequestIssue', 'BounceTrackingIssue', 'StylesheetLoadingIssue'])
+
+const TYPES = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript', '.mjs': 'text/javascript', '.css': 'text/css', '.json': 'application/json', '.svg': 'image/svg+xml', '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.avif': 'image/avif', '.gif': 'image/gif', '.ico': 'image/x-icon', '.woff2': 'font/woff2', '.woff': 'font/woff', '.txt': 'text/plain; charset=utf-8', '.xml': 'application/xml', '.wasm': 'application/wasm', '.webmanifest': 'application/manifest+json' }
+
+const fail = (code, message) => Object.assign(new Error(message), { code })
+const sleep = ms => new Promise(r => { setTimeout(r, ms) })
+
+/** The public directory a build wrote: the newer of `.output/public` (server presets) and `dist` (Netlify, Vercel static). */
+export function builtPublic(root) {
+  const found = ['.output/public', 'dist'].map(d => join(root, d)).filter(d => existsSync(join(d, 'index.html')))
+  return found.sort((a, b) => statSync(join(b, 'index.html')).mtimeMs - statSync(join(a, 'index.html')).mtimeMs)[0] ?? null
+}
+
+/** Every prerendered page under `dir`, as its URL path. */
+export function pagesIn(dir) {
+  const out = []
+  const walk = d => {
+    for (const e of readdirSync(d, { withFileTypes: true })) {
+      if (e.name.startsWith('.') || e.name.startsWith('_')) continue
+      const f = join(d, e.name)
+      if (e.isDirectory()) walk(f)
+      else if (e.name.endsWith('.html') && !/^(404|200|500)\.html$/.test(e.name)) {
+        const rel = relative(dir, f).split(sep).join('/')
+        out.push(`/${rel.replace(/(^|\/)index\.html$/, '$1').replace(/\.html$/, '')}`)
+      }
+    }
+  }
+  walk(dir)
+  return out.sort()
+}
+
+/**
+ * One page for each kind: `/` and each top-level page, then the first page of each section at each depth (the docs'
+ * 1,600 pages share a few layouts, and a layout's fault shows on its first page).
+ */
+export function samplePages(pages, max = 30) {
+  const seen = new Map()
+  for (const p of pages) {
+    const parts = p.split('/').filter(Boolean)
+    const key = parts.length <= 1 ? p : `${parts[0]}/${parts.length}`
+    if (!seen.has(key)) seen.set(key, p)
+  }
+  return [...seen.values()].slice(0, max)
+}
+
+/** A static server over a build's public directory, for the audit's Chrome. */
+export function serveStatic(dir) {
+  dir = resolve(dir)
+  const server = createServer((req, res) => {
+    const path = decodeURIComponent(new URL(req.url, 'http://x').pathname)
+    const tries = [path, `${path}/index.html`, `${path.replace(/\/$/, '')}.html`].map(p => resolve(dir, `.${p}`))
+    const file = tries.find(f => (f === dir || f.startsWith(dir + sep)) && existsSync(f) && statSync(f).isFile())
+    const missing = join(dir, '404.html')
+    if (!file) {
+      res.writeHead(404, { 'content-type': TYPES['.html'] })
+      return res.end(existsSync(missing) ? readFileSync(missing) : 'not found')
+    }
+    res.writeHead(200, { 'content-type': TYPES[extname(file)] ?? 'application/octet-stream' })
+    res.end(readFileSync(file))
+  })
+  return new Promise(ok => { server.listen(0, '127.0.0.1', () => ok({ url: `http://127.0.0.1:${server.address().port}`, close: () => server.close() })) })
+}
+
+/** A clean headless Chrome (its own empty profile: no extensions, nothing stored) and a DevTools protocol client. As root (a container, CI) Chrome only starts unsandboxed. */
+async function chrome(exe) {
+  const profile = mkdtempSync(join(tmpdir(), 'weft-audit-'))
+  const child = spawn(exe, [`--user-data-dir=${profile}`, '--headless=new', '--remote-debugging-port=0', '--no-first-run', '--no-default-browser-check', '--disable-extensions', '--disable-background-networking', '--mute-audio', ...(process.getuid?.() === 0 ? ['--no-sandbox'] : []), 'about:blank'], { stdio: 'ignore' })
+  const portFile = join(profile, 'DevToolsActivePort')
+  for (let i = 0; !existsSync(portFile) || !readFileSync(portFile, 'utf8').includes('\n'); i++) {
+    if (i > 150 || child.exitCode !== null) { child.kill(); throw fail('E_NO_CHROME', `Chrome at ${exe} didn't start`) }
+    await sleep(100)
+  }
+  const [port, path] = readFileSync(portFile, 'utf8').split('\n')
+  const ws = new WebSocket(`ws://127.0.0.1:${port}${path}`)
+  await new Promise((ok, no) => { ws.onopen = ok; ws.onerror = () => no(fail('E_CDP', 'could not reach Chrome over the DevTools protocol')) })
+  let next = 0
+  const waiting = new Map()
+  const listeners = new Set()
+  ws.onmessage = e => {
+    const m = JSON.parse(e.data)
+    if (m.id !== undefined) {
+      const w = waiting.get(m.id)
+      waiting.delete(m.id)
+      if (m.error) w?.no(fail('E_CDP', m.error.message))
+      else w?.ok(m.result)
+    } else for (const on of listeners) on(m)
+  }
+  const send = (method, params = {}, sessionId) => new Promise((ok, no) => {
+    const id = ++next
+    waiting.set(id, { ok, no })
+    ws.send(JSON.stringify({ id, method, params, sessionId }))
+  })
+  const close = () => {
+    try { ws.close() } catch {}
+    child.kill()
+    // Chrome holds the profile a moment after it's told to go.
+    setTimeout(() => rmSync(profile, { recursive: true, force: true }), 500).unref()
+  }
+  return { send, on: fn => { listeners.add(fn); return () => listeners.delete(fn) }, close }
+}
+
+/** In the page: how far the layout moved without a person asking (CLS, summed), and the first elements that moved. */
+const SHIFT = `new Promise(ok => {
+  let cls = 0
+  const moved = []
+  new PerformanceObserver(list => {
+    for (const e of list.getEntries()) {
+      if (e.hadRecentInput) continue
+      cls += e.value
+      for (const s of e.sources ?? []) {
+        if (!s.node || s.node.nodeType !== 1 || moved.length === 3) continue
+        const open = s.node.outerHTML.slice(0, s.node.outerHTML.indexOf('>') + 1)
+        moved.push(open.length > 120 ? open.slice(0, 117) + '…>' : open)
+      }
+    }
+  }).observe({ type: 'layout-shift', buffered: true })
+  setTimeout(() => ok({ cls: Math.round(cls * 1000) / 1000, moved }), 50)
+})`
+
+/** In the page: what a crawler reads from the head, and what pokes past a phone's right edge. */
+const HEAD = `(() => {
+  const meta = n => document.querySelector('meta[name="' + n + '"]')?.getAttribute('content')?.trim() ?? null
+  const wide = []
+  const edge = innerWidth + 1
+  if (document.documentElement.scrollWidth > edge) {
+    for (const el of document.body.querySelectorAll('*')) {
+      const r = el.getBoundingClientRect()
+      if (r.right > edge && r.width > 0 && getComputedStyle(el).position !== 'fixed' && !(el.parentElement && el.parentElement.getBoundingClientRect().right > edge)) {
+        const open = el.outerHTML.slice(0, el.outerHTML.indexOf('>') + 1)
+        wide.push(open.length > 120 ? open.slice(0, 117) + '…>' : open)
+        if (wide.length === 3) break
+      }
+    }
+  }
+  return {
+    title: document.title.trim(), lang: document.documentElement.getAttribute('lang') ?? '', description: meta('description'),
+    viewport: meta('viewport'), robots: meta('robots'), scroll: document.documentElement.scrollWidth - innerWidth, wide,
+  }
+})()`
+
+/** Audit one page in one form factor: what Chrome said while it loaded, its head, its layout, and axe-core's rules. */
+async function auditPage(browser, url, form, statics) {
+  const { targetId } = await browser.send('Target.createTarget', { url: 'about:blank' })
+  const { sessionId } = await browser.send('Target.attachToTarget', { targetId, flatten: true })
+  const send = (m, p) => browser.send(m, p, sessionId)
+  const found = []
+  let document = null
+  let loaded
+  const load = new Promise(ok => { loaded = ok })
+  const where = (u, line) => (u ? `${u.replace(/^https?:\/\/127\.0\.0\.1:\d+/, '')}${line === undefined ? '' : `:${line + 1}`}` : '')
+  const off = browser.on(m => {
+    if (m.sessionId !== sessionId) return
+    const p = m.params
+    if (m.method === 'Page.loadEventFired') loaded()
+    else if (m.method === 'Network.responseReceived' && p.type === 'Document' && !document) document = p.response
+    else if (m.method === 'Runtime.exceptionThrown') {
+      const d = p.exceptionDetails
+      found.push({ code: 'L010', key: d.exception?.description?.split('\n')[0] ?? d.text, at: where(d.url, d.lineNumber), text: d.exception?.description?.split('\n')[0] ?? d.text })
+    } else if (m.method === 'Runtime.consoleAPICalled' && (p.type === 'error' || p.type === 'assert')) {
+      const text = p.args.map(a => a.value ?? a.description ?? '').join(' ').split('\n')[0]
+      const top = p.stackTrace?.callFrames?.[0]
+      found.push({ code: 'L010', key: text, at: where(top?.url, top?.lineNumber), text })
+    } else if (m.method === 'Log.entryAdded' && p.entry.level === 'error') {
+      // a build's pages served as files have no server: its realtime and function routes answer 404 here and nowhere else
+      if (statics && /\/_weft\/(rt|ws|fn|data|m|x)\b/.test(`${p.entry.url ?? ''} ${p.entry.text}`)) return
+      found.push({ code: 'L011', key: `${p.entry.url ?? ''} ${p.entry.text}`, at: where(p.entry.url), text: p.entry.text })
+    } else if (m.method === 'Audits.issueAdded') {
+      const { code, details } = p.issue
+      if (code === 'DeprecationIssue') {
+        const d = details.deprecationIssueDetails
+        found.push({ code: 'L012', key: d.type, at: where(d.sourceCodeLocation?.url, d.sourceCodeLocation?.lineNumber), text: d.type })
+      } else if (ISSUES.has(code)) found.push({ code: 'L013', key: code, text: code.replace(/Issue$/, '').replace(/([a-z])([A-Z])/g, '$1 $2') })
+    }
+  })
+  try {
+    const f = FORMS[form]
+    await Promise.all(['Page.enable', 'Runtime.enable', 'Log.enable', 'Network.enable', 'Audits.enable'].map(m => send(m)))
+    await send('Emulation.setDeviceMetricsOverride', { width: f.width, height: f.height, deviceScaleFactor: f.deviceScaleFactor, mobile: f.mobile })
+    await send('Emulation.setTouchEmulationEnabled', { enabled: f.mobile, maxTouchPoints: f.mobile ? 5 : 1 })
+    await send('Page.navigate', { url })
+    await Promise.race([load, sleep(15_000)])
+    await sleep(800) // hydration's errors, and a font swap's shift, land after load
+    if (document && document.status >= 400) found.push({ code: 'L025', key: String(document.status), text: `HTTP ${document.status}` })
+    const header = Object.entries(document?.headers ?? {}).find(([k]) => k.toLowerCase() === 'x-robots-tag')?.[1]
+    const head = (await send('Runtime.evaluate', { expression: HEAD, returnByValue: true })).result.value
+    if (!head.title) found.push({ code: 'L020', key: 'title' })
+    if (!head.description) found.push({ code: 'L021', key: 'description' })
+    if (!head.lang) found.push({ code: 'L022', key: 'lang' })
+    if (!head.viewport || !/width=device-width/.test(head.viewport)) found.push({ code: 'L023', key: 'viewport' })
+    const noindex = [header && /noindex|none/i.test(header) && `the \`x-robots-tag: ${header}\` header`, head.robots && /noindex|none/i.test(head.robots) && `<meta name="robots" content="${head.robots}">`].filter(Boolean)
+    if (noindex.length) found.push({ code: 'L024', key: noindex.join(), text: noindex.join(' and '), header: !!header })
+    if (f.mobile && head.scroll > 0) found.push({ code: 'L030', key: head.wide.join() || 'page', text: `${head.scroll}px`, wide: head.wide })
+    const shift = (await send('Runtime.evaluate', { expression: SHIFT, awaitPromise: true, returnByValue: true })).result.value
+    if (shift.cls > 0.05) found.push({ code: 'L031', key: shift.moved.join() || 'page', cls: shift.cls, moved: shift.moved })
+    await send('Runtime.evaluate', { expression: axeSource() })
+    const { result, exceptionDetails } = await send('Runtime.evaluate', { expression: `axe.run(document, ${JSON.stringify(AXE)}).then(r => r.violations)`, awaitPromise: true, returnByValue: true })
+    if (exceptionDetails) throw fail('E_AUDIT', `axe-core failed on ${url}: ${exceptionDetails.exception?.description ?? exceptionDetails.text}`)
+    for (const v of result.value) {
+      for (const n of v.nodes) {
+        const tag = n.html.slice(0, n.html.indexOf('>') + 1)
+        found.push({ code: RULES[v.id] ?? 'L004', key: `${v.id} ${n.target.join(' ')}`, rule: v.id, help: v.help, fix: n.failureSummary?.replace(/^Fix (any|all) of the following:\s*/, '').split('\n')[0].trim(), selector: n.target.join(' '), tag: tag.length > 160 ? `${tag.slice(0, 157)}…>` : tag, contrast: v.id === 'color-contrast' ? n.any[0]?.data : undefined })
+      }
+    }
+    return found
+  } finally {
+    off()
+    await browser.send('Target.closeTarget', { targetId }).catch(() => {})
+  }
+}
+
+const say = {
+  L001: f => `${f.tag} (\`${f.selector}\`) has no accessible name (${f.rule}): a screen reader announces only its role. When the source has text, CSS hid it at this width.`,
+  L002: f => `${f.tag} (\`${f.selector}\`) is an image with no text alternative (${f.rule}): a screen reader reads its file name.`,
+  L003: f => `${f.tag} (\`${f.selector}\`): ${f.contrast ? `${f.contrast.fgColor} on ${f.contrast.bgColor} is ${f.contrast.contrastRatio}:1 at ${f.contrast.fontSize}, under ${f.contrast.expectedContrastRatio}` : 'its text contrast is too low'}.`,
+  L004: f => `${f.tag} (\`${f.selector}\`): ${f.help} (axe \`${f.rule}\`).`,
+  L031: f => `The layout moved by ${f.cls} (CLS) while the page loaded, with no one touching it${f.moved.length ? `: ${f.moved.join(', ')} moved` : ''}. Over 0.1 costs Lighthouse's Performance score.`,
+  L010: f => `Console error${f.at ? ` at ${f.at}` : ''}: ${f.text}`,
+  L011: f => (f.at === '/favicon.ico' ? 'The page names no icon, so the browser asked for /favicon.ico and got a 404: Lighthouse counts it as a console error. Add `<link rel="icon">` through `site.head`, or a `public/favicon.ico`.' : `The browser logged an error${f.at ? ` for ${f.at}` : ''}: ${f.text}`),
+  L012: f => `A deprecated browser API is in use${f.at ? ` at ${f.at}` : ''}: ${f.text}. Lighthouse marks Best Practices down for it.`,
+  L013: f => `Chrome logged a ${f.text} issue for the page. Lighthouse marks Best Practices down for it.`,
+  L020: () => 'The page has no `<title>`: search results and tabs show its URL.',
+  L021: () => 'The page has no meta description: search results make one up from the page.',
+  L022: () => '`<html>` has no `lang`: screen readers guess the language, and translation offers go wrong.',
+  L023: () => 'No `<meta name="viewport" content="width=device-width, initial-scale=1">`: a phone renders the page at 980px and shrinks it.',
+  L024: f => `Search engines are told not to index this page, by ${f.text}.${f.header ? ' Hosts add this header to preview and permalink URLs (Netlify, Vercel): on the production URL it is gone.' : ''}`,
+  L025: f => `The page answered ${f.text}.`,
+  L030: f => `The page scrolls sideways on a phone: it is ${f.text} wider than the screen.${f.wide?.length ? ` Past the edge: ${f.wide.join(', ')}` : ''}`,
+}
+/** A page may ask not to be indexed, and a host's preview URL does on its behalf: L024 says so without failing. */
+const SEVERITY = { L021: 'warning', L024: 'warning', L030: 'warning', L031: 'warning' }
+
+/**
+ * @param {string} root project root
+ * @param {{ url?: string, dir?: string, routes?: string[], all?: boolean, max?: number, forms?: (keyof FORMS)[], concurrency?: number }} [options]
+ *   `url`: audit a running site (a deploy, `weft start`); else `dir`, a build's public directory (found when left out)
+ * @returns {Promise<{ ok: boolean, skipped?: string, base: string, pages: string[], diagnostics: object[], ms: number }>}
+ */
+export async function audit(root, options = {}) {
+  const t = performance.now()
+  const exe = findChrome()
+  const forms = options.forms ?? ['phone', 'desktop']
+  const skip = why => ({ ok: true, skipped: why, base: options.url ?? '', pages: [], diagnostics: [diagnostic({ code: 'L000', severity: 'warning', file: 'weft.config.ts', why })], ms: 0 })
+  if (!exe) return skip('No Chrome or Chromium here, so the built pages were not audited (L001–L030). Set `WEFT_CHROME`, or run `weft audit --url <deploy>` where there is one.')
+  let base = options.url?.replace(/\/$/, '')
+  let server
+  let routes = options.routes
+  if (!base) {
+    const dir = options.dir ?? builtPublic(root)
+    if (!dir) return skip('No built pages to audit: run `weft build` first, or pass `--url`.')
+    const pages = pagesIn(dir)
+    if (!pages.length) return skip(`No prerendered pages in ${relative(root, dir)} to audit: pass \`--url\` to audit a running server.`)
+    routes ??= options.all ? pages : samplePages(pages, options.max)
+    server = await serveStatic(dir)
+    base = server.url
+  }
+  routes ??= ['/']
+  const browser = await chrome(exe)
+  const findings = new Map()
+  try {
+    const jobs = routes.flatMap(route => forms.map(form => ({ route, form })))
+    let i = 0
+    const worker = async () => {
+      for (let job; (job = jobs[i++]);) {
+        for (const f of await auditPage(browser, `${base}${job.route}`, job.form, !!server)) {
+          const key = `${f.code} ${f.key}`
+          const seen = findings.get(key) ?? { ...f, routes: new Set(), forms: new Set() }
+          seen.routes.add(job.route)
+          seen.forms.add(job.form)
+          findings.set(key, seen)
+        }
+      }
+    }
+    await Promise.all(Array.from({ length: Math.min(options.concurrency ?? 4, jobs.length) }, worker))
+  } finally {
+    browser.close()
+    server?.close()
+  }
+  const diagnostics = [...findings.values()].map(f => {
+    const pages = routes.filter(r => f.routes.has(r))
+    const on = `${forms.filter(x => f.forms.has(x)).join(' and ')}, ${pages.length === 1 ? pages[0] : `${pages.length} pages (${pages.slice(0, 3).join(', ')}${pages.length > 3 ? ', …' : ''})`}`
+    const severity = f.code === 'L031' && f.cls > 0.1 ? 'error' : SEVERITY[f.code] ?? 'error'
+    // an axe rule outside L001–L003 carries its own fix: the rule's first remedy, and its page
+    const help = f.code === 'L004' ? `${f.fix ? `${f.fix}. ` : ''}${WARP[f.rule] ?? ''}The rule: https://dequeuniversity.com/rules/axe/4.14/${f.rule}` : undefined
+    return diagnostic({ code: f.code, severity, file: pages[0], why: `${say[f.code](f)} (${on})`, help })
+  }).sort((a, b) => (a.severity === b.severity ? a.code.localeCompare(b.code) : a.severity === 'error' ? -1 : 1))
+  return { ok: !diagnostics.some(d => d.severity === 'error'), base: options.url ?? base, pages: routes, diagnostics, ms: Math.round(performance.now() - t) }
+}

package/src/browser/cli.mjs

@@ -0,0 +1,34 @@
+// `weft browser <command>`: JSON on stdout with --json, a readable form on stderr otherwise.
+
+import { browser, browserUsage, cliParams } from './commands.mjs'
+
+export { browserUsage }
+
+export async function browserCommand(args, { print, say, io }) {
+  const [cmd, ...words] = args.positional
+  if (!cmd || cmd === 'help') {
+    say(browserUsage)
+    return cmd ? 0 : 2
+  }
+  try {
+    const result = await browser(args.root, cmd, cliParams(cmd, words, args.flags), { url: args.flags.url, tab: args.flags.tab })
+    if (args.json) print(result)
+    else io.stdout.write(`${human(cmd, result)}\n`)
+    return result?.ok === false ? 1 : 0
+  } catch (error) {
+    if (error.code === 'E_USAGE') throw error
+    if (args.json) print({ ok: false, error: { code: error.code ?? 'E_INTERNAL', message: error.message, tabs: error.tabs } })
+    say(`weft browser ${cmd}: ${error.message}`)
+    return 1
+  }
+}
+
+function human(cmd, r) {
+  const text = v => (typeof v === 'string' ? v : v?.path ? `(${v.chars} chars in ${v.path})\n${v.head}` : '')
+  if (cmd === 'snapshot') return [`${r.title} ${r.url}`, r.delta ?? text(r.tree), r.graph ? `\n# graph\n${text(r.graph)}` : '', r.errors?.length ? `\n# errors\n${r.errors.map(e => `${e.message}${e.at ? ` (at ${e.at})` : ''}`).join('\n')}` : ''].filter(Boolean).join('\n')
+  if (cmd === 'act') return `${r.target}: ${r.changes}`
+  if (cmd === 'assert') return `${r.ok ? 'ok' : 'FAIL'} ${r.target} ${JSON.stringify(r.expected)}${r.ok ? '' : `, got ${JSON.stringify(r.actual)}`}`
+  if (cmd === 'graph') return text(r.graph)
+  if (cmd === 'record' && r.code) return r.code
+  return JSON.stringify(r, null, 2)
+}

package/src/browser/client.mjs

@@ -0,0 +1,132 @@
+// The `weft browser` transport: commands go to the dev server, which relays them to an open tab of the app (@weft-js/core/agent
+// in the page). No browser automation library: the page is whatever browser the agent or person already has open. When
+// there is none (CI, a sandbox), `launch` starts a plain headless Chrome on the app as a host page, and `screenshot`
+// reads it over the DevTools protocol.
+
+import { spawn } from 'node:child_process'
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { loadConfig } from '../load-config.mjs'
+
+/** The dev server: `--url`, else what the weft() plugin wrote to `.weft/dev.json`, else `environments.dev.url`. */
+export async function devUrl(root, given) {
+  if (given) return given.replace(/\/$/, '')
+  const file = join(root, '.weft', 'dev.json')
+  if (existsSync(file)) {
+    try { return JSON.parse(readFileSync(file, 'utf8')).url.replace(/\/$/, '') } catch {}
+  }
+  const { config } = await loadConfig(root).catch(() => ({ config: {} }))
+  return (config.environments?.dev?.url ?? 'http://localhost:5173').replace(/\/$/, '')
+}
+
+const fail = (code, message, extra) => Object.assign(new Error(message), { code, ...extra })
+
+async function request(url, init) {
+  try {
+    const res = await fetch(`${url}/__weft/agent`, { ...init, headers: { 'x-weft-agent': '1', 'content-type': 'application/json' } })
+    if (res.status === 404) throw fail('E_NO_BRIDGE', `${url} is not a weft dev server (no /__weft/agent): serve the app with the weft() Vite plugin`)
+    return await res.json()
+  } catch (e) {
+    if (e.code) throw e
+    throw fail('E_NO_DEV', `no dev server answers at ${url}: start it (vite), or pass --url`)
+  }
+}
+
+/** Run one command in a tab (the focused one, else the most recent). */
+export async function call(root, cmd, args = {}, { url, tab, timeout } = {}) {
+  const base = await devUrl(root, url)
+  const out = await request(base, { method: 'POST', body: JSON.stringify({ cmd, args, tab, timeout }) })
+  if (!out.ok) throw fail(out.code ?? 'E_PAGE', out.error, { tabs: out.tabs })
+  return out.result
+}
+
+export async function tabs(root, { url } = {}) {
+  const base = await devUrl(root, url)
+  const out = await request(base, { method: 'GET' })
+  return { url: base, agent: out.agent, tabs: out.tabs }
+}
+
+/** Wait until a tab is connected (after `launch` or `navigate`). */
+export async function waitForTab(root, { url, ms = 15_000 } = {}) {
+  const until = Date.now() + ms
+  for (;;) {
+    try {
+      const t = await tabs(root, { url })
+      if (t.tabs.length) return t
+    } catch (e) { if (Date.now() > until) throw e }
+    if (Date.now() > until) throw fail('E_NO_TAB', 'no tab connected in time')
+    await new Promise(r => { setTimeout(r, 150) })
+  }
+}
+
+// ---- a host page when the agent has no browser ------------------------------------------------------------------
+
+const chromes = {
+  darwin: ['/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', '/Applications/Chromium.app/Contents/MacOS/Chromium', '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge'],
+  linux: ['/usr/bin/google-chrome', '/usr/bin/google-chrome-stable', '/usr/bin/chromium', '/usr/bin/chromium-browser', '/snap/bin/chromium'],
+  win32: ['C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe', 'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe'],
+}
+
+export function findChrome() {
+  const env = process.env.WEFT_CHROME ?? process.env.CHROME_PATH
+  if (env && existsSync(env)) return env
+  return (chromes[process.platform] ?? []).find(p => existsSync(p)) ?? null
+}
+
+const stateFile = root => join(root, '.weft', 'browser', 'chrome.json')
+
+/** Start a headless Chrome on `route` (a plain page; @weft-js/core/agent in it connects back to the dev server). */
+export async function launch(root, route = '/', { url, headed = false } = {}) {
+  const exe = findChrome()
+  if (!exe) throw fail('E_NO_CHROME', 'no Chrome or Chromium found; open the app in your own browser instead, or set WEFT_CHROME')
+  close(root)
+  const base = await devUrl(root, url)
+  const profile = join(root, '.weft', 'browser', 'profile')
+  mkdirSync(profile, { recursive: true })
+  const args = [`--user-data-dir=${profile}`, '--remote-debugging-port=0', '--no-first-run', '--no-default-browser-check', '--disable-background-timer-throttling', '--disable-renderer-backgrounding', ...(headed ? [] : ['--headless=new']), `${base}${route.startsWith('/') ? route : `/${route}`}`]
+  const child = spawn(exe, args, { detached: true, stdio: 'ignore' })
+  child.unref()
+  writeFileSync(stateFile(root), JSON.stringify({ pid: child.pid, profile, exe }))
+  const t = await waitForTab(root, { url })
+  return { launched: true, pid: child.pid, headless: !headed, ...t }
+}
+
+export function close(root) {
+  const file = stateFile(root)
+  if (!existsSync(file)) return { closed: false }
+  const { pid } = JSON.parse(readFileSync(file, 'utf8'))
+  try { process.kill(pid) } catch {}
+  rmSync(file, { force: true })
+  return { closed: true, pid }
+}
+
+/** A PNG of the launched Chrome's page (DevTools protocol). An agent's own browser takes its own screenshots. */
+export async function screenshot(root, out) {
+  const file = stateFile(root)
+  if (!existsSync(file)) throw fail('E_NO_CHROME', 'screenshot needs `weft browser launch`; in your own browser, use its screenshot tool')
+  const { profile } = JSON.parse(readFileSync(file, 'utf8'))
+  const [port] = readFileSync(join(profile, 'DevToolsActivePort'), 'utf8').split('\n')
+  const targets = await (await fetch(`http://127.0.0.1:${port}/json`)).json()
+  const page = targets.find(t => t.type === 'page')
+  if (!page) throw fail('E_NO_TAB', 'the launched Chrome has no page')
+  const ws = new WebSocket(page.webSocketDebuggerUrl)
+  await new Promise((ok, no) => { ws.onopen = ok; ws.onerror = () => no(fail('E_CDP', 'could not reach the page over the DevTools protocol')) })
+  const data = await new Promise((ok, no) => {
+    ws.onmessage = e => { const m = JSON.parse(e.data); if (m.id !== 1) return; if (m.error) no(fail('E_CDP', m.error.message)); else ok(m.result.data) }
+    ws.send(JSON.stringify({ id: 1, method: 'Page.captureScreenshot', params: { format: 'png' } }))
+  })
+  ws.close()
+  const path = out ?? join(root, '.weft', 'browser', `screenshot-${Date.now()}.png`)
+  mkdirSync(join(path, '..'), { recursive: true })
+  writeFileSync(path, Buffer.from(data, 'base64'))
+  return { path }
+}
+
+/** Big payloads go to a file; the reply holds the path (research 05: snapshots pile up in context). */
+export function spill(root, name, text, limit = 8000) {
+  if (typeof text !== 'string' || text.length <= limit) return text
+  const path = join(root, '.weft', 'browser', `${name}-${Date.now()}.txt`)
+  mkdirSync(join(path, '..'), { recursive: true })
+  writeFileSync(path, text)
+  return { path, chars: text.length, head: `${text.slice(0, 1200)}\n…` }
+}

package/src/browser/commands.mjs

@@ -0,0 +1,143 @@
+// `weft browser` commands, shared by the CLI and the `weft mcp` browser tools. Each takes structured params and
+// returns JSON; the page side is @weft-js/core/agent (packages/weft/src/agent.ts).
+
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, isAbsolute, join } from 'node:path'
+import { call, close, launch, screenshot, spill, tabs, waitForTab } from './client.mjs'
+
+export const actions = ['click', 'dblclick', 'hover', 'focus', 'clear', 'fill', 'type', 'press', 'select', 'check', 'uncheck']
+export const expectations = ['visible', 'absent', 'text', 'exactText', 'value', 'checked', 'unchecked', 'disabled', 'enabled', 'focused', 'count']
+
+const sleep = ms => new Promise(r => { setTimeout(r, ms) })
+
+/**
+ * @param {string} root project root
+ * @param {string} cmd
+ * @param {Record<string, any>} p params
+ * @param {{ url?: string, tab?: string }} [o] dev server URL and tab
+ */
+export async function browser(root, cmd, p = {}, o = {}) {
+  const page = (name, args, extra) => call(root, name, args, { ...o, ...extra })
+  switch (cmd) {
+    case 'tabs': return tabs(root, o)
+    case 'launch': return launch(root, p.route ?? '/', { url: o.url, headed: p.headed })
+    case 'close': return close(root)
+    case 'open': {
+      const before = await page('info', {})
+      await page('navigate', { to: p.route ?? '/' })
+      // Same tab id after the load (@weft-js/core/agent keeps it in sessionStorage); wait for the new document to say hello.
+      const until = Date.now() + 15_000
+      do {
+        await sleep(150)
+        try {
+          const info = await page('info', {}, { timeout: 2000 })
+          if (info.url !== before.url || p.route === new URL(before.url).pathname) return info
+        } catch {}
+      } while (Date.now() <= until)
+      return waitForTab(root, o)
+    }
+    case 'snapshot': {
+      const out = await page('snapshot', { interactive: p.interactive, scope: p.scope, delta: p.delta, graph: p.graph })
+      if (!p.full) {
+        if (out.tree) out.tree = spill(root, 'snapshot', out.tree)
+        if (out.graph) out.graph = spill(root, 'graph', out.graph)
+      }
+      return out
+    }
+    case 'act': return page('act', { target: p.target, action: p.action, value: p.value })
+    case 'assert': return page('assert', { target: p.target, expect: p.expect, timeout: p.timeout })
+    case 'graph': {
+      const out = await page('graph', { filter: p.filter })
+      return { graph: p.full ? out.graph : spill(root, 'graph', out.graph), nodes: out.nodes.length }
+    }
+    case 'set': return page('set', { name: p.name, value: p.value })
+    case 'time': return page('time', { op: p.op, ms: p.ms, reload: p.reload })
+    case 'net': return page('net', { op: p.op, ms: p.ms })
+    case 'record': {
+      const out = await page('record', { op: p.op, text: p.text, component: p.component, from: p.from, props: p.props, imports: p.imports, name: p.name })
+      if (p.op === 'code' && p.out) {
+        const file = isAbsolute(p.out) ? p.out : join(root, p.out)
+        mkdirSync(dirname(file), { recursive: true })
+        writeFileSync(file, out.code)
+        return { ...out, written: file }
+      }
+      return out
+    }
+    case 'logs': return page('logs', {})
+    case 'overlay': return page('overlay', { show: p.show })
+    case 'info': return page('info', {})
+    case 'reload': return page('reload', {})
+    case 'screenshot': return screenshot(root, p.out && (isAbsolute(p.out) ? p.out : join(root, p.out)))
+    default:
+      throw Object.assign(new Error(`unknown browser command ${cmd}`), { code: 'E_USAGE' })
+  }
+}
+
+/** `button "Add Banana"`, `label Coupon`, `text Cart`, `@e5` → a target, and how many words it took. */
+export function parseTarget(words) {
+  const [a, b] = words
+  if (!a) throw Object.assign(new Error('missing target: <role> <name>, label <text>, text <text>, or @ref'), { code: 'E_USAGE' })
+  if (a.startsWith('@')) return [a, 1]
+  if (a === 'label') return [{ label: b }, 2]
+  if (a === 'text') return [{ text: b }, 2]
+  return [b === undefined || b === '-' ? { role: a } : { role: a, name: b }, b === undefined ? 1 : 2]
+}
+
+/** CLI words → params. */
+export function cliParams(cmd, words, flags) {
+  const num = v => (v === undefined ? undefined : Number(v))
+  switch (cmd) {
+    case 'launch': case 'open': return { route: words[0] ?? '/', headed: !!flags.headed }
+    case 'snapshot': return { interactive: !!flags.interactive, delta: !!flags.delta, graph: flags['graph-only'] ? 'only' : flags['no-graph'] ? false : flags.graph ?? true, scope: flags.scope ? parseScope(flags.scope) : undefined, full: !!flags.full }
+    case 'act': {
+      const [target, n] = parseTarget(words)
+      const action = words[n] ?? 'click'
+      if (!actions.includes(action)) throw Object.assign(new Error(`unknown action ${action}: ${actions.join(', ')}`), { code: 'E_USAGE' })
+      return { target, action, value: words[n + 1] }
+    }
+    case 'assert': {
+      const [target, n] = parseTarget(words)
+      const kind = words[n] ?? 'visible'
+      if (!expectations.includes(kind)) throw Object.assign(new Error(`unknown expectation ${kind}: ${expectations.join(', ')}`), { code: 'E_USAGE' })
+      const v = words[n + 1]
+      return { target, expect: { [kind]: kind === 'count' ? Number(v) : ['text', 'exactText', 'value'].includes(kind) ? v ?? '' : true }, timeout: num(flags.timeout) }
+    }
+    case 'graph': return { filter: words[0], full: !!flags.full }
+    case 'set': {
+      let value = words[1]
+      try { value = JSON.parse(words[1]) } catch {}
+      return { name: words[0], value }
+    }
+    case 'time': return { op: words[0] ?? 'status', ms: num(words[1]), reload: !!flags.reload }
+    case 'net': return { op: words[0] ?? 'status', ms: num(words[1]) }
+    case 'record': return { op: words[0] ?? 'code', text: words.slice(1).join(' '), component: flags.component, from: flags.from, props: flags.props, name: flags.name, out: flags.out }
+    case 'overlay': return { show: words[0] === undefined ? undefined : words[0] !== 'off' }
+    case 'screenshot': return { out: flags.out }
+    default: return {}
+  }
+}
+
+const parseScope = s => (s.startsWith('@') ? s : (() => { const i = s.indexOf(':'); return i < 0 ? { role: s } : { role: s.slice(0, i), name: s.slice(i + 1) } })())
+
+export const browserUsage = `usage: weft browser <command> [--json] [--url <dev server>] [--tab <id>]
+
+  The page is the app open in any browser (yours, an agent's, or \`launch\`); the dev server relays to it.
+  In a browser that runs JS, the same commands are \`await __weft__.agent.run('<command>', args)\`.
+
+  tabs                               tabs connected to the dev server
+  launch [route] [--headed]          start a headless Chrome on the app (when you have no browser)
+  open <route>                       navigate the tab
+  snapshot [--interactive] [--delta] [--scope role:name|@ref] [--graph-only|--no-graph] [--full]
+                                     roles, names and refs, plus the reactive graph (Cart.total = 42.5 ← …)
+  act <role> <name> <action> [value] click dblclick hover focus clear fill type press select check uncheck
+  act @e5 <action> [value]           (or: act label <text> …, act text <text> …)
+  assert <target> <expectation> [v]  visible absent text exactText value checked unchecked disabled enabled focused count
+  graph [filter]                     the named reactive graph
+  set <Name.box> <json>              write state by its graph name (dev only)
+  time pause [--reload]|advance <ms>|resume|status
+  net offline|online|latency <ms>|drop|reset|status
+  record start|stop|note <text>|code [--component App --from ./App --props '{…}' --out file.test.tsx]
+  logs                               console errors/warnings and uncaught errors since the last call
+  overlay [on|off]                   the graph panel in the page (Alt+Shift+G)
+  screenshot [--out file.png]        launched Chrome only; use your own browser's screenshot otherwise
+  close                              stop the launched Chrome`