From b1368b6a51379714958af82cb1e3dc24183b0583 Mon Sep 17 00:00:00 2001
From: Ariver <shanghai3168@gmail.com>
Date: Fri, 19 Jun 2026 19:21:31 +0800
Subject: [PATCH] Add horizontal waterfall arrow focus

---
 C1.source/Sources/Aligner/QuickSwitchRootView.swift | 1214 ++++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 files changed, 1,111 insertions(+), 103 deletions(-)

diff --git a/C1.source/Sources/Aligner/QuickSwitchRootView.swift b/C1.source/Sources/Aligner/QuickSwitchRootView.swift
index 6675a87..552dca0 100644
--- a/C1.source/Sources/Aligner/QuickSwitchRootView.swift
+++ b/C1.source/Sources/Aligner/QuickSwitchRootView.swift
@@ -10,6 +10,8 @@
 
 @MainActor
 final class QuickSwitchRootView: NSView {
+    private static let appShelfIndexSymbols = Array("1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ").map(String.init)
+
     private let backdropBlurView = NSVisualEffectView()
     private let layerHostView = NSView()
     private let backgroundLayer = CAGradientLayer()
@@ -52,6 +54,7 @@
     private var closeFeedback: CloseFeedback?
     private var closeFeedbackHideTask: Task<Void, Never>?
     private var isViewModeToggleButtonHovered = false
+    private var suppressViewModeToggleHoverPreview = false
     private var hoverTarget: HoverTarget = .none
     private var hoverTargetSource: HoverTargetSource = .event
     private var hoveredSpaceLaneID: UInt64?
@@ -66,8 +69,15 @@
     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 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?
@@ -217,6 +227,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 {
@@ -240,6 +277,7 @@
         let item: QuickSwitchAppShelfItemViewModel
         let containerLayer: CALayer
         let backgroundLayer: CALayer
+        let indexLayer: CATextLayer
         let iconLayer: CALayer
         let labelLayer: CATextLayer
         let badgeLayer: CATextLayer
@@ -255,6 +293,7 @@
     private struct WaterfallColumnLayers {
         let column: QuickSwitchWaterfallColumnViewModel
         let containerLayer: CALayer
+        let cardsClipLayer: CALayer
         let headerLayer: CALayer
         let appNameLayer: CATextLayer
         let countLayer: CATextLayer
@@ -298,6 +337,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 {
@@ -306,6 +349,24 @@
         static let shelfGap: CGFloat = 16
         static let waterfallTopGap: CGFloat = 14
         static let bottomMargin: CGFloat = 34
+    }
+
+    private enum ViewModeToggleMetrics {
+        static let hitSize: CGFloat = 34
+        static let visualSize: CGFloat = 30
+        static let cornerRadius: CGFloat = 9
+        static let iconInset: CGFloat = 7
+        static let glyphLineWidth: CGFloat = 1.65
+        static let glyphCornerRadius: CGFloat = 2.1
+        static let selectedShadowRadius: CGFloat = 10
+        static let idleShadowRadius: CGFloat = 5
+    }
+
+    private enum ViewModeToggleVisualState: String {
+        case horizontalAvailable = "H1"
+        case horizontalSelected = "H2"
+        case verticalAvailable = "Z1"
+        case verticalSelected = "Z2"
     }
 
     private enum WaterfallMetrics {
@@ -322,6 +383,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 {
@@ -423,6 +486,9 @@
         case TriggerKeyCode.tab:
             performKeyboardCommand("tab")
         default:
+            if handleAppShelfIndexKey(event) {
+                return
+            }
             super.keyDown(with: event)
         }
     }
@@ -485,8 +551,12 @@
         guard debugHoveredAppGroupIndex == nil else { return }
 
         let toggleHovered = viewModeToggleButtonContains(windowLocation: event.locationInWindow)
-        if isViewModeToggleButtonHovered != toggleHovered {
-            isViewModeToggleButtonHovered = toggleHovered
+        if !toggleHovered {
+            suppressViewModeToggleHoverPreview = false
+        }
+        let shouldShowToggleHoverPreview = toggleHovered && !suppressViewModeToggleHoverPreview
+        if isViewModeToggleButtonHovered != shouldShowToggleHoverPreview {
+            isViewModeToggleButtonHovered = shouldShowToggleHoverPreview
             needsLayout = true
         }
         if toggleHovered {
@@ -506,6 +576,7 @@
     override func mouseExited(with event: NSEvent) {
         guard debugHoveredAppGroupIndex == nil else { return }
         isViewModeToggleButtonHovered = false
+        suppressViewModeToggleHoverPreview = false
         hoveredCloseTarget = nil
         setHoverTarget(.none)
     }
@@ -698,7 +769,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
     }
@@ -727,11 +799,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()
@@ -742,6 +841,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
@@ -757,8 +866,15 @@
             screenshotSkippedReasonsByWindowID = [:]
             currentSelection = viewModel?.initialSelection
             columnSelectionHistory = [:]
+            keyboardFocusedAppGroupIndex = nil
+            keyboardFocusedWindowID = nil
             keyboardCommandsApplied = []
             lastKeyboardCommand = nil
+            lastKeyboardAppIndexCommand = nil
+            lastBoundaryBounceAxis = nil
+            lastBoundaryBounceDirection = nil
+            boundaryBounceCount = 0
+            selectionChangedByLastCommand = nil
             tabIgnoredCount = 0
             lastCommittedSelection = nil
             lastCommitSource = nil
@@ -792,12 +908,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
+            }
         }
     }
 
@@ -1082,10 +1221,16 @@
             "spaceFilterActive": currentViewModel?.lockedSpaceID != nil,
             "viewModeToggleButtonVisible": !viewModeToggleButtonLayer.isHidden,
             "viewModeToggleButtonHovered": isViewModeToggleButtonHovered,
+            "viewModeToggleHoverPreviewSuppressed": suppressViewModeToggleHoverPreview,
             "viewModeToggleButtonFrame": dictionary(from: viewModeToggleButtonLayer.frame),
+            "viewModeToggleHitSize": Double(ViewModeToggleMetrics.hitSize),
+            "viewModeToggleVisualSize": Double(ViewModeToggleMetrics.visualSize),
             "viewModeToggleCurrentMode": waterfallViewMode.rawValue,
             "viewModeToggleTargetMode": nextWaterfallViewMode.rawValue,
             "viewModeToggleIconKind": viewModeToggleIconKind,
+            "viewModeToggleVisualState": viewModeToggleVisualState.rawValue,
+            "viewModeToggleStandardBlueColor": colorDictionary(from: viewModeToggleBlueColor.cgColor),
+            "viewModeToggleGlyphLineWidth": Double(ViewModeToggleMetrics.glyphLineWidth),
             "viewModeToggleAccessibilityLabel": viewModeToggleAccessibilityLabel,
             "settingsButtonVisible": false,
             "spaceFocusAppGroupIndexes": spaceFocusedAppGroupIndexes(),
@@ -1148,8 +1293,16 @@
             "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(),
+            "lastBoundaryBounceAxis": lastBoundaryBounceAxis ?? NSNull(),
+            "lastBoundaryBounceDirection": lastBoundaryBounceDirection ?? NSNull(),
+            "boundaryBounceCount": boundaryBounceCount,
+            "selectionChangedByLastCommand": selectionChangedByLastCommand ?? NSNull(),
             "tabIgnoredCount": tabIgnoredCount,
             "lastCommittedAppGroupIndex": lastCommittedSelection?.appGroupIndex ?? NSNull(),
             "lastCommittedWindowIndex": lastCommittedSelection?.windowIndex ?? NSNull(),
@@ -1222,38 +1375,342 @@
             .lowercased()
         guard !command.isEmpty else { return }
 
+        if let indexSymbol = appShelfIndexSymbol(fromKeyboardCommand: command) {
+            let recordedCommand = "app:\(indexSymbol)"
+            recordKeyboardCommand(recordedCommand)
+            if !focusAppShelfItemForKeyboard(indexSymbol: indexSymbol, commandLabel: recordedCommand) {
+                selectionChangedByLastCommand = false
+            }
+            return
+        }
+
         switch command {
         case "left":
             recordKeyboardCommand("left")
-            moveSelection(.left)
+            if isHorizontalMasonryMode {
+                moveSelection(.left)
+            } else if !moveKeyboardAppFocus(cycleForward: false) {
+                selectionChangedByLastCommand = false
+            }
         case "right":
             recordKeyboardCommand("right")
-            moveSelection(.right)
+            if isHorizontalMasonryMode {
+                moveSelection(.right)
+            } else if !moveKeyboardAppFocus(cycleForward: true) {
+                selectionChangedByLastCommand = false
+            }
         case "up":
             recordKeyboardCommand("up")
-            moveSelection(.up)
+            if isHorizontalMasonryMode {
+                moveSelection(.up)
+            } else {
+                moveVerticalSelectionWithinFocusedColumn(.up)
+            }
         case "down":
             recordKeyboardCommand("down")
-            moveSelection(.down)
+            if isHorizontalMasonryMode {
+                moveSelection(.down)
+            } else {
+                moveVerticalSelectionWithinFocusedColumn(.down)
+            }
         case "enter", "return", "commit":
             recordKeyboardCommand("enter")
+            selectionChangedByLastCommand = false
             commitCurrentSelection()
         case "tab":
             if isHorizontalMasonryMode {
                 recordKeyboardCommand("tab")
-                moveSelection(.right)
+                moveHorizontalMasonryTabSelection()
             } else {
                 tabIgnoredCount += 1
                 recordKeyboardCommand("tabIgnored")
+                selectionChangedByLastCommand = false
             }
         default:
             recordKeyboardCommand("unknown:\(command)")
+            selectionChangedByLastCommand = false
         }
     }
 
     private func recordKeyboardCommand(_ command: String) {
         lastKeyboardCommand = command
         keyboardCommandsApplied.append(command)
+    }
+
+    private func handleAppShelfIndexKey(_ event: NSEvent) -> Bool {
+        guard !isHorizontalMasonryMode else { return false }
+        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
+        }
+
+        performKeyboardCommand(symbol)
+        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
+        )
+    }
+
+    @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) {
@@ -1330,6 +1787,12 @@
         case "click-background":
             recordMouseCommand("click-background")
             _ = onBackgroundClick?()
+        case "hover-view-toggle":
+            recordMouseCommand("hover-view-toggle")
+            suppressViewModeToggleHoverPreview = false
+            isViewModeToggleButtonHovered = true
+            hoveredCloseTarget = nil
+            setHoverTarget(.none, source: .debug)
         case "click-view-toggle", "click-settings":
             recordMouseCommand("click-view-toggle")
             clickViewModeToggleButton(source: "debug")
@@ -1400,13 +1863,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
         )
     }
 
