kaloko 0.4.10 → 0.5.0

package/src/lib/access.mjs

@@ -126,9 +126,12 @@ export async function gateForRequests (env, { root } = {}) {
   return { headers, toGate: Object.keys(headers).length ? originMatcher(gateOrigins(env)) : () => false, httpCredentials: options.httpCredentials || null, clientCertificates: options.clientCertificates || [] }
 }
 
-/** A new browser context with the environment's gate, policy and (optionally) an account's session. */
+/**
+ * A new browser context with the environment's gate, policy and (optionally) an account's session; `extra` adds
+ * Playwright context options (a device profile: pixel ratio, mobile, touch, user agent).
+ */
 export async function newContext (browser, env, opts = {}) {
-  const context = await browser.newContext(await contextOptions(env, opts))
+  const context = await browser.newContext({ ...await contextOptions(env, opts), ...(opts.extra || {}) })
   return prepareContext(context, env, opts)
 }
 

package/src/lib/anim.mjs

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

package/src/lib/apps/devices.mjs

@@ -0,0 +1,187 @@
+// Devices of app walks (batch E): which emulator, simulator or real device a `devices:` name means, getting it
+// ready (adb connect over Wi-Fi, starting an Android emulator, waking a phone, booting a simulator of a runtime),
+// and the system settings a capture key asks for (dark mode, reduced motion) on Android and the iOS Simulator.
+// Each device of a scenario becomes the `app.<platform>` block of its own walk; the drivers stay as they are.
+import { execFile, spawn } from 'node:child_process'
+import { promisify } from 'node:util'
+import { UserError } from '../util.mjs'
+
+const run = promisify(execFile)
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
+
+async function exec (bin, args, { timeout = 60000, hint = '' } = {}) {
+  try { return (await run(bin, args, { timeout, maxBuffer: 16 * 1024 * 1024 })).stdout } catch (error) {
+    if (error.code === 'ENOENT') throw new UserError(`${bin} is not installed or not on PATH.${hint ? ' ' + hint : ''}`)
+    throw new Error(`${bin} ${args.slice(0, 3).join(' ')}: ${String(error.stderr || error.message).trim().split('\n').pop()}`)
+  }
+}
+
+const norm = (s) => String(s || '').toLowerCase().replace(/[^a-z0-9]+/g, '')
+
+/** "iphone-15-pro-max-ios-18" → { name: 'iPhone 15 Pro Max', runtime: 'iOS 18' } (simulator name and runtime). */
+export function simulatorOf (id) {
+  const m = String(id).toLowerCase().match(/^(.*?)(?:-(ios|ipados)-(\d+(?:[.-]\d+)?))?$/)
+  const WORDS = { iphone: 'iPhone', ipad: 'iPad', pro: 'Pro', max: 'Max', plus: 'Plus', mini: 'mini', air: 'Air', se: 'SE', ultra: 'Ultra' }
+  const name = m[1].split('-').filter(Boolean).map((w) => WORDS[w] || (/^\d/.test(w) ? w : w.charAt(0).toUpperCase() + w.slice(1))).join(' ')
+  // "iPhone SE 3rd generation" is "iphone-se-3": the generation in parentheses as Xcode names it
+  const fixed = name.replace(/^iPhone SE (\d)$/, (_, n) => `iPhone SE (${n}${['', 'st', 'nd', 'rd'][n] || 'th'} generation)`)
+  return { name: fixed, runtime: m[3] ? `iOS ${m[3].replace('-', '.')}` : null }
+}
+
+/**
+ * The `app.<platform>` block for one device of the scenario: the environment's block with the device's entry
+ * (`devices: { <id>: { serial | avd | connect | udid | device | runtime | real } }`), or what the name says:
+ * an adb serial, an AVD (pixel-8-api-34 → Pixel_8_API_34) or a simulator (iphone-15-ios-18).
+ */
+export function deviceConfig (platform, cfg = {}, id = null) {
+  if (!id) return { ...cfg }
+  const own = cfg.devices?.[id] || null
+  const base = { ...cfg, devices: undefined }
+  if (platform === 'android') {
+    if (own) return { ...base, ...own, device: own.title || own.device || id }
+    // a serial (emulator-5554, R58M…, 192.168.1.20:5555) or an AVD name
+    if (/^emulator-\d+$|:\d+$|^[A-Z0-9]{8,}$/.test(id)) return { ...base, serial: id, ...(id.includes(':') ? { connect: id } : {}), device: id }
+    return { ...base, serial: undefined, avd: id, device: id }
+  }
+  if (platform === 'ios') {
+    if (own) return { ...base, ...own, ...(own.title ? { label: own.title } : {}) }
+    if (/^[0-9A-F]{8}-[0-9A-F]{4}-|^[0-9a-f]{40}$|^[0-9A-F]{8}-[0-9A-F]{16}$/i.test(id)) return { ...base, udid: id }
+    const sim = simulatorOf(id)
+    return { ...base, udid: undefined, device: sim.name, ...(sim.runtime ? { runtime: sim.runtime } : {}) }
+  }
+  return { ...base, ...(own || {}) }
+}
+
+/* ---------- Android: adb connect, emulators, a phone that is awake ---------- */
+
+const adbOf = (cfg) => (args, o) => exec(cfg.adb || 'adb', args, { hint: 'Install Android platform-tools (adb).', ...o })
+
+/** Serials of attached devices and emulators (`adb devices`). */
+export async function adbDevices (cfg = {}) {
+  const out = await adbOf(cfg)(['devices'])
+  return out.split('\n').slice(1).map((l) => l.trim().split(/\s+/)).filter((p) => p[0] && p[1] === 'device').map((p) => p[0])
+}
+
+/** AVD names of the emulator binary. */
+export async function listAvds (cfg = {}) {
+  return (await exec(emulatorBin(cfg), ['-list-avds'], { hint: 'Install the Android emulator (Android Studio → SDK Manager).' })).split('\n').map((s) => s.trim()).filter(Boolean)
+}
+const emulatorBin = (cfg) => cfg.emulator || (process.env.ANDROID_HOME ? `${process.env.ANDROID_HOME}/emulator/emulator` : process.env.ANDROID_SDK_ROOT ? `${process.env.ANDROID_SDK_ROOT}/emulator/emulator` : 'emulator')
+
+/**
+ * Makes the device of `cfg` reachable and returns the block with its serial: `connect` (a real device over Wi-Fi),
+ * a running emulator of `avd`, or that emulator started (headless unless KALOKO_EMULATOR_WINDOW=1) and booted.
+ */
+export async function prepareAndroid (cfg, { say = () => {}, bootTimeout = 240000 } = {}) {
+  const adb = adbOf(cfg)
+  if (cfg.connect) {
+    const out = await adb(['connect', cfg.connect])
+    if (!/connected/.test(out)) throw new UserError(`adb connect ${cfg.connect}: ${out.trim()}. Pair the phone once (Developer options → Wireless debugging → adb pair host:port code).`)
+    cfg = { ...cfg, serial: cfg.serial || cfg.connect }
+  }
+  if (cfg.avd && !cfg.serial) {
+    const running = await runningAvd(cfg, cfg.avd)
+    if (running) return { ...cfg, serial: running }
+    const avds = await listAvds(cfg)
+    const avd = avds.find((a) => a === cfg.avd) || avds.find((a) => norm(a) === norm(cfg.avd))
+    if (!avd) throw new UserError(`No Android emulator "${cfg.avd}". Known: ${avds.join(', ') || 'none'} (create one in Android Studio → Device Manager, or name it in app.android.devices).`)
+    say(`starting the ${avd} emulator…`)
+    const child = spawn(emulatorBin(cfg), ['-avd', avd, '-no-snapshot-save', '-no-boot-anim', ...(process.env.KALOKO_EMULATOR_WINDOW === '1' ? [] : ['-no-window'])], { detached: true, stdio: 'ignore' })
+    child.unref()
+    const end = Date.now() + bootTimeout
+    while (Date.now() < end) {
+      await sleep(2000)
+      const serial = await runningAvd(cfg, avd).catch(() => null)
+      if (serial && (await adb(['-s', serial, 'shell', 'getprop', 'sys.boot_completed']).catch(() => '')).trim() === '1') return { ...cfg, serial, avd }
+    }
+    throw new UserError(`The ${avd} emulator did not boot within ${Math.round(bootTimeout / 1000)} s.`)
+  }
+  return cfg
+}
+
+/** Serial of the running emulator of an AVD (`adb -s emulator-5554 emu avd name`). */
+async function runningAvd (cfg, avd) {
+  const adb = adbOf(cfg)
+  for (const serial of (await adbDevices(cfg)).filter((s) => s.startsWith('emulator-'))) {
+    const name = (await adb(['-s', serial, 'emu', 'avd', 'name']).catch(() => '')).split('\n')[0].trim()
+    if (name && norm(name) === norm(avd)) return serial
+  }
+  return null
+}
+
+/** A real phone for captures: screen on, keyguard away (no PIN), clean status bar (demo mode, 9:41). */
+export async function readyAndroid (cfg) {
+  const adb = adbOf(cfg); const s = cfg.serial ? ['-s', cfg.serial] : []
+  if (cfg.wake !== false) {
+    await adb([...s, 'shell', 'input', 'keyevent', 'KEYCODE_WAKEUP']).catch(() => {})
+    await adb([...s, 'shell', 'wm', 'dismiss-keyguard']).catch(() => {})
+  }
+  if (cfg.status_bar !== false) {
+    await adb([...s, 'shell', 'settings', 'put', 'global', 'sysui_demo_allowed', '1']).catch(() => {})
+    for (const extra of [['-e', 'command', 'enter'], ['-e', 'command', 'clock', '-e', 'hhmm', '0941'], ['-e', 'command', 'battery', '-e', 'level', '100', '-e', 'plugged', 'false'], ['-e', 'command', 'notifications', '-e', 'visible', 'false']]) {
+      await adb([...s, 'shell', 'am', 'broadcast', '-a', 'com.android.systemui.demo', ...extra]).catch(() => {})
+    }
+  }
+}
+
+/** After the walk: the phone's own status bar again. */
+export async function finishAndroid (cfg) {
+  if (cfg.status_bar === false) return
+  await adbOf(cfg)([...(cfg.serial ? ['-s', cfg.serial] : []), 'shell', 'am', 'broadcast', '-a', 'com.android.systemui.demo', '-e', 'command', 'exit']).catch(() => {})
+}
+
+/* ---------- iOS Simulator: a device of a runtime ---------- */
+
+/** The udid of the simulator `device` on `runtime` (newest matching runtime), booted when needed. */
+export async function prepareSimulator (cfg) {
+  if (cfg.udid || cfg.real || !cfg.device) return cfg
+  const list = JSON.parse(await exec('xcrun', ['simctl', 'list', 'devices', 'available', '-j'], { hint: 'Install Xcode with an iOS Simulator runtime.' })).devices
+  const want = cfg.runtime ? norm(cfg.runtime) : null
+  const runtimes = Object.keys(list).filter((r) => !want || norm(r.split('.').pop()).startsWith(want)).sort().reverse()
+  const hits = runtimes.flatMap((r) => list[r].filter((d) => d.name === cfg.device || norm(d.name) === norm(cfg.device)))
+  // a simulator of that name that is already running wins (its app is installed); else the newest runtime
+  const dev = hits.find((d) => d.state === 'Booted') || hits[0]
+  if (dev) return { ...cfg, udid: dev.udid, device: dev.name }
+  throw new UserError(`No iOS simulator "${cfg.device}"${cfg.runtime ? ` on ${cfg.runtime}` : ''}. Create it in Xcode → Window → Devices and Simulators, or: xcrun simctl create "${cfg.device}" "${cfg.device}" <runtime>.`)
+}
+
+/* ---------- system appearance per capture key ---------- */
+
+/**
+ * Sets dark mode and reduced motion on the device for a capture key; returns an undo. Android: `cmd uimode
+ * night` and the animator scales; iOS Simulator: `simctl ui appearance` (reduced motion has no simctl switch);
+ * Electron: emulated media. Other platforms report what they cannot set.
+ */
+export async function applyAppAppearance (platform, cfg, driver, variant) {
+  const notes = []
+  if (!variant || (!variant.color_scheme && !variant.reduced_motion)) return { undo: async () => {}, notes }
+  if (driver?.web && driver.page) {
+    await driver.page.emulateMedia({ ...(variant.color_scheme ? { colorScheme: variant.color_scheme } : {}), ...(variant.reduced_motion ? { reducedMotion: variant.reduced_motion } : {}) }).catch(() => {})
+    return { undo: async () => { await driver.page.emulateMedia({ colorScheme: null, reducedMotion: null }).catch(() => {}) }, notes }
+  }
+  if (platform === 'android') {
+    const adb = adbOf(cfg); const s = cfg.serial ? ['-s', cfg.serial] : []
+    const sh = (...a) => adb([...s, 'shell', ...a]).catch(() => '')
+    const before = { night: (await sh('cmd', 'uimode', 'night')).match(/yes|no|auto/)?.[0] || 'no', anim: (await sh('settings', 'get', 'global', 'animator_duration_scale')).trim() || '1' }
+    if (variant.color_scheme) await sh('cmd', 'uimode', 'night', variant.color_scheme === 'dark' ? 'yes' : 'no')
+    if (variant.reduced_motion) for (const k of ['animator_duration_scale', 'transition_animation_scale', 'window_animation_scale']) await sh('settings', 'put', 'global', k, variant.reduced_motion === 'reduce' ? '0' : '1')
+    // the app redraws (an activity may be recreated): give it a moment
+    await sleep(cfg.settle ?? 900)
+    return {
+      notes,
+      undo: async () => {
+        if (variant.color_scheme) await sh('cmd', 'uimode', 'night', before.night)
+        if (variant.reduced_motion) for (const k of ['animator_duration_scale', 'transition_animation_scale', 'window_animation_scale']) await sh('settings', 'put', 'global', k, before.anim === 'null' ? '1' : before.anim)
+      }
+    }
+  }
+  if (platform === 'ios' && !cfg.real) {
+    const dev = cfg.udid || 'booted'
+    if (variant.color_scheme) await exec('xcrun', ['simctl', 'ui', dev, 'appearance', variant.color_scheme]).catch((e) => notes.push(`appearance: ${e.message}`))
+    if (variant.reduced_motion === 'reduce') notes.push('reduced motion cannot be switched on the iOS Simulator from the command line; the capture shows the current setting')
+    await sleep(cfg.settle ?? 700)
+    return { notes, undo: async () => { if (variant.color_scheme) await exec('xcrun', ['simctl', 'ui', dev, 'appearance', 'light']).catch(() => {}) } }
+  }
+  notes.push(`${platform}${cfg.real ? ' (real device)' : ''}: dark mode and motion are not switched by Kaloko; the capture shows the device's own setting`)
+  return { notes, undo: async () => {} }
+}

