dsh-click 0.3.28 → 0.3.29

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.3.29] - 2026-11-13
+
+### Added
+
+- **`captureMethod` and `scope` on `screen_shot` results.** `captureMethod` names the path that produced the pixels (`printwindow-fullcontent` / `printwindow` / `copyfromscreen`), and `scope` says what was captured (`window` / `primary` / `virtual`). `scope: "virtual"` captures the whole virtual desktop (`SM_XVIRTUALSCREEN` family); it is opt-in, defaults to `primary`, and is marked experimental because the multi-monitor/negative-origin path is not fully verified.
+- **Minimized windows are reported honestly.** `app_list` marks them `minimized: true` and omits `rect` (Windows reports the `-32000` placeholder rectangle while iconified), and `screen_shot` / `screen_read` refuse them with `WINDOW_MINIMIZED` instead of capturing a broken frame.
+
+### Fixed
+
+- **Window screenshots no longer depend on occlusion (the main #6/#35 bug).** The helper now tries `PrintWindow(hwnd, hdc, PW_RENDERFULLCONTENT)` first, falls back to `PrintWindow(0)`, and only then to `CopyFromScreen`. A captured frame is rejected as blank by sampled checks on the 40px-inset 16x16 grid (quantized colour count and luminance standard deviation) plus a 99%-dark test on a 32x32 full-frame grid. Measured on Windows 11: a fully covered Explorer window produced byte-identical `PrintWindow(2)` frames across two different occluders, while `CopyFromScreen` captured the occluder and changed between runs. The colour-count rule is applied only to the no-flag fallback: a legitimate all-white Chrome page measured 3 quantized colours with a luminance sd of 9.6, so applying that rule to `PrintWindow(2)` would reject valid frames.
+- **One target resolver for `snapshot` / `tree` / `shot`.** `snapshot` used to read only `args.windowId`, so `{"op":"snapshot","args":{"target":{"windowId":N}}}` silently reported the foreground window. All three now read `args.target`, with the legacy top-level `windowId` kept as a fallback. A `snapshot` with neither fails with `NO_TARGET` instead of guessing.
+- **`shot` without a target documents and reports the primary screen**, not the foreground window; `screen_read` keeps the foreground default because it is a tree walk.
+- **A window capture and its `shotHash` now come from one frame.** The hash used to be computed from a second capture, which could disagree with the shipped image and with the capture path that was reported.
+
 ## [0.3.28] - 2026-11-13
 
 ### Fixed
@@ -79,8 +93,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Correct the release date in the previous section, which was stamped with the literal string `undefined` by the release stamper. No content or behaviour change; the version is bumped only because npm will not republish an existing version.
 
 
-## [Unreleased]
-
 ## [0.3.17] - 2026-10-04
 
 undefined

package/README.en.md

@@ -97,11 +97,11 @@ Every PerryLink plugin is listed in the built-in DSH Desktop market: **Market
 
 `dsh-click` splits the native desktop into an auditable observation face and action face:
 
-- **`screen_shot`** — captures a window (or the primary screen) and downscales it to `maxScreenshotSide`. With a vision-capable model the result carries the image; text-only models get a text description and keep working.
+- **`screen_shot`** — captures a window (or the primary screen) and downscales it to `maxScreenshotSide`. Window captures take `PrintWindow(PW_RENDERFULLCONTENT)` first, so they do not depend on other windows stacked on top; `captureMethod` reports the path that actually produced the pixels. With a vision-capable model the result carries the image; text-only models get a text description and keep working.
 - **`screen_read`** — the structured observation: the accessibility tree (element ids, types, names, rectangles, supported patterns) plus pixel-location hints with colors — plain text, no image model required.
 - **`screen_find`** — for applications that expose no accessibility tree, finds clickable text or a described visual target via optional OCR (`ocr.*`, tesseract probed at mount) or visual grounding, returning screen coordinates plus an `observationId`; read-only, never needs approval.
 - **`click` / `type` / `scroll` / `key`** — window-scoped actions addressed by element id or coordinates. Delivery prefers UIA invoke, falls back to posted window messages, and never steals foreground focus by default; `type` takes the UIA `ValuePattern` fast path and otherwise injects real keystrokes through `SendInput` (CJK-safe); `key` reports honestly when an app ignores posted input.
-- **`app_list` / `app_launch`** — enumerate running applications and their visible windows; launch one by name or executable path.
+- **`app_list` / `app_launch`** — enumerate running applications and their visible windows (minimized windows carry `minimized: true` and no `rect`); launch one by name or executable path.
 
 Every mutating action crosses one shared safety boundary:
 
@@ -133,6 +133,15 @@ model                           harness
 | `app_list` | ✅ | — | Running applications and their visible windows |
 | `app_launch` | | ✅ | By name or executable path, with optional arguments |
 
+### Screenshots and coordinate space
+
+- **A target means a window capture; no target means the primary screen** (`snapshot.windowId = 0`, `title = "primary screen"`), not the foreground window. For the whole virtual desktop (multiple monitors, negative origins) pass `scope: "virtual"`; that mode is marked **experimental** and its multi-monitor geometry is not fully verified yet.
+- **Window captures try `PrintWindow(hwnd, hdc, PW_RENDERFULLCONTENT)` first**: the window paints itself, so the image does not depend on what is stacked on top. On failure or a blank frame the helper falls back to `PrintWindow(0)` and then to `CopyFromScreen`. `captureMethod` (`printwindow-fullcontent` / `printwindow` / `copyfromscreen`) says which path produced the image.
+- **`width` / `height` are the bitmap size, not the window size**: they are already downscaled to `maxScreenshotSide`, while `snapshot.rect` is always the physical window (or screen) rectangle. Map with `bitmapX = (screenX - rect.x) * width / rect.width`.
+- **Every rectangle is in physical pixels**: DPI awareness is set when the helper starts (Per-Monitor V2), and `app_list`, `screen_read`, `screen_shot`, and `click` share one coordinate space.
+- **Minimized windows**: `app_list` marks them `minimized: true` and returns no `rect` (Windows reports the `-32000` placeholder rect while iconified); `screen_shot` / `screen_read` fail with `WINDOW_MINIMIZED`, so restore the window first.
+
+
 ### Examples
 
 These are the plugin’s real entry points; install once, then call one.

package/README.es.md

@@ -97,11 +97,11 @@ Todos los plugins de PerryLink pueden explorarse en el mercado integrado de DSH
 
 `dsh-click` separa el escritorio nativo en una cara de observación y otra de acción, ambas auditables:
 
-- **`screen_shot`** — captura una ventana (o la pantalla principal) y la escala a `maxScreenshotSide`. Con un modelo capaz de ver imágenes el resultado lleva la imagen; los modelos de solo texto reciben una descripción textual y siguen funcionando.
+- **`screen_shot`** — captura una ventana (o la pantalla principal) y la escala a `maxScreenshotSide`. Las capturas de ventana usan primero `PrintWindow(PW_RENDERFULLCONTENT)`, así que no dependen de otras ventanas superpuestas; `captureMethod` indica la ruta que produjo los píxeles. Con un modelo capaz de ver imágenes el resultado lleva la imagen; los modelos de solo texto reciben una descripción textual y siguen funcionando.
 - **`screen_read`** — la observación estructurada: el árbol de accesibilidad (ids de elemento, tipos, nombres, rectángulos, patrones soportados) más pistas de posición de píxeles con colores; texto plano, sin necesidad de modelo de imagen.
 - **`screen_find`** — para aplicaciones sin árbol de accesibilidad, busca texto clicable o un objetivo visual descrito mediante OCR opcional (`ocr.*`, tesseract sondeado al montar) o grounding visual, y devuelve coordenadas de pantalla más un `observationId`; es de solo lectura y nunca pide aprobación.
 - **`click` / `type` / `scroll` / `key`** — acciones con ámbito de ventana direccionadas por id de elemento o coordenadas. La entrega prefiere la invocación UIA y recurre a mensajes de ventana publicados, y por defecto nunca roba el foco de primer plano; `type` usa la vía rápida `ValuePattern` de UIA y, si falla, inyecta pulsaciones reales con `SendInput` (seguro para CJK); `key` informa con honestidad cuando una app ignora la entrada publicada.
-- **`app_list` / `app_launch`** — enumera las aplicaciones en ejecución y sus ventanas visibles; lanza una por nombre o ruta del ejecutable.
+- **`app_list` / `app_launch`** — enumera las aplicaciones en ejecución y sus ventanas visibles (las minimizadas llevan `minimized: true` y no traen `rect`); lanza una por nombre o ruta del ejecutable.
 
 Toda acción mutante cruza la misma frontera de seguridad:
 
@@ -133,6 +133,15 @@ modelo                          harness
 | `app_list` | ✅ | — | Aplicaciones en ejecución y sus ventanas visibles |
 | `app_launch` | | ✅ | Por nombre o ruta del ejecutable, con argumentos opcionales |
 
+### Capturas y espacio de coordenadas
+
+- **Con `target` se captura una ventana; sin `target` se captura la pantalla principal** (`snapshot.windowId = 0`, `title = "primary screen"`), no la ventana en primer plano. Para todo el escritorio virtual (varios monitores, con origen negativo) pasa `scope: "virtual"`; ese modo está marcado como **experimental** y su geometría multimonitor aún no está verificada por completo.
+- **La captura de ventana prueba primero `PrintWindow(hwnd, hdc, PW_RENDERFULLCONTENT)`**: la ventana se dibuja a sí misma, así que la imagen no depende de lo que haya encima. Si falla o sale en blanco, el helper retrocede a `PrintWindow(0)` y luego a `CopyFromScreen`. `captureMethod` (`printwindow-fullcontent` / `printwindow` / `copyfromscreen`) dice qué ruta produjo la imagen.
+- **`width` / `height` son el tamaño del bitmap, no el de la ventana**: ya vienen reducidos a `maxScreenshotSide`, mientras que `snapshot.rect` es siempre el rectángulo físico de la ventana (o de la pantalla). Conversión: `bitmapX = (screenX - rect.x) * width / rect.width`.
+- **Todos los rectángulos están en píxeles físicos**: la conciencia de DPI se fija al arrancar el helper (Per-Monitor V2), y `app_list`, `screen_read`, `screen_shot` y `click` comparten el mismo espacio de coordenadas.
+- **Ventanas minimizadas**: `app_list` las marca con `minimized: true` y no devuelve `rect` (Windows da el rectángulo comodín `-32000` mientras están minimizadas); `screen_shot` / `screen_read` fallan con `WINDOW_MINIMIZED`; restaura la ventana primero.
+
+
 ### Ejemplos
 
 Son los puntos de entrada reales del plugin; instala una vez y llama a uno.

package/README.hi.md

@@ -97,11 +97,11 @@ dsh plugin --profile <name> add dsh-click
 
 `dsh-click` नेटिव डेस्कटॉप को दो ऑडिट-योग्य पक्षों में बाँटता है — अवलोकन और कार्रवाई:
 
-- **`screen_shot`** — विंडो (या मुख्य स्क्रीन) की तस्वीर लेकर `maxScreenshotSide` तक छोटा करता है। जो मॉडल तस्वीरें लेता है उसे परिणाम में चित्र मिलता है; केवल-टेक्स्ट मॉडल को टेक्स्ट विवरण मिलता है और वे भी चलते रहते हैं।
+- **`screen_shot`** — विंडो (या मुख्य स्क्रीन) की तस्वीर लेकर `maxScreenshotSide` तक छोटा करता है। विंडो कैप्चर पहले `PrintWindow(PW_RENDERFULLCONTENT)` से होते हैं, इसलिए ऊपर रखी विंडो से प्रभावित नहीं होते; `captureMethod` बताता है कि पिक्सेल असल में किस रास्ते से आए। जो मॉडल तस्वीरें लेता है उसे परिणाम में चित्र मिलता है; केवल-टेक्स्ट मॉडल को टेक्स्ट विवरण मिलता है और वे भी चलते रहते हैं।
 - **`screen_read`** — संरचित अवलोकन: accessibility tree (तत्व id, प्रकार, नाम, आयत, समर्थित पैटर्न) और रंगों सहित pixel स्थिति-संकेत — शुद्ध टेक्स्ट, कोई इमेज मॉडल ज़रूरी नहीं।
 - **`screen_find`** — जिन ऐप्स में accessibility tree नहीं है, उनके लिए वैकल्पिक OCR (`ocr.*`, माउंट पर tesseract जाँचा जाता है) या visual grounding से क्लिक-योग्य टेक्स्ट/वर्णित लक्ष्य खोजता है और स्क्रीन निर्देशांक तथा `observationId` लौटाता है; यह केवल-पठन है और कभी मंज़ूरी नहीं माँगता।
 - **`click` / `type` / `scroll` / `key`** — तत्व id या निर्देशांक से पता किए गए विंडो-स्कोप कार्रवाई। डिलीवरी UIA invoke पसंद करती है और posted विंडो संदेशों पर लौटती है, तथा डिफ़ॉल्ट रूप से foreground फ़ोकस कभी नहीं छीनती; `type` पहले UIA `ValuePattern` तेज़ रास्ता लेता है, फिर `SendInput` से असली कीस्ट्रोक डालता है (CJK-सुरक्षित); posted इनपुट अनदेखा करने वाले ऐप्स पर `key` ईमानदारी से विफलता बताता है।
-- **`app_list` / `app_launch`** — चल रहे ऐप्स और उनकी दिखने वाली विंडो सूचीबद्ध करता है; नाम या executable पथ से ऐप लॉन्च करता है।
+- **`app_list` / `app_launch`** — चल रहे ऐप्स और उनकी दिखने वाली विंडो सूचीबद्ध करता है (minimized विंडो पर `minimized: true` होता है और कोई `rect` नहीं आता); नाम या executable पथ से ऐप लॉन्च करता है।
 
 हर बदलाव वाली कार्रवाई एक ही सुरक्षा सीमा से गुज़रती है:
 
@@ -133,6 +133,15 @@ dsh plugin --profile <name> add dsh-click
 | `app_list` | ✅ | — | चल रहे ऐप्स और उनकी दिखने वाली विंडो |
 | `app_launch` | | ✅ | नाम या executable पथ से, वैकल्पिक आर्ग्युमेंट के साथ |
 
+### स्क्रीनशॉट और निर्देशांक स्थान
+
+- **`target` हो तो विंडो कैप्चर होती है; `target` न हो तो मुख्य स्क्रीन** (`snapshot.windowId = 0`, `title = "primary screen"`), foreground विंडो नहीं। पूरे virtual desktop (कई मॉनिटर, ऋणात्मक मूल) के लिए `scope: "virtual"` भेजें; यह मोड **experimental** है और बहु-मॉनिटर ज्यामिति की पूरी पुष्टि नहीं हुई है।
+- **विंडो कैप्चर पहले `PrintWindow(hwnd, hdc, PW_RENDERFULLCONTENT)` आज़माते हैं**: विंडो स्वयं चित्रित होती है, इसलिए ऊपर रखी विंडो प्रभावित नहीं करती। विफलता या खाली फ़्रेम पर helper `PrintWindow(0)` और फिर `CopyFromScreen` पर लौटता है। `captureMethod` (`printwindow-fullcontent` / `printwindow` / `copyfromscreen`) बताता है कि चित्र किस रास्ते से बना।
+- **`width` / `height` बिटमैप का आकार हैं, विंडो का नहीं**: ये `maxScreenshotSide` तक घटाए जा चुके हैं, जबकि `snapshot.rect` हमेशा विंडो (या स्क्रीन) का भौतिक आयत है। रूपांतरण: `bitmapX = (screenX - rect.x) * width / rect.width`.
+- **सभी आयत भौतिक पिक्सेल में हैं**: DPI जागरूकता helper शुरू होते ही सेट होती है (Per-Monitor V2), और `app_list`, `screen_read`, `screen_shot` तथा `click` एक ही निर्देशांक स्थान साझा करते हैं।
+- **minimized विंडो**: `app_list` उन्हें `minimized: true` से चिह्नित करता है और `rect` नहीं देता (Windows minimized अवस्था में `-32000` प्लेसहोल्डर आयत देता है); `screen_shot` / `screen_read` स्पष्ट रूप से `WINDOW_MINIMIZED` देकर विफल होते हैं — पहले विंडो बहाल करें।
+
+
 ### उदाहरण
 
 ये प्लगइन के वास्तविक प्रवेश बिंदु हैं; एक बार इंस्टॉल करके एक चलाएँ।

package/README.md

@@ -97,11 +97,11 @@ dsh plugin --profile <name> add dsh-click
 
 `dsh-click` 把原生桌面拆成可审计的观察面与动作面：
 
-- **`screen_shot`** —— 截取窗口（或主屏幕），按 `maxScreenshotSide` 缩放。模型支持图像时结果附带图片；纯文本模型则得到文字描述，照常可用。
+- **`screen_shot`** —— 截取窗口（或主屏幕），按 `maxScreenshotSide` 缩放。窗口截图优先走 `PrintWindow(PW_RENDERFULLCONTENT)`，不受其它窗口遮挡影响；结果里的 `captureMethod` 写明实际路径。模型支持图像时结果附带图片；纯文本模型则得到文字描述，照常可用。
 - **`screen_read`** —— 结构化观察：无障碍树（元素 id、类型、名称、矩形、支持的模式）加像素位置提示与颜色 —— 纯文本，无需图像模型。
 - **`screen_find`** —— 对没有无障碍树的应用，用可选 OCR（`ocr.*`，挂载时探测 tesseract）或视觉 grounding 按文字/描述找可点目标，返回屏幕坐标与 `observationId`；只读，不需要审批。
 - **`click` / `type` / `scroll` / `key`** —— 以元素 id 或坐标寻址的窗口级操作。优先 UIA invoke，回退到 post 窗口消息，且默认绝不抢占前台焦点；`type` 走 UIA `ValuePattern` 快路径，失败再用 `SendInput` 注入真实按键（CJK 安全）；`key` 对忽略 post 输入的应用会大声拒绝。
-- **`app_list` / `app_launch`** —— 枚举运行中的应用及其可见窗口；按名称或可执行路径启动应用。
+- **`app_list` / `app_launch`** —— 枚举运行中的应用及其可见窗口（最小化窗口标 `minimized: true` 且不返回 `rect`）；按名称或可执行路径启动应用。
 
 每个变更性操作都穿过同一条安全边界：
 
@@ -133,6 +133,15 @@ dsh plugin --profile <name> add dsh-click
 | `app_list` | ✅ | — | 运行中的应用及其可见窗口 |
 | `app_launch` | | ✅ | 按名称或可执行路径启动，可带参数 |
 
+### 截图与坐标空间
+
+- **带 `target` 才是窗口截图；不带 `target` 抓的是主屏**（`snapshot.windowId = 0`、`title = "primary screen"`），不是前台窗口。要整个虚拟桌面（多屏，含负坐标）请传 `scope: "virtual"`；该模式标注为**实验性**，多屏几何尚未完整验证。
+- **窗口截图先走 `PrintWindow(hwnd, hdc, PW_RENDERFULLCONTENT)`**：窗口自己绘制，不受其它窗口遮挡影响；失败或空图时依次回退 `PrintWindow(0)` 与 `CopyFromScreen`。结果里的 `captureMethod` 为 `printwindow-fullcontent` / `printwindow` / `copyfromscreen`，直接说明这张图是怎么来的。
+- **`width` / `height` 是位图尺寸，不是窗口尺寸**：它们已被 `maxScreenshotSide` 下采样；`snapshot.rect` 始终是物理像素的窗口（或屏幕）矩形。换算方式：`bitmapX = (screenX - rect.x) * width / rect.width`。
+- **所有矩形都是物理像素**：DPI 感知在 helper 启动时设置（Per-Monitor V2），`app_list`、`screen_read`、`screen_shot` 与 `click` 共用同一坐标空间。
+- **最小化窗口**：`app_list` 标记 `minimized: true` 并且不返回 `rect`（Windows 在最小化时给的是 `-32000` 占位矩形）；`screen_shot` / `screen_read` 对它明确报 `WINDOW_MINIMIZED`，请先还原窗口。
+
+
 ### 示例
 
 以下为插件真实入口；安装后调用一个即可。

package/README.pt.md

@@ -97,11 +97,11 @@ Todo plugin PerryLink está listado no mercado integrado do DSH Desktop: **Marke
 
 O `dsh-click` separa o desktop nativo numa face de observação e noutra de ação, ambas auditáveis:
 
-- **`screen_shot`** — captura uma janela (ou a tela principal) e a reduz para `maxScreenshotSide`. Com um modelo que aceita imagens o resultado leva a imagem; modelos só de texto recebem uma descrição textual e continuam funcionando.
+- **`screen_shot`** — captura uma janela (ou a tela principal) e a reduz para `maxScreenshotSide`. Capturas de janela usam primeiro `PrintWindow(PW_RENDERFULLCONTENT)`, sem depender de outras janelas sobrepostas; `captureMethod` informa o caminho que produziu os píxeis. Com um modelo que aceita imagens o resultado leva a imagem; modelos só de texto recebem uma descrição textual e continuam funcionando.
 - **`screen_read`** — a observação estruturada: a árvore de acessibilidade (ids de elemento, tipos, nomes, retângulos, padrões suportados) mais dicas de posição de píxeis com cores; texto puro, sem precisar de modelo de imagem.
 - **`screen_find`** — para aplicações sem árvore de acessibilidade, encontra texto clicável ou um alvo visual descrito via OCR opcional (`ocr.*`, tesseract sondado ao montar) ou grounding visual, devolvendo coordenadas de tela mais um `observationId`; é só leitura e nunca pede aprovação.
 - **`click` / `type` / `scroll` / `key`** — ações com escopo de janela endereçadas por id de elemento ou coordenadas. A entrega prefere invocação UIA e recorre a mensagens de janela postadas, e por padrão nunca rouba o foco de primeiro plano; `type` usa o caminho rápido `ValuePattern` do UIA e, se falhar, injeta teclas reais via `SendInput` (seguro para CJK); `key` reporta com honestidade quando uma app ignora a entrada postada.
-- **`app_list` / `app_launch`** — enumera aplicações em execução e as suas janelas visíveis; lança uma por nome ou caminho do executável.
+- **`app_list` / `app_launch`** — enumera aplicações em execução e as suas janelas visíveis (as minimizadas levam `minimized: true` e não trazem `rect`); lança uma por nome ou caminho do executável.
 
 Toda ação mutante cruza a mesma fronteira de segurança:
 
@@ -133,6 +133,15 @@ modelo                          harness
 | `app_list` | ✅ | — | Aplicações em execução e as suas janelas visíveis |
 | `app_launch` | | ✅ | Por nome ou caminho do executável, com argumentos opcionais |
 
+### Capturas e espaço de coordenadas
+
+- **Com `target` captura-se uma janela; sem `target` captura-se a tela principal** (`snapshot.windowId = 0`, `title = "primary screen"`), não a janela em primeiro plano. Para todo o desktop virtual (vários monitores, com origem negativa) passe `scope: "virtual"`; esse modo está marcado como **experimental** e a geometria multimonitor ainda não está totalmente verificada.
+- **A captura de janela tenta primeiro `PrintWindow(hwnd, hdc, PW_RENDERFULLCONTENT)`**: a janela desenha-se a si mesma, pelo que a imagem não depende do que está por cima. Se falhar ou vier em branco, o helper recua para `PrintWindow(0)` e depois para `CopyFromScreen`. `captureMethod` (`printwindow-fullcontent` / `printwindow` / `copyfromscreen`) diz qual caminho produziu a imagem.
+- **`width` / `height` são o tamanho do bitmap, não o da janela**: já vêm reduzidos a `maxScreenshotSide`, enquanto `snapshot.rect` é sempre o retângulo físico da janela (ou da tela). Conversão: `bitmapX = (screenX - rect.x) * width / rect.width`.
+- **Todos os retângulos estão em píxeis físicos**: a consciência de DPI é definida quando o helper arranca (Per-Monitor V2), e `app_list`, `screen_read`, `screen_shot` e `click` partilham o mesmo espaço de coordenadas.
+- **Janelas minimizadas**: `app_list` marca-as com `minimized: true` e não devolve `rect` (o Windows dá o retângulo marcador `-32000` enquanto minimizadas); `screen_shot` / `screen_read` falham com `WINDOW_MINIMIZED`; restaure a janela primeiro.
+
+
 ### Exemplos
 
 Estes são os pontos de entrada reais do plugin; instale uma vez e chame um.

package/lib/index.js

@@ -623,7 +623,7 @@ var ObservationStore = class {
 * @module dsh-click/version
 */
 /** Plugin version advertised in the helper-protocol handshake. */
-const VERSION = "0.3.28";
+const VERSION = "0.3.29";
 /** The helper protocol revision; bump only on incompatible wire changes. */
 const HELPER_PROTOCOL_VERSION = 1;
 //#endregion
@@ -668,12 +668,16 @@ function expectWindow(value, op) {
 	const processId = typeof processIdRaw === "number" ? processIdRaw : null;
 	const executablePath = record["executablePath"];
 	if (executablePath !== null && typeof executablePath !== "string") throw new DshClickError(`helper "${op}" returned malformed executablePath`, "BAD_HELPER_RESPONSE");
+	const minimized = record["minimized"] === true;
+	const rectValue = record["rect"];
+	if (rectValue !== null && minimized) throw new DshClickError(`helper "${op}" returned a rect for a minimized window`, "BAD_HELPER_RESPONSE");
 	return {
 		windowId: expectNumber(record, "windowId", op),
 		processId,
 		title: expectString(record, "title", op),
 		className: expectString(record, "className", op),
-		rect: expectRect(record["rect"], op),
+		rect: rectValue === null ? null : expectRect(rectValue, op),
+		minimized,
 		executablePath,
 		visible: record["visible"] !== false
 	};
@@ -696,6 +700,18 @@ function expectSnapshot(value, op) {
 		elementCount: expectNumber(record, "elementCount", op)
 	};
 }
+/** Validate the helper's capture-path report. */
+function expectCaptureMethod(record, op) {
+	const value = expectString(record, "captureMethod", op);
+	if (value !== "printwindow-fullcontent" && value !== "printwindow" && value !== "copyfromscreen") throw new DshClickError(`helper "${op}" returned an unknown captureMethod`, "BAD_HELPER_RESPONSE");
+	return value;
+}
+/** Validate the helper's capture-scope report. */
+function expectCaptureScope(record, op) {
+	const value = expectString(record, "scope", op);
+	if (value !== "window" && value !== "primary" && value !== "virtual") throw new DshClickError(`helper "${op}" returned an unknown scope`, "BAD_HELPER_RESPONSE");
+	return value;
+}
 /** Validate one helper element record. */
 function expectElement(value, op) {
 	const record = expectRecordValue(value, op);
@@ -820,10 +836,11 @@ var HelperBackend = class {
 		if (!Array.isArray(result)) throw new DshClickError("helper \"windows\" returned a non-array result", "BAD_HELPER_RESPONSE");
 		return result.map((item) => expectWindow(item, "windows"));
 	}
-	async shot(ref, maxSide, signal) {
+	async shot(ref, maxSide, scope, signal) {
 		const record = expectRecordValue(await this.invoke("shot", {
 			target: ref,
 			maxSide,
+			scope,
 			maxElements: this.config.maxElements,
 			maxDepth: this.config.maxTreeDepth
 		}, signal), "shot");
@@ -831,6 +848,8 @@ var HelperBackend = class {
 			pngBase64: expectString(record, "pngBase64", "shot"),
 			width: expectNumber(record, "width", "shot"),
 			height: expectNumber(record, "height", "shot"),
+			captureMethod: expectCaptureMethod(record, "shot"),
+			scope: expectCaptureScope(record, "shot"),
 			snapshot: expectSnapshot(record["snapshot"], "shot")
 		};
 	}
@@ -1251,7 +1270,8 @@ function observedWindowInfo(info, maxTextLength) {
 		processId: info.processId,
 		title: sanitizeVisible(info.title, maxTextLength),
 		className: sanitizeVisible(info.className, maxTextLength),
-		rect: info.rect,
+		rect: info.rect === null ? null : { ...info.rect },
+		minimized: info.minimized,
 		executablePath: info.executablePath === null ? null : sanitizePath(info.executablePath, maxTextLength),
 		visible: info.visible
 	};
@@ -1279,8 +1299,8 @@ function backendGuard(services) {
 	if (!services.backend.available) throw new Error(`dsh-click backend unavailable on ${services.backend.platform}: ${services.backend.unavailableReason ?? "unknown reason"}`);
 }
 /** Plain-text fallback description for a captured screenshot. */
-function shotDescription(window, width, height) {
-	return `${width}x${height} screenshot of ${windowLine(window)}; run screen_read on the same window for the structured element list and pixel positions.`;
+function shotDescription(window, width, height, captureMethod) {
+	return `${width}x${height} bitmap via ${captureMethod} of ${windowLine(window)}; the bitmap is downscaled to the requested longest side, while the window rectangle is ${window.rect.width}x${window.rect.height} physical pixels (snapshot.rect) - map screen coordinates with rect.width/width. Run screen_read on the same window for the structured element list and pixel positions.`;
 }
 /**
 * `screen_shot` — capture the addressed window (or the primary screen).
@@ -1295,11 +1315,11 @@ function screenShotTool(services) {
 	const { ctx, config, backend, observations } = services;
 	return defineTool({
 		name: "screen_shot",
-		description: "Capture a screenshot of a desktop window (or the primary screen when no window is given). Returns an observationId that later actions cite in `basedOn`. When the current model accepts images the result includes the image; otherwise it includes a text description. Read-only: never needs approval.",
+		description: "Capture a screenshot of a desktop window, or of the primary screen when no target is given (a target-less shot never captures the foreground window). Window captures ask the window to paint itself with PrintWindow(PW_RENDERFULLCONTENT) first, so they are independent of other windows stacked on top; captureMethod reports which path produced the pixels. Returns an observationId that later actions cite in `basedOn`. When the current model accepts images the result includes the image; otherwise it includes a text description. Read-only: never needs approval.",
 		parameters: {
 			target: {
 				type: "object",
-				description: "Which window to capture (windowId, windowTitle, or processId); omitted = the foreground window.",
+				description: "Which window to capture (windowId, windowTitle, or processId); omitted = the primary screen.",
 				properties: {
 					windowId: {
 						type: "integer",
@@ -1316,9 +1336,14 @@ function screenShotTool(services) {
 				},
 				additionalProperties: false
 			},
+			scope: {
+				type: "string",
+				enum: ["primary", "virtual"],
+				description: "Only used without a target: capture the primary screen (default) or the whole virtual desktop (experimental - multi-monitor and negative-origin geometry are not fully verified)."
+			},
 			maxSide: {
 				type: "integer",
-				description: "Longest side in pixels; larger captures are downscaled."
+				description: "Longest side of the bitmap; larger captures are downscaled (the window rectangle in snapshot.rect stays in physical pixels)."
 			}
 		},
 		output: {
@@ -1364,6 +1389,22 @@ function screenShotTool(services) {
 						},
 						additionalProperties: false
 					},
+					captureMethod: {
+						type: "string",
+						enum: [
+							"printwindow-fullcontent",
+							"printwindow",
+							"copyfromscreen"
+						]
+					},
+					scope: {
+						type: "string",
+						enum: [
+							"window",
+							"primary",
+							"virtual"
+						]
+					},
 					description: { type: "string" }
 				},
 				additionalProperties: false
@@ -1384,13 +1425,14 @@ function screenShotTool(services) {
 		timeoutMs: config.helperTimeoutMs + 15e3,
 		async execute(args, exec) {
 			backendGuard(services);
-			const target = args.target ?? {};
-			const requestedSide = args.maxSide;
+			const parsed = args;
+			const target = parsed.target ?? {};
+			const requestedSide = parsed.maxSide;
 			const maxSide = requestedSide === void 0 ? config.maxScreenshotSide : Math.min(requestedSide, config.maxScreenshotSide);
-			const shot = await backend.shot(target, maxSide, exec.signal);
+			const shot = await backend.shot(target, maxSide, parsed.scope ?? "primary", exec.signal);
 			const sanitized = observedWindow(shot.snapshot, config.maxTextLength);
 			const record = observations.record(shot.snapshot);
-			const description = shotDescription(sanitized, shot.width, shot.height);
+			const description = shotDescription(sanitized, shot.width, shot.height, shot.captureMethod);
 			let image;
 			const attachments = ctx.get("attachments");
 			if (config.imageMode !== "text" && attachments !== void 0 && await sessionAcceptsImages(exec.agent, ctx, exec.signal)) try {
@@ -1422,6 +1464,8 @@ function screenShotTool(services) {
 				observationId: record.id,
 				window: sanitized,
 				...image !== void 0 ? { image } : {},
+				captureMethod: shot.captureMethod,
+				scope: shot.scope,
 				description
 			};
 		}
@@ -1603,7 +1647,7 @@ function screenFindTool(services) {
 		parameters: {
 			target: {
 				type: "object",
-				description: "Which window to search (windowId, windowTitle, or processId); omitted = the foreground window.",
+				description: "Which window to search (windowId, windowTitle, or processId); omitted = the primary screen (a target-less capture never uses the foreground window).",
 				properties: {
 					windowId: {
 						type: "integer",
@@ -1626,7 +1670,7 @@ function screenFindTool(services) {
 			},
 			maxSide: {
 				type: "integer",
-				description: "Longest side in pixels; larger captures are downscaled."
+				description: "Longest side of the bitmap; larger captures are downscaled (coordinates returned are still screen pixels)."
 			}
 		},
 		output: {
@@ -1705,7 +1749,7 @@ function screenFindTool(services) {
 			const parsed = args;
 			const requestedSide = parsed.maxSide;
 			const maxSide = requestedSide === void 0 ? config.maxScreenshotSide : Math.min(requestedSide, config.maxScreenshotSide);
-			const shot = await backend.shot(parsed.target ?? {}, maxSide, exec.signal);
+			const shot = await backend.shot(parsed.target ?? {}, maxSide, "primary", exec.signal);
 			const sanitized = observedWindow(shot.snapshot, config.maxTextLength);
 			const record = observations.record(shot.snapshot);
 			const targets = [];
@@ -2095,7 +2139,7 @@ function appListTool(services) {
 	const { config, backend } = services;
 	return defineTool({
 		name: "app_list",
-		description: "List running desktop applications and their visible windows (windowId, title, process id, executable path). Read-only: never needs approval. Use the returned windowIds as screen_shot/screen_read targets.",
+		description: "List running desktop applications and their visible windows (windowId, title, process id, executable path). Read-only: never needs approval. Use the returned windowIds as screen_shot/screen_read targets. Minimized windows are listed with minimized: true and no rect (Windows reports a -32000 placeholder while iconified); restore them before capturing.",
 		parameters: {},
 		output: {
 			schema: {
@@ -2122,7 +2166,7 @@ function appListTool(services) {
 											processId: { oneOf: [{ type: "integer" }, { type: "null" }] },
 											title: { type: "string" },
 											className: { type: "string" },
-											rect: {
+											rect: { oneOf: [{
 												type: "object",
 												properties: {
 													x: { type: "integer" },
@@ -2131,7 +2175,8 @@ function appListTool(services) {
 													height: { type: "integer" }
 												},
 												additionalProperties: false
-											},
+											}, { type: "null" }] },
+											minimized: { type: "boolean" },
 											executablePath: { oneOf: [{ type: "string" }, { type: "null" }] },
 											visible: { type: "boolean" }
 										},
@@ -2150,7 +2195,10 @@ function appListTool(services) {
 				const lines = [`${result.apps.length} running application(s) with windows:`];
 				for (const app of result.apps) {
 					lines.push(`- ${app.name} (pid ${app.processId}, ${app.executablePath ?? "unknown executable"})`);
-					for (const window of app.windows) lines.push(`  - [windowId ${window.windowId}] ${JSON.stringify(window.title)} at (${window.rect.x}, ${window.rect.y}) ${window.rect.width}x${window.rect.height}`);
+					for (const window of app.windows) {
+						const where = window.minimized ? "minimized (no rect; screen_shot refuses it until restored)" : window.rect === null ? "no rect reported" : `at (${window.rect.x}, ${window.rect.y}) ${window.rect.width}x${window.rect.height}`;
+						lines.push(`  - [windowId ${window.windowId}] ${JSON.stringify(window.title)} ${where}`);
+					}
 				}
 				return [{
 					type: "text",

package/lib/types/platform/runner.d.ts

@@ -10,7 +10,7 @@
  */
 import type { SubprocessRuntime } from '@deepseek-ai/dsh-subprocess';
 import type { ResolvedConfig } from '../config.js';
-import { type ActionOutcome, type AppInfo, type ClickRequest, type DesktopBackend, type KeyRequest, type LaunchOutcome, type Screenshot, type ScrollRequest, type Tree, type WindowInfo, type WindowRef, type WindowSnapshot, type TypeRequest } from './types.js';
+import { type ActionOutcome, type AppInfo, type ClickRequest, type DesktopBackend, type KeyRequest, type LaunchOutcome, type Screenshot, type ScreenScope, type ScrollRequest, type Tree, type WindowInfo, type WindowRef, type WindowSnapshot, type TypeRequest } from './types.js';
 /** The Windows helper backend over `ctx.subprocess`. */
 export declare class HelperBackend implements DesktopBackend {
     private readonly config;
@@ -27,7 +27,7 @@ export declare class HelperBackend implements DesktopBackend {
     /** Resolve (and cache) the powershell executable through the subprocess seam. */
     private resolvePowershell;
     listWindows(signal?: AbortSignal): Promise<WindowInfo[]>;
-    shot(ref: WindowRef, maxSide: number, signal?: AbortSignal): Promise<Screenshot>;
+    shot(ref: WindowRef, maxSide: number, scope: ScreenScope, signal?: AbortSignal): Promise<Screenshot>;
     tree(ref: WindowRef, maxElements: number, maxDepth: number, includePixels: boolean, signal?: AbortSignal): Promise<Tree>;
     snapshot(windowId: number, signal?: AbortSignal): Promise<WindowSnapshot>;
     click(request: ClickRequest, focusFallback: boolean, signal?: AbortSignal): Promise<ActionOutcome>;

package/lib/types/platform/runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../../src/platform/runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAElD,OAAO,EAML,KAAK,aAAa,EAClB,KAAK,OAAO,EACZ,KAAK,YAAY,EACjB,KAAK,cAAc,EAInB,KAAK,UAAU,EACf,KAAK,aAAa,EAGlB,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,IAAI,EACT,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,WAAW,EACjB,MAAM,YAAY,CAAA;AA6HnB,wDAAwD;AACxD,qBAAa,aAAc,YAAW,cAAc;IAShD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAT7B,gEAAgE;IAChE,OAAO,CAAC,UAAU,CAA6B;IAE/C,QAAQ,CAAC,SAAS,QAAO;IAEzB,mEAAmE;IACnE,uEAAuE;gBAEpD,MAAM,EAAE,cAAc,EACtB,UAAU,EAAE,iBAAiB;IAGhD,QAAQ,CAAC,QAAQ,WAAU;IAE3B,wEAAwE;YAC1D,MAAM;IAsDpB,iFAAiF;IACjF,OAAO,CAAC,iBAAiB;IAanB,WAAW,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAMxD,IAAI,CAAC,GAAG,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAgBhF,IAAI,CAAC,GAAG,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAexH,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC;IASzE,KAAK,CAAC,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC;IAKlG,IAAI,CAAC,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC;IAKhG,MAAM,CAAC,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC;IAKpG,GAAG,CAAC,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC;IAK9F,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAoB9C,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC;CAYlG"}
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../../src/platform/runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAElD,OAAO,EAML,KAAK,aAAa,EAClB,KAAK,OAAO,EAGZ,KAAK,YAAY,EACjB,KAAK,cAAc,EAInB,KAAK,UAAU,EACf,KAAK,aAAa,EAGlB,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,IAAI,EACT,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,WAAW,EACjB,MAAM,YAAY,CAAA;AAuJnB,wDAAwD;AACxD,qBAAa,aAAc,YAAW,cAAc;IAShD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAT7B,gEAAgE;IAChE,OAAO,CAAC,UAAU,CAA6B;IAE/C,QAAQ,CAAC,SAAS,QAAO;IAEzB,mEAAmE;IACnE,uEAAuE;gBAEpD,MAAM,EAAE,cAAc,EACtB,UAAU,EAAE,iBAAiB;IAGhD,QAAQ,CAAC,QAAQ,WAAU;IAE3B,wEAAwE;YAC1D,MAAM;IAsDpB,iFAAiF;IACjF,OAAO,CAAC,iBAAiB;IAanB,WAAW,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAMxD,IAAI,CAAC,GAAG,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAmBpG,IAAI,CAAC,GAAG,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAexH,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC;IASzE,KAAK,CAAC,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC;IAKlG,IAAI,CAAC,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC;IAKhG,MAAM,CAAC,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC;IAKpG,GAAG,CAAC,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC;IAK9F,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAoB9C,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC;CAYlG"}

package/lib/types/platform/types.d.ts

@@ -24,6 +24,20 @@ export interface WindowRef {
     /** Owning process id. */
     processId?: number;
 }
+/** Which screen region a target-less capture covers. */
+export type ScreenScope = 'primary' | 'virtual';
+/** What a capture actually covered: one window, the primary screen, or the virtual desktop. */
+export type CaptureScope = 'window' | ScreenScope;
+/**
+ * Which helper path produced the pixels.
+ *
+ * `printwindow-fullcontent` is `PrintWindow(hwnd, hdc, PW_RENDERFULLCONTENT)`:
+ * the window paints itself, so the image does not depend on what is stacked on
+ * top of it. `printwindow` is the legacy flag-0 call (some old windows only
+ * paint through it). `copyfromscreen` is the last-resort screen-region copy and
+ * is only correct while the window is unobscured.
+ */
+export type CaptureMethod = 'printwindow-fullcontent' | 'printwindow' | 'copyfromscreen';
 /** Screen-space rectangle, integer pixel coordinates. */
 export interface Rect {
     x: number;
@@ -37,7 +51,14 @@ export interface WindowInfo {
     processId: number | null;
     title: string;
     className: string;
-    rect: Rect;
+    /**
+     * Physical screen rectangle, or `null` for a minimized window: Windows reports
+     * the `CW_USEDEFAULT` placeholder (`-32000,-32000 314x50`) while iconified,
+     * which must never reach coordinate math.
+     */
+    rect: Rect | null;
+    /** True while the window is iconified (`IsIconic`); such a window cannot be captured. */
+    minimized: boolean;
     executablePath: string | null;
     visible: boolean;
 }
@@ -90,8 +111,18 @@ export interface WindowSnapshot {
 export interface Screenshot {
     /** PNG bytes, base64-encoded. */
     pngBase64: string;
+    /**
+     * Bitmap width after the `maxSide` downscale. This is NOT the window width:
+     * `snapshot.rect` always carries the physical window/screen rectangle, so a
+     * screen-to-bitmap mapping is `bitmapX = (screenX - rect.x) * width / rect.width`.
+     */
     width: number;
+    /** Bitmap height after the `maxSide` downscale (see {@link width}). */
     height: number;
+    /** Which capture path produced the pixels. */
+    captureMethod: CaptureMethod;
+    /** What was captured. `virtual` is experimental (multi-monitor geometry untested). */
+    scope: CaptureScope;
     snapshot: WindowSnapshot;
 }
 /** An accessibility tree read plus pixel hints. */
@@ -169,8 +200,12 @@ export interface DesktopBackend {
     readonly unavailableReason?: string;
     /** List every visible top-level window across running applications. */
     listWindows(signal?: AbortSignal): Promise<WindowInfo[]>;
-    /** Capture a screenshot of the addressed window (or the primary screen). */
-    shot(ref: WindowRef, maxSide: number, signal?: AbortSignal): Promise<Screenshot>;
+    /**
+     * Capture a screenshot of the addressed window, or of a screen region when
+     * the ref names no window (the helper never substitutes the foreground
+     * window here; the primary screen is the target-less default).
+     */
+    shot(ref: WindowRef, maxSide: number, scope: ScreenScope, signal?: AbortSignal): Promise<Screenshot>;
     /** Read the accessibility tree plus pixel hints of the addressed window. */
     tree(ref: WindowRef, maxElements: number, maxDepth: number, includePixels: boolean, signal?: AbortSignal): Promise<Tree>;
     /** Re-capture fresh identity + hashes for one window (the stale check). */

package/lib/types/platform/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/platform/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/platform/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAEhD,iFAAiF;AACjF,qBAAa,aAAc,SAAQ,KAAK;IAGT,QAAQ,CAAC,IAAI,EAAE,MAAM;IAFlD,+DAA+D;IAC/D,4DAA4D;gBAChD,OAAO,EAAE,MAAM,EAAW,IAAI,EAAE,MAAM;CAInD;AAED,+DAA+D;AAC/D,MAAM,WAAW,SAAS;IACxB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,yBAAyB;IACzB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,wDAAwD;AACxD,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,SAAS,CAAA;AAE/C,+FAA+F;AAC/F,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,WAAW,CAAA;AAEjD;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GAAG,yBAAyB,GAAG,aAAa,GAAG,gBAAgB,CAAA;AAExF,yDAAyD;AACzD,MAAM,WAAW,IAAI;IACnB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAED,wCAAwC;AACxC,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB;;;;OAIG;IACH,IAAI,EAAE,IAAI,GAAG,IAAI,CAAA;IACjB,yFAAyF;IACzF,SAAS,EAAE,OAAO,CAAA;IAClB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,OAAO,EAAE,OAAO,CAAA;CACjB;AAED,4DAA4D;AAC5D,MAAM,WAAW,WAAW;IAC1B,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAA;IACjB,6CAA6C;IAC7C,WAAW,EAAE,MAAM,CAAA;IACnB,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAA;IACZ,uCAAuC;IACvC,YAAY,EAAE,MAAM,CAAA;IACpB,gDAAgD;IAChD,IAAI,EAAE,IAAI,CAAA;IACV,sCAAsC;IACtC,OAAO,EAAE,OAAO,CAAA;IAChB,mGAAmG;IACnG,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB;AAED,uEAAuE;AACvE,MAAM,WAAW,SAAS;IACxB,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAA;IACb,2BAA2B;IAC3B,CAAC,EAAE,MAAM,CAAA;IACT,2BAA2B;IAC3B,CAAC,EAAE,MAAM,CAAA;IACT,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAA;CACd;AAED,oFAAoF;AACpF,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,IAAI,CAAA;IACV,0DAA0D;IAC1D,UAAU,EAAE,OAAO,CAAA;IACnB,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,CAAA;IAChB,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAA;IAChB,iDAAiD;IACjD,YAAY,EAAE,MAAM,CAAA;CACrB;AAED,uEAAuE;AACvE,MAAM,WAAW,UAAU;IACzB,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAA;IACjB;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,uEAAuE;IACvE,MAAM,EAAE,MAAM,CAAA;IACd,8CAA8C;IAC9C,aAAa,EAAE,aAAa,CAAA;IAC5B,sFAAsF;IACtF,KAAK,EAAE,YAAY,CAAA;IACnB,QAAQ,EAAE,cAAc,CAAA;CACzB;AAED,mDAAmD;AACnD,MAAM,WAAW,IAAI;IACnB,QAAQ,EAAE,cAAc,CAAA;IACxB,QAAQ,EAAE,WAAW,EAAE,CAAA;IACvB,MAAM,EAAE,SAAS,EAAE,CAAA;CACpB;AAED,uCAAuC;AACvC,MAAM,WAAW,OAAO;IACtB,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,OAAO,EAAE,UAAU,EAAE,CAAA;CACtB;AAED,iEAAiE;AACjE,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,CAAC,CAAC,EAAE,MAAM,CAAA;IACV,CAAC,CAAC,EAAE,MAAM,CAAA;IACV,MAAM,EAAE,MAAM,GAAG,OAAO,CAAA;CACzB;AAED,2DAA2D;AAC3D,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,4EAA4E;IAC5E,QAAQ,EAAE,OAAO,CAAA;CAClB;AAED,wBAAwB;AACxB,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,IAAI,GAAG,MAAM,GAAG,SAAS,GAAG,WAAW,CAAA;IAClD,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAA;CACf;AAED,0DAA0D;AAC1D,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;CACb;AAED,6EAA6E;AAC7E,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAA;IAChB,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAA;IACd,wCAAwC;IACxC,SAAS,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAA;IACpC,aAAa,EAAE,YAAY,CAAA;IAC3B,YAAY,EAAE,YAAY,CAAA;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,gCAAgC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,4CAA4C;AAC5C,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAA;IACjB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,iFAAiF;IACjF,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,kDAAkD;IAClD,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAEnC,uEAAuE;IACvE,WAAW,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAA;IACxD;;;;OAIG;IACH,IAAI,CAAC,GAAG,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;IACpG,4EAA4E;IAC5E,IAAI,CAAC,GAAG,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACxH,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC,CAAA;IACzE,gDAAgD;IAChD,KAAK,CAAC,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;IAClG,yCAAyC;IACzC,IAAI,CAAC,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;IAChG,2CAA2C;IAC3C,MAAM,CAAC,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;IACpG,mDAAmD;IACnD,GAAG,CAAC,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;IAC9F,yCAAyC;IACzC,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAA;IAC9C,8CAA8C;IAC9C,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;CAC5F;AAED,iEAAiE;AACjE,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAA;IAChB,aAAa,EAAE,MAAM,CAAA;IACrB,SAAS,EAAE,MAAM,CAAA;IACjB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC9B;AAED,kFAAkF;AAClF,MAAM,MAAM,cAAc,GACtB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GAC7B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAA;AAE3D,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAM/F;AAED,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAM/F;AAED,+EAA+E;AAC/E,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAMhH;AAED,8EAA8E;AAC9E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAKrF;AAED,oFAAoF;AACpF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,GAAG,YAAY,CAW3E"}

package/lib/types/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAKlD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAG/C,OAAO,EAA0B,KAAK,WAAW,EAAE,KAAK,uBAAuB,EAAE,MAAM,mBAAmB,CAAA;AAC1G,OAAO,KAAK,EAAE,cAAc,EAA0B,IAAI,EAAyC,MAAM,qBAAqB,CAAA;AAE9H,wEAAwE;AACxE,MAAM,WAAW,YAAY;IAC3B,4BAA4B;IAC5B,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAA;IACrB,8BAA8B;IAC9B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;IAC/B,kCAAkC;IAClC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAA;IAChC,6BAA6B;IAC7B,QAAQ,CAAC,YAAY,EAAE,gBAAgB,CAAA;IACvC,2BAA2B;IAC3B,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAA;IAChC,0CAA0C;IAC1C,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAA;IACzB,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,EAAE,uBAAuB,CAAA;CAC5C;AAED,4EAA4E;AAC5E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,IAAI,EAAE,IAAI,CAAA;IACV,UAAU,EAAE,OAAO,CAAA;CACpB;AAyFD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,YAAY,mDAoIpD;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,YAAY,mDA+IpD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,YAAY,mDAsJpD;AAiED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,YAAY,mDAoD/C;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,YAAY,mDAyC9C;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,YAAY,mDA0ChD;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,QAAQ,EAAE,YAAY,mDAkC7C;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,YAAY,mDA+EjD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,YAAY,mDAwCnD;AAED,oDAAoD;AACpD,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,YAAY,qDAY9C"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAKlD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAG/C,OAAO,EAA0B,KAAK,WAAW,EAAE,KAAK,uBAAuB,EAAE,MAAM,mBAAmB,CAAA;AAC1G,OAAO,KAAK,EAAE,cAAc,EAA0B,IAAI,EAAyC,MAAM,qBAAqB,CAAA;AAE9H,wEAAwE;AACxE,MAAM,WAAW,YAAY;IAC3B,4BAA4B;IAC5B,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAA;IACrB,8BAA8B;IAC9B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;IAC/B,kCAAkC;IAClC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAA;IAChC,6BAA6B;IAC7B,QAAQ,CAAC,YAAY,EAAE,gBAAgB,CAAA;IACvC,2BAA2B;IAC3B,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAA;IAChC,0CAA0C;IAC1C,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAA;IACzB,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,EAAE,uBAAuB,CAAA;CAC5C;AAED,4EAA4E;AAC5E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,IAAI,EAAE,IAAI,CAAA;IACV,UAAU,EAAE,OAAO,CAAA;CACpB;AA0FD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,YAAY,mDAiJpD;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,YAAY,mDA+IpD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,YAAY,mDAsJpD;AAiED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,YAAY,mDAoD/C;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,YAAY,mDAyC9C;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,YAAY,mDA0ChD;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,QAAQ,EAAE,YAAY,mDAkC7C;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,YAAY,mDAuFjD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,YAAY,mDAwCnD;AAED,oDAAoD;AACpD,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,YAAY,qDAY9C"}

package/lib/types/version.d.ts

@@ -7,7 +7,7 @@
  * @module dsh-click/version
  */
 /** Plugin version advertised in the helper-protocol handshake. */
-export declare const VERSION = "0.3.28";
+export declare const VERSION = "0.3.29";
 /** The helper protocol revision; bump only on incompatible wire changes. */
 export declare const HELPER_PROTOCOL_VERSION = 1;
 //# sourceMappingURL=version.d.ts.map

package/native/win32/dsh-click-helper.ps1

@@ -1,4 +1,4 @@
-# dsh-click native helper (Windows PowerShell 5.1).
+# dsh-click native helper (Windows PowerShell 5.1).
 #
 # One request = one process: JSON request on stdin, JSON response on stdout
 # (exit code 0 even for handled failures; the error envelope is the response).
@@ -6,7 +6,8 @@
 # any other stream, and nothing here steals foreground focus unless the
 # `focusFallback` flag is explicitly true (config-gated, approval-gated).
 #
-# Operations: windows, apps, shot, tree, snapshot, click, type, scroll, key, launch.
+# Operations: windows, apps, metrics, shot, tree, snapshot, click, type, scroll,
+# key, launch.
 # The helper is NOT a security boundary by itself - the harness-side
 # freshness check, approval gate, and process-identity check are. This file
 # only refuses to invent global input: actions address one window by handle.
@@ -150,6 +151,13 @@ public static class DshClickWin32 {
   [DllImport("user32.dll")]
   public static extern int GetSystemMetrics(int index);
 
+  // PrintWindow: ask a window to paint itself into a DC. Flag 2 is
+  // PW_RENDERFULLCONTENT (Windows 8.1+), which makes DWM/DirectComposition
+  // windows render their real content instead of a blank or chrome-only
+  // frame; flag 0 is the legacy path for windows that ignore the newer flag.
+  [DllImport("user32.dll", SetLastError = true)]
+  public static extern bool PrintWindow(IntPtr hWnd, IntPtr hdcBlt, uint nFlags);
+
   // DPI awareness. The helper is hosted by powershell.exe, whose manifest
   // declares no DPI awareness, so GetWindowRect/GetSystemMetrics/GetClientRect
   // return logical pixels while UIA BoundingRectangle and the screen DC are
@@ -346,8 +354,9 @@ function Resolve-Window($target) {
   $hwnd = ConvertTo-Hwnd $target.windowId
   if ($hwnd -ne [IntPtr]::Zero) {
     $rect = Get-WindowRectInfo $hwnd
-    if ($rect.width -le 0 -and $rect.height -le 0) {
+    if ($rect.width -le 0 -or $rect.height -le 0) {
       # A handle that no longer resolves to a window.
+      $script:ErrorCode = 'WINDOW_NOT_FOUND'
       throw "window $($target.windowId) not found"
     }
     return $hwnd
@@ -357,6 +366,7 @@ function Resolve-Window($target) {
     foreach ($candidate in [DshClickWin32]::EnumVisibleWindows()) {
       if ([DshClickWin32]::WindowTitle($candidate) -like "*$title*") { return $candidate }
     }
+    $script:ErrorCode = 'WINDOW_NOT_FOUND'
     throw "no visible window matches title '$title'"
   }
   $processId = $target.processId
@@ -366,13 +376,41 @@ function Resolve-Window($target) {
       [void][DshClickWin32]::GetWindowThreadProcessId($candidate, [ref]$pidValue)
       if ([int]$pidValue -eq [int]$processId) { return $candidate }
     }
+    $script:ErrorCode = 'WINDOW_NOT_FOUND'
     throw "no visible window owned by process $processId"
   }
   $foreground = [DshClickWin32]::GetForegroundWindow()
-  if ($foreground -eq [IntPtr]::Zero) { throw 'no foreground window and no target given' }
+  if ($foreground -eq [IntPtr]::Zero) {
+    $script:ErrorCode = 'WINDOW_NOT_FOUND'
+    throw 'no foreground window and no target given'
+  }
   return $foreground
 }
 
+# One target resolver for the observer ops. `tree`/`shot` always read
+# `args.target`; `snapshot` historically read `args.windowId`. Both spellings
+# now go through here, so `{"op":"snapshot","args":{"target":{"windowId":N}}}`
+# addresses window N instead of silently falling back to the foreground window.
+# `args.target` wins when both are present; the legacy top-level `windowId` is
+# only a fallback, so old callers keep working.
+function Resolve-OpTarget($opArgs) {
+  $target = @{}
+  if ($opArgs.target -ne $null) {
+    $candidate = $opArgs.target
+    if ($candidate.windowId -ne $null) { $target.windowId = $candidate.windowId }
+    if ($candidate.windowTitle -ne $null) { $target.windowTitle = $candidate.windowTitle }
+    if ($candidate.processId -ne $null) { $target.processId = $candidate.processId }
+  }
+  if ($target.windowId -eq $null -and $target.windowTitle -eq $null -and $target.processId -eq $null) {
+    if ($opArgs.windowId -ne $null) { $target.windowId = $opArgs.windowId }
+  }
+  return $target
+}
+
+function Test-TargetPresent($target) {
+  return ($target.windowId -ne $null) -or ($target.windowTitle -ne $null) -or ($target.processId -ne $null)
+}
+
 # ---------------------------------------------------------------------------
 # Accessibility walk (canonical: the same walk builds treeHash everywhere).
 # ---------------------------------------------------------------------------
@@ -458,30 +496,214 @@ function Get-TreeHashText($nodes) {
 # ---------------------------------------------------------------------------
 # Screenshot.
 # ---------------------------------------------------------------------------
-function Get-WindowBitmap($hwnd) {
+# A window is captured in three steps, best first:
+#   1. PrintWindow(hwnd, hdc, 2)  PW_RENDERFULLCONTENT - the window paints its
+#      own content, so identity and pixels do not depend on occlusion/Z-order.
+#   2. PrintWindow(hwnd, hdc, 0)  legacy windows that ignore the newer flag.
+#   3. CopyFromScreen             last resort; correct only while unobscured.
+# PrintWindow reports success for frames that carry no content at all (a blank
+# Electron frame, or a Chromium window that paints only its title-bar buttons),
+# so every candidate goes through Test-BitmapLooksBlank before it is accepted.
+# Measured on Windows 11: PW(2) carries content for WinUI3/Electron/Chromium;
+# PW(0/1) is blank or chrome-only for the latter two. The thresholds below are
+# fitted to that matrix: a pure-color check alone is fooled by a gray frame with
+# three title-bar buttons, so the color-count floor is 6 quantized colors.
+$script:CaptureInset = 40       # px trimmed from each edge before sampling
+$script:CaptureGrid = 16        # interior sample grid (16x16)
+$script:CaptureDarkGrid = 32    # full-frame sample grid for the dark-ratio test
+
+function Get-BitmapLuminance($color) {
+  return (0.299 * [double]$color.R) + (0.587 * [double]$color.G) + (0.114 * [double]$color.B)
+}
+
+# True when a captured frame carries no usable content: a flat interior, an
+# almost entirely black frame, or (on the no-flag PrintWindow path only) a few
+# flat colors with chrome painted in a corner.
+#
+# The color-count rule is `strict` because a legitimate all-white page can also
+# sample as 3 quantized colors: measured on a 2582x1550 Chrome new-tab window,
+# PrintWindow(2) gives 3 colors but a luminance sd of 9.6, while the chrome-only
+# frame the no-flag path paints on Chromium gives 4-5 colors with sd 13-14. The
+# two are indistinguishable by color count alone, so the count rule is applied
+# only where chrome-only frames are known to come from (PrintWindow flag 0).
+# A blank all-black frame is caught on every path by the sd/dark-ratio rules.
+function Test-BitmapLooksBlank($bitmap, $strict) {
+  if ($null -eq $bitmap -or $bitmap.Width -le 0 -or $bitmap.Height -le 0) { return $true }
+  $width = $bitmap.Width
+  $height = $bitmap.Height
+
+  # Interior region: drop the outer band (border, shadow, title-bar buttons)
+  # where a failed PrintWindow can still paint a plausible-looking frame.
+  $insetX = [Math]::Min($script:CaptureInset, [int][Math]::Floor(($width - 1) / 2))
+  $insetY = [Math]::Min($script:CaptureInset, [int][Math]::Floor(($height - 1) / 2))
+  $left = $insetX
+  $top = $insetY
+  $right = $width - 1 - $insetX
+  $bottom = $height - 1 - $insetY
+  if (($right - $left) -lt 8 -or ($bottom - $top) -lt 8) {
+    # Tiny window: the inset leaves nothing to sample, so use the full frame.
+    $left = 0; $top = 0; $right = $width - 1; $bottom = $height - 1
+  }
+  $spanX = [Math]::Max(1, $right - $left)
+  $spanY = [Math]::Max(1, $bottom - $top)
+  $stepX = [Math]::Max(1, [int][Math]::Ceiling($spanX / $script:CaptureGrid))
+  $stepY = [Math]::Max(1, [int][Math]::Ceiling($spanY / $script:CaptureGrid))
+
+  $colors = @{}
+  $sum = 0.0
+  $sumSquares = 0.0
+  $count = 0
+  for ($x = $left; $x -le $right; $x += $stepX) {
+    for ($y = $top; $y -le $bottom; $y += $stepY) {
+      $color = $bitmap.GetPixel($x, $y)
+      # 5-bit quantization: UI colors cluster, and an exact ARGB count is both
+      # noisy and slower than needed for a blank/non-blank verdict.
+      $key = ([int]($color.R -band 0xF8) -shl 16) -bor ([int]($color.G -band 0xF8) -shl 8) -bor [int]($color.B -band 0xF8)
+      $colors[$key] = $true
+      $luminance = Get-BitmapLuminance $color
+      $sum += $luminance
+      $sumSquares += $luminance * $luminance
+      $count += 1
+    }
+  }
+  if ($count -eq 0) { return $true }
+  $mean = $sum / $count
+  $variance = [Math]::Max(0.0, ($sumSquares / $count) - ($mean * $mean))
+  $deviation = [Math]::Sqrt($variance)
+  if ($deviation -lt 2) { return $true }
+  if ($strict -and $colors.Count -le 6) { return $true }
+
+  # Full-frame dark ratio: a PrintWindow frame that painted nothing at all.
+  $dark = 0
+  $samples = 0
+  $darkStepX = [Math]::Max(1, [int][Math]::Ceiling($width / $script:CaptureDarkGrid))
+  $darkStepY = [Math]::Max(1, [int][Math]::Ceiling($height / $script:CaptureDarkGrid))
+  for ($x = 0; $x -lt $width; $x += $darkStepX) {
+    for ($y = 0; $y -lt $height; $y += $darkStepY) {
+      if ((Get-BitmapLuminance $bitmap.GetPixel($x, $y)) -lt 8) { $dark += 1 }
+      $samples += 1
+    }
+  }
+  if ($samples -gt 0 -and (($dark * 100) -ge (99 * $samples))) { return $true }
+  return $false
+}
+
+function New-CaptureBitmap($width, $height) {
+  if ($width -le 0 -or $height -le 0) { throw "cannot allocate a ${width}x${height} capture bitmap" }
+  return New-Object System.Drawing.Bitmap($width, $height)
+}
+
+# One PrintWindow attempt; returns $null when the API refuses, otherwise the
+# bitmap (which may still be blank - the caller decides).
+function Get-PrintWindowFrame($hwnd, $rectInfo, $flags) {
+  $bitmap = New-CaptureBitmap $rectInfo.width $rectInfo.height
+  $graphics = [System.Drawing.Graphics]::FromImage($bitmap)
+  $hdc = [IntPtr]::Zero
+  $painted = $false
+  try {
+    $hdc = $graphics.GetHdc()
+    $painted = [DshClickWin32]::PrintWindow($hwnd, $hdc, [uint32]$flags)
+  } catch {
+    $painted = $false
+  } finally {
+    if ($hdc -ne [IntPtr]::Zero) {
+      try { $graphics.ReleaseHdc($hdc) } catch { }
+    }
+    $graphics.Dispose()
+  }
+  if (-not $painted) {
+    $bitmap.Dispose()
+    return $null
+  }
+  return $bitmap
+}
+
+# Capture one window: returns @{ bitmap; method; rect }. The caller owns the
+# bitmap and must dispose it. Minimized windows are refused up front: IsIconic
+# windows report a placeholder rect, and PrintWindow paints only the small
+# window-icon band even when it answers true, so there is no honest image.
+function Get-WindowCapture($hwnd) {
   $rectInfo = Get-WindowRectInfo $hwnd
-  if ($rectInfo.width -le 0 -or $rectInfo.height -le 0) { throw "window $hwnd has no drawable rect" }
-  $bitmap = New-Object System.Drawing.Bitmap($rectInfo.width, $rectInfo.height)
+  if ($rectInfo.width -le 0 -or $rectInfo.height -le 0) {
+    $script:ErrorCode = 'WINDOW_NOT_FOUND'
+    throw "window $hwnd has no drawable rect"
+  }
+  if ([DshClickWin32]::IsIconic($hwnd)) {
+    $script:ErrorCode = 'WINDOW_MINIMIZED'
+    throw "window $hwnd is minimized; a minimized window has no capturable pixels - restore it, then re-observe"
+  }
+
+  $candidate = Get-PrintWindowFrame $hwnd $rectInfo 2   # PW_RENDERFULLCONTENT
+  if ($candidate -ne $null) {
+    if (-not (Test-BitmapLooksBlank $candidate $false)) {
+      return @{ bitmap = $candidate; method = 'printwindow-fullcontent'; rect = $rectInfo }
+    }
+    $candidate.Dispose()
+  }
+  $candidate = Get-PrintWindowFrame $hwnd $rectInfo 0   # legacy PrintWindow
+  if ($candidate -ne $null) {
+    if (-not (Test-BitmapLooksBlank $candidate $true)) {
+      return @{ bitmap = $candidate; method = 'printwindow'; rect = $rectInfo }
+    }
+    $candidate.Dispose()
+  }
+
+  # Screen-region copy: the old path, kept for windows that refuse PrintWindow.
+  $bitmap = New-CaptureBitmap $rectInfo.width $rectInfo.height
   $graphics = [System.Drawing.Graphics]::FromImage($bitmap)
   try {
     $graphics.CopyFromScreen($rectInfo.x, $rectInfo.y, 0, 0, (New-Object System.Drawing.Size($rectInfo.width, $rectInfo.height)))
+  } catch {
+    $bitmap.Dispose()
+    throw
   } finally {
     $graphics.Dispose()
   }
-  return $bitmap
+  return @{ bitmap = $bitmap; method = 'copyfromscreen'; rect = $rectInfo }
 }
 
-function Get-PrimaryBitmap() {
-  $width = [DshClickWin32]::GetSystemMetrics(0)   # SM_CXSCREEN
-  $height = [DshClickWin32]::GetSystemMetrics(1)  # SM_CYSCREEN
-  $bitmap = New-Object System.Drawing.Bitmap($width, $height)
+# Resolve the requested screen rectangle. `virtual` is the whole desktop
+# (negative origins on multi-monitor setups) and stays experimental: only the
+# single-monitor case is covered by the verification runs, and BitBlt across
+# negative virtual-screen coordinates is untested here. If the virtual metrics
+# are unusable, fall back to the primary screen rather than failing the call.
+function Get-ScreenMetrics($scope) {
+  if ($scope -eq 'virtual') {
+    $virtualX = [int][DshClickWin32]::GetSystemMetrics(76)      # SM_XVIRTUALSCREEN
+    $virtualY = [int][DshClickWin32]::GetSystemMetrics(77)      # SM_YVIRTUALSCREEN
+    $virtualWidth = [int][DshClickWin32]::GetSystemMetrics(78)  # SM_CXVIRTUALSCREEN
+    $virtualHeight = [int][DshClickWin32]::GetSystemMetrics(79) # SM_CYVIRTUALSCREEN
+    if ($virtualWidth -gt 0 -and $virtualHeight -gt 0) {
+      return @{ scope = 'virtual'; x = $virtualX; y = $virtualY; width = $virtualWidth; height = $virtualHeight }
+    }
+  }
+  return @{
+    scope = 'primary'; x = 0; y = 0
+    width = [int][DshClickWin32]::GetSystemMetrics(0)   # SM_CXSCREEN
+    height = [int][DshClickWin32]::GetSystemMetrics(1)  # SM_CYSCREEN
+  }
+}
+
+# Capture a screen region: returns @{ bitmap; method; scope; rect }.
+function Get-ScreenCapture($scope) {
+  $metrics = Get-ScreenMetrics $scope
+  if ($metrics.width -le 0 -or $metrics.height -le 0) { throw 'the screen reports no drawable area' }
+  $bitmap = New-CaptureBitmap $metrics.width $metrics.height
   $graphics = [System.Drawing.Graphics]::FromImage($bitmap)
   try {
-    $graphics.CopyFromScreen(0, 0, 0, 0, (New-Object System.Drawing.Size($width, $height)))
+    $graphics.CopyFromScreen($metrics.x, $metrics.y, 0, 0, (New-Object System.Drawing.Size($metrics.width, $metrics.height)))
+  } catch {
+    $bitmap.Dispose()
+    throw
   } finally {
     $graphics.Dispose()
   }
-  return $bitmap
+  return @{
+    bitmap = $bitmap
+    method = 'copyfromscreen'
+    scope = $metrics.scope
+    rect = @{ x = $metrics.x; y = $metrics.y; width = $metrics.width; height = $metrics.height }
+  }
 }
 
 function Resize-BitmapIfNeeded($bitmap, $maxSide) {
@@ -651,12 +873,17 @@ function Invoke-OpWindows {
   foreach ($hwnd in [DshClickWin32]::EnumVisibleWindows()) {
     $pidValue = 0
     [void][DshClickWin32]::GetWindowThreadProcessId($hwnd, [ref]$pidValue)
+    # A minimized window still enumerates, but GetWindowRect then returns the
+    # CW_USEDEFAULT placeholder (-32000,-32000 314x50). Report the state and
+    # suppress the placeholder rect instead of handing it to coordinate math.
+    $minimized = [DshClickWin32]::IsIconic($hwnd)
     $windows += @{
       windowId = [int64]$hwnd
       processId = if ([int]$pidValue -gt 0) { [int]$pidValue } else { $null }
       title = [DshClickWin32]::WindowTitle($hwnd)
       className = [DshClickWin32]::WindowClass($hwnd)
-      rect = (Get-WindowRectInfo $hwnd)
+      rect = if ($minimized) { $null } else { Get-WindowRectInfo $hwnd }
+      minimized = $minimized
       executablePath = $null
       visible = $true
     }
@@ -682,12 +909,14 @@ function Invoke-OpApps {
     $pidInt = [int]$pidValue
     if ($pidInt -le 0) { continue }
     if (-not $byPid.ContainsKey($pidInt)) { $byPid[$pidInt] = @() }
+    $minimized = [DshClickWin32]::IsIconic($hwnd)
     $byPid[$pidInt] += @{
       windowId = [int64]$hwnd
       processId = $pidInt
       title = [DshClickWin32]::WindowTitle($hwnd)
       className = [DshClickWin32]::WindowClass($hwnd)
-      rect = (Get-WindowRectInfo $hwnd)
+      rect = if ($minimized) { $null } else { Get-WindowRectInfo $hwnd }
+      minimized = $minimized
       executablePath = $null
       visible = $true
     }
@@ -712,91 +941,129 @@ function Invoke-OpApps {
   return $apps
 }
 
-function Get-SnapshotRecord($hwnd, $maxElements, $maxDepth) {
-  $facts = Get-ProcessFacts $hwnd
-  $rect = Get-WindowRectInfo $hwnd
-  $foreground = ([DshClickWin32]::GetForegroundWindow() -eq $hwnd)
-  $script:TreeNodes = @()
-  $element = Get-UiaElement $hwnd
-  Walk-UiaTree $element 0 $maxDepth $maxElements $false
-  $treeHash = Get-StringHash (Get-TreeHashText $script:TreeNodes)
-  $bitmap = Get-WindowBitmap $hwnd
-  $shotHash = $null
+function Get-SnapshotRecord($hwnd, $maxElements, $maxDepth, $capture) {
+  $ownsCapture = $false
+  if ($null -eq $capture) {
+    $capture = Get-WindowCapture $hwnd
+    $ownsCapture = $true
+  }
   try {
-    $shotHash = Get-BitmapHash $bitmap
+    $facts = Get-ProcessFacts $hwnd
+    $rect = Get-WindowRectInfo $hwnd
+    $foreground = ([DshClickWin32]::GetForegroundWindow() -eq $hwnd)
+    $script:TreeNodes = @()
+    $element = Get-UiaElement $hwnd
+    Walk-UiaTree $element 0 $maxDepth $maxElements $false
+    $treeHash = Get-StringHash (Get-TreeHashText $script:TreeNodes)
+    # The hash is taken from the same frame the caller will ship as the
+    # screenshot (or compare later), not from a second capture: two captures
+    # can disagree on a busy window and on which capture path succeeded.
+    $shotHash = Get-BitmapHash $capture.bitmap
+    return @{
+      windowId = [int64]$hwnd
+      processId = $facts.pid
+      executablePath = $facts.executablePath
+      title = [DshClickWin32]::WindowTitle($hwnd)
+      className = [DshClickWin32]::WindowClass($hwnd)
+      rect = $rect
+      foreground = $foreground
+      treeHash = $treeHash
+      shotHash = $shotHash
+      elementCount = $script:TreeNodes.Count
+    }
   } finally {
-    $bitmap.Dispose()
-  }
-  return @{
-    windowId = [int64]$hwnd
-    processId = $facts.pid
-    executablePath = $facts.executablePath
-    title = [DshClickWin32]::WindowTitle($hwnd)
-    className = [DshClickWin32]::WindowClass($hwnd)
-    rect = $rect
-    foreground = $foreground
-    treeHash = $treeHash
-    shotHash = $shotHash
-    elementCount = $script:TreeNodes.Count
+    if ($ownsCapture) { $capture.bitmap.Dispose() }
   }
 }
 
 function Invoke-OpSnapshot($opArgs) {
-  $hwnd = Resolve-Window @{ windowId = $opArgs.windowId }
+  $target = Resolve-OpTarget $opArgs
+  if (-not (Test-TargetPresent $target)) {
+    # This used to fall back to the foreground window without saying so, which
+    # reported a different window than the caller asked for. Refuse instead.
+    $script:ErrorCode = 'NO_TARGET'
+    throw 'snapshot requires windowId or target; it never guesses the foreground window'
+  }
+  $hwnd = Resolve-Window $target
   $maxElements = if ($opArgs.maxElements -ne $null) { [int]$opArgs.maxElements } else { 500 }
   $maxDepth = if ($opArgs.maxDepth -ne $null) { [int]$opArgs.maxDepth } else { 32 }
-  return (Get-SnapshotRecord $hwnd $maxElements $maxDepth)
+  $capture = Get-WindowCapture $hwnd
+  try {
+    return (Get-SnapshotRecord $hwnd $maxElements $maxDepth $capture)
+  } finally {
+    $capture.bitmap.Dispose()
+  }
 }
 
 function Invoke-OpShot($opArgs) {
-  $target = if ($opArgs.target -ne $null) { $opArgs.target } else { @{} }
+  $target = Resolve-OpTarget $opArgs
+  $scope = if ($opArgs.scope -ne $null) { [string]$opArgs.scope } else { 'primary' }
+  if ($scope -ne 'primary' -and $scope -ne 'virtual') {
+    $script:ErrorCode = 'INVALID_SCOPE'
+    throw "unknown scope '$scope' (expected 'primary' or 'virtual')"
+  }
   $maxSide = if ($opArgs.maxSide -ne $null) { [int]$opArgs.maxSide } else { 2560 }
   $maxElements = if ($opArgs.maxElements -ne $null) { [int]$opArgs.maxElements } else { 500 }
   $maxDepth = if ($opArgs.maxDepth -ne $null) { [int]$opArgs.maxDepth } else { 32 }
-  $hasTarget = ($target.windowId -ne $null) -or ($target.windowTitle -ne $null) -or ($target.processId -ne $null)
-  if ($hasTarget) {
-    $hwnd = Resolve-Window $target
-    $bitmap = Get-WindowBitmap $hwnd
-    $snapshot = Get-SnapshotRecord $hwnd $maxElements $maxDepth
-  } else {
-    $hwnd = $null
-    $bitmap = Get-PrimaryBitmap
-    $snapshot = @{
-      windowId = 0; processId = 0; executablePath = $null
-      title = 'primary screen'; className = 'Screen'
-      rect = @{ x = 0; y = 0; width = $bitmap.Width; height = $bitmap.Height }
-      foreground = $true; treeHash = ''; shotHash = ''; elementCount = 0
-    }
-  }
+  $capture = $null
+  $bitmap = $null
   try {
-    $bitmap = Resize-BitmapIfNeeded $bitmap $maxSide
+    if (Test-TargetPresent $target) {
+      $hwnd = Resolve-Window $target
+      $capture = Get-WindowCapture $hwnd
+      $captureScope = 'window'
+      $snapshot = Get-SnapshotRecord $hwnd $maxElements $maxDepth $capture
+    } else {
+      # No target means the screen, not the foreground window: the result says
+      # `scope: primary` and its snapshot is titled "primary screen" (windowId 0).
+      $capture = Get-ScreenCapture $scope
+      $captureScope = $capture.scope
+      $snapshot = @{
+        windowId = 0; processId = 0; executablePath = $null
+        title = if ($capture.scope -eq 'virtual') { 'virtual screen' } else { 'primary screen' }
+        className = 'Screen'
+        rect = $capture.rect
+        foreground = $true; treeHash = ''; shotHash = ''; elementCount = 0
+      }
+    }
+    $bitmap = $capture.bitmap
+    if ([Math]::Max($bitmap.Width, $bitmap.Height) -gt $maxSide) {
+      # Resize-BitmapIfNeeded disposes the original; the finally below disposes
+      # whichever bitmap is current, and Dispose is idempotent.
+      $bitmap = Resize-BitmapIfNeeded $capture.bitmap $maxSide
+    }
     $base64 = Get-BitmapBase64 $bitmap
     return @{
       pngBase64 = $base64
       width = $bitmap.Width
       height = $bitmap.Height
+      captureMethod = $capture.method
+      scope = $captureScope
       snapshot = $snapshot
     }
   } finally {
-    $bitmap.Dispose()
+    if ($null -ne $bitmap) { $bitmap.Dispose() }
+    elseif ($null -ne $capture) { $capture.bitmap.Dispose() }
   }
 }
 
 function Invoke-OpTree($opArgs) {
-  $target = if ($opArgs.target -ne $null) { $opArgs.target } else { @{} }
+  $target = Resolve-OpTarget $opArgs
   $maxElements = if ($opArgs.maxElements -ne $null) { [int]$opArgs.maxElements } else { 500 }
   $maxDepth = if ($opArgs.maxDepth -ne $null) { [int]$opArgs.maxDepth } else { 32 }
   $includePixels = if ($opArgs.includePixels -ne $null) { [bool]$opArgs.includePixels } else { $true }
+  # An empty target still means the foreground window here (documented for
+  # screen_read); only `snapshot` refuses the guess.
   $hwnd = Resolve-Window $target
-  $snapshot = Get-SnapshotRecord $hwnd $maxElements $maxDepth
-  $script:TreeNodes = @()
-  $element = Get-UiaElement $hwnd
-  Walk-UiaTree $element 0 $maxDepth $maxElements $includePixels
-  $pixels = @()
-  if ($includePixels) {
-    $bitmap = Get-WindowBitmap $hwnd
-    try {
-      $rectInfo = Get-WindowRectInfo $hwnd
+  $capture = Get-WindowCapture $hwnd
+  try {
+    $snapshot = Get-SnapshotRecord $hwnd $maxElements $maxDepth $capture
+    $script:TreeNodes = @()
+    $element = Get-UiaElement $hwnd
+    Walk-UiaTree $element 0 $maxDepth $maxElements $includePixels
+    $pixels = @()
+    if ($includePixels) {
+      $rectInfo = $capture.rect
       $count = 0
       foreach ($node in $script:TreeNodes) {
         if ($count -ge 200) { break }
@@ -804,21 +1071,21 @@ function Invoke-OpTree($opArgs) {
         if ($r.width -le 0 -or $r.height -le 0) { continue }
         $cx = $r.x + [int]($r.width / 2) - $rectInfo.x
         $cy = $r.y + [int]($r.height / 2) - $rectInfo.y
-        $color = Get-PixelColorText $bitmap $cx $cy
+        $color = Get-PixelColorText $capture.bitmap $cx $cy
         if ($color -ne $null) {
           $label = if ($node.name -ne '') { $node.name } else { "$($node.controlType)[$($node.elementId)]" }
           $pixels += @{ label = $label; x = $r.x + [int]($r.width / 2); y = $r.y + [int]($r.height / 2); color = $color }
           $count += 1
         }
       }
-    } finally {
-      $bitmap.Dispose()
     }
-  }
-  return @{
-    snapshot = $snapshot
-    elements = @($script:TreeNodes)
-    pixels = $pixels
+    return @{
+      snapshot = $snapshot
+      elements = @($script:TreeNodes)
+      pixels = $pixels
+    }
+  } finally {
+    $capture.bitmap.Dispose()
   }
 }
 
@@ -1045,6 +1312,9 @@ try {
   # Per-request focus-fallback verdict (set by Set-DshFocusFallback, consumed by
   # Get-ActionOutcome); one helper process serves exactly one request.
   $script:focusFallbackDetail = $null
+  # Per-request failure code; a plain `throw` still defaults to HELPER_ERROR,
+  # while the capture/scope guards set a precise code for the caller.
+  $script:ErrorCode = $null
   switch ([string]$request.op) {
     'windows' { $result = Invoke-OpWindows }
     'metrics' { $result = Invoke-OpMetrics }
@@ -1064,6 +1334,7 @@ try {
 } catch {
   $message = $_.Exception.Message
   if ($message -eq $null -or $message.Length -eq 0) { $message = 'unknown helper failure' }
-  Write-DshError 'HELPER_ERROR' $message
+  $code = if ($script:ErrorCode -ne $null -and [string]$script:ErrorCode -ne '') { [string]$script:ErrorCode } else { 'HELPER_ERROR' }
+  Write-DshError $code $message
   exit 0
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-click",
-  "version": "0.3.28",
+  "version": "0.3.29",
   "description": "Cross-platform native desktop control tools for DeepSeek Harness (Windows first): screen_shot, screen_read (accessibility tree + pixel description for text-only models), click/type/scroll/key, and app_list/app_launch — every mutating action gated by approval, never stealing foreground focus, with stale-observation rejection and process-identity checks",
   "repository": {
     "type": "git",