@@ -1654,6 +2117,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)
         }
@@ -1687,8 +2155,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),
@@ -1700,26 +2171,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
     }
 
@@ -2301,7 +3106,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
 
@@ -2317,6 +3122,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,
@@ -2342,6 +3159,7 @@
             let closeButton = makeCloseButtonLayers()
 
             container.addSublayer(background)
+            container.addSublayer(indexLabel)
             container.addSublayer(icon)
             container.addSublayer(label)
             container.addSublayer(badge)
@@ -2352,6 +3170,7 @@
                 item: item,
                 containerLayer: container,
                 backgroundLayer: background,
+                indexLayer: indexLabel,
                 iconLayer: icon,
                 labelLayer: label,
                 badgeLayer: badge,
@@ -2376,8 +3195,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,
@@ -2394,6 +3218,10 @@
                 alignment: .right
             )
 
+            appName.zPosition = 42
+            count.zPosition = 42
+
+            container.addSublayer(cardsClip)
             container.addSublayer(header)
             container.addSublayer(appName)
             container.addSublayer(count)
@@ -2460,7 +3288,7 @@
                 card.addSublayer(state)
                 card.addSublayer(shine)
                 card.addSublayer(closeButton.containerLayer)
-                container.addSublayer(card)
+                cardsClip.addSublayer(card)
 
                 return WaterfallCardLayers(
                     item: window,
@@ -2481,6 +3309,7 @@
             return WaterfallColumnLayers(
                 column: column,
                 containerLayer: container,
+                cardsClipLayer: cardsClip,
                 headerLayer: header,
                 appNameLayer: appName,
                 countLayer: count,
@@ -2650,7 +3479,7 @@
     }
 
     private func layoutViewModeToggleButton() {
-        let size: CGFloat = 34
+        let size = ViewModeToggleMetrics.visualSize
         let topMargin = topSafeAreaInset + RootLayoutMetrics.topContentMargin
         let x = max(
             RootLayoutMetrics.horizontalMargin,
@@ -2661,16 +3490,23 @@
             glassLayer.bounds.height - topMargin - size
         )
         viewModeToggleButtonLayer.frame = CGRect(x: x, y: y, width: size, height: size)
-        viewModeToggleButtonLayer.backgroundColor = NSColor.windowBackgroundColor
-            .withAlphaComponent(isViewModeToggleButtonHovered ? 0.78 : 0.54)
-            .cgColor
-        viewModeToggleButtonLayer.borderColor = NSColor.separatorColor
-            .withAlphaComponent(isViewModeToggleButtonHovered ? 0.42 : 0.26)
-            .cgColor
-        viewModeToggleButtonLayer.shadowOpacity = isViewModeToggleButtonHovered ? 0.14 : 0.08
-        viewModeToggleButtonLayer.shadowRadius = isViewModeToggleButtonHovered ? 9 : 6
+        viewModeToggleButtonLayer.cornerRadius = ViewModeToggleMetrics.cornerRadius
+        let visualState = viewModeToggleVisualState
+        let isSelectedState = viewModeToggleVisualStateIsSelected(visualState)
+        viewModeToggleButtonLayer.backgroundColor = (isSelectedState
+            ? viewModeToggleBlueColor
+            : NSColor.windowBackgroundColor.withAlphaComponent(isViewModeToggleButtonHovered ? 0.76 : 0.58)
+        ).cgColor
+        viewModeToggleButtonLayer.borderColor = (isSelectedState
+            ? viewModeToggleBlueColor.withAlphaComponent(0.96)
+            : viewModeToggleBlueColor.withAlphaComponent(isViewModeToggleButtonHovered ? 0.72 : 0.34)
+        ).cgColor
+        viewModeToggleButtonLayer.shadowOpacity = isSelectedState ? 0.16 : (isViewModeToggleButtonHovered ? 0.11 : 0.06)
+        viewModeToggleButtonLayer.shadowRadius = isSelectedState
+            ? ViewModeToggleMetrics.selectedShadowRadius
+            : ViewModeToggleMetrics.idleShadowRadius
         viewModeToggleIconLayer.contentsScale = backingScaleFactor
-        let iconInset: CGFloat = 7
+        let iconInset = ViewModeToggleMetrics.iconInset
         viewModeToggleIconLayer.frame = viewModeToggleButtonLayer.bounds.insetBy(dx: iconInset, dy: iconInset)
         layoutViewModeToggleIcon()
     }
@@ -2686,39 +3522,28 @@
             return
         }
 
