kaloko 0.3.0

package/src/lib/probe.mjs

@@ -0,0 +1,379 @@
+/**
+ * In-page probe. Runs inside the browser via page.evaluate, so it must stay
+ * self-contained (no imports, no outer variables).
+ *
+ * Produces:
+ *  - state: reduced, evaluator-friendly outline of the visible page
+ *  - scoped: reduced outlines limited to criterion scopes
+ *  - checks: deterministic check results with evidence
+ *  - boxes: highlight rectangles in page coordinates
+ *  - overflow, meta, size
+ *  - design (when asked): structure (headings, landmarks, actions, fields) and used style values,
+ *    compared with the design reference and the token set outside the page (#42)
+ */
+export function probe ({ checks = [], highlights = [], scopes = [], maxChars = 90000, design = false }) {
+  const SKIP = new Set(['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEMPLATE', 'SVG', 'IFRAME', 'CANVAS', 'VIDEO', 'AUDIO', 'OBJECT', 'LINK', 'META'])
+  const LANDMARK = { HEADER: 'header', NAV: 'nav', MAIN: 'main', FOOTER: 'footer', ASIDE: 'aside', DIALOG: 'dialog', FORM: 'form' }
+  const ROLE_LANDMARK = { banner: 'header', navigation: 'nav', main: 'main', contentinfo: 'footer', complementary: 'aside', dialog: 'dialog', alertdialog: 'dialog', form: 'form' }
+  const mask = (s) => s
+    .replace(/[\w.+-]+@[\w-]+\.[\w.-]+/g, '<email>')
+    .replace(/\b[a-f0-9]{24,}\b/gi, '<token>')
+  const clean = (s) => mask(String(s || '').replace(/\s+/g, ' ').trim())
+  // Signed download links (CloudFront Policy/Signature, S3 X-Amz-*, GCS X-Goog-*, Azure sig, token) carry ~1 kB of
+  // credentials per attachment: noise for criteria and the evaluator, and a secret on the canvas.
+  const SIGNED = /^(policy|signature|key-pair-id|x-amz-[\w-]+|x-goog-[\w-]+|sig|token|access_token)$/i
+  const href = (h) => {
+    const raw = String(h || '')
+    const q = raw.indexOf('?')
+    if (q < 0) return raw
+    try {
+      const u = new URL(raw, location.href)
+      const keys = [...u.searchParams.keys()]
+      if (!keys.some((k) => SIGNED.test(k))) return raw
+      const kept = keys.filter((k) => !SIGNED.test(k))
+      const rest = new URLSearchParams(kept.map((k) => [k, u.searchParams.get(k)])).toString()
+      return `${raw.slice(0, q)}?${rest ? `${rest}&` : ''}<signed>`
+    } catch { return raw }
+  }
+  // Match on the raw text, as the verdict does, and mask only the snippet that is returned.
+  // Masking first turned e-mails into <email>, so a pattern containing an address decided the
+  // verdict but never matched the evidence text (evidence fell back to the page start or
+  // "found: undefined").
+  const matchIn = (raw, re) => {
+    const text = String(raw || '')
+    const m = text.match(re)
+    if (!m) return { match: null }
+    const at = m.index
+    const pre = clean(text.slice(Math.max(0, at - 80), at)).slice(-40)
+    const post = clean(text.slice(at + m[0].length, at + m[0].length + 80)).slice(0, 40)
+    const hit = clean(m[0])
+    return {
+      match: hit.length > 200 ? `${hit.slice(0, 120)}…${hit.slice(-60)}` : hit,
+      before: `${at > 40 ? '…' : ''}${pre}${pre && /\s/.test(text[at - 1] || '') ? ' ' : ''}`,
+      after: `${post && /\s/.test(text[at + m[0].length] || '') ? ' ' : ''}${post}${text.length > at + m[0].length + 40 ? '…' : ''}`
+    }
+  }
+  const visible = (el) => {
+    if (!(el instanceof Element)) return true
+    if (el.closest('head')) return true // meta, link, title: present means visible to crawlers
+    if (el.closest('[aria-hidden="true"],[hidden]')) return false
+    if (typeof el.checkVisibility === 'function') return el.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true })
+    const cs = getComputedStyle(el)
+    return cs.display !== 'none' && cs.visibility !== 'hidden'
+  }
+  const labelFor = (el) => {
+    if (el.labels && el.labels.length) return clean([...el.labels].map((l) => l.innerText).join(' '))
+    return clean(el.getAttribute('aria-label') || el.getAttribute('placeholder') || el.getAttribute('title') || el.name || '')
+  }
+  const hooks = (el) => {
+    const out = []
+    for (const a of el.attributes) {
+      if (a.name.startsWith('data-test') || a.name === 'data-qa' || a.name === 'id' && /^[a-z][\w-]{2,40}$/i.test(a.value)) out.push(`${a.name}=${a.value}`)
+    }
+    return out.length ? ` {${out.join(' ')}}` : ''
+  }
+
+  function outline (root) {
+    const sections = {}
+    const push = (section, line) => { if (line) (sections[section] ||= []).push(line) }
+    const walk = (node, section) => {
+      if (node.nodeType === Node.TEXT_NODE) {
+        const text = clean(node.textContent)
+        if (text) push(section, text)
+        return
+      }
+      if (node.nodeType !== Node.ELEMENT_NODE) return
+      const el = node
+      if (SKIP.has(el.tagName.toUpperCase())) return
+      const tag = el.tagName
+      // custom-styled checkboxes/radios: the native input is hidden, its label is what people see
+      if (tag === 'LABEL' && el.control && ['checkbox', 'radio'].includes(el.control.type) && !visible(el.control) && visible(el)) {
+        const c = el.control
+        push(LANDMARK[tag] || section, `[${c.type} ${c.checked ? 'checked' : 'unchecked'}${c.required ? ' required' : ''}] ${clean(el.innerText)}${hooks(c)}`)
+        return
+      }
+      if (!visible(el)) return
+      const role = el.getAttribute('role')
+      const next = LANDMARK[tag] || ROLE_LANDMARK[role] || section
+      if (/^H[1-6]$/.test(tag)) { push(next, `${'#'.repeat(+tag[1])} ${clean(el.innerText)}${hooks(el)}`); return }
+      if (tag === 'A') { push(next, `[link → ${href(el.getAttribute('href'))}] ${clean(el.innerText || el.getAttribute('aria-label'))}${hooks(el)}`); return }
+      if (tag === 'BUTTON' || role === 'button') { push(next, `[button${el.disabled ? ' disabled' : ''}] ${clean(el.innerText || el.getAttribute('aria-label'))}${hooks(el)}`); return }
+      if (tag === 'IMG') { const alt = clean(el.getAttribute('alt')); if (alt) push(next, `[image] ${alt}`); return }
+      if (tag === 'INPUT') {
+        const type = (el.getAttribute('type') || 'text').toLowerCase()
+        if (type === 'hidden') { if (el.name) push(next, `[hidden ${el.name}=${clean(el.value).slice(0, 60)}]`); return }
+        if (type === 'checkbox' || type === 'radio') { push(next, `[${type} ${el.checked ? 'checked' : 'unchecked'}${el.required ? ' required' : ''}] ${labelFor(el)}${hooks(el)}`); return }
+        if (type === 'submit' || type === 'button') { push(next, `[button] ${clean(el.value)}${hooks(el)}`); return }
+        push(next, `[input ${type}${el.required ? ' required' : ''}] ${labelFor(el)}${el.value && type !== 'password' ? ` = ${clean(el.value).slice(0, 80)}` : ''}${hooks(el)}`)
+        return
+      }
+      if (tag === 'SELECT') { push(next, `[select] ${labelFor(el)} = ${clean(el.selectedOptions?.[0]?.text)}`); return }
+      if (tag === 'TEXTAREA') { push(next, `[textarea] ${labelFor(el)}`); return }
+      if (tag === 'LABEL' && el.control && visible(el.control)) return // rendered with its control
+      for (const child of el.childNodes) walk(child, next)
+    }
+    walk(root, 'body')
+    // merge consecutive text fragments
+    for (const key of Object.keys(sections)) {
+      const merged = []
+      for (const line of sections[key]) {
+        const prev = merged[merged.length - 1]
+        if (prev && !line.startsWith('[') && !line.startsWith('#') && !prev.startsWith('[') && !prev.startsWith('#') && prev.length < 400) merged[merged.length - 1] = `${prev} ${line}`
+        else merged.push(line)
+      }
+      sections[key] = merged
+    }
+    let size = JSON.stringify(sections).length
+    if (size > maxChars) {
+      for (const key of ['footer', 'nav', 'header', 'aside', 'body']) {
+        if (size <= maxChars) break
+        if (sections[key]) { sections[key] = [`(${sections[key].length} lines omitted)`]; size = JSON.stringify(sections).length }
+      }
+    }
+    return sections
+  }
+
+  const meta = {
+    title: document.title,
+    lang: document.documentElement.lang || null,
+    description: document.querySelector('meta[name="description"]')?.content || null,
+    canonical: document.querySelector('link[rel="canonical"]')?.href || null,
+    robots: document.querySelector('meta[name="robots"]')?.content || null,
+    hreflang: [...document.querySelectorAll('link[rel="alternate"][hreflang]')].map((l) => ({ lang: l.hreflang, href: l.href })),
+    h1: [...document.querySelectorAll('h1')].filter(visible).map((h) => clean(h.innerText))
+  }
+
+  const overflowIn = (root) => {
+    const w = document.documentElement.clientWidth
+    const found = []
+    for (const el of root.querySelectorAll('*')) {
+      if (found.length >= 10) break
+      const r = el.getBoundingClientRect()
+      if (!r.width || !visible(el)) continue
+      if (r.right > w + 1 || r.left < -1) {
+        let clipped = false
+        for (let p = el.parentElement; p && p !== document.body; p = p.parentElement) {
+          const ox = getComputedStyle(p).overflowX
+          if (ox === 'hidden' || ox === 'auto' || ox === 'scroll' || ox === 'clip') { clipped = true; break }
+        }
+        if (!clipped) found.push({ el: `${el.tagName.toLowerCase()}${el.className && typeof el.className === 'string' ? '.' + el.className.trim().split(/\s+/).slice(0, 2).join('.') : ''}`, right: Math.round(r.right), width: w, text: clean(el.innerText).slice(0, 60) })
+      }
+    }
+    return found
+  }
+  const overflow = overflowIn(document.body)
+
+  const snippet = (el) => clean(el.outerHTML).slice(0, 220)
+  // accessibility and performance measurements for the a11y and perf packs (own rules, no library)
+  const describe = (el) => `${el.tagName.toLowerCase()}${el.id ? '#' + el.id : ''}${typeof el.className === 'string' && el.className.trim() ? '.' + el.className.trim().split(/\s+/).slice(0, 2).join('.') : ''}`
+  const nameOf = (el) => clean(el.getAttribute('aria-label') || (el.getAttribute('aria-labelledby') || '').split(/\s+/).filter(Boolean).map((i) => document.getElementById(i)?.innerText || '').join(' ') || el.innerText || el.getAttribute('title') || [...el.querySelectorAll('img[alt], svg[aria-label]')].map((i) => i.getAttribute('alt') || i.getAttribute('aria-label')).join(' ') || (el.tagName === 'INPUT' ? el.value : ''))
+  const rgba = (v) => { const m = String(v).match(/rgba?\(([^)]+)\)/); if (!m) return null; const p = m[1].split(/[\s,/]+/).filter(Boolean).map(Number); return [p[0], p[1], p[2], p.length > 3 ? p[3] : 1] }
+  const lum = (c) => { const f = (v) => { v /= 255; return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4 }; return 0.2126 * f(c[0]) + 0.7152 * f(c[1]) + 0.0722 * f(c[2]) }
+  const bgOf = (el) => { for (let e = el; e && e.nodeType === 1; e = e.parentElement) { const cs = getComputedStyle(e); if (cs.backgroundImage && cs.backgroundImage !== 'none') return null; const c = rgba(cs.backgroundColor); if (c && c[3] >= 0.99) return c } return [255, 255, 255, 1] }
+  const listOf = (els, max = 5) => els.slice(0, max).map(describe).join(', ') + (els.length > max ? ` (+${els.length - max})` : '')
+  const a11y = (kind) => {
+    if (kind === 'images_alt') { const bad = [...visibleAll('img').filter((i) => !i.hasAttribute('alt') && !/^(presentation|none)$/.test(i.getAttribute('role') || '')), ...visibleAll('[role=img]').filter((e) => !nameOf(e))]; return { ok: bad.length === 0, evidence: bad.length ? `${bad.length} image(s) without alt: ${listOf(bad)}` : 'every image has alt' } }
+    if (kind === 'names') { const bad = visibleAll('a[href], button, [role=button], [role=link], input[type=submit], input[type=button]').filter((e) => !nameOf(e)); return { ok: bad.length === 0, evidence: bad.length ? `${bad.length} control(s) without an accessible name: ${listOf(bad)}` : 'every link and button has a name' } }
+    if (kind === 'labels') { const bad = visibleAll('input:not([type=hidden]):not([type=submit]):not([type=button]):not([type=image]):not([type=reset]), select, textarea').filter((e) => !(e.labels?.length || e.getAttribute('aria-label') || e.getAttribute('aria-labelledby') || e.getAttribute('title'))); return { ok: bad.length === 0, evidence: bad.length ? `${bad.length} field(s) without a label: ${listOf(bad)}` : 'every field has a label' } }
+    if (kind === 'headings') { const hs = visibleAll('h1, h2, h3, h4, h5, h6'); const bad = []; let prev = 0; for (const h of hs) { const l = Number(h.tagName[1]); if (prev && l > prev + 1) bad.push(`h${prev}→h${l} "${clean(h.innerText).slice(0, 40)}"`); prev = l } return { ok: bad.length === 0, evidence: bad.length ? `heading level skipped: ${bad.slice(0, 3).join('; ')}` : `${hs.length} headings in order` } }
+    if (kind === 'main') { const m = document.querySelector('main, [role=main]'); return { ok: !!m, evidence: m ? describe(m) : 'no main landmark' } }
+    if (kind === 'unique_ids') { const seen = new Map(); for (const e of document.querySelectorAll('[id]')) seen.set(e.id, (seen.get(e.id) || 0) + 1); const dup = [...seen].filter(([, n]) => n > 1).map(([i, n]) => `#${i}×${n}`); return { ok: dup.length === 0, evidence: dup.length ? `duplicate ids: ${dup.slice(0, 5).join(', ')}` : 'ids are unique' } }
+    if (kind === 'contrast') {
+      const bad = []; const seen = new Set(); let checked = 0
+      const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT)
+      for (let t = walker.nextNode(); t && checked < 400; t = walker.nextNode()) {
+        const el = t.parentElement
+        if (!el || seen.has(el) || !t.textContent.trim() || !visible(el)) continue
+        seen.add(el); checked++
+        const cs = getComputedStyle(el); const fg = rgba(cs.color); const bg = bgOf(el)
+        if (!fg || !bg) continue
+        const mix = fg.slice(0, 3).map((v, i) => v * fg[3] + bg[i] * (1 - fg[3]))
+        const [a, b] = [lum(mix), lum(bg)].sort((x, y) => y - x)
+        const ratio = (a + 0.05) / (b + 0.05)
+        const size = parseFloat(cs.fontSize); const large = size >= 24 || (size >= 18.66 && Number(cs.fontWeight) >= 700)
+        if (ratio < (large ? 3 : 4.5)) bad.push(`${describe(el)} "${clean(t.textContent).slice(0, 30)}" ${ratio.toFixed(2)}:1`)
+      }
+      return { ok: bad.length === 0, evidence: bad.length ? `${bad.length} text(s) below WCAG AA contrast: ${bad.slice(0, 4).join('; ')}` : `${checked} texts meet WCAG AA contrast` }
+    }
+    return { ok: null, evidence: `unknown a11y check ${kind}` }
+  }
+  const buffered = (type) => { try { const po = new PerformanceObserver(() => {}); po.observe({ type, buffered: true }); const r = po.takeRecords(); po.disconnect(); return r } catch { return null } }
+  const perf = (kind, check) => {
+    const nav = performance.getEntriesByType('navigation')[0]
+    const sec = (ms) => `${(ms / 1000).toFixed(2)} s`
+    if (kind === 'lcp') { const r = buffered('largest-contentful-paint'); const v = r?.length ? r[r.length - 1].startTime : null; const max = check.max ?? 2500; return v == null ? { ok: null, evidence: 'LCP not measured (no paint entries)' } : { ok: v <= max, evidence: `LCP ${sec(v)} since page load (limit ${sec(max)})` } }
+    if (kind === 'cls') { const r = buffered('layout-shift'); if (!r) return { ok: null, evidence: 'CLS not measured' }; const v = r.filter((e) => !e.hadRecentInput).reduce((s, e) => s + e.value, 0); const max = check.max ?? 0.1; return { ok: v <= max, evidence: `CLS ${v.toFixed(3)} (limit ${max})` } }
+    if (kind === 'ttfb') { if (!nav) return { ok: null, evidence: 'no navigation timing' }; const v = nav.responseStart; const max = check.max ?? 800; return { ok: v <= max, evidence: `TTFB ${Math.round(v)} ms (limit ${max} ms)` } }
+    if (kind === 'weight') { const res = performance.getEntriesByType('resource'); const bytes = (nav?.transferSize || 0) + res.reduce((s, e) => s + (e.transferSize || 0), 0); const opaque = res.filter((e) => !e.transferSize).length; const max = (check.max ?? 3000) * 1024; return { ok: bytes <= max, evidence: `${Math.round(bytes / 1024)} kB transferred in ${res.length + 1} requests (limit ${Math.round(max / 1024)} kB)${opaque ? `; ${opaque} cached or cross-origin without timing count as 0` : ''}` } }
+    return { ok: null, evidence: `unknown perf check ${kind}` }
+  }
+  const visibleAll = (sel) => [...document.querySelectorAll(sel)].filter(visible)
+  // HTTP status of the document (Chrome 109+); null for pages set from stored HTML
+  const httpStatus = performance.getEntriesByType('navigation')[0]?.responseStatus || null
+  const results = {}
+  for (const { id, check } of checks) {
+    try {
+      // optional flags (i, m, s); page text is innerText, which follows CSS text-transform (#54)
+      const re = check.pattern ? new RegExp(check.pattern, 'u' + [...new Set(String(check.flags || '').replace(/[^ims]/g, ''))].join('')) : null
+      let ok = false
+      let evidence = ''
+      switch (check.assert) {
+        case 'exists': { const els = visibleAll(check.selector); ok = els.length > 0; evidence = els[0] ? snippet(els[0]) : `no visible ${check.selector}`; break }
+        case 'absent': { const els = visibleAll(check.selector); ok = els.length === 0; evidence = els[0] ? snippet(els[0]) : `no visible ${check.selector}`; break }
+        case 'count': { const n = visibleAll(check.selector).length; ok = n >= (check.min ?? 0) && n <= (check.max ?? Infinity); evidence = `${n}× ${check.selector}`; break }
+        case 'text_matches': {
+          const els = check.selector ? visibleAll(check.selector) : [document.body]
+          const hit = els.find((el) => re.test(el.innerText))
+          ok = !!hit
+          if (hit) {
+            const { before, match, after } = matchIn(hit.innerText, re)
+            evidence = match != null ? `${before}[${match}]${after}` : clean(hit.innerText).slice(0, 220)
+          } else evidence = els[0] ? `"${clean(els[0].innerText).slice(0, 160)}" does not match /${check.pattern}/` : `no visible ${check.selector}`
+          break
+        }
+        case 'text_absent': {
+          const els = check.selector ? visibleAll(check.selector) : [document.body]
+          const hit = els.find((el) => re.test(el.innerText))
+          ok = !hit
+          evidence = hit ? `found: ${matchIn(hit.innerText, re).match ?? clean(hit.innerText).slice(0, 160)}` : `/${check.pattern}/ not found`
+          break
+        }
+        case 'attr_equals': {
+          const el = document.querySelector(check.selector)
+          if (!el) { evidence = `no ${check.selector}`; break }
+          const v = (check.attr in el && typeof el[check.attr] === 'boolean') ? el[check.attr] : el.getAttribute(check.attr)
+          ok = String(v) === String(check.value)
+          evidence = `${check.attr}=${v}`
+          break
+        }
+        case 'no_overflow': { const list = check.selector ? [...document.querySelectorAll(check.selector)].flatMap(overflowIn) : overflow; ok = list.length === 0; evidence = ok ? 'no horizontal overflow' : list.slice(0, 3).map((o) => `${o.el} right=${o.right}px > ${o.width}px`).join('; '); break }
+        case 'title_matches': ok = re.test(document.title); evidence = document.title; break
+        case 'meta_matches': { const el = document.querySelector(check.selector); const v = el?.getAttribute('content'); ok = v != null && re.test(v); evidence = v ?? `no ${check.selector}`; break }
+        case 'http_status': {
+          if (!httpStatus) { ok = null; evidence = 'HTTP status not known for this capture'; break }
+          ok = check.value != null ? httpStatus === Number(check.value) : httpStatus >= (check.min ?? 200) && httpStatus <= (check.max ?? 299)
+          evidence = `HTTP ${httpStatus} ${location.pathname}${location.search}`
+          break
+        }
+        case 'link_home': {
+          // a visible link to the site's home: /, or a language home such as /cs/ or /en-us
+          const home = visibleAll('a[href]').find((a) => { try { const u = new URL(a.href); return u.origin === location.origin && /^\/([a-z]{2}([-_][a-z]{2})?\/?)?$/i.test(u.pathname) } catch { return false } })
+          ok = !!home; evidence = home ? snippet(home) : 'no visible link to the home page'
+          break
+        }
+        case 'link_matches': { const el = document.querySelector(check.selector); const v = el?.href; ok = v != null && re.test(v); evidence = v ?? `no ${check.selector}`; break }
+        default: {
+          if (/^a11y_/.test(check.assert)) { ({ ok, evidence } = a11y(check.assert.slice(5))); break }
+          if (/^perf_/.test(check.assert)) { ({ ok, evidence } = perf(check.assert.slice(5), check)); break }
+          evidence = `assert ${check.assert} is evaluated outside the page`; ok = null
+        }
+      }
+      results[id] = { ok, evidence }
+    } catch (error) {
+      results[id] = { ok: false, evidence: `check error: ${error.message}` }
+    }
+  }
+
+  const boxes = {}
+  for (const { id, selector } of highlights) {
+    try {
+      boxes[id] = [...document.querySelectorAll(selector)].filter(visible).slice(0, 5).map((el) => {
+        const r = el.getBoundingClientRect()
+        return { x: Math.round(r.left + scrollX), y: Math.round(r.top + scrollY), w: Math.round(r.width), h: Math.round(r.height) }
+      })
+    } catch { boxes[id] = [] }
+  }
+
+  // failing overflow checks point at the overflowing elements
+  for (const { id, check } of checks) {
+    if (check.assert !== 'no_overflow' || results[id]?.ok !== false) continue
+    const root = check.selector ? document.querySelector(check.selector) : document.body
+    const w = document.documentElement.clientWidth
+    boxes[id] = [...(root || document.body).querySelectorAll('*')].filter((el) => { const r = el.getBoundingClientRect(); return r.width && visible(el) && (r.right > w + 1 || r.left < -1) }).slice(0, 5).map((el) => {
+      const r = el.getBoundingClientRect()
+      return { x: Math.round(r.left + scrollX), y: Math.round(r.top + scrollY), w: Math.round(r.width), h: Math.round(r.height) }
+    })
+  }
+
+  const metadata = collectMetadata()
+
+  // design summary: what the page is made of (structure) and which style values it uses
+  function designSummary () {
+    const vis = (sel) => [...document.querySelectorAll(sel)].filter(visible)
+    const labelOf = (el) => clean(el.labels?.[0]?.innerText || el.getAttribute('aria-label') || el.getAttribute('placeholder') || el.name || '').slice(0, 80)
+    const structure = {
+      headings: metadata.headings.slice(0, 40),
+      landmarks: [...new Set(vis('header,nav,main,footer,aside,form,dialog,[role]').map((el) => ROLE_LANDMARK[el.getAttribute('role')] || LANDMARK[el.tagName]).filter(Boolean))].sort(),
+      actions: vis('button,a[href],[role=button],input[type=submit],input[type=button]').map((el) => clean(el.innerText || el.value || el.getAttribute('aria-label') || '').slice(0, 60)).filter(Boolean).slice(0, 40),
+      fields: vis('input:not([type=hidden]):not([type=submit]):not([type=button]),select,textarea').map((el) => ({ type: el.type || el.tagName.toLowerCase(), label: labelOf(el) })).slice(0, 40)
+    }
+    const PROPS = ['color', 'background-color', 'font-family', 'font-size', 'border-radius', 'padding-top', 'padding-right', 'padding-bottom', 'padding-left', 'margin-top', 'margin-bottom', 'gap', 'border-top-color']
+    const styles = {}
+    let n = 0
+    // browser defaults are not authored values: compare with the same tag in an empty document
+    let blank = null
+    try { const f = document.createElement('iframe'); f.style.cssText = 'position:absolute;width:0;height:0;border:0;visibility:hidden'; f.srcdoc = '<!doctype html><body></body>'; document.documentElement.appendChild(f); blank = f } catch {}
+    const defaults = new Map()
+    const uaDefault = (tag, prop) => {
+      const doc = blank?.contentDocument
+      if (!doc?.body) return null
+      if (!defaults.has(tag)) { try { const el = doc.createElement(tag); doc.body.appendChild(el); defaults.set(tag, doc.defaultView.getComputedStyle(el)) } catch { defaults.set(tag, null) } }
+      return defaults.get(tag)?.getPropertyValue(prop) ?? null
+    }
+    for (const el of document.querySelectorAll('body *')) {
+      if (n++ > 3000) break
+      if (!visible(el)) continue
+      const cs = getComputedStyle(el)
+      for (const p of PROPS) {
+        const v = cs.getPropertyValue(p)
+        if (!v || v === '0px' || v === 'normal' || v === 'auto' || /rgba\(0, 0, 0, 0\)/.test(v)) continue
+        if (p === 'border-top-color' && cs.borderTopWidth === '0px') continue
+        if (p === 'color' && ![...el.childNodes].some((x) => x.nodeType === 3 && x.textContent.trim())) continue
+        if (uaDefault(el.tagName.toLowerCase(), p) === v) continue
+        const bucket = (styles[p] ||= {})
+        if (!bucket[v]) bucket[v] = { count: 0, example: snippet(el).slice(0, 120) }
+        bucket[v].count++
+      }
+    }
+    try { blank?.remove() } catch {}
+    return { structure, styles }
+  }
+
+  const scoped = {}
+  for (const { id, selector } of scopes) {
+    const root = document.querySelector(selector)
+    scoped[id] = root ? outline(root) : null
+  }
+
+  function collectMetadata () {
+    const attr = (el, n) => el.getAttribute(n)
+    const metaTags = [...document.querySelectorAll('meta')].map((m) => ({ key: attr(m, 'property') || attr(m, 'name') || attr(m, 'http-equiv') || attr(m, 'itemprop') || (attr(m, 'charset') ? 'charset' : null), kind: attr(m, 'property') ? 'property' : attr(m, 'name') ? 'name' : attr(m, 'http-equiv') ? 'http-equiv' : attr(m, 'itemprop') ? 'itemprop' : 'charset', content: attr(m, 'content') ?? attr(m, 'charset') })).filter((m) => m.key)
+    const links = [...document.querySelectorAll('link[rel]')].filter((l) => !/stylesheet|preload|prefetch|preconnect|dns-prefetch|modulepreload/i.test(l.rel)).map((l) => ({ rel: l.rel, href: l.href, hreflang: attr(l, 'hreflang'), type: attr(l, 'type'), sizes: attr(l, 'sizes') }))
+    const jsonld = [...document.querySelectorAll('script[type="application/ld+json"]')].map((sc) => { try { return { ok: true, data: JSON.parse(sc.textContent) } } catch (e) { return { ok: false, error: e.message, raw: sc.textContent.slice(0, 500) } } })
+    const microdata = [...document.querySelectorAll('[itemscope]:not([itemprop])')].slice(0, 30).map(function item (el) {
+      const props = {}
+      for (const p of el.querySelectorAll('[itemprop]')) {
+        if (p.parentElement.closest('[itemscope]') !== el) continue
+        const v = p.hasAttribute('itemscope') ? item(p) : (attr(p, 'content') ?? attr(p, 'href') ?? attr(p, 'src') ?? clean(p.textContent).slice(0, 200))
+        const k = attr(p, 'itemprop')
+        props[k] = props[k] === undefined ? v : [].concat(props[k], v)
+      }
+      return { type: attr(el, 'itemtype'), props }
+    })
+    const headings = [...document.querySelectorAll('h1,h2,h3,h4,h5,h6')].filter(visible).slice(0, 80).map((h) => ({ level: +h.tagName[1], text: clean(h.innerText).slice(0, 160) }))
+    return { title: document.title, lang: document.documentElement.lang || null, url: location.href, meta: metaTags, links, jsonld, microdata, headings }
+  }
+
+  return {
+    state: outline(document.body),
+    http_status: httpStatus,
+    scoped,
+    checks: results,
+    boxes,
+    overflow,
+    meta,
+    metadata,
+    ...(design ? { design: designSummary() } : {}),
+    size: { width: document.documentElement.scrollWidth, height: document.documentElement.scrollHeight, viewport: [innerWidth, innerHeight] }
+  }
+}

