kaloko 0.4.9 → 0.4.11

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/ci.mjs

@@ -0,0 +1,207 @@
+// Packaged CI (#15): `kaloko ci github|gitlab` writes a workflow into the customer's repository that walks the
+// affected scenarios on the pull request's preview deployment and comments on the PR; `kaloko ci preview-url` finds
+// that deployment at run time (Vercel, Netlify, Cloudflare Pages and anything that reports GitHub deployments).
+import { readFile, appendFile } from 'node:fs/promises'
+
+const clean = (u) => (u ? (/^https?:\/\//.test(u) ? u : `https://${u}`).replace(/\/$/, '') : null)
+
+/** Preview URL from variables CI and hosting providers set; { url, source } or null. */
+export function previewFromEnv (vars = process.env, event = null) {
+  if (vars.KALOKO_PREVIEW_URL) return { url: clean(vars.KALOKO_PREVIEW_URL), source: 'KALOKO_PREVIEW_URL' }
+  const ds = event?.deployment_status
+  if (ds && ds.state === 'success' && (ds.environment_url || ds.target_url)) return { url: clean(ds.environment_url || ds.target_url), source: `deployment_status (${ds.environment || event.deployment?.environment || 'deployment'})` }
+  for (const [name, label] of [['VERCEL_BRANCH_URL', 'Vercel'], ['VERCEL_URL', 'Vercel'], ['DEPLOY_PRIME_URL', 'Netlify'], ['DEPLOY_URL', 'Netlify'], ['CF_PAGES_URL', 'Cloudflare Pages'], ['CI_ENVIRONMENT_URL', 'GitLab environment'], ['RENDER_EXTERNAL_URL', 'Render'], ['RAILWAY_PUBLIC_DOMAIN', 'Railway']]) {
+    if (vars[name]) return { url: clean(vars[name]), source: `${name} (${label})` }
+  }
+  return null
+}
+
+async function readEvent (vars) {
+  if (!vars.GITHUB_EVENT_PATH) return null
+  try { return JSON.parse(await readFile(vars.GITHUB_EVENT_PATH, 'utf8')) } catch { return null }
+}
+
+function github (vars, fetchImpl) {
+  const api = (vars.GITHUB_API_URL || 'https://api.github.com').replace(/\/$/, '')
+  const token = vars.GITHUB_TOKEN || vars.GH_TOKEN
+  return async (path) => {
+    const res = await fetchImpl(`${api}${path}`, { headers: { Accept: 'application/vnd.github+json', 'X-GitHub-Api-Version': '2022-11-28', ...(token ? { Authorization: `Bearer ${token}` } : {}) } })
+    if (!res.ok) throw new Error(`GitHub ${path} → HTTP ${res.status}`)
+    return res.json()
+  }
+}
+
+/** The pull request a CI run belongs to: { number, base, head, sha } from the event or, for a deployment, its commit. */
+export async function pullRequestOf ({ vars = process.env, event = undefined, fetchImpl = fetch } = {}) {
+  event = event === undefined ? await readEvent(vars) : event
+  if (vars.KALOKO_PR) return { number: Number(vars.KALOKO_PR), base: vars.KALOKO_BASE?.replace(/^origin\//, '') || null, sha: vars.GITHUB_SHA || null }
+  if (event?.pull_request) return { number: event.pull_request.number, base: event.pull_request.base?.ref || null, head: event.pull_request.head?.ref || null, sha: event.pull_request.head?.sha || null }
+  if (vars.CI_MERGE_REQUEST_IID) return { number: Number(vars.CI_MERGE_REQUEST_IID), base: vars.CI_MERGE_REQUEST_TARGET_BRANCH_NAME || null, head: vars.CI_MERGE_REQUEST_SOURCE_BRANCH_NAME || null, sha: vars.CI_COMMIT_SHA || null }
+  const sha = event?.deployment?.sha || vars.GITHUB_SHA
+  if (sha && vars.GITHUB_REPOSITORY) {
+    try {
+      const pulls = await github(vars, fetchImpl)(`/repos/${vars.GITHUB_REPOSITORY}/commits/${sha}/pulls`)
+      const pr = pulls.find((p) => p.state === 'open') || pulls[0]
+      if (pr) return { number: pr.number, base: pr.base?.ref || null, head: pr.head?.ref || null, sha }
+    } catch {}
+  }
+  return null
+}
+
+/**
+ * The preview deployment of this commit: variables first, then GitHub deployments of the commit (Vercel, Netlify and
+ * Cloudflare Pages report theirs there), polled until one succeeds or `wait` seconds pass. Production is skipped.
+ */
+export async function findPreview ({ vars = process.env, fetchImpl = fetch, wait = 0, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), say = () => {} } = {}) {
+  const event = await readEvent(vars)
+  const direct = previewFromEnv(vars, event)
+  if (direct) return direct
+  const sha = event?.pull_request?.head?.sha || event?.deployment?.sha || vars.GITHUB_SHA
+  if (!sha || !vars.GITHUB_REPOSITORY) return null
+  const gh = github(vars, fetchImpl)
+  const until = Date.now() + wait * 1000
+  for (let round = 0; ; round++) {
+    try {
+      const deployments = await gh(`/repos/${vars.GITHUB_REPOSITORY}/deployments?sha=${sha}&per_page=30`)
+      for (const d of deployments.filter((x) => !/^prod/i.test(x.environment || '') && !x.production_environment)) {
+        const statuses = await gh(`/repos/${vars.GITHUB_REPOSITORY}/deployments/${d.id}/statuses?per_page=10`)
+        const ok = statuses.find((s) => s.state === 'success' && (s.environment_url || s.target_url))
+        if (ok) return { url: clean(ok.environment_url || ok.target_url), source: `GitHub deployment ${d.environment}` }
+      }
+    } catch (e) { if (round === 0) say(`  (GitHub deployments not readable: ${e.message})`) }
+    if (Date.now() >= until) return null
+    if (round === 0) say(`Waiting up to ${wait} s for a preview deployment of ${sha.slice(0, 7)}…`)
+    await sleep(10000)
+  }
+}
+
+/** Lines for $GITHUB_ENV (or a dotenv file): the preview URL, the PR and its base for --affected and share --pr. */
+export function envLines ({ preview, pr }) {
+  return [
+    preview && `KALOKO_PREVIEW_URL=${preview.url}`,
+    pr?.number && `KALOKO_PR=${pr.number}`,
+    pr?.base && `KALOKO_BASE=origin/${pr.base}`,
+    pr?.head && `KALOKO_BRANCH=${pr.head}`
+  ].filter(Boolean)
+}
+
+export const writeEnvFile = (file, lines) => appendFile(file, lines.map((l) => l + '\n').join(''))
+
+const q = (s) => /^[A-Za-z0-9_./-]+$/.test(s) ? s : JSON.stringify(s)
+
+/** How the workflow runs kaloko: through the project's package manager when kaloko is a dependency, else npx. */
+export function runner ({ pm = 'npm', dependency = true, version = 'latest' }) {
+  if (!dependency) return { install: null, kaloko: `npx --yes kaloko@${version}` }
+  return {
+    install: { npm: 'npm ci', pnpm: 'pnpm install --frozen-lockfile', yarn: 'yarn install --frozen-lockfile', bun: 'bun install --frozen-lockfile' }[pm] || 'npm ci',
+    kaloko: { npm: 'npx kaloko', pnpm: 'pnpm exec kaloko', yarn: 'yarn kaloko', bun: 'bunx kaloko' }[pm] || 'npx kaloko'
+  }
+}
+
+/** The loop over scenarios both workflows run: walk what the change reaches, share, comment on the PR. */
+function walkScript ({ scenarios, env, affected, k }) {
+  return [
+    'status=0',
+    `for s in ${scenarios.map(q).join(' ')}; do`,
+    ...(affected ? [`  if ! ${k} affected --scenario "$s" --check; then echo "Nothing in $s is affected; skipped."; continue; fi`] : []),
+    `  ${k} start --scenario "$s" --env ${env}`,
+    `  ${k} walk --ephemeral${affected ? ' --affected' : ''} || status=1`,
+    `  ${k} share --pr || status=1`,
+    'done',
+    'exit $status'
+  ]
+}
+
+/** .github/workflows/kaloko.yml */
+export function githubWorkflow ({ scenarios, env = 'preview', trigger = 'deployment', affected = true, pm = 'npm', dependency = true, version = 'latest', node = 22 }) {
+  const { install, kaloko: k } = runner({ pm, dependency, version })
+  const indent = (lines, n) => lines.map((l) => ' '.repeat(n) + l).join('\n')
+  const on = trigger === 'deployment'
+    ? '  # Vercel, Netlify and Cloudflare Pages report each preview as a GitHub deployment\n  deployment_status:\n  workflow_dispatch:'
+    : '  pull_request:\n  workflow_dispatch:'
+  const guard = trigger === 'deployment'
+    ? "    if: github.event_name != 'deployment_status' || (github.event.deployment_status.state == 'success' && !startsWith(github.event.deployment_status.environment, 'Production') && !startsWith(github.event.deployment_status.environment, 'production'))\n"
+    : ''
+  return `# Kaloko: walk the scenarios this pull request affects on its preview deployment and comment on the PR.
+# Written by kaloko ci github. Secrets: KALOKO_TOKEN (tester role, upload scope; on Enterprise a service account's);
+# TYPESAFE_API_KEY only if semantic criteria should use your own evaluator key.
+name: Kaloko
+on:
+${on}
+concurrency:
+  group: kaloko-\${{ github.event.deployment.sha || github.event.pull_request.head.sha || github.sha }}
+  cancel-in-progress: true
+permissions:
+  contents: read
+  deployments: read
+  pull-requests: write
+jobs:
+  walk:
+${guard}    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    env:
+      KALOKO_TOKEN: \${{ secrets.KALOKO_TOKEN }}
+      TYPESAFE_API_KEY: \${{ secrets.TYPESAFE_API_KEY }}
+      GH_TOKEN: \${{ github.token }}
+      KALOKO_AGENT: github-actions
+      KALOKO_BROWSER_CHANNEL: chromium
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: \${{ github.event.deployment.sha || github.event.pull_request.head.sha || github.sha }}
+          fetch-depth: 0   # walk --affected compares with the pull request's base
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${node}
+${install ? `${['pnpm', 'yarn'].includes(pm) ? '      - run: corepack enable\n' : ''}      - run: ${install}\n` : ''}      - run: ${k} browser install --with-deps   # the Chromium of kaloko's own Playwright
+      - name: Preview deployment
+        # the deployment's URL, the pull request and its base; waits for the preview when it is still building
+        run: ${k} ci preview-url --wait 600 --github-env
+      - name: Walk, share, comment
+        run: |
+${indent(walkScript({ scenarios, env, affected, k }), 10)}
+`
+}
+
+/** kaloko.gitlab-ci.yml, included from .gitlab-ci.yml */
+export function gitlabJob ({ scenarios, env = 'preview', affected = true, pm = 'npm', dependency = true, version = 'latest', playwright = '1.55.0' }) {
+  const { install, kaloko: k } = runner({ pm, dependency, version })
+  const indent = (lines, n) => lines.map((l) => ' '.repeat(n) + l).join('\n')
+  return `# Kaloko: walk the scenarios a merge request affects on its review app and comment on the MR.
+# Written by kaloko ci gitlab. Include it from .gitlab-ci.yml:  include: { local: kaloko.gitlab-ci.yml }
+# CI/CD variables (masked): KALOKO_TOKEN (tester role, upload scope); KALOKO_GITLAB_TOKEN (project access
+# token with the api scope) for the MR comment; TYPESAFE_API_KEY optional.
+kaloko:
+  stage: test        # run it after the job that deploys the review app (needs: [deploy_review])
+  image: mcr.microsoft.com/playwright:v${playwright}-noble
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+  variables:
+    GIT_DEPTH: "0"   # walk --affected compares with the target branch
+    KALOKO_BROWSER_CHANNEL: chromium
+    KALOKO_AGENT: gitlab-ci
+    # KALOKO_PREVIEW_URL: https://$CI_COMMIT_REF_SLUG.review.example.com   # when the review app URL is known
+  script:
+${install ? `${['pnpm', 'yarn'].includes(pm) ? '    - corepack enable\n' : ''}    - ${install}\n` : ''}    - ${k} browser install
+    - export KALOKO_PREVIEW_URL="$(${k} ci preview-url --wait 600)"
+    - git fetch origin "$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
+    - |
+${indent(walkScript({ scenarios, env, affected, k }), 6)}
+`
+}
+
+/** Adds the preview environment to kaloko.config.yml text (block style); null when it cannot be placed safely. */
+export function addPreviewEnvironment (text, name = 'preview') {
+  if (new RegExp(`^  ${name}:`, 'm').test(text)) return text
+  const m = text.match(/^environments:\s*$/m)
+  if (!m) return null
+  const block = [
+    `  ${name}:                                    # pull request previews (kaloko ci): the URL comes from CI`,
+    '    base_url: ${KALOKO_PREVIEW_URL}',
+    '    # access:                                 # Vercel deployment protection: a bypass for automation',
+    '    #   headers:',
+    '    #     x-vercel-protection-bypass: { env: VERCEL_AUTOMATION_BYPASS_SECRET }'
+  ].join('\n')
+  const at = m.index + m[0].length
+  return text.slice(0, at) + '\n' + block + text.slice(at)
+}

package/src/lib/config.mjs

@@ -48,6 +48,8 @@ export async function loadConfig (start = process.cwd(), explicit) {
   config.output ||= !(await exists(join(dirname(file), 'tmp', 'kaloko'))) && (await exists(join(dirname(file), 'tmp', 'qawalk'))) ? 'tmp/qawalk' : 'tmp/kaloko'
   config.browser ||= {}
   config.browser.port ||= 9333
+  // CI runs the bundled Chromium without a separate config: KALOKO_BROWSER_CHANNEL=chromium (or chrome, msedge)
+  if (process.env.KALOKO_BROWSER_CHANNEL != null) config.browser.channel = ['', 'chromium', 'bundled'].includes(process.env.KALOKO_BROWSER_CHANNEL) ? undefined : process.env.KALOKO_BROWSER_CHANNEL
   return { config, root: dirname(file), file }
 }
 

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/evaluate.mjs

@@ -101,8 +101,10 @@ export async function evaluateRun ({ run, scenario, config, root, fetchImpl }) {
       const semantic = outOfSample ? [] : (node.criteria || []).filter((c) => c.check.type === 'semantic' && !(c.check.about === 'console' && !(capture.console_errors || []).length))
       // quick signals ride along on every captured page state (also steps without semantic criteria)
       const signals = settings.signals !== false && !outOfSample && !!capture.state
-      const request = (semantic.length || signals) && current ? buildRequest({ node, capture, criteria: semantic, model: settings.model, signals }) : null
-      work.push({ entry, node, capture, current, outOfSample, request, asks: semantic.length > 0, jev: current ? null : { skipped: 'Capture has no matching criteria fingerprint; capture this step again.' } })
+      // an imported screen without page text (#11) has nothing to ask about: a person decides on the canvas
+      const textless = capture.capture?.source === 'import' && !capture.state
+      const request = (semantic.length || signals) && current && !textless ? buildRequest({ node, capture, criteria: semantic, model: settings.model, signals }) : null
+      work.push({ entry, node, capture, current, outOfSample, request, asks: semantic.length > 0, jev: !current ? { skipped: 'Capture has no matching criteria fingerprint; capture this step again.' } : textless && semantic.length ? { skipped: 'imported screenshot without page text; a person decides on the canvas' } : null })
       if (!current) report.outdated.add(entry.node)
     }
 

package/src/lib/git.mjs

@@ -59,12 +59,16 @@ export async function gitMeta (cwd) {
     out('git', ['rev-parse', 'HEAD'], cwd)
   ])
   let pr = null
-  const json = await out('gh', ['pr', 'view', '--json', 'number,url,state'], cwd)
+  const vars = process.env
+  // CI checks out a detached commit: the branch and pull request come from the environment
+  const ciBranch = vars.KALOKO_BRANCH || vars.GITHUB_HEAD_REF || vars.CI_MERGE_REQUEST_SOURCE_BRANCH_NAME || vars.CI_COMMIT_REF_NAME || null
+  if (vars.GITLAB_CI && vars.CI_MERGE_REQUEST_IID) pr = { number: Number(vars.CI_MERGE_REQUEST_IID), url: `${vars.CI_MERGE_REQUEST_PROJECT_URL || vars.CI_PROJECT_URL}/-/merge_requests/${vars.CI_MERGE_REQUEST_IID}`, state: 'open' }
+  const json = pr ? null : await out('gh', ['pr', 'view', ...(vars.KALOKO_PR ? [String(vars.KALOKO_PR)] : []), '--json', 'number,url,state'], cwd)
   if (json) {
     try {
       const p = JSON.parse(json)
       pr = { number: p.number, url: p.url, state: String(p.state).toLowerCase() }
     } catch {}
   }
-  return { branch, commit, sha, message, author, pr }
+  return { branch: branch === 'HEAD' && ciBranch ? ciBranch : branch, commit, sha, message, author, pr }
 }