Record what shipped, and the one thing deliberately left

WHATS_NEW and both translations describe the six phases; CHANGELOG records
the compatibility-visible parts — the window backends, the AT-SPI backend,
platform_id, the new exception class and the D-Bus client's move.

Progress.md gains the macOS recorder: OSXRecorder is a complete
implementation that the platform wrapper never selects, and that is not an
oversight. osx_listener builds an NSApplication at import time and stopping a
recording needs a blocking run loop, so wiring it up as it stands would move
both onto the import path of the whole package. The capability matrix already
says 'unavailable', which matches.

Author: JE-Chen

CHANGELOG.md

@@ -10,6 +10,25 @@ only when documented here with a migration path.
 
 ### Added
 
+- Cross-platform window management. The 23 `AC_*` window commands and their
+  MCP tools now work on macOS and Linux/X11 as well as Windows, through a
+  backend seam (`je_auto_control.wrapper.window_backends`). Wayland remains
+  unsupported: the protocol does not let a client enumerate or move another
+  application's windows.
+- Linux accessibility backend over AT-SPI2
+  (`je_auto_control.utils.accessibility.backends.linux_backend`), with no new
+  dependency. Serves both X11 and Wayland sessions.
+- `je_auto_control.utils.platform_id` — one place that classifies the
+  operating system family, and the BSDs are now one of them. FreeBSD, OpenBSD,
+  NetBSD and DragonFly route to the X11 backend instead of raising "unknown
+  operating system".
+- `AutoControlUnsupportedOperationException`, raised when a platform backend
+  cannot perform an operation. It subclasses both `AutoControlException` and
+  `NotImplementedError`, so existing `except NotImplementedError` handlers are
+  unaffected while the executor's containment boundaries now catch it.
+- `je_auto_control.utils.dbus_client` — the D-Bus client, moved out of
+  `linux_wayland/` so `utils/` can use it. The old path re-exports it.
+
 - Stable, headless `je_auto_control.api` façade.
 - Portable `autocontrol.failure-bundle/v1` diagnostic archives and CLI command.
 - Public API lifecycle, capability matrix, security policy, coverage and type
@@ -247,6 +266,19 @@ only when documented here with a migration path.
 
 ### Fixed
 
+- macOS: `write()` typed a space instead of a backspace, because `"\b"` had
+  no route in the macOS key table and fell through to the space fallback.
+- macOS: USB enumeration returned `apple_vendor_id` in `vendor_id`, a field
+  documented as a four-hex-digit string. A value that is not a hex id is now
+  `None`; the device is still listed and `manufacturer` still names the vendor.
+- Linux/X11: `window_rect` returned the client area rather than the frame,
+  disagreeing with Win32's `GetWindowRect` by the window decorations.
+- Linux/X11: `move_window_by_title` configured the client window directly,
+  which under a reparenting window manager positions it in the wrong
+  coordinate space. It now goes through `_NET_MOVERESIZE_WINDOW`.
+- The D-Bus client could not marshal or demarshal signed integers, so any
+  protocol using them (AT-SPI extents among them) failed to decode.
+
 - **Wayland: an absolute mouse move through the ydotool fallback counted from
   the wrong origin.** `ydotool mousemove --absolute` emits no absolute event —
   it drives the cursor into the corner the compositor clamps to and then moves

Progress.md

@@ -50,6 +50,21 @@
 
 ---
 
