repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

win32-drive: make less annoying

a1bd15a692e083115569cd2fb7eba746b1131730

Oliver Krylow <o.krylow@isp-insoft.de> ·

SSH signature · not checked

Browse filesCompare with HEAD

Changed files (3)

pi/agent/skills/win32-drive/SKILL.md

Modified
9 9 Resolve `scripts/win32-drive.ps1` against this skill's directory and pass that absolute path; never rely on the current directory.
11 11 ```powershell
12 -powershell.exe -NoProfile -ExecutionPolicy Bypass -File <skill-dir>/scripts/win32-drive.ps1 <cmd> [opts]
12 +powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -WindowStyle Hidden -File <skill-dir>/scripts/win32-drive.ps1 <cmd> [opts]
15 -All commands emit JSON. On nonzero exit, JSON has `ok:false,error`.
15 +All commands emit one JSON object with `ok`, `cmd`, and `elapsedMs`; failures add `code` and `hint` and exit nonzero. `help` prints the full command and option catalog, so read it instead of guessing flags.
17 -## Safety
17 +## Work in this order
19 -Nonracing: `help`, `list`, `shot`, `pixel`, `uia`, `cursor`, `focus`, `idle`, clipboard read, theme read, `overlay`.
19 +1. **Observe** — `list`, `shot`, `uia`, `pixel`, `focus`, `idle`, `clipboard`. Free, invisible, never disturbs the human.
20 +2. **Act in the background** — `uia-invoke`, `uia-set`, `window`, `clipboard -Set`, `theme`. These change the app through accessibility or messages: no activation, no pointer, no keystrokes. The human keeps typing in another window.
21 +3. **Take over the machine** — `click`, `type`, `key`, or any `-Focus auto`. Last resort only.
21 -Racing/mutating: `uia-invoke`, `uia-set`, `click`, `type`, `key`, `window`, `clipboard -Set`, theme set. These fade a 16px red border/ring, wait 800ms user-idle, then act. The overlay never takes focus and never swallows input. Screenshots never show the guard.
23 +Before anything in step 3: **ask the human first** and say what you will click or type. The human is usually working on this machine; a takeover steals the pointer and the foreground window. Never chain takeovers silently; ask once per task, not once per click.
23 -`-IdleMs n` (default 800) and `-TimeoutMs n` (default 10000) tune that guard; `-IdleMs 0` skips waiting and is for tests, not for a desktop the user is touching.
25 +If step 2 fails with `no-pattern`, that app has no usable accessibility action — report that to the human and ask for permission to use the pointer instead of just escalating.
25 -## Commands
27 +## Be fast
27 -```text
28 -help
29 -list
30 -shot [-Hwnd n|-Process p -TitleContains t|-X x -Y y -Width w -Height h] [-Out file.png]
31 -pixel -X x -Y y
32 -uia [-Hwnd n|-Process p|-TitleContains t] [-Depth n]
33 -uia-invoke -Hwnd n|-Process p|-TitleContains t [-Name n] [-AutomationId a] [-ClassName c] [-ControlType t] [-Index i]
34 -uia-set -Hwnd n|-Process p|-TitleContains t -Value text [-Name n] [-AutomationId a] [-ClassName c] [-ControlType t] [-Index i]
35 -cursor
36 -focus
37 -idle
38 -clipboard | clipboard -Set text
39 -theme | theme -Mode dark|light [-Scope apps|system|both] [-Refresh broadcast|full]
40 -overlay [-X x -Y y] [-DurationMs ms]
41 -click -Pointer [-Hwnd n|-Process p|-TitleContains t] [-X x -Y y] [-Button left|right] [-Count n] [-Focus auto|require|skip] [-Cursor restore|keep]
42 -type [-Hwnd n|-Process p|-TitleContains t] -Text text [-Focus auto|require|skip] [-Pointer] [-Method unicode|sendkeys]
43 -key [-Hwnd n|-Process p|-TitleContains t] -Keys '^s' [-Focus auto|require|skip] [-Pointer]
44 -window -Action move|min|max|restore|close [-Hwnd n|-Process p|-TitleContains t] [-X x -Y y -Width w -Height h]
29 +Process start costs about 1.4s and dwarfs every action, so **batch** whole interactions into one invocation:
31 +```powershell
32 +# steps.json
33 +[{"cmd":"uia-invoke","TitleContains":"Notepad","Name":"File"},
34 + {"cmd":"wait","ms":250},
35 + {"cmd":"uia-set","TitleContains":"Notepad","ClassName":"*EDIT*","Value":"hello"},
36 + {"cmd":"shot","TitleContains":"Notepad","Out":"C:/temp/after.png"}]
47 -Selector preference: `-Hwnd` > `-Process` + `-TitleContains` > unique `-TitleContains` > coordinates.
39 +```powershell
40 +... -File <skill-dir>/scripts/win32-drive.ps1 batch -File steps.json
41 +```
49 -## Coordinates
43 +- Steps use the same option names as the command line; flags are `true` (`"Pointer": true`).
44 +- `{"cmd":"wait","ms":300}` pauses between steps; use it instead of separate invocations.
45 +- Execution stops at the first failing step (`failedAt`, per-step `code`) unless `-ContinueOnError`.
46 +- `-Json` also works from Bash or Nushell, but PowerShell mangles embedded quotes: prefer `-File` or stdin.
51 -Screen pixels everywhere, except `click -X/-Y` with a window selector, which are relative to the window origin reported by `list` and `shot` (DWM frame bounds). Without `-X/-Y`, a window click targets the center.
48 +Do not re-query what a result already contains:
53 -`uia` returns screen coordinates: convert with `click -X (uia.x - shot.x) -Y (uia.y - shot.y)`, or click without a selector.
50 +- `list` returns `count`, `foreground`, `idleMs`, and per window `z`, `focused`, `minimized`; it accepts `-Process`/`-TitleContains`/`-Hwnd` filters.
51 +- `click`/`type`/`key` return `target`, `foreground`, `returnedTo`.
52 +- `window` returns the updated window rect.
53 +- `uia-invoke`/`uia-set` return the matched `element` and which `pattern` fired.
54 +- Errors return context: `candidates` for `no-window`, `ambiguous-window`, `no-element`, `ambiguous-element`; `foreground`, `lockTimeoutMs`, `idleMs` for `focus-denied`.
55 -`shot -Hwnd` returns exactly the `list` frame bounds, so image pixel `(0,0)` is screen pixel `(x,y)` in both `printwindow` and `screen-crop` modes. After `shot`, immediately read the returned PNG path with the harness `read` tool.
56 +The native layer is compiled once and cached in `%LOCALAPPDATA%\win32-drive`; `help.nativeLoad` reports `cache`, `compiled`, or `loaded`. A `compiled` result means the cache was cold, which also briefly spawns the C# compiler; steady state is `cache`.
57 58 ## Acting without stealing focus
59 -Prefer `uia-invoke` and `uia-set`. They drive the app through accessibility and posted messages: no activation, no cursor movement, no synthetic keystrokes, so the user keeps working in another window. Read the tree with `uia` first, then address the element by `-Name`, `-AutomationId`, `-ClassName`, or `-ControlType`; the string filters accept wildcards, `-Index` disambiguates, and an ambiguous match reports the candidates.
60 +Read the tree with `uia`, then address the element by `-Name`, `-AutomationId`, `-ClassName`, or `-ControlType`; string filters accept wildcards, `-Index` disambiguates, ambiguity reports candidates.
61 -`uia-invoke` tries `Invoke`, `Toggle`, `SelectionItem`, `ExpandCollapse`, then MSAA default action, then `BM_CLICK`, and reports which one it used. `uia-set` tries `Value`, then posts characters to the control and verifies the resulting text. Both fail loudly when the app exposes nothing usable, which is common for GPU-rendered apps with no accessibility tree; fall back to pointer input there.
62 +`uia-invoke` tries `Invoke`, `Toggle`, `SelectionItem`, `ExpandCollapse`, MSAA default action, then `BM_CLICK`. `uia-set` tries `ValuePattern`, then posts characters to the control and verifies the resulting text. Both report which path fired and leave the foreground window alone. They cannot hover, drag, or reach anything outside the accessibility tree; GPU-rendered apps often expose nothing.
63 -They cannot hover, drag, or reach anything outside the accessibility tree.
64 +## Takeover contract
65 -## Focus and pointer input
66 +Pointer input requires the explicit `-Pointer` flag. `click` always needs it; `type` and `key` need it only for `-Focus auto`, whose fallback is a pointer click on the target caption.
67 -Synthetic mouse input requires the explicit `-Pointer` flag. `click` always needs it; `type` and `key` need it only for `-Focus auto`, whose fallback is a pointer click.
68 +Every takeover: wait for an input gap, then show a red border, a ring on the target point, and a banner naming the action and target window, counting down (`-CountdownMs`, default 1200). **Any keyboard or mouse input during the countdown cancels the action** with code `takeover-aborted`; that is the human vetoing you, so stop and ask again. `-NoCountdown` skips the countdown and belongs to tests, not to a desktop in use.
69 -`click`, `type`, and `key` with a selector focus the target and verify it actually became foreground; they fail instead of driving whatever window happens to be in front. Focusing happens after the racing guard, never before: Windows denies activation to background processes while the user is typing or moving the mouse.
70 +Focus modes: `require` (default, activation APIs only), `auto` (adds the caption click, needs `-Pointer`), `skip` (no focusing). Focusing happens after the guard, because Windows denies activation while the human is typing. Minimized targets fail; restore them first.
71 -- `require` (default): activation APIs only; fails when Windows denies them, which is normal on systems with a large `ForegroundLockTimeout`.
72 -- `auto`: adds a single left click on the target's title bar, which always activates because it is real pointer input. Needs `-Pointer`. On a borderless window that click lands on content.
73 -- `skip`: no focusing at all; input goes to whatever is focused.
72 +After acting, focus returns to the window the human was using (`-Return restore`, default; `returnedTo` reports the result). Pass `-Return keep` when the next step in the same batch needs the target focused.
75 -Minimized targets fail: restore them first.
74 +`-IdleMs n` (default 800) and `-TimeoutMs n` (default 10000) tune the idle gate. `overlay -Text "..."` previews the banner without acting.
77 -Errors report the real foreground window, whether it is hung, the system `ForegroundLockTimeout`, and the current user idle time. `focus` reports the same foreground record on demand. A hung foreground window cannot be displaced at all; nothing can be driven until it recovers.
76 +## Coordinates
79 -Never use `AttachThreadInput` to force activation from this script: it couples input queues and has hung the host terminal here.
78 +Screen pixels everywhere, except `click -X/-Y` with a window selector, which are relative to the window origin reported by `list` and `shot`. Without `-X/-Y`, a window click targets the center.
81 -## Typing
83 -`type` injects Unicode code units directly (`-Method unicode`, the default on 64-bit) so text arrives verbatim, newline as Enter, carriage returns dropped. `-Method sendkeys` uses the legacy escaped SendKeys path. `key` is always SendKeys, for chords like `^s` or `%{F4}`.
80 +`uia` returns screen coordinates: convert with `click -X (uia.x - shot.x) -Y (uia.y - shot.y)`, or click without a selector. `shot -Hwnd` returns exactly the `list` frame bounds, so image pixel `(0,0)` is screen pixel `(x,y)` in both `printwindow` and `screen-crop` modes. After `shot`, read the returned PNG path with the harness `read` tool.
85 82 ## Limits
87 -No UAC secure desktop or lock screen. Elevated apps need an elevated agent. GPU/fullscreen windows fall back from `printwindow` to `screen-crop`, which captures whatever is on top. Theme only updates Windows plus apps that follow the system theme; `-Refresh full` additionally runs `UpdatePerUserSystemParameters`, which can perturb wallpaper and per-user parameters, so prefer the default broadcast. Even the default broadcasts `WM_SETTINGCHANGE` to every window, which has been observed to wedge apps that react to it: set the theme once, not in a loop. `theme -Mode` returns `previous` for restoring state.
84 +No UAC secure desktop or lock screen; elevated apps need an elevated agent. GPU/fullscreen windows fall back to `screen-crop`, which captures whatever is on top. A hung foreground window (`foreground.hung`) cannot be displaced at all. Theme changes broadcast `WM_SETTINGCHANGE` to every window and have wedged apps here: set a theme once, never in a loop, and `-Refresh full` additionally perturbs per-user parameters. Never use `AttachThreadInput` for activation: it couples input queues and has hung the host terminal here.
89 86 ## Tests
91 -`mise run win32-drive-test` (from the dotfiles root) drives a fixture window and asserts real effects. It takes over mouse, keyboard, and clipboard for about a minute; never run it while the user is working. Theme writes are skipped unless the script is invoked directly with `-IncludeTheme`.
88 +`mise run win32-drive-test` (from the dotfiles root) drives a fixture window and asserts real effects. It takes over mouse, keyboard, and clipboard for about a minute; never run it while the user is working. Theme writes need `-IncludeTheme` on a direct invocation.

pi/agent/skills/win32-drive/scripts/win32-drive.ps1

Modified
20 20 $ErrorActionPreference = 'Stop'
21 -Add-Type -AssemblyName System.Drawing,System.Windows.Forms
22 -Add-Type @"
21 +$script:win32DriveStart = [Diagnostics.Stopwatch]::StartNew()
23 +# Assemblies are loaded on demand: list/focus/window/uia never pay for WinForms.
24 +function Import-Drawing {
25 + if (-not $script:win32DriveDrawing) { Add-Type -AssemblyName System.Drawing; $script:win32DriveDrawing = $true }
28 +function Import-Forms {
29 + if (-not $script:win32DriveForms) { Import-Drawing; Add-Type -AssemblyName System.Windows.Forms; $script:win32DriveForms = $true }
32 +$script:win32DriveNativeSource = @"
23 33 using System;
24 34 using System.Text;
25 35 using System.Runtime.InteropServices;
52 62 [DllImport("user32.dll", CharSet=CharSet.Unicode, SetLastError=true, EntryPoint="SendMessageTimeoutW")] public static extern IntPtr SendMessageTimeoutPtr(IntPtr hWnd, uint msg, UIntPtr wParam, IntPtr lParam, uint flags, uint timeout, out UIntPtr result);
53 63 [DllImport("user32.dll", CharSet=CharSet.Unicode, SetLastError=true, EntryPoint="SendMessageTimeoutW")] public static extern IntPtr SendMessageTimeoutText(IntPtr hWnd, uint msg, UIntPtr wParam, StringBuilder lParam, uint flags, uint timeout, out UIntPtr result);
54 64 [DllImport("kernel32.dll")] public static extern uint GetTickCount();
55 - [DllImport("user32.dll")] public static extern IntPtr GetForegroundWindow();
56 65 [DllImport("user32.dll")] public static extern bool IsIconic(IntPtr hWnd);
66 + [DllImport("user32.dll")] public static extern IntPtr GetForegroundWindow();
57 67 [DllImport("user32.dll", SetLastError=true)] public static extern bool SetProcessDpiAwarenessContext(IntPtr value);
58 68 [DllImport("shcore.dll")] public static extern int SetProcessDpiAwareness(int value);
59 69 [DllImport("user32.dll")] public static extern bool SetProcessDPIAware();
172 +# Compiling this P/Invoke surface costs about a second and spawns csc.exe, which
173 +# flashes a console window. Cache the assembly per source hash and reuse it.
174 +function Import-Native([string] $Source) {
175 + if ('Win32DriveNative' -as [type]) { return 'loaded' }
176 + $sha = [Security.Cryptography.SHA256]::Create()
177 + try {
178 + $hash = ([BitConverter]::ToString($sha.ComputeHash([Text.Encoding]::UTF8.GetBytes($Source))) -replace '-', '').Substring(0, 16)
179 + } finally { $sha.Dispose() }
180 + $dir = Join-Path $env:LOCALAPPDATA 'win32-drive'
181 + $dll = Join-Path $dir "Win32DriveNative-$hash.dll"
182 + if (Test-Path $dll) {
183 + try {
184 + Add-Type -Path $dll
185 + return 'cache'
186 + } catch {}
188 + if (-not (Test-Path $dir)) { New-Item -ItemType Directory -Force -Path $dir | Out-Null }
189 + $staging = Join-Path $dir ('build-' + [guid]::NewGuid().ToString('N') + '.dll')
190 + Add-Type -TypeDefinition $Source -OutputAssembly $staging -OutputType Library
191 + try { Move-Item -LiteralPath $staging -Destination $dll -Force } catch { Remove-Item -LiteralPath $staging -Force -ErrorAction SilentlyContinue }
192 + if (Test-Path $dll) { Add-Type -Path $dll } else { Add-Type -TypeDefinition $Source }
193 + 'compiled'
196 +$script:win32DriveNativeLoad = Import-Native $script:win32DriveNativeSource
162 198 function Set-DpiAwareness {
163 199 try { if ([Win32DriveNative]::SetProcessDpiAwarenessContext([IntPtr] (-4))) { return 'per-monitor-v2' } } catch {}
164 200 try { if ([Win32DriveNative]::SetProcessDpiAwareness(2) -eq 0) { return 'per-monitor' } } catch {}
172 208 $Value | ConvertTo-Json -Depth 24 -Compress
211 +# Errors carry a stable code, a hint, and whatever context saves the agent a
212 +# follow-up query (candidate windows, foreground state, idle time).
213 +function Fail([string] $Code, [string] $Message, [string] $Hint, $Extra) {
214 + $payload = [ordered] @{ ok = $false; error = $Message; code = $Code }
215 + if ($Hint) { $payload['hint'] = $Hint }
216 + if ($Extra) { foreach ($key in $Extra.Keys) { $payload[$key] = $Extra[$key] } }
217 + $script:win32DriveFailure = $payload
218 + throw $Message
221 +function Get-FailurePayload([string] $Name, $ErrorRecord) {
222 + $message = $ErrorRecord.Exception.Message
223 + $payload = if ($script:win32DriveFailure -and $script:win32DriveFailure['error'] -eq $message) {
224 + $script:win32DriveFailure
225 + } else {
226 + [ordered] @{ ok = $false; error = $message; code = 'unexpected' }
228 + $script:win32DriveFailure = $null
229 + $payload['cmd'] = $Name
230 + [pscustomobject] $payload
233 +$script:win32DriveValueOptions = @('Hwnd','Process','TitleContains','X','Y','Width','Height','Out','Text','Keys','Action','Button','Count','DurationMs','IdleMs','TimeoutMs','CountdownMs','Set','Depth','Mode','Scope','Focus','Cursor','Return','Refresh','Method','Name','AutomationId','ClassName','ControlType','Index','Value','Json','File')
234 +$script:win32DriveFlagOptions = @('Pointer','ContinueOnError','NoCountdown')
175 236 function Parse-Options([string[]] $ArgList) {
176 237 $opts = @{}
177 238 $pos = @()
178 - $valueOptions = @('Hwnd','Process','TitleContains','X','Y','Width','Height','Out','Text','Keys','Action','Button','Count','DurationMs','IdleMs','TimeoutMs','Set','Depth','Mode','Scope','Focus','Cursor','Refresh','Method','Name','AutomationId','ClassName','ControlType','Index','Value')
179 - $flagOptions = @('Pointer')
180 239 for ($i = 0; $i -lt $ArgList.Count; $i++) {
181 240 $arg = $ArgList[$i]
182 241 if ($arg.StartsWith('-')) {
183 242 $key = $arg.TrimStart('-')
184 - if ($flagOptions -contains $key) { $opts[$key] = $true; continue }
185 - if ($valueOptions -notcontains $key) { throw "Unknown option: -$key" }
186 - if ($i + 1 -ge $ArgList.Count) { throw "Missing value for -$key" }
243 + if ($script:win32DriveFlagOptions -contains $key) { $opts[$key] = $true; continue }
244 + if ($script:win32DriveValueOptions -notcontains $key) {
245 + Fail 'unknown-option' "Unknown option: -$key" 'run help for the option catalog' @{ knownOptions = @($script:win32DriveValueOptions + $script:win32DriveFlagOptions) }
247 + if ($i + 1 -ge $ArgList.Count) { Fail 'missing-value' "Missing value for -$key" "pass a value after -$key" }
188 249 $opts[$key] = $ArgList[$i]
189 250 } else {
190 251 $pos += $arg
193 - if ($pos.Count -gt 0) { throw ('Unexpected positional args: ' + ($pos -join ' ')) }
254 + if ($pos.Count -gt 0) { Fail 'positional-args' ('Unexpected positional args: ' + ($pos -join ' ')) 'every input is a named option, for example -Text hello' }
209 270 [string] $Opts[$Name]
273 +function Get-ProcessNames {
274 + if ($null -ne $script:win32DriveProcessNames) { return $script:win32DriveProcessNames }
275 + $map = @{}
276 + foreach ($proc in (Get-Process -ErrorAction SilentlyContinue)) { $map[[int64] $proc.Id] = $proc.ProcessName }
277 + $script:win32DriveProcessNames = $map
278 + $map
212 281 function Get-Windows {
213 282 $script:win32DriveWindows = @()
283 + $script:win32DriveForeground = [Win32DriveNative]::GetForegroundWindow()
284 + $names = Get-ProcessNames
214 285 [Win32DriveNative]::EnumWindows({ param($h, $l)
215 286 if ([Win32DriveNative]::IsWindowVisible($h)) {
216 287 $sb = [Text.StringBuilder]::new(1024)
219 290 if ($title.Trim().Length -gt 0) {
220 291 [uint32] $procId = 0
221 292 [void] [Win32DriveNative]::GetWindowThreadProcessId($h, [ref] $procId)
222 - $proc = Get-Process -Id $procId -ErrorAction SilentlyContinue
223 293 $rect = Get-Rect $h
224 294 $script:win32DriveWindows += [pscustomobject] [ordered] @{
225 295 hwnd = $h.ToInt64()
226 296 pid = [int64] $procId
227 - process = if ($proc) { $proc.ProcessName } else { $null }
297 + process = $names[[int64] $procId]
228 298 title = $title
229 299 x = $rect.Left
230 300 y = $rect.Top
231 301 width = $rect.Right - $rect.Left
232 302 height = $rect.Bottom - $rect.Top
303 + z = $script:win32DriveWindows.Count
304 + minimized = [bool] [Win32DriveNative]::IsIconic($h)
305 + focused = $h -eq $script:win32DriveForeground
259 332 function Get-FocusMode($Opts) {
260 333 $focus = (Str-Opt $Opts 'Focus' 'require').ToLowerInvariant()
261 - if (@('auto','require','skip') -notcontains $focus) { throw 'Focus must be auto, require, or skip' }
262 - if ($focus -eq 'auto' -and -not $Opts.ContainsKey('Pointer')) { throw 'Focus auto falls back to clicking the target caption: pass -Pointer to allow pointer input' }
334 + if (@('auto','require','skip') -notcontains $focus) { Fail 'invalid-value' 'Focus must be auto, require, or skip' 'require uses activation APIs only, auto adds a caption click, skip does not focus' }
335 + if ($focus -eq 'auto' -and -not $Opts.ContainsKey('Pointer')) {
336 + Fail 'pointer-consent' 'Focus auto falls back to clicking the target caption' 'ask the user first, then pass -Pointer'
263 338 $focus
273 348 $title = $sb.ToString()
274 349 [void] [Win32DriveNative]::GetWindowThreadProcessId($h, [ref] $procId)
276 - $proc = Get-Process -Id $procId -ErrorAction SilentlyContinue
351 + $proc = (Get-ProcessNames)[[int64] $procId]
277 352 $hung = $false
278 353 try { $hung = [bool] [Win32DriveNative]::IsHungAppWindow($h) } catch {}
279 354 [pscustomobject] [ordered] @{
280 355 hwnd = $h.ToInt64()
281 356 pid = [int64] $procId
282 - process = if ($proc) { $proc.ProcessName } else { $null }
357 + process = $proc
283 358 title = $title
284 359 hung = $hung
313 388 function Set-Foreground([IntPtr] $Hwnd, [string] $Mode = 'auto', [int] $TimeoutMs = 2500) {
314 - if ([Win32DriveNative]::IsIconic($Hwnd)) { throw ('Target window is minimized; run: window -Hwnd ' + $Hwnd.ToInt64() + ' -Action restore') }
389 + if ([Win32DriveNative]::IsIconic($Hwnd)) {
390 + Fail 'window-minimized' 'Target window is minimized' ('restore it first: window -Hwnd ' + $Hwnd.ToInt64() + ' -Action restore') @{ hwnd = $Hwnd.ToInt64() }
315 392 $deadline = (Get-Date).AddMilliseconds($TimeoutMs)
317 394 # Windows denies activation to background processes while the user is
325 402 if ($Mode -eq 'auto' -and (Invoke-CaptionClick $Hwnd)) { return }
326 403 $fg = Get-ForegroundInfo
327 404 $reason = if ($fg.hung) { 'the current foreground window is not responding' } elseif ((Get-IdleMs) -lt 500) { 'the user is still providing input' } else { 'foreground lock' }
328 - $diagnostics = [ordered] @{ lockTimeoutMs = [int64] [Win32DriveNative]::GetForegroundLockTimeout(); idleMs = Get-IdleMs }
329 - throw ('Could not focus target window ' + $Hwnd.ToInt64() + ' (' + $reason + '); foreground is ' + ($fg | ConvertTo-Json -Compress) + '; ' + ($diagnostics | ConvertTo-Json -Compress))
405 + $hint = if ($fg.hung) {
406 + 'nothing can be driven until that window recovers'
407 + } elseif ($Mode -eq 'require') {
408 + 'ask the user, then retry with -Focus auto -Pointer, which clicks the target caption'
409 + } else {
410 + 'retry when the user is idle, or drive the app with uia-invoke/uia-set instead'
412 + Fail 'focus-denied' ('Could not focus target window ' + $Hwnd.ToInt64() + ': ' + $reason) $hint @{
413 + hwnd = $Hwnd.ToInt64()
414 + foreground = $fg
415 + lockTimeoutMs = [int64] [Win32DriveNative]::GetForegroundLockTimeout()
416 + idleMs = Get-IdleMs
417 + focusMode = $Mode
421 +function Select-Windows($Opts) {
422 + $wins = @(Get-Windows)
423 + $proc = Str-Opt $Opts 'Process'
424 + $title = Str-Opt $Opts 'TitleContains'
425 + if ($Opts.ContainsKey('Hwnd')) {
426 + $wanted = Long-Opt $Opts 'Hwnd'
427 + $wins = @($wins | Where-Object { $_.hwnd -eq $wanted })
429 + if ($proc) { $wins = @($wins | Where-Object { $_.process -eq $proc }) }
430 + if ($title) { $wins = @($wins | Where-Object { $_.title.IndexOf($title, [StringComparison]::OrdinalIgnoreCase) -ge 0 }) }
431 + $wins
434 +function Get-WindowInfo([IntPtr] $Hwnd) {
435 + @(Get-Windows) | Where-Object { $_.hwnd -eq $Hwnd.ToInt64() } | Select-Object -First 1
332 438 function Resolve-Window($Opts) {
333 439 if ($Opts.ContainsKey('Hwnd')) {
334 440 $hwnd = [IntPtr] (Long-Opt $Opts 'Hwnd')
335 - if (-not [Win32DriveNative]::IsWindow($hwnd)) { throw 'Invalid window handle' }
441 + if (-not [Win32DriveNative]::IsWindow($hwnd)) {
442 + Fail 'stale-window' 'Invalid window handle' 'the window closed or the handle is wrong: run list again' @{ hwnd = $hwnd.ToInt64() }
336 444 return $hwnd
338 - $wins = @(Get-Windows)
339 - $proc = Str-Opt $Opts 'Process'
340 - $title = Str-Opt $Opts 'TitleContains'
341 - if ($proc) { $wins = @($wins | Where-Object { $_.process -eq $proc }) }
342 - if ($title) { $wins = @($wins | Where-Object { $_.title.IndexOf($title, [StringComparison]::OrdinalIgnoreCase) -ge 0 }) }
343 - if ($wins.Count -eq 0) { throw 'No matching window' }
344 - if ($wins.Count -gt 1) { throw ('Ambiguous window: ' + (($wins | Select-Object -First 8 hwnd,process,title) | ConvertTo-Json -Compress)) }
446 + $wins = @(Select-Windows $Opts)
447 + if ($wins.Count -eq 0) {
448 + $proc = Str-Opt $Opts 'Process'
449 + $candidates = if ($proc) {
450 + @(Get-Windows | Where-Object { $_.process -like "*$proc*" } | Select-Object -First 8)
451 + } else {
452 + @(Get-Windows | Select-Object -First 8)
454 + Fail 'no-window' 'No matching window' 'relax the selector; candidates lists what is open right now' @{ candidates = $candidates }
456 + if ($wins.Count -gt 1) {
457 + Fail 'ambiguous-window' ('Ambiguous window: ' + $wins.Count + ' matches') 'pick one -Hwnd from candidates' @{ candidates = @($wins | Select-Object -First 8) }
345 459 [IntPtr] $wins[0].hwnd
355 469 function Wait-UserIdle([int] $IdleMs, [int] $TimeoutMs) {
356 470 $start = Get-Date
357 471 while ((Get-IdleMs) -lt $IdleMs) {
358 - if (((Get-Date) - $start).TotalMilliseconds -gt $TimeoutMs) { throw "User not idle for $IdleMs ms" }
472 + if (((Get-Date) - $start).TotalMilliseconds -gt $TimeoutMs) {
473 + Fail 'user-active' "User not idle for $IdleMs ms" 'the human is using the machine: retry later, raise -TimeoutMs, or use a background command' @{ idleMs = Get-IdleMs; requiredIdleMs = $IdleMs }
359 475 Start-Sleep -Milliseconds 100
363 -function Draw-Indicator($X = $null, $Y = $null, [int] $DurationMs = 180) {
479 +# One overlay renderer: quick flash for background commands, banner plus
480 +# countdown for foreground takeovers, which the human can veto by touching
481 +# keyboard or mouse.
482 +function Show-Overlay($X = $null, $Y = $null, [string] $Banner = $null, [int] $DurationMs = 180, [bool] $AbortOnInput = $false) {
483 + Import-Forms
484 + $state = [pscustomobject] @{ Banner = $Banner; Remaining = $DurationMs }
485 + $bannerScreen = if ($null -ne $X -and $null -ne $Y) {
486 + [Windows.Forms.Screen]::FromPoint([Drawing.Point]::new([int] $X, [int] $Y))
487 + } else {
488 + [Windows.Forms.Screen]::PrimaryScreen
364 490 $forms = @()
365 491 foreach ($screen in [Windows.Forms.Screen]::AllScreens) {
366 492 $b = $screen.Bounds
367 493 $targetX = $X
368 494 $targetY = $Y
495 + $showBanner = $Banner -and $screen.DeviceName -eq $bannerScreen.DeviceName
369 496 $form = New-Object Windows.Forms.Form
370 497 $form.FormBorderStyle = 'None'
371 498 $form.StartPosition = 'Manual'
386 513 $localY = [int]$targetY - $b.Top
387 514 $event.Graphics.DrawEllipse($pen, $localX - 24, $localY - 24, 48, 48)
516 + if ($showBanner) {
517 + $text = $state.Banner
518 + if ($state.Remaining -gt 0) {
519 + $text = $text + "`nacting in " + [Math]::Max(0, [Math]::Round($state.Remaining / 1000.0, 1)) + 's - touch keyboard or mouse to cancel'
521 + $font = New-Object Drawing.Font 'Segoe UI', 20, ([Drawing.FontStyle]::Bold)
522 + $back = New-Object Drawing.SolidBrush ([Drawing.Color]::FromArgb(235, 20, 0, 0))
523 + $fore = New-Object Drawing.SolidBrush ([Drawing.Color]::White)
524 + try {
525 + $size = $event.Graphics.MeasureString($text, $font)
526 + $boxWidth = $size.Width + 48
527 + $boxHeight = $size.Height + 28
528 + $boxX = ($sender.Width - $boxWidth) / 2
529 + $boxY = 48
530 + $event.Graphics.FillRectangle($back, $boxX, $boxY, $boxWidth, $boxHeight)
531 + $event.Graphics.DrawRectangle($pen, $boxX, $boxY, $boxWidth, $boxHeight)
532 + $event.Graphics.DrawString($text, $font, $fore, $boxX + 24, $boxY + 14)
533 + } finally {
534 + $font.Dispose(); $back.Dispose(); $fore.Dispose()
389 537 } finally {
390 538 $pen.Dispose()
401 549 [Windows.Forms.Application]::DoEvents()
402 550 Start-Sleep -Milliseconds 20
404 - if ($DurationMs -gt 0) { Start-Sleep -Milliseconds $DurationMs }
552 + $completed = $true
553 + if ($DurationMs -gt 0) {
554 + $deadline = (Get-Date).AddMilliseconds($DurationMs)
555 + while ($true) {
556 + $remaining = ($deadline - (Get-Date)).TotalMilliseconds
557 + if ($remaining -le 0) { break }
558 + $state.Remaining = [int] $remaining
559 + if ($Banner) { foreach ($form in $forms) { $form.Invalidate() } }
560 + [Windows.Forms.Application]::DoEvents()
561 + Start-Sleep -Milliseconds 50
562 + if ($AbortOnInput -and (Get-IdleMs) -lt 150) { $completed = $false; break }
405 565 foreach ($opacity in 0.7,0.45,0.2,0.0) {
406 566 foreach ($form in $forms) { $form.Opacity = $opacity }
407 567 [Windows.Forms.Application]::DoEvents()
410 570 foreach ($form in $forms) { $form.Close(); $form.Dispose() }
411 571 [Windows.Forms.Application]::DoEvents()
572 + $completed
575 +function Draw-Indicator($X = $null, $Y = $null, [int] $DurationMs = 180) {
576 + [void] (Show-Overlay $X $Y $null $DurationMs $false)
579 +# Background commands: wait for an input gap, flash once, act.
414 580 function Invoke-RacingGuard($Opts, $X = $null, $Y = $null) {
415 581 $idle = Int-Opt $Opts 'IdleMs' 800
416 582 $timeout = Int-Opt $Opts 'TimeoutMs' 10000
418 584 Draw-Indicator $X $Y 120
587 +# Foreground/pointer commands: same wait, then a named banner with a countdown
588 +# the human can veto.
589 +function Invoke-Takeover($Opts, [string] $Label, $X = $null, $Y = $null) {
590 + $idle = Int-Opt $Opts 'IdleMs' 800
591 + $timeout = Int-Opt $Opts 'TimeoutMs' 10000
592 + Wait-UserIdle $idle $timeout
593 + $countdown = if ($Opts.ContainsKey('NoCountdown')) { 0 } else { Int-Opt $Opts 'CountdownMs' 1200 }
594 + if (-not (Show-Overlay $X $Y $Label $countdown $true)) {
595 + Fail 'takeover-aborted' 'Foreground takeover cancelled by user input' 'the human took the machine back mid-countdown: ask before retrying' @{ label = $Label }
421 599 function Theme-Name($Value) {
422 600 if ([int]$Value -eq 0) { 'dark' } else { 'light' }
484 662 function Get-PixelColor([int] $X, [int] $Y) {
663 + Import-Drawing
485 664 $bmp = [Drawing.Bitmap]::new(1, 1)
486 665 $g = [Drawing.Graphics]::FromImage($bmp)
496 675 function Capture-Region([int] $X, [int] $Y, [int] $Width, [int] $Height, [string] $Out) {
676 + Import-Drawing
497 677 $bmp = [Drawing.Bitmap]::new($Width, $Height)
498 678 $g = [Drawing.Graphics]::FromImage($bmp)
521 701 function Capture-Window([IntPtr] $Hwnd, [string] $Out) {
702 + Import-Drawing
522 703 $frame = Get-Rect $Hwnd
523 704 $raw = Get-RawRect $Hwnd
524 705 $w = $frame.Right - $frame.Left
639 820 $root = if (Has-Selector $Opts) {
640 821 [Windows.Automation.AutomationElement]::FromHandle((Resolve-Window $Opts))
641 822 } else {
642 - throw 'element commands need a window selector: -Hwnd, -Process, or -TitleContains'
823 + Fail 'missing-selector' 'element commands need a window selector' 'pass -Hwnd, -Process, or -TitleContains; list shows all windows'
644 825 if (-not ($Opts.ContainsKey('Name') -or $Opts.ContainsKey('AutomationId') -or $Opts.ContainsKey('ClassName') -or $Opts.ContainsKey('ControlType'))) {
645 - throw 'element commands need -Name, -AutomationId, -ClassName, or -ControlType'
826 + Fail 'missing-filter' 'element commands need -Name, -AutomationId, -ClassName, or -ControlType' 'read the tree with uia first, then address the element; filters accept wildcards'
647 828 # ControlType narrows the tree walk; the string filters are wildcards, because
648 829 # bridged providers generate volatile class names and automation ids.
658 839 $property = $filter[1]
659 840 $found = @($found | Where-Object { [string] $_.Current.$property -like $pattern })
661 - if ($found.Count -eq 0) { throw 'No matching element' }
842 + if ($found.Count -eq 0) {
843 + $sample = @($root.FindAll([Windows.Automation.TreeScope]::Children, [Windows.Automation.Condition]::TrueCondition) | Select-Object -First 8 | ForEach-Object { Describe-UiaElement $_ })
844 + Fail 'no-element' 'No matching element' 'filters are wildcards against the uia tree; candidates lists the direct children' @{ candidates = $sample }
662 846 if ($Opts.ContainsKey('Index')) {
663 847 $index = Int-Opt $Opts 'Index'
664 - if ($index -lt 0 -or $index -ge $found.Count) { throw ('Index out of range: ' + $found.Count + ' matching elements') }
848 + if ($index -lt 0 -or $index -ge $found.Count) {
849 + Fail 'index-out-of-range' ('Index out of range: ' + $found.Count + ' matching elements') 'use an index between 0 and matches-1' @{ matches = $found.Count }
665 851 return $found[$index]
667 853 if ($found.Count -gt 1) {
668 - $preview = @($found | Select-Object -First 8 | ForEach-Object { Describe-UiaElement $_ })
669 - throw ('Ambiguous element, pass -Index: ' + ($preview | ConvertTo-Json -Compress))
854 + Fail 'ambiguous-element' ('Ambiguous element: ' + $found.Count + ' matches') 'narrow the filters or pass -Index' @{ candidates = @($found | Select-Object -First 8 | ForEach-Object { Describe-UiaElement $_ }) }
671 856 $found[0]
692 877 return 'BM_CLICK'
695 - throw 'Element supports no invokable pattern; use click -Pointer instead'
880 + Fail 'no-pattern' 'Element supports no invokable pattern' 'this app exposes no usable accessibility action: ask the user, then use click -Pointer' @{ element = (Describe-UiaElement $Element) }
698 883 function Set-UiaElementValue($Element, [string] $Value) {
705 890 $native = Get-UiaNativeHandle $Element
706 891 if ($native -ne [IntPtr]::Zero -and (Send-WindowText $native $Value)) { return 'WM_CHAR' }
707 - throw 'Element exposes no value pattern; use type -Pointer instead'
892 + Fail 'no-pattern' 'Element exposes no settable value' 'ask the user, then focus it and use type -Pointer' @{ element = (Describe-UiaElement $Element) }
710 895 # Posted characters reach a native edit control without focus and still raise
780 965 $out.ToString()
968 +function Get-ReturnMode($Opts) {
969 + $mode = (Str-Opt $Opts 'Return' 'restore').ToLowerInvariant()
970 + if (@('restore','keep') -notcontains $mode) { Fail 'invalid-value' 'Return must be restore or keep' 'restore puts the human back in their window when the action is done' }
971 + $mode
974 +function Format-TakeoverLabel([string] $Action, $Target, $X = $null, $Y = $null) {
975 + $where = if ($Target) {
976 + $title = [string] $Target.title
977 + if ($title.Length -gt 60) { $title = $title.Substring(0, 57) + '...' }
978 + $Target.process + ': ' + $title
979 + } elseif ($null -ne $X) {
980 + "screen $X,$Y"
981 + } else {
982 + 'the focused window'
984 + 'win32-drive ' + $Action + ' -> ' + $where
987 +function Restore-Foreground($Previous, [string] $Mode) {
988 + if ($Mode -ne 'restore' -or $null -eq $Previous -or $Previous.hwnd -eq 0) { return $null }
989 + $handle = [IntPtr] $Previous.hwnd
990 + if ([Win32DriveNative]::GetForegroundWindow() -eq $handle) { return $Previous.hwnd }
991 + if (-not [Win32DriveNative]::IsWindow($handle)) { return $null }
992 + if ([Win32DriveNative]::Foreground($handle, 400) -or [Win32DriveNative]::ForegroundUnlocked($handle, 400)) { return $Previous.hwnd }
993 + $null
996 +# One process start costs more than every action in it, so a whole interaction
997 +# can be sent as an ordered step list with pauses between steps.
998 +function Invoke-Batch($Opts) {
999 + $json = if ($Opts.ContainsKey('Json')) { Str-Opt $Opts 'Json' }
1000 + elseif ($Opts.ContainsKey('File')) { Get-Content -Raw -LiteralPath (Str-Opt $Opts 'File') }
1001 + else { [Console]::In.ReadToEnd() }
1002 + if (-not $json -or $json.Trim().Length -eq 0) {
1003 + Fail 'batch-empty' 'batch needs steps' 'pass -Json, -File, or pipe JSON on stdin: [{"cmd":"list"},{"cmd":"wait","ms":300}]'
1005 + # Assigning first matters: @(ConvertFrom-Json ...) wraps the whole array in one element.
1006 + try {
1007 + $parsed = ConvertFrom-Json $json
1008 + } catch {
1009 + Fail 'batch-invalid-json' ('Batch steps are not valid JSON: ' + $_.Exception.Message) 'shells mangle embedded quotes: prefer -File steps.json or pipe the JSON on stdin' @{ received = $json.Substring(0, [Math]::Min(200, $json.Length)) }
1011 + $steps = @($parsed)
1012 + $continueOnError = $Opts.ContainsKey('ContinueOnError')
1013 + $results = @()
1014 + $failedAt = $null
1015 + for ($index = 0; $index -lt $steps.Count; $index++) {
1016 + $step = $steps[$index]
1017 + $name = [string] $step.cmd
1018 + $stepOpts = @{}
1019 + foreach ($property in $step.PSObject.Properties) {
1020 + if ($property.Name -in @('cmd','ms')) { continue }
1021 + if ($property.Value -is [bool]) {
1022 + if ($property.Value) { $stepOpts[$property.Name] = $true }
1023 + continue
1025 + if ($script:win32DriveValueOptions -notcontains $property.Name -and $script:win32DriveFlagOptions -notcontains $property.Name) {
1026 + Fail 'unknown-option' ("Unknown option in step " + $index + ": " + $property.Name) 'steps use the same option names as the command line'
1028 + $stepOpts[$property.Name] = [string] $property.Value
1030 + $stepWatch = [Diagnostics.Stopwatch]::StartNew()
1031 + try {
1032 + $payload = if ($name -eq 'wait') {
1033 + $ms = if ($null -ne $step.ms) { [int] $step.ms } else { 250 }
1034 + Start-Sleep -Milliseconds $ms
1035 + [pscustomobject] [ordered] @{ ok = $true; waitedMs = $ms }
1036 + } else {
1037 + Invoke-DriveCommand $name $stepOpts
1039 + $results += (Add-Envelope $name $payload $index $stepWatch)
1040 + } catch {
1041 + $results += (Add-Envelope $name (Get-FailurePayload $name $_) $index $stepWatch)
1042 + $failedAt = $index
1043 + if (-not $continueOnError) { break }
1046 + [pscustomobject] [ordered] @{
1047 + ok = ($null -eq $failedAt)
1048 + steps = $steps.Count
1049 + ran = $results.Count
1050 + failedAt = $failedAt
1051 + results = $results
1055 +function Add-Envelope([string] $Name, $Payload, $Step = $null, $Watch = $null) {
1056 + $elapsed = if ($Watch) { [int] $Watch.ElapsedMilliseconds } else { [int] $script:win32DriveStart.ElapsedMilliseconds }
1057 + $result = $Payload | Add-Member -PassThru -NotePropertyName cmd -NotePropertyValue $Name -Force
1058 + $result = $result | Add-Member -PassThru -NotePropertyName elapsedMs -NotePropertyValue $elapsed -Force
1059 + if ($null -ne $Step) { $result = $result | Add-Member -PassThru -NotePropertyName step -NotePropertyValue $Step -Force }
1060 + $result
783 1063 function Show-Help {
784 1064 [pscustomobject] [ordered] @{
785 1065 ok = $true
786 1066 runtime = 'Windows PowerShell 5.1+'
787 1067 dpiAwareness = $script:win32DriveDpi
1068 + nativeLoad = $script:win32DriveNativeLoad
1069 + speed = 'process start dominates: send one batch of steps instead of many invocations; every result carries cmd and elapsedMs'
1070 + errors = 'failures are JSON with code, hint, and context: candidates for no-window/ambiguous-window/no-element, foreground plus lockTimeoutMs plus idleMs for focus-denied'
1071 + takeover = 'pointer and focus commands show a named banner with a countdown; user input during the countdown aborts with code takeover-aborted'
788 1072 coordinates = 'screen pixels; with a window selector, click -X/-Y are relative to the DWM frame bounds reported by list and shot'
789 1073 racingGuard = 'racing commands fade a 16px red border/ring, wait for user idle, then act'
790 1074 focus = 'uia-invoke and uia-set act without focus, pointer, or keyboard; click/type/key focus the target after the racing guard and verify it, where require uses activation APIs only, auto adds a caption click and needs -Pointer, and skip does not focus'
792 1076 globalOptions = '-IdleMs n (default 800) and -TimeoutMs n (default 10000) tune the racing guard'
793 1077 commands = [ordered] @{
794 1078 help = [ordered] @{ racing = $false; usage = 'help' }
795 - list = [ordered] @{ racing = $false; usage = 'list' }
1079 + batch = [ordered] @{ racing = $null; usage = 'batch -File steps.json | batch (JSON on stdin) | batch -Json ''[{"cmd":"list"},{"cmd":"wait","ms":300}]'' [-ContinueOnError]' }
1080 + list = [ordered] @{ racing = $false; usage = 'list [-Hwnd n|-Process p|-TitleContains t]' }
796 1081 shot = [ordered] @{ racing = $false; usage = 'shot [-Hwnd n|-Process p -TitleContains t|-X x -Y y -Width w -Height h] [-Out file.png]' }
797 1082 pixel = [ordered] @{ racing = $false; usage = 'pixel -X x -Y y' }
798 1083 uia = [ordered] @{ racing = $false; usage = 'uia [-Hwnd n|-Process p|-TitleContains t] [-Depth n]' }
803 1088 idle = [ordered] @{ racing = $false; usage = 'idle' }
804 1089 clipboard = [ordered] @{ racing = $null; usage = 'clipboard | clipboard -Set text' }
805 1090 theme = [ordered] @{ racing = $true; usage = 'theme | theme -Mode dark|light [-Scope apps|system|both] [-Refresh broadcast|full]' }
806 - overlay = [ordered] @{ racing = $false; usage = 'overlay [-X x -Y y] [-DurationMs ms]' }
807 - click = [ordered] @{ racing = $true; usage = 'click [-Hwnd n|-Process p|-TitleContains t] [-X x -Y y] [-Button left|right] [-Count n] [-Focus auto|require|skip] [-Cursor restore|keep]' }
808 - type = [ordered] @{ racing = $true; usage = 'type [-Hwnd n|-Process p|-TitleContains t] -Text text [-Focus auto|require|skip] [-Method unicode|sendkeys]' }
809 - key = [ordered] @{ racing = $true; usage = 'key [-Hwnd n|-Process p|-TitleContains t] -Keys "^s" [-Focus auto|require|skip]' }
1091 + overlay = [ordered] @{ racing = $false; usage = 'overlay [-X x -Y y] [-Text banner] [-DurationMs ms]' }
1092 + click = [ordered] @{ racing = $true; takeover = $true; usage = 'click -Pointer [-Hwnd n|-Process p|-TitleContains t] [-X x -Y y] [-Button left|right] [-Count n] [-Focus auto|require|skip] [-Cursor restore|keep] [-Return restore|keep] [-CountdownMs n|-NoCountdown]' }
1093 + type = [ordered] @{ racing = $true; takeover = $true; usage = 'type [-Hwnd n|-Process p|-TitleContains t] -Text text [-Focus auto|require|skip] [-Pointer] [-Method unicode|sendkeys] [-Return restore|keep] [-CountdownMs n|-NoCountdown]' }
1094 + key = [ordered] @{ racing = $true; takeover = $true; usage = 'key [-Hwnd n|-Process p|-TitleContains t] -Keys "^s" [-Focus auto|require|skip] [-Pointer] [-Return restore|keep] [-CountdownMs n|-NoCountdown]' }
810 1095 window = [ordered] @{ racing = $true; usage = 'window -Action move|min|max|restore|close [-Hwnd n|-Process p|-TitleContains t] [-X x -Y y -Width w -Height h]' }
815 -function Invoke-CommandImpl {
816 - $opts = Parse-Options $Rest
817 - switch ($Command.ToLowerInvariant()) {
1100 +function Invoke-DriveCommand([string] $Name, $Opts) {
1101 + $opts = $Opts
1102 + switch ($Name.ToLowerInvariant()) {
818 1103 'help' { return Show-Help }
819 - 'list' { return [pscustomobject] [ordered] @{ ok = $true; windows = @(Get-Windows) } }
1104 + 'list' {
1105 + $windows = if (Has-Selector $opts) { @(Select-Windows $opts) } else { @(Get-Windows) }
1106 + return [pscustomobject] [ordered] @{
1107 + ok = $true
1108 + count = $windows.Count
1109 + foreground = (Get-ForegroundInfo)
1110 + idleMs = Get-IdleMs
1111 + windows = $windows
820 1114 'idle' { return [pscustomobject] [ordered] @{ ok = $true; idleMs = Get-IdleMs } }
821 1115 'focus' { return (Get-ForegroundInfo) | Add-Member -PassThru -NotePropertyName ok -NotePropertyValue $true }
822 1116 'cursor' {
825 1119 return [pscustomobject] [ordered] @{ ok = $true; x = $p.X; y = $p.Y }
827 1121 'overlay' {
828 - Draw-Indicator (Int-Opt $opts 'X') (Int-Opt $opts 'Y') (Int-Opt $opts 'DurationMs' 650)
829 - return [pscustomobject] [ordered] @{ ok = $true }
1122 + $banner = Str-Opt $opts 'Text'
1123 + $duration = Int-Opt $opts 'DurationMs' 650
1124 + $completed = Show-Overlay (Int-Opt $opts 'X') (Int-Opt $opts 'Y') $banner $duration ($opts.ContainsKey('Pointer') -eq $false -and $null -ne $banner)
1125 + return [pscustomobject] [ordered] @{ ok = $true; banner = $banner; durationMs = $duration; completed = $completed }
831 1127 'pixel' {
832 1128 $x = Int-Opt $opts 'X'
837 1133 'shot' {
838 1134 $out = Str-Opt $opts 'Out'
839 1135 if (Has-Selector $opts) { return Capture-Window (Resolve-Window $opts) $out }
1136 + Import-Forms
840 1137 $screen = [System.Windows.Forms.SystemInformation]::VirtualScreen
841 1138 $x = Int-Opt $opts 'X' $screen.Left
842 1139 $y = Int-Opt $opts 'Y' $screen.Top
870 1167 return [pscustomobject] [ordered] @{ ok = $true; tree = Dump-Uia $el 0 $depth }
872 1169 'clipboard' {
1170 + Import-Forms
873 1171 if ($opts.ContainsKey('Set')) {
874 1172 Invoke-RacingGuard $opts
875 1173 [Windows.Forms.Clipboard]::SetText((Str-Opt $opts 'Set'))
883 1181 return Set-Theme (Str-Opt $opts 'Mode') (Str-Opt $opts 'Scope' 'both') (Str-Opt $opts 'Refresh' 'broadcast')
885 1183 'click' {
886 - if (-not $opts.ContainsKey('Pointer')) { throw 'click injects pointer input: pass -Pointer to allow it, or use uia-invoke' }
1184 + if (-not $opts.ContainsKey('Pointer')) {
1185 + Fail 'pointer-consent' 'click injects pointer input' 'ask the user first, then pass -Pointer; uia-invoke acts without pointer or focus'
887 1187 $button = (Str-Opt $opts 'Button' 'left').ToLowerInvariant()
888 1188 $count = Int-Opt $opts 'Count' 1
889 1189 $focus = Get-FocusMode $opts
1190 + $returnMode = Get-ReturnMode $opts
890 1191 $cursorMode = (Str-Opt $opts 'Cursor' 'restore').ToLowerInvariant()
891 - if (@('restore','keep') -notcontains $cursorMode) { throw 'Cursor must be restore or keep' }
1192 + if (@('restore','keep') -notcontains $cursorMode) { Fail 'invalid-value' 'Cursor must be restore or keep' 'restore puts the pointer back where the human left it' }
892 1193 $x = Int-Opt $opts 'X'
893 1194 $y = Int-Opt $opts 'Y'
894 1195 $hwnd = $null
1196 + $target = $null
895 1197 if (Has-Selector $opts) {
896 1198 $hwnd = Resolve-Window $opts
1199 + $target = Get-WindowInfo $hwnd
897 1200 $r = Get-Rect $hwnd
898 1201 if ($x -eq $null) { $x = [int] (($r.Left + $r.Right) / 2) } else { $x = $r.Left + $x }
899 1202 if ($y -eq $null) { $y = [int] (($r.Top + $r.Bottom) / 2) } else { $y = $r.Top + $y }
901 - if ($x -eq $null -or $y -eq $null) { throw 'click needs -X and -Y unless targeting a window center' }
1204 + if ($x -eq $null -or $y -eq $null) { Fail 'missing-option' 'click needs -X and -Y unless targeting a window center' 'pass screen coordinates, or a window selector for a center click' }
902 1205 $origin = New-Object Win32DriveNative+POINT
903 1206 [void] [Win32DriveNative]::GetCursorPos([ref] $origin)
1207 + $previous = Get-ForegroundInfo
904 1208 # Focus after the guard: activation is only granted during input gaps.
905 - Invoke-RacingGuard $opts $x $y
1209 + Invoke-Takeover $opts (Format-TakeoverLabel "$button click" $target $x $y) $x $y
906 1210 if ($hwnd -ne $null -and $focus -ne 'skip') { Set-Foreground $hwnd $focus }
907 1211 Invoke-PointerClick $x $y $button $count $false
908 1212 if ($cursorMode -eq 'restore') { [void] [Win32DriveNative]::SetCursorPos($origin.X, $origin.Y) }
909 - return [pscustomobject] [ordered] @{ ok = $true; x = $x; y = $y; button = $button; count = $count; focus = $focus; cursor = $cursorMode; foreground = (Get-ForegroundInfo) }
1213 + $returnedTo = Restore-Foreground $previous $returnMode
1214 + return [pscustomobject] [ordered] @{
1215 + ok = $true
1216 + x = $x
1217 + y = $y
1218 + button = $button
1219 + count = $count
1220 + focus = $focus
1221 + cursor = $cursorMode
1222 + return = $returnMode
1223 + returnedTo = $returnedTo
1224 + target = $target
1225 + foreground = (Get-ForegroundInfo)
911 1228 'type' {
912 1229 $text = Str-Opt $opts 'Text'
913 - if ($null -eq $text) { throw 'type needs -Text' }
1230 + if ($null -eq $text) { Fail 'missing-option' 'type needs -Text' 'pass the literal text; newlines become Enter' }
914 1231 $focus = Get-FocusMode $opts
915 - $target = if (Has-Selector $opts) { Resolve-Window $opts } else { $null }
1232 + $returnMode = Get-ReturnMode $opts
1233 + $handle = if (Has-Selector $opts) { Resolve-Window $opts } else { $null }
1234 + $target = if ($handle) { Get-WindowInfo $handle } else { $null }
916 1235 $defaultMethod = if ([IntPtr]::Size -eq 8) { 'unicode' } else { 'sendkeys' }
917 1236 $method = (Str-Opt $opts 'Method' $defaultMethod).ToLowerInvariant()
918 - if (@('unicode','sendkeys') -notcontains $method) { throw 'Method must be unicode or sendkeys' }
919 - Invoke-RacingGuard $opts
920 - if ($target -ne $null -and $focus -ne 'skip') { Set-Foreground $target $focus }
1237 + if (@('unicode','sendkeys') -notcontains $method) { Fail 'invalid-value' 'Method must be unicode or sendkeys' 'unicode sends the text verbatim; sendkeys uses the legacy escaped syntax' }
1238 + $previous = Get-ForegroundInfo
1239 + Invoke-Takeover $opts (Format-TakeoverLabel 'type' $target)
1240 + if ($handle -ne $null -and $focus -ne 'skip') { Set-Foreground $handle $focus }
921 1241 if ($method -eq 'unicode') { [void] [Win32DriveNative]::TypeUnicode($text) }
922 - else { [Windows.Forms.SendKeys]::SendWait((Escape-SendKeysText $text)) }
923 - return [pscustomobject] [ordered] @{ ok = $true; chars = $text.Length; method = $method; focus = $focus; foreground = (Get-ForegroundInfo) }
1242 + else { Import-Forms; [Windows.Forms.SendKeys]::SendWait((Escape-SendKeysText $text)) }
1243 + $returnedTo = Restore-Foreground $previous $returnMode
1244 + return [pscustomobject] [ordered] @{
1245 + ok = $true
1246 + chars = $text.Length
1247 + method = $method
1248 + focus = $focus
1249 + return = $returnMode
1250 + returnedTo = $returnedTo
1251 + target = $target
1252 + foreground = (Get-ForegroundInfo)
925 1255 'key' {
926 1256 $keySpec = Str-Opt $opts 'Keys'
927 - if (-not $keySpec) { throw 'key needs -Keys' }
1257 + if (-not $keySpec) { Fail 'missing-option' 'key needs -Keys' 'SendKeys syntax, for example ^s or %{F4}' }
928 1258 $focus = Get-FocusMode $opts
929 - $target = if (Has-Selector $opts) { Resolve-Window $opts } else { $null }
930 - Invoke-RacingGuard $opts
931 - if ($target -ne $null -and $focus -ne 'skip') { Set-Foreground $target $focus }
1259 + $returnMode = Get-ReturnMode $opts
1260 + $handle = if (Has-Selector $opts) { Resolve-Window $opts } else { $null }
1261 + $target = if ($handle) { Get-WindowInfo $handle } else { $null }
1262 + $previous = Get-ForegroundInfo
1263 + Invoke-Takeover $opts (Format-TakeoverLabel "key $keySpec" $target)
1264 + if ($handle -ne $null -and $focus -ne 'skip') { Set-Foreground $handle $focus }
1265 + Import-Forms
932 1266 [Windows.Forms.SendKeys]::SendWait($keySpec)
933 - return [pscustomobject] [ordered] @{ ok = $true; keys = $keySpec; focus = $focus; foreground = (Get-ForegroundInfo) }
1267 + $returnedTo = Restore-Foreground $previous $returnMode
1268 + return [pscustomobject] [ordered] @{
1269 + ok = $true
1270 + keys = $keySpec
1271 + focus = $focus
1272 + return = $returnMode
1273 + returnedTo = $returnedTo
1274 + target = $target
1275 + foreground = (Get-ForegroundInfo)
935 1278 'window' {
936 1279 $action = (Str-Opt $opts 'Action').ToLowerInvariant()
937 - if (-not $action) { throw 'window needs -Action' }
1280 + if (-not $action) { Fail 'missing-option' 'window needs -Action' 'move, min, max, restore, or close' }
938 1281 $hwnd = Resolve-Window $opts
939 1282 Invoke-RacingGuard $opts
940 1283 switch ($action) {
950 1293 'max' { [void] [Win32DriveNative]::ShowWindow($hwnd, 3) }
951 1294 'restore' { [void] [Win32DriveNative]::ShowWindow($hwnd, 9) }
952 1295 'close' { [void] [Win32DriveNative]::PostMessage($hwnd, 0x0010, [IntPtr]::Zero, [IntPtr]::Zero) }
953 - default { throw "Unknown window action: $action" }
1296 + default { Fail 'invalid-value' "Unknown window action: $action" 'move, min, max, restore, or close' }
1298 + Start-Sleep -Milliseconds 120
1299 + return [pscustomobject] [ordered] @{
1300 + ok = $true
1301 + hwnd = $hwnd.ToInt64()
1302 + action = $action
1303 + window = (Get-WindowInfo $hwnd)
1304 + foreground = (Get-ForegroundInfo)
955 - return [pscustomobject] [ordered] @{ ok = $true; hwnd = $hwnd.ToInt64(); action = $action }
957 - default { throw "Unknown command: $Command" }
1307 + default {
1308 + Fail 'unknown-command' "Unknown command: $Name" 'run help for the command catalog' @{ commands = @((Show-Help).commands.Keys) }
962 - Write-Json (Invoke-CommandImpl)
1314 + $options = Parse-Options $Rest
1315 + $payload = if ($Command.ToLowerInvariant() -eq 'batch') { Invoke-Batch $options } else { Invoke-DriveCommand $Command $options }
1316 + Write-Json (Add-Envelope $Command $payload)
963 1317 exit 0
964 1318 } catch {
965 - Write-Json ([pscustomobject] [ordered] @{ ok = $false; error = $_.Exception.Message; command = $Command })
1319 + Write-Json (Add-Envelope $Command (Get-FailurePayload $Command $_))
966 1320 exit 1

pi/agent/skills/win32-drive/scripts/win32-drive.test.ps1

Modified
83 83 foreach ($cmd in 'list','shot','pixel','uia','cursor','focus','idle','overlay') { Assert ($help.commands.$cmd.racing -eq $false) "$cmd must be nonracing" }
84 84 Assert ($help.dpiAwareness -in @('per-monitor-v2','per-monitor','system','unaware')) 'help must report dpi awareness'
85 85 Assert ($help.dpiAwareness -ne 'unaware') 'process must be dpi aware'
86 + Assert ($help.nativeLoad -in @('cache','compiled','loaded')) 'help must report how the native assembly loaded'
87 + Assert ($help.cmd -eq 'help' -and $help.elapsedMs -ge 0) 'every result needs cmd and elapsedMs'
89 + # batch: one process start, ordered steps, per-step envelopes.
90 + # Steps go through a file because shells mangle embedded quotes.
91 + function Invoke-Batch([string] $StepsJson, [switch] $AllowFail, [string[]] $Extra = @()) {
92 + $path = Join-Path $env:TEMP ("win32-drive-test-batch-" + [guid]::NewGuid().ToString('N') + '.json')
93 + Set-Content -LiteralPath $path -Value $StepsJson -Encoding UTF8
94 + try { (Invoke-Raw (@('batch','-File',$path) + $Extra) -AllowFail:$AllowFail) } finally { Remove-Item -LiteralPath $path -Force -ErrorAction SilentlyContinue }
95 + }
96 + $batch = (Invoke-Batch '[{"cmd":"focus"},{"cmd":"wait","ms":50},{"cmd":"idle"}]').Json
97 + Assert ($batch.ok -and $batch.steps -eq 3 -and $batch.ran -eq 3) 'batch must run every step'
98 + Assert ($batch.results[0].cmd -eq 'focus' -and $batch.results[0].step -eq 0) 'batch results need cmd and step'
99 + Assert ($batch.results[1].waitedMs -eq 50) 'batch wait step failed'
100 + Assert ($null -eq $batch.failedAt) 'successful batch must not report failedAt'
101 + $batchFail = Invoke-Batch '[{"cmd":"idle"},{"cmd":"nonsense"},{"cmd":"idle"}]' -AllowFail
102 + Assert ($batchFail.Json.ok -eq $false -and $batchFail.Json.failedAt -eq 1 -and $batchFail.Json.ran -eq 2) 'batch must stop at the failing step'
103 + Assert ($batchFail.Json.results[1].code -eq 'unknown-command') 'batch failures must carry the error code'
104 + $batchContinue = Invoke-Batch '[{"cmd":"nonsense"},{"cmd":"idle"}]' -AllowFail -Extra @('-ContinueOnError')
105 + Assert ($batchContinue.Json.ran -eq 2) 'batch -ContinueOnError must keep going'
106 + $batchBogus = Invoke-Batch '[{"cmd":"idle","Bogus":1}]' -AllowFail
107 + Assert ($batchBogus.Json.code -eq 'unknown-option' -and $batchBogus.Json.error -match 'step 0') 'batch must reject unknown step options'
109 + # structured errors carry codes, hints, and context
110 + $noWindow = (Invoke-Raw @('list','-Hwnd','1') -AllowFail).Json
111 + Assert ($noWindow.count -eq 0) 'list with an unmatched selector returns no windows'
112 + $stale = (Invoke-Raw @('window','-Hwnd','999999999','-Action','min','-IdleMs','0') -AllowFail).Json
113 + Assert ($stale.code -eq 'stale-window' -and $stale.hint) 'stale handles need code stale-window plus a hint'
114 + $missing = (Invoke-Raw @('shot','-TitleContains',('no-window-' + [guid]::NewGuid().ToString('N'))) -AllowFail).Json
115 + Assert ($missing.code -eq 'no-window' -and $missing.candidates.Count -gt 0) 'no-window must list candidates'
116 + $consent = (Invoke-Raw @('click','-X','10','-Y','10','-IdleMs','0') -AllowFail).Json
117 + Assert ($consent.code -eq 'pointer-consent') 'click without -Pointer must fail with pointer-consent'
87 119 $list = Invoke-Json @('list')
88 120 Assert ($list.windows.Count -gt 0) 'list should return visible windows'
121 + Assert ($list.count -eq $list.windows.Count -and $null -ne $list.foreground -and $null -ne $list.idleMs) 'list must report count, foreground, and idle time'
122 + Assert (($list.windows | Where-Object { $_.focused }).Count -le 1) 'at most one window can be focused'
123 + Assert ($list.windows[0].z -eq 0) 'list must report z order'
89 124 $idle = Invoke-Json @('idle')
90 125 Assert ($idle.idleMs -is [int] -or $idle.idleMs -is [long]) 'idleMs must be numeric'
91 126 $cursor = Invoke-Json @('cursor')
152 187 Assert-Err @('uia-invoke','-Hwnd',$hwnd,'-Name','definitely-no-such-control','-IdleMs','0','-TimeoutMs','1000') 'No matching element'
154 189 # pointer input needs explicit consent
155 - Assert-Err @('click','-Hwnd',$hwnd,'-IdleMs','0','-TimeoutMs','1000') 'pass -Pointer'
156 - Assert-Err @('type','-Hwnd',$hwnd,'-Text','x','-Focus','auto','-IdleMs','0','-TimeoutMs','1000') 'pass -Pointer'
190 + Assert ((Invoke-Raw @('click','-Hwnd',$hwnd,'-IdleMs','0','-TimeoutMs','1000') -AllowFail).Json.code -eq 'pointer-consent') 'click without -Pointer must fail with pointer-consent'
191 + Assert ((Invoke-Raw @('type','-Hwnd',$hwnd,'-Text','x','-Focus','auto','-IdleMs','0','-TimeoutMs','1000') -AllowFail).Json.code -eq 'pointer-consent') '-Focus auto without -Pointer must fail with pointer-consent'
158 193 $theme = Invoke-Json @('theme')
159 194 Assert ($theme.apps -in @('dark','light') -and $theme.system -in @('dark','light')) 'theme read failed'
181 216 $buttonX = [int]($button.x + $button.width / 2 - $winShot.x)
182 217 $buttonY = [int]($button.y + $button.height / 2 - $winShot.y)
183 218 $before = Invoke-Json @('cursor')
184 - $click = Invoke-Json @('click','-Hwnd',$hwnd,'-X',[string]$buttonX,'-Y',[string]$buttonY,'-Pointer','-Focus','auto','-IdleMs','0','-TimeoutMs','1000')
219 + $click = Invoke-Json @('click','-Hwnd',$hwnd,'-X',[string]$buttonX,'-Y',[string]$buttonY,'-Pointer','-Focus','auto','-Return','keep','-NoCountdown','-IdleMs','0','-TimeoutMs','1000')
185 220 Assert ($click.foreground.hwnd -eq $app.Window.hwnd) 'click must report the target window as foreground'
221 + Assert ($click.target.hwnd -eq $app.Window.hwnd -and $click.target.title -like 'Win32DriveTest-*') 'click must echo the resolved target window'
222 + Assert ($click.return -eq 'keep' -and $null -eq $click.returnedTo) '-Return keep must leave focus on the target'
186 223 Assert ($click.focus -eq 'auto' -and $click.cursor -eq 'restore') 'click focus/cursor reporting wrong'
187 224 Wait-Title $app.Window.hwnd "$($app.Title) clicked" | Out-Null
188 225 $after = Invoke-Json @('cursor')
189 226 # Tolerates the human moving the mouse mid-run: the regression is a cursor
190 227 # parked on the click target, not a cursor that simply moved.
191 228 Assert (($after.x -eq $before.x -and $after.y -eq $before.y) -or $after.x -ne $click.x -or $after.y -ne $click.y) 'click must restore the cursor position'
192 - Assert ((Invoke-Json @('click','-Hwnd',$hwnd,'-X',[string]$buttonX,'-Y',[string]$buttonY,'-Pointer','-Cursor','keep','-Focus','skip','-IdleMs','0','-TimeoutMs','1000')).cursor -eq 'keep') 'click -Cursor keep failed'
229 + Assert ((Invoke-Json @('click','-Hwnd',$hwnd,'-X',[string]$buttonX,'-Y',[string]$buttonY,'-Pointer','-Cursor','keep','-Focus','skip','-NoCountdown','-IdleMs','0','-TimeoutMs','1000')).cursor -eq 'keep') 'click -Cursor keep failed'
193 230 Assert-Err @('click','-Hwnd',$hwnd,'-Pointer','-Focus','wat','-IdleMs','0','-TimeoutMs','1000') 'Focus must be auto, require, or skip'
194 231 Assert-Err @('click','-Hwnd',$hwnd,'-Pointer','-Cursor','wat','-IdleMs','0','-TimeoutMs','1000') 'Cursor must be restore or keep'
198 235 # elimination instead of by AutomationId (which is just the raw HWND here).
199 236 $textbox = $uia.tree.children | Where-Object { $_.name -ne 'ClickMe' -and $_.width -gt 200 } | Select-Object -First 1
200 237 Assert ($null -ne $textbox) 'uia did not expose the text box'
201 - Assert ((Invoke-Json @('click','-Hwnd',$hwnd,'-X',[string]([int]($textbox.x + $textbox.width / 2 - $winShot.x)),'-Y',[string]([int]($textbox.y + $textbox.height / 2 - $winShot.y)),'-Pointer','-Focus','auto','-IdleMs','0','-TimeoutMs','1000')).ok) 'textbox click failed'
238 + Assert ((Invoke-Json @('click','-Hwnd',$hwnd,'-X',[string]([int]($textbox.x + $textbox.width / 2 - $winShot.x)),'-Y',[string]([int]($textbox.y + $textbox.height / 2 - $winShot.y)),'-Pointer','-Focus','auto','-NoCountdown','-IdleMs','0','-TimeoutMs','1000')).ok) 'textbox click failed'
202 239 $unicode = 'Grusse-ae-' + [char] 0x00E4 + [char] 0x20AC
203 - Assert ((Invoke-Json @('key','-Hwnd',$hwnd,'-Keys','^a','-Pointer','-Focus','auto','-IdleMs','0','-TimeoutMs','1000')).ok) 'select all before typing failed'
204 - $typed = Invoke-Json @('type','-Hwnd',$hwnd,'-Text',$unicode,'-Pointer','-Focus','auto','-IdleMs','0','-TimeoutMs','1000')
240 + Assert ((Invoke-Json @('key','-Hwnd',$hwnd,'-Keys','^a','-Pointer','-Focus','auto','-NoCountdown','-IdleMs','0','-TimeoutMs','1000')).ok) 'select all before typing failed'
241 + $typed = Invoke-Json @('type','-Hwnd',$hwnd,'-Text',$unicode,'-Pointer','-Focus','auto','-NoCountdown','-IdleMs','0','-TimeoutMs','1000')
205 242 Assert ($typed.chars -eq $unicode.Length) 'type failed'
206 243 Assert ($typed.method -eq 'unicode') 'type must default to the unicode method on 64-bit'
207 244 Assert ($typed.foreground.hwnd -eq $app.Window.hwnd) 'type must report the target window as foreground'
208 245 Wait-Title $app.Window.hwnd "$($app.Title) text:$unicode" | Out-Null
210 - Assert ((Invoke-Json @('key','-Hwnd',$hwnd,'-Keys','^a','-Pointer','-Focus','auto','-IdleMs','0','-TimeoutMs','1000')).foreground.hwnd -eq $app.Window.hwnd) 'key failed'
247 + Assert ((Invoke-Json @('key','-Hwnd',$hwnd,'-Keys','^a','-Pointer','-Focus','auto','-NoCountdown','-IdleMs','0','-TimeoutMs','1000')).foreground.hwnd -eq $app.Window.hwnd) 'key failed'
211 248 $sendkeys = 'sk+^%~(){}[]'
212 - Assert ((Invoke-Json @('type','-Hwnd',$hwnd,'-Text',$sendkeys,'-Method','sendkeys','-Pointer','-Focus','auto','-IdleMs','0','-TimeoutMs','1000')).method -eq 'sendkeys') 'type -Method sendkeys failed'
249 + Assert ((Invoke-Json @('type','-Hwnd',$hwnd,'-Text',$sendkeys,'-Method','sendkeys','-Pointer','-Focus','auto','-NoCountdown','-IdleMs','0','-TimeoutMs','1000')).method -eq 'sendkeys') 'type -Method sendkeys failed'
213 250 Wait-Title $app.Window.hwnd "$($app.Title) text:$sendkeys" | Out-Null
214 251 Assert-Err @('type','-Hwnd',$hwnd,'-Text','x','-Method','wat','-Pointer','-IdleMs','0','-TimeoutMs','1000') 'Method must be unicode or sendkeys'
216 253 # focusing must fail loudly instead of driving whatever happens to be in front
217 254 Assert ((Invoke-Json @('window','-Hwnd',$hwnd,'-Action','min','-IdleMs','0','-TimeoutMs','1000')).ok) 'window min failed'
218 255 Start-Sleep -Milliseconds 250
219 - Assert-Err @('type','-Hwnd',$hwnd,'-Text','must-not-arrive','-Pointer','-Focus','auto','-IdleMs','0','-TimeoutMs','1000') 'minimized'
256 + Assert-Err @('type','-Hwnd',$hwnd,'-Text','must-not-arrive','-Pointer','-Focus','auto','-NoCountdown','-IdleMs','0','-TimeoutMs','1000') 'minimized'
220 257 Assert ((Invoke-Json @('window','-Hwnd',$hwnd,'-Action','restore','-IdleMs','0','-TimeoutMs','1000')).ok) 'window restore failed'
221 258 Start-Sleep -Milliseconds 250
223 - Assert ((Invoke-Json @('window','-Hwnd',$hwnd,'-Action','move','-X','100','-Y','100','-Width','430','-Height','270','-IdleMs','0','-TimeoutMs','1000')).ok) 'window move failed'
260 + $movedResult = Invoke-Json @('window','-Hwnd',$hwnd,'-Action','move','-X','100','-Y','100','-Width','430','-Height','270','-IdleMs','0','-TimeoutMs','1000')
261 + Assert ($movedResult.ok) 'window move failed'
262 + Assert ($movedResult.window.width -gt 350 -and $movedResult.window.height -gt 200) 'window must return the updated rect without a second query'
224 263 Start-Sleep -Milliseconds 150
225 264 $moved = @(Invoke-Json @('list')).windows | Where-Object hwnd -eq $app.Window.hwnd | Select-Object -First 1
226 265 Assert ($moved.width -gt 350 -and $moved.height -gt 200) 'window move/list update failed'
232 271 $app.Process.WaitForExit(5000) | Out-Null
233 272 Assert ($app.Process.HasExited) 'test window did not close'
274 + # the takeover countdown must be vetoable by real user input
275 + $abortJob = Start-Job -ScriptBlock {
276 + param($scriptPath)
277 + & powershell.exe -NoProfile -ExecutionPolicy Bypass -File $scriptPath overlay -Text 'abort probe' -DurationMs 3000
278 + } -ArgumentList $script
279 + Start-Sleep -Milliseconds 1500
280 + Invoke-Json @('key','-Keys','{F13}','-Focus','skip','-NoCountdown','-IdleMs','0','-TimeoutMs','1000') | Out-Null
281 + $abort = (Receive-Job -Job $abortJob -Wait -AutoRemoveJob) | ConvertFrom-Json
282 + Assert ($abort.completed -eq $false) 'user input during the countdown must cancel the overlay'
235 284 Assert-Err @('wat') 'Unknown command'
236 285 Assert-Err @('shot','-Bogus','x') 'Unknown option'
237 286 Assert-Err @('shot','-X') 'Missing value'