kaloko 0.4.9 → 0.4.11

package/src/lib/recording.mjs

@@ -0,0 +1,373 @@
+// Recordings and traces of walked steps (batch D, #12). A web or Electron page is observed over one CDP session:
+// Page.startScreencast frames (JPEG, at most the preset's frame rate, written to a temporary folder), pointer and
+// input events from a page hook, and Network/console events for the trace. The walk calls four hooks per step:
+//   beforeStep(node) → beforeCapture(node) → afterStep(node, { records, error }) … finish()
+// A step's clip runs from the start of its script to the moment it is captured (the interaction from the previous
+// state to this one); a flow recording runs over the whole walk of a locale with a chapter per step.
+// Opt-in: `walk --record [step|flow|failed]`, config/scenario `capture.record`, per step `record: true`.
+import { mkdir, mkdtemp, writeFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join, relative, dirname } from 'node:path'
+import { writeJson, localized } from './util.mjs'
+import { addCapture, runPaths } from './run.mjs'
+import { encodeClip, preset, MAX_SECONDS } from './video.mjs'
+import { PAGE_HOOK, networkEntries, actionEntries, summarizeTrace, cleanText, TRACE_LIMITS } from './trace.mjs'
+
+export const RECORD_MODES = ['step', 'flow', 'failed']
+const QUALITIES = ['low', 'medium', 'high']
+
+/** `record` as written anywhere (true, 'flow', { mode, quality, … }) → { mode, quality, max_seconds, codec, mp4 } or null. */
+export function parseRecord (v) {
+  if (v == null || v === false || v === 'off' || v === 'false' || v === 'none') return v == null ? undefined : null
+  if (v === true || v === 'true' || v === '') return { mode: 'step' }
+  if (typeof v === 'string') return RECORD_MODES.includes(v) ? { mode: v } : undefined
+  if (typeof v === 'object') {
+    const o = {}
+    if (v.mode === false || v.mode === 'off') return null
+    o.mode = RECORD_MODES.includes(v.mode) ? v.mode : 'step'
+    if (QUALITIES.includes(v.quality)) o.quality = v.quality
+    if (Number(v.max_seconds) > 0) o.max_seconds = Math.min(3600, Number(v.max_seconds))
+    if (['auto', 'vp9', 'av1', 'h264'].includes(v.codec)) o.codec = v.codec
+    if (v.mp4 != null) o.mp4 = v.mp4 === true || v.mp4 === 'true' ? true : v.mp4 === false || v.mp4 === 'false' ? false : 'auto'
+    if (v.cursor === false) o.cursor = false
+    return o
+  }
+  return undefined
+}
+
+/**
+ * Recording and trace settings of a walk: CLI over scenario over config. { record: {…} | null, trace: boolean }.
+ * --record [step|flow|failed|off], --record-quality, --no-trace; capture.record / capture.trace in the config and the
+ * scenario.
+ */
+export function recordSettings ({ args = {}, config = {}, scenario = {} } = {}) {
+  const layers = [config.capture?.record, scenario.capture?.record, args.record === undefined ? undefined : args.record]
+  let record = null
+  for (const l of layers) {
+    const p = parseRecord(l)
+    if (p === undefined) continue
+    record = p === null ? null : { ...(record || {}), ...p }
+  }
+  if (record && QUALITIES.includes(args['record-quality'])) record.quality = args['record-quality']
+  if (record) { record.quality ||= 'medium'; record.max_seconds ||= MAX_SECONDS[record.mode === 'flow' ? 'flow' : 'step'] }
+  const trace = !args['no-trace'] && args.trace !== false && config.capture?.trace !== false && scenario.capture?.trace !== false
+  return { record, trace }
+}
+
+/** Whether one step is recorded: per step `record: true|false` (or capture.record) wins over the walk's mode. */
+export function stepRecorded (settings, node) {
+  const own = parseRecord(node?.record ?? node?.capture?.record)
+  if (own === null) return null
+  if (own) return { quality: 'medium', max_seconds: MAX_SECONDS.step, ...(settings.record || {}), ...own, mode: settings.record?.mode === 'flow' ? 'flow' : own.mode || 'step' }
+  return settings.record
+}
+
+/** Width and height of a JPEG from its SOF marker. */
+export function jpegSize (buf) {
+  let p = 2
+  while (p + 9 < buf.length) {
+    if (buf[p] !== 0xff) { p++; continue }
+    const m = buf[p + 1]; const len = buf.readUInt16BE(p + 2)
+    if (m >= 0xc0 && m <= 0xcf && ![0xc4, 0xc8, 0xcc].includes(m)) return [buf.readUInt16BE(p + 7), buf.readUInt16BE(p + 5)]
+    p += 2 + len
+  }
+  return null
+}
+
+/**
+ * Observes a Chromium page over CDP. screencast: frames for recordings; trace: network, console, actions.
+ * Returns null where CDP is not available (Firefox, WebKit): such walks are neither recorded nor traced.
+ */
+export async function observePage (page, { screencast = false, trace = true, quality = 'medium' } = {}) {
+  let cdp
+  try { cdp = await page.context().newCDPSession(page) } catch { return null }
+  const P = preset(quality)
+  const dir = screencast ? await mkdtemp(join(tmpdir(), 'kaloko-frames-')) : null
+  const o = { frames: [], events: [], requests: new Map(), console: [], navigations: [], dir, cdp, closed: false }
+  let seq = 0; let lastKept = 0; let pending = null; let timer = null; let writing = Promise.resolve()
+  const minGap = 1000 / P.fps
+  const keep = (f) => {
+    const buf = Buffer.from(f.data, 'base64')
+    const size = jpegSize(buf) || [f.metadata.deviceWidth, f.metadata.deviceHeight]
+    const file = join(dir, `${String(seq++).padStart(6, '0')}.jpg`)
+    const t = f.metadata.timestamp ? Math.round(f.metadata.timestamp * 1000) : Date.now()
+    o.frames.push({ t, file, w: size[0], h: size[1], dw: f.metadata.deviceWidth || size[0], ot: f.metadata.offsetTop || 0 })
+    lastKept = t
+    writing = writing.then(() => writeFile(file, buf)).catch(() => {})
+  }
+  const on = (event, fn) => cdp.on(event, (e) => { try { fn(e) } catch {} })
+  on('Runtime.bindingCalled', (e) => { if (e.name !== '__kalokoRec') return; const ev = JSON.parse(e.payload); if (o.events.length < 20000) o.events.push(ev) })
+  if (screencast) {
+    on('Page.screencastFrame', (f) => {
+      cdp.send('Page.screencastFrameAck', { sessionId: f.sessionId }).catch(() => {})
+      const t = f.metadata.timestamp ? f.metadata.timestamp * 1000 : Date.now()
+      // at most the preset's frame rate: a frame that comes too soon waits, and is replaced by a newer one
+      if (t - lastKept >= minGap) { pending = null; keep(f); return }
+      pending = f
+      if (!timer) timer = setTimeout(() => { timer = null; if (pending) { const p = pending; pending = null; keep(p) } }, minGap)
+    })
+  }
+  if (trace) {
+    let base = null // wall clock minus the monotonic clock of network timestamps
+    const wall = (ts) => base == null ? Date.now() : Math.round((ts + base) * 1000)
+    on('Network.requestWillBeSent', (e) => {
+      if (e.wallTime) base = e.wallTime - e.timestamp
+      if (o.requests.size >= TRACE_LIMITS.network * 4) return
+      const prev = o.requests.get(e.requestId)
+      if (prev && e.redirectResponse) { prev.status = e.redirectResponse.status; prev.end = wall(e.timestamp); o.requests.set(`${e.requestId}:${prev.start}`, prev) }
+      o.requests.set(e.requestId, { method: e.request.method, url: e.request.url, type: e.type, start: wall(e.timestamp) })
+    })
+    on('Network.responseReceived', (e) => { const r = o.requests.get(e.requestId); if (r) { r.status = e.response.status; r.mime = e.response.mimeType; r.fromCache = !!(e.response.fromDiskCache || e.response.fromServiceWorker) } })
+    on('Network.loadingFinished', (e) => { const r = o.requests.get(e.requestId); if (r) { r.bytes = Math.round(e.encodedDataLength); r.end = wall(e.timestamp) } })
+    on('Network.loadingFailed', (e) => { const r = o.requests.get(e.requestId); if (r) { r.failed = e.blockedReason ? `blocked: ${e.blockedReason}` : e.canceled ? 'canceled' : e.errorText; r.end = wall(e.timestamp) } })
+    on('Runtime.consoleAPICalled', (e) => { if (String(e.args?.[0]?.value || '').startsWith('--playwright')) return; if (o.console.length < TRACE_LIMITS.console * 4) o.console.push({ t: Math.round(e.timestamp), level: e.type === 'warning' ? 'warn' : ['error', 'assert'].includes(e.type) ? 'error' : e.type, text: cleanText((e.args || []).map((a) => a.value ?? a.description ?? a.type).join(' ')) }) })
+    on('Log.entryAdded', (e) => { if (o.console.length < TRACE_LIMITS.console * 4) o.console.push({ t: Math.round(e.entry.timestamp), level: e.entry.level === 'warning' ? 'warn' : e.entry.level, text: cleanText(e.entry.text), source: e.entry.source }) })
+    on('Page.frameNavigated', (e) => { if (!e.frame.parentId) o.navigations.push({ t: Date.now(), url: e.frame.url }) })
+  }
+  try {
+    await cdp.send('Runtime.enable')
+    await cdp.send('Page.enable')
+    await cdp.send('Runtime.addBinding', { name: '__kalokoRec' })
+    const { identifier } = await cdp.send('Page.addScriptToEvaluateOnNewDocument', { source: PAGE_HOOK })
+    o.scriptId = identifier
+    await cdp.send('Runtime.evaluate', { expression: PAGE_HOOK }).catch(() => {})
+    if (trace) { await cdp.send('Network.enable', { maxTotalBufferSize: 1_000_000, maxResourceBufferSize: 0 }); await cdp.send('Log.enable').catch(() => {}) }
+    if (screencast) await cdp.send('Page.startScreencast', { format: 'jpeg', quality: P.jpeg, maxWidth: P.width, maxHeight: Math.round(P.width * 2.2), everyNthFrame: 1 })
+  } catch {
+    await cdp.detach().catch(() => {})
+    if (dir) await rm(dir, { recursive: true, force: true })
+    return null
+  }
+  o.flush = async () => { if (pending) { const p = pending; pending = null; keep(p) } await writing }
+  /** Frames, pointer events (in frame pixels) and labels between two moments; the frame on screen at `from` too. */
+  o.clip = (from, to) => {
+    let first = 0
+    while (first + 1 < o.frames.length && o.frames[first + 1].t <= from) first++
+    const frames = o.frames.slice(first).filter((f, i) => i === 0 || f.t <= to)
+    const ref = frames[0]
+    const k = ref ? ref.w / ref.dw : 1
+    const events = o.events.filter((e) => e.t >= from - 4000 && e.t <= to && ['move', 'down', 'up', 'click'].includes(e.k) && e.x != null).map((e) => ({ t: e.t, type: e.k === 'click' ? 'move' : e.k, x: e.x * k, y: (e.y + (ref?.ot || 0)) * k }))
+    return { frames, events }
+  }
+  /** Trace between two moments (ms epoch). */
+  o.trace = (from, to) => ({
+    actions: actionEntries(o.events, o.navigations, from, to),
+    network: networkEntries(o.requests, from, to),
+    console: o.console.filter((c) => c.t >= from - 50 && c.t <= to).slice(0, TRACE_LIMITS.console).map((c) => ({ ...c, t: Math.max(0, c.t - from) }))
+  })
+  /** Forgets what happened before `t` (frames on disk too, except the one on screen at `t`). */
+  o.prune = async (t) => {
+    await writing
+    let keepFrom = 0
+    while (keepFrom + 1 < o.frames.length && o.frames[keepFrom + 1].t <= t) keepFrom++
+    const gone = o.frames.splice(0, keepFrom)
+    for (const f of gone) await rm(f.file, { force: true })
+    o.events = o.events.filter((e) => e.t >= t - 4000)
+    for (const [id, r] of o.requests) if ((r.end ?? r.start) < t) o.requests.delete(id)
+    o.console = o.console.filter((c) => c.t >= t)
+    o.navigations = o.navigations.filter((n) => n.t >= t)
+  }
+  o.stop = async () => {
+    if (o.closed) return
+    o.closed = true
+    if (timer) clearTimeout(timer)
+    await o.flush().catch(() => {})
+    if (screencast) await cdp.send('Page.stopScreencast').catch(() => {})
+    if (o.scriptId) await cdp.send('Page.removeScriptToEvaluateOnNewDocument', { identifier: o.scriptId }).catch(() => {})
+    await cdp.send('Runtime.removeBinding', { name: '__kalokoRec' }).catch(() => {})
+    await cdp.detach().catch(() => {})
+  }
+  o.cleanup = async () => { await o.stop(); if (dir) await rm(dir, { recursive: true, force: true }) }
+  return o
+}
+
+/** Paths of a step's recording files (without extension: .webm, .mp4, .webp/.gif, .poster.webp, .json). */
+export const recBase = (runDir, nodeId, locale, viewport) => runPaths(runDir).step(nodeId, locale, viewport, 'rec')
+export const flowBase = (runDir, locale) => join(runDir, 'attachments', 'flow', `${locale}.rec`)
+
+/** Viewport name of a page size among the walk's viewports (first match by width), else the first captured one. */
+function viewportOf (viewports, width, records) {
+  const hit = Object.entries(viewports || {}).find(([, [w]]) => w === width)
+  return hit?.[0] || records?.[0]?.viewport || Object.keys(viewports || {})[0] || 'desktop'
+}
+
+const failedRecord = (records) => (records || []).some((r) => Object.values(r.checks || {}).some((c) => c?.ok === false))
+
+/**
+ * One locale's walk on one page: per step trace and recording, and the flow recording. `encoder` is an async
+ * function returning a page to encode in (a headless Chrome of its own, started on first use).
+ * settings: recordSettings(); viewports: the walk's scope viewports; say: progress lines.
+ */
+export async function recordingSession ({ page, run, scenario, locale, settings, viewports, encoder, say = () => {}, label = 'walk' }) {
+  const anyRecord = !!settings.record || scenario.nodes.some((n) => parseRecord(n.record ?? n.capture?.record))
+  if (!anyRecord && !settings.trace) return null
+  const flow = settings.record?.mode === 'flow'
+  const quality = settings.record?.quality || 'medium'
+  const obs = await observePage(page, { screencast: anyRecord, trace: settings.trace, quality })
+  if (!obs) { if (anyRecord) say(`Recording skipped (${label}): it needs a Chromium-based browser (Chrome, Edge, Electron).`); return null }
+  const steps = new Map()
+  const chapters = []
+  let queue = Promise.resolve()
+  const notes = new Set()
+  const enqueue = (job) => { queue = queue.then(job).catch((e) => notes.add(`recording: ${String(e.message).split('\n')[0]}`)); return queue }
+
+  const writeTrace = async (node, vp, t0, t1, records) => {
+    const tr = obs.trace(t0, t1)
+    const file = runPaths(run.dir).step(node.id, locale, vp, 'trace.json')
+    const trace = { schema: 'qawalk.trace.v1', node: node.id, locale, viewport: vp, started_at: new Date(t0).toISOString(), duration_ms: Math.max(0, t1 - t0), ...tr }
+    trace.summary = summarizeTrace(trace)
+    await mkdir(dirname(file), { recursive: true })
+    await writeJson(file, trace)
+    await addCapture(run.dir, { type: 'trace', node: node.id, locale, viewport: vp, file: relative(run.dir, file), captured_at: records?.[0]?.captured_at || null, at: new Date().toISOString() })
+  }
+
+  return {
+    observer: obs,
+    beforeStep (node) { steps.set(node.id, { t0: Date.now(), t1: null }) },
+    beforeCapture (node) { const s = steps.get(node.id); if (s && !s.t1) s.t1 = Date.now() },
+    async afterStep (node, { records = null, error = null } = {}) {
+      const s = steps.get(node.id); if (!s) return
+      steps.delete(node.id)
+      const t2 = Date.now()
+      const t1 = s.t1 || t2
+      await obs.flush()
+      const failed = !!error || failedRecord(records)
+      const frameW = obs.frames.at(-1)?.dw || page.viewportSize?.()?.width
+      const vp = records?.length ? (records.find((r) => viewports?.[r.viewport]?.[0] === frameW) || records[0]).viewport : viewportOf(viewports, frameW, records)
+      if (settings.trace) await writeTrace(node, vp, s.t0, error ? t2 : t1, records).catch((e) => notes.add(`trace: ${e.message}`))
+      const want = stepRecorded(settings, node)
+      if (flow) { chapters.push({ node: node.id, title: localized(node.title, locale) || node.id, start: s.t0, capture: t1, end: t2, status: failed ? 'fail' : 'ok' }); return }
+      const keepClip = want && (want.mode !== 'failed' || failed)
+      if (!keepClip) { await obs.prune(t2); return }
+      const clip = obs.clip(s.t0, error ? t2 : t1)
+      // the frames stay on disk until the encoder has them; pruning waits in the same queue
+      enqueue(async () => {
+        const base = recBase(run.dir, node.id, locale, vp)
+        await mkdir(dirname(base), { recursive: true })
+        const r = await encodeClip({ page: await encoder(), frames: clip.frames, events: want.cursor === false ? [] : clip.events, start: s.t0, end: error ? t2 : t1, out: base, quality: want.quality, maxSeconds: want.max_seconds, codec: want.codec || 'auto', mp4: want.mp4 ?? 'auto' })
+        // offset_ms: where the clip starts after the step's start (a trimmed long step keeps its end); the trace aligns by it
+        if (r) await saveRecording({ run, node, locale, viewport: vp, result: { ...r, offset_ms: Math.max(0, Math.round(r.start - s.t0)) }, mode: want.mode, failed, error, captured_at: records?.[0]?.captured_at || null, source: 'screencast' })
+        for (const n of r?.notes || []) notes.add(n)
+        await obs.prune(t2)
+      })
+    },
+    async finish () {
+      await queue
+      if (flow && chapters.length) {
+        await obs.flush()
+        const t0 = chapters[0].start; const t1 = chapters.at(-1).end
+        const clip = obs.clip(t0, t1)
+        const labels = chapters.map((c, i) => ({ t: c.start, text: `${i + 1} · ${c.title}` }))
+        const base = flowBase(run.dir, locale)
+        await mkdir(dirname(base), { recursive: true })
+        try {
+          const r = await encodeClip({ page: await encoder(), frames: clip.frames, events: settings.record.cursor === false ? [] : clip.events, labels, start: t0, end: t1, out: base, quality, maxSeconds: settings.record.max_seconds, codec: settings.record.codec || 'auto', mp4: settings.record.mp4 ?? 'auto' })
+          if (r) {
+            const off = r.start
+            const info = await saveRecording({ run, node: null, locale, viewport: viewportOf(viewports, clip.frames[0]?.dw, null), result: r, mode: 'flow', chapters: chapters.map((c) => ({ node: c.node, title: c.title, start: Math.max(0, c.start - off), capture: Math.max(0, c.capture - off), end: Math.max(0, c.end - off), status: c.status })), source: 'screencast' })
+            say(`Flow recording ${locale}: ${Math.round(r.duration_ms / 1000)} s, ${chapters.length} chapters → ${relative(run.dir, info.file)}`)
+          }
+          for (const n of r?.notes || []) notes.add(n)
+        } catch (e) { notes.add(`flow recording: ${String(e.message).split('\n')[0]}`) }
+      }
+      await obs.cleanup()
+      return [...notes]
+    }
+  }
+}
+
+/** Writes the recording's sidecar (qawalk.recording.v1) and its captures.jsonl entry; returns { file, info }. */
+export async function saveRecording ({ run, node, locale, viewport, result, mode, failed = false, error = null, captured_at = null, chapters = null, taps = null, source }) {
+  const rel = (f) => (f ? relative(run.dir, f) : null)
+  const files = Object.fromEntries(Object.entries(result.files || {}).map(([k, f]) => [k, rel(f)]))
+  const base = node ? recBase(run.dir, node.id, locale, viewport) : flowBase(run.dir, locale)
+  const info = {
+    schema: 'qawalk.recording.v1',
+    ...(node ? { node: node.id } : { scope: 'flow' }),
+    locale,
+    viewport,
+    mode,
+    source,
+    ...(failed ? { failed: true } : {}),
+    ...(error ? { error: String(error.message || error).split('\n')[0].slice(0, 300) } : {}),
+    captured_at,
+    recorded_at: new Date().toISOString(),
+    duration_ms: result.duration_ms,
+    width: result.width,
+    height: result.height,
+    fps: result.fps || null,
+    codec: result.codec,
+    ...(result.trimmed ? { trimmed: true } : {}),
+    ...(result.offset_ms ? { offset_ms: result.offset_ms } : {}),
+    files,
+    bytes: result.bytes || {},
+    ...(chapters ? { chapters } : {}),
+    ...(taps?.length ? { taps } : {})
+  }
+  const file = `${base}.json`
+  await mkdir(dirname(file), { recursive: true })
+  await writeJson(file, info)
+  await addCapture(run.dir, { type: 'recording', ...(node ? { node: node.id } : { scope: 'flow' }), locale, viewport, file: relative(run.dir, file), captured_at, ...(failed ? { failed: true } : {}), at: info.recorded_at })
+  return { file, info }
+}
+
+/** Recording files a manifest names (step captures, failed attempts, flow recordings, the walkthrough). */
+export function recordingFiles (manifest) {
+  const out = new Set()
+  const add = (r) => { for (const k of ['webm', 'mp4', 'preview', 'poster']) if (r?.[k]) out.add(r[k]) }
+  for (const n of manifest.nodes || []) {
+    for (const vps of Object.values(n.captures || {})) for (const c of Object.values(vps || {})) add(c?.rec)
+    for (const r of n.recordings || []) add(r)
+  }
+  for (const r of Object.values(manifest.recordings?.flow || {})) add(r)
+  if (manifest.walkthrough?.file) out.add(manifest.walkthrough.file)
+  return [...out]
+}
+
+/** Trace files a manifest names (shared on every plan: they are small JSON). */
+export function traceFiles (manifest) {
+  const out = new Set()
+  for (const n of manifest.nodes || []) for (const vps of Object.values(n.captures || {})) for (const c of Object.values(vps || {})) if (c?.trace) out.add(c.trace)
+  return [...out]
+}
+
+/** The manifest without recordings (plans without the recordings feature share screenshots and traces only). */
+export function stripRecordings (manifest) {
+  const nodes = (manifest.nodes || []).map((n) => {
+    const { recordings, ...rest } = n
+    if (!rest.captures) return rest
+    const captures = Object.fromEntries(Object.entries(rest.captures).map(([l, vps]) => [l, Object.fromEntries(Object.entries(vps || {}).map(([vp, c]) => {
+      if (!c?.rec) return [vp, c]
+      const { rec, ...keep } = c
+      return [vp, keep]
+    }))]))
+    return { ...rest, captures }
+  })
+  const m = { ...manifest, nodes }
+  delete m.recordings
+  delete m.walkthrough
+  return m
+}
+
+/** The manifest without the recordings that use any of `paths` (each such recording goes as a whole). */
+export function withoutRecordings (manifest, paths) {
+  const uses = (r) => r && ['webm', 'mp4', 'preview', 'poster'].some((k) => r[k] && paths.has(r[k]))
+  const nodes = (manifest.nodes || []).map((n) => {
+    const captures = Object.fromEntries(Object.entries(n.captures || {}).map(([l, vps]) => [l, Object.fromEntries(Object.entries(vps || {}).map(([vp, c]) => {
+      if (!uses(c?.rec)) return [vp, c]
+      const { rec, ...keep } = c
+      return [vp, keep]
+    }))]))
+    const recs = (n.recordings || []).filter((r) => !uses(r))
+    const out = { ...n, captures }
+    if (n.recordings) { if (recs.length) out.recordings = recs; else delete out.recordings }
+    return out
+  })
+  const m = { ...manifest, nodes }
+  if (manifest.recordings?.flow) {
+    const flow = Object.fromEntries(Object.entries(manifest.recordings.flow).filter(([, r]) => !uses(r)))
+    if (Object.keys(flow).length) m.recordings = { ...manifest.recordings, flow }; else delete m.recordings
+  }
+  if (manifest.walkthrough?.file && paths.has(manifest.walkthrough.file)) delete m.walkthrough
+  return m
+}

