kaloko 0.3.0

package/src/lib/design.mjs

@@ -0,0 +1,164 @@
+// Design environments (#42): a folder of live HTML steps, served locally, rendered into captures and
+// exchanged with the service as revisions of a shared draft. Node side of design-core.mjs.
+import { createServer } from 'node:http'
+import { readFile, readdir, stat, mkdir, writeFile, copyFile, rm } from 'node:fs/promises'
+import { join, resolve, dirname, relative, sep } from 'node:path'
+import { UserError } from './util.mjs'
+import { bundleProblems, closure, contentTypeOf, revisionId, sha256Hex, TOKENS_FILE, SHARED_DIR, extOf } from './design-core.mjs'
+
+export const isDesign = (env) => env?.kind === 'design'
+
+/** Absolute design folder of a design environment. */
+export function designDir (env, root) {
+  if (!isDesign(env)) throw new UserError(`Environment ${env?.name} is not a design environment (kind: design).`)
+  return resolve(root, env.serve)
+}
+
+const exists = async (p) => { try { await stat(p); return true } catch { return false } }
+const isFile = async (p) => { try { return (await stat(p)).isFile() } catch { return false } }
+const toPosix = (p) => p.split(sep).join('/')
+
+async function listFiles (dir, base = dir) {
+  let entries = []
+  try { entries = await readdir(dir, { withFileTypes: true }) } catch { return [] }
+  const out = []
+  for (const e of entries) {
+    if (e.name.startsWith('.')) continue
+    const full = join(dir, e.name)
+    if (e.isDirectory()) out.push(...await listFiles(full, base))
+    else out.push(toPosix(relative(base, full)))
+  }
+  return out
+}
+
+/**
+ * The files of one step in one locale: `<step>/<locale>/…` overrides `<step>/…` (other locales' folders
+ * are left out), plus every bundle file those reference. Returns { entry, files: [{ path, bytes, hash }] }
+ * or null when the step has no folder.
+ */
+export async function scanStep ({ dir, node, locale, locales }) {
+  const stepDir = join(dir, node)
+  if (!await exists(stepDir)) return null
+  const own = await listFiles(stepDir)
+  const localeDirs = new Set(locales)
+  const common = own.filter((p) => !localeDirs.has(p.split('/')[0]))
+  const mine = own.filter((p) => p.split('/')[0] === locale)
+  const entry = mine.includes(`${locale}/index.html`) ? `${node}/${locale}/index.html` : common.includes('index.html') ? `${node}/index.html` : null
+  if (!entry) throw new UserError(`Design step ${node}: add ${node}/index.html (or ${node}/${locale}/index.html).`)
+  // roots: the entry and the assets next to it (not the other pages of the folder: a locale's page must not pull in
+  // the default page or another locale's); everything else comes in through references
+  const entryDir = entry.slice(0, entry.lastIndexOf('/') + 1)
+  const beside = (entryDir === `${node}/` ? common : mine.map((p) => p.slice(locale.length + 1))).filter((p) => !p.includes('/') && extOf(p) !== 'html')
+  const roots = [entry, ...beside.map((p) => entryDir + p)]
+  const paths = await closure({ roots, read: (p) => readFile(join(dir, p), 'utf8'), exists: (p) => isFile(join(dir, p)) })
+  const files = []
+  for (const path of paths) {
+    const buf = await readFile(join(dir, path))
+    files.push({ path, bytes: buf.length, hash: await sha256Hex(buf) })
+  }
+  const problems = bundleProblems(files, entry)
+  if (problems.length) throw new UserError(`Design step ${node} (${locale}) breaks the bundle rules:\n  - ${problems.join('\n  - ')}`)
+  return { entry, files }
+}
+
+/** Token set reference of the design folder (tokens.json), or null. */
+export async function tokensRef (dir, project) {
+  const file = join(dir, TOKENS_FILE)
+  if (!await exists(file)) return null
+  const text = await readFile(file, 'utf8')
+  try { JSON.parse(text) } catch (e) { throw new UserError(`${TOKENS_FILE} is not valid JSON: ${e.message}`) }
+  return { project: project || null, version: null, hash: await sha256Hex(text) }
+}
+
+/** A revision of one step and locale, with its id. */
+export async function revisionOf ({ dir, scenario, node, locale, locales, tokens }) {
+  const scan = await scanStep({ dir, node, locale, locales })
+  if (!scan) return null
+  // the token set travels with every revision: the canvas inspector names values from it on the live origin
+  if (tokens && !scan.files.some((f) => f.path === TOKENS_FILE)) {
+    const buf = await readFile(join(dir, TOKENS_FILE))
+    scan.files.push({ path: TOKENS_FILE, bytes: buf.length, hash: await sha256Hex(buf) })
+  }
+  const files = Object.fromEntries(scan.files.map((f) => [f.path, f.hash]))
+  const id = await revisionId({ scenario, node, locale, entry: scan.entry, files, tokens })
+  return { id, scenario, node, locale, state: 'default', kind: 'design', entry: scan.entry, files, sizes: Object.fromEntries(scan.files.map((f) => [f.path, f.bytes])), tokens }
+}
+
+/**
+ * Serves the design folder on 127.0.0.1 (random port). Only GET/HEAD of allowed bundle types;
+ * nothing outside the folder, no directory listings. Returns { url, close }.
+ */
+export async function serveDesign (dir) {
+  const server = createServer(async (req, res) => {
+    try {
+      if (!['GET', 'HEAD'].includes(req.method)) { res.writeHead(405).end(); return }
+      let path = decodeURIComponent(new URL(req.url, 'http://x').pathname).replace(/^\/+/, '')
+      if (!path || path.endsWith('/')) path += 'index.html'
+      const full = resolve(dir, path)
+      const type = contentTypeOf(path)
+      if (!full.startsWith(dir + sep) || !type || path.split('/').some((s) => s.startsWith('.'))) { res.writeHead(404).end(); return }
+      const body = await readFile(full)
+      res.writeHead(200, { 'Content-Type': type, 'Cache-Control': 'no-store' })
+      res.end(req.method === 'HEAD' ? undefined : body)
+    } catch { res.writeHead(404).end() }
+  })
+  await new Promise((ok) => server.listen(0, '127.0.0.1', ok))
+  return { url: `http://127.0.0.1:${server.address().port}`, close: () => new Promise((ok) => server.close(ok)) }
+}
+
+/** Copies the live files of a revision into the run directory (live/<revision>/<path>) for the local preview. */
+export async function copyLive (runDir, dir, rev) {
+  const base = join(runDir, 'live', rev.id)
+  for (const path of Object.keys(rev.files)) {
+    const to = join(base, path)
+    if (await exists(to)) continue
+    await mkdir(dirname(to), { recursive: true })
+    await copyFile(join(dir, path), to)
+  }
+}
+
+// ---- render cache: a capture is reused when the same revision was rendered in the same viewport ----
+
+export const cacheDir = (root, output) => resolve(root, output, '.cache', 'design')
+
+export async function fromCache ({ root, output, key }) {
+  const dir = join(cacheDir(root, output), key.replace(/[^A-Za-z0-9_-]/g, '_'))
+  try { return { dir, record: JSON.parse(await readFile(join(dir, 'capture.json'), 'utf8')) } } catch { return null }
+}
+
+export async function toCache ({ root, output, key, runDir, record }) {
+  const dir = join(cacheDir(root, output), key.replace(/[^A-Za-z0-9_-]/g, '_'))
+  await rm(dir, { recursive: true, force: true })
+  await mkdir(dir, { recursive: true })
+  for (const f of ['image', 'thumb', 'html']) if (record.files[f]) await copyFile(join(runDir, record.files[f]), join(dir, `${f}.${extOf(record.files[f])}`))
+  await writeFile(join(dir, 'capture.json'), JSON.stringify(record))
+}
+
+/** Restores a cached capture into the run directory under the step's paths; returns the new record. */
+export async function restoreCached ({ cached, runDir, paths, node, locale, viewport }) {
+  const rec = JSON.parse(JSON.stringify(cached.record))
+  const files = {}
+  for (const f of ['image', 'thumb', 'html']) {
+    if (!rec.files[f]) continue
+    const ext = f === 'thumb' ? 'thumb.webp' : extOf(rec.files[f])
+    const to = paths.step(node, locale, viewport, ext)
+    await mkdir(dirname(to), { recursive: true })
+    await copyFile(join(cached.dir, `${f}.${extOf(rec.files[f])}`), to)
+    files[f] = toPosix(relative(runDir, to))
+  }
+  rec.files = { png: files.image, image: files.image, thumb: files.thumb || null, html: files.html }
+  return rec
+}
+
+// ---- draft base: which draft revisions the local folder was last synced with ----
+
+const baseFile = (dir) => join(dir, '.qawalk', 'draft.json')
+export async function readBase (dir) { try { return JSON.parse(await readFile(baseFile(dir), 'utf8')) } catch { return null } }
+export async function writeBase (dir, base) {
+  await mkdir(dirname(baseFile(dir)), { recursive: true })
+  await writeFile(baseFile(dir), JSON.stringify(base, null, 2) + '\n')
+  await writeFile(join(dir, '.qawalk', '.gitignore'), '*\n').catch(() => {})
+}
+
+export const headKey = (node, locale, state = 'default') => `${node}|${locale}|${state}`
+export { SHARED_DIR }

