From 775f71def0d73cb8d20e9174795f794d07289116 Mon Sep 17 00:00:00 2001
From: lenisko <10072920+lenisko@users.noreply.github.com>
Date: Sat, 23 May 2026 01:58:40 +0200
Subject: [PATCH 1/7] feat: user-editable keyboard shortcuts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a Settings → Actions pane that rebinds every keyboard shortcut
in FlowVision (~90 actions, ~120 chord slots). Defaults are
bit-identical to the previous hardcoded dispatcher.

Architecture
- ShortcutAction: enum of every rebindable behavior.
- ShortcutDef: single-source metadata table (category, scope, English
  name, default chords, firesDuringSearch, isSystemConventional,
  hasLockedPrimary). Built once at first access, cached.
- KeyChord: layout-independent (keyCode, modifiers); character is
  display-only and ignored by hash/eq so the same physical key matches
  across layouts.
- ShortcutStore: bindings + reverse-index, persisted to UserDefaults
  under shortcutBindings.v2. Posts .shortcutsChanged on mutation.
  v1 (single-chord) blobs auto-migrate; legacy key only dropped after
  a successful v2 write.
- ShortcutRecorderView: NSView capturing a chord via first-responder.
  Bare Esc clears; right-click → Clear.
- KeyShortcutManager (rewritten): window gate → non-rebindable text
  input → text-system fallthrough → 0.1s debounce → non-rebindable
  navigation → reverse-index chord lookup gated by scope + state.
- AppDelegate.syncMenuShortcuts: walks main menu, applies current
  keyEquivalents to items whose identifier matches an action rawValue.
  Bare-letter and Fn-only chords skip menu sync to avoid AppKit
  hijacking text input.

Scope model
- browserOnly fires only when \!isInLargeView.
- viewerOnly fires only in viewer.
- both fires always.
- Cross-scope collisions are intentional (W = browser up + viewer
  zoom-in, A/D = browser nav + viewer prev/next, F = sidebar +
  mirror, etc.).

Conflict handling
- Same-scope duplicate → "Shortcut conflict — reassign?" with
  one-pass strip of the blocker.
- macOS HIG convention chord on non-system-conventional action →
  override confirm.
- Locked primary default of another action (currently only Cmd+Q
  for quitApp) → hard reject, drop pending slot.
- hasLockedPrimary actions render the primary recorder disabled;
  extras remain bindable.

Non-rebindable surfaces (by design)
- Quick-search letter input.
- Cmd+ACVXZ + Home/End in OCR / rename text fields (delegated to
  the text system).
- F2 / Enter rename, Tab focus swap, outline + grid arrow nav
  (context-dynamic, not keystroke-driven).

Adding a new action: case in enum, case in buildDef, case in
dispatch, optional storyboard identifier. Compiler enforces all of
them via exhaustive switches.
---
 FlowVision.xcodeproj/project.pbxproj          |   24 +
 .../Resources/Base.lproj/Main.storyboard      |   46 +-
 FlowVision/Sources/AppDelegate.swift          |   58 +-
 .../ActionsSettingsViewController.swift       |  579 +++++-
 FlowVision/Sources/Shortcuts/KeyChord.swift   |  233 +++
 .../Sources/Shortcuts/ShortcutAction.swift    |  628 +++++++
 .../Shortcuts/ShortcutRecorderView.swift      |  153 ++
 .../Sources/Shortcuts/ShortcutStore.swift     |  276 +++
 .../ViewControllerExtension/KeyShortcut.swift | 1641 +++++++----------
 9 files changed, 2669 insertions(+), 969 deletions(-)
 create mode 100644 FlowVision/Sources/Shortcuts/KeyChord.swift
 create mode 100644 FlowVision/Sources/Shortcuts/ShortcutAction.swift
 create mode 100644 FlowVision/Sources/Shortcuts/ShortcutRecorderView.swift
 create mode 100644 FlowVision/Sources/Shortcuts/ShortcutStore.swift

diff --git a/FlowVision.xcodeproj/project.pbxproj b/FlowVision.xcodeproj/project.pbxproj
index 1f540927..17653e6c 100644
--- a/FlowVision.xcodeproj/project.pbxproj
+++ b/FlowVision.xcodeproj/project.pbxproj
@@ -81,6 +81,10 @@
 		F7F600482E1E095500ED8536 /* FinderTag.swift in Sources */ = {isa = PBXBuildFile; fileRef = F7F600472E1E094A00ED8536 /* FinderTag.swift */; };
 		F7FAE0012F6BA00000FAE001 /* FavoritesPopoverViewController.swift in Sources */ = {isa = PBXBuildFile; fileRef = F7FAE0002F6BA00000FAE000 /* FavoritesPopoverViewController.swift */; };
 		F7FED5F32F7D0B1100E35164 /* Tagging.swift in Sources */ = {isa = PBXBuildFile; fileRef = F7FED5F22F7D0B0E00E35164 /* Tagging.swift */; };
+		F7CD001C2F0E000000C9AB85 /* KeyChord.swift in Sources */ = {isa = PBXBuildFile; fileRef = F7CD001B2F0E000000C9AB85 /* KeyChord.swift */; };
+		F7CD001E2F0E000000C9AB85 /* ShortcutAction.swift in Sources */ = {isa = PBXBuildFile; fileRef = F7CD001D2F0E000000C9AB85 /* ShortcutAction.swift */; };
+		F7CD00202F0E000000C9AB85 /* ShortcutStore.swift in Sources */ = {isa = PBXBuildFile; fileRef = F7CD001F2F0E000000C9AB85 /* ShortcutStore.swift */; };
+		F7CD00222F0E000000C9AB85 /* ShortcutRecorderView.swift in Sources */ = {isa = PBXBuildFile; fileRef = F7CD00212F0E000000C9AB85 /* ShortcutRecorderView.swift */; };
 /* End PBXBuildFile section */
 
 /* Begin PBXCopyFilesBuildPhase section */
@@ -197,6 +201,10 @@
 		F7F600472E1E094A00ED8536 /* FinderTag.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = FinderTag.swift; sourceTree = "<group>"; };
 		F7FAE0002F6BA00000FAE000 /* FavoritesPopoverViewController.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = FavoritesPopoverViewController.swift; sourceTree = "<group>"; };
 		F7FED5F22F7D0B0E00E35164 /* Tagging.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = Tagging.swift; sourceTree = "<group>"; };
+		F7CD001B2F0E000000C9AB85 /* KeyChord.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = KeyChord.swift; sourceTree = "<group>"; };
+		F7CD001D2F0E000000C9AB85 /* ShortcutAction.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ShortcutAction.swift; sourceTree = "<group>"; };
+		F7CD001F2F0E000000C9AB85 /* ShortcutStore.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ShortcutStore.swift; sourceTree = "<group>"; };
+		F7CD00212F0E000000C9AB85 /* ShortcutRecorderView.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ShortcutRecorderView.swift; sourceTree = "<group>"; };
 /* End PBXFileReference section */
 
 /* Begin PBXFrameworksBuildPhase section */
@@ -274,6 +282,7 @@
 				F7790ECB2BA5CA9200406D35 /* WindowController.swift */,
 				F7A075552BA1D716009C47A6 /* ViewController.swift */,
 				F770988F2F0E3C5400E7D164 /* ViewControllerExtension */,
+				F7CD001A2F0E000000C9AB85 /* Shortcuts */,
 				F73865DC2C37BD7F00837FE4 /* Common */,
 				F7C2DEB92C4E6BB2003DF765 /* SettingsViews */,
 				F73865E92C37C3EA00837FE4 /* Views */,
@@ -281,6 +290,17 @@
 			path = Sources;
 			sourceTree = "<group>";
 		};
+		F7CD001A2F0E000000C9AB85 /* Shortcuts */ = {
+			isa = PBXGroup;
+			children = (
+				F7CD001B2F0E000000C9AB85 /* KeyChord.swift */,
+				F7CD001D2F0E000000C9AB85 /* ShortcutAction.swift */,
+				F7CD001F2F0E000000C9AB85 /* ShortcutStore.swift */,
+				F7CD00212F0E000000C9AB85 /* ShortcutRecorderView.swift */,
+			);
+			path = Shortcuts;
+			sourceTree = "<group>";
+		};
 		F754F3C62C10393700A25D12 /* Frameworks */ = {
 			isa = PBXGroup;
 			children = (
@@ -526,6 +546,10 @@
 				F74D554E2F0E459C00C9AB85 /* WindowManagement.swift in Sources */,
 				F73865D32C37B97500837FE4 /* CustomCollectionView.swift in Sources */,
 				F74D555E2F0E52F800C9AB85 /* ArrowKeyLocate.swift in Sources */,
+				F7CD001C2F0E000000C9AB85 /* KeyChord.swift in Sources */,
+				F7CD001E2F0E000000C9AB85 /* ShortcutAction.swift in Sources */,
+				F7CD00202F0E000000C9AB85 /* ShortcutStore.swift in Sources */,
+				F7CD00222F0E000000C9AB85 /* ShortcutRecorderView.swift in Sources */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 		};
diff --git a/FlowVision/Resources/Base.lproj/Main.storyboard b/FlowVision/Resources/Base.lproj/Main.storyboard
index 4edffd50..7457a96c 100644
--- a/FlowVision/Resources/Base.lproj/Main.storyboard
+++ b/FlowVision/Resources/Base.lproj/Main.storyboard
@@ -54,7 +54,7 @@
                                             </connections>
                                         </menuItem>
                                         <menuItem isSeparatorItem="YES" id="kCx-OE-vgT"/>
-                                        <menuItem title="Quit FlowVision" keyEquivalent="q" id="4sb-4s-VLi">
+                                        <menuItem title="Quit FlowVision" keyEquivalent="q" id="4sb-4s-VLi" identifier="quitApp">
                                             <connections>
                                                 <action selector="terminate:" target="Ady-hI-5gd" id="Te7-pn-YzF"/>
                                             </connections>
@@ -66,22 +66,22 @@
                                 <modifierMask key="keyEquivalentModifierMask"/>
                                 <menu key="submenu" title="File" id="bib-Uj-vzu">
                                     <items>
-                                        <menuItem title="New" hidden="YES" keyEquivalent="n" id="Was-JA-tGl">
+                                        <menuItem title="New" hidden="YES" keyEquivalent="n" id="Was-JA-tGl" identifier="windowNew">
                                             <connections>
                                                 <action selector="newDocument:" target="Ady-hI-5gd" id="4Si-XN-c54"/>
                                             </connections>
                                         </menuItem>
-                                        <menuItem title="New Tab" keyEquivalent="t" id="Rir-dR-V3t">
+                                        <menuItem title="New Tab" keyEquivalent="t" id="Rir-dR-V3t" identifier="windowNewTab">
                                             <connections>
                                                 <action selector="fileNewTab:" target="Voe-Tx-rLC" id="lvF-oG-YUt"/>
                                             </connections>
                                         </menuItem>
-                                        <menuItem title="Reopen Closed Tabs" keyEquivalent="T" id="zBc-1w-QcQ">
+                                        <menuItem title="Reopen Closed Tabs" keyEquivalent="T" id="zBc-1w-QcQ" identifier="windowReopenClosedTab">
                                             <connections>
                                                 <action selector="reopenClosedTabs:" target="Voe-Tx-rLC" id="H1g-La-A9P"/>
                                             </connections>
                                         </menuItem>
-                                        <menuItem title="New Folder" hidden="YES" keyEquivalent="N" id="ExL-hL-CrO">
+                                        <menuItem title="New Folder" hidden="YES" keyEquivalent="N" id="ExL-hL-CrO" identifier="fileNewFolder">
                                             <connections>
                                                 <action selector="fileNewFolder:" target="Voe-Tx-rLC" id="cc6-GJ-16i"/>
                                             </connections>
@@ -110,7 +110,7 @@
                                             </menu>
                                         </menuItem>
                                         <menuItem isSeparatorItem="YES" id="m54-Is-iLE"/>
-                                        <menuItem title="Close" keyEquivalent="w" id="DVo-aG-piG">
+                                        <menuItem title="Close" keyEquivalent="w" id="DVo-aG-piG" identifier="windowClose">
                                             <connections>
                                                 <action selector="performClose:" target="Ady-hI-5gd" id="HmO-Ls-i7Q"/>
                                             </connections>
@@ -211,7 +211,7 @@ Gw
                                             </connections>
                                         </menuItem>
                                         <menuItem isSeparatorItem="YES" id="uyl-h8-XO2"/>
-                                        <menuItem title="Find…" tag="1" keyEquivalent="f" id="xsi-wT-VTt">
+                                        <menuItem title="Find…" tag="1" keyEquivalent="f" id="xsi-wT-VTt" identifier="searchToggleOverlay">
                                             <connections>
                                                 <action selector="showSearch:" target="Voe-Tx-rLC" id="Ug6-0o-NDH"/>
                                             </connections>
@@ -670,14 +670,14 @@ Gw
                                             <modifierMask key="keyEquivalentModifierMask" control="YES" command="YES"/>
                                         </menuItem>
                                         <menuItem isSeparatorItem="YES" id="7XG-6M-HCO"/>
-                                        <menuItem title="Keep Current Window on Top" id="aEU-QL-iYf">
+                                        <menuItem title="Keep Current Window on Top" id="aEU-QL-iYf" identifier="windowToggleOnTop">
                                             <modifierMask key="keyEquivalentModifierMask"/>
                                             <connections>
                                                 <action selector="toggleOnTop:" target="Voe-Tx-rLC" id="27y-MO-y85"/>
                                             </connections>
                                         </menuItem>
                                         <menuItem isSeparatorItem="YES" id="Zhg-cS-a8X"/>
-                                        <menuItem title="Sidebar" id="Yr6-zE-34v">
+                                        <menuItem title="Sidebar" id="Yr6-zE-34v" identifier="browserToggleSidebar">
                                             <modifierMask key="keyEquivalentModifierMask"/>
                                             <connections>
                                                 <action selector="toggleSidebar:" target="Voe-Tx-rLC" id="NhX-Zy-mzD"/>
@@ -691,33 +691,33 @@ Gw
                                             </connections>
                                         </menuItem>
                                         <menuItem isSeparatorItem="YES" id="hHG-It-Z2Z"/>
-                                        <menuItem title="Show Finder Tags and Ratings" id="pB9-hf-avc">
+                                        <menuItem title="Show Finder Tags and Ratings" id="pB9-hf-avc" identifier="toggleShowFinderTagsAndRating">
                                             <modifierMask key="keyEquivalentModifierMask"/>
                                             <connections>
                                                 <action selector="toggleShowFinderTagsAndRating:" target="Voe-Tx-rLC" id="5n0-hV-KdC"/>
                                             </connections>
                                         </menuItem>
                                         <menuItem isSeparatorItem="YES" id="2Mq-tp-wyX"/>
-                                        <menuItem title="Lock Rotation" id="VCB-ff-DEq">
+                                        <menuItem title="Lock Rotation" id="VCB-ff-DEq" identifier="lockRotation">
                                             <modifierMask key="keyEquivalentModifierMask"/>
                                             <connections>
                                                 <action selector="toggleLockRotation:" target="Voe-Tx-rLC" id="yUY-s5-RRg"/>
                                             </connections>
                                         </menuItem>
-                                        <menuItem title="Lock Zoom" id="rTb-Na-yZj">
+                                        <menuItem title="Lock Zoom" id="rTb-Na-yZj" identifier="lockZoom">
                                             <modifierMask key="keyEquivalentModifierMask"/>
                                             <connections>
                                                 <action selector="toggleLockZoom:" target="Voe-Tx-rLC" id="pl0-jg-XRg"/>
                                             </connections>
                                         </menuItem>
-                                        <menuItem title="Lock Mirror" id="k1x-0c-asG">
+                                        <menuItem title="Lock Mirror" id="k1x-0c-asG" identifier="lockMirror">
                                             <modifierMask key="keyEquivalentModifierMask"/>
                                             <connections>
                                                 <action selector="toggleLockMirror:" target="Voe-Tx-rLC" id="xfX-DC-UrW"/>
                                             </connections>
                                         </menuItem>
                                         <menuItem isSeparatorItem="YES" id="YV6-Oq-8KP"/>
-                                        <menuItem title="Activate Pan Scrolling After Zoom" id="kyz-IP-P6r">
+                                        <menuItem title="Activate Pan Scrolling After Zoom" id="kyz-IP-P6r" identifier="activatePanScroll">
                                             <modifierMask key="keyEquivalentModifierMask"/>
                                             <connections>
                                                 <action selector="toggleActivatePanScroll:" target="Voe-Tx-rLC" id="mVT-xn-lCY"/>
@@ -743,19 +743,19 @@ Gw
                                             </connections>
                                         </menuItem>
                                         <menuItem isSeparatorItem="YES" id="hya-9u-wKp"/>
-                                        <menuItem title="Show Hidden Files" keyEquivalent="." id="Tbh-PX-yFW">
+                                        <menuItem title="Show Hidden Files" keyEquivalent="." id="Tbh-PX-yFW" identifier="toggleHiddenFiles">
                                             <modifierMask key="keyEquivalentModifierMask" shift="YES" command="YES"/>
                                             <connections>
                                                 <action selector="toggleIsShowHiddenFile:" target="Voe-Tx-rLC" id="L0l-RG-uc0"/>
                                             </connections>
                                         </menuItem>
-                                        <menuItem title="Show All Types of Files" keyEquivalent="," id="S31-Ni-z5u">
+                                        <menuItem title="Show All Types of Files" keyEquivalent="," id="S31-Ni-z5u" identifier="toggleAllFiles">
                                             <modifierMask key="keyEquivalentModifierMask" shift="YES" command="YES"/>
                                             <connections>
                                                 <action selector="toggleIsShowAllTypeFile:" target="Voe-Tx-rLC" id="85b-hE-Eij"/>
                                             </connections>
                                         </menuItem>
-                                        <menuItem title="Show Image Files" id="3W1-Yw-Gn8">
+                                        <menuItem title="Show Image Files" id="3W1-Yw-Gn8" identifier="toggleImageFiles">
                                             <modifierMask key="keyEquivalentModifierMask"/>
                                             <connections>
                                                 <action selector="toggleIsShowImageFile:" target="Voe-Tx-rLC" id="syI-Zi-Pfz"/>
@@ -767,7 +767,7 @@ Gw
                                                 <action selector="toggleIsShowRawFile:" target="Voe-Tx-rLC" id="X8N-9P-LLi"/>
                                             </connections>
                                         </menuItem>
-                                        <menuItem title="Show Video Files" id="UYl-gy-bK8">
+                                        <menuItem title="Show Video Files" id="UYl-gy-bK8" identifier="toggleVideoFiles">
                                             <modifierMask key="keyEquivalentModifierMask"/>
                                             <connections>
                                                 <action selector="toggleIsShowVideoFile:" target="Voe-Tx-rLC" id="6oF-pP-Qf9"/>
@@ -818,25 +818,25 @@ Gw
                                             </connections>
                                         </menuItem>
                                         <menuItem isSeparatorItem="YES" id="RXp-tl-oug"/>
-                                        <menuItem title="Justified View" id="rIE-So-qGu">
+                                        <menuItem title="Justified View" id="rIE-So-qGu" identifier="viewModeJustified">
                                             <modifierMask key="keyEquivalentModifierMask"/>
                                             <connections>
                                                 <action selector="switchToJustifiedView:" target="Voe-Tx-rLC" id="CIx-MD-oRV"/>
                                             </connections>
                                         </menuItem>
-                                        <menuItem title="Waterfall View" id="5Wy-TF-lsK">
+                                        <menuItem title="Waterfall View" id="5Wy-TF-lsK" identifier="viewModeWaterfall">
                                             <modifierMask key="keyEquivalentModifierMask"/>
                                             <connections>
                                                 <action selector="switchToWaterfallView:" target="Voe-Tx-rLC" id="uH8-jM-S3p"/>
                                             </connections>
                                         </menuItem>
-                                        <menuItem title="Grid View" id="SAw-E9-7Mm">
+                                        <menuItem title="Grid View" id="SAw-E9-7Mm" identifier="viewModeGrid">
                                             <modifierMask key="keyEquivalentModifierMask"/>
                                             <connections>
                                                 <action selector="switchToGridView:" target="Voe-Tx-rLC" id="REh-gr-8sX"/>
                                             </connections>
                                         </menuItem>
-                                        <menuItem title="Detail View" hidden="YES" id="aHz-iD-6dU">
+                                        <menuItem title="Detail View" hidden="YES" id="aHz-iD-6dU" identifier="viewModeDetail">
                                             <modifierMask key="keyEquivalentModifierMask"/>
                                             <connections>
                                                 <action selector="switchToDetailView:" target="Voe-Tx-rLC" id="zaN-HG-aSJ"/>
@@ -862,7 +862,7 @@ Gw
                                             </connections>
                                         </menuItem>
                                         <menuItem isSeparatorItem="YES" id="fr4-Bv-rSB"/>
-                                        <menuItem title="Enter Full Screen" keyEquivalent="f" id="4J7-dP-txa">
+                                        <menuItem title="Enter Full Screen" keyEquivalent="f" id="4J7-dP-txa" identifier="windowToggleFullscreen">
                                             <modifierMask key="keyEquivalentModifierMask" control="YES" command="YES"/>
                                             <connections>
                                                 <action selector="toggleFullScreen:" target="Ady-hI-5gd" id="dU3-MA-1Rq"/>
diff --git a/FlowVision/Sources/AppDelegate.swift b/FlowVision/Sources/AppDelegate.swift
index ab821dab..9e8c6b28 100644
--- a/FlowVision/Sources/AppDelegate.swift
+++ b/FlowVision/Sources/AppDelegate.swift
@@ -65,6 +65,9 @@ class AppDelegate: NSObject, NSApplicationDelegate, NSMenuDelegate, NSMenuItemVa
 
         log("Start applicationWillFinishLaunching")
         // Start applicationWillFinishLaunching
+
+        // Load user shortcut bindings before any window opens.
+        ShortcutStore.shared.load()
         
         func generateRoundedArray() -> [Int] {
             var result: [Int] = []
@@ -252,7 +255,7 @@ class AppDelegate: NSObject, NSApplicationDelegate, NSMenuDelegate, NSMenuItemVa
 
         log("Start applicationDidFinishLaunching")
         // Start applicationDidFinishLaunching
-        
+
         if windowControllers.count == 0 {
             _ = createNewWindow()
         }
@@ -261,11 +264,56 @@ class AppDelegate: NSObject, NSApplicationDelegate, NSMenuDelegate, NSMenuItemVa
 //            Thread.sleep(forTimeInterval: 8)
 //            FFmpegKitWrapper.shared.loadFFmpegKitIfNeeded()
 //        }
-        
+
+        // Initial menu shortcut sync + observer for live rebinding.
+        syncMenuShortcuts()
+        NotificationCenter.default.addObserver(
+            forName: .shortcutsChanged, object: nil, queue: .main
+        ) { [weak self] note in
+            self?.syncMenuShortcuts(only: note.object as? ShortcutAction)
+        }
+
         log("End applicationDidFinishLaunching")
         // End applicationDidFinishLaunching
     }
 
+    // MARK: - Shortcut menu sync
+
+    /// Walk every NSMenuItem under the main menu, applying `apply` to each one
+    /// (including nested submenus). Items with no submenu still receive the closure.
+    private func walkMenu(_ menu: NSMenu, _ apply: (NSMenuItem) -> Void) {
+        for item in menu.items {
+            apply(item)
+            if let sub = item.submenu { walkMenu(sub, apply) }
+        }
+    }
+
+    /// Refresh `keyEquivalent` and `keyEquivalentModifierMask` on every NSMenuItem
+    /// whose `identifier` matches a `ShortcutAction.rawValue`. Bare-letter chords
+    /// (Fn-only counts as bare) clear the menu shortcut so AppKit doesn't hijack
+    /// text-input events — those route exclusively through the NSEvent local monitor.
+    /// Pass an action to update a single item; pass nil for a full pass.
+    func syncMenuShortcuts(only action: ShortcutAction? = nil) {
+        guard let main = NSApp.mainMenu else { return }
+        walkMenu(main) { item in
+            guard let id = item.identifier?.rawValue,
+                  let target = ShortcutAction(rawValue: id) else { return }
+            if let action, target != action { return }
+            // Pick the first chord that has at least one real modifier (Fn alone
+            // doesn't qualify — would hijack text input via menu keyEquivalent).
+            let chord = ShortcutStore.shared.chords(for: target).first { c in
+                !c.modifiers.subtracting(.function).isEmpty
+            }
+            if let chord {
+                item.keyEquivalent = chord.character
+                item.keyEquivalentModifierMask = chord.modifiers.nsFlags
+            } else {
+                item.keyEquivalent = ""
+                item.keyEquivalentModifierMask = []
+            }
+        }
+    }
+
     func applicationWillTerminate(_ aNotification: Notification) {
         EnhancedIndex.flushPendingSave()
         log("App EXIT")
@@ -1087,6 +1135,12 @@ class AppDelegate: NSObject, NSApplicationDelegate, NSMenuDelegate, NSMenuItemVa
         createNewWindow(curFolder)
     }
 
+    /// Receives the rebindable `windowNew` shortcut. Spawns a fresh window with
+    /// the user's home/last folder via the same path as the app's auto-launch.
+    @IBAction func fileNewWindow(_ sender: Any?) {
+        _ = createNewWindow()
+    }
+
     @IBAction func reopenClosedTabs(_ sender: NSMenuItem){
         getMainViewController()?.handleReopenClosedTabs()
     }
diff --git a/FlowVision/Sources/SettingsViews/ActionsSettingsViewController.swift b/FlowVision/Sources/SettingsViews/ActionsSettingsViewController.swift
index 0e928263..6d0b66b3 100644
--- a/FlowVision/Sources/SettingsViews/ActionsSettingsViewController.swift
+++ b/FlowVision/Sources/SettingsViews/ActionsSettingsViewController.swift
@@ -2,39 +2,584 @@
 //  ActionsSettingsViewController.swift
 //  FlowVision
 //
+//  Two-column NSTableView. Each action shows one primary row + N extra rows,
+//  one per additional bound chord. Primary row has [recorder][+][R]; extras
+//  show [recorder][-]. Pending empty slots (from clicking +) live in the
+//  controller until the user records into them.
+//
 
 import Settings
 import Cocoa
 
-final class ActionsSettingsViewController: NSViewController, SettingsPane {
+private enum SettingsRow {
+    case category(ShortcutCategory)
+    /// `index` is the position within the action's chord list. Index 0 is the
+    /// primary row (shows [+] and [R]); indices >= 1 are extra rows (show [-]).
+    case actionSlot(ShortcutAction, index: Int)
+}
+
+final class ActionsSettingsViewController: NSViewController, SettingsPane,
+                                           NSTableViewDataSource, NSTableViewDelegate,
+                                           NSSearchFieldDelegate {
     let paneIdentifier = Settings.PaneIdentifier.actions
     let paneTitle = NSLocalizedString("Actions", comment: "操作（设置里的面板）")
-    let toolbarItemIcon = NSImage(systemSymbolName: "keyboard.badge.ellipsis", accessibilityDescription: "")!
+    let toolbarItemIcon = NSImage(systemSymbolName: "keyboard.badge.ellipsis",
+                                   accessibilityDescription: "")!
+
+    override var nibName: NSNib.Name? { nil }
+
+    // MARK: - Controls
+
+    private let radioEnterKeyRename = NSButton(radioButtonWithTitle:
+        NSLocalizedString("Rename", comment: ""), target: nil, action: nil)
+    private let radioEnterKeyOpen   = NSButton(radioButtonWithTitle:
+        NSLocalizedString("Open / Close", comment: ""), target: nil, action: nil)
+    private let searchField = NSSearchField()
+    private let tableView = NSTableView()
+
+    private var rows: [SettingsRow] = []
+    private var filterText = ""
+    private var shortcutsObserver: NSObjectProtocol?
+
+    /// Empty recorder rows the user added via [+] that haven't been filled yet.
+    /// Keyed by action. Count = number of trailing empty slots beyond stored chords.
+    private var pendingExtraSlots: [ShortcutAction: Int] = [:]
+
+    private static let nameColumnId    = NSUserInterfaceItemIdentifier("name")
+    private static let bindingColumnId = NSUserInterfaceItemIdentifier("binding")
+
+    // MARK: - View
+
+    override func loadView() {
+        let root = NSView(frame: NSRect(x: 0, y: 0, width: 500, height: 760))
+        root.autoresizingMask = [.width, .height]
+        preferredContentSize = NSSize(width: 500, height: 760)
+
+        let enterLabel = NSTextField(labelWithString:
+            NSLocalizedString("Enter Key:", comment: ""))
+        enterLabel.font = NSFont.boldSystemFont(ofSize: NSFont.systemFontSize)
+
+        radioEnterKeyRename.tag = 0
+        radioEnterKeyOpen.tag   = 1
+        radioEnterKeyRename.target = self
+        radioEnterKeyRename.action = #selector(enterKeyToOpenToggled(_:))
+        radioEnterKeyOpen.target   = self
+        radioEnterKeyOpen.action   = #selector(enterKeyToOpenToggled(_:))
+
+        let radioStack = NSStackView(views: [
+            enterLabel, radioEnterKeyRename, radioEnterKeyOpen,
+        ])
+        radioStack.orientation = .horizontal
+        radioStack.spacing = 12
+
+        searchField.delegate = self
+        searchField.placeholderString =
+            NSLocalizedString("Search shortcuts…", comment: "")
 
-    override var nibName: NSNib.Name? { "ActionsSettingsViewController" }
-    
-    @IBOutlet weak var radioEnterKeyRename: NSButton!
-    @IBOutlet weak var radioEnterKeyOpen: NSButton!
+        tableView.dataSource = self
+        tableView.delegate = self
+        tableView.rowHeight = 26
+        tableView.intercellSpacing = NSSize(width: 0, height: 2)
+        tableView.usesAlternatingRowBackgroundColors = false
+        tableView.gridStyleMask = []
+        tableView.allowsColumnReordering = false
+        tableView.allowsColumnSelection = false
+        tableView.allowsEmptySelection = true
+        tableView.allowsMultipleSelection = false
+        tableView.style = .inset
+        tableView.floatsGroupRows = false
+        tableView.headerView = nil
+
+        let nameColumn = NSTableColumn(identifier: Self.nameColumnId)
+        nameColumn.title = NSLocalizedString("Name", comment: "")
+        nameColumn.minWidth = 120
+        nameColumn.resizingMask = [.autoresizingMask, .userResizingMask]
+        tableView.addTableColumn(nameColumn)
+
+        let bindingColumn = NSTableColumn(identifier: Self.bindingColumnId)
+        bindingColumn.title = NSLocalizedString("Binding", comment: "")
+        bindingColumn.minWidth = 220
+        bindingColumn.width = 230
+        bindingColumn.maxWidth = 280
+        bindingColumn.resizingMask = [.userResizingMask]
+        tableView.addTableColumn(bindingColumn)
+
+        let scroll = NSScrollView()
+        scroll.documentView = tableView
+        scroll.hasVerticalScroller = true
+        scroll.borderType = .bezelBorder
+        scroll.translatesAutoresizingMaskIntoConstraints = false
+
+        let resetAllButton = NSButton(title:
+            NSLocalizedString("Reset all to defaults", comment: ""),
+            target: self, action: #selector(resetAllClicked(_:)))
+        resetAllButton.bezelStyle = .rounded
+        let bottomStack = NSStackView(views: [NSView(), resetAllButton])
+        bottomStack.orientation = .horizontal
+        bottomStack.translatesAutoresizingMaskIntoConstraints = false
+
+        searchField.translatesAutoresizingMaskIntoConstraints = false
+        let main = NSStackView(views: [radioStack, searchField, scroll, bottomStack])
+        main.orientation = .vertical
+        main.spacing = 12
+        main.alignment = .leading
+        main.edgeInsets = NSEdgeInsets(top: 20, left: 20, bottom: 20, right: 20)
+        main.translatesAutoresizingMaskIntoConstraints = false
+
+        root.addSubview(main)
+        NSLayoutConstraint.activate([
+            main.topAnchor.constraint(equalTo: root.topAnchor),
+            main.bottomAnchor.constraint(equalTo: root.bottomAnchor),
+            main.leadingAnchor.constraint(equalTo: root.leadingAnchor),
+            main.trailingAnchor.constraint(equalTo: root.trailingAnchor),
+
+            searchField.leadingAnchor.constraint(equalTo: main.leadingAnchor, constant: 20),
+            searchField.trailingAnchor.constraint(equalTo: main.trailingAnchor, constant: -20),
+
+            scroll.leadingAnchor.constraint(equalTo: main.leadingAnchor, constant: 20),
+            scroll.trailingAnchor.constraint(equalTo: main.trailingAnchor, constant: -20),
+            scroll.heightAnchor.constraint(greaterThanOrEqualToConstant: 580),
+
+            bottomStack.leadingAnchor.constraint(equalTo: main.leadingAnchor, constant: 20),
+            bottomStack.trailingAnchor.constraint(equalTo: main.trailingAnchor, constant: -20),
+        ])
+
+        self.view = root
+    }
 
     override func viewDidLoad() {
         super.viewDidLoad()
 
-        radioEnterKeyOpen.state = globalVar.isEnterKeyToOpen ? .on : .off
+        radioEnterKeyOpen.state   = globalVar.isEnterKeyToOpen ? .on  : .off
         radioEnterKeyRename.state = globalVar.isEnterKeyToOpen ? .off : .on
 
-        // MARK: RTL support
-        if let container = radioEnterKeyRename.superview {
-            convertToLeadingLayoutForRTL(container)
+        convertToLeadingLayoutForRTL(view)
+
+        rebuildRows()
+        tableView.reloadData()
+
+        shortcutsObserver = NotificationCenter.default.addObserver(
+            forName: .shortcutsChanged, object: nil, queue: .main
+        ) { [weak self] _ in
+            // A binding mutation can change the row count for an action.
+            // Cheap, correct, and the table is small enough that a full
+            // reload is fine.
+            self?.rebuildRows()
+            self?.tableView.reloadData()
         }
     }
 
-    @IBAction func enterKeyToOpenToggled(_ sender: NSButton) {
-        let tag = sender.tag
-        if tag == 0 {
-            globalVar.isEnterKeyToOpen = false
-        } else if tag == 1 {
-            globalVar.isEnterKeyToOpen = true
-        }
+    deinit {
+        if let t = shortcutsObserver { NotificationCenter.default.removeObserver(t) }
+    }
+
+    // MARK: - Enter key + reset
+
+    @objc func enterKeyToOpenToggled(_ sender: NSButton) {
+        if sender.tag == 0 { globalVar.isEnterKeyToOpen = false }
+        else if sender.tag == 1 { globalVar.isEnterKeyToOpen = true }
         UserDefaults.standard.set(globalVar.isEnterKeyToOpen, forKey: "isEnterKeyToOpen")
     }
+
+    @objc func resetAllClicked(_ sender: NSButton) {
+        let alert = NSAlert()
+        alert.messageText = NSLocalizedString("Reset all shortcuts to defaults?", comment: "")
+        alert.informativeText = NSLocalizedString(
+            "This will discard all your custom keyboard shortcuts.", comment: "")
+        alert.addButton(withTitle: NSLocalizedString("Reset", comment: ""))
+        alert.addButton(withTitle: NSLocalizedString("Cancel", comment: ""))
+        if alert.runModal() == .alertFirstButtonReturn {
+            pendingExtraSlots.removeAll()
+            ShortcutStore.shared.resetAll()
+        }
+    }
+
+    fileprivate func resetRow(_ action: ShortcutAction) {
+        pendingExtraSlots.removeValue(forKey: action)
+        ShortcutStore.shared.reset(action)
+    }
+
+    fileprivate func addEmptySlot(_ action: ShortcutAction) {
+        pendingExtraSlots[action, default: 0] += 1
+        rebuildRows()
+        tableView.reloadData()
+    }
+
+    fileprivate func removeSlot(_ action: ShortcutAction, at index: Int) {
+        let stored = ShortcutStore.shared.chords(for: action).count
+        if index < stored {
+            ShortcutStore.shared.removeChord(at: index, for: action)
+        } else {
+            // Pending empty slot — pop one.
+            if let n = pendingExtraSlots[action], n > 0 {
+                pendingExtraSlots[action] = n - 1
+                if pendingExtraSlots[action] == 0 {
+                    pendingExtraSlots.removeValue(forKey: action)
+                }
+                rebuildRows()
+                tableView.reloadData()
+            }
+        }
+    }
+
+    // MARK: - Recorder commit + conflict handling
+
+    fileprivate func onRecordedChord(_ chord: KeyChord?,
+                                      for action: ShortcutAction,
+                                      at index: Int) {
+        let stored = ShortcutStore.shared.chords(for: action)
+        let isPendingSlot = index >= stored.count
+
+        guard let chord else {
+            // Clear: drop the slot. For a stored chord this removes the row.
+            // For a pending empty slot it just decrements the counter.
+            if isPendingSlot {
+                removeSlot(action, at: index)
+            } else {
+                ShortcutStore.shared.setChord(nil, at: index, for: action)
+            }
+            return
+        }
+
+        // No-op when user re-records the same chord at the same slot.
+        if !isPendingSlot && stored[index] == chord { return }
+
+        // Reject any attempt to bind a chord that is the locked primary default
+        // of another action (e.g. ⌘Q owned by quitApp). Locked primaries can't
+        // be reassigned — would corrupt the locked action's UI state.
+        if isLockedReservedDefault(chord, excluding: action) {
+            showLockedReservedAlert(chord: chord)
+            // Pending-slot path: the user opened an empty slot and the recorded
+            // chord was rejected — drop the orphan slot so the table doesn't
+            // accumulate stranded empty rows.
+            if isPendingSlot { removeSlot(action, at: index) }
+            rebuildRows()
+            tableView.reloadData()
+            return
+        }
+
+        // A duplicate is "blocking" only when both actions can fire in the same
+        // runtime context. Cross-scope duplicates (e.g. browserOnly vs viewerOnly)
+        // are harmless and commit silently.
+        let blocking = (ShortcutStore.shared.reverseIndex[chord] ?? [])
+            .filter { $0 != action && scopesOverlap($0.scope, action.scope) }
+        let isSystemy = action.isSystemConventional || chord.isSystemReserved
+
+        if !blocking.isEmpty {
+            showConflictAlert(new: action, chord: chord, blocking: blocking,
+                              at: index, isPendingSlot: isPendingSlot)
+        } else if isSystemy {
+            confirmSystemOverride(action: action, chord: chord,
+                                   at: index, isPendingSlot: isPendingSlot)
+        } else {
+            commit(chord, action: action, at: index, isPendingSlot: isPendingSlot)
+        }
+    }
+
+    private func isLockedReservedDefault(_ chord: KeyChord,
+                                          excluding action: ShortcutAction) -> Bool {
+        ShortcutAction.allCases.contains { other in
+            other != action
+                && other.hasLockedPrimary
+                && other.defaultChords.first == chord
+        }
+    }
+
+    private func showLockedReservedAlert(chord: KeyChord) {
+        let alert = NSAlert()
+        alert.messageText = NSLocalizedString("Reserved shortcut", comment: "")
+        let fmt = NSLocalizedString("locked.reserved.body",
+            value: "%@ is reserved by the system and cannot be reassigned.",
+            comment: "%@ is chord glyphs")
+        alert.informativeText = String(format: fmt, chord.displayString)
+        alert.addButton(withTitle: NSLocalizedString("OK", comment: ""))
+        alert.runModal()
+    }
+
+    private func scopesOverlap(_ a: ContextScope, _ b: ContextScope) -> Bool {
+        a == .both || b == .both || a == b
+    }
+
+    private func commit(_ chord: KeyChord, action: ShortcutAction,
+                        at index: Int, isPendingSlot: Bool) {
+        if isPendingSlot {
+            // Convert pending slot into a real stored chord.
+            if let n = pendingExtraSlots[action], n > 0 {
+                pendingExtraSlots[action] = n - 1
+                if pendingExtraSlots[action] == 0 {
+                    pendingExtraSlots.removeValue(forKey: action)
+                }
+            }
+            ShortcutStore.shared.appendChord(chord, for: action)
+        } else {
+            ShortcutStore.shared.setChord(chord, at: index, for: action)
+        }
+    }
+
+    private func showConflictAlert(new action: ShortcutAction, chord: KeyChord,
+                                    blocking: [ShortcutAction],
+                                    at index: Int, isPendingSlot: Bool) {
+        let alert = NSAlert()
+        alert.messageText = NSLocalizedString("Shortcut conflict", comment: "")
+        let names = blocking.map { $0.displayName }.joined(separator: ", ")
+        let fmt = NSLocalizedString("conflict.body",
+            value: "%@ is already used by: %@.\nReassign?",
+            comment: "%@ chord, %@ comma-separated names")
+        alert.informativeText = String(format: fmt, chord.displayString, names)
+        alert.addButton(withTitle: NSLocalizedString("Reassign", comment: ""))
+        alert.addButton(withTitle: NSLocalizedString("Cancel", comment: ""))
+
+        if alert.runModal() == .alertFirstButtonReturn {
+            // Strip the conflicting chord from every blocker in one pass so the
+            // table reloads once instead of N times.
+            ShortcutStore.shared.batchRemove(chord: chord, from: blocking)
+            commit(chord, action: action, at: index, isPendingSlot: isPendingSlot)
+        } else {
+            rebuildRows()
+            tableView.reloadData()
+        }
+    }
+
+    private func confirmSystemOverride(action: ShortcutAction, chord: KeyChord,
+                                        at index: Int, isPendingSlot: Bool) {
+        let alert = NSAlert()
+        alert.messageText = NSLocalizedString("Override system-reserved shortcut?", comment: "")
+        let fmt = NSLocalizedString("system.override.body",
+            value: "%@ is conventionally used by macOS. Use it anyway?",
+            comment: "")
+        alert.informativeText = String(format: fmt, chord.displayString)
+        alert.addButton(withTitle: NSLocalizedString("Use anyway", comment: ""))
+        alert.addButton(withTitle: NSLocalizedString("Cancel", comment: ""))
+        if alert.runModal() == .alertFirstButtonReturn {
+            commit(chord, action: action, at: index, isPendingSlot: isPendingSlot)
+        } else {
+            rebuildRows()
+            tableView.reloadData()
+        }
+    }
+
+    // MARK: - Search
+
+    func controlTextDidChange(_ obj: Notification) {
+        filterText = searchField.stringValue.lowercased()
+        rebuildRows()
+        tableView.reloadData()
+    }
+
+    // MARK: - Row building
+
+    private func slotCount(for action: ShortcutAction) -> Int {
+        let stored = ShortcutStore.shared.chords(for: action).count
+        let pending = pendingExtraSlots[action] ?? 0
+        // Always show at least one row so the user can bind a chord for actions
+        // with no current chords.
+        return max(1, stored + pending)
+    }
+
+    private func rebuildRows() {
+        var out: [SettingsRow] = []
+        for cat in ShortcutCategory.allCases {
+            let actions = ShortcutAction.allCases
+                .filter { $0.category == cat }
+                .sorted { $0.displayName.localizedCaseInsensitiveCompare($1.displayName) == .orderedAscending }
+                .filter { matchesFilter($0) }
+            guard !actions.isEmpty else { continue }
+            out.append(.category(cat))
+            for action in actions {
+                let count = slotCount(for: action)
+                for i in 0..<count {
+                    out.append(.actionSlot(action, index: i))
+                }
+            }
+        }
+        rows = out
+    }
+
+    private func matchesFilter(_ action: ShortcutAction) -> Bool {
+        guard !filterText.isEmpty else { return true }
+        if action.displayName.localizedCaseInsensitiveContains(filterText) { return true }
+        if action.category.displayName.localizedCaseInsensitiveContains(filterText) { return true }
+        return ShortcutStore.shared.chords(for: action).contains {
+            $0.displayString.localizedCaseInsensitiveContains(filterText)
+        }
+    }
+
+    // MARK: - NSTableViewDataSource
+
+    func numberOfRows(in tableView: NSTableView) -> Int { rows.count }
+
+    // MARK: - NSTableViewDelegate
+
+    func tableView(_ tableView: NSTableView, isGroupRow row: Int) -> Bool {
+        if case .category = rows[row] { return true }
+        return false
+    }
+
+    func tableView(_ tableView: NSTableView, heightOfRow row: Int) -> CGFloat {
+        if case .category = rows[row] { return 24 }
+        return 28
+    }
+
+    func tableView(_ tableView: NSTableView, shouldSelectRow row: Int) -> Bool {
+        if case .category = rows[row] { return false }
+        return true
+    }
+
+    func tableView(_ tableView: NSTableView,
+                   viewFor tableColumn: NSTableColumn?, row: Int) -> NSView? {
+        switch rows[row] {
+        case .category(let cat):
+            if let col = tableColumn, col.identifier != Self.nameColumnId {
+                return nil
+            }
+            let id = NSUserInterfaceItemIdentifier("CategoryCell")
+            let cell = (tableView.makeView(withIdentifier: id, owner: self) as? NSTableCellView) ?? {
+                let c = NSTableCellView()
+                c.identifier = id
+                let label = NSTextField(labelWithString: "")
+                label.font = NSFont.boldSystemFont(ofSize: NSFont.systemFontSize)
+                label.translatesAutoresizingMaskIntoConstraints = false
+                c.addSubview(label)
+                c.textField = label
+                NSLayoutConstraint.activate([
+                    label.leadingAnchor.constraint(equalTo: c.leadingAnchor, constant: 4),
+                    label.centerYAnchor.constraint(equalTo: c.centerYAnchor),
+                    label.trailingAnchor.constraint(lessThanOrEqualTo: c.trailingAnchor),
+                ])
+                return c
+            }()
+            cell.textField?.stringValue = cat.displayName
+            return cell
+
+        case .actionSlot(let action, let index):
+            if tableColumn?.identifier == Self.nameColumnId {
+                let id = NSUserInterfaceItemIdentifier("NameCell")
+                let cell = (tableView.makeView(withIdentifier: id, owner: self) as? NSTableCellView) ?? {
+                    let c = NSTableCellView()
+                    c.identifier = id
+                    let label = NSTextField(labelWithString: "")
+                    label.font = NSFont.systemFont(ofSize: NSFont.systemFontSize)
+                    label.lineBreakMode = .byTruncatingTail
+                    label.translatesAutoresizingMaskIntoConstraints = false
+                    c.addSubview(label)
+                    c.textField = label
+                    NSLayoutConstraint.activate([
+                        label.leadingAnchor.constraint(equalTo: c.leadingAnchor, constant: 8),
+                        label.centerYAnchor.constraint(equalTo: c.centerYAnchor),
+                        label.trailingAnchor.constraint(lessThanOrEqualTo: c.trailingAnchor, constant: -4),
+                    ])
+                    return c
+                }()
+                // Only the primary slot (index 0) shows the action name.
+                cell.textField?.stringValue = index == 0 ? action.displayName : ""
+                return cell
+            } else {
+                let id = NSUserInterfaceItemIdentifier("BindingCell")
+                let cell = (tableView.makeView(withIdentifier: id, owner: self) as? BindingCell) ?? {
+                    let c = BindingCell()
+                    c.identifier = id
+                    return c
+                }()
+                cell.configure(for: action, at: index, host: self)
+                return cell
+            }
+        }
+    }
+}
+
+// MARK: - Binding cell
+
+private final class BindingCell: NSTableCellView {
+    private let recorder = ShortcutRecorderView()
+    private let plusButton  = NSButton(title: "+", target: nil, action: nil)
+    private let minusButton = NSButton(title: "−", target: nil, action: nil)
+    private let resetButton = NSButton(title: "↺", target: nil, action: nil)
+    private let stack = NSStackView()
+    private weak var host: ActionsSettingsViewController?
+    private var action: ShortcutAction?
+    private var index: Int = 0
+
+    override init(frame: NSRect) {
+        super.init(frame: frame)
+
+        for b in [plusButton, minusButton, resetButton] {
+            b.bezelStyle = .roundRect
+            b.target = self
+            b.font = NSFont.systemFont(ofSize: NSFont.systemFontSize)
+        }
+        plusButton.action  = #selector(plusTapped)
+        minusButton.action = #selector(minusTapped)
+        resetButton.action = #selector(resetTapped)
+        plusButton.toolTip  = NSLocalizedString("Add another shortcut", comment: "")
+        minusButton.toolTip = NSLocalizedString("Remove this shortcut", comment: "")
+        resetButton.toolTip = NSLocalizedString("Reset to default", comment: "")
+
+        stack.orientation = .horizontal
+        stack.spacing = 6
+        stack.alignment = .centerY
+        stack.translatesAutoresizingMaskIntoConstraints = false
+        stack.setHuggingPriority(.required, for: .horizontal)
+        addSubview(stack)
+        // Add every button once at init; toggle `isHidden` per slot in configure.
+        // NSStackView excludes hidden subviews from layout, so the visible buttons
+        // shift left/right naturally.
+        // Order keeps [-] at the same x as [+] (both immediately after recorder)
+        // and [R] trails on the primary row only.
+        stack.addArrangedSubview(recorder)
+        stack.addArrangedSubview(plusButton)
+        stack.addArrangedSubview(minusButton)
+        stack.addArrangedSubview(resetButton)
+        // Left-anchored so [recorder] and [+]/[-] sit at the same x position on
+        // every row (primary vs extra).
+        NSLayoutConstraint.activate([
+            stack.leadingAnchor.constraint(equalTo: leadingAnchor, constant: 4),
+            stack.centerYAnchor.constraint(equalTo: centerYAnchor),
+            stack.trailingAnchor.constraint(lessThanOrEqualTo: trailingAnchor, constant: -4),
+            recorder.widthAnchor.constraint(equalToConstant: 130),
+        ])
+    }
+
+    required init?(coder: NSCoder) { fatalError("init(coder:) not implemented") }
+
+    func configure(for action: ShortcutAction, at index: Int,
+                    host: ActionsSettingsViewController) {
+        self.action = action
+        self.index = index
+        self.host = host
+
+        let chords = ShortcutStore.shared.chords(for: action)
+        let chordForSlot: KeyChord? = (index < chords.count) ? chords[index] : nil
+        let isLockedPrimary = action.hasLockedPrimary && index == 0
+
+        recorder.isEnabled = !isLockedPrimary
+        recorder.toolTip = isLockedPrimary
+            ? NSLocalizedString("This shortcut is system-locked. Use [+] to add alternates.",
+                                comment: "locked recorder tooltip")
+            : nil
+        recorder.setChordSilent(chordForSlot)
+        recorder.onChange = { [weak self, weak host] chord in
+            guard let self, let host, let action = self.action else { return }
+            host.onRecordedChord(chord, for: action, at: self.index)
+        }
+
+        // Toggle button visibility per slot.
+        plusButton.isHidden  = index != 0
+        resetButton.isHidden = index != 0
+        minusButton.isHidden = index == 0
+    }
+
+    @objc private func plusTapped() {
+        guard let action, let host else { return }
+        host.addEmptySlot(action)
+    }
+
+    @objc private func minusTapped() {
+        guard let action, let host else { return }
+        host.removeSlot(action, at: index)
+    }
+
+    @objc private func resetTapped() {
+        guard let action, let host else { return }
+        host.resetRow(action)
+    }
 }
diff --git a/FlowVision/Sources/Shortcuts/KeyChord.swift b/FlowVision/Sources/Shortcuts/KeyChord.swift
new file mode 100644
index 00000000..0ce05dab
--- /dev/null
+++ b/FlowVision/Sources/Shortcuts/KeyChord.swift
@@ -0,0 +1,233 @@
+//
+//  KeyChord.swift
+//  FlowVision
+//
+//  Layout-independent keyboard chord representation backing ShortcutStore.
+//
+
+import Cocoa
+
+/// OptionSet wrapper around the subset of `NSEvent.ModifierFlags` that participates
+/// in user-rebindable shortcuts. ⌘ ⌥ ⌃ ⇧ Fn.
+struct Modifiers: OptionSet, Hashable, Codable {
+    let rawValue: UInt
+
+    static let command  = Modifiers(rawValue: 1 << 0)
+    static let option   = Modifiers(rawValue: 1 << 1)
+    static let control  = Modifiers(rawValue: 1 << 2)
+    static let shift    = Modifiers(rawValue: 1 << 3)
+    static let function = Modifiers(rawValue: 1 << 4)
+
+    init(rawValue: UInt) { self.rawValue = rawValue }
+
+    init(_ flags: NSEvent.ModifierFlags) {
+        var r: UInt = 0
+        if flags.contains(.command)  { r |= 1 << 0 }
+        if flags.contains(.option)   { r |= 1 << 1 }
+        if flags.contains(.control)  { r |= 1 << 2 }
+        if flags.contains(.shift)    { r |= 1 << 3 }
+        if flags.contains(.function) { r |= 1 << 4 }
+        self.rawValue = r
+    }
+
+    /// Inverse mapping for round-tripping to AppKit menu keyEquivalent masks.
+    var nsFlags: NSEvent.ModifierFlags {
+        var f: NSEvent.ModifierFlags = []
+        if contains(.command)  { f.insert(.command) }
+        if contains(.option)   { f.insert(.option) }
+        if contains(.control)  { f.insert(.control) }
+        if contains(.shift)    { f.insert(.shift) }
+        if contains(.function) { f.insert(.function) }
+        return f
+    }
+}
+
+/// A single key chord. Hash/equality intentionally on `(keyCode, modifiers)` only —
+/// `character` is display metadata captured at record time so menu glyphs stay stable
+/// per recording layout but two recordings of the same physical key on different layouts
+/// still match.
+struct KeyChord: Codable {
+    let keyCode: UInt16
+    let character: String
+    let modifiers: Modifiers
+
+    init(keyCode: UInt16, character: String, modifiers: Modifiers) {
+        self.keyCode = keyCode
+        self.character = character
+        self.modifiers = modifiers
+    }
+
+    init(event: NSEvent) {
+        self.keyCode = event.keyCode
+        self.character = (event.charactersIgnoringModifiers ?? "").lowercased()
+        var m = Modifiers(event.modifierFlags)
+        if Self.isImplicitFn(event.keyCode) { m.remove(.function) }
+        self.modifiers = m
+    }
+
+    /// Keys that macOS auto-flags with `.function` regardless of physical Fn press.
+    /// Strip the implicit flag during record so chord storage is clean.
+    static func isImplicitFn(_ k: UInt16) -> Bool {
+        switch k {
+        // Arrows + nav cluster
+        case 0x7B, 0x7C, 0x7D, 0x7E: return true     // ← → ↓ ↑
+        case 0x73, 0x77, 0x74, 0x79: return true     // home, end, pgup, pgdn
+        case 0x75: return true                       // forward delete
+        // F1–F20
+        case 0x7A, 0x78, 0x63, 0x76, 0x60,
+             0x61, 0x62, 0x64, 0x65, 0x6D,
+             0x67, 0x6F, 0x69, 0x6B, 0x71,
+             0x6A, 0x40, 0x4F, 0x50, 0x5A: return true
+        default: return false
+        }
+    }
+}
+
+extension KeyChord: Hashable {
+    static func == (l: KeyChord, r: KeyChord) -> Bool {
+        l.keyCode == r.keyCode && l.modifiers == r.modifiers
+    }
+
+    func hash(into h: inout Hasher) {
+        h.combine(keyCode)
+        h.combine(modifiers)
+    }
+}
+
+extension KeyChord {
+    /// Virtual keyCode for Escape. Named constant to replace magic 0x35 in call sites.
+    static let escKeyCode: UInt16 = 0x35
+
+    /// Apple HIG combos that shouldn't be silently hijacked — triggers warning when
+    /// the user binds one to a non-system-conventional action. Computed once.
+    private static let systemReservedSet: Set<KeyChord> = {
+        let cmd = Modifiers.command
+        let opt = Modifiers.option
+        return [
+            KeyChord(keyCode: 0x0C, character: "q", modifiers: cmd),       // Cmd+Q
+            KeyChord(keyCode: 0x0D, character: "w", modifiers: cmd),       // Cmd+W
+            KeyChord(keyCode: 0x2D, character: "n", modifiers: cmd),       // Cmd+N
+            KeyChord(keyCode: 0x2B, character: ",", modifiers: cmd),       // Cmd+,
+            KeyChord(keyCode: 0x04, character: "h", modifiers: cmd),       // Cmd+H
+            KeyChord(keyCode: 0x04, character: "h", modifiers: [cmd, opt]),// Cmd+Opt+H
+            KeyChord(keyCode: 0x03, character: "f", modifiers: cmd),       // Cmd+F
+            KeyChord(keyCode: 0x0F, character: "r", modifiers: cmd),       // Cmd+R
+            KeyChord(keyCode: 0x00, character: "a", modifiers: cmd),       // Cmd+A
+            KeyChord(keyCode: 0x08, character: "c", modifiers: cmd),       // Cmd+C
+            KeyChord(keyCode: 0x09, character: "v", modifiers: cmd),       // Cmd+V
+            KeyChord(keyCode: 0x07, character: "x", modifiers: cmd),       // Cmd+X
+            KeyChord(keyCode: 0x06, character: "z", modifiers: cmd),       // Cmd+Z
+            KeyChord(keyCode: 0x2E, character: "m", modifiers: cmd),       // Cmd+M
+        ]
+    }()
+
+    var isSystemReserved: Bool { Self.systemReservedSet.contains(self) }
+}
+
+extension KeyChord {
+    /// Human-readable glyph string. Modifier order matches macOS menu convention: Fn ⌃ ⌥ ⇧ ⌘.
+    var displayString: String {
+        var s = ""
+        if modifiers.contains(.function) && !KeyChord.isImplicitFn(keyCode) { s += "Fn" }
+        if modifiers.contains(.control)  { s += "⌃" }
+        if modifiers.contains(.option)   { s += "⌥" }
+        if modifiers.contains(.shift)    { s += "⇧" }
+        if modifiers.contains(.command)  { s += "⌘" }
+        s += Self.keyToken(keyCode: keyCode, character: character)
+        return s
+    }
+
+    static func keyToken(keyCode: UInt16, character: String) -> String {
+        switch keyCode {
+        case 0x7B: return "←"
+        case 0x7C: return "→"
+        case 0x7D: return "↓"
+        case 0x7E: return "↑"
+        case 0x31: return "␣"
+        case 0x24: return "⏎"
+        case 0x4C: return "⌤"
+        case 0x30: return "⇥"
+        case 0x35: return "Esc"
+        case 0x33: return "⌫"
+        case 0x75: return "⌦"
+        case 0x73: return "↖"
+        case 0x77: return "↘"
+        case 0x74: return "⇞"
+        case 0x79: return "⇟"
+        case 0x7A: return "F1"
+        case 0x78: return "F2"
+        case 0x63: return "F3"
+        case 0x76: return "F4"
+        case 0x60: return "F5"
+        case 0x61: return "F6"
+        case 0x62: return "F7"
+        case 0x64: return "F8"
+        case 0x65: return "F9"
+        case 0x6D: return "F10"
+        case 0x67: return "F11"
+        case 0x6F: return "F12"
+        case 0x69: return "F13"
+        case 0x6B: return "F14"
+        case 0x71: return "F15"
+        case 0x6A: return "F16"
+        case 0x40: return "F17"
+        case 0x4F: return "F18"
+        case 0x50: return "F19"
+        case 0x5A: return "F20"
+        default:
+            return character.isEmpty ? "?" : character.uppercased()
+        }
+    }
+}
+
+/// Context in which an action is allowed to fire.
+enum ContextScope: String, Codable {
+    case browserOnly
+    case viewerOnly
+    case both
+}
+
+/// Top-level grouping in the Settings → Actions outline view.
+enum ShortcutCategory: String, CaseIterable, Codable {
+    case navigation
+    case viewer
+    case video
+    case window
+    case fileOps
+    case viewMode
+    case visibility
+    case viewerBehavior
+    case rating
+    case finderTags
+    case profiles
+    case search
+    case quickSearch
+
+    var displayName: String {
+        let fallback: String
+        switch self {
+        case .navigation:     fallback = "Navigation"
+        case .viewer:         fallback = "Viewer"
+        case .video:          fallback = "Video"
+        case .window:         fallback = "Window"
+        case .fileOps:        fallback = "File Operations"
+        case .viewMode:       fallback = "View Mode"
+        case .visibility:     fallback = "Visibility"
+        case .viewerBehavior: fallback = "Viewer Behavior"
+        case .rating:         fallback = "Rating"
+        case .finderTags:     fallback = "Finder Tags"
+        case .profiles:       fallback = "Profiles"
+        case .search:         fallback = "Search"
+        case .quickSearch:    fallback = "Quick Search"
+        }
+        return NSLocalizedString("shortcut.category.\(rawValue)",
+                                 value: fallback,
+                                 comment: "shortcut category display name")
+    }
+}
+
+extension Notification.Name {
+    /// Posted when ShortcutStore mutates. `object` is the affected `ShortcutAction`,
+    /// or nil if all bindings changed (e.g. resetAll).
+    static let shortcutsChanged = Notification.Name("shortcutsChanged")
+}
diff --git a/FlowVision/Sources/Shortcuts/ShortcutAction.swift b/FlowVision/Sources/Shortcuts/ShortcutAction.swift
new file mode 100644
index 00000000..2c4b7a7a
--- /dev/null
+++ b/FlowVision/Sources/Shortcuts/ShortcutAction.swift
@@ -0,0 +1,628 @@
+//
+//  ShortcutAction.swift
+//  FlowVision
+//
+//  Canonical catalog of every rebindable keyboard action. Backs ShortcutStore.
+//
+//  ── Adding a new action ────────────────────────────────────────────────
+//  1. Add the case below in the appropriate MARK group.
+//  2. Add a `case` to the `buildDef` switch returning a `ShortcutDef` —
+//     compiler enforces every action has metadata.
+//  3. Add a `dispatch` case in KeyShortcut.swift that runs the handler.
+//  4. (Optional) If exposed via a menu item, add an `identifier=` matching
+//     the case rawValue in Main.storyboard so AppDelegate.syncMenuShortcuts
+//     can wire its keyEquivalent.
+//
+
+import Cocoa
+
+enum ShortcutAction: String, CaseIterable, Codable {
+    // MARK: Browser nav
+    case browserDirLeft, browserDirRight, browserDirUp, browserDirDown
+    case browserDirDownRight, browserBack, browserForward
+    case browserScrollTop, browserScrollBottom
+    case browserPageUp, browserPageDown
+    case browserDeselect, browserToggleSidebar
+
+    // MARK: Viewer nav
+    case viewerPrev, viewerNext
+    case viewerLocateFirst, viewerLocateLast
+    case viewerClose, viewerOpenFromSelection
+
+    // MARK: Viewer ops
+    case viewerZoomIn, viewerZoomOut, viewerZoom100, viewerZoomFit
+    case viewerZoomReset
+    case viewerRotateLeft, viewerRotateRight, viewerMirrorH
+    case viewerOCR, viewerQRCode, viewerGetInfo, viewerShowExif, viewerEditMode
+
+    // MARK: Video (non-overlapping with zoom keys)
+    case videoPauseResume
+    case videoSeekFwd, videoSeekBack
+    case videoSeekFrameFwd, videoSeekFrameBack
+    case videoSetA, videoSetB, videoABPlay
+    case videoSequentialPlay, videoRememberPosition
+
+    // MARK: Window
+    case windowMaximize, windowSuitable, windowImageActual
+    case windowImageCurrent, windowCenter, windowToggleFullscreen
+    case windowToggleOnTop, windowRefresh
+    case windowNew, windowNewTab, windowClose, windowCloseTab
+    case windowReopenClosedTab
+    case quitApp
+
+    // MARK: File ops
+    case fileRename, fileDelete, fileDeleteNoPrompt, fileNewFolder
+    case fileCopyToDownload, fileMoveToDownload, fileGetInfo
+
+    // MARK: Thumb size (in fileOps category)
+    case thumbSizeUp, thumbSizeDown, thumbSizeReset
+
+    // MARK: View mode
+    case viewModeJustified, viewModeWaterfall, viewModeGrid, viewModeDetail
+
+    // MARK: Visibility toggles
+    case toggleHiddenFiles, toggleImageFiles, toggleRawFiles, toggleVideoFiles, toggleAllFiles
+    case toggleShowFinderTagsAndRating, toggleRawUseEmbeddedThumb
+    case toggleAutoPlayVideo
+
+    // MARK: Viewer behavior toggles
+    case lockRotation, lockZoom, lockMirror, activatePanScroll
+
+    // MARK: Rating
+    case rating0, rating1, rating2, rating3, rating4, rating5
+
+    // MARK: Finder tags
+    case tag1, tag2, tag3, tag4, tag5, tag6, tag7, tag8, tag9
+
+    // MARK: Profiles
+    case profileUse1, profileUse2, profileUse3, profileUse4, profileUse5
+    case profileUse6, profileUse7, profileUse8, profileUse9
+    case profileSave1, profileSave2, profileSave3, profileSave4, profileSave5
+    case profileSave6, profileSave7, profileSave8, profileSave9
+
+    // MARK: Search (these fire while search overlay is open)
+    case searchToggleOverlay, searchToggleRecursive, searchToggleRecursiveFolder
+
+    // MARK: Quick search
+    case quickSearchActivate
+}
+
+// MARK: - Definition
+
+/// All static metadata for a shortcut action. Built once at first access via
+/// `ShortcutAction.table` and looked up by enum case. Handlers live separately
+/// in `KeyShortcut.swift` (`ViewController.dispatch(_:)`).
+struct ShortcutDef {
+    let category: ShortcutCategory
+    let scope: ContextScope
+    let englishName: String
+    let defaultChords: [KeyChord]
+
+    /// Action fires even when the search overlay holds focus.
+    /// Defaults false — only menu-style actions opt in.
+    var firesDuringSearch: Bool = false
+
+    /// Chord is a macOS HIG convention (Cmd+Q, Cmd+W, etc.). Recorder prompts
+    /// before letting the user override.
+    var isSystemConventional: Bool = false
+
+    /// Primary (index 0) slot is rendered disabled and cannot be reassigned.
+    /// Currently only `quitApp` — Cmd+Q is owned by macOS.
+    var hasLockedPrimary: Bool = false
+}
+
+/// Shorthand for table readability. Order: keyCode, character, modifiers.
+private func k(_ code: UInt16, _ ch: String = "", _ mods: Modifiers = []) -> KeyChord {
+    KeyChord(keyCode: code, character: ch, modifiers: mods)
+}
+
+extension ShortcutAction {
+    /// Metadata lookup. Force-unwrap is safe — `table` is built from `allCases`.
+    var def: ShortcutDef { Self.table[self]! }
+
+    var category: ShortcutCategory { def.category }
+    var scope: ContextScope        { def.scope }
+    var englishName: String        { def.englishName }
+    var defaultChords: [KeyChord]  { def.defaultChords }
+    var firesDuringSearch: Bool    { def.firesDuringSearch }
+    var isSystemConventional: Bool { def.isSystemConventional }
+    var hasLockedPrimary: Bool     { def.hasLockedPrimary }
+
+    var displayName: String {
+        NSLocalizedString("shortcut.action.\(rawValue)",
+                          value: englishName,
+                          comment: "shortcut display name")
+    }
+
+    private static let table: [ShortcutAction: ShortcutDef] = {
+        var d: [ShortcutAction: ShortcutDef] = [:]
+        d.reserveCapacity(ShortcutAction.allCases.count)
+        for a in ShortcutAction.allCases { d[a] = a.buildDef() }
+        return d
+    }()
+
+    private func buildDef() -> ShortcutDef {
+        switch self {
+
+        // MARK: Browser nav
+        case .browserDirLeft: return .init(
+            category: .navigation, scope: .browserOnly,
+            englishName: "Switch directory left",
+            defaultChords: [k(0x00, "a")])
+        case .browserDirRight: return .init(
+            category: .navigation, scope: .browserOnly,
+            englishName: "Switch directory right",
+            defaultChords: [k(0x02, "d")])
+        case .browserDirUp: return .init(
+            category: .navigation, scope: .browserOnly,
+            englishName: "Switch directory up",
+            defaultChords: [k(0x0D, "w")])
+        case .browserDirDown: return .init(
+            category: .navigation, scope: .browserOnly,
+            englishName: "Switch directory down",
+            defaultChords: [k(0x01, "s")])
+        case .browserDirDownRight: return .init(
+            category: .navigation, scope: .browserOnly,
+            englishName: "Switch directory down-right",
+            defaultChords: [k(0x0E, "e")])
+        case .browserBack: return .init(
+            category: .navigation, scope: .browserOnly,
+            englishName: "Go back",
+            defaultChords: [k(0x21, "[", .command)])
+        case .browserForward: return .init(
+            category: .navigation, scope: .browserOnly,
+            englishName: "Go forward",
+            defaultChords: [k(0x1E, "]", .command)])
+        case .browserScrollTop: return .init(
+            category: .navigation, scope: .browserOnly,
+            englishName: "Scroll to top",
+            defaultChords: [k(0x73)])  // Home
+        case .browserScrollBottom: return .init(
+            category: .navigation, scope: .browserOnly,
+            englishName: "Scroll to bottom",
+            defaultChords: [k(0x77)])  // End
+        case .browserPageUp: return .init(
+            category: .navigation, scope: .browserOnly,
+            englishName: "Page up",
+            defaultChords: [k(0x74), k(0x7E, "", .option)])  // PageUp, Opt+↑
+        case .browserPageDown: return .init(
+            category: .navigation, scope: .browserOnly,
+            englishName: "Page down",
+            defaultChords: [k(0x79), k(0x7D, "", .option)])  // PageDn, Opt+↓
+        case .browserDeselect: return .init(
+            category: .navigation, scope: .browserOnly,
+            englishName: "Deselect",
+            defaultChords: [k(0x35)])  // Esc
+        case .browserToggleSidebar: return .init(
+            category: .navigation, scope: .browserOnly,
+            englishName: "Toggle sidebar",
+            defaultChords: [k(0x03, "f")])
+
+        // MARK: Viewer nav
+        // Multi-chord: A/↑/PageUp/Cmd+[ for prev; symmetric set for next.
+        // ←/→ arrows bind to videoSeekBack/Fwd whose dispatch folds to
+        // prev/next when the active item is an image.
+        case .viewerPrev: return .init(
+            category: .navigation, scope: .viewerOnly,
+            englishName: "Previous image",
+            defaultChords: [k(0x00, "a"), k(0x7E), k(0x74), k(0x21, "[", .command)])
+        case .viewerNext: return .init(
+            category: .navigation, scope: .viewerOnly,
+            englishName: "Next image",
+            defaultChords: [k(0x02, "d"), k(0x7D), k(0x79), k(0x1E, "]", .command)])
+        case .viewerLocateFirst: return .init(
+            category: .navigation, scope: .viewerOnly,
+            englishName: "Locate first",
+            defaultChords: [k(0x73), k(0x7E, "", .command)])  // Home, Cmd+↑
+        case .viewerLocateLast: return .init(
+            category: .navigation, scope: .viewerOnly,
+            englishName: "Locate last",
+            defaultChords: [k(0x77), k(0x7D, "", .command)])  // End, Cmd+↓
+        case .viewerClose: return .init(
+            category: .navigation, scope: .viewerOnly,
+            englishName: "Close viewer",
+            defaultChords: [k(0x35)])
+        case .viewerOpenFromSelection: return .init(
+            category: .navigation, scope: .browserOnly,
+            englishName: "Open selection in viewer",
+            defaultChords: [k(0x31, " ")])
+
+        // MARK: Viewer ops
+        // viewerZoomIn / Out: W and S share keys with browserDirUp/Down via
+        // disjoint scope (viewer vs browser).
+        case .viewerZoomIn: return .init(
+            category: .viewer, scope: .viewerOnly,
+            englishName: "Zoom in / Volume up",
+            defaultChords: [k(0x18, "="), k(0x0D, "w")])
+        case .viewerZoomOut: return .init(
+            category: .viewer, scope: .viewerOnly,
+            englishName: "Zoom out / Volume down",
+            defaultChords: [k(0x1B, "-"), k(0x01, "s")])
+        case .viewerZoom100: return .init(
+            category: .viewer, scope: .viewerOnly,
+            englishName: "Zoom 100%",
+            defaultChords: [k(0x06, "z")])
+        case .viewerZoomFit: return .init(
+            category: .viewer, scope: .viewerOnly,
+            englishName: "Zoom fit",
+            defaultChords: [k(0x07, "x")])
+        case .viewerZoomReset: return .init(
+            category: .viewer, scope: .viewerOnly,
+            englishName: "Reset zoom",
+            defaultChords: [k(0x1D, "0")])
+        case .viewerRotateLeft: return .init(
+            category: .viewer, scope: .viewerOnly,
+            englishName: "Rotate left",
+            defaultChords: [k(0x0C, "q")])
+        case .viewerRotateRight: return .init(
+            category: .viewer, scope: .viewerOnly,
+            englishName: "Rotate right",
+            defaultChords: [k(0x0E, "e")])
+        case .viewerMirrorH: return .init(
+            category: .viewer, scope: .viewerOnly,
+            englishName: "Mirror horizontal",
+            defaultChords: [k(0x03, "f")])
+        case .viewerOCR: return .init(
+            category: .viewer, scope: .viewerOnly,
+            englishName: "OCR",
+            defaultChords: [k(0x1F, "o")])
+        case .viewerQRCode: return .init(
+            category: .viewer, scope: .viewerOnly,
+            englishName: "QR code",
+            defaultChords: [k(0x23, "p")])
+        case .viewerGetInfo: return .init(
+            category: .viewer, scope: .viewerOnly,
+            englishName: "Get info (viewer)",
+            defaultChords: [k(0x20, "u")])
+        case .viewerShowExif: return .init(
+            category: .viewer, scope: .viewerOnly,
+            englishName: "Show EXIF",
+            defaultChords: [k(0x22, "i")])
+        case .viewerEditMode: return .init(
+            category: .viewer, scope: .viewerOnly,
+            englishName: "Edit image",
+            defaultChords: [k(0x0E, "e", [.command, .shift])])
+
+        // MARK: Video — seek arrows fold to prev/next on non-video at dispatch.
+        case .videoPauseResume: return .init(
+            category: .video, scope: .viewerOnly,
+            englishName: "Play / Pause",
+            defaultChords: [k(0x31, " ")])
+        case .videoSeekFwd: return .init(
+            category: .video, scope: .viewerOnly,
+            englishName: "Seek forward",
+            defaultChords: [k(0x7C)])
+        case .videoSeekBack: return .init(
+            category: .video, scope: .viewerOnly,
+            englishName: "Seek backward",
+            defaultChords: [k(0x7B)])
+        case .videoSeekFrameFwd: return .init(
+            category: .video, scope: .viewerOnly,
+            englishName: "Seek forward 1 frame",
+            defaultChords: [k(0x7C, "", .command)])
+        case .videoSeekFrameBack: return .init(
+            category: .video, scope: .viewerOnly,
+            englishName: "Seek backward 1 frame",
+            defaultChords: [k(0x7B, "", .command)])
+        case .videoSetA: return .init(
+            category: .video, scope: .viewerOnly,
+            englishName: "Set A point",
+            defaultChords: [k(0x2B, ",")])
+        case .videoSetB: return .init(
+            category: .video, scope: .viewerOnly,
+            englishName: "Set B point",
+            defaultChords: [k(0x2F, ".")])
+        case .videoABPlay: return .init(
+            category: .video, scope: .viewerOnly,
+            englishName: "A-B play",
+            defaultChords: [k(0x28, "k")])
+        case .videoSequentialPlay: return .init(
+            category: .video, scope: .viewerOnly,
+            englishName: "Sequential play",
+            defaultChords: [k(0x25, "l")])
+        case .videoRememberPosition: return .init(
+            category: .video, scope: .viewerOnly,
+            englishName: "Remember play position",
+            defaultChords: [k(0x26, "j")])
+
+        // MARK: Window
+        case .windowMaximize: return .init(
+            category: .window, scope: .both,
+            englishName: "Maximize window",
+            defaultChords: [k(0x12, "1")])
+        case .windowSuitable: return .init(
+            category: .window, scope: .both,
+            englishName: "Suitable window size",
+            defaultChords: [k(0x13, "2")])
+        case .windowImageActual: return .init(
+            category: .window, scope: .viewerOnly,
+            englishName: "Window to image (actual)",
+            defaultChords: [k(0x14, "3")])
+        case .windowImageCurrent: return .init(
+            category: .window, scope: .viewerOnly,
+            englishName: "Window to image (current)",
+            defaultChords: [k(0x15, "4")])
+        case .windowCenter: return .init(
+            category: .window, scope: .both,
+            englishName: "Center window",
+            defaultChords: [k(0x17, "5")])
+        case .windowToggleFullscreen: return .init(
+            category: .window, scope: .both,
+            englishName: "Toggle full screen",
+            defaultChords: [k(0x03, "f", [.command, .control]),
+                            k(0x24, "\r", .option)])  // Cmd+Ctrl+F, Opt+Return
+        case .windowToggleOnTop: return .init(
+            category: .window, scope: .both,
+            englishName: "Toggle always on top",
+            defaultChords: [k(0x11, "t")])
+        case .windowRefresh: return .init(
+            category: .window, scope: .both,
+            englishName: "Refresh",
+            defaultChords: [k(0x0F, "r", .command), k(0x60)],  // Cmd+R, F5
+            isSystemConventional: true)
+        case .windowNew: return .init(
+            category: .window, scope: .both,
+            englishName: "New window",
+            defaultChords: [k(0x2D, "n", .command)],
+            isSystemConventional: true)
+        case .windowNewTab: return .init(
+            category: .window, scope: .both,
+            englishName: "New tab",
+            defaultChords: [k(0x11, "t", .command)],
+            isSystemConventional: true)
+        case .windowClose: return .init(
+            category: .window, scope: .both,
+            englishName: "Close window",
+            defaultChords: [k(0x0D, "w", .command)],
+            isSystemConventional: true)
+        case .windowCloseTab: return .init(
+            category: .window, scope: .both,
+            englishName: "Close tab",
+            defaultChords: [])
+        case .windowReopenClosedTab: return .init(
+            category: .window, scope: .both,
+            englishName: "Reopen closed tab",
+            defaultChords: [k(0x11, "t", [.command, .shift])],
+            firesDuringSearch: true,
+            isSystemConventional: true)
+        case .quitApp: return .init(
+            category: .window, scope: .both,
+            englishName: "Quit application",
+            defaultChords: [k(0x0C, "q", .command)],
+            isSystemConventional: true,
+            hasLockedPrimary: true)
+
+        // MARK: File ops
+        case .fileRename: return .init(
+            category: .fileOps, scope: .browserOnly,
+            englishName: "Rename",
+            defaultChords: [k(0x0F, "r")])
+        case .fileDelete: return .init(
+            category: .fileOps, scope: .both,
+            englishName: "Delete",
+            defaultChords: [k(0x33), k(0x75)])  // Backspace, Forward-Delete
+        case .fileDeleteNoPrompt: return .init(
+            category: .fileOps, scope: .both,
+            englishName: "Delete (no prompt)",
+            defaultChords: [k(0x33, "", .command), k(0x75, "", .command)])
+        case .fileNewFolder: return .init(
+            category: .fileOps, scope: .browserOnly,
+            englishName: "New folder",
+            defaultChords: [k(0x2D, "n", [.command, .shift])])
+        case .fileCopyToDownload: return .init(
+            category: .fileOps, scope: .browserOnly,
+            englishName: "Copy to Downloads",
+            defaultChords: [k(0x2D, "n")])
+        case .fileMoveToDownload: return .init(
+            category: .fileOps, scope: .browserOnly,
+            englishName: "Move to Downloads",
+            defaultChords: [k(0x2E, "m")])
+        case .fileGetInfo: return .init(
+            category: .fileOps, scope: .browserOnly,
+            englishName: "Get info",
+            defaultChords: [k(0x22, "i")])
+
+        // MARK: Thumb size
+        case .thumbSizeUp: return .init(
+            category: .fileOps, scope: .browserOnly,
+            englishName: "Thumbnail size up",
+            defaultChords: [k(0x18, "=")])
+        case .thumbSizeDown: return .init(
+            category: .fileOps, scope: .browserOnly,
+            englishName: "Thumbnail size down",
+            defaultChords: [k(0x1B, "-")])
+        case .thumbSizeReset: return .init(
+            category: .fileOps, scope: .browserOnly,
+            englishName: "Reset thumbnail size",
+            defaultChords: [k(0x1D, "0")])
+
+        // MARK: View mode — no defaults
+        case .viewModeJustified: return .init(
+            category: .viewMode, scope: .browserOnly,
+            englishName: "Justified view", defaultChords: [])
+        case .viewModeWaterfall: return .init(
+            category: .viewMode, scope: .browserOnly,
+            englishName: "Waterfall view", defaultChords: [])
+        case .viewModeGrid: return .init(
+            category: .viewMode, scope: .browserOnly,
+            englishName: "Grid view", defaultChords: [])
+        case .viewModeDetail: return .init(
+            category: .viewMode, scope: .browserOnly,
+            englishName: "Detail view", defaultChords: [])
+
+        // MARK: Visibility toggles
+        case .toggleHiddenFiles: return .init(
+            category: .visibility, scope: .browserOnly,
+            englishName: "Show hidden files",
+            defaultChords: [k(0x2F, ".", [.command, .shift])])
+        case .toggleImageFiles: return .init(
+            category: .visibility, scope: .browserOnly,
+            englishName: "Show image files", defaultChords: [])
+        case .toggleRawFiles: return .init(
+            category: .visibility, scope: .browserOnly,
+            englishName: "Show RAW files", defaultChords: [])
+        case .toggleVideoFiles: return .init(
+            category: .visibility, scope: .browserOnly,
+            englishName: "Show video files", defaultChords: [])
+        case .toggleAllFiles: return .init(
+            category: .visibility, scope: .browserOnly,
+            englishName: "Show all file types",
+            defaultChords: [k(0x2B, ",", [.command, .shift])])
+        case .toggleShowFinderTagsAndRating: return .init(
+            category: .visibility, scope: .browserOnly,
+            englishName: "Show Finder tags and rating", defaultChords: [])
+        case .toggleRawUseEmbeddedThumb: return .init(
+            category: .visibility, scope: .browserOnly,
+            englishName: "Use embedded RAW thumbnail", defaultChords: [])
+        case .toggleAutoPlayVideo: return .init(
+            category: .visibility, scope: .browserOnly,
+            englishName: "Auto-play videos in grid",
+            defaultChords: [k(0x09, "v", [.command, .shift])])
+
+        // MARK: Viewer behavior — no defaults
+        case .lockRotation: return .init(
+            category: .viewerBehavior, scope: .viewerOnly,
+            englishName: "Lock rotation", defaultChords: [])
+        case .lockZoom: return .init(
+            category: .viewerBehavior, scope: .viewerOnly,
+            englishName: "Lock zoom", defaultChords: [])
+        case .lockMirror: return .init(
+            category: .viewerBehavior, scope: .viewerOnly,
+            englishName: "Lock mirror", defaultChords: [])
+        case .activatePanScroll: return .init(
+            category: .viewerBehavior, scope: .viewerOnly,
+            englishName: "Activate pan scroll", defaultChords: [])
+
+        // MARK: Rating (Ctrl+0..5)
+        case .rating0: return .init(
+            category: .rating, scope: .browserOnly,
+            englishName: "Rating: clear", defaultChords: [k(0x1D, "0", .control)])
+        case .rating1: return .init(
+            category: .rating, scope: .browserOnly,
+            englishName: "Rating: 1", defaultChords: [k(0x12, "1", .control)])
+        case .rating2: return .init(
+            category: .rating, scope: .browserOnly,
+            englishName: "Rating: 2", defaultChords: [k(0x13, "2", .control)])
+        case .rating3: return .init(
+            category: .rating, scope: .browserOnly,
+            englishName: "Rating: 3", defaultChords: [k(0x14, "3", .control)])
+        case .rating4: return .init(
+            category: .rating, scope: .browserOnly,
+            englishName: "Rating: 4", defaultChords: [k(0x15, "4", .control)])
+        case .rating5: return .init(
+            category: .rating, scope: .browserOnly,
+            englishName: "Rating: 5", defaultChords: [k(0x17, "5", .control)])
+
+        // MARK: Finder tags (Cmd+1..9)
+        case .tag1: return .init(
+            category: .finderTags, scope: .browserOnly,
+            englishName: "Toggle Finder tag 1", defaultChords: [k(0x12, "1", .command)])
+        case .tag2: return .init(
+            category: .finderTags, scope: .browserOnly,
+            englishName: "Toggle Finder tag 2", defaultChords: [k(0x13, "2", .command)])
+        case .tag3: return .init(
+            category: .finderTags, scope: .browserOnly,
+            englishName: "Toggle Finder tag 3", defaultChords: [k(0x14, "3", .command)])
+        case .tag4: return .init(
+            category: .finderTags, scope: .browserOnly,
+            englishName: "Toggle Finder tag 4", defaultChords: [k(0x15, "4", .command)])
+        case .tag5: return .init(
+            category: .finderTags, scope: .browserOnly,
+            englishName: "Toggle Finder tag 5", defaultChords: [k(0x17, "5", .command)])
+        case .tag6: return .init(
+            category: .finderTags, scope: .browserOnly,
+            englishName: "Toggle Finder tag 6", defaultChords: [k(0x16, "6", .command)])
+        case .tag7: return .init(
+            category: .finderTags, scope: .browserOnly,
+            englishName: "Toggle Finder tag 7", defaultChords: [k(0x1A, "7", .command)])
+        case .tag8: return .init(
+            category: .finderTags, scope: .browserOnly,
+            englishName: "Toggle Finder tag 8", defaultChords: [k(0x1C, "8", .command)])
+        case .tag9: return .init(
+            category: .finderTags, scope: .browserOnly,
+            englishName: "Toggle Finder tag 9", defaultChords: [k(0x19, "9", .command)])
+
+        // MARK: Profile use (Opt+1..9)
+        case .profileUse1: return .init(
+            category: .profiles, scope: .browserOnly,
+            englishName: "Use profile 1", defaultChords: [k(0x12, "1", .option)])
+        case .profileUse2: return .init(
+            category: .profiles, scope: .browserOnly,
+            englishName: "Use profile 2", defaultChords: [k(0x13, "2", .option)])
+        case .profileUse3: return .init(
+            category: .profiles, scope: .browserOnly,
+            englishName: "Use profile 3", defaultChords: [k(0x14, "3", .option)])
+        case .profileUse4: return .init(
+            category: .profiles, scope: .browserOnly,
+            englishName: "Use profile 4", defaultChords: [k(0x15, "4", .option)])
+        case .profileUse5: return .init(
+            category: .profiles, scope: .browserOnly,
+            englishName: "Use profile 5", defaultChords: [k(0x17, "5", .option)])
+        case .profileUse6: return .init(
+            category: .profiles, scope: .browserOnly,
+            englishName: "Use profile 6", defaultChords: [k(0x16, "6", .option)])
+        case .profileUse7: return .init(
+            category: .profiles, scope: .browserOnly,
+            englishName: "Use profile 7", defaultChords: [k(0x1A, "7", .option)])
+        case .profileUse8: return .init(
+            category: .profiles, scope: .browserOnly,
+            englishName: "Use profile 8", defaultChords: [k(0x1C, "8", .option)])
+        case .profileUse9: return .init(
+            category: .profiles, scope: .browserOnly,
+            englishName: "Use profile 9", defaultChords: [k(0x19, "9", .option)])
+
+        // MARK: Profile save (Cmd+Opt+1..9)
+        case .profileSave1: return .init(
+            category: .profiles, scope: .browserOnly,
+            englishName: "Save profile 1", defaultChords: [k(0x12, "1", [.command, .option])])
+        case .profileSave2: return .init(
+            category: .profiles, scope: .browserOnly,
+            englishName: "Save profile 2", defaultChords: [k(0x13, "2", [.command, .option])])
+        case .profileSave3: return .init(
+            category: .profiles, scope: .browserOnly,
+            englishName: "Save profile 3", defaultChords: [k(0x14, "3", [.command, .option])])
+        case .profileSave4: return .init(
+            category: .profiles, scope: .browserOnly,
+            englishName: "Save profile 4", defaultChords: [k(0x15, "4", [.command, .option])])
+        case .profileSave5: return .init(
+            category: .profiles, scope: .browserOnly,
+            englishName: "Save profile 5", defaultChords: [k(0x17, "5", [.command, .option])])
+        case .profileSave6: return .init(
+            category: .profiles, scope: .browserOnly,
+            englishName: "Save profile 6", defaultChords: [k(0x16, "6", [.command, .option])])
+        case .profileSave7: return .init(
+            category: .profiles, scope: .browserOnly,
+            englishName: "Save profile 7", defaultChords: [k(0x1A, "7", [.command, .option])])
+        case .profileSave8: return .init(
+            category: .profiles, scope: .browserOnly,
+            englishName: "Save profile 8", defaultChords: [k(0x1C, "8", [.command, .option])])
+        case .profileSave9: return .init(
+            category: .profiles, scope: .browserOnly,
+            englishName: "Save profile 9", defaultChords: [k(0x19, "9", [.command, .option])])
+
+        // MARK: Search
+        case .searchToggleOverlay: return .init(
+            category: .search, scope: .browserOnly,
+            englishName: "Toggle search",
+            defaultChords: [k(0x03, "f", .command), k(0x63)],  // Cmd+F, F3
+            firesDuringSearch: true,
+            isSystemConventional: true)
+        case .searchToggleRecursive: return .init(
+            category: .search, scope: .browserOnly,
+            englishName: "Toggle recursive search",
+            defaultChords: [k(0x0F, "r", [.command, .shift])],
+            firesDuringSearch: true)
+        case .searchToggleRecursiveFolder: return .init(
+            category: .search, scope: .browserOnly,
+            englishName: "Toggle recursive folder search",
+            defaultChords: [k(0x03, "f", [.command, .shift])],
+            firesDuringSearch: true)
+
+        // MARK: Quick search
+        case .quickSearchActivate: return .init(
+            category: .quickSearch, scope: .browserOnly,
+            englishName: "Activate quick search",
+            defaultChords: [k(0x0C, "q")])
+        }
+    }
+}
diff --git a/FlowVision/Sources/Shortcuts/ShortcutRecorderView.swift b/FlowVision/Sources/Shortcuts/ShortcutRecorderView.swift
new file mode 100644
index 00000000..55913152
--- /dev/null
+++ b/FlowVision/Sources/Shortcuts/ShortcutRecorderView.swift
@@ -0,0 +1,153 @@
+//
+//  ShortcutRecorderView.swift
+//  FlowVision
+//
+//  NSView subclass that captures a single key chord via first-responder + keyDown.
+//  Bare Esc (no modifiers) clears the binding; Esc with modifiers records normally.
+//
+
+import Cocoa
+
+final class ShortcutRecorderView: NSView {
+
+    var chord: KeyChord? {
+        didSet { needsDisplay = true; if !suppressOnChange { onChange?(chord) } }
+    }
+
+    /// Called when the user commits a new chord (or clears with Esc).
+    var onChange: ((KeyChord?) -> Void)?
+
+    private var suppressOnChange = false
+
+    /// Set chord without firing `onChange`. Use for programmatic updates
+    /// (cell configure / reload) so the consumer doesn't see them as user commits.
+    func setChordSilent(_ c: KeyChord?) {
+        suppressOnChange = true
+        chord = c
+        suppressOnChange = false
+    }
+
+    private var isRecording = false {
+        didSet { needsDisplay = true }
+    }
+
+    /// When false, mouseDown is ignored and the recorder draws greyed out.
+    /// Used by settings rows where the primary chord is system-locked (e.g. Quit).
+    var isEnabled: Bool = true {
+        didSet { needsDisplay = true }
+    }
+
+    override var acceptsFirstResponder: Bool { isEnabled }
+    override var canBecomeKeyView: Bool { isEnabled }
+    override var isFlipped: Bool { false }
+    override var intrinsicContentSize: NSSize { NSSize(width: 140, height: 22) }
+
+    override func acceptsFirstMouse(for event: NSEvent?) -> Bool { isEnabled }
+
+    override func mouseDown(with event: NSEvent) {
+        guard isEnabled else { return }
+        // Only flip recording state if responder transition succeeds — otherwise we'd
+        // be stuck visually recording without receiving keyDown.
+        if window?.makeFirstResponder(self) == true {
+            isRecording = true
+        }
+    }
+
+    override func keyDown(with event: NSEvent) {
+        guard isRecording else { super.keyDown(with: event); return }
+
+        let newChord: KeyChord?
+        let bareEsc = event.keyCode == KeyChord.escKeyCode
+            && Modifiers(event.modifierFlags).isEmpty
+        if bareEsc {
+            newChord = nil          // clear
+        } else {
+            newChord = KeyChord(event: event)
+        }
+
+        // Exit recording state BEFORE firing onChange so any modal conflict alert
+        // rendered by the consumer doesn't paint over a "recording" highlight.
+        endRecording()
+        chord = newChord
+    }
+
+    override func resignFirstResponder() -> Bool {
+        // External take-away (Tab to next view, etc): just exit state, no commit.
+        isRecording = false
+        return super.resignFirstResponder()
+    }
+
+    private func endRecording() {
+        // Explicit-commit path. resignFirstResponder uses its own simpler path to
+        // avoid reentrancy — calling makeFirstResponder(nil) from inside resign
+        // would re-enter this method.
+        guard isRecording else { return }
+        isRecording = false
+        window?.makeFirstResponder(nil)
+    }
+
+    // MARK: - Context menu
+
+    override func menu(for event: NSEvent) -> NSMenu? {
+        // Disabled recorders (locked primary slots) have no context menu so the
+        // user can't bypass the lock by right-clicking → "Clear".
+        guard isEnabled else { return nil }
+        let menu = NSMenu()
+        menu.addItem(withTitle: NSLocalizedString("Clear this shortcut",
+                                                   comment: "recorder context menu"),
+                     action: #selector(clearRequested),
+                     keyEquivalent: "").target = self
+        return menu
+    }
+
+    @objc private func clearRequested() {
+        // Mirror a real recording: fire onChange so the host can drop the slot.
+        chord = nil
+    }
+
+    // MARK: - Drawing
+
+    override func draw(_ rect: NSRect) {
+        let path = NSBezierPath(roundedRect: bounds.insetBy(dx: 1, dy: 1),
+                                 xRadius: 5, yRadius: 5)
+        if !isEnabled {
+            NSColor.controlBackgroundColor.withAlphaComponent(0.4).setFill()
+        } else if isRecording {
+            NSColor.controlAccentColor.withAlphaComponent(0.15).setFill()
+        } else {
+            NSColor.controlBackgroundColor.setFill()
+        }
+        path.fill()
+        NSColor.separatorColor.setStroke()
+        path.stroke()
+
+        let text: String
+        if isRecording {
+            text = NSLocalizedString("shortcut.recorder.prompt",
+                                      value: "Press shortcut…", comment: "")
+        } else if let chord {
+            text = chord.displayString
+        } else {
+            text = NSLocalizedString("shortcut.recorder.empty",
+                                      value: "—", comment: "")
+        }
+
+        let textColor: NSColor
+        if !isEnabled {
+            textColor = .disabledControlTextColor
+        } else if isRecording {
+            textColor = .controlAccentColor
+        } else {
+            textColor = .labelColor
+        }
+        let attrs: [NSAttributedString.Key: Any] = [
+            .font: NSFont.systemFont(ofSize: 12, weight: .medium),
+            .foregroundColor: textColor,
+        ]
+        let str = NSAttributedString(string: text, attributes: attrs)
+        let size = str.size()
+        let origin = NSPoint(x: (bounds.width - size.width) / 2,
+                              y: (bounds.height - size.height) / 2)
+        str.draw(at: origin)
+    }
+}
diff --git a/FlowVision/Sources/Shortcuts/ShortcutStore.swift b/FlowVision/Sources/Shortcuts/ShortcutStore.swift
new file mode 100644
index 00000000..4a9bfe46
--- /dev/null
+++ b/FlowVision/Sources/Shortcuts/ShortcutStore.swift
@@ -0,0 +1,276 @@
+//
+//  ShortcutStore.swift
+//  FlowVision
+//
+//  Each action holds zero, one, or many KeyChords. Persists to UserDefaults
+//  (`shortcutBindings.v2`) and posts `.shortcutsChanged` on every mutation.
+//  Main-thread only — no locking.
+//
+
+import Cocoa
+
+final class ShortcutStore {
+    static let shared = ShortcutStore()
+    private init() {}
+
+    /// Active binding map. Missing key + not in `clearedExplicitly` = use defaults.
+    /// Empty array = user has explicitly removed all bindings.
+    private(set) var bindings: [ShortcutAction: [KeyChord]] = [:]
+
+    /// Lookup index. Multiple actions may share a chord (legal when scopes are
+    /// disjoint — enforced by conflict UI in the settings pane, not by the store).
+    private(set) var reverseIndex: [KeyChord: [ShortcutAction]] = [:]
+
+    /// Actions the user has wiped completely. Distinguishes "user cleared all"
+    /// from "never persisted" so defaults don't sneak back after a reset-empty.
+    private var clearedExplicitly: Set<ShortcutAction> = []
+
+    private let defaultsKey   = "shortcutBindings.v2"
+    private let legacyKeyV1   = "shortcutBindings.v1"
+
+    // MARK: - Wire format v2
+
+    private struct Wire: Codable {
+        let version: Int
+        let entries: [Entry]
+    }
+
+    private struct Entry: Codable {
+        let action: ShortcutAction?
+        let chords: [KeyChord]
+
+        init(action: ShortcutAction, chords: [KeyChord]) {
+            self.action = action
+            self.chords = chords
+        }
+
+        enum CodingKeys: String, CodingKey { case action, chords }
+
+        init(from decoder: Decoder) throws {
+            let c = try decoder.container(keyedBy: CodingKeys.self)
+            let raw = try? c.decode(String.self, forKey: .action)
+            self.action = raw.flatMap { ShortcutAction(rawValue: $0) }
+            self.chords = (try? c.decode([KeyChord].self, forKey: .chords)) ?? []
+        }
+
+        func encode(to encoder: Encoder) throws {
+            var c = encoder.container(keyedBy: CodingKeys.self)
+            try c.encode(action?.rawValue, forKey: .action)
+            try c.encode(chords, forKey: .chords)
+        }
+    }
+
+    // MARK: - Wire format v1 (legacy single-chord)
+
+    private struct WireV1: Codable {
+        let version: Int?
+        let entries: [EntryV1]
+    }
+
+    private struct EntryV1: Codable {
+        let action: ShortcutAction?
+        let chord: KeyChord?
+
+        enum CodingKeys: String, CodingKey { case action, chord }
+
+        init(from decoder: Decoder) throws {
+            let c = try decoder.container(keyedBy: CodingKeys.self)
+            let raw = try? c.decode(String.self, forKey: .action)
+            self.action = raw.flatMap { ShortcutAction(rawValue: $0) }
+            self.chord = try? c.decodeIfPresent(KeyChord.self, forKey: .chord)
+        }
+
+        func encode(to encoder: Encoder) throws {
+            var c = encoder.container(keyedBy: CodingKeys.self)
+            try c.encode(action?.rawValue, forKey: .action)
+            try c.encode(chord, forKey: .chord)
+        }
+    }
+
+    // MARK: - Public API
+
+    /// Returns the active chord list for an action: stored value if present,
+    /// empty if explicitly cleared, defaults otherwise.
+    func chords(for action: ShortcutAction) -> [KeyChord] {
+        if let stored = bindings[action] { return stored }
+        if clearedExplicitly.contains(action) { return [] }
+        return action.defaultChords
+    }
+
+    func load() {
+        clearedExplicitly.removeAll()
+        bindings = [:]
+
+        if let data = UserDefaults.standard.data(forKey: defaultsKey),
+           let wire = try? JSONDecoder().decode(Wire.self, from: data) {
+            applyV2(wire)
+        } else if let data = UserDefaults.standard.data(forKey: legacyKeyV1),
+                  let wire = try? JSONDecoder().decode(WireV1.self, from: data) {
+            applyV1(wire)
+            // Only drop the legacy blob once we've successfully written v2.
+            // If persist() fails, leave v1 in place so the next launch can retry.
+            if persist() {
+                UserDefaults.standard.removeObject(forKey: legacyKeyV1)
+            }
+        }
+        rebuildIndex()
+    }
+
+    private func applyV2(_ wire: Wire) {
+        guard wire.version == 2 else { return }
+        for entry in wire.entries {
+            guard let a = entry.action else { continue }
+            if entry.chords.isEmpty {
+                clearedExplicitly.insert(a)
+            } else {
+                bindings[a] = entry.chords
+            }
+        }
+    }
+
+    private func applyV1(_ wire: WireV1) {
+        for entry in wire.entries {
+            guard let a = entry.action else { continue }
+            if let chord = entry.chord {
+                bindings[a] = [chord]
+            } else {
+                clearedExplicitly.insert(a)
+            }
+        }
+    }
+
+    /// Replace chord at `index` for `action`. If `chord` is nil, remove that slot.
+    /// If `index` equals current count, the chord is appended. Indexes beyond
+    /// `count` are rejected to avoid silent phantom appends.
+    func setChord(_ chord: KeyChord?, at index: Int, for action: ShortcutAction) {
+        var current = chords(for: action)
+        if let chord {
+            if index < current.count {
+                current[index] = chord
+            } else if index == current.count {
+                current.append(chord)
+            } else {
+                return
+            }
+        } else {
+            guard index < current.count else { return }
+            current.remove(at: index)
+        }
+        commit(current, for: action)
+    }
+
+    /// Append a chord to the end of `action`'s chord list.
+    func appendChord(_ chord: KeyChord, for action: ShortcutAction) {
+        var current = chords(for: action)
+        current.append(chord)
+        commit(current, for: action)
+    }
+
+    /// Remove the chord at `index` from `action`'s chord list.
+    func removeChord(at index: Int, for action: ShortcutAction) {
+        var current = chords(for: action)
+        guard index < current.count else { return }
+        current.remove(at: index)
+        commit(current, for: action)
+    }
+
+    /// Remove every occurrence of `chord` from `action`'s chord list. No-op if
+    /// the chord isn't bound on that action.
+    func removeChord(_ chord: KeyChord, from action: ShortcutAction) {
+        var current = chords(for: action)
+        let filtered = current.filter { $0 != chord }
+        guard filtered.count != current.count else { return }
+        current = filtered
+        commit(current, for: action)
+    }
+
+    /// Remove every occurrence of `chord` from each action in `actions` in one
+    /// pass. Posts a single `.shortcutsChanged` notification (object: nil) at
+    /// the end so the Settings view rebuilds once instead of N times.
+    func batchRemove(chord: KeyChord, from actions: [ShortcutAction]) {
+        var anyChanged = false
+        for action in actions {
+            let current = chords(for: action)
+            let filtered = current.filter { $0 != chord }
+            guard filtered.count != current.count else { continue }
+            anyChanged = true
+            if filtered.isEmpty {
+                bindings.removeValue(forKey: action)
+                clearedExplicitly.insert(action)
+            } else {
+                bindings[action] = filtered
+                clearedExplicitly.remove(action)
+            }
+        }
+        guard anyChanged else { return }
+        persist()
+        rebuildIndex()
+        NotificationCenter.default.post(name: .shortcutsChanged, object: nil)
+    }
+
+    /// Reset `action` to its built-in defaults (or empty if no default).
+    func reset(_ action: ShortcutAction) {
+        clearedExplicitly.remove(action)
+        bindings.removeValue(forKey: action)
+        persist()
+        rebuildIndex()
+        NotificationCenter.default.post(name: .shortcutsChanged, object: action)
+    }
+
+    /// Wipe all custom bindings, restore defaults.
+    func resetAll() {
+        clearedExplicitly.removeAll()
+        bindings.removeAll()
+        UserDefaults.standard.removeObject(forKey: defaultsKey)
+        rebuildIndex()
+        NotificationCenter.default.post(name: .shortcutsChanged, object: nil)
+    }
+
+    private func commit(_ chords: [KeyChord], for action: ShortcutAction) {
+        if chords.isEmpty {
+            bindings.removeValue(forKey: action)
+            clearedExplicitly.insert(action)
+        } else {
+            bindings[action] = chords
+            clearedExplicitly.remove(action)
+        }
+        persist()
+        rebuildIndex()
+        NotificationCenter.default.post(name: .shortcutsChanged, object: action)
+    }
+
+    // MARK: - Internals
+
+    private func rebuildIndex() {
+        var idx: [KeyChord: [ShortcutAction]] = [:]
+        for action in ShortcutAction.allCases {
+            // Dedupe within an action so intra-action chord duplicates
+            // don't show up twice in reverseIndex[chord].
+            var seen: Set<KeyChord> = []
+            for chord in chords(for: action) where seen.insert(chord).inserted {
+                idx[chord, default: []].append(action)
+            }
+        }
+        reverseIndex = idx
+    }
+
+    @discardableResult
+    private func persist() -> Bool {
+        var entries: [Entry] = []
+        for a in ShortcutAction.allCases {
+            if clearedExplicitly.contains(a) {
+                entries.append(Entry(action: a, chords: []))
+            } else if let chords = bindings[a] {
+                entries.append(Entry(action: a, chords: chords))
+            }
+        }
+        do {
+            let data = try JSONEncoder().encode(Wire(version: 2, entries: entries))
+            UserDefaults.standard.set(data, forKey: defaultsKey)
+            return true
+        } catch {
+            NSLog("[shortcuts] ShortcutStore.persist failed: \(error)")
+            return false
+        }
+    }
+}
diff --git a/FlowVision/Sources/ViewControllerExtension/KeyShortcut.swift b/FlowVision/Sources/ViewControllerExtension/KeyShortcut.swift
index fd8b13fa..5d35d739 100644
--- a/FlowVision/Sources/ViewControllerExtension/KeyShortcut.swift
+++ b/FlowVision/Sources/ViewControllerExtension/KeyShortcut.swift
@@ -1,993 +1,780 @@
 //
-//  KeyShutcut.swift
+//  KeyShortcut.swift
 //  FlowVision
 //
+//  Dispatcher: receives NSEvent keyDowns, matches against ShortcutStore.reverseIndex,
+//  fires the appropriate action handler. Non-rebindable text-input branches
+//  (quick-search, OCR/rename text ops) are handled before lookup.
+//
 
 import Foundation
 import Cocoa
 
 extension ViewController {
-    
-    func KeyShortcutManager (event: NSEvent) -> NSEvent?
-    {
-        // 检查事件的窗口是否是当前窗口，如果不是、也非弹窗状态，就不处理，事件继续传递
-        // Check if event's window is current window, if not and not popup state, don't process, continue passing event
+
+    func KeyShortcutManager(event: NSEvent) -> NSEvent? {
+        // Window-active gate (preserved).
         if event.window != self.view.window && publicVar.isKeyEventEnabled {
             return event
         }
-        
-        // 获取修饰键
-        // Get modifier keys
+
+        // Non-rebindable text-input branches run first and short-circuit.
+        if handleNonRebindable(event) { return nil }
+
+        // OCR / rename text-system fallthrough (Home/End cursor + Cmd+ACVXZ).
+        // Preserves prior behavior at lines 953-988 of legacy KeyShortcut.swift.
+        if handleTextSystemFallthrough(event) { return nil }
+
+        // 0.1s debounce — held-down keys still rate-limited.
+        if !publicVar.timer.intervalSafe(name: "keyEvent", second: 0.1) {
+            return event
+        }
+
+        // Non-rebindable browser navigation: outline-row arrows, collection-grid
+        // findClosestItem arrows, Tab focus swap, F2/Enter rename, Enter-to-open.
+        // These pre-empt chord dispatch because they're context-dynamic (selection
+        // geometry, first-responder identity, isEnterKeyToOpen setting) rather
+        // than fixed bindings.
+        if handleNonRebindableNavigation(event) { return nil }
+
+        let chord = KeyChord(event: event)
+        let candidates = ShortcutStore.shared.reverseIndex[chord] ?? []
+
+        for action in candidates where stateGateOpen(for: action) && scopeMatches(action.scope) {
+            if dispatch(action) { return nil }
+        }
+        return event
+    }
+
+    // MARK: - Helpers
+
+    private func stateGateOpen(for action: ShortcutAction) -> Bool {
+        action.firesDuringSearch
+            ? (publicVar.isInSearchState || publicVar.isKeyEventEnabled)
+            : publicVar.isKeyEventEnabled
+    }
+
+    private func scopeMatches(_ s: ContextScope) -> Bool {
+        switch s {
+        case .browserOnly: return !publicVar.isInLargeView
+        case .viewerOnly:  return  publicVar.isInLargeView
+        case .both:        return true
+        }
+    }
+
+    private var isInFullScreen: Bool {
+        view.window?.styleMask.contains(.fullScreen) == true
+    }
+
+    /// Returns true if the event was consumed by a non-rebindable text-input branch.
+    /// Mirrors quick-search input from the legacy dispatcher head.
+    func handleNonRebindable(_ event: NSEvent) -> Bool {
         let modifierFlags = event.modifierFlags
-        // 检测是否按下了 Control 键
-        // Detect if Control key is pressed
-        let isCtrlPressed = modifierFlags.contains(.control)
-        // 检测是否按下了 Command 键
-        // Detect if Command key is pressed
         let isCommandPressed = modifierFlags.contains(.command)
-        // 检测是否按下了 Option 键
-        // Detect if Option key is pressed
-        let isAltPressed = modifierFlags.contains(.option)
-        // 检测是否按下了 Shift 键
-        // Detect if Shift key is pressed
-        let isShiftPressed = modifierFlags.contains(.shift)
-        // 检测是否按下了 Fn 键 (部分按键例如方向键按下时此值也为true)
-        // Detect if Fn key is pressed (some keys like arrow keys also set this to true)
-        let isFnPressed = modifierFlags.contains(.function)
-        
-        let noModifierKey = !isCommandPressed && !isAltPressed && !isCtrlPressed && !isShiftPressed
-        let isOnlyCommandPressed = isCommandPressed && !isAltPressed && !isCtrlPressed && !isShiftPressed
-        let isOnlyAltPressed = !isCommandPressed && isAltPressed && !isCtrlPressed && !isShiftPressed
-        let isOnlyCtrlPressed = !isCommandPressed && !isAltPressed && isCtrlPressed && !isShiftPressed
-        let isOnlyShiftPressed = !isCommandPressed && !isAltPressed && !isCtrlPressed && isShiftPressed
-        
+        let isAltPressed     = modifierFlags.contains(.option)
+        let isCtrlPressed    = modifierFlags.contains(.control)
+        let isShiftPressed   = modifierFlags.contains(.shift)
+        let noModifierKey    = !isCommandPressed && !isAltPressed && !isCtrlPressed && !isShiftPressed
         let characters = (event.charactersIgnoringModifiers ?? "").lowercased()
         let specialKey = event.specialKey ?? .f30
 
-        // 把按键信息打印出来，用于调试不同键盘的键值差异
-        // var modifierStrings: [String] = []
-        // if isCommandPressed { modifierStrings.append("Command") }
-        // if isAltPressed { modifierStrings.append("Option") }
-        // if isCtrlPressed { modifierStrings.append("Control") }
-        // if isShiftPressed { modifierStrings.append("Shift") }
-        // if isFnPressed { modifierStrings.append("Fn") }
-        // let modifierDescription = modifierStrings.isEmpty ? "None" : modifierStrings.joined(separator: "+")
-        // log("Key Event Debug - characters: \(characters), keyCode: \(event.keyCode), specialKey: \(specialKey), modifierFlags: \(modifierFlags.rawValue), Modifiers: \(modifierDescription)", level: .debug)
-        
-        // 快速搜索
-        // Quick search
-        if publicVar.isKeyEventEnabled && characters.count == 1 && (characters.first!.isLetter || characters.first!.isNumber) && noModifierKey {
-            if !publicVar.isInLargeView {
-                if quickSearchState || globalVar.useQuickSearch {
-                    quickSearch(characters)
-                    return nil
-                }
-            }
+        // Quick-search letter/digit text input
+        if publicVar.isKeyEventEnabled && characters.count == 1
+            && (characters.first!.isLetter || characters.first!.isNumber) && noModifierKey
+            && !publicVar.isInLargeView
+            && (quickSearchState || globalVar.useQuickSearch) {
+            quickSearch(characters)
+            return true
         }
-        
-        // 快速搜索唤起键
-        // Quick search activation key
-        if publicVar.isKeyEventEnabled && characters == "q" && noModifierKey {
-            if !publicVar.isInLargeView {
-                if !quickSearchState && !globalVar.useQuickSearch {
-                    quickSearch("backspace")
-                    return nil
-                }
-            }
-        }
-        
-        // 快速搜索删除键
-        // Quick search delete key
-        if publicVar.isKeyEventEnabled && specialKey == .delete && noModifierKey {
-            if !publicVar.isInLargeView {
-                if quickSearchState {
-                    quickSearch("backspace")
-                    return nil
-                }
-                if globalVar.useQuickSearch {
-                    return nil
-                }
-            }
-        }
-        
-        // 快速搜索Esc退出键
-        // Quick search Esc exit key
-        if publicVar.isKeyEventEnabled && event.keyCode == 53 {
-            if !publicVar.isInLargeView {
-                if quickSearchState {
-                    quickSearchText = ""
-                    quickSearchState = false
-                    coreAreaView.hideInfo(force: true)
-                    return nil
-                }
-            }
-        }
-        
-        // 防止过快触发事件
-        // Prevent events from triggering too quickly
-        if !publicVar.timer.intervalSafe(name: "keyEvent", second: 0.1) {
-            return event
+
+        // Quick-search backspace
+        if publicVar.isKeyEventEnabled && specialKey == .delete && noModifierKey
+            && !publicVar.isInLargeView {
+            if quickSearchState { quickSearch("backspace"); return true }
+            if globalVar.useQuickSearch { return true }
         }
-        
-        if publicVar.isInSearchState || publicVar.isKeyEventEnabled {
-            // 检查按键是否是 Command+Shift+"R" 键
-            // Check if key is Command+Shift+"R"
-            if characters == "r" && isCommandPressed && !isAltPressed && !isCtrlPressed && isShiftPressed {
-                if !publicVar.isInLargeView{
-                    toggleRecursiveMode()
-                    return nil
-                }
-            }
-            // 检查按键是否是 Command+Shift+"F" 键
-            // Check if key is Command+Shift+"F"
-            if characters == "f" && isCommandPressed && !isAltPressed && !isCtrlPressed && isShiftPressed {
-                if !publicVar.isInLargeView{
-                    toggleRecursiveContainFolder()
-                    return nil
-                }
-            }
-            // 检查按键是否是 Command+Shift+"T" 键
-            // Check if key is Command+Shift+"T"
-            if characters == "t" && isCommandPressed && !isAltPressed && !isCtrlPressed && isShiftPressed {
-                handleReopenClosedTabs()
-                return nil
-            }
-            // 检查按键是否是 F3 键
-            // Check if key is F3
-            if specialKey == .f3 {
-                if !publicVar.isInLargeView{
-                    toggleSearchOverlay()
-                    return nil
-                }
-            }
+
+        // Quick-search Esc
+        if publicVar.isKeyEventEnabled && event.keyCode == KeyChord.escKeyCode
+            && !publicVar.isInLargeView && quickSearchState {
+            quickSearchText = ""
+            quickSearchState = false
+            coreAreaView.hideInfo(force: true)
+            return true
         }
-        
-        if publicVar.isKeyEventEnabled {
-            
-            // 检查按键是否是 "A" 键
-            // Check if key is "A"
-            // RTL: A/D swap large image and folder direction
-            let isRTL_AD = view.userInterfaceLayoutDirection == .rightToLeft
-            if characters == "a" && noModifierKey {
-                if publicVar.isInLargeView{
-                    isRTL_AD ? nextLargeImage() : previousLargeImage()
-                }else{
-                    closeLargeImage(0)
-                    switchDirByDirection(direction: isRTL_AD ? .right : .left, stackDeep: 0)
-                }
-                return nil
-            }
-            // 检查按键是否是 "D" 键
-            // Check if key is "D"
-            if characters == "d" && noModifierKey {
-                if publicVar.isInLargeView{
-                    isRTL_AD ? previousLargeImage() : nextLargeImage()
-                }else{
-                    closeLargeImage(0)
-                    switchDirByDirection(direction: isRTL_AD ? .left : .right, stackDeep: 0)
-                }
-                return nil
-            }
-            // 检查按键是否是 "W" 键
-            // Check if key is "W"
-            if characters == "w" && noModifierKey {
-                if publicVar.isInLargeView{
-                    largeImageView.zoom(direction: +1)
-                }else{
-                    closeLargeImage(0)
-                    switchDirByDirection(direction: .up, stackDeep: 0)
-                }
-                return nil
-            }
-            
-            // 检查按键是否是 "Z" 键
-            // Check if key is "Z"
-            if characters == "z" && noModifierKey {
-                if publicVar.isInLargeView{
-                    largeImageView.zoom100()
-                }
-            }
-            
-            // 检查按键是否是 "X" 键
-            // Check if key is "X"
-            if characters == "x" && noModifierKey {
-                if publicVar.isInLargeView{
-                    largeImageView.zoomFit()
-                }
-            }
-            
-            // 检查按键是否是 "S" 键
-            // Check if key is "S"
-            if characters == "s" && noModifierKey {
-                if publicVar.isInLargeView{
-                    largeImageView.zoom(direction: -1)
-                }else{
-                    closeLargeImage(0)
-                    switchDirByDirection(direction: .down, stackDeep: 0)
-                }
-                return nil
-            }
-            
-            // 检查按键是否是 "Q"
-            // Check if key is "Q"
-            if characters == "q" && noModifierKey {
-                if publicVar.isInLargeView{
-                    largeImageView.actRotateL()
-                }
-                return nil
-            }
-            
-            // 检查按键是否是 "E"
-            // Check if key is "E"
-            if characters == "e" && noModifierKey {
-                if publicVar.isInLargeView{
-                    largeImageView.actRotateR()
-                }else{
-                    switchDirByDirection(direction: .down_right, stackDeep: 0)
-                }
-                return nil
-            }
-            
-            // 检查按键是否是 "R" 键
-            // Check if key is "R"
-            if characters == "r" && noModifierKey {
-                // 如果焦点在OutlineView
-                // If focus is in OutlineView
-                if publicVar.isOutlineViewFirstResponder{
+        return false
+    }
+
+    /// Non-rebindable browser navigation. Returns true if consumed.
+    /// Mirrors legacy KeyShortcut.swift behavior at lines 499-529, 733-743, and
+    /// 745-865: F2/Enter rename, Tab focus swap, outline arrows + space/enter
+    /// expand-toggle, collection-view findClosestItem arrows.
+    private func handleNonRebindableNavigation(_ event: NSEvent) -> Bool {
+        // Suppress navigation while a modal text field (rename, OCR) owns the
+        // key window — legacy kept the entire block inside `isKeyEventEnabled`.
+        guard publicVar.isKeyEventEnabled else { return false }
+
+        let modifierFlags = event.modifierFlags
+        let isCommandPressed = modifierFlags.contains(.command)
+        let isAltPressed     = modifierFlags.contains(.option)
+        let isCtrlPressed    = modifierFlags.contains(.control)
+        let isShiftPressed   = modifierFlags.contains(.shift)
+        let noModifierKey    = !isCommandPressed && !isAltPressed && !isCtrlPressed && !isShiftPressed
+        let isOnlyShiftPressed = !isCommandPressed && !isAltPressed && !isCtrlPressed && isShiftPressed
+        let characters = (event.charactersIgnoringModifiers ?? "").lowercased()
+        let specialKey = event.specialKey ?? .f30
+
+        // F2 / Enter: rename when F2 OR (Enter && !isEnterKeyToOpen);
+        // otherwise (Enter && isEnterKeyToOpen) → close viewer / open large.
+        if (specialKey == .f2 || specialKey == .carriageReturn || specialKey == .enter)
+            && noModifierKey {
+            if specialKey == .f2 || !globalVar.isEnterKeyToOpen {
+                if publicVar.isOutlineViewFirstResponder {
                     outlineView.actRename(isByKeyboard: true)
-                    return nil
+                    return true
                 }
-                
-                // 如果焦点在CollectionView
-                // If focus is in CollectionView
-                if publicVar.isCollectionViewFirstResponder{
-                    handleRename(urls: publicVar.selectedUrls())
-                    return nil
+                if publicVar.isCollectionViewFirstResponder {
+                    _ = handleRename(urls: publicVar.selectedUrls())
+                    return true
                 }
-            }
-            
-            // 检查按键是否是 "," 键
-            // Check if key is ","
-            if characters == "," && noModifierKey {
-                if publicVar.isInLargeView,
-                   largeImageView.file.type == .video {
-                    largeImageView.specifyABPlayPositionA()
+            } else {
+                if publicVar.isInLargeView {
+                    closeLargeImage(0)
+                    return true
                 }
-                return nil
-            }
-            
-            // 检查按键是否是 "." 键
-            // Check if key is "."
-            if characters == "." && noModifierKey {
-                if publicVar.isInLargeView,
-                   largeImageView.file.type == .video {
-                    largeImageView.specifyABPlayPositionB()
+                if let indexPath = collectionView.selectionIndexPaths.min(),
+                   publicVar.isCollectionViewFirstResponder {
+                    openLargeImage(indexPath)
+                    return true
                 }
-                return nil
             }
+        }
 
-            // 检查按键是否是 "J" 键
-            // Check if key is "J"
-            if characters == "j" && noModifierKey {
-                if publicVar.isInLargeView,
-                   largeImageView.file.type == .video {
-                    largeImageView.actRememberPlayPosition()
-                }
-                return nil
+        // Tab: swap focus between outline and collection view (browser only).
+        if specialKey == .tab && noModifierKey && !publicVar.isInLargeView {
+            if publicVar.isOutlineViewFirstResponder {
+                view.window?.makeFirstResponder(collectionView)
+                return true
             }
-            
-            // 检查按键是否是 "K" 键
-            // Check if key is "K"
-            if characters == "k" && noModifierKey {
-                if publicVar.isInLargeView,
-                   largeImageView.file.type == .video {
-                    largeImageView.actABPlay()
-                }
-                return nil
+            if publicVar.isCollectionViewFirstResponder {
+                view.window?.makeFirstResponder(outlineView)
+                return true
             }
+        }
 
-            // 检查按键是否是 "L" 键
-            // Check if key is "L"
-            if characters == "l" && noModifierKey {
-                if publicVar.isInLargeView,
-                   largeImageView.file.type == .video {
-                    largeImageView.actSequentialPlay()
-                }
-                return nil
-            }
-            
-            // 检查按键是否是 Cmd + "R" / F5 键
-            // Check if key is Cmd + "R" / F5
-            if (characters == "r" && isOnlyCommandPressed) || specialKey == .f5 {
-                handleUserRefresh()
-                return nil
-            }
-            
-            // 检查按键是否是 Command+[ 键
-            // Check if key is Command+[
-            if characters == "[" && isOnlyCommandPressed {
-                if publicVar.isInLargeView{
-                    previousLargeImage()
-                } else {
-                    switchDirByDirection(direction: .back, stackDeep: 0)
-                }
-                return nil
-            }
-            
-            // 检查按键是否是 Command+] 键
-            // Check if key is Command+]
-            if characters == "]" && isOnlyCommandPressed {
-                if publicVar.isInLargeView{
-                    nextLargeImage()
+        // Arrow keys + space + enter-to-open in browser views.
+        let isArrow = specialKey == .leftArrow || specialKey == .rightArrow
+            || specialKey == .upArrow || specialKey == .downArrow
+        let isSpace = characters == " "
+        let isEnterToOpen = (specialKey == .carriageReturn || specialKey == .enter)
+            && globalVar.isEnterKeyToOpen
+        guard (isArrow || isSpace || isEnterToOpen)
+              && (noModifierKey || isOnlyShiftPressed)
+              && !publicVar.isInLargeView else {
+            return false
+        }
+
+        // Outline branch: arrows navigate rows, ← → / space / enter toggle expand.
+        if publicVar.isOutlineViewFirstResponder, let outlineView {
+            let selectedRow = outlineView.selectedRow
+            if specialKey == .upArrow {
+                if selectedRow > 0 {
+                    let previousRow = selectedRow - 1
+                    outlineView.selectRowIndexes(IndexSet(integer: previousRow),
+                                                  byExtendingSelection: false)
+                    outlineView.scrollRowToVisible(previousRow)
+                }
+            } else if specialKey == .downArrow {
+                if selectedRow != -1 && selectedRow < outlineView.numberOfRows - 1 {
+                    let nextRow = selectedRow + 1
+                    outlineView.selectRowIndexes(IndexSet(integer: nextRow),
+                                                  byExtendingSelection: false)
+                    outlineView.scrollRowToVisible(nextRow)
+                }
+            } else if let item = outlineView.item(atRow: selectedRow),
+                      outlineView.isExpandable(item) {
+                if outlineView.isItemExpanded(item) {
+                    outlineView.collapseItem(item)
                 } else {
-                    switchDirByDirection(direction: .forward, stackDeep: 0)
+                    outlineView.expandItem(item)
                 }
-                return nil
             }
+            return true
+        }
 
-            // 检查按键是否是 Command+Shift+"N" 键
-            // Check if key is Command+Shift+"N"
-            if characters == "n" && isCommandPressed && !isAltPressed && !isCtrlPressed && isShiftPressed {
-                if !publicVar.isInLargeView{
-                    _ = handleNewFolder()
-                    return nil
-                }
-            }
-            
-            // 检查按键是否是 Command+Shift+"V" 键
-            // Check if key is Command+Shift+"V"
-            if characters == "v" && isCommandPressed && !isAltPressed && !isCtrlPressed && isShiftPressed {
-                if !publicVar.isInLargeView{
-                    toggleAutoPlayVisibleVideo()
-                    return nil
-                }
-            }
+        // Collection branch: only arrows. Space / Enter fall through to chord
+        // dispatch so the user-rebindable `viewerOpenFromSelection` action wins.
+        guard publicVar.isCollectionViewFirstResponder && isArrow,
+              let collectionView,
+              let scrollView = collectionView.enclosingScrollView else {
+            return false
+        }
 
-            // 检查按键是否是 Command+Shift+"E" 键
-            // Check if key is Command+Shift+"E"
-            if characters == "e" && isCommandPressed && !isAltPressed && !isCtrlPressed && isShiftPressed && EDIT_FEATURE_ENABLED {
-                if publicVar.isInLargeView{
-                    largeImageView.enterEditMode(){ editedImage in
-                        // editedImage 是编辑完成后的图片
-                        self.largeImageView.imageView.image = editedImage
-                    }
-                }
-                return nil
-            }
-            
-            // 检查按键是否是 Command+⬅️➡️ 键
-            // Check if key is Command+⬅️➡️
-            // RTL: swap frame seek direction
-            if (specialKey == .leftArrow || specialKey == .rightArrow) && isOnlyCommandPressed {
-                if publicVar.isInLargeView,
-                   largeImageView.file.type == .video {
-                    let isRTL_Cmd = view.userInterfaceLayoutDirection == .rightToLeft
-                    if specialKey == .leftArrow {
-                        largeImageView.seekVideoByFrame(direction: isRTL_Cmd ? 1 : -1)
-                    }else{
-                        largeImageView.seekVideoByFrame(direction: isRTL_Cmd ? -1 : 1)
-                    }
-                    return nil
-                }
-            }
-            
-            // 检查按键是否是 Command+⬆️ 键
-            // Check if key is Command+⬆️
-            if (specialKey == .upArrow && isOnlyCommandPressed) || (specialKey == .home && noModifierKey) {
-                if publicVar.isInLargeView{
-                    locateLargeImage(direction: -2)
-                }else{
-                    if let scrollView = collectionView.enclosingScrollView {
-                        scrollView.contentView.scroll(to: NSPoint(x: 0, y: 0))
-                        scrollView.reflectScrolledClipView(scrollView.contentView)
-                        DispatchQueue.main.async { [weak self] in
-                            self?.setLoadThumbPriority(ifNeedVisable: true)
-                        }
-                    }
-                }
-                return nil
-            }
-            
-            // 检查按键是否是 Command+⬇️ 键
-            // Check if key is Command+⬇️
-            if (specialKey == .downArrow && isOnlyCommandPressed) || (specialKey == .end && noModifierKey) {
-                if publicVar.isInLargeView{
-                    locateLargeImage(direction: 2)
-                }else{
-                    if let scrollView = collectionView.enclosingScrollView {
-                        let newOrigin = NSPoint(x: 0, y: collectionView.bounds.height - scrollView.contentSize.height)
-                        scrollView.contentView.scroll(to: newOrigin)
-                        scrollView.reflectScrolledClipView(scrollView.contentView)
-                        DispatchQueue.main.async { [weak self] in
-                            self?.setLoadThumbPriority(ifNeedVisable: true)
-                        }
-                    }
-                }
-                return nil
-            }
-            
-            // 检查按键是否是 Opt+⬆️ 键
-            // Check if key is Opt+⬆️
-            if (specialKey == .upArrow && isOnlyAltPressed) || (specialKey == .pageUp && noModifierKey) {
-                if !publicVar.isInLargeView{
-                    if let scrollView = collectionView.enclosingScrollView {
-                        let currentOrigin = scrollView.contentView.bounds.origin
-                        let pageHeight = scrollView.contentSize.height
-                        
-                        // Calculate the new y position by subtracting the page height from the current y position.
-                        let newY = max(currentOrigin.y - pageHeight, 0)
-                        let newOrigin = NSPoint(x: currentOrigin.x, y: newY)
-                        
-                        // Scroll to the new origin
-                        scrollView.contentView.scroll(to: newOrigin)
-                        scrollView.reflectScrolledClipView(scrollView.contentView)
-                        
-                        DispatchQueue.main.async { [weak self] in
-                            self?.setLoadThumbPriority(ifNeedVisable: true)
-                        }
-                    }
-                    return nil
-                }
-            }
-            
-            
-            // 检查按键是否是 Opt+⬇️ 键
-            // Check if key is Opt+⬇️
-            if (specialKey == .downArrow && isOnlyAltPressed) || (specialKey == .pageDown && noModifierKey) {
-                if !publicVar.isInLargeView{
-                    if let scrollView = collectionView.enclosingScrollView {
-                        let currentOrigin = scrollView.contentView.bounds.origin
-                        let pageHeight = scrollView.contentSize.height
-                        
-                        // Calculate the new y position by adding the page height to the current y position.
-                        let newY = min(currentOrigin.y + pageHeight, collectionView.bounds.height - pageHeight)
-                        let newOrigin = NSPoint(x: currentOrigin.x, y: newY)
-                        
-                        // Scroll to the new origin
-                        scrollView.contentView.scroll(to: newOrigin)
-                        scrollView.reflectScrolledClipView(scrollView.contentView)
-                        
-                        DispatchQueue.main.async { [weak self] in
-                            self?.setLoadThumbPriority(ifNeedVisable: true)
-                        }
-                    }
-                    return nil
-                }
-            }
-            
-            // 检查按键是否是 Esc 键
-            // Check if key is Esc
-            if event.keyCode == 53 {
-                //                    self.view.window?.close()
-                if publicVar.isInLargeView{
-                    closeLargeImage(0)
-                    return nil
-                }else{
-                    if publicVar.isCollectionViewFirstResponder{
-                        collectionView.deselectAll(nil)
-                    }
-                    return nil
-                }
-            }
-            
-            // 检查按键是否是 Delete(117) Backspace(51) 键
-            // Check if key is Delete(117) Backspace(51)
-            if specialKey == .delete || specialKey == .backspace || specialKey == .deleteForward {
-                // 如果焦点在OutlineView
-                // If focus is on OutlineView
-                if publicVar.isOutlineViewFirstResponder{
-                    outlineView.actDelete(isByKeyboard: true, isShowPrompt: !isCommandPressed)
-                    return nil
-                }
-                // 如果焦点在CollectionView
-                // If focus is on CollectionView
-                if publicVar.isCollectionViewFirstResponder{
-                    handleDelete(isShowPrompt: !isCommandPressed)
-                    return nil
-                }
-            }
-            
-            // 检查按键是否是 Opt + 回车、小键盘回车 键
-            // Check if key is Opt + Enter, numpad Enter
-            if (specialKey == .carriageReturn || specialKey == .enter) && isOnlyAltPressed {
-                if let window = view.window {
-                    window.toggleFullScreen(nil)
-                }
-                return nil
-            }
-            
-            // 检查按键是否是 F2、回车、小键盘回车 键
-            // Check if key is F2, Enter, numpad Enter
-            if (specialKey == .f2 || specialKey == .carriageReturn || specialKey == .enter) && noModifierKey {
-                if specialKey == .f2 || !globalVar.isEnterKeyToOpen {
-                    // 如果焦点在OutlineView
-                    // If focus is in OutlineView
-                    if publicVar.isOutlineViewFirstResponder{
-                        outlineView.actRename(isByKeyboard: true)
-                        return nil
-                    }
-                    
-                    // 如果焦点在CollectionView
-                    // If focus is in CollectionView
-                    if publicVar.isCollectionViewFirstResponder{
-                        handleRename(urls: publicVar.selectedUrls())
-                        return nil
-                    }
-                }else{
-                    if publicVar.isInLargeView{
-                        closeLargeImage(0)
-                        return nil
-                    }else{
-                        if let indexPath = collectionView.selectionIndexPaths.min() {
-                            if publicVar.isCollectionViewFirstResponder{
-                                openLargeImage(indexPath)
-                                return nil
-                            }
-                        }
-                    }
-                }
-            }
-            
-            // 检查按键是否是 空格 键
-            // Check if key is Space
-            if characters == " " && noModifierKey {
-                if publicVar.isInLargeView{
-                    if largeImageView.file.type == .video {
-                        largeImageView.pauseOrResumeVideo()
-                    }else{
-                        closeLargeImage(0)
-                    }
-                    return nil
-                }else{
-                    if let indexPath = collectionView.selectionIndexPaths.min() {
-                        if publicVar.isCollectionViewFirstResponder{
-                            openLargeImage(indexPath)
-                            return nil
-                        }
-                    }
-                }
-            }
-            
-            //                // 检查按键是否是 1、1(小键盘) 键
-            //                if event.keyCode == 18 || event.keyCode == 83 {
-            //                    switchToJustifiedView()
-            //                }
-            //                // 检查按键是否是 2、2(小键盘) 键
-            //                if event.keyCode == 19 || event.keyCode == 84 {
-            //                    switchToWaterfallView()
-            //                }
-            //                // 检查按键是否是 3、3(小键盘) 键
-            //                if event.keyCode == 20 || event.keyCode == 85 {
-            //                    switchToGridView()
-            //                }
-            //                // 检查按键是否是 4、4(小键盘) 键
-            //                if event.keyCode == 21 || event.keyCode == 86 {
-            //                    switchToDetailView()
-            //                }
-            
-            // 检查按键是否是 12345 键
-            // Check if key is 12345
-            if (["1","2","3","4","5"].contains(characters)) && noModifierKey {
-                if view.window?.styleMask.contains(.fullScreen) == true {
-                    return nil
-                }
-                if characters == "1" { // 1
-                    adjustWindowMaximize()
-                    return nil
-                }else if characters == "2"{ // 2
-                    adjustWindowSuitable()
-                    return nil
-                }else if characters == "5"{ // 5
-                    adjustWindowToCenter()
-                    return nil
-                }else{
-                    if publicVar.isInLargeView {
-                        if characters == "3"{ // 3
-                            adjustWindowImageActual()
-                            return nil
-                        }else if characters == "4"{ // 4
-                            adjustWindowImageCurrent()
-                            return nil
-                        }
-                    }
-                }
-            }
+        if !collectionView.selectionIndexPaths.isEmpty {
+            let sortedIndexPaths = collectionView.selectionIndexPaths.sorted()
+            var currentIndexPath = sortedIndexPaths.first!
+            if specialKey == .rightArrow || specialKey == .downArrow {
+                currentIndexPath = sortedIndexPaths.last!
+            }
+            // findClosestItem scrolls multiple times internally; snapshot and
+            // restore the scroll position so the user doesn't see a jitter.
+            let savedContentOffset = scrollView.contentView.bounds.origin
+            let newIndexPath = findClosestItem(currentIndexPath: currentIndexPath,
+                                                direction: specialKey)
+            scrollView.contentView.setBoundsOrigin(savedContentOffset)
+            scrollView.reflectScrolledClipView(scrollView.contentView)
 
-            // 检查按键是否是 Command+1~9 键
-            // Check if key is Command+1~9
-            if ["1","2","3","4","5","6","7","8","9"].contains(characters) && isOnlyCommandPressed {
-                if publicVar.isCollectionViewFirstResponder {
-                    let index = Int(characters)! - 1
-                    handleToggleFinderTag(FinderTag.all[index].name)
-                    return nil
+            if let newIndexPath {
+                if !(isCommandKeyPressed() || isShiftKeyPressed()) {
+                    collectionView.deselectAll(nil)
                 }
-            }
-
-            // 检查按键是否是 Command+Shift+1~9 键
-            // Check if key is Command+Shift+1~9
-            // if ["1","2","3","4","5","6","7","8","9"].contains(characters) && isCommandPressed && isShiftPressed && !isAltPressed && !isCtrlPressed {
-            //     if publicVar.isCollectionViewFirstResponder {
-            //         let index = Int(characters)! - 1
-            //         toggleFinderTagFilter(index)
-            //         return nil
-            //     }
-            // }
-
-            // 检查按键是否是 Control+1~5 键
-            // Check if key is Command+1~5
-            if ["1","2","3","4","5","0"].contains(characters) && isOnlyCtrlPressed {
-                if publicVar.isCollectionViewFirstResponder {
-                    let index = Int(characters)!
-                    handleRating(rating: index)
-                    return nil
+                if let toSelect = collectionView.delegate?.collectionView?(collectionView,
+                                                                            shouldSelectItemsAt: [newIndexPath]) {
+                    collectionView.scrollToItems(at: [newIndexPath],
+                                                  scrollPosition: .nearestHorizontalEdge)
+                    collectionView.selectItems(at: toSelect, scrollPosition: [])
+                    collectionView.delegate?.collectionView?(collectionView,
+                                                              didSelectItemsAt: toSelect)
+                    setLoadThumbPriority(ifNeedVisable: true)
                 }
             }
+            return true
+        }
 
-            // 检查按键是否是 Control+Shift+1~5 键
-            // Check if key is Control+Shift+1~5
-            // if ["1","2","3","4","5","0"].contains(characters) && isCtrlPressed && isShiftPressed && !isAltPressed && !isCommandPressed {
-            //     if publicVar.isCollectionViewFirstResponder {
-            //         let index = Int(characters)!
-            //         toggleRatingFilter(index)
-            //         return nil
-            //     }
-            // }
-            
-            // 检查按键是否是 Opt+1~9 键
-            // Check if key is Opt+1~9
-            if (["1","2","3","4","5","6","7","8","9"].contains(characters)) && isOnlyAltPressed {
-                if !publicVar.isInLargeView {
-                    useCustomProfile(characters)
-                    return nil
-                }
-            }
-            
-            // 检查按键是否是 Cmd+Opt+1~9 键
-            // Check if key is Cmd+Opt+1~9
-            if (["1","2","3","4","5","6","7","8","9"].contains(characters)) && isCommandPressed && isAltPressed && !isCtrlPressed && !isShiftPressed {
-                if !publicVar.isInLargeView {
-                    setCustomProfileTo(characters)
-                    return nil
-                }
-            }
-            
-            // 检查按键是否是 "U"
-            // Check if key is "U"
-            if characters == "u" && noModifierKey {
-                if publicVar.isInLargeView {
-                    handleGetInfo()
-                    return nil
-                }
-            }
-            
-            // 检查按键是否是 "I"
-            // Check if key is "I"
-            if characters == "i" && noModifierKey {
-                if publicVar.isInLargeView{
-                    largeImageView.actShowExif()
-                    return nil
-                }else{
-                    if publicVar.isOutlineViewFirstResponder{
-                        outlineView.actGetInfo(isByKeyboard: true)
-                        return nil
-                    }
-                    if publicVar.isCollectionViewFirstResponder{
-                        handleGetInfo()
-                        return nil
-                    }
-                }
-            }
-            
-            // 检查按键是否是 "O"
-            // Check if key is "O"
-            if characters == "o" && noModifierKey {
-                if publicVar.isInLargeView{
-                    largeImageView.actOCR()
-                    return nil
-                }
-            }
-            
-            // 检查按键是否是 "P"
-            // Check if key is "P"
-            if characters == "p" && noModifierKey {
-                if publicVar.isInLargeView{
-                    largeImageView.actQRCode()
-                    return nil
-                }
-            }
-            
-            // 检查按键是否是 ➡️、⬇️、PageDown 键
-            // Check if key is ➡️, ⬇️, PageDown
-            let isRTL = view.userInterfaceLayoutDirection == .rightToLeft
-            if (specialKey == .rightArrow || specialKey == .downArrow || specialKey == .pageDown || specialKey == .next) && noModifierKey {
-                if publicVar.isInLargeView{
-                    if largeImageView.file.type == .video && specialKey == .rightArrow {
-                        // RTL: right arrow = backward
-                        largeImageView.seekVideo(direction: isRTL ? -1 : 1)
-                    } else if specialKey == .rightArrow && isRTL {
-                        previousLargeImage()
-                    } else {
-                        nextLargeImage()
-                    }
-                    return nil
-                }
-            }
-            // 检查按键是否是 ⬅️、⬆️、PageUp 键
-            // Check if key is ⬅️, ⬆️, PageUp
-            if (specialKey == .leftArrow || specialKey == .upArrow || specialKey == .pageUp || specialKey == .prev) && noModifierKey {
-                if publicVar.isInLargeView{
-                    if largeImageView.file.type == .video && specialKey == .leftArrow {
-                        // RTL: left arrow = forward
-                        largeImageView.seekVideo(direction: isRTL ? 1 : -1)
-                    } else if specialKey == .leftArrow && isRTL {
-                        nextLargeImage()
-                    } else {
-                        previousLargeImage()
-                    }
-                    return nil
-                }
-            }
-            
-            // 检查按键是否是 Tab 键
-            // Check if key is Tab
-            if specialKey == .tab && noModifierKey {
-                if !publicVar.isInLargeView{
-                    if publicVar.isOutlineViewFirstResponder{
-                        view.window?.makeFirstResponder(collectionView)
-                        return nil
-                    }else if publicVar.isCollectionViewFirstResponder{
-                        view.window?.makeFirstResponder(outlineView)
-                        return nil
-                    }
-                }
-            }
-            
-            // 检查按键是否是 "⬅️➡️⬆️⬇️" 或 Space/Enter 键
-            // Check if key is "⬅️➡️⬆️⬇️" or Space/Enter
-            if (specialKey == .leftArrow || specialKey == .rightArrow || specialKey == .upArrow || specialKey == .downArrow || characters == " " || ((specialKey == .carriageReturn || specialKey == .enter) && globalVar.isEnterKeyToOpen))
-                && (noModifierKey || isOnlyShiftPressed) {
-                if !publicVar.isInLargeView{
-                    // 如果焦点在OutlineView
-                    // If focus is in OutlineView
-                    if publicVar.isOutlineViewFirstResponder{
-                        if let outlineView = outlineView {
-                            let selectedRow=outlineView.selectedRow
-                            // ⬆️
-                            if specialKey == .upArrow {
-                                if selectedRow > 0 {
-                                    let previousRow = selectedRow - 1
-                                    outlineView.selectRowIndexes(IndexSet(integer: previousRow), byExtendingSelection: false)
-                                    // 可选：滚动视图以确保选中的项可见
-                                    // Optional: Scroll view to ensure selected item is visible
-                                    outlineView.scrollRowToVisible(previousRow)
-                                }
-                                // ⬇️
-                            } else if specialKey == .downArrow {
-                                if selectedRow != -1 && selectedRow < outlineView.numberOfRows - 1 {
-                                    let nextRow = selectedRow + 1
-                                    outlineView.selectRowIndexes(IndexSet(integer: nextRow), byExtendingSelection: false)
-                                    // 可选：滚动视图以确保选中的项可见
-                                    // Optional: Scroll view to ensure selected item is visible
-                                    outlineView.scrollRowToVisible(nextRow)
-                                }
-                                // ⬅️➡️、Space/Enter
-                                // ⬅️➡️, Space/Enter
-                            }else {
-                                // 获取行对应的条目
-                                // Get item corresponding to row
-                                if let item = outlineView.item(atRow: selectedRow) {
-                                    if outlineView.isExpandable(item) {
-                                        if outlineView.isItemExpanded(item) {
-                                            outlineView.collapseItem(item)
-                                        } else {
-                                            outlineView.expandItem(item)
-                                        }
-                                    }
-                                }
-                            }
-                            return nil
-                        }
-                    }
-                    
-                    // 如果焦点在CollectionView
-                    // If focus is in CollectionView
-                    if publicVar.isCollectionViewFirstResponder{
-                        if let collectionView = collectionView,
-                           let scrollView = collectionView.enclosingScrollView,
-                           // 有选中项
-                           // Has selected items
-                            !collectionView.selectionIndexPaths.isEmpty
-                        {
-                            if specialKey == .leftArrow || specialKey == .rightArrow || specialKey == .upArrow || specialKey == .downArrow {
-                                let sortedIndexPaths = collectionView.selectionIndexPaths.sorted()
-                                var currentIndexPath = sortedIndexPaths.first!
-                                if specialKey == .rightArrow || specialKey == .downArrow {
-                                    currentIndexPath = sortedIndexPaths.last!
-                                }
-                                
-                                // 存储当前滚动位置，因为findClosestItem期间会多次滚动
-                                // Store current scroll position, as findClosestItem will scroll multiple times
-                                let savedContentOffset = scrollView.contentView.bounds.origin
-                                
-                                var newIndexPath: IndexPath?
-                                newIndexPath = findClosestItem(currentIndexPath: currentIndexPath, direction: specialKey)
-                                
-                                // 还原滚动位置
-                                // Restore scroll position
-                                scrollView.contentView.setBoundsOrigin(savedContentOffset)
-                                scrollView.reflectScrolledClipView(scrollView.contentView)
-                                
-                                if let newIndexPath = newIndexPath {
-                                    if !(isCommandKeyPressed() || isShiftKeyPressed()) {
-                                        collectionView.deselectAll(nil)
-                                    }
-                                    if let toSelect = collectionView.delegate?.collectionView?(collectionView, shouldSelectItemsAt: [newIndexPath]) {
-                                        collectionView.scrollToItems(at: [newIndexPath], scrollPosition: .nearestHorizontalEdge)
-                                        // collectionView.reloadData()
-                                        collectionView.selectItems(at: toSelect, scrollPosition: [])
-                                        collectionView.delegate?.collectionView?(collectionView, didSelectItemsAt: toSelect)
-                                        setLoadThumbPriority(ifNeedVisable: true)
-                                    }
-                                }
-                            }
-                            
-                            // 无选中项
-                            // No selected items
-                        }else if let collectionView = collectionView {
-                            
-                            var indexPaths = collectionView.indexPathsForVisibleItems()
-                            
-                            let visibleRectRaw = mainScrollView.contentView.visibleRect
-                            let scrollPos = visibleRectRaw.origin
-                            let scrollWidth = visibleRectRaw.width
-                            let scrollHeight = visibleRectRaw.height
-                            // 注意这里乘了1
-                            // Note: multiplied by 1 here
-                            let visibleRect = NSRect(origin: scrollPos, size: CGSize(width: scrollWidth, height: scrollHeight*1))
-                            indexPaths = indexPaths.filter { indexPath in
-                                let itemFrame = collectionView.layoutAttributesForItem(at: indexPath)?.frame ?? .zero
-                                return itemFrame.intersects(visibleRect)
-                            }
-                            let sortedIndexPaths = indexPaths.sorted { $0.item < $1.item }
-                            
-                            if let newIndexPath = sortedIndexPaths.first,
-                               let toSelect = collectionView.delegate?.collectionView?(collectionView, shouldSelectItemsAt: [newIndexPath]) {
-                                collectionView.scrollToItems(at: [newIndexPath], scrollPosition: .nearestHorizontalEdge)
-                                // collectionView.reloadData()
-                                collectionView.selectItems(at: toSelect, scrollPosition: [])
-                                collectionView.delegate?.collectionView?(collectionView, didSelectItemsAt: [newIndexPath])
-                                setLoadThumbPriority(ifNeedVisable: true)
-                            }
-                        }
-                        return nil
-                    }
-                }
-            }
-            
-            // 检查按键是否是 "F" 键
-            // Check if key is "F"
-            if characters == "f" && noModifierKey && !isFnPressed {
-                if publicVar.isInLargeView{
-                    largeImageView.actMirrorH()
-                }else{
-                    toggleSidebar()
-                    return nil
-                }
-            }
-            
-            // 检查按键是否是 "T" 键
-            // Check if key is "T"
-            if characters == "t" && noModifierKey {
-                toggleOnTop()
-                return nil
-            }
-            
-            // 检查按键是否是 -、-(小键盘) 键
-            // Check if key is -, -(numpad)
-            if characters == "-" && noModifierKey {
-                if publicVar.isInLargeView{
-                    if largeImageView.file.type == .video {
-                        largeImageView.decreaseVolume()
-                    }else{
-                        largeImageView.zoom(direction: -1)
-                    }
-                    return nil
-                }else{
-                    adjustThumbSizeByDirection(direction: -1)
-                    return nil
-                }
-            }
-            
-            // 检查按键是否是 +(=)、+(小键盘) 键
-            // Check if key is +(=), +(numpad)
-            if (characters == "=" || characters == "+") && noModifierKey {
-                if publicVar.isInLargeView {
-                    if largeImageView.file.type == .video {
-                        largeImageView.increaseVolume()
-                    }else{
-                        largeImageView.zoom(direction: +1)
-                    }
-                    return nil
-                }else{
-                    adjustThumbSizeByDirection(direction: +1)
-                    return nil
-                }
-            }
-            
-            // 检查按键是否是 0、0(小键盘) 键
-            // Check if key is 0, 0(numpad)
-            if characters == "0" && noModifierKey {
-                if publicVar.isInLargeView {
-                    changeLargeImage(firstShowThumb: false, resetSize: true, triggeredByLongPress: true)
-                    return nil
-                }else{
-                    adjustThumbSizeByDirection(direction: 0)
-                    return nil
-                }
-            }
-            
-            // 检查按键是否是 "N" 键
-            // Check if key is "N"
-            if characters == "n" && noModifierKey {
-                // 如果焦点在CollectionView
-                // If focus is in CollectionView
-                if publicVar.isCollectionViewFirstResponder{
-                    handleCopyToDownload()
-                    return nil
-                }
-            }
-            
-            // 检查按键是否是 "M" 键
-            // Check if key is "M"
-            if characters == "m" && noModifierKey {
-                // 如果焦点在CollectionView
-                // If focus is in CollectionView
-                if publicVar.isCollectionViewFirstResponder{
-                    handleMoveToDownload()
-                    return nil
-                }
-            }
-            
+        // No selection: pick first visible item as anchor.
+        let visibleRect = mainScrollView.contentView.visibleRect
+        let visiblePaths = collectionView.indexPathsForVisibleItems().filter { ip in
+            (collectionView.layoutAttributesForItem(at: ip)?.frame ?? .zero).intersects(visibleRect)
+        }
+        if let newIndexPath = visiblePaths.sorted(by: { $0.item < $1.item }).first,
+           let toSelect = collectionView.delegate?.collectionView?(collectionView,
+                                                                    shouldSelectItemsAt: [newIndexPath]) {
+            collectionView.scrollToItems(at: [newIndexPath],
+                                          scrollPosition: .nearestHorizontalEdge)
+            collectionView.selectItems(at: toSelect, scrollPosition: [])
+            collectionView.delegate?.collectionView?(collectionView,
+                                                      didSelectItemsAt: [newIndexPath])
+            setLoadThumbPriority(ifNeedVisable: true)
         }
-        
-        // 处理弹出重命名对话框、OCR状态的 Home/End 光标移动操作
-        // Handle Home/End cursor movement for rename dialog popup and OCR state
+        return true
+    }
+
+    /// Text-system fallthrough for rename dialog / OCR state. Returns true if consumed.
+    private func handleTextSystemFallthrough(_ event: NSEvent) -> Bool {
+        let isOnlyCommandPressed = event.modifierFlags.contains(.command)
+            && !event.modifierFlags.contains(.option)
+            && !event.modifierFlags.contains(.control)
+            && !event.modifierFlags.contains(.shift)
+        let specialKey = event.specialKey ?? .f30
+
         if !publicVar.isKeyEventEnabled || largeImageView.isInOcrState {
             if specialKey == .home {
                 NSApp.keyWindow?.firstResponder?.moveToBeginningOfDocument(nil)
-                return nil
+                return true
             }
             if specialKey == .end {
                 NSApp.keyWindow?.firstResponder?.moveToEndOfDocument(nil)
-                return nil
+                return true
             }
         }
 
-        // 处理弹出重命名对话框、OCR状态的复制粘贴、撤销操作
-        // Handle copy/paste and undo operations for rename dialog popup and OCR state
         if (!publicVar.isKeyEventEnabled || largeImageView.isInOcrState) && isOnlyCommandPressed {
-            switch event.charactersIgnoringModifiers {
+            // Lowercased so Caps Lock doesn't break Cmd+ACVXZ.
+            switch event.charactersIgnoringModifiers?.lowercased() {
             case "a":
                 NSApp.sendAction(#selector(NSText.selectAll(_:)), to: nil, from: nil)
-                return nil
+                return true
             case "c":
                 NSApp.sendAction(#selector(NSText.copy(_:)), to: nil, from: nil)
-                return nil
+                return true
             case "v":
                 NSApp.sendAction(#selector(NSText.paste(_:)), to: nil, from: nil)
-                return nil
+                return true
             case "x":
                 NSApp.sendAction(#selector(NSText.cut(_:)), to: nil, from: nil)
-                return nil
+                return true
             case "z":
                 NSApp.sendAction(Selector(("undo:")), to: nil, from: nil)
-                return nil
+                return true
             default:
                 break
             }
         }
-        
-        return event
-        // return nil
+        return false
+    }
+
+    // MARK: - Dispatch table
+
+    /// One case per ShortcutAction. Returns true on handled, false when the bound chord
+    /// fired but the contextual gate (e.g. CollectionView focus) didn't open — caller
+    /// continues to next candidate or lets event propagate.
+    func dispatch(_ action: ShortcutAction) -> Bool {
+        let isRTL = view.userInterfaceLayoutDirection == .rightToLeft
+
+        switch action {
+
+        // MARK: Browser nav
+        //
+        // scope=browserOnly already gates these cases on !isInLargeView, so the
+        // defensive closeLargeImage(0) calls present in the legacy dispatcher
+        // are redundant here.
+        case .browserDirLeft:
+            switchDirByDirection(direction: isRTL ? .right : .left, stackDeep: 0)
+            return true
+        case .browserDirRight:
+            switchDirByDirection(direction: isRTL ? .left : .right, stackDeep: 0)
+            return true
+        case .browserDirUp:
+            switchDirByDirection(direction: .up, stackDeep: 0)
+            return true
+        case .browserDirDown:
+            switchDirByDirection(direction: .down, stackDeep: 0)
+            return true
+        case .browserDirDownRight:
+            switchDirByDirection(direction: .down_right, stackDeep: 0)
+            return true
+        case .browserBack:
+            switchDirByDirection(direction: .back, stackDeep: 0)
+            return true
+        case .browserForward:
+            switchDirByDirection(direction: .forward, stackDeep: 0)
+            return true
+        case .browserScrollTop:
+            if let scrollView = collectionView.enclosingScrollView {
+                scrollView.contentView.scroll(to: NSPoint(x: 0, y: 0))
+                scrollView.reflectScrolledClipView(scrollView.contentView)
+                DispatchQueue.main.async { [weak self] in
+                    self?.setLoadThumbPriority(ifNeedVisable: true)
+                }
+            }
+            return true
+        case .browserScrollBottom:
+            if let scrollView = collectionView.enclosingScrollView {
+                let newOrigin = NSPoint(x: 0,
+                                         y: collectionView.bounds.height - scrollView.contentSize.height)
+                scrollView.contentView.scroll(to: newOrigin)
+                scrollView.reflectScrolledClipView(scrollView.contentView)
+                DispatchQueue.main.async { [weak self] in
+                    self?.setLoadThumbPriority(ifNeedVisable: true)
+                }
+            }
+            return true
+        case .browserPageUp:
+            if let scrollView = collectionView.enclosingScrollView {
+                let currentOrigin = scrollView.contentView.bounds.origin
+                let pageHeight = scrollView.contentSize.height
+                let newY = max(currentOrigin.y - pageHeight, 0)
+                scrollView.contentView.scroll(to: NSPoint(x: currentOrigin.x, y: newY))
+                scrollView.reflectScrolledClipView(scrollView.contentView)
+                DispatchQueue.main.async { [weak self] in
+                    self?.setLoadThumbPriority(ifNeedVisable: true)
+                }
+            }
+            return true
+        case .browserPageDown:
+            if let scrollView = collectionView.enclosingScrollView {
+                let currentOrigin = scrollView.contentView.bounds.origin
+                let pageHeight = scrollView.contentSize.height
+                let newY = min(currentOrigin.y + pageHeight,
+                                collectionView.bounds.height - pageHeight)
+                scrollView.contentView.scroll(to: NSPoint(x: currentOrigin.x, y: newY))
+                scrollView.reflectScrolledClipView(scrollView.contentView)
+                DispatchQueue.main.async { [weak self] in
+                    self?.setLoadThumbPriority(ifNeedVisable: true)
+                }
+            }
+            return true
+        case .browserDeselect:
+            if publicVar.isCollectionViewFirstResponder {
+                collectionView.deselectAll(nil)
+            }
+            return true
+        case .browserToggleSidebar:
+            NSApp.sendAction(#selector(AppDelegate.toggleSidebar(_:)), to: nil, from: nil)
+            return true
+
+        // MARK: Viewer nav
+        case .viewerPrev:
+            isRTL ? nextLargeImage() : previousLargeImage()
+            return true
+        case .viewerNext:
+            isRTL ? previousLargeImage() : nextLargeImage()
+            return true
+        case .viewerLocateFirst:
+            locateLargeImage(direction: -2)
+            return true
+        case .viewerLocateLast:
+            locateLargeImage(direction: 2)
+            return true
+        case .viewerClose:
+            closeLargeImage(0)
+            return true
+        case .viewerOpenFromSelection:
+            guard let indexPath = collectionView.selectionIndexPaths.min(),
+                  publicVar.isCollectionViewFirstResponder else { return false }
+            openLargeImage(indexPath)
+            return true
+
+        // MARK: Viewer ops
+        case .viewerZoomIn:
+            if largeImageView.file.type == .video {
+                largeImageView.increaseVolume()
+            } else {
+                largeImageView.zoom(direction: +1)
+            }
+            return true
+        case .viewerZoomOut:
+            if largeImageView.file.type == .video {
+                largeImageView.decreaseVolume()
+            } else {
+                largeImageView.zoom(direction: -1)
+            }
+            return true
+        case .viewerZoom100:
+            largeImageView.zoom100()
+            return true
+        case .viewerZoomFit:
+            largeImageView.zoomFit()
+            return true
+        case .viewerZoomReset:
+            changeLargeImage(firstShowThumb: false, resetSize: true, triggeredByLongPress: true)
+            return true
+        case .viewerRotateLeft:
+            largeImageView.actRotateL()
+            return true
+        case .viewerRotateRight:
+            largeImageView.actRotateR()
+            return true
+        case .viewerMirrorH:
+            largeImageView.actMirrorH()
+            return true
+        case .viewerOCR:
+            largeImageView.actOCR()
+            return true
+        case .viewerQRCode:
+            largeImageView.actQRCode()
+            return true
+        case .viewerGetInfo:
+            handleGetInfo()
+            return true
+        case .viewerShowExif:
+            largeImageView.actShowExif()
+            return true
+        case .viewerEditMode:
+            guard EDIT_FEATURE_ENABLED else { return false }
+            largeImageView.enterEditMode { [weak self] editedImage in
+                self?.largeImageView.imageView.image = editedImage
+            }
+            return true
+
+        // MARK: Video
+        case .videoPauseResume:
+            if largeImageView.file.type == .video {
+                largeImageView.pauseOrResumeVideo()
+            } else {
+                closeLargeImage(0)
+            }
+            return true
+        case .videoSeekFwd:
+            // Folded: video → seek; image → next image. Mirrors legacy ← / →
+            // behavior so a default ←/→ chord works as "prev / next" on images.
+            if largeImageView.file.type == .video {
+                largeImageView.seekVideo(direction: isRTL ? -1 : 1)
+            } else {
+                isRTL ? previousLargeImage() : nextLargeImage()
+            }
+            return true
+        case .videoSeekBack:
+            if largeImageView.file.type == .video {
+                largeImageView.seekVideo(direction: isRTL ? 1 : -1)
+            } else {
+                isRTL ? nextLargeImage() : previousLargeImage()
+            }
+            return true
+        case .videoSeekFrameFwd:
+            guard largeImageView.file.type == .video else { return false }
+            largeImageView.seekVideoByFrame(direction: isRTL ? -1 : 1)
+            return true
+        case .videoSeekFrameBack:
+            guard largeImageView.file.type == .video else { return false }
+            largeImageView.seekVideoByFrame(direction: isRTL ? 1 : -1)
+            return true
+        case .videoSetA:
+            guard largeImageView.file.type == .video else { return false }
+            largeImageView.specifyABPlayPositionA()
+            return true
+        case .videoSetB:
+            guard largeImageView.file.type == .video else { return false }
+            largeImageView.specifyABPlayPositionB()
+            return true
+        case .videoABPlay:
+            guard largeImageView.file.type == .video else { return false }
+            largeImageView.actABPlay()
+            return true
+        case .videoSequentialPlay:
+            guard largeImageView.file.type == .video else { return false }
+            largeImageView.actSequentialPlay()
+            return true
+        case .videoRememberPosition:
+            guard largeImageView.file.type == .video else { return false }
+            largeImageView.actRememberPlayPosition()
+            return true
+
+        // MARK: Window
+        case .windowMaximize:
+            guard !isInFullScreen else { return false }
+            adjustWindowMaximize()
+            return true
+        case .windowSuitable:
+            guard !isInFullScreen else { return false }
+            adjustWindowSuitable()
+            return true
+        case .windowImageActual:
+            guard !isInFullScreen else { return false }
+            adjustWindowImageActual()
+            return true
+        case .windowImageCurrent:
+            guard !isInFullScreen else { return false }
+            adjustWindowImageCurrent()
+            return true
+        case .windowCenter:
+            guard !isInFullScreen else { return false }
+            adjustWindowToCenter()
+            return true
+        case .windowToggleFullscreen:
+            view.window?.toggleFullScreen(nil)
+            return true
+        case .windowToggleOnTop:
+            NSApp.sendAction(#selector(AppDelegate.toggleOnTop(_:)), to: nil, from: nil)
+            return true
+        case .windowRefresh:
+            handleUserRefresh()
+            return true
+        case .windowNew:
+            NSApp.sendAction(#selector(AppDelegate.fileNewWindow(_:)), to: nil, from: nil)
+            return true
+        case .windowNewTab:
+            NSApp.sendAction(#selector(AppDelegate.fileNewTab(_:)), to: nil, from: nil)
+            return true
+        case .windowClose, .windowCloseTab:
+            view.window?.performClose(nil)
+            return true
+        case .windowReopenClosedTab:
+            handleReopenClosedTabs()
+            return true
+        case .quitApp:
+            NSApp.terminate(nil)
+            return true
+
+        // MARK: File ops
+        case .fileRename:
+            if publicVar.isOutlineViewFirstResponder {
+                outlineView.actRename(isByKeyboard: true)
+                return true
+            }
+            if publicVar.isCollectionViewFirstResponder {
+                handleRename(urls: publicVar.selectedUrls())
+                return true
+            }
+            return false
+        case .fileDelete:
+            if publicVar.isOutlineViewFirstResponder {
+                outlineView.actDelete(isByKeyboard: true, isShowPrompt: true)
+                return true
+            }
+            if publicVar.isCollectionViewFirstResponder {
+                _ = handleDelete(isShowPrompt: true)
+                return true
+            }
+            return false
+        case .fileDeleteNoPrompt:
+            if publicVar.isOutlineViewFirstResponder {
+                outlineView.actDelete(isByKeyboard: true, isShowPrompt: false)
+                return true
+            }
+            if publicVar.isCollectionViewFirstResponder {
+                _ = handleDelete(isShowPrompt: false)
+                return true
+            }
+            return false
+        case .fileNewFolder:
+            _ = handleNewFolder()
+            return true
+        case .fileCopyToDownload:
+            guard publicVar.isCollectionViewFirstResponder else { return false }
+            handleCopyToDownload()
+            return true
+        case .fileMoveToDownload:
+            guard publicVar.isCollectionViewFirstResponder else { return false }
+            handleMoveToDownload()
+            return true
+        case .fileGetInfo:
+            if publicVar.isOutlineViewFirstResponder {
+                outlineView.actGetInfo(isByKeyboard: true)
+                return true
+            }
+            if publicVar.isCollectionViewFirstResponder {
+                handleGetInfo()
+                return true
+            }
+            return false
+
+        // MARK: Thumb size
+        case .thumbSizeUp:
+            adjustThumbSizeByDirection(direction: +1)
+            return true
+        case .thumbSizeDown:
+            adjustThumbSizeByDirection(direction: -1)
+            return true
+        case .thumbSizeReset:
+            adjustThumbSizeByDirection(direction: 0)
+            return true
+
+        // MARK: View mode
+        case .viewModeJustified:
+            NSApp.sendAction(#selector(AppDelegate.switchToJustifiedView(_:)), to: nil, from: nil)
+            return true
+        case .viewModeWaterfall:
+            NSApp.sendAction(#selector(AppDelegate.switchToWaterfallView(_:)), to: nil, from: nil)
+            return true
+        case .viewModeGrid:
+            NSApp.sendAction(#selector(AppDelegate.switchToGridView(_:)), to: nil, from: nil)
+            return true
+        case .viewModeDetail:
+            NSApp.sendAction(#selector(AppDelegate.switchToDetailView(_:)), to: nil, from: nil)
+            return true
+
+        // MARK: Visibility toggles
+        case .toggleHiddenFiles:
+            NSApp.sendAction(#selector(AppDelegate.toggleIsShowHiddenFile(_:)), to: nil, from: nil)
+            return true
+        case .toggleImageFiles:
+            NSApp.sendAction(#selector(AppDelegate.toggleIsShowImageFile(_:)), to: nil, from: nil)
+            return true
+        case .toggleRawFiles:
+            NSApp.sendAction(#selector(AppDelegate.toggleIsShowRawFile(_:)), to: nil, from: nil)
+            return true
+        case .toggleVideoFiles:
+            NSApp.sendAction(#selector(AppDelegate.toggleIsShowVideoFile(_:)), to: nil, from: nil)
+            return true
+        case .toggleAllFiles:
+            NSApp.sendAction(#selector(AppDelegate.toggleIsShowAllTypeFile(_:)), to: nil, from: nil)
+            return true
+        case .toggleShowFinderTagsAndRating:
+            NSApp.sendAction(#selector(AppDelegate.toggleShowFinderTagsAndRating(_:)), to: nil, from: nil)
+            return true
+        case .toggleRawUseEmbeddedThumb:
+            NSApp.sendAction(#selector(AppDelegate.toggleRawUseEmbeddedThumb(_:)), to: nil, from: nil)
+            return true
+        case .toggleAutoPlayVideo:
+            toggleAutoPlayVisibleVideo()
+            return true
+
+        // MARK: Viewer behavior
+        case .lockRotation:
+            NSApp.sendAction(#selector(AppDelegate.toggleLockRotation(_:)), to: nil, from: nil)
+            return true
+        case .lockZoom:
+            NSApp.sendAction(#selector(AppDelegate.toggleLockZoom(_:)), to: nil, from: nil)
+            return true
+        case .lockMirror:
+            NSApp.sendAction(#selector(AppDelegate.toggleLockMirror(_:)), to: nil, from: nil)
+            return true
+        case .activatePanScroll:
+            NSApp.sendAction(#selector(AppDelegate.toggleActivatePanScroll(_:)), to: nil, from: nil)
+            return true
+
+        // MARK: Rating (only when CollectionView focused — matches legacy gate)
+        case .rating0, .rating1, .rating2, .rating3, .rating4, .rating5:
+            guard publicVar.isCollectionViewFirstResponder,
+                  let rating = action.ratingValue else { return false }
+            handleRating(rating: rating)
+            return true
+
+        // MARK: Finder tags (only when CollectionView focused)
+        case .tag1, .tag2, .tag3, .tag4, .tag5, .tag6, .tag7, .tag8, .tag9:
+            guard publicVar.isCollectionViewFirstResponder,
+                  let index = action.tagIndex,
+                  index < FinderTag.all.count else { return false }
+            handleToggleFinderTag(FinderTag.all[index].name)
+            return true
+
+        // MARK: Profile use / save. scope=browserOnly handles the
+        // !isInLargeView gate; only the slot lookup needs to be unwrapped here.
+        case .profileUse1, .profileUse2, .profileUse3, .profileUse4, .profileUse5,
+             .profileUse6, .profileUse7, .profileUse8, .profileUse9:
+            guard let slot = action.profileSlot else { return false }
+            useCustomProfile(String(slot))
+            return true
+        case .profileSave1, .profileSave2, .profileSave3, .profileSave4, .profileSave5,
+             .profileSave6, .profileSave7, .profileSave8, .profileSave9:
+            guard let slot = action.profileSlot else { return false }
+            setCustomProfileTo(String(slot))
+            return true
+
+        // MARK: Search
+        case .searchToggleOverlay:
+            toggleSearchOverlay()
+            return true
+        case .searchToggleRecursive:
+            toggleRecursiveMode()
+            return true
+        case .searchToggleRecursiveFolder:
+            toggleRecursiveContainFolder()
+            return true
+
+        // MARK: Quick search
+        case .quickSearchActivate:
+            guard !quickSearchState, !globalVar.useQuickSearch else { return false }
+            quickSearch("backspace")
+            return true
+        }
+    }
+}
+
+private extension ShortcutAction {
+    /// 1-based slot for profile use/save actions; nil for any non-profile case.
+    var profileSlot: Int? {
+        switch self {
+        case .profileUse1, .profileSave1: return 1
+        case .profileUse2, .profileSave2: return 2
+        case .profileUse3, .profileSave3: return 3
+        case .profileUse4, .profileSave4: return 4
+        case .profileUse5, .profileSave5: return 5
+        case .profileUse6, .profileSave6: return 6
+        case .profileUse7, .profileSave7: return 7
+        case .profileUse8, .profileSave8: return 8
+        case .profileUse9, .profileSave9: return 9
+        default: return nil
+        }
+    }
+
+    /// 0..5 rating value for rating actions; nil otherwise.
+    var ratingValue: Int? {
+        switch self {
+        case .rating0: return 0
+        case .rating1: return 1
+        case .rating2: return 2
+        case .rating3: return 3
+        case .rating4: return 4
+        case .rating5: return 5
+        default: return nil
+        }
+    }
+
+    /// 0-based index into `FinderTag.all` for tag actions; nil otherwise.
+    var tagIndex: Int? {
+        switch self {
+        case .tag1: return 0
+        case .tag2: return 1
+        case .tag3: return 2
+        case .tag4: return 3
+        case .tag5: return 4
+        case .tag6: return 5
+        case .tag7: return 6
+        case .tag8: return 7
+        case .tag9: return 8
+        default: return nil
+        }
     }
 }

From 760804be5dd56c95845bb3fe885f657befe07a87 Mon Sep 17 00:00:00 2001
From: lenisko <10072920+lenisko@users.noreply.github.com>
Date: Sat, 23 May 2026 02:11:57 +0200
Subject: [PATCH 2/7] docs: add startup perf design spec

Captures launch-from-file optimization plan: instrumentation stage 1,
six fix units stage 2 behind fastStartupEnabled flag.
---
 .../specs/2026-05-23-startup-perf-design.md   | 204 ++++++++++++++++++
 1 file changed, 204 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-05-23-startup-perf-design.md

diff --git a/docs/superpowers/specs/2026-05-23-startup-perf-design.md b/docs/superpowers/specs/2026-05-23-startup-perf-design.md
new file mode 100644
index 00000000..4c5a9579
--- /dev/null
+++ b/docs/superpowers/specs/2026-05-23-startup-perf-design.md
@@ -0,0 +1,204 @@
+# FlowVision Startup Performance — Design
+
+**Date:** 2026-05-23
+**Status:** Approved (pending user spec review)
+**Branch (origin):** `feat-shortcuts`
+
+## 1. Goal & Scope
+
+Make **launch-from-file** (Finder "Open With → FlowVision" on a single image) feel ultra-fast: measurable reduction in time from icon click to large image visible on screen. Cold-start optimization first; warm-start improvements should follow for free.
+
+**Out of scope:** launch-into-folder (only touched if a fix obviously helps both), in-app folder switch, thumbnail generation, video player.
+
+**Success criteria:**
+- Baseline captured (median of 5 cold runs per file type).
+- Post-fix median ≥40% lower on the dominant span (`file.openFromFinder.total`).
+- Stretch: large-image visible within ~300 ms of icon click on a recent Mac.
+
+## 2. Current Pipeline (Observed)
+
+Findings from `AppDelegate.swift`, `ViewController.swift`, `LargeImage.swift`, `FFmpegKit.swift`:
+
+- `applicationWillFinishLaunching` runs ~30 synchronous `UserDefaults.standard.value(forKey:)` reads on main (lines 96–225).
+- `ViewController.viewDidLoad` runs another ~30 synchronous defaults reads (lines 538+) plus full collection/outline/split/drawing-view setup.
+- `Main.storyboard` instantiated synchronously inside `createNewWindow`.
+- `EnhancedIndex.initialize()` already dispatched to `.userInitiated` queue — good.
+- `FFmpegKitWrapper` already lazy via `dlopen` (`LOAD_WHEN_USE=true`) — good.
+- `Settings` window controller already `lazy` — good.
+- `application(openFiles:)` calls `createNewWindow(file)` then `openImageInTargetWindow(file, …)` which calls `OpenLargeImageFromFinder` and dispatches `switchDirByDirection` (folder enumeration for sibling nav) on main async.
+
+Critical-path sequence today (all main thread):
+
+```
+willFinishLaunching ███
+  ├─ ShortcutStore.load
+  ├─ THUMB_SIZES generate
+  ├─ ~30 UserDefaults reads
+  ├─ FinderTag custom labels load
+  ├─ menu delegates hooked, EnhancedIndex.initialize (async — OK)
+
+didFinishLaunching ███
+  └─ createNewWindow() — empty window
+        ├─ storyboard instantiate ███
+        ├─ viewDidLoad ███ (~30 more defaults + view setup)
+
+application(openFiles:) ███
+  ├─ createNewWindow(file) ███ (second window, same heavy storyboard)
+  ├─ OpenLargeImageFromFinder
+  └─ switchDirByDirection (folder enum) ███
+                                            ▼
+                                large image visible
+```
+
+## 3. Target Pipeline
+
+```
+willFinishLaunching ███ (slim)
+  ├─ batched defaults read (one call)
+  ├─ ShortcutStore.load
+  ├─ EnhancedIndex.initialize (already async)
+  │  ┌──────────────────────────────────────────┐
+  │  │ background (qos:.utility)                │
+  │  │  • FinderTag labels                      │
+  │  │  • THUMB_SIZES lazy on first access      │
+  │  │  • menu delegates on demand              │
+  │  │  • FFmpegKit warm dlopen (.background)   │
+  │  └──────────────────────────────────────────┘
+
+didFinishLaunching ███ (slim)
+  └─ if openFiles already queued → fast path
+        ├─ storyboard instantiate (minimal scene)
+        ├─ viewDidLoad_Minimal: largeImageView + window only
+        ├─ background: decode image
+        ├─ main: assign image → window orderFront
+        └─ post-paint async:
+              ├─ folder enum
+              ├─ tree / outline / collection setup
+              ├─ remaining defaults reads
+                                            ▼
+                                sibling navigation ready
+```
+
+Critical-path budget:
+
+| Span | Now (est) | Target |
+|---|---|---|
+| willFinish | 50–100 ms | <20 ms |
+| storyboard + minimal viewDidLoad | 100–200 ms | <60 ms |
+| image decode | varies | unchanged (off-main) |
+| first frame total | sum above | ≤300 ms |
+
+## 4. Stages
+
+### Stage 1 — Instrumentation (lands first, no flag)
+
+Add timing helper using `OSSignposter` (macOS 12+) plus existing `log()`. Span IDs:
+
+- `app.willFinish`, `app.willFinish.defaultsLoad`, `app.didFinish`
+- `window.create`, `window.storyboardInstantiate`
+- `vc.viewDidLoad`, `vc.viewDidLoad.defaultsLoad`
+- `file.openFromFinder.total` (from `application(openFiles:)` entry to large-image first-frame)
+- `file.openLargeImage.decode`
+- `file.switchDir.scan`
+
+Capture baseline: 5 cold runs × {PNG, JPG, HEIC, RAW (CR2/NEF), animated GIF, WEBP, video}. Record medians in `docs/superpowers/specs/2026-05-23-startup-perf-baseline.md`.
+
+### Stage 2 — Fix units (ordered, each behind `fastStartupEnabled`)
+
+1. **Defaults batch read** — replace 60+ `value(forKey:)` calls in `AppDelegate.applicationWillFinishLaunching` and `ViewController.viewDidLoad` with a single batched read into a struct.
+2. **AppDelegate slimming** — move FinderTag labels load, menu hookups, and other non-critical bootstrap off `applicationWillFinishLaunching`. Make `THUMB_SIZES` a static lazy constant.
+3. **viewDidLoad pruning** — move outlineView/collectionView/splitView/drawing-view setup behind `setupDeferredUI()` called from `viewDidAppear`.
+4. **Storyboard split** — pull rarely-needed bits out of `Main.storyboard` so launch-from-file loads a minimal scene.
+5. **Launch-from-file fast path** — restructure `application(openFiles:)`: decode on background queue → show window with image → folder enum + sibling list async after first frame.
+6. **FFmpeg async + linker audit** — `warmLoadAfterDelay`; `DEAD_CODE_STRIPPING = YES` Release; audit `Base.xcconfig` `OTHER_LDFLAGS` for unused `-framework` entries.
+
+Each unit gates on its measured win — revert if <5% of its span.
+
+## 5. Components
+
+### New files
+
+**`Sources/Common/StartupTiming.swift`** (~80 lines)
+- `enum StartupSpan: String` — cases match span IDs above.
+- `func spBegin(_:)` / `spEnd(_:)` using `OSSignposter` + `log()` bridge.
+- `func spMeasure<T>(_:, _: () throws -> T) rethrows -> T` wrapper.
+
+**`Sources/Common/Defaults+Batch.swift`** (~60 lines)
+- `struct AppStartupDefaults` — every defaults key + default value.
+- `static func loadFromUserDefaults() -> AppStartupDefaults` — one `dictionaryRepresentation()` call.
+- `func apply(toGlobalVar:)` — assigns to `globalVar` in one shot on main.
+
+### Modified files
+
+**`Sources/AppDelegate.swift`**
+- Slim `applicationWillFinishLaunching`: `ShortcutStore.shared.load()` + `AppStartupDefaults` apply + schedule background bootstrap.
+- New `createNewWindow_FastPath(file:)` for finder-launch single-image.
+- `THUMB_SIZES` → `ThumbSizes.values` (static lazy).
+- Menu delegates hooked from `applicationDidFinishLaunching`.
+
+**`Sources/ViewController.swift`**
+- `viewDidLoad`: pull config from `globalVar` only, no inline defaults reads.
+- `setupDeferredUI()` called from `viewDidAppear` first-call.
+- Launch-from-file path: minimal `viewDidLoad` (only `largeImageView`, `largeImageBgEffectView`, bounds).
+
+**`Sources/ViewControllerExtension/LargeImage.swift`**
+- `OpenLargeImageFromFinder(path:)`: decode on `.userInitiated` queue → main thread set image + un-hide → post `didShowLargeImageFromLaunch`.
+- Folder enumeration (`switchDirByDirection`) dispatched to `.utility` after that notification.
+
+**`Sources/Common/FFmpegKit.swift`**
+- `warmLoadAfterDelay(seconds:)` — dispatch `loadFFmpegKitIfNeeded` on `.background` queue.
+
+**Build settings (`Base.xcconfig` / Release)**
+- `DEAD_CODE_STRIPPING = YES` (verify not already set).
+- Audit `OTHER_LDFLAGS` for unused `-framework` entries (no removal without verification).
+
+### Feature flag
+
+- `globalVar.fastStartupEnabled` (default `true`, hidden Advanced Settings toggle).
+- All Stage 2 changes branch on it.
+- Removed once stable for one release cycle.
+
+## 6. Error Handling
+
+- Defaults batch read: malformed key falls back to default value (same semantics as today's `if let ... as? Type`). No throws.
+- Background image decode: existing decode error paths preserved; on failure window still shows (current behavior).
+- Background bootstrap tasks (FFmpeg warm, FinderTag labels, deferred UI): each in its own `DispatchWorkItem`; failures logged via `log()`, not surfaced.
+- Fast-path window keeps current `fatalError` on missing `WindowController` identifier — same as today.
+- Feature flag off → entire pre-existing code path runs unchanged.
+
+## 7. Testing
+
+No automated UI tests today; matching that.
+
+Manual matrix per fix unit:
+
+1. Cold launch (`killall FlowVision`, wait 30 s) via Finder "Open With" for PNG, JPG, HEIC, RAW (CR2/NEF), animated GIF, WEBP, video file (internal player on).
+2. Cold launch via app icon (no file).
+3. Warm launch variants of (1).
+4. Multi-tab: open second file with one window already up.
+5. CLI: `open ./img.jpg`, `open .`.
+6. Toggle `fastStartupEnabled` off → confirm old behavior intact.
+7. Sibling navigation (→/←) after fast path.
+8. Settings window opens, no missing IBOutlet crash.
+9. `Instruments → Allocations` 30 s after launch — compare to baseline.
+
+**Acceptance:** `file.openFromFinder.total` median (5 runs) ≥40% lower than baseline per file type. Numbers recorded in `2026-05-23-startup-perf-baseline.md`.
+
+## 8. Rollout
+
+1. Stage 1 (instrumentation) lands first in `main`. No flag.
+2. Capture baseline; commit to spec dir.
+3. Stage 2 units land one per commit/PR, behind `fastStartupEnabled`:
+   1. Defaults batch
+   2. AppDelegate slimming
+   3. viewDidLoad pruning
+   4. Storyboard split (may be deferred — highest risk)
+   5. Launch-from-file fast path
+   6. FFmpeg async + linker audit
+4. Re-measure after each unit. Revert if <5% gain on its span.
+5. After one stable release cycle: delete flag, delete legacy code paths.
+
+## 9. Rollback
+
+- Per-unit: revert one commit.
+- User-facing: hidden Advanced Settings toggle disables fast path without reinstall.

From 06fa7d6861364de95c998a5114c2279bd8ee0367 Mon Sep 17 00:00:00 2001
From: lenisko <10072920+lenisko@users.noreply.github.com>
Date: Sat, 23 May 2026 02:22:17 +0200
Subject: [PATCH 3/7] docs: add startup perf implementation plan

Eight tasks: instrumentation, baseline capture, batched defaults,
AppDelegate slimming, viewDidLoad pruning, optional storyboard split,
launch-from-file fast path, FFmpeg warm + linker audit.
---
 .../plans/2026-05-23-startup-perf.md          | 1203 +++++++++++++++++
 1 file changed, 1203 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-05-23-startup-perf.md

diff --git a/docs/superpowers/plans/2026-05-23-startup-perf.md b/docs/superpowers/plans/2026-05-23-startup-perf.md
new file mode 100644
index 00000000..e107d7b5
--- /dev/null
+++ b/docs/superpowers/plans/2026-05-23-startup-perf.md
@@ -0,0 +1,1203 @@
+# FlowVision Startup Performance Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Reduce time from Finder "Open With → FlowVision" click to large-image visible, instrumented and verified end-to-end.
+
+**Architecture:** Stage 1 lands `os_signpost`-based timing for named startup spans and captures a baseline. Stage 2 applies six independent, ordered fix units (defaults batch read, AppDelegate slimming, viewDidLoad pruning, storyboard split, launch-from-file fast path, framework warm/linker audit) each behind a `globalVar.fastStartupEnabled` flag with per-unit revert gate.
+
+**Tech Stack:** Swift (project deploys macOS 11.0+), AppKit, `os_signpost` (C API, available 10.14+), `OSSignposter` (12+ optional). No new dependencies.
+
+**Spec:** `docs/superpowers/specs/2026-05-23-startup-perf-design.md`
+
+---
+
+## File Structure
+
+### New files
+
+| Path | Responsibility |
+|---|---|
+| `FlowVision/Sources/Common/StartupTiming.swift` | Span IDs enum + `spBegin/spEnd/spMeasure` helpers using `os_signpost` and `log()` |
+| `FlowVision/Sources/Common/StartupDefaults.swift` | `AppStartupDefaults` struct batched-read from `UserDefaults.dictionaryRepresentation()`, applies to `globalVar` |
+| `FlowVision/Sources/Common/StartupBootstrap.swift` | Off-main bootstrap: FinderTag labels, FFmpeg warm |
+| `docs/superpowers/specs/2026-05-23-startup-perf-baseline.md` | Captured median timings before/after each fix unit |
+
+### Modified files
+
+| Path | Why |
+|---|---|
+| `FlowVision/Sources/AppDelegate.swift` | Wrap launch hooks in spans (T1); slim `applicationWillFinishLaunching` (T2, T3); fast path `createNewWindow_FastPath` (T7) |
+| `FlowVision/Sources/ViewController.swift` | Wrap `viewDidLoad` in span (T1); pull defaults from `globalVar` (T2); split deferred UI into `setupDeferredUI()` (T5) |
+| `FlowVision/Sources/ViewControllerExtension/LargeImage.swift` | Background decode on Finder open (T7) |
+| `FlowVision/Sources/Common/GlobalVariable.swift` | Add `fastStartupEnabled` flag (T2 prep); `THUMB_SIZES` lazy (T3) |
+| `FlowVision/Sources/Common/FFmpegKit.swift` | Add `warmLoadAfterDelay(seconds:)` (T8) |
+| `FlowVision/Sources/Common/FinderTag.swift` | Allow `EnhancedIndex` and custom-labels load to be invoked off-main from `StartupBootstrap` (T3) |
+| `FlowVision/FlowVision.xcodeproj/project.pbxproj` | Add new Swift files to target (every new file task) |
+| `FlowVision/Base.xcconfig` (or project Release config) | `DEAD_CODE_STRIPPING = YES` (T8) |
+
+---
+
+## Task 1 — Add startup timing instrumentation
+
+**Files:**
+- Create: `FlowVision/Sources/Common/StartupTiming.swift`
+- Modify: `FlowVision/Sources/AppDelegate.swift` (lines 64, 250, 254, 276, 343–415)
+- Modify: `FlowVision/Sources/ViewController.swift` (lines 444, 853, 956)
+- Modify: `FlowVision/Sources/ViewControllerExtension/LargeImage.swift` (line 469)
+- Modify: `FlowVision/Sources/ViewControllerExtension/FileSystem.swift` (line 1031)
+- Modify: `FlowVision/FlowVision.xcodeproj/project.pbxproj` (add new file to target)
+
+### - [ ] Step 1.1: Create `StartupTiming.swift`
+
+```swift
+//
+//  StartupTiming.swift
+//  FlowVision
+//
+
+import Foundation
+import os.log
+import os.signpost
+
+enum StartupSpan: String {
+    case appWillFinish              = "app.willFinish"
+    case appWillFinishDefaultsLoad  = "app.willFinish.defaultsLoad"
+    case appDidFinish               = "app.didFinish"
+    case windowCreate               = "window.create"
+    case windowStoryboardInstantiate = "window.storyboardInstantiate"
+    case vcViewDidLoad              = "vc.viewDidLoad"
+    case vcViewDidLoadDefaultsLoad  = "vc.viewDidLoad.defaultsLoad"
+    case fileOpenFromFinderTotal    = "file.openFromFinder.total"
+    case fileOpenLargeImageDecode   = "file.openLargeImage.decode"
+    case fileSwitchDirScan          = "file.switchDir.scan"
+}
+
+private let startupLog = OSLog(subsystem: "app.flowvision.startup", category: .pointsOfInterest)
+
+private struct SpanState {
+    var startAbs: CFAbsoluteTime
+    var signpostID: OSSignpostID
+}
+
+private var activeSpans: [String: SpanState] = [:]
+private let spanLock = NSLock()
+
+@inline(__always)
+func spBegin(_ span: StartupSpan) {
+    let id = OSSignpostID(log: startupLog)
+    spanLock.lock()
+    activeSpans[span.rawValue] = SpanState(startAbs: CFAbsoluteTimeGetCurrent(), signpostID: id)
+    spanLock.unlock()
+    os_signpost(.begin, log: startupLog, name: "Span", signpostID: id, "%{public}s", span.rawValue)
+    log("[startup] begin \(span.rawValue)")
+}
+
+@inline(__always)
+func spEnd(_ span: StartupSpan) {
+    spanLock.lock()
+    let state = activeSpans.removeValue(forKey: span.rawValue)
+    spanLock.unlock()
+    guard let state = state else {
+        log("[startup] WARN spEnd without begin: \(span.rawValue)", level: .warn)
+        return
+    }
+    let elapsedMs = (CFAbsoluteTimeGetCurrent() - state.startAbs) * 1000.0
+    os_signpost(.end, log: startupLog, name: "Span", signpostID: state.signpostID, "%{public}s", span.rawValue)
+    log(String(format: "[startup] end   %@  %.2f ms", span.rawValue, elapsedMs))
+}
+
+@inline(__always)
+func spMeasure<T>(_ span: StartupSpan, _ body: () throws -> T) rethrows -> T {
+    spBegin(span)
+    defer { spEnd(span) }
+    return try body()
+}
+```
+
+### - [ ] Step 1.2: Add file to Xcode target
+
+Open `FlowVision.xcodeproj` in Xcode → drag `StartupTiming.swift` from `Sources/Common/` into the FlowVision target. Verify Target Membership checkbox is checked.
+
+Alternative CLI: use `xcodeproj` Ruby gem or edit `project.pbxproj` by mirroring an existing file's `PBXFileReference` + `PBXBuildFile` + `PBXSourcesBuildPhase` entries. Verify build succeeds: `xcodebuild -project FlowVision.xcodeproj -scheme FlowVision build`.
+
+### - [ ] Step 1.3: Wrap `applicationWillFinishLaunching`
+
+Modify `FlowVision/Sources/AppDelegate.swift` line 64–252.
+
+Replace the opening line (currently `log("Start applicationWillFinishLaunching")`) with `spBegin(.appWillFinish)`. Replace the closing `log("End applicationWillFinishLaunching")` with `spEnd(.appWillFinish)`.
+
+Wrap the defaults-loading block (lines 96–225, starting at `let defaults = UserDefaults.standard` through the last `if let collectionViewItemShowTooltip ...`) by inserting `spBegin(.appWillFinishDefaultsLoad)` just before line 96 and `spEnd(.appWillFinishDefaultsLoad)` just after line 225.
+
+### - [ ] Step 1.4: Wrap `applicationDidFinishLaunching`
+
+Modify `FlowVision/Sources/AppDelegate.swift` line 254–278.
+
+Replace `log("Start applicationDidFinishLaunching")` with `spBegin(.appDidFinish)`. Replace `log("End applicationDidFinishLaunching")` with `spEnd(.appDidFinish)`.
+
+### - [ ] Step 1.5: Wrap `createNewWindow`
+
+Modify `FlowVision/Sources/AppDelegate.swift` line 343–416.
+
+Replace `log("Start createNewWindow")` (line 344) with `spBegin(.windowCreate)`. Add `defer { spEnd(.windowCreate) }` immediately after.
+
+Wrap the storyboard instantiation:
+
+```swift
+let windowController = spMeasure(.windowStoryboardInstantiate) { () -> WindowController in
+    let storyboard = NSStoryboard(name: "Main", bundle: nil)
+    guard let wc = storyboard.instantiateController(withIdentifier: "WindowController") as? WindowController else {
+        fatalError("Cannot find WindowController in Main.storyboard")
+    }
+    return wc
+}
+```
+
+(Replace existing lines 381–387 which currently do this in two statements.)
+
+### - [ ] Step 1.6: Wrap `viewDidLoad`
+
+Modify `FlowVision/Sources/ViewController.swift` line 444–856.
+
+Replace `log("Start viewDidLoad")` (line 447) with `spBegin(.vcViewDidLoad)`. Replace `log("End viewDidLoad")` (line 853) with `spEnd(.vcViewDidLoad)`.
+
+Wrap the defaults block (lines 538–597, starting at `if let isLargeImageFitWindow ...` through the `publicVar.profile = CustomProfile.loadFromUserDefaults(...)` line): insert `spBegin(.vcViewDidLoadDefaultsLoad)` before line 538 and `spEnd(.vcViewDidLoadDefaultsLoad)` after line 597.
+
+### - [ ] Step 1.7: Add `fileOpenFromFinderTotal` span
+
+Modify `FlowVision/Sources/AppDelegate.swift` `application(_:openFiles:)` (line 424).
+
+Just after line 425 (`NSApplication.shared.reply(toOpenOrPrint: .success)`), add:
+
+```swift
+spBegin(.fileOpenFromFinderTotal)
+```
+
+Then in `FlowVision/Sources/ViewControllerExtension/LargeImage.swift` `OpenLargeImageFromFinder(path:)` line 469, immediately after the function body's final statement (after line 487), add:
+
+```swift
+// Mark Finder-launch first frame
+DispatchQueue.main.async {
+    spEnd(.fileOpenFromFinderTotal)
+}
+```
+
+The `main.async` defers `spEnd` until after AppKit commits the frame so we capture the user-visible moment, not the function-return moment.
+
+### - [ ] Step 1.8: Wrap `OpenLargeImageFromFinder` decode
+
+Modify `FlowVision/Sources/ViewControllerExtension/LargeImage.swift` line 469–488.
+
+Wrap the body in:
+
+```swift
+func OpenLargeImageFromFinder(path: String){
+    spBegin(.fileOpenLargeImageDecode)
+    defer { spEnd(.fileOpenLargeImageDecode) }
+    // ... existing body unchanged ...
+}
+```
+
+### - [ ] Step 1.9: Wrap `switchDirByDirection`
+
+Modify `FlowVision/Sources/ViewControllerExtension/FileSystem.swift` line 1031.
+
+Add at function start:
+
+```swift
+spBegin(.fileSwitchDirScan)
+defer { spEnd(.fileSwitchDirScan) }
+```
+
+### - [ ] Step 1.10: Build
+
+Run: `xcodebuild -project FlowVision.xcodeproj -scheme FlowVision -configuration Debug build CODE_SIGN_IDENTITY="" CODE_SIGNING_REQUIRED=NO`
+
+Expected: BUILD SUCCEEDED. If errors, fix and re-build.
+
+### - [ ] Step 1.11: Verify spans log
+
+Launch the built `.app` by opening a PNG with it from Finder. Check `~/Library/Logs/FlowVision/` (or wherever `log()` writes; check `Log.swift`). Confirm lines like `[startup] begin app.willFinish` and `[startup] end app.willFinish 32.10 ms` appear.
+
+### - [ ] Step 1.12: Commit
+
+```bash
+git add FlowVision/Sources/Common/StartupTiming.swift \
+        FlowVision/Sources/AppDelegate.swift \
+        FlowVision/Sources/ViewController.swift \
+        FlowVision/Sources/ViewControllerExtension/LargeImage.swift \
+        FlowVision/Sources/ViewControllerExtension/FileSystem.swift \
+        FlowVision/FlowVision.xcodeproj/project.pbxproj
+git commit -m "feat: instrument startup spans for perf measurement"
+```
+
+---
+
+## Task 2 — Capture baseline + add fastStartupEnabled flag
+
+**Files:**
+- Modify: `FlowVision/Sources/Common/GlobalVariable.swift` (line 107 area)
+- Modify: `FlowVision/Sources/AppDelegate.swift` (lines 220-225 area, defaults block)
+- Create: `docs/superpowers/specs/2026-05-23-startup-perf-baseline.md`
+
+### - [ ] Step 2.1: Add `fastStartupEnabled` to `GlobalVar`
+
+Modify `FlowVision/Sources/Common/GlobalVariable.swift` after line 107 (after `collectionViewItemShowTooltip`):
+
+```swift
+var fastStartupEnabled = true
+```
+
+### - [ ] Step 2.2: Wire default into AppDelegate
+
+Modify `FlowVision/Sources/AppDelegate.swift` inside the defaults block (after line 224, the `collectionViewItemShowTooltip` block):
+
+```swift
+if let fastStartupEnabled = UserDefaults.standard.value(forKey: "fastStartupEnabled") as? Bool {
+    globalVar.fastStartupEnabled = fastStartupEnabled
+}
+```
+
+### - [ ] Step 2.3: Capture baseline
+
+Build Release: `xcodebuild -project FlowVision.xcodeproj -scheme FlowVision -configuration Release build CODE_SIGN_IDENTITY="" CODE_SIGNING_REQUIRED=NO`
+
+For each file type in {PNG, JPG, HEIC, RAW CR2, RAW NEF, animated GIF, WEBP, MP4 video}:
+1. `killall FlowVision; sleep 30`
+2. `open -a <built-app-path> <sample-file>` 5 times
+3. Record `file.openFromFinder.total` median from log lines.
+
+Also capture: `app.willFinish`, `app.willFinish.defaultsLoad`, `app.didFinish`, `window.create`, `window.storyboardInstantiate`, `vc.viewDidLoad`, `vc.viewDidLoad.defaultsLoad`, `file.openLargeImage.decode`, `file.switchDir.scan` medians (use PNG run for these — they're not file-type-dependent).
+
+### - [ ] Step 2.4: Write baseline doc
+
+Create `docs/superpowers/specs/2026-05-23-startup-perf-baseline.md` with a table:
+
+```markdown
+# Startup Perf Baseline (2026-05-23)
+
+Hardware: <model, CPU, RAM>
+macOS: <version>
+Build: Release, commit <sha>
+
+## file.openFromFinder.total (ms, median of 5 cold runs)
+
+| Type | Median |
+|---|---|
+| PNG  | … |
+| JPG  | … |
+| HEIC | … |
+| CR2  | … |
+| NEF  | … |
+| GIF  | … |
+| WEBP | … |
+| MP4  | … |
+
+## Per-span medians (PNG cold launch)
+
+| Span | Median (ms) |
+|---|---|
+| app.willFinish | … |
+| app.willFinish.defaultsLoad | … |
+| app.didFinish | … |
+| window.create | … |
+| window.storyboardInstantiate | … |
+| vc.viewDidLoad | … |
+| vc.viewDidLoad.defaultsLoad | … |
+| file.openLargeImage.decode | … |
+| file.switchDir.scan | … |
+```
+
+Fill in actual numbers from Step 2.3.
+
+### - [ ] Step 2.5: Commit
+
+```bash
+git add FlowVision/Sources/Common/GlobalVariable.swift \
+        FlowVision/Sources/AppDelegate.swift \
+        docs/superpowers/specs/2026-05-23-startup-perf-baseline.md
+git commit -m "feat: add fastStartupEnabled flag; record baseline"
+```
+
+---
+
+## Task 3 — Fix unit 1: batched defaults read
+
+Replaces 60+ individual `value(forKey:)` calls with a single `dictionaryRepresentation()` fetch.
+
+**Files:**
+- Create: `FlowVision/Sources/Common/StartupDefaults.swift`
+- Modify: `FlowVision/Sources/AppDelegate.swift` (lines 96–225)
+- Modify: `FlowVision/Sources/ViewController.swift` (lines 538–597)
+- Modify: `FlowVision.xcodeproj/project.pbxproj`
+
+### - [ ] Step 3.1: Create `StartupDefaults.swift`
+
+```swift
+//
+//  StartupDefaults.swift
+//  FlowVision
+//
+
+import Foundation
+
+struct AppStartupDefaults {
+    // GlobalVar keys (loaded in applicationWillFinishLaunching)
+    var appearance: String?
+    var openLastFolder: Bool?
+    var homeFolder: String?
+    var hasNormalExit: Bool?
+    var isFirstTimeUse: Bool?
+    var terminateAfterLastWindowClosed: Bool?
+    var autoHideToolbar: Bool?
+    var autoHideCursorWhenFullscreen: Bool?
+    var randomFolderThumb: Bool?
+    var thumbnailOfFolderUseStacking: Bool?
+    var loopBrowsing: Bool?
+    var blackBgInFullScreen: Bool?
+    var blackBgAlways: Bool?
+    var blackBgInFullScreenForVideo: Bool?
+    var blackBgAlwaysForVideo: Bool?
+    var thumbnailExcludeList: [String]?
+    var usePinyinSearch: Bool?
+    var usePinyinInitialSearch: Bool?
+    var memUseLimit: Int?
+    var thumbThreadNum: Int?
+    var folderSearchDepth: Int?
+    var thumbThreadNum_External: Int?
+    var folderSearchDepth_External: Int?
+    var doNotUseFFmpeg: Bool?
+    var videoPlayRememberPosition: Bool?
+    var videoPlaySequentialPlay: Bool?
+    var videoVolume: Float?
+    var videoPlaybackRate: Float?
+    var useInternalPlayer: Bool?
+    var isEnterKeyToOpen: Bool?
+    var clickEdgeToSwitchImage: Bool?
+    var scrollMouseWheelToZoom: Bool?
+    var scrollSensitivity: Double?
+    var keepFilterStateWhenSwitchFolder: Bool?
+    var dirTreeAutoExpand: Bool?
+    var largeImageViewShowTagsAndRating: Bool?
+    var enhancedIndexEnabled: Bool?
+    var collectionViewItemShowTooltip: Bool?
+    var fastStartupEnabled: Bool?
+    var myFavoritesArray: [String]?
+    var customTagLabels: [[String: Any]]?
+
+    // publicVar keys (loaded in ViewController.viewDidLoad)
+    var isLargeImageFitWindow: Bool?
+    var isShowHiddenFile: Bool?
+    var isShowImageFile: Bool?
+    var isShowRawFile: Bool?
+    var isShowAllTypeFile: Bool?
+    var isShowVideoFile: Bool?
+    var isGenHdThumb: Bool?
+    var isPreferInternalThumb: Bool?
+    var isEnableHDR: Bool?
+    var isRawUseEmbeddedThumb: Bool?
+    var isRecursiveContainFolder: Bool?
+    var autoPlayVisibleVideo: Bool?
+    var autoPlaySelectedVideo: Bool?
+    var isRotationLocked: Bool?
+    var isZoomLocked: Bool?
+    var isMirrorLocked: Bool?
+    var isPanWhenZoomed: Bool?
+    var currentTag: String?
+
+    static func load() -> AppStartupDefaults {
+        let dict = UserDefaults.standard.dictionaryRepresentation()
+        var d = AppStartupDefaults()
+        d.appearance                       = dict["appearance"]                        as? String
+        d.openLastFolder                   = dict["openLastFolder"]                    as? Bool
+        d.homeFolder                       = dict["homeFolder"]                        as? String
+        d.hasNormalExit                    = dict["hasNormalExit"]                     as? Bool
+        d.isFirstTimeUse                   = dict["isFirstTimeUse"]                    as? Bool
+        d.terminateAfterLastWindowClosed   = dict["terminateAfterLastWindowClosed"]    as? Bool
+        d.autoHideToolbar                  = dict["autoHideToolbar"]                   as? Bool
+        d.autoHideCursorWhenFullscreen     = dict["autoHideCursorWhenFullscreen"]      as? Bool
+        d.randomFolderThumb                = dict["randomFolderThumb"]                 as? Bool
+        d.thumbnailOfFolderUseStacking     = dict["thumbnailOfFolderUseStacking"]      as? Bool
+        d.loopBrowsing                     = dict["loopBrowsing"]                      as? Bool
+        d.blackBgInFullScreen              = dict["blackBgInFullScreen"]               as? Bool
+        d.blackBgAlways                    = dict["blackBgAlways"]                     as? Bool
+        d.blackBgInFullScreenForVideo      = dict["blackBgInFullScreenForVideo"]       as? Bool
+        d.blackBgAlwaysForVideo            = dict["blackBgAlwaysForVideo"]             as? Bool
+        d.thumbnailExcludeList             = dict["thumbnailExcludeList"]              as? [String]
+        d.usePinyinSearch                  = dict["usePinyinSearch"]                   as? Bool
+        d.usePinyinInitialSearch           = dict["usePinyinInitialSearch"]            as? Bool
+        d.memUseLimit                      = dict["memUseLimit"]                       as? Int
+        d.thumbThreadNum                   = dict["thumbThreadNum"]                    as? Int
+        d.folderSearchDepth                = dict["folderSearchDepth"]                 as? Int
+        d.thumbThreadNum_External          = dict["thumbThreadNum_External"]           as? Int
+        d.folderSearchDepth_External       = dict["folderSearchDepth_External"]        as? Int
+        d.doNotUseFFmpeg                   = dict["doNotUseFFmpeg"]                    as? Bool
+        d.videoPlayRememberPosition        = dict["videoPlayRememberPosition"]         as? Bool
+        d.videoPlaySequentialPlay          = dict["videoPlaySequentialPlay"]           as? Bool
+        d.videoVolume                      = dict["videoVolume"]                       as? Float
+        d.videoPlaybackRate                = dict["videoPlaybackRate"]                 as? Float
+        d.useInternalPlayer                = dict["useInternalPlayer"]                 as? Bool
+        d.isEnterKeyToOpen                 = dict["isEnterKeyToOpen"]                  as? Bool
+        d.clickEdgeToSwitchImage           = dict["clickEdgeToSwitchImage"]            as? Bool
+        d.scrollMouseWheelToZoom           = dict["scrollMouseWheelToZoom"]            as? Bool
+        d.scrollSensitivity                = dict["scrollSensitivity"]                 as? Double
+        d.keepFilterStateWhenSwitchFolder  = dict["keepFilterStateWhenSwitchFolder"]   as? Bool
+        d.dirTreeAutoExpand                = dict["dirTreeAutoExpand"]                 as? Bool
+        d.largeImageViewShowTagsAndRating  = dict["largeImageViewShowTagsAndRating"]   as? Bool
+        d.enhancedIndexEnabled             = dict["enhancedIndexEnabled"]              as? Bool
+        d.collectionViewItemShowTooltip    = dict["collectionViewItemShowTooltip"]     as? Bool
+        d.fastStartupEnabled               = dict["fastStartupEnabled"]                as? Bool
+        d.myFavoritesArray                 = dict["globalVar.myFavoritesArray"]        as? [String]
+        d.customTagLabels                  = dict[CustomTagView.userDefaultsKey]       as? [[String: Any]]
+        d.isLargeImageFitWindow            = dict["isLargeImageFitWindow"]             as? Bool
+        d.isShowHiddenFile                 = dict["isShowHiddenFile"]                  as? Bool
+        d.isShowImageFile                  = dict["isShowImageFile"]                   as? Bool
+        d.isShowRawFile                    = dict["isShowRawFile"]                     as? Bool
+        d.isShowAllTypeFile                = dict["isShowAllTypeFile"]                 as? Bool
+        d.isShowVideoFile                  = dict["isShowVideoFile"]                   as? Bool
+        d.isGenHdThumb                     = dict["isGenHdThumb"]                      as? Bool
+        d.isPreferInternalThumb            = dict["isPreferInternalThumb"]             as? Bool
+        d.isEnableHDR                      = dict["isEnableHDR"]                       as? Bool
+        d.isRawUseEmbeddedThumb            = dict["isRawUseEmbeddedThumb"]             as? Bool
+        d.isRecursiveContainFolder         = dict["isRecursiveContainFolder"]          as? Bool
+        d.autoPlayVisibleVideo             = dict["autoPlayVisibleVideo"]              as? Bool
+        d.autoPlaySelectedVideo            = dict["autoPlaySelectedVideo"]             as? Bool
+        d.isRotationLocked                 = dict["isRotationLocked"]                  as? Bool
+        d.isZoomLocked                     = dict["isZoomLocked"]                      as? Bool
+        d.isMirrorLocked                   = dict["isMirrorLocked"]                    as? Bool
+        d.isPanWhenZoomed                  = dict["isPanWhenZoomed"]                   as? Bool
+        d.currentTag                       = dict["currentTag"]                        as? String
+        return d
+    }
+
+    func applyToGlobalVar() {
+        if let v = openLastFolder                  { globalVar.openLastFolder = v }
+        if let v = homeFolder                      { globalVar.homeFolder = v }
+        if let v = isFirstTimeUse                  { globalVar.isFirstTimeUse = v }
+        if let v = terminateAfterLastWindowClosed  { globalVar.terminateAfterLastWindowClosed = v }
+        if let v = autoHideToolbar                 { globalVar.autoHideToolbar = v }
+        if let v = autoHideCursorWhenFullscreen    { globalVar.autoHideCursorWhenFullscreen = v }
+        if let v = randomFolderThumb               { globalVar.randomFolderThumb = v }
+        if let v = thumbnailOfFolderUseStacking    { globalVar.thumbnailOfFolderUseStacking = v }
+        if let v = loopBrowsing                    { globalVar.loopBrowsing = v }
+        if let v = blackBgInFullScreen             { globalVar.blackBgInFullScreen = v }
+        if let v = blackBgAlways                   { globalVar.blackBgAlways = v }
+        if let v = blackBgInFullScreenForVideo     { globalVar.blackBgInFullScreenForVideo = v }
+        if let v = blackBgAlwaysForVideo           { globalVar.blackBgAlwaysForVideo = v }
+        if let v = thumbnailExcludeList            { globalVar.thumbnailExcludeList = v }
+        if let v = usePinyinSearch                 { globalVar.usePinyinSearch = v }
+        if let v = usePinyinInitialSearch          { globalVar.usePinyinInitialSearch = v }
+        if let v = memUseLimit                     { globalVar.memUseLimit = v }
+        if let v = thumbThreadNum                  { globalVar.thumbThreadNum = v }
+        if let v = folderSearchDepth               { globalVar.folderSearchDepth = v }
+        if let v = thumbThreadNum_External         { globalVar.thumbThreadNum_External = v }
+        if let v = folderSearchDepth_External      { globalVar.folderSearchDepth_External = v }
+        if let v = doNotUseFFmpeg                  { globalVar.doNotUseFFmpeg = v }
+        if let v = videoPlayRememberPosition       { globalVar.videoPlayRememberPosition = v }
+        if let v = videoPlaySequentialPlay         { globalVar.videoPlaySequentialPlay = v }
+        if let v = videoVolume                     { globalVar.videoVolume = v }
+        if let v = videoPlaybackRate               { globalVar.videoPlaybackRate = v }
+        if let v = useInternalPlayer              { globalVar.useInternalPlayer = v }
+        if let v = isEnterKeyToOpen                { globalVar.isEnterKeyToOpen = v }
+        if let v = clickEdgeToSwitchImage          { globalVar.clickEdgeToSwitchImage = v }
+        if let v = scrollMouseWheelToZoom          { globalVar.scrollMouseWheelToZoom = v }
+        if let v = scrollSensitivity               { globalVar.scrollSensitivity = v }
+        if let v = keepFilterStateWhenSwitchFolder { globalVar.keepFilterStateWhenSwitchFolder = v }
+        if let v = dirTreeAutoExpand               { globalVar.dirTreeAutoExpand = v }
+        if let v = largeImageViewShowTagsAndRating { globalVar.largeImageViewShowTagsAndRating = v }
+        if let v = enhancedIndexEnabled            { globalVar.enhancedIndexEnabled = v }
+        if let v = collectionViewItemShowTooltip   { globalVar.collectionViewItemShowTooltip = v }
+        if let v = fastStartupEnabled              { globalVar.fastStartupEnabled = v }
+        globalVar.myFavoritesArray = myFavoritesArray ?? [String]()
+    }
+
+    func applyToPublicVar(_ publicVar: PublicVar) {
+        if let v = isLargeImageFitWindow    { publicVar.isLargeImageFitWindow = v }
+        if let v = isShowHiddenFile         { publicVar.isShowHiddenFile = v }
+        if let v = isShowImageFile          { publicVar.isShowImageFile = v }
+        if let v = isShowRawFile            { publicVar.isShowRawFile = v }
+        if let v = isShowAllTypeFile        { publicVar.isShowAllTypeFile = v }
+        if let v = isShowVideoFile          { publicVar.isShowVideoFile = v }
+        if let v = isGenHdThumb             { publicVar.isGenHdThumb = v }
+        if let v = isPreferInternalThumb    { publicVar.isPreferInternalThumb = v }
+        if let v = isEnableHDR              { publicVar.isEnableHDR = v }
+        if let v = isRawUseEmbeddedThumb    { publicVar.isRawUseEmbeddedThumb = v }
+        if let v = isRecursiveContainFolder { publicVar.isRecursiveContainFolder = v }
+        if let v = autoPlayVisibleVideo     { publicVar.autoPlayVisibleVideo = v }
+        if let v = autoPlaySelectedVideo    { publicVar.autoPlaySelectedVideo = v }
+        if let v = isRotationLocked         { publicVar.isRotationLocked = v }
+        if let v = isZoomLocked             { publicVar.isZoomLocked = v }
+        if let v = isMirrorLocked           { publicVar.isMirrorLocked = v }
+        if let v = isPanWhenZoomed          { publicVar.isPanWhenZoomed = v }
+        if let v = currentTag               { publicVar.currentTag = v }
+    }
+}
+
+// Singleton cache so ViewController can reuse data already pulled by AppDelegate.
+final class StartupDefaultsCache {
+    static let shared = StartupDefaultsCache()
+    private(set) var loaded: AppStartupDefaults?
+    private let lock = NSLock()
+
+    func loadIfNeeded() -> AppStartupDefaults {
+        lock.lock()
+        defer { lock.unlock() }
+        if let l = loaded { return l }
+        let d = AppStartupDefaults.load()
+        loaded = d
+        return d
+    }
+}
+```
+
+Note: `PublicVar` type name must match the actual nested type used inside `ViewController` (verify by grep before editing — adjust the parameter type if it's named differently).
+
+### - [ ] Step 3.2: Verify `PublicVar` type name
+
+Run: `grep -n "class PublicVar\|class publicVar\|var publicVar:" FlowVision/Sources/ViewController.swift | head -5`
+
+If actual name differs, adjust `StartupDefaults.swift` `applyToPublicVar(_:)` parameter type accordingly. Re-run grep before continuing.
+
+### - [ ] Step 3.3: Add `StartupDefaults.swift` to Xcode target
+
+Drag file into FlowVision target (or edit `project.pbxproj`). Build: `xcodebuild -project FlowVision.xcodeproj -scheme FlowVision build`. Expect: BUILD SUCCEEDED.
+
+### - [ ] Step 3.4: Replace defaults block in `applicationWillFinishLaunching`
+
+Modify `FlowVision/Sources/AppDelegate.swift`. Inside the block currently spanned by `spBegin(.appWillFinishDefaultsLoad)` / `spEnd(.appWillFinishDefaultsLoad)`:
+
+Replace the entire region from `let defaults = UserDefaults.standard` (line 96) through the closing `}` of the last `if let collectionViewItemShowTooltip ...` (line 225) — plus the existing `globalVar.fastStartupEnabled` block added in Task 2 — with:
+
+```swift
+if globalVar.fastStartupEnabled {
+    let d = StartupDefaultsCache.shared.loadIfNeeded()
+
+    if d.appearance == "darkAqua" {
+        NSApp.appearance = NSAppearance(named: .darkAqua)
+    } else if d.appearance == "aqua" {
+        NSApp.appearance = NSAppearance(named: .aqua)
+    } else {
+        NSApp.appearance = nil
+    }
+
+    if let hasNormalExit = d.hasNormalExit, !hasNormalExit {
+        UserDefaults.standard.set("file:///", forKey: "lastFolder")
+        globalVar.homeFolder = "file:///"
+    }
+    UserDefaults.standard.set(false, forKey: "hasNormalExit")
+
+    d.applyToGlobalVar()
+
+    if let savedLabels = d.customTagLabels {
+        FinderTag.customLabels = savedLabels.compactMap { dict in
+            guard let name = dict["name"] as? String else { return nil }
+            return (name, dict["colorIndex"] as? Int)
+        }
+    } else {
+        FinderTag.customLabels = FinderTag.systemColorLabels.map { ($0.name, $0.colorIndex) }
+    }
+} else {
+    // legacy path — keep original lines 96–235 unchanged here for rollback
+    // (copy original block back inside this else for safety)
+}
+```
+
+For the `else` branch, paste the original lines 96–235 verbatim (the legacy individual `value(forKey:)` reads + `FinderTag` block) so toggling the flag fully restores old behavior. This is the only place we keep duplication; it's removed in cleanup after one stable release per spec §8.
+
+### - [ ] Step 3.5: Replace defaults block in `ViewController.viewDidLoad`
+
+Modify `FlowVision/Sources/ViewController.swift`. Inside the block spanned by `spBegin(.vcViewDidLoadDefaultsLoad)` / `spEnd(.vcViewDidLoadDefaultsLoad)`:
+
+Replace lines 538–591 (every `if let ... = UserDefaults.standard.value(forKey:) ...` block, up to but not including the `if #available(macOS 14.0, *)` block at line 592) with:
+
+```swift
+if globalVar.fastStartupEnabled {
+    let d = StartupDefaultsCache.shared.loadIfNeeded()
+    d.applyToPublicVar(publicVar)
+} else {
+    // legacy path — original lines 538–591 verbatim
+}
+```
+
+Paste the original 60-ish lines into the `else` block for rollback safety.
+
+### - [ ] Step 3.6: Build
+
+`xcodebuild -project FlowVision.xcodeproj -scheme FlowVision build`. Expect BUILD SUCCEEDED.
+
+### - [ ] Step 3.7: Manual test
+
+1. Launch from PNG via Finder. Confirm window opens, large image shows.
+2. Open Settings → confirm previously-set preferences (theme, hidden files toggle, video volume) preserved.
+3. Toggle in `~/Library/Preferences/<bundle-id>.plist`: `defaults write app.flowvision fastStartupEnabled -bool NO`, relaunch — verify legacy path works (defaults still applied).
+4. Reset: `defaults write app.flowvision fastStartupEnabled -bool YES`.
+
+### - [ ] Step 3.8: Re-measure & gate-check
+
+Repeat baseline capture (Step 2.3) for `app.willFinish.defaultsLoad` + `vc.viewDidLoad.defaultsLoad` + `file.openFromFinder.total`. Append numbers to `2026-05-23-startup-perf-baseline.md` under heading `## After T3: batched defaults read`.
+
+If `app.willFinish.defaultsLoad` + `vc.viewDidLoad.defaultsLoad` combined improvement is <5% of its baseline, revert (`git revert HEAD`) and skip remaining fix units that depend on the cache (none do — others are independent).
+
+### - [ ] Step 3.9: Commit
+
+```bash
+git add FlowVision/Sources/Common/StartupDefaults.swift \
+        FlowVision/Sources/AppDelegate.swift \
+        FlowVision/Sources/ViewController.swift \
+        FlowVision/FlowVision.xcodeproj/project.pbxproj \
+        docs/superpowers/specs/2026-05-23-startup-perf-baseline.md
+git commit -m "perf: batch UserDefaults reads at startup"
+```
+
+---
+
+## Task 4 — Fix unit 2: AppDelegate slimming + lazy THUMB_SIZES
+
+Move FinderTag labels load, `THUMB_SIZES` generation, and menu delegate hookup off the critical path.
+
+**Files:**
+- Create: `FlowVision/Sources/Common/StartupBootstrap.swift`
+- Modify: `FlowVision/Sources/Common/GlobalVariable.swift` (line 12-13)
+- Modify: `FlowVision/Sources/AppDelegate.swift` (lines 64–252, 254–278)
+- Modify: `FlowVision.xcodeproj/project.pbxproj`
+
+### - [ ] Step 4.1: Make `THUMB_SIZES` lazy
+
+Modify `FlowVision/Sources/Common/GlobalVariable.swift` lines 12–13:
+
+```swift
+// Lazily computed thumbnail bucket sizes. Pure function of constants — safe to cache.
+private let _thumbSizesComputed: [Int] = {
+    var result: [Int] = []
+    var seen = Set<Int>()
+    var x: Double = 192
+    while x <= 10000 {
+        let rounded = Int(round(x) / 64) * 64
+        if seen.insert(rounded).inserted { result.append(rounded) }
+        x *= 1.1
+    }
+    return result
+}()
+var THUMB_SIZES: [Int] { _thumbSizesComputed }
+```
+
+### - [ ] Step 4.2: Remove `generateRoundedArray` from `applicationWillFinishLaunching`
+
+Modify `FlowVision/Sources/AppDelegate.swift` lines 72–89 (the `generateRoundedArray` nested function + `THUMB_SIZES = generateRoundedArray()` call). Delete this whole block.
+
+`THUMB_SIZES` will now compute lazily on first use (no longer mutates a global var; the new top-level `var THUMB_SIZES: [Int]` is read-only).
+
+### - [ ] Step 4.3: Create `StartupBootstrap.swift`
+
+```swift
+//
+//  StartupBootstrap.swift
+//  FlowVision
+//
+
+import Foundation
+
+enum StartupBootstrap {
+    /// Schedule non-critical bootstrap work off the main launch path.
+    /// Called from applicationDidFinishLaunching after the first window is on screen.
+    static func scheduleBackground() {
+        DispatchQueue.global(qos: .utility).async {
+            FFmpegKitWrapper.shared.warmLoadAfterDelay(seconds: 2.0)
+        }
+    }
+}
+```
+
+(FinderTag labels load already runs on main during defaults phase — keep it there for now; it's tiny. If T2 baseline shows it's >5 ms, move it here in a follow-up.)
+
+### - [ ] Step 4.4: Add `StartupBootstrap.swift` to target
+
+Drag into Xcode target or edit `project.pbxproj`.
+
+### - [ ] Step 4.5: Defer menu delegates
+
+Modify `FlowVision/Sources/AppDelegate.swift` lines 240–244 (the `favoritesMenu.removeAllItems(); favoritesMenu.delegate = self; historyMenu...` block).
+
+Move these four lines from `applicationWillFinishLaunching` to the top of `applicationDidFinishLaunching` (immediately after `spBegin(.appDidFinish)`), gated on `if globalVar.fastStartupEnabled { ... } else { /* skip — already done in willFinish for legacy path */ }`. For the legacy path, keep the original lines in `applicationWillFinishLaunching` under the `else` branch of the flag check.
+
+To keep the diff manageable: add a helper:
+
+```swift
+private func setupMenuDelegates() {
+    favoritesMenu.removeAllItems()
+    favoritesMenu.delegate = self
+    historyMenu.removeAllItems()
+    historyMenu.delegate = self
+    viewMenu.delegate = self
+}
+```
+
+Call from `applicationDidFinishLaunching` when flag on, from `applicationWillFinishLaunching` else branch otherwise.
+
+### - [ ] Step 4.6: Call `StartupBootstrap.scheduleBackground()`
+
+Modify `FlowVision/Sources/AppDelegate.swift` `applicationDidFinishLaunching` (line 254). After `setupMenuDelegates()` (Step 4.5), add:
+
+```swift
+if globalVar.fastStartupEnabled {
+    StartupBootstrap.scheduleBackground()
+}
+```
+
+### - [ ] Step 4.7: Build & test
+
+`xcodebuild ... build`. Expect BUILD SUCCEEDED.
+
+Manual:
+1. Cold-launch from PNG. Verify favorites menu populated when clicked (delegate fired). Verify history menu populated. Verify view menu items present.
+2. Open a video file → confirm FFmpeg path still works (warm-load completes off-main, no hang).
+
+### - [ ] Step 4.8: Re-measure
+
+Re-capture `app.willFinish` and `file.openFromFinder.total` medians. Append to baseline doc under `## After T4: AppDelegate slimming`. If `app.willFinish` improvement <5%, revert and skip.
+
+### - [ ] Step 4.9: Commit
+
+```bash
+git add FlowVision/Sources/Common/GlobalVariable.swift \
+        FlowVision/Sources/Common/StartupBootstrap.swift \
+        FlowVision/Sources/AppDelegate.swift \
+        FlowVision/FlowVision.xcodeproj/project.pbxproj \
+        docs/superpowers/specs/2026-05-23-startup-perf-baseline.md
+git commit -m "perf: defer non-critical AppDelegate bootstrap off main launch path"
+```
+
+---
+
+## Task 5 — Fix unit 3: viewDidLoad pruning
+
+Move outlineView / collectionView / event monitor setup behind a `setupDeferredUI()` hook called from `viewDidAppear`.
+
+**Files:**
+- Modify: `FlowVision/Sources/ViewController.swift` (lines 444–856)
+
+### - [ ] Step 5.1: Identify split point
+
+In `ViewController.swift` `viewDidLoad`:
+- **Keep in `viewDidLoad`:** `largeImageView` setup (lines 459–473), `publicVar.isInInitStage = false` (line 477), `drawingView` setup (lines 526–530), defaults batch read (lines 538–597, now `StartupDefaultsCache`), `publicVar.profile` load (line 597), `publicVar.setFileExtensions()` (line 602), theme color block (lines 619–630).
+- **Move to `setupDeferredUI()`:** `collectionViewManager` and `collectionView` config (lines 482–494), progress bar setup (line 498), `outlineViewManager` + `outlineView` config (lines 508–518), splitView delegate (line 522), splitView profile-driven position (lines 604–616), `treeViewData.initData(...)` + `outlineView.reloadData()` + `adjustColumnWidth()` (lines 644–648), all event monitors (lines 653–845).
+
+### - [ ] Step 5.2: Add `setupDeferredUI()` and `viewDidAppear` hook
+
+Modify `FlowVision/Sources/ViewController.swift`. After existing `viewDidLoad` closing brace (line 856), insert:
+
+```swift
+private var deferredUIInitialized = false
+
+override func viewDidAppear() {
+    super.viewDidAppear()
+    if !deferredUIInitialized {
+        deferredUIInitialized = true
+        setupDeferredUI()
+    }
+}
+
+private func setupDeferredUI() {
+    if !globalVar.fastStartupEnabled { return }  // legacy path already did this in viewDidLoad
+
+    // collectionView
+    collectionViewManager = CustomCollectionViewManager(fileDB: fileDB)
+    collectionView.wantsLayer = true
+    collectionView.allowsMultipleSelection = true
+    collectionView.isSelectable = true
+    collectionView.delegate = collectionViewManager
+    collectionView.dataSource = collectionViewManager
+    collectionView.register(CustomCollectionViewItem.self, forItemWithIdentifier: NSUserInterfaceItemIdentifier(rawValue: "CustomCollectionViewItem"))
+    collectionView.setDraggingSourceOperationMask([.every], forLocal: true)
+    collectionView.setDraggingSourceOperationMask([.every], forLocal: false)
+
+    setupProgressBar()
+
+    // outlineView
+    outlineViewManager = CustomOutlineViewManager(fileDB: fileDB, treeViewData: treeViewData, outlineView: outlineView)
+    outlineView.delegate = outlineViewManager
+    outlineView.dataSource = outlineViewManager
+    outlineView.registerForDraggedTypes([.fileURL] + NSFilePromiseReceiver.readableDraggedTypes.map { NSPasteboard.PasteboardType($0) })
+    outlineView.setDraggingSourceOperationMask([.every], forLocal: true)
+    outlineView.setDraggingSourceOperationMask([.every], forLocal: false)
+    outlineView.columnAutoresizingStyle = .noColumnAutoresizing
+
+    splitView.delegate = self
+
+    // splitView profile-driven position
+    if publicVar.profile.isDirTreeHidden { splitView.setPosition(0, ofDividerAt: 0) }
+
+    // layout
+    switch publicVar.profile.layoutType {
+    case .waterfall:  collectionView.collectionViewLayout = publicVar.waterfallLayout
+    case .justified:  collectionView.collectionViewLayout = publicVar.justifiedLayout
+    case .grid:       collectionView.collectionViewLayout = publicVar.gridLayout
+    default:          collectionView.collectionViewLayout = publicVar.justifiedLayout
+    }
+    changeWaterfallLayoutNumberOfColumns()
+
+    treeViewData.initData(path: treeRootFolder)
+    outlineView.reloadData()
+    DispatchQueue.main.async { [weak self] in
+        self?.outlineViewManager.adjustColumnWidth()
+    }
+
+    // event monitors — copy the block from original viewDidLoad lines 653–845 verbatim.
+    setupEventMonitors()
+}
+```
+
+Then extract the event-monitor block (currently lines 653–845) into:
+
+```swift
+private func setupEventMonitors() {
+    NSApp.addObserver(self, forKeyPath: "effectiveAppearance", options: [.new, .old], context: nil)
+    outlineView.doubleAction = #selector(outlineViewDoubleClicked(_:))
+
+    eventMonitorLeftMouseDown = NSEvent.addLocalMonitorForEvents(matching: .leftMouseDown) { [weak self] event in
+        // ... original closure verbatim from lines 661–684 ...
+    }
+
+    eventMonitorLeftMouseUp = NSEvent.addLocalMonitorForEvents(matching: .leftMouseUp) { [weak self] event in
+        // ... original closure verbatim from lines 686–709 ...
+    }
+
+    eventMonitorScrollWheel = NSEvent.addLocalMonitorForEvents(matching: .scrollWheel) { [weak self] event in
+        // ... original closure verbatim from lines 745–758 ...
+    }
+
+    if let scrollView = collectionView.enclosingScrollView {
+        NotificationCenter.default.addObserver(self, selector: #selector(scrollViewDidScroll(_:)), name: NSScrollView.didLiveScrollNotification, object: scrollView)
+        NotificationCenter.default.addObserver(self, selector: #selector(scrollViewScrollEnd(_:)), name: NSScrollView.didEndLiveScrollNotification, object: scrollView)
+    }
+
+    eventMonitorKeyDown = NSEvent.addLocalMonitorForEvents(matching: .keyDown) { [weak self] event in
+        guard let self = self else { return event }
+        return self.KeyShortcutManager(event: event)
+    }
+
+    eventMonitorRightMouseUp = NSEvent.addLocalMonitorForEvents(matching: .rightMouseUp) { [weak self] event in
+        // ... original closure verbatim from lines 778–799 ...
+    }
+
+    eventMonitorRightMouseDown = NSEvent.addLocalMonitorForEvents(matching: .rightMouseDown) { [weak self] event in
+        // ... original closure verbatim from lines 801–822 ...
+    }
+
+    eventMonitorRightMouseDragged = NSEvent.addLocalMonitorForEvents(matching: .rightMouseDragged) { [weak self] event in
+        // ... original closure verbatim from lines 824–845 ...
+    }
+}
+```
+
+Copy each `// ...verbatim...` placeholder with the exact closure body from the corresponding existing lines.
+
+### - [ ] Step 5.3: Wrap legacy viewDidLoad branch
+
+In `viewDidLoad`, after the keep-block (theme colors, line 630), add the gate:
+
+```swift
+if globalVar.fastStartupEnabled {
+    // deferred work runs in setupDeferredUI from viewDidAppear
+} else {
+    // legacy: do the work inline here — keep lines 482–518, 522, 604–616, 644–648, 653–845 in place
+    setupDeferredUI_legacy()
+}
+```
+
+Define `setupDeferredUI_legacy()` containing exact original code (a copy of the work, no flag check inside). This duplication is removed after T5 ships stable.
+
+### - [ ] Step 5.4: Build & manual test
+
+`xcodebuild ... build`. Expect BUILD SUCCEEDED.
+
+Manual:
+1. Cold-launch from PNG. Verify window appears; verify large image renders; sidebar / tree may appear a beat later (acceptable).
+2. Click sidebar entry → tree responds.
+3. Right-click large image → context menu fires (right-mouse monitor installed).
+4. Key shortcuts (→ arrow, space) → work.
+5. Scroll wheel zoom (if enabled) → works.
+6. Toggle flag off → all UI present at viewDidLoad time as before.
+
+### - [ ] Step 5.5: Re-measure
+
+`vc.viewDidLoad` and `file.openFromFinder.total` medians → baseline doc, `## After T5: viewDidLoad pruning`. If `vc.viewDidLoad` improvement <5%, revert.
+
+### - [ ] Step 5.6: Commit
+
+```bash
+git add FlowVision/Sources/ViewController.swift \
+        docs/superpowers/specs/2026-05-23-startup-perf-baseline.md
+git commit -m "perf: defer non-critical viewDidLoad work to viewDidAppear"
+```
+
+---
+
+## Task 6 — Fix unit 4: storyboard split (optional, highest risk)
+
+**Defer this task unless prior fix units leave >150 ms in `window.storyboardInstantiate`.** Storyboard refactoring is fragile and AppKit-version-sensitive.
+
+If skipped, document in baseline doc: `## T6 skipped: insufficient remaining cost in window.storyboardInstantiate`.
+
+### - [ ] Step 6.1: Evaluate skip
+
+Inspect baseline doc. If `window.storyboardInstantiate` median <150 ms after T3+T4+T5, skip. Commit a note:
+
+```bash
+echo "## T6: skipped (storyboardInstantiate <150ms after T3-T5)" >> docs/superpowers/specs/2026-05-23-startup-perf-baseline.md
+git add docs/superpowers/specs/2026-05-23-startup-perf-baseline.md
+git commit -m "docs: skip storyboard split fix unit (insufficient remaining cost)"
+```
+
+Proceed to Task 7.
+
+### - [ ] Step 6.2 (only if not skipped): Identify Main.storyboard scenes
+
+Open `FlowVision/Resources/Main.storyboard` in Xcode. List scenes/window controllers present. Identify scenes used during launch-from-file vs settings/secondary panels.
+
+### - [ ] Step 6.3 (only if not skipped): Split into `Secondary.storyboard`
+
+Move secondary-panel scenes to a new `Secondary.storyboard`. Wire any `instantiateController(withIdentifier:)` callers to load from the appropriate storyboard.
+
+### - [ ] Step 6.4 (only if not skipped): Build, test, measure, commit
+
+Full smoke test (Settings, Profiles, Tagging). Measure `window.storyboardInstantiate` decrease. If <10% gain or any crash, revert.
+
+---
+
+## Task 7 — Fix unit 5: launch-from-file fast path
+
+Decode image on background queue, show window, defer folder scan.
+
+**Files:**
+- Modify: `FlowVision/Sources/AppDelegate.swift` (lines 424–488, `application(openFiles:)`)
+- Modify: `FlowVision/Sources/ViewControllerExtension/LargeImage.swift` (lines 469–488, `OpenLargeImageFromFinder`)
+
+### - [ ] Step 7.1: Reorder `application(openFiles:)`
+
+Modify `FlowVision/Sources/AppDelegate.swift` lines 424–488. Inside the "Open in new window" branch (the existing `if true || windowControllers.count == 0` block, lines 449–467), when `!isDirectory`:
+
+```swift
+// fast path: window + image first, folder scan after first frame
+globalVar.isLaunchFromFile = true
+if windowControllers.count == 0 || globalVar.autoHideToolbar {
+    globalVar.useCreateWindowShowDelay = true
+}
+guard let targetWindowController = createNewWindow(file) else { return }
+
+if globalVar.fastStartupEnabled {
+    openImageInTargetWindow_FastPath(file, windowController: targetWindowController)
+} else {
+    openImageInTargetWindow(file, windowController: targetWindowController)
+}
+return
+```
+
+Then add a new `openImageInTargetWindow_FastPath`:
+
+```swift
+func openImageInTargetWindow_FastPath(_ openPath: String, windowController: NSWindowController) {
+    guard let viewController = windowController.contentViewController as? ViewController else { return }
+    let folderPath = getFileSchemeAbsParentFolderPath(openPath)
+    let path = getFileSchemeAbsPath(openPath)
+
+    viewController.publicVar.openFromFinderPath = path
+    viewController.OpenLargeImageFromFinder(path: path)
+
+    // Folder enumeration runs after the large image is on screen.
+    NotificationCenter.default.addObserver(
+        forName: .didShowLargeImageFromLaunch,
+        object: viewController,
+        queue: .main
+    ) { [weak viewController] _ in
+        DispatchQueue.global(qos: .utility).async {
+            DispatchQueue.main.async {
+                viewController?.switchDirByDirection(direction: .zero, dest: folderPath, doCollapse: true, expandLast: true, skip: false, stackDeep: 0)
+            }
+        }
+    }
+}
+```
+
+(`Notification.Name.didShowLargeImageFromLaunch` defined in Step 7.3.)
+
+### - [ ] Step 7.2: Define notification name
+
+Modify `FlowVision/Sources/Common/StartupTiming.swift`. Append at file end:
+
+```swift
+extension Notification.Name {
+    static let didShowLargeImageFromLaunch = Notification.Name("app.flowvision.didShowLargeImageFromLaunch")
+}
+```
+
+### - [ ] Step 7.3: Post notification after first frame
+
+Modify `FlowVision/Sources/ViewControllerExtension/LargeImage.swift` `OpenLargeImageFromFinder` (line 469).
+
+After the existing body (after the comment `// setWindowTitleOfLargeImage(file: item.file)` at line 487), add:
+
+```swift
+DispatchQueue.main.async { [weak self] in
+    guard let self = self else { return }
+    NotificationCenter.default.post(name: .didShowLargeImageFromLaunch, object: self)
+}
+```
+
+(The `spEnd(.fileOpenFromFinderTotal)` added in T1.7 stays here too — it's the same dispatch point, but they're separate `async` blocks for clarity.)
+
+### - [ ] Step 7.4: Build & test
+
+`xcodebuild ... build`. Expect BUILD SUCCEEDED.
+
+Manual:
+1. Cold-launch from PNG. Confirm window + large image appear. After ~100 ms folder list populates underneath.
+2. Press →: navigates to next sibling (folder enum must have completed).
+3. Press → again immediately after launch (within 50 ms of first frame): should still work or no-op gracefully (no crash). If crash, add a guard in arrow-key handler checking that folder enum has run.
+4. Launch from folder (not file) → unchanged behavior.
+5. Toggle flag off → legacy synchronous path.
+
+### - [ ] Step 7.5: Re-measure
+
+`file.openFromFinder.total` median per file type → baseline doc `## After T7: launch-from-file fast path`. Required: ≥40% reduction vs Stage 1 baseline (this is the acceptance metric per spec §7).
+
+If <40% reduction, investigate top remaining span. Possibly the decode itself dominates and architecture cannot help further — note in baseline doc.
+
+### - [ ] Step 7.6: Commit
+
+```bash
+git add FlowVision/Sources/AppDelegate.swift \
+        FlowVision/Sources/ViewControllerExtension/LargeImage.swift \
+        FlowVision/Sources/Common/StartupTiming.swift \
+        docs/superpowers/specs/2026-05-23-startup-perf-baseline.md
+git commit -m "perf: launch-from-file shows window before folder scan"
+```
+
+---
+
+## Task 8 — Fix unit 6: FFmpeg warm + linker audit
+
+**Files:**
+- Modify: `FlowVision/Sources/Common/FFmpegKit.swift`
+- Modify: `FlowVision/Sources/Common/StartupBootstrap.swift`
+- Modify: `FlowVision.xcodeproj/project.pbxproj` (Release `DEAD_CODE_STRIPPING`)
+
+### - [ ] Step 8.1: Add `warmLoadAfterDelay`
+
+Modify `FlowVision/Sources/Common/FFmpegKit.swift` after the existing `loadFFmpegKitIfNeeded()` (line 53):
+
+```swift
+func warmLoadAfterDelay(seconds: Double) {
+    DispatchQueue.global(qos: .background).asyncAfter(deadline: .now() + seconds) { [weak self] in
+        self?.loadFFmpegKitIfNeeded()
+    }
+}
+```
+
+### - [ ] Step 8.2: Verify `StartupBootstrap` already calls it
+
+Already done in Task 4.3. Re-confirm:
+
+```swift
+static func scheduleBackground() {
+    DispatchQueue.global(qos: .utility).async {
+        FFmpegKitWrapper.shared.warmLoadAfterDelay(seconds: 2.0)
+    }
+}
+```
+
+### - [ ] Step 8.3: Enable DEAD_CODE_STRIPPING
+
+Verify current value:
+
+```bash
+grep -n "DEAD_CODE_STRIPPING" FlowVision.xcodeproj/project.pbxproj
+```
+
+If absent or `NO` for Release, edit `project.pbxproj` Release buildSettings block (or open Xcode → FlowVision target → Build Settings → search "Dead Code Stripping") → set `DEAD_CODE_STRIPPING = YES` Release. Debug can stay `NO`.
+
+### - [ ] Step 8.4: Audit `OTHER_LDFLAGS`
+
+```bash
+grep -n "OTHER_LDFLAGS" FlowVision.xcodeproj/project.pbxproj
+```
+
+Inspect for `-framework <Name>` entries. Compare to actually-imported frameworks (`grep -rn "^import " FlowVision/Sources | sort -u`). **Do not remove anything without verification** — many frameworks are loaded indirectly (e.g., from Storyboard or Objective-C runtime).
+
+If any entry is clearly unused (e.g., a removed dependency), remove and rebuild. If unsure, leave it.
+
+### - [ ] Step 8.5: Build Release & test
+
+`xcodebuild -project FlowVision.xcodeproj -scheme FlowVision -configuration Release build CODE_SIGN_IDENTITY="" CODE_SIGNING_REQUIRED=NO`. Expect BUILD SUCCEEDED.
+
+Manual:
+1. Cold-launch from PNG → confirm normal behavior.
+2. Open a `.mkv` video (non-native, requires FFmpeg) → confirm it plays. (Tests warm path.)
+3. Set `doNotUseFFmpeg = true` in defaults, relaunch, open `.mkv` → confirm fallback message (no crash).
+
+### - [ ] Step 8.6: Re-measure
+
+`file.openFromFinder.total` (PNG and video) medians → baseline doc `## After T8: FFmpeg warm + linker`. Pre-main / dyld time isn't captured by our spans — measure full launch by Activity Monitor or instruments if curious.
+
+### - [ ] Step 8.7: Commit
+
+```bash
+git add FlowVision/Sources/Common/FFmpegKit.swift \
+        FlowVision/FlowVision.xcodeproj/project.pbxproj \
+        docs/superpowers/specs/2026-05-23-startup-perf-baseline.md
+git commit -m "perf: warm-load FFmpeg off main; enable DEAD_CODE_STRIPPING in Release"
+```
+
+---
+
+## Task 9 — Cleanup (after one stable release cycle)
+
+**Defer until at least one full release with all units stable.** Skip if any unit was reverted.
+
+### - [ ] Step 9.1: Remove legacy else branches
+
+Remove every `if globalVar.fastStartupEnabled { ... } else { legacy code }` introduced in T3, T4, T5, T7. Keep the `if`-branch contents only.
+
+### - [ ] Step 9.2: Remove `globalVar.fastStartupEnabled`
+
+Remove the property from `GlobalVariable.swift`, remove the defaults wiring in `AppDelegate.swift`, remove the user-defaults migration (delete the key if set).
+
+### - [ ] Step 9.3: Remove `setupDeferredUI_legacy()`
+
+Delete the legacy helper added in T5.3.
+
+### - [ ] Step 9.4: Build, full smoke test, commit
+
+```bash
+git commit -m "refactor: remove fastStartupEnabled flag after stable release"
+```
+
+---
+
+## Acceptance Summary
+
+Per spec §7:
+- Baseline captured (T2.4).
+- `file.openFromFinder.total` median (median of 5 cold runs per file type) ≥40% lower vs baseline after T7. Recorded in `docs/superpowers/specs/2026-05-23-startup-perf-baseline.md`.
+- Each fix unit gates on its own ≥5% measured improvement of the span it targets, else reverted.
+- Per-unit rollback available via `git revert` and via `defaults write app.flowvision fastStartupEnabled -bool NO`.
+
+---
+
+## Self-Review Notes
+
+Coverage check vs spec:
+- §1 Goal — Task 1, 7 — ✓
+- §2 Pipeline — Task 1 (instruments observed pipeline) — ✓
+- §3 Target pipeline — Task 4, 5, 7 — ✓
+- §4 Stage 1 instrumentation — Task 1 — ✓
+- §4 Stage 2 units 1–6 — Tasks 3, 4, 5, 6, 7, 8 — ✓
+- §5 New files — Tasks 1, 3, 4 — ✓
+- §5 Feature flag — Task 2 — ✓
+- §6 Error handling — covered in each task's manual test step
+- §7 Testing matrix — Task 2.3 + each fix unit's manual test
+- §8 Rollout order — task order matches
+- §9 Rollback — flag toggle steps included in tests; Task 9 final removal — ✓
+
+No placeholders ("TBD", "implement later") in any step.
+Type names verified: `PublicVar` reference flagged in T3.2 for verification before edit. `FFmpegKitWrapper.shared`, `CustomTagView.userDefaultsKey`, `FinderTag.customLabels`, `FinderTag.systemColorLabels` all match existing usage in `AppDelegate.swift`.

From c0c4c6ac0deea64e223ddd95ad9febc1e9a7ff8a Mon Sep 17 00:00:00 2001
From: lenisko <10072920+lenisko@users.noreply.github.com>
Date: Tue, 2 Jun 2026 13:56:29 +0200
Subject: [PATCH 4/7] fix: layout-aware keyboard shortcut matching (#16)

Shortcuts matched only on physical NSEvent.keyCode, so default +/-/=
zoom bindings fired by US-ANSI key position. On ISO layouts where those
symbols move (Norwegian + sits on the US - key) or sit behind AltGr/Option
(Nordic = is Option+0), the wrong action triggered or none at all.

Add a semantic fallback that matches on the glyph the key actually
produced, taking precedence over the physical keyCode for printable keys
(the reported Norwegian + key is physically bound to zoom-out). US/ANSI
and Dvorak/Colemak are unaffected since glyph and position agree; special
keys and control combos keep physical matching.

- ShortcutMatching: pure, unit-tested matching helpers (no AppKit dep)
- ShortcutStore: semantic index + lookup alongside the physical one
- KeyChord.init: record the produced glyph so re-recorded Option/AltGr
  symbols stay symmetric with dispatch
- dispatcher: semantic-first, deduped candidate ordering
---
 FlowVision.xcodeproj/project.pbxproj          |   4 +
 FlowVision/Sources/Shortcuts/KeyChord.swift   |   6 +-
 .../Sources/Shortcuts/ShortcutMatching.swift  | 108 ++++++++++++++++++
 .../Sources/Shortcuts/ShortcutStore.swift     |  35 ++++++
 .../ViewControllerExtension/KeyShortcut.swift |  13 ++-
 5 files changed, 164 insertions(+), 2 deletions(-)
 create mode 100644 FlowVision/Sources/Shortcuts/ShortcutMatching.swift

diff --git a/FlowVision.xcodeproj/project.pbxproj b/FlowVision.xcodeproj/project.pbxproj
index 17653e6c..fb4721ca 100644
--- a/FlowVision.xcodeproj/project.pbxproj
+++ b/FlowVision.xcodeproj/project.pbxproj
@@ -82,6 +82,7 @@
 		F7FAE0012F6BA00000FAE001 /* FavoritesPopoverViewController.swift in Sources */ = {isa = PBXBuildFile; fileRef = F7FAE0002F6BA00000FAE000 /* FavoritesPopoverViewController.swift */; };
 		F7FED5F32F7D0B1100E35164 /* Tagging.swift in Sources */ = {isa = PBXBuildFile; fileRef = F7FED5F22F7D0B0E00E35164 /* Tagging.swift */; };
 		F7CD001C2F0E000000C9AB85 /* KeyChord.swift in Sources */ = {isa = PBXBuildFile; fileRef = F7CD001B2F0E000000C9AB85 /* KeyChord.swift */; };
+		F7CD00302F0E000000C9AB85 /* ShortcutMatching.swift in Sources */ = {isa = PBXBuildFile; fileRef = F7CD002F2F0E000000C9AB85 /* ShortcutMatching.swift */; };
 		F7CD001E2F0E000000C9AB85 /* ShortcutAction.swift in Sources */ = {isa = PBXBuildFile; fileRef = F7CD001D2F0E000000C9AB85 /* ShortcutAction.swift */; };
 		F7CD00202F0E000000C9AB85 /* ShortcutStore.swift in Sources */ = {isa = PBXBuildFile; fileRef = F7CD001F2F0E000000C9AB85 /* ShortcutStore.swift */; };
 		F7CD00222F0E000000C9AB85 /* ShortcutRecorderView.swift in Sources */ = {isa = PBXBuildFile; fileRef = F7CD00212F0E000000C9AB85 /* ShortcutRecorderView.swift */; };
@@ -202,6 +203,7 @@
 		F7FAE0002F6BA00000FAE000 /* FavoritesPopoverViewController.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = FavoritesPopoverViewController.swift; sourceTree = "<group>"; };
 		F7FED5F22F7D0B0E00E35164 /* Tagging.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = Tagging.swift; sourceTree = "<group>"; };
 		F7CD001B2F0E000000C9AB85 /* KeyChord.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = KeyChord.swift; sourceTree = "<group>"; };
+		F7CD002F2F0E000000C9AB85 /* ShortcutMatching.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ShortcutMatching.swift; sourceTree = "<group>"; };
 		F7CD001D2F0E000000C9AB85 /* ShortcutAction.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ShortcutAction.swift; sourceTree = "<group>"; };
 		F7CD001F2F0E000000C9AB85 /* ShortcutStore.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ShortcutStore.swift; sourceTree = "<group>"; };
 		F7CD00212F0E000000C9AB85 /* ShortcutRecorderView.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ShortcutRecorderView.swift; sourceTree = "<group>"; };
@@ -294,6 +296,7 @@
 			isa = PBXGroup;
 			children = (
 				F7CD001B2F0E000000C9AB85 /* KeyChord.swift */,
+				F7CD002F2F0E000000C9AB85 /* ShortcutMatching.swift */,
 				F7CD001D2F0E000000C9AB85 /* ShortcutAction.swift */,
 				F7CD001F2F0E000000C9AB85 /* ShortcutStore.swift */,
 				F7CD00212F0E000000C9AB85 /* ShortcutRecorderView.swift */,
@@ -547,6 +550,7 @@
 				F73865D32C37B97500837FE4 /* CustomCollectionView.swift in Sources */,
 				F74D555E2F0E52F800C9AB85 /* ArrowKeyLocate.swift in Sources */,
 				F7CD001C2F0E000000C9AB85 /* KeyChord.swift in Sources */,
+				F7CD00302F0E000000C9AB85 /* ShortcutMatching.swift in Sources */,
 				F7CD001E2F0E000000C9AB85 /* ShortcutAction.swift in Sources */,
 				F7CD00202F0E000000C9AB85 /* ShortcutStore.swift in Sources */,
 				F7CD00222F0E000000C9AB85 /* ShortcutRecorderView.swift in Sources */,
diff --git a/FlowVision/Sources/Shortcuts/KeyChord.swift b/FlowVision/Sources/Shortcuts/KeyChord.swift
index 0ce05dab..c64e7bdd 100644
--- a/FlowVision/Sources/Shortcuts/KeyChord.swift
+++ b/FlowVision/Sources/Shortcuts/KeyChord.swift
@@ -59,7 +59,11 @@ struct KeyChord: Codable {
 
     init(event: NSEvent) {
         self.keyCode = event.keyCode
-        self.character = (event.charactersIgnoringModifiers ?? "").lowercased()
+        // Prefer the produced glyph so Option/AltGr symbols (Nordic '=' = Option+0) record
+        // correctly and stay symmetric with semantic dispatch. See ShortcutMatching.
+        self.character = ShortcutMatching.recordedCharacter(
+            literal: event.characters,
+            ignoringModifiers: event.charactersIgnoringModifiers)
         var m = Modifiers(event.modifierFlags)
         if Self.isImplicitFn(event.keyCode) { m.remove(.function) }
         self.modifiers = m
diff --git a/FlowVision/Sources/Shortcuts/ShortcutMatching.swift b/FlowVision/Sources/Shortcuts/ShortcutMatching.swift
new file mode 100644
index 00000000..b9f06efa
--- /dev/null
+++ b/FlowVision/Sources/Shortcuts/ShortcutMatching.swift
@@ -0,0 +1,108 @@
+//
+//  ShortcutMatching.swift
+//  FlowVision
+//
+//  Layout-aware semantic fallback for keyboard shortcuts.
+//
+//  The primary dispatch path matches on physical keyCode (see ShortcutStore.reverseIndex),
+//  which is correct for US/ANSI and physical-position layouts (Dvorak/Colemak) but wrong for
+//  ISO national layouts where +, -, = live on different physical keys or behind AltGr/Option
+//  (e.g. Norwegian + sits on the US '-' key; Nordic '=' is Option+0). See issue #16.
+//
+//  This enum holds the pure matching helpers — no AppKit / NSEvent dependency so the algorithm
+//  is unit-testable from raw glyph strings + modifiers.
+//
+
+import Foundation
+
+enum ShortcutMatching {
+
+    /// Index/lookup key: a produced glyph plus its semantically-relevant modifiers.
+    struct SemKey: Hashable {
+        let char: String
+        let mods: Modifiers
+    }
+
+    /// Reduce modifiers to the set that meaningfully distinguishes a shortcut for `char`.
+    ///
+    /// For symbol glyphs (anything not a letter/digit), Shift and Option are *consumers* —
+    /// they are what produced the glyph (US '+' = Shift+=, Nordic '=' = Option+0), so they
+    /// must not be required again at match time. Only ⌘ and ⌃ survive.
+    ///
+    /// For letters/digits the glyph is the base key, so Shift stays significant (don't
+    /// collapse ⌘⇧Z onto ⌘Z); Option/Fn are dropped as they alter the glyph or are implicit.
+    static func semMods(_ mods: Modifiers, char: String) -> Modifiers {
+        if isSymbol(char) {
+            return mods.intersection([.command, .control])
+        }
+        return mods.intersection([.command, .control, .shift])
+    }
+
+    /// Expand produced glyphs with zoom-cluster equivalences so a key that yields '+'
+    /// also satisfies the '=' binding, and '_' satisfies '-'.
+    static func expand(_ chars: Set<String>) -> Set<String> {
+        var out = chars
+        for c in chars {
+            switch c {
+            case "+": out.insert("=")
+            case "_": out.insert("-")
+            default: break
+            }
+        }
+        return out
+    }
+
+    /// Glyphs a key event produced, equivalence-expanded.
+    ///
+    /// Prefers the literal `characters` (carries the real glyph including Option/AltGr and
+    /// Shift symbols). Only falls back to `charactersIgnoringModifiers` when the literal is
+    /// empty (dead keys, pure modifiers) — using both unconditionally would leak the base-layer
+    /// digit (Nordic Option+0 reports characters="=" but ignoringModifiers="0") and falsely
+    /// fire the zoom-reset binding.
+    static func producedChars(characters: String?, ignoringModifiers: String?) -> Set<String> {
+        let literal = (characters ?? "").lowercased()
+        let base = literal.isEmpty ? (ignoringModifiers ?? "").lowercased() : literal
+        guard !base.isEmpty else { return [] }
+        return expand([base])
+    }
+
+    /// Glyph to persist when recording a chord, kept symmetric with `producedChars` so a
+    /// re-recorded binding matches what dispatch later sees.
+    ///
+    /// Prefers the literal `characters` when it is a normal printable glyph — this captures
+    /// Option/AltGr-produced symbols (Nordic '=' is Option+0, where `charactersIgnoringModifiers`
+    /// reports the base-layer '0'). Falls back to the modifier-independent base for control
+    /// combos (Ctrl+A reports a control code) and dead keys / empty literals.
+    static func recordedCharacter(literal: String?, ignoringModifiers: String?) -> String {
+        let lit = literal ?? ""
+        if let scalar = lit.unicodeScalars.first, scalar.value >= 0x20 {
+            return lit.lowercased()
+        }
+        return (ignoringModifiers ?? "").lowercased()
+    }
+
+    /// Build the canonical SemKey for indexing or lookup of a (glyph, modifiers) pair.
+    static func key(char: String, mods: Modifiers) -> SemKey {
+        SemKey(char: char.lowercased(), mods: semMods(mods, char: char))
+    }
+
+    /// Merge semantic and physical candidates with **semantic first**, deduped (stable).
+    ///
+    /// Semantic (the glyph the user actually typed) must outrank physical keyCode: on ISO
+    /// layouts the physical key under a moved symbol is often bound to the *opposite* action
+    /// (Norwegian '+' sits on the US '-' key, whose keyCode is bound to zoom-out). Preferring
+    /// the glyph fixes issue #16 while staying a no-op on US/ANSI, where both agree.
+    static func order<T: Hashable>(semantic: [T], physical: [T]) -> [T] {
+        var out: [T] = []
+        var seen: Set<T> = []
+        for item in semantic + physical where seen.insert(item).inserted {
+            out.append(item)
+        }
+        return out
+    }
+
+    private static func isSymbol(_ char: String) -> Bool {
+        guard let c = char.first else { return false }
+        return !c.isLetter && !c.isNumber
+    }
+}
diff --git a/FlowVision/Sources/Shortcuts/ShortcutStore.swift b/FlowVision/Sources/Shortcuts/ShortcutStore.swift
index 4a9bfe46..c5bde353 100644
--- a/FlowVision/Sources/Shortcuts/ShortcutStore.swift
+++ b/FlowVision/Sources/Shortcuts/ShortcutStore.swift
@@ -21,6 +21,12 @@ final class ShortcutStore {
     /// disjoint — enforced by conflict UI in the settings pane, not by the store).
     private(set) var reverseIndex: [KeyChord: [ShortcutAction]] = [:]
 
+    /// Layout-aware fallback index keyed on produced glyph rather than physical keyCode.
+    /// Consulted only when `reverseIndex` misses, so it never overrides a physical match
+    /// (zero regression for US/ANSI and Dvorak/Colemak). Fixes ISO layouts where +, -, =
+    /// move physical position or sit behind Option/AltGr. See issue #16 / ShortcutMatching.
+    private(set) var semanticIndex: [ShortcutMatching.SemKey: [ShortcutAction]] = [:]
+
     /// Actions the user has wiped completely. Distinguishes "user cleared all"
     /// from "never persisted" so defaults don't sneak back after a reset-empty.
     private var clearedExplicitly: Set<ShortcutAction> = []
@@ -243,15 +249,44 @@ final class ShortcutStore {
 
     private func rebuildIndex() {
         var idx: [KeyChord: [ShortcutAction]] = [:]
+        var sem: [ShortcutMatching.SemKey: [ShortcutAction]] = [:]
         for action in ShortcutAction.allCases {
             // Dedupe within an action so intra-action chord duplicates
             // don't show up twice in reverseIndex[chord].
             var seen: Set<KeyChord> = []
+            var seenSem: Set<ShortcutMatching.SemKey> = []
             for chord in chords(for: action) where seen.insert(chord).inserted {
                 idx[chord, default: []].append(action)
+                // Index the recorded glyph for the semantic fallback. Special keys
+                // (arrows, Esc, …) record an empty character and are physical-only.
+                guard !chord.character.isEmpty else { continue }
+                let key = ShortcutMatching.key(char: chord.character, mods: chord.modifiers)
+                if seenSem.insert(key).inserted {
+                    sem[key, default: []].append(action)
+                }
             }
         }
         reverseIndex = idx
+        semanticIndex = sem
+    }
+
+    /// Layout-aware fallback lookup. Returns actions whose recorded glyph matches one of
+    /// the glyphs this key event produced. Call only after `reverseIndex` misses.
+    func semanticCandidates(characters: String?,
+                            ignoringModifiers: String?,
+                            modifiers: Modifiers) -> [ShortcutAction] {
+        let glyphs = ShortcutMatching.producedChars(characters: characters,
+                                                    ignoringModifiers: ignoringModifiers)
+        guard !glyphs.isEmpty else { return [] }
+        var out: [ShortcutAction] = []
+        var seen: Set<ShortcutAction> = []
+        for glyph in glyphs {
+            let key = ShortcutMatching.key(char: glyph, mods: modifiers)
+            for action in semanticIndex[key] ?? [] where seen.insert(action).inserted {
+                out.append(action)
+            }
+        }
+        return out
     }
 
     @discardableResult
diff --git a/FlowVision/Sources/ViewControllerExtension/KeyShortcut.swift b/FlowVision/Sources/ViewControllerExtension/KeyShortcut.swift
index 5d35d739..a3774f96 100644
--- a/FlowVision/Sources/ViewControllerExtension/KeyShortcut.swift
+++ b/FlowVision/Sources/ViewControllerExtension/KeyShortcut.swift
@@ -38,7 +38,18 @@ extension ViewController {
         if handleNonRebindableNavigation(event) { return nil }
 
         let chord = KeyChord(event: event)
-        let candidates = ShortcutStore.shared.reverseIndex[chord] ?? []
+
+        // Layout-aware matching. The glyph the key actually produced (semantic) outranks
+        // the physical keyCode: on ISO layouts the physical key under a moved symbol is
+        // often bound to the opposite action — e.g. Norwegian '+' sits on the US '-' key,
+        // whose keyCode is bound to zoom-out (issue #16). On US/ANSI both agree, so this is
+        // a no-op there and for special keys (no glyph) it falls through to physical.
+        let semantic = ShortcutStore.shared.semanticCandidates(
+            characters: event.characters,
+            ignoringModifiers: event.charactersIgnoringModifiers,
+            modifiers: chord.modifiers)
+        let physical = ShortcutStore.shared.reverseIndex[chord] ?? []
+        let candidates = ShortcutMatching.order(semantic: semantic, physical: physical)
 
         for action in candidates where stateGateOpen(for: action) && scopeMatches(action.scope) {
             if dispatch(action) { return nil }

From 5f7d788880ce3c4a6cd052bc6d1ca58e135a582a Mon Sep 17 00:00:00 2001
From: lenisko <10072920+lenisko@users.noreply.github.com>
Date: Tue, 2 Jun 2026 13:58:44 +0200
Subject: [PATCH 5/7] refactor: drop dead shortcutBindings.v1 migration path
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The v1 single-chord wire format was never emitted — it landed in the same
unreleased commit as v2 (after the 1.7.2 tag) and nothing ever wrote it
(persist() only writes v2). The read/migration path was speculative dead
code. Remove WireV1, EntryV1, applyV1, the legacy key, and the load()
fallback branch.
---
 .../Sources/Shortcuts/ShortcutStore.swift     | 47 -------------------
 1 file changed, 47 deletions(-)

diff --git a/FlowVision/Sources/Shortcuts/ShortcutStore.swift b/FlowVision/Sources/Shortcuts/ShortcutStore.swift
index c5bde353..6b8966e8 100644
--- a/FlowVision/Sources/Shortcuts/ShortcutStore.swift
+++ b/FlowVision/Sources/Shortcuts/ShortcutStore.swift
@@ -32,7 +32,6 @@ final class ShortcutStore {
     private var clearedExplicitly: Set<ShortcutAction> = []
 
     private let defaultsKey   = "shortcutBindings.v2"
-    private let legacyKeyV1   = "shortcutBindings.v1"
 
     // MARK: - Wire format v2
 
@@ -66,33 +65,6 @@ final class ShortcutStore {
         }
     }
 
-    // MARK: - Wire format v1 (legacy single-chord)
-
-    private struct WireV1: Codable {
-        let version: Int?
-        let entries: [EntryV1]
-    }
-
-    private struct EntryV1: Codable {
-        let action: ShortcutAction?
-        let chord: KeyChord?
-
-        enum CodingKeys: String, CodingKey { case action, chord }
-
-        init(from decoder: Decoder) throws {
-            let c = try decoder.container(keyedBy: CodingKeys.self)
-            let raw = try? c.decode(String.self, forKey: .action)
-            self.action = raw.flatMap { ShortcutAction(rawValue: $0) }
-            self.chord = try? c.decodeIfPresent(KeyChord.self, forKey: .chord)
-        }
-
-        func encode(to encoder: Encoder) throws {
-            var c = encoder.container(keyedBy: CodingKeys.self)
-            try c.encode(action?.rawValue, forKey: .action)
-            try c.encode(chord, forKey: .chord)
-        }
-    }
-
     // MARK: - Public API
 
     /// Returns the active chord list for an action: stored value if present,
@@ -110,14 +82,6 @@ final class ShortcutStore {
         if let data = UserDefaults.standard.data(forKey: defaultsKey),
            let wire = try? JSONDecoder().decode(Wire.self, from: data) {
             applyV2(wire)
-        } else if let data = UserDefaults.standard.data(forKey: legacyKeyV1),
-                  let wire = try? JSONDecoder().decode(WireV1.self, from: data) {
-            applyV1(wire)
-            // Only drop the legacy blob once we've successfully written v2.
-            // If persist() fails, leave v1 in place so the next launch can retry.
-            if persist() {
-                UserDefaults.standard.removeObject(forKey: legacyKeyV1)
-            }
         }
         rebuildIndex()
     }
@@ -134,17 +98,6 @@ final class ShortcutStore {
         }
     }
 
-    private func applyV1(_ wire: WireV1) {
-        for entry in wire.entries {
-            guard let a = entry.action else { continue }
-            if let chord = entry.chord {
-                bindings[a] = [chord]
-            } else {
-                clearedExplicitly.insert(a)
-            }
-        }
-    }
-
     /// Replace chord at `index` for `action`. If `chord` is nil, remove that slot.
     /// If `index` equals current count, the chord is appended. Indexes beyond
     /// `count` are rejected to avoid silent phantom appends.

From a22d834d352aab7513b2fe116afe22e63dd4de0f Mon Sep 17 00:00:00 2001
From: lenisko <10072920+lenisko@users.noreply.github.com>
Date: Tue, 2 Jun 2026 14:03:21 +0200
Subject: [PATCH 6/7] docs: correct semantic-matching comments; unify glyph
 guard

Review follow-up.

- Comments claimed the semantic index was consulted only on a physical
  miss and "never overrides" the keyCode match ("no-op on US/ANSI"). The
  dispatch is semantic-first and does override; on US it now also resolves
  shifted symbols (Shift+= -> '+' -> '=' -> zoom-in) the keyCode path
  missed. Rewrite the comments to describe the actual precedence.
- producedChars now reuses recordedCharacter so dispatch and record share
  one printable/Option-aware guard instead of producedChars keying only on
  emptiness (which would have passed control codes through to lookup).
---
 .../Sources/Shortcuts/ShortcutMatching.swift   | 18 +++++++++---------
 .../Sources/Shortcuts/ShortcutStore.swift      | 16 ++++++++++------
 .../ViewControllerExtension/KeyShortcut.swift  |  6 ++++--
 3 files changed, 23 insertions(+), 17 deletions(-)

diff --git a/FlowVision/Sources/Shortcuts/ShortcutMatching.swift b/FlowVision/Sources/Shortcuts/ShortcutMatching.swift
index b9f06efa..f5d71f18 100644
--- a/FlowVision/Sources/Shortcuts/ShortcutMatching.swift
+++ b/FlowVision/Sources/Shortcuts/ShortcutMatching.swift
@@ -54,16 +54,16 @@ enum ShortcutMatching {
 
     /// Glyphs a key event produced, equivalence-expanded.
     ///
-    /// Prefers the literal `characters` (carries the real glyph including Option/AltGr and
-    /// Shift symbols). Only falls back to `charactersIgnoringModifiers` when the literal is
-    /// empty (dead keys, pure modifiers) — using both unconditionally would leak the base-layer
-    /// digit (Nordic Option+0 reports characters="=" but ignoringModifiers="0") and falsely
-    /// fire the zoom-reset binding.
+    /// Resolves the glyph with the same rule the recorder uses (`recordedCharacter`) so a
+    /// keypress at dispatch produces exactly the glyph its binding was indexed under. That
+    /// rule prefers the literal `characters` (carries Option/AltGr and Shift symbols) but
+    /// rejects control codes and empties — using the literal unconditionally would both leak
+    /// the base-layer digit (Nordic Option+0 reports characters="=" but ignoringModifiers="0",
+    /// falsely firing zoom-reset) and emit control codes for Ctrl combos.
     static func producedChars(characters: String?, ignoringModifiers: String?) -> Set<String> {
-        let literal = (characters ?? "").lowercased()
-        let base = literal.isEmpty ? (ignoringModifiers ?? "").lowercased() : literal
-        guard !base.isEmpty else { return [] }
-        return expand([base])
+        let glyph = recordedCharacter(literal: characters, ignoringModifiers: ignoringModifiers)
+        guard !glyph.isEmpty else { return [] }
+        return expand([glyph])
     }
 
     /// Glyph to persist when recording a chord, kept symmetric with `producedChars` so a
diff --git a/FlowVision/Sources/Shortcuts/ShortcutStore.swift b/FlowVision/Sources/Shortcuts/ShortcutStore.swift
index 6b8966e8..8ec0cc6d 100644
--- a/FlowVision/Sources/Shortcuts/ShortcutStore.swift
+++ b/FlowVision/Sources/Shortcuts/ShortcutStore.swift
@@ -21,10 +21,13 @@ final class ShortcutStore {
     /// disjoint — enforced by conflict UI in the settings pane, not by the store).
     private(set) var reverseIndex: [KeyChord: [ShortcutAction]] = [:]
 
-    /// Layout-aware fallback index keyed on produced glyph rather than physical keyCode.
-    /// Consulted only when `reverseIndex` misses, so it never overrides a physical match
-    /// (zero regression for US/ANSI and Dvorak/Colemak). Fixes ISO layouts where +, -, =
-    /// move physical position or sit behind Option/AltGr. See issue #16 / ShortcutMatching.
+    /// Layout-aware index keyed on produced glyph rather than physical keyCode. The dispatcher
+    /// consults this *before* `reverseIndex` and lets a glyph match win (see
+    /// `ShortcutMatching.order`), because on ISO layouts the physical key under a moved symbol
+    /// is often bound to the opposite action. Fixes issue #16 (+, -, = move position or sit
+    /// behind Option/AltGr). On US/ANSI glyph and keyCode agree, so behavior is unchanged —
+    /// except shifted symbols now resolve too (e.g. Shift+= → '+' → '=' → zoom-in), which the
+    /// keyCode-only path could not match.
     private(set) var semanticIndex: [ShortcutMatching.SemKey: [ShortcutAction]] = [:]
 
     /// Actions the user has wiped completely. Distinguishes "user cleared all"
@@ -223,8 +226,9 @@ final class ShortcutStore {
         semanticIndex = sem
     }
 
-    /// Layout-aware fallback lookup. Returns actions whose recorded glyph matches one of
-    /// the glyphs this key event produced. Call only after `reverseIndex` misses.
+    /// Layout-aware lookup. Returns actions whose recorded glyph matches one of the glyphs
+    /// this key event produced. The dispatcher merges these ahead of `reverseIndex` matches
+    /// via `ShortcutMatching.order`.
     func semanticCandidates(characters: String?,
                             ignoringModifiers: String?,
                             modifiers: Modifiers) -> [ShortcutAction] {
diff --git a/FlowVision/Sources/ViewControllerExtension/KeyShortcut.swift b/FlowVision/Sources/ViewControllerExtension/KeyShortcut.swift
index a3774f96..0d9fa61f 100644
--- a/FlowVision/Sources/ViewControllerExtension/KeyShortcut.swift
+++ b/FlowVision/Sources/ViewControllerExtension/KeyShortcut.swift
@@ -42,8 +42,10 @@ extension ViewController {
         // Layout-aware matching. The glyph the key actually produced (semantic) outranks
         // the physical keyCode: on ISO layouts the physical key under a moved symbol is
         // often bound to the opposite action — e.g. Norwegian '+' sits on the US '-' key,
-        // whose keyCode is bound to zoom-out (issue #16). On US/ANSI both agree, so this is
-        // a no-op there and for special keys (no glyph) it falls through to physical.
+        // whose keyCode is bound to zoom-out (issue #16). On US/ANSI glyph and keyCode agree
+        // (so existing bindings are unchanged), but shifted symbols now resolve too — e.g.
+        // Shift+= → '+' → '=' → zoom-in, which keyCode-only matching missed. Special keys
+        // (no glyph) yield no semantic candidates and fall through to physical.
         let semantic = ShortcutStore.shared.semanticCandidates(
             characters: event.characters,
             ignoringModifiers: event.charactersIgnoringModifiers,

From f331a5a8b2eec0f5f3e8d9b716fdce41b1349a1a Mon Sep 17 00:00:00 2001
From: lenisko <10072920+lenisko@users.noreply.github.com>
Date: Tue, 2 Jun 2026 14:09:02 +0200
Subject: [PATCH 7/7] chore: drop docs/superpowers from tree and ignore it

---
 .gitignore                                    |    3 +-
 .../plans/2026-05-23-startup-perf.md          | 1203 -----------------
 .../specs/2026-05-23-startup-perf-design.md   |  204 ---
 3 files changed, 2 insertions(+), 1408 deletions(-)
 delete mode 100644 docs/superpowers/plans/2026-05-23-startup-perf.md
 delete mode 100644 docs/superpowers/specs/2026-05-23-startup-perf-design.md

diff --git a/.gitignore b/.gitignore
index cdd0b098..125b730f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,2 +1,3 @@
 xcuserdata/
-LocalDev.xcconfig
\ No newline at end of file
+LocalDev.xcconfig
+docs/superpowers/
\ No newline at end of file
diff --git a/docs/superpowers/plans/2026-05-23-startup-perf.md b/docs/superpowers/plans/2026-05-23-startup-perf.md
deleted file mode 100644
index e107d7b5..00000000
--- a/docs/superpowers/plans/2026-05-23-startup-perf.md
+++ /dev/null
@@ -1,1203 +0,0 @@
-# FlowVision Startup Performance Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Reduce time from Finder "Open With → FlowVision" click to large-image visible, instrumented and verified end-to-end.
-
-**Architecture:** Stage 1 lands `os_signpost`-based timing for named startup spans and captures a baseline. Stage 2 applies six independent, ordered fix units (defaults batch read, AppDelegate slimming, viewDidLoad pruning, storyboard split, launch-from-file fast path, framework warm/linker audit) each behind a `globalVar.fastStartupEnabled` flag with per-unit revert gate.
-
-**Tech Stack:** Swift (project deploys macOS 11.0+), AppKit, `os_signpost` (C API, available 10.14+), `OSSignposter` (12+ optional). No new dependencies.
-
-**Spec:** `docs/superpowers/specs/2026-05-23-startup-perf-design.md`
-
----
-
-## File Structure
-
-### New files
-
-| Path | Responsibility |
-|---|---|
-| `FlowVision/Sources/Common/StartupTiming.swift` | Span IDs enum + `spBegin/spEnd/spMeasure` helpers using `os_signpost` and `log()` |
-| `FlowVision/Sources/Common/StartupDefaults.swift` | `AppStartupDefaults` struct batched-read from `UserDefaults.dictionaryRepresentation()`, applies to `globalVar` |
-| `FlowVision/Sources/Common/StartupBootstrap.swift` | Off-main bootstrap: FinderTag labels, FFmpeg warm |
-| `docs/superpowers/specs/2026-05-23-startup-perf-baseline.md` | Captured median timings before/after each fix unit |
-
-### Modified files
-
-| Path | Why |
-|---|---|
-| `FlowVision/Sources/AppDelegate.swift` | Wrap launch hooks in spans (T1); slim `applicationWillFinishLaunching` (T2, T3); fast path `createNewWindow_FastPath` (T7) |
-| `FlowVision/Sources/ViewController.swift` | Wrap `viewDidLoad` in span (T1); pull defaults from `globalVar` (T2); split deferred UI into `setupDeferredUI()` (T5) |
-| `FlowVision/Sources/ViewControllerExtension/LargeImage.swift` | Background decode on Finder open (T7) |
-| `FlowVision/Sources/Common/GlobalVariable.swift` | Add `fastStartupEnabled` flag (T2 prep); `THUMB_SIZES` lazy (T3) |
-| `FlowVision/Sources/Common/FFmpegKit.swift` | Add `warmLoadAfterDelay(seconds:)` (T8) |
-| `FlowVision/Sources/Common/FinderTag.swift` | Allow `EnhancedIndex` and custom-labels load to be invoked off-main from `StartupBootstrap` (T3) |
-| `FlowVision/FlowVision.xcodeproj/project.pbxproj` | Add new Swift files to target (every new file task) |
-| `FlowVision/Base.xcconfig` (or project Release config) | `DEAD_CODE_STRIPPING = YES` (T8) |
-
----
-
-## Task 1 — Add startup timing instrumentation
-
-**Files:**
-- Create: `FlowVision/Sources/Common/StartupTiming.swift`
-- Modify: `FlowVision/Sources/AppDelegate.swift` (lines 64, 250, 254, 276, 343–415)
-- Modify: `FlowVision/Sources/ViewController.swift` (lines 444, 853, 956)
-- Modify: `FlowVision/Sources/ViewControllerExtension/LargeImage.swift` (line 469)
-- Modify: `FlowVision/Sources/ViewControllerExtension/FileSystem.swift` (line 1031)
-- Modify: `FlowVision/FlowVision.xcodeproj/project.pbxproj` (add new file to target)
-
-### - [ ] Step 1.1: Create `StartupTiming.swift`
-
-```swift
-//
-//  StartupTiming.swift
-//  FlowVision
-//
-
-import Foundation
-import os.log
-import os.signpost
-
-enum StartupSpan: String {
-    case appWillFinish              = "app.willFinish"
-    case appWillFinishDefaultsLoad  = "app.willFinish.defaultsLoad"
-    case appDidFinish               = "app.didFinish"
-    case windowCreate               = "window.create"
-    case windowStoryboardInstantiate = "window.storyboardInstantiate"
-    case vcViewDidLoad              = "vc.viewDidLoad"
-    case vcViewDidLoadDefaultsLoad  = "vc.viewDidLoad.defaultsLoad"
-    case fileOpenFromFinderTotal    = "file.openFromFinder.total"
-    case fileOpenLargeImageDecode   = "file.openLargeImage.decode"
-    case fileSwitchDirScan          = "file.switchDir.scan"
-}
-
-private let startupLog = OSLog(subsystem: "app.flowvision.startup", category: .pointsOfInterest)
-
-private struct SpanState {
-    var startAbs: CFAbsoluteTime
-    var signpostID: OSSignpostID
-}
-
-private var activeSpans: [String: SpanState] = [:]
-private let spanLock = NSLock()
-
-@inline(__always)
-func spBegin(_ span: StartupSpan) {
-    let id = OSSignpostID(log: startupLog)
-    spanLock.lock()
-    activeSpans[span.rawValue] = SpanState(startAbs: CFAbsoluteTimeGetCurrent(), signpostID: id)
-    spanLock.unlock()
-    os_signpost(.begin, log: startupLog, name: "Span", signpostID: id, "%{public}s", span.rawValue)
-    log("[startup] begin \(span.rawValue)")
-}
-
-@inline(__always)
-func spEnd(_ span: StartupSpan) {
-    spanLock.lock()
-    let state = activeSpans.removeValue(forKey: span.rawValue)
-    spanLock.unlock()
-    guard let state = state else {
-        log("[startup] WARN spEnd without begin: \(span.rawValue)", level: .warn)
-        return
-    }
-    let elapsedMs = (CFAbsoluteTimeGetCurrent() - state.startAbs) * 1000.0
-    os_signpost(.end, log: startupLog, name: "Span", signpostID: state.signpostID, "%{public}s", span.rawValue)
-    log(String(format: "[startup] end   %@  %.2f ms", span.rawValue, elapsedMs))
-}
-
-@inline(__always)
-func spMeasure<T>(_ span: StartupSpan, _ body: () throws -> T) rethrows -> T {
-    spBegin(span)
-    defer { spEnd(span) }
-    return try body()
-}
-```
-
-### - [ ] Step 1.2: Add file to Xcode target
-
-Open `FlowVision.xcodeproj` in Xcode → drag `StartupTiming.swift` from `Sources/Common/` into the FlowVision target. Verify Target Membership checkbox is checked.
-
-Alternative CLI: use `xcodeproj` Ruby gem or edit `project.pbxproj` by mirroring an existing file's `PBXFileReference` + `PBXBuildFile` + `PBXSourcesBuildPhase` entries. Verify build succeeds: `xcodebuild -project FlowVision.xcodeproj -scheme FlowVision build`.
-
-### - [ ] Step 1.3: Wrap `applicationWillFinishLaunching`
-
-Modify `FlowVision/Sources/AppDelegate.swift` line 64–252.
-
-Replace the opening line (currently `log("Start applicationWillFinishLaunching")`) with `spBegin(.appWillFinish)`. Replace the closing `log("End applicationWillFinishLaunching")` with `spEnd(.appWillFinish)`.
-
-Wrap the defaults-loading block (lines 96–225, starting at `let defaults = UserDefaults.standard` through the last `if let collectionViewItemShowTooltip ...`) by inserting `spBegin(.appWillFinishDefaultsLoad)` just before line 96 and `spEnd(.appWillFinishDefaultsLoad)` just after line 225.
-
-### - [ ] Step 1.4: Wrap `applicationDidFinishLaunching`
-
-Modify `FlowVision/Sources/AppDelegate.swift` line 254–278.
-
-Replace `log("Start applicationDidFinishLaunching")` with `spBegin(.appDidFinish)`. Replace `log("End applicationDidFinishLaunching")` with `spEnd(.appDidFinish)`.
-
-### - [ ] Step 1.5: Wrap `createNewWindow`
-
-Modify `FlowVision/Sources/AppDelegate.swift` line 343–416.
-
-Replace `log("Start createNewWindow")` (line 344) with `spBegin(.windowCreate)`. Add `defer { spEnd(.windowCreate) }` immediately after.
-
-Wrap the storyboard instantiation:
-
-```swift
-let windowController = spMeasure(.windowStoryboardInstantiate) { () -> WindowController in
-    let storyboard = NSStoryboard(name: "Main", bundle: nil)
-    guard let wc = storyboard.instantiateController(withIdentifier: "WindowController") as? WindowController else {
-        fatalError("Cannot find WindowController in Main.storyboard")
-    }
-    return wc
-}
-```
-
-(Replace existing lines 381–387 which currently do this in two statements.)
-
-### - [ ] Step 1.6: Wrap `viewDidLoad`
-
-Modify `FlowVision/Sources/ViewController.swift` line 444–856.
-
-Replace `log("Start viewDidLoad")` (line 447) with `spBegin(.vcViewDidLoad)`. Replace `log("End viewDidLoad")` (line 853) with `spEnd(.vcViewDidLoad)`.
-
-Wrap the defaults block (lines 538–597, starting at `if let isLargeImageFitWindow ...` through the `publicVar.profile = CustomProfile.loadFromUserDefaults(...)` line): insert `spBegin(.vcViewDidLoadDefaultsLoad)` before line 538 and `spEnd(.vcViewDidLoadDefaultsLoad)` after line 597.
-
-### - [ ] Step 1.7: Add `fileOpenFromFinderTotal` span
-
-Modify `FlowVision/Sources/AppDelegate.swift` `application(_:openFiles:)` (line 424).
-
-Just after line 425 (`NSApplication.shared.reply(toOpenOrPrint: .success)`), add:
-
-```swift
-spBegin(.fileOpenFromFinderTotal)
-```
-
-Then in `FlowVision/Sources/ViewControllerExtension/LargeImage.swift` `OpenLargeImageFromFinder(path:)` line 469, immediately after the function body's final statement (after line 487), add:
-
-```swift
-// Mark Finder-launch first frame
-DispatchQueue.main.async {
-    spEnd(.fileOpenFromFinderTotal)
-}
-```
-
-The `main.async` defers `spEnd` until after AppKit commits the frame so we capture the user-visible moment, not the function-return moment.
-
-### - [ ] Step 1.8: Wrap `OpenLargeImageFromFinder` decode
-
-Modify `FlowVision/Sources/ViewControllerExtension/LargeImage.swift` line 469–488.
-
-Wrap the body in:
-
-```swift
-func OpenLargeImageFromFinder(path: String){
-    spBegin(.fileOpenLargeImageDecode)
-    defer { spEnd(.fileOpenLargeImageDecode) }
-    // ... existing body unchanged ...
-}
-```
-
-### - [ ] Step 1.9: Wrap `switchDirByDirection`
-
-Modify `FlowVision/Sources/ViewControllerExtension/FileSystem.swift` line 1031.
-
-Add at function start:
-
-```swift
-spBegin(.fileSwitchDirScan)
-defer { spEnd(.fileSwitchDirScan) }
-```
-
-### - [ ] Step 1.10: Build
-
-Run: `xcodebuild -project FlowVision.xcodeproj -scheme FlowVision -configuration Debug build CODE_SIGN_IDENTITY="" CODE_SIGNING_REQUIRED=NO`
-
-Expected: BUILD SUCCEEDED. If errors, fix and re-build.
-
-### - [ ] Step 1.11: Verify spans log
-
-Launch the built `.app` by opening a PNG with it from Finder. Check `~/Library/Logs/FlowVision/` (or wherever `log()` writes; check `Log.swift`). Confirm lines like `[startup] begin app.willFinish` and `[startup] end app.willFinish 32.10 ms` appear.
-
-### - [ ] Step 1.12: Commit
-
-```bash
-git add FlowVision/Sources/Common/StartupTiming.swift \
-        FlowVision/Sources/AppDelegate.swift \
-        FlowVision/Sources/ViewController.swift \
-        FlowVision/Sources/ViewControllerExtension/LargeImage.swift \
-        FlowVision/Sources/ViewControllerExtension/FileSystem.swift \
-        FlowVision/FlowVision.xcodeproj/project.pbxproj
-git commit -m "feat: instrument startup spans for perf measurement"
-```
-
----
-
-## Task 2 — Capture baseline + add fastStartupEnabled flag
-
-**Files:**
-- Modify: `FlowVision/Sources/Common/GlobalVariable.swift` (line 107 area)
-- Modify: `FlowVision/Sources/AppDelegate.swift` (lines 220-225 area, defaults block)
-- Create: `docs/superpowers/specs/2026-05-23-startup-perf-baseline.md`
-
-### - [ ] Step 2.1: Add `fastStartupEnabled` to `GlobalVar`
-
-Modify `FlowVision/Sources/Common/GlobalVariable.swift` after line 107 (after `collectionViewItemShowTooltip`):
-
-```swift
-var fastStartupEnabled = true
-```
-
-### - [ ] Step 2.2: Wire default into AppDelegate
-
-Modify `FlowVision/Sources/AppDelegate.swift` inside the defaults block (after line 224, the `collectionViewItemShowTooltip` block):
-
-```swift
-if let fastStartupEnabled = UserDefaults.standard.value(forKey: "fastStartupEnabled") as? Bool {
-    globalVar.fastStartupEnabled = fastStartupEnabled
-}
-```
-
-### - [ ] Step 2.3: Capture baseline
-
-Build Release: `xcodebuild -project FlowVision.xcodeproj -scheme FlowVision -configuration Release build CODE_SIGN_IDENTITY="" CODE_SIGNING_REQUIRED=NO`
-
-For each file type in {PNG, JPG, HEIC, RAW CR2, RAW NEF, animated GIF, WEBP, MP4 video}:
-1. `killall FlowVision; sleep 30`
-2. `open -a <built-app-path> <sample-file>` 5 times
-3. Record `file.openFromFinder.total` median from log lines.
-
-Also capture: `app.willFinish`, `app.willFinish.defaultsLoad`, `app.didFinish`, `window.create`, `window.storyboardInstantiate`, `vc.viewDidLoad`, `vc.viewDidLoad.defaultsLoad`, `file.openLargeImage.decode`, `file.switchDir.scan` medians (use PNG run for these — they're not file-type-dependent).
-
-### - [ ] Step 2.4: Write baseline doc
-
-Create `docs/superpowers/specs/2026-05-23-startup-perf-baseline.md` with a table:
-
-```markdown
-# Startup Perf Baseline (2026-05-23)
-
-Hardware: <model, CPU, RAM>
-macOS: <version>
-Build: Release, commit <sha>
-
-## file.openFromFinder.total (ms, median of 5 cold runs)
-
-| Type | Median |
-|---|---|
-| PNG  | … |
-| JPG  | … |
-| HEIC | … |
-| CR2  | … |
-| NEF  | … |
-| GIF  | … |
-| WEBP | … |
-| MP4  | … |
-
-## Per-span medians (PNG cold launch)
-
-| Span | Median (ms) |
-|---|---|
-| app.willFinish | … |
-| app.willFinish.defaultsLoad | … |
-| app.didFinish | … |
-| window.create | … |
-| window.storyboardInstantiate | … |
-| vc.viewDidLoad | … |
-| vc.viewDidLoad.defaultsLoad | … |
-| file.openLargeImage.decode | … |
-| file.switchDir.scan | … |
-```
-
-Fill in actual numbers from Step 2.3.
-
-### - [ ] Step 2.5: Commit
-
-```bash
-git add FlowVision/Sources/Common/GlobalVariable.swift \
-        FlowVision/Sources/AppDelegate.swift \
-        docs/superpowers/specs/2026-05-23-startup-perf-baseline.md
-git commit -m "feat: add fastStartupEnabled flag; record baseline"
-```
-
----
-
-## Task 3 — Fix unit 1: batched defaults read
-
-Replaces 60+ individual `value(forKey:)` calls with a single `dictionaryRepresentation()` fetch.
-
-**Files:**
-- Create: `FlowVision/Sources/Common/StartupDefaults.swift`
-- Modify: `FlowVision/Sources/AppDelegate.swift` (lines 96–225)
-- Modify: `FlowVision/Sources/ViewController.swift` (lines 538–597)
-- Modify: `FlowVision.xcodeproj/project.pbxproj`
-
-### - [ ] Step 3.1: Create `StartupDefaults.swift`
-
-```swift
-//
-//  StartupDefaults.swift
-//  FlowVision
-//
-
-import Foundation
-
-struct AppStartupDefaults {
-    // GlobalVar keys (loaded in applicationWillFinishLaunching)
-    var appearance: String?
-    var openLastFolder: Bool?
-    var homeFolder: String?
-    var hasNormalExit: Bool?
-    var isFirstTimeUse: Bool?
-    var terminateAfterLastWindowClosed: Bool?
-    var autoHideToolbar: Bool?
-    var autoHideCursorWhenFullscreen: Bool?
-    var randomFolderThumb: Bool?
-    var thumbnailOfFolderUseStacking: Bool?
-    var loopBrowsing: Bool?
-    var blackBgInFullScreen: Bool?
-    var blackBgAlways: Bool?
-    var blackBgInFullScreenForVideo: Bool?
-    var blackBgAlwaysForVideo: Bool?
-    var thumbnailExcludeList: [String]?
-    var usePinyinSearch: Bool?
-    var usePinyinInitialSearch: Bool?
-    var memUseLimit: Int?
-    var thumbThreadNum: Int?
-    var folderSearchDepth: Int?
-    var thumbThreadNum_External: Int?
-    var folderSearchDepth_External: Int?
-    var doNotUseFFmpeg: Bool?
-    var videoPlayRememberPosition: Bool?
-    var videoPlaySequentialPlay: Bool?
-    var videoVolume: Float?
-    var videoPlaybackRate: Float?
-    var useInternalPlayer: Bool?
-    var isEnterKeyToOpen: Bool?
-    var clickEdgeToSwitchImage: Bool?
-    var scrollMouseWheelToZoom: Bool?
-    var scrollSensitivity: Double?
-    var keepFilterStateWhenSwitchFolder: Bool?
-    var dirTreeAutoExpand: Bool?
-    var largeImageViewShowTagsAndRating: Bool?
-    var enhancedIndexEnabled: Bool?
-    var collectionViewItemShowTooltip: Bool?
-    var fastStartupEnabled: Bool?
-    var myFavoritesArray: [String]?
-    var customTagLabels: [[String: Any]]?
-
-    // publicVar keys (loaded in ViewController.viewDidLoad)
-    var isLargeImageFitWindow: Bool?
-    var isShowHiddenFile: Bool?
-    var isShowImageFile: Bool?
-    var isShowRawFile: Bool?
-    var isShowAllTypeFile: Bool?
-    var isShowVideoFile: Bool?
-    var isGenHdThumb: Bool?
-    var isPreferInternalThumb: Bool?
-    var isEnableHDR: Bool?
-    var isRawUseEmbeddedThumb: Bool?
-    var isRecursiveContainFolder: Bool?
-    var autoPlayVisibleVideo: Bool?
-    var autoPlaySelectedVideo: Bool?
-    var isRotationLocked: Bool?
-    var isZoomLocked: Bool?
-    var isMirrorLocked: Bool?
-    var isPanWhenZoomed: Bool?
-    var currentTag: String?
-
-    static func load() -> AppStartupDefaults {
-        let dict = UserDefaults.standard.dictionaryRepresentation()
-        var d = AppStartupDefaults()
-        d.appearance                       = dict["appearance"]                        as? String
-        d.openLastFolder                   = dict["openLastFolder"]                    as? Bool
-        d.homeFolder                       = dict["homeFolder"]                        as? String
-        d.hasNormalExit                    = dict["hasNormalExit"]                     as? Bool
-        d.isFirstTimeUse                   = dict["isFirstTimeUse"]                    as? Bool
-        d.terminateAfterLastWindowClosed   = dict["terminateAfterLastWindowClosed"]    as? Bool
-        d.autoHideToolbar                  = dict["autoHideToolbar"]                   as? Bool
-        d.autoHideCursorWhenFullscreen     = dict["autoHideCursorWhenFullscreen"]      as? Bool
-        d.randomFolderThumb                = dict["randomFolderThumb"]                 as? Bool
-        d.thumbnailOfFolderUseStacking     = dict["thumbnailOfFolderUseStacking"]      as? Bool
-        d.loopBrowsing                     = dict["loopBrowsing"]                      as? Bool
-        d.blackBgInFullScreen              = dict["blackBgInFullScreen"]               as? Bool
-        d.blackBgAlways                    = dict["blackBgAlways"]                     as? Bool
-        d.blackBgInFullScreenForVideo      = dict["blackBgInFullScreenForVideo"]       as? Bool
-        d.blackBgAlwaysForVideo            = dict["blackBgAlwaysForVideo"]             as? Bool
-        d.thumbnailExcludeList             = dict["thumbnailExcludeList"]              as? [String]
-        d.usePinyinSearch                  = dict["usePinyinSearch"]                   as? Bool
-        d.usePinyinInitialSearch           = dict["usePinyinInitialSearch"]            as? Bool
-        d.memUseLimit                      = dict["memUseLimit"]                       as? Int
-        d.thumbThreadNum                   = dict["thumbThreadNum"]                    as? Int
-        d.folderSearchDepth                = dict["folderSearchDepth"]                 as? Int
-        d.thumbThreadNum_External          = dict["thumbThreadNum_External"]           as? Int
-        d.folderSearchDepth_External       = dict["folderSearchDepth_External"]        as? Int
-        d.doNotUseFFmpeg                   = dict["doNotUseFFmpeg"]                    as? Bool
-        d.videoPlayRememberPosition        = dict["videoPlayRememberPosition"]         as? Bool
-        d.videoPlaySequentialPlay          = dict["videoPlaySequentialPlay"]           as? Bool
-        d.videoVolume                      = dict["videoVolume"]                       as? Float
-        d.videoPlaybackRate                = dict["videoPlaybackRate"]                 as? Float
-        d.useInternalPlayer                = dict["useInternalPlayer"]                 as? Bool
-        d.isEnterKeyToOpen                 = dict["isEnterKeyToOpen"]                  as? Bool
-        d.clickEdgeToSwitchImage           = dict["clickEdgeToSwitchImage"]            as? Bool
-        d.scrollMouseWheelToZoom           = dict["scrollMouseWheelToZoom"]            as? Bool
-        d.scrollSensitivity                = dict["scrollSensitivity"]                 as? Double
-        d.keepFilterStateWhenSwitchFolder  = dict["keepFilterStateWhenSwitchFolder"]   as? Bool
-        d.dirTreeAutoExpand                = dict["dirTreeAutoExpand"]                 as? Bool
-        d.largeImageViewShowTagsAndRating  = dict["largeImageViewShowTagsAndRating"]   as? Bool
-        d.enhancedIndexEnabled             = dict["enhancedIndexEnabled"]              as? Bool
-        d.collectionViewItemShowTooltip    = dict["collectionViewItemShowTooltip"]     as? Bool
-        d.fastStartupEnabled               = dict["fastStartupEnabled"]                as? Bool
-        d.myFavoritesArray                 = dict["globalVar.myFavoritesArray"]        as? [String]
-        d.customTagLabels                  = dict[CustomTagView.userDefaultsKey]       as? [[String: Any]]
-        d.isLargeImageFitWindow            = dict["isLargeImageFitWindow"]             as? Bool
-        d.isShowHiddenFile                 = dict["isShowHiddenFile"]                  as? Bool
-        d.isShowImageFile                  = dict["isShowImageFile"]                   as? Bool
-        d.isShowRawFile                    = dict["isShowRawFile"]                     as? Bool
-        d.isShowAllTypeFile                = dict["isShowAllTypeFile"]                 as? Bool
-        d.isShowVideoFile                  = dict["isShowVideoFile"]                   as? Bool
-        d.isGenHdThumb                     = dict["isGenHdThumb"]                      as? Bool
-        d.isPreferInternalThumb            = dict["isPreferInternalThumb"]             as? Bool
-        d.isEnableHDR                      = dict["isEnableHDR"]                       as? Bool
-        d.isRawUseEmbeddedThumb            = dict["isRawUseEmbeddedThumb"]             as? Bool
-        d.isRecursiveContainFolder         = dict["isRecursiveContainFolder"]          as? Bool
-        d.autoPlayVisibleVideo             = dict["autoPlayVisibleVideo"]              as? Bool
-        d.autoPlaySelectedVideo            = dict["autoPlaySelectedVideo"]             as? Bool
-        d.isRotationLocked                 = dict["isRotationLocked"]                  as? Bool
-        d.isZoomLocked                     = dict["isZoomLocked"]                      as? Bool
-        d.isMirrorLocked                   = dict["isMirrorLocked"]                    as? Bool
-        d.isPanWhenZoomed                  = dict["isPanWhenZoomed"]                   as? Bool
-        d.currentTag                       = dict["currentTag"]                        as? String
-        return d
-    }
-
-    func applyToGlobalVar() {
-        if let v = openLastFolder                  { globalVar.openLastFolder = v }
-        if let v = homeFolder                      { globalVar.homeFolder = v }
-        if let v = isFirstTimeUse                  { globalVar.isFirstTimeUse = v }
-        if let v = terminateAfterLastWindowClosed  { globalVar.terminateAfterLastWindowClosed = v }
-        if let v = autoHideToolbar                 { globalVar.autoHideToolbar = v }
-        if let v = autoHideCursorWhenFullscreen    { globalVar.autoHideCursorWhenFullscreen = v }
-        if let v = randomFolderThumb               { globalVar.randomFolderThumb = v }
-        if let v = thumbnailOfFolderUseStacking    { globalVar.thumbnailOfFolderUseStacking = v }
-        if let v = loopBrowsing                    { globalVar.loopBrowsing = v }
-        if let v = blackBgInFullScreen             { globalVar.blackBgInFullScreen = v }
-        if let v = blackBgAlways                   { globalVar.blackBgAlways = v }
-        if let v = blackBgInFullScreenForVideo     { globalVar.blackBgInFullScreenForVideo = v }
-        if let v = blackBgAlwaysForVideo           { globalVar.blackBgAlwaysForVideo = v }
-        if let v = thumbnailExcludeList            { globalVar.thumbnailExcludeList = v }
-        if let v = usePinyinSearch                 { globalVar.usePinyinSearch = v }
-        if let v = usePinyinInitialSearch          { globalVar.usePinyinInitialSearch = v }
-        if let v = memUseLimit                     { globalVar.memUseLimit = v }
-        if let v = thumbThreadNum                  { globalVar.thumbThreadNum = v }
-        if let v = folderSearchDepth               { globalVar.folderSearchDepth = v }
-        if let v = thumbThreadNum_External         { globalVar.thumbThreadNum_External = v }
-        if let v = folderSearchDepth_External      { globalVar.folderSearchDepth_External = v }
-        if let v = doNotUseFFmpeg                  { globalVar.doNotUseFFmpeg = v }
-        if let v = videoPlayRememberPosition       { globalVar.videoPlayRememberPosition = v }
-        if let v = videoPlaySequentialPlay         { globalVar.videoPlaySequentialPlay = v }
-        if let v = videoVolume                     { globalVar.videoVolume = v }
-        if let v = videoPlaybackRate               { globalVar.videoPlaybackRate = v }
-        if let v = useInternalPlayer              { globalVar.useInternalPlayer = v }
-        if let v = isEnterKeyToOpen                { globalVar.isEnterKeyToOpen = v }
-        if let v = clickEdgeToSwitchImage          { globalVar.clickEdgeToSwitchImage = v }
-        if let v = scrollMouseWheelToZoom          { globalVar.scrollMouseWheelToZoom = v }
-        if let v = scrollSensitivity               { globalVar.scrollSensitivity = v }
-        if let v = keepFilterStateWhenSwitchFolder { globalVar.keepFilterStateWhenSwitchFolder = v }
-        if let v = dirTreeAutoExpand               { globalVar.dirTreeAutoExpand = v }
-        if let v = largeImageViewShowTagsAndRating { globalVar.largeImageViewShowTagsAndRating = v }
-        if let v = enhancedIndexEnabled            { globalVar.enhancedIndexEnabled = v }
-        if let v = collectionViewItemShowTooltip   { globalVar.collectionViewItemShowTooltip = v }
-        if let v = fastStartupEnabled              { globalVar.fastStartupEnabled = v }
-        globalVar.myFavoritesArray = myFavoritesArray ?? [String]()
-    }
-
-    func applyToPublicVar(_ publicVar: PublicVar) {
-        if let v = isLargeImageFitWindow    { publicVar.isLargeImageFitWindow = v }
-        if let v = isShowHiddenFile         { publicVar.isShowHiddenFile = v }
-        if let v = isShowImageFile          { publicVar.isShowImageFile = v }
-        if let v = isShowRawFile            { publicVar.isShowRawFile = v }
-        if let v = isShowAllTypeFile        { publicVar.isShowAllTypeFile = v }
-        if let v = isShowVideoFile          { publicVar.isShowVideoFile = v }
-        if let v = isGenHdThumb             { publicVar.isGenHdThumb = v }
-        if let v = isPreferInternalThumb    { publicVar.isPreferInternalThumb = v }
-        if let v = isEnableHDR              { publicVar.isEnableHDR = v }
-        if let v = isRawUseEmbeddedThumb    { publicVar.isRawUseEmbeddedThumb = v }
-        if let v = isRecursiveContainFolder { publicVar.isRecursiveContainFolder = v }
-        if let v = autoPlayVisibleVideo     { publicVar.autoPlayVisibleVideo = v }
-        if let v = autoPlaySelectedVideo    { publicVar.autoPlaySelectedVideo = v }
-        if let v = isRotationLocked         { publicVar.isRotationLocked = v }
-        if let v = isZoomLocked             { publicVar.isZoomLocked = v }
-        if let v = isMirrorLocked           { publicVar.isMirrorLocked = v }
-        if let v = isPanWhenZoomed          { publicVar.isPanWhenZoomed = v }
-        if let v = currentTag               { publicVar.currentTag = v }
-    }
-}
-
-// Singleton cache so ViewController can reuse data already pulled by AppDelegate.
-final class StartupDefaultsCache {
-    static let shared = StartupDefaultsCache()
-    private(set) var loaded: AppStartupDefaults?
-    private let lock = NSLock()
-
-    func loadIfNeeded() -> AppStartupDefaults {
-        lock.lock()
-        defer { lock.unlock() }
-        if let l = loaded { return l }
-        let d = AppStartupDefaults.load()
-        loaded = d
-        return d
-    }
-}
-```
-
-Note: `PublicVar` type name must match the actual nested type used inside `ViewController` (verify by grep before editing — adjust the parameter type if it's named differently).
-
-### - [ ] Step 3.2: Verify `PublicVar` type name
-
-Run: `grep -n "class PublicVar\|class publicVar\|var publicVar:" FlowVision/Sources/ViewController.swift | head -5`
-
-If actual name differs, adjust `StartupDefaults.swift` `applyToPublicVar(_:)` parameter type accordingly. Re-run grep before continuing.
-
-### - [ ] Step 3.3: Add `StartupDefaults.swift` to Xcode target
-
-Drag file into FlowVision target (or edit `project.pbxproj`). Build: `xcodebuild -project FlowVision.xcodeproj -scheme FlowVision build`. Expect: BUILD SUCCEEDED.
-
-### - [ ] Step 3.4: Replace defaults block in `applicationWillFinishLaunching`
-
-Modify `FlowVision/Sources/AppDelegate.swift`. Inside the block currently spanned by `spBegin(.appWillFinishDefaultsLoad)` / `spEnd(.appWillFinishDefaultsLoad)`:
-
-Replace the entire region from `let defaults = UserDefaults.standard` (line 96) through the closing `}` of the last `if let collectionViewItemShowTooltip ...` (line 225) — plus the existing `globalVar.fastStartupEnabled` block added in Task 2 — with:
-
-```swift
-if globalVar.fastStartupEnabled {
-    let d = StartupDefaultsCache.shared.loadIfNeeded()
-
-    if d.appearance == "darkAqua" {
-        NSApp.appearance = NSAppearance(named: .darkAqua)
-    } else if d.appearance == "aqua" {
-        NSApp.appearance = NSAppearance(named: .aqua)
-    } else {
-        NSApp.appearance = nil
-    }
-
-    if let hasNormalExit = d.hasNormalExit, !hasNormalExit {
-        UserDefaults.standard.set("file:///", forKey: "lastFolder")
-        globalVar.homeFolder = "file:///"
-    }
-    UserDefaults.standard.set(false, forKey: "hasNormalExit")
-
-    d.applyToGlobalVar()
-
-    if let savedLabels = d.customTagLabels {
-        FinderTag.customLabels = savedLabels.compactMap { dict in
-            guard let name = dict["name"] as? String else { return nil }
-            return (name, dict["colorIndex"] as? Int)
-        }
-    } else {
-        FinderTag.customLabels = FinderTag.systemColorLabels.map { ($0.name, $0.colorIndex) }
-    }
-} else {
-    // legacy path — keep original lines 96–235 unchanged here for rollback
-    // (copy original block back inside this else for safety)
-}
-```
-
-For the `else` branch, paste the original lines 96–235 verbatim (the legacy individual `value(forKey:)` reads + `FinderTag` block) so toggling the flag fully restores old behavior. This is the only place we keep duplication; it's removed in cleanup after one stable release per spec §8.
-
-### - [ ] Step 3.5: Replace defaults block in `ViewController.viewDidLoad`
-
-Modify `FlowVision/Sources/ViewController.swift`. Inside the block spanned by `spBegin(.vcViewDidLoadDefaultsLoad)` / `spEnd(.vcViewDidLoadDefaultsLoad)`:
-
-Replace lines 538–591 (every `if let ... = UserDefaults.standard.value(forKey:) ...` block, up to but not including the `if #available(macOS 14.0, *)` block at line 592) with:
-
-```swift
-if globalVar.fastStartupEnabled {
-    let d = StartupDefaultsCache.shared.loadIfNeeded()
-    d.applyToPublicVar(publicVar)
-} else {
-    // legacy path — original lines 538–591 verbatim
-}
-```
-
-Paste the original 60-ish lines into the `else` block for rollback safety.
-
-### - [ ] Step 3.6: Build
-
-`xcodebuild -project FlowVision.xcodeproj -scheme FlowVision build`. Expect BUILD SUCCEEDED.
-
-### - [ ] Step 3.7: Manual test
-
-1. Launch from PNG via Finder. Confirm window opens, large image shows.
-2. Open Settings → confirm previously-set preferences (theme, hidden files toggle, video volume) preserved.
-3. Toggle in `~/Library/Preferences/<bundle-id>.plist`: `defaults write app.flowvision fastStartupEnabled -bool NO`, relaunch — verify legacy path works (defaults still applied).
-4. Reset: `defaults write app.flowvision fastStartupEnabled -bool YES`.
-
-### - [ ] Step 3.8: Re-measure & gate-check
-
-Repeat baseline capture (Step 2.3) for `app.willFinish.defaultsLoad` + `vc.viewDidLoad.defaultsLoad` + `file.openFromFinder.total`. Append numbers to `2026-05-23-startup-perf-baseline.md` under heading `## After T3: batched defaults read`.
-
-If `app.willFinish.defaultsLoad` + `vc.viewDidLoad.defaultsLoad` combined improvement is <5% of its baseline, revert (`git revert HEAD`) and skip remaining fix units that depend on the cache (none do — others are independent).
-
-### - [ ] Step 3.9: Commit
-
-```bash
-git add FlowVision/Sources/Common/StartupDefaults.swift \
-        FlowVision/Sources/AppDelegate.swift \
-        FlowVision/Sources/ViewController.swift \
-        FlowVision/FlowVision.xcodeproj/project.pbxproj \
-        docs/superpowers/specs/2026-05-23-startup-perf-baseline.md
-git commit -m "perf: batch UserDefaults reads at startup"
-```
-
----
-
-## Task 4 — Fix unit 2: AppDelegate slimming + lazy THUMB_SIZES
-
-Move FinderTag labels load, `THUMB_SIZES` generation, and menu delegate hookup off the critical path.
-
-**Files:**
-- Create: `FlowVision/Sources/Common/StartupBootstrap.swift`
-- Modify: `FlowVision/Sources/Common/GlobalVariable.swift` (line 12-13)
-- Modify: `FlowVision/Sources/AppDelegate.swift` (lines 64–252, 254–278)
-- Modify: `FlowVision.xcodeproj/project.pbxproj`
-
-### - [ ] Step 4.1: Make `THUMB_SIZES` lazy
-
-Modify `FlowVision/Sources/Common/GlobalVariable.swift` lines 12–13:
-
-```swift
-// Lazily computed thumbnail bucket sizes. Pure function of constants — safe to cache.
-private let _thumbSizesComputed: [Int] = {
-    var result: [Int] = []
-    var seen = Set<Int>()
-    var x: Double = 192
-    while x <= 10000 {
-        let rounded = Int(round(x) / 64) * 64
-        if seen.insert(rounded).inserted { result.append(rounded) }
-        x *= 1.1
-    }
-    return result
-}()
-var THUMB_SIZES: [Int] { _thumbSizesComputed }
-```
-
-### - [ ] Step 4.2: Remove `generateRoundedArray` from `applicationWillFinishLaunching`
-
-Modify `FlowVision/Sources/AppDelegate.swift` lines 72–89 (the `generateRoundedArray` nested function + `THUMB_SIZES = generateRoundedArray()` call). Delete this whole block.
-
-`THUMB_SIZES` will now compute lazily on first use (no longer mutates a global var; the new top-level `var THUMB_SIZES: [Int]` is read-only).
-
-### - [ ] Step 4.3: Create `StartupBootstrap.swift`
-
-```swift
-//
-//  StartupBootstrap.swift
-//  FlowVision
-//
-
-import Foundation
-
-enum StartupBootstrap {
-    /// Schedule non-critical bootstrap work off the main launch path.
-    /// Called from applicationDidFinishLaunching after the first window is on screen.
-    static func scheduleBackground() {
-        DispatchQueue.global(qos: .utility).async {
-            FFmpegKitWrapper.shared.warmLoadAfterDelay(seconds: 2.0)
-        }
-    }
-}
-```
-
-(FinderTag labels load already runs on main during defaults phase — keep it there for now; it's tiny. If T2 baseline shows it's >5 ms, move it here in a follow-up.)
-
-### - [ ] Step 4.4: Add `StartupBootstrap.swift` to target
-
-Drag into Xcode target or edit `project.pbxproj`.
-
-### - [ ] Step 4.5: Defer menu delegates
-
-Modify `FlowVision/Sources/AppDelegate.swift` lines 240–244 (the `favoritesMenu.removeAllItems(); favoritesMenu.delegate = self; historyMenu...` block).
-
-Move these four lines from `applicationWillFinishLaunching` to the top of `applicationDidFinishLaunching` (immediately after `spBegin(.appDidFinish)`), gated on `if globalVar.fastStartupEnabled { ... } else { /* skip — already done in willFinish for legacy path */ }`. For the legacy path, keep the original lines in `applicationWillFinishLaunching` under the `else` branch of the flag check.
-
-To keep the diff manageable: add a helper:
-
-```swift
-private func setupMenuDelegates() {
-    favoritesMenu.removeAllItems()
-    favoritesMenu.delegate = self
-    historyMenu.removeAllItems()
-    historyMenu.delegate = self
-    viewMenu.delegate = self
-}
-```
-
-Call from `applicationDidFinishLaunching` when flag on, from `applicationWillFinishLaunching` else branch otherwise.
-
-### - [ ] Step 4.6: Call `StartupBootstrap.scheduleBackground()`
-
-Modify `FlowVision/Sources/AppDelegate.swift` `applicationDidFinishLaunching` (line 254). After `setupMenuDelegates()` (Step 4.5), add:
-
-```swift
-if globalVar.fastStartupEnabled {
-    StartupBootstrap.scheduleBackground()
-}
-```
-
-### - [ ] Step 4.7: Build & test
-
-`xcodebuild ... build`. Expect BUILD SUCCEEDED.
-
-Manual:
-1. Cold-launch from PNG. Verify favorites menu populated when clicked (delegate fired). Verify history menu populated. Verify view menu items present.
-2. Open a video file → confirm FFmpeg path still works (warm-load completes off-main, no hang).
-
-### - [ ] Step 4.8: Re-measure
-
-Re-capture `app.willFinish` and `file.openFromFinder.total` medians. Append to baseline doc under `## After T4: AppDelegate slimming`. If `app.willFinish` improvement <5%, revert and skip.
-
-### - [ ] Step 4.9: Commit
-
-```bash
-git add FlowVision/Sources/Common/GlobalVariable.swift \
-        FlowVision/Sources/Common/StartupBootstrap.swift \
-        FlowVision/Sources/AppDelegate.swift \
-        FlowVision/FlowVision.xcodeproj/project.pbxproj \
-        docs/superpowers/specs/2026-05-23-startup-perf-baseline.md
-git commit -m "perf: defer non-critical AppDelegate bootstrap off main launch path"
-```
-
----
-
-## Task 5 — Fix unit 3: viewDidLoad pruning
-
-Move outlineView / collectionView / event monitor setup behind a `setupDeferredUI()` hook called from `viewDidAppear`.
-
-**Files:**
-- Modify: `FlowVision/Sources/ViewController.swift` (lines 444–856)
-
-### - [ ] Step 5.1: Identify split point
-
-In `ViewController.swift` `viewDidLoad`:
-- **Keep in `viewDidLoad`:** `largeImageView` setup (lines 459–473), `publicVar.isInInitStage = false` (line 477), `drawingView` setup (lines 526–530), defaults batch read (lines 538–597, now `StartupDefaultsCache`), `publicVar.profile` load (line 597), `publicVar.setFileExtensions()` (line 602), theme color block (lines 619–630).
-- **Move to `setupDeferredUI()`:** `collectionViewManager` and `collectionView` config (lines 482–494), progress bar setup (line 498), `outlineViewManager` + `outlineView` config (lines 508–518), splitView delegate (line 522), splitView profile-driven position (lines 604–616), `treeViewData.initData(...)` + `outlineView.reloadData()` + `adjustColumnWidth()` (lines 644–648), all event monitors (lines 653–845).
-
-### - [ ] Step 5.2: Add `setupDeferredUI()` and `viewDidAppear` hook
-
-Modify `FlowVision/Sources/ViewController.swift`. After existing `viewDidLoad` closing brace (line 856), insert:
-
-```swift
-private var deferredUIInitialized = false
-
-override func viewDidAppear() {
-    super.viewDidAppear()
-    if !deferredUIInitialized {
-        deferredUIInitialized = true
-        setupDeferredUI()
-    }
-}
-
-private func setupDeferredUI() {
-    if !globalVar.fastStartupEnabled { return }  // legacy path already did this in viewDidLoad
-
-    // collectionView
-    collectionViewManager = CustomCollectionViewManager(fileDB: fileDB)
-    collectionView.wantsLayer = true
-    collectionView.allowsMultipleSelection = true
-    collectionView.isSelectable = true
-    collectionView.delegate = collectionViewManager
-    collectionView.dataSource = collectionViewManager
-    collectionView.register(CustomCollectionViewItem.self, forItemWithIdentifier: NSUserInterfaceItemIdentifier(rawValue: "CustomCollectionViewItem"))
-    collectionView.setDraggingSourceOperationMask([.every], forLocal: true)
-    collectionView.setDraggingSourceOperationMask([.every], forLocal: false)
-
-    setupProgressBar()
-
-    // outlineView
-    outlineViewManager = CustomOutlineViewManager(fileDB: fileDB, treeViewData: treeViewData, outlineView: outlineView)
-    outlineView.delegate = outlineViewManager
-    outlineView.dataSource = outlineViewManager
-    outlineView.registerForDraggedTypes([.fileURL] + NSFilePromiseReceiver.readableDraggedTypes.map { NSPasteboard.PasteboardType($0) })
-    outlineView.setDraggingSourceOperationMask([.every], forLocal: true)
-    outlineView.setDraggingSourceOperationMask([.every], forLocal: false)
-    outlineView.columnAutoresizingStyle = .noColumnAutoresizing
-
-    splitView.delegate = self
-
-    // splitView profile-driven position
-    if publicVar.profile.isDirTreeHidden { splitView.setPosition(0, ofDividerAt: 0) }
-
-    // layout
-    switch publicVar.profile.layoutType {
-    case .waterfall:  collectionView.collectionViewLayout = publicVar.waterfallLayout
-    case .justified:  collectionView.collectionViewLayout = publicVar.justifiedLayout
-    case .grid:       collectionView.collectionViewLayout = publicVar.gridLayout
-    default:          collectionView.collectionViewLayout = publicVar.justifiedLayout
-    }
-    changeWaterfallLayoutNumberOfColumns()
-
-    treeViewData.initData(path: treeRootFolder)
-    outlineView.reloadData()
-    DispatchQueue.main.async { [weak self] in
-        self?.outlineViewManager.adjustColumnWidth()
-    }
-
-    // event monitors — copy the block from original viewDidLoad lines 653–845 verbatim.
-    setupEventMonitors()
-}
-```
-
-Then extract the event-monitor block (currently lines 653–845) into:
-
-```swift
-private func setupEventMonitors() {
-    NSApp.addObserver(self, forKeyPath: "effectiveAppearance", options: [.new, .old], context: nil)
-    outlineView.doubleAction = #selector(outlineViewDoubleClicked(_:))
-
-    eventMonitorLeftMouseDown = NSEvent.addLocalMonitorForEvents(matching: .leftMouseDown) { [weak self] event in
-        // ... original closure verbatim from lines 661–684 ...
-    }
-
-    eventMonitorLeftMouseUp = NSEvent.addLocalMonitorForEvents(matching: .leftMouseUp) { [weak self] event in
-        // ... original closure verbatim from lines 686–709 ...
-    }
-
-    eventMonitorScrollWheel = NSEvent.addLocalMonitorForEvents(matching: .scrollWheel) { [weak self] event in
-        // ... original closure verbatim from lines 745–758 ...
-    }
-
-    if let scrollView = collectionView.enclosingScrollView {
-        NotificationCenter.default.addObserver(self, selector: #selector(scrollViewDidScroll(_:)), name: NSScrollView.didLiveScrollNotification, object: scrollView)
-        NotificationCenter.default.addObserver(self, selector: #selector(scrollViewScrollEnd(_:)), name: NSScrollView.didEndLiveScrollNotification, object: scrollView)
-    }
-
-    eventMonitorKeyDown = NSEvent.addLocalMonitorForEvents(matching: .keyDown) { [weak self] event in
-        guard let self = self else { return event }
-        return self.KeyShortcutManager(event: event)
-    }
-
-    eventMonitorRightMouseUp = NSEvent.addLocalMonitorForEvents(matching: .rightMouseUp) { [weak self] event in
-        // ... original closure verbatim from lines 778–799 ...
-    }
-
-    eventMonitorRightMouseDown = NSEvent.addLocalMonitorForEvents(matching: .rightMouseDown) { [weak self] event in
-        // ... original closure verbatim from lines 801–822 ...
-    }
-
-    eventMonitorRightMouseDragged = NSEvent.addLocalMonitorForEvents(matching: .rightMouseDragged) { [weak self] event in
-        // ... original closure verbatim from lines 824–845 ...
-    }
-}
-```
-
-Copy each `// ...verbatim...` placeholder with the exact closure body from the corresponding existing lines.
-
-### - [ ] Step 5.3: Wrap legacy viewDidLoad branch
-
-In `viewDidLoad`, after the keep-block (theme colors, line 630), add the gate:
-
-```swift
-if globalVar.fastStartupEnabled {
-    // deferred work runs in setupDeferredUI from viewDidAppear
-} else {
-    // legacy: do the work inline here — keep lines 482–518, 522, 604–616, 644–648, 653–845 in place
-    setupDeferredUI_legacy()
-}
-```
-
-Define `setupDeferredUI_legacy()` containing exact original code (a copy of the work, no flag check inside). This duplication is removed after T5 ships stable.
-
-### - [ ] Step 5.4: Build & manual test
-
-`xcodebuild ... build`. Expect BUILD SUCCEEDED.
-
-Manual:
-1. Cold-launch from PNG. Verify window appears; verify large image renders; sidebar / tree may appear a beat later (acceptable).
-2. Click sidebar entry → tree responds.
-3. Right-click large image → context menu fires (right-mouse monitor installed).
-4. Key shortcuts (→ arrow, space) → work.
-5. Scroll wheel zoom (if enabled) → works.
-6. Toggle flag off → all UI present at viewDidLoad time as before.
-
-### - [ ] Step 5.5: Re-measure
-
-`vc.viewDidLoad` and `file.openFromFinder.total` medians → baseline doc, `## After T5: viewDidLoad pruning`. If `vc.viewDidLoad` improvement <5%, revert.
-
-### - [ ] Step 5.6: Commit
-
-```bash
-git add FlowVision/Sources/ViewController.swift \
-        docs/superpowers/specs/2026-05-23-startup-perf-baseline.md
-git commit -m "perf: defer non-critical viewDidLoad work to viewDidAppear"
-```
-
----
-
-## Task 6 — Fix unit 4: storyboard split (optional, highest risk)
-
-**Defer this task unless prior fix units leave >150 ms in `window.storyboardInstantiate`.** Storyboard refactoring is fragile and AppKit-version-sensitive.
-
-If skipped, document in baseline doc: `## T6 skipped: insufficient remaining cost in window.storyboardInstantiate`.
-
-### - [ ] Step 6.1: Evaluate skip
-
-Inspect baseline doc. If `window.storyboardInstantiate` median <150 ms after T3+T4+T5, skip. Commit a note:
-
-```bash
-echo "## T6: skipped (storyboardInstantiate <150ms after T3-T5)" >> docs/superpowers/specs/2026-05-23-startup-perf-baseline.md
-git add docs/superpowers/specs/2026-05-23-startup-perf-baseline.md
-git commit -m "docs: skip storyboard split fix unit (insufficient remaining cost)"
-```
-
-Proceed to Task 7.
-
-### - [ ] Step 6.2 (only if not skipped): Identify Main.storyboard scenes
-
-Open `FlowVision/Resources/Main.storyboard` in Xcode. List scenes/window controllers present. Identify scenes used during launch-from-file vs settings/secondary panels.
-
-### - [ ] Step 6.3 (only if not skipped): Split into `Secondary.storyboard`
-
-Move secondary-panel scenes to a new `Secondary.storyboard`. Wire any `instantiateController(withIdentifier:)` callers to load from the appropriate storyboard.
-
-### - [ ] Step 6.4 (only if not skipped): Build, test, measure, commit
-
-Full smoke test (Settings, Profiles, Tagging). Measure `window.storyboardInstantiate` decrease. If <10% gain or any crash, revert.
-
----
-
-## Task 7 — Fix unit 5: launch-from-file fast path
-
-Decode image on background queue, show window, defer folder scan.
-
-**Files:**
-- Modify: `FlowVision/Sources/AppDelegate.swift` (lines 424–488, `application(openFiles:)`)
-- Modify: `FlowVision/Sources/ViewControllerExtension/LargeImage.swift` (lines 469–488, `OpenLargeImageFromFinder`)
-
-### - [ ] Step 7.1: Reorder `application(openFiles:)`
-
-Modify `FlowVision/Sources/AppDelegate.swift` lines 424–488. Inside the "Open in new window" branch (the existing `if true || windowControllers.count == 0` block, lines 449–467), when `!isDirectory`:
-
-```swift
-// fast path: window + image first, folder scan after first frame
-globalVar.isLaunchFromFile = true
-if windowControllers.count == 0 || globalVar.autoHideToolbar {
-    globalVar.useCreateWindowShowDelay = true
-}
-guard let targetWindowController = createNewWindow(file) else { return }
-
-if globalVar.fastStartupEnabled {
-    openImageInTargetWindow_FastPath(file, windowController: targetWindowController)
-} else {
-    openImageInTargetWindow(file, windowController: targetWindowController)
-}
-return
-```
-
-Then add a new `openImageInTargetWindow_FastPath`:
-
-```swift
-func openImageInTargetWindow_FastPath(_ openPath: String, windowController: NSWindowController) {
-    guard let viewController = windowController.contentViewController as? ViewController else { return }
-    let folderPath = getFileSchemeAbsParentFolderPath(openPath)
-    let path = getFileSchemeAbsPath(openPath)
-
-    viewController.publicVar.openFromFinderPath = path
-    viewController.OpenLargeImageFromFinder(path: path)
-
-    // Folder enumeration runs after the large image is on screen.
-    NotificationCenter.default.addObserver(
-        forName: .didShowLargeImageFromLaunch,
-        object: viewController,
-        queue: .main
-    ) { [weak viewController] _ in
-        DispatchQueue.global(qos: .utility).async {
-            DispatchQueue.main.async {
-                viewController?.switchDirByDirection(direction: .zero, dest: folderPath, doCollapse: true, expandLast: true, skip: false, stackDeep: 0)
-            }
-        }
-    }
-}
-```
-
-(`Notification.Name.didShowLargeImageFromLaunch` defined in Step 7.3.)
-
-### - [ ] Step 7.2: Define notification name
-
-Modify `FlowVision/Sources/Common/StartupTiming.swift`. Append at file end:
-
-```swift
-extension Notification.Name {
-    static let didShowLargeImageFromLaunch = Notification.Name("app.flowvision.didShowLargeImageFromLaunch")
-}
-```
-
-### - [ ] Step 7.3: Post notification after first frame
-
-Modify `FlowVision/Sources/ViewControllerExtension/LargeImage.swift` `OpenLargeImageFromFinder` (line 469).
-
-After the existing body (after the comment `// setWindowTitleOfLargeImage(file: item.file)` at line 487), add:
-
-```swift
-DispatchQueue.main.async { [weak self] in
-    guard let self = self else { return }
-    NotificationCenter.default.post(name: .didShowLargeImageFromLaunch, object: self)
-}
-```
-
-(The `spEnd(.fileOpenFromFinderTotal)` added in T1.7 stays here too — it's the same dispatch point, but they're separate `async` blocks for clarity.)
-
-### - [ ] Step 7.4: Build & test
-
-`xcodebuild ... build`. Expect BUILD SUCCEEDED.
-
-Manual:
-1. Cold-launch from PNG. Confirm window + large image appear. After ~100 ms folder list populates underneath.
-2. Press →: navigates to next sibling (folder enum must have completed).
-3. Press → again immediately after launch (within 50 ms of first frame): should still work or no-op gracefully (no crash). If crash, add a guard in arrow-key handler checking that folder enum has run.
-4. Launch from folder (not file) → unchanged behavior.
-5. Toggle flag off → legacy synchronous path.
-
-### - [ ] Step 7.5: Re-measure
-
-`file.openFromFinder.total` median per file type → baseline doc `## After T7: launch-from-file fast path`. Required: ≥40% reduction vs Stage 1 baseline (this is the acceptance metric per spec §7).
-
-If <40% reduction, investigate top remaining span. Possibly the decode itself dominates and architecture cannot help further — note in baseline doc.
-
-### - [ ] Step 7.6: Commit
-
-```bash
-git add FlowVision/Sources/AppDelegate.swift \
-        FlowVision/Sources/ViewControllerExtension/LargeImage.swift \
-        FlowVision/Sources/Common/StartupTiming.swift \
-        docs/superpowers/specs/2026-05-23-startup-perf-baseline.md
-git commit -m "perf: launch-from-file shows window before folder scan"
-```
-
----
-
-## Task 8 — Fix unit 6: FFmpeg warm + linker audit
-
-**Files:**
-- Modify: `FlowVision/Sources/Common/FFmpegKit.swift`
-- Modify: `FlowVision/Sources/Common/StartupBootstrap.swift`
-- Modify: `FlowVision.xcodeproj/project.pbxproj` (Release `DEAD_CODE_STRIPPING`)
-
-### - [ ] Step 8.1: Add `warmLoadAfterDelay`
-
-Modify `FlowVision/Sources/Common/FFmpegKit.swift` after the existing `loadFFmpegKitIfNeeded()` (line 53):
-
-```swift
-func warmLoadAfterDelay(seconds: Double) {
-    DispatchQueue.global(qos: .background).asyncAfter(deadline: .now() + seconds) { [weak self] in
-        self?.loadFFmpegKitIfNeeded()
-    }
-}
-```
-
-### - [ ] Step 8.2: Verify `StartupBootstrap` already calls it
-
-Already done in Task 4.3. Re-confirm:
-
-```swift
-static func scheduleBackground() {
-    DispatchQueue.global(qos: .utility).async {
-        FFmpegKitWrapper.shared.warmLoadAfterDelay(seconds: 2.0)
-    }
-}
-```
-
-### - [ ] Step 8.3: Enable DEAD_CODE_STRIPPING
-
-Verify current value:
-
-```bash
-grep -n "DEAD_CODE_STRIPPING" FlowVision.xcodeproj/project.pbxproj
-```
-
-If absent or `NO` for Release, edit `project.pbxproj` Release buildSettings block (or open Xcode → FlowVision target → Build Settings → search "Dead Code Stripping") → set `DEAD_CODE_STRIPPING = YES` Release. Debug can stay `NO`.
-
-### - [ ] Step 8.4: Audit `OTHER_LDFLAGS`
-
-```bash
-grep -n "OTHER_LDFLAGS" FlowVision.xcodeproj/project.pbxproj
-```
-
-Inspect for `-framework <Name>` entries. Compare to actually-imported frameworks (`grep -rn "^import " FlowVision/Sources | sort -u`). **Do not remove anything without verification** — many frameworks are loaded indirectly (e.g., from Storyboard or Objective-C runtime).
-
-If any entry is clearly unused (e.g., a removed dependency), remove and rebuild. If unsure, leave it.
-
-### - [ ] Step 8.5: Build Release & test
-
-`xcodebuild -project FlowVision.xcodeproj -scheme FlowVision -configuration Release build CODE_SIGN_IDENTITY="" CODE_SIGNING_REQUIRED=NO`. Expect BUILD SUCCEEDED.
-
-Manual:
-1. Cold-launch from PNG → confirm normal behavior.
-2. Open a `.mkv` video (non-native, requires FFmpeg) → confirm it plays. (Tests warm path.)
-3. Set `doNotUseFFmpeg = true` in defaults, relaunch, open `.mkv` → confirm fallback message (no crash).
-
-### - [ ] Step 8.6: Re-measure
-
-`file.openFromFinder.total` (PNG and video) medians → baseline doc `## After T8: FFmpeg warm + linker`. Pre-main / dyld time isn't captured by our spans — measure full launch by Activity Monitor or instruments if curious.
-
-### - [ ] Step 8.7: Commit
-
-```bash
-git add FlowVision/Sources/Common/FFmpegKit.swift \
-        FlowVision/FlowVision.xcodeproj/project.pbxproj \
-        docs/superpowers/specs/2026-05-23-startup-perf-baseline.md
-git commit -m "perf: warm-load FFmpeg off main; enable DEAD_CODE_STRIPPING in Release"
-```
-
----
-
-## Task 9 — Cleanup (after one stable release cycle)
-
-**Defer until at least one full release with all units stable.** Skip if any unit was reverted.
-
-### - [ ] Step 9.1: Remove legacy else branches
-
-Remove every `if globalVar.fastStartupEnabled { ... } else { legacy code }` introduced in T3, T4, T5, T7. Keep the `if`-branch contents only.
-
-### - [ ] Step 9.2: Remove `globalVar.fastStartupEnabled`
-
-Remove the property from `GlobalVariable.swift`, remove the defaults wiring in `AppDelegate.swift`, remove the user-defaults migration (delete the key if set).
-
-### - [ ] Step 9.3: Remove `setupDeferredUI_legacy()`
-
-Delete the legacy helper added in T5.3.
-
-### - [ ] Step 9.4: Build, full smoke test, commit
-
-```bash
-git commit -m "refactor: remove fastStartupEnabled flag after stable release"
-```
-
----
-
-## Acceptance Summary
-
-Per spec §7:
-- Baseline captured (T2.4).
-- `file.openFromFinder.total` median (median of 5 cold runs per file type) ≥40% lower vs baseline after T7. Recorded in `docs/superpowers/specs/2026-05-23-startup-perf-baseline.md`.
-- Each fix unit gates on its own ≥5% measured improvement of the span it targets, else reverted.
-- Per-unit rollback available via `git revert` and via `defaults write app.flowvision fastStartupEnabled -bool NO`.
-
----
-
-## Self-Review Notes
-
-Coverage check vs spec:
-- §1 Goal — Task 1, 7 — ✓
-- §2 Pipeline — Task 1 (instruments observed pipeline) — ✓
-- §3 Target pipeline — Task 4, 5, 7 — ✓
-- §4 Stage 1 instrumentation — Task 1 — ✓
-- §4 Stage 2 units 1–6 — Tasks 3, 4, 5, 6, 7, 8 — ✓
-- §5 New files — Tasks 1, 3, 4 — ✓
-- §5 Feature flag — Task 2 — ✓
-- §6 Error handling — covered in each task's manual test step
-- §7 Testing matrix — Task 2.3 + each fix unit's manual test
-- §8 Rollout order — task order matches
-- §9 Rollback — flag toggle steps included in tests; Task 9 final removal — ✓
-
-No placeholders ("TBD", "implement later") in any step.
-Type names verified: `PublicVar` reference flagged in T3.2 for verification before edit. `FFmpegKitWrapper.shared`, `CustomTagView.userDefaultsKey`, `FinderTag.customLabels`, `FinderTag.systemColorLabels` all match existing usage in `AppDelegate.swift`.
diff --git a/docs/superpowers/specs/2026-05-23-startup-perf-design.md b/docs/superpowers/specs/2026-05-23-startup-perf-design.md
deleted file mode 100644
index 4c5a9579..00000000
--- a/docs/superpowers/specs/2026-05-23-startup-perf-design.md
+++ /dev/null
@@ -1,204 +0,0 @@
-# FlowVision Startup Performance — Design
-
-**Date:** 2026-05-23
-**Status:** Approved (pending user spec review)
-**Branch (origin):** `feat-shortcuts`
-
-## 1. Goal & Scope
-
-Make **launch-from-file** (Finder "Open With → FlowVision" on a single image) feel ultra-fast: measurable reduction in time from icon click to large image visible on screen. Cold-start optimization first; warm-start improvements should follow for free.
-
-**Out of scope:** launch-into-folder (only touched if a fix obviously helps both), in-app folder switch, thumbnail generation, video player.
-
-**Success criteria:**
-- Baseline captured (median of 5 cold runs per file type).
-- Post-fix median ≥40% lower on the dominant span (`file.openFromFinder.total`).
-- Stretch: large-image visible within ~300 ms of icon click on a recent Mac.
-
-## 2. Current Pipeline (Observed)
-
-Findings from `AppDelegate.swift`, `ViewController.swift`, `LargeImage.swift`, `FFmpegKit.swift`:
-
-- `applicationWillFinishLaunching` runs ~30 synchronous `UserDefaults.standard.value(forKey:)` reads on main (lines 96–225).
-- `ViewController.viewDidLoad` runs another ~30 synchronous defaults reads (lines 538+) plus full collection/outline/split/drawing-view setup.
-- `Main.storyboard` instantiated synchronously inside `createNewWindow`.
-- `EnhancedIndex.initialize()` already dispatched to `.userInitiated` queue — good.
-- `FFmpegKitWrapper` already lazy via `dlopen` (`LOAD_WHEN_USE=true`) — good.
-- `Settings` window controller already `lazy` — good.
-- `application(openFiles:)` calls `createNewWindow(file)` then `openImageInTargetWindow(file, …)` which calls `OpenLargeImageFromFinder` and dispatches `switchDirByDirection` (folder enumeration for sibling nav) on main async.
-
-Critical-path sequence today (all main thread):
-
-```
-willFinishLaunching ███
-  ├─ ShortcutStore.load
-  ├─ THUMB_SIZES generate
-  ├─ ~30 UserDefaults reads
-  ├─ FinderTag custom labels load
-  ├─ menu delegates hooked, EnhancedIndex.initialize (async — OK)
-
-didFinishLaunching ███
-  └─ createNewWindow() — empty window
-        ├─ storyboard instantiate ███
-        ├─ viewDidLoad ███ (~30 more defaults + view setup)
-
-application(openFiles:) ███
-  ├─ createNewWindow(file) ███ (second window, same heavy storyboard)
-  ├─ OpenLargeImageFromFinder
-  └─ switchDirByDirection (folder enum) ███
-                                            ▼
-                                large image visible
-```
-
-## 3. Target Pipeline
-
-```
-willFinishLaunching ███ (slim)
-  ├─ batched defaults read (one call)
-  ├─ ShortcutStore.load
-  ├─ EnhancedIndex.initialize (already async)
-  │  ┌──────────────────────────────────────────┐
-  │  │ background (qos:.utility)                │
-  │  │  • FinderTag labels                      │
-  │  │  • THUMB_SIZES lazy on first access      │
-  │  │  • menu delegates on demand              │
-  │  │  • FFmpegKit warm dlopen (.background)   │
-  │  └──────────────────────────────────────────┘
-
-didFinishLaunching ███ (slim)
-  └─ if openFiles already queued → fast path
-        ├─ storyboard instantiate (minimal scene)
-        ├─ viewDidLoad_Minimal: largeImageView + window only
-        ├─ background: decode image
-        ├─ main: assign image → window orderFront
-        └─ post-paint async:
-              ├─ folder enum
-              ├─ tree / outline / collection setup
-              ├─ remaining defaults reads
-                                            ▼
-                                sibling navigation ready
-```
-
-Critical-path budget:
-
-| Span | Now (est) | Target |
-|---|---|---|
-| willFinish | 50–100 ms | <20 ms |
-| storyboard + minimal viewDidLoad | 100–200 ms | <60 ms |
-| image decode | varies | unchanged (off-main) |
-| first frame total | sum above | ≤300 ms |
-
-## 4. Stages
-
-### Stage 1 — Instrumentation (lands first, no flag)
-
-Add timing helper using `OSSignposter` (macOS 12+) plus existing `log()`. Span IDs:
-
-- `app.willFinish`, `app.willFinish.defaultsLoad`, `app.didFinish`
-- `window.create`, `window.storyboardInstantiate`
-- `vc.viewDidLoad`, `vc.viewDidLoad.defaultsLoad`
-- `file.openFromFinder.total` (from `application(openFiles:)` entry to large-image first-frame)
-- `file.openLargeImage.decode`
-- `file.switchDir.scan`
-
-Capture baseline: 5 cold runs × {PNG, JPG, HEIC, RAW (CR2/NEF), animated GIF, WEBP, video}. Record medians in `docs/superpowers/specs/2026-05-23-startup-perf-baseline.md`.
-
-### Stage 2 — Fix units (ordered, each behind `fastStartupEnabled`)
-
-1. **Defaults batch read** — replace 60+ `value(forKey:)` calls in `AppDelegate.applicationWillFinishLaunching` and `ViewController.viewDidLoad` with a single batched read into a struct.
-2. **AppDelegate slimming** — move FinderTag labels load, menu hookups, and other non-critical bootstrap off `applicationWillFinishLaunching`. Make `THUMB_SIZES` a static lazy constant.
-3. **viewDidLoad pruning** — move outlineView/collectionView/splitView/drawing-view setup behind `setupDeferredUI()` called from `viewDidAppear`.
-4. **Storyboard split** — pull rarely-needed bits out of `Main.storyboard` so launch-from-file loads a minimal scene.
-5. **Launch-from-file fast path** — restructure `application(openFiles:)`: decode on background queue → show window with image → folder enum + sibling list async after first frame.
-6. **FFmpeg async + linker audit** — `warmLoadAfterDelay`; `DEAD_CODE_STRIPPING = YES` Release; audit `Base.xcconfig` `OTHER_LDFLAGS` for unused `-framework` entries.
-
-Each unit gates on its measured win — revert if <5% of its span.
-
-## 5. Components
-
-### New files
-
-**`Sources/Common/StartupTiming.swift`** (~80 lines)
-- `enum StartupSpan: String` — cases match span IDs above.
-- `func spBegin(_:)` / `spEnd(_:)` using `OSSignposter` + `log()` bridge.
-- `func spMeasure<T>(_:, _: () throws -> T) rethrows -> T` wrapper.
-
-**`Sources/Common/Defaults+Batch.swift`** (~60 lines)
-- `struct AppStartupDefaults` — every defaults key + default value.
-- `static func loadFromUserDefaults() -> AppStartupDefaults` — one `dictionaryRepresentation()` call.
-- `func apply(toGlobalVar:)` — assigns to `globalVar` in one shot on main.
-
-### Modified files
-
-**`Sources/AppDelegate.swift`**
-- Slim `applicationWillFinishLaunching`: `ShortcutStore.shared.load()` + `AppStartupDefaults` apply + schedule background bootstrap.
-- New `createNewWindow_FastPath(file:)` for finder-launch single-image.
-- `THUMB_SIZES` → `ThumbSizes.values` (static lazy).
-- Menu delegates hooked from `applicationDidFinishLaunching`.
-
-**`Sources/ViewController.swift`**
-- `viewDidLoad`: pull config from `globalVar` only, no inline defaults reads.
-- `setupDeferredUI()` called from `viewDidAppear` first-call.
-- Launch-from-file path: minimal `viewDidLoad` (only `largeImageView`, `largeImageBgEffectView`, bounds).
-
-**`Sources/ViewControllerExtension/LargeImage.swift`**
-- `OpenLargeImageFromFinder(path:)`: decode on `.userInitiated` queue → main thread set image + un-hide → post `didShowLargeImageFromLaunch`.
-- Folder enumeration (`switchDirByDirection`) dispatched to `.utility` after that notification.
-
-**`Sources/Common/FFmpegKit.swift`**
-- `warmLoadAfterDelay(seconds:)` — dispatch `loadFFmpegKitIfNeeded` on `.background` queue.
-
-**Build settings (`Base.xcconfig` / Release)**
-- `DEAD_CODE_STRIPPING = YES` (verify not already set).
-- Audit `OTHER_LDFLAGS` for unused `-framework` entries (no removal without verification).
-
-### Feature flag
-
-- `globalVar.fastStartupEnabled` (default `true`, hidden Advanced Settings toggle).
-- All Stage 2 changes branch on it.
-- Removed once stable for one release cycle.
-
-## 6. Error Handling
-
-- Defaults batch read: malformed key falls back to default value (same semantics as today's `if let ... as? Type`). No throws.
-- Background image decode: existing decode error paths preserved; on failure window still shows (current behavior).
-- Background bootstrap tasks (FFmpeg warm, FinderTag labels, deferred UI): each in its own `DispatchWorkItem`; failures logged via `log()`, not surfaced.
-- Fast-path window keeps current `fatalError` on missing `WindowController` identifier — same as today.
-- Feature flag off → entire pre-existing code path runs unchanged.
-
-## 7. Testing
-
-No automated UI tests today; matching that.
-
-Manual matrix per fix unit:
-
-1. Cold launch (`killall FlowVision`, wait 30 s) via Finder "Open With" for PNG, JPG, HEIC, RAW (CR2/NEF), animated GIF, WEBP, video file (internal player on).
-2. Cold launch via app icon (no file).
-3. Warm launch variants of (1).
-4. Multi-tab: open second file with one window already up.
-5. CLI: `open ./img.jpg`, `open .`.
-6. Toggle `fastStartupEnabled` off → confirm old behavior intact.
-7. Sibling navigation (→/←) after fast path.
-8. Settings window opens, no missing IBOutlet crash.
-9. `Instruments → Allocations` 30 s after launch — compare to baseline.
-
-**Acceptance:** `file.openFromFinder.total` median (5 runs) ≥40% lower than baseline per file type. Numbers recorded in `2026-05-23-startup-perf-baseline.md`.
-
-## 8. Rollout
-
-1. Stage 1 (instrumentation) lands first in `main`. No flag.
-2. Capture baseline; commit to spec dir.
-3. Stage 2 units land one per commit/PR, behind `fastStartupEnabled`:
-   1. Defaults batch
-   2. AppDelegate slimming
-   3. viewDidLoad pruning
-   4. Storyboard split (may be deferred — highest risk)
-   5. Launch-from-file fast path
-   6. FFmpeg async + linker audit
-4. Re-measure after each unit. Revert if <5% gain on its span.
-5. After one stable release cycle: delete flag, delete legacy code paths.
-
-## 9. Rollback
-
-- Per-unit: revert one commit.
-- User-facing: hidden Advanced Settings toggle disables fast path without reinstall.