kaloko 0.4.8 → 0.4.9

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/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/spec-cli.mjs

@@ -0,0 +1,90 @@
+// `kaloko spec` and `kaloko drift` (#42 Dev mode for agents): what to build for a step as it was approved, and how
+// an implementation run differs from it, in the same vocabulary (elements by role and name, styles → DTCG tokens,
+// interaction states). The spec comes from the service (design reference, draft, a version or a shared run) or from
+// a local run's captures; drift compares the local implementation run with the reference from the service.
+import { join } from 'node:path'
+import { readJson, UserError } from './util.mjs'
+import { readCaptures } from './run.mjs'
+import { latestCaptures } from './evaluate.mjs'
+import { specText, specDrift, driftText } from './devspec.mjs'
+
+const enc = encodeURIComponent
+
+/** The local run's specs: [{ node, locale, viewport, spec }] (newest capture of each). */
+export async function localSpecs (run, { step, locale, viewport } = {}) {
+  const out = []
+  for (const c of latestCaptures(await readCaptures(run.dir))) {
+    if (c.item || (step && c.node !== step) || (locale && c.locale !== locale) || (viewport && c.viewport !== viewport)) continue
+    const rec = await readJson(join(run.dir, c.file), null)
+    out.push({ node: c.node, locale: c.locale, viewport: c.viewport, spec: rec?.spec || null })
+  }
+  return out
+}
+
+const pickOne = (list, viewport) => list.find((x) => x.viewport === viewport) || list.find((x) => x.viewport === 'desktop') || list[0]
+
+export async function specCmd ({ config, client, run, scenario, scenarioId, args, say }) {
+  const step = typeof args._[0] === 'string' ? args._[0] : typeof args.step === 'string' ? args.step : null
+  const locale = typeof args.locale === 'string' ? args.locale : null
+  const viewport = typeof args.viewport === 'string' ? args.viewport : null
+  const steps = step ? [step] : (scenario?.nodes || []).filter((n) => n.kind !== 'decision' && n.kind !== 'external').map((n) => n.id)
+  if (!steps.length) throw new UserError('Usage: kaloko spec <step> [--ref design|draft|vN|<run id>] [--locale l] [--viewport v] [--local] [--json]')
+  const out = []
+  for (const s of steps) {
+    if (args.local || !client) {
+      if (!run) throw new UserError('--local needs a run: pass --run <id> or start one.')
+      const list = (await localSpecs(run, { step: s, locale, viewport })).filter((x) => locale || x.locale === (run.meta.scope?.locales?.[0] || x.locale))
+      const one = pickOne(list, viewport)
+      if (!one) continue
+      out.push({ node: s, locale: one.locale, viewport: one.viewport, ref: 'local', spec: one.spec })
+    } else {
+      const ref = typeof args.ref === 'string' ? args.ref : typeof args.version === 'string' || typeof args.version === 'number' ? `v${args.version}` : 'design'
+      const q = new URLSearchParams(Object.entries({ ref, locale, viewport }).filter(([, v]) => v))
+      try {
+        const d = await client.request('GET', `/orgs/${config.org}/scenarios/${enc(scenarioId)}/steps/${enc(s)}/spec?${q}`)
+        out.push({ node: s, locale: d.locale, viewport: d.viewport, ref: d.ref, spec: d.spec })
+      } catch (e) { if (step) throw e; out.push({ node: s, error: e.message.split('\n')[0] }) }
+    }
+  }
+  if (args.json) { say(JSON.stringify(step ? out[0] || null : out, null, 2)); return }
+  if (!out.length) throw new UserError(`No capture of ${step || 'any step'} in this run.`)
+  say(out.map((o) => o.error ? `${o.node}: ${o.error}` : specText(o.spec, { title: `${o.node} · ${o.locale} · ${o.viewport} · ${o.ref}` })).join('\n\n'))
+}
+
+/**
+ * Drift of the local implementation run (or, with --remote, a shared run) from the approved design. Exit code 1
+ * when anything differs, so an agent can loop: implement → walk → drift → fix.
+ */
+export async function driftCmd ({ config, client, run, scenarioId, args, say }) {
+  const step = typeof args._[0] === 'string' ? args._[0] : typeof args.step === 'string' ? args.step : null
+  const ref = typeof args.ref === 'string' ? args.ref : typeof args.version === 'string' || typeof args.version === 'number' ? `v${args.version}` : 'design'
+  const locale = typeof args.locale === 'string' ? args.locale : null
+  const viewport = typeof args.viewport === 'string' ? args.viewport : null
+  if (!client) throw new UserError('kaloko drift compares with the approved design on the service: set org and a token (kaloko login).')
+  const results = []
+  if (args.remote) {
+    if (!step) throw new UserError('Usage: kaloko drift <step> --remote <run id|latest>')
+    const q = new URLSearchParams(Object.entries({ run: typeof args.remote === 'string' ? args.remote : 'latest', ref, locale, viewport }).filter(([, v]) => v))
+    const d = await client.request('GET', `/orgs/${config.org}/scenarios/${enc(scenarioId)}/steps/${enc(step)}/drift?${q}`)
+    results.push({ node: step, locale: d.locale, viewport: d.viewport, ref: d.ref, findings: d.findings, text: d.text })
+  } else {
+    if (!run) throw new UserError('No implementation run here: walk the scenario first (packs: [design] on the steps), or pass --remote <run id>.')
+    if (run.meta.environment?.kind === 'design') throw new UserError('This is a design run; drift compares an implementation run with the design. Pass --run <implementation run>.')
+    const git = run.meta.git?.branch
+    const mine = (await localSpecs(run, { step, locale, viewport }))
+    if (!mine.length) throw new UserError(`No capture${step ? ` of ${step}` : ''} in run ${run.meta.id}.`)
+    for (const m of mine) {
+      if (!m.spec) { results.push({ node: m.node, locale: m.locale, viewport: m.viewport, note: 'no spec in this capture: add packs: [design] to the step and walk again' }); continue }
+      const q = new URLSearchParams(Object.entries({ ref, locale: m.locale, viewport: m.viewport, git }).filter(([, v]) => v))
+      let d
+      try { d = await client.request('GET', `/orgs/${config.org}/scenarios/${enc(scenarioId)}/steps/${enc(m.node)}/spec?${q}`) } catch (e) { results.push({ node: m.node, locale: m.locale, viewport: m.viewport, note: e.message.split('\n')[0] }); continue }
+      if (!d.spec) { results.push({ node: m.node, locale: m.locale, viewport: m.viewport, note: 'the design has no spec for this step yet (walk and sync the design with the current CLI)' }); continue }
+      const findings = specDrift(m.spec, d.spec)
+      results.push({ node: m.node, locale: m.locale, viewport: m.viewport, ref: d.ref, findings, text: driftText(findings, { title: `${m.node} · ${m.locale} · ${m.viewport} vs ${d.ref}` }) })
+    }
+  }
+  const differing = results.filter((r) => r.findings?.length).length
+  if (args.json) say(JSON.stringify(results.map(({ text, ...r }) => r), null, 2))
+  else say(results.map((r) => r.text || `${r.node} · ${r.locale} · ${r.viewport}: ${r.note}`).join('\n\n') + `\n\n${differing ? `${differing} of ${results.length} capture(s) differ from the approved design.` : `${results.filter((r) => r.findings).length} capture(s) match the approved design.`}`)
+  if (differing) process.exitCode = 1
+}

