kaloko 0.4.10 → 0.4.11

package/src/lib/anim.mjs

@@ -0,0 +1,125 @@
+// Animated previews in pure Node: an animated WebP assembled from single-frame WebP images (the browser encodes each
+// frame, this only writes the container), and a GIF encoder for browsers that cannot encode WebP. Both stay small:
+// a preview is a few seconds of a step at thumbnail size.
+
+const chunk = (fourcc, payload) => {
+  const pad = payload.length % 2
+  const head = Buffer.alloc(8); head.write(fourcc, 0, 'ascii'); head.writeUInt32LE(payload.length, 4)
+  return Buffer.concat([head, payload, pad ? Buffer.alloc(1) : Buffer.alloc(0)])
+}
+const u24 = (n) => { const b = Buffer.alloc(3); b.writeUIntLE(n, 0, 3); return b }
+
+/** Chunks of a still WebP: { width, height, alpha, frame: Buffer of the ALPH + VP8/VP8L chunks }. */
+export function readWebp (buf) {
+  if (buf.toString('ascii', 0, 4) !== 'RIFF' || buf.toString('ascii', 8, 12) !== 'WEBP') throw new Error('not a WebP image')
+  let p = 12; let width = 0; let height = 0; let alpha = false
+  const keep = []
+  while (p + 8 <= buf.length) {
+    const fourcc = buf.toString('ascii', p, p + 4); const size = buf.readUInt32LE(p + 4)
+    const body = buf.subarray(p + 8, p + 8 + size)
+    if (fourcc === 'VP8X') { width = body.readUIntLE(4, 3) + 1; height = body.readUIntLE(7, 3) + 1 } else if (fourcc === 'ALPH') { alpha = true; keep.push(chunk('ALPH', body)) } else if (fourcc === 'VP8 ') {
+      // key frame header: 3-byte tag, start code 9d 01 2a, then 14-bit width and height
+      if (!width) { width = body.readUInt16LE(6) & 0x3fff; height = body.readUInt16LE(8) & 0x3fff }
+      keep.push(chunk('VP8 ', body))
+    } else if (fourcc === 'VP8L') {
+      if (!width) { const bits = body.readUInt32LE(1); width = (bits & 0x3fff) + 1; height = ((bits >>> 14) & 0x3fff) + 1; alpha = !!((bits >>> 28) & 1) }
+      keep.push(chunk('VP8L', body))
+    }
+    p += 8 + size + (size % 2)
+  }
+  if (!keep.length) throw new Error('WebP without image data')
+  return { width, height, alpha, frame: Buffer.concat(keep) }
+}
+
+/** frames: [{ webp: Buffer, ms }] → animated WebP looping forever. */
+export function animatedWebp (frames, { loop = 0, background = [255, 255, 255, 255] } = {}) {
+  if (!frames.length) throw new Error('no frames')
+  const parsed = frames.map((f) => ({ ...readWebp(f.webp), ms: Math.max(20, Math.round(f.ms)) }))
+  const W = Math.max(...parsed.map((f) => f.width)); const H = Math.max(...parsed.map((f) => f.height))
+  const alpha = parsed.some((f) => f.alpha)
+  const vp8x = Buffer.alloc(10); vp8x[0] = 0x02 | (alpha ? 0x10 : 0); vp8x.writeUIntLE(W - 1, 4, 3); vp8x.writeUIntLE(H - 1, 7, 3)
+  const anim = Buffer.alloc(6); anim[0] = background[2]; anim[1] = background[1]; anim[2] = background[0]; anim[3] = background[3]; anim.writeUInt16LE(loop, 4)
+  // each frame covers the canvas without blending (bit 1) and is kept until the next (no dispose)
+  const anmf = parsed.map((f) => chunk('ANMF', Buffer.concat([u24(0), u24(0), u24(f.width - 1), u24(f.height - 1), u24(Math.min(0xffffff, f.ms)), Buffer.from([0x02]), f.frame])))
+  const body = Buffer.concat([Buffer.from('WEBP'), chunk('VP8X', vp8x), chunk('ANIM', anim), ...anmf])
+  const head = Buffer.alloc(8); head.write('RIFF', 0, 'ascii'); head.writeUInt32LE(body.length, 4)
+  return Buffer.concat([head, body])
+}
+
+/** Frames and loop count of an animated WebP (tests). */
+export function webpFrames (buf) {
+  let p = 12; const out = []; let loop = null
+  while (p + 8 <= buf.length) {
+    const fourcc = buf.toString('ascii', p, p + 4); const size = buf.readUInt32LE(p + 4)
+    if (fourcc === 'ANIM') loop = buf.readUInt16LE(p + 12)
+    if (fourcc === 'ANMF') out.push({ width: buf.readUIntLE(p + 14, 3) + 1, height: buf.readUIntLE(p + 17, 3) + 1, ms: buf.readUIntLE(p + 20, 3) })
+    p += 8 + size + (size % 2)
+  }
+  return { loop, frames: out }
+}
+
+// ---------- GIF ----------
+// A fixed 6×7×6 colour cube (252 colours) plus four greys, with 4×4 ordered dithering: no per-frame palette search,
+// stable colours from frame to frame, and small files for flat UI screens.
+const LEVELS = [6, 7, 6]
+const PALETTE = (() => {
+  const p = []
+  for (let r = 0; r < 6; r++) for (let g = 0; g < 7; g++) for (let b = 0; b < 6; b++) p.push([Math.round(r * 255 / 5), Math.round(g * 255 / 6), Math.round(b * 255 / 5)])
+  for (const v of [32, 96, 160, 224]) p.push([v, v, v])
+  return p
+})()
+const BAYER = [0, 8, 2, 10, 12, 4, 14, 6, 3, 11, 1, 9, 15, 7, 13, 5].map((v) => (v + 0.5) / 16 - 0.5)
+
+/** RGBA pixels → palette indices of the colour cube, dithered. */
+export function quantize (rgba, width, height) {
+  const out = new Uint8Array(width * height)
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const i = y * width + x; const d = BAYER[(y & 3) * 4 + (x & 3)]
+      const q = (v, n) => Math.max(0, Math.min(n - 1, Math.round(v / 255 * (n - 1) + d)))
+      out[i] = q(rgba[i * 4], LEVELS[0]) * 42 + q(rgba[i * 4 + 1], LEVELS[1]) * 6 + q(rgba[i * 4 + 2], LEVELS[2])
+    }
+  }
+  return out
+}
+
+/** GIF LZW with 8-bit codes, packed into 255-byte sub-blocks. */
+export function lzw (indices, minCode = 8) {
+  const clear = 1 << minCode; const eoi = clear + 1
+  const bytes = []; let cur = 0; let nbits = 0
+  let size = minCode + 1; let next = eoi + 1
+  let dict = new Map()
+  const emit = (code) => { cur |= code << nbits; nbits += size; while (nbits >= 8) { bytes.push(cur & 0xff); cur >>>= 8; nbits -= 8 } }
+  emit(clear)
+  let prefix = indices[0]
+  for (let i = 1; i < indices.length; i++) {
+    const k = indices[i]; const key = prefix * 256 + k
+    const hit = dict.get(key)
+    if (hit !== undefined) { prefix = hit; continue }
+    emit(prefix)
+    if (next < 4096) { dict.set(key, next++); if (next > (1 << size) && size < 12) size++ } else { emit(clear); dict = new Map(); size = minCode + 1; next = eoi + 1 }
+    prefix = k
+  }
+  emit(prefix); emit(eoi)
+  if (nbits > 0) bytes.push(cur & 0xff)
+  const out = [minCode]
+  for (let i = 0; i < bytes.length; i += 255) { const n = Math.min(255, bytes.length - i); out.push(n, ...bytes.slice(i, i + n)) }
+  out.push(0)
+  return Buffer.from(out)
+}
+
+/** frames: [{ rgba, ms }] of one size → looping GIF. */
+export function encodeGif (frames, { width, height, loop = 0 }) {
+  const parts = [Buffer.from('GIF89a')]
+  const lsd = Buffer.alloc(7); lsd.writeUInt16LE(width, 0); lsd.writeUInt16LE(height, 2); lsd[4] = 0xf7; parts.push(lsd) // global table of 256
+  const table = Buffer.alloc(256 * 3); PALETTE.forEach(([r, g, b], i) => { table[i * 3] = r; table[i * 3 + 1] = g; table[i * 3 + 2] = b }); parts.push(table)
+  parts.push(Buffer.from([0x21, 0xff, 0x0b, ...Buffer.from('NETSCAPE2.0'), 0x03, 0x01, loop & 0xff, loop >> 8, 0x00]))
+  for (const f of frames) {
+    const delay = Math.max(2, Math.round(f.ms / 10))
+    parts.push(Buffer.from([0x21, 0xf9, 0x04, 0x04, delay & 0xff, delay >> 8, 0x00, 0x00]))
+    const desc = Buffer.alloc(10); desc[0] = 0x2c; desc.writeUInt16LE(width, 5); desc.writeUInt16LE(height, 7); parts.push(desc)
+    parts.push(lzw(quantize(f.rgba, width, height)))
+  }
+  parts.push(Buffer.from([0x3b]))
+  return Buffer.concat(parts)
+}