-        let activeStroke = (isViewModeToggleButtonHovered
-            ? NSColor.controlAccentColor
-            : NSColor.secondaryLabelColor
-        ).withAlphaComponent(isViewModeToggleButtonHovered ? 0.88 : 0.82)
-        let quietStroke = (isViewModeToggleButtonHovered
-            ? NSColor.controlAccentColor
-            : NSColor.secondaryLabelColor
-        ).withAlphaComponent(isViewModeToggleButtonHovered ? 0.34 : 0.24)
-        let subtleFill = (isViewModeToggleButtonHovered
-            ? NSColor.controlAccentColor
-            : NSColor.labelColor
-        ).withAlphaComponent(isViewModeToggleButtonHovered ? 0.06 : 0.025)
+        let visualState = viewModeToggleVisualState
+        let isSelectedState = viewModeToggleVisualStateIsSelected(visualState)
+        let strokeColor = isSelectedState
+            ? NSColor.white.withAlphaComponent(0.98)
+            : viewModeToggleBlueColor.withAlphaComponent(0.96)
+        let fillColor = isSelectedState
+            ? NSColor.white.withAlphaComponent(0.22)
+            : viewModeToggleBlueColor.withAlphaComponent(0.06)
+        let glyphRect = centeredSquare(in: bounds)
 
