kaloko 0.4.10 → 0.4.11

package/src/lib/video-cli.mjs

@@ -0,0 +1,209 @@
+/* global MediaRecorder, createImageBitmap, requestAnimationFrame */
+// `kaloko video …` (batch D, #23): the walkthrough video of a run (step recordings stitched with a title card per
+// step: its title and verdict), recordings and traces of a run, and what this machine can record with.
+import { mkdtemp, rm, writeFile, stat, mkdir } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join, resolve, relative, dirname } from 'node:path'
+import { resolveRun, addCapture } from './run.mjs'
+import { loadScenario } from './scenario.mjs'
+import { buildManifest } from './build.mjs'
+import { launchEphemeral } from './browser.mjs'
+import { readJson, localized, UserError } from './util.mjs'
+import { videoTools, encoderCaps, ffmpeg, preset, installHint, outputSize } from './video.mjs'
+import { formatTrace } from './trace.mjs'
+
+const FORMATS = ['mp4', 'webm', 'gif']
+const VERDICT = {
+  en: { pass: 'Passed', fail: 'Failed', partial: 'Partly passed', skip: 'Not walked', step: (i, n) => `Step ${i} of ${n}` },
+  cs: { pass: 'Splněno', fail: 'Nesplněno', partial: 'Splněno zčásti', skip: 'Nekontrolováno', step: (i, n) => `Krok ${i} z ${n}` }
+}
+const fmtSize = (n) => n >= 1048576 ? `${(n / 1048576).toFixed(1)} MB` : `${Math.round(n / 1024)} kB`
+const flowOrder = (nodes) => nodes.filter((n) => n.kind !== 'decision' && n.kind !== 'stack').sort((a, b) => a.col - b.col || a.lane - b.lane)
+
+/**
+ * The segments of a walkthrough in flow order for one locale and viewport: a step's own recording, or its chapter of
+ * the flow recording. [{ node, title, status, file, from, to }] (from/to in seconds, null for the whole file).
+ */
+export function walkthroughPlan (manifest, { locale, viewport = null, steps = null } = {}) {
+  const loc = locale || manifest.scope?.locales?.[0]
+  const flow = manifest.recordings?.flow?.[loc]
+  const out = []
+  for (const n of flowOrder(manifest.nodes || [])) {
+    if (steps && !steps.includes(n.id)) continue
+    const vps = n.captures?.[loc] || {}
+    const vp = viewport && vps[viewport]?.rec ? viewport : Object.keys(vps).find((v) => vps[v]?.rec && (!viewport || v === viewport))
+    const rec = vp ? vps[vp].rec : (n.recordings || []).find((r) => r.locale === loc && (!viewport || r.viewport === viewport))
+    const status = n.by_locale?.[loc] || n.status || 'skip'
+    const title = localized(n.title, loc) || n.id
+    if (rec) { out.push({ node: n.id, title, status, file: rec.mp4 || rec.webm, from: null, to: null }); continue }
+    const ch = flow?.chapters?.find((c) => c.node === n.id)
+    if (ch) out.push({ node: n.id, title, status, file: flow.mp4 || flow.webm, from: ch.start / 1000, to: ch.capture / 1000 })
+  }
+  return out
+}
+
+/** ffmpeg arguments that stitch title cards and clips into one file. */
+export function stitchArgs ({ parts, out, format, width, height, fps, card = 1.6, encoders = {} }) {
+  const inputs = []; const filters = []; let k = 0
+  for (const p of parts) {
+    if (p.card) inputs.push('-loop', '1', '-t', String(card), '-framerate', String(fps), '-i', p.card)
+    else inputs.push(...(p.from != null ? ['-ss', p.from.toFixed(3)] : []), ...(p.to != null ? ['-to', p.to.toFixed(3)] : []), '-i', p.file)
+    filters.push(`[${k}:v]scale=${width}:${height}:force_original_aspect_ratio=decrease,pad=${width}:${height}:(ow-iw)/2:(oh-ih)/2:color=0x151514,fps=${fps},format=yuv420p,setsar=1[v${k}]`)
+    k++
+  }
+  const joined = `${parts.map((_, i) => `[v${i}]`).join('')}concat=n=${parts.length}:v=1:a=0[out]`
+  if (format === 'gif') return [...inputs, '-filter_complex', `${filters.join(';')};${joined};[out]split[a][b];[a]palettegen=max_colors=128[p];[b][p]paletteuse=dither=bayer[g]`, '-map', '[g]', '-loop', '0', out]
+  const codec = format === 'webm'
+    ? ['-c:v', encoders.vp9 || 'libvpx-vp9', '-deadline', 'good', '-cpu-used', '5', '-row-mt', '1', '-b:v', '0', '-crf', '36']
+    : encoders.h264 === 'libx264' || !encoders.h264 ? ['-c:v', 'libx264', '-preset', 'medium', '-crf', '26', '-movflags', '+faststart'] : ['-c:v', encoders.h264, '-b:v', '2M', '-movflags', '+faststart']
+  return [...inputs, '-filter_complex', `${filters.join(';')};${joined}`, '-map', '[out]', '-an', ...codec, '-g', String(fps * 2), out]
+}
+
+/** Without ffmpeg: the browser plays the clips and title cards onto a canvas and MediaRecorder keeps it (real time). */
+async function stitchInBrowser (page, { parts, width, height, fps, card }) {
+  const clips = []
+  for (const p of parts) {
+    if (p.card) clips.push({ card: p.cardData, ms: card * 1000 })
+    else clips.push({ video: (await import('node:fs/promises').then((fs) => fs.readFile(p.file))).toString('base64'), type: p.file.endsWith('.mp4') ? 'video/mp4' : 'video/webm', from: p.from, to: p.to })
+  }
+  return page.evaluate(async ({ clips, width, height, fps }) => {
+    const canvas = document.createElement('canvas'); canvas.width = width; canvas.height = height; document.body.append(canvas)
+    const g = canvas.getContext('2d')
+    const fromB64 = (s) => Uint8Array.from(atob(s), (c) => c.charCodeAt(0))
+    const stream = canvas.captureStream(fps)
+    const type = ['video/webm;codecs=vp9', 'video/webm;codecs=vp8', 'video/webm'].find((t) => MediaRecorder.isTypeSupported(t))
+    const rec = new MediaRecorder(stream, { mimeType: type, videoBitsPerSecond: 1_500_000 })
+    const chunks = []; rec.ondataavailable = (e) => { if (e.data.size) chunks.push(e.data) }
+    const fit = (w, h) => { const k = Math.min(width / w, height / h); return [(width - w * k) / 2, (height - h * k) / 2, w * k, h * k] }
+    rec.start(500)
+    for (const c of clips) {
+      g.fillStyle = '#151514'; g.fillRect(0, 0, width, height)
+      if (c.card) {
+        const bm = await createImageBitmap(new Blob([fromB64(c.card)], { type: 'image/png' }))
+        const end = performance.now() + c.ms
+        while (performance.now() < end) { g.drawImage(bm, 0, 0, width, height); await new Promise((resolve) => requestAnimationFrame(resolve)) }
+        continue
+      }
+      const v = document.createElement('video'); v.muted = true; v.playsInline = true
+      v.src = URL.createObjectURL(new Blob([fromB64(c.video)], { type: c.type }))
+      await new Promise((resolve, reject) => { v.onloadeddata = resolve; v.onerror = reject })
+      if (c.from != null) { v.currentTime = c.from; await new Promise((resolve) => { v.onseeked = resolve }) }
+      await v.play()
+      while (!v.ended && (c.to == null || v.currentTime < c.to)) { const [x, y, w, h] = fit(v.videoWidth, v.videoHeight); g.fillStyle = '#151514'; g.fillRect(0, 0, width, height); g.drawImage(v, x, y, w, h); await new Promise((resolve) => requestAnimationFrame(resolve)) }
+      v.pause(); URL.revokeObjectURL(v.src)
+    }
+    await new Promise((resolve) => { rec.onstop = resolve; rec.stop() })
+    const buf = new Uint8Array(await new Blob(chunks).arrayBuffer())
+    let s = ''; for (let i = 0; i < buf.length; i += 0x8000) s += String.fromCharCode.apply(null, buf.subarray(i, i + 0x8000))
+    return btoa(s)
+  }, { clips, width, height, fps })
+}
+
+/** `kaloko video export`: the walkthrough of the current run (or --run) as MP4, WebM or GIF. */
+export async function exportWalkthrough ({ config, root, args, say }) {
+  const run = await resolveRun({ root, output: config.output, run: args.run })
+  const scenario = await loadScenario(resolve(root, run.meta.scenario_file))
+  const manifest = await buildManifest({ run, scenario, config, root, catalog: [] })
+  const format = FORMATS.includes(args.format) ? args.format : 'mp4'
+  const lang = args.lang === 'cs' ? 'cs' : 'en'
+  const locale = typeof args.locale === 'string' ? args.locale : manifest.scope.locales[0]
+  const steps = typeof args.steps === 'string' ? args.steps.split(',').map((s) => s.trim()).filter(Boolean) : null
+  const plan = walkthroughPlan(manifest, { locale, viewport: typeof args.viewport === 'string' ? args.viewport : null, steps })
+  if (!plan.length) throw new UserError(`No recordings in run ${run.meta.id} for ${locale}. Walk with recordings first: kaloko walk --record (or --record flow), then export.`)
+  const tools = await videoTools()
+  if (!tools.ffmpeg && format !== 'webm') throw new UserError(`A walkthrough as ${format.toUpperCase()} needs ffmpeg (${installHint('ffmpeg')}). Without it, export WebM: kaloko video export --format webm (it plays the clips once in real time).`)
+  const P = preset(args.quality || 'medium')
+  const fps = format === 'gif' ? 10 : P.fps
+  const [width, height] = format === 'gif' ? outputSize(1280, 800, 800) : outputSize(1280, 800, Math.min(P.width, 1280))
+  const card = Math.max(0.5, Math.min(6, Number(args['card-seconds']) || 1.6))
+  const browser = await launchEphemeral(config)
+  const tmp = await mkdtemp(join(tmpdir(), 'kaloko-walkthrough-'))
+  const defaultOut = join(run.dir, 'attachments', `walkthrough.rec.${format}`)
+  const out = typeof args.out === 'string' ? resolve(args.out) : defaultOut
+  try {
+    const page = await browser.newPage()
+    await encoderCaps(page)
+    const V = VERDICT[lang]
+    const parts = []
+    const cardPng = async (lines, verdict) => {
+      const r = await page.evaluate((a) => window.__kenc.card(a), { width, height, lines, verdict })
+      const f = join(tmp, `card${parts.length}.png`)
+      await writeFile(f, Buffer.from(r.data, 'base64'))
+      return { card: f, cardData: r.data }
+    }
+    const s = manifest.summary || {}
+    parts.push(await cardPng([`${manifest.environment?.name || ''} · ${locale} · ${new Date(manifest.started_at).toISOString().slice(0, 10)}`, localized(manifest.scenario.title, locale) || manifest.scenario.id, `${plan.length} ${lang === 'cs' ? 'kroků se záznamem' : 'recorded steps'}${s.pass != null ? ` · ${s.pass} ${V.pass.toLowerCase()} · ${s.fail || 0} ${V.fail.toLowerCase()}` : ''}`], null))
+    plan.forEach((p, i) => { p.index = i + 1 })
+    for (const p of plan) {
+      parts.push(await cardPng([V.step(p.index, plan.length), p.title, p.node], { status: p.status, text: V[p.status] || p.status }))
+      parts.push({ file: join(run.dir, p.file), from: p.from, to: p.to })
+    }
+    await mkdir(dirname(out), { recursive: true })
+    if (tools.ffmpeg) {
+      say(`Stitching ${plan.length} recording(s) with title cards (${format.toUpperCase()}, ${width}×${height})…`)
+      await ffmpeg(tools, stitchArgs({ parts, out, format, width, height, fps, card, encoders: tools.ffmpeg.encoders }))
+    } else {
+      say(`No ffmpeg: playing ${plan.length} recording(s) through the browser in real time to record a WebM…`)
+      await writeFile(out, Buffer.from(await stitchInBrowser(page, { parts, width, height, fps, card }), 'base64'))
+    }
+    const bytes = (await stat(out)).size
+    const duration = Math.round((plan.reduce((n, p) => n + ((p.to ?? 0) - (p.from ?? 0)), 0) + card * (plan.length + 1)) * 1000)
+    const inside = !relative(run.dir, out).startsWith('..')
+    if (inside) await addCapture(run.dir, { type: 'walkthrough', file: relative(run.dir, out), format, bytes, locale, viewport: args.viewport || null, steps: plan.length, ...(plan.every((p) => p.to != null) ? { duration_ms: duration } : {}), at: new Date().toISOString() })
+    say(`Walkthrough: ${relative(process.cwd(), out)} (${fmtSize(bytes)}, ${plan.length} steps)`)
+    if (inside) say('kaloko share uploads it with the run (Business plan and up); people with the link play or download it on the canvas.')
+    return { file: out, bytes, steps: plan.length }
+  } finally { await browser.close().catch(() => {}); await rm(tmp, { recursive: true, force: true }) }
+}
+
+export async function videoCmd ({ config, root, args, say }) {
+  const sub = args._[0] || 'help'
+  if (sub === 'export') return exportWalkthrough({ config, root, args, say })
+  if (sub === 'tools') {
+    const t = await videoTools({ refresh: true })
+    const ff = t.ffmpeg
+    say([
+      `ffmpeg      ${ff ? `${ff.version} · H.264 ${ff.encoders.h264 || '—'} · VP9 ${ff.encoders.vp9 ? 'yes' : '—'} · AV1 ${ff.encoders.av1 || '—'}` : `not found (${installHint('ffmpeg', t.platform)}); WebM still works, MP4 and the walkthrough export need it`}`,
+      `adb         ${t.adb ? 'found (Android screenrecord)' : `not found (${installHint('adb', t.platform)})`}`,
+      ...(t.platform === 'darwin' ? [`simctl      ${t.simctl ? 'found (iOS Simulator recordVideo)' : `not found (${installHint('simctl', 'darwin')})`}`, 'screencapture  macOS desktop recordings (needs Screen Recording permission: kaloko doctor checks it)'] : [])
+    ].join('\n'))
+    return t
+  }
+  const run = await resolveRun({ root, output: config.output, run: args.run })
+  const scenario = await loadScenario(resolve(root, run.meta.scenario_file))
+  const manifest = await buildManifest({ run, scenario, config, root, catalog: [] })
+  if (sub === 'list') {
+    const rows = []
+    for (const n of manifest.nodes) {
+      for (const [l, vps] of Object.entries(n.captures || {})) for (const [vp, c] of Object.entries(vps || {})) if (c?.rec || c?.trace_summary) rows.push({ step: n.id, locale: l, viewport: vp, recording: c.rec || null, trace: c.trace_summary || null })
+      for (const r of n.recordings || []) rows.push({ step: n.id, locale: r.locale, viewport: r.viewport, recording: r, trace: null })
+    }
+    const flows = manifest.recordings?.flow || {}
+    if (args.json) { say(JSON.stringify({ run: run.meta.id, steps: rows, flow: flows, walkthrough: manifest.walkthrough || null }, null, 2)); return }
+    for (const r of rows) say(`${r.step.padEnd(24)} ${r.locale}/${r.viewport}  ${r.recording ? `${Math.round(r.recording.duration_ms / 100) / 10} s ${[r.recording.webm && 'WebM', r.recording.mp4 && 'MP4'].filter(Boolean).join('+')} ${fmtSize(r.recording.bytes || 0)}${r.recording.failed ? ' (failed attempt)' : ''}` : 'no recording'}${r.trace ? ` · trace ${r.trace.actions} actions, ${r.trace.requests} requests${r.trace.failed_requests ? ` (${r.trace.failed_requests} failed)` : ''}, ${r.trace.console_errors} console errors` : ''}`)
+    for (const [l, f] of Object.entries(flows)) say(`flow ${l}: ${Math.round(f.duration_ms / 1000)} s, ${f.chapters?.length || 0} chapters, ${fmtSize(f.bytes || 0)}`)
+    if (manifest.walkthrough) say(`walkthrough: ${manifest.walkthrough.file} (${fmtSize(manifest.walkthrough.bytes || 0)})`)
+    if (!rows.length && !Object.keys(flows).length) say('Nothing recorded in this run. kaloko walk --record records each step; traces are on unless capture.trace is false.')
+    return
+  }
+  if (sub === 'trace') {
+    const step = typeof args.step === 'string' ? args.step : null
+    const n = manifest.nodes.find((x) => x.id === step)
+    if (!n) throw new UserError(`Usage: kaloko video trace --step <id> [--locale l] [--viewport v] [--json]. Steps: ${manifest.nodes.map((x) => x.id).join(', ')}`)
+    const loc = typeof args.locale === 'string' ? args.locale : Object.keys(n.captures || {})[0]
+    const vps = n.captures?.[loc] || {}
+    const vp = typeof args.viewport === 'string' ? args.viewport : Object.keys(vps).find((v) => vps[v]?.trace)
+    const file = vps[vp]?.trace
+    if (!file) throw new UserError(`No trace for ${step} ${loc}${vp ? `/${vp}` : ''}. Walk the step again (traces are on unless capture.trace is false).`)
+    const trace = await readJson(join(run.dir, file), null)
+    say(args.json ? JSON.stringify(trace, null, 2) : `${step} ${loc}/${vp}: ${trace.duration_ms} ms, ${trace.summary?.requests ?? 0} requests, ${trace.summary?.console_errors ?? 0} console errors\n${formatTrace(trace)}`)
+    return
+  }
+  say(`Usage:
+  kaloko video export [--format mp4|webm|gif] [--locale l] [--viewport v] [--steps a,b] [--lang en|cs] [--out file]
+                      The run's recordings stitched in flow order with a title card per step (title, verdict)
+  kaloko video list [--json]               Recordings and traces of the run, with sizes
+  kaloko video trace --step <id> [--locale l] [--viewport v] [--json]
+                                           Actions, requests and console messages of the step, in time order
+  kaloko video tools                       ffmpeg, adb, simctl: what this machine can record and encode with`)
+}

