kaloko 0.4.11 → 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/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
+}

package/src/lib/apps/tree.mjs

@@ -3,7 +3,8 @@
 // Units are logical (dp on Android, points on iOS and macOS) so touch targets compare across devices; `scale` in
 // the capture converts them to screenshot pixels.
 // Formats read: Android uiautomator / Appium Android XML, Appium iOS (XCUIElementType…) XML, idb describe-all JSON,
-// Maestro hierarchy JSON, the macOS accessibility dump of the Kaloko helper, OCR lines, and Kaloko's own tree JSON.
+// Maestro hierarchy JSON, the macOS accessibility dump of the Kaloko helper, Windows UI Automation (windows.ps1 tree),
+// OCR lines, and Kaloko's own tree JSON.
 
 const decode = (s) => String(s ?? '').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&apos;|&#39;/g, "'").replace(/&#10;/g, '\n').replace(/&#(\d+);/g, (_, n) => String.fromCharCode(Number(n))).replace(/&amp;/g, '&')
 const clean = (s) => String(s ?? '').replace(/\s+/g, ' ').trim()
@@ -75,6 +76,12 @@ function fromAx (e) {
   const role = iosRole(e.role)
   return { role, name: clean(e.title || e.description || e.label || ''), text: clean(e.value ?? e.title ?? ''), id: e.identifier || '', cls: e.role || '', bounds: e.frame ? { x: e.frame.x, y: e.frame.y, w: e.frame.w ?? e.frame.width, h: e.frame.h ?? e.frame.height } : null, clickable: INTERACTIVE.has(role) || (e.actions || []).includes('AXPress'), enabled: e.enabled !== false, focused: !!e.focused, children: (e.children || []).map(fromAx) }
 }