-        addViewModeToggleRoundedRect(
-            bounds.insetBy(dx: 0.65, dy: 0.65),
-            cornerRadius: 4.8,
-            strokeColor: quietStroke,
-            fillColor: NSColor.clear,
-            lineWidth: 1.05
-        )
-
-        switch nextWaterfallViewMode {
-        case .verticalColumns:
+        switch visualState {
+        case .verticalAvailable, .verticalSelected:
             addVerticalColumnsToggleGlyph(
-                in: bounds.insetBy(dx: 4.15, dy: 3.25),
-                strokeColor: activeStroke,
-                fillColor: subtleFill
+                in: glyphRect,
+                strokeColor: strokeColor,
+                fillColor: fillColor
             )
-        case .horizontalMasonry:
+        case .horizontalAvailable, .horizontalSelected:
             addHorizontalMasonryToggleGlyph(
-                in: bounds.insetBy(dx: 3.95, dy: 3.95),
-                strokeColor: activeStroke,
-                fillColor: subtleFill
+                in: glyphRect,
+                strokeColor: strokeColor,
+                fillColor: fillColor
             )
         }
 
@@ -2730,17 +3555,17 @@
         strokeColor: NSColor,
         fillColor: NSColor
     ) {
-        let columnWidth: CGFloat = 3.35
-        let gap = max(1.7, (rect.width - columnWidth * 3) / 2)
+        let columnWidth = rect.width * 0.22
+        let gap = (rect.width - columnWidth * 3) / 2
         for index in 0..<3 {
             let x = rect.minX + CGFloat(index) * (columnWidth + gap)
             let columnRect = CGRect(x: x, y: rect.minY, width: columnWidth, height: rect.height)
             addViewModeToggleRoundedRect(
                 columnRect,
-                cornerRadius: 1.6,
+                cornerRadius: ViewModeToggleMetrics.glyphCornerRadius,
                 strokeColor: strokeColor,
                 fillColor: fillColor,
-                lineWidth: 1.22
+                lineWidth: ViewModeToggleMetrics.glyphLineWidth
             )
         }
     }
