kaloko 0.4.8 → 0.4.10

package/src/lib/devspec.mjs

@@ -0,0 +1,821 @@
+// Dev mode and the step spec (#42): what a developer or an agent needs to build a design step exactly as it was
+// approved. One engine, `kalokoDev`, runs inside the page: the canvas frame helper (worker/src/frame.js) embeds it
+// for Dev mode, and the CLI capture evaluates it to store `<viewport>.spec.json` next to the screenshot. So the
+// canvas shows what the API, MCP and `kaloko spec` give an agent: elements with roles and names, computed styles
+// mapped to DTCG tokens (exact, or the nearest with a warning), interaction states, contrast and assets.
+//
+// kalokoDev must stay self-contained: it is serialised with Function.prototype.toString and must not reference
+// anything outside its own body (no imports, no module constants). The Node helpers below it (specText, specDrift,
+// driftText) are ordinary code.
+
+export const SPEC_SCHEMA = 'qawalk.spec.v1'
+
+/**
+ * The in-page engine. opts: { tokens: a DTCG set or resolver (object) or null, maxElements }.
+ * Returns { tokens, describe(el), pageSpec(), usage(), statesOf(el), forceState(el, state), elementsFor(q), loadRules() }.
+ */
+export function kalokoDev (opts) {
+  'use strict'
+  const o = opts || {}
+
+  // ---------------- colors and numbers ----------------
+  const canvas = document.createElement('canvas'); canvas.width = canvas.height = 1
+  const g2 = canvas.getContext('2d', { willReadFrequently: true })
+  const colorCache = new Map()
+  /** Any CSS color (hex, rgb, hsl, oklch, named, color()) as [r, g, b, a 0..1], or null. */
+  function rgba (v) {
+    if (v == null) return null
+    v = String(v).trim()
+    if (colorCache.has(v)) return colorCache.get(v)
+    let out = null
+    const m = v.match(/^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)(?:\s*[,/]\s*([\d.]+%?))?\s*\)$/)
+    if (m) out = [+m[1], +m[2], +m[3], m[4] == null ? 1 : m[4].endsWith('%') ? parseFloat(m[4]) / 100 : +m[4]]
+    else if (v && typeof CSS !== 'undefined' && CSS.supports('color', v) && g2) {
+      g2.clearRect(0, 0, 1, 1); g2.fillStyle = '#000'; g2.fillStyle = v; g2.fillRect(0, 0, 1, 1)
+      const d = g2.getImageData(0, 0, 1, 1).data
+      out = d[3] ? [d[0], d[1], d[2], Math.round(d[3] / 255 * 100) / 100] : [0, 0, 0, 0]
+    }
+    colorCache.set(v, out)
+    return out
+  }
+  const h2 = (n) => Math.max(0, Math.min(255, Math.round(n))).toString(16).padStart(2, '0')
+  const hexOf = (c) => c ? '#' + h2(c[0]) + h2(c[1]) + h2(c[2]) + (c[3] < 1 ? h2(c[3] * 255) : '') : null
+  const hex = (v) => hexOf(rgba(v))
+  const rootPx = () => parseFloat(getComputedStyle(document.documentElement).fontSize) || 16
+  /** A length as px ("16px", "1rem", 16), or null. em is relative to `em` (letter-spacing tokens). */
+  function px (v, em) {
+    if (typeof v === 'number') return v
+    if (v && typeof v === 'object' && 'value' in v) return px(v.value + (v.unit || 'px'), em)
+    const m = String(v == null ? '' : v).trim().match(/^(-?[\d.]+)(px|rem|em)?$/)
+    if (!m) return null
+    return m[2] === 'rem' ? +m[1] * rootPx() : m[2] === 'em' ? +m[1] * (em || rootPx()) : +m[1]
+  }
+  const r1 = (n) => Math.round(n * 100) / 100
+  const fmtPx = (n) => r1(n) + 'px'
+
+  // ---------------- tokens (W3C DTCG; the same reading as src/lib/tokens.mjs) ----------------
+  const isTok = (v) => v && typeof v === 'object' && !Array.isArray(v) && '$value' in v
+  const isGrp = (v) => v && typeof v === 'object' && !Array.isArray(v) && !('$value' in v)
+  const clone = (v) => v == null ? v : JSON.parse(JSON.stringify(v))
+  function merge (a, b) { const out = clone(a) || {}; for (const k of Object.keys(b || {})) { const v = b[k]; out[k] = isGrp(v) && isGrp(out[k]) ? merge(out[k], v) : clone(v) } return out }
+  function pointer (doc, ref) {
+    if (typeof ref !== 'string' || ref[0] !== '#') return undefined
+    let cur = doc
+    for (const raw of ref.slice(1).split('/').slice(1)) { const k = raw.replace(/~1/g, '/').replace(/~0/g, '~'); if (cur == null || typeof cur !== 'object' || !(k in cur)) return undefined; cur = cur[k] }
+    return cur
+  }
+  function byPath (doc, path) { let cur = doc; for (const k of path.split('.')) { if (cur == null || typeof cur !== 'object' || !(k in cur)) return undefined; cur = cur[k] } return cur }
+  function applyExtends (doc, node, depth) {
+    if (!isGrp(node) || depth > 20) return node
+    let out = {}
+    for (const k of Object.keys(node)) out[k] = isGrp(node[k]) ? applyExtends(doc, node[k], depth + 1) : node[k]
+    const ext = node.$extends
+    if (typeof ext === 'string') {
+      const target = ext[0] === '#' ? pointer(doc, ext) : byPath(doc, ext.replace(/^\{|\}$/g, ''))
+      if (isGrp(target)) { const local = Object.assign({}, out); delete local.$extends; out = merge(applyExtends(doc, target, depth + 1), local) }
+    }
+    return out
+  }
+  function resolveResolver (doc, want) {
+    const pick = (mod) => { const ctx = mod.contexts || {}; return ctx[(want && ctx[want] ? want : null) || mod.default || Object.keys(ctx)[0]] || [] }
+    const sources = (list) => (list || []).map((s) => s && s.$ref ? pointer(doc, s.$ref) : s).filter(isGrp)
+    let out = {}
+    for (const item of doc.resolutionOrder || []) {
+      const ref = (item && item.$ref) || ''
+      const target = ref ? pointer(doc, ref) : item
+      if (!target) continue
+      if (ref.startsWith('#/modifiers/') || (!ref && target.contexts)) { for (const s of sources(pick(target))) out = merge(out, s) } else if (Array.isArray(target.sources)) { for (const s of sources(target.sources)) out = merge(out, s) } else if (isGrp(target)) out = merge(out, target)
+    }
+    return out
+  }
+  /** The set per mode: [{ mode, doc }] (mode null when the set has none). */
+  function modeDocs (set) {
+    if (Array.isArray(set.resolutionOrder)) {
+      const ctxs = [...new Set(Object.values(set.modifiers || {}).flatMap((m) => Object.keys((m && m.contexts) || {})))]
+      return ctxs.length ? ctxs.map((c) => ({ mode: c, doc: resolveResolver(set, c) })) : [{ mode: null, doc: resolveResolver(set, null) }]
+    }
+    const declared = set.$extensions && set.$extensions['qawalk.modes']
+    const modes = Array.isArray(declared) ? declared.filter((m) => isGrp(set[m])) : ['light', 'dark', 'high-contrast'].filter((m) => isGrp(set[m]))
+    const base = {}; for (const k of Object.keys(set)) if (!modes.includes(k)) base[k] = set[k]
+    return modes.length ? modes.map((m) => ({ mode: m, doc: merge(base, set[m]) })) : [{ mode: null, doc: base }]
+  }
+  const WEIGHTS = { thin: 100, hairline: 100, 'extra-light': 200, 'ultra-light': 200, light: 300, normal: 400, regular: 400, book: 400, medium: 500, 'semi-bold': 600, 'demi-bold': 600, bold: 700, 'extra-bold': 800, 'ultra-bold': 800, black: 900, heavy: 900 }
+  function colorObject (c) {
+    const a = c.alpha == null ? 1 : +c.alpha
+    const [x, y, z] = (c.components || []).map((v) => v === 'none' ? 0 : +v)
+    const sp = String(c.colorSpace || '').toLowerCase()
+    const ok = [x, y, z].every(Number.isFinite)
+    const out = (r, g, b) => hexOf([r * 255, g * 255, b * 255, a])
+    if (sp === 'srgb' && ok) return out(x, y, z)
+    if (sp === 'srgb-linear' && ok) { const f = (v) => v <= 0.0031308 ? 12.92 * v : 1.055 * Math.pow(v, 1 / 2.4) - 0.055; return out(f(x), f(y), f(z)) }
+    if (sp === 'hsl' && ok) { const s = y / 100, l = z / 100, k = (n) => (n + x / 30) % 12, f = (n) => l - s * Math.min(l, 1 - l) * Math.max(-1, Math.min(k(n) - 3, 9 - k(n), 1)); return out(f(0), f(8), f(4)) }
+    return c.hex ? hex(c.hex) : null
+  }
+  const unit = (v) => v && typeof v === 'object' && 'value' in v ? v.value + (v.unit || '') : v
+  function css (type, v) {
+    if (v == null) return v
+    if (type === 'color' || (typeof v === 'object' && 'colorSpace' in v)) return typeof v === 'string' ? v : colorObject(v)
+    if (type === 'dimension' || type === 'duration' || (typeof v === 'object' && 'unit' in v && 'value' in v)) return unit(v)
+    if (type === 'fontFamily') return Array.isArray(v) ? v.join(', ') : v
+    if (type === 'fontWeight') return typeof v === 'string' ? (WEIGHTS[v.toLowerCase()] || v) : v
+    if (type === 'typography' && typeof v === 'object') return { fontFamily: css('fontFamily', v.fontFamily), fontSize: css('dimension', v.fontSize), fontWeight: css('fontWeight', v.fontWeight), lineHeight: unit(v.lineHeight), letterSpacing: css('dimension', v.letterSpacing) }
+    if (type === 'border' && typeof v === 'object') return { color: css('color', v.color), width: css('dimension', v.width) }
+    if (type === 'shadow') return [].concat(v).map((s) => ({ color: css('color', s.color), offsetX: css('dimension', s.offsetX), offsetY: css('dimension', s.offsetY), blur: css('dimension', s.blur), spread: css('dimension', s.spread), inset: !!s.inset }))
+    return v
+  }
+  function flatOne (doc) {
+    doc = applyExtends(doc, doc, 0)
+    const raw = new Map()
+    const walk = (obj, path, inherited, dep) => {
+      for (const k of Object.keys(obj || {})) {
+        if (k[0] === '$' && k !== '$root') continue
+        const v = obj[k]
+        const d = v && typeof v === 'object' && '$deprecated' in v ? v.$deprecated : dep
+        if (isTok(v)) raw.set((k === '$root' ? path : path.concat(k)).join('.'), { type: v.$type || inherited || null, raw: v.$value, deprecated: !!d })
+        else if (isGrp(v)) walk(v, path.concat(k), v.$type || inherited, d)
+      }
+    }
+    walk(doc, [], null, false)
+    const resolve = (value, depth) => {
+      if (depth > 10) return value
+      if (typeof value === 'string') { const m = value.match(/^\{([^}]+)\}$/); if (!m) return value; const t = raw.get(m[1].replace(/\.\$root$/, '')); return t ? resolve(t.raw, depth + 1) : value }
+      if (value && typeof value === 'object' && typeof value.$ref === 'string') { const at = pointer(doc, value.$ref); return resolve(isTok(at) ? at.$value : at, depth + 1) }
+      if (Array.isArray(value)) return value.map((x) => resolve(x, depth + 1))
+      if (value && typeof value === 'object') { const out = {}; for (const k of Object.keys(value)) out[k] = resolve(value[k], depth + 1); return out }
+      return value
+    }
+    const out = new Map()
+    for (const [name, t] of raw) out.set(name, { type: t.type, value: css(t.type, resolve(t.raw, 0)), deprecated: t.deprecated })
+    return out
+  }
+  const shadowKey = (parts) => parts.map((s) => (s.inset ? 'inset ' : '') + [s.offsetX, s.offsetY, s.blur, s.spread].map((x) => r1(px(x) || 0)).join(' ') + ' ' + (hex(s.color) || '')).join(', ')
+  /** Primitive entries of a token value, composite types split into their parts (typography.fontSize, …). */
+  function primitives (name, type, value) {
+    if (Array.isArray(value) && type === 'shadow') return [{ name, type, css: value.map((s) => [s.inset ? 'inset' : '', s.offsetX, s.offsetY, s.blur, s.spread, s.color].filter(Boolean).join(' ')).join(', '), kind: 'shadow', key: shadowKey(value) }]
+    if (value && typeof value === 'object') {
+      const out = []
+      for (const k of Object.keys(value)) {
+        if (value[k] == null) continue
+        const t = k === 'color' ? 'color' : k === 'fontFamily' ? 'fontFamily' : k === 'fontWeight' ? 'fontWeight' : k === 'lineHeight' ? 'lineHeight' : k === 'letterSpacing' ? 'letterSpacing' : k === 'fontSize' ? 'fontSize' : k === 'width' ? 'borderWidth' : 'dimension'
+        out.push(...primitives(name + '.' + k, t, value[k]))
+      }
+      return out
+    }
+    const s = value == null ? '' : String(value)
+    if (type === 'fontFamily' || /font.?family/i.test(name)) return [{ name, type, css: s, kind: 'font', key: s.split(',')[0].trim().replace(/^["']|["']$/g, '').toLowerCase() }]
+    if (type === 'fontWeight' || (/weight/i.test(name) && /^\d+$/.test(s))) return [{ name, type: 'fontWeight', css: s, kind: 'weight', key: +s }]
+    if (/^-?[\d.]+$/.test(s) && (type === 'number' || type === 'lineHeight' || /line|leading/i.test(name))) return [{ name, type: type || 'number', css: s, kind: 'number', key: +s }]
+    if (type === 'color' || (!type && !/^-?[\d.]/.test(s) && rgba(s))) { const c = hex(s); return c ? [{ name, type: 'color', css: s, kind: 'color', key: c }] : [] }
+    if (/em$/.test(s) && !/rem$/.test(s) && (type === 'letterSpacing' || /letter|tracking/i.test(name))) return [{ name, type: 'letterSpacing', css: s, kind: 'em', key: parseFloat(s) }]
+    const d = px(s)
+    if (d != null && type !== 'duration') return [{ name, type: type || 'dimension', css: s, kind: 'dim', key: d }]
+    return []
+  }
+  /** The token set as entries [{ name, type, css, mode, kind, key, deprecated }] and its modes. */
+  function readTokens (set) {
+    if (!set || typeof set !== 'object') return { entries: [], modes: [] }
+    const docs = modeDocs(set)
+    const per = docs.map((d) => ({ mode: d.mode, flat: flatOne(d.doc) }))
+    const names = [...new Set(per.flatMap((p) => [...p.flat.keys()]))]
+    const entries = []
+    for (const name of names) {
+      const vals = per.filter((p) => p.flat.has(name)).map((p) => ({ mode: p.mode, t: p.flat.get(name) }))
+      const same = vals.every((v) => JSON.stringify(v.t.value) === JSON.stringify(vals[0].t.value))
+      for (const v of same ? [{ mode: null, t: vals[0].t }] : vals) for (const e of primitives(name, v.t.type, v.t.value)) entries.push(Object.assign(e, { mode: v.mode, deprecated: v.t.deprecated }))
+    }
+    return { entries, modes: docs.map((d) => d.mode).filter(Boolean) }
+  }
+  const TOK = readTokens(o.tokens)
+  const live = TOK.entries.filter((e) => !e.deprecated)
+  // a token's custom property: color.brand.primary → --color-brand-primary
+  const varName = (name) => '--' + name.replace(/\./g, '-').replace(/[^\w-]/g, '-')
+  const byVar = new Map()
+  for (const e of TOK.entries) byVar.set(varName(e.name).toLowerCase(), e.name)
+
+  // which token names suit a CSS property (an 8px radius is not an 8px spacing)
+  function kindOf (prop) {
+    if (/color|^fill$|^stroke$/.test(prop)) return { kind: 'color' }
+    if (prop === 'font-family') return { kind: 'font' }
+    if (prop === 'font-weight') return { kind: 'weight' }
+    if (prop === 'box-shadow') return { kind: 'shadow' }
+    if (/radius/.test(prop)) return { kind: 'dim', fit: (e) => /radius|round|corner/i.test(e.name) || e.type === 'borderRadius' }
+    if (prop === 'font-size') return { kind: 'dim', fit: (e) => e.type === 'fontSize' || (/font|text|type/i.test(e.name) && !/line|leading|letter|weight/i.test(e.name)) }
+    if (prop === 'line-height') return { kind: 'dim', fit: (e) => e.type === 'lineHeight' || /line|leading/i.test(e.name) }
+    if (prop === 'letter-spacing') return { kind: 'dim', fit: (e) => e.type === 'letterSpacing' || /letter|tracking/i.test(e.name) }
+    if (/^(padding|margin)|gap$/.test(prop)) return { kind: 'dim', fit: (e) => e.type === 'spacing' || /space|spacing|gap|gutter|inset/i.test(e.name) || (/size/i.test(e.name) && !/font|text|type|line|radius/i.test(e.name)) }
+    if (/width$/.test(prop)) return { kind: 'dim', fit: (e) => e.type === 'borderWidth' || /border|stroke/i.test(e.name) }
+    return null
+  }
+  const pref = (list) => list.find((e) => !e.mode) || list[0]
+  const tokOut = (m, e, extra) => Object.assign({ m, name: e.name, value: e.css }, e.mode ? { mode: e.mode } : {}, extra || {})
+  /**
+   * The token of one computed value: { m: 'exact', name, value, mode? } or { m: 'nearest', name, value } for a
+   * value outside the set, or { m: 'none' }; null when the value needs no token (0, none, transparent).
+   * ctx: { fontSize } for line-height and em letter-spacing.
+   */
+  function match (prop, value, ctx) {
+    const k = kindOf(prop)
+    if (!k || value == null) return null
+    const v = String(value).trim()
+    if (!v || /^(none|normal|auto|0px|0|transparent)$/.test(v)) return null
+    if (!live.length) return null // no token set: nothing to say about tokens
+    if (k.kind === 'color') {
+      const c = rgba(v); if (!c || c[3] === 0) return null
+      const key = hexOf(c)
+      let best = null, dist = Infinity
+      for (const e of live) {
+        if (e.kind !== 'color') continue
+        if (e.key === key) return tokOut('exact', pref(live.filter((x) => x.kind === 'color' && x.key === key)))
+        const t = rgba(e.key); const d = Math.sqrt(Math.pow(t[0] - c[0], 2) + Math.pow(t[1] - c[1], 2) + Math.pow(t[2] - c[2], 2) + Math.pow((t[3] - c[3]) * 255, 2))
+        if (d < dist) { dist = d; best = e }
+      }
+      if (best && dist <= 1.8) return tokOut('exact', best) // rounding of srgb components
+      return best ? tokOut('nearest', best) : null
+    }
+    if (k.kind === 'font') {
+      const f = v.split(',')[0].trim().replace(/^["']|["']$/g, '').toLowerCase()
+      const fonts = live.filter((e) => e.kind === 'font')
+      const hit = fonts.filter((e) => e.key === f)
+      return hit.length ? tokOut('exact', pref(hit)) : fonts.length ? tokOut('nearest', fonts[0]) : null
+    }
+    if (k.kind === 'weight') {
+      const w = +v; const ws = live.filter((e) => e.kind === 'weight' || (e.kind === 'number' && /weight/i.test(e.name)))
+      const hit = ws.filter((e) => e.key === w)
+      if (hit.length) return tokOut('exact', pref(hit))
+      let best = null; for (const e of ws) if (!best || Math.abs(e.key - w) < Math.abs(best.key - w)) best = e
+      return best ? tokOut('nearest', best) : null
+    }
+    if (k.kind === 'shadow') {
+      const key = shadowOf(v)
+      const sh = live.filter((e) => e.kind === 'shadow')
+      const hit = sh.filter((e) => e.key === key)
+      return hit.length ? tokOut('exact', pref(hit)) : sh.length ? tokOut('nearest', sh[0]) : null
+    }
+    // dimensions; line-height also matches unitless tokens (1.5 × font size), letter-spacing em tokens
+    const n = px(v); if (n == null || n === 0) return null
+    const fs = (ctx && ctx.fontSize) || rootPx()
+    const valueOf = (e) => e.kind === 'dim' ? e.key : e.kind === 'number' && prop === 'line-height' ? e.key * fs : e.kind === 'em' && prop === 'letter-spacing' ? e.key * fs : null
+    let pool = live.filter((e) => valueOf(e) != null)
+    // a set without tokens of this kind (no line heights, no border widths) has nothing to say about the value
+    const fitting = k.fit ? pool.filter(k.fit) : pool
+    if (!fitting.length) return null
+    pool = fitting
+    const hit = pool.filter((e) => Math.abs(valueOf(e) - n) < 0.05)
+    if (hit.length) return tokOut('exact', pref(hit))
+    let best = null; for (const e of pool) if (!best || Math.abs(valueOf(e) - n) < Math.abs(valueOf(best) - n)) best = e
+    return best ? tokOut('nearest', best) : null
+  }
+  function shadowOf (v) {
+    return splitTop(v, ',').map((layer) => {
+      const inset = /\binset\b/.test(layer)
+      let color = ''
+      const rest = layer.replace(/\binset\b/, '').replace(/(rgba?|hsla?|oklch|oklab|lab|lch|color)\([^)]*\)|#[0-9a-f]{3,8}\b/i, (m) => { color = m; return ' ' })
+      const nums = rest.trim().split(/\s+/).filter(Boolean)
+      if (!color) { const c = nums.find((x) => px(x) == null); if (c) { color = c; nums.splice(nums.indexOf(c), 1) } }
+      const l = nums.map((x) => r1(px(x) || 0)); while (l.length < 4) l.push(0)
+      return (inset ? 'inset ' : '') + l.slice(0, 4).join(' ') + ' ' + (hex(color) || '')
+    }).join(', ')
+  }
+  function splitTop (s, sep) {
+    const out = []; let depth = 0, cur = ''
+    for (const ch of String(s)) { if (ch === '(' || ch === '[') depth++; else if (ch === ')' || ch === ']') depth--; if (ch === sep && depth === 0) { out.push(cur.trim()); cur = '' } else cur += ch }
+    if (cur.trim()) out.push(cur.trim())
+    return out
+  }
+
+  // ---------------- stylesheets: authored values and interaction states ----------------
+  let rules = null
+  /** Style rules of the page in order, @media rules that apply included; linked sheets the CSSOM hides are fetched. */
+  async function loadRules () {
+    if (rules) return rules
+    const out = []
+    const walk = (list, media) => {
+      for (const r of list) {
+        if (r.selectorText != null && r.style) out.push({ sel: r.selectorText, style: r.style, media, i: out.length })
+        else if (r.media && r.cssRules) { if (matchMedia(r.media.mediaText).matches) walk(r.cssRules, r.media.mediaText) } else if (r.cssRules && !r.selectorText) walk(r.cssRules, media)
+      }
+    }
+    for (const sheet of [...document.styleSheets]) {
+      const own = sheet.ownerNode
+      if (own && own.hasAttribute && (own.hasAttribute('data-kaloko-states') || own.hasAttribute('data-qawalk-overlay'))) continue
+      let list = null
+      try { list = sheet.cssRules } catch (e) {}
+      if (!list && sheet.href) {
+        try { const text = await (await fetch(sheet.href)).text(); const s = new CSSStyleSheet(); s.replaceSync(text.replace(/@import[^;]+;/g, '')); list = s.cssRules } catch (e) {}
+      }
+      if (list) walk(list, null)
+    }
+    rules = out
+    return out
+  }
+  function specificity (sel) {
+    const s = sel.replace(/:(not|is|has)\(/g, '(').replace(/:where\([^)]*\)/g, '').replace(/::[\w-]+/g, '')
+    const a = (s.match(/#[\w-]+/g) || []).length
+    const b = (s.match(/\.[\w-]+|\[[^\]]+\]|:[\w-]+/g) || []).length
+    const c = (s.match(/(^|[\s>+~(])[a-zA-Z][\w-]*/g) || []).length
+    return a * 10000 + b * 100 + c
+  }
+  const safeMatches = (el, sel) => { try { return el.matches(sel) } catch (e) { return false } }
+  const STATE_RE = { hover: /:hover(?![\w-])/, focus: /:focus(-visible|-within)?(?![\w-])/, active: /:active(?![\w-])/, disabled: /:disabled(?![\w-])|\[disabled\]|\[aria-disabled=["']?true["']?\]/ }
+  const ANY_STATE = /:(hover|focus-visible|focus-within|focus|active|disabled)(?![\w-])|\[disabled\]|\[aria-disabled=["']?true["']?\]/g
+  const HAS_STATE = new RegExp(ANY_STATE.source)
+  /** A selector with the state pseudo-classes outside parentheses removed (`button:not(:disabled):hover` → `button:not(:disabled)`). */
+  function stripStates (sel, replace) {
+    let out = '', depth = 0, i = 0
+    while (i < sel.length) {
+      const ch = sel[i]
+      if (depth === 0 && (ch === ':' || ch === '[')) {
+        ANY_STATE.lastIndex = i
+        const m = ANY_STATE.exec(sel)
+        if (m && m.index === i) { out += replace ? replace(m[0]) : ''; i += m[0].length; continue }
+      }
+      if (ch === '(') depth++; else if (ch === ')') depth--
+      out += ch; i++
+    }
+    ANY_STATE.lastIndex = 0
+    out = out.trim()
+    return !out || /[>+~]$/.test(out) ? out + '*' : out.replace(/\s+$/, '')
+  }
+  const ownState = (part) => { let f = false; stripStates(part, (m) => { f = true; return m }); return f }
+  const stateOf = (pseudo) => /hover/.test(pseudo) ? 'hover' : /focus/.test(pseudo) ? 'focus' : /active/.test(pseudo) ? 'active' : 'disabled'
+  /** Matching rules of an element (the base state), most specific last. */
+  function matched (el) {
+    const out = []
+    for (const r of (rules || []).concat(forced ? forced.rules : [])) {
+      let best = -1
+      for (const part of splitTop(r.sel, ',')) { if (HAS_STATE.test(part) && ownState(part)) continue; if (safeMatches(el, part)) best = Math.max(best, specificity(part)) }
+      if (best >= 0) out.push({ r, spec: best })
+    }
+    return out.sort((a, b) => a.spec - b.spec || a.r.i - b.r.i)
+  }
+  const SHORT = { 'padding-top': ['padding', 0], 'padding-right': ['padding', 1], 'padding-bottom': ['padding', 2], 'padding-left': ['padding', 3], 'margin-top': ['margin', 0], 'margin-right': ['margin', 1], 'margin-bottom': ['margin', 2], 'margin-left': ['margin', 3], 'border-top-left-radius': ['border-radius', 0], 'border-top-right-radius': ['border-radius', 1], 'border-bottom-right-radius': ['border-radius', 2], 'border-bottom-left-radius': ['border-radius', 3], 'border-top-color': ['border-color', 0], 'border-top-width': ['border-width', 0], 'background-color': ['background', -1], 'row-gap': ['gap', 0], 'column-gap': ['gap', 1] }
+  const INHERITED = /^(color|font-|line-height|letter-spacing)/
+  function sidePart (value, idx) {
+    const parts = splitTop(value, ' ')
+    if (idx < 0) return (value.match(/var\(--[\w-]+[^)]*\)/) || [null])[0] || value
+    if (idx <= 1 && parts.length <= 2 && parts.length > 0) return parts[idx % parts.length] || parts[0]
+    const four = parts.length === 1 ? [parts[0], parts[0], parts[0], parts[0]] : parts.length === 2 ? [parts[0], parts[1], parts[0], parts[1]] : parts.length === 3 ? [parts[0], parts[1], parts[2], parts[1]] : parts
+    return four[idx]
+  }
+  /** What the author wrote for a property of an element (inline style, then the cascade, then inherited): a string, or null. */
+  function authored (el, prop) {
+    const sh = SHORT[prop]
+    for (let e = el, hops = 0; e && e.nodeType === 1 && hops < 30; e = e.parentElement, hops++) {
+      const decl = (style) => { let v = style.getPropertyValue(prop); if (v) return v.trim(); if (sh) { v = style.getPropertyValue(sh[0]); if (v) return sidePart(v.trim(), sh[1]) } return null }
+      const inline = e.style && decl(e.style)
+      if (inline) return { v: inline, own: e === el }
+      const list = matched(e)
+      for (let i = list.length - 1; i >= 0; i--) { const v = decl(list[i].r.style); if (v) return { v, own: e === el } }
+      if (!INHERITED.test(prop)) return null
+    }
+    return null
+  }
+  /** The token an authored var() names: directly (--color-brand-primary) or through one custom property in between. */
+  function tokenOfVar (value) {
+    const m = String(value || '').match(/^var\(\s*(--[\w-]+)/)
+    if (!m) return null
+    const direct = byVar.get(m[1].toLowerCase())
+    if (direct) return { name: direct, via: m[1] }
+    for (const r of rules || []) { const v = r.style.getPropertyValue(m[1]); const n = v && v.trim().match(/^var\(\s*(--[\w-]+)/); if (n && byVar.get(n[1].toLowerCase())) return { name: byVar.get(n[1].toLowerCase()), via: m[1] } }
+    return { name: null, via: m[1] }
+  }
+
+  /** Interaction states the page's CSS defines for an element (rules with :hover, :focus, :active, :disabled). */
+  function statesOf (el) {
+    const out = new Set()
+    for (const r of rules || []) {
+      if (!HAS_STATE.test(r.sel)) continue
+      for (const part of splitTop(r.sel, ',')) {
+        // only states of the element itself count: :not(:disabled) inside parentheses is a condition, not a state
+        const found = []
+        const base = stripStates(part, (m) => { found.push(stateOf(m)); return '' })
+        if (found.length && safeMatches(el, base)) found.forEach((s) => out.add(s))
+      }
+    }
+    return ['hover', 'focus', 'active', 'disabled'].filter((s) => out.has(s))
+  }
+  let forced = null
+  /** Renders an element in a state: the state's rules rewritten to attribute selectors on the element (and its
+      ancestors for hover), transitions off; `default` restores the page. */
+  function forceState (el, state) {
+    if (forced) {
+      forced.style.remove()
+      for (const [node, attrs] of forced.saved) for (const [k, v] of attrs) { if (v == null) node.removeAttribute(k); else node.setAttribute(k, v) }
+      forced = null
+    }
+    if (!el || !state || state === 'default') return
+    const attr = 'data-kaloko-state'
+    const text = [], extra = []
+    for (const r of rules || []) {
+      if (!STATE_RE[state].test(r.sel)) continue
+      const parts = splitTop(r.sel, ',').filter((p) => STATE_RE[state].test(p)).map((p) => stripStates(p, (m) => stateOf(m) === state ? '[' + attr + '~="' + state + '"]' : ''))
+      if (!parts.length) continue
+      const body = r.style.cssText
+      text.push((r.media ? '@media ' + r.media + '{' : '') + parts.join(',') + '{' + body + '}' + (r.media ? '}' : ''))
+      extra.push({ sel: parts.join(','), style: r.style, media: r.media, i: 1e6 + r.i })
+    }
+    const style = document.createElement('style'); style.setAttribute('data-kaloko-states', ''); style.textContent = text.join('\n')
+    const saved = new Map()
+    const set = (node, k, v) => { if (!saved.has(node)) saved.set(node, new Map()); const m = saved.get(node); if (!m.has(k)) m.set(k, node.getAttribute(k)); node.setAttribute(k, v) }
+    const targets = state === 'hover' ? (function () { const a = []; for (let e = el; e && e.nodeType === 1; e = e.parentElement) a.push(e); return a })() : [el]
+    for (const t of targets) set(t, attr, ((t.getAttribute(attr) || '') + ' ' + state).trim())
+    if (state === 'disabled') { if ('disabled' in el) set(el, 'disabled', ''); set(el, 'aria-disabled', 'true') }
+    set(el, 'style', (el.getAttribute('style') || '') + ';transition:none!important;animation:none!important')
+    document.head.appendChild(style)
+    forced = { style, saved, rules: extra }
+  }
+
+  // ---------------- elements ----------------
+  const visible = (el) => { const r = el.getBoundingClientRect(); if (r.width < 1 || r.height < 1) return false; const cs = getComputedStyle(el); return cs.visibility !== 'hidden' && cs.display !== 'none' && +cs.opacity > 0 }
+  const ident = (s) => /^[A-Za-z_][\w-]*$/.test(s)
+  function selectorOf (el) {
+    if (el.id && ident(el.id)) return '#' + el.id
+    const parts = []
+    for (let e = el; e && e.nodeType === 1 && e !== document.body && e !== document.documentElement && parts.length < 5; e = e.parentElement) {
+      if (e.id && ident(e.id)) { parts.unshift('#' + e.id); break }
+      const q = e.getAttribute('data-testid') || e.getAttribute('data-kaloko') || e.getAttribute('data-qawalk')
+      let s = e.tagName.toLowerCase()
+      if (q) { const a = e.hasAttribute('data-testid') ? 'data-testid' : e.hasAttribute('data-kaloko') ? 'data-kaloko' : 'data-qawalk'; parts.unshift(s + '[' + a + '="' + q.replace(/["\\]/g, '') + '"]'); break }
+      const cls = [...e.classList].filter(ident).slice(0, 2)
+      if (cls.length) s += '.' + cls.join('.')
+      const sib = e.parentElement ? [...e.parentElement.children].filter((x) => x.tagName === e.tagName) : []
+      if (sib.length > 1 && !(cls.length && e.parentElement.querySelectorAll(':scope > ' + s).length === 1)) s += ':nth-of-type(' + (sib.indexOf(e) + 1) + ')'
+      parts.unshift(s)
+    }
+    return parts.join(' > ')
+  }
+  const ROLES = { button: 'button', nav: 'navigation', main: 'main', header: 'banner', footer: 'contentinfo', aside: 'complementary', form: 'form', ul: 'list', ol: 'list', li: 'listitem', table: 'table', dialog: 'dialog', select: 'combobox', textarea: 'textbox', img: 'img', h1: 'heading', h2: 'heading', h3: 'heading', h4: 'heading', h5: 'heading', h6: 'heading', label: 'label', p: 'paragraph', svg: 'img' }
+  function roleOf (el) {
+    const r = el.getAttribute('role'); if (r) return r.split(/\s+/)[0]
+    const t = el.tagName.toLowerCase()
+    if (t === 'a') return el.hasAttribute('href') ? 'link' : null
+    if (t === 'input') { const ty = (el.getAttribute('type') || 'text').toLowerCase(); return /^(button|submit|reset|image)$/.test(ty) ? 'button' : ty === 'checkbox' ? 'checkbox' : ty === 'radio' ? 'radio' : ty === 'range' ? 'slider' : ty === 'hidden' ? null : 'textbox' }
+    if (t === 'section' && (el.getAttribute('aria-label') || el.getAttribute('aria-labelledby'))) return 'region'
+    return ROLES[t] || null
+  }
+  const clean = (s) => String(s || '').replace(/\s+/g, ' ').trim()
+  function nameOf (el) {
+    const lab = el.getAttribute('aria-label'); if (lab) return clean(lab).slice(0, 80)
+    const by = el.getAttribute('aria-labelledby'); if (by) { const t = by.split(/\s+/).map((id) => document.getElementById(id)).filter(Boolean).map((x) => x.innerText).join(' '); if (clean(t)) return clean(t).slice(0, 80) }
+    const t = el.tagName.toLowerCase()
+    if (t === 'img') return clean(el.getAttribute('alt')).slice(0, 80)
+    if (/^(input|select|textarea)$/.test(t)) { const l = el.labels && el.labels[0]; return clean((l && l.innerText) || el.getAttribute('placeholder') || (/^(button|submit|reset)$/.test(el.type) ? el.value : '') || el.name).slice(0, 80) }
+    if (t === 'svg') { const ti = el.querySelector('title'); return ti ? clean(ti.textContent).slice(0, 80) : '' }
+    return clean(el.innerText).slice(0, 80)
+  }
+  const ownText = (el) => [...el.childNodes].some((x) => x.nodeType === 3 && x.textContent.trim())
+  const quad = (a) => a[0] === a[1] && a[1] === a[2] && a[2] === a[3] ? [a[0]] : a[0] === a[2] && a[1] === a[3] ? [a[0], a[1]] : a[1] === a[3] ? [a[0], a[1], a[2]] : a
+  /** Luminance contrast of the element's text against what is behind it (background images are ignored). */
+  function contrastOf (el, cs) {
+    const fg = rgba(cs.color); if (!fg) return null
+    const layers = []; let approx = false
+    for (let e = el; e && e.nodeType === 1; e = e.parentElement) { const s = getComputedStyle(e); if (s.backgroundImage && s.backgroundImage !== 'none') approx = true; const c = rgba(s.backgroundColor); if (c && c[3] > 0) { layers.push(c); if (c[3] >= 1) break } }
+    let bg = [255, 255, 255]
+    for (const c of layers.reverse()) bg = [0, 1, 2].map((i) => c[i] * c[3] + bg[i] * (1 - c[3]))
+    const text = [0, 1, 2].map((i) => fg[i] * fg[3] + bg[i] * (1 - fg[3]))
+    const lum = (c) => { const f = (v) => { v /= 255; return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4) }; return 0.2126 * f(c[0]) + 0.7152 * f(c[1]) + 0.0722 * f(c[2]) }
+    const [a, b] = [lum(text), lum(bg)].sort((x, y) => y - x)
+    const ratio = Math.round((a + 0.05) / (b + 0.05) * 100) / 100
+    const size = parseFloat(cs.fontSize), weight = +cs.fontWeight || 400
+    const large = size >= 24 || (size >= 18.66 && weight >= 700)
+    return Object.assign({ ratio, fg: hexOf(text), bg: hexOf(bg), large, aa: ratio >= (large ? 3 : 4.5), aaa: ratio >= (large ? 4.5 : 7) }, approx ? { approx: true } : {})
+  }
+
+  /**
+   * One row per property worth knowing: { g: group, prop, value, tok, parts?, auth? }. `tok` as match() returns;
+   * when the author wrote var(--token) the row says so (m 'exact', via); a raw value equal to a token is `hard`.
+   */
+  function rowsOf (el, all) {
+    const cs = getComputedStyle(el)
+    const fs = parseFloat(cs.fontSize)
+    const rows = []
+    const text = ownText(el) || /^(input|textarea|select|button)$/i.test(el.tagName)
+    const tokFor = (prop, value) => {
+      let t = match(prop, value, { fontSize: fs })
+      if (!t) return null
+      const au = rules ? authored(el, prop) : null
+      const a = au && au.v
+      if (a && /^var\(/.test(a)) {
+        const v = tokenOfVar(a)
+        if (v && v.name) { const e = TOK.entries.find((x) => x.name === v.name); t = Object.assign({ m: 'exact', name: v.name, value: e ? e.css : value }, e && e.mode ? { mode: e.mode } : {}, { via: v.via }) } else if (v) t = Object.assign({}, t, { via: v.via })
+      } else if (a && au.own && t.m === 'exact') t = Object.assign({}, t, { hard: a })
+      return t
+    }
+    const add = (g, prop, value, tok) => rows.push(Object.assign({ g, prop, value: value == null ? '' : String(value) }, tok ? { tok } : {}))
+    const one = (g, prop, value) => add(g, prop, value, tokFor(prop, value))
+    const sides = (g, prop, longs, fmt) => {
+      const vals = longs.map((p) => cs.getPropertyValue(p))
+      if (vals.every((v) => !v || parseFloat(v) === 0)) return
+      const q = quad(vals)
+      const toks = longs.map((p, i) => tokFor(p, vals[i]))
+      const idx = q.length === 1 ? [0] : q.length === 2 ? [0, 1] : q.length === 3 ? [0, 1, 2] : [0, 1, 2, 3]
+      const parts = idx.map((i) => toks[i])
+      add(g, prop, q.map(fmt || ((x) => x)).join(' '), null)
+      rows[rows.length - 1].parts = parts.map((t, i) => Object.assign({ value: q[i] }, t ? { tok: t } : {}))
+    }
+    // typography
+    if (text || all) {
+      one('type', 'font-family', cs.fontFamily)
+      one('type', 'font-size', cs.fontSize)
+      one('type', 'font-weight', cs.fontWeight)
+      if (cs.lineHeight !== 'normal') one('type', 'line-height', cs.lineHeight)
+      if (cs.letterSpacing !== 'normal' && parseFloat(cs.letterSpacing) !== 0) one('type', 'letter-spacing', cs.letterSpacing)
+      if (all && cs.textTransform !== 'none') add('type', 'text-transform', cs.textTransform)
+      if (all && cs.textAlign !== 'start' && cs.textAlign !== 'left') add('type', 'text-align', cs.textAlign)
+    }
+    // colors
+    if (text || all) add('color', 'color', hex(cs.color), tokFor('color', cs.color))
+    const bg = rgba(cs.backgroundColor)
+    if (bg && bg[3] > 0) add('color', 'background-color', hexOf(bg), tokFor('background-color', cs.backgroundColor))
+    if (cs.backgroundImage && cs.backgroundImage !== 'none' && all) add('color', 'background-image', cs.backgroundImage.slice(0, 200))
+    const bw = parseFloat(cs.borderTopWidth) || parseFloat(cs.borderRightWidth) || parseFloat(cs.borderBottomWidth) || parseFloat(cs.borderLeftWidth)
+    if (bw && cs.borderTopStyle !== 'none') add('color', 'border-color', hex(cs.borderTopColor), tokFor('border-top-color', cs.borderTopColor))
+    // spacing
+    sides('space', 'padding', ['padding-top', 'padding-right', 'padding-bottom', 'padding-left'])
+    if (all) sides('space', 'margin', ['margin-top', 'margin-right', 'margin-bottom', 'margin-left'])
+    const flexGrid = /flex|grid/.test(cs.display)
+    if (flexGrid && cs.rowGap !== 'normal' && (parseFloat(cs.rowGap) || parseFloat(cs.columnGap))) {
+      if (cs.rowGap === cs.columnGap) one('space', 'gap', cs.rowGap)
+      else { one('space', 'row-gap', cs.rowGap); one('space', 'column-gap', cs.columnGap) }
+    }
+    // size and shape
+    if (all) { const r = el.getBoundingClientRect(); add('size', 'width', fmtPx(r.width)); add('size', 'height', fmtPx(r.height)) }
+    if (bw && cs.borderTopStyle !== 'none') sides('shape', 'border-width', ['border-top-width', 'border-right-width', 'border-bottom-width', 'border-left-width'])
+    sides('shape', 'border-radius', ['border-top-left-radius', 'border-top-right-radius', 'border-bottom-right-radius', 'border-bottom-left-radius'])
+    if (cs.boxShadow && cs.boxShadow !== 'none') { const t = tokFor('box-shadow', cs.boxShadow); add('shape', 'box-shadow', cs.boxShadow.replace(/rgba?\([^)]*\)/g, (m) => hex(m)), t) }
+    if (+cs.opacity < 1) add('shape', 'opacity', cs.opacity)
+    // layout
+    if (all || flexGrid) {
+      if (all || flexGrid) add('layout', 'display', cs.display)
+      if (/flex/.test(cs.display)) { add('layout', 'flex-direction', cs.flexDirection); if (cs.flexWrap !== 'nowrap') add('layout', 'flex-wrap', cs.flexWrap); add('layout', 'justify-content', cs.justifyContent); add('layout', 'align-items', cs.alignItems) }
+      if (/grid/.test(cs.display)) { add('layout', 'grid-template-columns', cs.gridTemplateColumns.slice(0, 160)); if (cs.gridTemplateRows !== 'none') add('layout', 'grid-template-rows', cs.gridTemplateRows.slice(0, 160)); add('layout', 'align-items', cs.alignItems) }
+      if (all && cs.position !== 'static') add('layout', 'position', cs.position)
+    }
+    return rows
+  }
+  const box = (el) => { const r = el.getBoundingClientRect(); return [Math.round(r.left + scrollX), Math.round(r.top + scrollY), Math.round(r.width), Math.round(r.height)] }
+  function assetsOf (el) {
+    const out = []
+    const list = [el, ...el.querySelectorAll('img, svg, picture source, video, [style*="url("], *')].slice(0, 400)
+    const seen = new Set()
+    for (const e of list) {
+      if (out.length >= 30) break
+      const t = e.tagName.toLowerCase()
+      if (t === 'svg' && !(e.parentElement && e.parentElement.closest('svg'))) {
+        const markup = e.outerHTML
+        if (markup.length <= 200000 && !seen.has(markup)) { seen.add(markup); const r = e.getBoundingClientRect(); out.push({ kind: 'svg', name: (nameOf(e) || 'icon').replace(/[^\w.-]+/g, '-').slice(0, 40) + '.svg', size: [Math.round(r.width), Math.round(r.height)], svg: markup }) }
+        continue
+      }
+      if (t === 'img' && (e.currentSrc || e.src)) { const u = e.currentSrc || e.src; if (!seen.has(u)) { seen.add(u); out.push({ kind: 'img', url: u, name: decodeURIComponent(u.split(/[?#]/)[0].split('/').pop() || 'image').slice(0, 80), size: [e.naturalWidth, e.naturalHeight], alt: clean(e.getAttribute('alt')).slice(0, 120) }) } continue }
+      const bgi = getComputedStyle(e).backgroundImage
+      if (bgi && bgi !== 'none') for (const m of bgi.matchAll(/url\(["']?([^"')]+)["']?\)/g)) { if (seen.has(m[1]) || /^data:/.test(m[1]) && m[1].length > 200000) continue; seen.add(m[1]); out.push({ kind: 'background', url: m[1], name: decodeURIComponent(m[1].split(/[?#]/)[0].split('/').pop() || 'background').slice(0, 80) }) }
+    }
+    return out
+  }
+  /** Full description of one element for the canvas inspector (Dev mode). */
+  function describe (el, state) {
+    const cs = getComputedStyle(el)
+    const parent = el.parentElement && el.parentElement !== document.documentElement ? el.parentElement : null
+    const b = el.getBoundingClientRect()
+    let inset = null
+    if (parent) { const p = parent.getBoundingClientRect(); inset = [b.top - p.top, p.right - b.right, p.bottom - b.bottom, b.left - p.left].map((n) => Math.round(n)) }
+    return {
+      sel: selectorOf(el), tag: el.tagName.toLowerCase(), role: roleOf(el), name: nameOf(el), box: box(el), state: state || 'default',
+      rows: rowsOf(el, true),
+      contrast: ownText(el) || /^(input|textarea|select|button)$/i.test(el.tagName) ? contrastOf(el, cs) : null,
+      states: statesOf(el),
+      parent: parent ? { sel: selectorOf(parent), tag: parent.tagName.toLowerCase(), inset } : null,
+      assets: assetsOf(el)
+    }
+  }
+  const meaningful = (el, cs) => {
+    if (/^(script|style|template|noscript|head|meta|link|br|wbr)$/i.test(el.tagName)) return false
+    if (el.closest('[data-qawalk-overlay]')) return false
+    const role = roleOf(el)
+    if (role && !/^(paragraph|listitem|list|label)$/.test(role)) return true
+    if (ownText(el) || /^(img|svg|video|canvas|input|select|textarea)$/i.test(el.tagName)) return true
+    const bg = rgba(cs.backgroundColor)
+    return !!((bg && bg[3] > 0) || (parseFloat(cs.borderTopWidth) && cs.borderTopStyle !== 'none') || cs.boxShadow !== 'none' || parseFloat(cs.borderTopLeftRadius) || /flex|grid/.test(cs.display))
+  }
+  /** Rows as the compact spec form: { prop: { value, token?, mode?, nearest?, var?, hard? } }. */
+  function compact (rows, inherit) {
+    const out = {}
+    for (const r of rows) {
+      if (r.g === 'size') continue
+      const one = (t) => !t ? {} : t.m === 'exact' ? Object.assign({ token: t.name }, t.mode ? { mode: t.mode } : {}, t.hard ? { hard: true } : {}) : t.m === 'nearest' ? Object.assign({ nearest: t.name }, t.via ? { var: t.via } : {}) : t.via ? { var: t.via } : { token: null }
+      let entry
+      if (r.parts) {
+        const ts = r.parts.map((p) => p.tok)
+        entry = { value: r.value }
+        if (ts.every((t) => !t || t.m === 'exact')) { if (ts.some(Boolean)) { entry.token = ts.map((t) => t ? t.name : '0').join(' '); if (ts.some((t) => t && t.hard)) entry.hard = true } } else if (ts.some((t) => t && t.m === 'nearest')) entry.nearest = ts.map((t) => t ? t.name || '-' : '0').join(' '); else entry.token = null
+      } else entry = Object.assign({ value: r.value }, one(r.tok))
+      if (inherit && INHERITED.test(r.prop) && inherit[r.prop] && inherit[r.prop].value === entry.value) continue
+      out[r.prop] = entry
+    }
+    return out
+  }
+  const STATE_PROPS = ['color', 'background-color', 'border-color', 'box-shadow', 'opacity', 'text-decoration-line', 'outline-color', 'outline-width']
+  /** The page as the spec agents read: meaningful elements in document order with roles, names, styles → tokens. */
+  async function pageSpec () {
+    await loadRules()
+    const max = o.maxElements || 300
+    const elements = []
+    const idx = new Map()
+    // the page's own typography and text color (body): elements list only what differs from what they inherit
+    const page = compact(rowsOf(document.body, true).filter((r) => INHERITED.test(r.prop)))
+    const eff = []
+    const all = [...document.body.querySelectorAll('*')]
+    for (const el of all) {
+      if (elements.length >= max) break
+      const cs = getComputedStyle(el)
+      if (!visible(el) || !meaningful(el, cs)) continue
+      let p = el.parentElement; while (p && !idx.has(p)) p = p.parentElement
+      const parent = p ? idx.get(p) : -1
+      const rows = rowsOf(el, false)
+      const inherit = parent >= 0 ? eff[parent] : page
+      const styles = compact(rows, inherit)
+      const mine = Object.assign({}, inherit); for (const p of Object.keys(styles)) if (INHERITED.test(p)) mine[p] = styles[p]
+      eff.push(mine)
+      const item = { i: elements.length, parent, tag: el.tagName.toLowerCase(), role: roleOf(el), name: nameOf(el) || null, sel: selectorOf(el), box: box(el), styles }
+      if (!ownText(el) && item.role !== 'heading' && item.name && el.children.length) item.name = null // a container's text is its children's
+      if (ownText(el) || /^(input|textarea|select|button)$/i.test(el.tagName)) { const c = contrastOf(el, cs); if (c) item.contrast = { ratio: c.ratio, aa: c.aa } }
+      const states = /^(a|button|input|select|textarea|summary)$/i.test(el.tagName) || el.hasAttribute('tabindex') || /button|link|tab|menuitem|checkbox|switch/.test(item.role || '') ? statesOf(el) : []
+      if (states.length) {
+        item.states = {}
+        const base = {}; for (const r of rows) base[r.prop] = r.value
+        for (const s of states) {
+          forceState(el, s)
+          const diff = {}
+          for (const r of rowsOf(el, false)) if (STATE_PROPS.includes(r.prop) && base[r.prop] !== r.value) diff[r.prop] = compact([r])[r.prop]
+          const cs2 = getComputedStyle(el)
+          for (const p of ['opacity', 'text-decoration-line', 'outline-width']) { const v = cs2.getPropertyValue(p); if (!(p in base) && v !== cs.getPropertyValue(p)) diff[p] = { value: v } }
+          item.states[s] = diff
+        }
+        forceState(null)
+      }
+      const t = el.tagName.toLowerCase()
+      if (t === 'img') item.asset = { kind: 'img', src: (el.currentSrc || el.src || '').replace(location.origin, '').slice(0, 200), size: [el.naturalWidth, el.naturalHeight], alt: el.getAttribute('alt') }
+      if (t === 'svg') item.asset = { kind: 'svg' }
+      idx.set(el, item.i)
+      elements.push(item)
+    }
+    const u = usage(elements)
+    return {
+      schema: 'qawalk.spec.v1',
+      title: document.title, lang: document.documentElement.lang || null,
+      viewport: [innerWidth, innerHeight], size: [document.documentElement.scrollWidth, document.documentElement.scrollHeight],
+      tokens: TOK.entries.length ? { count: new Set(TOK.entries.map((e) => e.name)).size, modes: TOK.modes } : null,
+      page, elements, used: u.used, off: u.off
+    }
+  }
+  /** Tokens used by the elements (name → count) and raw values outside the set, from spec elements or the live page. */
+  function usage (elements) {
+    const used = {}, off = new Map()
+    const take = (prop, entry, sel) => {
+      if (!entry) return
+      if (entry.token) for (const n of String(entry.token).split(' ')) { if (n !== '0') used[n] = (used[n] || 0) + 1 }
+      if (!entry.token && (entry.nearest || entry.token === null || entry.hard)) {
+        const k = prop + '|' + entry.value
+        const cur = off.get(k) || { prop, value: entry.value, count: 0, nearest: entry.nearest || null, sel }
+        cur.count++; off.set(k, cur)
+      }
+    }
+    for (const e of elements) for (const p of Object.keys(e.styles)) take(p, e.styles[p], e.sel)
+    return { used, off: [...off.values()].sort((a, b) => b.count - a.count).slice(0, 60) }
+  }
+  /** Live page usage for the canvas Tokens tab: tokens used, values outside the set, raw values that equal a token. */
+  async function liveUsage () {
+    await loadRules()
+    const elements = []
+    for (const el of [...document.body.querySelectorAll('*')].slice(0, 3000)) {
+      const cs = getComputedStyle(el)
+      if (!visible(el) || !meaningful(el, cs)) continue
+      elements.push({ sel: selectorOf(el), styles: compact(rowsOf(el, false)) })
+    }
+    const u = usage(elements)
+    // the stylesheet itself: raw values the author typed that equal a token (use the custom property instead)
+    const hard = []
+    const probe = document.createElement('div'); probe.style.display = 'none'; document.documentElement.appendChild(probe)
+    for (const r of rules || []) {
+      if (hard.length >= 60) break
+      for (let i = 0; i < r.style.length; i++) {
+        const prop = r.style[i]; const raw = r.style.getPropertyValue(prop)
+        if (!raw || /var\(/.test(raw) || prop.startsWith('--') || !kindOf(prop)) continue
+        probe.style.cssText = ''; probe.style.setProperty(prop, raw)
+        const t = match(prop, getComputedStyle(probe).getPropertyValue(prop))
+        if (t && t.m === 'exact') hard.push({ sel: r.sel.slice(0, 160), prop, value: kindOf(prop).kind === 'color' ? hex(raw) || raw.trim() : raw.trim(), token: t.name })
+      }
+    }
+    probe.remove()
+    const all = []; const seen = new Set()
+    for (const e of TOK.entries) { const k = e.name + '|' + (e.mode || ''); if (seen.has(k)) continue; seen.add(k); all.push({ name: e.name, value: String(e.css).slice(0, 120), kind: e.kind, mode: e.mode || null, deprecated: e.deprecated || false }) }
+    return { used: u.used, off: u.off, hard, all: all.slice(0, 600), modes: TOK.modes }
+  }
+  /** Elements to outline for a token name, or for a property and raw value. */
+  function elementsFor (q) {
+    const out = []
+    for (const el of [...document.body.querySelectorAll('*')].slice(0, 3000)) {
+      if (out.length >= 300) break
+      const cs = getComputedStyle(el)
+      if (!visible(el) || !meaningful(el, cs)) continue
+      const st = compact(rowsOf(el, false))
+      const hit = Object.keys(st).some((p) => q.token ? String(st[p].token || '').split(' ').includes(q.token) : p === q.prop && st[p].value === q.value)
+      if (hit) out.push(el)
+    }
+    return out
+  }
+  return { tokens: TOK, match, describe, pageSpec, liveUsage, elementsFor, statesOf, forceState, loadRules, selectorOf, varName, hex }
+}
+
+// ---------------- Node side: reading a spec, and comparing an implementation with it ----------------
+
+const show = (s) => s.token ? `${s.value}=${s.token}${s.mode ? `(${s.mode})` : ''}${s.hard ? ' (typed raw; use the custom property)' : ''}` : s.nearest ? `${s.value} (not a token; nearest ${s.nearest})` : s.var ? `${s.value} via ${s.var}` : s.token === null ? `${s.value} (not a token)` : String(s.value)
+const SHORTP = { 'background-color': 'bg', 'font-family': 'font', 'font-size': 'size', 'font-weight': 'weight', 'line-height': 'leading', 'letter-spacing': 'tracking', 'border-radius': 'radius', 'border-color': 'border', 'border-width': 'border-width', 'box-shadow': 'shadow', padding: 'pad' }
+/** An element as one line: role or tag, name, size, styles with tokens. */
+export function elementLine (e) {
+  const head = `${e.role && e.role !== e.tag ? `${e.tag}[${e.role}]` : e.tag}${e.name ? ` "${e.name}"` : ''}`
+  const st = Object.entries(e.styles || {}).map(([p, s]) => `${SHORTP[p] || p} ${show(s)}`)
+  if (e.contrast) st.push(`contrast ${e.contrast.ratio}:1 ${e.contrast.aa ? 'AA' : 'fails AA'}`)
+  if (e.asset?.kind === 'img') st.push(`img ${e.asset.src}${e.asset.alt ? ` alt "${e.asset.alt}"` : ''}`)
+  return `${head}  ${e.box ? `${e.box[2]}×${e.box[3]}` : ''}${st.length ? `  ${st.join(' · ')}` : ''}  {${e.sel}}`
+}
+/** The spec as indented text: the format the CLI prints and MCP returns (token-efficient, readable). */
+export function specText (spec, { title = '' } = {}) {
+  if (!spec?.elements) return 'No spec for this step: walk it again with the current CLI (design steps, or steps with packs: [design]).'
+  const depth = new Map()
+  const lines = [`${title ? title + ' · ' : ''}${spec.viewport ? `${spec.viewport[0]}×${spec.viewport[1]}` : ''} · ${spec.elements.length} elements · ${spec.tokens ? `${spec.tokens.count} tokens${spec.tokens.modes?.length ? ` (modes ${spec.tokens.modes.join(', ')})` : ''}` : 'no token set'}`]
+  if (spec.page && Object.keys(spec.page).length) lines.push(`page  ${Object.entries(spec.page).map(([p, s]) => `${SHORTP[p] || p} ${show(s)}`).join(' · ')}  (inherited unless an element says otherwise)`)
+  for (const e of spec.elements) {
+    const d = e.parent >= 0 ? (depth.get(e.parent) ?? 0) + 1 : 0
+    depth.set(e.i, d)
+    lines.push('  '.repeat(d) + elementLine(e))
+    for (const [s, diff] of Object.entries(e.states || {})) {
+      const parts = Object.entries(diff).map(([p, v]) => `${SHORTP[p] || p} ${show(v)}`)
+      lines.push('  '.repeat(d + 1) + `:${s} ${parts.length ? parts.join(' · ') : '(no visible change)'}`)
+    }
+  }
+  if (spec.off?.length) lines.push('', 'Values outside the token set:', ...spec.off.slice(0, 20).map((o) => `  ${o.prop} ${o.value} ×${o.count}${o.nearest ? ` → nearest ${o.nearest}` : ''}  {${o.sel}}`))
+  return lines.join('\n')
+}
+
+const norm = (s) => String(s || '').toLowerCase().replace(/\s+/g, ' ').trim()
+const keyOf = (e) => e.role && e.name ? `${e.role}|${norm(e.name)}` : e.name && e.tag ? `${e.tag}|${norm(e.name)}` : ['main', 'navigation', 'banner', 'contentinfo', 'form', 'dialog', 'complementary'].includes(e.role) ? `${e.role}|` : null
+const COMPARE = ['color', 'background-color', 'border-color', 'font-family', 'font-size', 'font-weight', 'line-height', 'letter-spacing', 'padding', 'gap', 'row-gap', 'column-gap', 'border-radius', 'border-width', 'box-shadow']
+const sameValue = (a, b) => norm(a) === norm(b) || (/^-?[\d.]+px$/.test(a) && /^-?[\d.]+px$/.test(b) && Math.abs(parseFloat(a) - parseFloat(b)) < 0.6)
+/**
+ * Drift of an implementation spec from the approved design spec, in the spec's vocabulary: elements matched by
+ * role and accessible name (landmarks by role), then each style the design gives a token compared with what the
+ * implementation computes. Returns [{ element, prop, state?, expected: { token, value }, actual: { value, token? }, kind }].
+ * kind: missing (the element is not in the implementation), value (different value), raw (same value, typed raw
+ * instead of the token), state (an interaction state the design defines is missing or differs).
+ */
+export function specDrift (impl, ref) {
+  const out = []
+  if (!impl?.elements || !ref?.elements) return out
+  // what each element shows, inherited values included (the spec lists only what differs from the parent)
+  const effective = (spec) => { const eff = []; for (const e of spec.elements) { const up = e.parent >= 0 && eff[e.parent] ? eff[e.parent] : (spec.page || {}); const own = {}; for (const [p, v] of Object.entries(up)) if (/^(color|font-|line-height|letter-spacing)/.test(p)) own[p] = v; eff[e.i] = Object.assign(own, e.styles || {}) } return eff }
+  const implEff = effective(impl), refEff = effective(ref)
+  const pool = new Map()
+  for (const e of impl.elements) { const k = keyOf(e); if (k) { if (!pool.has(k)) pool.set(k, []); pool.get(k).push(e) } }
+  const label = (e) => `${e.role || e.tag}${e.name ? ` "${e.name}"` : ''}`
+  const used = new Map()
+  for (const r of ref.elements) {
+    const k = keyOf(r); if (!k) continue
+    const n = used.get(k) || 0; used.set(k, n + 1)
+    const m = pool.get(k)?.[n]
+    if (!m) { out.push({ element: label(r), ref: r.sel, kind: 'missing' }); continue }
+    const cmp = (rs, ms, state) => {
+      for (const p of COMPARE) {
+        const want = rs[p]; if (!want) continue
+        const got = ms[p]
+        if (!got) { if (want.token && !state) { /* inherited from a parent in the implementation: compare with nothing to say */ } else if (want.token && state) out.push({ element: label(r), sel: m.sel, prop: p, state, expected: { token: want.token, value: want.value }, actual: null, kind: 'state' }); continue }
+        if (!sameValue(want.value, got.value)) out.push({ element: label(r), sel: m.sel, prop: p, ...(state ? { state } : {}), expected: { token: want.token || null, value: want.value }, actual: { value: got.value, token: got.token || null, nearest: got.nearest || null }, kind: state ? 'state' : 'value' })
+        else if (want.token && got.hard && !want.hard) out.push({ element: label(r), sel: m.sel, prop: p, ...(state ? { state } : {}), expected: { token: want.token, value: want.value }, actual: { value: got.value }, kind: 'raw' })
+      }
+    }
+    // text elements (they carry a contrast) are compared with what they show, inherited typography and color included
+    cmp(r.contrast ? refEff[r.i] || r.styles || {} : r.styles || {}, implEff[m.i] || m.styles || {}, null)
+    for (const [s, diff] of Object.entries(r.states || {})) {
+      if (!m.states?.[s]) { if (Object.keys(diff).length) out.push({ element: label(r), sel: m.sel, state: s, kind: 'state', expected: null, actual: null }); continue }
+      cmp(diff, m.states[s], s)
+    }
+  }
+  return out
+}
+/** Drift findings as lines an agent can act on. */
+export function driftText (findings, { title = '' } = {}) {
+  if (!findings.length) return `${title ? title + ': ' : ''}matches the approved design (roles, names, tokens and states).`
+  const lines = [`${title ? title + ': ' : ''}${findings.length} difference${findings.length === 1 ? '' : 's'} from the approved design`]
+  for (const f of findings) {
+    const exp = f.expected ? `${f.expected.token ? `token ${f.expected.token} (${f.expected.value})` : f.expected.value}` : ''
+    const act = f.actual ? `${f.actual.value}${f.actual.token ? `=${f.actual.token}` : f.actual.nearest ? ' (not a token)' : ''}` : ''
+    if (f.kind === 'missing') lines.push(`- ${f.element}: not found in the implementation (design: {${f.ref}})`)
+    else if (f.kind === 'raw') lines.push(`- ${f.element}${f.state ? ` :${f.state}` : ''}: ${f.prop} has the right value but is typed raw; use var(--${f.expected.token.replace(/\./g, '-')})  {${f.sel}}`)
+    else if (f.kind === 'state' && !f.prop) lines.push(`- ${f.element}: the design defines :${f.state}; the implementation does not  {${f.sel}}`)
+    else lines.push(`- ${f.element}${f.state ? ` :${f.state}` : ''}: ${f.prop} expected ${exp}, got ${act || 'nothing'}  {${f.sel}}`)
+  }
+  return lines.join('\n')
+}
+
+/** Expression for page.evaluate that returns the page spec (async: linked stylesheets may need a fetch). */
+export const pageSpecScript = (tokens, maxElements = 300) => `(${kalokoDev.toString()})(${JSON.stringify({ tokens: tokens || null, maxElements })}).pageSpec()`