+const UIA_ROLES = { Button: 'button', SplitButton: 'button', Edit: 'textbox', Document: 'textbox', CheckBox: 'checkbox', RadioButton: 'radio', ComboBox: 'combobox', List: 'list', ListItem: 'cell', DataGrid: 'list', DataItem: 'cell', Table: 'list', Tree: 'list', TreeItem: 'cell', Text: 'text', ToolTip: 'text', HeaderItem: 'text', Hyperlink: 'link', Tab: 'tablist', TabItem: 'tab', Menu: 'menu', MenuBar: 'menu', MenuItem: 'menuitem', Image: 'image', Window: 'window', ToolBar: 'toolbar', TitleBar: 'toolbar', AppBar: 'toolbar', Slider: 'slider', Spinner: 'slider', ProgressBar: 'progressbar' }
+/** Windows UI Automation (windows.ps1 `tree`): control types, AutomationId, names and values; offscreen nodes are hidden. */
+function fromUia (e) {
+  const role = UIA_ROLES[e.type] || 'group'
+  return { role, name: clean(e.name || ''), text: clean(e.value ?? e.name ?? ''), id: e.id || '', cls: e.cls || e.type || '', bounds: e.w > 0 && e.h > 0 ? { x: e.x, y: e.y, w: e.w, h: e.h } : null, clickable: INTERACTIVE.has(role), enabled: e.enabled !== false, focused: !!e.focused, ...(e.offscreen ? { visible: false } : {}), children: (e.children || []).map(fromUia) }
+}
 const fromOwn = (e) => ({ role: e.role || 'group', name: clean(e.name || ''), text: clean(e.text || ''), id: e.id || '', cls: e.cls || '', bounds: e.bounds || null, clickable: !!e.clickable, enabled: e.enabled !== false, focused: !!e.focused, checked: !!e.checked, children: (e.children || []).map(fromOwn) })
 
 /**
@@ -101,6 +108,7 @@ export function readTree (input, { density = 1 } = {}) {
   if (data?.schema === 'qawalk.tree.v1') return { root: fromOwn(data.root), format: data.format || 'qawalk' }
   if (Array.isArray(data?.ocr)) return { root: { role: 'application', name: '', text: '', id: '', bounds: null, clickable: false, enabled: true, children: data.ocr.map((l) => ({ role: 'text', name: clean(l.text), text: clean(l.text), id: '', bounds: { x: l.x, y: l.y, w: l.w, h: l.h }, clickable: false, enabled: true, children: [] })) }, format: 'ocr' }
   if (data?.ax) return { root: fromAx(data.ax), format: 'macos-ax' }
+  if (data?.uia) return { root: fromUia(data.uia), format: 'windows-uia' }
   if (Array.isArray(data) && (data[0]?.AXLabel !== undefined || data[0]?.AXFrame !== undefined || data[0]?.type)) return { root: { role: 'application', name: '', text: '', id: '', bounds: null, clickable: false, enabled: true, children: data.map(fromIdb) }, format: 'ios-idb' }
   if (data?.attributes || data?.children && !data.role) return { root: fromMaestro(data), format: 'maestro' }
   if (data?.role) return { root: fromOwn(data), format: 'qawalk' }

package/src/lib/apps/webview.mjs

@@ -0,0 +1,54 @@
+// WebViews inside native apps (batch E): an Android app's WebView with debugging on (WebView.setWebContentsDebuggingEnabled
+// or a debuggable build) is a Chromium page over the DevTools protocol. Kaloko forwards its socket with adb and
+// connects Playwright to it, so a step script can drive the page and the capture is a web capture with the DOM and
+// the web checks. iOS WKWebViews (isInspectable) speak Safari's Web Inspector protocol, which Playwright cannot attach
+// to; capture those screens as app screens (tree, OCR) or test the web content in WebKit on its own.
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { createServer } from 'node:net'
+import { UserError } from '../util.mjs'
+
+const run = promisify(execFile)
+
+const freePort = () => new Promise((done, fail) => { const s = createServer().once('error', fail).listen(0, '127.0.0.1', () => { const p = s.address().port; s.close(() => done(p)) }) })
+
+/** DevTools sockets of WebViews on the device: [{ socket, pid }] from /proc/net/unix. */
+export function webviewSockets (procNetUnix) {
+  const out = []
+  for (const line of String(procNetUnix).split('\n')) {
+    const m = line.match(/@((?:webview_devtools_remote|chrome_devtools_remote)(?:_(\d+))?)\s*$/)
+    if (m && !out.some((x) => x.socket === m[1])) out.push({ socket: m[1], pid: m[2] ? Number(m[2]) : null })
+  }
+  return out
+}
+
+/**
+ * Attaches to the WebView of `cfg.package` (or the only one) on the device of `cfg` (adb, serial): forwards a
+ * local port and connects Playwright over CDP. Returns { browser, page, pages, close }.
+ */
+export async function attachAndroidWebView (cfg, { timeout = 15000 } = {}) {
+  const adb = (args) => run(cfg.adb || 'adb', [...(cfg.serial ? ['-s', cfg.serial] : []), ...args], { timeout: 30000 }).then((r) => r.stdout).catch((e) => { if (e.code === 'ENOENT') throw new UserError('adb is not installed or not on PATH.'); throw e })
+  const end = Date.now() + timeout
+  let socket = null
+  while (!socket && Date.now() < end) {
+    const all = webviewSockets(await adb(['shell', 'cat', '/proc/net/unix']).catch(() => ''))
+    const pid = cfg.package ? Number((await adb(['shell', 'pidof', cfg.package]).catch(() => '')).trim().split(/\s+/)[0]) || null : null
+    socket = (pid && all.find((x) => x.pid === pid)) || (!cfg.package && all.length === 1 ? all[0] : null) || (cfg.package ? null : all[0]) || null
+    if (!socket) await new Promise((r) => setTimeout(r, 500))
+  }
+  if (!socket) throw new UserError(`No debuggable WebView${cfg.package ? ` in ${cfg.package}` : ''} on the device. Turn on WebView.setWebContentsDebuggingEnabled(true) in debug builds (or open the screen with the WebView first).`)
+  const port = await freePort()
+  await adb(['forward', `tcp:${port}`, `localabstract:${socket.socket}`])
+  const { chromium } = await import('playwright')
+  let browser
+  try { browser = await chromium.connectOverCDP(`http://127.0.0.1:${port}`, { timeout }) } catch (e) {
+    await adb(['forward', '--remove', `tcp:${port}`]).catch(() => {})
+    throw new UserError(`Could not connect to the WebView (${socket.socket}): ${e.message.split('\n')[0]}`)
+  }
+  const pages = browser.contexts().flatMap((c) => c.pages())
+  // the visible page first: a WebView app often keeps hidden ones around
+  let page = pages[0] || null
+  for (const p of pages) { if (await p.evaluate(() => document.visibilityState === 'visible').catch(() => false)) { page = p; break } }
+  if (!page) { await browser.close().catch(() => {}); throw new UserError('The WebView has no page open.') }
+  return { browser, page, pages, socket: socket.socket, close: async () => { await browser.close().catch(() => {}); await adb(['forward', '--remove', `tcp:${port}`]).catch(() => {}) } }
+}

package/src/lib/apps/windows.mjs

