Port upstream 0.67.0: provider switcher shortcut editor and persistence (stacked on #693)

[Finesssee]

Summary

PR 2 of 2 for the deferred upstream 0.67.0 "provider switcher keyboard shortcuts" feature. PR 1 (#693) added the fixed keys (Left/Right, Ctrl+1..9). This PR makes them configurable:

• New switcher_shortcuts setting (overrides only; omitted when everything is default), validated in Rust (rust/src/switcher_shortcuts.rs) and mirrored in apps/desktop-tauri/src/lib/switcherShortcuts.ts.
• The settings snapshot exposes the fully resolved map; the settings patch carries overrides and replaces the stored map ({} restores defaults).
• New Settings > Menu > Provider switcher shortcuts editor (record, clear to none, reset to defaults, inline localized errors for duplicate / reserved / invalid keys).
• The tray flyout and pop-out switcher hook follow the configured shortcuts.
• An invalid stored map falls back to defaults on load with a tracing warning; it does not break the rest of the settings.
• ShortcutCapture gained optional compose, recordingHint and emptyLabel props so the editor reuses it without a mode flag.
• docs/CONFIGURATION.md documents the editor, the switcher_shortcuts key and the rules.

Approved design

From the approved note design-provider-switcher-shortcuts.md, implemented as written:

• Grammar follows upstream: modifier order ctrl alt shift; keys are left, right, ,, or an ASCII letter/digit; none disables an action. cmd is accepted as an alias for ctrl.
• Reserved: ctrl+r, ctrl+q, ctrl+,, ctrl+w, and letters/digits/comma with only shift or no modifier. Duplicates and unknown actions are rejected.
• 11 actions: previous, next, select1..select9. Defaults: left, right, ctrl+1..9.
• Storage: only non-default overrides in settings.json; the snapshot exposes the resolved map.
• The menu settings tab id is reused, so the tab whitelist is unchanged.
• Open questions resolved with the note's recommendations.

Upstream reference

steipete/CodexBar 0.67.0, provider switcher keyboard shortcuts (tag-pinned read only).

Ported / Deferred

Ported: persistence, validation (Rust + TS), snapshot/patch plumbing, Settings > Menu editor, hook wiring, docs.

Deferred: the portable-preferences key switcherShortcuts, because portable preferences does not exist on this base. It can be added when that feature lands.

Validation

• cargo +1.98.0 fmt --all
• cargo +1.98.0 clippy --workspace --all-targets -- -D warnings (both manifests): clean
• cargo +1.98.0 test -p codexbar: 2175 passed, 0 failed
• cargo +1.98.0 test -p codexbar-desktop-tauri: 465 passed, 1 failed. commands::tests::bootstrap_payload_exposes_every_provider_variant reports 79 catalog entries vs 78 active providers. get_bootstrap_state adds a deprecated provider to the catalog when it is enabled in the machine-local settings, so this depends on the developer machine's state and is not touched by this change (this PR only adds a field to the settings snapshot). CI runs on a clean profile.
• pnpm test (vitest): 71 files, 449 tests passed
• pnpm run build (tsc + vite): passed; lint has only pre-existing warnings

Affected areas

• rust/src/switcher_shortcuts.rs (+ tests.rs), rust/src/settings.rs, rust/src/settings/raw.rs, rust/src/locale.rs, rust/src/locale/en-US.ftl
• apps/desktop-tauri/src-tauri/src/commands/settings.rs, commands/bridge.rs
• apps/desktop-tauri/src/: lib/switcherShortcuts.ts, hooks/useProviderSwitcherKeys.ts, hooks/useTrayPanelController.ts, surfaces/PopOutPanel.tsx, surfaces/settings/SwitcherShortcutsSection.tsx, surfaces/settings/tabs/DisplayTab.tsx, components/ShortcutCapture.tsx, i18n/keys.ts, types/bridge.ts
• docs/CONFIGURATION.md

UI proof

This PR changes Settings chrome (Menu tab). CUA / desktop proof has not been captured: the automation run that produced this PR is not permitted to launch the desktop app. Coverage is Vitest component tests (SwitcherShortcutsSection.test.tsx, 8 tests) only. A CUA retest at CODEXBAR_PROOF_MODE=settings:menu on a fresh debug build is still required before merge; hence this is a draft.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Finesssee]

Thermo-nuclear review

Head reviewed: 3b02210e (stacked on #693). Spec: design-provider-switcher-shortcuts.md (upstream 0.67.0 ProviderSwitcherShortcuts, tag-pinned). Verdict: no blocking findings; nothing to fix.

Correctness against the spec

• Grammar and rules match the approved note: modifier order ctrl alt shift, keys left|right|,|[a-z0-9], cmd folded to ctrl, none disables and frees its key, duplicates and unknown actions rejected, reserved ctrl+r/q/,/w, letters/digits/comma need ctrl or alt. alt+f4 / alt+tab fall out as invalid (F4/Tab are outside the grammar), as the note allows.
• Rust (switcher_shortcuts.rs) and TS (lib/switcherShortcuts.ts) were compared branch by branch on empty modifier lists, duplicate modifiers (ctrl+cmd+1), whitespace, none with modifiers, and non-ASCII keys. They agree.
• Storage is override-only, skip_serializing_if keeps settings.json clean, the snapshot exposes the resolved map, and the patch replaces the stored map ({} resets). An invalid stored map is sanitized on load with a tracing::warn! and never blocks the rest of the settings. A rejected patch leaves the stored value untouched (covered by a test).
• Both surfaces (tray panel and pop-out) read settings.switcherShortcuts through useSettings, which re-fetches on settings-changed, so an edit in the detached Settings window reaches them live.

Structure and size

• No file crosses 1000 lines (bridge.rs was already 1063, +4; settings.rs 1437 to 1444, already over). New logic lives in its own module plus a sibling tests.rs, and the editor is its own component rather than more branching in DisplayTab.
• ShortcutCapture gained compose / recordingHint / emptyLabel. These are a function and two strings with the previous behavior as defaults, not a boolean mode flag, so I am not asking for a split.
• Locale keys are en-US only. Other catalogs are already 100 to 200 keys behind en-US and fall back, so this matches repo practice.
• No new dependencies. Reserved and default tables are const arrays, no magic.

Non-blocking notes (left as is, no change requested)

1. Rust and TS each carry a copy of the grammar (~100 lines each). The approved note asks for frontend validation for live feedback, so this is by design. The keep in step comments plus mirrored test cases are the guard; a shared fixture would be the next step if it ever drifts.
2. resolve_or_default (Rust) and the try/catch in resolveSwitcherShortcuts (TS) are defensive only: load already sanitizes and writes are validated. They are cheap and the snapshot conversion is infallible, so I would not spend a refactor on them.
3. The snapshot carries the resolved map while the patch carries overrides. This asymmetry is what the note specifies and it is tested in both directions.

Validation I re-ran

• cargo +1.98.0 fmt --all -- --check: clean.
• vitest run on switcherShortcuts, useProviderSwitcherKeys, SwitcherShortcutsSection, ShortcutCapture: 4 files, 49 tests passed.
• Full cargo and clippy results are the PR-body numbers; the one failing Tauri test named there (bootstrap_payload_exposes_every_provider_variant) is machine-state dependent and untouched here.

UI proof

Settings chrome changed (Menu tab). A proof build from this head and a proof kit are being prepared for the CUA run at CODEXBAR_PROOF_MODE=settings:menu; the PR stays draft until that is captured.

[Finesssee]

Thermo-nuclear review follow-up (second pass)

Reviewed by Codex gpt-6-luna (xhigh); verified and validated by Claude. The earlier review comment stands; this pass found and fixed the following.

Fixed:

• P2 lib/switcherShortcuts.ts: letter shortcuts were read from event.code, which follows US key positions and breaks configured letters on other layouts. Letters now use event.key; digits and comma still use code so Shift+1 and Shift+, keep working. Tests added.
• P2 locale: the 12 switcher-shortcut strings were missing from es-MX, ja-JP, ko-KR and ru-RU (English fallback). Added them plus a regression test.
• P2 ShortcutCapture / SwitcherShortcutsSection: Record and Clear buttons and the status chip had no row context for screen readers. Added per-action accessible names and a component test (also corrected one assertion in that test: the default Next binding is right, so Clear is enabled).

Left:

• Fresh-build CUA proof (including WebView2 handling of Ctrl+digit) is still outstanding; it needs a desktop build and run, which this pass did not do. PR stays draft.
• Tauri crate clippy/tests not re-run: no Rust files in that crate changed.

Commands run: cargo +1.98.0 fmt --all -- --check; cargo +1.98.0 clippy --manifest-path rust/Cargo.toml --all-targets -- -D warnings; cargo +1.98.0 test --manifest-path rust/Cargo.toml --lib -- switcher_shortcut locale (32 passed); vitest on switcherShortcuts, useProviderSwitcherKeys, SwitcherShortcutsSection, ShortcutCapture (53 passed); tsc --noEmit clean.

[Finesssee]

CUA proof (rerun)

Build commit: 66dc1c4212db0a785ebf3e9dcc3606c04c8c800f (current PR head, "Address thermo review"). Debug build via pnpm --dir apps/desktop-tauri run tauri:build:debug.

Proof-only patch (throwaway, restored with git restore, never committed): root Cargo.toml [patch.crates-io] dirs = { path = ".../proof-shim/dirs" }, which redirects home/config/data/cache dirs under CODEXBAR_PROOF_HOME. Settings live in an isolated profile (Codex only, theme auto, seeded Codex 42% / 67% via CODEXBAR_SEED_USAGE_JSON). No provider fetch is involved in this change.

Driven with the cua-driver CLI only, background delivery only (UIA invoke, PostMessage keys, window-state screenshots), proof windows on the second monitor.

#	Assertion	Result
0	No real email/account from the machine visible	PASS
1	Menu tab shows "Provider switcher shortcuts" with helper text, 11 rows (left, right, ctrl+1..9), Record/Clear per row, Reset to defaults	PASS
2	Theme stays dark under auto, no clipped text	PASS
3	Previous provider: Record then Backspace shows "Disabled" and its Clear is disabled	PASS
4	Item 5: Record then bare a shows "That key is reserved. Letters, digits and comma need Ctrl or Alt; ..." and the chip is unchanged	PASS
5	Item 3: Record then right (taken by Next) shows "Go to item 3: That key is already assigned to another action." (red) and the chip stays ctrl+3	PASS
6	A following valid edit (item 2 set to left) succeeds and clears the error line	PASS
7	Reset to defaults restores all 11 chips to left, right, ctrl+1..9	PASS
8	Persistence: Previous disabled + item 2 = left survive an app restart; other rows default	PASS
9	Live effect in tray panel with that map: bare left selects the Codex tile (Session 42%, Secondary 67%)	PASS
10	Modifier combinations (Shift+Right, Ctrl+Alt+2, Ctrl+4 duplicate, Ctrl+R reserved) and the new aria-label / layout-aware letter-key changes	NOT TESTED: background key delivery of modifier combos is refused by the WebView2 surface (background_unavailable), and foreground input was not used because the desktop is in use. Covered by the unit tests only.

Notes: settings.json is DPAPI-wrapped, so the on-disk map was not inspected; persistence was checked through the UI after restart.

Screenshots (local, not committed), %LOCALAPPDATA%\Win-CodexBar\port-audit\proof\700\shots\: 01-tall.png (initial), 05-backspace.png, 06-invalid-a.png, 07-duplicate.png, 08-success-left.png, 09-reset.png, 11-persist-after.png, 12-tray-before.png, 13-tray-after-left.png.

[Finesssee]

UI proof (browser-use)

Build commit: 66dc1c42 (PR head, "Address thermo review", pushed). Debug build via pnpm --dir apps/desktop-tauri run tauri:build:debug (target W:\cargo-target\lane-b). Proof-only patch (throwaway, never committed): root Cargo.toml [patch.crates-io] dirs = <local proof shim> → isolated CODEXBAR_PROOF_HOME.

Driven over WebView2 CDP (port 9352) with browser-use only — DOM reads, programmatic clicks and KeyboardEvent dispatch; no OS-level input. Proof window on DISPLAY2 via proof-window-guard.ps1. Surface: CODEXBAR_PROOF_MODE=settings:menu. This proof complements the earlier CUA proof at the same head (its assertions 1–9); it covers what CUA #10 could not: modifier-combo rendering and a restart-persistence round-trip.

#	Assertion	Result
0	Privacy: page scan shows no emails/personal tokens (kit home uses only synthetic seeded data)	PASS
1	Editor renders: Settings → Menu → "Provider switcher shortcuts" with helper text, 11 capture rows (Previous, Next, Go to item 1..9), 11 Record + 11 Clear buttons, Reset to defaults	PASS
2	Modifier-combo chips render normalized from real KeyboardEvent dispatch through ShortcutCapture: Record(Next) + Shift+Right → chip shift+right; Record(item 2) + Ctrl+Alt+2 → ctrl+alt+2; Record(item 1) + Ctrl+Shift+, → ctrl+shift+, (the layout-aware comma path from the thermo pass)	PASS
3	Persistence round-trip: bridge patch {previous:none, select2:left} → snapshot shows previous:"none", select2:"left", app restart, snapshot still carries the overrides and the chips render Disabled / left; other rows default	PASS
4	Reset to defaults: patch {} restores all 11 chips to left, right, ctrl+1..9 and the snapshot shows the full default map	PASS
5	Inline validation: Record(Previous) + bare h renders the error line Previous provider: That key is reserved. Letters, digits and comma need Ctrl or Alt; Ctrl+R, Ctrl+Q, Ctrl+, and Ctrl+W are taken. (role=alert) and the chip stays left — the Rust-side rejection path mirrors this (bridge rejects with the same message)	PASS
6	Dark theme: body background rgb(28, 28, 30) under auto; locale strings render (en-US from en-US.ftl)	PASS

Caveats (both pre-existing, neither caused by this PR's delta):

• Key delivery: real keyboard input to a background WebView2 surface is refused (background_unavailable — the same limitation documented in the CUA proof feat(ui): localize Windows UI to Simplified Chinese #10). The combo assertions above dispatch DOM KeyboardEvents through the page, which is exactly what the capture component listens for; this is noted so the evidence is not mistaken for OS-level keystrokes.
• Focus: document.hasFocus() read false during this capture, but as with the [0.64.1] Animate budget disclosure chevron #608 proof the branch base predates Stop CodexBar from stealing focus #713 (no-focus-stealing, integrated on main); this PR's delta touches no activation path.

Screenshots (local, not committed), in port-audit\proof\700\shots\ (mirrored to both port-audit paths): b1-editor-overrides.png, b2-persist-after-restart.png, b3-invalid-error.png, b4-modifier-combos.png, b5-final-dark.png.

[Finesssee]

UI proof (browser-use)

Combined build of integrate/v0.70.0-ports at ddd85594 (all 40 port PRs and the follow-ups). Debug desktop build in proof mode, isolated config/data dirs, driven by browser-use over the WebView2 DevTools protocol with DOM events only (no mouse or keyboard input, no focus changes). All data is synthetic: local mock servers for L1, a seeded usage snapshot plus synthetic local logs for L2.

The PopOut layout is retired on the release line, so the shortcuts reach the tray flyout only (follow-up 40b29a5 drops the pop-out wording).

Scenario	Check	Result
L1 extras (preferences, keys, toggles)	#700 Menu editor: 11 shortcut rows; Next shows the imported ctrl+shift+right, Previous left, Select 3 ctrl+3	PASS
L1 extras (preferences, keys, toggles)	#700 helper text names the tray panel, no pop-out wording	PASS
L1 extras (preferences, keys, toggles)	#693/#700 flyout keys under the imported override: plain Right does nothing, ctrl+shift+Right steps Overview -> 1st -> 2nd provider, Left back, ctrl+3 = 2nd provider, ctrl+1 = Overview	PASS
L1 editor reset re-export	#700 editor Reset: re-export has no switcher_shortcuts (overrides empty) and the resolved map equals the defaults	PASS

Every surface also passed the privacy check (no email-like text, account e-mail nodes or profile paths in the DOM) and theme auto rendered dark on the tray flyout, float bar and settings windows.

Validation at ddd85594: cargo fmt --all --check, cargo clippy --workspace --all-targets -- -D warnings, cargo test -p codexbar (3567 passed, 0 failed) and cargo test -p codexbar-desktop-tauri (606 passed, 0 failed). Screenshots were captured for each scenario and kept with the local proof kit.

[Finesssee]

Shipped in v0.70.0: this PR's head is included in main via #735 (merge commit 9d0a37a). Closing as integrated.