package/src/lib/stability-core.mjs

@@ -0,0 +1,114 @@
+// Unstable regions (#20): parts of a screen that change between captures of the same state (clocks, ads,
+// carousels, avatars, "3 minutes ago"). Pure functions without Node APIs: `unstableRegions` also runs inside a
+// browser page (the CLI injects its source to compare WebP captures there), so it must stay self-contained.
+
+/**
+ * Regions that differ in most consecutive pairs of `images` (RGBA arrays of the same width × height).
+ * The images are split into cells; a cell changes in a pair when at least `cellFill` of its pixels differ by more
+ * than `threshold` (sum of RGB differences, the canvas diff's rule). A cell is unstable when it changed in at least
+ * `minShare` of the pairs. Neighbouring unstable cells (gap up to `gap` cells) become one rectangle.
+ * When more than `maxArea` of the screen is unstable the page itself changed: no regions are suggested.
+ * @returns {{ regions: Array<{x:number,y:number,w:number,h:number,share:number}>, changed: number, pairs: number, too_much?: boolean }}
+ */
+export function unstableRegions ({ images, width, height, threshold = 48, cell = 8, cellFill = 0.02, minShare = 0.66, gap = 2, pad = 4, maxArea = 0.35, minCells = 2 }) {
+  const pairs = images.length - 1
+  if (pairs < 1 || !width || !height) return { regions: [], changed: 0, pairs: Math.max(0, pairs) }
+  const cw = Math.ceil(width / cell); const ch = Math.ceil(height / cell)
+  const hits = new Uint16Array(cw * ch)
+  const count = new Uint32Array(cw * ch)
+  for (let p = 0; p < pairs; p++) {
+    const a = images[p]; const b = images[p + 1]
+    count.fill(0)
+    for (let y = 0; y < height; y++) {
+      const row = (y / cell | 0) * cw
+      for (let x = 0; x < width; x++) {
+        const i = (y * width + x) * 4
+        if (Math.abs(a[i] - b[i]) + Math.abs(a[i + 1] - b[i + 1]) + Math.abs(a[i + 2] - b[i + 2]) > threshold) count[row + (x / cell | 0)]++
+      }
+    }
+    for (let c = 0; c < count.length; c++) {
+      const cx = c % cw; const cy = (c / cw) | 0
+      const area = (Math.min(cell, width - cx * cell)) * (Math.min(cell, height - cy * cell))
+      if (count[c] >= Math.max(1, area * cellFill)) hits[c]++
+    }
+  }
+  const flagged = new Uint8Array(cw * ch)
+  let total = 0
+  for (let c = 0; c < hits.length; c++) if (hits[c] / pairs >= minShare) { flagged[c] = 1; total++ }
+  const changed = total / (cw * ch)
+  if (changed > maxArea) return { regions: [], changed, pairs, too_much: true }
+  // connected components over flagged cells, bridging gaps of up to `gap` cells
+  const label = new Int32Array(cw * ch).fill(-1)
+  const boxes = []
+  for (let c = 0; c < flagged.length; c++) {
+    if (!flagged[c] || label[c] >= 0) continue
+    const box = { x0: c % cw, y0: (c / cw) | 0, x1: c % cw, y1: (c / cw) | 0, cells: 0, hits: 0 }
+    const stack = [c]; label[c] = boxes.length
+    while (stack.length) {
+      const k = stack.pop(); const kx = k % cw; const ky = (k / cw) | 0
+      box.cells++; box.hits += hits[k]
+      if (kx < box.x0) box.x0 = kx; if (kx > box.x1) box.x1 = kx; if (ky < box.y0) box.y0 = ky; if (ky > box.y1) box.y1 = ky
+      for (let dy = -gap - 1; dy <= gap + 1; dy++) {
+        for (let dx = -gap - 1; dx <= gap + 1; dx++) {
+          const nx = kx + dx; const ny = ky + dy
+          if (nx < 0 || ny < 0 || nx >= cw || ny >= ch) continue
+          const n = ny * cw + nx
+          if (flagged[n] && label[n] < 0) { label[n] = boxes.length; stack.push(n) }
+        }
+      }
+    }
+    boxes.push(box)
+  }
+  const regions = boxes.filter((b) => b.cells >= minCells).map((b) => {
+    const x = Math.max(0, b.x0 * cell - pad); const y = Math.max(0, b.y0 * cell - pad)
+    return { x, y, w: Math.min(width, (b.x1 + 1) * cell + pad) - x, h: Math.min(height, (b.y1 + 1) * cell + pad) - y, share: Math.round((b.hits / b.cells / pairs) * 100) / 100 }
+  })
+  return { regions: mergeRects(regions), changed, pairs }
+}
+
+/** Merges overlapping rectangles ({x,y,w,h}); keeps the highest share. */
+export function mergeRects (rects, slack = 0) {
+  const out = rects.map((r) => ({ ...r }))
+  for (let merged = true; merged;) {
+    merged = false
+    for (let i = 0; i < out.length && !merged; i++) {
+      for (let j = i + 1; j < out.length; j++) {
+        const a = out[i]; const b = out[j]
+        if (a.x - slack <= b.x + b.w && b.x - slack <= a.x + a.w && a.y - slack <= b.y + b.h && b.y - slack <= a.y + a.h) {
+          const x = Math.min(a.x, b.x); const y = Math.min(a.y, b.y)
+          out[i] = { ...a, x, y, w: Math.max(a.x + a.w, b.x + b.w) - x, h: Math.max(a.y + a.h, b.y + b.h) - y, ...(a.share != null || b.share != null ? { share: Math.max(a.share ?? 0, b.share ?? 0) } : {}) }
+          out.splice(j, 1); merged = true; break
+        }
+      }
+    }
+  }
+  return out
+}
+
+/**
+ * The ignore entries of a step that apply to one locale and viewport. Scenario form:
+ * ignore: [{ selector: '.clock' }, { rect: [x, y, w, h], viewport: desktop }, { selector: '#ad', locales: [cs] }]
+ */
+export function ignoreFor (node, locale, viewport) {
+  return (Array.isArray(node?.ignore) ? node.ignore : []).filter((e) => {
+    if (!e || typeof e !== 'object') return false
+    if (e.viewport && e.viewport !== viewport) return false
+    if (Array.isArray(e.viewports) && e.viewports.length && !e.viewports.includes(viewport)) return false
+    if (Array.isArray(e.locales) && e.locales.length && !e.locales.includes(locale)) return false
+    return !!(e.selector || (Array.isArray(e.rect) && e.rect.length === 4))
+  })
+}
+
+/** Is pixel (x, y) (CSS px of the page) inside one of the rectangles? For diff loops, prefer `ignoreMask`. */
+export const inRects = (rects, x, y) => rects.some((r) => x >= r.x && x < r.x + r.w && y >= r.y && y < r.y + r.h)
+
+/** A W × H mask (1 = ignored) from rectangles in CSS px scaled by k (diff width / page width). */
+export function ignoreMask (rects, W, H, k = 1) {
+  const m = new Uint8Array(W * H)
+  for (const r of rects || []) {
+    const x0 = Math.max(0, Math.floor(r.x * k)); const y0 = Math.max(0, Math.floor(r.y * k))
+    const x1 = Math.min(W, Math.ceil((r.x + r.w) * k)); const y1 = Math.min(H, Math.ceil((r.y + r.h) * k))
+    for (let y = y0; y < y1; y++) m.fill(1, y * W + x0, y * W + x1)
+  }
+  return m
+}