+## macOS 的錄製器寫了，但接不上去
+
+`TODO` — `osx/record/osx_record.py`、`osx/listener/osx_listener.py`
+
+`OSXRecorder` 是完整實作，但 `wrapper/_platform_osx.py` 裡寫的是
+`recorder = None`，所以它永遠不會被選到。這不是疏失：
+`osx_listener.py` 在 **import 時**就呼叫 `NSApplication.sharedApplication()`，
+而停止錄製要靠 `AppHelper.runEventLoop()`，那是一個會卡住呼叫緒的
+事件迴圈。直接接上去會把這兩件事都搬進 `import je_auto_control`
+的路徑上，那是回歸而不是修好。
+
+要接上去得先把 listener 改成：不在 import 時建立 NSApplication，
+且把 run loop 放到自己的執行緒。`docs/CAPABILITY_MATRIX.md` 的 Recorder
+macOS 格寫的是 `unavailable`，跟現狀一致。
+
 ## `mouse_scroll` 的方向在三個平台上不是同一回事
 
 `DECIDE` — `wrapper/auto_control_mouse.py::mouse_scroll`

README/WHATS_NEW_zh-CN.md

@@ -1,5 +1,69 @@
 # 本次更新 — AutoControl
 
+## 本次更新 (2026-08-20) — 声称支援的平台，這回真的量過了
+
+整套测试一直只在 `windows-2022` 跑，另加容器裡一次 Linux
+執行。macOS 只跑兩行指令。Wayland 有五個 job 對真的對等體
+讀回輸入；X11——兩條 Linux 路徑中更老、部署更廣的那一
+條——一個都沒有，而且套件裡每一條 X11 斷言都是對著
+`python-Xlib` 的 mock 做的。
+
+**测试套件現在真的在它宣稱支援的平台上跑。**
+`pytest-headless` 改成 OS 矩陣；Linux 跑在真的 Xvfb 上而不是 Qt 的
+offscreen，因為 X11 後端在 import 時就連線，offscreen 會將正好要找的
+毛病蓋掉。第一輪就抓到兩個真的 macOS 缺陷：
+
+- `write("\b")` 在 macOS 沒有任何按鍵路徑，會落到空白鍵
+  fallback——要求退格，打出來的是空白。
+- `system_profiler` 對 Apple 自家裝置回的是 **符號式** vendor
+  id（`apple_vendor_id`），而那個欄位文件上寫的是四位十六進位。
+
+**X11 的輸入現在從真的客戶端讀回。** 新的 `x11-verification`
+job 跑在真的 Xvfb + 真的視窗管理員上，對照組來自受測對象以外的
+程式碼：`xev`、ImageMagick 的 `import`、`xdotool` 與 `xdpyinfo`。
+最值得點名的一項是 `synthetic NO`——`XSendEvent` 的事件帶的是
+`YES`，大多數 toolkit 會直接丟掉，所以一個患患停止驅動真實
+輸入的後端，在只數事件的檢查下仍然會全綠。
+
+**macOS 在 CI 裡其實完全驗得了，跟一般假設相反。**
+`macos-14` runner **兩個 TCC 權限都給**：擷取回來的是真像素而不是
+被拒時的全黑矩形，`CGEventPost` 真的移得動游標且讀回完全相符，
+AX 樹也走得出真的元素。這是先量再斷言的，而且探針在期望表
+還是空的時候會拒絕通過。
+
+### 視窗管理不再是 Windows 專屬
+
+以前是：門面在 `sys.platform` 上分支，其他平台一律丟例外，
+23 個 `AC_*` 指令跟對應的 MCP 工具在 macOS 與 Linux 上都是死的。
+現在走平台縫：Win32、X11 的 EWMH、macOS 的 Quartz + 無障礙 API。
+
+兩件只有真的視窗管理員才能披露的錯，第一版都錯了：
+
+- **矩形是外框，不是客戶區。** Win32 的 `GetWindowRect`
+  回的是外框，所有呼叫端都是照那個寫的。
+- **移動必須走 `_NET_MOVERESIZE_WINDOW`。** 在 reparenting
+  視窗管理員下，客戶端自己的 x/y 是相對於外框的；對 openbox
+  要 (300, 220)，直接 `ConfigureWindow` 的結果是落在 (302, 260)。
+
+### Linux 有無障礙後端了
+
+之前完全沒有。新後端走 **AT-SPI2**——它是 D-Bus 協定而不是
+函式庫，這就是它不用加新相依的原因：`pyatspi` 與
+`gi.repository.Atspi` 是發行版套件，裝不進 venv。
+
+拿真的 bus 跟真的 GTK 程式一驗，當場抓到 D-Bus 客戶端的一個缺口：
+**它不會解有號整數**。portal 從來不需要，而 AT-SPI 的 extents 是四個
+**有號**值——因為主螢幕左邊（或上方）的螢幕上，視窗坐標是負的。
+
+### BSD 與 arm64
+
+`platform_wrapper` 對非 win/darwin/linux 一律丟「unknown operating
+system」，七個 X11 後端模組又各自帶一份同樣的 Linux 專屬守衛。
+新的 `utils/platform_id` 是唯一的判定點，`freebsd` job 在 runner 裡開
+真的 FreeBSD 14 VM，在真的 X server 上 import X11 模組並把游標移完讀回。
+`ubuntu-22.04-arm` 與 `windows-11-arm` 加進 smoke 矩陣。
+
+
 ## 本次更新 (2026-08-19) — Wayland 两个等人拍板的取舍,拍板了
 
 `Progress.md` 上挂着两个 `DECIDE`:缺的不是活，是决定。两件事其实是同一个问题犯两次

