kaloko 0.4.8 → 0.4.10

package/src/lib/keyboard.mjs

@@ -0,0 +1,261 @@
+// Keyboard and screen-reader checks of the a11y pack (#19), measured in the live page after the capture:
+// a Tab walk (focus order, visible focus with contrast, traps, skip link) and accessible names from Chrome's
+// accessibility tree (CDP). The page is left as it was found apart from focus: nothing is clicked or typed.
+import { decodePng } from './png.mjs'
+
+export const KEYBOARD_ASSERTS = new Set(['a11y_focus_order', 'a11y_focus_visible', 'a11y_keyboard_trap', 'a11y_skip_link', 'a11y_ax_names'])
+export const needsKeyboard = (node) => (node?.criteria || []).some((c) => c.check?.type === 'deterministic' && KEYBOARD_ASSERTS.has(c.check.assert))
+
+// In the page: the focused element (through shadow roots), where it is and what it is called.
+function describeFocus () {
+  let el = document.activeElement
+  while (el && el.shadowRoot && el.shadowRoot.activeElement) el = el.shadowRoot.activeElement
+  if (!el || el === document.body || el === document.documentElement) return null
+  const path = (e) => { const p = []; for (; e && e.nodeType === 1; e = e.parentElement || e.getRootNode()?.host) { let i = 1; for (let s = e.previousElementSibling; s; s = s.previousElementSibling) i++; p.unshift(`${e.tagName.toLowerCase()}:${i}`) } return p.join('/') }
+  const clean = (s) => String(s || '').replace(/\s+/g, ' ').trim()
+  const name = clean(el.getAttribute('aria-label') || (el.getAttribute('aria-labelledby') || '').split(/\s+/).filter(Boolean).map((i) => document.getElementById(i)?.innerText || '').join(' ') || el.innerText || el.getAttribute('alt') || el.getAttribute('title') || el.value || el.getAttribute('placeholder') || [...el.querySelectorAll('img[alt]')].map((i) => i.alt).join(' '))
+  const r = el.getBoundingClientRect(); const cs = getComputedStyle(el)
+  let fixed = false
+  for (let e = el; e && e.nodeType === 1; e = e.parentElement) { const p = getComputedStyle(e).position; if (p === 'fixed' || p === 'sticky') { fixed = true; break } }
+  const visible = r.width > 0 && r.height > 0 && cs.visibility !== 'hidden' && Number(cs.opacity) > 0.05 && r.right + scrollX > 0 && r.bottom + scrollY > 0
+  const inView = r.bottom > 0 && r.right > 0 && r.top < innerHeight && r.left < innerWidth
+  let obscured = false
+  if (visible && inView) {
+    const hit = document.elementFromPoint(Math.min(innerWidth - 1, Math.max(0, r.left + r.width / 2)), Math.min(innerHeight - 1, Math.max(0, r.top + r.height / 2)))
+    obscured = !!hit && !(hit === el || el.contains(hit) || hit.contains(el) || (el.labels && [...el.labels].some((l) => l.contains(hit))))
+  }
+  const cls = typeof el.className === 'string' && el.className.trim() ? '.' + el.className.trim().split(/\s+/).slice(0, 2).join('.') : ''
+  return {
+    key: path(el), tag: el.tagName.toLowerCase(), role: el.getAttribute('role') || '', name: name.slice(0, 60), href: el.getAttribute('href'),
+    desc: `${el.tagName.toLowerCase()}${el.id ? '#' + el.id : ''}${cls}`,
+    x: Math.round(r.left + scrollX), y: Math.round(r.top + scrollY), w: Math.round(r.width), h: Math.round(r.height),
+    visible, fixed, obscured, dialog: !!el.closest('dialog[open], [aria-modal=true]'), main: !!el.closest('main, [role=main]'),
+    tabindex: el.getAttribute('tabindex')
+  }
+}
+
+// In the page: focuses the element at the path describeFocus produced, centred in the viewport; its viewport box.
+function focusByPath (key) {
+  let el = document.documentElement
+  for (const part of key.split('/').slice(1)) {
+    const i = Number(part.split(':')[1])
+    const kids = el.shadowRoot && !el.children.length ? el.shadowRoot.children : el.children
+    el = kids[i - 1]
+    if (!el) return null
+  }
+  el.scrollIntoView({ block: 'center', inline: 'nearest' }); el.focus({ preventScroll: true })
+  const r = el.getBoundingClientRect()
+  return { x: r.left, y: r.top, w: r.width, h: r.height, vw: innerWidth, vh: innerHeight }
+}
+
+// In the page: static facts for the order check (positive tabindex, controls taken out of the tab order, click-only).
+function orderFacts () {
+  const visible = (e) => { const r = e.getBoundingClientRect(); const cs = getComputedStyle(e); return r.width > 0 && r.height > 0 && cs.visibility !== 'hidden' && cs.display !== 'none' }
+  const d = (e) => `${e.tagName.toLowerCase()}${e.id ? '#' + e.id : ''}${typeof e.className === 'string' && e.className.trim() ? '.' + e.className.trim().split(/\s+/).slice(0, 2).join('.') : ''}`
+  const pos = [...document.querySelectorAll('[tabindex]')].filter((e) => Number(e.getAttribute('tabindex')) > 0 && visible(e))
+  const removed = [...document.querySelectorAll('a[href][tabindex^="-"], button[tabindex^="-"], input[tabindex^="-"]:not([type=hidden]), select[tabindex^="-"], textarea[tabindex^="-"]')].filter((e) => visible(e) && !e.closest('[aria-hidden=true], [inert]'))
+  const clickOnly = [...document.querySelectorAll('[role=button], [role=link], [role=tab], [role=menuitem], [role=checkbox], [onclick]')].filter((e) => visible(e) && !e.matches('a[href], button, input, select, textarea, summary, [tabindex], [contenteditable=true]') && !e.closest('a[href], button'))
+  const box = (e) => { const r = e.getBoundingClientRect(); return { x: Math.round(r.left + scrollX), y: Math.round(r.top + scrollY), w: Math.round(r.width), h: Math.round(r.height) } }
+  return { positive: pos.slice(0, 5).map(d), positiveCount: pos.length, removed: removed.slice(0, 5).map(d), removedCount: removed.length, clickOnly: clickOnly.slice(0, 5).map(d), clickOnlyCount: clickOnly.length, boxes: [...removed, ...clickOnly].slice(0, 5).map(box), innerHeight }
+}
+
+// In the page: does an in-page link lead to the main content?
+function skipTarget (href) {
+  const id = decodeURIComponent(String(href || '').slice(1))
+  if (!id) return null
+  const t = document.getElementById(id) || document.querySelector(`[name="${CSS.escape(id)}"]`)
+  if (!t) return { exists: false }
+  return { exists: true, main: t.matches('main, [role=main]') || !!t.closest('main, [role=main]') || !!t.querySelector('main, [role=main]') }
+}
+
+const lum = (r, g, b) => { const f = (v) => { v /= 255; return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4 }; return 0.2126 * f(r) + 0.7152 * f(g) + 0.0722 * f(b) }
+
+/**
+ * How visible the focus indicator is: pixels that change between the unfocused and the focused screenshot of the
+ * same area, and how many of them change with at least 3:1 contrast (WCAG 2.4.7 / 2.4.13).
+ * @returns {{ changed: number, strong: number, contrast: number }} contrast: median of the changed pixels
+ */
+export function focusDelta (focusedPng, plainPng) {
+  const a = decodePng(focusedPng); const b = decodePng(plainPng)
+  const w = Math.min(a.width, b.width); const h = Math.min(a.height, b.height)
+  let changed = 0; let strong = 0
+  const ratios = []
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      const i = (y * a.width + x) * 4; const j = (y * b.width + x) * 4
+      const d = Math.abs(a.data[i] - b.data[j]) + Math.abs(a.data[i + 1] - b.data[j + 1]) + Math.abs(a.data[i + 2] - b.data[j + 2])
+      if (d <= 48) continue
+      changed++
+      const l1 = lum(a.data[i], a.data[i + 1], a.data[i + 2]); const l2 = lum(b.data[j], b.data[j + 1], b.data[j + 2])
+      const ratio = (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05)
+      if (ratio >= 3) strong++
+      if (ratios.length < 4000) ratios.push(ratio)
+    }
+  }
+  ratios.sort((p, q) => p - q)
+  return { changed, strong, contrast: ratios.length ? Math.round(ratios[ratios.length >> 1] * 10) / 10 : 1 }
+}
+
+/** Verdict of one focus stop from its delta and size: ok, weak (below 3:1), none (no visible change). */
+export function focusVerdict (delta, w, h) {
+  const perimeter = 2 * (Math.max(1, w) + Math.max(1, h))
+  if (delta.strong >= perimeter * 0.75) return 'ok'
+  if (delta.changed >= perimeter * 0.5) return 'weak'
+  return 'none'
+}
+
+const label = (s) => `${s.desc}${s.name ? ` "${s.name.slice(0, 30)}"` : ''}`
+
+/**
+ * Walks the page with Tab and fills the keyboard criteria of `criteria` ({ id, check }).
+ * opts: maxStops (60), focusChecks (stops checked for a visible indicator, 15), shots (focus screenshots, 5),
+ * saveShot(n, pngBuffer) → relative file path or null.
+ * @returns {{ checks: Record<string, {ok, evidence}>, boxes: Record<string, Array>, keyboard: object }}
+ */
+export async function keyboardChecks (page, criteria, { maxStops = 60, focusChecks = 15, shots = 5, saveShot = null } = {}) {
+  const want = new Map(criteria.filter((c) => c.check.type === 'deterministic' && KEYBOARD_ASSERTS.has(c.check.assert)).map((c) => [c.check.assert, c.id]))
+  const checks = {}; const boxes = {}
+  if (!want.size) return { checks, boxes, keyboard: null }
+  const set = (assert, ok, evidence, list) => { const id = want.get(assert); if (!id) return; checks[id] = { ok, evidence }; if (list?.length) boxes[id] = list.slice(0, 5) }
+  const keyboard = { stops: [], complete: false, total: 0, shots: [] }
+  const tabbing = [...want.keys()].some((a) => a !== 'a11y_ax_names')
+  try {
+    if (tabbing) {
+      // start from the top of the document: a temporary, invisible focus target before everything else
+      await page.evaluate(() => {
+        const a = document.activeElement; if (a && a !== document.body) a.blur()
+        scrollTo(0, 0)
+        const s = document.createElement('span'); s.id = '__kaloko_start'; s.tabIndex = -1; s.style.cssText = 'position:absolute;left:0;top:0;width:0;height:0;overflow:hidden'
+        document.body.prepend(s); s.focus({ preventScroll: true })
+      })
+      const stops = []; const seen = new Map()
+      let trap = null; let iframeRun = 0
+      for (let i = 0; i < maxStops; i++) {
+        await page.keyboard.press('Tab')
+        if (i === 0) await page.evaluate(() => document.getElementById('__kaloko_start')?.remove()).catch(() => {})
+        const f = await page.evaluate(describeFocus).catch(() => null)
+        if (!f) { keyboard.complete = true; break } // focus went back to the browser: the whole page was walked
+        if (stops.length && f.key === stops[0].key) { keyboard.complete = true; break }
+        if (f.tag === 'iframe') { if (stops.at(-1)?.key === f.key) { if (++iframeRun > 30) break; continue } } else iframeRun = 0
+        if (seen.has(f.key)) { const from = seen.get(f.key); const cycle = stops.slice(from); trap = { at: from, size: cycle.length, dialog: cycle.every((s) => s.dialog), first: cycle[0] }; break }
+        seen.set(f.key, stops.length)
+        stops.push(f)
+      }
+      keyboard.total = stops.length
+
+      // order: hidden stops, big jumps back up the page, positive tabindex, controls left out of the tab order
+      if (want.has('a11y_focus_order')) {
+        const facts = await page.evaluate(orderFacts)
+        const hidden = stops.filter((s) => !s.visible)
+        const jumps = []
+        for (let i = 1; i < stops.length; i++) {
+          const a = stops[i - 1]; const b = stops[i]
+          if (a.visible && b.visible && !a.fixed && !b.fixed && b.y + b.h < a.y - facts.innerHeight) jumps.push(`${i}→${i + 1} ${label(b)} jumps ${a.y - b.y} px up`)
+        }
+        const problems = [
+          ...(hidden.length ? [`focus lands on ${hidden.length} invisible element(s): ${hidden.slice(0, 3).map(label).join(', ')}`] : []),
+          ...(jumps.length ? [`order jumps back: ${jumps.slice(0, 2).join('; ')}`] : []),
+          ...(facts.positiveCount ? [`positive tabindex reorders the page: ${facts.positive.join(', ')}`] : []),
+          ...(facts.removedCount ? [`${facts.removedCount} visible control(s) taken out of the tab order: ${facts.removed.join(', ')}`] : []),
+          ...(facts.clickOnlyCount ? [`${facts.clickOnlyCount} control(s) reachable only by mouse: ${facts.clickOnly.join(', ')}`] : [])
+        ]
+        const seq = stops.slice(0, 8).map((s, i) => `${i + 1} ${label(s)}`).join(' → ')
+        set('a11y_focus_order', problems.length === 0, problems.length ? problems.join('; ') : `${stops.length} tab stop(s)${keyboard.complete ? '' : ` (first ${maxStops} checked)`} in reading order: ${seq || 'no focusable elements'}`, [...hidden.filter((s) => s.w && s.h), ...facts.boxes])
+      }
+
+      if (want.has('a11y_keyboard_trap')) {
+        if (trap && !trap.dialog) set('a11y_keyboard_trap', false, `Tab keeps cycling through ${trap.size} element(s) from ${label(trap.first)}; the rest of the page cannot be reached`, stops.slice(trap.at, trap.at + 5))
+        else if (trap) set('a11y_keyboard_trap', true, `an open modal dialog keeps focus inside (${trap.size} element(s)); that is expected while it is open`)
+        else set('a11y_keyboard_trap', true, keyboard.complete ? `Tab goes through all ${stops.length} stop(s) and leaves the page` : `no trap in the first ${stops.length} tab stops`)
+      }
+
+      if (want.has('a11y_skip_link')) {
+        let ok = null; let evidence = 'nothing on the page takes keyboard focus'
+        if (stops.length) {
+          const first = stops.slice(0, 3)
+          let skip = null
+          for (const s of first) {
+            if (!s.href || !s.href.startsWith('#') || s.href.length < 2) continue
+            const t = await page.evaluate(skipTarget, s.href).catch(() => null)
+            if (t?.exists && (t.main || /skip|jump|přeskoč|preskoč|obsah|content|main|hlavní/i.test(s.name))) { skip = { s, t }; break }
+            if (t && !t.exists && /skip|přeskoč|obsah|content|main/i.test(s.name)) { skip = { s, t, broken: true }; break }
+          }
+          const mainAt = stops.findIndex((s) => s.main)
+          if (skip && !skip.broken) { ok = true; evidence = `skip link ${label(skip.s)} → ${skip.s.href}` }
+          else if (skip?.broken) { ok = false; evidence = `skip link ${label(skip.s)} points to ${skip.s.href}, which does not exist` }
+          else if (mainAt >= 0 && mainAt < 3) { ok = true; evidence = `main content is reached at tab stop ${mainAt + 1}; no skip link needed` }
+          else if (mainAt < 0 && !stops.some((s) => s.main)) {
+            const hasMain = await page.evaluate(() => !!document.querySelector('main, [role=main]'))
+            ok = !hasMain && stops.length <= 3 ? true : false
+            evidence = ok ? `only ${stops.length} tab stop(s) on the page` : hasMain ? `no skip link; main content has no focusable element in the first ${stops.length} stops` : 'no skip link and no main landmark to skip to'
+          } else { ok = false; evidence = `no skip link; main content is first reached at tab stop ${mainAt + 1}, after ${mainAt} stop(s) of header and navigation` }
+        }
+        set('a11y_skip_link', ok, evidence)
+      }
+
+      // visible focus: each stop focused and unfocused, the same area compared (keyboard modality stays on)
+      const verdicts = new Map()
+      if (want.has('a11y_focus_visible') || shots > 0) {
+        const candidates = stops.map((s, i) => ({ s, n: i + 1 })).filter(({ s }) => s.visible && s.tag !== 'iframe').slice(0, Math.max(want.has('a11y_focus_visible') ? focusChecks : 0, shots))
+        for (const { s, n } of candidates) {
+          const pos = await page.evaluate(focusByPath, s.key).catch(() => null)
+          if (!pos || !pos.w || !pos.h) continue
+          const clipOf = (pad) => { const x = Math.max(0, Math.floor(pos.x - pad)); const y = Math.max(0, Math.floor(pos.y - pad)); return { x, y, width: Math.max(1, Math.min(pos.vw, Math.ceil(pos.x + pos.w + pad)) - x), height: Math.max(1, Math.min(pos.vh, Math.ceil(pos.y + pos.h + pad)) - y) } }
+          const clip = clipOf(6)
+          if (clip.width < 2 || clip.height < 2) continue
+          const focused = await page.screenshot({ clip, scale: 'css', animations: 'disabled', caret: 'hide' })
+          if (keyboard.shots.length < shots && saveShot) {
+            const file = await saveShot(n, await page.screenshot({ clip: clipOf(48), scale: 'css', animations: 'disabled', caret: 'hide' })).catch(() => null)
+            if (file) keyboard.shots.push({ n, file, name: s.name || s.desc })
+          }
+          if (!want.has('a11y_focus_visible') || verdicts.size >= focusChecks) continue
+          await page.evaluate(() => { let a = document.activeElement; while (a?.shadowRoot?.activeElement) a = a.shadowRoot.activeElement; a?.blur?.() })
+          const plain = await page.screenshot({ clip, scale: 'css', animations: 'disabled', caret: 'hide' })
+          const delta = focusDelta(focused, plain)
+          verdicts.set(n, { v: s.obscured ? 'obscured' : focusVerdict(delta, pos.w, pos.h), contrast: delta.contrast })
+        }
+        if (want.has('a11y_focus_visible')) {
+          const bad = [...verdicts].filter(([, x]) => x.v !== 'ok')
+          const say = ([n, x]) => { const s = stops[n - 1]; return x.v === 'none' ? `${n} ${label(s)}: no visible change on focus` : x.v === 'weak' ? `${n} ${label(s)}: indicator contrast ${x.contrast}:1 (needs 3:1)` : `${n} ${label(s)}: covered by another element when focused` }
+          set('a11y_focus_visible', verdicts.size ? bad.length === 0 : null, !verdicts.size ? 'no visible focus stop to check' : bad.length ? `${bad.length} of ${verdicts.size} focus stop(s) without a clear indicator: ${bad.slice(0, 4).map(say).join('; ')}` : `all ${verdicts.size} checked focus stop(s) show an indicator with at least 3:1 contrast`, bad.map(([n]) => stops[n - 1]))
+        }
+      }
+      keyboard.stops = stops.slice(0, 40).map((s, i) => ({ n: i + 1, x: s.x, y: s.y, w: s.w, h: s.h, name: s.name, el: s.desc, ...(s.visible ? {} : { hidden: true }), ...(verdicts.has(i + 1) ? { focus: verdicts.get(i + 1).v, contrast: verdicts.get(i + 1).contrast } : {}) }))
+      // leave the page as found: nothing focused, at the top
+      await page.evaluate(() => { let a = document.activeElement; while (a?.shadowRoot?.activeElement) a = a.shadowRoot.activeElement; a?.blur?.(); scrollTo(0, 0) }).catch(() => {})
+    }
+    if (want.has('a11y_ax_names')) {
+      const r = await axNames(page)
+      set('a11y_ax_names', r.ok, r.evidence, r.boxes)
+    }
+  } catch (error) {
+    for (const id of want.values()) if (!checks[id]) checks[id] = { ok: null, evidence: `keyboard check error: ${String(error.message).split('\n')[0]}` }
+  }
+  return { checks, boxes, keyboard: tabbing ? keyboard : null }
+}
+
+const INTERACTIVE = new Set(['button', 'link', 'textbox', 'searchbox', 'combobox', 'checkbox', 'radio', 'switch', 'slider', 'spinbutton', 'menuitem', 'menuitemcheckbox', 'menuitemradio', 'tab', 'listbox', 'treeitem'])
+
+/** Interactive nodes of Chrome's accessibility tree without a name (what a screen reader announces). */
+export async function axNames (page) {
+  let cdp
+  try { cdp = await page.context().newCDPSession(page) } catch { return { ok: null, evidence: 'the accessibility tree needs Chrome (CDP)' } }
+  try {
+    const { nodes } = await cdp.send('Accessibility.getFullAXTree')
+    const controls = nodes.filter((n) => !n.ignored && INTERACTIVE.has(n.role?.value))
+    const bad = controls.filter((n) => !String(n.name?.value || '').trim())
+    const boxes = []; const names = []
+    for (const n of bad.slice(0, 5)) {
+      try {
+        const { object } = await cdp.send('DOM.resolveNode', { backendNodeId: n.backendDOMNodeId })
+        const { result } = await cdp.send('Runtime.callFunctionOn', { objectId: object.objectId, returnByValue: true, functionDeclaration: 'function () { const r = this.getBoundingClientRect(); const c = typeof this.className === "string" && this.className.trim() ? "." + this.className.trim().split(/\\s+/).slice(0, 2).join(".") : ""; return { d: this.tagName.toLowerCase() + (this.id ? "#" + this.id : "") + c, x: Math.round(r.left + scrollX), y: Math.round(r.top + scrollY), w: Math.round(r.width), h: Math.round(r.height) } }' })
+        const v = result.value
+        names.push(`${v.d} (${n.role.value})`)
+        if (v.w && v.h) boxes.push({ x: v.x, y: v.y, w: v.w, h: v.h })
+      } catch { names.push(n.role.value) }
+    }
+    return bad.length
+      ? { ok: false, evidence: `${bad.length} of ${controls.length} control(s) have no name in the accessibility tree: ${names.join(', ')}${bad.length > 5 ? ` (+${bad.length - 5})` : ''}`, boxes }
+      : { ok: true, evidence: `all ${controls.length} control(s) in the accessibility tree have a name`, boxes }
+  } finally { await cdp.detach().catch(() => {}) }
+}