@@ -0,0 +1,108 @@
+// Windows desktop apps (batch E): the app's window as a screenshot, its UI Automation tree and clicks or typing,
+// through windows.ps1 in the PowerShell every Windows has (no WinAppDriver, FlaUI or Appium to install). Same driver
+// interface as drivers.mjs; captures are app captures (tree, checks, OCR-free text from UIA names and values).
+// Not on Windows: walk on a Windows machine or CI runner, or capture with kaloko capture --image --tree uia.json.
+import { execFile, spawn } 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, dirname, basename } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { UserError } from '../util.mjs'
+import { readTree, query } from './tree.mjs'
+
+const run = promisify(execFile)
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
+const here = dirname(fileURLToPath(import.meta.url))
+export const WINDOWS_SCRIPT = join(here, 'windows.ps1')
+const pngSize = (buf) => (buf?.length > 24 && buf.readUInt32BE(12) === 0x49484452 ? [buf.readUInt32BE(16), buf.readUInt32BE(20)] : null)
+
+/** SendKeys treats + ^ % ~ ( ) { } [ ] as commands: braces make them plain characters. */
+export const sendKeysText = (text) => String(text).replace(/[+^%~(){}[\]]/g, (c) => `{${c}}`).replace(/\n/g, '{ENTER}')
+
+/** UIA tree in screen pixels → window-relative logical units (what touch targets and boxes use). */
+export function uiaToWindow (node, win) {
+  const s = win.scale || 1
+  const map = (n) => ({ ...n, x: Math.round((n.x - win.x) / s), y: Math.round((n.y - win.y) / s), w: Math.round(n.w / s), h: Math.round(n.h / s), children: (n.children || []).map(map) })
+  return map(node)
+}
+
+export function windowsApp (cfg, ctx) {
+  const ps = cfg.powershell || (process.platform === 'win32' ? 'powershell.exe' : null)
+  if (!ps) throw new UserError('Windows apps are walked on Windows (a machine or a windows-latest CI runner). Elsewhere capture the screens with kaloko capture --image shot.png [--tree uia.json] --platform windows.')
+  const name = cfg.name || (cfg.path ? basename(cfg.path).replace(/\.exe$/i, '') : null)
+  if (!name) throw new UserError('environments.<env>.app.windows needs name (process name or window title) or path.')
+  const call = async (...args) => {
+    try {
+      const { stdout } = await run(ps, ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', WINDOWS_SCRIPT, ...args.map(String)], { timeout: 120000, maxBuffer: 64 * 1024 * 1024, windowsHide: true })
+      return JSON.parse(stdout.trim() || '{}')
+    } catch (error) {
+      if (error.code === 'ENOENT') throw new UserError(`${ps} was not found. Set app.windows.powershell to powershell.exe or pwsh.`)
+      throw new Error(`windows ${args[0]}: ${String(error.stderr || error.message).trim().split('\n').filter(Boolean).pop()}`)
+    }
+  }
+  let win = null
+  const findWindow = async (timeout = 15000) => {
+    const end = Date.now() + timeout
+    let last
+    while (Date.now() < end) { try { return await call('window', name) } catch (e) { last = e; await sleep(500) } }
+    throw new UserError(`No window of ${name} on the screen: ${last?.message || 'not found'}`)
+  }
+  const d = {
+    platform: 'windows',
+    async open ({ reset, attach = false } = {}) {
+      if (cfg.launch !== false && !attach) {
+        if (reset ?? cfg.reset) { await call('close', name).catch(() => {}); await sleep(800) }
+        if (cfg.aumid) spawn('explorer.exe', [`shell:AppsFolder\\${cfg.aumid}`], { detached: true, stdio: 'ignore' }).unref()
+        else if (cfg.path) spawn(resolve(ctx.root, cfg.path), cfg.args || [], { detached: true, stdio: 'ignore', cwd: ctx.root }).unref()
+        await sleep(cfg.launch_wait ?? 2000)
+      }
+      win = await findWindow()
+    },
+    async link (url) { spawn(ps, ['-NoProfile', '-Command', 'Start-Process', `'${String(url).replace(/'/g, "''")}'`], { detached: true, stdio: 'ignore' }).unref(); await sleep(cfg.settle ?? 1000) },
+    async tap (target) {
+      const p = await point(d, target)
+      win = await call('window', name)
+      await call('click', Math.round(win.x + p.x * (win.scale || 1)), Math.round(win.y + p.y * (win.scale || 1)))
+      await sleep(cfg.settle ?? 500)
+    },
+    async type (text) { await call('type', sendKeysText(text)); await sleep(300) },
+    async back () { throw new UserError('Windows apps have no system back: tap the app\'s own back button.') },
+    async wait (w) {
+      if (typeof w === 'number') return sleep(w)
+      const sel = w?.selector || (w?.text ? `[name*="${String(w.text).replace(/"/g, '')}"]` : null)
+      if (!sel) return
+      const end = Date.now() + (w.timeout || 15000)
+      while (Date.now() < end) { const t = await d.tree().catch(() => null); if (t && query(t.root, sel).length) return; await sleep(500) }
+      throw new Error(`timed out waiting for ${sel}`)
+    },
+    async tree () {
+      win ||= await call('window', name)
+      const raw = await call('tree', win.hwnd)
+      return raw?.uia ? readTree({ uia: uiaToWindow(raw.uia, win) }) : null
+    },
+    async snapshot () {
+      win = await call('window', name)
+      const dir = await mkdtemp(join(tmpdir(), 'kaloko-win-'))
+      try {
+        const f = join(dir, 'w.png')
+        await call('shot', win.hwnd, f)
+        const png = await readFile(f); const px = pngSize(png) || [win.w, win.h]
+        const scale = win.scale || 1
+        const tree = await d.tree().catch(() => null)
+        return { png, tree, size: [Math.round(px[0] / scale), Math.round(px[1] / scale)], scale, device: `Windows · ${win.owner || name}`, crash: null, logErrors: null }
+      } finally { await rm(dir, { recursive: true, force: true }) }
+    },
+    async close () {}
+  }
+  return d
+}
+
+async function point (d, target) {
+  if (target && typeof target === 'object' && 'x' in target) return target
+  const t = await d.tree()
+  if (!t) throw new UserError('No UI tree to find the element in; tap by coordinates { x, y }.')
+  const n = query(t.root, String(target)).find((x) => x.bounds && x.bounds.w > 0)
+  if (!n) throw new Error(`no visible ${target}`)
+  return { x: n.bounds.x + n.bounds.w / 2, y: n.bounds.y + n.bounds.h / 2 }
+}

package/src/lib/apps/windows.ps1

@@ -0,0 +1,78 @@
+# Kaloko helper for Windows desktop apps: window lookup, window screenshot, UI Automation tree, click and typing.
+# Runs in Windows PowerShell 5.1 (built in) or PowerShell 7 on Windows; nothing to install. Prints JSON.
+#   window <process name or title>   { pid, hwnd, title, owner, x, y, w, h, scale }  (physical pixels, scale = DPI / 96)
+#   shot <hwnd> <file.png>           the window as PNG (PrintWindow, else a screen copy)
+#   tree <hwnd>                      { uia: { type, name, id, cls, value, x, y, w, h, enabled, focused, offscreen, children } }
+#   click <x> <y>                    left click at screen pixels
+#   type <text>                      SendKeys text (already escaped by the caller)
+#   close <process name>             asks the app's main window to close
+param([string]$Cmd, [string]$A1, [string]$A2)
+$ErrorActionPreference = 'Stop'
+# Node reads UTF-8; Windows PowerShell 5.1 would write the OEM code page (Czech names arrive garbled)
+[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
+Add-Type -AssemblyName UIAutomationClient, UIAutomationTypes, System.Drawing, System.Windows.Forms
+Add-Type @"
+using System; using System.Runtime.InteropServices;
+public static class KalokoWin {
+  [DllImport("user32.dll")] public static extern bool SetProcessDPIAware();
+  [DllImport("user32.dll")] public static extern bool SetForegroundWindow(IntPtr h);
+  [DllImport("user32.dll")] public static extern bool ShowWindow(IntPtr h, int n);
+  [DllImport("user32.dll")] public static extern bool GetWindowRect(IntPtr h, out RECT r);
+  [DllImport("user32.dll")] public static extern uint GetDpiForWindow(IntPtr h);
+  [DllImport("user32.dll")] public static extern bool SetCursorPos(int x, int y);
+  [DllImport("user32.dll")] public static extern void mouse_event(uint f, uint x, uint y, uint d, IntPtr e);
+  [DllImport("user32.dll")] public static extern bool PrintWindow(IntPtr h, IntPtr hdc, uint flags);
+  [StructLayout(LayoutKind.Sequential)] public struct RECT { public int Left, Top, Right, Bottom; }
+}
+"@
+[KalokoWin]::SetProcessDPIAware() | Out-Null
+
+function Get-Rect($h) { $r = New-Object KalokoWin+RECT; [KalokoWin]::GetWindowRect($h, [ref]$r) | Out-Null; return $r }
+
+function Find-Window($name) {
+  $p = Get-Process | Where-Object { $_.MainWindowHandle -ne 0 -and ($_.ProcessName -ieq $name -or $_.MainWindowTitle -like "*$name*") } | Select-Object -First 1
+  if (-not $p) { throw "No window of '$name' (is the app running and not minimised?)." }
+  $r = Get-Rect $p.MainWindowHandle
+  $dpi = 96; try { $dpi = [KalokoWin]::GetDpiForWindow($p.MainWindowHandle) } catch {}
+  [pscustomobject]@{ pid = $p.Id; hwnd = [int64]$p.MainWindowHandle; title = $p.MainWindowTitle; owner = $p.ProcessName; x = $r.Left; y = $r.Top; w = $r.Right - $r.Left; h = $r.Bottom - $r.Top; scale = $dpi / 96 }
+}
+
+function Num($v) { if ([double]::IsInfinity($v) -or [double]::IsNaN($v)) { return 0 } return [int]$v }
+
+switch ($Cmd) {
+  'window' { Find-Window $A1 | ConvertTo-Json -Compress }
+  'shot' {
+    $h = [IntPtr][int64]$A1
+    [KalokoWin]::ShowWindow($h, 9) | Out-Null; [KalokoWin]::SetForegroundWindow($h) | Out-Null; Start-Sleep -Milliseconds 300
+    $r = Get-Rect $h; $w = $r.Right - $r.Left; $hh = $r.Bottom - $r.Top
+    $bmp = New-Object System.Drawing.Bitmap $w, $hh
+    $g = [System.Drawing.Graphics]::FromImage($bmp)
+    $hdc = $g.GetHdc(); $ok = [KalokoWin]::PrintWindow($h, $hdc, 2); $g.ReleaseHdc($hdc)
+    if (-not $ok) { $g.CopyFromScreen($r.Left, $r.Top, 0, 0, $bmp.Size) }
+    $bmp.Save($A2, [System.Drawing.Imaging.ImageFormat]::Png); $g.Dispose(); $bmp.Dispose()
+    '{"ok":true}'
+  }
+  'tree' {
+    $root = [System.Windows.Automation.AutomationElement]::FromHandle([IntPtr][int64]$A1)
+    $walker = [System.Windows.Automation.TreeWalker]::ControlViewWalker
+    $script:count = 0
+    function Node($el, $depth) {
+      $script:count++
+      if ($script:count -gt 2500 -or $depth -gt 40) { return $null }
+      # an element that disappears while the tree is read is left out, not the whole tree
+      try { $c = $el.Current; $b = $c.BoundingRectangle } catch { return $null }
+      $kids = @(); $ch = $null; try { $ch = $walker.GetFirstChild($el) } catch {}
+      while ($ch -ne $null) { $k = Node $ch ($depth + 1); if ($k) { $kids += $k }; try { $ch = $walker.GetNextSibling($ch) } catch { $ch = $null } }
+      $v = $null; try { $v = $el.GetCurrentPattern([System.Windows.Automation.ValuePattern]::Pattern).Current.Value } catch {}
+      $empty = $b.IsEmpty
+      [pscustomobject]@{ type = ($c.ControlType.ProgrammaticName -replace '^ControlType\.', ''); name = $c.Name; id = $c.AutomationId; cls = $c.ClassName; value = $v
+        x = $(if ($empty) { 0 } else { Num $b.X }); y = $(if ($empty) { 0 } else { Num $b.Y }); w = $(if ($empty) { 0 } else { Num $b.Width }); h = $(if ($empty) { 0 } else { Num $b.Height })
+        enabled = $c.IsEnabled; focused = $c.HasKeyboardFocus; offscreen = $c.IsOffscreen; children = $kids }
+    }
+    @{ uia = (Node $root 0) } | ConvertTo-Json -Depth 90 -Compress
+  }
+  'click' { [KalokoWin]::SetCursorPos([int]$A1, [int]$A2) | Out-Null; [KalokoWin]::mouse_event(2, 0, 0, 0, [IntPtr]::Zero); [KalokoWin]::mouse_event(4, 0, 0, 0, [IntPtr]::Zero); '{"ok":true}' }
+  'type' { [System.Windows.Forms.SendKeys]::SendWait($A1); '{"ok":true}' }
+  'close' { Get-Process | Where-Object { $_.ProcessName -ieq $A1 } | ForEach-Object { $_.CloseMainWindow() | Out-Null }; '{"ok":true}' }
+  default { throw "unknown command $Cmd" }
+}