README/WHATS_NEW_zh-TW.md

@@ -1,5 +1,69 @@
 # 本次更新 — AutoControl
 
+## 本次更新 (2026-08-20) — 嬣稱支援的平台，這回真的量過了
+
+整套測試一直只在 `windows-2022` 跑，另加容器裡一次 Linux
+執行。macOS 只跑兩行指令。Wayland 有五個 job 對真的對等體
+讀回輸入；X11——兩條 Linux 路徑中更老、部署更廣的那一
+條——一個都沒有，而且套件裡每一條 X11 斷言都是對著
+`python-Xlib` 的 mock 做的。
+
+**測試套件現在真的在它宣稱支援的平台上跑。**
+`pytest-headless` 改成 OS 矩陣；Linux 跑在真的 Xvfb 上而不是 Qt 的
+offscreen，因為 X11 後端在 import 時就連線，offscreen 會將正好要找的
+毛病蓋掉。第一輪就抓到兩個真的 macOS 缺陷：
+
+- `write("\b")` 在 macOS 沒有任何按鍵路徑，會落到空白鍵
+  fallback——要求退格，打出來的是空白。
+- `system_profiler` 對 Apple 自家裝置回的是 **符號式** vendor
+  id（`apple_vendor_id`），而那個欄位文件上寫的是四位十六進位。
+
+**X11 的輸入現在從真的客戶端讀回。** 新的 `x11-verification`
+job 跑在真的 Xvfb + 真的視窗管理員上，對照組來自受測對象以外的
+程式碼：`xev`、ImageMagick 的 `import`、`xdotool` 與 `xdpyinfo`。
+最值得點名的一項是 `synthetic NO`——`XSendEvent` 的事件帶的是
+`YES`，大多數 toolkit 會直接丟掉，所以一個患患停止驅動真實
+輸入的後端，在只數事件的檢查下仍然會全綠。
+
+**macOS 在 CI 裡其實完全驗得了，跟一般假設相反。**
+`macos-14` runner **兩個 TCC 權限都給**：擷取回來的是真像素而不是
+被拒時的全黑矩形，`CGEventPost` 真的移得動游標且讀回完全相符，
+AX 樹也走得出真的元素。這是先量再斷言的，而且探針在期望表
+還是空的時候會拒絕通過。
+
+### 視窗管理不再是 Windows 專屬
+
+以前是：門面在 `sys.platform` 上分支，其他平台一律丟例外，
+23 個 `AC_*` 指令跟對應的 MCP 工具在 macOS 與 Linux 上都是死的。
+現在走平台縫：Win32、X11 的 EWMH、macOS 的 Quartz + 無障礙 API。
+
+兩件只有真的視窗管理員才能披露的錯，第一版都錯了：
+
+- **矩形是外框，不是客戶區。** Win32 的 `GetWindowRect`
+  回的是外框，所有呼叫端都是照那個寫的。
+- **移動必須走 `_NET_MOVERESIZE_WINDOW`。** 在 reparenting
+  視窗管理員下，客戶端自己的 x/y 是相對於外框的；對 openbox
+  要 (300, 220)，直接 `ConfigureWindow` 的結果是落在 (302, 260)。
+
+### Linux 有無障礙後端了
+
+之前完全沒有。新後端走 **AT-SPI2**——它是 D-Bus 協定而不是
+函式庫，這就是它不用加新相依的原因：`pyatspi` 與
+`gi.repository.Atspi` 是發行版套件，裝不進 venv。
+
+拿真的 bus 跟真的 GTK 程式一驗，當場抓到 D-Bus 客戶端的一個缺口：
+**它不會解有號整數**。portal 從來不需要，而 AT-SPI 的 extents 是四個
+**有號**值——因為主螢幕左邊（或上方）的螢幕上，視窗坐標是負的。
+
+### BSD 與 arm64
+
+`platform_wrapper` 對非 win/darwin/linux 一律丟「unknown operating
+system」，七個 X11 後端模組又各自帶一份同樣的 Linux 專屬守衛。
+新的 `utils/platform_id` 是唯一的判定點，`freebsd` job 在 runner 裡開
+真的 FreeBSD 14 VM，在真的 X server 上 import X11 模組並把游標移完讀回。
+`ubuntu-22.04-arm` 與 `windows-11-arm` 加進 smoke 矩陣。
+
+
 ## 本次更新 (2026-08-19) — Wayland 兩個等人拍板的取捨,拍板了
 
 `Progress.md` 上掛著兩個 `DECIDE`:缺的不是工，是決定。兩件事其實是同一個問題犯兩次