package/src/lib/doctor.mjs

@@ -0,0 +1,149 @@
+// `kaloko doctor`: is this project ready to run and share a walkthrough?
+// Every check returns { name, ok, detail, hint } so the CLI and tests can read it.
+import { appTools, macPermissions } from './apps/drivers.mjs'
+import { createServer } from 'node:net'
+import { access as exists, stat } from 'node:fs/promises'
+import { resolve } from 'node:path'
+import { environment } from './config.mjs'
+import { gateOf, gateHeaders, accountFor } from './access.mjs'
+import { missing } from './secrets.mjs'
+import { portFor } from './browser.mjs'
+import { DEFAULTS as JEV } from './jev.mjs'
+import { serviceUrl } from './service.mjs'
+
+const portFree = (port) => new Promise((done) => {
+  const s = createServer().once('error', () => done(false)).once('listening', () => s.close(() => done(true)))
+  s.listen(port, '127.0.0.1')
+})
+
+async function reach (url, fetchImpl, ms = 6000, headers = {}) {
+  const ctl = new AbortController(); const t = setTimeout(() => ctl.abort(), ms)
+  try {
+    const res = await fetchImpl(url, { method: 'GET', redirect: 'manual', signal: ctl.signal, headers: { 'User-Agent': 'kaloko-doctor', ...headers } })
+    return { ok: res.status < 500, status: res.status }
+  } catch (e) { return { ok: false, error: e.name === 'AbortError' ? `no answer in ${ms / 1000} s` : e.message } } finally { clearTimeout(t) }
+}
+
+/**
+ * @param {object} o
+ * @param {object} o.config loaded kaloko.config.yml
+ * @param {string} o.root project root
+ * @param {Function} [o.fetchImpl]
+ * @param {Function} [o.launchChrome] async () => { version } — throws when Chrome is missing
+ * @param {object} [o.env] process.env
+ */
+export async function doctor ({ config, root, fetchImpl = fetch, launchChrome = defaultLaunch, env = process.env, fix = false }) {
+  const checks = []
+  const add = (name, ok, detail = '', hint = '') => checks.push({ name, ok, detail, hint })
+
+  const major = Number(process.versions.node.split('.')[0])
+  add('node', major >= 20, `Node ${process.versions.node}`, major >= 20 ? '' : 'Kaloko needs Node 20 or newer.')
+
+  add('config', true, `${root}/qawalk.config.yml · org ${config.org || '—'} · ${Object.keys(config.environments || {}).length} environments`)
+  if (!config.org) add('org', false, 'no org in config', 'Set org: <slug> (the organization slug from kaloko.app).')
+
+  try { const c = await launchChrome(config); add('chrome', true, c.version ? `Chrome ${c.version}` : 'Chrome found') } catch (e) { add('chrome', false, e.message.split('\n')[0].slice(0, 160), config.browser?.channel ? 'Install Google Chrome, or remove browser.channel to use bundled Chromium (npx playwright install chromium).' : 'Run: npx playwright install chromium') }
+
+  for (const name of Object.keys(config.environments || {})) {
+    let e
+    try { e = environment(config, name, env) } catch (err) { add(`env ${name}`, false, err.message, 'Set the variable, or run doctor where CI provides it.'); continue }
+    const port = portFor(config, name)
+    const free = await portFree(port)
+    add(`port ${name}`, true, `${port} ${free ? 'free' : 'in use (shared browser running, or another project)'}`)
+    const base = typeof e.base_url === 'string' ? e.base_url : Object.values(e.base_url || {})[0]
+    // apps: the tools their driver needs
+    for (const p of Object.keys(e.app || {})) {
+      const t = await appTools()
+      if (p === 'android') add(`app ${name} android`, t.adb, t.adb ? `adb found · ${e.app.android.package || 'no package'}` : 'adb not found', 'Install Android platform-tools and start an emulator or connect a device (adb devices).')
+      if (p === 'ios') add(`app ${name} ios`, t.simctl, t.simctl ? `simctl · ${t.idb ? 'idb for the UI tree and taps' : 'no idb: screen text by OCR, deep links only'}` : 'Xcode simctl not found', 'Install Xcode with an iOS Simulator runtime; optional idb (brew install facebook/fb/idb-companion, pip install fb-idb) for the UI tree and taps.')
+      if (p === 'desktop') {
+        if (process.platform !== 'darwin') { add(`app ${name} desktop`, false, 'built-in desktop capture needs macOS', 'On Windows or Linux capture with kaloko capture --image --tree.'); continue }
+        const perm = await macPermissions(false).catch(() => null)
+        add(`app ${name} desktop`, !!perm?.screen, perm ? `Screen Recording ${perm.screen ? 'allowed' : 'not allowed'} · Accessibility ${perm.accessibility ? 'allowed (UI tree)' : 'not allowed (text by OCR)'}` : 'the macOS helper could not run', perm?.screen ? '' : 'Run kaloko doctor --fix to ask macOS, then turn this terminal on in System Settings → Privacy & Security → Screen Recording (and Accessibility for the UI tree) and restart it.')
+        if (fix && perm && (!perm.screen || !perm.accessibility)) await macPermissions(true).catch(() => {})
+      }
+      if (p === 'electron') add(`app ${name} electron`, true, e.app.electron.main || e.app.electron.executable || 'electron')
+    }
+    if (!base && e.app) continue
+    if (!base) { add(`env ${name}`, false, 'no base_url', 'Every environment needs base_url (or an app block for app scenarios).'); continue }
+    // the gate in front of the environment: its variables, then a request through it
+    const gate = gateOf(e)
+    const gateVars = [gate.basic?.user_env, gate.basic?.password_env, ...Object.values(gate.headers || {}).map((h) => h?.env), gate.client_certificate?.cert_env, gate.client_certificate?.key_env, gate.client_certificate?.passphrase_env]
+    const unset = missing(gateVars, env)
+    if (unset.length) { add(`access ${name}`, false, `not set: ${unset.join(', ')}`, `Put them into .env or ~/.config/kaloko/.env (ask whoever runs ${name} for the values).`); continue }
+    let headers = {}
+    try { headers = gateHeaders(e, env) } catch (err) { add(`access ${name}`, false, err.message); continue }
+    const certOnly = !!gate.client_certificate && !Object.keys(headers).length
+    const r = await reach(base, fetchImpl, 6000, headers)
+    const denied = r.status === 401 || r.status === 403
+    let hint = ''
+    if (denied) hint = Object.keys(headers).length ? `The gate rejected the credentials in access (HTTP ${r.status}); check the values.` : `The environment is protected (HTTP ${r.status}). Describe its gate under environments.${name}.access (basic, headers or client_certificate).`
+    else if (!r.ok) hint = name === 'local' ? 'Start the application locally, or run against another environment.' : 'Check the URL and your network or VPN.'
+    // doctor does not present client certificates; with mutual TLS only the browser gets through
+    const ok = certOnly || (r.ok && !denied)
+    add(`env ${name}`, ok, `${base} → ${r.error || `HTTP ${r.status}`}${Object.keys(headers).length ? ' · through the gate' : ''}${certOnly ? ' · client certificate (checked by the browser only)' : ''}${e.readonly ? ' · readonly' : ''}`, ok ? '' : hint)
+    for (const [key, spec] of Object.entries(e.accounts || {})) {
+      const need = missing([spec.user_env, spec.password_env, spec.totp_env], env)
+      const saved = await stat(accountFor(e, key, { root, config }).storage_state).catch(() => null)
+      const detail = saved ? `saved sign-in ${Math.round((Date.now() - saved.mtimeMs) / 36e5)} h old` : 'no saved sign-in'
+      add(`account ${name}/${key}`, !need.length || !!saved, need.length ? `not set: ${need.join(', ')} · ${detail}` : detail, need.length && !saved ? `Set the variables, or have a person run: kaloko auth save --env ${name} --account ${key}` : '')
+    }
+    const mail = e.mail
+    if (mail?.provider === 'script') {
+      const file = resolve(root, mail.script || '')
+      const found = mail.script && await exists(file).then(() => true, () => false)
+      add(`mail ${name}`, !!found, found ? `script ${mail.script}` : `mail.script ${mail.script || '(missing)'} not found`, found ? '' : 'Point mail.script to the adapter module (see templates/mail/letter-opener.mjs in the package).')
+    } else if (mail?.provider === 'mailpit' && mail.url) {
+      const basic = mail.auth?.basic || (mail.user_env ? mail : null)
+      const need = missing([basic?.user_env, basic?.password_env, ...Object.values(mail.auth?.headers || {}).map((h) => h?.env)], env)
+      if (need.length) add(`mail ${name}`, false, `not set: ${need.join(', ')}`, 'Put the mailbox credentials into .env.')
+      else {
+        const m = await reach(mail.url.replace(/\/$/, '') + '/api/v1/info', fetchImpl, 6000, basic ? { Authorization: 'Basic ' + Buffer.from(`${env[basic.user_env]}:${env[basic.password_env]}`).toString('base64') } : {})
+        add(`mail ${name}`, m.ok && m.status < 400, `Mailpit ${mail.url} → ${m.error || `HTTP ${m.status}`}`, m.status === 401 || m.status === 403 ? 'Mailpit needs mail.auth (basic or headers).' : m.ok && m.status < 400 ? '' : 'Check mail.url and that Mailpit runs.')
+      }
+    }
+  }
+
+  const tokenEnv = config.share?.token_env || 'KALOKO_TOKEN'
+  const token = env[tokenEnv]
+  const service = serviceUrl(config, env)
+  if (!token) add('token', false, `${tokenEnv} not set`, `Create a tester token in ${service}/${config.org || '<org>'}/settings and put ${tokenEnv}=… into .env (or ~/.config/kaloko/.env).`)
+  else {
+    try {
+      const res = await fetchImpl(`${service}/api/v1/me`, { headers: { Authorization: `Bearer ${token}` } })
+      if (!res.ok) add('token', false, `${service} → HTTP ${res.status}`, res.status === 401 ? `${tokenEnv} is invalid, expired or revoked; create a new one in Settings.` : 'The service did not accept the request.')
+      else {
+        const me = await res.json()
+        const sameOrg = !config.org || me.org === config.org
+        add('token', sameOrg, `${me.email} · ${me.role} · org ${me.org}${me.role === 'viewer' ? ' (viewer tokens cannot share runs)' : ''}`, sameOrg ? '' : `The token belongs to organization "${me.org}" but the config says "${config.org}".`)
+        if (me.role === 'viewer') add('token role', false, 'viewer', 'kaloko share needs a tester token.')
+      }
+    } catch (e) { add('token', false, `${service} unreachable: ${e.message}`, 'Check your network; KALOKO_URL overrides the service URL.') }
+  }
+
+  const jev = config.evaluators?.jev
+  if (jev === null || config.evaluators?.jev === false) add('evaluator', true, 'semantic evaluator disabled in config')
+  else {
+    const keyEnv = jev?.api_key_env || JEV.api_key_env
+    if (env[keyEnv]) add('evaluator', true, `${keyEnv} set · your key · model ${jev?.model || JEV.model}`)
+    else if (token && jev?.hosted !== false) {
+      // no own key: the organization's service evaluates (plan allowance per month)
+      let s = null
+      try { const r = await fetchImpl(`${service}/api/v1/orgs/${config.org}/semantic`, { headers: { Authorization: `Bearer ${token}` } }); if (r.ok) s = await r.json() } catch {}
+      if (s?.available) add('evaluator', true, `via Kaloko · ${s.questions}${s.limit != null ? ` of ${s.limit}` : ''} questions this month`)
+      else add('evaluator', false, s ? 'hosted evaluation not included in the plan' : 'hosted evaluation unavailable', `Put ${keyEnv} into .env or ~/.config/kaloko/.env to evaluate with your own key${s ? ', or upgrade the plan' : ''}.`)
+    } else add('evaluator', false, `${keyEnv} not set`, `Semantic criteria will be "not evaluated" until ${keyEnv} is in .env or ~/.config/kaloko/.env${jev?.hosted === false ? '' : `, or ${tokenEnv} lets the service evaluate`}.`)
+  }
+
+  return { ok: checks.every((c) => c.ok), checks }
+}
+
+async function defaultLaunch (config) {
+  const { chromium } = await import('playwright')
+  const browser = await chromium.launch({ headless: true, channel: config.browser?.channel || undefined })
+  const version = browser.version()
+  await browser.close()
+  return { version }
+}
+
+export const formatDoctor = ({ ok, checks }) => [...checks.map((c) => `${c.ok ? '✓' : '✕'} ${c.name.padEnd(16)} ${c.detail}${!c.ok && c.hint ? `\n    → ${c.hint}` : ''}`), ok ? 'All good.' : 'Fix the ✕ items above.'].join('\n')