package/src/lib/apps/recording-native.mjs

@@ -0,0 +1,212 @@
+// Recordings of native app steps (batch D): the device or the desktop records itself while the step runs.
+//   android   adb shell screenrecord, in segments (the tool stops after 3 minutes), touches shown while recording
+//   ios       xcrun simctl io <device> recordVideo (H.264)
+//   desktop   macOS screencapture -v with clicks shown (needs Screen Recording permission)
+// Electron windows are web pages and use the screencast recorder (recording.mjs).
+// Each finished clip is MP4 H.264, which every browser plays; ffmpeg joins segments, remuxes the macOS .mov and makes
+// the poster and preview. Taps the step script made through the driver are kept as markers for the canvas.
+import { mkdir, rm, rename, writeFile, stat, copyFile } from 'node:fs/promises'
+import { join, dirname } from 'node:path'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { startProcess, ffmpeg, mediaDuration, stillsFromVideo, videoTools, installHint } from '../video.mjs'
+import { recBase, saveRecording, stepRecorded, parseRecord } from '../recording.mjs'
+import { addCapture, runPaths } from '../run.mjs'
+import { writeJson } from '../util.mjs'
+import { summarizeTrace } from '../trace.mjs'
+
+const run = promisify(execFile)
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+/** screenrecord stops at 180 s; segments a little shorter leave time to start the next one. */
+export const ANDROID_SEGMENT = 170
+const ANDROID_BITRATE = { low: 2_000_000, medium: 4_000_000, high: 8_000_000 }
+
+/** Shell arguments of one Android segment (tests read them). */
+export function screenrecordArgs ({ serial, file, quality = 'medium', seconds = ANDROID_SEGMENT }) {
+  return [...(serial ? ['-s', serial] : []), 'shell', 'screenrecord', '--time-limit', String(Math.min(180, seconds)), '--bit-rate', String(ANDROID_BITRATE[quality] || ANDROID_BITRATE.medium), file]
+}
+
+/** The booted simulator a config means (udid, device name, or the first booted one), as the iOS driver picks it. */
+export async function bootedSimulator (cfg = {}, exec = run) {
+  const { stdout } = await exec('xcrun', ['simctl', 'list', 'devices', 'booted', '-j'])
+  const all = Object.values(JSON.parse(stdout).devices || {}).flat()
+  const dev = cfg.udid ? all.find((d) => d.udid === cfg.udid) : cfg.device ? all.find((d) => d.name === cfg.device) : all[0]
+  return dev?.udid || null
+}
+
+/**
+ * One recorder for one step: start() before the step, stop() at its capture → { file (.mp4 or .mov), source } or null.
+ * `tools` from videoTools(). Throws nothing: a recording that cannot start leaves `reason`.
+ */
+export function nativeRecorder ({ platform, cfg = {}, tools, quality = 'medium', maxSeconds = 60, tmp }) {
+  const r = { platform, reason: null, segments: [], child: null, started: 0 }
+  if (platform === 'android') {
+    const adb = cfg.adb || process.env.KALOKO_ADB || 'adb'
+    const serial = cfg.serial || process.env.ANDROID_SERIAL || null
+    let n = 0; let stopping = false; let showTouches = null
+    const shell = (...a) => run(adb, [...(serial ? ['-s', serial] : []), 'shell', ...a], { timeout: 20000 })
+    const next = () => {
+      const remote = `/sdcard/kaloko-rec-${process.pid}-${Date.now().toString(36)}-${n++}.mp4`
+      r.segments.push(remote)
+      const left = Math.max(1, Math.ceil(maxSeconds - (Date.now() - r.started) / 1000))
+      r.child = startProcess(adb, screenrecordArgs({ serial, file: remote, quality, seconds: Math.min(ANDROID_SEGMENT, left) }))
+      r.child.done.then(() => { if (!stopping && (Date.now() - r.started) / 1000 < maxSeconds - 1) next() })
+    }
+    r.start = async () => {
+      if (!tools.adb) { r.reason = `adb is not installed (${installHint('adb')})`; return false }
+      showTouches = (await shell('settings', 'get', 'system', 'show_touches').catch(() => ({ stdout: '' }))).stdout.trim()
+      await shell('settings', 'put', 'system', 'show_touches', '1').catch(() => {})
+      r.started = Date.now(); next(); await sleep(700)
+      return true
+    }
+    r.stop = async () => {
+      stopping = true
+      await shell('pkill', '-INT', 'screenrecord').catch(() => {})
+      await Promise.race([r.child?.done, sleep(6000)])
+      if (showTouches !== '1') await shell('settings', 'put', 'system', 'show_touches', showTouches || '0').catch(() => {})
+      await sleep(400) // the device finishes writing the file
+      const local = []
+      for (const [i, remote] of r.segments.entries()) {
+        const f = join(tmp, `seg${i}.mp4`)
+        try { await run(adb, [...(serial ? ['-s', serial] : []), 'pull', remote, f], { timeout: 120000 }); local.push(f) } catch {}
+        await shell('rm', '-f', remote).catch(() => {})
+      }
+      if (!local.length) { r.reason = 'the device kept no recording'; return null }
+      return { file: await joinSegments(tools, local, join(tmp, 'android.mp4')), source: 'adb', segments: local.length }
+    }
+  } else if (platform === 'ios') {
+    let file = null
+    r.start = async () => {
+      if (!tools.simctl) { r.reason = `simctl is missing (${installHint('simctl', 'darwin')})`; return false }
+      const udid = await bootedSimulator(cfg).catch(() => null)
+      if (!udid) { r.reason = 'no booted iOS Simulator'; return false }
+      file = join(tmp, 'ios.mp4')
+      r.child = startProcess('xcrun', ['simctl', 'io', udid, 'recordVideo', '--codec=h264', '--force', file])
+      r.started = Date.now()
+      // simctl says when the first frame is in; a step that starts before would miss its beginning
+      for (let i = 0; i < 50 && !/Recording started/i.test(r.child.output()); i++) await sleep(100)
+      return true
+    }
+    r.stop = async () => {
+      r.child?.kill('SIGINT')
+      await Promise.race([r.child?.done, sleep(8000)])
+      return (await stat(file).catch(() => null))?.size ? { file, source: 'simctl' } : null
+    }
+  } else if (platform === 'desktop') {
+    let file = null
+    r.start = async () => {
+      if (process.platform !== 'darwin') { r.reason = 'desktop recording needs macOS'; return false }
+      file = join(tmp, 'desktop.mov')
+      // -v video, -C cursor, -k clicks, -x no sound, -V the longest it may take
+      r.child = startProcess('/usr/sbin/screencapture', ['-v', '-C', '-k', '-x', '-V', String(Math.max(2, Math.round(maxSeconds))), file])
+      r.started = Date.now(); await sleep(800)
+      return true
+    }
+    r.stop = async () => {
+      r.child?.kill('SIGINT')
+      await Promise.race([r.child?.done, sleep(8000)])
+      if (!(await stat(file).catch(() => null))?.size) { r.reason = 'screencapture kept no recording (allow Screen Recording for this terminal in System Settings → Privacy & Security)'; return null }
+      if (!tools.ffmpeg) { r.reason = `the macOS recording is QuickTime (.mov); ffmpeg turns it into MP4 for the canvas (${installHint('ffmpeg', 'darwin')})`; return { file, source: 'screencapture', mov: true } }
+      const mp4 = join(tmp, 'desktop.mp4')
+      try { await ffmpeg(tools, ['-i', file, '-c:v', 'copy', '-movflags', '+faststart', '-an', mp4]) } catch { await ffmpeg(tools, ['-i', file, '-c:v', tools.ffmpeg.encoders.h264 || 'libx264', '-pix_fmt', 'yuv420p', '-movflags', '+faststart', '-an', mp4]) }
+      return { file: mp4, source: 'screencapture' }
+    }
+  } else {
+    r.start = async () => { r.reason = `no native recorder for ${platform}`; return false }
+    r.stop = async () => null
+  }
+  return r
+}
+
+/** Segments of one recording as one MP4: ffmpeg concatenates them; without ffmpeg the last segment is kept. */
+export async function joinSegments (tools, files, out) {
+  if (files.length === 1) { await rename(files[0], out); return out }
+  if (!tools.ffmpeg) { await rename(files.at(-1), out); return out }
+  const list = join(dirname(out), 'segments.txt')
+  await writeFile(list, files.map((f) => `file '${f.replaceAll("'", "'\\''")}'`).join('\n') + '\n')
+  await ffmpeg(tools, ['-f', 'concat', '-safe', '0', '-i', list, '-c', 'copy', '-movflags', '+faststart', out])
+  return out
+}
+
+/**
+ * The driver with its interactions logged ({ t, type, target }) for the trace and the tap markers; typed text is
+ * never kept, only its length.
+ */
+export function instrumentDriver (driver, log) {
+  const wrap = (name, describe) => {
+    const fn = driver[name]
+    if (typeof fn !== 'function') return
+    driver[name] = async (...a) => { log.push({ t: Date.now(), type: name, ...describe(...a) }); return fn.apply(driver, a) }
+  }
+  wrap('tap', (target) => (target && typeof target === 'object' && target.x != null ? { x: target.x, y: target.y } : { target: String(target ?? '').slice(0, 120) }))
+  wrap('type', (text) => ({ target: `${String(text ?? '').length} characters` }))
+  wrap('back', () => ({}))
+  wrap('link', (url) => ({ url: String(url ?? '').slice(0, 300) }))
+  wrap('swipe', (...a) => ({ target: a.map((x) => typeof x === 'object' ? JSON.stringify(x) : String(x)).join(' ').slice(0, 120) }))
+  return driver
+}
+
+/**
+ * Per locale of an app walk (android, ios, desktop): beforeStep(node) starts the device recording when the step is
+ * recorded; afterStep(node, { record, error }) stops it, stores the MP4, poster, preview, taps and a trace of the
+ * driver's actions. `encoder` returns a Chrome page for the WebP preview (optional).
+ */
+export async function nativeSession ({ platform, env, run, scenario, locale, settings, driver, encoder, say = () => {} }) {
+  const anyRecord = !!settings.record || scenario.nodes.some((n) => parseRecord(n.record ?? n.capture?.record))
+  if (!anyRecord && !settings.trace) return null
+  const tools = anyRecord ? await videoTools() : {}
+  const actions = []
+  instrumentDriver(driver, actions)
+  const cfg = env.app?.[platform] || {}
+  let cur = null
+  const notes = new Set()
+  return {
+    async beforeStep (node) {
+      actions.length = 0
+      cur = { node, t0: Date.now(), t1: null, rec: null }
+      const want = settings.record?.mode === 'flow' ? { ...settings.record, mode: 'step' } : stepRecorded(settings, node)
+      if (!want) return
+      const tmp = join(run.dir, '.rec-tmp', `${node.id}-${locale}`)
+      await mkdir(tmp, { recursive: true })
+      const r = nativeRecorder({ platform, cfg, tools, quality: want.quality, maxSeconds: want.max_seconds || 60, tmp })
+      if (await r.start()) cur.rec = { r, want, tmp }
+      else if (r.reason) notes.add(`recording ${platform}: ${r.reason}`)
+    },
+    async beforeCapture () { if (cur && !cur.t1) { cur.t1 = Date.now(); if (cur.rec) cur.clip = await cur.rec.r.stop().catch(() => null) } },
+    async afterStep (node, { record = null, error = null } = {}) {
+      if (!cur || cur.node !== node) return
+      const { t0, rec } = cur
+      const t1 = cur.t1 || Date.now()
+      const clip = cur.clip !== undefined ? cur.clip : rec ? await rec.r.stop().catch(() => null) : null
+      cur = null
+      const vp = record?.viewport || Object.keys(run.meta.scope.viewports || {})[0] || 'phone'
+      const failed = !!error || Object.values(record?.checks || {}).some((c) => c?.ok === false)
+      const size = record?.size?.viewport || null
+      if (settings.trace) {
+        const file = runPaths(run.dir).step(node.id, locale, vp, 'trace.json')
+        const trace = { schema: 'qawalk.trace.v1', node: node.id, locale, viewport: vp, platform, started_at: new Date(t0).toISOString(), duration_ms: t1 - t0, actions: actions.filter((a) => a.t <= t1).map((a) => ({ ...a, t: Math.max(0, a.t - t0) })), network: [], console: [] }
+        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: file.slice(run.dir.length + 1), captured_at: record?.captured_at || null, at: new Date().toISOString() })
+      }
+      if (!rec) return
+      try {
+        if (!clip || (rec.want.mode === 'failed' && !failed)) { if (!clip && rec.r.reason) notes.add(`recording ${platform}: ${rec.r.reason}`); return }
+        const base = recBase(run.dir, node.id, locale, vp)
+        await mkdir(dirname(base), { recursive: true })
+        if (clip.mov) { await copyFile(clip.file, `${base}.mov`); notes.add(rec.r.reason); return }
+        await copyFile(clip.file, `${base}.mp4`)
+        const duration = (tools.ffmpeg && await mediaDuration(tools, `${base}.mp4`)) || (t1 - t0)
+        const stills = await stillsFromVideo({ tools, page: await encoder?.(), file: `${base}.mp4`, out: base, quality: rec.want.quality, duration })
+        const files = { mp4: `${base}.mp4`, ...(stills.poster ? { poster: stills.poster } : {}), ...(stills.preview ? { preview: stills.preview } : {}) }
+        const bytes = {}
+        for (const [k, f] of Object.entries(files)) bytes[k] = (await stat(f)).size
+        // taps with coordinates, as fractions of the screen, relative to the clip
+        const taps = size ? actions.filter((a) => a.type === 'tap' && a.x != null && a.t <= t1).map((a) => ({ t: Math.max(0, a.t - t0), x: +(a.x / size[0]).toFixed(4), y: +(a.y / size[1]).toFixed(4) })) : []
+        await saveRecording({ run, node, locale, viewport: vp, result: { files, bytes, duration_ms: duration, width: null, height: null, codec: 'h264' }, mode: rec.want.mode, failed, error, captured_at: record?.captured_at || null, taps, source: clip.source })
+      } catch (e) { notes.add(`recording ${platform}: ${String(e.message).split('\n')[0]}`) } finally { await rm(rec.tmp, { recursive: true, force: true }) }
+    },
+    async finish () { await rm(join(run.dir, '.rec-tmp'), { recursive: true, force: true }); return [...notes].filter(Boolean).map((n) => `${n} (${locale})`) }
+  }
+}