@@ -2750,23 +3575,22 @@
         strokeColor: NSColor,
         fillColor: NSColor
     ) {
-        let cellSize: CGFloat = 3.65
-        let gapX = max(1.65, (rect.width - cellSize * 3) / 2)
-        let gapY = max(1.65, (rect.height - cellSize * 3) / 2)
-        for row in 0..<3 {
-            for column in 0..<3 {
+        let cellSize = rect.width * 0.38
+        let gap = rect.width - cellSize * 2
+        for row in 0..<2 {
+            for column in 0..<2 {
                 let cellRect = CGRect(
-                    x: rect.minX + CGFloat(column) * (cellSize + gapX),
-                    y: rect.minY + CGFloat(row) * (cellSize + gapY),
+                    x: rect.minX + CGFloat(column) * (cellSize + gap),
+                    y: rect.minY + CGFloat(row) * (cellSize + gap),
                     width: cellSize,
                     height: cellSize
                 )
                 addViewModeToggleRoundedRect(
                     cellRect,
-                    cornerRadius: 1.15,
+                    cornerRadius: ViewModeToggleMetrics.glyphCornerRadius,
                     strokeColor: strokeColor,
                     fillColor: fillColor,
-                    lineWidth: 1.18
+                    lineWidth: ViewModeToggleMetrics.glyphLineWidth
                 )
             }
         }
@@ -2793,6 +3617,16 @@
         layer.lineWidth = lineWidth
         layer.lineJoin = .round
         viewModeToggleIconLayer.addSublayer(layer)
+    }
+
+    private func centeredSquare(in rect: CGRect) -> CGRect {
+        let side = min(rect.width, rect.height)
+        return CGRect(
+            x: rect.midX - side / 2,
+            y: rect.midY - side / 2,
+            width: side,
+            height: side
+        )
     }
 
     private var topSafeAreaInset: CGFloat {
@@ -3150,7 +3984,10 @@
             x: locationInView.x - glassLayer.frame.minX,
             y: locationInView.y - glassLayer.frame.minY
         )
-        return viewModeToggleButtonLayer.frame.contains(locationInGlass)
+        let hitOutset = (ViewModeToggleMetrics.hitSize - ViewModeToggleMetrics.visualSize) / 2
+        return viewModeToggleButtonLayer.frame
+            .insetBy(dx: -hitOutset, dy: -hitOutset)
+            .contains(locationInGlass)
     }
 
     private func clickViewModeToggleButton(source: String) {
@@ -3163,6 +4000,8 @@
         if !mouseCommandsApplied.contains("click-view-toggle") {
             mouseCommandsApplied.append("click-view-toggle")
         }
+        isViewModeToggleButtonHovered = false
+        suppressViewModeToggleHoverPreview = true
         onToggleWaterfallViewMode?()
     }
 
@@ -3190,7 +4029,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
             }
         }
