kaloko 0.4.9 → 0.4.11

package/src/lib/heal.mjs

@@ -0,0 +1,207 @@
+// Self-healing selectors (#13): when a step script waits in vain for a selector, propose a replacement from the page
+// as it is now (role and accessible name, test ids, text), preferring the element the old selector matched in the
+// step's previous capture. The proposal is printed as a patch; `walk --heal` applies it to the script only after the
+// step passed with it. Nothing is ever changed silently.
+import { readFile, writeFile, rm, readdir } from 'node:fs/promises'
+import { join, dirname, basename, relative, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { readJson } from './util.mjs'
+
+/** The selector a Playwright timeout waited for, or null (only plain locator strings can be patched). */
+export function failedSelector (message) {
+  const text = String(message || '')
+  if (!/Timeout \d+ms exceeded|waiting for/i.test(text) || /strict mode violation/i.test(text)) return null
+  const unq = (s, q) => s.replace(new RegExp(`\\\\${q}`, 'g'), q)
+  let m = text.match(/waiting for locator\('((?:\\'|[^'])+)'\)/)
+  if (m) return unq(m[1], "'")
+  m = text.match(/waiting for locator\("((?:\\"|[^"])+)"\)/)
+  if (m) return unq(m[1], '"')
+  m = text.match(/waiting for selector "((?:\\"|[^"])+)"/)
+  if (m) return unq(m[1], '"')
+  return null
+}
+
+/** Words a selector is made of: ids, classes, attribute values and text, split on punctuation and camelCase. */
+export function tokensOf (selector) {
+  return [...new Set(String(selector)
+    .replace(/([a-z])([A-Z])/g, '$1 $2')
+    .toLowerCase()
+    .split(/[^a-z0-9áčďéěíňóřšťúůýž]+/i)
+    .filter((w) => w.length > 1 && !['text', 'has', 'nth', 'first', 'last', 'visible', 'true', 'role', 'name', 'internal', 'data', 'testid', 'test', 'id', 'qa', 'cy', 'div', 'span'].includes(w)))]
+}
+
+/**
+ * In the page (self-contained, passed to evaluate): interactive and labelled elements with role, accessible name,
+ * test id, id and classes; given an element, that element only.
+ */
+function describeAll (limit) {
+  const TEST = ['data-testid', 'data-test', 'data-qa', 'data-cy', 'data-test-id']
+  const roleOf = (el) => {
+    const r = el.getAttribute('role'); if (r) return r
+    const t = el.tagName.toLowerCase()
+    if (t === 'a' && el.hasAttribute('href')) return 'link'
+    if (t === 'button' || (t === 'input' && ['button', 'submit', 'reset'].includes(el.type))) return 'button'
+    if (t === 'input') return { checkbox: 'checkbox', radio: 'radio', range: 'slider', search: 'searchbox' }[el.type] || 'textbox'
+    if (t === 'textarea') return 'textbox'
+    if (t === 'select') return 'combobox'
+    if (/^h[1-6]$/.test(t)) return 'heading'
+    if (t === 'img') return 'img'
+    return null
+  }
+  const text = (s) => String(s || '').replace(/\s+/g, ' ').trim()
+  const nameOf = (el) => {
+    const l = el.getAttribute('aria-label'); if (l) return text(l)
+    const by = el.getAttribute('aria-labelledby'); if (by) { const t = by.split(/\s+/).map((id) => document.getElementById(id)?.textContent || '').join(' '); if (text(t)) return text(t) }
+    if (el.id) { const lab = document.querySelector(`label[for="${CSS.escape(el.id)}"]`); if (lab) return text(lab.textContent) }
+    const wrap = el.closest('label'); if (wrap && wrap !== el && /^(input|select|textarea)$/i.test(el.tagName)) return text(wrap.textContent)
+    if (/^(input|textarea)$/i.test(el.tagName)) return text(el.getAttribute('placeholder') || el.getAttribute('title') || (['button', 'submit'].includes(el.type) ? el.value : ''))
+    if (el.tagName === 'IMG') return text(el.getAttribute('alt'))
+    return text(el.innerText || el.textContent).slice(0, 80)
+  }
+  const describe = (el) => {
+    const testid = TEST.map((a) => el.getAttribute(a) ? [a, el.getAttribute(a)] : null).find(Boolean) || null
+    const r = el.getBoundingClientRect(); const cs = getComputedStyle(el)
+    return { tag: el.tagName.toLowerCase(), role: roleOf(el), name: nameOf(el), testid, id: el.id || null, classes: [...el.classList].slice(0, 8), visible: r.width > 0 && r.height > 0 && cs.visibility !== 'hidden' && cs.display !== 'none' }
+  }
+  if (typeof limit === 'object' && limit?.nodeType === 1) return describe(limit)
+  const sel = 'a[href], button, input, select, textarea, summary, [role], [aria-label], [data-testid], [data-test], [data-qa], [data-cy], [data-test-id], h1, h2, h3, label'
+  return [...document.querySelectorAll(sel)].slice(0, limit).map(describe).filter((d) => d.visible && (d.name || d.testid || d.id))
+}
+
+/** The element the old selector matched in the previous capture of this step (its HTML), described; null if none. */
+async function previousFingerprint ({ page, selector, root, output, run, node, locale }) {
+  const base = resolve(root, output)
+  let names = []
+  try { names = (await readdir(base, { withFileTypes: true })).filter((e) => e.isDirectory() && e.name !== run.meta.id && !e.name.startsWith('.')).map((e) => e.name).sort().reverse() } catch { return null }
+  for (const name of names.slice(0, 20)) {
+    const meta = await readJson(join(base, name, 'meta.json'), null)
+    if (meta?.scenario?.id !== run.meta.scenario.id) continue
+    let html = null
+    for (const vp of Object.keys(run.meta.scope.viewports || {})) { html = await readFile(join(base, name, 'steps', node.id, locale, `${vp}.html`), 'utf8').catch(() => null); if (html) break }
+    if (!html) continue
+    let scratch = null
+    try {
+      const browser = page.context().browser()
+      scratch = browser ? await browser.newContext({ javaScriptEnabled: false }) : null
+      if (!scratch) return null
+      const p = await scratch.newPage()
+      await p.route('**/*', (r) => r.abort())
+      await p.setContent(html.replace(/<script[\s\S]*?<\/script>/gi, ''), { waitUntil: 'domcontentloaded', timeout: 5000 })
+      const el = p.locator(selector).first()
+      if (!(await el.count().catch(() => 0))) continue
+      const fp = await el.evaluate(describeAll)
+      return { ...fp, run: name }
+    } catch { continue } finally { await scratch?.close().catch(() => {}) }
+  }
+  return null
+}
+
+const q = (s) => JSON.stringify(String(s))
+
+/** Scores a candidate against the fingerprint of the old element and the words of the old selector. */
+export function score (c, { fp, tokens }) {
+  let s = 0; const why = []
+  if (fp) {
+    if (fp.testid && c.testid && fp.testid[1] === c.testid[1]) { s += 6; why.push(`same ${c.testid[0]} "${c.testid[1]}"`) }
+    if (fp.name && c.name && fp.name.toLowerCase() === c.name.toLowerCase()) { s += 4; why.push(`same name "${c.name}"`) }
+    if (fp.role && fp.role === c.role) { s += 2; why.push(`role ${c.role}`) }
+    if (fp.tag === c.tag) s += 1
+    if (fp.id && fp.id === c.id) { s += 3; why.push(`same id ${c.id}`) }
+    const shared = (fp.classes || []).filter((k) => c.classes.includes(k)).length
+    s += Math.min(2, shared)
+  }
+  const hay = [c.id, ...(c.classes || []), c.testid?.[1], c.name, c.role, c.tag].filter(Boolean).join(' ').toLowerCase()
+  const words = tokens.filter((t) => hay.includes(t))
+  if (words.length) { s += words.length * 1.5; why.push(`words ${words.map((w) => `"${w}"`).join(', ')} of the old selector`) }
+  return { score: s, why }
+}
+
+/** Selectors for an element, most stable first: test id, role + name, id, text. */
+export function selectorsFor (c) {
+  const out = []
+  if (c.testid) out.push(`[${c.testid[0]}=${q(c.testid[1])}]`)
+  if (c.role && c.name) out.push(`role=${c.role}[name=${q(c.name)}]`)
+  if (c.id && !/\d{3,}|^[a-f0-9-]{16,}$|^(radix|headlessui|mui|react-aria|:r)/i.test(c.id)) out.push(`#${c.id}`)
+  if (c.name && c.name.length <= 60) out.push(`text=${q(c.name)}`)
+  return out
+}
+
+/**
+ * A replacement for `selector` on the page as it is now: { replacement, why, from } or null.
+ * The replacement matches exactly one element.
+ */
+export async function proposeSelector ({ page, selector, root, output, run, node, locale }) {
+  const fp = await previousFingerprint({ page, selector, root, output, run, node, locale }).catch(() => null)
+  const tokens = tokensOf(selector)
+  let candidates
+  try { candidates = await page.evaluate(describeAll, 1500) } catch { return null }
+  const ranked = candidates.map((c) => ({ c, ...score(c, { fp, tokens }) })).filter((x) => x.score >= (fp ? 4 : 3)).sort((a, b) => b.score - a.score)
+  for (const { c, why } of ranked.slice(0, 8)) {
+    for (const sel of selectorsFor(c)) {
+      if (sel === selector) continue
+      const n = await page.locator(sel).count().catch(() => 0)
+      if (n === 1) return { replacement: sel, why: why.join(', ') || 'closest element', from: fp?.run || null, element: { role: c.role, name: c.name, tag: c.tag } }
+    }
+  }
+  return null
+}
+
+/** Replaces the selector's string literal in a script; { text, diff, count } or null when it is not written literally. */
+export function patchScript (source, selector, replacement, file = 'script.mjs') {
+  const lines = source.split('\n')
+  const out = []; const diff = []; let count = 0
+  for (const [i, line] of lines.entries()) {
+    let next = line
+    for (const quote of ["'", '"', '`']) {
+      const lit = quote + selector.replaceAll('\\', '\\\\').replaceAll(quote, '\\' + quote) + quote
+      if (next.includes(lit)) {
+        const rep = quote + replacement.replaceAll('\\', '\\\\').replaceAll(quote, '\\' + quote) + quote
+        count += next.split(lit).length - 1
+        next = next.replaceAll(lit, rep)
+      }
+    }
+    if (next !== line) diff.push(`@@ -${i + 1} +${i + 1} @@`, `-${line}`, `+${next}`)
+    out.push(next)
+  }
+  if (!count) return null
+  return { text: out.join('\n'), count, diff: [`--- a/${file}`, `+++ b/${file}`, ...diff].join('\n') }
+}
+
+/**
+ * After a failed step: the proposal and, with `apply`, a re-run of the step with the patched script. `rerun(module)`
+ * runs the step with a script module and throws when it fails. Returns { selector, proposal, patch, applied, note }.
+ */
+export async function healStep ({ error, page, scriptFile, root, output, run, node, locale, apply = false, rerun }) {
+  const selector = failedSelector(error?.message)
+  if (!selector) return null
+  const proposal = await proposeSelector({ page, selector, root, output, run, node, locale })
+  if (!proposal) return { selector, proposal: null, note: `no element on the page now resembles ${selector}` }
+  const source = await readFile(scriptFile, 'utf8').catch(() => null)
+  const rel = relative(root, scriptFile)
+  const patch = source ? patchScript(source, selector, proposal.replacement, rel) : null
+  if (!patch) return { selector, proposal, patch: null, note: `${selector} is not written literally in ${rel}; change it by hand` }
+  if (!apply) return { selector, proposal, patch, applied: false }
+  // the patched script runs from a sibling file (its relative imports resolve the same) and replaces the original
+  // only when the step passed with it
+  const trial = join(dirname(scriptFile), `.${basename(scriptFile, '.mjs')}.kaloko-heal-${process.pid}.mjs`)
+  try {
+    await writeFile(trial, patch.text)
+    await rerun(await import(`${pathToFileURL(trial).href}?t=${Date.now()}`))
+    await writeFile(scriptFile, patch.text)
+    return { selector, proposal, patch, applied: true }
+  } catch (e) {
+    return { selector, proposal, patch, applied: false, note: `the step still fails with the proposal (${String(e.message).split('\n')[0]}); ${rel} is unchanged` }
+  } finally { await rm(trial, { force: true }) }
+}
+
+/** Lines for the terminal: what failed, what is proposed and why, and the patch. */
+export function formatHeal (h, { stepArg }) {
+  if (!h) return ''
+  if (!h.proposal) return `  ↳ selector ${h.selector}: ${h.note}`
+  const lines = [`  ↳ selector ${h.selector} not found; proposed ${h.proposal.replacement} (${h.proposal.why}${h.proposal.from ? `; the old selector matched it in run ${h.proposal.from}` : ''})`]
+  if (h.applied) lines.push(`  ↳ healed: the step passed with it, ${h.patch.count} occurrence(s) changed:`)
+  else if (h.note) lines.push(`  ↳ ${h.note}`)
+  if (h.patch) lines.push(h.patch.diff.split('\n').map((l) => `    ${l}`).join('\n'))
+  if (h.patch && !h.applied && !h.note) lines.push(`  ↳ apply it after the step passes: kaloko walk --steps ${stepArg} --heal`)
+  return lines.join('\n')
+}

package/src/lib/import.mjs

@@ -0,0 +1,374 @@
+// `kaloko import` (#11): screenshots, recordings and traces that agents and tools already produced, laid out as a run.
+//
+// Sources (detected, or --format):
+//   playwright-json  the JSON reporter's file (npx playwright test --reporter=json): screenshots attached to each test
+//   playwright-html  an HTML report folder (playwright-report/): the report embedded in index.html and its data/ files
+//   trace            a trace.zip: one screenshot after each page action (goto, click, fill …) from the screencast
+//   folder           any folder of images: with steps.json (titles, step ids, URLs, notes), or a Markdown walkthrough
+//                    whose images appear in order under headings (Cursor, Antigravity, Claude Code), or just images
+//                    in file name order. Sub-folders of a test-results folder are read the same way.
+// Every source becomes items { title, image, ext, url?, notes?, step?, locale?, viewport?, group? }; items are mapped
+// to scenario steps by step id, URL path or title, or become the steps of an ad-hoc flow.
+import { readFile, readdir, stat, writeFile, mkdir, copyFile, rm } from 'node:fs/promises'
+import { join, dirname, basename, extname, relative, resolve } from 'node:path'
+import { readZip } from './unzip.mjs'
+import { pathOf } from './affected-core.mjs'
+import { runPaths, addCapture } from './run.mjs'
+import { writeJson } from './util.mjs'
+import { criteriaHash } from './evaluate.mjs'
+import { encodeImage } from './capture.mjs'
+
+const IMAGE = /\.(png|jpe?g|webp)$/i
+const VIDEO = /\.(webm|mp4|mov)$/i
+const MIME = { png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', webp: 'image/webp' }
+const extOf = (f) => { const e = extname(f).slice(1).toLowerCase(); return e === 'jpeg' ? 'jpg' : e }
+const natural = (a, b) => a.localeCompare(b, undefined, { numeric: true, sensitivity: 'base' })
+export const slug = (s) => String(s || '').toLowerCase().normalize('NFD').replace(/[̀-ͯ]/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 50)
+/** "03_checkout-page@2x.png" → "Checkout page" */
+export const titleFromFile = (f) => { const t = basename(f, extname(f)).replace(/@\dx$/, '').replace(/^[\d\s._-]+(?=\D)/, '').replace(/[-_.]+/g, ' ').trim(); return t ? t[0].toUpperCase() + t.slice(1) : basename(f) }
+
+/** Width and height of a PNG, JPEG or WebP image, or null. */
+export function imageSize (b) {
+  if (b.length > 24 && b.readUInt32BE(0) === 0x89504e47) return [b.readUInt32BE(16), b.readUInt32BE(20)]
+  if (b[0] === 0xff && b[1] === 0xd8) {
+    for (let i = 2; i < b.length - 9;) {
+      if (b[i] !== 0xff) { i++; continue }
+      const m = b[i + 1]; const len = b.readUInt16BE(i + 2)
+      if (m >= 0xc0 && m <= 0xcf && ![0xc4, 0xc8, 0xcc].includes(m)) return [b.readUInt16BE(i + 7), b.readUInt16BE(i + 5)]
+      i += 2 + len
+    }
+    return null
+  }
+  if (b.length > 30 && b.toString('ascii', 0, 4) === 'RIFF' && b.toString('ascii', 8, 12) === 'WEBP') {
+    const kind = b.toString('ascii', 12, 16)
+    if (kind === 'VP8X') return [1 + b.readUIntLE(24, 3), 1 + b.readUIntLE(27, 3)]
+    if (kind === 'VP8 ') return [b.readUInt16LE(26) & 0x3fff, b.readUInt16LE(28) & 0x3fff]
+    if (kind === 'VP8L') { const bits = b.readUInt32LE(21); return [1 + (bits & 0x3fff), 1 + ((bits >> 14) & 0x3fff)] }
+  }
+  return null
+}
+
+// ---------- readers ----------
+
+/** Markdown walkthrough: images in order, titled by the heading above them, with the text between as notes. */
+export function parseMarkdown (text) {
+  const items = []; const videos = []
+  let heading = null; let notes = []
+  for (const line of text.split('\n')) {
+    const h = line.match(/^#{1,4}\s+(.+?)\s*#*\s*$/)
+    if (h) { heading = h[1].replace(/[*_`]/g, ''); notes = []; continue }
+    let found = false
+    for (const m of line.matchAll(/!\[([^\]]*)\]\(<?([^)>\s]+)>?(?:\s+"[^"]*")?\)|<img[^>]+src=["']([^"']+)["'][^>]*>/g)) {
+      const src = decodeURI(m[2] || m[3])
+      if (/^https?:/.test(src)) continue
+      if (VIDEO.test(src)) { videos.push(src); found = true; continue }
+      items.push({ title: heading || m[1] || titleFromFile(src), alt: m[1] || null, file: src, notes: notes.join(' ').trim() || null })
+      found = true
+    }
+    for (const m of line.matchAll(/\[[^\]]*\]\(<?([^)>\s]+\.(?:webm|mp4|mov))>?\)/gi)) { videos.push(decodeURI(m[1])); found = true }
+    if (!found && line.trim() && !/^(```|---|\|)/.test(line.trim())) notes.push(line.trim().replace(/^[-*>]\s+/, ''))
+  }
+  // a heading with several images: the extra ones keep the alt text as their title
+  const seen = new Map()
+  for (const it of items) { const n = (seen.get(it.title) || 0) + 1; seen.set(it.title, n); if (n > 1) it.title = it.alt ? `${it.title}: ${it.alt}` : `${it.title} (${n})` }
+  return { items, videos }
+}
+
+async function readFolder (dir, { depth = 0 } = {}) {
+  const names = (await readdir(dir, { withFileTypes: true })).sort((a, b) => natural(a.name, b.name))
+  const files = names.filter((e) => e.isFile()).map((e) => e.name)
+  const manifest = files.find((f) => /^(steps|walkthrough|kaloko-import|manifest)\.json$/i.test(f))
+  if (manifest) {
+    const m = JSON.parse(await readFile(join(dir, manifest), 'utf8'))
+    const steps = Array.isArray(m) ? m : m.steps || []
+    const items = []
+    for (const s of steps) {
+      const file = s.image || s.screenshot || s.file
+      if (!file) continue
+      items.push({ title: s.title || titleFromFile(file), image: await readFile(resolve(dir, file)), ext: extOf(file), file, url: s.url || null, notes: s.notes || s.description || null, step: s.step || null, locale: s.locale || null, viewport: s.viewport || null })
+    }
+    const videos = steps.map((s) => s.video).filter(Boolean).map((v) => resolve(dir, v))
+    return { tool: m.tool || 'walkthrough', title: m.title || null, url: m.url || null, items, videos }
+  }
+  const md = files.filter((f) => /\.md$/i.test(f)).sort((a, b) => (/^(walkthrough|steps|readme)/i.test(a) ? -1 : 1) - (/^(walkthrough|steps|readme)/i.test(b) ? -1 : 1))
+  for (const f of md) {
+    const text = await readFile(join(dir, f), 'utf8')
+    const parsed = parseMarkdown(text)
+    if (!parsed.items.length) continue
+    const items = []
+    for (const it of parsed.items) {
+      const abs = resolve(dir, it.file)
+      const image = await readFile(abs).catch(() => null)
+      if (image && IMAGE.test(abs)) items.push({ ...it, image, ext: extOf(abs) })
+    }
+    const title = (text.match(/^#\s+(.+)$/m) || [])[1] || null
+    return { tool: 'walkthrough', title, items, videos: parsed.videos.map((v) => resolve(dir, v)) }
+  }
+  const images = files.filter((f) => IMAGE.test(f))
+  const videos = files.filter((f) => VIDEO.test(f)).map((f) => join(dir, f))
+  if (images.length || depth > 0) {
+    const items = []
+    for (const f of images) items.push({ title: titleFromFile(f), image: await readFile(join(dir, f)), ext: extOf(f), file: f })
+    return { tool: 'folder', title: null, items, videos }
+  }
+  // a folder of folders (Playwright test-results, one folder per test): each folder's images, grouped by folder
+  const out = { tool: 'folder', title: null, items: [], videos }
+  for (const sub of names.filter((e) => e.isDirectory() && !e.name.startsWith('.'))) {
+    const subDir = join(dir, sub.name)
+    const traces = (await readdir(subDir).catch(() => [])).filter((f) => /\.zip$/i.test(f))
+    const r = await readFolder(subDir, { depth: depth + 1 })
+    if (!r.items.length && traces.length) { const t = readTrace(await readFile(join(subDir, traces[0]))); r.items = t.items }
+    const group = titleFromFile(sub.name)
+    for (const it of r.items) out.items.push({ ...it, group, title: r.items.length > 1 ? `${group}: ${it.title}` : group })
+    out.videos.push(...r.videos)
+  }
+  return out
+}
+
+const ACTIONS = new Set(['goto', 'click', 'dblclick', 'fill', 'press', 'type', 'check', 'uncheck', 'selectOption', 'setInputFiles', 'tap', 'hover', 'reload', 'goBack', 'goForward'])
+const short = (v) => String(v || '').replace(/^https?:\/\/[^/]+/, '').slice(0, 60)
+
+/** A Playwright trace: one screenshot after each page action, from the screencast frames. */
+export function readTrace (zipBuf) {
+  const zip = readZip(zipBuf)
+  const actions = new Map(); const frames = []
+  for (const [name, get] of zip) {
+    if (!/(^|\/)[^/]*\.trace$/.test(name)) continue
+    for (const line of get().toString('utf8').split('\n')) {
+      if (!line.trim()) continue
+      let e; try { e = JSON.parse(line) } catch { continue }
+      if (e.type === 'before') actions.set(e.callId, { method: e.method || (e.apiName || '').split('.').pop(), title: e.title || e.apiName || null, params: e.params || {}, start: e.startTime, end: null, error: null })
+      else if (e.type === 'after' && actions.has(e.callId)) Object.assign(actions.get(e.callId), { end: e.endTime, error: e.error?.message || null })
+      else if (e.type === 'action' && e.metadata) actions.set(e.metadata.id || actions.size, { method: e.metadata.method || (e.metadata.apiName || '').split('.').pop(), title: e.metadata.apiName || null, params: e.metadata.params || {}, start: e.metadata.startTime, end: e.metadata.endTime, error: e.metadata.error?.error?.message || null })
+      else if (e.type === 'screencast-frame') frames.push({ sha1: e.sha1, ts: e.timestamp, w: e.width, h: e.height })
+    }
+  }
+  frames.sort((a, b) => a.ts - b.ts)
+  const list = [...actions.values()].filter((a) => ACTIONS.has(a.method) && a.end != null).sort((a, b) => a.start - b.start)
+  const items = []; let url = null; let lastSha = null
+  for (const [i, a] of list.entries()) {
+    if (a.method === 'goto' && a.params.url) url = a.params.url
+    const until = list[i + 1]?.start ?? Infinity
+    // the screen as the action left it: the first frame after it ended (before the next began), else the last one before
+    const frame = frames.find((f) => f.ts >= a.end && f.ts < until) || [...frames].reverse().find((f) => f.ts <= a.end)
+    if (!frame || frame.sha1 === lastSha) continue
+    const file = [...zip.keys()].find((k) => k.endsWith(`resources/${frame.sha1}`))
+    if (!file) continue
+    lastSha = frame.sha1
+    const target = a.params.url || a.params.selector || a.params.key || ''
+    items.push({ title: `${a.method} ${short(target)}`.trim(), image: zip.get(file)(), ext: frame.sha1.endsWith('.png') ? 'png' : 'jpg', url, notes: a.error ? `Failed: ${a.error.split('\n')[0]}` : null, file: `trace:${i}` })
+  }
+  return { tool: 'playwright-trace', title: null, items, videos: [] }
+}
+
+/** Tests of a Playwright JSON report (nested suites): [{ title, group, result }]. */
+function testsOf (suite, path = []) {
+  const here = suite.title ? [...path, suite.title] : path
+  const out = []
+  for (const spec of suite.specs || []) for (const t of spec.tests || []) out.push({ title: spec.title, path: here, project: t.projectName || null, result: (t.results || []).at(-1) })
+  for (const s of suite.suites || []) out.push(...testsOf(s, here))
+  return out
+}
+
+/** Items of one test result: its image attachments, else the frames of its trace. */
+async function resultItems (test, readAttachment) {
+  const items = []; const videos = []
+  for (const a of test.result?.attachments || []) {
+    if (/^image\/(png|jpe?g|webp)$/.test(a.contentType || '')) {
+      const image = await readAttachment(a)
+      if (!image) continue
+      const named = a.name && !/^screenshot(-\d+)?$/.test(a.name) ? `: ${a.name}` : ''
+      items.push({ title: `${test.title}${named}`, group: test.title, image, ext: a.contentType.includes('png') ? 'png' : a.contentType.includes('webp') ? 'webp' : 'jpg', file: a.path || a.name, notes: test.result.status && test.result.status !== 'passed' ? `Test ${test.result.status}${test.result.error?.message ? `: ${String(test.result.error.message).split('\n')[0].slice(0, 200)}` : ''}` : null })
+    } else if (/^video\//.test(a.contentType || '') && a.path) videos.push(a.path)
+  }
+  if (!items.length) {
+    const trace = (test.result?.attachments || []).find((a) => a.name === 'trace' || /\.zip$/.test(a.path || ''))
+    const buf = trace && await readAttachment(trace)
+    if (buf) for (const it of readTrace(buf).items) items.push({ ...it, group: test.title, title: `${test.title}: ${it.title}` })
+  }
+  return { items, videos }
+}
+
+async function readPlaywrightJson (file) {
+  const report = JSON.parse(await readFile(file, 'utf8'))
+  const base = dirname(file)
+  const read = async (a) => a.body ? Buffer.from(a.body, 'base64') : a.path ? readFile(resolve(base, a.path)).catch(() => null) : null
+  const out = { tool: 'playwright', title: null, items: [], videos: [] }
+  for (const s of report.suites || []) for (const t of testsOf(s)) { const r = await resultItems(t, read); out.items.push(...r.items); out.videos.push(...r.videos.map((v) => resolve(base, v))) }
+  return out
+}
+
+async function readPlaywrightHtml (dir) {
+  const html = await readFile(join(dir, 'index.html'), 'utf8')
+  const m = html.match(/playwrightReportBase64\s*=\s*["']data:application\/zip;base64,([A-Za-z0-9+/=]+)["']/)
+  if (!m) throw new Error(`${dir}/index.html has no embedded Playwright report`)
+  const zip = readZip(Buffer.from(m[1], 'base64'))
+  const out = { tool: 'playwright', title: null, items: [], videos: [] }
+  const read = async (a) => a.body ? Buffer.from(a.body, 'base64') : a.path ? readFile(resolve(dir, a.path)).catch(() => null) : null
+  const files = [...zip.keys()].filter((k) => k.endsWith('.json') && k !== 'report.json').sort(natural)
+  for (const k of files) {
+    const f = JSON.parse(zip.get(k)().toString('utf8'))
+    for (const t of f.tests || []) {
+      const r = await resultItems({ title: t.title, path: t.path || [], result: (t.results || []).at(-1) }, read)
+      out.items.push(...r.items); out.videos.push(...r.videos.map((v) => resolve(dir, v)))
+    }
+  }
+  return out
+}
+
+/** Reads any supported source; { format, tool, title, items, videos }. */
+export async function readSource (path, format = 'auto') {
+  const st = await stat(path).catch(() => null)
+  if (!st) throw new Error(`${path} does not exist`)
+  if (format === 'auto') {
+    if (st.isDirectory()) format = (await stat(join(path, 'index.html')).catch(() => null)) && /playwrightReportBase64/.test(await readFile(join(path, 'index.html'), 'utf8')) ? 'playwright-html' : 'folder'
+    else if (/\.zip$/i.test(path)) format = 'trace'
+    else if (/\.json$/i.test(path)) format = 'playwright-json'
+    else if (/\.md$/i.test(path)) format = 'markdown'
+    else throw new Error(`${path}: give a folder, a Playwright report (folder or .json) or a trace .zip`)
+  }
+  let r
+  if (format === 'folder') r = await readFolder(path)
+  else if (format === 'markdown') {
+    const parsed = parseMarkdown(await readFile(path, 'utf8'))
+    const items = []
+    for (const it of parsed.items) { const abs = resolve(dirname(path), it.file); const image = await readFile(abs).catch(() => null); if (image && IMAGE.test(abs)) items.push({ ...it, image, ext: extOf(abs) }) }
+    r = { tool: 'walkthrough', title: null, items, videos: parsed.videos.map((v) => resolve(dirname(path), v)) }
+  } else if (format === 'trace') r = readTrace(await readFile(path))
+  else if (format === 'playwright-json') r = await readPlaywrightJson(path)
+  else if (format === 'playwright-html' || format === 'playwright') r = await readPlaywrightHtml(path)
+  else throw new Error(`Unknown --format ${format} (auto, folder, markdown, playwright-json, playwright-html, trace)`)
+  for (const it of r.items) it.size = imageSize(it.image)
+  return { format, ...r }
+}
+
+// ---------- mapping ----------
+
+const words = (s) => new Set(slug(s).split('-').filter((w) => w.length > 1))
+const overlap = (a, b) => { const A = words(a); const B = words(b); if (!A.size || !B.size) return 0; let n = 0; for (const w of A) if (B.has(w)) n++; return n / Math.min(A.size, B.size) }
+
+/** The step an item belongs to: its `step`, --map, the URL path, then the title against step ids and titles. */
+export function stepFor (item, nodes, map = {}) {
+  const steps = nodes.filter((n) => n.kind !== 'decision')
+  const byId = (id) => steps.find((n) => n.id === id)
+  if (item.step && byId(item.step)) return { node: byId(item.step), how: 'step id' }
+  for (const [label, id] of Object.entries(map)) if (byId(id) && [item.title, item.group, item.file].some((t) => t && slug(t).includes(slug(label)))) return { node: byId(id), how: `--map ${label}` }
+  const p = pathOf(item.url)
+  if (p) {
+    const hit = steps.find((n) => [n.path].flat().flatMap((x) => (x && typeof x === 'object' ? Object.values(x) : [x])).some((x) => x && pathOf(x) === p))
+    if (hit) return { node: hit, how: `URL ${p}` }
+  }
+  const labels = [item.title, item.group, item.file && titleFromFile(item.file)].filter(Boolean)
+  for (const l of labels) { const s = slug(l); const hit = steps.find((n) => n.id === s || slug(typeof n.title === 'string' ? n.title : Object.values(n.title || {})[0]) === s); if (hit) return { node: hit, how: 'title' } }
+  let best = null
+  for (const n of steps) {
+    const t = typeof n.title === 'string' ? n.title : Object.values(n.title || {})[0] || ''
+    const sc = Math.max(...labels.map((l) => Math.max(overlap(l, n.id), overlap(l, t))))
+    if (sc >= 0.67 && (!best || sc > best.sc)) best = { node: n, sc }
+  }
+  return best ? { node: best.node, how: 'similar title' } : null
+}
+
+/** The run viewport closest to the image's width (screens taken at 2× or 3× count by their CSS width). */
+export function viewportFor (size, viewports, wanted = null) {
+  if (wanted && viewports[wanted]) return wanted
+  const names = Object.keys(viewports)
+  if (!size || names.length === 1) return names[0]
+  let best = names[0]; let bestD = Infinity
+  for (const n of names) for (const k of [1, 2, 3]) { const d = Math.abs(size[0] / k - viewports[n][0]); if (d < bestD) { bestD = d; best = n } }
+  return best
+}
+
+/** An ad-hoc flow from the items: one screen per item, in order, for a source with no scenario. */
+export function adhocScenario (src, { id, title, locale = 'en' } = {}) {
+  const ids = new Set()
+  const nodes = src.items.map((it, i) => {
+    let nid = slug(it.title) || `step-${i + 1}`
+    while (ids.has(nid)) nid = `${nid}-${i + 1}`
+    ids.add(nid)
+    it.step = nid
+    const p = pathOf(it.url)
+    return {
+      id: nid, kind: 'screen', title: String(it.title).slice(0, 100), ...(p ? { path: p } : {}),
+      purpose: it.notes ? String(it.notes).slice(0, 300) : `Imported from ${src.tool}: ${it.title}.`,
+      execution: { strategy: 'manual', instructions: `Imported from ${src.tool}${it.file ? ` (${it.file})` : ''}; capture it again with kaloko import or kaloko capture --step ${nid}.` },
+      criteria: []
+    }
+  })
+  const widest = src.items.map((it) => it.size).filter(Boolean).sort((a, b) => b[0] - a[0])[0]
+  const w = widest ? (widest[0] > 2000 ? Math.round(widest[0] / 2) : widest[0]) : 1280
+  const vp = w < 700 ? 'mobile' : w < 1100 ? 'tablet' : 'desktop'
+  return {
+    schema: 'qawalk.scenario.v1', id: id || `IMPORT-${slug(src.title || src.tool).toUpperCase().slice(0, 40) || 'RUN'}`, title: title || src.title || `Imported from ${src.tool}`,
+    kind: 'task', version: 1, locales: [locale], viewports: { [vp]: [w, vp === 'mobile' ? 844 : 800] },
+    lanes: ['Imported'], nodes, edges: nodes.slice(1).map((n, i) => ({ from: nodes[i].id, to: n.id }))
+  }
+}
+
+// ---------- writing captures ----------
+
+/** PNG bytes of any browser-readable image, through the encoder page. */
+async function toPng (encoder, buf, ext) {
+  const bytes = await encoder.evaluate(async ({ url }) => {
+    const img = new Image(); await new Promise((res, rej) => { img.onload = res; img.onerror = rej; img.src = url })
+    const c = document.createElement('canvas'); c.width = img.width; c.height = img.height; c.getContext('2d').drawImage(img, 0, 0)
+    const b = await new Promise((res) => c.toBlob(res, 'image/png'))
+    return Array.from(new Uint8Array(await b.arrayBuffer()))
+  }, { url: `data:${MIME[ext]};base64,${buf.toString('base64')}` })
+  return Buffer.from(bytes)
+}
+
+/** One imported screen as a capture of a step (no page: deterministic checks are not run, semantic ones wait). */
+export async function writeImported ({ run, node, locale, viewport, item, tool, encoder = null }) {
+  const paths = runPaths(run.dir)
+  const base = paths.step(node.id, locale, viewport, 'x')
+  await mkdir(dirname(base), { recursive: true })
+  for (const ext of ['eval.json', 'html', 'png', 'jpg', 'webp', 'thumb.webp']) await rm(paths.step(node.id, locale, viewport, ext), { force: true })
+  let image = paths.step(node.id, locale, viewport, item.ext); let thumb = null
+  if (encoder) {
+    try {
+      const png = item.ext === 'png' ? item.image : await toPng(encoder, item.image, item.ext)
+      const enc = await encodeImage(encoder, png, { format: 'webp' })
+      image = paths.step(node.id, locale, viewport, 'webp'); thumb = paths.step(node.id, locale, viewport, 'thumb.webp')
+      await writeFile(image, enc.image); await writeFile(thumb, enc.thumb)
+    } catch { image = paths.step(node.id, locale, viewport, item.ext); thumb = null }
+  }
+  if (!thumb) await writeFile(image, item.image)
+  const scale = item.size && run.meta.scope.viewports[viewport] ? Math.max(1, Math.round(item.size[0] / run.meta.scope.viewports[viewport][0])) : 1
+  const size = item.size ? [Math.round(item.size[0] / scale), Math.round(item.size[1] / scale)] : run.meta.scope.viewports[viewport] || [0, 0]
+  const record = {
+    schema: 'qawalk.capture.v1', node: node.id, locale, viewport, url: item.url || null,
+    captured_at: new Date().toISOString(), criteria_hash: criteriaHash(node),
+    console_errors: [], blocked_requests: [], state: '', scoped: {}, boxes: {}, overflow: [], meta: null, metadata: null,
+    checks: Object.fromEntries((node.criteria || []).filter((c) => c.check.type === 'deterministic').map((c) => [c.id, { ok: null, evidence: `imported screenshot (${tool}): there is no page to check; walk the step to check it` }])),
+    size: { width: size[0], height: size[1], viewport: size },
+    capture: { format: extOf(image), scale, masked: 0, annotations: [], source: 'import' },
+    imported: { tool, title: item.title, file: item.file || null, notes: item.notes || null },
+    files: { png: relative(run.dir, image), image: relative(run.dir, image), thumb: thumb ? relative(run.dir, thumb) : null, html: null }
+  }
+  const file = paths.step(node.id, locale, viewport, 'capture.json')
+  await writeJson(file, record)
+  await addCapture(run.dir, { type: 'capture', node: node.id, locale, viewport, file: relative(run.dir, file), at: record.captured_at })
+  return record
+}
+
+/** A second screen for a step already imported: an attachment (shown under the step's attachments). */
+export async function attachImported ({ run, node, locale, item }) {
+  const name = `${node.id}-${locale}-${slug(item.title).slice(0, 30) || 'import'}-${Date.now().toString(36)}${Math.random().toString(36).slice(2, 5)}.${item.ext}`
+  const file = runPaths(run.dir).attachment(name)
+  await mkdir(dirname(file), { recursive: true })
+  await writeFile(file, item.image)
+  const entry = { type: 'attachment', kind: 'crop', node: node.id, locale, title: item.title, file: relative(run.dir, file), at: new Date().toISOString(), source: 'import' }
+  await addCapture(run.dir, entry)
+  return entry
+}
+
+/** Imported recordings are kept in the run folder (imported/), not attached to a step and not uploaded. */
+export async function keepVideos (run, videos) {
+  const kept = []
+  for (const v of [...new Set(videos)]) {
+    const to = join(run.dir, 'imported', basename(v))
+    try { await mkdir(dirname(to), { recursive: true }); await copyFile(v, to); kept.push(relative(run.dir, to)) } catch {}
+  }
+  return kept
+}