agent-desktop/docs/solutions/best-practices
Lahfir 3f322728b4
feat!: implement Playwright-grade foundation contract
Settle the Playwright-grade reliability contract in agent-desktop-core
before the Windows/Linux adapters are built, so they inherit it instead
of redesigning it. Every command now observes, waits, verifies, and
reports honestly instead of firing blindly.

Highlights: capability-supertrait split of PlatformAdapter with
not_supported() defaults; canonical role/state vocabulary with live
`is --property visible`; display enumeration (`list-displays`) and honest
`--screen` with scale factor; truthful Automation permission; `native_id`
identity spine; window-id-first resolution; serializable `LocatorQuery`
with live `find`; default-on auto-wait before every ref action; three-way
`hit_test` occlusion gate; `scroll_into_view` in core; core accessible-name
precedence; typed `ActionStep` delivery tier; `ProcessState` and
`APP_UNRESPONSIVE`; `LaunchOptions`; baseline-diff desktop signals
(`wait --event`); typed clipboard (`Text`/`Image`/`FileUrls`); mouse
modifier chords and `mouse-wheel`. Hardened through a 35-reviewer pass with
independent validation and a green live e2e gate (109/0), plus a
head-vs-main performance comparison harness.

BREAKING CHANGE: default-on auto-wait changes the timing of every
previously-untouched ref-action call (bounded 5000 ms default; `--timeout-ms 0`
restores single-shot). `ENVELOPE_VERSION` is now `2.1` (adds the
`APP_UNRESPONSIVE` code and process state in error details). FFI ABI major
is `3` (append-only struct evolution; `wait --event` is intentionally not
exposed over FFI). The legacy string clipboard API is removed in favor of
typed content. `key-down`/`key-up` fail closed until daemon-owned held input
exists. `close-app` verifies termination and the osascript fallback path is
removed. `--text` matching is subtree containment: `find --text X --first`
returns the outermost matching container.
2026-07-20 00:21:38 -07:00
..
abort-state-guidance-multi-step-physical-input.md feat!: implement Playwright-grade foundation contract 2026-07-20 00:21:38 -07:00
deduplicate-ref-allocator-via-config-struct-2026-04-14.md feat!: implement Playwright-grade foundation contract 2026-07-20 00:21:38 -07:00
envelope-version-bump-contract-2026-05-13.md feat!: implement Playwright-grade foundation contract 2026-07-20 00:21:38 -07:00
exhaustiveness-guards-over-catch-alls-in-policy-mirrors.md feat!: implement Playwright-grade foundation contract 2026-07-20 00:21:38 -07:00
ffi-repr-c-struct-size-pinning.md feat!: implement Playwright-grade foundation contract 2026-07-20 00:21:38 -07:00
identity-fingerprint-against-os-reorder-2026-04-16.md feat!: implement Playwright-grade foundation contract 2026-07-20 00:21:38 -07:00
keep-ffi-action-policy-aligned-with-cli-2026-05-12.md feat!: implement Playwright-grade foundation contract 2026-07-20 00:21:38 -07:00
macos-gesture-headless-capability-2026-06-10.md feat!: implement Playwright-grade foundation contract 2026-07-20 00:21:38 -07:00
playwright-grade-desktop-reliability-2026-06-02.md feat!: implement Playwright-grade foundation contract 2026-07-20 00:21:38 -07:00
preserve-command-policy-semantics-during-refactor-2026-05-12.md feat!: implement Playwright-grade foundation contract 2026-07-20 00:21:38 -07:00
real-app-tests-are-the-platform-adapter-gate.md feat!: implement Playwright-grade foundation contract 2026-07-20 00:21:38 -07:00