package/src/lib/apps/drivers.mjs

@@ -15,10 +15,12 @@ import { createHash } from 'node:crypto'
 import { fileURLToPath } from 'node:url'
 import { UserError } from '../util.mjs'
 import { readTree, query } from './tree.mjs'
+import { iosRealDevice } from './ios-device.mjs'
+import { windowsApp } from './windows.mjs'
 
 const run = promisify(execFile)
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
-export const PLATFORMS = ['web', 'android', 'ios', 'electron', 'desktop']
+export const PLATFORMS = ['web', 'android', 'ios', 'electron', 'desktop', 'windows']
 export const isApp = (platform) => !!platform && platform !== 'web'
 
 async function exec (bin, args, opts = {}) {
@@ -199,7 +201,7 @@ function electron (cfg, ctx) {
 
 /* ---------- macOS desktop apps: window screenshot, accessibility tree or OCR ---------- */
 function desktop (cfg, ctx) {
-  if (process.platform !== 'darwin') throw new UserError('Built-in desktop capture supports macOS. On Windows or Linux drive the app with your tool and capture with kaloko capture --image (and --tree).')
+  if (process.platform !== 'darwin') throw new UserError('Platform desktop is a macOS app. A Windows app is platform: windows (app.windows, UI Automation); on Linux drive the app with your tool and capture with kaloko capture --image (and --tree).')
   const name = cfg.name || cfg.bundle
   if (!name) throw new UserError('environments.<env>.app.desktop needs name (the app as macOS shows it) or bundle.')
   let win = null
@@ -272,7 +274,10 @@ export function driverFor (platform, env, ctx) {
   const cfg = env.app?.[platform]
   if (!cfg && platform !== 'desktop') throw new UserError(`Environment ${env.name} has no app.${platform} block in kaloko.config.yml.`)
   if (platform === 'android') return android(cfg, ctx)
+  // batch E: a real iPhone (devicectl, screenshots), Windows apps (UI Automation): own modules, same interface
+  if (platform === 'ios' && cfg.real) return iosRealDevice(cfg, ctx, { ocr: (png) => ocr(png, ocrLangs(ctx.locale)) })
   if (platform === 'ios') return ios(cfg, ctx)
+  if (platform === 'windows') return windowsApp(cfg, ctx)
   if (platform === 'electron') return electron(cfg, ctx)
   if (platform === 'desktop') return desktop(cfg || {}, ctx)
   throw new UserError(`Unknown platform ${platform}.`)
@@ -280,5 +285,8 @@ export function driverFor (platform, env, ctx) {
 
 /** Tools available for app platforms (doctor). */
 export async function appTools () {
-  return { adb: await which('adb'), simctl: process.platform === 'darwin' && await which('xcrun'), idb: await which('idb'), swiftc: process.platform === 'darwin' && await which('xcrun') }
+  const mac = process.platform === 'darwin'
+  const sdk = process.env.ANDROID_HOME || process.env.ANDROID_SDK_ROOT
+  const emulator = await which('emulator') || (sdk ? await access(join(sdk, 'emulator', process.platform === 'win32' ? 'emulator.exe' : 'emulator')).then(() => true, () => false) : false)
+  return { adb: await which('adb'), emulator, simctl: mac && await which('xcrun'), devicectl: mac && await which('xcrun'), idb: await which('idb'), idevicescreenshot: await which('idevicescreenshot'), pymobiledevice3: await which('pymobiledevice3'), swiftc: mac && await which('xcrun'), powershell: process.platform === 'win32' && (await which('powershell') || await which('pwsh')) }
 }

package/src/lib/apps/ios-device.mjs

@@ -0,0 +1,78 @@
+// A real iPhone or iPad (batch E): what works from the command line without a test runner. Xcode's devicectl
+// installs and launches the app and opens deep links; a screenshot comes from libimobiledevice (idevicescreenshot)
+// or pymobiledevice3 (iOS 17+ needs its tunnel: sudo pymobiledevice3 remote tunneld). There is no UI tree and no
+// tapping: the screen text is read by OCR on macOS, and flows that need taps are driven by XCUITest, Maestro or
+// Appium, then captured with kaloko capture --image. Same driver interface as drivers.mjs.
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { mkdtemp, readFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { UserError } from '../util.mjs'
+import { readTree } from './tree.mjs'
+
+const run = promisify(execFile)
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
+const which = async (bin) => { try { await run(process.platform === 'win32' ? 'where' : 'which', [bin]); return true } catch { return false } }
+const pngSize = (buf) => (buf?.length > 24 && buf.readUInt32BE(12) === 0x49484452 ? [buf.readUInt32BE(16), buf.readUInt32BE(20)] : null)
+
+async function exec (bin, args, { timeout = 120000, hint = '' } = {}) {
+  try { return (await run(bin, args, { timeout, maxBuffer: 64 * 1024 * 1024 })).stdout } catch (error) {
+    if (error.code === 'ENOENT') throw new UserError(`${bin} is not installed or not on PATH.${hint ? ' ' + hint : ''}`)
+    throw new Error(`${bin} ${args.slice(0, 4).join(' ')}: ${String(error.stderr || error.message).trim().split('\n').pop()}`)
+  }
+}
+
+/** Which screenshot tool is installed: idevicescreenshot (libimobiledevice) or pymobiledevice3. */
+export async function iosShotTool () {
+  if (await which('idevicescreenshot')) return 'idevicescreenshot'
+  if (await which('pymobiledevice3')) return 'pymobiledevice3'
+  return null
+}
+
+export function iosRealDevice (cfg, ctx, { ocr = null } = {}) {
+  if (!cfg.udid) throw new UserError('A real iOS device needs its udid in app.ios (xcrun devicectl list devices, or idevice_id -l).')
+  const devicectl = (args, o) => exec('xcrun', ['devicectl', ...args], { hint: 'Install Xcode 15 or newer (devicectl).', ...o })
+  const scale = cfg.scale || 3
+  let tool = null
+  const d = {
+    platform: 'ios', real: true,
+    async open ({ locale, attach = false } = {}) {
+      tool = cfg.screenshot || await iosShotTool()
+      if (!tool) throw new UserError('Screenshots of a real iPhone need libimobiledevice (brew install libimobiledevice: idevicescreenshot) or pymobiledevice3 (pipx install pymobiledevice3; on iOS 17+ also sudo pymobiledevice3 remote tunneld).')
+      if (attach) return
+      if (cfg.app && cfg.install !== false) await devicectl(['device', 'install', 'app', '--device', cfg.udid, resolve(ctx.root, cfg.app)], { timeout: 600000 })
+      if (!cfg.bundle) return
+      const lang = locale ? ['-AppleLanguages', `(${locale})`, '-AppleLocale', locale.replace('-', '_')] : []
+      await devicectl(['device', 'process', 'launch', '--device', cfg.udid, '--terminate-existing', cfg.bundle, ...lang, ...(cfg.args || [])])
+      await sleep(cfg.launch_wait ?? 2000)
+    },
+    async link (url) {
+      if (!cfg.bundle) throw new UserError('Deep links on a real iOS device need app.ios.bundle (devicectl opens the URL with the app).')
+      await devicectl(['device', 'process', 'launch', '--device', cfg.udid, '--payload-url', url, cfg.bundle])
+      await sleep(cfg.settle ?? 1200)
+    },
+    async tap () { throw new UserError('Kaloko does not tap on a real iPhone. Drive the flow with XCUITest, Maestro or Appium and capture each screen with kaloko capture --image (and --tree when the tool dumps one).') },
+    async type () { throw new UserError('Kaloko does not type on a real iPhone; use XCUITest, Maestro or Appium.') },
+    async back () { throw new UserError('iOS has no system back: tap the app\'s own back button (with your test tool).') },
+    async wait (w) { await sleep(typeof w === 'number' ? w : 1000) },
+    async tree () { return null },
+    async snapshot () {
+      const dir = await mkdtemp(join(tmpdir(), 'kaloko-iosdev-'))
+      try {
+        const f = join(dir, 's.png')
+        if (tool === 'pymobiledevice3') await exec('pymobiledevice3', ['developer', 'dvt', 'screenshot', '--udid', cfg.udid, f])
+        else await exec('idevicescreenshot', ['-u', cfg.udid, f])
+        const png = await readFile(f); const px = pngSize(png) || [1179, 2556]
+        let tree = null
+        if (ocr && cfg.ocr !== false && process.platform === 'darwin') {
+          const res = await ocr(png).catch(() => null)
+          if (res) tree = readTree({ ocr: res.ocr.map((l) => ({ text: l.text, x: Math.round(l.x / scale), y: Math.round(l.y / scale), w: Math.round(l.w / scale), h: Math.round(l.h / scale) })) })
+        }
+        return { png, tree, size: [Math.round(px[0] / scale), Math.round(px[1] / scale)], scale, device: cfg.label || cfg.device || `iPhone ${cfg.udid.slice(0, 8)}`, crash: null, logErrors: null }
+      } finally { await rm(dir, { recursive: true, force: true }) }
+    },
+    async close () {}
+  }
+  return d
+}