feat: user-editable keyboard shortcuts

[lenisko]

Summary

Adds a Settings → Actions pane that lets users rebind every keyboard shortcut in FlowVision (~90 actions, ~120 chord slots). Defaults are bit-identical to the previous hardcoded
dispatcher; existing muscle memory continues to work without any user action.

Why

The original KeyShortcut.swift was a 1000-line dispatcher with chords baked into the logic. Users couldn't rebind, RTL handling was scattered, and adding a new action meant editing
eight places. This PR splits dispatch (what to do) from binding (which key does it), routes everything through a single chord-lookup table, and exposes that table to the user.

Architecture

Component	Responsibility
ShortcutAction (enum)	Every rebindable action — one case per behavior.
ShortcutDef (struct)	Per-action metadata: category, scope, English name, default chords, flags. One central table.
KeyChord (struct)	Layout-independent (keyCode, modifiers) — character is display metadata only, hash/eq ignore it.
ShortcutStore (singleton)	Bindings + reverse-index, persisted to UserDefaults["shortcutBindings.v2"]. Posts .shortcutsChanged on mutation.
ShortcutRecorderView (NSView)	First-responder + keyDown capture. Bare Esc clears; right-click → Clear.
ActionsSettingsViewController	Two-column table grouped by category. Per-action: [recorder] [+] [↺] plus [recorder] [−] rows for extra chords.
ViewController.KeyShortcutManager	Dispatch pipeline (see below).
AppDelegate.syncMenuShortcuts	Walks mainMenu, applies keyEquivalent from store to any item whose identifier matches an action rawValue. Re-runs on .shortcutsChanged.

Dispatch pipeline (KeyShortcutManager)

1. Window-active gate — events from other windows pass through when isKeyEventEnabled.
2. Non-rebindable text input — quick-search letter/digit, backspace, Esc-to-clear.
3. Text-system fallthrough — Home/End + Cmd+ACVXZ in rename modals / OCR (sent to NSText selectors).
4. 0.1 s debounce — caps held-key repeat rate for chord dispatch (text input bypasses).
5. Non-rebindable navigation — F2/Enter rename, Tab focus swap, outline arrows, collection-view findClosestItem arrows. Gated by isKeyEventEnabled.
6. Reverse-index chord lookup — ShortcutStore.reverseIndex[chord] → first action whose state gate (firesDuringSearch vs isKeyEventEnabled) and scope gate (browserOnly /
   viewerOnly / both) both pass.

Scope model

Cross-scope chord collisions are intentional and load-bearing:

• W = browser dir up (scope: browserOnly) AND viewer zoom-in (scope: viewerOnly)
• S = browser dir down AND viewer zoom-out
• A / D = browser dir left/right AND viewer prev/next
• F = sidebar toggle (browser) AND mirror horizontal (viewer)

Same-scope collisions trigger the conflict dialog at bind time.

Persistence — wire format

v2 (shortcutBindings.v2):

{ "version": 2, "entries": [{ "action": "viewerZoomIn", "chords": [...] }, ...] }