package/src/lib/draft.mjs

@@ -0,0 +1,76 @@
+// `kaloko draft <url…>`: a first acceptance plan and scenario for public pages, drafted from the pages
+// themselves (title, description, H1, language). Read-only production scenario with the seo, a11y, perf and
+// console packs; the agent or person then sharpens purposes and criteria. No service or model call.
+import yaml from 'js-yaml'
+
+const decode = (s) => String(s || '').replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;|&apos;/g, "'").replace(/&nbsp;/g, ' ').replace(/&#(\d+);/g, (_, n) => String.fromCharCode(Number(n)))
+const text = (html) => decode(String(html || '').replace(/<script[\s\S]*?<\/script>|<style[\s\S]*?<\/style>/gi, ' ').replace(/<[^>]+>/g, ' ')).replace(/\s+/g, ' ').trim()
+
+/** Title, description, first H1 and language of an HTML document (regex, no DOM). */
+export function pageFacts (html) {
+  const pick = (re) => { const m = String(html || '').match(re); return m ? text(m[1]) : '' }
+  const meta = (name) => { const m = String(html || '').match(new RegExp(`<meta[^>]+(?:name|property)=["']${name}["'][^>]*>`, 'i')); return m ? decode((m[0].match(/content=["']([^"']*)["']/i) || [])[1] || '').trim() : '' }
+  return { title: pick(/<title[^>]*>([\s\S]*?)<\/title>/i), description: meta('description') || meta('og:description'), h1: pick(/<h1[^>]*>([\s\S]*?)<\/h1>/i), lang: ((String(html || '').match(/<html[^>]*\blang=["']([a-zA-Z-]+)["']/i) || [])[1] || '').slice(0, 2).toLowerCase() }
+}
+
+const slug = (s) => String(s || '').toLowerCase().normalize('NFD').replace(/[̀-ͯ]/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40)
+
+/** pages: [{ url, facts }] (same origin) → { scenario, plan, origin } */
+export function draftScenario (pages, { id, title } = {}) {
+  if (!pages.length) throw new Error('Give at least one URL.')
+  const origin = new URL(pages[0].url).origin
+  for (const p of pages) if (new URL(p.url).origin !== origin) throw new Error(`All URLs must share one origin (${origin}); ${p.url} does not.`)
+  const host = new URL(origin).hostname.replace(/^www\./, '')
+  const ids = new Set()
+  const nodes = pages.map((p, i) => {
+    const u = new URL(p.url)
+    let nid = u.pathname === '/' ? 'home' : slug(u.pathname) || `page-${i + 1}`
+    while (ids.has(nid)) nid = `${nid}-${i + 1}`
+    ids.add(nid)
+    const f = p.facts || {}
+    const name = f.h1 || f.title || u.pathname
+    return {
+      id: nid, kind: 'screen', title: name.slice(0, 80), path: u.pathname + u.search,
+      purpose: f.description ? `A visitor understands: ${f.description}` : `A visitor understands what ${name} offers and what to do next.`,
+      packs: ['seo', 'a11y', 'perf', 'console'],
+      execution: i === 0
+        ? { strategy: 'playwright', script: 'steps/consent.mjs', instructions: 'Open the page as a new visitor and accept the consent dialog if there is one.' }
+        : { strategy: 'playwright', script: 'steps/open.mjs', instructions: `Open ${u.pathname}.` },
+      criteria: [
+        { id: 'AC1', text: 'One main heading', check: { type: 'deterministic', assert: 'count', selector: 'h1', min: 1, max: 1 } },
+        { id: 'AC2', text: 'The purpose is clear on the first screen', check: { type: 'semantic', question: `Does the first screen make clear${f.description ? ` that ${f.description.replace(/[.?!]+$/, '')}` : ' what this page offers'}, and what the visitor can do next?`, scope: 'main, body' } }
+      ]
+    }
+  })
+  // every site has an error page: an address that cannot exist must answer 404 with a way back
+  let nf = 'not-found'; while (ids.has(nf)) nf += '-page'
+  nodes.push({
+    id: nf, kind: 'screen', title: 'Page not found', path: '/no-such-page-{random}',
+    purpose: 'A visitor who follows a broken link gets a real 404 with a way back to the site.',
+    packs: ['errors'],
+    execution: { strategy: 'playwright', script: 'steps/open.mjs', instructions: 'Open an address that does not exist ({random} makes it unique).' },
+    criteria: []
+  })
+  const scenarioId = id || `SITE-${slug(host).toUpperCase()}`
+  const scenario = {
+    schema: 'qawalk.scenario.v1', id: scenarioId, title: title || `Public pages of ${host}`, kind: 'flow', version: 1,
+    locales: [...new Set(pages.map((p) => p.facts?.lang).filter(Boolean))].slice(0, 3).concat(pages.some((p) => p.facts?.lang) ? [] : ['en']),
+    viewports: { desktop: [1280, 800], mobile: [390, 844] },
+    environments: ['production'], readonly: true, lanes: ['Visitor'],
+    nodes,
+    edges: nodes.slice(1).map((n) => ({ from: nodes[0].id, to: n.id, label: 'visit', kind: 'alt' }))
+  }
+  const plan = [
+    `# Acceptance plan ${scenarioId}`, '',
+    `Source of truth for intent. Machine scenario: next to this file. Drafted by \`kaloko draft\` from ${pages.length} page(s) of ${origin} on ${new Date().toISOString().slice(0, 10)}; sharpen purposes and criteria before relying on it.`, '',
+    '## Goal and scope', '', `Public pages of ${host} read well, are findable, accessible and fast, as a visitor sees them. Read-only on production; nothing is submitted.`, '',
+    '## Steps and criteria', '',
+    'Every page step also runs the packs `seo` (AC1xx), `a11y` (AC3xx), `perf` (AC4xx) and `console` (AC501); the error page runs `errors` (AC6xx).', '',
+    ...nodes.flatMap((n) => [`### ${n.id} — ${n.title} (\`screen\`)`, '', `- Path: \`${n.path}\``, `- Purpose: ${n.purpose}`, ...n.criteria.map((c) => `- ${c.id}: ${c.text}.`), '']),
+    '## Environments and limits', '', `production (read-only, as a visitor): add \`environments.production: { base_url: ${origin}, readonly: true }\` to kaloko.config.yml if it is not there.`, '',
+    '## Change log', '', '| Date | Commit | Change |', '|---|---|---|', `| ${new Date().toISOString().slice(0, 10)} | — | Drafted from the pages by kaloko draft. |`, ''
+  ].join('\n')
+  return { scenario, plan, origin }
+}
+
+export const scenarioYaml = (scenario) => yaml.dump(scenario, { lineWidth: 160, noRefs: true, flowLevel: 4 })

package/src/lib/drift.mjs

@@ -0,0 +1,145 @@
+// Checks of an implementation against its design reference (#42, pack `design`): pixels, structure and
+// token use. They run outside the page, after the capture: the reference comes from the service (the
+// accepted design version), the token set from the project. Results land in capture.checks like the
+// in-page checks, so combine() turns them into verdicts the usual way.
+import { readFile, writeFile, mkdir } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+import { flattenTokens, tokenIndex, checkDeclaration } from './tokens.mjs'
+import { sha256 } from './util.mjs'
+
+export const DRIFT_ASSERTS = new Set(['design_pixels', 'design_structure', 'uses_tokens'])
+export const needsDrift = (node) => (node.criteria || []).some((c) => c.check.type === 'deterministic' && DRIFT_ASSERTS.has(c.check.assert))
+
+/** Structure difference between an implementation and the reference: a list of human-readable findings. */
+export function structureDiff (mine, ref) {
+  const out = []
+  if (!mine || !ref) return ['structure missing (capture again with the current CLI)']
+  const norm = (s) => String(s || '').toLowerCase().replace(/\s+/g, ' ').trim()
+  const outline = (h) => h.map((x) => `h${x.level}`).join(' ')
+  if (outline(mine.headings) !== outline(ref.headings)) out.push(`heading outline ${outline(mine.headings) || '—'} vs reference ${outline(ref.headings) || '—'}`)
+  const refH1 = ref.headings.find((h) => h.level === 1), myH1 = mine.headings.find((h) => h.level === 1)
+  if (refH1 && myH1 && norm(refH1.text) !== norm(myH1.text)) out.push(`h1 "${myH1.text}" vs reference "${refH1.text}"`)
+  const missingLm = ref.landmarks.filter((l) => !mine.landmarks.includes(l))
+  if (missingLm.length) out.push(`missing landmarks: ${missingLm.join(', ')}`)
+  const myActions = new Set(mine.actions.map(norm))
+  const missingActions = ref.actions.filter((a) => !myActions.has(norm(a)))
+  if (missingActions.length) out.push(`missing actions: ${missingActions.slice(0, 5).map((a) => `"${a}"`).join(', ')}`)
+  const myFields = new Set(mine.fields.map((f) => `${f.type}|${norm(f.label)}`))
+  const missingFields = ref.fields.filter((f) => !myFields.has(`${f.type}|${norm(f.label)}`))
+  if (missingFields.length) out.push(`missing fields: ${missingFields.slice(0, 5).map((f) => `${f.type} "${f.label}"`).join(', ')}`)
+  return out
+}
+
+/** Style values of a capture that are not in the token set: [{ property, value, suggest, example }]. */
+export function tokenOffenders (styles, tokens, mode = null, allowed = null) {
+  if (!styles) return null
+  const index = tokenIndex(flattenTokens(tokens, mode))
+  const out = []
+  for (const [prop, values] of Object.entries(styles)) {
+    const cssProp = prop.replace(/^(padding|margin)-(top|right|bottom|left)$/, '$1').replace('border-top-color', 'border-color')
+    for (const [value, info] of Object.entries(values)) {
+      // a raw value the accepted design itself uses is not drift of the implementation
+      if (allowed?.[prop]?.[value]) continue
+      for (const o of checkDeclaration(cssProp, value, index)) out.push({ property: prop, value: o.value, suggest: o.suggest, count: info.count, example: info.example })
+    }
+  }
+  return out.sort((a, b) => b.count - a.count)
+}
+
+/** Pixel difference ratio of two images in a browser page (the viewer's algorithm, so numbers match the canvas). */
+export async function pixelRatio (page, a, b, width) {
+  return page.evaluate(async ({ a, b, W }) => {
+    const load = (src) => new Promise((ok, no) => { const i = new Image(); i.onload = () => ok(i); i.onerror = no; i.src = src })
+    const [x, y] = await Promise.all([load(a), load(b)])
+    const ha = Math.round(x.naturalHeight * W / x.naturalWidth), hb = Math.round(y.naturalHeight * W / y.naturalWidth), H = Math.max(ha, hb)
+    const draw = (img, h) => { const c = document.createElement('canvas'); c.width = W; c.height = H; const g = c.getContext('2d', { willReadFrequently: true }); g.fillStyle = '#fff'; g.fillRect(0, 0, W, H); g.drawImage(img, 0, 0, W, h); return g.getImageData(0, 0, W, H).data }
+    const da = draw(x, ha), db = draw(y, hb)
+    let n = 0
+    for (let i = 0; i < da.length; i += 4) if (Math.abs(da[i] - db[i]) + Math.abs(da[i + 1] - db[i + 1]) + Math.abs(da[i + 2] - db[i + 2]) > 48) n++
+    return { ratio: n / (W * H), heights: [ha, hb] }
+  }, { a, b, W: width })
+}
+
+/**
+ * Fills capture.checks for the drift criteria of one capture. ctx: { client, org, scenarioId, tokens, mode,
+ * page (browser page for pixel diff), cacheDir, isDesign, references: Map }.
+ */
+export async function driftForCapture ({ node, entry, capture, runDir, ctx }) {
+  const results = {}
+  const crit = (node.criteria || []).filter((c) => c.check.type === 'deterministic' && DRIFT_ASSERTS.has(c.check.assert))
+  if (!crit.length) return results
+  let ref = null
+  const needRef = crit.some((c) => c.check.assert !== 'uses_tokens')
+  if (needRef && !ctx.isDesign) ref = await referenceStep(ctx, node.id, entry.locale)
+  for (const c of crit) {
+    const a = c.check.assert
+    if (a === 'uses_tokens') {
+      if (!ctx.tokens) { results[c.id] = { ok: null, evidence: 'No token set: push one with kaloko tokens push, or keep tokens.json in the design folder.' }; continue }
+      const refStyles = !ctx.isDesign ? (await referenceStep(ctx, node.id, entry.locale))?.captures?.[entry.viewport]?.design?.styles : null
+      const off = tokenOffenders(capture.design?.styles, ctx.tokens, ctx.mode, refStyles)
+      if (off == null) { results[c.id] = { ok: null, evidence: 'Capture has no style summary; capture this step again.' }; continue }
+      results[c.id] = off.length
+        ? { ok: false, evidence: `${off.length} value(s) outside the token set: ${off.slice(0, 5).map((o) => `${o.property} ${o.value}${o.suggest ? ` → ${o.suggest}` : ''}`).join('; ')}` }
+        : { ok: true, evidence: 'every color, font, size, spacing and radius comes from the token set' }
+      continue
+    }
+    if (ctx.isDesign) { results[c.id] = { ok: null, evidence: 'This is the design itself; the check applies to implementation runs.' }; continue }
+    if (!ref) { results[c.id] = { ok: null, evidence: ctx.referenceError || 'No design reference for this scenario yet: accept a version and set it as the design reference.' }; continue }
+    const rc = ref.captures?.[entry.viewport]
+    if (!rc) { results[c.id] = { ok: null, evidence: `The design reference has no ${entry.viewport} capture for ${entry.locale}.` }; continue }
+    if (a === 'design_structure') {
+      const diff = structureDiff(capture.design?.structure, rc.design?.structure)
+      results[c.id] = diff.length ? { ok: false, evidence: `vs design v${ctx.referenceVersion ?? '?'}: ${diff.join('; ')}` } : { ok: true, evidence: `same headings, landmarks, actions and fields as design v${ctx.referenceVersion ?? '?'}` }
+    }
+    if (a === 'design_pixels') {
+      if (!ctx.page || !rc.image) { results[c.id] = { ok: null, evidence: 'Pixel comparison needs the reference screenshot and a browser.' }; continue }
+      const refPath = await cachedImage(ctx, rc.image)
+      const mine = join(runDir, capture.files.image || capture.files.png)
+      const toData = async (p) => `data:image/${p.endsWith('.png') ? 'png' : 'webp'};base64,${(await readFile(p)).toString('base64')}`
+      const { ratio } = await pixelRatio(ctx.page, await toData(mine), await toData(refPath), Math.min(1000, capture.size?.viewport?.[0] || 1280))
+      const max = c.check.ratio ?? 0.03
+      results[c.id] = { ok: ratio <= max, evidence: `${(ratio * 100).toFixed(1)} % of pixels differ from design v${ctx.referenceVersion ?? '?'} (limit ${(max * 100).toFixed(1)} %)`, ratio }
+    }
+  }
+  return results
+}
+
+async function referenceStep (ctx, nodeId, locale) {
+  const key = `${nodeId}|${locale}`
+  if (ctx.references.has(key)) return ctx.references.get(key)
+  let step = null
+  try {
+    // an implementation on a git branch is checked against the reference of the design branch linked to it
+    const d = await ctx.client.request('GET', `/orgs/${ctx.org}/scenarios/${encodeURIComponent(ctx.scenarioId)}/steps/${encodeURIComponent(nodeId)}?ref=design&locale=${encodeURIComponent(locale)}${ctx.git ? `&git=${encodeURIComponent(ctx.git)}` : ''}`)
+    step = d.steps.find((s) => s.locale === locale) || null
+    if (d.run_id && ctx.referenceVersion == null) ctx.referenceVersion = d.run_id.match(/-v(\d+)-/)?.[1] ?? null
+  } catch (e) { ctx.referenceError = /404/.test(e.message) ? null : `Design reference unavailable: ${e.message.split('\n')[0]}` }
+  ctx.references.set(key, step)
+  return step
+}
+
+async function cachedImage (ctx, url) {
+  // the signed URL changes; the cache key is the stable part of the path
+  const stable = url.replace(/\/f\/\d+\.[^/]+\//, '/f/')
+  const file = join(ctx.cacheDir, sha256(stable).slice(0, 24) + '.webp')
+  try { await readFile(file); return file } catch {}
+  const res = url.includes('/api/v1/') ? await ctx.client.fetch(url.replace(/^.*\/api\/v1/, '')) : await fetch(url)
+  if (!res.ok) throw new Error(`reference screenshot: HTTP ${res.status}`)
+  await mkdir(ctx.cacheDir, { recursive: true })
+  await writeFile(file, Buffer.from(await res.arrayBuffer()))
+  return file
+}
+
+/** The token set the drift checks use: the project's latest on the service, else tokens.json of a design folder. */
+export async function loadTokens ({ client, config, root, designDir }) {
+  if (client && config.project) {
+    try { return (await client.request('GET', `/orgs/${config.org}/projects/${encodeURIComponent(config.project)}/tokens`)).tokens } catch {}
+  }
+  if (designDir) {
+    // a DTCG resolver (sets and a theme modifier) wins over a plain tokens.json
+    try { const { inlineResolver } = await import('./tokens.mjs'); return await inlineResolver(JSON.parse(await readFile(join(designDir, 'tokens.resolver.json'), 'utf8')), (ref) => readFile(join(designDir, ref), 'utf8')) } catch {}
+    try { return JSON.parse(await readFile(join(designDir, 'tokens.json'), 'utf8')) } catch {}
+  }
+  return null
+}
+export const driftCacheDir = (root, output) => resolve(root, output, '.cache', 'design-ref')