Add vertical App Shelf keyboard focus

Ariver

2026-06-18 b6e11990cc9bd3c838ad6cdd9e53caafff0fd7cb

 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,14 @@
    private var horizontalMasonryScrollOffset: CGFloat = 0
    private var currentSelection: QuickSwitchSelection?
    private var columnSelectionHistory: [Int: Int] = [:]
    private var keyboardFocusedAppGroupIndex: Int?
    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 +226,7 @@
    private enum HoverTargetSource: String {
        case event
        case debug
        case keyboard
    }

    private struct SpaceLaneSegmentLayers {
@@ -240,6 +250,7 @@
        let item: QuickSwitchAppShelfItemViewModel
        let containerLayer: CALayer
        let backgroundLayer: CALayer
        let indexLayer: CATextLayer
        let iconLayer: CALayer
        let labelLayer: CATextLayer
        let badgeLayer: CATextLayer
@@ -298,6 +309,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 +321,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 {
@@ -423,6 +456,9 @@
        case TriggerKeyCode.tab:
            performKeyboardCommand("tab")
        default:
            if handleAppShelfIndexKey(event) {
                return
            }
            super.keyDown(with: event)
        }
    }
@@ -485,8 +521,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 +546,7 @@
    override func mouseExited(with event: NSEvent) {
        guard debugHoveredAppGroupIndex == nil else { return }
        isViewModeToggleButtonHovered = false
        suppressViewModeToggleHoverPreview = false
        hoveredCloseTarget = nil
        setHoverTarget(.none)
    }
@@ -727,11 +768,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 +810,10 @@
            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 currentSelection {
                columnSelectionHistory[currentSelection.appGroupIndex] = currentSelection.windowIndex
@@ -757,8 +829,14 @@
            screenshotSkippedReasonsByWindowID = [:]
            currentSelection = viewModel?.initialSelection
            columnSelectionHistory = [:]
            keyboardFocusedAppGroupIndex = nil
            keyboardCommandsApplied = []
            lastKeyboardCommand = nil
            lastKeyboardAppIndexCommand = nil
            lastBoundaryBounceAxis = nil
            lastBoundaryBounceDirection = nil
            boundaryBounceCount = 0
            selectionChangedByLastCommand = nil
            tabIgnoredCount = 0
            lastCommittedSelection = nil
            lastCommitSource = nil
@@ -792,12 +870,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 +1183,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 +1255,14 @@
            "selectedAppGroupIndex": effectiveSelection?.appGroupIndex ?? NSNull(),
            "selectedWindowIndex": effectiveSelection?.windowIndex ?? NSNull(),
            "selectedWindowID": effectiveSelection?.windowID ?? NSNull(),
            "keyboardFocusedAppGroupIndex": keyboardFocusedAppGroupIndex ?? 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,21 +1335,47 @@
            .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 {
@@ -1245,15 +1384,241 @@
            } 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
        lastKeyboardAppIndexCommand = appIndexCommand
        selectionChangedByLastCommand = false
        clearKeyboardBoundaryFeedback()
        ensureAppShelfItemVisible(appGroupIndex)
        layoutSubtreeIfNeeded()
        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 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
        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 +1695,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 +1771,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
        )
    }

@@ -1687,8 +2058,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),
@@ -1711,8 +2085,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.moveHorizontalMasonrySelection", [
            "direction": String(describing: direction),
@@ -2301,7 +2678,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 +2694,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 +2731,7 @@
            let closeButton = makeCloseButtonLayers()

            container.addSublayer(background)
            container.addSublayer(indexLabel)
            container.addSublayer(icon)
            container.addSublayer(label)
            container.addSublayer(badge)
@@ -2352,6 +2742,7 @@
                item: item,
                containerLayer: container,
                backgroundLayer: background,
                indexLayer: indexLabel,
                iconLayer: icon,
                labelLayer: label,
                badgeLayer: badge,
@@ -2650,7 +3041,7 @@
    }

    private func layoutViewModeToggleButton() {
        let size: CGFloat = 34
        let size = ViewModeToggleMetrics.visualSize
        let topMargin = topSafeAreaInset + RootLayoutMetrics.topContentMargin
        let x = max(
            RootLayoutMetrics.horizontalMargin,
@@ -2661,16 +3052,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 +3084,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 +3117,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 +3137,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 +3179,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 +3546,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 +3562,8 @@
        if !mouseCommandsApplied.contains("click-view-toggle") {
            mouseCommandsApplied.append("click-view-toggle")
        }
        isViewModeToggleButtonHovered = false
        suppressViewModeToggleHoverPreview = true
        onToggleWaterfallViewMode?()
    }

@@ -3375,6 +3776,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 +3808,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 +4070,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)
    }
@@ -3687,6 +4159,7 @@
            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 {
@@ -3833,9 +4306,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 +4318,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(
@@ -3872,6 +4345,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,8 +4360,7 @@
        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 isAppLinked = isWaterfallCardAppLinked(card)
        applyWaterfallCardVisualState(
            card,
            selected: shouldShowSelectedVisual(isSelected: isSelected, isHovered: isHovered),
@@ -4540,6 +5013,26 @@
        return card.item.primarySpaceID == activeSpaceFocusID
    }

    private func isWaterfallCardAppLinked(_ card: WaterfallCardLayers) -> Bool {
        guard card.item.appGroupIndex == appIconHoverLinkedAppGroupIndex else { return false }

        if isHorizontalMasonryMode {
            return true
        }

        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 {
        guard waterfallColumns.count > 0 else { return WaterfallMetrics.columnWidth }

@@ -4563,13 +5056,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 {
@@ -4979,6 +5487,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,
@@ -5052,12 +5566,14 @@
                "frame": dictionary(from: column.containerLayer.frame),
                "visibleFrame": dictionary(from: visibleFrame),
                "headerFrame": dictionary(from: column.headerLayer.frame),
                "headerBackgroundColor": colorDictionary(from: column.headerLayer.backgroundColor),
                "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)
@@ -5252,8 +5768,7 @@
        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
        let isAppLinked = isWaterfallCardAppLinked(card)
        if shouldShowSelectedVisual(isSelected: isSelected, isHovered: isHovered) {
            states.append("selected")
        } else if isSelected {