package/src/lib/manifest-core.mjs

@@ -38,10 +38,14 @@ export function slimCapture (cap) {
     overflow: cap.overflow || [], meta: cap.meta, mail: cap.mail || null, metadata: cap.metadata || null, ...(cap.view ? { view: cap.view } : {}),
     ...(cap.http_status ? { http_status: cap.http_status } : {}), ...(cap.platform ? { platform: cap.platform, device: cap.device || null } : {}),
     ...(cap.design ? { design: cap.design } : {}), ...(cap.capture ? { capture: cap.capture } : {}),
-    ...(cap.criteria_hash ? { criteria_hash: cap.criteria_hash } : {})
+    ...(cap.criteria_hash ? { criteria_hash: cap.criteria_hash } : {}),
+    ...(cap.ignore?.length ? { ignore: cap.ignore } : {}), ...(cap.unstable ? { unstable: cap.unstable } : {}), ...(cap.keyboard ? { keyboard: cap.keyboard } : {})
   }
 }
 
+/** The keyboard walk of a capture as the canvas draws it: tab stops (numbered boxes) and the focus screenshots. */
+export const keyboardOf = (k) => k ? { complete: !!k.complete, total: k.total ?? (k.stops || []).length, stops: (k.stops || []).slice(0, 40), shots: (k.shots || []).slice(0, 10) } : null
+
 /**
  * One manifest node from its scenario node and captures.
  * captures: [{ locale, viewport, cap (capture record or slimCapture), ev (valid evaluation or null),
@@ -65,11 +69,15 @@ export function assembleNode ({ node, pos, locales, viewportNames, captures, att
       ...(cap.capture && (cap.capture.scale !== 1 || cap.capture.format === 'png' || cap.capture.masked || cap.capture.annotations?.length) ? { quality: cap.capture } : {}), size: [cap.size.width, cap.size.height],
       boxes: cap.boxes, captured_at: cap.captured_at, console_errors: (cap.console_errors || []).length, console: (cap.console_errors || []).slice(0, 20), blocked_list: (cap.blocked_requests || []).slice(0, 20),
       blocked: (cap.blocked_requests || []).length, overflow: (cap.overflow || []).length, meta: cap.meta,
-      mail: cap.mail || null, eval: ev ? c.files.eval : null,
+      mail: cap.mail || null, eval: ev ? c.files.eval : null, ...(c.files.spec ? { spec: c.files.spec } : {}),
       // quick signals from the evaluator (probabilities: purpose met, expected language, looks broken)
       ...(ev?.signals ? { signals: ev.signals } : {}),
       ...(c.live ? { live: c.live } : {}),
-      ...(cap.view?.revision ? { view: cap.view } : {})
+      ...(cap.view?.revision ? { view: cap.view } : {}),
+      // regions left out of pixel diffs (#20), regions that moved between repeated shots, the keyboard walk (#19)
+      ...(cap.ignore?.length ? { ignore: cap.ignore.slice(0, 50) } : {}),
+      ...(cap.unstable?.regions?.length ? { unstable: cap.unstable.regions.slice(0, 50) } : {}),
+      ...(cap.keyboard ? { keyboard: keyboardOf(cap.keyboard) } : {})
     }
     if (ev?.semantic || ev?.jev) semanticByKey[`${c.locale}|${c.viewport}`] = ev.semantic || ev.jev
     if (cap.metadata && !metadata[c.locale]) metadata[c.locale] = cap.metadata
@@ -80,11 +88,14 @@ export function assembleNode ({ node, pos, locales, viewportNames, captures, att
       const loc = (agg.by_locale[c.locale] ||= {})
       const score = r.score ?? r.jev?.noul ?? r.noul ?? null
       // semantic answers carry the thresholds they were judged by and where they were evaluated (own key or Kaloko)
-      loc[c.viewport] = { verdict: r.verdict, evidence: r.evidence, score, note: r.note ?? null, ...(score != null && ev.thresholds ? { th: [ev.thresholds.fail, ev.thresholds.pass] } : {}), ...(r.type === 'semantic' && ev.semantic?.via ? { via: ev.semantic.via } : {}) }
+      // semantic answers carry their one-sentence reason (#17) and whether the evaluator saw the screenshot
+      const seen = r.provider && /-vision$/.test(r.provider)
+      loc[c.viewport] = { verdict: r.verdict, evidence: r.evidence, score, note: r.note ?? null, ...(score != null && ev.thresholds ? { th: [ev.thresholds.fail, ev.thresholds.pass] } : {}), ...(r.type === 'semantic' && (seen ? ev.vision?.via : ev.semantic?.via) ? { via: seen ? ev.vision.via : ev.semantic.via } : {}), ...(r.reason ? { reason: r.reason, ...(r.reason_source === 'model' ? { reason_by: 'model' } : {}) } : {}), ...(seen ? { vision: true, ...(r.text_score != null ? { text_score: r.text_score } : {}) } : {}) }
       if (r.evidence && (!agg.evidence || r.verdict !== 'pass')) agg.evidence = r.evidence
+      if (r.reason && (!agg.reason || (r.verdict !== 'pass' && agg.reason_verdict === 'pass'))) { agg.reason = r.reason; agg.reason_verdict = r.verdict }
     }
   }
-  const criteria = [...perCriterion.values()].map((agg) => {
+  const criteria = [...perCriterion.values()].map(({ reason_verdict: _rv, ...agg }) => {
     for (const l of applicable) for (const vp of viewportNames) ((agg.by_locale[l] ||= {})[vp] ||= { verdict: 'not_reached' })
     const verdicts = applicable.flatMap((l) => viewportNames.map((vp) => agg.by_locale[l][vp].verdict))
     return { ...agg, verdict: aggregate(verdicts) }

package/src/lib/onboarding.mjs

@@ -10,16 +10,23 @@ export const realOrg = (org) => (typeof org === 'string' && /^[a-z0-9][a-z0-9-]{
 /** Address of the organization's sample run on the service. */
 export const sampleUrl = (base, org) => `${String(base).replace(/\/$/, '')}/${org}/sample`
 
