kaloko 0.4.9 → 0.4.10

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
+}
+
+/** Recordings are kept in the run folder (imported/), not uploaded: the canvas does not play them yet. */
+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
+}

package/src/lib/init-detect.mjs

@@ -0,0 +1,219 @@
+// Smarter `kaloko init` (#26): what the project is (framework, dev server command and URL, locales from the i18n
+// config, main routes) and a first scenario that walks on the first try. Reads files only; never runs the project.
+import { readFile, readdir, stat } from 'node:fs/promises'
+import { join } from 'node:path'
+import { routeOf } from './affected-core.mjs'
+
+const read = (root, f) => readFile(join(root, f), 'utf8').catch(() => null)
+const exists = (root, f) => stat(join(root, f)).then(() => true, () => false)
+const firstOf = async (root, files) => { for (const f of files) { const t = await read(root, f); if (t != null) return { file: f, text: t } } return null }
+
+const FRAMEWORKS = [
+  ['next', 'Next.js', ['next'], 3000],
+  ['nuxt', 'Nuxt', ['nuxt', 'nuxt3'], 3000],
+  ['sveltekit', 'SvelteKit', ['@sveltejs/kit'], 5173],
+  ['remix', 'Remix / React Router', ['@remix-run/dev', '@remix-run/react', '@react-router/dev'], 5173],
+  ['astro', 'Astro', ['astro'], 4321],
+  ['gatsby', 'Gatsby', ['gatsby'], 8000],
+  ['angular', 'Angular', ['@angular/core'], 4200],
+  ['cra', 'Create React App', ['react-scripts'], 3000],
+  ['vite', 'Vite', ['vite'], 5173]
+]
+
+/** Framework, package manager and dev server (command, port, URL). */
+async function detectStack (root) {
+  const pkgText = await read(root, 'package.json')
+  let pkg = null
+  try { pkg = pkgText ? JSON.parse(pkgText) : null } catch {}
+  const deps = { ...(pkg?.dependencies || {}), ...(pkg?.devDependencies || {}) }
+  const pm = (await exists(root, 'pnpm-lock.yaml')) ? 'pnpm' : (await exists(root, 'yarn.lock')) ? 'yarn' : (await exists(root, 'bun.lockb')) || (await exists(root, 'bun.lock')) ? 'bun' : 'npm'
+  const runCmd = (script) => (pm === 'npm' ? `npm run ${script}` : pm === 'bun' ? `bun run ${script}` : `${pm} ${script}`)
+  let framework = null
+  for (const [id, name, names, port] of FRAMEWORKS) if (names.some((n) => deps[n])) { framework = { id, name, port }; break }
+  const gem = await read(root, 'Gemfile')
+  if (!framework && gem && /^\s*gem\s+['"]rails['"]/m.test(gem)) framework = { id: 'rails', name: 'Rails', port: 3000 }
+  if (!framework && await exists(root, 'manage.py')) framework = { id: 'django', name: 'Django', port: 8000 }
+  if (!framework && await exists(root, 'artisan')) framework = { id: 'laravel', name: 'Laravel', port: 8000 }
+  let command = null; let port = framework?.port || 3000
+  if (pkg?.scripts) {
+    const script = ['dev', 'start', 'serve', 'develop'].find((s) => pkg.scripts[s])
+    if (script) {
+      command = runCmd(script)
+      const m = pkg.scripts[script].match(/(?:--port[ =]|-p\s+|PORT=)(\d{2,5})/)
+      if (m) port = Number(m[1])
+    }
+  }
+  if (framework?.id === 'rails') command = (await exists(root, 'bin/dev')) ? 'bin/dev' : 'bin/rails server'
+  if (framework?.id === 'django') command = 'python manage.py runserver'
+  if (framework?.id === 'laravel') command = 'php artisan serve'
+  // a port in the bundler config wins over the default
+  const vite = await firstOf(root, ['vite.config.ts', 'vite.config.js', 'vite.config.mjs'])
+  const vp = vite?.text.match(/server\s*:\s*{[^}]*port\s*:\s*(\d{2,5})/)
+  if (vp && !/(?:--port|-p\s|PORT=)/.test(pkg?.scripts?.dev || '')) port = Number(vp[1])
+  const nuxtCfg = framework?.id === 'nuxt' ? await firstOf(root, ['nuxt.config.ts', 'nuxt.config.js']) : null
+  const np = nuxtCfg?.text.match(/devServer\s*:\s*{[^}]*port\s*:\s*(\d{2,5})/)
+  if (np) port = Number(np[1])
+  return { framework, pm, command, port, url: `http://localhost:${port}`, name: pkg?.name || null }
+}
+
+const LOCALE = /^[a-z]{2}(?:-[A-Za-z]{2,4})?$/
+const listOf = (src) => [...String(src || '').matchAll(/['"`]([a-z]{2}(?:-[A-Za-z]{2,4})?)['"`]/g)].map((m) => m[1])
+const codesOf = (src) => { const codes = [...String(src || '').matchAll(/code\s*:\s*['"`]([a-z]{2}(?:-[A-Za-z]{2,4})?)['"`]/g)].map((m) => m[1]); return codes.length ? codes : listOf(src) }
+const ordered = (list, def) => { const u = [...new Set(list)]; return def && u.includes(def) ? [def, ...u.filter((l) => l !== def)] : u }
+
+/** Locales from the i18n config: { list, default, source, prefix: 'always'|'except-default'|'none' } or null. */
+async function detectLocales (root, framework) {
+  // Next.js pages router i18n
+  const next = await firstOf(root, ['next.config.js', 'next.config.mjs', 'next.config.ts'])
+  const ni = next?.text.match(/i18n\s*:\s*{([\s\S]*?)}/)
+  if (ni) {
+    const list = listOf((ni[1].match(/locales\s*:\s*\[([^\]]*)\]/) || [])[1])
+    const def = (ni[1].match(/defaultLocale\s*:\s*['"`]([^'"`]+)/) || [])[1]
+    if (list.length) return { list: ordered(list, def), default: def || list[0], source: next.file, prefix: 'except-default' }
+  }
+  // next-intl, i18next routing files
+  const routing = await firstOf(root, ['src/i18n/routing.ts', 'src/i18n/routing.js', 'i18n/routing.ts', 'i18n/routing.js', 'src/i18n.ts', 'i18n.ts', 'src/i18n/config.ts', 'i18n/config.ts', 'src/middleware.ts', 'middleware.ts'])
+  const rl = routing?.text.match(/locales\s*:\s*\[([^\]]*)\]/) || routing?.text.match(/(?:export\s+)?const\s+locales\s*=\s*\[([^\]]*)\]/)
+  if (rl && listOf(rl[1]).length) {
+    const def = (routing.text.match(/defaultLocale\s*[:=]\s*['"`]([^'"`]+)/) || [])[1]
+    const prefix = /localePrefix\s*:\s*['"`](as-needed)['"`]/.test(routing.text) ? 'except-default' : /localePrefix\s*:\s*['"`]never['"`]/.test(routing.text) ? 'none' : 'always'
+    const list = listOf(rl[1])
+    return { list: ordered(list, def), default: def || list[0], source: routing.file, prefix }
+  }
+  // Nuxt i18n
+  const nuxt = framework?.id === 'nuxt' ? await firstOf(root, ['nuxt.config.ts', 'nuxt.config.js']) : null
+  const nx = nuxt?.text.match(/i18n\s*:\s*{([\s\S]*?)\n\s{0,4}}/)
+  if (nx) {
+    const block = nx[1]
+    const list = codesOf((block.match(/locales\s*:\s*\[([\s\S]*?)\]/) || [])[1])
+    const def = (block.match(/defaultLocale\s*:\s*['"`]([^'"`]+)/) || [])[1]
+    const strategy = (block.match(/strategy\s*:\s*['"`]([^'"`]+)/) || [])[1] || 'prefix_except_default'
+    if (list.length) return { list: ordered(list, def), default: def || list[0], source: nuxt.file, prefix: strategy === 'prefix' ? 'always' : strategy === 'no_prefix' ? 'none' : 'except-default' }
+  }
+  // Paraglide / inlang (SvelteKit and others)
+  const inlang = await read(root, 'project.inlang/settings.json')
+  if (inlang) {
+    try {
+      const s = JSON.parse(inlang); const list = s.locales || s.languageTags || []; const def = s.baseLocale || s.sourceLanguageTag
+      if (list.length) return { list: ordered(list, def), default: def || list[0], source: 'project.inlang/settings.json', prefix: 'except-default' }
+    } catch {}
+  }
+  // Rails
+  if (framework?.id === 'rails') {
+    const app = await read(root, 'config/application.rb') || ''
+    const avail = (app.match(/available_locales\s*=\s*\[([^\]]*)\]/) || [])[1]
+    const def = (app.match(/default_locale\s*=\s*:?['"]?([a-z]{2}(?:-[A-Z]{2})?)/) || [])[1]
+    let list = avail ? [...avail.matchAll(/:?['"]?([a-z]{2}(?:-[A-Z]{2})?)['"]?/g)].map((m) => m[1]) : []
+    if (!list.length) list = (await readdir(join(root, 'config/locales')).catch(() => [])).map((f) => f.replace(/\.(ya?ml|rb)$/, '')).filter((f) => LOCALE.test(f))
+    const routes = await read(root, 'config/routes.rb') || ''
+    if (list.length) return { list: ordered(list, def), default: def || list[0], source: avail ? 'config/application.rb' : 'config/locales', prefix: /scope\s+['"]\(?:locale\)?['"]|scope\s+['"]\/?:locale['"]/.test(routes) ? (/\(:locale\)/.test(routes) ? 'except-default' : 'always') : 'none' }
+  }
+  // message folders: messages/en.json, locales/cs.json, public/locales/en/…, src/locales/de.ts
+  for (const dir of ['messages', 'locales', 'lang', 'src/locales', 'src/messages', 'src/lang', 'public/locales', 'i18n', 'src/i18n']) {
+    const names = (await readdir(join(root, dir)).catch(() => [])).map((f) => f.replace(/\.(json|ya?ml|ts|js)$/, '')).filter((f) => LOCALE.test(f))
+    if (names.length) {
+      const appDir = await firstOf(root, ['app/[locale]/page.tsx', 'src/app/[locale]/page.tsx', 'app/[locale]/layout.tsx', 'src/app/[locale]/layout.tsx', 'app/[lang]/page.tsx', 'src/app/[lang]/page.tsx'])
+      return { list: ordered(names, names.includes('en') ? 'en' : null), default: names.includes('en') ? 'en' : names[0], source: dir, prefix: appDir ? 'always' : 'none' }
+    }
+  }
+  return null
+}
+
+const SOURCE_DIRS = ['app', 'src/app', 'pages', 'src/pages', 'src/routes', 'app/routes', 'app/pages']
+
+async function filesUnder (root, dir, out = [], depth = 0) {
+  if (depth > 8 || out.length > 5000) return out
+  let entries = []
+  try { entries = await readdir(join(root, dir), { withFileTypes: true }) } catch { return out }
+  for (const e of entries) {
+    const p = `${dir}/${e.name}`
+    if (e.isDirectory()) { if (!['node_modules', 'api', 'components', 'lib'].includes(e.name) && !e.name.startsWith('.')) await filesUnder(root, p, out, depth + 1) } else out.push(p)
+  }
+  return out
+}
+
+/** Static routes from route files (any locale segment removed) or Rails routes; '/' first, shallow before deep. */
+async function detectRoutes (root, framework) {
+  const found = new Map()
+  if (framework?.id === 'rails') {
+    const text = await read(root, 'config/routes.rb') || ''
+    if (/^\s*root\b/m.test(text)) found.set('/', 'config/routes.rb')
+    for (const m of text.matchAll(/^\s*(?:get|resources|resource)\s+[:'"]\/?([a-z][\w/-]*)['"]?/gm)) found.set('/' + m[1].replace(/_/g, '-'), 'config/routes.rb')
+  } else {
+    for (const dir of SOURCE_DIRS) {
+      for (const f of await filesUnder(root, dir)) {
+        if (!/\.(m?[jt]sx?|vue|svelte|astro|mdx?)$/.test(f) || /\/(_|\[\.\.\.)/.test(f) && !/\/\[(locale|lang)\]\//.test(f)) continue
+        const r = routeOf(f)
+        if (!r || r.scope !== 'page' || /\/api(\/|$)/.test(r.route)) continue
+        const route = r.route.replace(/^\/:(locale|lang|lng)(?=\/|$)/, '') || '/'
+        if (/[:*]/.test(route)) continue
+        if (!found.has(route)) found.set(route, f)
+      }
+    }
+  }
+  const skip = /^\/(api|admin|_|auth|oauth|callback|404|500|error)(\/|$)/
+  return [...found].filter(([p]) => !skip.test(p)).map(([path, file]) => ({ path, file })).sort((a, b) => (a.path === '/' ? -1 : b.path === '/' ? 1 : a.path.split('/').length - b.path.split('/').length || a.path.localeCompare(b.path)))
+}
+
+/** Everything init can tell about the project. */
+export async function detectProject (root) {
+  const stack = await detectStack(root)
+  const locales = await detectLocales(root, stack.framework)
+  const routes = await detectRoutes(root, stack.framework)
+  return { ...stack, locales, routes }
+}
+
+const words = (p) => p === '/' ? 'Home' : p.split('/').filter(Boolean).pop().replace(/[-_]+/g, ' ').replace(/^./, (c) => c.toUpperCase())
+const slug = (s) => String(s || '').toLowerCase().normalize('NFD').replace(/[̀-ͯ]/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40)
+
+/** A path per locale for the locale strategy: prefix always, except the default locale, or none. */
+export function localizedPath (path, locales) {
+  if (!locales || locales.prefix === 'none' || locales.list.length < 2) return path
+  return Object.fromEntries(locales.list.map((l) => [l, locales.prefix === 'except-default' && l === locales.default ? path : `/${l}${path === '/' ? '' : path}`]))
+}
+
+/** The first scenario: the main routes, one screen each, that a walk can open as they are. */
+export function initScenario (d, { max = 6, project = null } = {}) {
+  const routes = (d.routes.length ? d.routes : [{ path: '/', file: null }]).slice(0, max)
+  const name = project || d.name || 'app'
+  const ids = new Set()
+  const nodes = routes.map((r, i) => {
+    let id = r.path === '/' ? 'home' : slug(r.path) || `page-${i + 1}`
+    while (ids.has(id)) id += `-${i + 1}`
+    ids.add(id)
+    const title = words(r.path)
+    return {
+      id, kind: 'screen', title, path: localizedPath(r.path, d.locales),
+      purpose: `A visitor sees the ${title.toLowerCase()} page and can tell what to do next.`,
+      execution: i === 0
+        ? { strategy: 'playwright', script: 'steps/consent.mjs', instructions: `Open ${r.path} as a new visitor and accept the consent dialog if there is one.` }
+        : { strategy: 'playwright', script: 'steps/open.mjs', instructions: `Open ${r.path}.` },
+      criteria: [
+        { id: 'AC1', text: 'No errors in the browser console', check: { type: 'deterministic', assert: 'no_console_errors' } },
+        { id: 'AC2', text: 'The page makes its purpose clear', check: { type: 'semantic', question: `Does the first screen make clear what the ${title.toLowerCase()} page offers and what the visitor can do next?`, scope: 'main, body' } }
+      ]
+    }
+  })
+  return {
+    schema: 'qawalk.scenario.v1',
+    id: `${slug(name).toUpperCase() || 'APP'}-MAIN`,
+    title: `Main pages of ${name}`,
+    kind: 'flow', version: 1,
+    locales: d.locales?.list?.slice(0, 6) || ['en'],
+    viewports: { desktop: [1280, 800], mobile: [390, 844] },
+    environments: ['local'],
+    lanes: ['Visitor'],
+    nodes,
+    edges: nodes.slice(1).map((n) => ({ from: nodes[0].id, to: n.id, label: 'visit', kind: 'alt' }))
+  }
+}
+
+/** One paragraph for the terminal. */
+export function formatDetection (d, root) {
+  const lines = [`Detected ${d.framework ? d.framework.name : 'no known framework'}${d.command ? `; dev server: ${d.command}` : ''} → ${d.url}`]
+  if (d.locales) lines.push(`  locales: ${d.locales.list.join(', ')} (from ${d.locales.source}; ${d.locales.prefix === 'none' ? 'no locale in the URL' : d.locales.prefix === 'always' ? 'every locale prefixes the URL' : `/${d.locales.list.find((l) => l !== d.locales.default) || 'xx'}/… except ${d.locales.default}`})`)
+  else lines.push('  locales: none found in an i18n config (the scenario uses en)')
+  lines.push(d.routes.length ? `  routes: ${d.routes.slice(0, 8).map((r) => r.path).join(', ')}${d.routes.length > 8 ? `, +${d.routes.length - 8} more` : ''}` : '  routes: none found in route files (the scenario starts at /)')
+  return lines.join('\n')
+}
+

package/src/lib/onboarding.mjs

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