package/src/lib/recheck.mjs

@@ -0,0 +1,70 @@
+// `kaloko evaluate --recheck` (#55): after a scenario fix, re-run the deterministic checks against the stored HTML of
+// each capture instead of walking again (some steps cannot be repeated: data created, e-mails sent once, states that
+// moved on). Page scripts stay off, so nothing in the stored page runs; checks that only the live page can answer
+// (console errors, overflow, performance) keep their result from the capture.
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { readJson, writeJson } from './util.mjs'
+import { readCaptures } from './run.mjs'
+import { latestCaptures, criteriaHash } from './evaluate.mjs'
+import { probe } from './probe.mjs'
+import { probeArgs } from './capture.mjs'
+import { contextOptions, prepareContext } from './access.mjs'
+import { launchEphemeral } from './browser.mjs'
+import { treeChecks } from './apps/tree.mjs'
+
+export const LIVE_ONLY = (assert) => assert === 'no_console_errors' || assert === 'no_overflow' || assert === 'http_status' || /^perf_/.test(assert)
+
+const withBase = (html, url) => {
+  if (!url || /<base\s/i.test(html)) return html
+  const tag = `<base href="${String(url).replace(/"/g, '&quot;')}">`
+  return /<head[^>]*>/i.test(html) ? html.replace(/<head[^>]*>/i, (m) => m + tag) : tag + html
+}
+
+export async function recheckCaptures ({ run, scenario, config, root, env, only = null }) {
+  const nodes = new Map(scenario.nodes.map((n) => [n.id, n]))
+  const entries = latestCaptures(await readCaptures(run.dir)).filter((e) => nodes.has(e.node) && (!only || only.includes(e.node)))
+  if (!entries.length) return { rechecked: 0, skipped: [] }
+  const browser = await launchEphemeral(config)
+  const contexts = new Map()
+  const report = { rechecked: 0, skipped: [] }
+  try {
+    for (const e of entries) {
+      const node = nodes.get(e.node)
+      const file = join(run.dir, e.file)
+      const cap = await readJson(file)
+      if (cap.files?.tree) {
+        // app capture: the deterministic checks run again on the stored UI tree
+        const t = await readJson(join(run.dir, cap.files.tree), null)
+        if (!t) { report.skipped.push(`${e.node}/${e.locale}/${e.viewport}: no stored UI tree`); continue }
+        const { checks, boxes } = treeChecks(node.criteria, t.root, { platform: cap.platform, format: t.format, crash: cap.crash || null, logErrors: cap.console_errors })
+        await writeJson(file, { ...cap, checks, boxes, criteria_hash: criteriaHash(node), rechecked_at: new Date().toISOString() })
+        report.rechecked++
+        continue
+      }
+      const htmlPath = cap.files?.html ? join(run.dir, cap.files.html) : null
+      const html = htmlPath ? await readFile(htmlPath, 'utf8').catch(() => null) : null
+      if (!html) { report.skipped.push(`${e.node}/${e.locale}/${e.viewport}: no stored HTML`); continue }
+      const [width, height] = run.meta.scope.viewports?.[e.viewport] || [1280, 800]
+      const key = `${width}x${height}`
+      if (!contexts.has(key)) {
+        const ctx = await browser.newContext({ ...(await contextOptions(env, { root, config })), javaScriptEnabled: false, viewport: { width, height } })
+        await prepareContext(ctx, env)
+        contexts.set(key, ctx)
+      }
+      const page = await contexts.get(key).newPage()
+      try {
+        await page.setContent(withBase(html, cap.url), { waitUntil: 'load', timeout: 20000 }).catch(() => {})
+        const result = await page.evaluate(probe, probeArgs(node, config.evaluators?.jev?.max_state_chars))
+        const checks = {}
+        for (const c of node.criteria || []) {
+          if (c.check.type !== 'deterministic') continue
+          checks[c.id] = LIVE_ONLY(c.check.assert) ? (cap.checks?.[c.id] ?? { ok: null, evidence: 'live-page check; capture the step again to evaluate it' }) : result.checks[c.id]
+        }
+        await writeJson(file, { ...cap, checks, boxes: result.boxes, criteria_hash: criteriaHash(node), rechecked_at: new Date().toISOString() })
+        report.rechecked++
+      } finally { await page.close() }
+    }
+  } finally { await browser.close() }
+  return report
+}