package/src/lib/video.mjs

@@ -0,0 +1,427 @@
+/* global VideoEncoder, VideoFrame, OffscreenCanvas, createImageBitmap, location */
+// Video tooling for recordings (batch D): quality presets, which formats this machine can make, the encoder that runs
+// in Chrome (WebCodecs, no native dependency) and the optional ffmpeg steps (MP4 H.264 for Safari, AV1, native app
+// recordings, walkthrough export). Without ffmpeg a web recording still becomes a seekable WebM (VP9 or VP8), a
+// poster and an animated preview; MP4 and the stitched walkthrough need ffmpeg.
+import { execFile, spawn } from 'node:child_process'
+import { readFile, writeFile, mkdtemp, rm, stat, readdir } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { muxWebm } from './webm.mjs'
+import { animatedWebp, encodeGif } from './anim.mjs'
+
+/** Quality presets: frames per second, longest side, JPEG quality of screencast frames, bitrates and CRFs. */
+export const PRESETS = {
+  low: { fps: 8, width: 960, jpeg: 55, bitrate: 350_000, crf: { vp9: 44, x264: 32, av1: 46 }, preview: { width: 240, frames: 16 } },
+  medium: { fps: 12, width: 1280, jpeg: 65, bitrate: 800_000, crf: { vp9: 38, x264: 29, av1: 40 }, preview: { width: 320, frames: 20 } },
+  high: { fps: 24, width: 1920, jpeg: 80, bitrate: 2_000_000, crf: { vp9: 32, x264: 24, av1: 34 }, preview: { width: 400, frames: 28 } }
+}
+/** Longest kept recording in seconds: a step keeps its last minute, a flow its last 15 minutes. */
+export const MAX_SECONDS = { step: 60, flow: 900 }
+export const preset = (q) => PRESETS[q] || PRESETS.medium
+
+const execP = (bin, args, opts = {}) => new Promise((resolve, reject) => {
+  execFile(bin, args, { maxBuffer: 32 * 1024 * 1024, timeout: opts.timeout || 600000, encoding: opts.encoding || 'utf8' }, (error, stdout, stderr) => error ? reject(Object.assign(error, { stderr })) : resolve({ stdout, stderr }))
+})
+
+/** Install hints per tool and OS (macOS brew, Debian/Ubuntu apt, Windows winget or choco). */
+export function installHint (tool, platform = process.platform) {
+  const H = {
+    ffmpeg: { darwin: 'brew install ffmpeg', linux: 'sudo apt install ffmpeg (or dnf install ffmpeg)', win32: 'winget install Gyan.FFmpeg (or choco install ffmpeg)' },
+    adb: { darwin: 'brew install --cask android-platform-tools', linux: 'sudo apt install adb', win32: 'winget install Google.PlatformTools (or choco install adb)' },
+    simctl: { darwin: 'Install Xcode with an iOS Simulator runtime (xcode-select --install for the command line tools)' }
+  }
+  return H[tool]?.[platform] || H[tool]?.linux || ''
+}
+
+let cached = null
+/**
+ * What this machine can use for recordings: { ffmpeg: { path, version, encoders: { vp9, vp8, av1, h264, gif } } | null,
+ * adb, simctl, screencapture, platform }. `run` is stubbed in tests; KALOKO_FFMPEG points at another ffmpeg.
+ */
+export async function videoTools ({ run = execP, env = process.env, platform = process.platform, refresh = false } = {}) {
+  if (cached && !refresh && run === execP) return cached
+  const bin = env.KALOKO_FFMPEG || 'ffmpeg'
+  let ffmpeg = null
+  try {
+    const v = await run(bin, ['-hide_banner', '-version'], { timeout: 15000 })
+    const e = await run(bin, ['-hide_banner', '-encoders'], { timeout: 15000 })
+    const list = String(e.stdout)
+    const has = (name) => new RegExp(`^\\s*V\\S*\\s+${name}\\s`, 'm').test(list)
+    const h264 = ['libx264', platform === 'darwin' ? 'h264_videotoolbox' : null, platform === 'win32' ? 'h264_mf' : null, 'h264_nvenc', 'h264_vaapi'].filter(Boolean).find(has) || null
+    ffmpeg = {
+      path: bin,
+      version: (String(v.stdout).match(/ffmpeg version (\S+)/) || [])[1] || 'unknown',
+      encoders: { vp9: has('libvpx-vp9') ? 'libvpx-vp9' : null, vp8: has('libvpx') ? 'libvpx' : null, av1: ['libsvtav1', 'libaom-av1', 'librav1e'].find(has) || null, h264, gif: has('gif') ? 'gif' : null }
+    }
+  } catch {}
+  const ok = async (b, a) => { try { await run(b, a, { timeout: 15000 }); return true } catch { return false } }
+  const out = {
+    platform,
+    ffmpeg,
+    adb: await ok(env.KALOKO_ADB || 'adb', ['version']),
+    simctl: platform === 'darwin' ? await ok('xcrun', ['simctl', 'help']) : false,
+    screencapture: platform === 'darwin'
+  }
+  if (run === execP) cached = out
+  return out
+}
+
+/**
+ * Formats a recording gets, from what the encoder page (WebCodecs, WebP) and ffmpeg can do. `codec`: auto | vp9 |
+ * av1 | h264; `mp4`: auto (when ffmpeg can make H.264) | true | false. Returns { webm, mp4, preview, notes }.
+ */
+export function chooseFormats ({ tools = {}, caps = {}, codec = 'auto', mp4 = 'auto' } = {}) {
+  const ff = tools.ffmpeg?.encoders || {}
+  const notes = []
+  let webm = null
+  if (codec === 'av1') {
+    // AV1 in WebM needs codec private data the browser does not hand out: ffmpeg encodes it
+    if (ff.av1) webm = { via: 'ffmpeg', codec: 'av1', encoder: ff.av1 }
+    else notes.push('AV1 needs ffmpeg with libsvtav1 or libaom; using VP9.')
+  }
+  if (!webm && codec !== 'h264') {
+    if (caps.vp9) webm = { via: 'webcodecs', codec: 'vp9' }
+    else if (caps.vp8) webm = { via: 'webcodecs', codec: 'vp8' }
+    else if (ff.vp9) webm = { via: 'ffmpeg', codec: 'vp9', encoder: ff.vp9 }
+    else if (ff.vp8) webm = { via: 'ffmpeg', codec: 'vp8', encoder: ff.vp8 }
+  }
+  let mp4Out = null
+  if (mp4 !== false && mp4 !== 'false' && ff.h264) mp4Out = { via: 'ffmpeg', encoder: ff.h264 }
+  else if ((mp4 === true || codec === 'h264') && !ff.h264) notes.push(`MP4 (H.264) needs ffmpeg: ${installHint('ffmpeg', tools.platform)}.`)
+  if (!webm && !mp4Out) notes.push(`No video encoder: this browser has no WebCodecs and ffmpeg is missing (${installHint('ffmpeg', tools.platform)}); only the poster and preview are kept.`)
+  const preview = caps.webp ? 'webp' : 'gif'
+  return { webm, mp4: mp4Out, preview, notes }
+}
+
+/** Output size: the frame scaled to the preset's width, both sides even (encoders need it). */
+export function outputSize (w, h, maxWidth) {
+  const k = Math.min(1, maxWidth / Math.max(1, w))
+  const even = (n) => Math.max(2, Math.round(n / 2) * 2)
+  return [even(w * k), even(h * k)]
+}
+
+/**
+ * The frames a clip encodes at a constant rate: for each tick the newest source frame at or before it, the pointer
+ * and the click ripples at that moment, and which ticks also make the preview and the poster.
+ * frames: [{ t }] sorted (ms); events: [{ t, type: move|down|up, x, y }] in frame pixels; labels: [{ t, text }].
+ * Returns { ticks, start, end, trimmed }; tick t is ms from the clip start.
+ */
+export function schedule ({ frames, events = [], labels = [], start, end, fps, maxSeconds, previewFrames = 20 }) {
+  if (!frames.length) return { ticks: [], start, end, trimmed: false }
+  start = Math.max(start ?? frames[0].t, frames[0].t)
+  end = Math.max(end ?? frames[frames.length - 1].t, start + 1000 / fps)
+  let trimmed = false
+  if (maxSeconds && end - start > maxSeconds * 1000) { start = end - maxSeconds * 1000; trimmed = true }
+  const step = 1000 / fps
+  const n = Math.max(1, Math.ceil((end - start) / step))
+  const ticks = []
+  let src = 0
+  // the source frame shown at the clip start may be older than the start (nothing repainted since)
+  while (src + 1 < frames.length && frames[src + 1].t <= start) src++
+  let ev = 0; let cursor = null
+  const pv = new Set(Array.from({ length: Math.min(previewFrames, n) }, (_, i) => Math.floor(i * n / Math.min(previewFrames, n))))
+  for (let i = 0; i < n; i++) {
+    const at = start + i * step
+    while (src + 1 < frames.length && frames[src + 1].t <= at) src++
+    while (ev < events.length && events[ev].t <= at) { if (events[ev].x != null) cursor = { x: events[ev].x, y: events[ev].y }; ev++ }
+    const rip = events.filter((e) => e.type === 'down' && e.t <= at && at - e.t < 450).map((e) => ({ x: e.x, y: e.y, a: (at - e.t) / 450 }))
+    const label = labels.filter((l) => l.t <= at && at - l.t < 1600).pop()?.text || null
+    ticks.push({ t: Math.round(i * step), src, ...(cursor ? { cur: cursor } : {}), ...(rip.length ? { rip } : {}), ...(label ? { label } : {}), ...(pv.has(i) ? { preview: true } : {}), ...(i === 0 ? { poster: true } : {}) })
+  }
+  return { ticks, start, end, trimmed }
+}
+
+// ---------- the encoder page (Chrome) ----------
+
+/** Installs the encoder into a page (about:blank of the walk's browser or of an own headless Chrome). */
+function install () {
+  if (window.__kenc) return
+  const CODECS = { vp9: 'vp09.00.10.08', vp8: 'vp8', h264: 'avc1.42001f' }
+  const b64 = (u8) => { let s = ''; for (let i = 0; i < u8.length; i += 0x8000) s += String.fromCharCode.apply(null, u8.subarray(i, i + 0x8000)); return btoa(s) }
+  const fromB64 = (s) => Uint8Array.from(atob(s), (c) => c.charCodeAt(0))
+  const blobBytes = async (canvas, type, q) => { const b = await canvas.convertToBlob({ type, quality: q }); return { type: b.type, data: b64(new Uint8Array(await b.arrayBuffer())) } }
+  const pointer = (g, x, y, s) => {
+    g.save(); g.translate(x, y); g.scale(s, s)
+    g.beginPath(); g.moveTo(0, 0); g.lineTo(0, 17); g.lineTo(4.5, 13); g.lineTo(7.5, 20); g.lineTo(10.5, 18.8); g.lineTo(7.6, 12); g.lineTo(13, 12); g.closePath()
+    g.fillStyle = '#151514'; g.fill(); g.lineWidth = 1.6; g.strokeStyle = '#ffffff'; g.stroke(); g.restore()
+  }
+  window.__kenc = {
+    async caps () {
+      const out = { webcodecs: typeof VideoEncoder !== 'undefined', vp9: false, vp8: false, h264: false, webp: false }
+      if (out.webcodecs) {
+        for (const [k, codec] of Object.entries(CODECS)) {
+          try { out[k] = !!(await VideoEncoder.isConfigSupported({ codec, width: 640, height: 480, bitrate: 500000, framerate: 12 })).supported } catch {}
+        }
+      }
+      try { const c = new OffscreenCanvas(2, 2); c.getContext('2d').fillRect(0, 0, 2, 2); out.webp = (await c.convertToBlob({ type: 'image/webp', quality: 0.5 })).type === 'image/webp' } catch {}
+      return out
+    },
+    start (cfg) {
+      this.cfg = cfg; this.chunks = []; this.bitmaps = new Map(); this.n = 0; this.error = null
+      this.canvas = new OffscreenCanvas(cfg.width, cfg.height); this.g = this.canvas.getContext('2d')
+      this.pcanvas = new OffscreenCanvas(cfg.pw, cfg.ph); this.pg = this.pcanvas.getContext('2d', { willReadFrequently: cfg.previewType === 'gif' })
+      this.enc = null
+      if (cfg.codec) {
+        this.enc = new VideoEncoder({ output: (chunk) => { const u = new Uint8Array(chunk.byteLength); chunk.copyTo(u); this.chunks.push({ ts: chunk.timestamp / 1000, key: chunk.type === 'key', data: b64(u) }) }, error: (e) => { this.error = String(e?.message || e) } })
+        this.enc.configure({ codec: CODECS[cfg.codec], width: cfg.width, height: cfg.height, bitrate: cfg.bitrate, framerate: cfg.fps, latencyMode: 'quality' })
+      }
+      return true
+    },
+    async feed ({ images, ticks }) {
+      const c = this.cfg; const g = this.g
+      for (const im of images) this.bitmaps.set(im.i, await createImageBitmap(new Blob([fromB64(im.b64)], { type: 'image/jpeg' })))
+      const out = { previews: [], poster: null }
+      for (const tk of ticks) {
+        for (const [k, bm] of this.bitmaps) if (k < tk.src) { bm.close(); this.bitmaps.delete(k) }
+        const bm = this.bitmaps.get(tk.src)
+        g.fillStyle = '#ffffff'; g.fillRect(0, 0, c.width, c.height)
+        if (bm) g.drawImage(bm, 0, 0, c.width, c.height)
+        if (tk.poster && !c.noPoster) out.poster = await blobBytes(this.canvas, 'image/webp', 0.8)
+        const s = c.width / c.srcWidth
+        for (const r of tk.rip || []) { g.beginPath(); g.arc(r.x * s, r.y * s, (8 + 26 * r.a) * c.ui, 0, Math.PI * 2); g.fillStyle = `rgba(255,228,82,${0.55 * (1 - r.a)})`; g.fill(); g.lineWidth = 2 * c.ui; g.strokeStyle = `rgba(21,21,20,${0.8 * (1 - r.a)})`; g.stroke() }
+        if (tk.cur) pointer(g, tk.cur.x * s, tk.cur.y * s, c.ui)
+        if (tk.label) {
+          g.font = `600 ${Math.round(15 * c.ui)}px system-ui, sans-serif`; const w = g.measureText(tk.label).width + 20 * c.ui
+          g.fillStyle = 'rgba(21,21,20,0.82)'; g.fillRect(12 * c.ui, 12 * c.ui, w, 30 * c.ui); g.fillStyle = '#ffe452'; g.textBaseline = 'middle'; g.fillText(tk.label, 22 * c.ui, 27 * c.ui)
+        }
+        if (this.enc) {
+          const f = new VideoFrame(this.canvas, { timestamp: Math.round(tk.t * 1000), duration: Math.round(1e6 / c.fps) })
+          this.enc.encode(f, { keyFrame: this.n % c.keyEvery === 0 }); f.close(); this.n++
+          while (this.enc.encodeQueueSize > 6) await new Promise((resolve) => setTimeout(resolve, 2))
+        }
+        if (tk.preview) {
+          this.pg.drawImage(this.canvas, 0, 0, c.pw, c.ph)
+          if (c.previewType === 'webp') out.previews.push(await blobBytes(this.pcanvas, 'image/webp', 0.62))
+          else out.previews.push({ type: 'rgba', data: b64(new Uint8Array(this.pg.getImageData(0, 0, c.pw, c.ph).data.buffer)) })
+        }
+      }
+      return { ...out, chunks: this.chunks.splice(0), error: this.error }
+    },
+    async finish () {
+      if (this.enc) { try { await this.enc.flush() } catch (e) { this.error = String(e?.message || e) } this.enc.close() }
+      for (const bm of this.bitmaps.values()) bm.close()
+      this.bitmaps.clear()
+      return { chunks: this.chunks.splice(0), error: this.error }
+    },
+    // a still image (title card of the walkthrough export): text on the brand colours, as PNG
+    async card ({ width, height, lines, verdict }) {
+      const cv = new OffscreenCanvas(width, height); const g = cv.getContext('2d'); const u = width / 1280
+      g.fillStyle = '#151514'; g.fillRect(0, 0, width, height)
+      const colors = { pass: '#3fb950', fail: '#f85149', partial: '#d29922', skip: '#8b949e' }
+      g.textBaseline = 'top'; let y = height * 0.36
+      lines.forEach((l, i) => { g.font = `${i === 1 ? 700 : 500} ${Math.round((i === 1 ? 44 : 22) * u)}px system-ui, sans-serif`; g.fillStyle = i === 1 ? '#ffffff' : '#c9c9c4'; g.fillText(l, 80 * u, y); y += (i === 1 ? 64 : 36) * u })
+      if (verdict) { g.font = `700 ${Math.round(22 * u)}px system-ui, sans-serif`; const w = g.measureText(verdict.text).width + 32 * u; g.fillStyle = colors[verdict.status] || '#ffe452'; g.fillRect(80 * u, y + 12 * u, w, 40 * u); g.fillStyle = '#151514'; g.fillText(verdict.text, 96 * u, y + 21 * u) }
+      g.fillStyle = '#ffe452'; g.fillRect(0, height - 8 * u, width, 8 * u)
+      return blobBytes(cv, 'image/png')
+    }
+  }
+}
+
+const NO_CAPS = { webcodecs: false, vp9: false, vp8: false, h264: false, webp: false }
+const CAPS = new WeakMap()
+/** WebCodecs needs a secure context: the encoder page opens a routed https page that never reaches the network. */
+const ENCODER_URL = 'https://encoder.kaloko.invalid/'
+/**
+ * Installs the encoder into `page` (moved to a secure origin first) and answers what it can do
+ * ({ webcodecs, vp9, vp8, h264, webp }); cached per page.
+ */
+export async function encoderCaps (page) {
+  if (!page) return NO_CAPS
+  if (CAPS.has(page)) return CAPS.get(page)
+  let caps = NO_CAPS
+  try {
+    if (!(await page.evaluate(() => window.isSecureContext && location.href !== 'about:blank'))) {
+      await page.route(ENCODER_URL, (route) => route.fulfill({ status: 200, contentType: 'text/html', body: '<!doctype html><title>encoder</title>' }))
+      await page.goto(ENCODER_URL)
+    }
+    await page.evaluate(install)
+    caps = await page.evaluate(() => window.__kenc.caps())
+  } catch {}
+  CAPS.set(page, caps)
+  return caps
+}
+
+/**
+ * Encodes a recorded clip. frames: [{ t, file, w, h }] (JPEG files, frame pixels); events and labels as in schedule().
+ * Writes <out>.webm / .mp4 / .webp (or .gif) preview / .poster.webp and returns what was written:
+ * { files: { webm, mp4, preview, poster }, duration_ms, width, height, codec, fps, trimmed, notes }.
+ */
+// the encoder page holds one clip at a time: parallel locales and named sessions take turns
+const LOCKS = new WeakMap()
+export function encodeClip (opts) {
+  if (!opts.page) return encodeClipNow(opts)
+  const prev = LOCKS.get(opts.page) || Promise.resolve()
+  const next = prev.catch(() => {}).then(() => encodeClipNow(opts))
+  LOCKS.set(opts.page, next.catch(() => {}))
+  return next
+}
+
+async function encodeClipNow ({ page, frames, events = [], labels = [], start, end, out, quality = 'medium', maxSeconds = MAX_SECONDS.step, codec = 'auto', mp4 = 'auto', tools = null, caps = null }) {
+  const P = preset(quality)
+  if (!frames?.length) return null
+  caps ||= await encoderCaps(page)
+  tools ||= await videoTools()
+  const formats = chooseFormats({ tools, caps, codec, mp4 })
+  const srcW = frames[0].w; const srcH = frames[0].h
+  const [width, height] = outputSize(srcW, srcH, P.width)
+  const [pw, ph] = outputSize(srcW, srcH, P.preview.width)
+  const sch = schedule({ frames, events, labels, start, end, fps: P.fps, maxSeconds, previewFrames: P.preview.frames })
+  const files = {}
+  const notes = [...formats.notes]
+  const duration = Math.round(sch.end - sch.start)
+  if (page) {
+    try {
+      const viaBrowser = formats.webm?.via === 'webcodecs' ? formats.webm.codec : null
+      await page.evaluate((cfg) => window.__kenc.start(cfg), { codec: viaBrowser, width, height, fps: P.fps, bitrate: P.bitrate, keyEvery: P.fps * 2, srcWidth: srcW, pw, ph, previewType: formats.preview, ui: Math.max(0.6, width / 1280) })
+      const chunks = []; const previews = []; let poster = null; let error = null
+      const sent = new Set()
+      for (let i = 0; i < sch.ticks.length; i += 24) {
+        const batch = sch.ticks.slice(i, i + 24)
+        const need = [...new Set(batch.map((t) => t.src))].filter((s) => !sent.has(s))
+        const images = []
+        for (const s of need) { sent.add(s); images.push({ i: s, b64: (await readFile(frames[s].file)).toString('base64') }) }
+        const r = await page.evaluate((arg) => window.__kenc.feed(arg), { images, ticks: batch })
+        chunks.push(...r.chunks); previews.push(...r.previews); poster ||= r.poster; error ||= r.error
+      }
+      const fin = await page.evaluate(() => window.__kenc.finish())
+      chunks.push(...fin.chunks); error ||= fin.error
+      if (poster) { files.poster = `${out}.poster.webp`; await writeFile(files.poster, Buffer.from(poster.data, 'base64')) }
+      if (previews.length) {
+        const ms = Math.max(90, Math.min(250, Math.round(Math.min(duration, 3500) / previews.length)))
+        if (formats.preview === 'webp' && previews[0].type === 'image/webp') { files.preview = `${out}.webp`; await writeFile(files.preview, animatedWebp(previews.map((p) => ({ webp: Buffer.from(p.data, 'base64'), ms })))) } else if (previews[0].type === 'rgba') { files.preview = `${out}.gif`; await writeFile(files.preview, encodeGif(previews.map((p) => ({ rgba: Buffer.from(p.data, 'base64'), ms })), { width: pw, height: ph })) }
+      }
+      if (viaBrowser) {
+        if (error || !chunks.length) notes.push(`The browser encoder failed${error ? `: ${error}` : ''}.`)
+        else { files.webm = `${out}.webm`; await writeFile(files.webm, muxWebm({ width, height, codec: viaBrowser, chunks: chunks.map((c) => ({ ...c, data: Buffer.from(c.data, 'base64') })), duration, fps: P.fps })) }
+      }
+    } catch (error) { notes.push(`The browser encoder failed: ${String(error.message).split('\n')[0]}`) }
+  }
+  // ffmpeg: WebM when the browser could not, AV1, and MP4 (H.264) next to the WebM for Safari
+  if (tools.ffmpeg && ((!files.webm && formats.webm?.via === 'ffmpeg') || formats.mp4)) {
+    const tmp = await mkdtemp(join(tmpdir(), 'kaloko-rec-'))
+    try {
+      let source = files.webm
+      if (!source) {
+        // the source frames at their own times (no pointer drawn: that needs the browser)
+        const first = sch.ticks[0]?.src || 0
+        const used = frames.slice(first).filter((f, k) => k === 0 || f.t <= sch.end)
+        const list = used.map((f, k) => `file '${f.file.replaceAll("'", "'\\''")}'\nduration ${Math.max(0.001, ((used[k + 1]?.t ?? sch.end) - Math.max(f.t, sch.start)) / 1000).toFixed(3)}`).join('\n') + `\nfile '${used[used.length - 1].file.replaceAll("'", "'\\''")}'\n`
+        await writeFile(join(tmp, 'list.txt'), list)
+        source = { concat: join(tmp, 'list.txt') }
+      }
+      if (!files.webm && formats.webm?.via === 'ffmpeg') {
+        files.webm = `${out}.webm`
+        await ffmpegEncode(tools, source, files.webm, { kind: formats.webm.codec, encoder: formats.webm.encoder, width, height, fps: P.fps, crf: P.crf[formats.webm.codec === 'av1' ? 'av1' : 'vp9'] })
+      }
+      if (formats.mp4) {
+        files.mp4 = `${out}.mp4`
+        await ffmpegEncode(tools, source, files.mp4, { kind: 'h264', encoder: formats.mp4.encoder, width, height, fps: P.fps, crf: P.crf.x264, bitrate: P.bitrate })
+      }
+    } catch (error) {
+      notes.push(`ffmpeg failed: ${String(error.stderr || error.message).trim().split('\n').pop()}`)
+      for (const k of ['mp4']) if (files[k]) { await rm(files[k], { force: true }); delete files[k] }
+    } finally { await rm(tmp, { recursive: true, force: true }) }
+  }
+  const bytes = {}
+  for (const [k, f] of Object.entries(files)) bytes[k] = (await stat(f).catch(() => ({ size: 0 }))).size
+  return { files, bytes, duration_ms: duration, width, height, codec: files.webm ? (formats.webm?.codec || null) : files.mp4 ? 'h264' : null, fps: P.fps, trimmed: sch.trimmed, start: sch.start, end: sch.end, notes }
+}
+
+/** ffmpeg arguments for one output; `source` is a file or { concat: list.txt } of still frames with durations. */
+export function ffmpegArgs (source, outFile, { kind, encoder, width, height, fps, crf, bitrate }) {
+  const input = typeof source === 'string' ? ['-i', source] : ['-f', 'concat', '-safe', '0', '-i', source.concat]
+  const scale = `scale=${width}:${height}:force_original_aspect_ratio=decrease,pad=${width}:${height}:(ow-iw)/2:(oh-ih)/2:color=white,fps=${fps},format=yuv420p`
+  const codec = {
+    vp9: ['-c:v', encoder || 'libvpx-vp9', '-deadline', 'realtime', '-cpu-used', '8', '-row-mt', '1', '-b:v', '0', '-crf', String(crf)],
+    vp8: ['-c:v', encoder || 'libvpx', '-deadline', 'realtime', '-cpu-used', '8', '-b:v', String(bitrate || 800000), '-crf', String(Math.min(63, crf || 30))],
+    av1: encoder === 'libsvtav1' ? ['-c:v', 'libsvtav1', '-preset', '10', '-crf', String(crf)] : ['-c:v', encoder || 'libaom-av1', '-cpu-used', '8', '-row-mt', '1', '-b:v', '0', '-crf', String(crf)],
+    h264: encoder === 'libx264' ? ['-c:v', 'libx264', '-preset', 'veryfast', '-crf', String(crf), '-profile:v', 'high'] : ['-c:v', encoder, '-b:v', String(bitrate || 1000000)]
+  }[kind === 'vp8' ? 'vp8' : kind]
+  // a key frame every two seconds: chapters and the step markers seek without decoding from the start
+  return ['-y', '-v', 'error', ...input, '-an', '-vf', scale, ...codec, '-g', String(Math.max(1, Math.round(fps * 2))), ...(kind === 'h264' ? ['-movflags', '+faststart'] : []), outFile]
+}
+
+export async function ffmpegEncode (tools, source, outFile, opts) {
+  await execP(tools.ffmpeg.path, ffmpegArgs(source, outFile, opts), { timeout: 900000 })
+}
+
+/** Runs ffmpeg with raw arguments (export, native recordings). */
+export const ffmpeg = (tools, args, timeout = 900000) => execP(tools.ffmpeg.path, ['-y', '-v', 'error', ...args], { timeout })
+
+/** Duration of a media file in ms from ffmpeg's stderr; null when unknown. */
+export async function mediaDuration (tools, file) {
+  try { await execP(tools.ffmpeg.path, ['-hide_banner', '-i', file], { timeout: 30000 }) } catch (e) {
+    const m = String(e.stderr || '').match(/Duration: (\d+):(\d+):(\d+(?:\.\d+)?)/)
+    if (m) return Math.round(((+m[1]) * 3600 + (+m[2]) * 60 + (+m[3])) * 1000)
+  }
+  return null
+}
+
+/**
+ * Poster and animated preview of a finished video file (native app recordings): frames come out of ffmpeg and are
+ * encoded in the encoder page (WebP) or as a GIF by ffmpeg itself. { poster, preview } paths or null each.
+ */
+export async function stillsFromVideo ({ tools, page, file, out, quality = 'medium', duration = null }) {
+  const P = preset(quality)
+  const res = { poster: null, preview: null }
+  if (!tools.ffmpeg) return res
+  const tmp = await mkdtemp(join(tmpdir(), 'kaloko-stills-'))
+  try {
+    const secs = Math.max(0.5, (duration || await mediaDuration(tools, file) || 3000) / 1000)
+    const rate = Math.max(0.2, P.preview.frames / secs)
+    await ffmpeg(tools, ['-i', file, '-vf', `fps=${rate.toFixed(3)},scale=${P.preview.width}:-2`, '-frames:v', String(P.preview.frames), join(tmp, 'f%03d.png')])
+    const names = (await readdir(tmp)).filter((f) => f.endsWith('.png')).sort()
+    if (!names.length) return res
+    await ffmpeg(tools, ['-i', file, '-frames:v', '1', '-vf', `scale='min(${P.width},iw)':-2`, `${out}.poster.png`]).catch(() => {})
+    const caps = await encoderCaps(page)
+    if (caps.webp) {
+      const frames = []
+      for (const n of names) frames.push({ webp: Buffer.from((await page.evaluate(async (b64) => { const bm = await createImageBitmap(new Blob([Uint8Array.from(atob(b64), (c) => c.charCodeAt(0))], { type: 'image/png' })); const c = new OffscreenCanvas(bm.width, bm.height); c.getContext('2d').drawImage(bm, 0, 0); const b = await c.convertToBlob({ type: 'image/webp', quality: 0.62 }); const u = new Uint8Array(await b.arrayBuffer()); let s = ''; for (let i = 0; i < u.length; i += 0x8000) s += String.fromCharCode.apply(null, u.subarray(i, i + 0x8000)); return btoa(s) }, (await readFile(join(tmp, n))).toString('base64'))), 'base64'), ms: Math.min(250, Math.max(90, Math.round(Math.min(secs * 1000, 3500) / names.length))) })
+      res.preview = `${out}.webp`; await writeFile(res.preview, animatedWebp(frames))
+      const posterPng = await readFile(`${out}.poster.png`).catch(() => null)
+      if (posterPng) {
+        const webp = await page.evaluate(async (b64) => { const bm = await createImageBitmap(new Blob([Uint8Array.from(atob(b64), (c) => c.charCodeAt(0))], { type: 'image/png' })); const c = new OffscreenCanvas(bm.width, bm.height); c.getContext('2d').drawImage(bm, 0, 0); const b = await c.convertToBlob({ type: 'image/webp', quality: 0.8 }); const u = new Uint8Array(await b.arrayBuffer()); let s = ''; for (let i = 0; i < u.length; i += 0x8000) s += String.fromCharCode.apply(null, u.subarray(i, i + 0x8000)); return btoa(s) }, posterPng.toString('base64'))
+        res.poster = `${out}.poster.webp`; await writeFile(res.poster, Buffer.from(webp, 'base64'))
+      }
+    } else if (tools.ffmpeg.encoders.gif) {
+      res.preview = `${out}.gif`
+      await ffmpeg(tools, ['-framerate', String(Math.max(4, Math.round(names.length / Math.min(secs, 3.5)))), '-i', join(tmp, 'f%03d.png'), '-vf', 'split[a][b];[a]palettegen=max_colors=128[p];[b][p]paletteuse=dither=bayer', '-loop', '0', res.preview])
+    }
+    await rm(`${out}.poster.png`, { force: true })
+  } catch {} finally { await rm(tmp, { recursive: true, force: true }) }
+  return res
+}
+
+/** Starts a long-running process (adb screenrecord, simctl recordVideo, screencapture) and returns it. */
+export function startProcess (bin, args, opts = {}) {
+  const child = spawn(bin, args, { stdio: ['ignore', 'pipe', 'pipe'], ...opts })
+  let stderr = ''
+  child.stderr.on('data', (d) => { stderr += d; if (stderr.length > 20000) stderr = stderr.slice(-10000) })
+  child.output = () => stderr
+  child.done = new Promise((resolve) => child.on('close', (code, signal) => resolve({ code, signal, stderr })))
+  child.on('error', () => {})
+  return child
+}
+
+/**
+ * `kaloko doctor` lines about recordings: ffmpeg and its encoders, and the recorders the config's app environments
+ * need. Recording is optional, so a missing tool fails the check only when the config asks for what needs it.
+ */
+export function recordingChecks ({ config = {}, tools }) {
+  const out = []
+  const ff = tools.ffmpeg
+  const want = config.capture?.record
+  const needsFf = want && typeof want === 'object' && (want.mp4 === true || ['av1', 'h264'].includes(want.codec))
+  out.push({
+    name: 'recording',
+    ok: !!ff || !needsFf,
+    detail: ff ? `ffmpeg ${ff.version} · MP4 ${ff.encoders.h264 || '—'} · VP9 ${ff.encoders.vp9 ? 'yes' : '—'} · AV1 ${ff.encoders.av1 || '—'}` : 'no ffmpeg: web recordings are WebM from Chrome; MP4 for Safari, native app recordings and kaloko video export need ffmpeg',
+    hint: ff ? '' : `Install ffmpeg: ${installHint('ffmpeg', tools.platform)}`
+  })
+  const apps = new Set(Object.values(config.environments || {}).flatMap((e) => Object.keys(e?.app || {})))
+  if (apps.has('android')) out.push({ name: 'recording android', ok: !!tools.adb, detail: tools.adb ? 'adb screenrecord (3-minute segments, touches shown)' : 'adb not found', hint: tools.adb ? '' : installHint('adb', tools.platform) })
+  if (apps.has('ios')) out.push({ name: 'recording ios', ok: !!tools.simctl, detail: tools.simctl ? 'simctl io recordVideo (H.264)' : 'simctl not found', hint: tools.simctl ? '' : installHint('simctl', 'darwin') })
+  if (apps.has('desktop')) out.push({ name: 'recording desktop', ok: tools.platform === 'darwin', detail: tools.platform === 'darwin' ? `screencapture -v (Screen Recording permission: see "app … desktop" above)${ff ? '' : '; .mov until ffmpeg is installed'}` : 'desktop recording needs macOS', hint: '' })
+  return out
+}