• Missing entry + not cleared → fall back to defaultChords.
• chords: [] → user explicitly wiped this action (defaults won't sneak back).
• v1 migration: single-chord blobs auto-migrate on first load. Legacy shortcutBindings.v1 key is only deleted after a successful v2 write — failed migrations retry on next launch.

Conflict / system-reserved handling

Trigger	UX
Chord already bound to another action with overlapping scope	"Shortcut conflict — reassign?" Reassign strips the chord from blockers in one pass (single table reload).
Chord is a macOS HIG convention (Cmd+Q/W/N/M/etc.) and target isn't itself system-conventional	"Override system-reserved shortcut?" prompt.
Chord is the locked primary default of another action (e.g. Cmd+Q owned by quitApp)	Hard reject — alert + drop the pending slot.
Target action has hasLockedPrimary (currently only quitApp)	Primary recorder rendered disabled; extras still bindable.

Storyboard wiring

Menu items that should reflect the live binding gain an identifier="<actionRawValue>" attribute. syncMenuShortcuts then walks the main menu and applies the current chord's
keyEquivalent. Bare-letter and Fn-only chords are skipped so AppKit doesn't hijack text-input events through the menu — those keys route exclusively through the NSEvent local monitor.

What stays non-rebindable

By design — these are context-dynamic, not keystroke-driven:

• Quick-search letter input — would conflict with typing search terms.
• Text-system shortcuts in rename / OCR — Cmd+A/C/V/X/Z and Home/End delegate to the focused responder.
• F2 / Enter rename, Tab focus swap, arrow-key grid navigation — depend on first-responder identity and selection geometry, not fixed chords.
• Esc close viewer / clear selection — keyCode-only branch; modifier variants are user-rebindable via viewerClose / browserDeselect.

How to add a new action

Documented inline at the top of ShortcutAction.swift:

// 1. Add the case in the appropriate MARK group.
// 2. Add a `case` to `buildDef` returning a ShortcutDef — compiler enforces.
// 3. Add a `dispatch` case in KeyShortcut.swift that runs the handler.
// 4. (Optional) Add identifier=<rawValue> to the menu item in Main.storyboard.

Compiler-enforced exhaustiveness means a missing metadata entry or dispatch case is a build error, not a runtime surprise.

Compatibility / verification

• Builds against macOS 11.0+ on Xcode 17.
• Every default chord preserved against the pre-refactor dispatcher (full per-case audit).
• RTL handling, video frame-seek (Cmd+←/→), Cmd+Opt+Return fullscreen, Cmd+Shift+T reopen, EDIT_FEATURE_ENABLED gate, Cmd+ForwardDelete no-prompt delete, Tab focus while OCR/rename
  modal open — all verified.
• v1 → v2 migration: round-trip one-chord-per-action without data loss.

Files

New

• FlowVision/Sources/Shortcuts/KeyChord.swift
• FlowVision/Sources/Shortcuts/ShortcutAction.swift
• FlowVision/Sources/Shortcuts/ShortcutStore.swift
• FlowVision/Sources/Shortcuts/ShortcutRecorderView.swift
• FlowVision/Sources/SettingsViews/ActionsSettingsViewController.swift

Modified

• FlowVision/Sources/ViewControllerExtension/KeyShortcut.swift — rewritten as dispatcher.
• FlowVision/Sources/AppDelegate.swift — load store + menu sync.
• FlowVision/Resources/Base.lproj/Main.storyboard — identifier= on menu items that should auto-sync.

[lenisko]

Hey there. This PR adds ability to change/add new keyboard shortcuts. It might need some expert eyes, changes itself are working, though I haven't tested all shortcuts.

[netdcy]

Hi. Thank you very much for your work!

Custom key bindings have indeed been a long‑missing feature, and the reason is that a perfect implementation requires considering many factors, such as:

1. How to help users understand the software’s unique features (e.g., right‑click gestures, quick search, image manipulation, custom view‑style switching), whereas a simple list of customizable keys fails to highlight these aspects.
2. How to handle key conflicts and differences across various scenarios, such as thumbnail view and image view (your approach of dividing by smaller concepts is a good idea).

Regarding this pull request, there are still a few questions:

3. Currently, the default key chords use hardcoded key codes, and equality checks are also based on these codes. We need to confirm that these hardcoded key codes remain consistent across different keyboard layouts; otherwise, it could lead to the issue described in Key commands locked to US/EN keyboard, unusable on Nordic keyboard #16.
4. What is shortcutBindings.v1?
5. Which LLM did you use to assist with writing the code?

[lenisko]

Hey, thanks for interest! Been looking for fitting image viewer on Mac for years, had it hard as pervious IrfanView user which was doing a great job on Windows.

1. Agree. Btw, this PR is only touching keyboard shortcuts, without mouse related actions. Assumed it might be way too big to ship in a single PR.
2. 👍
3. You are right, this change will bring back regression, but leaves an option for Norwegian users to re-bind via settings. should be handled now.
4. Legacy persistence format - previous version was using only single shortcut per action, I was using it pre changes, hence migration. Dropped it.
5. I'm using Claude Opus 4.7/4.8. I don't have great experience around Swift (except small changes over years) so not hiding a fact it might need a pair of eyes :)