WHATS_NEW.md

@@ -1,5 +1,112 @@
 # What's New — AutoControl
 
+## What's new (2026-08-20)
+
+### The Platforms This Project Claims, Now Measured
+
+The suite ran on `windows-2022` alone for its whole life, plus one Linux
+container run. macOS got two commands and nothing else. Wayland had five jobs
+reading input back off a real peer; X11 — the older and more widely deployed
+of the two Linux paths — had none, and every X11 assertion in the suite was
+made against a mock of `python-Xlib`.
+
+**The suite now runs where the project says it runs.** `pytest-headless`
+became an OS matrix: Windows keeps all five Pythons, Linux and macOS carry the
+two ends of the range. Linux runs under a real Xvfb rather than Qt's offscreen
+platform, because the X11 backend opens a display at import time and offscreen
+would hide exactly the breakage this exists to find. It found two real macOS
+defects on the first run:
+
+- `write("\b")` had no key route on macOS, so it fell through to the space
+  fallback and typed a space where a backspace was asked for. X11 and Wayland
+  both carry the raw character; macOS was the one that did not.
+- `system_profiler` reports a *symbolic* vendor id for Apple's own devices —
+  `apple_vendor_id`, not a number — and that went straight into a field
+  documented as four hex digits. Its leading `a` is a valid hex digit, so a
+  lenient parse turns it into `000a`.
+
+**X11 input is read back out of a real client.** A new `x11-verification` job
+runs against a real Xvfb server with a real window manager, taking ground
+truth from other codebases than the subject: `xev`, a real X client that
+prints every event delivered to its window; ImageMagick's `import` against a
+root painted two asymmetric colours; `xdotool` and `xdpyinfo`. The assertion
+worth naming is `synthetic NO` — `XSendEvent` traffic arrives with `YES` and
+is discarded by most toolkits, so a backend that quietly stopped driving real
+input would still pass any check that only counted events.
+
+**macOS turned out to be fully testable in CI, contrary to the usual
+assumption.** A `macos-14` runner grants *both* Screen Recording and
+Accessibility: capture returns real pixels rather than the black rectangle a
+refusal produces, `CGEventPost` moves the cursor and the move reads back
+exactly, and the AX walk returns real elements. That was measured first and
+asserted second, and the probe still refuses to pass while its expectations
+table is empty.
+
+### Window Management Is No Longer Windows-Only
+
+It was: the facade branched on `sys.platform` and raised everywhere else,
+leaving 23 `AC_*` commands and their MCP tools dead on macOS and Linux. It now
+goes through a backend seam — Win32, EWMH over `python-Xlib` on X11, Quartz
+plus the accessibility API on macOS, and a null fallback that lists nothing
+and refuses actions with a reason.
+
+Two things only a real window manager could show up were wrong first time:
+
+- **The rectangle is the frame, not the client.** Win32's `GetWindowRect`
+  returns the frame, and every caller is written against that, so reporting
+  the client area was off by the decorations on X11 alone — silently, and by
+  a different amount per window manager.
+- **A move has to go through `_NET_MOVERESIZE_WINDOW`.** Under a reparenting
+  window manager a client's own x/y are relative to its frame, so a direct
+  `ConfigureWindow` asks in the wrong coordinate space. Asking openbox for
+  (300, 220) that way landed the window at (302, 260).
+
+Refusals now raise a class that is both an `AutoControlException` and a
+`NotImplementedError`. The GUI tabs and the REST handler already catch the
+latter to say "not on this platform"; the executor catches the former, and a
+bare `NotImplementedError` slipped past every containment boundary — aborting
+a whole script where one action should have been reported as failed.
+
+### Linux Has an Accessibility Backend
+
+It had none — the selector fell through to the null one while the capability
+matrix claimed "backend tests" for Linux X11. The new backend speaks
+**AT-SPI2**, which is a D-Bus protocol rather than a library, and that is what
+makes it reachable without a new dependency: `pyatspi` and
+`gi.repository.Atspi` are distribution packages built against the system
+introspection data and cannot be installed into a virtual environment.
+
+The D-Bus client written for the portal handshake moved from `linux_wayland/`
+to `utils/dbus_client/` to make that possible, and verifying the backend
+against a real bus and a real GTK application immediately found a gap in it:
+**it could not demarshal signed integers.** The portal never needed one, and
+AT-SPI reports a component's extents as four *signed* values, because a window
+on a monitor left of or above the primary one is at a negative coordinate — so
+the backend could read a tree but not where anything in it was.
+
+Because AT-SPI is a bus rather than a display protocol, this is the one
+capability where Wayland is not the restricted case: the same bus serves both
+Linux sessions.
+
+### The BSDs, and arm64
+
+`platform_wrapper` refused to start on anything that was not
+win32/cygwin/msys, darwin or linux/linux2, and each of the seven X11 backend
+modules carried its own copy of the same Linux-only guard — so a FreeBSD,
+OpenBSD or NetBSD desktop, which runs the same X server and the same
+`python-Xlib`, could not import the package at all. `sys.platform` was being
+compared against literal lists in over a hundred places, so the fix is one
+place that decides: `utils/platform_id`, whose `is_x11_unix()` asks the
+question those guards were always trying to ask.
+
+A `freebsd` job boots a real FreeBSD 14 VM inside the runner, imports the X11
+modules under a real X server, and moves the pointer and reads it back. It
+covers the platform layer rather than the whole package, because opencv has no
+FreeBSD wheel — a limit stated in the job rather than left to be discovered.
+`ubuntu-22.04-arm` and `windows-11-arm` join the smoke matrix; `macos-14` was
+already arm64.
+
+
 ## What's new (2026-08-19)
 
 ### Two Wayland Judgement Calls, Settled