package/src/lib/run.mjs

@@ -0,0 +1,85 @@
+import { readdir, writeFile, readFile, mkdir } from 'node:fs/promises'
+import { join, relative, resolve } from 'node:path'
+import { readJson, writeJson, readJsonl, appendJsonl, shortId, slugify, today, UserError } from './util.mjs'
+
+/**
+ * A run directory:
+ *   meta.json         run metadata (scenario, env, scope, git, executor)
+ *   captures.jsonl    one line per capture
+ *   steps/<node>/<locale>/<viewport>.{png,html,capture.json,eval.json}
+ *   attachments/      crops and other files
+ *   run.json          built manifest
+ *   index.html        canvas
+ */
+export function runPaths (dir) {
+  return {
+    dir,
+    meta: join(dir, 'meta.json'),
+    captures: join(dir, 'captures.jsonl'),
+    manifest: join(dir, 'run.json'),
+    index: join(dir, 'index.html'),
+    step: (node, locale, viewport, ext) => join(dir, 'steps', node, locale, `${viewport}.${ext}`),
+    attachment: (name) => join(dir, 'attachments', name)
+  }
+}
+
+export function newRunId (scenario, date = new Date()) {
+  const short = shortId()
+  return { id: `${today(date)}-${slugify(scenario.id)}-${short}`, short }
+}
+
+export async function createRun ({ output, scenario, scenarioFile, env, scope, git, executor, root, project = null, issue = null, appVersion = null }) {
+  const { id, short } = newRunId(scenario)
+  const dir = resolve(root, output, id)
+  await mkdir(dir, { recursive: true })
+  const meta = {
+    id,
+    short,
+    scenario_file: relative(root, scenarioFile),
+    scenario: { id: scenario.id, title: scenario.title, kind: scenario.kind || 'task', version: scenario.version ?? null, source: scenario.source ?? null, ...(scenario.archived ? { archived: true } : {}), ...(scenario.platform && scenario.platform !== 'web' ? { platform: scenario.platform } : {}) },
+    environment: { name: env.name, base_url: env.base_url, readonly: env.readonly, ...(env.kind === 'design' ? { kind: 'design' } : {}) },
+    scope,
+    git,
+    executor,
+    project,
+    issue,
+    app_version: appVersion,
+    started_at: new Date().toISOString()
+  }
+  await writeJson(join(dir, 'meta.json'), meta)
+  await writeFile(join(resolve(root, output), 'CURRENT'), id + '\n')
+  return { dir, meta }
+}
+
+/** Resolves --run (id or path) or the CURRENT pointer in the output directory. */
+export async function resolveRun ({ root, output, run }) {
+  const base = resolve(root, output)
+  let dir
+  run ||= process.env.KALOKO_RUN // several agents in one repository: each pins its run
+  if (run) dir = run.includes('/') ? resolve(run) : join(base, run)
+  else {
+    let id
+    try { id = (await readFile(join(base, 'CURRENT'), 'utf8')).trim() } catch {}
+    if (!id) throw new UserError('No current run. Start one with "kaloko start --scenario <file> --env <name>".')
+    dir = join(base, id)
+  }
+  const meta = await readJson(join(dir, 'meta.json'), null)
+  if (!meta) throw new UserError(`Run directory ${dir} has no meta.json`)
+  return { dir, meta, paths: runPaths(dir) }
+}
+
+export const readCaptures = (dir) => readJsonl(join(dir, 'captures.jsonl'))
+export const addCapture = (dir, entry) => appendJsonl(join(dir, 'captures.jsonl'), entry)
+
+/** Lists other runs in the output directory (for history in the canvas). */
+export async function listRuns (root, output) {
+  const base = resolve(root, output)
+  let names = []
+  try { names = (await readdir(base, { withFileTypes: true })).filter((e) => e.isDirectory() && !e.name.startsWith('.')).map((e) => e.name) } catch { return [] }
+  const runs = []
+  for (const name of names) {
+    const manifest = await readJson(join(base, name, 'run.json'), null)
+    if (manifest?.schema === 'qawalk.run.v1') runs.push(manifest)
+  }
+  return runs
+}

