kaloko 0.4.10 → 0.5.0

package/src/lib/apps/recording-native.mjs

@@ -0,0 +1,212 @@
+// Recordings of native app steps (batch D): the device or the desktop records itself while the step runs.
+//   android   adb shell screenrecord, in segments (the tool stops after 3 minutes), touches shown while recording
+//   ios       xcrun simctl io <device> recordVideo (H.264)
+//   desktop   macOS screencapture -v with clicks shown (needs Screen Recording permission)
+// Electron windows are web pages and use the screencast recorder (recording.mjs).
+// Each finished clip is MP4 H.264, which every browser plays; ffmpeg joins segments, remuxes the macOS .mov and makes
+// the poster and preview. Taps the step script made through the driver are kept as markers for the canvas.
+import { mkdir, rm, rename, writeFile, stat, copyFile } from 'node:fs/promises'
+import { join, dirname } from 'node:path'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { startProcess, ffmpeg, mediaDuration, stillsFromVideo, videoTools, installHint } from '../video.mjs'
+import { recBase, saveRecording, stepRecorded, parseRecord } from '../recording.mjs'
+import { addCapture, runPaths } from '../run.mjs'
+import { writeJson } from '../util.mjs'
+import { summarizeTrace } from '../trace.mjs'
+
+const run = promisify(execFile)
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+/** screenrecord stops at 180 s; segments a little shorter leave time to start the next one. */
+export const ANDROID_SEGMENT = 170
+const ANDROID_BITRATE = { low: 2_000_000, medium: 4_000_000, high: 8_000_000 }
+
+/** Shell arguments of one Android segment (tests read them). */
+export function screenrecordArgs ({ serial, file, quality = 'medium', seconds = ANDROID_SEGMENT }) {
+  return [...(serial ? ['-s', serial] : []), 'shell', 'screenrecord', '--time-limit', String(Math.min(180, seconds)), '--bit-rate', String(ANDROID_BITRATE[quality] || ANDROID_BITRATE.medium), file]
+}
+
+/** The booted simulator a config means (udid, device name, or the first booted one), as the iOS driver picks it. */
+export async function bootedSimulator (cfg = {}, exec = run) {
+  const { stdout } = await exec('xcrun', ['simctl', 'list', 'devices', 'booted', '-j'])
+  const all = Object.values(JSON.parse(stdout).devices || {}).flat()
+  const dev = cfg.udid ? all.find((d) => d.udid === cfg.udid) : cfg.device ? all.find((d) => d.name === cfg.device) : all[0]
+  return dev?.udid || null
+}
+
+/**
+ * One recorder for one step: start() before the step, stop() at its capture → { file (.mp4 or .mov), source } or null.
+ * `tools` from videoTools(). Throws nothing: a recording that cannot start leaves `reason`.
+ */
+export function nativeRecorder ({ platform, cfg = {}, tools, quality = 'medium', maxSeconds = 60, tmp }) {
+  const r = { platform, reason: null, segments: [], child: null, started: 0 }
+  if (platform === 'android') {
+    const adb = cfg.adb || process.env.KALOKO_ADB || 'adb'
+    const serial = cfg.serial || process.env.ANDROID_SERIAL || null
+    let n = 0; let stopping = false; let showTouches = null
+    const shell = (...a) => run(adb, [...(serial ? ['-s', serial] : []), 'shell', ...a], { timeout: 20000 })
+    const next = () => {
+      const remote = `/sdcard/kaloko-rec-${process.pid}-${Date.now().toString(36)}-${n++}.mp4`
+      r.segments.push(remote)
+      const left = Math.max(1, Math.ceil(maxSeconds - (Date.now() - r.started) / 1000))
+      r.child = startProcess(adb, screenrecordArgs({ serial, file: remote, quality, seconds: Math.min(ANDROID_SEGMENT, left) }))
+      r.child.done.then(() => { if (!stopping && (Date.now() - r.started) / 1000 < maxSeconds - 1) next() })
+    }
+    r.start = async () => {
+      if (!tools.adb) { r.reason = `adb is not installed (${installHint('adb')})`; return false }
+      showTouches = (await shell('settings', 'get', 'system', 'show_touches').catch(() => ({ stdout: '' }))).stdout.trim()
+      await shell('settings', 'put', 'system', 'show_touches', '1').catch(() => {})
+      r.started = Date.now(); next(); await sleep(700)
+      return true
+    }
+    r.stop = async () => {
+      stopping = true
+      await shell('pkill', '-INT', 'screenrecord').catch(() => {})
+      await Promise.race([r.child?.done, sleep(6000)])
+      if (showTouches !== '1') await shell('settings', 'put', 'system', 'show_touches', showTouches || '0').catch(() => {})
+      await sleep(400) // the device finishes writing the file
+      const local = []
+      for (const [i, remote] of r.segments.entries()) {
+        const f = join(tmp, `seg${i}.mp4`)
+        try { await run(adb, [...(serial ? ['-s', serial] : []), 'pull', remote, f], { timeout: 120000 }); local.push(f) } catch {}
+        await shell('rm', '-f', remote).catch(() => {})
+      }
+      if (!local.length) { r.reason = 'the device kept no recording'; return null }
+      return { file: await joinSegments(tools, local, join(tmp, 'android.mp4')), source: 'adb', segments: local.length }
+    }
+  } else if (platform === 'ios') {
+    let file = null
+    r.start = async () => {
+      if (!tools.simctl) { r.reason = `simctl is missing (${installHint('simctl', 'darwin')})`; return false }
+      const udid = await bootedSimulator(cfg).catch(() => null)
+      if (!udid) { r.reason = 'no booted iOS Simulator'; return false }
+      file = join(tmp, 'ios.mp4')
+      r.child = startProcess('xcrun', ['simctl', 'io', udid, 'recordVideo', '--codec=h264', '--force', file])
+      r.started = Date.now()
+      // simctl says when the first frame is in; a step that starts before would miss its beginning
+      for (let i = 0; i < 50 && !/Recording started/i.test(r.child.output()); i++) await sleep(100)
+      return true
+    }
+    r.stop = async () => {
+      r.child?.kill('SIGINT')
+      await Promise.race([r.child?.done, sleep(8000)])
+      return (await stat(file).catch(() => null))?.size ? { file, source: 'simctl' } : null
+    }
+  } else if (platform === 'desktop') {
+    let file = null
+    r.start = async () => {
+      if (process.platform !== 'darwin') { r.reason = 'desktop recording needs macOS'; return false }
+      file = join(tmp, 'desktop.mov')
+      // -v video, -C cursor, -k clicks, -x no sound, -V the longest it may take
+      r.child = startProcess('/usr/sbin/screencapture', ['-v', '-C', '-k', '-x', '-V', String(Math.max(2, Math.round(maxSeconds))), file])
+      r.started = Date.now(); await sleep(800)
+      return true
+    }
+    r.stop = async () => {
+      r.child?.kill('SIGINT')
+      await Promise.race([r.child?.done, sleep(8000)])
+      if (!(await stat(file).catch(() => null))?.size) { r.reason = 'screencapture kept no recording (allow Screen Recording for this terminal in System Settings → Privacy & Security)'; return null }
+      if (!tools.ffmpeg) { r.reason = `the macOS recording is QuickTime (.mov); ffmpeg turns it into MP4 for the canvas (${installHint('ffmpeg', 'darwin')})`; return { file, source: 'screencapture', mov: true } }
+      const mp4 = join(tmp, 'desktop.mp4')
+      try { await ffmpeg(tools, ['-i', file, '-c:v', 'copy', '-movflags', '+faststart', '-an', mp4]) } catch { await ffmpeg(tools, ['-i', file, '-c:v', tools.ffmpeg.encoders.h264 || 'libx264', '-pix_fmt', 'yuv420p', '-movflags', '+faststart', '-an', mp4]) }
+      return { file: mp4, source: 'screencapture' }
+    }
+  } else {
+    r.start = async () => { r.reason = `no native recorder for ${platform}`; return false }
+    r.stop = async () => null
+  }
+  return r
+}
+
+/** Segments of one recording as one MP4: ffmpeg concatenates them; without ffmpeg the last segment is kept. */
+export async function joinSegments (tools, files, out) {
+  if (files.length === 1) { await rename(files[0], out); return out }
+  if (!tools.ffmpeg) { await rename(files.at(-1), out); return out }
+  const list = join(dirname(out), 'segments.txt')
+  await writeFile(list, files.map((f) => `file '${f.replaceAll("'", "'\\''")}'`).join('\n') + '\n')
+  await ffmpeg(tools, ['-f', 'concat', '-safe', '0', '-i', list, '-c', 'copy', '-movflags', '+faststart', out])
+  return out
+}
+
+/**
+ * The driver with its interactions logged ({ t, type, target }) for the trace and the tap markers; typed text is
+ * never kept, only its length.
+ */
+export function instrumentDriver (driver, log) {
+  const wrap = (name, describe) => {
+    const fn = driver[name]
+    if (typeof fn !== 'function') return
+    driver[name] = async (...a) => { log.push({ t: Date.now(), type: name, ...describe(...a) }); return fn.apply(driver, a) }
+  }
+  wrap('tap', (target) => (target && typeof target === 'object' && target.x != null ? { x: target.x, y: target.y } : { target: String(target ?? '').slice(0, 120) }))
+  wrap('type', (text) => ({ target: `${String(text ?? '').length} characters` }))
+  wrap('back', () => ({}))
+  wrap('link', (url) => ({ url: String(url ?? '').slice(0, 300) }))
+  wrap('swipe', (...a) => ({ target: a.map((x) => typeof x === 'object' ? JSON.stringify(x) : String(x)).join(' ').slice(0, 120) }))
+  return driver
+}
+
+/**
+ * Per locale of an app walk (android, ios, desktop): beforeStep(node) starts the device recording when the step is
+ * recorded; afterStep(node, { record, error }) stops it, stores the MP4, poster, preview, taps and a trace of the
+ * driver's actions. `encoder` returns a Chrome page for the WebP preview (optional).
+ */
+export async function nativeSession ({ platform, env, run, scenario, locale, settings, driver, encoder, say = () => {} }) {
+  const anyRecord = !!settings.record || scenario.nodes.some((n) => parseRecord(n.record ?? n.capture?.record))
+  if (!anyRecord && !settings.trace) return null
+  const tools = anyRecord ? await videoTools() : {}
+  const actions = []
+  instrumentDriver(driver, actions)
+  const cfg = env.app?.[platform] || {}
+  let cur = null
+  const notes = new Set()
+  return {
+    async beforeStep (node) {
+      actions.length = 0
+      cur = { node, t0: Date.now(), t1: null, rec: null }
+      const want = settings.record?.mode === 'flow' ? { ...settings.record, mode: 'step' } : stepRecorded(settings, node)
+      if (!want) return
+      const tmp = join(run.dir, '.rec-tmp', `${node.id}-${locale}`)
+      await mkdir(tmp, { recursive: true })
+      const r = nativeRecorder({ platform, cfg, tools, quality: want.quality, maxSeconds: want.max_seconds || 60, tmp })
+      if (await r.start()) cur.rec = { r, want, tmp }
+      else if (r.reason) notes.add(`recording ${platform}: ${r.reason}`)
+    },
+    async beforeCapture () { if (cur && !cur.t1) { cur.t1 = Date.now(); if (cur.rec) cur.clip = await cur.rec.r.stop().catch(() => null) } },
+    async afterStep (node, { record = null, error = null } = {}) {
+      if (!cur || cur.node !== node) return
+      const { t0, rec } = cur
+      const t1 = cur.t1 || Date.now()
+      const clip = cur.clip !== undefined ? cur.clip : rec ? await rec.r.stop().catch(() => null) : null
+      cur = null
+      const vp = record?.viewport || Object.keys(run.meta.scope.viewports || {})[0] || 'phone'
+      const failed = !!error || Object.values(record?.checks || {}).some((c) => c?.ok === false)
+      const size = record?.size?.viewport || null
+      if (settings.trace) {
+        const file = runPaths(run.dir).step(node.id, locale, vp, 'trace.json')
+        const trace = { schema: 'qawalk.trace.v1', node: node.id, locale, viewport: vp, platform, started_at: new Date(t0).toISOString(), duration_ms: t1 - t0, actions: actions.filter((a) => a.t <= t1).map((a) => ({ ...a, t: Math.max(0, a.t - t0) })), network: [], console: [] }
+        trace.summary = summarizeTrace(trace)
+        await mkdir(dirname(file), { recursive: true })
+        await writeJson(file, trace)
+        await addCapture(run.dir, { type: 'trace', node: node.id, locale, viewport: vp, file: file.slice(run.dir.length + 1), captured_at: record?.captured_at || null, at: new Date().toISOString() })
+      }
+      if (!rec) return
+      try {
+        if (!clip || (rec.want.mode === 'failed' && !failed)) { if (!clip && rec.r.reason) notes.add(`recording ${platform}: ${rec.r.reason}`); return }
+        const base = recBase(run.dir, node.id, locale, vp)
+        await mkdir(dirname(base), { recursive: true })
+        if (clip.mov) { await copyFile(clip.file, `${base}.mov`); notes.add(rec.r.reason); return }
+        await copyFile(clip.file, `${base}.mp4`)
+        const duration = (tools.ffmpeg && await mediaDuration(tools, `${base}.mp4`)) || (t1 - t0)
+        const stills = await stillsFromVideo({ tools, page: await encoder?.(), file: `${base}.mp4`, out: base, quality: rec.want.quality, duration })
+        const files = { mp4: `${base}.mp4`, ...(stills.poster ? { poster: stills.poster } : {}), ...(stills.preview ? { preview: stills.preview } : {}) }
+        const bytes = {}
+        for (const [k, f] of Object.entries(files)) bytes[k] = (await stat(f)).size
+        // taps with coordinates, as fractions of the screen, relative to the clip
+        const taps = size ? actions.filter((a) => a.type === 'tap' && a.x != null && a.t <= t1).map((a) => ({ t: Math.max(0, a.t - t0), x: +(a.x / size[0]).toFixed(4), y: +(a.y / size[1]).toFixed(4) })) : []
+        await saveRecording({ run, node, locale, viewport: vp, result: { files, bytes, duration_ms: duration, width: null, height: null, codec: 'h264' }, mode: rec.want.mode, failed, error, captured_at: record?.captured_at || null, taps, source: clip.source })
+      } catch (e) { notes.add(`recording ${platform}: ${String(e.message).split('\n')[0]}`) } finally { await rm(rec.tmp, { recursive: true, force: true }) }
+    },
+    async finish () { await rm(join(run.dir, '.rec-tmp'), { recursive: true, force: true }); return [...notes].filter(Boolean).map((n) => `${n} (${locale})`) }
+  }
+}

package/src/lib/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" }
+}