-/** Lines printed at the end of `kaloko init`. */
-export function initNextSteps ({ base, org, loggedIn = false }) {
+/**
+ * Lines printed at the end of `kaloko init`. `devServer` ({ command, url }) when init found the app's dev server but it
+ * is not answering yet; `scenario` the path of the first scenario init drafted, which then is the first real flow.
+ */
+export function initNextSteps ({ base, org, loggedIn = false, devServer = null, scenario = null }) {
   const o = realOrg(org)
-  return [
-    'Next:',
-    loggedIn ? '  1. Signed in already (KALOKO_TOKEN found).' : '  1. npx kaloko login   (approve a token in the browser; or put KALOKO_TOKEN from Settings → API tokens into .env)',
-    o ? `  2. Try a review on the sample run: ${sampleUrl(base, o)}` : '  2. Set org: in kaloko.config.yml, then open <service>/<org>/sample to try a review on the sample run.',
-    '  3. Your first real flow: npx kaloko draft <your app URL>   (public pages), or ask your agent:',
-    `     "${FIRST_FLOW_PROMPT}"`
+  const steps = [
+    loggedIn ? 'Signed in already (KALOKO_TOKEN found).' : 'npx kaloko login   (approve a token in the browser; or put KALOKO_TOKEN from Settings → API tokens into .env)'
   ]
+  if (devServer) steps.push(`${devServer.command || 'start your app'}   (the dev server is not answering on ${devServer.url} yet)`)
+  steps.push(o ? `Try a review on the sample run: ${sampleUrl(base, o)}` : 'Set org: in kaloko.config.yml, then open <service>/<org>/sample to try a review on the sample run.')
+  if (scenario) steps.push(`Your first real flow: npx kaloko start --scenario ${scenario} --env local && npx kaloko walk`)
+  else steps.push('Your first real flow: npx kaloko draft <your app URL>   (public pages), or ask your agent:', `   "${FIRST_FLOW_PROMPT}"`)
+  const lines = ['Next:']
+  let n = 0
+  for (const s of steps) lines.push(s.startsWith('   "') ? `  ${s}` : `  ${++n}. ${s}`)
+  return lines
 }
 
 /** Lines printed after a successful `kaloko login`. */

package/src/lib/pack-help.mjs

@@ -25,6 +25,13 @@ export const PACK_HELP = {
   AC305: { cs: 'Text splňuje kontrast WCAG AA', why: ['Low contrast text is hard to read in sunlight and for people with weaker sight.', 'Text s nízkým kontrastem se špatně čte na slunci i lidem se slabším zrakem.'], fix: ['Darken the text or lighten the background to at least 4.5 : 1 (3 : 1 for large text).', 'Ztmavte text nebo zesvětlete pozadí aspoň na 4,5 : 1 (u velkého textu 3 : 1).'] },
   AC306: { cs: 'Stránka má hlavní oblast (main)', why: ['Screen reader users jump straight to <main> to skip the navigation.', 'Uživatelé čteček skáčou rovnou na <main>, aby přeskočili navigaci.'], fix: ['Wrap the main content in <main> (once per page).', 'Hlavní obsah obalte do <main> (jednou na stránce).'] },
   AC307: { cs: 'Id prvků jsou jedinečná', why: ['Duplicate ids break labels, anchors and scripts that look elements up by id.', 'Duplicitní id rozbijí popisky, kotvy i skripty, které prvky hledají podle id.'], fix: ['Rename the repeated ids listed in the evidence (often from a copied component).', 'Přejmenujte opakovaná id z důkazu (často z kopírované komponenty).'] },
+  AC308: { cs: 'Pořadí tabulátoru odpovídá stránce a dojde ke každému prvku', why: ['People who use a keyboard move with Tab; focus that jumps around or skips a button leaves them lost or stuck.', 'Kdo ovládá web klávesnicí, posouvá se tabulátorem; když fokus skáče nebo tlačítko vynechá, ztratí se nebo nemůže dál.'], fix: ['Keep the DOM in reading order, remove positive tabindex, and use real buttons and links instead of clickable divs.', 'Držte DOM v pořadí čtení, odstraňte kladný tabindex a místo klikacích divů použijte skutečná tlačítka a odkazy.'] },
+  AC309: { cs: 'Fokus klávesnice je dobře vidět (kontrast aspoň 3 : 1)', why: ['Without a visible focus ring, keyboard users do not know where they are on the page.', 'Bez viditelného rámečku fokusu uživatel klávesnice neví, kde na stránce je.'], fix: ['Do not remove outline; style :focus-visible with an outline of at least 2 px that contrasts 3 : 1 with its surroundings.', 'Neodstraňujte outline; nastavte :focus-visible s obrysem aspoň 2 px a kontrastem 3 : 1 vůči okolí.'] },
+  AC310: { cs: 'Klávesnice nikde neuvízne', why: ['A widget that keeps Tab inside (an embed, a custom menu) traps keyboard users for good.', 'Prvek, který tabulátor nepustí ven (vložený přehrávač, vlastní menu), uživatele klávesnice uvězní.'], fix: ['Let Tab leave the widget; trap focus only in an open modal dialog that closes with Esc.', 'Nechte tabulátor z prvku odejít; fokus držte jen v otevřeném modálním okně, které zavře Esc.'] },
+  AC311: { cs: 'Odkaz pro přeskočení na obsah nebo rychlá cesta k němu', why: ['Without a skip link, keyboard and screen reader users tab through the whole menu on every page.', 'Bez odkazu „Přeskočit na obsah“ musí uživatelé klávesnice a čteček na každé stránce protabovat celé menu.'], fix: ['Add <a href="#main" class="skip-link">Skip to content</a> as the first element and show it on focus.', 'Jako první prvek přidejte <a href="#main" class="skip-link">Přeskočit na obsah</a> a při fokusu ho zobrazte.'] },
+  AC312: { cs: 'Ovládací prvky mají název ve stromu přístupnosti', why: ['The accessibility tree is what screen readers read; a control without a name there is announced as just "button".', 'Strom přístupnosti je to, co čtečky skutečně čtou; prvek bez názvu ohlásí jen jako „tlačítko“.'], fix: ['Give the control visible text, aria-label or aria-labelledby; check that the label is not hidden with aria-hidden.', 'Dejte prvku viditelný text, aria-label nebo aria-labelledby; ověřte, že popisek neskrývá aria-hidden.'] },
+  AC313: { cs: 'Orientační oblasti jsou úplné a pojmenované', why: ['Screen reader users jump between header, navigation, main and footer; duplicates without names all sound the same.', 'Uživatelé čteček skáčou mezi hlavičkou, navigací, obsahem a patičkou; neoznačené duplicity znějí všechny stejně.'], fix: ['Use one <main>, one page <header> and <footer>, and give repeated <nav> or <aside> an aria-label.', 'Použijte jeden <main>, jednu hlavičku a patičku stránky a opakovaným <nav> či <aside> dejte aria-label.'] },
+  AC314: { cs: 'Role a atributy ARIA jsou platné', why: ['Wrong ARIA is worse than none: screen readers trust it and announce things that are not there.', 'Chybná ARIA je horší než žádná: čtečky jí věří a ohlašují, co na stránce není.'], fix: ['Fix the listed role or attribute, point aria-labelledby to an existing id, and never put aria-hidden on focusable content.', 'Opravte uvedenou roli nebo atribut, aria-labelledby nasměrujte na existující id a aria-hidden nikdy nedávejte na prvky s fokusem.'] },
   AC401: { cs: 'Největší obsah se vykreslí do 2,5 s', why: ['LCP is how long people wait before the page looks ready; Google uses it for ranking.', 'LCP je doba, než stránka působí hotově; Google ho používá při řazení.'], fix: ['Make the hero image smaller (WebP/AVIF, right size), preload it, and cut render-blocking scripts.', 'Zmenšete hlavní obrázek (WebP/AVIF, správná velikost), přednačtěte ho a omezte blokující skripty.'] },
   AC402: { cs: 'Rozvržení se při načítání nehýbe (CLS pod 0,1)', why: ['Content that jumps while loading makes people tap the wrong thing.', 'Obsah, který při načítání poskakuje, svádí k ťuknutí vedle.'], fix: ['Give images and embeds width and height, and reserve space for banners and fonts.', 'Dejte obrázkům a vloženým prvkům šířku a výšku a rezervujte místo pro bannery a písma.'] },
   AC403: { cs: 'Server odpoví do 800 ms', why: ['A slow first byte delays everything else on the page.', 'Pomalý první bajt zdrží všechno ostatní na stránce.'], fix: ['Cache the page (CDN, full-page cache) or speed up the backend work behind it.', 'Stránku kešujte (CDN, cache celé stránky) nebo zrychlete práci backendu za ní.'] },

package/src/lib/packs.mjs

@@ -43,7 +43,7 @@ export const PACKS = {
   },
   a11y: {
     base: 300,
-    title: 'Accessibility basics (WCAG 2.2 AA subset): alt texts, names, labels, headings, contrast, landmarks, unique ids',
+    title: 'Accessibility (WCAG 2.2 AA subset): alt texts, names, labels, headings, contrast, landmarks, unique ids, plus a keyboard walk (tab order, visible focus, traps, skip link) and the accessibility tree (names, landmarks, ARIA)',
     criteria: () => [
       { id: 'AC301', text: 'Images have alternative text', check: det('a11y_images_alt') },
       { id: 'AC302', text: 'Links and buttons have an accessible name', check: det('a11y_names') },
@@ -51,7 +51,14 @@ export const PACKS = {
       { id: 'AC304', text: 'Heading levels are not skipped', check: det('a11y_headings') },
       { id: 'AC305', text: 'Text meets WCAG AA contrast', check: det('a11y_contrast') },
       { id: 'AC306', text: 'The page has a main landmark', check: det('a11y_main') },
-      { id: 'AC307', text: 'Element ids are unique', check: det('a11y_unique_ids') }
+      { id: 'AC307', text: 'Element ids are unique', check: det('a11y_unique_ids') },
+      { id: 'AC308', text: 'Tab order follows the page and reaches every control', check: det('a11y_focus_order') },
+      { id: 'AC309', text: 'Keyboard focus is clearly visible (at least 3:1 contrast)', check: det('a11y_focus_visible') },
+      { id: 'AC310', text: 'No keyboard trap', check: det('a11y_keyboard_trap') },
+      { id: 'AC311', text: 'A skip link or an early way into the main content', check: det('a11y_skip_link') },
+      { id: 'AC312', text: 'Controls have a name in the accessibility tree', check: det('a11y_ax_names') },
+      { id: 'AC313', text: 'Landmarks are complete and labelled', check: det('a11y_landmarks') },
+      { id: 'AC314', text: 'ARIA roles and attributes are valid', check: det('a11y_aria') }
     ]
   },
   perf: {

package/src/lib/png.mjs

@@ -0,0 +1,61 @@
+// Minimal PNG codec (no native dependency): decodes the 8-bit, non-interlaced PNGs that Chrome screenshots are
+// (truecolour, truecolour with alpha, greyscale, palette) into RGBA, and encodes RGBA for tests and crops.
+import { inflateSync, deflateSync, crc32 } from 'node:zlib'
+
+const SIG = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+
+/** @returns {{ width: number, height: number, data: Uint8ClampedArray }} RGBA pixels */
+export function decodePng (buf) {
+  buf = Buffer.from(buf)
+  if (!buf.subarray(0, 8).equals(SIG)) throw new Error('not a PNG')
+  let width = 0; let height = 0; let depth = 0; let type = 0; let interlace = 0; let palette = null; let trns = null
+  const idat = []
+  for (let at = 8; at < buf.length;) {
+    const len = buf.readUInt32BE(at); const kind = buf.toString('latin1', at + 4, at + 8); const data = buf.subarray(at + 8, at + 8 + len)
+    if (kind === 'IHDR') { width = data.readUInt32BE(0); height = data.readUInt32BE(4); depth = data[8]; type = data[9]; interlace = data[12] }
+    else if (kind === 'PLTE') palette = data
+    else if (kind === 'tRNS') trns = data
+    else if (kind === 'IDAT') idat.push(data)
+    else if (kind === 'IEND') break
+    at += 12 + len
+  }
+  if (depth !== 8 || interlace) throw new Error(`unsupported PNG (bit depth ${depth}, interlace ${interlace})`)
+  const channels = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 }[type]
+  if (!channels) throw new Error(`unsupported PNG colour type ${type}`)
+  const raw = inflateSync(Buffer.concat(idat))
+  const stride = width * channels
+  const px = Buffer.alloc(stride * height)
+  for (let y = 0; y < height; y++) {
+    const f = raw[y * (stride + 1)]; const src = y * (stride + 1) + 1; const dst = y * stride
+    for (let x = 0; x < stride; x++) {
+      const a = x >= channels ? px[dst + x - channels] : 0
+      const b = y ? px[dst - stride + x] : 0
+      const c = y && x >= channels ? px[dst - stride + x - channels] : 0
+      let v = raw[src + x]
+      if (f === 1) v += a
+      else if (f === 2) v += b
+      else if (f === 3) v += (a + b) >> 1
+      else if (f === 4) { const p = a + b - c; const pa = Math.abs(p - a); const pb = Math.abs(p - b); const pc = Math.abs(p - c); v += pa <= pb && pa <= pc ? a : pb <= pc ? b : c }
+      px[dst + x] = v & 255
+    }
+  }
+  const data = new Uint8ClampedArray(width * height * 4)
+  for (let i = 0, j = 0; i < width * height; i++, j += channels) {
+    const o = i * 4
+    if (type === 6) { data[o] = px[j]; data[o + 1] = px[j + 1]; data[o + 2] = px[j + 2]; data[o + 3] = px[j + 3] }
+    else if (type === 2) { data[o] = px[j]; data[o + 1] = px[j + 1]; data[o + 2] = px[j + 2]; data[o + 3] = 255 }
+    else if (type === 0 || type === 4) { data[o] = data[o + 1] = data[o + 2] = px[j]; data[o + 3] = type === 4 ? px[j + 1] : 255 }
+    else { const k = px[j] * 3; data[o] = palette[k]; data[o + 1] = palette[k + 1]; data[o + 2] = palette[k + 2]; data[o + 3] = trns && px[j] < trns.length ? trns[px[j]] : 255 }
+  }
+  return { width, height, data }
+}
+
+/** RGBA → PNG (filter 0, colour type 6). */
+export function encodePng ({ width, height, data }) {
+  const stride = width * 4
+  const raw = Buffer.alloc((stride + 1) * height)
+  for (let y = 0; y < height; y++) Buffer.from(data.buffer, data.byteOffset + y * stride, stride).copy(raw, y * (stride + 1) + 1)
+  const chunk = (kind, body) => { const len = Buffer.alloc(4); len.writeUInt32BE(body.length); const td = Buffer.concat([Buffer.from(kind, 'latin1'), body]); const crc = Buffer.alloc(4); crc.writeUInt32BE(crc32(td) >>> 0); return Buffer.concat([len, td, crc]) }
+  const ihdr = Buffer.alloc(13); ihdr.writeUInt32BE(width, 0); ihdr.writeUInt32BE(height, 4); ihdr[8] = 8; ihdr[9] = 6
+  return Buffer.concat([SIG, chunk('IHDR', ihdr), chunk('IDAT', deflateSync(raw)), chunk('IEND', Buffer.alloc(0))])
+}

package/src/lib/pr.mjs

@@ -52,8 +52,11 @@ export function prCommentBody ({ manifest, url, at = new Date() }) {
  * Creates or updates the scenario's comment on the current branch's PR.
  * @returns {{ ok: boolean, action?: 'created'|'updated', url?: string, reason?: string }}
  */
-export async function upsertPrComment ({ manifest, url, cwd, run = defaultRun }) {
-  const view = await run('gh', ['pr', 'view', '--json', 'number,url,headRepository,headRepositoryOwner'], cwd)
+export async function upsertPrComment ({ manifest, url, cwd, run = defaultRun, vars = process.env, fetchImpl = fetch }) {
+  // GitLab merge request pipelines: a note on the merge request through the API
+  if (vars.GITLAB_CI && vars.CI_MERGE_REQUEST_IID) return upsertMrNote({ manifest, url, vars, fetchImpl })
+  // in CI the checkout is often a detached commit: KALOKO_PR (kaloko ci preview-url sets it) names the pull request
+  const view = await run('gh', ['pr', 'view', ...(vars.KALOKO_PR ? [String(vars.KALOKO_PR)] : []), '--json', 'number,url,headRepository,headRepositoryOwner'], cwd)
   if (view == null) return { ok: false, reason: 'gh is not installed, not signed in, or this branch has no pull request' }
   let pr
   try { pr = JSON.parse(view) } catch { return { ok: false, reason: 'gh pr view returned no JSON' } }
@@ -73,6 +76,25 @@ export async function upsertPrComment ({ manifest, url, cwd, run = defaultRun })
   return r == null ? { ok: false, reason: 'could not create the comment' } : { ok: true, action: 'created', url: r.trim() || pr.url }
 }
 
+/** One note per scenario on a GitLab merge request (KALOKO_GITLAB_TOKEN: a project access token with the api scope). */
+export async function upsertMrNote ({ manifest, url, vars = process.env, fetchImpl = fetch }) {
+  const token = vars.KALOKO_GITLAB_TOKEN || vars.GITLAB_TOKEN
+  if (!token) return { ok: false, reason: 'set KALOKO_GITLAB_TOKEN (a project access token with the api scope) to comment on the merge request' }
+  const notes = `${vars.CI_API_V4_URL}/projects/${encodeURIComponent(vars.CI_PROJECT_ID)}/merge_requests/${vars.CI_MERGE_REQUEST_IID}/notes`
+  const headers = { 'PRIVATE-TOKEN': token, 'Content-Type': 'application/json' }
+  const body = prCommentBody({ manifest, url })
+  const link = (id) => `${vars.CI_MERGE_REQUEST_PROJECT_URL || vars.CI_PROJECT_URL}/-/merge_requests/${vars.CI_MERGE_REQUEST_IID}#note_${id}`
+  try {
+    const list = await fetchImpl(`${notes}?per_page=100&sort=desc`, { headers })
+    if (!list.ok) return { ok: false, reason: `GitLab answered ${list.status} listing notes` }
+    const mine = (await list.json()).find((n) => String(n.body || '').includes(marker(manifest.scenario.id)))
+    const res = await fetchImpl(mine ? `${notes}/${mine.id}` : notes, { method: mine ? 'PUT' : 'POST', headers, body: JSON.stringify({ body }) })
+    if (!res.ok) return { ok: false, reason: `GitLab answered ${res.status}` }
+    const note = await res.json()
+    return { ok: true, action: mine ? 'updated' : 'created', url: link(note.id || mine?.id) }
+  } catch (e) { return { ok: false, reason: e.message } }
+}
+
 async function defaultRun (cmd, args, cwd) {
   try { const { stdout } = await exec(cmd, args, { cwd, timeout: 30000, maxBuffer: 4 * 1024 * 1024 }); return stdout } catch { return null }
 }

package/src/lib/probe.mjs

@@ -195,6 +195,63 @@ export function probe ({ checks = [], highlights = [], scopes = [], maxChars = 9
       }
       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` }
     }
+    if (kind === 'landmarks') {
+      // landmark structure as a screen reader lists it: one main, one top-level banner and contentinfo, repeated
+      // landmarks told apart by a label
+      const roleOf = (e) => {
+        const r = e.getAttribute('role'); if (r) return ['banner', 'navigation', 'main', 'contentinfo', 'complementary', 'search', 'form', 'region'].includes(r) ? r : null
+        const t = e.tagName
+        if (t === 'MAIN') return 'main'; if (t === 'NAV') return 'navigation'; if (t === 'ASIDE') return 'complementary'; if (t === 'SEARCH') return 'search'
+        // header/footer are banner/contentinfo only outside article, aside, main, nav and section
+        if (t === 'HEADER' || t === 'FOOTER') return e.parentElement?.closest('article, aside, main, nav, section') ? null : t === 'HEADER' ? 'banner' : 'contentinfo'
+        if ((t === 'SECTION' || t === 'FORM') && (e.getAttribute('aria-label') || e.getAttribute('aria-labelledby'))) return t === 'FORM' ? 'form' : 'region'
+        return null
+      }
+      const all = [...document.querySelectorAll('main, nav, aside, header, footer, search, section, form, [role]')].filter((e) => !e.closest('[aria-hidden=true]') && visible(e)).map((e) => ({ e, role: roleOf(e) })).filter((x) => x.role)
+      const by = {}; for (const x of all) (by[x.role] ||= []).push(x.e)
+      const bad = []
+      if (!by.main) bad.push('no main landmark')
+      else if (by.main.length > 1) bad.push(`${by.main.length} main landmarks`)
+      for (const r of ['banner', 'contentinfo']) if ((by[r] || []).length > 1) bad.push(`${by[r].length} ${r} landmarks`)
+      for (const [r, list] of Object.entries(by)) {
+        if (list.length < 2 || r === 'main') continue
+        const labels = list.map((e) => clean(e.getAttribute('aria-label') || (e.getAttribute('aria-labelledby') || '').split(/\s+/).map((i) => document.getElementById(i)?.innerText || '').join(' ')))
+        if (labels.some((l) => !l) || new Set(labels).size < labels.length) bad.push(`${list.length} ${r} landmarks without distinct labels (aria-label)`)
+      }
+      const summary = Object.entries(by).map(([r, list]) => `${r}${list.length > 1 ? ` ×${list.length}` : ''}`).join(', ')
+      return { ok: bad.length === 0, evidence: bad.length ? `${bad.join('; ')} (landmarks: ${summary || 'none'})` : `landmarks: ${summary}` }
+    }
+    if (kind === 'aria') {
+      // ARIA that misleads a screen reader: unknown roles, misspelt attributes, references to missing ids, hidden
+      // focusable content, boolean attributes with other values
+      const ROLES = 'alert alertdialog application article banner blockquote button caption cell checkbox code columnheader combobox complementary contentinfo definition deletion dialog directory document emphasis feed figure form generic grid gridcell group heading img insertion link list listbox listitem log main marquee math meter menu menubar menuitem menuitemcheckbox menuitemradio navigation none note option paragraph presentation progressbar radio radiogroup region row rowgroup rowheader scrollbar search searchbox separator slider spinbutton status strong subscript superscript switch tab table tablist tabpanel term textbox time timer toolbar tooltip tree treegrid treeitem doc-abstract doc-acknowledgments doc-afterword doc-appendix doc-backlink doc-biblioentry doc-bibliography doc-biblioref doc-chapter doc-colophon doc-conclusion doc-cover doc-credit doc-credits doc-dedication doc-endnote doc-endnotes doc-epigraph doc-epilogue doc-errata doc-example doc-footnote doc-foreword doc-glossary doc-glossref doc-index doc-introduction doc-noteref doc-notice doc-pagebreak doc-pagelist doc-part doc-preface doc-prologue doc-pullquote doc-qna doc-subtitle doc-tip doc-toc graphics-document graphics-object graphics-symbol'.split(' ')
+      const ATTRS = 'activedescendant atomic autocomplete braillelabel brailleroledescription busy checked colcount colindex colindextext colspan controls current describedby description details disabled dropeffect errormessage expanded flowto grabbed haspopup hidden invalid keyshortcuts label labelledby level live modal multiline multiselectable orientation owns placeholder posinset pressed readonly relevant required roledescription rowcount rowindex rowindextext rowspan selected setsize sort valuemax valuemin valuenow valuetext'.split(' ')
+      const BOOL = ['atomic', 'busy', 'disabled', 'hidden', 'modal', 'multiline', 'multiselectable', 'readonly', 'required']
+      const TRI = { expanded: ['true', 'false', 'undefined'], selected: ['true', 'false', 'undefined'], checked: ['true', 'false', 'mixed', 'undefined'], pressed: ['true', 'false', 'mixed', 'undefined'] }
+      // rendered on screen, whatever aria-hidden says (visible() treats aria-hidden content as gone)
+      const rendered = (e) => typeof e.checkVisibility === 'function' ? e.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true }) : getComputedStyle(e).display !== 'none'
+      const REFS = ['labelledby', 'describedby', 'controls', 'owns', 'activedescendant', 'errormessage', 'flowto', 'details']
+      const FOCUSABLE = 'a[href], button:not([disabled]), input:not([disabled]):not([type=hidden]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex^="-"]), [contenteditable=true]'
+      const issues = []
+      const add = (e, text) => { if (issues.length < 40) issues.push(`${describe(e)}: ${text}`) }
+      for (const e of document.querySelectorAll('body [role], body *')) {
+        if (issues.length >= 40) break
+        const role = e.getAttribute('role')
+        if (role != null && role.trim() && !role.trim().split(/\s+/).some((r) => ROLES.includes(r))) add(e, `unknown role "${role}"`)
+        for (const a of e.attributes) {
+          if (!a.name.startsWith('aria-')) continue
+          const n = a.name.slice(5)
+          if (!ATTRS.includes(n)) { add(e, `unknown attribute ${a.name}`); continue }
+          if (BOOL.includes(n) && !['true', 'false', ''].includes(a.value.trim())) add(e, `${a.name}="${a.value}" (true or false)`)
+          if (TRI[n] && a.value.trim() && !TRI[n].includes(a.value.trim())) add(e, `${a.name}="${a.value}" (${TRI[n].join(', ')})`)
+          if (REFS.includes(n)) { const missing = a.value.split(/\s+/).filter(Boolean).filter((i) => !document.getElementById(i)); if (missing.length) add(e, `${a.name} points to missing id ${missing.slice(0, 2).map((i) => '#' + i).join(', ')}`) }
+        }
+        if (e.getAttribute('aria-hidden') === 'true' && rendered(e)) { const f = e.matches(FOCUSABLE) ? e : e.querySelector(FOCUSABLE); if (f && rendered(f) && !f.closest('[inert]')) add(e, `aria-hidden="true" hides focusable ${describe(f)} from screen readers`) }
+        if (/^(presentation|none)$/.test(role || '') && e.matches(FOCUSABLE)) add(e, `role="${role}" on a focusable element`)
+      }
+      const shown = [...new Set(issues)]
+      return { ok: shown.length === 0, evidence: shown.length ? `${shown.length} ARIA problem(s): ${shown.slice(0, 5).join('; ')}` : 'roles and aria-* attributes are valid' }
+    }
     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 } }

package/src/lib/recheck.mjs

@@ -12,8 +12,10 @@ import { probeArgs } from './capture.mjs'
 import { contextOptions, prepareContext } from './access.mjs'
 import { launchEphemeral } from './browser.mjs'
 import { treeChecks } from './apps/tree.mjs'
+import { KEYBOARD_ASSERTS } from './keyboard.mjs'
 
-export const LIVE_ONLY = (assert) => assert === 'no_console_errors' || assert === 'no_overflow' || assert === 'http_status' || assert === 'links_ok' || assert === 'hreflang_pairs' || /^perf_/.test(assert)
+// keyboard walk and accessibility tree (#19) need the live page too
+export const LIVE_ONLY = (assert) => assert === 'no_console_errors' || assert === 'no_overflow' || assert === 'http_status' || assert === 'links_ok' || assert === 'hreflang_pairs' || /^perf_/.test(assert) || KEYBOARD_ASSERTS.has(assert)
 
 const withBase = (html, url) => {
   if (!url || /<base\s/i.test(html)) return html

package/src/lib/scenario.mjs

@@ -31,7 +31,8 @@ export function validateScenario (data) {
     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`)
+    // a manual screen may have no path: a person (or an imported walkthrough) shows how to get there
+    if (node.kind === 'screen' && !node.path && (!data.platform || data.platform === 'web') && node.execution?.strategy !== 'manual') 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`)
   }