Shell 28: platform-shortcuts-on-wayland (#820) #905

Closed
charles wants to merge 0 commits from shell-28-platform-shortcuts-on-wayland into shell
Owner

Stacked on: shell-3-spike-wayland-global-shortcuts, shell-18-platform-desktop-entry-and, shell-25-platform-shortcut-back-end (Shell 3 and 18 are already on shell; Shell 25 is merged into this branch).

What this builds

crates/fluxer-platform/src/shortcuts/portal.rs: PortalBackend, the GlobalShortcuts portal back end (ashpd 0.14, Linux only), built from the Shell 3 spike, with system_backend(BackendKind::Portal) returning it.

  • Open (start, and every later start, which is how core's recovery reopens): a new bus connection whose first portal call is org.freedesktop.host.portal.Registry.Register("flaxative") (refused without Shell 18's desktop entry: reported as registered: false, and the session opens anyway), then CreateSession and ListShortcuts. The result is Opened { version, registered, listed }, or OpenFailed classified as the original's classify_*_error / classifyOpenFailure. No answer within 30 s (OPEN_TIMEOUT, the original's SETUP_TIMEOUT) is Timeout.
  • Bind (portal_bind): BindShortcuts with every global-capable action, in ShortcutAction::ALL order, with its label and the XDG trigger of its first global combo as preferred trigger. There is no timeout on the desktop's dialog. As the original's bind_step: response 1 is Cancelled and response 2 is Denied; an empty success is checked with ListShortcuts, and an empty list there is Denied.
  • Configure (portal_configure): ConfigureShortcuts on version 2. On version 1, or when the portal answers UnknownMethod or Failed, it reports ConfigureUnsupported.
  • Events: Activated / Deactivated → BackendOutput::Event.
    • A repeated Activated is ignored for a hold. For a toggle it is ignored unless 1.5 s have passed since the last one; then it gives a release and a press (TOGGLE_REARM, D/LinuxGlobalShortcutsPortal.ts:462-475).
    • Hold debounce: a hold's Deactivated is delivered HOLD_RELEASE_DEBOUNCE (60 ms) later, unless an Activated for it arrives first. In that case neither reaches core (KDE bug 484525; the reason is in the module doc). A press is never invented.
  • Changes and losses:
    • ShortcutsChanged releases at once every held action whose trigger changed or went away (as handleShortcutsChanged), then reports Triggers.
    • Session.Closed releases every hold and reports SessionLost(Closed). The portal's name changing owner does the same with SessionLost(PortalRestarted).
    • The portal appearing again reports Available. It is watched after a failed open as well.
    • stop releases everything (including a pending debounce), closes the session, joins every thread and reports Stopped once.
  • Threads: a control thread owns the state and the timers. Each connection has a worker that opens the session and then forwards its signals. A bind or configure call runs on its own thread, so an open dialog delays nothing; when its connection is replaced or stopped, the call is dropped.

Deviations from the plan (please look)

  1. PortalUpdate::Shell(fluxer_core::shell::PortalUpdate) is appended to the platform's PortalUpdate, and the back end reports everything through it. Shell 25's variants (Version, Unregistered, Bound, Denied, Triggers, Reconnecting) were written before core's portal machine (Shell 12), and they cannot carry what core takes: the open result as one update, cancelled and failed binds, unassigned triggers, the reason for a loss, and the portal appearing. PortalUpdate::into_shell() converts any variant for Task 34. The plan's "owner changing → Reconnecting" is therefore SessionLost(PortalRestarted), which is what into_shell maps Reconnecting to, and "unregistered reported" is Opened { registered: false }.
  2. Two default methods are appended to ShortcutBackend: portal_bind() and portal_configure(). They are no-ops except on the portal. Shell 25's trait had no way to carry ShortcutsCommand::{PortalBind, PortalConfigure}. FakeBackend keeps the defaults, and Task 34 can record them there if it needs to.
  3. Session handle token: ashpd 0.14 picks it at random (its CreateSessionOptions cannot be set), so it is not the plan's fixed token. Nothing depends on it, because every open uses a new connection and so gets a new session path.
  4. A failed open is reported as OpenFailed, not as an error of start. start returns Ok and sends Started(Portal), because core's portal machine decides what an open failure means. A start while running reopens and does not send Started again.
  5. An Interface error (no GlobalShortcuts interface) is Unsupported, as the original's unsupported:interface. Core's doc comment of PortalOpenFailure::NoPortal mentions "no interface"; the original is followed here.

Tests

  • tests/portal_shortcuts_bus.rs, module backend (17 tests on Task 3's fake portal on a private dbus-daemon; the fake gained Session.Closed): registers_then_creates_session, unregistered_is_reported_and_the_session_still_opens, listed_shortcuts_are_reported_on_open, no_portal_fails_to_open, bind_sends_all_actions_with_triggers, bound_reports_the_assigned_triggers, denied_bind_reported (empty → denied, cancel → cancelled), activated_deactivated_map_to_events, hold_release_debounced_and_cancelled_by_press, toggle_rearmed_after_repeat, repeated_hold_press_is_ignored, changed_triggers_reported_and_released, closed_session_is_lost_and_releases, portal_restart_reconnects, v1_has_no_configure, stop_releases_what_is_held, updates_print_no_trigger.
  • Unit tests in portal.rs: the Holds timing (debounce, cancel by press, toggle rearm, release all), the trigger-change rule, definitions, and the error classification.
  • FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci is green locally. The base gate before any code of this task hit one flake in xtask/tests/package.rs ("Text file busy" on spawning the AppImage, while another worktree ran its gate); it passed on its own when re-run. Opened as #903.
  • No real-desktop test was run: nothing here touches the session bus outside PortalBackend::new(), and no test calls that. The hand checks on KDE Plasma 6 Wayland belong to Task 44: push-to-talk through the portal with another key tapped during the hold, a toggle, changing a trigger in System Settings, and restarting xdg-desktop-portal.

Strings: the labels sent to the portal are core's ShortcutAction::label(), which matches the original's GLOBAL_SHORTCUT_DEFAULT_DESCRIPTIONS. No new strings.

Keys: nothing is logged except the open failure's kind and the loss's reason. Definition's and PortalUpdate::Shell's Debug output prints no trigger, and a test checks this.

Closes #820

🤖 Generated with Claude Code

https://claude.ai/code/session_0161qMQMsCyJhjYw4gqa6e4K

Stacked on: shell-3-spike-wayland-global-shortcuts, shell-18-platform-desktop-entry-and, shell-25-platform-shortcut-back-end (Shell 3 and 18 are already on `shell`; Shell 25 is merged into this branch). ## What this builds `crates/fluxer-platform/src/shortcuts/portal.rs`: `PortalBackend`, the `GlobalShortcuts` portal back end (`ashpd` 0.14, Linux only), built from the Shell 3 spike, with `system_backend(BackendKind::Portal)` returning it. - **Open** (`start`, and every later `start`, which is how core's recovery reopens): a new bus connection whose first portal call is `org.freedesktop.host.portal.Registry.Register("flaxative")` (refused without Shell 18's desktop entry: reported as `registered: false`, and the session opens anyway), then `CreateSession` and `ListShortcuts`. The result is `Opened { version, registered, listed }`, or `OpenFailed` classified as the original's `classify_*_error` / `classifyOpenFailure`. No answer within 30 s (`OPEN_TIMEOUT`, the original's `SETUP_TIMEOUT`) is `Timeout`. - **Bind** (`portal_bind`): `BindShortcuts` with every global-capable action, in `ShortcutAction::ALL` order, with its label and the XDG trigger of its first global combo as preferred trigger. There is no timeout on the desktop's dialog. As the original's `bind_step`: response 1 is `Cancelled` and response 2 is `Denied`; an empty success is checked with `ListShortcuts`, and an empty list there is `Denied`. - **Configure** (`portal_configure`): `ConfigureShortcuts` on version 2. On version 1, or when the portal answers UnknownMethod or Failed, it reports `ConfigureUnsupported`. - **Events**: `Activated` / `Deactivated` → `BackendOutput::Event`. - A repeated `Activated` is ignored for a hold. For a toggle it is ignored unless 1.5 s have passed since the last one; then it gives a release and a press (`TOGGLE_REARM`, `D/LinuxGlobalShortcutsPortal.ts:462-475`). - **Hold debounce**: a hold's `Deactivated` is delivered `HOLD_RELEASE_DEBOUNCE` (60 ms) later, unless an `Activated` for it arrives first. In that case neither reaches core (KDE bug 484525; the reason is in the module doc). A press is never invented. - **Changes and losses**: - `ShortcutsChanged` releases at once every held action whose trigger changed or went away (as `handleShortcutsChanged`), then reports `Triggers`. - `Session.Closed` releases every hold and reports `SessionLost(Closed)`. The portal's name changing owner does the same with `SessionLost(PortalRestarted)`. - The portal appearing again reports `Available`. It is watched after a failed open as well. - `stop` releases everything (including a pending debounce), closes the session, joins every thread and reports `Stopped` once. - **Threads**: a control thread owns the state and the timers. Each connection has a worker that opens the session and then forwards its signals. A bind or configure call runs on its own thread, so an open dialog delays nothing; when its connection is replaced or stopped, the call is dropped. ## Deviations from the plan (please look) 1. **`PortalUpdate::Shell(fluxer_core::shell::PortalUpdate)`** is appended to the platform's `PortalUpdate`, and the back end reports everything through it. Shell 25's variants (`Version`, `Unregistered`, `Bound`, `Denied`, `Triggers`, `Reconnecting`) were written before core's portal machine (Shell 12), and they cannot carry what core takes: the open result as one update, cancelled and failed binds, unassigned triggers, the reason for a loss, and the portal appearing. `PortalUpdate::into_shell()` converts any variant for Task 34. The plan's "owner changing → `Reconnecting`" is therefore `SessionLost(PortalRestarted)`, which is what `into_shell` maps `Reconnecting` to, and "`unregistered` reported" is `Opened { registered: false }`. 2. **Two default methods are appended to `ShortcutBackend`**: `portal_bind()` and `portal_configure()`. They are no-ops except on the portal. Shell 25's trait had no way to carry `ShortcutsCommand::{PortalBind, PortalConfigure}`. `FakeBackend` keeps the defaults, and Task 34 can record them there if it needs to. 3. **Session handle token**: ashpd 0.14 picks it at random (its `CreateSessionOptions` cannot be set), so it is not the plan's fixed token. Nothing depends on it, because every open uses a new connection and so gets a new session path. 4. A failed open is reported as `OpenFailed`, not as an error of `start`. `start` returns `Ok` and sends `Started(Portal)`, because core's portal machine decides what an open failure means. A `start` while running reopens and does not send `Started` again. 5. An `Interface` error (no `GlobalShortcuts` interface) is `Unsupported`, as the original's `unsupported:interface`. Core's doc comment of `PortalOpenFailure::NoPortal` mentions "no interface"; the original is followed here. ## Tests - `tests/portal_shortcuts_bus.rs`, module `backend` (17 tests on Task 3's fake portal on a private `dbus-daemon`; the fake gained `Session.Closed`): `registers_then_creates_session`, `unregistered_is_reported_and_the_session_still_opens`, `listed_shortcuts_are_reported_on_open`, `no_portal_fails_to_open`, `bind_sends_all_actions_with_triggers`, `bound_reports_the_assigned_triggers`, `denied_bind_reported` (empty → denied, cancel → cancelled), `activated_deactivated_map_to_events`, `hold_release_debounced_and_cancelled_by_press`, `toggle_rearmed_after_repeat`, `repeated_hold_press_is_ignored`, `changed_triggers_reported_and_released`, `closed_session_is_lost_and_releases`, `portal_restart_reconnects`, `v1_has_no_configure`, `stop_releases_what_is_held`, `updates_print_no_trigger`. - Unit tests in `portal.rs`: the `Holds` timing (debounce, cancel by press, toggle rearm, release all), the trigger-change rule, `definitions`, and the error classification. - `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` is green locally. The base gate before any code of this task hit one flake in `xtask/tests/package.rs` ("Text file busy" on spawning the AppImage, while another worktree ran its gate); it passed on its own when re-run. Opened as #903. - No real-desktop test was run: nothing here touches the session bus outside `PortalBackend::new()`, and no test calls that. The hand checks on KDE Plasma 6 Wayland belong to Task 44: push-to-talk through the portal with another key tapped during the hold, a toggle, changing a trigger in System Settings, and restarting `xdg-desktop-portal`. Strings: the labels sent to the portal are core's `ShortcutAction::label()`, which matches the original's `GLOBAL_SHORTCUT_DEFAULT_DESCRIPTIONS`. No new strings. Keys: nothing is logged except the open failure's kind and the loss's reason. `Definition`'s and `PortalUpdate::Shell`'s `Debug` output prints no trigger, and a test checks this. Closes #820 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_0161qMQMsCyJhjYw4gqa6e4K
The `shortcuts` module: the `ShortcutBackend` trait, `ShortcutSink`,
`BackendOutput`, `PortalUpdate`, `BackendError`, `system_backend` (no OS
back end yet) and the scripted `FakeBackend`; `shortcuts::keys` ports the
original's tables (DOM code <-> evdev, X11, Windows scan code and virtual
key), the layout key, mouse button numbering and the XDG trigger strings
(fluxer_desktop/src/main/GlobalShortcutKeys.ts at ba98441b4).

Refs #817

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0161qMQMsCyJhjYw4gqa6e4K
# Conflicts:
#	crates/fluxer-platform/README.md
#	crates/fluxer-platform/src/lib.rs
The private-bus tests of the GlobalShortcuts portal back end, on Task 3's
fake org.freedesktop.portal.Desktop (extended with Session.Closed), the
trait's portal_bind/portal_configure and PortalUpdate::Shell, and a stub
back end.

Refs #820

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0161qMQMsCyJhjYw4gqa6e4K
The GlobalShortcuts portal back end (ashpd 0.14): registers the app id as
the connection's first portal call, opens the session and lists, binds
every global-capable action with its label and preferred trigger on
portal_bind (no timeout on the dialog), configures on version 2, maps
Activated/Deactivated to shortcut events with the original's toggle
rearm (1.5 s) and a 60 ms hold-release debounce (KDE bug 484525),
releases on ShortcutsChanged, Session.Closed and the portal changing
owner, and reports everything as core's PortalUpdate.

Refs #820

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

Review: Shell 28 (portal back end), reviewed at 945fde70 (diff 4a7f4a1c..945fde70)

Gate: FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci run in a separate review worktree: all steps passed. portal_shortcuts_bus passed 29/29, including the 17 backend::* tests.

Checked:

  • All nine tests the plan names exist and assert what the plan says: 60 ms debounce, 1.5 s re-arm, Register → CreateSession → ListShortcuts order, the BindShortcuts payload with every global-capable action, its label and its trigger, and no configure on v1.
  • Interfaces: PortalBackend, system_backend(Portal) (Linux; None elsewhere under cfg), HOLD_RELEASE_DEBOUNCE and TOGGLE_REARM are named constants, and the module doc gives the reason for the debounce.
  • Invariants: keys never logged. The only tracing:: calls are on ?failure and ?reason. Definition, PortalUpdate::Shell and core's PortalShortcut all redact the trigger, and ashpd is built without its tracing feature, which would log call bodies. Nothing from the bus can panic. No secrets.
  • Windows: mod portal and the Portal arm are cfg(linux), with a cfg(not(linux)) Portal => None. PortalUpdate::Shell and into_shell only use core types, so they build on every OS.
  • Parity, checked against fluxer-soundboard:
    • handleActivated (LinuxGlobalShortcutsPortal.ts:462-475): hold repeat ignored; toggle re-armed after 1500 ms, measured from the last activation. Matches.
    • handleShortcutsChanged: a held action is released when its trigger is null or has changed. Matches.
    • bind_step / listed_outcome (codes 1 → Cancelled, 2 → Denied, 0 with nothing listed → Denied). Match.
    • classify_interface_error / classify_create_session_error, and SETUP_TIMEOUT of 30 s. Match.
  • Deviations accepted:
    • PortalUpdate::Shell was appended at the end, and into_shell maps the older variants. Core's existing ports.rs shape is the source of truth here. Note for Task 34: route through into_shell().
    • The default no-op trait methods portal_bind / portal_configure are an append-only change to the registration file.
    • The session token is random because ashpd 0.14 does not let it be set. Nothing depends on it.

Findings

  1. [blocking] Portal::configure never reports ConfigureUnsupported on a v2 portal (shortcuts/portal.rs, fn configure).
    • ashpd 0.14's Proxy::call / call_versioned turn every D-Bus method error into Error::Portal(PortalError::…): org.freedesktop.portal.Error.Failed becomes PortalError::Failed(_), and any other name, such as UnknownMethod, becomes PortalError::ZBus(MethodError). It never returns ashpd::Error::Zbus (see ashpd-0.14.0/src/proxy.rs:270-288 and error.rs:10-31).
    • So the arm Err(ashpd::Error::Zbus(error)) => !matches!(…UNKNOWN_METHOD | portal.Error.Failed) can never match, and those errors fall into _ => true.
    • Result: a version-2 front end whose desktop back end lacks ConfigureShortcuts answers the click with nothing, a silent no-op. The original's classify_configure_error maps UnknownMethod | portal.Error.Failed to unsupported:version. This goes against Review Focus 6 and against the original's behaviour.
    • Fix: match Error::Portal(PortalError::Failed(_)) and Error::Portal(PortalError::ZBus(e)), testing error_name(e) == UNKNOWN_METHOD, and keep the Zbus arm for safety.
    • Add a private-bus test: a v2 fake whose ConfigureShortcuts answers UnknownMethod, and one that answers org.freedesktop.portal.Error.Failed, each expecting ConfigureUnsupported.
  2. [minor] Register drops the original's retry and "already associated" handling.
    • In the original classify_register_error, portal.Error.Failed is retried over REGISTER_RETRY_DELAYS, and an error containing "already associated" counts as registered when it was registered before.
    • Here, any non-fatal error is reported as registered: false at once.
    • The session still opens, so this is not blocking. Either port the retry or record the difference in the module doc.
  3. [minor] ListShortcuts answering with a non-zero response.
    • The original (global_shortcuts.rs ~1456) treats it as an empty list.
    • Here .response()? gives Error::Response. During the open, open_failure then reports OpenFailed(NoPortal). In bind's empty-answer fallback it gives Failed instead of the original's Denied. Consider mapping Error::Response(_) from list() to Ok(vec![]).
  4. [minor] Possible timing flake in backend::hold_release_debounced_and_cancelled_by_press.
    • It relies on the fake's Deactivated and the next Activated reaching the control thread within 60 ms of each other.
    • That is fine on an idle private bus, but it could flake on a loaded runner. If it ever does, a single fake method that emits both signals back to back would make it deterministic.

Verdict: changes requested. One blocking finding (1); 2–4 can be fixed now or deferred as follow-ups. Gate green.

## Review: Shell 28 (portal back end), reviewed at 945fde70 (diff 4a7f4a1c..945fde70) **Gate:** `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` run in a separate review worktree: **all steps passed**. `portal_shortcuts_bus` passed 29/29, including the 17 `backend::*` tests. **Checked:** - All nine tests the plan names exist and assert what the plan says: 60 ms debounce, 1.5 s re-arm, Register → CreateSession → ListShortcuts order, the BindShortcuts payload with every global-capable action, its label and its trigger, and no configure on v1. - Interfaces: `PortalBackend`, `system_backend(Portal)` (Linux; `None` elsewhere under cfg), `HOLD_RELEASE_DEBOUNCE` and `TOGGLE_REARM` are named constants, and the module doc gives the reason for the debounce. - Invariants: keys never logged. The only `tracing::` calls are on `?failure` and `?reason`. `Definition`, `PortalUpdate::Shell` and core's `PortalShortcut` all redact the trigger, and ashpd is built without its `tracing` feature, which would log call bodies. Nothing from the bus can panic. No secrets. - Windows: `mod portal` and the `Portal` arm are `cfg(linux)`, with a `cfg(not(linux))` `Portal => None`. `PortalUpdate::Shell` and `into_shell` only use core types, so they build on every OS. - Parity, checked against fluxer-soundboard: - `handleActivated` (`LinuxGlobalShortcutsPortal.ts:462-475`): hold repeat ignored; toggle re-armed after 1500 ms, measured from the last activation. Matches. - `handleShortcutsChanged`: a held action is released when its trigger is null or has changed. Matches. - `bind_step` / `listed_outcome` (codes 1 → Cancelled, 2 → Denied, 0 with nothing listed → Denied). Match. - `classify_interface_error` / `classify_create_session_error`, and `SETUP_TIMEOUT` of 30 s. Match. - Deviations accepted: - `PortalUpdate::Shell` was appended at the end, and `into_shell` maps the older variants. Core's existing `ports.rs` shape is the source of truth here. Note for Task 34: route through `into_shell()`. - The default no-op trait methods `portal_bind` / `portal_configure` are an append-only change to the registration file. - The session token is random because ashpd 0.14 does not let it be set. Nothing depends on it. ### Findings 1. **[blocking] `Portal::configure` never reports `ConfigureUnsupported` on a v2 portal** (`shortcuts/portal.rs`, `fn configure`). - ashpd 0.14's `Proxy::call` / `call_versioned` turn every D-Bus method error into `Error::Portal(PortalError::…)`: `org.freedesktop.portal.Error.Failed` becomes `PortalError::Failed(_)`, and any other name, such as `UnknownMethod`, becomes `PortalError::ZBus(MethodError)`. It never returns `ashpd::Error::Zbus` (see `ashpd-0.14.0/src/proxy.rs:270-288` and `error.rs:10-31`). - So the arm `Err(ashpd::Error::Zbus(error)) => !matches!(…UNKNOWN_METHOD | portal.Error.Failed)` can never match, and those errors fall into `_ => true`. - Result: a version-2 front end whose desktop back end lacks ConfigureShortcuts answers the click with nothing, a silent no-op. The original's `classify_configure_error` maps `UnknownMethod | portal.Error.Failed` to `unsupported:version`. This goes against Review Focus 6 and against the original's behaviour. - Fix: match `Error::Portal(PortalError::Failed(_))` and `Error::Portal(PortalError::ZBus(e))`, testing `error_name(e) == UNKNOWN_METHOD`, and keep the `Zbus` arm for safety. - Add a private-bus test: a v2 fake whose ConfigureShortcuts answers `UnknownMethod`, and one that answers `org.freedesktop.portal.Error.Failed`, each expecting `ConfigureUnsupported`. 2. **[minor] `Register` drops the original's retry and "already associated" handling.** - In the original `classify_register_error`, `portal.Error.Failed` is retried over `REGISTER_RETRY_DELAYS`, and an error containing "already associated" counts as registered when it was registered before. - Here, any non-fatal error is reported as `registered: false` at once. - The session still opens, so this is not blocking. Either port the retry or record the difference in the module doc. 3. **[minor] `ListShortcuts` answering with a non-zero response.** - The original (`global_shortcuts.rs` ~1456) treats it as an empty list. - Here `.response()?` gives `Error::Response`. During the open, `open_failure` then reports `OpenFailed(NoPortal)`. In bind's empty-answer fallback it gives `Failed` instead of the original's `Denied`. Consider mapping `Error::Response(_)` from `list()` to `Ok(vec![])`. 4. **[minor] Possible timing flake in `backend::hold_release_debounced_and_cancelled_by_press`.** - It relies on the fake's `Deactivated` and the next `Activated` reaching the control thread within 60 ms of each other. - That is fine on an idle private bus, but it could flake on a loaded runner. If it ever does, a single fake method that emits both signals back to back would make it deterministic. **Verdict: changes requested.** One blocking finding (1); 2–4 can be fixed now or deferred as follow-ups. Gate green.
- ConfigureShortcuts: ashpd 0.14 reports a portal method's D-Bus error as
  Error::Portal (Failed, or ZBus for any other name), never Error::Zbus, so
  UnknownMethod and portal.Error.Failed on a version 2 portal were a silent
  no-op. They are now ConfigureUnsupported (classify_configure_error).
