Shell 30: platform-wayland-activation (#822) #897

Closed
charles wants to merge 0 commits from shell-30-platform-wayland-activation into shell
Owner

Stacked on: origin/shell-4-spike-raising-a-wayland, origin/shell-32-ui-daemon-window-lifecycle (both already contained in origin/shell at 8e3ae168; nothing extra merged)

What this builds (spec §10.2, plan Task 30)

  • fluxer_platform::activation::activate(&WindowRef, &ActivationToken) -> Result<(), ActivationError>: binds xdg_activation_v1 on a second queue over the window's wl_display (Backend::from_foreign_display), wraps the window's wl_surface (ObjectId::from_ptr, which checks the interface), calls activate(token, surface), flushes, then drops the binding. This is the call Task 4 proved. ActivationError::{Unsupported, EmptyToken, NotOffered, NoSurface, Connection}. A non-Wayland window, or any OS other than Linux, gets Unsupported without its handles being touched. No error carries the token.
  • Notifications on Linux: the notifier now sends Notify itself, on its own zbus connection. Before sending, it adds match rules and opens the message stream, then waits on that connection for ActivationToken(id, token), ActionInvoked and NotificationClosed. Plasma sends these as targeted signals, and notify-rust's wait_for_response drops ActivationToken. notify-rust still builds the notification and its hints. The hints map is built outside any block_on, which keeps the #752 behaviour.
  • notify::Clicked { notification, activation_token } (re-exported). OnClick is now Fn(&Clicked). On Windows the token is always None.
  • wayland-client 0.31 (system) and wayland-protocols 0.32 (client, staging) move from Linux dev-deps to Linux deps. iced (workspace) becomes a normal dep for raw_window_handle. No new crate enters the graph.

Deviations

  • activate is an unsafe fn. WindowRef::new is safe and public, so a safe activate that dereferences its pointers would be unsound. The safety contract: the handles stay live for the whole call, meaning it runs between WindowHost::opened and closed with closed held off, or inside window::run. Task 33 calls it inside unsafe.
  • The plan says "Clicked gains activation_token", but no Clicked type existed. I added notify::Clicked and changed OnClick to take it. To keep the build compiling, apps/fluxer got minimal call-site edits (runtime.rs notify worker and a test fake, tests/dailyuse_runtime.rs). The runtime does not use the token yet: Task 33 wires it to activate.

Tests

  • tests/activation.rs (every OS): unsupported_off_wayland (Xlib, Xcb, Win32), unsupported_for_a_wayland_surface_on_an_x11_display, token_never_in_debug (errors and Clicked), an_empty_token_is_refused_before_the_window_is_used.
  • tests/notify_session_bus.rs: click_carries_activation_token. The fake server sends ActivationToken for the id, plus one for another id, then ActionInvoked. The test checks that the token reaches OnClick and is never printed. The existing test now also checks that a click without a token gives None.
  • Unit test a_click_carries_the_servers_activation_token in notify/mod.rs.
  • Opt-in second_launch_raises_window (FLUXER_DESKTOP_TESTS=1, Linux). It maps a toplevel, lets a second "launcher" toplevel take focus and request a token, activates the first through activate, and waits for xdg_toplevel activated. I ran it, and it passes in a private kwin_wayland --virtual (KWin 6.8.2) under dbus-run-session. It was never run on the desktop in use. Run instructions are in the crate README. Not run on sway: the spike showed headless sway marks the window urgent instead of focusing it.
  • FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci: all steps passed locally.

For Charles to check by hand (Task 44)

  • A notification click on Plasma Wayland raises a covered window. This needs Task 33's wiring.
  • Windows: only the Clicked construction in notify/windows.rs changed (token None). That code is compiled by the Windows runner only.

Strings: none added (no UI).

Closes #822
Closes #55

🤖 Generated with Claude Code

https://claude.ai/code/session_0161qMQMsCyJhjYw4gqa6e4K

Stacked on: origin/shell-4-spike-raising-a-wayland, origin/shell-32-ui-daemon-window-lifecycle (both already contained in origin/shell at 8e3ae168; nothing extra merged) ## What this builds (spec §10.2, plan Task 30) - `fluxer_platform::activation::activate(&WindowRef, &ActivationToken) -> Result<(), ActivationError>`: binds `xdg_activation_v1` on a second queue over the window's `wl_display` (`Backend::from_foreign_display`), wraps the window's `wl_surface` (`ObjectId::from_ptr`, which checks the interface), calls `activate(token, surface)`, flushes, then drops the binding. This is the call Task 4 proved. `ActivationError::{Unsupported, EmptyToken, NotOffered, NoSurface, Connection}`. A non-Wayland window, or any OS other than Linux, gets `Unsupported` without its handles being touched. No error carries the token. - Notifications on Linux: the notifier now sends `Notify` itself, on its own zbus connection. Before sending, it adds match rules and opens the message stream, then waits on that connection for `ActivationToken(id, token)`, `ActionInvoked` and `NotificationClosed`. Plasma sends these as targeted signals, and notify-rust's `wait_for_response` drops `ActivationToken`. `notify-rust` still builds the notification and its hints. The hints map is built outside any `block_on`, which keeps the #752 behaviour. - `notify::Clicked { notification, activation_token }` (re-exported). `OnClick` is now `Fn(&Clicked)`. On Windows the token is always `None`. - `wayland-client` 0.31 (`system`) and `wayland-protocols` 0.32 (`client`, `staging`) move from Linux dev-deps to Linux deps. `iced` (workspace) becomes a normal dep for `raw_window_handle`. No new crate enters the graph. ## Deviations - `activate` is an `unsafe fn`. `WindowRef::new` is safe and public, so a safe `activate` that dereferences its pointers would be unsound. The safety contract: the handles stay live for the whole call, meaning it runs between `WindowHost::opened` and `closed` with `closed` held off, or inside `window::run`. Task 33 calls it inside `unsafe`. - The plan says "`Clicked` gains `activation_token`", but no `Clicked` type existed. I added `notify::Clicked` and changed `OnClick` to take it. To keep the build compiling, `apps/fluxer` got minimal call-site edits (`runtime.rs` notify worker and a test fake, `tests/dailyuse_runtime.rs`). The runtime does not use the token yet: Task 33 wires it to `activate`. ## Tests - `tests/activation.rs` (every OS): `unsupported_off_wayland` (Xlib, Xcb, Win32), `unsupported_for_a_wayland_surface_on_an_x11_display`, `token_never_in_debug` (errors and `Clicked`), `an_empty_token_is_refused_before_the_window_is_used`. - `tests/notify_session_bus.rs`: `click_carries_activation_token`. The fake server sends `ActivationToken` for the id, plus one for another id, then `ActionInvoked`. The test checks that the token reaches `OnClick` and is never printed. The existing test now also checks that a click without a token gives `None`. - Unit test `a_click_carries_the_servers_activation_token` in `notify/mod.rs`. - Opt-in `second_launch_raises_window` (`FLUXER_DESKTOP_TESTS=1`, Linux). It maps a toplevel, lets a second "launcher" toplevel take focus and request a token, activates the first through `activate`, and waits for `xdg_toplevel` `activated`. **I ran it, and it passes in a private `kwin_wayland --virtual` (KWin 6.8.2) under `dbus-run-session`.** It was never run on the desktop in use. Run instructions are in the crate README. Not run on sway: the spike showed headless sway marks the window urgent instead of focusing it. - `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci`: all steps passed locally. ## For Charles to check by hand (Task 44) - A notification click on Plasma Wayland raises a covered window. This needs Task 33's wiring. - Windows: only the `Clicked` construction in `notify/windows.rs` changed (token `None`). That code is compiled by the Windows runner only. Strings: none added (no UI). Closes #822 Closes #55 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_0161qMQMsCyJhjYw4gqa6e4K
Failing tests first: unsupported_off_wayland, token_never_in_debug, the
notifications harness's click_carries_activation_token (the ActivationToken
signal of the notification specification 1.2, as Plasma's libnotificationmanager
sends it before ActionInvoked), and the opt-in second_launch_raises_window.

