feat: merge AT-SPI targeting and delay post-action screenshots

README.md

@@ -84,7 +84,44 @@ Other action examples:
 }
 ```
 
-Use coordinates from your own screenshot, not these example coordinates. `expectedSize` is optional and rejects input if the screen size changed. Supported actions are click, scroll, keys, text, and wait. Drag is deferred. Actions are serialized by a VM-side lock; avoid manual interaction while a request runs. The full request is validated before any actions execute, but runtime failures can still leave partial effects.
+Use coordinates from your own screenshot, not these example coordinates. `expectedSize` is optional and rejects input if the screen size changed. Supported actions are click, click_target, scroll, keys, text, and wait. Drag is deferred. Actions are serialized by a VM-side lock; avoid manual interaction while a request runs. The full request is validated before any actions execute, but runtime failures can still leave partial effects.
+
+After a non-empty action batch, the helper waits **500 ms** before taking the resulting screenshot and scanning accessibility targets. Capture-only requests have no added delay. This allows ordinary UI updates to paint; slow loads still need an explicit wait or another observation.
+
+## AT-SPI numbered targets
+
+Install the accessibility bindings inside `home`:
+
+```sh
+sudo pacman -S --needed at-spi2-core python-atspi
+```
+
+Enable **Settings → Accessibility → Enable assistive technologies** in XFCE if disabled, then log out/in and reopen applications. The helper must use the graphical session's D-Bus address; session registration captures it automatically.
+
+Rebuild and reinstall from berlin:
+
+```sh
+npm run build
+npm run home -- install home
+npm run home -- capture home artifacts/targets.png
+```
+
+Focus Mousepad or another GTK application before capturing. The PNG has magenta element bounds and yellow numbered labels; an unmarked original is saved as `artifacts/targets.png.raw.png`. CLI output includes `targets`, `observationId`, and any accessibility warning. Only actionable, enabled, showing elements in active accessible windows are included. There are traversal, target-count, and three-second collection limits. Missing support or timeouts leave pixel interaction available. This does not add OCR or infer targets from image content.
+
+To click a label, copy the actual ID and observation ID into an action file:
+
+```json
+{
+    "actions": [
+        {"type": "click_target", "target": "3", "observationId": "COPY-FROM-CAPTURE"},
+        {"type": "text", "text": "Hello from an accessibility target"}
+    ]
+}
+```
+
+A target click must be first, and only one is allowed per request. The helper checks it against the latest capture and a fresh accessibility scan (application/path, name, role, and bounds) before clicking its center. Any intervening capture invalidates earlier IDs. This detects many stale targets, but is not an atomic guarantee against moving UI or occlusion. For small, overlapping, or poorly exposed elements, use a fresh screenshot and coordinate clicks in the configured coordinate space instead. AT-SPI target IDs always resolve directly to pixels, regardless of `DESKTOP_COORDINATE_SPACE`; target bounds are reported in pixels. Avoid changing windows manually while the model operates.
+
+The model receives annotated screenshots and a text list of targets. Original images are retained beside the annotated run artifacts. Targets depend on the application's accessibility support: games, launchers, menus, and custom interfaces may expose none. Start testing with a focused editor, then try the launcher/browser. If a normal editor shows no targets, check accessibility settings, restart the app, and re-register the graphical session.
 
 ## Try shell execution