From 6f2856fa70722dad7f7c69a3addaa05ea9fd6e94 Mon Sep 17 00:00:00 2001
From: Ariver <shanghai3168@gmail.com>
Date: Fri, 19 Jun 2026 22:36:43 +0800
Subject: [PATCH] Add two-key window shortcut codes

---
 C1.source/Sources/Aligner/QuickSwitchRootView.swift | 1255 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 1,214 insertions(+), 41 deletions(-)

diff --git a/C1.source/Sources/Aligner/QuickSwitchRootView.swift b/C1.source/Sources/Aligner/QuickSwitchRootView.swift
index 9b47c99..5fff479 100644
--- a/C1.source/Sources/Aligner/QuickSwitchRootView.swift
+++ b/C1.source/Sources/Aligner/QuickSwitchRootView.swift
@@ -10,6 +10,18 @@
 
 @MainActor
 final class QuickSwitchRootView: NSView {
+    private static let appShelfIndexSymbols = Array("1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ").map(String.init)
+    private static let windowIndexKeyPendingInterval: CFTimeInterval = 0.8
+    private static let appShelfIndexKeyCodes: [String: UInt16] = [
+        "1": 18, "2": 19, "3": 20, "4": 21, "5": 23,
+        "6": 22, "7": 26, "8": 28, "9": 25, "0": 29,
+        "A": 0, "B": 11, "C": 8, "D": 2, "E": 14, "F": 3,
+        "G": 5, "H": 4, "I": 34, "J": 38, "K": 40, "L": 37,
+        "M": 46, "N": 45, "O": 31, "P": 35, "Q": 12, "R": 15,
+        "S": 1, "T": 17, "U": 32, "V": 9, "W": 13, "X": 7,
+        "Y": 16, "Z": 6
+    ]
+
     private let backdropBlurView = NSVisualEffectView()
     private let layerHostView = NSView()
     private let backgroundLayer = CAGradientLayer()
@@ -67,8 +79,21 @@
     private var horizontalMasonryScrollOffset: CGFloat = 0
     private var currentSelection: QuickSwitchSelection?
     private var columnSelectionHistory: [Int: Int] = [:]
+    private var keyboardFocusedAppGroupIndex: Int?
+    private var keyboardFocusedWindowID: UInt32?
     private var keyboardCommandsApplied: [String] = []
     private var lastKeyboardCommand: String?
+    private var lastKeyboardAppIndexCommand: String?
+    private var appShelfIndexKeyDownCount = 0
+    private var lastAppShelfIndexKeySymbol: String?
+    private var windowIndexKeyPending: WindowIndexKeyPending?
+    private var windowIndexKeyPendingClearTask: Task<Void, Never>?
+    private var lastWindowIndexKeyCommand: String?
+    private var lastWindowIndexKeyCommitCode: String?
+    private var lastBoundaryBounceAxis: String?
+    private var lastBoundaryBounceDirection: String?
+    private var boundaryBounceCount = 0
+    private var selectionChangedByLastCommand: Bool?
     private var tabIgnoredCount = 0
     private var lastCommittedSelection: QuickSwitchSelection?
     private var lastCommitSource: QuickSwitchCommitSource?
@@ -218,6 +243,33 @@
     private enum HoverTargetSource: String {
         case event
         case debug
+        case keyboard
+    }
+
+    private enum HorizontalKeyboardFocusKind: String {
+        case app
+        case window
+    }
+
+    private struct HorizontalKeyboardFocusNode {
+        let kind: HorizontalKeyboardFocusKind
+        let appGroupIndex: Int
+        let windowIndex: Int?
+        let windowID: UInt32?
+        let spaceID: UInt64?
+        let frame: CGRect
+        let order: Int
+
+        var center: CGPoint {
+            CGPoint(x: frame.midX, y: frame.midY)
+        }
+
+        func matches(_ other: HorizontalKeyboardFocusNode) -> Bool {
+            kind == other.kind
+                && appGroupIndex == other.appGroupIndex
+                && windowIndex == other.windowIndex
+                && windowID == other.windowID
+        }
     }
 
     private struct SpaceLaneSegmentLayers {
@@ -241,6 +293,7 @@
         let item: QuickSwitchAppShelfItemViewModel
         let containerLayer: CALayer
         let backgroundLayer: CALayer
+        let indexLayer: CATextLayer
         let iconLayer: CALayer
         let labelLayer: CATextLayer
         let badgeLayer: CATextLayer
@@ -256,6 +309,7 @@
     private struct WaterfallColumnLayers {
         let column: QuickSwitchWaterfallColumnViewModel
         let containerLayer: CALayer
+        let cardsClipLayer: CALayer
         let headerLayer: CALayer
         let appNameLayer: CATextLayer
         let countLayer: CATextLayer
@@ -273,6 +327,12 @@
         let stateLayer: CATextLayer
         let shineLayer: CAGradientLayer
         let closeButton: CloseButtonLayers
+    }
+
+    private struct WindowIndexKeyPending {
+        let appSymbol: String
+        let appGroupIndex: Int
+        let startedAt: CFTimeInterval
     }
 
     private struct ProjectionLayerSnapshot {
@@ -299,6 +359,10 @@
         static let normalGap: CGFloat = 16
         static let minGap: CGFloat = 8
         static let maxRows = 2
+        static let indexFontSize: CGFloat = 16
+        static let compressedIndexFontSize: CGFloat = 14
+        static let indexWidth: CGFloat = 18
+        static let indexHeight: CGFloat = 24
     }
 
     private enum RootLayoutMetrics {
@@ -341,6 +405,8 @@
         static let cardGap: CGFloat = 12
         static let revealPadding: CGFloat = 24
         static let horizontalRevealPadding: CGFloat = 0
+        static let selectedCardScale: CGFloat = 1.015
+        static let selectedCardScaleOverflow: CGFloat = cardHeight * (selectedCardScale - 1) / 2
     }
 
     private enum HorizontalMasonryMetrics {
@@ -442,11 +508,15 @@
         case TriggerKeyCode.tab:
             performKeyboardCommand("tab")
         default:
+            if handleAppShelfIndexKey(event) {
+                return
+            }
             super.keyDown(with: event)
         }
     }
 
     override func scrollWheel(with event: NSEvent) {
+        clearWindowIndexKeyPending()
         refreshHoverTarget(at: event.locationInWindow)
 
         let dominantDelta = abs(event.scrollingDeltaX) >= abs(event.scrollingDeltaY)
@@ -502,6 +572,7 @@
 
     override func mouseMoved(with event: NSEvent) {
         guard debugHoveredAppGroupIndex == nil else { return }
+        clearWindowIndexKeyPending()
 
         let toggleHovered = viewModeToggleButtonContains(windowLocation: event.locationInWindow)
         if !toggleHovered {
@@ -528,6 +599,7 @@
 
     override func mouseExited(with event: NSEvent) {
         guard debugHoveredAppGroupIndex == nil else { return }
+        clearWindowIndexKeyPending()
         isViewModeToggleButtonHovered = false
         suppressViewModeToggleHoverPreview = false
         hoveredCloseTarget = nil
@@ -543,6 +615,7 @@
             ])
             return
         }
+        clearWindowIndexKeyPending()
 
         if handleCloseConfirmationMouseDown(at: event.locationInWindow) {
             return
@@ -597,11 +670,49 @@
         layoutSubtreeIfNeeded()
         for command in commands {
             let measurementStart = CACurrentMediaTime()
-            performKeyboardCommand(command)
+            if !performDebugPhysicalIndexKeyCommand(command) {
+                performKeyboardCommand(command)
+            }
             layoutSubtreeIfNeeded()
             CATransaction.flush()
             keyboardResponseLatencyMilliseconds.append(milliseconds(since: measurementStart))
         }
+    }
+
+    private func performDebugPhysicalIndexKeyCommand(_ rawCommand: String) -> Bool {
+        let command = rawCommand.trimmingCharacters(in: .whitespacesAndNewlines)
+        let uppercased = command.uppercased()
+        let prefixes = ["PHYSICAL-INDEX:", "PHYSICAL-INDEX-", "KEYDOWN:", "KEYDOWN-"]
+        guard let prefix = prefixes.first(where: { uppercased.hasPrefix($0) }) else {
+            return false
+        }
+
+        let symbolStart = command.index(command.startIndex, offsetBy: prefix.count)
+        guard let symbol = appShelfIndexSymbol(fromKeyboardCommand: String(command[symbolStart...])),
+              let keyCode = Self.appShelfIndexKeyCodes[symbol],
+              let event = NSEvent.keyEvent(
+                with: .keyDown,
+                location: .zero,
+                modifierFlags: [.option],
+                timestamp: ProcessInfo.processInfo.systemUptime,
+                windowNumber: window?.windowNumber ?? 0,
+                context: nil,
+                characters: symbol.lowercased(),
+                charactersIgnoringModifiers: symbol.lowercased(),
+                isARepeat: false,
+                keyCode: keyCode
+              )
+        else {
+            recordKeyboardCommand("invalidPhysicalIndex:\(command)")
+            selectionChangedByLastCommand = false
+            return true
+        }
+
+        let previousSuppressEventInput = suppressEventInput
+        suppressEventInput = false
+        keyDown(with: event)
+        suppressEventInput = previousSuppressEventInput
+        return true
     }
 
     func performDebugMouseCommands(_ commands: [String]) {
@@ -722,7 +833,8 @@
         if case .realScreenshot = resolution.source {
             let isSelected = card.item.window.id == effectiveSelection?.windowID
             let isHovered = card.item.window.id == hoveredWindowID
-            card.shineLayer.opacity = shouldShowSelectedVisual(isSelected: isSelected, isHovered: isHovered) ? 1 : 0
+            let isKeyboardFocused = card.item.window.id == keyboardFocusedWindowID
+            card.shineLayer.opacity = (shouldShowSelectedVisual(isSelected: isSelected, isHovered: isHovered) || isKeyboardFocused) ? 1 : 0
         }
         needsLayout = true
     }
@@ -751,11 +863,38 @@
         apply(viewModel: viewModel, preservingInteractionState: true, animatedProjection: true)
     }
 
+    func hoverNextAppGroupIndex(cycleForward: Bool = true) -> Bool {
+        guard !appShelfItems.isEmpty else {
+            return false
+        }
+
+        let orderedIndexes = appShelfItems.map(\.item.appGroupIndex)
+        let sortedIndexes = orderedIndexes
+
+        var currentIndexPosition: Int?
+        if let currentHovered = effectiveHoveredAppGroupIndex {
+            currentIndexPosition = sortedIndexes.firstIndex(of: currentHovered)
+        }
+
+        let nextPosition = currentIndexPosition.map { current in
+            if cycleForward {
+                (current + 1) % sortedIndexes.count
+            } else {
+                (current - 1 + sortedIndexes.count) % sortedIndexes.count
+            }
+        } ?? 0
+
+        let nextAppGroupIndex = sortedIndexes[nextPosition]
+        hoverAppGroup(nextAppGroupIndex)
+        return true
+    }
+
     private func apply(
         viewModel: QuickSwitchViewModel?,
         preservingInteractionState: Bool,
         animatedProjection: Bool
     ) {
+        let preservedWindowThumbnails = preservingInteractionState ? cachedThumbnailsByWindowID() : [:]
         let transitionSnapshot = animatedProjection ? captureProjectionTransitionSnapshot() : nil
         if !animatedProjection {
             resetProjectionTransitionReport()
@@ -766,6 +905,16 @@
             currentSelection = validSelection(currentSelection, in: viewModel) ?? viewModel?.initialSelection
             columnSelectionHistory = columnSelectionHistory.filter { appGroupIndex, _ in
                 viewModel?.waterfallColumns.contains { $0.appGroupIndex == appGroupIndex } == true
+            }
+            if let keyboardFocusedAppGroupIndex,
+               viewModel?.waterfallColumns.contains(where: { $0.appGroupIndex == keyboardFocusedAppGroupIndex }) != true {
+                self.keyboardFocusedAppGroupIndex = nil
+            }
+            if let keyboardFocusedWindowID,
+               viewModel?.waterfallColumns.contains(where: { column in
+                   column.windows.contains { $0.window.id == keyboardFocusedWindowID }
+               }) != true {
+                self.keyboardFocusedWindowID = nil
             }
             if let currentSelection {
                 columnSelectionHistory[currentSelection.appGroupIndex] = currentSelection.windowIndex
@@ -781,8 +930,20 @@
             screenshotSkippedReasonsByWindowID = [:]
             currentSelection = viewModel?.initialSelection
             columnSelectionHistory = [:]
+            keyboardFocusedAppGroupIndex = nil
+            keyboardFocusedWindowID = nil
             keyboardCommandsApplied = []
             lastKeyboardCommand = nil
+            lastKeyboardAppIndexCommand = nil
+            appShelfIndexKeyDownCount = 0
+            lastAppShelfIndexKeySymbol = nil
+            clearWindowIndexKeyPending()
+            lastWindowIndexKeyCommand = nil
+            lastWindowIndexKeyCommitCode = nil
+            lastBoundaryBounceAxis = nil
+            lastBoundaryBounceDirection = nil
+            boundaryBounceCount = 0
+            selectionChangedByLastCommand = nil
             tabIgnoredCount = 0
             lastCommittedSelection = nil
             lastCommitSource = nil
@@ -816,12 +977,35 @@
         rebuildSpaceLaneSegments()
         rebuildAppShelfItems()
         rebuildWaterfallColumns()
+
+        if preservingInteractionState {
+            restoreThumbnailsFromCache(preservedWindowThumbnails)
+        }
+
         needsLayout = true
         ensureCurrentSelectionVisible(horizontalIntent: .alignWithAppShelf(animated: false))
         needsLayout = true
         if animatedProjection, let transitionSnapshot {
             layoutSubtreeIfNeeded()
             applyProjectionTransitionAnimations(from: transitionSnapshot)
+        }
+    }
+
+    private func cachedThumbnailsByWindowID() -> [UInt32: Any] {
+        var snapshots: [UInt32: Any] = [:]
+
+        for card in waterfallCardsByWindowID().values {
+            snapshots[card.item.window.id] = card.thumbnailLayer.contents
+        }
+
+        return snapshots
+    }
+
+    private func restoreThumbnailsFromCache(_ cachedThumbnails: [UInt32: Any]) {
+        for card in waterfallCardsByWindowID().values {
+            if let thumbnail = cachedThumbnails[card.item.window.id] {
+                card.thumbnailLayer.contents = thumbnail
+            }
         }
     }
 
@@ -1178,8 +1362,22 @@
             "selectedAppGroupIndex": effectiveSelection?.appGroupIndex ?? NSNull(),
             "selectedWindowIndex": effectiveSelection?.windowIndex ?? NSNull(),
             "selectedWindowID": effectiveSelection?.windowID ?? NSNull(),
+            "keyboardFocusedAppGroupIndex": keyboardFocusedAppGroupIndex ?? NSNull(),
+            "keyboardFocusedWindowID": keyboardFocusedWindowID ?? NSNull(),
+            "horizontalAppDefaultWindowID": horizontalAppDefaultWindowID ?? NSNull(),
             "keyboardCommandsApplied": keyboardCommandsApplied,
             "lastKeyboardCommand": lastKeyboardCommand ?? NSNull(),
+            "lastKeyboardAppIndexCommand": lastKeyboardAppIndexCommand ?? NSNull(),
+            "appShelfIndexKeyDownCount": appShelfIndexKeyDownCount,
+            "lastAppShelfIndexKeySymbol": lastAppShelfIndexKeySymbol ?? NSNull(),
+            "windowIndexKeyPendingAppGroupIndex": windowIndexKeyPending?.appGroupIndex ?? NSNull(),
+            "windowIndexKeyPendingAppSymbol": windowIndexKeyPending?.appSymbol ?? NSNull(),
+            "lastWindowIndexKeyCommand": lastWindowIndexKeyCommand ?? NSNull(),
+            "lastWindowIndexKeyCommitCode": lastWindowIndexKeyCommitCode ?? NSNull(),
+            "lastBoundaryBounceAxis": lastBoundaryBounceAxis ?? NSNull(),
+            "lastBoundaryBounceDirection": lastBoundaryBounceDirection ?? NSNull(),
+            "boundaryBounceCount": boundaryBounceCount,
+            "selectionChangedByLastCommand": selectionChangedByLastCommand ?? NSNull(),
             "tabIgnoredCount": tabIgnoredCount,
             "lastCommittedAppGroupIndex": lastCommittedSelection?.appGroupIndex ?? NSNull(),
             "lastCommittedWindowIndex": lastCommittedSelection?.windowIndex ?? NSNull(),
@@ -1252,32 +1450,68 @@
             .lowercased()
         guard !command.isEmpty else { return }
 
+        if let indexSymbol = appShelfIndexSymbol(fromKeyboardCommand: command) {
+            let recordedCommand = "app:\(indexSymbol)"
+            recordKeyboardCommand(recordedCommand)
+            clearWindowIndexKeyPending()
+            if !focusAppShelfItemForKeyboard(indexSymbol: indexSymbol, commandLabel: recordedCommand) {
+                selectionChangedByLastCommand = false
+            }
+            return
+        }
+
         switch command {
         case "left":
+            clearWindowIndexKeyPending()
             recordKeyboardCommand("left")
-            moveSelection(.left)
+            if isHorizontalMasonryMode {
+                moveSelection(.left)
+            } else if !moveKeyboardAppFocus(cycleForward: false) {
+                selectionChangedByLastCommand = false
+            }
         case "right":
+            clearWindowIndexKeyPending()
             recordKeyboardCommand("right")
-            moveSelection(.right)
+            if isHorizontalMasonryMode {
+                moveSelection(.right)
+            } else if !moveKeyboardAppFocus(cycleForward: true) {
+                selectionChangedByLastCommand = false
+            }
         case "up":
+            clearWindowIndexKeyPending()
             recordKeyboardCommand("up")
-            moveSelection(.up)
+            if isHorizontalMasonryMode {
+                moveSelection(.up)
+            } else {
+                moveVerticalSelectionWithinFocusedColumn(.up)
+            }
         case "down":
+            clearWindowIndexKeyPending()
             recordKeyboardCommand("down")
-            moveSelection(.down)
+            if isHorizontalMasonryMode {
+                moveSelection(.down)
+            } else {
+                moveVerticalSelectionWithinFocusedColumn(.down)
+            }
         case "enter", "return", "commit":
+            clearWindowIndexKeyPending()
             recordKeyboardCommand("enter")
+            selectionChangedByLastCommand = false
             commitCurrentSelection()
         case "tab":
+            clearWindowIndexKeyPending()
             if isHorizontalMasonryMode {
                 recordKeyboardCommand("tab")
-                moveSelection(.right)
+                moveHorizontalMasonryTabSelection()
             } else {
                 tabIgnoredCount += 1
                 recordKeyboardCommand("tabIgnored")
+                selectionChangedByLastCommand = false
             }
         default:
+            clearWindowIndexKeyPending()
             recordKeyboardCommand("unknown:\(command)")
+            selectionChangedByLastCommand = false
         }
     }
 
@@ -1286,11 +1520,374 @@
         keyboardCommandsApplied.append(command)
     }
 
+    private func handleAppShelfIndexKey(_ event: NSEvent) -> Bool {
+        let flags = event.modifierFlags.intersection(.deviceIndependentFlagsMask)
+        guard flags.isDisjoint(with: [.command, .control]) else { return false }
+        guard let characters = event.charactersIgnoringModifiers,
+              let symbol = appShelfIndexSymbol(fromKeyboardCommand: characters)
+        else {
+            return false
+        }
+
+        appShelfIndexKeyDownCount += 1
+        lastAppShelfIndexKeySymbol = symbol
+        if flags.contains(.option), handleWindowIndexKey(symbol: symbol) {
+            return true
+        }
+        clearWindowIndexKeyPending()
+        performKeyboardCommand(symbol)
+        return true
+    }
+
+    private func handleWindowIndexKey(symbol: String) -> Bool {
+        let now = CACurrentMediaTime()
+        if let pending = validWindowIndexKeyPending(now: now) {
+            let code = "\(pending.appSymbol)\(symbol)"
+            if let card = waterfallCard(appGroupIndex: pending.appGroupIndex, windowIndexSymbol: symbol) {
+                recordKeyboardCommand("window:\(code)")
+                lastWindowIndexKeyCommand = "window:\(code)"
+                lastWindowIndexKeyCommitCode = code
+                clearWindowIndexKeyPending()
+                commitKeyboardWindowCard(card, trigger: "windowIndexKey")
+                return true
+            }
+
+            recordKeyboardCommand("windowInvalid:\(code)")
+            lastWindowIndexKeyCommand = "windowInvalid:\(code)"
+            lastWindowIndexKeyCommitCode = nil
+            selectionChangedByLastCommand = false
+            clearWindowIndexKeyPending()
+            return true
+        }
+
+        let recordedCommand = "app:\(symbol)"
+        recordKeyboardCommand(recordedCommand)
+        lastWindowIndexKeyCommand = nil
+        lastWindowIndexKeyCommitCode = nil
+        if focusAppShelfItemForKeyboard(indexSymbol: symbol, commandLabel: recordedCommand),
+           let ordinal = Self.appShelfIndexSymbols.firstIndex(of: symbol),
+           ordinal < appShelfItems.count {
+            setWindowIndexKeyPending(
+                appSymbol: symbol,
+                appGroupIndex: appShelfItems[ordinal].item.appGroupIndex,
+                startedAt: now
+            )
+        } else {
+            selectionChangedByLastCommand = false
+            clearWindowIndexKeyPending()
+        }
+        return true
+    }
+
+    private func appShelfIndexSymbol(fromKeyboardCommand command: String) -> String? {
+        var candidate = command.trimmingCharacters(in: .whitespacesAndNewlines).uppercased()
+        for prefix in ["APP:", "APP-", "INDEX:", "INDEX-"] where candidate.hasPrefix(prefix) {
+            candidate.removeFirst(prefix.count)
+            break
+        }
+        guard candidate.count == 1,
+              Self.appShelfIndexSymbols.contains(candidate)
+        else {
+            return nil
+        }
+        return candidate
+    }
+
+    private func focusAppShelfItemForKeyboard(indexSymbol: String, commandLabel: String) -> Bool {
+        guard let ordinal = Self.appShelfIndexSymbols.firstIndex(of: indexSymbol),
+              ordinal < appShelfItems.count
+        else {
+            return false
+        }
+
+        return focusAppShelfItemForKeyboard(
+            appGroupIndex: appShelfItems[ordinal].item.appGroupIndex,
+            appIndexCommand: commandLabel
+        )
+    }
+
+    private func validWindowIndexKeyPending(now: CFTimeInterval) -> WindowIndexKeyPending? {
+        guard let pending = windowIndexKeyPending else { return nil }
+        guard now - pending.startedAt <= Self.windowIndexKeyPendingInterval else {
+            clearWindowIndexKeyPending()
+            return nil
+        }
+        return pending
+    }
+
+    private func setWindowIndexKeyPending(appSymbol: String, appGroupIndex: Int, startedAt: CFTimeInterval) {
+        windowIndexKeyPendingClearTask?.cancel()
+        windowIndexKeyPending = WindowIndexKeyPending(
+            appSymbol: appSymbol,
+            appGroupIndex: appGroupIndex,
+            startedAt: startedAt
+        )
+        windowIndexKeyPendingClearTask = Task { @MainActor [weak self] in
+            do {
+                try await Task.sleep(nanoseconds: UInt64(Self.windowIndexKeyPendingInterval * 1_000_000_000))
+            } catch {
+                return
+            }
+            guard let self,
+                  let pending = self.windowIndexKeyPending,
+                  pending.appSymbol == appSymbol,
+                  pending.appGroupIndex == appGroupIndex,
+                  pending.startedAt == startedAt
+            else {
+                return
+            }
+            self.windowIndexKeyPending = nil
+            self.windowIndexKeyPendingClearTask = nil
+        }
+    }
+
+    private func clearWindowIndexKeyPending() {
+        windowIndexKeyPendingClearTask?.cancel()
+        windowIndexKeyPendingClearTask = nil
+        windowIndexKeyPending = nil
+    }
+
+    @discardableResult
+    private func focusAppShelfItemForKeyboard(
+        appGroupIndex: Int,
+        appIndexCommand: String? = nil
+    ) -> Bool {
+        guard appShelfItems.contains(where: { $0.item.appGroupIndex == appGroupIndex }),
+              waterfallColumns.contains(where: { $0.column.appGroupIndex == appGroupIndex })
+        else {
+            return false
+        }
+
+        keyboardFocusedAppGroupIndex = appGroupIndex
+        keyboardFocusedWindowID = nil
+        lastKeyboardAppIndexCommand = appIndexCommand
+        selectionChangedByLastCommand = false
+        clearKeyboardBoundaryFeedback()
+        ensureAppShelfItemVisible(appGroupIndex)
+        layoutSubtreeIfNeeded()
+        if isHorizontalMasonryMode {
+            _ = selectHorizontalMasonryDefaultWindowForApp(appGroupIndex)
+        }
+        hoverAppGroup(appGroupIndex, source: .keyboard)
+        needsLayout = true
+        return true
+    }
+
+    @discardableResult
+    private func moveKeyboardAppFocus(cycleForward: Bool) -> Bool {
+        let orderedAppGroupIndexes = appShelfItems.map(\.item.appGroupIndex)
+        guard !orderedAppGroupIndexes.isEmpty else { return false }
+
+        let currentAppGroupIndex = keyboardFocusedAppGroupIndex
+            ?? appHoverTargetAppGroupIndex
+            ?? effectiveSelection?.appGroupIndex
+        let currentPosition = currentAppGroupIndex.flatMap { orderedAppGroupIndexes.firstIndex(of: $0) }
+        let nextPosition = currentPosition.map { current in
+            if cycleForward {
+                return (current + 1) % orderedAppGroupIndexes.count
+            }
+            return (current - 1 + orderedAppGroupIndexes.count) % orderedAppGroupIndexes.count
+        } ?? (cycleForward ? 0 : orderedAppGroupIndexes.count - 1)
+
+        return focusAppShelfItemForKeyboard(appGroupIndex: orderedAppGroupIndexes[nextPosition])
+    }
+
+    private var appHoverTargetAppGroupIndex: Int? {
+        guard case .app(let appGroupIndex) = hoverTarget else { return nil }
+        return appGroupIndex
+    }
+
+    private var horizontalAppDefaultWindowID: UInt32? {
+        guard isHorizontalMasonryMode,
+              case .app(let appGroupIndex) = hoverTarget
+        else {
+            return nil
+        }
+        return firstHorizontalMasonryCard(for: appGroupIndex)?.item.window.id
+    }
+
+    private func firstHorizontalMasonryCard(for appGroupIndex: Int) -> WaterfallCardLayers? {
+        waterfallColumns
+            .first { $0.column.appGroupIndex == appGroupIndex }?
+            .cards
+            .sorted { $0.item.windowIndex < $1.item.windowIndex }
+            .first
+    }
+
+    private func isHorizontalAppDefaultCard(_ card: WaterfallCardLayers) -> Bool {
+        guard isHorizontalMasonryMode,
+              card.item.window.id == horizontalAppDefaultWindowID
+        else {
+            return false
+        }
+        return true
+    }
+
+    @discardableResult
+    private func selectHorizontalMasonryDefaultWindowForApp(
+        _ appGroupIndex: Int,
+        recordsSelectionChange: Bool = false
+    ) -> QuickSwitchSelection? {
+        guard isHorizontalMasonryMode,
+              let card = firstHorizontalMasonryCard(for: appGroupIndex)
+        else {
+            return nil
+        }
+
+        let previousSelection = effectiveSelection
+        let selection = selectionForCard(card)
+        currentSelection = selection
+        columnSelectionHistory[selection.appGroupIndex] = selection.windowIndex
+        if recordsSelectionChange {
+            selectionChangedByLastCommand = previousSelection != selection
+        }
+        return selection
+    }
+
+    private func moveVerticalSelectionWithinFocusedColumn(_ direction: QuickSwitchKeyboardDirection) {
+        guard direction == .up || direction == .down,
+              let targetAppGroupIndex = verticalKeyboardNavigationAppGroupIndex(),
+              let column = waterfallColumns.first(where: { $0.column.appGroupIndex == targetAppGroupIndex })
+        else {
+            DevelopmentDiagnostics.log("quickSwitch.view.moveVerticalSelection.blocked", [
+                "direction": keyboardDirectionName(direction),
+                "hasFocusedApp": keyboardFocusedAppGroupIndex != nil,
+                "hasSelection": effectiveSelection != nil
+            ])
+            selectionChangedByLastCommand = false
+            return
+        }
+
+        let cards = column.cards.sorted { $0.item.windowIndex < $1.item.windowIndex }
+        guard !cards.isEmpty else {
+            selectionChangedByLastCommand = false
+            return
+        }
+
+        let previousSelection = effectiveSelection
+        let nextSelection: QuickSwitchSelection
+        if let current = previousSelection,
+           current.appGroupIndex == targetAppGroupIndex,
+           let currentPosition = cards.firstIndex(where: { $0.item.window.id == current.windowID }) {
+            let nextPosition = currentPosition + (direction == .down ? 1 : -1)
+            guard cards.indices.contains(nextPosition) else {
+                keyboardFocusedAppGroupIndex = targetAppGroupIndex
+                hoverAppGroup(targetAppGroupIndex, source: .keyboard)
+                triggerKeyboardBoundaryFeedback(appGroupIndex: targetAppGroupIndex, direction: direction)
+                DevelopmentDiagnostics.log("quickSwitch.view.moveVerticalSelection.boundary", [
+                    "direction": keyboardDirectionName(direction),
+                    "appGroupIndex": targetAppGroupIndex,
+                    "windowIndex": current.windowIndex
+                ])
+                needsLayout = true
+                return
+            }
+            nextSelection = selectionForCard(cards[nextPosition])
+        } else {
+            let rememberedWindowIndex = columnSelectionHistory[targetAppGroupIndex]
+            let rememberedCard = rememberedWindowIndex.flatMap { windowIndex in
+                cards.first { $0.item.windowIndex == windowIndex }
+            }
+            nextSelection = selectionForCard(rememberedCard ?? cards[0])
+        }
+
+        keyboardFocusedAppGroupIndex = targetAppGroupIndex
+        currentSelection = nextSelection
+        keyboardFocusedWindowID = nextSelection.windowID
+        columnSelectionHistory[nextSelection.appGroupIndex] = nextSelection.windowIndex
+        selectionChangedByLastCommand = previousSelection != nextSelection
+        clearKeyboardBoundaryFeedback()
+        hoverAppGroup(targetAppGroupIndex, source: .keyboard)
+        ensureCurrentSelectionVisible(horizontalIntent: .alignWithAppShelf(animated: true))
+        DevelopmentDiagnostics.log("quickSwitch.view.moveVerticalSelection", [
+            "direction": keyboardDirectionName(direction),
+            "appGroupIndex": nextSelection.appGroupIndex,
+            "windowIndex": nextSelection.windowIndex,
+            "windowID": nextSelection.windowID
+        ])
+        needsLayout = true
+    }
+
+    private func verticalKeyboardNavigationAppGroupIndex() -> Int? {
+        if let keyboardFocusedAppGroupIndex,
+           waterfallColumns.contains(where: { $0.column.appGroupIndex == keyboardFocusedAppGroupIndex }) {
+            return keyboardFocusedAppGroupIndex
+        }
+        if let appHoverTargetAppGroupIndex,
+           waterfallColumns.contains(where: { $0.column.appGroupIndex == appHoverTargetAppGroupIndex }) {
+            return appHoverTargetAppGroupIndex
+        }
+        if let appGroupIndex = effectiveSelection?.appGroupIndex,
+           waterfallColumns.contains(where: { $0.column.appGroupIndex == appGroupIndex }) {
+            return appGroupIndex
+        }
+        return waterfallColumns.first?.column.appGroupIndex
+    }
+
+    private func clearKeyboardBoundaryFeedback() {
+        lastBoundaryBounceAxis = nil
+        lastBoundaryBounceDirection = nil
+    }
+
+    private func triggerKeyboardBoundaryFeedback(
+        appGroupIndex: Int,
+        direction: QuickSwitchKeyboardDirection
+    ) {
+        selectionChangedByLastCommand = false
+        lastBoundaryBounceAxis = "vertical"
+        lastBoundaryBounceDirection = keyboardDirectionName(direction)
+        boundaryBounceCount += 1
+
+        layoutSubtreeIfNeeded()
+        guard let column = waterfallColumns.first(where: { $0.column.appGroupIndex == appGroupIndex }) else { return }
+
+        let animationKey = "keyboardBoundaryBounce"
+        column.containerLayer.removeAnimation(forKey: animationKey)
+        if NSWorkspace.shared.accessibilityDisplayShouldReduceMotion {
+            let pulse = CABasicAnimation(keyPath: "opacity")
+            pulse.fromValue = 1
+            pulse.toValue = 0.9
+            pulse.duration = 0.12
+            pulse.autoreverses = true
+            pulse.timingFunction = CAMediaTimingFunction(name: .easeInEaseOut)
+            column.containerLayer.add(pulse, forKey: animationKey)
+            return
+        }
+
+        let currentY = column.containerLayer.presentation()?.position.y
+            ?? column.containerLayer.position.y
+        let delta: CGFloat = direction == .up ? 5 : -5
+        let bounce = CAKeyframeAnimation(keyPath: "position.y")
+        bounce.values = [currentY, currentY + delta, currentY]
+        bounce.keyTimes = [0, 0.38, 1]
+        bounce.timingFunctions = [
+            CAMediaTimingFunction(name: .easeOut),
+            CAMediaTimingFunction(name: .easeInEaseOut)
+        ]
+        bounce.duration = 0.23
+        bounce.isRemovedOnCompletion = true
+        column.containerLayer.add(bounce, forKey: animationKey)
+    }
+
+    private func keyboardDirectionName(_ direction: QuickSwitchKeyboardDirection) -> String {
+        switch direction {
+        case .left:
+            return "left"
+        case .right:
+            return "right"
+        case .up:
+            return "up"
+        case .down:
+            return "down"
+        }
+    }
+
     private func performMouseCommand(_ rawCommand: String) {
         let command = rawCommand
             .trimmingCharacters(in: .whitespacesAndNewlines)
             .lowercased()
         guard !command.isEmpty else { return }
+        clearWindowIndexKeyPending()
 
         let parts = command.split(separator: ":").map(String.init)
         switch parts.first {
@@ -1436,13 +2033,13 @@
         return command.hasPrefix("hover-")
     }
 
-    private func hoverAppGroup(_ appGroupIndex: Int) {
+    private func hoverAppGroup(_ appGroupIndex: Int, source: HoverTargetSource = .debug) {
         updateHoverState(
             appGroupIndex: appGroupIndex,
             windowID: nil,
             spaceID: nil,
             alignsWaterfallWithAppShelf: true,
-            source: .debug
+            source: source
         )
     }
 
@@ -1601,6 +2198,34 @@
         commitWindowCard(card, trigger: "windowCard")
     }
 
+    private func commitKeyboardWindowCard(_ card: WaterfallCardLayers, trigger: String) {
+        let selection = QuickSwitchSelection(
+            appGroupIndex: card.item.appGroupIndex,
+            windowIndex: card.item.windowIndex,
+            windowID: card.item.window.id
+        )
+        DevelopmentDiagnostics.log("quickSwitch.view.commitKeyboardWindow", [
+            "trigger": trigger,
+            "appGroupIndex": selection.appGroupIndex,
+            "windowIndex": selection.windowIndex,
+            "windowID": selection.windowID,
+            "appName": card.item.window.app.name,
+            "appPID": card.item.window.app.processIdentifier,
+            "titleHash": DevelopmentDiagnostics.stableFingerprint(card.item.window.title),
+            "titleLength": card.item.window.title.count,
+            "titleIsEmpty": card.item.window.title.isEmpty,
+            "isMinimized": card.item.window.isMinimized,
+            "isFullscreen": card.item.window.isFullscreen,
+            "identifierSource": String(describing: card.item.window.identifierSource)
+        ])
+        currentSelection = selection
+        columnSelectionHistory[selection.appGroupIndex] = selection.windowIndex
+        lastCommittedSelection = selection
+        lastCommitSource = .keyboard
+        ensureCurrentSelectionVisible()
+        onCommitSelection?(selection, .keyboard)
+    }
+
     private func commitWindowCard(_ card: WaterfallCardLayers, trigger: String) {
         let selection = QuickSwitchSelection(
             appGroupIndex: card.item.appGroupIndex,
@@ -1690,6 +2315,11 @@
         hoveredSpaceID = target.spaceID
         hoveredSpaceLaneID = target.spaceLaneID
 
+        if case .app(let appGroupIndex) = target, isHorizontalMasonryMode {
+            keyboardFocusedWindowID = nil
+            _ = selectHorizontalMasonryDefaultWindowForApp(appGroupIndex)
+        }
+
         if alignsWaterfallWithAppShelf, let appGroupIndex = target.appGroupIndex {
             alignWaterfallColumnWithAppShelfIcon(appGroupIndex: appGroupIndex, animated: true)
         }
@@ -1723,8 +2353,11 @@
         }
 
         columnSelectionHistory[current.appGroupIndex] = current.windowIndex
+        let previousSelection = effectiveSelection
         currentSelection = next
         columnSelectionHistory[next.appGroupIndex] = next.windowIndex
+        selectionChangedByLastCommand = previousSelection != next
+        clearKeyboardBoundaryFeedback()
         ensureCurrentSelectionVisible(horizontalIntent: .alignWithAppShelf(animated: true))
         DevelopmentDiagnostics.log("quickSwitch.view.moveSelection", [
             "direction": String(describing: direction),
@@ -1736,26 +2369,360 @@
     }
 
     private func moveHorizontalMasonrySelection(_ direction: QuickSwitchKeyboardDirection) {
-        guard let current = currentSelection ?? currentViewModel?.initialSelection,
-              let next = nextHorizontalMasonrySelection(from: current, direction: direction)
+        layoutSubtreeIfNeeded()
+
+        let nodes = horizontalKeyboardFocusNodes()
+        guard !nodes.isEmpty,
+              let current = currentHorizontalKeyboardFocusNode(in: nodes),
+              let next = nextHorizontalKeyboardFocusNode(from: current, direction: direction, in: nodes)
         else {
             DevelopmentDiagnostics.log("quickSwitch.view.moveHorizontalMasonrySelection.blocked", [
                 "direction": String(describing: direction),
+                "hasNodes": !nodes.isEmpty,
                 "hasSelection": (currentSelection ?? currentViewModel?.initialSelection) != nil
             ])
+            selectionChangedByLastCommand = false
+            return
+        }
+
+        focusHorizontalKeyboardNode(next, direction: direction)
+        DevelopmentDiagnostics.log("quickSwitch.view.moveHorizontalMasonrySelection", [
+            "direction": String(describing: direction),
+            "kind": next.kind.rawValue,
+            "appGroupIndex": next.appGroupIndex,
+            "windowIndex": next.windowIndex ?? -1,
+            "windowID": next.windowID ?? 0
+        ])
+    }
+
+    private func moveHorizontalMasonryTabSelection() {
+        guard let current = currentSelection ?? currentViewModel?.initialSelection,
+              let next = nextHorizontalMasonrySelection(from: current, direction: .right)
+        else {
+            DevelopmentDiagnostics.log("quickSwitch.view.moveHorizontalMasonryTabSelection.blocked", [
+                "hasSelection": (currentSelection ?? currentViewModel?.initialSelection) != nil
+            ])
+            selectionChangedByLastCommand = false
             return
         }
 
         columnSelectionHistory[current.appGroupIndex] = current.windowIndex
+        let previousSelection = effectiveSelection
         currentSelection = next
+        keyboardFocusedAppGroupIndex = next.appGroupIndex
+        keyboardFocusedWindowID = next.windowID
         columnSelectionHistory[next.appGroupIndex] = next.windowIndex
+        selectionChangedByLastCommand = previousSelection != next
+        clearKeyboardBoundaryFeedback()
+        setHoverTarget(
+            .window(appGroupIndex: next.appGroupIndex, windowID: next.windowID, spaceID: nil),
+            source: .keyboard
+        )
         ensureCurrentSelectionVisible(horizontalIntent: .alignWithAppShelf(animated: true))
-        DevelopmentDiagnostics.log("quickSwitch.view.moveHorizontalMasonrySelection", [
-            "direction": String(describing: direction),
+        DevelopmentDiagnostics.log("quickSwitch.view.moveHorizontalMasonryTabSelection", [
             "appGroupIndex": next.appGroupIndex,
             "windowIndex": next.windowIndex,
             "windowID": next.windowID
         ])
+        needsLayout = true
+    }
+
+    private func horizontalKeyboardFocusNodes() -> [HorizontalKeyboardFocusNode] {
+        var nodes: [HorizontalKeyboardFocusNode] = []
+        nodes.reserveCapacity(appShelfItems.count + waterfallColumns.reduce(0) { $0 + $1.cards.count })
+
+        for (index, item) in appShelfItems.enumerated() {
+            let frame = item.iconLayer.frame.offsetBy(
+                dx: shelfLayer.frame.minX
+                    + appShelfContentLayer.frame.minX
+                    + item.containerLayer.frame.minX,
+                dy: shelfLayer.frame.minY
+                    + appShelfContentLayer.frame.minY
+                    + item.containerLayer.frame.minY
+            )
+            nodes.append(HorizontalKeyboardFocusNode(
+                kind: .app,
+                appGroupIndex: item.item.appGroupIndex,
+                windowIndex: nil,
+                windowID: nil,
+                spaceID: nil,
+                frame: frame,
+                order: index
+            ))
+        }
+
+        var order = appShelfItems.count
+        for column in waterfallColumns.sorted(by: { $0.column.appGroupIndex < $1.column.appGroupIndex }) {
+            for card in column.cards.sorted(by: { $0.item.windowIndex < $1.item.windowIndex }) {
+                let frame = card.containerLayer.frame.offsetBy(
+                    dx: waterfallLayer.frame.minX
+                        + waterfallContentLayer.frame.minX
+                        + column.containerLayer.frame.minX
+                        + column.cardsClipLayer.frame.minX,
+                    dy: waterfallLayer.frame.minY
+                        + waterfallContentLayer.frame.minY
+                        + column.containerLayer.frame.minY
+                        + column.cardsClipLayer.frame.minY
+                )
+                nodes.append(HorizontalKeyboardFocusNode(
+                    kind: .window,
+                    appGroupIndex: card.item.appGroupIndex,
+                    windowIndex: card.item.windowIndex,
+                    windowID: card.item.window.id,
+                    spaceID: card.item.primarySpaceID,
+                    frame: frame,
+                    order: order
+                ))
+                order += 1
+            }
+        }
+
+        return nodes
+    }
+
+    private func currentHorizontalKeyboardFocusNode(
+        in nodes: [HorizontalKeyboardFocusNode]
+    ) -> HorizontalKeyboardFocusNode? {
+        if case .app(let appGroupIndex) = hoverTarget,
+           let node = nodes.first(where: { $0.kind == .app && $0.appGroupIndex == appGroupIndex }) {
+            return node
+        }
+
+        if let keyboardFocusedWindowID,
+           let node = nodes.first(where: { $0.kind == .window && $0.windowID == keyboardFocusedWindowID }) {
+            return node
+        }
+
+        if case .window(_, let windowID, _) = hoverTarget,
+           let node = nodes.first(where: { $0.kind == .window && $0.windowID == windowID }) {
+            return node
+        }
+
+        if let selection = effectiveSelection,
+           let node = nodes.first(where: { $0.kind == .window && $0.windowID == selection.windowID }) {
+            return node
+        }
+
+        return nodes.min { $0.order < $1.order }
+    }
+
+    private func nextHorizontalKeyboardFocusNode(
+        from current: HorizontalKeyboardFocusNode,
+        direction: QuickSwitchKeyboardDirection,
+        in nodes: [HorizontalKeyboardFocusNode]
+    ) -> HorizontalKeyboardFocusNode? {
+        let candidates = nodes.filter { !$0.matches(current) }
+        guard !candidates.isEmpty else { return current }
+
+        if current.kind == .app,
+           direction == .down,
+           let firstWindow = firstHorizontalWindowNode(for: current.appGroupIndex, in: nodes) {
+            return firstWindow
+        }
+
+        if current.kind == .window,
+           direction == .up,
+           current.windowID == firstHorizontalMasonryCard(for: current.appGroupIndex)?.item.window.id,
+           let appNode = nodes.first(where: { $0.kind == .app && $0.appGroupIndex == current.appGroupIndex }) {
+            return appNode
+        }
+
+        switch direction {
+        case .left, .right:
+            let sameKindCandidates = candidates.filter { $0.kind == current.kind }
+            return nextHorizontalFocusByX(
+                from: current,
+                direction: direction,
+                candidates: sameKindCandidates.isEmpty ? candidates : sameKindCandidates
+            )
+        case .up, .down:
+            return nextHorizontalFocusByY(from: current, direction: direction, candidates: candidates)
+        }
+    }
+
+    private func firstHorizontalWindowNode(
+        for appGroupIndex: Int,
+        in nodes: [HorizontalKeyboardFocusNode]
+    ) -> HorizontalKeyboardFocusNode? {
+        nodes
+            .filter { $0.kind == .window && $0.appGroupIndex == appGroupIndex }
+            .min { lhs, rhs in
+                (lhs.windowIndex ?? .max, lhs.order) < (rhs.windowIndex ?? .max, rhs.order)
+            }
+    }
+
+    private func nextHorizontalFocusByX(
+        from current: HorizontalKeyboardFocusNode,
+        direction: QuickSwitchKeyboardDirection,
+        candidates: [HorizontalKeyboardFocusNode]
+    ) -> HorizontalKeyboardFocusNode? {
+        let epsilon: CGFloat = 0.5
+        let forward = direction == .right
+        let directional = candidates.filter { node in
+            forward
+                ? node.center.x > current.center.x + epsilon
+                : node.center.x < current.center.x - epsilon
+        }
+        let sameBand = directional.filter { isHorizontalFocusSameBand($0, current) }
+        let pool = sameBand.isEmpty ? directional : sameBand
+        if let next = pool.sorted(by: horizontalFocusXSort(from: current, forward: forward)).first {
+            return next
+        }
+
+        let wrapSameBand = candidates.filter { isHorizontalFocusSameBand($0, current) }
+        let wrapPool = wrapSameBand.isEmpty ? candidates : wrapSameBand
+        return wrapPool.sorted(by: horizontalFocusXWrapSort(from: current, forward: forward)).first
+    }
+
+    private func nextHorizontalFocusByY(
+        from current: HorizontalKeyboardFocusNode,
+        direction: QuickSwitchKeyboardDirection,
+        candidates: [HorizontalKeyboardFocusNode]
+    ) -> HorizontalKeyboardFocusNode? {
+        let epsilon: CGFloat = 0.5
+        let upward = direction == .up
+        let directional = candidates.filter { node in
+            upward
+                ? node.center.y > current.center.y + epsilon
+                : node.center.y < current.center.y - epsilon
+        }
+        if let next = directional.sorted(by: horizontalFocusYSort(from: current, upward: upward)).first {
+            return next
+        }
+        return candidates.sorted(by: horizontalFocusYWrapSort(from: current, upward: upward)).first
+    }
+
+    private func isHorizontalFocusSameBand(
+        _ lhs: HorizontalKeyboardFocusNode,
+        _ rhs: HorizontalKeyboardFocusNode
+    ) -> Bool {
+        let tolerance = max(lhs.frame.height, rhs.frame.height) * 0.75
+        return abs(lhs.center.y - rhs.center.y) <= tolerance
+    }
+
+    private func horizontalFocusXSort(
+        from current: HorizontalKeyboardFocusNode,
+        forward: Bool
+    ) -> (HorizontalKeyboardFocusNode, HorizontalKeyboardFocusNode) -> Bool {
+        { lhs, rhs in
+            let lhsPrimary = abs(lhs.center.x - current.center.x)
+            let rhsPrimary = abs(rhs.center.x - current.center.x)
+            if abs(lhsPrimary - rhsPrimary) > 0.5 {
+                return lhsPrimary < rhsPrimary
+            }
+
+            let lhsSecondary = abs(lhs.center.y - current.center.y)
+            let rhsSecondary = abs(rhs.center.y - current.center.y)
+            if abs(lhsSecondary - rhsSecondary) > 0.5 {
+                return lhsSecondary < rhsSecondary
+            }
+
+            return forward ? lhs.order < rhs.order : lhs.order > rhs.order
+        }
+    }
+
+    private func horizontalFocusXWrapSort(
+        from current: HorizontalKeyboardFocusNode,
+        forward: Bool
+    ) -> (HorizontalKeyboardFocusNode, HorizontalKeyboardFocusNode) -> Bool {
+        { lhs, rhs in
+            if abs(lhs.center.x - rhs.center.x) > 0.5 {
+                return forward ? lhs.center.x < rhs.center.x : lhs.center.x > rhs.center.x
+            }
+
+            let lhsSecondary = abs(lhs.center.y - current.center.y)
+            let rhsSecondary = abs(rhs.center.y - current.center.y)
+            if abs(lhsSecondary - rhsSecondary) > 0.5 {
+                return lhsSecondary < rhsSecondary
+            }
+
+            return forward ? lhs.order < rhs.order : lhs.order > rhs.order
+        }
+    }
+
+    private func horizontalFocusYSort(
+        from current: HorizontalKeyboardFocusNode,
+        upward: Bool
+    ) -> (HorizontalKeyboardFocusNode, HorizontalKeyboardFocusNode) -> Bool {
+        { lhs, rhs in
+            let lhsPrimary = abs(lhs.center.y - current.center.y)
+            let rhsPrimary = abs(rhs.center.y - current.center.y)
+            if abs(lhsPrimary - rhsPrimary) > 0.5 {
+                return lhsPrimary < rhsPrimary
+            }
+
+            let lhsSecondary = abs(lhs.center.x - current.center.x)
+            let rhsSecondary = abs(rhs.center.x - current.center.x)
+            if abs(lhsSecondary - rhsSecondary) > 0.5 {
+                return lhsSecondary < rhsSecondary
+            }
+
+            return upward ? lhs.order < rhs.order : lhs.order > rhs.order
+        }
+    }
+
+    private func horizontalFocusYWrapSort(
+        from current: HorizontalKeyboardFocusNode,
+        upward: Bool
+    ) -> (HorizontalKeyboardFocusNode, HorizontalKeyboardFocusNode) -> Bool {
+        { lhs, rhs in
+            if abs(lhs.center.y - rhs.center.y) > 0.5 {
+                return upward ? lhs.center.y < rhs.center.y : lhs.center.y > rhs.center.y
+            }
+
+            let lhsSecondary = abs(lhs.center.x - current.center.x)
+            let rhsSecondary = abs(rhs.center.x - current.center.x)
+            if abs(lhsSecondary - rhsSecondary) > 0.5 {
+                return lhsSecondary < rhsSecondary
+            }
+
+            return upward ? lhs.order < rhs.order : lhs.order > rhs.order
+        }
+    }
+
+    private func focusHorizontalKeyboardNode(
+        _ node: HorizontalKeyboardFocusNode,
+        direction _: QuickSwitchKeyboardDirection
+    ) {
+        switch node.kind {
+        case .app:
+            keyboardFocusedAppGroupIndex = node.appGroupIndex
+            keyboardFocusedWindowID = nil
+            clearKeyboardBoundaryFeedback()
+            ensureAppShelfItemVisible(node.appGroupIndex)
+            _ = selectHorizontalMasonryDefaultWindowForApp(
+                node.appGroupIndex,
+                recordsSelectionChange: true
+            )
+            hoverAppGroup(node.appGroupIndex, source: .keyboard)
+        case .window:
+            guard let windowIndex = node.windowIndex,
+                  let windowID = node.windowID
+            else {
+                selectionChangedByLastCommand = false
+                return
+            }
+
+            let previousSelection = effectiveSelection
+            let next = QuickSwitchSelection(
+                appGroupIndex: node.appGroupIndex,
+                windowIndex: windowIndex,
+                windowID: windowID
+            )
+            keyboardFocusedAppGroupIndex = node.appGroupIndex
+            keyboardFocusedWindowID = windowID
+            currentSelection = next
+            columnSelectionHistory[next.appGroupIndex] = next.windowIndex
+            selectionChangedByLastCommand = previousSelection != next
+            clearKeyboardBoundaryFeedback()
+            ensureAppShelfItemVisible(node.appGroupIndex)
+            setHoverTarget(
+                .window(appGroupIndex: node.appGroupIndex, windowID: windowID, spaceID: node.spaceID),
+                source: .keyboard
+            )
+            ensureCurrentSelectionVisible(horizontalIntent: .alignWithAppShelf(animated: true))
+        }
+
         needsLayout = true
     }
 
@@ -2337,7 +3304,7 @@
             item.containerLayer.removeFromSuperlayer()
         }
 
-        appShelfItems = (currentViewModel?.appShelf ?? []).map { item in
+        appShelfItems = (currentViewModel?.appShelf ?? []).enumerated().map { ordinal, item in
             let container = CALayer()
             container.name = item.app.name
 
@@ -2353,6 +3320,18 @@
             icon.contents = appIconProvider.icon(for: item.app)
             icon.cornerRadius = 12
             icon.masksToBounds = false
+
+            let indexLabel = makeTextLayer(
+                string: appShelfIndexText(forOrdinal: ordinal),
+                fontSize: AppShelfMetrics.indexFontSize,
+                weight: .regular,
+                color: appShelfIndexColor,
+                alignment: .center
+            )
+            indexLabel.font = appShelfIndexFont(size: AppShelfMetrics.indexFontSize)
+            indexLabel.fontSize = AppShelfMetrics.indexFontSize
+            indexLabel.truncationMode = .end
+            indexLabel.zPosition = 14
 
             let label = makeTextLayer(
                 string: item.app.name,
@@ -2378,6 +3357,7 @@
             let closeButton = makeCloseButtonLayers()
 
             container.addSublayer(background)
+            container.addSublayer(indexLabel)
             container.addSublayer(icon)
             container.addSublayer(label)
             container.addSublayer(badge)
@@ -2388,6 +3368,7 @@
                 item: item,
                 containerLayer: container,
                 backgroundLayer: background,
+                indexLayer: indexLabel,
                 iconLayer: icon,
                 labelLayer: label,
                 badgeLayer: badge,
@@ -2412,8 +3393,13 @@
             container.borderColor = NSColor.separatorColor.withAlphaComponent(0.34).cgColor
             container.borderWidth = 1
 
+            let cardsClip = CALayer()
+            cardsClip.masksToBounds = true
+            cardsClip.backgroundColor = NSColor.clear.cgColor
+
             let header = CALayer()
             header.backgroundColor = NSColor.controlBackgroundColor.withAlphaComponent(0.68).cgColor
+            header.zPosition = 40
 
             let appName = makeTextLayer(
                 string: column.app.name,
@@ -2430,6 +3416,10 @@
                 alignment: .right
             )
 
+            appName.zPosition = 42
+            count.zPosition = 42
+
+            container.addSublayer(cardsClip)
             container.addSublayer(header)
             container.addSublayer(appName)
             container.addSublayer(count)
@@ -2461,7 +3451,8 @@
                     string: waterfallMetaText(for: window),
                     fontSize: 10,
                     weight: .regular,
-                    color: .secondaryLabelColor
+                    color: .secondaryLabelColor,
+                    alignment: .right
                 )
                 let appIcon = CALayer()
                 appIcon.contentsGravity = .resizeAspect
@@ -2496,7 +3487,7 @@
                 card.addSublayer(state)
                 card.addSublayer(shine)
                 card.addSublayer(closeButton.containerLayer)
-                container.addSublayer(card)
+                cardsClip.addSublayer(card)
 
                 return WaterfallCardLayers(
                     item: window,
@@ -2517,6 +3508,7 @@
             return WaterfallColumnLayers(
                 column: column,
                 containerLayer: container,
+                cardsClipLayer: cardsClip,
                 headerLayer: header,
                 appNameLayer: appName,
                 countLayer: count,
@@ -3236,7 +4228,14 @@
                 x: locationInWaterfallContent.x - column.containerLayer.frame.minX,
                 y: locationInWaterfallContent.y - column.containerLayer.frame.minY
             )
-            if let card = column.cards.first(where: { $0.containerLayer.frame.contains(locationInColumn) }) {
+            guard column.cardsClipLayer.frame.contains(locationInColumn) else {
+                continue
+            }
+            let locationInCardsClip = CGPoint(
+                x: locationInColumn.x - column.cardsClipLayer.frame.minX,
+                y: locationInColumn.y - column.cardsClipLayer.frame.minY
+            )
+            if let card = column.cards.first(where: { $0.containerLayer.frame.contains(locationInCardsClip) }) {
                 return card
             }
         }
@@ -3249,6 +4248,15 @@
             .first(where: { $0.column.appGroupIndex == appGroupIndex })?
             .cards
             .first(where: { $0.item.windowIndex == windowIndex })
+    }
+
+    private func waterfallCard(appGroupIndex: Int, windowIndexSymbol: String) -> WaterfallCardLayers? {
+        guard let ordinal = Self.appShelfIndexSymbols.firstIndex(of: windowIndexSymbol),
+              ordinal < Self.appShelfIndexSymbols.count
+        else {
+            return nil
+        }
+        return waterfallCard(appGroupIndex: appGroupIndex, windowIndex: ordinal)
     }
 
     private func waterfallCard(windowID: UInt32) -> WaterfallCardLayers? {
@@ -3421,6 +4429,13 @@
             )
             : nil
         item.iconLayer.frame = CGRect(x: iconX, y: iconY, width: visualIconSize, height: visualIconSize)
+        layoutAppShelfIndexLayer(
+            item.indexLayer,
+            iconFrame: item.iconLayer.frame,
+            iconSize: visualIconSize,
+            itemBounds: bounds,
+            highlighted: showsSelectedVisual || isHovered
+        )
         item.labelLayer.contentsScale = backingScaleFactor
         item.labelLayer.frame = CGRect(x: 0, y: 0, width: bounds.width, height: 14)
         item.badgeLayer.string = badgeText
@@ -3446,6 +4461,66 @@
         )
         item.selectedIndicatorLayer.frame = .zero
         item.selectedIndicatorLayer.backgroundColor = NSColor.clear.cgColor
+    }
+
+    private var appShelfIndexColor: NSColor {
+        NSColor.labelColor.withAlphaComponent(0.48)
+    }
+
+    private var appShelfIndexHighlightedColor: NSColor {
+        NSColor.labelColor.withAlphaComponent(0.58)
+    }
+
+    private func appShelfIndexFont(size: CGFloat) -> NSFont {
+        for fontName in ["Bradley Hand ITC", "Noteworthy-Light", "Marker Felt", "Snell Roundhand"] {
+            if let font = NSFont(name: fontName, size: size) {
+                return font
+            }
+        }
+
+        return NSFont.monospacedSystemFont(ofSize: size, weight: .regular)
+    }
+
+    private func appShelfIndexText(forOrdinal ordinal: Int) -> String {
+        guard ordinal >= 0 else { return "" }
+        if ordinal < Self.appShelfIndexSymbols.count {
+            return Self.appShelfIndexSymbols[ordinal]
+        }
+
+        let overflowIndex = ordinal - Self.appShelfIndexSymbols.count
+        let prefix = Self.appShelfIndexSymbols[10 + (overflowIndex / 26) % 26]
+        let suffix = Self.appShelfIndexSymbols[10 + overflowIndex % 26]
+        return "\(prefix)\(suffix)"
+    }
+
+    private func layoutAppShelfIndexLayer(
+        _ layer: CATextLayer,
+        iconFrame: CGRect,
+        iconSize: CGFloat,
+        itemBounds: CGRect,
+        highlighted: Bool
+    ) {
+        let fontSize = iconSize <= AppShelfMetrics.minIconSize + 1
+            ? AppShelfMetrics.compressedIndexFontSize
+            : AppShelfMetrics.indexFontSize
+        layer.contentsScale = backingScaleFactor
+        layer.font = appShelfIndexFont(size: fontSize)
+        layer.fontSize = fontSize
+        layer.foregroundColor = (highlighted ? appShelfIndexHighlightedColor : appShelfIndexColor).cgColor
+        layer.opacity = 1
+
+        let indexWidth = AppShelfMetrics.indexWidth
+        let indexHeight = AppShelfMetrics.indexHeight
+        let preferredX = iconFrame.minX - indexWidth - 2
+        let clampedX = max(-7, min(itemBounds.width - indexWidth, preferredX))
+        let preferredY = iconFrame.maxY - indexHeight + 6
+        let clampedY = max(0, min(itemBounds.height - indexHeight, preferredY))
+        layer.frame = CGRect(
+            x: clampedX,
+            y: clampedY,
+            width: indexWidth,
+            height: indexHeight
+        )
     }
 
     private func appShelfRows() -> [[AppShelfItemLayers]] {
@@ -3648,6 +4723,10 @@
         return item.item.windowCount > 1 ? "\(item.item.windowCount)" : ""
     }
 
+    private var waterfallAppHoverHeaderFillColor: NSColor {
+        NSColor.systemGray.withAlphaComponent(0.22)
+    }
+
     private var appShelfMaxScrollOffset: CGFloat {
         max(0, appShelfContentWidth - shelfLayer.bounds.width)
     }
@@ -3728,11 +4807,14 @@
             column.containerLayer.shadowOpacity = 0
             column.containerLayer.shadowRadius = 0
             column.containerLayer.shadowOffset = .zero
+            column.cardsClipLayer.frame = column.containerLayer.bounds
+            column.cardsClipLayer.masksToBounds = false
             column.headerLayer.isHidden = true
             column.appNameLayer.isHidden = true
             column.countLayer.isHidden = true
 
             for card in column.cards {
+                card.containerLayer.transform = CATransform3DIdentity
                 if let frame = layout.cardFramesByWindowID[card.item.window.id] {
                     card.containerLayer.frame = frame
                 } else {
@@ -3866,6 +4948,14 @@
         column.countLayer.isHidden = false
 
         let bounds = column.containerLayer.bounds
+        let cardsClipFrame = CGRect(
+            x: 0,
+            y: 0,
+            width: bounds.width,
+            height: max(1, bounds.height - WaterfallMetrics.headerHeight)
+        )
+        column.cardsClipLayer.frame = cardsClipFrame
+        column.cardsClipLayer.masksToBounds = true
         let isSpaceFocused = spaceFocusWindowCount(for: column.column.appGroupIndex) > 0
         let isHovered = column.column.appGroupIndex == effectiveHoveredAppGroupIndex
         column.containerLayer.borderColor = (isSpaceFocused
@@ -3880,7 +4970,7 @@
             height: WaterfallMetrics.headerHeight
         )
         column.headerLayer.backgroundColor = (isHovered
-            ? viewModeToggleBlueColor
+            ? waterfallAppHoverHeaderFillColor
             : (isSpaceFocused
                 ? NSColor.systemFill.withAlphaComponent(0.10)
                 : NSColor.controlBackgroundColor.withAlphaComponent(0.52))
@@ -3891,14 +4981,14 @@
             width: max(1, bounds.width - WaterfallMetrics.columnHeaderTextInset * 2),
             height: 16
         )
-        column.appNameLayer.foregroundColor = (isHovered ? NSColor.white : NSColor.labelColor).cgColor
+        column.appNameLayer.foregroundColor = NSColor.labelColor.cgColor
         column.countLayer.frame = CGRect(
             x: bounds.width - 48,
             y: bounds.height - 24,
             width: 36,
             height: 16
         )
-        column.countLayer.foregroundColor = (isHovered ? NSColor.white : NSColor.secondaryLabelColor).cgColor
+        column.countLayer.foregroundColor = NSColor.secondaryLabelColor.cgColor
 
         let appGroupIndex = column.column.appGroupIndex
         let verticalOffset = clampedWaterfallColumnOffset(
@@ -3908,8 +4998,8 @@
         waterfallColumnScrollOffsets[appGroupIndex] = verticalOffset
 
         let cardWidth = max(1, bounds.width - WaterfallMetrics.columnHorizontalPadding * 2)
-        let firstCardTop = bounds.height
-            - WaterfallMetrics.headerHeight
+        let firstCardTop = cardsClipFrame.height
+            - WaterfallMetrics.selectedCardScaleOverflow
             - WaterfallMetrics.columnVerticalPadding
             + verticalOffset
 
@@ -3918,6 +5008,7 @@
             let y = firstCardTop
                 - WaterfallMetrics.cardHeight
                 - CGFloat(cardIndex) * (WaterfallMetrics.cardHeight + WaterfallMetrics.cardGap)
+            card.containerLayer.transform = CATransform3DIdentity
             card.containerLayer.frame = CGRect(
                 x: WaterfallMetrics.columnHorizontalPadding,
                 y: y,
@@ -3932,11 +5023,14 @@
         let bounds = card.containerLayer.bounds
         let isSelected = card.item.window.id == effectiveSelection?.windowID
         let isHovered = card.item.window.id == hoveredWindowID
-        let isAppLinked = isHorizontalMasonryMode
-            && card.item.appGroupIndex == appIconHoverLinkedAppGroupIndex
+        let isKeyboardFocused = card.item.window.id == keyboardFocusedWindowID
+        let isHorizontalAppDefaultFocused = isHorizontalAppDefaultCard(card)
+        let isAppLinked = isWaterfallCardAppLinked(card)
         applyWaterfallCardVisualState(
             card,
-            selected: shouldShowSelectedVisual(isSelected: isSelected, isHovered: isHovered),
+            selected: shouldShowSelectedVisual(isSelected: isSelected, isHovered: isHovered)
+                || isKeyboardFocused
+                || isHorizontalAppDefaultFocused,
             hovered: isHovered,
             appLinked: isAppLinked
         )
@@ -4042,7 +5136,7 @@
                     ? CGSize(width: 0, height: -5)
                     : .zero
         card.containerLayer.zPosition = selected ? 20 : hovered ? 12 : appLinked ? 10 : isSpaceFocused ? 8 : 0
-        let focusedScale: CGFloat = selected ? 1.015 : isSpaceFocused ? 1.012 : 1.008
+        let focusedScale: CGFloat = selected ? WaterfallMetrics.selectedCardScale : isSpaceFocused ? 1.012 : 1.008
         card.containerLayer.transform = (selected || hovered || isSpaceFocused)
             ? CATransform3DMakeScale(focusedScale, focusedScale, 1)
             : CATransform3DIdentity
@@ -4054,9 +5148,12 @@
                 transform: nil
             )
             : nil
-        card.titleBarLayer.backgroundColor = appLinked
-            ? spaceLaneOccupiedColor.withAlphaComponent(0.18).cgColor
-            : NSColor.clear.cgColor
+        card.titleBarLayer.backgroundColor = (selected
+            ? spaceLaneOccupiedColor.withAlphaComponent(0.22)
+            : appLinked
+                ? spaceLaneOccupiedColor.withAlphaComponent(0.18)
+                : NSColor.clear
+        ).cgColor
         card.titleBarLayer.borderColor = NSColor.clear.cgColor
         card.titleBarLayer.borderWidth = 0
         card.shineLayer.opacity = selected ? 1 : 0
@@ -4518,11 +5615,18 @@
                 x: locationInWaterfallContent.x - column.containerLayer.frame.minX,
                 y: locationInWaterfallContent.y - column.containerLayer.frame.minY
             )
-            for card in column.cards where card.containerLayer.frame.contains(locationInColumn) {
+            guard column.cardsClipLayer.frame.contains(locationInColumn) else {
+                continue
+            }
+            let locationInCardsClip = CGPoint(
+                x: locationInColumn.x - column.cardsClipLayer.frame.minX,
+                y: locationInColumn.y - column.cardsClipLayer.frame.minY
+            )
+            for card in column.cards where card.containerLayer.frame.contains(locationInCardsClip) {
                 guard card.closeButton.containerLayer.opacity > 0 else { continue }
                 let locationInCard = CGPoint(
-                    x: locationInColumn.x - card.containerLayer.frame.minX,
-                    y: locationInColumn.y - card.containerLayer.frame.minY
+                    x: locationInCardsClip.x - card.containerLayer.frame.minX,
+                    y: locationInCardsClip.y - card.containerLayer.frame.minY
                 )
                 if card.closeButton.containerLayer.frame.insetBy(dx: -8, dy: -8).contains(locationInCard) {
                     return .window(
@@ -4564,11 +5668,13 @@
                 x: waterfallLayer.frame.minX
                     + waterfallContentLayer.frame.minX
                     + column.containerLayer.frame.minX
+                    + column.cardsClipLayer.frame.minX
                     + card.containerLayer.frame.minX
                     + card.closeButton.containerLayer.frame.midX,
                 y: waterfallLayer.frame.minY
                     + waterfallContentLayer.frame.minY
                     + column.containerLayer.frame.minY
+                    + column.cardsClipLayer.frame.minY
                     + card.containerLayer.frame.minY
                     + card.closeButton.containerLayer.frame.midY
             )
@@ -4584,6 +5690,30 @@
     private func isWaterfallCardSpaceFocused(_ card: WaterfallCardLayers) -> Bool {
         guard let activeSpaceFocusID else { return false }
         return card.item.primarySpaceID == activeSpaceFocusID
+    }
+
+    private func isWaterfallCardAppLinked(_ card: WaterfallCardLayers) -> Bool {
+        guard card.item.appGroupIndex == appIconHoverLinkedAppGroupIndex else { return false }
+
+        if isHorizontalMasonryMode {
+            return true
+        }
+
+        if keyboardFocusedWindowID != nil {
+            return false
+        }
+
+        return waterfallColumns
+            .first(where: { $0.column.appGroupIndex == card.item.appGroupIndex })?
+            .cards
+            .sorted { lhs, rhs in
+                if lhs.item.windowIndex != rhs.item.windowIndex {
+                    return lhs.item.windowIndex < rhs.item.windowIndex
+                }
+                return lhs.item.window.id < rhs.item.window.id
+            }
+            .first?
+            .item.window.id == card.item.window.id
     }
 
     private func waterfallColumnWidth() -> CGFloat {
@@ -4676,7 +5806,7 @@
         )
         let contentHeight = CGFloat(column.cards.count) * WaterfallMetrics.cardHeight
             + CGFloat(max(0, column.cards.count - 1)) * WaterfallMetrics.cardGap
-        return max(0, contentHeight - visibleHeight)
+        return max(0, contentHeight - visibleHeight + WaterfallMetrics.selectedCardScaleOverflow * 2)
     }
 
     private func clampedWaterfallColumnOffset(_ offset: CGFloat, appGroupIndex: Int) -> CGFloat {
@@ -4684,7 +5814,26 @@
     }
 
     private func waterfallMetaText(for card: QuickSwitchWindowCardViewModel) -> String {
-        card.primarySpaceLabel ?? "No Space"
+        windowShortcutCode(for: card) ?? ""
+    }
+
+    private func windowShortcutCode(for card: QuickSwitchWindowCardViewModel) -> String? {
+        guard let appOrdinal = appShelfItems.firstIndex(where: { $0.item.appGroupIndex == card.appGroupIndex }),
+              let appSymbol = singleIndexSymbol(forOrdinal: appOrdinal),
+              let windowSymbol = singleIndexSymbol(forOrdinal: card.windowIndex)
+        else {
+            return nil
+        }
+        return "\(appSymbol)\(windowSymbol)"
+    }
+
+    private func singleIndexSymbol(forOrdinal ordinal: Int) -> String? {
+        guard ordinal >= 0,
+              ordinal < Self.appShelfIndexSymbols.count
+        else {
+            return nil
+        }
+        return Self.appShelfIndexSymbols[ordinal]
     }
 
     private func waterfallStateText(for card: QuickSwitchWindowCardViewModel) -> String {
@@ -5040,6 +6189,12 @@
                 "frame": dictionary(from: item.containerLayer.frame),
                 "visibleFrame": dictionary(from: visibleFrame),
                 "iconFrame": dictionary(from: item.iconLayer.frame),
+                "indexText": item.indexLayer.string ?? "",
+                "indexFrame": dictionary(from: item.indexLayer.frame),
+                "indexVisible": !item.indexLayer.isHidden && item.indexLayer.opacity > 0,
+                "indexFontSize": Double(item.indexLayer.fontSize),
+                "indexOpacity": Double(item.indexLayer.opacity),
+                "indexColor": colorDictionary(from: item.indexLayer.foregroundColor),
                 "labelFrame": dictionary(from: item.labelLayer.frame),
                 "labelTruncationMode": "middle",
                 "badgeVisible": !item.badgeLayer.isHidden,
@@ -5093,10 +6248,13 @@
             let appGroupIndex = column.column.appGroupIndex
             let isHovered = appGroupIndex == effectiveHoveredAppGroupIndex
             let firstCardFrame = column.cards.first?.containerLayer.frame
-            let headerToFirstCardGap = firstCardFrame.map {
+            let visibleFirstCardFrame = firstCardFrame.map {
+                $0.offsetBy(dx: column.cardsClipLayer.frame.minX, dy: column.cardsClipLayer.frame.minY)
+            }
+            let headerToFirstCardGap = visibleFirstCardFrame.map {
                 column.headerLayer.frame.minY - $0.maxY
             }
-            let topToFirstCardGap = firstCardFrame.map {
+            let topToFirstCardGap = visibleFirstCardFrame.map {
                 column.containerLayer.bounds.height - $0.maxY
             }
 
@@ -5114,6 +6272,8 @@
                 "visibleFrame": dictionary(from: visibleFrame),
                 "headerFrame": dictionary(from: column.headerLayer.frame),
                 "headerBackgroundColor": colorDictionary(from: column.headerLayer.backgroundColor),
+                "cardsClipFrame": dictionary(from: column.cardsClipLayer.frame),
+                "cardsClipMasksToBounds": column.cardsClipLayer.masksToBounds,
                 "headerToFirstCardGap": headerToFirstCardGap.map(Double.init) ?? NSNull(),
                 "topToFirstCardGap": topToFirstCardGap.map(Double.init) ?? NSNull(),
                 "appNameFrame": dictionary(from: column.appNameLayer.frame),
@@ -5178,8 +6338,8 @@
     private func waterfallCardReports(for column: WaterfallColumnLayers) -> [[String: Any]] {
         column.cards.map { card in
             let visibleFrame = card.containerLayer.frame.offsetBy(
-                dx: column.containerLayer.frame.minX + waterfallContentLayer.frame.minX,
-                dy: column.containerLayer.frame.minY
+                dx: column.containerLayer.frame.minX + column.cardsClipLayer.frame.minX + waterfallContentLayer.frame.minX,
+                dy: column.containerLayer.frame.minY + column.cardsClipLayer.frame.minY
             )
             let screenshotSource = screenshotSourcesByWindowID[card.item.window.id]
 
@@ -5193,10 +6353,13 @@
                 "titleIsEmpty": card.item.window.title.isEmpty,
                 "primarySpaceID": card.item.primarySpaceID ?? NSNull(),
                 "primarySpaceLabel": card.item.primarySpaceLabel ?? NSNull(),
+                "windowShortcutCode": waterfallMetaText(for: card.item),
                 "isMinimized": card.item.window.isMinimized,
                 "isFullscreen": card.item.window.isFullscreen,
                 "identifierSource": "\(card.item.window.identifierSource)",
                 "isSelected": card.item.window.id == effectiveSelection?.windowID,
+                "isKeyboardFocused": card.item.window.id == keyboardFocusedWindowID,
+                "isHorizontalAppDefault": isHorizontalAppDefaultCard(card),
                 "visualStates": waterfallCardVisualStates(for: card),
                 "thumbnailStrategy": thumbnailStrategyString(for: card.item.window),
                 "screenshotSource": screenshotSourceString(screenshotSource, for: card.item.window),
@@ -5221,6 +6384,7 @@
                 "closeButtonGlyphLineWidth": Double(card.closeButton.glyphLayer.lineWidth),
                 "shineVisible": card.shineLayer.opacity > 0,
                 "zPosition": Double(card.containerLayer.zPosition),
+                "bounds": dictionary(from: card.containerLayer.bounds),
                 "frame": dictionary(from: card.containerLayer.frame),
                 "visibleFrame": dictionary(from: visibleFrame),
                 "titleTruncationMode": "middle"
@@ -5315,13 +6479,22 @@
         var states: [String] = []
         let isSelected = card.item.window.id == effectiveSelection?.windowID
         let isHovered = card.item.window.id == hoveredWindowID
-        let isAppLinked = isHorizontalMasonryMode
-            && card.item.appGroupIndex == appIconHoverLinkedAppGroupIndex
-        if shouldShowSelectedVisual(isSelected: isSelected, isHovered: isHovered) {
+        let isKeyboardFocused = card.item.window.id == keyboardFocusedWindowID
+        let isHorizontalAppDefaultFocused = isHorizontalAppDefaultCard(card)
+        let isAppLinked = isWaterfallCardAppLinked(card)
+        if shouldShowSelectedVisual(isSelected: isSelected, isHovered: isHovered)
+            || isKeyboardFocused
+            || isHorizontalAppDefaultFocused {
             states.append("selected")
         } else if isSelected {
             states.append("selectedVisualSuppressed")
         }
+        if isKeyboardFocused {
+            states.append("keyboardFocused")
+        }
+        if isHorizontalAppDefaultFocused {
+            states.append("appDefault")
+        }
         if isHovered {
             states.append("hover")
         }

--
Gitblit v1.9.3