kaloko 0.4.7 → 0.4.9

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/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/review.mjs

@@ -0,0 +1,69 @@
+// The service's review queue in words for the terminal (`kaloko review`, `kaloko share`, `kaloko feedback`): what a
+// person still has to decide on a shared run, so an agent can tell them what waits and where. Agents never decide
+// for people; they point them to the review mode link.
+
+const REASON = {
+  fail: 'failed',
+  returned: 'returned',
+  needs_review: 'needs a person’s judgement',
+  not_evaluated: 'not evaluated',
+  revoked: 'carried approval revoked',
+  changed: 'changed since the accepted run',
+  new: 'new',
+  comments: 'open comments'
+}
+const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`
+const day = (iso) => (iso ? String(iso).slice(0, 10) : '')
+const cut = (s, n = 140) => { const t = String(s ?? '').replace(/\s+/g, ' ').trim(); return t.length > n ? `${t.slice(0, n - 1)}…` : t }
+
+/** One line after `kaloko share`: "12 steps unchanged, approvals carried over; 5 need review: <link>". */
+export function shareReviewLine (r) {
+  if (!r || r.queue == null) return null
+  const carried = r.carried ? `${plural(r.carried, 'step', 'steps')} unchanged, approvals carried over; ` : ''
+  if (!r.pending) return `${carried}no step waits for a person; the run still needs its verdict: ${r.url}`
+  return `${carried}${r.pending} ${r.pending === 1 ? 'needs' : 'need'} review: ${r.url}`
+}
+
+/** Who decided and how, in a few words. */
+function decisionText (d) {
+  if (!d) return 'waiting for a person'
+  const via = d.via === 'agent' ? ' (agent)' : d.via === 'token' ? ' (token)' : ''
+  if (d.state === 'carried') return `approval carried over: ${d.by}${via} approved it on ${day(d.at)} in run ${d.from_run}`
+  if (d.state === 'approved') return `approved by ${d.by}${via} on ${day(d.at)}`
+  return `returned by ${d.by}${via} on ${day(d.at)}: ${cut(d.note, 200)}`
+}
+
+/** The whole queue for the terminal. */
+export function formatReviewQueue (q) {
+  if (!q?.run) return 'No published run found.'
+  const c = q.counts || {}
+  const out = []
+  out.push(`Review of ${q.run.id} (${q.run.scenario}${q.run.environment ? `, ${q.run.environment}` : ''}): ${c.decided || 0} of ${plural(c.queue || 0, 'step', 'steps')} decided, ${c.pending || 0} waiting for a person${c.carried ? `; ${plural(c.carried, 'unchanged step', 'unchanged steps')} kept ${c.carried === 1 ? 'its' : 'their'} approval` : ''}`)
+  out.push(q.reference
+    ? `Compared with the accepted run ${q.reference.id} (accepted${q.reference.accepted_by ? ` by ${q.reference.accepted_by}` : ''}${q.reference.accepted_at ? ` on ${day(q.reference.accepted_at)}` : ''})`
+    : 'No accepted run of this scenario yet: every step is new to the reviewers.')
+  if (!q.policy?.carry_over) out.push('Approvals do not carry over in this organization (Settings → Approvals).')
+  for (const it of q.items || []) {
+    const mark = !it.decision ? '○' : it.decision.state === 'returned' ? '↩' : '✓'
+    out.push(`  ${mark} ${it.step}${it.title ? `  ${typeof it.title === 'string' ? it.title : Object.values(it.title)[0]}` : ''} — ${it.reasons.map((r) => REASON[r] || r).join(', ')}`)
+    if (it.changed?.captures?.length) out.push(`      changed: ${it.changed.captures.map((x) => `${x.locale}/${x.viewport}${x.why !== 'pixels' ? ` (${x.why})` : ''}`).join(', ')}${it.changed.criteria ? ' · criteria changed' : ''}`)
+    else if (it.changed?.criteria) out.push('      changed: criteria')
+    for (const cr of (it.criteria || []).filter((x) => x.cells?.length).slice(0, 4)) {
+      const cell = cr.cells.find((x) => x.verdict === 'fail') || cr.cells[0]
+      out.push(`      ${cr.id} [${cell.locale}/${cell.viewport}] ${cell.verdict}${cell.evidence ? `: ${cut(cell.evidence)}` : ''}`)
+    }
+    out.push(`      ${decisionText(it.decision)}`)
+    if (it.unconfirmed) out.push(`      not counted: ${decisionText(it.unconfirmed)}`)
+    if (it.open_comments) out.push(`      ${plural(it.open_comments, 'open comment', 'open comments')} (kaloko feedback)`)
+  }
+  if (!(q.items || []).length) out.push('  Nothing waits for a person on the steps.')
+  if (q.carried?.length) {
+    out.push(`Approvals carried over (${q.carried.length}):`)
+    for (const x of q.carried.slice(0, 12)) out.push(`  ✓ ${x.step} — ${x.approved_by}${x.approved_via && x.approved_via !== 'session' ? ` (${x.approved_via})` : ''}, ${day(x.approved_at)}, ${x.kind === 'run' ? 'accepted run' : 'step approved in'} ${x.from_run}`)
+    if (q.carried.length > 12) out.push(`  … and ${q.carried.length - 12} more`)
+  }
+  const v = q.verdict || {}
+  out.push(`Run verdict: ${v.verdict || 'pending'}${v.by ? ` by ${v.by}${v.via && v.via !== 'session' ? ` (${v.via})` : ''}` : ''}${v.awaiting?.length ? ` · awaiting approval from ${v.awaiting.join(', ')}` : ''}`)
+  out.push(`Review mode for a person: ${q.review_url}`)
+  return out.join('\n')
+}

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
+}