Refs #822

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0161qMQMsCyJhjYw4gqa6e4K
activation::activate(&WindowRef, &ActivationToken) binds xdg_activation_v1 on
a queue of its own over the window's wl_display and activates the window's
wl_surface (Task 4's proven call); Unsupported for non-Wayland windows and off
Linux. The Linux notifier sends Notify on its own connection and waits there
for ActivationToken / ActionInvoked / NotificationClosed, so OnClick gets
notify::Clicked { notification, activation_token }. wayland-client and
wayland-protocols move from the spike's dev-dependencies to the normal ones;
iced (already linked through fluxer-ui) gives raw_window_handle.

Refs #822

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0161qMQMsCyJhjYw4gqa6e4K
Author
Owner

Independent review: Shell 30 (platform-wayland-activation)

Reviewed git diff 8e3ae168..origin/shell-30-platform-wayland-activation (e7514502) cold.

Gate: FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci in a fresh review worktree: all steps passed (exit 0). unsupported_off_wayland, token_never_in_debug, click_carries_activation_token and the unit test a_click_carries_the_servers_activation_token ran and passed. second_launch_raises_window skipped cleanly (no FLUXER_DESKTOP_TESTS).

Checks

  1. Plan tests: all four named tests exist. click_carries_activation_token runs a fake org.freedesktop.Notifications on a private dbus-daemon. It sends ActivationToken for this id, then a decoy token for id+1, then ActionInvoked. The test checks that each click carries exactly the server's token for its own id and that the token is never printed. The opt-in desktop test is env-gated, runs only on a private compositor and drives the shipped activate.
  2. Interfaces: fluxer_platform::activation::{activate, ActivationError} and notify::Clicked { notification, activation_token } (re-exported) exist, and OnClick = Arc<dyn Fn(&Clicked)>. Deviation: activate is an unsafe fn (see m1). No unmerged shell branch uses OnClick, so the type change breaks nobody.
  3. Invariants: fluxer-core and fluxer-ui are untouched. ActivationToken's Debug is redacted, no ActivationError carries the token, and the notifier never logs it. The new dependencies are named by the task and already in the tree. The cfg(not(linux)) path compiles to a plain Unsupported with no unused imports, and Answer's dead_code allow covers Windows non-test builds. SAFETY: comments are present. Soundness checked in wayland-backend 0.3.17: on drop, a foreign-display backend destroys the proxies it created (the registry and activation) and its own queue but does not disconnect the display. winit's surface is not in its known_proxies, so it is left alone.
  4. Parity (checked against fluxer_desktop/native/linux-notifications/src/lib.rs:563-580 and src/main/NotificationsIpc.ts:284-300): the signal interface, member names and body shapes match (ActionInvoked (u32,String), NotificationClosed (u32,u32)). Hints still match (urgency normal, category im, desktop-entry, default action "Open"). The sent Notify matches notify-rust's own send_notification_via_connection (same tuple). hints replaces get_hints() with no change, because build sets no custom hints. ActivationToken is new per spec §10.2 (the original ignores it).
  5. Review Focus: no item names Task 30. The relevant one, #6 (honest capability), holds: Unsupported, NotOffered, NoSurface and EmptyToken are typed states, and Ok is documented as "sent", not "raised".

Findings

  • m1 (minor): activate is unsafe fn, but the plan's Interfaces block says activate(&WindowRef, &ActivationToken) -> Result<…>. The deviation is justified because WindowRef::new is safe and public. Task 33 must call it inside unsafe with a SAFETY: comment that holds the host's lock across the call, so closed cannot return while it runs. The orchestrator should tell Task 33.
  • m2 (minor): the branch no longer merges cleanly into the current origin/shell (d48106dc, after Shell 23). There are doc-comment-only conflicts in crates/fluxer-platform/src/lib.rs (a registration file: keep both, i.e. badge/displays/sound_allowed and activation) and in src/notify/mod.rs's module docs (keep both paragraphs). Merge origin/shell and re-run the crate tests before merging.
  • m3 (minor): with watch, a failed AddMatch now fails the whole Notify, so the notification is not shown. Before, only the wait could fail. This should be rare on a working bus. Showing the notification unwatched would be more forgiving.
  • m4 (note): the PR body says Closes #55, as the plan's Global Constraints require. The plan also leaves #55's Windows box to Task 44, so the orchestrator decides whether #55 closes on this merge.

Verdict: APPROVED. No blocking findings and the local gate is green. The origin/shell merge (m2) is needed before merging.

## Independent review: Shell 30 (platform-wayland-activation) Reviewed `git diff 8e3ae168..origin/shell-30-platform-wayland-activation` (e7514502) cold. **Gate:** `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` in a fresh review worktree: **all steps passed** (exit 0). `unsupported_off_wayland`, `token_never_in_debug`, `click_carries_activation_token` and the unit test `a_click_carries_the_servers_activation_token` ran and passed. `second_launch_raises_window` skipped cleanly (no `FLUXER_DESKTOP_TESTS`). ### Checks 1. **Plan tests**: all four named tests exist. `click_carries_activation_token` runs a fake `org.freedesktop.Notifications` on a private `dbus-daemon`. It sends `ActivationToken` for this id, then a decoy token for id+1, then `ActionInvoked`. The test checks that each click carries exactly the server's token for its own id and that the token is never printed. The opt-in desktop test is env-gated, runs only on a private compositor and drives the shipped `activate`. 2. **Interfaces**: `fluxer_platform::activation::{activate, ActivationError}` and `notify::Clicked { notification, activation_token }` (re-exported) exist, and `OnClick = Arc<dyn Fn(&Clicked)>`. Deviation: `activate` is an `unsafe fn` (see m1). No unmerged shell branch uses `OnClick`, so the type change breaks nobody. 3. **Invariants**: fluxer-core and fluxer-ui are untouched. `ActivationToken`'s `Debug` is redacted, no `ActivationError` carries the token, and the notifier never logs it. The new dependencies are named by the task and already in the tree. The `cfg(not(linux))` path compiles to a plain `Unsupported` with no unused imports, and `Answer`'s `dead_code` allow covers Windows non-test builds. `SAFETY:` comments are present. Soundness checked in wayland-backend 0.3.17: on drop, a foreign-display backend destroys the proxies it created (the registry and activation) and its own queue but does not disconnect the display. winit's surface is not in its `known_proxies`, so it is left alone. 4. **Parity** (checked against `fluxer_desktop/native/linux-notifications/src/lib.rs:563-580` and `src/main/NotificationsIpc.ts:284-300`): the signal interface, member names and body shapes match (`ActionInvoked (u32,String)`, `NotificationClosed (u32,u32)`). Hints still match (`urgency normal`, `category im`, `desktop-entry`, `default` action "Open"). The sent `Notify` matches notify-rust's own `send_notification_via_connection` (same tuple). `hints` replaces `get_hints()` with no change, because `build` sets no custom hints. `ActivationToken` is new per spec §10.2 (the original ignores it). 5. **Review Focus**: no item names Task 30. The relevant one, #6 (honest capability), holds: `Unsupported`, `NotOffered`, `NoSurface` and `EmptyToken` are typed states, and `Ok` is documented as "sent", not "raised". ### Findings - **m1 (minor)**: `activate` is `unsafe fn`, but the plan's Interfaces block says `activate(&WindowRef, &ActivationToken) -> Result<…>`. The deviation is justified because `WindowRef::new` is safe and public. Task 33 must call it inside `unsafe` with a `SAFETY:` comment that holds the host's lock across the call, so `closed` cannot return while it runs. The orchestrator should tell Task 33. - **m2 (minor)**: the branch no longer merges cleanly into the current `origin/shell` (d48106dc, after Shell 23). There are doc-comment-only conflicts in `crates/fluxer-platform/src/lib.rs` (a registration file: keep both, i.e. `badge`/`displays`/`sound_allowed` and `activation`) and in `src/notify/mod.rs`'s module docs (keep both paragraphs). Merge `origin/shell` and re-run the crate tests before merging. - **m3 (minor)**: with `watch`, a failed `AddMatch` now fails the whole `Notify`, so the notification is not shown. Before, only the wait could fail. This should be rare on a working bus. Showing the notification unwatched would be more forgiving. - **m4 (note)**: the PR body says `Closes #55`, as the plan's Global Constraints require. The plan also leaves #55's Windows box to Task 44, so the orchestrator decides whether #55 closes on this merge. **Verdict: APPROVED.** No blocking findings and the local gate is green. The `origin/shell` merge (m2) is needed before merging.
Author
Owner

Merged into shell by hand (the merge API returns 405); the commits are in the branch.

Merged into `shell` by hand (the merge API returns 405); the commits are in the branch.
charles closed this pull request 2026-11-18 17:07:14 +00:00

Pull request closed

Sign in to join this conversation.
No description provided.