packages/cua-driver/docs/wayland-compositor-identity-plan.md
This is an architecture explanation and evidence plan for expanding exact browser attachment beyond Sway. It does not claim generic Wayland support.
Existing-profile setup can open an internal browser page and press one exact accessibility control. Before doing so, Cua Driver must prove that the native toplevel, browser PID, geometry, AT-SPI application/window, product descriptor, and loopback endpoint all describe the same browser generation.
Title, application ID, or screen-coordinate similarity alone is insufficient. An attacker or unrelated window can reuse those values. When the compositor cannot attest exact identity, mutation must refuse before opening the setup page or sending input.
The existing Sway adapter uses compositor IPC to correlate the exact container, PID, and rectangle with the AT-SPI tree. Setup may briefly focus that attested container for fixed browser-owned internal navigation, then restores the prior container. Canonical Sway evidence accepts Google Chrome, Chromium, and Microsoft Edge after each product completed the same full matrix with playable video and no unexpected results.
The maintained WinRects extension v4 exposes the narrow identity route Cua Driver needs on GNOME Shell and Mutter: a stable window identifier, PID, geometry, focus and stacking state, and exact activation.
The Linux adapter resolves the extension's immutable unique D-Bus owner,
verifies that the owner is the current user's system-installed gnome-shell
process, requires helper API v4 for browser-sensitive calls, and addresses that
unique owner directly. This prevents an unrelated same-session process from
replacing the public bus name between verification and activation. Setup and
consent briefly activate one exact window, then restore and verify the prior
Shell focus.
The route is accepted for Google Chrome after the full standalone-browser matrix recorded 13 delivered behaviors, 3 policy refusals, 0 failures, and 0 skips with 16 playable videos at one source commit. Other Chromium-family products still require their own product-specific evidence on GNOME.
The adapter refuses when the component is missing, incompatible, disabled, or unable to distinguish multiple windows for one browser process. Enabling a generic unsafe-mode switch is not an acceptable production dependency.
KWin 6 scripting exposes a per-window internal ID, PID, frame geometry, stacking order, active state, and workspace activation. See the official KWin scripting API.
A maintained Cua Driver KWin component could return a versioned, read-only identity record and perform one exact focus-and-restore transition. The adapter must bind its D-Bus peer, KWin generation, internal window ID, PID, geometry, and AT-SPI window. A generic user-provided script or title lookup is not enough.
The standard ext-foreign-toplevel-list-v1 protocol exposes an opaque stable
toplevel identifier, title, and application ID, but not PID or geometry. See
the foreign toplevel protocol.
It can contribute one part of a proof, but cannot independently authorize
mutation.
wlroots compositors may expose additional management or compositor IPC. Each route remains compositor-specific until it proves all required fields. No screen-coordinate fallback is allowed.
Each adapter and harness must cover:
Any ambiguity produces a stable, non-mutating structured refusal.
A compositor is listed as supported only after the canonical matrix records: