Shell 25: platform-shortcut-back-end (#817) #887

Closed
charles wants to merge 0 commits from shell-25-platform-shortcut-back-end into shell
Owner

What

fluxer-platform::shortcuts (spec §8.2, §8.3, §12), the boundary Tasks 26–29 and 34 build on:

  • ShortcutBackend trait: kind(), start(ShortcutSink) -> Result<(), BackendError>, set_bindings(&[(ShortcutAction, KeyCombo)]) (the portal's only), capture(bool), stop(), with the contract documented (Started once running, never swallow input, Stopped once on stop or loss, no key in a log/error).
  • ShortcutSink (new(fn), channel(), send), BackendOutput::{Input, Event, Status, Portal, Session}, PortalUpdate::{Version, Unregistered, Bound, Denied, Triggers, Reconnecting} (append-only; Debug prints actions, never the trigger text), BackendError::{Permission, StartFailed, Unsupported} (+ failure(), status(kind)).
  • system_backend(kind): None for every kind until Tasks 26–29 add their arm.
  • FakeBackend::{new, scripted} + FakeControl (emit, fail_next_start, bindings, capturing, running, starts).
  • shortcuts::keys: the original's tables from D/GlobalShortcutKeys.ts (generated from the file: evdev 185, Windows scan 157, virtual key 144 entries), X11 = evdev + 8, windows_to_dom (scan then VK), windows_raw_code (GlobalShortcutsNative.ts), hook_key_name_to_dom_code, us_layout_key_to_dom_code, layout_key(code, text), mouse buttons from X11 / evdev / Windows (windows_mouse also reports activity for Task 26's watchdog), xdg_trigger(&KeyCombo) (comboToXdgTrigger).

Tests

crates/fluxer-platform/tests/shortcut_keys.rs: every_dom_code_round_trips_per_table, extended_scan_codes, mouse_buttons_3_and_4, layout_key_only_for_printables, xdg_trigger_strings, no_trigger_for_mouse_or_modifier_only, fake_backend_scripts, plus fake_backend_fails_as_told, hook_names_and_us_layout_keys, outputs_print_no_key, sink_from_a_function_and_after_the_receiver_is_gone, no_system_backend_before_the_os_tasks. The fork has no tests of these functions, so the vectors come from its tables. Seen failing (module missing), then passing. FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci green locally (the first run hit an unrelated timing flake in screenshare_runtime, filed as #886; the rerun passed). No real-desktop test belongs to this task.

Deviations from the plan

  • BackendOutput has a fifth variant, Session(SessionEvent): Task 26 reports Locked | Suspending, which core's BackendStatus does not have; SessionEvent does and maps straight to ShellEvent::Session for Task 34.
  • PortalUpdate's variants are not named by the plan beyond Triggers; chosen from Task 28's list. Task 28 may append.
  • The trait has no portal bind / configure method (not in the interface); Task 28 adds them (default no-op methods keep the other back ends unchanged).
  • Reverse lookups (DOM → code) where the original's tables share a name take the later, specific code (KEY_PROG1, VK_LSHIFT, 0xE037), except Windows Pause = 0x45.
  • layout_key takes the DOM code too, so the numpad never matches by layout.

No Windows-only code here; nothing for Charles to check by hand. No strings shown to users.

Stacked on: shell-11-core-keybinds-actions-combos (already in shell; the merge was a no-op).

Closes #817

🤖 Generated with Claude Code

https://claude.ai/code/session_0161qMQMsCyJhjYw4gqa6e4K

## What `fluxer-platform::shortcuts` (spec §8.2, §8.3, §12), the boundary Tasks 26–29 and 34 build on: - `ShortcutBackend` trait: `kind()`, `start(ShortcutSink) -> Result<(), BackendError>`, `set_bindings(&[(ShortcutAction, KeyCombo)])` (the portal's only), `capture(bool)`, `stop()`, with the contract documented (Started once running, never swallow input, Stopped once on stop or loss, no key in a log/error). - `ShortcutSink` (`new(fn)`, `channel()`, `send`), `BackendOutput::{Input, Event, Status, Portal, Session}`, `PortalUpdate::{Version, Unregistered, Bound, Denied, Triggers, Reconnecting}` (append-only; `Debug` prints actions, never the trigger text), `BackendError::{Permission, StartFailed, Unsupported}` (+ `failure()`, `status(kind)`). - `system_backend(kind)`: `None` for every kind until Tasks 26–29 add their arm. - `FakeBackend::{new, scripted}` + `FakeControl` (`emit`, `fail_next_start`, `bindings`, `capturing`, `running`, `starts`). - `shortcuts::keys`: the original's tables from `D/GlobalShortcutKeys.ts` (generated from the file: evdev 185, Windows scan 157, virtual key 144 entries), X11 = evdev + 8, `windows_to_dom` (scan then VK), `windows_raw_code` (`GlobalShortcutsNative.ts`), `hook_key_name_to_dom_code`, `us_layout_key_to_dom_code`, `layout_key(code, text)`, mouse buttons from X11 / evdev / Windows (`windows_mouse` also reports activity for Task 26's watchdog), `xdg_trigger(&KeyCombo)` (`comboToXdgTrigger`). ## Tests `crates/fluxer-platform/tests/shortcut_keys.rs`: `every_dom_code_round_trips_per_table`, `extended_scan_codes`, `mouse_buttons_3_and_4`, `layout_key_only_for_printables`, `xdg_trigger_strings`, `no_trigger_for_mouse_or_modifier_only`, `fake_backend_scripts`, plus `fake_backend_fails_as_told`, `hook_names_and_us_layout_keys`, `outputs_print_no_key`, `sink_from_a_function_and_after_the_receiver_is_gone`, `no_system_backend_before_the_os_tasks`. The fork has no tests of these functions, so the vectors come from its tables. Seen failing (module missing), then passing. `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` green locally (the first run hit an unrelated timing flake in `screenshare_runtime`, filed as #886; the rerun passed). No real-desktop test belongs to this task. ## Deviations from the plan - `BackendOutput` has a fifth variant, `Session(SessionEvent)`: Task 26 reports `Locked | Suspending`, which core's `BackendStatus` does not have; `SessionEvent` does and maps straight to `ShellEvent::Session` for Task 34. - `PortalUpdate`'s variants are not named by the plan beyond `Triggers`; chosen from Task 28's list. Task 28 may append. - The trait has no portal bind / configure method (not in the interface); Task 28 adds them (default no-op methods keep the other back ends unchanged). - Reverse lookups (DOM → code) where the original's tables share a name take the later, specific code (`KEY_PROG1`, `VK_LSHIFT`, `0xE037`), except Windows `Pause` = `0x45`. - `layout_key` takes the DOM code too, so the numpad never matches by layout. No Windows-only code here; nothing for Charles to check by hand. No strings shown to users. Stacked on: shell-11-core-keybinds-actions-combos (already in `shell`; the merge was a no-op). Closes #817 🤖 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
Author
Owner

Independent review: Shell 25 (shortcut back-end trait, key tables, fake)

Reviewed ef96e13a..c22ccee6 cold.

What I checked

  • Plan tests: all 7 named tests exist (every_dom_code_round_trips_per_table, extended_scan_codes, mouse_buttons_3_and_4, layout_key_only_for_printables, xdg_trigger_strings, no_trigger_for_mouse_or_modifier_only, fake_backend_scripts), plus 5 more. They assert what the plan asks.
  • Interfaces: ShortcutBackend { kind, start(sink) -> Result<(), BackendError::{Permission, StartFailed, Unsupported}>, set_bindings(&[(ShortcutAction, KeyCombo)]), capture(bool), stop() }, ShortcutSink, BackendOutput::{Input, Event, Status, Portal}, FakeBackend and system_backend(kind) -> Option<Box<dyn ShortcutBackend>> all exist exactly as written. The added Session(SessionEvent) variant fits Task 34's ShellEvent::Session, and BackendStatus has no Locked or Suspending state, so the deviation is justified.
  • Parity: I evaluated the fork's GlobalShortcutKeys.ts (ba98441b4) with node and diffed it against the Rust tables. EVDEV_KEY_CODES (185), WINDOWS_SCAN_CODES (157) and WINDOWS_VIRTUAL_KEY_CODES (144) are identical, in the same order. No code appears twice, so the forward lookup is exact. MACOS_KEY_CODES adds no name to KNOWN_DOM_CODES, as claimed. These also match their sources:
    • x11KeycodeToDomCode, windowsKeyToDomCode and keyCodeIdentity (raw with WINDOWS_VK_RAW_PREFIX 0x10000)
    • XDG_CODE_KEYSYMS and comboToXdgTrigger
    • browser_button (X11), evdev_button_to_browser_button, windows_mouse::classify
    • PUNCTUATION_KEY_CODES and hookKeyNameForLayoutKey
  • Invariants: no tracing, println or unsafe in non-test code, and no panics outside tests. Debug of PortalUpdate hides the triggers and ShortcutSink prints its name only (tested). The Debug of FakeState contains KeyCombo, which prints …. No changes to fluxer-core. The module header names the ported files and the commit. No Windows-only code.
  • Review Focus 1: no key reaches a log or error from this module. Raw Inputs do leave it by design (the matcher is in core, as plan §8.2 says), so Task 34 has to keep them out of --record and the logs.
  • Gate: FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci on c22ccee6 passed every step (fmt, clippy, deny, core-isolation, parity, test, vendored-tests, screenshot-tests). shortcut_keys ran 12 tests and all passed.

Findings

  1. (minor) The trait has no way to carry ShortcutsCommand::PortalBind or PortalConfigure. Task 28 or Task 34 will need to add default methods to shortcuts/mod.rs (a registration file, append-only). The plan's interface names none, so this is not blocking. It is noted here so Task 28 plans for it.
  2. (minor, parity edge) xdg_keysym_for_combo treats code: Some("") as missing and falls back to the US layout. The original's combo.code ?? … keeps "" and returns no trigger. This only matters if a stored combo ever carries an empty code. Worth a one-line alignment, or a comment, when Task 28 uses it.
  3. (minor, note for Task 34) BackendOutput::Input carries every raw key the back end sees, including unbound ones. The runtime has to make sure ShellEvent::ShortcutInput is never written to --record or a log (that is Task 34's log_contains_no_key).

Verdict: APPROVED (0 blocking, 3 minor; gate green locally).

## Independent review: Shell 25 (shortcut back-end trait, key tables, fake) Reviewed `ef96e13a..c22ccee6` cold. **What I checked** - **Plan tests:** all 7 named tests exist (`every_dom_code_round_trips_per_table`, `extended_scan_codes`, `mouse_buttons_3_and_4`, `layout_key_only_for_printables`, `xdg_trigger_strings`, `no_trigger_for_mouse_or_modifier_only`, `fake_backend_scripts`), plus 5 more. They assert what the plan asks. - **Interfaces:** `ShortcutBackend { kind, start(sink) -> Result<(), BackendError::{Permission, StartFailed, Unsupported}>, set_bindings(&[(ShortcutAction, KeyCombo)]), capture(bool), stop() }`, `ShortcutSink`, `BackendOutput::{Input, Event, Status, Portal}`, `FakeBackend` and `system_backend(kind) -> Option<Box<dyn ShortcutBackend>>` all exist exactly as written. The added `Session(SessionEvent)` variant fits Task 34's `ShellEvent::Session`, and `BackendStatus` has no Locked or Suspending state, so the deviation is justified. - **Parity:** I evaluated the fork's `GlobalShortcutKeys.ts` (ba98441b4) with node and diffed it against the Rust tables. `EVDEV_KEY_CODES` (185), `WINDOWS_SCAN_CODES` (157) and `WINDOWS_VIRTUAL_KEY_CODES` (144) are identical, in the same order. No code appears twice, so the forward lookup is exact. `MACOS_KEY_CODES` adds no name to `KNOWN_DOM_CODES`, as claimed. These also match their sources: - `x11KeycodeToDomCode`, `windowsKeyToDomCode` and `keyCodeIdentity` (`raw` with `WINDOWS_VK_RAW_PREFIX` 0x10000) - `XDG_CODE_KEYSYMS` and `comboToXdgTrigger` - `browser_button` (X11), `evdev_button_to_browser_button`, `windows_mouse::classify` - `PUNCTUATION_KEY_CODES` and `hookKeyNameForLayoutKey` - **Invariants:** no `tracing`, `println` or `unsafe` in non-test code, and no panics outside tests. `Debug` of `PortalUpdate` hides the triggers and `ShortcutSink` prints its name only (tested). The `Debug` of `FakeState` contains `KeyCombo`, which prints `…`. No changes to fluxer-core. The module header names the ported files and the commit. No Windows-only code. - **Review Focus 1:** no key reaches a log or error from this module. Raw `Input`s do leave it by design (the matcher is in core, as plan §8.2 says), so Task 34 has to keep them out of `--record` and the logs. - **Gate:** `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` on c22ccee6 passed every step (fmt, clippy, deny, core-isolation, parity, test, vendored-tests, screenshot-tests). `shortcut_keys` ran 12 tests and all passed. **Findings** 1. *(minor)* The trait has no way to carry `ShortcutsCommand::PortalBind` or `PortalConfigure`. Task 28 or Task 34 will need to add default methods to `shortcuts/mod.rs` (a registration file, append-only). The plan's interface names none, so this is not blocking. It is noted here so Task 28 plans for it. 2. *(minor, parity edge)* `xdg_keysym_for_combo` treats `code: Some("")` as missing and falls back to the US layout. The original's `combo.code ?? …` keeps `""` and returns no trigger. This only matters if a stored combo ever carries an empty code. Worth a one-line alignment, or a comment, when Task 28 uses it. 3. *(minor, note for Task 34)* `BackendOutput::Input` carries every raw key the back end sees, including unbound ones. The runtime has to make sure `ShellEvent::ShortcutInput` is never written to `--record` or a log (that is Task 34's `log_contains_no_key`). **Verdict: APPROVED** (0 blocking, 3 minor; gate green locally).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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 15:41:23 +00:00

Pull request closed

Sign in to join this conversation.
No description provided.