@@ -3375,6 +4221,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
@@ -3400,6 +4253,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]] {
@@ -3602,6 +4515,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)
     }
@@ -3682,11 +4599,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 {
@@ -3820,6 +4740,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
@@ -3833,9 +4761,11 @@
             width: bounds.width,
             height: WaterfallMetrics.headerHeight
         )
-        column.headerLayer.backgroundColor = (isSpaceFocused
-            ? NSColor.systemFill.withAlphaComponent(0.10)
-            : NSColor.controlBackgroundColor.withAlphaComponent(0.52)
+        column.headerLayer.backgroundColor = (isHovered
+            ? waterfallAppHoverHeaderFillColor
+            : (isSpaceFocused
+                ? NSColor.systemFill.withAlphaComponent(0.10)
+                : NSColor.controlBackgroundColor.withAlphaComponent(0.52))
         ).cgColor
         column.appNameLayer.frame = CGRect(
             x: WaterfallMetrics.columnHeaderTextInset,
@@ -3843,16 +4773,14 @@
             width: max(1, bounds.width - WaterfallMetrics.columnHeaderTextInset * 2),
             height: 16
         )
-        column.appNameLayer.foregroundColor = (isHovered
-            ? spaceLaneOccupiedColor
-            : 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 = NSColor.secondaryLabelColor.cgColor
 
         let appGroupIndex = column.column.appGroupIndex
         let verticalOffset = clampedWaterfallColumnOffset(
@@ -3862,8 +4790,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
 
@@ -3872,6 +4800,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,
@@ -3886,11 +4815,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
         )
@@ -3996,7 +4928,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
@@ -4008,9 +4940,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
@@ -4472,11 +5407,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(
@@ -4518,11 +5460,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
             )
@@ -4538,6 +5482,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 {
@@ -4563,13 +5531,28 @@
         isHorizontalMasonryMode ? .verticalColumns : .horizontalMasonry
     }
 
-    private var viewModeToggleIconKind: String {
-        switch nextWaterfallViewMode {
-        case .verticalColumns:
-            return "verticalColumnsTarget"
-        case .horizontalMasonry:
-            return "horizontalMasonryTarget"
+    private var viewModeToggleBlueColor: NSColor {
+        NSColor(deviceRed: 135.0 / 255.0, green: 200.0 / 255.0, blue: 1, alpha: 1)
+    }
+
+    private var viewModeToggleVisualState: ViewModeToggleVisualState {
+        if isHorizontalMasonryMode {
+            return isViewModeToggleButtonHovered ? .verticalAvailable : .horizontalSelected
         }
+        return isViewModeToggleButtonHovered ? .horizontalAvailable : .verticalSelected
+    }
+
+    private func viewModeToggleVisualStateIsSelected(_ state: ViewModeToggleVisualState) -> Bool {
+        switch state {
+        case .horizontalSelected, .verticalSelected:
+            return true
+        case .horizontalAvailable, .verticalAvailable:
+            return false
+        }
+    }
+
+    private var viewModeToggleIconKind: String {
+        viewModeToggleVisualState.rawValue
     }
 
     private var viewModeToggleAccessibilityLabel: String {
@@ -4615,7 +5598,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 {
@@ -4979,6 +5962,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,
@@ -5032,10 +6021,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
             }
 
@@ -5052,12 +6044,16 @@
                 "frame": dictionary(from: column.containerLayer.frame),
                 "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),
                 "appNameAlignment": column.appNameLayer.alignmentMode.rawValue,
                 "appNameColor": colorDictionary(from: column.appNameLayer.foregroundColor),
                 "countFrame": dictionary(from: column.countLayer.frame),
+                "countColor": colorDictionary(from: column.countLayer.foregroundColor),
                 "verticalScrollOffset": Double(waterfallColumnScrollOffsets[appGroupIndex] ?? 0),
                 "maxVerticalScrollOffset": Double(waterfallMaxVerticalScrollOffset(for: appGroupIndex)),
                 "cards": waterfallCardReports(for: column)
@@ -5115,8 +6111,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]
 
@@ -5134,6 +6130,8 @@
                 "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),
@@ -5158,6 +6156,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"
@@ -5252,13 +6251,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