- Register: portal.Error.Failed is retried after each of
  REGISTER_RETRY_DELAYS (250 ms, 750 ms, 2 s) before it counts as refused,
  and "already associated" counts as registered when an earlier connection
  of the back end registered (the original's RegisterFailure).
- ListShortcuts: a non-zero response is an empty list, so an open lists
  nothing and an empty bind answer is Denied.
- Signals are timed when the connection's thread reads them, and the
  debounce test sends Deactivated and Activated back to back.
- The fake portal answers ConfigureShortcuts with the real error names, and
  can fail Register, answer ListShortcuts non-zero and refuse configure.

Refs #820

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

Review round 1 fixed in adafda23 (cargo xtask ci green locally, with FLUXER_SCREENSHOT_TESTS=1).

Blocking: Portal::configure never reported ConfigureUnsupported on a v2 portal. Fixed. The new configure_offered matches Error::RequiresVersion, Error::Portal(PortalError::Failed(_)), and UnknownMethod or portal.Error.Failed inside Error::Portal(PortalError::ZBus(_)) (or Error::Zbus). Each of these means unsupported, as the original's classify_configure_error does. Tests: the unit test configure_unsupported_as_the_original, and the bus test backend::v2_without_configure_is_unsupported, which runs a v2 fake that answers UnknownMethod and then portal.Error.Failed and expects ConfigureUnsupported. Both failed on the old code. The fake's ConfigureShortcuts also had a bug of its own: it sent its UnknownMethod as org.freedesktop.zbus.Error because the error went through a #[zbus(error)] variant. It now uses an error type that sends the real names.

Minor: Register retry and "already associated". Ported. classify_register_error(name, message) now returns the original's RegisterFailure. portal.Error.Failed is retried after each of REGISTER_RETRY_DELAYS (250 ms, 750 ms, 2 s) and counts as refused after the last one. "already associated" counts as registered if an earlier connection of this back end registered. Tests: backend::register_failure_is_retried, plus unregistered_is_reported_and_the_session_still_opens, which now checks for 4 Register calls.

Minor: a non-zero ListShortcuts response. Fixed. Portal::list now returns an empty list for Error::Response(_), so opening reports Opened with nothing listed and bind's fallback for an empty answer gives Denied. Test: backend::non_zero_list_answer_is_an_empty_list.

Minor: the debounce test could flake. Two changes reduce the risk. The connection's thread now timestamps each signal when it reads it, so a busy control thread no longer adds time between the release and the press. The test now sends Deactivated and Activated back to back with the fake's new release_and_press. The test passed 15 times in a row here. Delivery of the two signals over the bus within 60 ms is still assumed, but they are two consecutive messages from one sender to one receiver.

🤖 Generated with Claude Code

Review round 1 fixed in adafda23 (`cargo xtask ci` green locally, with `FLUXER_SCREENSHOT_TESTS=1`). **Blocking: `Portal::configure` never reported `ConfigureUnsupported` on a v2 portal.** Fixed. The new `configure_offered` matches `Error::RequiresVersion`, `Error::Portal(PortalError::Failed(_))`, and `UnknownMethod` or `portal.Error.Failed` inside `Error::Portal(PortalError::ZBus(_))` (or `Error::Zbus`). Each of these means unsupported, as the original's `classify_configure_error` does. Tests: the unit test `configure_unsupported_as_the_original`, and the bus test `backend::v2_without_configure_is_unsupported`, which runs a v2 fake that answers `UnknownMethod` and then `portal.Error.Failed` and expects `ConfigureUnsupported`. Both failed on the old code. The fake's `ConfigureShortcuts` also had a bug of its own: it sent its `UnknownMethod` as `org.freedesktop.zbus.Error` because the error went through a `#[zbus(error)]` variant. It now uses an error type that sends the real names. **Minor: Register retry and "already associated".** Ported. `classify_register_error(name, message)` now returns the original's `RegisterFailure`. `portal.Error.Failed` is retried after each of `REGISTER_RETRY_DELAYS` (250 ms, 750 ms, 2 s) and counts as refused after the last one. "already associated" counts as registered if an earlier connection of this back end registered. Tests: `backend::register_failure_is_retried`, plus `unregistered_is_reported_and_the_session_still_opens`, which now checks for 4 `Register` calls. **Minor: a non-zero ListShortcuts response.** Fixed. `Portal::list` now returns an empty list for `Error::Response(_)`, so opening reports `Opened` with nothing listed and bind's fallback for an empty answer gives `Denied`. Test: `backend::non_zero_list_answer_is_an_empty_list`. **Minor: the debounce test could flake.** Two changes reduce the risk. The connection's thread now timestamps each signal when it reads it, so a busy control thread no longer adds time between the release and the press. The test now sends `Deactivated` and `Activated` back to back with the fake's new `release_and_press`. The test passed 15 times in a row here. Delivery of the two signals over the bus within 60 ms is still assumed, but they are two consecutive messages from one sender to one receiver. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Author
Owner

Independent review, round 2 (Task 28, commit adafda23)

Reviewed git diff 4a7f4a1c..origin/shell-28-platform-shortcuts-on-wayland cold.

Gate: FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci in a fresh review worktree: all steps passed, EXIT=0. All 32 tests in portal_shortcuts_bus ran and passed. None were skipped.

What checks out

  • Every test named in the plan exists in tests/portal_shortcuts_bus.rs (backend::registers_then_creates_session, bind_sends_all_actions_with_triggers, activated_deactivated_map_to_events, hold_release_debounced_and_cancelled_by_press, toggle_rearmed_after_repeat, changed_triggers_reported_and_released, denied_bind_reported, portal_restart_reconnects, v1_has_no_configure). Each asserts what the plan says. Round 1's fixes have tests too: v2_without_configure_is_unsupported, register_failure_is_retried and non_zero_list_answer_is_an_empty_list.
  • The appends to shortcuts/mod.rs (portal_bind, portal_configure, PortalUpdate::Shell, the system_backend arm) only add to what is there. Existing variants keep their shape. The cfg(not(linux)) arm still covers the match exhaustively.
  • Parity, checked against the fork:
    • TOGGLE_REARM is 1500 ms, as PORTAL_TOGGLE_REARM_MS.
    • Holds::activated is handleActivated (LinuxGlobalShortcutsPortal.ts:462-475) line for line.
    • REGISTER_RETRY_DELAYS (250 / 750 / 2000 ms), OPEN_TIMEOUT (30 s, SETUP_TIMEOUT), classify_register_error and the "already associated" handling match linux-portals/src/global_shortcuts.rs exactly.
    • configure_offered matches classify_configure_error (UnknownMethod / portal Failed mean unsupported).
    • The changed release rule matches handleShortcutsChanged.
    • The action ids and labels sent to BindShortcuts match GlobalShortcutActions.ts.
  • Review Focus 3: the 60 ms debounce delays only the release of a hold. It never makes a press: a cancelled release leaves the hold held, as it was. Holds are released on Session.Closed, on the portal changing owner, on changed triggers and on stop. A pending debounced release is delivered before Stopped.
  • Keys are never logged. The three new tracing:: lines print only PortalOpenFailure / PortalLoss or nothing. Definition and PortalUpdate::Shell hide their triggers, and updates_print_no_trigger tests this.

Findings

  1. [blocking] The session handle token is random, not fixed. This breaks the plan's Interfaces item ("session with a fixed handle token") and the original's behaviour.
    • ashpd 0.14's CreateSessionOptions cannot set session_handle_token, so every connection gets a random one. The module doc says "nothing depends on it". That is not true on KDE: when a session has no app id, xdg-desktop-portal-kde names the KGlobalAccel component after the session token ("token_" + token; the string token_ is in /usr/lib/xdg-desktop-portal-kde on this machine).
    • That is why the original sends a fixed per-channel token (LINUX_PORTAL_SESSION_TOKEN in DesktopIdentity.ts, DEFAULT_SESSION_TOKEN = "fluxer_global_shortcuts" in linux-portals).
    • Here, whenever Register is refused, every launch and every reconnect creates a new component. That covers a portal older than 1.19.4, a missing desktop entry (Desktop shell 18) and a refusal after the retries. Each time, the user's assigned triggers are lost, "Set up" has to be done again, and stale entries pile up in System Settings.
    • Fix: call CreateSession without ashpd's helper, through zbus with session_handle_token set to a fixed flaxative_global_shortcuts, as the spike's raw Register call already does. Build the session proxy from the returned path. Add a bus test asserting the fake sees the fixed token.
  2. [minor] Session loss is not deferred while a bind dialog is open. The original defers a session-lost that arrives during binding (pendingLoss). Here, lost() reports it at once while the bind call is still running. The loss is still reported and the holds are still released, so nothing gets stuck. Core may just see SessionLost before Bind(...).
  3. [minor] The reported names differ from the Interfaces block's names. Owner change is reported as Portal(Shell(SessionLost(PortalRestarted))), not PortalUpdate::Reconnecting, and "unregistered" is reported as Opened { registered: false }. This is documented, and PortalUpdate::into_shell maps the old variants. The runtime's routing task should consume into_shell() / Shell(..).
  4. [minor] retire() can block the control thread. It calls zbus::block_on(portal.session.close()) on the control thread, under a 30 s method timeout. A hung (not gone) portal would stall that thread, and with it pending debounces of a new connection, for up to 30 s. Holds are already released before it, so push-to-talk cannot stick. A short teardown timeout, like the original's TEARDOWN_TIMEOUT of 2 s, would match it.

Verdict: changes requested. One blocking finding (1). Everything else is correct and CI is green.

## Independent review, round 2 (Task 28, commit adafda23) Reviewed `git diff 4a7f4a1c..origin/shell-28-platform-shortcuts-on-wayland` cold. **Gate:** `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` in a fresh review worktree: all steps passed, EXIT=0. All 32 tests in `portal_shortcuts_bus` ran and passed. None were skipped. **What checks out** - Every test named in the plan exists in `tests/portal_shortcuts_bus.rs` (`backend::registers_then_creates_session`, `bind_sends_all_actions_with_triggers`, `activated_deactivated_map_to_events`, `hold_release_debounced_and_cancelled_by_press`, `toggle_rearmed_after_repeat`, `changed_triggers_reported_and_released`, `denied_bind_reported`, `portal_restart_reconnects`, `v1_has_no_configure`). Each asserts what the plan says. Round 1's fixes have tests too: `v2_without_configure_is_unsupported`, `register_failure_is_retried` and `non_zero_list_answer_is_an_empty_list`. - The appends to `shortcuts/mod.rs` (`portal_bind`, `portal_configure`, `PortalUpdate::Shell`, the `system_backend` arm) only add to what is there. Existing variants keep their shape. The `cfg(not(linux))` arm still covers the match exhaustively. - Parity, checked against the fork: - `TOGGLE_REARM` is 1500 ms, as `PORTAL_TOGGLE_REARM_MS`. - `Holds::activated` is `handleActivated` (`LinuxGlobalShortcutsPortal.ts:462-475`) line for line. - `REGISTER_RETRY_DELAYS` (250 / 750 / 2000 ms), `OPEN_TIMEOUT` (30 s, `SETUP_TIMEOUT`), `classify_register_error` and the "already associated" handling match `linux-portals/src/global_shortcuts.rs` exactly. - `configure_offered` matches `classify_configure_error` (UnknownMethod / portal Failed mean unsupported). - The `changed` release rule matches `handleShortcutsChanged`. - The action ids and labels sent to `BindShortcuts` match `GlobalShortcutActions.ts`. - Review Focus 3: the 60 ms debounce delays only the release of a hold. It never makes a press: a cancelled release leaves the hold held, as it was. Holds are released on `Session.Closed`, on the portal changing owner, on changed triggers and on `stop`. A pending debounced release is delivered before `Stopped`. - Keys are never logged. The three new `tracing::` lines print only `PortalOpenFailure` / `PortalLoss` or nothing. `Definition` and `PortalUpdate::Shell` hide their triggers, and `updates_print_no_trigger` tests this. **Findings** 1. **[blocking] The session handle token is random, not fixed.** This breaks the plan's Interfaces item ("session with a fixed handle token") and the original's behaviour. - ashpd 0.14's `CreateSessionOptions` cannot set `session_handle_token`, so every connection gets a random one. The module doc says "nothing depends on it". That is not true on KDE: when a session has no app id, xdg-desktop-portal-kde names the KGlobalAccel component after the session token (`"token_" + token`; the string `token_` is in `/usr/lib/xdg-desktop-portal-kde` on this machine). - That is why the original sends a fixed per-channel token (`LINUX_PORTAL_SESSION_TOKEN` in `DesktopIdentity.ts`, `DEFAULT_SESSION_TOKEN = "fluxer_global_shortcuts"` in `linux-portals`). - Here, whenever `Register` is refused, every launch and every reconnect creates a new component. That covers a portal older than 1.19.4, a missing desktop entry (Desktop shell 18) and a refusal after the retries. Each time, the user's assigned triggers are lost, "Set up" has to be done again, and stale entries pile up in System Settings. - Fix: call `CreateSession` without ashpd's helper, through `zbus` with `session_handle_token` set to a fixed `flaxative_global_shortcuts`, as the spike's raw `Register` call already does. Build the session proxy from the returned path. Add a bus test asserting the fake sees the fixed token. 2. **[minor] Session loss is not deferred while a bind dialog is open.** The original defers a `session-lost` that arrives during `binding` (`pendingLoss`). Here, `lost()` reports it at once while the bind call is still running. The loss is still reported and the holds are still released, so nothing gets stuck. Core may just see `SessionLost` before `Bind(...)`. 3. **[minor] The reported names differ from the Interfaces block's names.** Owner change is reported as `Portal(Shell(SessionLost(PortalRestarted)))`, not `PortalUpdate::Reconnecting`, and "unregistered" is reported as `Opened { registered: false }`. This is documented, and `PortalUpdate::into_shell` maps the old variants. The runtime's routing task should consume `into_shell()` / `Shell(..)`. 4. **[minor] `retire()` can block the control thread.** It calls `zbus::block_on(portal.session.close())` on the control thread, under a 30 s method timeout. A hung (not gone) portal would stall that thread, and with it pending debounces of a new connection, for up to 30 s. Holds are already released before it, so push-to-talk cannot stick. A short teardown timeout, like the original's `TEARDOWN_TIMEOUT` of 2 s, would match it. **Verdict: changes requested.** One blocking finding (1). Everything else is correct and CI is green.
- CreateSession, ListShortcuts, BindShortcuts, ConfigureShortcuts and Session.Close go
  through zbus directly, so the session's handle token is the fixed SESSION_HANDLE_TOKEN
  (flaxative_global_shortcuts, as the original's LINUX_PORTAL_SESSION_TOKEN); ashpd could
  not set it, and xdg-desktop-portal-kde names an unregistered session's KGlobalAccel
  component after it.
- A session lost while a bind or configure waits gives that call up: no outcome of the
  dead session is reported after the loss (the original's pendingLoss).
- Closing the session waits at most TEARDOWN_TIMEOUT (2 s), not the 30 s method timeout.

Refs #820

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

Round 2 fixes, commit f18fd7e1 (local FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci green).

Blocking: random session handle token (portal.rs). Fixed. ashpd 0.14 cannot set the token, and its Session cannot be built from a path. So the session's calls (CreateSession, ListShortcuts, BindShortcuts, ConfigureShortcuts, Session.Close) now go through zbus directly. A small request helper subscribes to the request object's Response before each call, as ashpd does. CreateSession sends the fixed session_handle_token SESSION_HANDLE_TOKEN = flaxative_global_shortcuts. That is the original's fluxer_global_shortcuts pattern, keyed to our app id so it does not mix with the Electron app's KGlobalAccel component. ashpd is still used for the version and the Activated/Deactivated/ShortcutsChanged signals. New bus test backend::session_has_the_fixed_handle_token: registered and unregistered, the session path is .../session/<unique>/flaxative_global_shortcuts, and it stays so after a reopen on a new connection.

Minor: session loss during an open bind dialog. Fixed in a form that gives the same visible result. Each link now has a separate calls stop. On Session.Closed or a portal owner change, the waiting bind or configure is given up, and an answer still queued for a session that is no longer open is dropped. Core gets SessionLost and never a stale Bind(..) after it. That is what the original produces too: its native side ends the request with SessionLost, and the TS pendingLoss then reports only the loss. Holds are still released at once. New bus test backend::session_lost_during_bind_gives_up_the_bind: (a) the portal closes the session and then answers the bind with response 2, giving SessionLost(Closed) and nothing after it. I checked that this case fails without the fix, where Bind(Denied) followed the loss. (b) The dialog stays open when the session is lost, giving SessionLost, a later bind gives Failed at once, and stop does not hang.

Minor: owner change reported as Shell(SessionLost(PortalRestarted)) (mod.rs). No code change. This is intended: the back end reports core's own PortalUpdate, and PortalUpdate::into_shell maps the older Reconnecting/Opened{registered:false} forms. The runtime routing task has to consume PortalUpdate::Shell / into_shell, as the README's portal section says.

Minor: retire() closing with the 30 s method timeout. Fixed. Session.Close now races TEARDOWN_TIMEOUT (2 s, the original's constant), so a hung portal holds the control thread for at most 2 s. New bus test backend::stop_does_not_wait_on_a_hung_close, against a fake whose Close never answers: stop takes between 2 s and 5 s and still reports Stopped.

README portal section updated (fixed token, a lost bind given up, bounded close).

Round 2 fixes, commit f18fd7e1 (local `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` green). **Blocking: random session handle token (portal.rs).** Fixed. ashpd 0.14 cannot set the token, and its `Session` cannot be built from a path. So the session's calls (`CreateSession`, `ListShortcuts`, `BindShortcuts`, `ConfigureShortcuts`, `Session.Close`) now go through zbus directly. A small `request` helper subscribes to the request object's `Response` before each call, as ashpd does. `CreateSession` sends the fixed `session_handle_token` `SESSION_HANDLE_TOKEN` = `flaxative_global_shortcuts`. That is the original's `fluxer_global_shortcuts` pattern, keyed to our app id so it does not mix with the Electron app's KGlobalAccel component. ashpd is still used for the version and the `Activated`/`Deactivated`/`ShortcutsChanged` signals. New bus test `backend::session_has_the_fixed_handle_token`: registered and unregistered, the session path is `.../session/<unique>/flaxative_global_shortcuts`, and it stays so after a reopen on a new connection. **Minor: session loss during an open bind dialog.** Fixed in a form that gives the same visible result. Each link now has a separate `calls` stop. On `Session.Closed` or a portal owner change, the waiting bind or configure is given up, and an answer still queued for a session that is no longer open is dropped. Core gets `SessionLost` and never a stale `Bind(..)` after it. That is what the original produces too: its native side ends the request with `SessionLost`, and the TS `pendingLoss` then reports only the loss. Holds are still released at once. New bus test `backend::session_lost_during_bind_gives_up_the_bind`: (a) the portal closes the session and then answers the bind with response 2, giving `SessionLost(Closed)` and nothing after it. I checked that this case fails without the fix, where `Bind(Denied)` followed the loss. (b) The dialog stays open when the session is lost, giving `SessionLost`, a later bind gives `Failed` at once, and stop does not hang. **Minor: owner change reported as `Shell(SessionLost(PortalRestarted))` (mod.rs).** No code change. This is intended: the back end reports core's own `PortalUpdate`, and `PortalUpdate::into_shell` maps the older `Reconnecting`/`Opened{registered:false}` forms. The runtime routing task has to consume `PortalUpdate::Shell` / `into_shell`, as the README's portal section says. **Minor: `retire()` closing with the 30 s method timeout.** Fixed. `Session.Close` now races `TEARDOWN_TIMEOUT` (2 s, the original's constant), so a hung portal holds the control thread for at most 2 s. New bus test `backend::stop_does_not_wait_on_a_hung_close`, against a fake whose `Close` never answers: stop takes between 2 s and 5 s and still reports `Stopped`. README portal section updated (fixed token, a lost bind given up, bounded close).
Author
Owner

Independent review, round 3 (Task 28, commit f18fd7e1)

I read git diff 4a7f4a1c..origin/shell-28-platform-shortcuts-on-wayland cold.

Gate: I ran FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci in a fresh review worktree (sh-review-28). All steps passed, EXIT=0. portal_shortcuts_bus: 35 passed, 0 failed, 0 ignored.

What checks out

  • Plan tests. All nine tests the plan names exist under backend::* and assert what the plan says: Register → CreateSession → ListShortcuts in that order, the BindShortcuts payload (every global-capable action with its label and XDG trigger), the 60 ms debounce cancelled by a press, the 1.5 s re-arm, changed triggers released at once, denied/cancelled, restart → SessionLost(PortalRestarted) → Available → reopen, and no configure on v1.
  • Round 2 fixes verified.
    • CreateSession now sends session_handle_token = SESSION_HANDLE_TOKEN (flaxative_global_shortcuts). session_has_the_fixed_handle_token checks the path .../session/<unique>/flaxative_global_shortcuts, registered and unregistered, and after a reopen.
    • lost() signals link.calls, and a Bound or Configured that arrives after the session closed is dropped (session_lost_during_bind_gives_up_the_bind, both cases).
    • close() races TEARDOWN_TIMEOUT (stop_does_not_wait_on_a_hung_close).
    • The request helper subscribes to Response before it makes the call.
  • Interfaces.
    • PortalBackend::{new, on_bus} exists.
    • system_backend(Portal) returns it on Linux, with a cfg(not(linux)) arm Portal => None.
    • portal_bind and portal_configure are appended to the trait as default no-ops, so other back ends are not broken.
    • PortalUpdate::Shell is appended. into_shell maps the older variants, so the Task 34 runtime can feed ShellEvent::Portal from any of them.
    • HOLD_RELEASE_DEBOUNCE and TOGGLE_REARM are named constants, and the module doc gives the reason for the debounce (KDE bug 484525).
  • Invariants.
    • The non-test diff has only three tracing:: lines (thread spawn failure, ?failure, ?reason). None of them log a key or trigger.
    • Definition, PortalUpdate::Shell and core's PortalShortcut print no trigger (updates_print_no_trigger).
    • There is no unwrap, expect or panic outside tests, and bus data cannot panic: unknown ids are dropped, a session handle that is neither a string nor a path falls back to the token's path, and a non-zero response is mapped to an outcome.
    • No secrets. No unsafe.
    • fluxer-core is untouched.
  • Parity, checked against /home/cdaoust/src/fluxer-soundboard.
    • Holds::activated matches handleActivated (LinuxGlobalShortcutsPortal.ts:462-475): a hold's repeat is ignored, and a toggle re-arms 1500 ms after the last activation (PORTAL_TOGGLE_REARM_MS = 1500).
    • changed() matches handleShortcutsChanged + applyBindings: the change is merged, then every held action whose trigger is null or differs is released.
    • REGISTER_RETRY_DELAYS is 250/750/2000 ms, OPEN_TIMEOUT = SETUP_TIMEOUT = 30 s, TEARDOWN_TIMEOUT = 2 s, and "already associated" is handled as in N/linux-portals/src/global_shortcuts.rs:18-24,340.
    • The labels match GLOBAL_SHORTCUT_DEFAULT_DESCRIPTIONS (GlobalShortcutActions.ts).
  • Review Focus 3.
    • Holds are released on Session.Closed, when the portal's owner changes, on stop (including a release still waiting out the debounce, delivered before Stopped), and on ShortcutsChanged.
    • The debounce only drops a release when the same action is pressed again within 60 ms, so it never invents a press.

Findings

  1. minor: the branch does not merge cleanly with current origin/shell. Shell 27 and Shell 29 have since been merged into shell. git merge-tree HEAD origin/shell conflicts in crates/fluxer-platform/{README.md, src/lib.rs, src/shortcuts/mod.rs}. All three are registration files, so keep both sides. In system_backend, combine the arms by hand:

    • keep #[cfg(target_os = "linux")] BackendKind::Portal => Some(Box::new(portal::PortalBackend::new()));
    • keep shell's HookWindows / XRecord / Evdev arms;
    • turn shell's BackendKind::None | BackendKind::Portal => None into BackendKind::None => None plus #[cfg(not(target_os = "linux"))] BackendKind::Portal => None;
    • keep both pub mod xrecord; and #[cfg(target_os = "linux")] pub mod portal;.

    Merge origin/shell and re-run the gate before this PR is merged.

  2. minor: start() on a back end that is already running does not send Status(Started(Portal)) to the new sink. It goes straight to Opened or OpenFailed. FakeBackend::start always sends Started. If Task 34's runtime recovers by calling start again and expects Started first, the portal will differ from the fake. Either document this on the trait or send Started on reopen as well. This does not block this task.

  3. minor (process): the commit trailers read Co-Authored-By: Claude Opus 5.5, while the repo contract asks for Claude Fable 5.2. This was left as is to avoid a force push. Noted for Charles; not a code issue.

Verdict: APPROVED. No blocking findings and the gate is green. Finding 1 must be handled when origin/shell is merged in.

## Independent review, round 3 (Task 28, commit f18fd7e1) I read `git diff 4a7f4a1c..origin/shell-28-platform-shortcuts-on-wayland` cold. **Gate:** I ran `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` in a fresh review worktree (`sh-review-28`). All steps passed, EXIT=0. `portal_shortcuts_bus`: 35 passed, 0 failed, 0 ignored. **What checks out** - **Plan tests.** All nine tests the plan names exist under `backend::*` and assert what the plan says: Register → CreateSession → ListShortcuts in that order, the BindShortcuts payload (every global-capable action with its label and XDG trigger), the 60 ms debounce cancelled by a press, the 1.5 s re-arm, changed triggers released at once, denied/cancelled, restart → `SessionLost(PortalRestarted)` → `Available` → reopen, and no configure on v1. - **Round 2 fixes verified.** - `CreateSession` now sends `session_handle_token` = `SESSION_HANDLE_TOKEN` (`flaxative_global_shortcuts`). `session_has_the_fixed_handle_token` checks the path `.../session/<unique>/flaxative_global_shortcuts`, registered and unregistered, and after a reopen. - `lost()` signals `link.calls`, and a `Bound` or `Configured` that arrives after the session closed is dropped (`session_lost_during_bind_gives_up_the_bind`, both cases). - `close()` races `TEARDOWN_TIMEOUT` (`stop_does_not_wait_on_a_hung_close`). - The `request` helper subscribes to `Response` before it makes the call. - **Interfaces.** - `PortalBackend::{new, on_bus}` exists. - `system_backend(Portal)` returns it on Linux, with a `cfg(not(linux))` arm `Portal => None`. - `portal_bind` and `portal_configure` are appended to the trait as default no-ops, so other back ends are not broken. - `PortalUpdate::Shell` is appended. `into_shell` maps the older variants, so the Task 34 runtime can feed `ShellEvent::Portal` from any of them. - `HOLD_RELEASE_DEBOUNCE` and `TOGGLE_REARM` are named constants, and the module doc gives the reason for the debounce (KDE bug 484525). - **Invariants.** - The non-test diff has only three `tracing::` lines (thread spawn failure, `?failure`, `?reason`). None of them log a key or trigger. - `Definition`, `PortalUpdate::Shell` and core's `PortalShortcut` print no trigger (`updates_print_no_trigger`). - There is no `unwrap`, `expect` or `panic` outside tests, and bus data cannot panic: unknown ids are dropped, a session handle that is neither a string nor a path falls back to the token's path, and a non-zero response is mapped to an outcome. - No secrets. No `unsafe`. - `fluxer-core` is untouched. - **Parity, checked against `/home/cdaoust/src/fluxer-soundboard`.** - `Holds::activated` matches `handleActivated` (`LinuxGlobalShortcutsPortal.ts:462-475`): a hold's repeat is ignored, and a toggle re-arms 1500 ms after the last activation (`PORTAL_TOGGLE_REARM_MS = 1500`). - `changed()` matches `handleShortcutsChanged` + `applyBindings`: the change is merged, then every held action whose trigger is null or differs is released. - `REGISTER_RETRY_DELAYS` is 250/750/2000 ms, `OPEN_TIMEOUT` = `SETUP_TIMEOUT` = 30 s, `TEARDOWN_TIMEOUT` = 2 s, and "already associated" is handled as in `N/linux-portals/src/global_shortcuts.rs:18-24,340`. - The labels match `GLOBAL_SHORTCUT_DEFAULT_DESCRIPTIONS` (`GlobalShortcutActions.ts`). - **Review Focus 3.** - Holds are released on `Session.Closed`, when the portal's owner changes, on stop (including a release still waiting out the debounce, delivered before `Stopped`), and on `ShortcutsChanged`. - The debounce only drops a release when the same action is pressed again within 60 ms, so it never invents a press. **Findings** 1. **minor: the branch does not merge cleanly with current `origin/shell`.** Shell 27 and Shell 29 have since been merged into `shell`. `git merge-tree HEAD origin/shell` conflicts in `crates/fluxer-platform/{README.md, src/lib.rs, src/shortcuts/mod.rs}`. All three are registration files, so keep both sides. In `system_backend`, combine the arms by hand: - keep `#[cfg(target_os = "linux")] BackendKind::Portal => Some(Box::new(portal::PortalBackend::new()))`; - keep shell's `HookWindows` / `XRecord` / `Evdev` arms; - turn shell's `BackendKind::None | BackendKind::Portal => None` into `BackendKind::None => None` plus `#[cfg(not(target_os = "linux"))] BackendKind::Portal => None`; - keep both `pub mod xrecord;` and `#[cfg(target_os = "linux")] pub mod portal;`. Merge `origin/shell` and re-run the gate before this PR is merged. 2. **minor: `start()` on a back end that is already running does not send `Status(Started(Portal))` to the new sink.** It goes straight to `Opened` or `OpenFailed`. `FakeBackend::start` always sends `Started`. If Task 34's runtime recovers by calling `start` again and expects `Started` first, the portal will differ from the fake. Either document this on the trait or send `Started` on reopen as well. This does not block this task. 3. **minor (process): the commit trailers read `Co-Authored-By: Claude Opus 5.5`, while the repo contract asks for `Claude Fable 5.2`.** This was left as is to avoid a force push. Noted for Charles; not a code issue. **Verdict: APPROVED.** No blocking findings and the gate is green. Finding 1 must be handled when `origin/shell` is merged in.
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0161qMQMsCyJhjYw4gqa6e4K
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0161qMQMsCyJhjYw4gqa6e4K
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 20:16:30 +00:00

Pull request closed

Sign in to join this conversation.
No description provided.