package/src/lib/scenario.mjs

@@ -31,7 +31,8 @@ export function validateScenario (data) {
     if (node.kind === 'stack' && node.items && ['urls', 'file', 'sitemap', 'crawl', 'script'].filter((k) => node.items[k]).length !== 1) problems.push(`node "${node.id}": items needs exactly one source of urls, file, sitemap, crawl or script`)
     if (node.kind !== 'stack' && (node.items || node.fields)) problems.push(`node "${node.id}": items and fields belong to stack steps`)
     // app screens are reached by a script or a person as often as by a deep link
-    if (node.kind === 'screen' && !node.path && (!data.platform || data.platform === 'web')) problems.push(`node "${node.id}": screen steps need a path`)
+    // a manual screen may have no path: a person (or an imported walkthrough) shows how to get there
+    if (node.kind === 'screen' && !node.path && (!data.platform || data.platform === 'web') && node.execution?.strategy !== 'manual') problems.push(`node "${node.id}": screen steps need a path`)
     if (node.kind === 'stack' && data.platform && data.platform !== 'web') problems.push(`node "${node.id}": stack steps list web pages; they are not available on platform ${data.platform}`)
     if (node.kind === 'email' && !node.mail) problems.push(`node "${node.id}": email steps need mail.subject`)
   }