package/src/lib/stability.mjs

@@ -0,0 +1,249 @@
+// Auto-detected unstable regions (#20). Two sources:
+//  - repeated screenshots of one capture (`kaloko walk --stability N`): what moves while nobody touches the page
+//    (clocks, carousels, animations) lands in the capture record as `unstable`;
+//  - earlier local runs of the same scenario and environment (`kaloko stability`): what differs on every load
+//    (ads, avatars, "3 minutes ago").
+// `kaloko stability` turns both into ignore suggestions per step (`ignore: [{ selector } | { rect, viewport }]`),
+// written next to the run and, with --apply, into the scenario. Pixel diffs on the canvas and the design pixel
+// check skip ignored regions.
+import { readFile, writeFile, readdir } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+import yaml from 'js-yaml'
+import { readJson, writeJson, UserError } from './util.mjs'
+import { readCaptures } from './run.mjs'
+import { latestCaptures } from './evaluate.mjs'
+import { decodePng } from './png.mjs'
+import { unstableRegions, mergeRects, ignoreFor } from './stability-core.mjs'
+
+const MAX_HEIGHT = 12000
+
+/** Copies the top-left width × height of an RGBA image. */
+function cropRgba (img, width, height) {
+  if (img.width === width) return img.data.subarray(0, width * height * 4)
+  const out = new Uint8ClampedArray(width * height * 4)
+  for (let y = 0; y < height; y++) out.set(img.data.subarray(y * img.width * 4, y * img.width * 4 + width * 4), y * width * 4)
+  return out
+}
+
+/** Regions that change while the page sits still: `n` screenshots `delay` ms apart (CSS pixels). */
+export async function repeatRegions (page, { n = 3, delay = 800, fullPage = true } = {}) {
+  const shots = []
+  for (let i = 0; i < n; i++) {
+    if (i) await page.waitForTimeout(delay)
+    shots.push(decodePng(await page.screenshot({ fullPage, scale: 'css', animations: 'allow' })))
+  }
+  const width = Math.min(...shots.map((s) => s.width)); const height = Math.min(MAX_HEIGHT, ...shots.map((s) => s.height))
+  const r = unstableRegions({ images: shots.map((s) => cropRgba(s, width, height)), width, height })
+  return { shots: n, regions: r.regions, ...(r.too_much ? { too_much: Math.round(r.changed * 100) / 100 } : {}) }
+}
+
+/** Ignore regions of one capture as page rectangles (CSS px): selectors resolved in the live page, rects as given. */
+export async function resolveIgnore (page, node, locale, viewport) {
+  const entries = ignoreFor(node, locale, viewport)
+  if (!entries.length) return []
+  const sels = entries.filter((e) => e.selector).map((e) => e.selector)
+  const found = sels.length ? await page.evaluate((list) => list.flatMap((sel) => {
+    let els = []
+    try { els = [...document.querySelectorAll(sel)] } catch { return [] }
+    return els.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), selector: sel } }).filter((r) => r.w > 0 && r.h > 0).slice(0, 20)
+  }), sels).catch(() => []) : []
+  return [...found, ...entries.filter((e) => e.rect).map((e) => ({ x: e.rect[0], y: e.rect[1], w: e.rect[2], h: e.rect[3] }))]
+}
+
+/** Local runs of the scenario and environment of `run`, newest first (meta and directory). */
+export async function siblingRuns ({ root, config, run, sameCommit = false }) {
+  const base = resolve(root, config.output)
+  let names = []
+  try { names = (await readdir(base, { withFileTypes: true })).filter((e) => e.isDirectory() && !e.name.startsWith('.')).map((e) => e.name) } catch { return [] }
+  const out = []
+  for (const name of names) {
+    const meta = await readJson(join(base, name, 'meta.json'), null)
+    if (!meta || meta.id === run.meta.id || meta.scenario?.id !== run.meta.scenario?.id || meta.environment?.name !== run.meta.environment?.name) continue
+    if (sameCommit && (meta.git?.commit || null) !== (run.meta.git?.commit || null)) continue
+    out.push({ dir: join(base, name), meta })
+  }
+  return out.sort((a, b) => String(b.meta.started_at).localeCompare(String(a.meta.started_at)))
+}
+
+const key = (e) => `${e.node}|${e.locale}|${e.viewport}`
+
+// the self-contained detector, injected into a blank page to compare WebP captures there
+const DETECTOR = `window.__mergeRects = ${mergeRects.toString()}; const mergeRects = window.__mergeRects; window.__unstableRegions = ${unstableRegions.toString()};`
+
+/** Cross-run regions of one step, locale and viewport: images drawn at the page's CSS width. */
+async function crossRegions (page, sources, cssWidth) {
+  return page.evaluate(async ({ sources, W, MAX }) => {
+    const load = (src) => new Promise((ok, no) => { const i = new Image(); i.onload = () => ok(i); i.onerror = no; i.src = src })
+    const imgs = await Promise.all(sources.map(load))
+    const H = Math.min(MAX, ...imgs.map((i) => Math.round(i.naturalHeight * W / i.naturalWidth)))
+    const data = imgs.map((img) => { const c = document.createElement('canvas'); c.width = W; c.height = H; const g = c.getContext('2d', { willReadFrequently: true }); g.drawImage(img, 0, 0, W, Math.round(img.naturalHeight * W / img.naturalWidth)); return g.getImageData(0, 0, W, H).data })
+    return window.__unstableRegions({ images: data, width: W, height: H })
+  }, { sources, W: cssWidth, MAX: MAX_HEIGHT })
+}
+
+const dataUrl = async (file) => `data:image/${file.endsWith('.png') ? 'png' : 'webp'};base64,${(await readFile(file)).toString('base64')}`
+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
+}
+
+/** A stable CSS selector for the element that covers a region in the stored HTML, or null (runs in the page). */
+function selectorAt (r) {
+  const cx = r.x + r.w / 2; const cy = r.y + r.h / 2
+  window.scrollTo(0, Math.max(0, cy - innerHeight / 2))
+  const hit = document.elementFromPoint(cx - scrollX, cy - scrollY)
+  const fit = (e) => {
+    const b = e.getBoundingClientRect(); const x = b.left + scrollX; const y = b.top + scrollY
+    const ix = Math.max(0, Math.min(x + b.width, r.x + r.w) - Math.max(x, r.x)); const iy = Math.max(0, Math.min(y + b.height, r.y + r.h) - Math.max(y, r.y))
+    return { covers: (ix * iy) / (r.w * r.h), ratio: (b.width * b.height) / (r.w * r.h) }
+  }
+  let best = null
+  for (let e = hit; e && e !== document.body && e !== document.documentElement; e = e.parentElement) {
+    const f = fit(e)
+    if (f.ratio > 6) break
+    if (f.covers >= 0.7) { best = e; break }
+  }
+  if (!best) return null
+  const esc = (s) => CSS.escape(s)
+  const unique = (s) => { try { return document.querySelectorAll(s).length === 1 } catch { return false } }
+  // generated ids and state classes change between builds; leave them out
+  const stableId = (e) => e.id && !/\d{4,}|[a-f0-9]{8,}|^:r/i.test(e.id)
+  const part = (e) => e.tagName.toLowerCase() + [...e.classList].filter((c) => !/\d{4,}|[a-f0-9]{6,}|^(is|has)-|active|current|visible|show|open|selected|swiper-slide-/i.test(c)).slice(0, 2).map((c) => '.' + esc(c)).join('')
+  if (stableId(best) && unique('#' + esc(best.id))) return '#' + esc(best.id)
+  let sel = part(best)
+  if (sel.includes('.') && unique(sel)) return sel
+  for (let e = best.parentElement, d = 0; e && e !== document.body && d < 4; e = e.parentElement, d++) {
+    if (stableId(e) && unique(`#${esc(e.id)} ${sel}`)) return `#${esc(e.id)} ${sel}`
+    sel = `${part(e)} > ${sel}`
+    if (unique(sel)) return sel
+  }
+  return null
+}
+
+/**
+ * Ignore suggestions for the steps of `run` from its own repeated shots and from earlier runs.
+ * @returns {{ runs: string[], steps: Array<{ node, ignore: object[], found: object[] }>, skipped: string[] }}
+ */
+export async function detectUnstable ({ root, config, run, scenario, last = 4, runs = null, sameCommit = false, launch = null }) {
+  const others = runs ? (await Promise.all(runs.map(async (id) => {
+    const dir = id.includes('/') ? resolve(id) : join(resolve(root, config.output), id)
+    const meta = await readJson(join(dir, 'meta.json'), null)
+    if (!meta) throw new UserError(`Run ${id} not found in ${config.output}.`)
+    return { dir, meta }
+  }))) : (await siblingRuns({ root, config, run, sameCommit })).slice(0, Math.max(0, last - 1))
+  const all = [{ dir: run.dir, meta: run.meta }, ...others]
+  const maps = await Promise.all(all.map(async (r) => new Map(latestCaptures(await readCaptures(r.dir)).filter((e) => !e.item).map((e) => [key(e), { ...e, dir: r.dir }]))))
+  const nodes = new Map(scenario.nodes.map((n) => [n.id, n]))
+  const found = new Map() // node → [{ locale, viewport, x, y, w, h, share, source }]
+  const skipped = []
+  const browser = await (launch ? launch() : (await import('./browser.mjs')).launchEphemeral(config))
+  try {
+    const page = await browser.newPage()
+    await page.setContent('<!doctype html><title>stability</title>')
+    await page.addScriptTag({ content: DETECTOR })
+    for (const [k, entry] of maps[0]) {
+      if (!nodes.has(entry.node)) continue
+      const caps = []
+      for (const m of maps) { const e = m.get(k); if (e) caps.push({ e, cap: await readJson(join(e.dir, e.file), null) }) }
+      const mine = caps[0].cap
+      if (!mine?.files) continue
+      const regions = []
+      for (const { cap } of caps) for (const r of cap?.unstable?.regions || []) regions.push({ ...r, source: 'repeat' })
+      const usable = caps.filter(({ cap }) => cap?.files?.image || cap?.files?.png)
+      if (usable.length >= 2) {
+        try {
+          const cssWidth = mine.size?.width || mine.size?.viewport?.[0] || 1280
+          const r = await crossRegions(page, await Promise.all(usable.map(({ e, cap }) => dataUrl(join(e.dir, cap.files.image || cap.files.png)))), cssWidth)
+          if (r.too_much) skipped.push(`${entry.node} ${entry.locale}/${entry.viewport}: ${Math.round(r.changed * 100)} % of the screen differs between runs; that is a changed page, not a noisy region`)
+          for (const x of r.regions) regions.push({ ...x, source: 'runs' })
+        } catch (error) { skipped.push(`${entry.node} ${entry.locale}/${entry.viewport}: ${error.message}`) }
+      }
+      if (!regions.length) continue
+      const merged = mergeRects(regions.map(({ x, y, w, h, share }) => ({ x, y, w, h, share })), 8)
+      const list = found.get(entry.node) || []
+      for (const r of merged) list.push({ ...r, locale: entry.locale, viewport: entry.viewport, html: mine.files.html ? join(entry.dir, mine.files.html) : null, url: mine.url, sources: [...new Set(regions.filter((x) => x.x < r.x + r.w && r.x < x.x + x.w && x.y < r.y + r.h && r.y < x.y + x.h).map((x) => x.source))] })
+      found.set(entry.node, list)
+    }
+    // regions → selectors in the stored HTML (scripts off); rectangles when no element fits
+    const steps = []
+    for (const [node, list] of found) {
+      const ignore = []
+      for (const r of list) {
+        let selector = null
+        if (r.html) {
+          const vp = run.meta.scope.viewports?.[r.viewport] || [1280, 800]
+          const ctx = await browser.newContext({ viewport: { width: vp[0], height: vp[1] }, javaScriptEnabled: false })
+          try {
+            const p = await ctx.newPage()
+            await p.setContent(withBase(await readFile(r.html, 'utf8'), r.url), { waitUntil: 'load', timeout: 20000 }).catch(() => {})
+            selector = await p.evaluate(selectorAt, { x: r.x, y: r.y, w: r.w, h: r.h }).catch(() => null)
+          } finally { await ctx.close() }
+        }
+        const note = `${r.sources.includes('repeat') ? 'moves while the page is idle' : 'changes between runs'} (${r.locale}/${r.viewport})`
+        const known = selector && ignore.find((x) => x.selector === selector)
+        if (known) { known.viewports = [...new Set([...(known.viewports || []), r.viewport])]; continue }
+        ignore.push(selector ? { selector, viewports: [r.viewport], note } : { rect: [r.x, r.y, r.w, r.h], viewport: r.viewport, note })
+      }
+      // a selector seen in every viewport of the run needs no viewport list
+      const vps = Object.keys(run.meta.scope.viewports || {})
+      for (const x of ignore) if (x.viewports && vps.every((v) => x.viewports.includes(v))) delete x.viewports
+      steps.push({ node, ignore, found: list.map(({ html, url, ...r }) => r) })
+    }
+    return { runs: all.map((r) => r.meta.id), steps, skipped }
+  } finally { await browser.close() }
+}
+
+/** The suggestions as a YAML fragment per step, ready to paste under each node. */
+export function suggestionsYaml (report) {
+  return report.steps.map((s) => `# ${s.node}\nignore:\n${s.ignore.map((x) => `  - ${yaml.dump(x, { flowLevel: 0, lineWidth: 200 }).trim()}`).join('\n')}`).join('\n\n')
+}
+
+/**
+ * Inserts the suggestions into the scenario file under each node that has no `ignore` yet (block-style nodes only;
+ * comments and formatting stay). Returns { applied: [node], skipped: [reason] }.
+ */
+export async function applySuggestions (file, report) {
+  let text = await readFile(file, 'utf8')
+  const applied = []; const skipped = []
+  const parsed = yaml.load(text)
+  for (const s of report.steps) {
+    const node = (parsed?.nodes || []).find((n) => n.id === s.node)
+    if (!node) { skipped.push(`${s.node}: not in ${file}`); continue }
+    if (node.ignore) { skipped.push(`${s.node}: already has ignore; merge by hand`); continue }
+    const lines = text.split('\n')
+    const at = lines.findIndex((l) => new RegExp(`^(\\s*)- id: ['"]?${s.node.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}['"]?\\s*(#.*)?$`).test(l))
+    if (at < 0) { skipped.push(`${s.node}: node is not in block style; paste the suggestion by hand`); continue }
+    const indent = lines[at].match(/^(\s*)-/)[1] + '  '
+    const block = [`${indent}ignore:`, ...s.ignore.map((x) => `${indent}  - ${yaml.dump(x, { flowLevel: 0, lineWidth: 400 }).trim()}`)]
+    lines.splice(at + 1, 0, ...block)
+    text = lines.join('\n')
+    applied.push(s.node)
+  }
+  if (applied.length) {
+    yaml.load(text) // must still parse
+    await writeFile(file, text)
+  }
+  return { applied, skipped }
+}
+
+/** `kaloko stability`: detect, write stability.json and stability.yml in the run, print, optionally apply. */
+export async function stabilityCmd ({ root, config, run, scenario, args, say }) {
+  const report = await detectUnstable({ root, config, run, scenario, last: Number(args.last) || 4, runs: typeof args.runs === 'string' ? args.runs.split(',').map((s) => s.trim()).filter(Boolean) : null, sameCommit: !!args['same-commit'] })
+  await writeJson(join(run.dir, 'stability.json'), { schema: 'qawalk.stability.v1', generated_at: new Date().toISOString(), ...report })
+  if (args.json) { say(JSON.stringify(report, null, 2)); return report }
+  const repeats = report.steps.some((s) => s.found.some((r) => r.sources.includes('repeat')))
+  say(`Compared ${report.runs.length} run(s)${report.runs.length < 2 && !repeats ? ' (one run and no repeated shots: walk again, or walk with --stability 3, to find regions that move)' : ''}: ${report.steps.length ? `${report.steps.reduce((n, s) => n + s.ignore.length, 0)} unstable region(s) in ${report.steps.length} step(s).` : 'no unstable regions.'}`)
+  for (const s of report.skipped) say(`  ! ${s}`)
+  if (!report.steps.length) return report
+  const text = suggestionsYaml(report)
+  await writeFile(join(run.dir, 'stability.yml'), text + '\n')
+  say(`\n${text}\n\nSuggestions: ${join(run.dir, 'stability.yml')}`)
+  if (args.apply) {
+    const file = resolve(root, run.meta.scenario_file)
+    const r = await applySuggestions(file, report)
+    if (r.applied.length) say(`Added ignore to ${r.applied.join(', ')} in ${run.meta.scenario_file}. Capture those steps again so the canvas and diffs use them.`)
+    for (const x of r.skipped) say(`  skipped ${x}`)
+  } else say('Check them on the screenshots, then run kaloko stability --apply (or paste them into the scenario).')
+  return report
+}