kaloko 0.4.11 → 0.5.0

package/src/cli.mjs

@@ -51,9 +51,13 @@ import { exportDesign } from './lib/design-export.mjs'
 import { driverFor, isApp, pngSize, ocr as ocrImage } from './lib/apps/drivers.mjs'
 import { captureApp } from './lib/apps/capture.mjs'
 import { readTree, flatten } from './lib/apps/tree.mjs'
-import { recordSettings, recordingSession, recordingFiles, traceFiles, stripRecordings, withoutRecordings } from './lib/recording.mjs'
+import { recordSettings, recordingSession, parseRecord, recordingFiles, traceFiles, stripRecordings, withoutRecordings } from './lib/recording.mjs'
 import { nativeSession } from './lib/apps/recording-native.mjs'
 import { videoCmd } from './lib/video-cli.mjs'
+import { passesOf, enginesOf, contextOptionsOf, launchEngine, pickKeys, variantFields, variantOf, dimensionValues, BROWSERS } from './lib/dimensions.mjs'
+import { startScope, scopeKeys, dimensionLine, baseViewports, engineKeys, appDeviceGroups } from './lib/walk-dimensions.mjs'
+import { deviceConfig, prepareAndroid, readyAndroid, finishAndroid, prepareSimulator, applyAppAppearance } from './lib/apps/devices.mjs'
+import { attachAndroidWebView } from './lib/apps/webview.mjs'
 
 
 const HELP = `kaloko — walk, assess and approve what your agents built, on one flow canvas
@@ -91,9 +95,19 @@ Run
   start --scenario <file> --env <name> [--locales cs,en] [--viewports desktop,mobile] [--executor <name>]
                                     [--app-version <v>] (default: the git tag on HEAD; documentation captures carry it)
                                     Create a run directory and make it current
+       [--viewports iphone-15,ipad-landscape,desktop]   Viewport names of the scenario or device presets
+                                    (kaloko devices lists them; <preset>-landscape turns one sideways)
+       [--browsers chromium,webkit,firefox] [--color-schemes light,dark] [--reduced-motion no-preference,reduce]
+       [--forced-colors none,active] [--display-modes browser,standalone]
+                                    More dimensions: every step is captured in each combination (keys like
+                                    mobile.webkit.dark); default from the scenario, then walk: in the config
+       [--devices pixel-8-api-34,iphone-15-ios-18]   App scenarios: the emulators, simulators or devices to walk on
   browser start|stop|status [--env e] [--headed]   One shared browser per environment (port = browser.port + index)
                                     Shared Chromium with CDP (agents, scripts and people drive it)
-  browser install [--with-deps]     Download the Chromium of kaloko's Playwright (CI; KALOKO_BROWSER_CHANNEL=chromium uses it)
+  browser install [--with-deps] [--browsers chromium,webkit,firefox]
+                                    Download the engines of kaloko's Playwright (default Chromium; CI:
+                                    KALOKO_BROWSER_CHANNEL=chromium uses it); WebKit and Firefox for cross-browser runs
+  devices [--json]                  Device presets for viewports: (phones, foldables, tablets, laptop, desktop, TV)
   open --step <id> [--locale l]     Navigate the current page to the step URL
   session reset                     New visitor: clear cookies and storage in the shared browser
   capture --step <id> [--locale l] [--url <url>] [--page <substring>] [--viewports a,b]
@@ -115,10 +129,14 @@ Run
                                     A person signs in once (SSO, MFA) in a visible browser; the session is saved
                                     for that account and walk reuses it (never uploaded)
   auth list                         Saved sessions per environment and account, with their age
-  walk [--steps a,b] [--locales l] [--keep-going] [--ephemeral]
+  walk [--steps a,b] [--locales l] [--keep-going] [--ephemeral] [--browsers webkit]
                                     Run playwright steps (execution.script) and capture them; a session stops
                                     after 3 steps in a row fail with the same error unless --keep-going
                                     One walk at a time per shared browser; --ephemeral walks in an own browser
+                                    A run with several browsers or device presets walks once per engine and device
+                                    profile; --browsers walks only those engines of the run
+       [--devices pixel-8-api-34]   App runs walk once per device of devices: (emulators start, phones wake up);
+                                    --devices walks only those; dark mode and reduced motion are set per capture
                                     Semantic questions start as each step is captured; the walk ends with the
                                     verdicts and what failed (--no-evaluate skips that; kaloko evaluate redoes it)
        [--items a,b] [--limit N]    Stack steps (kind: stack, many pages of one template): only pages whose id or
@@ -353,10 +371,20 @@ async function scenarioIdOf (args, config, root) {
   throw new UserError('--scenario <id|file> is required when there is no current run.')
 }
 
+/**
+ * Keys a capture of the current page takes (kaloko capture): the Chromium keys without a device preset, whose
+ * pixel ratio, touch and agent the page does not have; a preset key only when --viewports names it.
+ */
+function manualKeys (run, pick) {
+  const scope = run.meta.scope
+  if (pick) return scopeViewports(run, pick)
+  const keys = engineKeys(scope, 'chromium').filter((k) => !scope.devices?.[variantOf(scope, k).viewport]?.emulation)
+  return scopeKeys(scope, keys.length ? keys : engineKeys(scope, 'chromium'), null)
+}
+
+/** { key: [w, h] } a capture on a Chromium page takes: every Chromium key of the run, or those of `pick`. */
 function scopeViewports (run, pick) {
-  const all = run.meta.scope.viewports
-  const names = pick || Object.keys(all)
-  return Object.fromEntries(names.map((n) => { if (!all[n]) throw new UserError(`Unknown viewport "${n}".`); return [n, all[n]] }))
+  return scopeKeys(run.meta.scope, engineKeys(run.meta.scope, 'chromium'), pick)
 }
 
 async function scenarioFiles (config, root) {
@@ -472,14 +500,17 @@ async function exportScenario ({ args, config, root, client }) {
  * Walks a stack step: resolves its pages, then opens and captures each one with the step's criteria and index
  * fields (HTTP status of the main document included). A step script, when given, runs per page with `item`.
  */
-async function walkStack ({ node, locale, page, env, run, scenario, scenarioDir, config, consoleFile, args }) {
+async function walkStack ({ node, locale, page, env, run, scenario, scenarioDir, config, consoleFile, args, keys = null, tag = '' }) {
   const { items, total, truncated } = await resolveItems({ node, base: baseUrl(env, locale), page, scenarioDir, env, locale, limit: Number(args.limit) || undefined })
   const only = list(args.items)
   const chosen = only ? items.filter((it) => only.some((q) => it.id === q || it.path.includes(q))) : items
-  const scope = run.meta.scope.viewports
-  const vpNames = (node.items.viewports || []).filter((v) => scope[v])
-  const viewports = Object.fromEntries((vpNames.length ? vpNames : [Object.keys(scope)[0]]).map((v) => [v, scope[v]]))
-  say(`▦ ${node.id} ${locale}: ${chosen.length} page(s)${truncated ? ` — limit ${Number(args.limit) || node.items.limit || DEFAULT_LIMIT} reached (${total}+ found; raise items.limit or pass --limit)` : ''}`)
+  const passKeys = keys || engineKeys(run.meta.scope, 'chromium')
+  const bases = baseViewports(run.meta.scope)
+  const vpNames = (node.items.viewports || []).filter((v) => bases.includes(v) || run.meta.scope.viewports[v])
+  const passBases = baseViewports({ ...run.meta.scope, viewports: Object.fromEntries(passKeys.map((k) => [k, run.meta.scope.viewports[k]])) })
+  const viewports = scopeKeys(run.meta.scope, passKeys, vpNames.length ? vpNames : [passBases[0] || bases[0]])
+  if (!Object.keys(viewports).length) { say(`▦ ${node.id} ${locale}${tag}: no viewport of this step in this pass`); return [] }
+  say(`▦ ${node.id} ${locale}${tag}: ${chosen.length} page(s)${truncated ? ` — limit ${Number(args.limit) || node.items.limit || DEFAULT_LIMIT} reached (${total}+ found; raise items.limit or pass --limit)` : ''}`)
   const fields = fieldsOf(node)
   const script = node.execution?.script ? await import(pathToFileURL(resolve(scenarioDir, node.execution.script)).href) : null
   let status = null
@@ -493,7 +524,7 @@ async function walkStack ({ node, locale, page, env, run, scenario, scenarioDir,
       status = null
       const since = Date.now()
       let captured = false
-      const capture = (opts = {}) => { captured = true; return captureStep({ page, node, locale, viewports: opts.viewports ? Object.fromEntries(opts.viewports.map((v) => [v, scope[v]])) : viewports, run, consoleFile, since, item, fields, maxChars: config.evaluators?.jev?.max_state_chars, options: captureOptions(scenario, node), extra: { http_status: status } }) }
+      const capture = (opts = {}) => { captured = true; return captureStep({ page, node, locale, viewports: opts.viewports ? scopeKeys(run.meta.scope, passKeys, opts.viewports) : viewports, run, consoleFile, since, item, fields, maxChars: config.evaluators?.jev?.max_state_chars, options: captureOptions(scenario, node), extra: { http_status: status } }) }
       try {
         if (script) await script.default({ page, item, url: () => item.url, locale, env, run: run.meta, capture, acceptDialogs: () => acceptDialogs(page) })
         else await page.goto(item.url, { waitUntil: 'domcontentloaded', timeout: 30000 })
@@ -501,12 +532,12 @@ async function walkStack ({ node, locale, page, env, run, scenario, scenarioDir,
         ok++; streak.ok('stack')
       } catch (error) {
         failed.push(`${item.id} (${item.path}): ${error.message.split('\n')[0]}`)
-        if (streak.record('stack', error.message)) say(`  stopping ${node.id} (${locale}): the last 5 pages failed with the same error`)
+        if (streak.record('stack', error.message)) say(`  stopping ${node.id} (${locale}${tag}): the last 5 pages failed with the same error`)
       }
       if ((i + 1) % 25 === 0 && i + 1 < chosen.length) say(`  ${node.id} ${locale}: ${i + 1}/${chosen.length}`)
     }
   } finally { page.off('response', onResponse) }
-  say(`${failed.length ? '✗' : '✓'} ${node.id} ${locale}: ${ok}/${chosen.length} page(s) captured`)
+  say(`${failed.length ? '✗' : '✓'} ${node.id} ${locale}${tag}: ${ok}/${chosen.length} page(s) captured`)
   return failed
 }
 
@@ -529,14 +560,17 @@ function lazyEncoder (config) {
 const appViewport = (run) => Object.keys(run.meta.scope.viewports || {})[0] || null
 
 /**
- * Walks an app scenario (platform android, ios, electron, desktop) with the environment's driver: per locale the
- * app starts fresh, each step runs its script (with `app`, the driver) or opens its deep link, then is captured.
+ * Walks an app scenario (platform android, ios, electron, desktop, windows) with the environment's driver: per
+ * device of the run (devices:, batch E) and locale the app starts fresh, each step runs its script (with `app`, the
+ * driver) or opens its deep link, then is captured in each of the device's keys (dark mode, reduced motion set on
+ * the device). `capture({ webview: true })` (or app.android.webview) captures an Android WebView's page instead.
  */
 async function walkApp ({ config, root, run, scenario, env, args }) {
   const platform = scenario.platform
   const pick = list(args.steps)
   const locales = list(args.locales) || run.meta.scope.locales
   const scenarioDir = resolve(root, run.meta.scenario_file, '..')
+  const scope = run.meta.scope
   const pending = []; const failed = []; const skipped = []
   // WebP and thumbnails are encoded in a headless Chrome page (no native image dependency); PNG without Chrome
   const enc = await launchEphemeral(config).catch(() => null)
@@ -545,65 +579,111 @@ async function walkApp ({ config, root, run, scenario, env, args }) {
   const maxChars = config.evaluators?.jev?.max_state_chars
   // recordings and traces (batch D): Electron windows use the screencast recorder, devices record themselves
   const recSettings = recordSettings({ args, config, scenario })
+  const groups = appDeviceGroups(scope, list(args.devices))
+  // app captures carry the scheme and motion of their key (no browser: the app draws itself)
+  const fieldsOf = (key) => { const { browser: _b, ...f } = variantFields(scope, key); return f }
   try {
-    for (const locale of locales) {
-      const driver = driverFor(platform, env, { root, scenarioDir, locale })
-      try {
-        await driver.open({ locale, reset: true })
-        if (driver.web) observeConsole(driver.page)
-        say(`${platform} ${locale}: ${driver.web ? 'Electron window' : 'app'} ready`)
-      } catch (error) { failed.push(`${platform} (${locale}): ${error.message.split('\n')[0]}`); say(`✗ ${platform} ${locale}: ${error.message.split('\n')[0]}`); await driver.close().catch(() => {}); if (error instanceof UserError) break; continue }
-      const rec = driver.web
-        ? await recordingSession({ page: driver.page, run, scenario, locale, settings: recSettings, viewports: run.meta.scope.viewports, encoder: async () => encoder, say, label: `${platform} ${locale}` }).catch(() => null)
-        : await nativeSession({ platform, env, run, scenario, locale, settings: recSettings, driver, encoder: async () => encoder, say }).catch(() => null)
+    for (const group of groups) {
+      const tag = group.device && groups.length > 1 ? ` · ${group.title}` : ''
+      if (groups.length > 1) say(`\n${group.title}: ${group.keys.join(', ')}`)
+      // the device: its entry in app.<platform>.devices or what its name says; an emulator starts, a phone wakes up
+      let cfg = deviceConfig(platform, env.app?.[platform] || {}, group.device)
       try {
-        for (const node of scenario.nodes) {
-          if (node.kind === 'decision' || (pick && !pick.includes(node.id))) continue
-          if (node.kind === 'stack') { pending.push(`${node.id} (${locale}): stack steps list web pages; not walked on ${platform}`); continue }
-          if (node.kind === 'email' && node.mail?.to) {
-            try { const r = await captureMail({ config, root, run, env, node, locale, to: expandRun(node.mail.to, run.meta.short), subject: localized(node.mail?.subject, locale), timeoutMs: 45000 }); say(`✓ ${node.id} ${locale}: "${r.subject}"`) } catch (error) { failed.push(`${node.id} (${locale}): ${error.message.split('\n')[0]}`); say(`✗ ${node.id} ${locale}: ${error.message.split('\n')[0]}`) }
-            continue
-          }
-          const scripted = ['playwright', 'script'].includes(node.execution?.strategy) && node.execution?.script
-          const link = linkFor(env, node, locale)
-          if (!scripted && !(link && ['playwright', 'script'].includes(node.execution?.strategy))) { pending.push(`${node.id} (${locale}): ${node.execution?.strategy || 'agent'} — ${(node.execution?.instructions || '').split('\n')[0]}`); continue }
-          if (streak.stopped(locale)) { skipped.push(`${node.id} (${locale})`); continue }
-          const records = []
-          try {
-            let captured = false
-            await rec?.beforeStep(node)
-            const capture = async (o = {}) => {
-              captured = true
-              await rec?.beforeCapture(node)
-              if (driver.web) {
-                const [w, h] = await driver.page.evaluate(() => [innerWidth, innerHeight])
-                const r = await captureStep({ page: driver.page, node, locale, options: captureOptions(scenario, node), viewports: { [o.viewport || appViewport(run) || 'window']: [w, h] }, run, consoleFile: null, maxChars, extra: { platform, device: 'Electron' } })
-                records.push(...r)
-                return r
+        if (platform === 'android') { cfg = await prepareAndroid(cfg, { say }); await readyAndroid(cfg) }
+        if (platform === 'ios' && group.device) cfg = await prepareSimulator(cfg)
+      } catch (error) { failed.push(`${group.device || platform}: ${error.message.split('\n')[0]}`); say(`✗ ${group.device || platform}: ${error.message.split('\n')[0]}`); continue }
+      const denv = { ...env, app: { ...(env.app || {}), [platform]: cfg } }
+      // recordings and traces land on this device's keys (a failed step without a capture: its first key)
+      const grun = { ...run, meta: { ...run.meta, scope: { ...scope, viewports: scopeKeys(scope, group.keys) } } }
+      let look = { key: null, undo: async () => {} } // the system appearance the device is in now
+      const appearance = async (driver, key) => {
+        const v = scope.variants?.[key] || null
+        const want = JSON.stringify([v?.color_scheme || null, v?.reduced_motion || null])
+        if (look.key === want) return look.notes || []
+        await look.undo()
+        const r = await applyAppAppearance(platform, cfg, driver, v)
+        look = { key: want, undo: r.undo, notes: r.notes }
+        return r.notes
+      }
+      for (const locale of locales) {
+        const driver = driverFor(platform, denv, { root, scenarioDir, locale })
+        let webview = null
+        if (platform === 'android') driver.webview = async () => (webview ||= await attachAndroidWebView(cfg)).page
+        try {
+          await driver.open({ locale, reset: true })
+          if (driver.web) observeConsole(driver.page)
+          say(`${platform} ${locale}${tag}: ${driver.web ? 'Electron window' : 'app'} ready`)
+        } catch (error) { failed.push(`${platform} (${locale}${tag}): ${error.message.split('\n')[0]}`); say(`✗ ${platform} ${locale}${tag}: ${error.message.split('\n')[0]}`); await driver.close().catch(() => {}); if (error instanceof UserError) break; continue }
+        const rec = driver.web
+          ? await recordingSession({ page: driver.page, run: grun, scenario, locale, settings: recSettings, viewports: grun.meta.scope.viewports, encoder: async () => encoder, say, label: `${platform} ${locale}${tag}` }).catch(() => null)
+          : await nativeSession({ platform, env: denv, run: grun, scenario, locale, settings: recSettings, driver, encoder: async () => encoder, say }).catch(() => null)
+        try {
+          for (const node of scenario.nodes) {
+            if (node.kind === 'decision' || (pick && !pick.includes(node.id))) continue
+            if (node.kind === 'stack') { pending.push(`${node.id} (${locale}): stack steps list web pages; not walked on ${platform}`); continue }
+            if (node.kind === 'email' && group !== groups[0]) continue // one message, captured on the first device
+            if (node.kind === 'email' && node.mail?.to) {
+              try { const r = await captureMail({ config, root, run, env, node, locale, to: expandRun(node.mail.to, run.meta.short), subject: localized(node.mail?.subject, locale), timeoutMs: 45000 }); say(`✓ ${node.id} ${locale}: "${r.subject}"`) } catch (error) { failed.push(`${node.id} (${locale}): ${error.message.split('\n')[0]}`); say(`✗ ${node.id} ${locale}: ${error.message.split('\n')[0]}`) }
+              continue
+            }
+            const scripted = ['playwright', 'script'].includes(node.execution?.strategy) && node.execution?.script
+            const link = linkFor(env, node, locale)
+            if (!scripted && !(link && ['playwright', 'script'].includes(node.execution?.strategy))) { pending.push(`${node.id} (${locale}): ${node.execution?.strategy || 'agent'} — ${(node.execution?.instructions || '').split('\n')[0]}`); continue }
+            const streakKey = `${group.device || ''}|${locale}`
+            if (streak.stopped(streakKey)) { skipped.push(`${node.id} (${locale}${tag})`); continue }
+            const records = []
+            try {
+              let captured = false
+              await rec?.beforeStep(node)
+              const capture = async (o = {}) => {
+                captured = true
+                await rec?.beforeCapture(node)
+                // a named viewport: within this device, or any of the run when it has no devices (as before)
+                const keys = o.viewport ? pickKeys(scope, group.device ? group.keys : Object.keys(scope.viewports), [o.viewport]) : group.keys
+                if (!keys.length) throw new UserError(`Unknown viewport "${o.viewport}" for ${group.device || platform}.`)
+                const out = []
+                for (const key of keys) {
+                  if (driver.web) {
+                    // Electron: a web capture; captureStep emulates the key's scheme and motion itself
+                    const [w, h] = await driver.page.evaluate(() => [innerWidth, innerHeight])
+                    out.push(...await captureStep({ page: driver.page, node, locale, options: captureOptions(scenario, node), viewports: { [key]: [w, h] }, run, consoleFile: null, maxChars, extra: { platform, device: 'Electron' } }))
+                    continue
+                  }
+                  const notes = await appearance(driver, key)
+                  if (o.webview || (cfg.webview && o.webview !== false)) {
+                    if (!driver.webview) throw new UserError(`WebView captures need an Android app; on ${platform} capture the screen (tree or OCR).`)
+                    const page = await driver.webview()
+                    const [w, h] = await page.evaluate(() => [innerWidth, innerHeight])
+                    out.push(...await captureStep({ page, node, locale, options: captureOptions(scenario, node), viewports: { [key]: [w, h] }, run, consoleFile: null, maxChars, extra: { platform, device: cfg.device || null, webview: true, ...fieldsOf(key) } }))
+                    continue
+                  }
+                  out.push(await captureApp({ snapshot: await driver.snapshot(), node, locale, viewport: key, run, platform, encoder, maxChars, extra: { url: link, ...fieldsOf(key), ...(notes.length ? { notes } : {}) } }))
+                }
+                records.push(...out)
+                return out.length === 1 ? out[0] : out
               }
-              const r = await captureApp({ snapshot: await driver.snapshot(), node, locale, viewport: o.viewport || appViewport(run), run, platform, encoder, maxChars, extra: { url: link } })
-              records.push(r)
-              return r
+              if (scripted) {
+                const mod = await import(pathToFileURL(resolve(scenarioDir, node.execution.script)).href)
+                await mod.default({ app: driver, page: driver.page || null, webview: driver.webview || null, locale, node: { id: node.id, title: localized(node.title, locale), kind: node.kind }, device: group.device, env, run: run.meta, capture, link: (id = node.id) => linkFor(env, stepOf(scenario, id), locale), url: (id = node.id) => linkFor(env, stepOf(scenario, id), locale) })
+              } else await driver.link(link)
+              if (!captured) await capture()
+              await rec?.afterStep(node, driver.web ? { records } : { record: records[0] })
+              say(`✓ ${node.id} ${locale}${tag}`)
+              streak.ok(streakKey)
+            } catch (error) {
+              await rec?.afterStep(node, driver.web ? { error, records } : { error, record: records[0] }).catch(() => {})
+              failed.push(`${node.id} (${locale}${tag}): ${error.message.split('\n')[0]}`)
+              say(`✗ ${node.id} ${locale}${tag}: ${error.message.split('\n')[0]}`)
+              if (streak.record(streakKey, error.message)) say(`  stopping ${locale}${tag}: the last 3 steps failed with the same error`)
             }
-            if (scripted) {
-              const mod = await import(pathToFileURL(resolve(scenarioDir, node.execution.script)).href)
-              await mod.default({ app: driver, page: driver.page || null, locale, node: { id: node.id, title: localized(node.title, locale), kind: node.kind }, env, run: run.meta, capture, link: (id = node.id) => linkFor(env, stepOf(scenario, id), locale), url: (id = node.id) => linkFor(env, stepOf(scenario, id), locale) })
-            } else await driver.link(link)
-            if (!captured) await capture()
-            await rec?.afterStep(node, driver.web ? { records } : { record: records[0] })
-            say(`✓ ${node.id} ${locale}`)
-            streak.ok(locale)
-          } catch (error) {
-            await rec?.afterStep(node, driver.web ? { error, records } : { error, record: records[0] }).catch(() => {})
-            failed.push(`${node.id} (${locale}): ${error.message.split('\n')[0]}`)
-            say(`✗ ${node.id} ${locale}: ${error.message.split('\n')[0]}`)
-            if (streak.record(locale, error.message)) say(`  stopping ${locale}: the last 3 steps failed with the same error`)
           }
+        } finally {
+          for (const n of (await rec?.finish().catch((e) => [`recording: ${e.message}`])) || []) say(`  ${n}`)
+          await webview?.close(); await driver.close().catch(() => {})
         }
-      } finally {
-        for (const n of (await rec?.finish().catch((e) => [`recording: ${e.message}`])) || []) say(`  ${n}`)
-        await driver.close().catch(() => {})
       }
+      await look.undo().catch(() => {})
+      if (platform === 'android') await finishAndroid(cfg)
     }
   } finally { await enc?.close().catch(() => {}) }
   if (pending.length) say(`\nSteps for an agent or a person (drive the app, then kaloko capture --step <id> --image shot.png [--tree dump.xml|json]):\n  - ${[...new Set(pending)].join('\n  - ')}`)
@@ -771,29 +851,40 @@ const commands = {
     if (scenario.environments && !scenario.environments.includes(env.name)) throw new UserError(`Scenario ${scenario.id} is not allowed on ${env.name} (allowed: ${scenario.environments.join(', ')}).`)
     if (env.readonly && !scenario.readonly) throw new UserError(`Environment ${env.name} is readonly; the scenario must declare readonly: true.`)
     const locales = list(args.locales) || scenario.locales || ['default']
-    const vpAll = scenario.viewports || { desktop: [1280, 800], mobile: [390, 844] }
-    const vpNames = list(args.viewports) || Object.keys(vpAll)
-    const scope = { locales, viewports: Object.fromEntries(vpNames.map((n) => [n, vpAll[n]])), ...(args.note ? { note: args.note } : {}) }
+    const scope = { ...startScope({ args, scenario, config, env }), ...(args.note ? { note: args.note } : {}) }
+    scope.locales = locales
+    const vpNames = baseViewports(scope)
     const git = await gitMeta(root)
     const executor = { kind: args.executor ? 'agent' : 'cli', name: args.executor || 'kaloko-cli' }
     const { project, issue } = await projectAndIssue({ cwd: root, config, scenario, branch: git?.branch })
     const appVer = typeof args['app-version'] === 'string' ? args['app-version'].slice(0, 80) : await appVersion(root)
     const { dir, meta } = await createRun({ output: config.output, scenario, scenarioFile, env, scope, git, executor, root, project, issue, appVersion: appVer })
-    say(`Run ${meta.id}\n  dir: ${relative(process.cwd(), dir)}\n  env: ${env.name}${env.readonly ? ' (readonly)' : ''}\n  locales: ${locales.join(', ')}  viewports: ${vpNames.join(', ')}\n  project: ${project.slug}${issue ? `  issue: ${issue.repo ? issue.repo + '#' : '#'}${issue.number}` : ''}`)
+    say(`Run ${meta.id}\n  dir: ${relative(process.cwd(), dir)}\n  env: ${env.name}${env.readonly ? ' (readonly)' : ''}\n  locales: ${locales.join(', ')}  viewports: ${vpNames.length > 12 ? `${vpNames.slice(0, 12).join(', ')} … (${vpNames.length})` : vpNames.join(', ')}${dimensionLine(scope)}\n  project: ${project.slug}${issue ? `  issue: ${issue.repo ? issue.repo + '#' : '#'}${issue.number}` : ''}`)
     const addr = recipient(env.mail, meta.short)
     if (addr) say(`  test e-mail: ${addr}`)
     say(`  other agents may start runs here too: pin this one with --run ${meta.id} or KALOKO_RUN=${meta.id}`)
   },
 
+  /** `kaloko devices`: the device presets a scenario's viewports may name. */
+  async devices (args) {
+    const { DEVICES, devicePreset } = await import('./lib/devices.mjs')
+    const all = Object.keys(DEVICES).map((n) => devicePreset(n))
+    if (args.json) { say(JSON.stringify(all, null, 2)); return }
+    for (const d of all) say(`${d.name.padEnd(26)} ${d.title.padEnd(28)} ${`${d.size[0]}×${d.size[1]}`.padEnd(10)} screen ${`${d.screen[0]}×${d.screen[1]}`.padEnd(10)} ${String(d.dpr).padEnd(6)}× ${d.touch ? 'touch' : ''}`)
+    say('\nUse them in viewports: (a list of names, or name: preset), or kaloko start --viewports iphone-15,desktop-hd.\n<preset>-landscape turns a phone, foldable or tablet sideways; Design environments use the whole screen.')
+  },
+
   async browser (args) {
     const { config, root } = await context(args)
     const action = args._[0] || 'status'
     if (action === 'install') {
-      // the Chromium of the Playwright version kaloko itself uses (CI: --with-deps adds the system libraries)
+      // the engines of the Playwright version kaloko itself uses (CI: --with-deps adds the system libraries)
+      const engines = list(args.browsers) || ['chromium']
+      for (const e of engines) if (!BROWSERS.includes(e)) throw new UserError(`Unknown browser engine ${e}. Use: ${BROWSERS.join(', ')}.`)
       const { spawn } = await import('node:child_process')
       const cli = join(dirname(fileURLToPath(import.meta.resolve('playwright/package.json'))), 'cli.js')
-      const code = await new Promise((done) => spawn(process.execPath, [cli, 'install', ...(args['with-deps'] ? ['--with-deps'] : []), 'chromium'], { stdio: 'inherit' }).on('close', done))
-      if (code) throw new UserError(`Installing Chromium failed (exit ${code}).`)
+      const code = await new Promise((done) => spawn(process.execPath, [cli, 'install', ...(args['with-deps'] ? ['--with-deps'] : []), ...engines], { stdio: 'inherit' }).on('close', done))
+      if (code) throw new UserError(`Installing ${engines.join(', ')} failed (exit ${code}).`)
       return
     }
     let env = null
@@ -836,13 +927,17 @@ const commands = {
       return
     }
     if (isApp(scenario.platform)) {
-      // the app's current screen, through the environment's driver (no navigation)
-      const driver = driverFor(scenario.platform, env, { root, scenarioDir: resolve(root, run.meta.scenario_file, '..'), locale })
+      // the app's current screen, through the environment's driver (no navigation); --viewport may name a device key
+      const key = typeof args.viewport === 'string' ? args.viewport : Object.keys(run.meta.scope.viewports || {})[0]
+      const device = run.meta.scope.devices?.[variantOf(run.meta.scope, key).viewport]?.app ? variantOf(run.meta.scope, key).viewport : null
+      const cfg = deviceConfig(scenario.platform, env.app?.[scenario.platform] || {}, device)
+      const driver = driverFor(scenario.platform, { ...env, app: { ...(env.app || {}), [scenario.platform]: cfg } }, { root, scenarioDir: resolve(root, run.meta.scenario_file, '..'), locale })
       if (driver.web) throw new UserError('For Electron, run kaloko walk --steps <id>, or pass --image.')
       await driver.open({ locale, attach: true })
       const enc = await launchEphemeral(config).catch(() => null)
       try {
-        const r = await captureApp({ snapshot: await driver.snapshot(), node, locale, viewport: typeof args.viewport === 'string' ? args.viewport : Object.keys(run.meta.scope.viewports || {})[0], run, platform: scenario.platform, encoder: enc ? await enc.newPage() : null, maxChars: config.evaluators?.jev?.max_state_chars })
+        const { browser: _b, ...dims } = variantFields(run.meta.scope, key)
+        const r = await captureApp({ snapshot: await driver.snapshot(), node, locale, viewport: key, run, platform: scenario.platform, encoder: enc ? await enc.newPage() : null, maxChars: config.evaluators?.jev?.max_state_chars, extra: dims })
         say(`✓ ${node.id} ${locale} ${r.viewport}  ${r.device || scenario.platform}  ${r.files.tree ? `UI tree (${r.capture.tree})` : 'no UI tree'}`)
       } finally { await enc?.close().catch(() => {}) }
       return
@@ -867,7 +962,7 @@ const commands = {
         return
       }
       const since = (await readCaptures(run.dir)).filter((c) => c.node === node.id).map((c) => c.at).pop()
-      const results = await captureStep({ page, node, locale, options: captureOptions(scenario, node), viewports: scopeViewports(run, list(args.viewports)), run, consoleFile: conn ? consoleLog(root, config.output, env.name) : null, maxChars: config.evaluators?.jev?.max_state_chars, since, htmlView: htmlViewAllowed(env, scenario) ? { scenarioId: scenario.id } : null, stability: Number(args.stability) || 0 })
+      const results = await captureStep({ page, node, locale, options: captureOptions(scenario, node), viewports: manualKeys(run, list(args.viewports)), run, consoleFile: conn ? consoleLog(root, config.output, env.name) : null, maxChars: config.evaluators?.jev?.max_state_chars, since, htmlView: htmlViewAllowed(env, scenario) ? { scenarioId: scenario.id } : null, stability: Number(args.stability) || 0 })
       for (const r of results) {
         const failed = Object.entries(r.checks).filter(([, v]) => v.ok === false).map(([k]) => k)
         say(`✓ ${node.id} ${locale} ${r.viewport}  ${r.size.width}×${r.size.height}px  ${failed.length ? `failing checks: ${failed.join(', ')}` : 'checks ok'}${r.blocked_requests.length ? `  blocked: ${r.blocked_requests.length}` : ''}`)
@@ -933,17 +1028,23 @@ const commands = {
     if (isApp(scenario.platform)) return walkApp({ config, root, run, scenario, env, args })
     const pick = list(args.steps)
     const locales = list(args.locales) || run.meta.scope.locales
+    const scope = run.meta.scope
+    // browser engines and device profiles (batch E): one pass each, capturing only its own keys; a run without
+    // dimensions has a single pass, the walk of before
+    const only = args.browsers ? dimensionValues('browsers', args.browsers) : null
+    const passes = passesOf(scope, { only })
+    if (!passes.length) throw new UserError(`This run has no captures in ${only.join(', ')} (its browsers: ${enginesOf(scope).join(', ')}).`)
+    const needChromium = passes.some((p) => p.engine === 'chromium')
     // --ephemeral: an own browser (own cookies and tabs) even when the shared one runs, so runs can walk in parallel
     configureGate(await gateForRequests(env, { root }))
-    const conn = args.ephemeral ? null : await connectBrowser({ root, config, env })
+    const conn = args.ephemeral || !needChromium ? null : await connectBrowser({ root, config, env })
     const releaseLock = conn ? await acquireWalkLock({ root, config, env, run: run.meta.id }).catch(async (e) => { await conn.browser.close(); throw e }) : null
-    const ephemeral = conn ? null : await launchEphemeral(config)
-    const browser = conn ? conn.browser : ephemeral
+    const ephemeral = conn || !needChromium ? null : await launchEphemeral(config)
+    const chromium = conn ? conn.browser : ephemeral
     // locales are independent: with --concurrency > 1 each walks in its own browser context at the same time (#27);
     // one locale at a time keeps the shared browser's own context, as before
     const concurrency = walkConcurrency(args, config, locales.length, !!conn)
     const parallel = concurrency > 1 && locales.length > 1
-    const ctx = parallel ? null : conn ? conn.context : await newContext(ephemeral, env, { root, config })
     const scenarioDir = resolve(root, run.meta.scenario_file, '..')
     // semantic questions of every new capture start right away; the walk ends with the verdicts (--no-evaluate: skip)
     const prefetch = args['no-evaluate'] ? null : semanticPrefetch({ scenario, config, root })
@@ -952,127 +1053,156 @@ const commands = {
     const recSettings = recordSettings({ args, config, scenario })
     const encoder = lazyEncoder(config)
     const sessions = scenario.sessions || null
-    // named sessions: one isolated browser context per person and locale (cookies, storage, sign-in), created lazily
-    const sessionContexts = new Map()
     const ownContexts = []
+    const engines = new Map() // WebKit and Firefox, launched for their passes
     // `account` stays the scenario's key; `credentials` resolves it in this environment (config accounts)
     const sessionInfo = (key) => key && sessions?.[key] ? { key, title: localized(sessions[key].title, locales[0]), mailbox: sessions[key].mailbox ? expandRun(sessions[key].mailbox, run.meta.short) : null, account: sessions[key].account || null, credentials: accountFor(env, sessions[key].account, { root, config }) } : null
-    const contextFor = async (key, locale) => {
-      if (!key || !sessions?.[key]) return null
-      const id = `${key}|${locale}`
-      if (!sessionContexts.has(id)) {
-        // every context gets the environment's gate and readonly policy; an account's saved sign-in is loaded
-        const account = accountFor(env, sessions[key].account, { root, config })
-        const c = await newContext(browser, env, { root, config, account })
-        const p = await c.newPage()
-        observeConsole(p)
-        sessionContexts.set(id, { context: c, page: p })
-        const saved = account && await access(account.storage_state).then(() => true, () => false)
-        say(`session ${key} (${locale}): new browser context${saved ? ' with the saved sign-in' : ''}`)
-      }
-      return sessionContexts.get(id)
-    }
     // stop a session after the same failure repeats (shared precondition such as a failed sign-in);
     // --keep-going walks every step regardless
     const streak = failureStreak(args['keep-going'] ? 0 : 3)
     const proposals = []
-    // one locale: its own tab (and, in parallel, its own context); returns what it could not walk
-    const walkLocale = async (locale) => {
-      const pending = []; const failed = []; const skipped = []
-      let lctx = ctx
-      if (parallel) { lctx = await newContext(browser, env, { root, config }); ownContexts.push(lctx) }
-      // the walk owns its tab; agents and people keep theirs in the same shared browser
-      const page = await lctx.newPage()
-      const shared = conn && !parallel // the shared browser's own context logs its console to a file
-      if (!shared) observeConsole(page)
-      // one recorder per page (the walk's tab and each named session's), started on its first step
-      const recorders = new Map()
-      const recorderFor = async (p) => {
-        if (!recorders.has(p)) recorders.set(p, recordingSession({ page: p, run, scenario, locale, settings: recSettings, viewports: run.meta.scope.viewports, encoder: encoder.page, say, label: locale }).catch(() => null))
-        return recorders.get(p)
-      }
-      try {
-        // every locale starts as a new visitor on its first walk in the run (an own context is new already)
-        if (shared && !walked.some((c) => c.locale === locale)) { await resetSession(lctx, page, baseUrl(env, locale)); say(`session reset (new visitor, ${locale})`) }
-        for (const node of scenario.nodes) {
-          if (node.kind === 'decision' || (pick && !pick.includes(node.id))) continue
-          if (node.kind !== 'stack' && node.path && !urlFor(env, node, locale)) continue // step does not exist in this locale
-          if (node.session && sessions?.[node.session]?.blocked_on?.includes(env.name)) { pending.push(`${node.id} (${locale}): session ${node.session} is blocked on ${env.name}`); continue }
-          const sess = await contextFor(node.session, locale)
-          const sPage = sess ? sess.page : page
-          const sCtx = sess ? sess.context : lctx
-          const consoleFile = shared && !sess ? consoleLog(root, config.output, env.name) : null
-          if (node.kind === 'stack') {
-            try {
-              const bad = await walkStack({ node, locale, page: sPage, env, run, scenario, scenarioDir, config, consoleFile, args })
-              for (const b of bad) failed.push(`${node.id} (${locale}) ${b}`)
-            } catch (error) {
-              failed.push(`${node.id} (${locale}): ${error.message.split('\n')[0]}`)
-              say(`✗ ${node.id} ${locale}: ${error.message.split('\n')[0]}`)
-            }
-            continue
-          }
-          if (node.kind === 'email' && (node.mail?.to || sessionInfo(node.session)?.mailbox)) {
-            // an e-mail node with a recipient is walked like a step: wait for the message and capture it
-            try {
-              const to = expandRun(node.mail?.to || sessionInfo(node.session).mailbox, run.meta.short)
-              const results = await captureMail({ config, root, run, env, node, locale, to, subject: localized(node.mail?.subject, locale), timeoutMs: 45000 })
-              say(`✓ ${node.id} ${locale}: "${results.subject}"`)
-            } catch (error) {
-              failed.push(`${node.id} (${locale}): ${error.message.split('\n')[0]}`)
-              say(`✗ ${node.id} ${locale}: ${error.message.split('\n')[0]}`)
-            }
-            continue
+    const results = []
+    const recSkipped = new Set() // engines whose passes are not recorded (once per engine)
+    try {
+      for (const [passIndex, pass] of passes.entries()) {
+        const first = passIndex === 0
+        const plain = pass.engine === 'chromium' && !pass.emulation
+        let browser = chromium
+        if (pass.engine !== 'chromium') {
+          if (!engines.has(pass.engine)) engines.set(pass.engine, await launchEngine(pass.engine))
+          browser = engines.get(pass.engine)
+        }
+        const extra = contextOptionsOf(pass)
+        const tag = passes.length > 1 && pass.label ? ` · ${pass.label}` : ''
+        if (passes.length > 1) say(`\n${pass.label || 'chromium'}: ${pass.keys.join(', ')}`)
+        // recordings and traces (batch D) in Chromium passes; a flow recording is one per locale, made in the first
+        let passRec = recSettings
+        if (pass.engine !== 'chromium') {
+          passRec = null
+          const wanted = !!recSettings.record || scenario.nodes.some((n) => parseRecord(n.record ?? n.capture?.record))
+          if (wanted && !recSkipped.has(pass.engine)) { recSkipped.add(pass.engine); say(`Recording and traces skipped in ${pass.engine}: they need Chromium (the Chromium keys of this run are recorded).`) }
+        } else if (passes.slice(0, passIndex).some((p) => p.engine === 'chromium') && recSettings.record?.mode === 'flow') passRec = { ...recSettings, record: null }
+        const ctx = parallel ? null : plain && conn ? conn.context : await newContext(browser, env, { root, config, extra })
+        if (ctx && ctx !== conn?.context) ownContexts.push(ctx)
+        // named sessions: one isolated browser context per person and locale (cookies, storage, sign-in), created lazily
+        const sessionContexts = new Map()
+        const contextFor = async (key, locale) => {
+          if (!key || !sessions?.[key]) return null
+          const id = `${key}|${locale}`
+          if (!sessionContexts.has(id)) {
+            // every context gets the environment's gate and readonly policy; an account's saved sign-in is loaded
+            const account = accountFor(env, sessions[key].account, { root, config })
+            const c = await newContext(browser, env, { root, config, account, extra })
+            ownContexts.push(c)
+            const p = await c.newPage()
+            observeConsole(p)
+            sessionContexts.set(id, { context: c, page: p })
+            const saved = account && await access(account.storage_state).then(() => true, () => false)
+            say(`session ${key} (${locale}${tag}): new browser context${saved ? ' with the saved sign-in' : ''}`)
           }
-          if (!['playwright', 'script'].includes(node.execution.strategy) || !node.execution.script) { pending.push(`${node.id} (${locale}): ${node.execution.strategy} — ${node.execution.instructions.split('\n')[0]}`); continue }
-          const streakKey = `${node.session || ''}|${locale}`
-          if (streak.stopped(streakKey)) { skipped.push(`${node.id} (${locale})`); continue }
-          const scriptFile = resolve(scenarioDir, node.execution.script)
-          // one invocation of the step script; the automatic capture runs unless the script captured the step itself:
-          // a crop is an attachment (#49), and a capture from an earlier walk must not stand in for this one (#50)
-          const rec = await recorderFor(sPage)
-          const runStep = async (mod) => {
-            let captured = false
-            rec?.beforeStep(node)
-            const records = []
-            const capture = (opts = {}) => { captured = true; rec?.beforeCapture(node); return captureStep({ page: sPage, node, locale, options: captureOptions(scenario, node), viewports: scopeViewports(run, opts.viewports), run, htmlView: htmlViewAllowed(env, scenario) ? { scenarioId: scenario.id } : null, consoleFile, maxChars: config.evaluators?.jev?.max_state_chars, extra: node.session ? { session: node.session } : {}, stability: Number(args.stability) || 0 }).then((r) => { prefetch?.add(r, run.dir); records.push(...r); return r }) }
-            try {
-              await mod.default({ page: sPage, context: sCtx, locale, node: { id: node.id, title: localized(node.title, locale), kind: node.kind }, session: sessionInfo(node.session), url: (id = node.id) => urlFor(env, stepOf(scenario, id), locale), env, run: run.meta, capture, crop: (selector, title, o = {}) => captureCrop({ page: sPage, node, locale, selector, title, run, padding: Number(o.padding) || 0 }), acceptDialogs: () => acceptDialogs(sPage) })
-              if (!captured) await capture()
-            } catch (error) { await rec?.afterStep(node, { error }); throw error }
-            await rec?.afterStep(node, { records })
+          return sessionContexts.get(id)
+        }
+        // one locale: its own tab (and, in parallel, its own context); returns what it could not walk
+        const walkLocale = async (locale) => {
+          const pending = []; const failed = []; const skipped = []
+          let lctx = ctx
+          if (parallel) { lctx = await newContext(browser, env, { root, config, extra }); ownContexts.push(lctx) }
+          // the walk owns its tab; agents and people keep theirs in the same shared browser
+          const page = await lctx.newPage()
+          const shared = conn && !parallel && plain // the shared browser's own context logs its console to a file
+          if (!shared) observeConsole(page)
+          // one recorder per page (the walk's tab and each named session's), started on its first step;
+          // recordings and traces need CDP: Chromium passes only
+          const recorders = new Map()
+          const recorderFor = async (p) => {
+            if (!passRec) return null
+            if (!recorders.has(p)) recorders.set(p, recordingSession({ page: p, run, scenario, locale, settings: passRec, viewports: scopeKeys(scope, pass.keys), encoder: encoder.page, say, label: `${locale}${tag}` }).catch(() => null))
+            return recorders.get(p)
           }
           try {
-            await runStep(await import(pathToFileURL(scriptFile).href))
-            say(`✓ ${node.id} ${locale}`)
-            streak.ok(streakKey)
-          } catch (error) {
-            // a selector the page no longer has: propose one from the page (#13); --heal applies it once the step passes
-            const healed = args['no-heal'] ? null : await healStep({ error, page: sPage, scriptFile, root, output: config.output, run, node, locale, apply: !!args.heal, rerun: runStep }).catch(() => null)
-            if (healed?.applied) {
-              say(`✓ ${node.id} ${locale} (healed)\n${formatHeal(healed, { stepArg: node.id })}`)
-              streak.ok(streakKey)
-              continue
+            // every locale starts as a new visitor on its first walk in the run (an own context is new already)
+            if (shared && !walked.some((c) => c.locale === locale)) { await resetSession(lctx, page, baseUrl(env, locale)); say(`session reset (new visitor, ${locale}${tag})`) }
+            for (const node of scenario.nodes) {
+              if (node.kind === 'decision' || (pick && !pick.includes(node.id))) continue
+              if (node.kind !== 'stack' && node.path && !urlFor(env, node, locale)) continue // step does not exist in this locale
+              if (node.session && sessions?.[node.session]?.blocked_on?.includes(env.name)) { pending.push(`${node.id} (${locale}${tag}): session ${node.session} is blocked on ${env.name}`); continue }
+              const sess = await contextFor(node.session, locale)
+              const sPage = sess ? sess.page : page
+              const sCtx = sess ? sess.context : lctx
+              const consoleFile = shared && !sess ? consoleLog(root, config.output, env.name) : null
+              if (node.kind === 'stack') {
+                try {
+                  const bad = await walkStack({ node, locale, page: sPage, env, run, scenario, scenarioDir, config, consoleFile, args, keys: pass.keys, tag })
+                  for (const b of bad) failed.push(`${node.id} (${locale}${tag}) ${b}`)
+                } catch (error) {
+                  failed.push(`${node.id} (${locale}${tag}): ${error.message.split('\n')[0]}`)
+                  say(`✗ ${node.id} ${locale}${tag}: ${error.message.split('\n')[0]}`)
+                }
+                continue
+              }
+              if (node.kind === 'email' && !first) continue // one message, captured in the first pass
+              if (node.kind === 'email' && (node.mail?.to || sessionInfo(node.session)?.mailbox)) {
+                // an e-mail node with a recipient is walked like a step: wait for the message and capture it
+                try {
+                  const to = expandRun(node.mail?.to || sessionInfo(node.session).mailbox, run.meta.short)
+                  const results = await captureMail({ config, root, run, env, node, locale, to, subject: localized(node.mail?.subject, locale), timeoutMs: 45000 })
+                  say(`✓ ${node.id} ${locale}${tag}: "${results.subject}"`)
+                } catch (error) {
+                  failed.push(`${node.id} (${locale}${tag}): ${error.message.split('\n')[0]}`)
+                  say(`✗ ${node.id} ${locale}${tag}: ${error.message.split('\n')[0]}`)
+                }
+                continue
+              }
+              if (!['playwright', 'script'].includes(node.execution.strategy) || !node.execution.script) { pending.push(`${node.id} (${locale}${tag}): ${node.execution.strategy} — ${node.execution.instructions.split('\n')[0]}`); continue }
+              const streakKey = `${pass.engine}|${pass.emulation?.key || ''}|${node.session || ''}|${locale}`
+              if (streak.stopped(streakKey)) { skipped.push(`${node.id} (${locale}${tag})`); continue }
+              const scriptFile = resolve(scenarioDir, node.execution.script)
+              // one invocation of the step script; the automatic capture runs unless the script captured the step itself:
+              // a crop is an attachment (#49), and a capture from an earlier walk must not stand in for this one (#50)
+              const rec = await recorderFor(sPage)
+              const runStep = async (mod) => {
+                let captured = false
+                rec?.beforeStep(node)
+                const records = []
+                const capture = (opts = {}) => { captured = true; rec?.beforeCapture(node); return captureStep({ page: sPage, node, locale, options: captureOptions(scenario, node), viewports: scopeKeys(run.meta.scope, pass.keys, opts.viewports || null), run, htmlView: htmlViewAllowed(env, scenario) ? { scenarioId: scenario.id } : null, consoleFile, maxChars: config.evaluators?.jev?.max_state_chars, extra: node.session ? { session: node.session } : {}, stability: Number(args.stability) || 0 }).then((r) => { prefetch?.add(r, run.dir); records.push(...r); return r }) }
+                try {
+                  await mod.default({ page: sPage, context: sCtx, locale, node: { id: node.id, title: localized(node.title, locale), kind: node.kind }, session: sessionInfo(node.session), url: (id = node.id) => urlFor(env, stepOf(scenario, id), locale), env, run: run.meta, capture, crop: (selector, title, o = {}) => captureCrop({ page: sPage, node, locale, selector, title, run, padding: Number(o.padding) || 0 }), acceptDialogs: () => acceptDialogs(sPage) })
+                  if (!captured) await capture()
+                } catch (error) { await rec?.afterStep(node, { error }); throw error }
+                await rec?.afterStep(node, { records })
+              }
+              try {
+                await runStep(await import(pathToFileURL(scriptFile).href))
+                say(`✓ ${node.id} ${locale}${tag}`)
+                streak.ok(streakKey)
+              } catch (error) {
+                // a selector the page no longer has: propose one from the page (#13); --heal applies it once the step passes
+                const healed = args['no-heal'] ? null : await healStep({ error, page: sPage, scriptFile, root, output: config.output, run, node, locale, apply: !!args.heal, rerun: runStep }).catch(() => null)
+                if (healed?.applied) {
+                  say(`✓ ${node.id} ${locale}${tag} (healed)\n${formatHeal(healed, { stepArg: node.id })}`)
+                  streak.ok(streakKey)
+                  continue
+                }
+                failed.push(`${node.id} (${locale}${tag}): ${error.message.split('\n')[0]}`)
+                say(`✗ ${node.id} ${locale}${tag}: ${error.message.split('\n')[0]}`)
+                if (healed) { say(formatHeal(healed, { stepArg: node.id })); if (healed.patch) proposals.push(node.id) }
+                if (streak.record(streakKey, error.message)) say(`  stopping ${node.session ? `session ${node.session}` : 'this walk'} (${locale}${tag}): the last 3 steps failed with the same error; fix the shared cause (sign-in, environment) and rerun, or pass --keep-going`)
+              }
             }
-            failed.push(`${node.id} (${locale}): ${error.message.split('\n')[0]}`)
-            say(`✗ ${node.id} ${locale}: ${error.message.split('\n')[0]}`)
-            if (healed) { say(formatHeal(healed, { stepArg: node.id })); if (healed.patch) proposals.push(node.id) }
-            if (streak.record(streakKey, error.message)) say(`  stopping ${node.session ? `session ${node.session}` : 'this walk'} (${locale}): the last 3 steps failed with the same error; fix the shared cause (sign-in, environment) and rerun, or pass --keep-going`)
+          } finally {
+            for (const r of recorders.values()) { const notes = await (await r)?.finish().catch((e) => [`recording: ${e.message}`]); for (const n of notes || []) say(`  ${n}`) }
+            await page.close().catch(() => {})
           }
+          return { pending, failed, skipped }
         }
-      } finally {
-        for (const r of recorders.values()) { const notes = await (await r)?.finish().catch((e) => [`recording: ${e.message}`]); for (const n of notes || []) say(`  ${n}`) }
-        await page.close().catch(() => {})
+        if (parallel) say(`Walking ${locales.length} locales, ${concurrency} at a time (each in its own browser context); output in locale order.`)
+        results.push(...await inOrder(locales, parallel ? concurrency : 1, (locale) => walkLocale(locale).catch((error) => ({ pending: [], failed: [`${locale}${tag}: ${error.message.split('\n')[0]}`], skipped: [] }))))
+        // the next pass has its own contexts: close this one's now
+        for (const c of ownContexts.splice(0)) await c.close().catch(() => {})
       }
-      return { pending, failed, skipped }
-    }
-    let results
-    try {
-      if (parallel) say(`Walking ${locales.length} locales, ${concurrency} at a time (each in its own browser context); output in locale order.`)
-      results = await inOrder(locales, parallel ? concurrency : 1, (locale) => walkLocale(locale).catch((error) => ({ pending: [], failed: [`${locale}: ${error.message.split('\n')[0]}`], skipped: [] })))
     } finally {
-      for (const { context } of sessionContexts.values()) await context.close().catch(() => {})
       for (const c of ownContexts) await c.close().catch(() => {})
+      for (const b of engines.values()) await b.close().catch(() => {})
       if (conn) await conn.browser.close() // over CDP this only disconnects; the shared browser keeps running
       if (ephemeral) await ephemeral.close()
       await encoder.close()
@@ -1211,17 +1341,20 @@ const commands = {
         say(`Added the environment ${envName} to ${relative(process.cwd(), file) || CONFIG_FILE}: base_url \${KALOKO_PREVIEW_URL}, set by kaloko ci preview-url in CI.`)
       } else say(`Add to environments: in ${CONFIG_FILE}:\n  ${envName}:\n    base_url: \${KALOKO_PREVIEW_URL}`)
     }
+    // the engines the job installs: Chromium and whatever the scenarios and walk.browsers ask for (batch E)
+    const engines = new Set(['chromium', ...(config.walk?.browsers || [])])
     for (const f of scenarios) {
       let sc = null
       try { sc = yaml.load(await readFile(resolve(root, f), 'utf8')) } catch { throw new UserError(`${f} cannot be read.`) }
       if (sc?.environments && !sc.environments.includes(envName)) say(`! ${f} allows environments [${sc.environments.join(', ')}]: add ${envName}, or kaloko start refuses it in CI.`)
+      for (const b of sc?.browsers || []) engines.add(b)
     }
     let pkg = null
     try { pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8')) } catch {}
     const pm = existsSync(join(root, 'pnpm-lock.yaml')) ? 'pnpm' : existsSync(join(root, 'yarn.lock')) ? 'yarn' : existsSync(join(root, 'bun.lockb')) || existsSync(join(root, 'bun.lock')) ? 'bun' : 'npm'
     const dependency = !!(pkg && ({ ...pkg.dependencies, ...pkg.devDependencies }).kaloko)
     const version = JSON.parse(await readFile(join(packageRoot, 'package.json'), 'utf8')).version
-    const opts = { scenarios, env: envName, affected: !args['no-affected'], pm, dependency, version: `^${version}`, trigger: args.trigger === 'pull_request' ? 'pull_request' : 'deployment' }
+    const opts = { scenarios, env: envName, affected: !args['no-affected'], pm, dependency, version: `^${version}`, trigger: args.trigger === 'pull_request' ? 'pull_request' : 'deployment', browsers: [...engines] }
     const content = action === 'github' ? githubWorkflow(opts) : gitlabJob(opts)
     if (args.print) { say(content); return }
     const out = resolve(root, typeof args.out === 'string' ? args.out : action === 'github' ? '.github/workflows/kaloko.yml' : 'kaloko.gitlab-ci.yml')
@@ -1846,7 +1979,10 @@ const commands = {
 
   async doctor (args) {
     const { config, root, file } = await context(args)
-    const r = await doctor({ config, root, file, fix: !!args.fix })
+    // engines the scenarios ask for (browsers: [webkit, firefox]), so doctor checks they are installed
+    const engines = []
+    for (const f of await scenarioFiles(config, root).catch(() => [])) { try { engines.push(...((yaml.load(await readFile(f, 'utf8')) || {}).browsers || [])) } catch {} }
+    const r = await doctor({ config, root, file, fix: !!args.fix, engines })
     say(args.json ? JSON.stringify(r, null, 2) : formatDoctor(r))
     if (!r.ok) process.exitCode = 1
   },