package/src/lib/service.mjs

@@ -43,7 +43,13 @@ export function service (config) {
     },
     async upload (path, data, name, extra = {}) {
       for (let attempt = 0; ; attempt++) {
-        const res = await limited(() => fetch(base + path, { method: 'PUT', headers: { ...headers, ...extra }, body: data }))
+        // a dropped connection (flaky Wi-Fi, CI runner hiccup) is tried again like a 5xx; the next share resumes otherwise
+        let res
+        try { res = await limited(() => fetch(base + path, { method: 'PUT', headers: { ...headers, ...extra }, body: data })) } catch (e) {
+          if (attempt >= 3) throw new UserError(`upload ${name}: ${e.cause?.code || e.message}. Run kaloko share again: files already stored are not sent twice.`)
+          await new Promise((r) => setTimeout(r, 1000 * (attempt + 1)))
+          continue
+        }
         if (res.ok || attempt >= 2 || res.status < 500) return check(res, `upload ${name}`)
         await new Promise((r) => setTimeout(r, 1000 * (attempt + 1)))
       }

package/src/lib/trace.mjs

@@ -0,0 +1,109 @@
+// Trace per step (#12): a light, Playwright-trace-like record of what happened between the previous capture and this
+// one: actions (clicks, typing into fields, keys, navigations), network requests with status, size and timing, and
+// console messages. Collected from CDP events while the step runs (recording.mjs) and stored as
+// steps/<node>/<locale>/<viewport>.trace.json (qawalk.trace.v1). Field values and typed characters are never kept.
+import { redact } from './secrets.mjs'
+
+export const TRACE_LIMITS = { network: 600, console: 200, actions: 300, url: 400, text: 500 }
+
+/** A URL as stored: secrets the CLI knows removed, values of credential-like query parameters masked, length capped. */
+export function cleanUrl (u) {
+  let s = redact(String(u || ''))
+  try {
+    const url = new URL(s)
+    for (const k of [...url.searchParams.keys()]) if (/token|secret|password|passwd|auth|key|session|code|sig/i.test(k)) url.searchParams.set(k, '***')
+    s = url.href
+  } catch {}
+  return s.length > TRACE_LIMITS.url ? s.slice(0, TRACE_LIMITS.url) + '…' : s
+}
+
+/** Console text as stored: known secrets removed, credential-like query values in URLs masked. */
+export const cleanText = (t) => redact(String(t ?? '')).replace(/([?&;](?:[\w-]*(?:token|secret|password|passwd|auth|key|session|code|sig)[\w-]*)=)[^&\s'"#]+/gi, '$1***').slice(0, TRACE_LIMITS.text)
+
+/** Network entries from CDP Network.* events (already joined per request id), relative to `t0` (ms epoch). */
+export function networkEntries (requests, t0, t1 = Infinity) {
+  return [...requests.values()]
+    .filter((r) => r.start >= t0 - 50 && r.start <= t1)
+    .sort((a, b) => a.start - b.start)
+    .slice(0, TRACE_LIMITS.network)
+    .map((r) => ({
+      t: Math.max(0, Math.round(r.start - t0)),
+      method: r.method,
+      url: cleanUrl(r.url),
+      type: r.type || null,
+      status: r.status ?? null,
+      bytes: r.bytes ?? null,
+      ms: r.end != null ? Math.max(0, Math.round(r.end - r.start)) : null,
+      ...(r.failed ? { failed: String(r.failed).slice(0, 120) } : {}),
+      ...(r.mime ? { mime: r.mime } : {}),
+      ...(r.fromCache ? { cache: true } : {})
+    }))
+}
+
+/** Summary for the manifest and MCP: counts, failed requests, errors, bytes, the slowest request. */
+export function summarizeTrace (trace) {
+  const net = trace?.network || []
+  // a request the page cancelled itself (a favicon, a navigation away) is not a failure
+  const failed = net.filter((r) => (r.failed && r.failed !== 'canceled') || (r.status != null && r.status >= 400))
+  const slowest = net.filter((r) => r.ms != null).sort((a, b) => b.ms - a.ms)[0] || null
+  return {
+    duration_ms: trace?.duration_ms ?? null,
+    actions: (trace?.actions || []).length,
+    requests: net.length,
+    failed_requests: failed.length,
+    bytes: net.reduce((n, r) => n + (r.bytes || 0), 0),
+    console_errors: (trace?.console || []).filter((c) => c.level === 'error').length,
+    console: (trace?.console || []).length,
+    ...(slowest ? { slowest: { url: slowest.url, ms: slowest.ms, status: slowest.status } } : {}),
+    ...(failed.length ? { failed: failed.slice(0, 5).map((r) => ({ method: r.method, url: r.url, status: r.status, ...(r.failed ? { error: r.failed } : {}) })) } : {})
+  }
+}
+
+/** One line per entry for the terminal (`kaloko video trace`), in time order. */
+export function formatTrace (trace, { max = 60 } = {}) {
+  const rows = [
+    ...(trace.actions || []).map((a) => ({ t: a.t, s: `action   ${a.type}${a.target ? ` ${a.target}` : ''}${a.url ? ` ${a.url}` : ''}` })),
+    ...(trace.network || []).map((r) => ({ t: r.t, s: `${r.failed || r.status >= 400 ? 'network ✕' : 'network  '} ${r.method} ${r.status ?? '—'} ${r.url}${r.ms != null ? ` ${r.ms} ms` : ''}${r.bytes ? ` ${Math.round(r.bytes / 1024)} kB` : ''}${r.failed ? ` (${r.failed})` : ''}` })),
+    ...(trace.console || []).map((c) => ({ t: c.t, s: `console  ${c.level}: ${c.text}` }))
+  ].sort((a, b) => a.t - b.t)
+  const lines = rows.slice(0, max).map((r) => `${String(r.t).padStart(6)} ms  ${r.s}`)
+  if (rows.length > max) lines.push(`… ${rows.length - max} more`)
+  return lines.join('\n')
+}
+
+/**
+ * Script injected into every document of a recorded or traced page: reports pointer positions, clicks, field edits,
+ * named keys, submits and scrolls to the binding `__kalokoRec` (no field values, no typed characters).
+ */
+export const PAGE_HOOK = `(() => {
+  if (window.__kalokoHooked || typeof window.__kalokoRec !== 'function') return; window.__kalokoHooked = true
+  const send = (e) => { try { window.__kalokoRec(JSON.stringify({ ...e, t: Date.now() })) } catch {} }
+  const name = (el) => {
+    if (!el || el.nodeType !== 1) return ''
+    const tag = el.tagName.toLowerCase(); const role = el.getAttribute('role')
+    const label = el.getAttribute('aria-label') || (el.labels && el.labels[0] && el.labels[0].innerText) || el.getAttribute('name') || el.getAttribute('placeholder') || el.getAttribute('title') || (/^(input|textarea|select)$/.test(tag) ? '' : (el.innerText || el.value || ''))
+    return ((role || tag) + (el.id && !/\\d{4,}/.test(el.id) ? '#' + el.id : '') + (label ? ' "' + String(label).trim().replace(/\\s+/g, ' ').slice(0, 60) + '"' : '')).slice(0, 120)
+  }
+  const target = (el) => el && el.closest ? (el.closest('a,button,input,select,textarea,label,summary,[role=button],[role=link],[role=tab],[role=menuitem],[role=option],[role=checkbox],[onclick]') || el) : el
+  let last = 0
+  addEventListener('pointermove', (e) => { const n = performance.now(); if (n - last < 40) return; last = n; send({ k: 'move', x: e.clientX, y: e.clientY }) }, { capture: true, passive: true })
+  addEventListener('pointerdown', (e) => send({ k: 'down', x: e.clientX, y: e.clientY }), { capture: true, passive: true })
+  addEventListener('pointerup', (e) => send({ k: 'up', x: e.clientX, y: e.clientY }), { capture: true, passive: true })
+  addEventListener('click', (e) => send({ k: 'click', x: e.clientX, y: e.clientY, d: name(target(e.target)) }), { capture: true, passive: true })
+  addEventListener('change', (e) => { const el = e.target; const type = (el.type || '').toLowerCase(); send({ k: type === 'checkbox' || type === 'radio' ? (el.checked ? 'check' : 'uncheck') : el.tagName === 'SELECT' ? 'select' : 'fill', d: name(el) }) }, { capture: true, passive: true })
+  addEventListener('keydown', (e) => { if (e.key && e.key.length > 1 && !/^(Shift|Control|Alt|Meta|CapsLock)$/.test(e.key)) send({ k: 'key', key: e.key, d: name(e.target) }) }, { capture: true, passive: true })
+  addEventListener('submit', (e) => send({ k: 'submit', d: name(e.target) }), { capture: true, passive: true })
+  let sc = 0
+  addEventListener('scroll', () => { const n = performance.now(); if (n - sc < 400) return; sc = n; send({ k: 'scroll', y: Math.round(scrollY) }) }, { capture: true, passive: true })
+})()`
+
+/** Actions of the trace from page hook events and navigations, relative to `t0`. Pointer moves are left out. */
+export function actionEntries (events, navigations, t0, t1 = Infinity) {
+  const acts = []
+  for (const e of events) {
+    if (e.t < t0 - 50 || e.t > t1 || ['move', 'down', 'up'].includes(e.k)) continue
+    acts.push({ t: Math.max(0, Math.round(e.t - t0)), type: e.k === 'key' ? `key ${e.key}` : e.k, ...(e.d ? { target: e.d } : {}), ...(e.k === 'scroll' ? { y: e.y } : {}) })
+  }
+  for (const n of navigations) if (n.t >= t0 - 50 && n.t <= t1) acts.push({ t: Math.max(0, Math.round(n.t - t0)), type: 'navigate', url: cleanUrl(n.url) })
+  return acts.sort((a, b) => a.t - b.t).slice(0, TRACE_LIMITS.actions)
+}

package/src/lib/unzip.mjs

@@ -0,0 +1,31 @@
+// Minimal ZIP reader for `kaloko import` (Playwright traces and the report embedded in an HTML report): stored and
+// deflated entries from the central directory. No ZIP64; entries are read when asked for.
+import { inflateRawSync } from 'node:zlib'
+
+/** Entries of a zip archive: Map name → () => Buffer. */
+export function readZip (buf) {
+  let eocd = -1
+  for (let i = buf.length - 22; i >= Math.max(0, buf.length - 65557); i--) if (buf.readUInt32LE(i) === 0x06054b50) { eocd = i; break }
+  if (eocd < 0) throw new Error('not a zip archive (no end of central directory)')
+  const count = buf.readUInt16LE(eocd + 10)
+  let at = buf.readUInt32LE(eocd + 16)
+  const out = new Map()
+  for (let n = 0; n < count; n++) {
+    if (buf.readUInt32LE(at) !== 0x02014b50) throw new Error('broken zip central directory')
+    const method = buf.readUInt16LE(at + 10)
+    const size = buf.readUInt32LE(at + 20)
+    const nameLen = buf.readUInt16LE(at + 28); const extraLen = buf.readUInt16LE(at + 30); const commentLen = buf.readUInt16LE(at + 32)
+    const local = buf.readUInt32LE(at + 42)
+    const name = buf.subarray(at + 46, at + 46 + nameLen).toString('utf8')
+    at += 46 + nameLen + extraLen + commentLen
+    if (name.endsWith('/')) continue
+    out.set(name, () => {
+      const start = local + 30 + buf.readUInt16LE(local + 26) + buf.readUInt16LE(local + 28)
+      const data = buf.subarray(start, start + size)
+      if (method === 0) return Buffer.from(data)
+      if (method === 8) return inflateRawSync(data)
+      throw new Error(`${name}: unsupported compression method ${method}`)
+    })
+  }
+  return out
+}