package/src/lib/build.mjs

@@ -17,6 +17,7 @@ export async function buildManifest ({ run, scenario, config, root, catalog = []
   const entries = await readCaptures(run.dir)
   const captures = latestCaptures(entries)
   const attachments = entries.filter((e) => e.type === 'attachment')
+  const media = entries.filter((e) => e.type === 'trace' || e.type === 'recording' || e.type === 'walkthrough')
   const pos = new Map(layout(scenario).map((p) => [p.id, p]))
   const locales = meta.scope.locales
   const viewportNames = Object.keys(meta.scope.viewports)
@@ -36,7 +37,9 @@ export async function buildManifest ({ run, scenario, config, root, catalog = []
     }
     // focus screenshots of the keyboard walk (#19): only those of the current captures, not of earlier walks
     const shots = new Set(caps.flatMap((c) => (c.cap.keyboard?.shots || []).map((s) => s.file)))
-    nodes.push(assembleNode({ node, pos: pos.get(node.id), locales, viewportNames, captures: caps, attachments: attachments.filter((a) => a.node === node.id && (a.kind !== 'focus' || shots.has(a.file))) }))
+    const out = assembleNode({ node, pos: pos.get(node.id), locales, viewportNames, captures: caps, attachments: attachments.filter((a) => a.node === node.id && (a.kind !== 'focus' || shots.has(a.file))) })
+    await attachMedia(out, { run, entries: media, captures: caps })
+    nodes.push(out)
   }
   const summary = summarize(nodes, scenario.sessions)
 
@@ -79,10 +82,62 @@ export async function buildManifest ({ run, scenario, config, root, catalog = []
     summary,
     coverage: cov,
     history,
-    catalog
+    catalog,
+    ...(await runMedia({ run, entries: media }))
   }
 }
 
+/** The recording entry of a sidecar as the manifest carries it: file paths, duration, size, markers. */
+async function recEntry (run, e) {
+  const r = await readJson(join(run.dir, e.file), null)
+  if (!r?.files || !Object.values(r.files).some(Boolean)) return null
+  const files = Object.fromEntries(Object.entries(r.files).filter(([k, f]) => f && ['webm', 'mp4', 'preview', 'poster'].includes(k) && existsSync(join(run.dir, f))))
+  if (!files.webm && !files.mp4) return null
+  return { ...files, duration_ms: r.duration_ms, ...(r.width ? { size: [r.width, r.height] } : {}), codec: r.codec || null, mode: r.mode, source: r.source || null, bytes: Object.values(r.bytes || {}).reduce((n, b) => n + (b || 0), 0), ...(r.failed ? { failed: true } : {}), ...(r.error ? { error: r.error } : {}), ...(r.trimmed ? { trimmed: true } : {}), ...(r.offset_ms ? { offset_ms: r.offset_ms } : {}), ...(r.taps?.length ? { taps: r.taps.slice(0, 200) } : {}), ...(r.chapters ? { chapters: r.chapters } : {}) }
+}
+
+/**
+ * Traces and recordings of a step's captures (batch D, #12): each capture gets the trace and recording made in the
+ * same walk (matched by captured_at), `trace_summary` for the canvas, MCP and the CLI; a step whose script failed
+ * before its capture keeps its recording under `recordings`.
+ */
+async function attachMedia (node, { run, entries, captures }) {
+  const mine = entries.filter((e) => e.node === node.id && !e.scope)
+  if (!mine.length) return
+  const latest = (type, c) => mine.filter((e) => e.type === type && e.locale === c.locale && e.viewport === c.viewport && e.captured_at && e.captured_at === c.cap.captured_at).pop()
+  for (const c of captures) {
+    const out = node.captures?.[c.locale]?.[c.viewport]
+    if (!out) continue
+    const t = latest('trace', c)
+    if (t) {
+      const trace = await readJson(join(run.dir, t.file), null)
+      if (trace) { out.trace = t.file; out.trace_summary = trace.summary || null }
+    }
+    const r = latest('recording', c)
+    if (r) { const rec = await recEntry(run, r); if (rec) out.rec = rec }
+  }
+  // recordings of failed attempts newer than the step's capture in that locale and viewport
+  const failed = []
+  for (const e of mine.filter((x) => x.type === 'recording' && !x.captured_at)) {
+    const cap = captures.find((c) => c.locale === e.locale && c.viewport === e.viewport)
+    if (cap && cap.cap.captured_at > e.at) continue
+    const rec = await recEntry(run, e)
+    if (rec) failed.push({ locale: e.locale, viewport: e.viewport, ...rec })
+  }
+  if (failed.length) node.recordings = failed.slice(-4)
+}
+
+/** Run-level media: flow recordings per locale with their chapters, and the exported walkthrough video. */
+async function runMedia ({ run, entries }) {
+  const out = {}
+  const flows = {}
+  for (const e of entries.filter((x) => x.type === 'recording' && x.scope === 'flow')) { const rec = await recEntry(run, e); if (rec) flows[e.locale] = { viewport: e.viewport, ...rec } }
+  if (Object.keys(flows).length) out.recordings = { flow: flows }
+  const w = entries.filter((x) => x.type === 'walkthrough' && existsSync(join(run.dir, x.file))).pop()
+  if (w) out.walkthrough = { file: w.file, format: w.format, duration_ms: w.duration_ms ?? null, bytes: w.bytes ?? null, locale: w.locale || null, viewport: w.viewport || null, steps: w.steps ?? null }
+  return out
+}
+
 
 /**
  * A stack step: its pages go to steps/<node>/items.json (qawalk.stack.v1: fields, criteria, and per page the path,
@@ -160,10 +215,11 @@ export async function writePreview ({ run, manifest }) {
   const template = await readFile(join(packageRoot, 'viewer', 'index.html'), 'utf8')
   // the local preview opens from file://, where fetch cannot read files: stack indexes go inline
   // file:// cannot fetch: stack indexes and app UI trees travel inside the preview
+  // traces of steps (#12) too: the Technical tab reads them without a request
   const withTrees = async (n) => {
-    if (!Object.values(n.captures || {}).some((vps) => Object.values(vps).some((c) => c?.tree || c?.spec))) return n
+    if (!Object.values(n.captures || {}).some((vps) => Object.values(vps).some((c) => c?.tree || c?.spec || c?.trace))) return n
     const captures = {}
-    for (const [l, vps] of Object.entries(n.captures)) { captures[l] = {}; for (const [vp, c] of Object.entries(vps)) captures[l][vp] = c?.tree || c?.spec ? { ...c, ...(c.tree ? { tree_inline: await readJson(join(run.dir, c.tree), null) } : {}), ...(c.spec ? { spec_inline: await readJson(join(run.dir, c.spec), null) } : {}) } : c }
+    for (const [l, vps] of Object.entries(n.captures)) { captures[l] = {}; for (const [vp, c] of Object.entries(vps)) captures[l][vp] = c?.tree || c?.spec || c?.trace ? { ...c, ...(c.tree ? { tree_inline: await readJson(join(run.dir, c.tree), null) } : {}), ...(c.spec ? { spec_inline: await readJson(join(run.dir, c.spec), null) } : {}), ...(c.trace ? { trace_inline: await readJson(join(run.dir, c.trace), null) } : {}) } : c }
     return { ...n, captures }
   }
   // design runs: live steps open from the merged tree, where links between steps resolve (design.mjs copyLive)

package/src/lib/doctor.mjs

@@ -11,6 +11,7 @@ import { portFor } from './browser.mjs'
 import { DEFAULTS as JEV } from './jev.mjs'
 import { visionSettings, VISION_WEIGHT } from './vision-core.mjs'
 import { serviceUrl } from './service.mjs'
+import { videoTools, recordingChecks } from './video.mjs'
 
 const portFree = (port) => new Promise((done) => {
   const s = createServer().once('error', () => done(false)).once('listening', () => s.close(() => done(true)))
@@ -33,7 +34,7 @@ async function reach (url, fetchImpl, ms = 6000, headers = {}) {
  * @param {Function} [o.launchChrome] async () => { version } — throws when Chrome is missing
  * @param {object} [o.env] process.env
  */
-export async function doctor ({ config, root, file = null, fetchImpl = fetch, launchChrome = defaultLaunch, env = process.env, fix = false }) {
+export async function doctor ({ config, root, file = null, fetchImpl = fetch, launchChrome = defaultLaunch, env = process.env, fix = false, videoToolsImpl = null }) {
   const checks = []
   const add = (name, ok, detail = '', hint = '') => checks.push({ name, ok, detail, hint })
 
@@ -144,6 +145,9 @@ export async function doctor ({ config, root, file = null, fetchImpl = fetch, la
   else if (token && vision.hosted !== false) add('vision evaluator', true, `via Kaloko · model ${vision.model} · one vision question counts as ${VISION_WEIGHT}`)
   else add('vision evaluator', true, `${vision.api_key_env} not set (optional)`, `Criteria with vision: true and unsure answers stay with a person until ${vision.api_key_env} is set or ${tokenEnv} lets the service ask.`)
 
+  // recordings (batch D): ffmpeg and the device recorders, with install hints per OS
+  checks.push(...recordingChecks({ config, tools: await (videoToolsImpl || videoTools)() }))
+
   return { ok: checks.every((c) => c.ok), checks }
 }
 

package/src/lib/import.mjs

@@ -363,7 +363,7 @@ export async function attachImported ({ run, node, locale, item }) {
   return entry
 }
 
-/** Recordings are kept in the run folder (imported/), not uploaded: the canvas does not play them yet. */
+/** 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)]) {