package/src/lib/scenario.mjs

@@ -0,0 +1,98 @@
+import { readFile } from 'node:fs/promises'
+import yaml from 'js-yaml'
+import { schemaErrors } from './schema.mjs'
+import { UserError } from './util.mjs'
+import { expandPacks } from './packs.mjs'
+
+export async function loadScenario (file) {
+  const data = yaml.load(await readFile(file, 'utf8'))
+  const problems = validateScenario(data)
+  if (!problems.length) expandPacks(data)
+  if (problems.length) throw new UserError(`Scenario ${file} is invalid:\n  - ${problems.join('\n  - ')}`)
+  return data
+}
+
+/** Schema validation plus cross-reference rules the schema cannot express. */
+export function validateScenario (data) {
+  const problems = schemaErrors('scenario.v1', data)
+  if (problems.length) return problems
+  try { expandPacks(JSON.parse(JSON.stringify(data))) } catch (e) { problems.push(e.message) }
+  const ids = new Set()
+  for (const node of data.nodes) {
+    if (ids.has(node.id)) problems.push(`node id "${node.id}" is duplicated`)
+    ids.add(node.id)
+    const acIds = new Set()
+    for (const c of node.criteria || []) {
+      if (acIds.has(c.id)) problems.push(`node "${node.id}": criterion ${c.id} is duplicated`)
+      acIds.add(c.id)
+    }
+    if (!['decision', 'stack'].includes(node.kind) && !node.execution) problems.push(`node "${node.id}": execution is required for ${node.kind} steps`)
+    if (node.kind === 'stack' && !node.items) problems.push(`node "${node.id}": stack steps need items (urls, file, sitemap, crawl or script)`)
+    if (node.kind === 'stack' && node.items && ['urls', 'file', 'sitemap', 'crawl', 'script'].filter((k) => node.items[k]).length !== 1) problems.push(`node "${node.id}": items needs exactly one source of urls, file, sitemap, crawl or script`)
+    if (node.kind !== 'stack' && (node.items || node.fields)) problems.push(`node "${node.id}": items and fields belong to stack steps`)
+    // app screens are reached by a script or a person as often as by a deep link
+    if (node.kind === 'screen' && !node.path && (!data.platform || data.platform === 'web')) problems.push(`node "${node.id}": screen steps need a path`)
+    if (node.kind === 'stack' && data.platform && data.platform !== 'web') problems.push(`node "${node.id}": stack steps list web pages; they are not available on platform ${data.platform}`)
+    if (node.kind === 'email' && !node.mail) problems.push(`node "${node.id}": email steps need mail.subject`)
+  }
+  const sessions = data.sessions ? Object.keys(data.sessions) : []
+  for (const node of data.nodes) {
+    if (node.session && !sessions.includes(node.session)) problems.push(`node "${node.id}": session "${node.session}" is not declared in sessions`)
+    if (sessions.length && !node.session && !['decision', 'external'].includes(node.kind)) problems.push(`node "${node.id}": session is required when the scenario declares sessions (${sessions.join(', ')})`)
+  }
+  for (const e of data.edges) {
+    if (!ids.has(e.from)) problems.push(`edge ${e.from} → ${e.to}: unknown node "${e.from}"`)
+    if (!ids.has(e.to)) problems.push(`edge ${e.from} → ${e.to}: unknown node "${e.to}"`)
+  }
+  if ((data.environments || []).includes('production') && !data.readonly) {
+    problems.push('scenarios allowed on production must set readonly: true')
+  }
+  return problems
+}
+
+/**
+ * Layered layout: column = longest path from a root, lane = explicit `lane`
+ * or inherited from the parent (+1 for each extra `alt` branch).
+ */
+export function layout (scenario) {
+  const nodes = scenario.nodes
+  const incoming = new Map(nodes.map((n) => [n.id, []]))
+  const outgoing = new Map(nodes.map((n) => [n.id, []]))
+  for (const e of scenario.edges) {
+    incoming.get(e.to)?.push(e)
+    outgoing.get(e.from)?.push(e)
+  }
+  const col = new Map()
+  const visiting = new Set()
+  const depth = (id) => {
+    if (col.has(id)) return col.get(id)
+    if (visiting.has(id)) return 0 // cycle: stop
+    visiting.add(id)
+    const parents = incoming.get(id).filter((e) => !isBackEdge(e))
+    const d = parents.length ? Math.max(...parents.map((e) => depth(e.from) + 1)) : 0
+    visiting.delete(id)
+    col.set(id, d)
+    return d
+  }
+  const order = new Map(nodes.map((n, i) => [n.id, i]))
+  const isBackEdge = (e) => order.get(e.to) <= order.get(e.from)
+  nodes.forEach((n) => depth(n.id))
+
+  const lane = new Map()
+  const taken = new Set()
+  const claim = (c, l) => { while (taken.has(`${c}:${l}`)) l++; taken.add(`${c}:${l}`); return l }
+  // sessions without explicit lanes: one swimlane per person, in declaration order
+  const sessionLane = scenario.sessions && !(scenario.lanes || []).length ? new Map(Object.keys(scenario.sessions).map((k, i) => [k, i])) : null
+  for (const n of [...nodes].sort((a, b) => col.get(a.id) - col.get(b.id) || order.get(a.id) - order.get(b.id))) {
+    let wanted = n.lane
+    if (wanted == null && sessionLane && n.session != null && sessionLane.has(n.session)) wanted = sessionLane.get(n.session)
+    if (wanted == null) {
+      const parents = incoming.get(n.id).filter((e) => !isBackEdge(e) && lane.has(e.from))
+      const main = parents.find((e) => (e.kind || 'main') === 'main')
+      const via = main || parents[0]
+      wanted = via ? lane.get(via.from) + ((via.kind === 'alt' && !main) ? 1 : 0) : 0
+    }
+    lane.set(n.id, claim(col.get(n.id), wanted))
+  }
+  return nodes.map((n) => ({ id: n.id, col: col.get(n.id), lane: lane.get(n.id) }))
+}