feat(desktop/hotkeys): v1 directional pane focus + best-effort v1 override migrator

[saddlepaddle]

Summary

Two related hotkey fixes bundled together:

• Restore directional pane focus in v1 workspaces. PR feat(desktop): Cmd+Alt+Arrow moves focus between v2 panes #3403 wired Cmd+Alt+Arrow spatial pane focus for v2 but skipped v1, leaving v1 with no keyboard pane navigation at all. Reimplements the spatial neighbor walker against v1's MosaicNode<string> tree (no cross-package coupling to v2's LayoutNode) and adds FOCUS_PANE_LEFT/RIGHT/UP/DOWN handlers to the v1 workspace route. Also teaches the recorder that Option is a legitimate app modifier on Mac (⌥⌫ etc.) and warns when an alt-only chord could mask typing special characters.

• Best-effort migrator for v1 hotkey overrides. The v1 recorder stored chords from event.key — layout-dependent raw glyphs like meta+,, ctrl+shift+@, meta+alt+ª — while the new store matches on event.code names. The previous sanitizeOverride was strict (/^[a-z0-9]+$/) and silently dropped most real-world v1 entries. Extends it with a token rewrite pre-pass covering:

  • US-ANSI punctuation (,→comma, [→bracketleft, etc.)
  • Shifted glyphs (@→2, _→minus, ?→slash, etc.)
  • macOS Option dead-keys (ª→9, å→a, •→8, etc.)

  The Mac Option table is gated behind a navigator.keyboard.getLayoutMap() probe — on non-US Mac layouts (where Option+Q produces • instead of œ), the glyphs fall through and drop rather than silently rebind to the wrong physical key.

Coverage

Validated against three real leveldb / app-state dumps captured from the indigo-pentaceratops (v1.4.7), tray-polling-fix, and hotkeys-fixes worktrees — every captured chord is locked in as a parametric test case. 20/20 entries from the v1.4.7 blob now migrate successfully (17 rewritten + 3 null unassigns). 64 tests total in overrideSanitizer.test.ts.

Test plan

• bun test apps/desktop/src/renderer/hotkeys/utils/overrideSanitizer.test.ts — 64 pass
• bun run --filter=@superset/desktop typecheck — clean
• bun run lint — clean
• Smoke test v1 workspace: build 2×2 pane grid, verify Cmd+Alt+Arrow walks to the spatially adjacent pane, edges are no-ops
• Smoke test v2 workspace: same chord still works (no v2 files touched)
• Boot against an existing app-state.json with v1 overrides, confirm migration runs once and localStorage.getItem('hotkey-overrides') contains the rewritten entries
• Verify on a non-US Mac layout (or swap layout via System Settings): dead-key glyphs drop instead of being mis-rewritten

---

Summary by cubic

Restores Cmd+Alt+Arrow directional pane focus in v1 workspaces and migrates v1 hotkey overrides to the v2 format so users keep their shortcuts. Adds Mac-specific recording logic and a safety warning for alt-only chords.

• New Features

  • v1: Added spatial pane focus (left/right/up/down) using a Mosaic walker; binds FOCUS_PANE_LEFT/RIGHT/UP/DOWN and no-ops at edges.
  • Recorder: Accepts Option-only chords on macOS and warns that Option shortcuts may block typing special characters.
  • v2 behavior unchanged.

• Migration

  • Converts v1 event.key chords (e.g., "meta+,", "ctrl+shift+@", "meta+alt+ª") to event.code names.
  • Rewrites US-ANSI punctuation and shifted glyphs; recovers macOS Option dead-keys only on US‑compatible layouts (via navigator.keyboard.getLayoutMap()).
  • Drops ambiguous non‑US dead‑key glyphs instead of misbinding.
  • Added focused tests covering real overrides.

^{Written for commit 1b3099d. Summary will update on new commits.}

Summary by CodeRabbit

• New Features

  • Added directional pane navigation hotkeys (Focus Pane Left/Right/Up/Down) for easier workspace navigation.
  • Enhanced macOS keyboard support with improved Option key recognition for custom hotkeys.

• Improvements

  • Better keyboard shortcut organization in settings with Navigation category.
  • Improved hotkey sanitization and keyboard layout detection.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 458d512e-d4d6-493a-a20e-582cf48df8dd

📥 Commits

Reviewing files that changed from the base of the PR and between 93140d9 and 1b3099d.

⛔ Files ignored due to path filters (1)

• bun.lock is excluded by !**/*.lock

📒 Files selected for processing (8)

• apps/desktop/src/renderer/hotkeys/hooks/useRecordHotkeys/useRecordHotkeys.ts
• apps/desktop/src/renderer/hotkeys/migrate.ts
• apps/desktop/src/renderer/hotkeys/utils/detectUSLayout.ts
• apps/desktop/src/renderer/hotkeys/utils/overrideSanitizer.test.ts
• apps/desktop/src/renderer/hotkeys/utils/sanitizeOverride.ts
• apps/desktop/src/renderer/routes/_authenticated/_dashboard/workspace/$workspaceId/page.tsx
• apps/desktop/src/renderer/routes/_authenticated/settings/keyboard/page.tsx
• apps/desktop/src/renderer/stores/tabs/utils.ts

---

📝 Walkthrough

Walkthrough

These changes enhance hotkey handling on macOS by detecting keyboard layouts, supporting Mac Option modifier for hotkeys, and improving sanitization of override strings. Additionally, directional pane navigation with spatial awareness is introduced alongside corresponding hotkeys.

Changes

Cohort / File(s)	Summary
Hotkey Recording & Mac Option Support apps/desktop/src/renderer/hotkeys/hooks/useRecordHotkeys/useRecordHotkeys.ts	Modified captureHotkeyFromEvent to treat Mac Option (altKey) as a valid modifier for non-F keys. Added isMacAltOnlyChord helper to detect and warn about Option-only chords (alt+<key> without meta/ctrl).
Keyboard Layout Detection apps/desktop/src/renderer/hotkeys/utils/detectUSLayout.ts	New module exposing isUSCompatibleLayout() that probes the Keyboard Map API to detect US-compatible layouts, with memoized results and a test reset function. Falls back to true if API unavailable.
Hotkey Sanitization apps/desktop/src/renderer/hotkeys/utils/sanitizeOverride.ts	Updated to accept SanitizeOverrideOptions parameter. Adds ALWAYS_SAFE_REWRITES and MAC_US_DEAD_KEYS lookup maps to rewrite punctuation and dead-key glyph tokens before canonicalization based on layout detection.
Migration & Layout Integration apps/desktop/src/renderer/hotkeys/migrate.ts	Integrated US layout detection during migration; passes assumeUSMacLayout flag to sanitizeOverride() based on platform and detected keyboard layout.
Pane Spatial Navigation apps/desktop/src/renderer/stores/tabs/utils.ts, apps/desktop/src/renderer/routes/_authenticated/_dashboard/workspace/$workspaceId/page.tsx	Added FocusDirection type and getSpatialNeighborMosaicPaneId() algorithm to compute visually adjacent panes. Workspace page registers four new directional focus hotkeys (FOCUS_PANE_LEFT/RIGHT/UP/DOWN) to navigate pane tree spatially.
Keyboard Settings UI apps/desktop/src/renderer/routes/_authenticated/settings/keyboard/page.tsx	Reordered keyboard shortcut categories to render "Navigation" first in the settings table.
Comprehensive Test Suite apps/desktop/src/renderer/hotkeys/utils/overrideSanitizer.test.ts	Restructured test organization with granular test groups covering input validation, canonicalization, v1 normalization, hardware/OS-specific rules, layout gates, and integration-style table-driven tests. Expanded coverage for punctuation rewrites, arrow aliasing, multi-char tokens, function keys, numpad edge cases, and macOS dead-key recovery.

Sequence Diagram

sequenceDiagram
    actor User
    participant WorkspacePage as Workspace Page
    participant Focus as Focus Handler
    participant Spatial as Spatial Navigator
    participant Store as Focus Store

    User->>WorkspacePage: Press hotkey (e.g., Ctrl+Left)
    WorkspacePage->>Focus: moveFocusDirectional("left")
    Focus->>Spatial: getSpatialNeighborMosaicPaneId(root, currentPaneId, "left")
    Spatial->>Spatial: Locate mosaic path to currentPaneId
    Spatial->>Spatial: Traverse ancestor splits aligned with left axis
    Spatial->>Spatial: Descend perpendicular split to select edge pane
    Spatial-->>Focus: Return neighbor paneId or null
    Focus->>Store: setFocusedPane(neighborPaneId)
    Store->>WorkspacePage: Update focused pane state
    WorkspacePage->>User: Render focus highlight on neighbor pane

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Poem

🐰 Mac's Option key now hops in place,
US layouts dance with grace,
Spatial panes leap left and right,
As hotkeys guide the focus bright! ✨🎹

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 22.22% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately captures the two main changes: v1 directional pane focus restoration and v1 hotkey override migration, matching the substantive file changes across the codebase.
Description check	✅ Passed	The description is comprehensive, covering motivation, implementation details, test coverage, and a detailed test plan. It follows the template structure with clear sections for Summary, Coverage, and Test plan.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch hotkeys-fixes

---

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 and usage tips.}

[cubic-dev-ai]

No issues found across 9 files

[github-actions]

🧹 Preview Cleanup Complete

The following preview resources have been cleaned up:

• ✅ Neon database branch
• ✅ Electric Fly.io app

Thank you for your contribution! 🎉

[greptile-apps]

Greptile Summary

This PR delivers two well-scoped hotkey improvements for the desktop app: directional pane focus for v1 workspaces (matching the v2 behaviour added in #3403) and a best-effort v1 override migrator that handles the event.key→event.code format gap that was silently dropping most real-world user overrides.

Key changes:

• utils.ts — adds getSpatialNeighborMosaicPaneId, findPanePath, getFirstPaneId, and FocusDirection type to implement a Mosaic-tree spatial walker; algorithm correctly handles cross-axis alignment via a path hint and returns null at the outer grid edges.
• workspace/$workspaceId/page.tsx — wires FOCUS_PANE_LEFT/RIGHT/UP/DOWN hotkeys to moveFocusDirectional using useCallback with correct dependency arrays.
• sanitizeOverride.ts — new file with three layered rewrite tables (US punctuation, shifted glyphs, Mac Option dead-keys); the regex gate [a-z0-9]+ is sufficient for all known event.code names produced by the tables.
• migrate.ts — bumps the migration marker to -v2 so users on the pre-sanitizer build re-migrate; error path leaves the marker unset for automatic retry on next boot.
• detectUSLayout.ts — module-level cached Keyboard Layout Map probe; 6-key heuristic catches QWERTZ, AZERTY, and UK layouts correctly; optimistic fallback on file:// (packaged Electron) is intentional and documented.
• useRecordHotkeys.ts — allows Mac Option as a standalone app modifier and emits a warning for alt-only chords that may mask special-character input.
• 64 parametric tests including real production data blobs lock in the migration behaviour.

Confidence Score: 4/5

Safe to merge; the only open item is a minor UX gap where alt+backspace/alt+delete cannot be re-recorded via the keyboard settings UI now that alt-only Mac chords are supported.

The spatial navigation algorithm is correct (traced through multiple 2×2 layouts manually), the migrator is well-tested against real production data with 64 passing parametric cases, type-check and lint are clean, and the one-time migration marker design handles transient failures gracefully. The only gap is the recorder's Backspace/Delete unassign intercept firing before the new altIsAppModifier guard — a UX limitation, not a data-loss or correctness issue.

No files require special attention beyond the P2 note on useRecordHotkeys.ts regarding alt+backspace/delete recording.

Important Files Changed

Filename	Overview
apps/desktop/src/renderer/hotkeys/hooks/useRecordHotkeys/useRecordHotkeys.ts	Adds Mac Option as a valid recording modifier (altIsAppModifier) and warns when an alt-only chord could mask special-character typing; Escape/Backspace/Delete intercept still fires before the modifier guard, preventing alt+backspace and alt+delete from being recordable via the UI.
apps/desktop/src/renderer/hotkeys/migrate.ts	One-time migration from tRPC-backed JSON to localStorage; marker key bumped to -v2 to force a re-run for users who migrated before the sanitizer landed; error path intentionally leaves marker unset for retry-on-next-boot semantics.
apps/desktop/src/renderer/hotkeys/utils/detectUSLayout.ts	Module-level cache for the Keyboard Layout Map API probe; optimistic fallback to true on file:// (packaged Electron) is intentional and documented; 6-key heuristic correctly identifies AZERTY/QWERTZ/UK layouts as non-US.
apps/desktop/src/renderer/hotkeys/utils/overrideSanitizer.test.ts	64 parametric test cases covering input validation, v2 identity, v1 punctuation rewrites, shifted-glyph recovery, numpad edge-case, Mac dead-key recovery, non-US opt-out, and real captured production blobs; thorough and well-organized.
apps/desktop/src/renderer/hotkeys/utils/sanitizeOverride.ts	New file implementing v1→v2 chord migration with three rewrite tables (always-safe punctuation, shifted glyphs, Mac dead-keys); logic is well-structured and correctly handles the separator-collision edge case via regex gating.
apps/desktop/src/renderer/routes/_authenticated/_dashboard/workspace/$workspaceId/page.tsx	Wires FOCUS_PANE_LEFT/RIGHT/UP/DOWN hotkeys for the v1 workspace route using getSpatialNeighborMosaicPaneId; useCallback deps are correct and consistent with other hotkey callbacks in the same file.
apps/desktop/src/renderer/routes/_authenticated/settings/keyboard/page.tsx	Warning-severity reserved chords now emit a toast but still allow the save to proceed; consistent with the PR's intent to warn (not block) on alt-only chords.
apps/desktop/src/renderer/stores/tabs/utils.ts	Adds FocusDirection, getSpatialNeighborMosaicPaneId, findPanePath, getFirstPaneId, and related helpers for v1 Mosaic spatial navigation; algorithm correctly handles cross-axis alignment via the alignmentPath hint and returns null at outer edges.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[App boot] --> B{migration marker set?}
    B -- yes --> Z[skip]
    B -- no --> C[fetch v1 overrides via tRPC]
    C --> D{any overrides?}
    D -- no --> E[set marker, log skip]
    D -- yes --> F{PLATFORM === mac?}
    F -- yes --> G[isUSCompatibleLayout\ngetLayoutMap probe]
    F -- no --> H[assumeUSMacLayout = true]
    G --> I{US-compatible?}
    I -- yes --> H
    I -- no --> J[assumeUSMacLayout = false]
    H & J --> K[sanitizeOverride per entry]
    K --> L{result?}
    L -- string --> M[include in cleaned map]
    L -- null --> M
    L -- undefined --> N[drop / increment dropped counter]
    M & N --> O[write to localStorage hotkey-overrides]
    O --> P[set migration marker]

    subgraph sanitizeOverride
        K1[split by +] --> K2[ALWAYS_SAFE_REWRITES]
        K2 --> K3{assumeUSMacLayout?}
        K3 -- yes --> K4[MAC_US_DEAD_KEYS]
        K3 -- no --> K5[pass through]
        K4 & K5 --> K6[canonicalizeChord]
        K6 --> K7{single non-modifier matching a-z0-9+?}
        K7 -- yes --> K8[return canonical]
        K7 -- no --> K9[return undefined]
    end

Loading

Comments Outside Diff (1)

1. apps/desktop/src/renderer/hotkeys/hooks/useRecordHotkeys/useRecordHotkeys.ts, line 124-133 (link)

   alt+backspace / alt+delete can't be recorded

   The Escape, Backspace, and Delete intercepts fire on event.key before captureHotkeyFromEvent is reached. Now that altIsAppModifier makes alt-only chords capturable on Mac, pressing Option+Delete (⌥⌫ — the "delete word" shortcut explicitly cited in the PR description) during recording will trigger the unassign path rather than capturing alt+delete as a chord.

   If no current registry entry uses these combinations this is a silent limitation rather than an active regression, but worth a comment so the next person who adds an alt+backspace-style default doesn't wonder why it can't be re-recorded. Possible fix: check event.altKey (and skip the unassign shortcut) when PLATFORM === "mac" and alt is the sole non-shift modifier.

   // Escape cancels recording unconditionally.
   if (event.key === "Escape") {
       optionsRef.current?.onCancel?.();
       return;
   }
   
   // Backspace/Delete unassign — but not when they're part of an alt-only chord
   // on Mac, so users can record ⌥⌫ / ⌥Delete if needed.
   const altOnly = PLATFORM === "mac" && event.altKey && !event.metaKey && !event.ctrlKey;
   if (!altOnly && (event.key === "Backspace" || event.key === "Delete")) {
       setOverride(recordingId, null);
       optionsRef.current?.onUnassign?.(recordingId);
       return;
   }

_{Reviews (1): Last reviewed commit: "feat(desktop/hotkeys): best-effort migra..." | Re-trigger Greptile}

[greptile-apps]

Regex rejects multi-word code names used outside the rewrite tables

The final guard !/^[a-z0-9]+$/.test(keys[0]) passes for all names currently produced by the rewrite tables (bracketleft, arrowup, pagedown, etc.). However, if a v1 chord ever stored a hyphenated or otherwise non-alphanumeric code name (e.g. a future key like numpad-decimal from an obscure layout), it would be silently dropped even though canonicalizeChord might have accepted it. The current table coverage makes this a theoretical concern, but a comment explaining why [a-z0-9]+ is sufficient given the known code-name vocabulary would help the next person extending ALWAYS_SAFE_REWRITES.