From 0a64c8163445e27f5123fdcf083fb3a5449b5c49 Mon Sep 17 00:00:00 2001
From: Ariver <shanghai3168@gmail.com>
Date: Sat, 20 Jun 2026 03:43:08 +0800
Subject: [PATCH] Fix dark Space hover readability

---
 C1.source/Sources/Aligner/QuickSwitchRootView.swift | 1341 ++++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 files changed, 1,261 insertions(+), 80 deletions(-)

diff --git a/C1.source/Sources/Aligner/QuickSwitchRootView.swift b/C1.source/Sources/Aligner/QuickSwitchRootView.swift
index f7cbfa2..81e6310 100644
--- a/C1.source/Sources/Aligner/QuickSwitchRootView.swift
+++ b/C1.source/Sources/Aligner/QuickSwitchRootView.swift
@@ -11,10 +11,24 @@
 @MainActor
 final class QuickSwitchRootView: NSView {
     private static let appShelfIndexSymbols = Array("1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ").map(String.init)
+    private static let windowIndexKeyPendingInterval: CFTimeInterval = 0.8
+    private static let appShelfIndexKeyCodes: [String: UInt16] = [
+        "1": 18, "2": 19, "3": 20, "4": 21, "5": 23,
+        "6": 22, "7": 26, "8": 28, "9": 25, "0": 29,
+        "A": 0, "B": 11, "C": 8, "D": 2, "E": 14, "F": 3,
+        "G": 5, "H": 4, "I": 34, "J": 38, "K": 40, "L": 37,
+        "M": 46, "N": 45, "O": 31, "P": 35, "Q": 12, "R": 15,
+        "S": 1, "T": 17, "U": 32, "V": 9, "W": 13, "X": 7,
+        "Y": 16, "Z": 6
+    ]
 
     private let backdropBlurView = NSVisualEffectView()
     private let layerHostView = NSView()
     private let backgroundLayer = CAGradientLayer()
+    private let darkAmbientLeftLayer = CAGradientLayer()
+    private let darkAmbientCenterLayer = CAGradientLayer()
+    private let darkAmbientRightLayer = CAGradientLayer()
+    private let darkVignetteLayer = CAGradientLayer()
     private let safeAreaFillLayer = CALayer()
     private let glassLayer = CALayer()
     private let laneLayer = CALayer()
@@ -28,6 +42,8 @@
     private let closeFeedbackTextLayer = CATextLayer()
     private let viewModeToggleButtonLayer = CALayer()
     private let viewModeToggleIconLayer = CALayer()
+    private let themeToggleButtonLayer = CALayer()
+    private let themeToggleIconLayer = CALayer()
     private let appIconProvider: any AppIconProviderProtocol = WorkspaceAppIconProvider()
     private let skeletonThumbnailProvider = NativeSkeletonThumbnailProvider(size: NSSize(width: 160, height: 96))
     private var screenshotSourcesByWindowID: [UInt32: ScreenshotResolutionSource] = [:]
@@ -55,6 +71,8 @@
     private var closeFeedbackHideTask: Task<Void, Never>?
     private var isViewModeToggleButtonHovered = false
     private var suppressViewModeToggleHoverPreview = false
+    private var isThemeToggleButtonHovered = false
+    private var suppressThemeToggleHoverPreview = false
     private var hoverTarget: HoverTarget = .none
     private var hoverTargetSource: HoverTargetSource = .event
     private var hoveredSpaceLaneID: UInt64?
@@ -62,6 +80,7 @@
     private var debugHoveredAppGroupIndex: Int?
     private var waterfallColumns: [WaterfallColumnLayers] = []
     private var waterfallViewMode: QuickSwitchWaterfallViewMode = .verticalColumns
+    private var themePreference: ThemePreference = .light
     private var waterfallContentWidth: CGFloat = 0
     private var waterfallScrollOffset: CGFloat = 0
     private var waterfallColumnScrollOffsets: [Int: CGFloat] = [:]
@@ -74,6 +93,12 @@
     private var keyboardCommandsApplied: [String] = []
     private var lastKeyboardCommand: String?
     private var lastKeyboardAppIndexCommand: String?
+    private var appShelfIndexKeyDownCount = 0
+    private var lastAppShelfIndexKeySymbol: String?
+    private var windowIndexKeyPending: WindowIndexKeyPending?
+    private var windowIndexKeyPendingClearTask: Task<Void, Never>?
+    private var lastWindowIndexKeyCommand: String?
+    private var lastWindowIndexKeyCommitCode: String?
     private var lastBoundaryBounceAxis: String?
     private var lastBoundaryBounceDirection: String?
     private var boundaryBounceCount = 0
@@ -105,6 +130,7 @@
     var onSpaceLaneClick: ((UInt64, Int) -> Void)?
     var onBackgroundClick: (() -> Bool)?
     var onToggleWaterfallViewMode: (() -> Void)?
+    var onToggleTheme: (() -> Void)?
     var onRequestClose: ((QuickSwitchCloseRequest) -> Void)?
     var onCloseConfirmationDisabled: (() -> Void)?
 
@@ -230,6 +256,32 @@
         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 {
         let space: QuickSwitchSpaceViewModel
         let containerLayer: CALayer
@@ -287,6 +339,12 @@
         let closeButton: CloseButtonLayers
     }
 
+    private struct WindowIndexKeyPending {
+        let appSymbol: String
+        let appGroupIndex: Int
+        let startedAt: CFTimeInterval
+    }
+
     private struct ProjectionLayerSnapshot {
         let layer: CALayer
         let frame: CGRect
@@ -341,6 +399,118 @@
         case horizontalSelected = "H2"
         case verticalAvailable = "Z1"
         case verticalSelected = "Z2"
+    }
+
+    private enum ThemeToggleMetrics {
+        static let buttonGap: CGFloat = 10
+    }
+
+    private enum QuickSwitchResolvedTheme: String {
+        case light
+        case dark
+    }
+
+    private struct QuickSwitchThemePalette {
+        let resolvedTheme: QuickSwitchResolvedTheme
+        let backgroundGradientColors: [NSColor]
+        let safeAreaFill: NSColor
+        let displayGroupBackground: NSColor
+        let spaceLanePrimaryText: NSColor
+        let spaceLaneSecondaryText: NSColor
+        let columnBackground: NSColor
+        let columnBorder: NSColor
+        let columnHeaderBackground: NSColor
+        let columnHeaderHoverBackground: NSColor
+        let columnHeaderSpaceFocusedBackground: NSColor
+        let columnText: NSColor
+        let columnSecondaryText: NSColor
+        let cardBackground: NSColor
+        let cardSelectedBackground: NSColor
+        let cardText: NSColor
+        let cardSecondaryText: NSColor
+        let appShelfLabelText: NSColor
+        let appShelfIndexText: NSColor
+        let appShelfIndexHighlightedText: NSColor
+        let appShelfBackgroundSelected: NSColor
+        let appShelfBackgroundHovered: NSColor
+        let appShelfBackgroundSpaceFocused: NSColor
+        let closeFeedbackBackground: NSColor
+        let closeFeedbackBorder: NSColor
+        let closeFeedbackText: NSColor
+        let shinePeak: NSColor
+
+        static func palette(for theme: QuickSwitchResolvedTheme) -> QuickSwitchThemePalette {
+            switch theme {
+            case .light:
+                return QuickSwitchThemePalette(
+                    resolvedTheme: .light,
+                    backgroundGradientColors: [
+                        NSColor.windowBackgroundColor.withAlphaComponent(0.58),
+                        NSColor.controlBackgroundColor.withAlphaComponent(0.48)
+                    ],
+                    safeAreaFill: .black,
+                    displayGroupBackground: NSColor.windowBackgroundColor,
+                    spaceLanePrimaryText: .labelColor,
+                    spaceLaneSecondaryText: .secondaryLabelColor,
+                    columnBackground: NSColor.controlBackgroundColor.withAlphaComponent(0.56),
+                    columnBorder: NSColor.separatorColor.withAlphaComponent(0.24),
+                    columnHeaderBackground: NSColor.controlBackgroundColor.withAlphaComponent(0.52),
+                    columnHeaderHoverBackground: NSColor.systemGray.withAlphaComponent(0.22),
+                    columnHeaderSpaceFocusedBackground: NSColor.systemFill.withAlphaComponent(0.10),
+                    columnText: .labelColor,
+                    columnSecondaryText: .secondaryLabelColor,
+                    cardBackground: NSColor.windowBackgroundColor.withAlphaComponent(0.82),
+                    cardSelectedBackground: NSColor.windowBackgroundColor.withAlphaComponent(0.94),
+                    cardText: .labelColor,
+                    cardSecondaryText: .secondaryLabelColor,
+                    appShelfLabelText: .secondaryLabelColor,
+                    appShelfIndexText: NSColor.labelColor.withAlphaComponent(0.48),
+                    appShelfIndexHighlightedText: NSColor.labelColor.withAlphaComponent(0.58),
+                    appShelfBackgroundSelected: NSColor.controlAccentColor.withAlphaComponent(0.14),
+                    appShelfBackgroundHovered: NSColor.controlAccentColor.withAlphaComponent(0.13),
+                    appShelfBackgroundSpaceFocused: NSColor.controlAccentColor.withAlphaComponent(0.14),
+                    closeFeedbackBackground: NSColor.windowBackgroundColor.withAlphaComponent(0.94),
+                    closeFeedbackBorder: NSColor.separatorColor.withAlphaComponent(0.28),
+                    closeFeedbackText: NSColor.secondaryLabelColor.withAlphaComponent(0.96),
+                    shinePeak: NSColor.white.withAlphaComponent(0.16)
+                )
+            case .dark:
+                return QuickSwitchThemePalette(
+                    resolvedTheme: .dark,
+                    backgroundGradientColors: [
+                        NSColor(calibratedRed: 5 / 255, green: 8 / 255, blue: 20 / 255, alpha: 1),
+                        NSColor(calibratedRed: 15 / 255, green: 24 / 255, blue: 54 / 255, alpha: 1),
+                        NSColor(calibratedRed: 3 / 255, green: 42 / 255, blue: 52 / 255, alpha: 1),
+                        NSColor(calibratedRed: 2 / 255, green: 6 / 255, blue: 13 / 255, alpha: 1)
+                    ],
+                    safeAreaFill: .black,
+                    displayGroupBackground: NSColor(calibratedRed: 14 / 255, green: 24 / 255, blue: 39 / 255, alpha: 0.72),
+                    spaceLanePrimaryText: NSColor.white.withAlphaComponent(0.88),
+                    spaceLaneSecondaryText: NSColor.white.withAlphaComponent(0.56),
+                    columnBackground: NSColor(calibratedRed: 92 / 255, green: 97 / 255, blue: 111 / 255, alpha: 0.72),
+                    columnBorder: NSColor.white.withAlphaComponent(0.20),
+                    columnHeaderBackground: NSColor(calibratedRed: 104 / 255, green: 111 / 255, blue: 126 / 255, alpha: 0.70),
+                    columnHeaderHoverBackground: NSColor(calibratedRed: 185 / 255, green: 190 / 255, blue: 205 / 255, alpha: 0.32),
+                    columnHeaderSpaceFocusedBackground: NSColor(calibratedRed: 92 / 255, green: 171 / 255, blue: 255 / 255, alpha: 0.16),
+                    columnText: NSColor.black.withAlphaComponent(0.82),
+                    columnSecondaryText: NSColor.black.withAlphaComponent(0.46),
+                    cardBackground: NSColor.white.withAlphaComponent(0.90),
+                    cardSelectedBackground: NSColor.white.withAlphaComponent(0.96),
+                    cardText: NSColor.black.withAlphaComponent(0.86),
+                    cardSecondaryText: NSColor.black.withAlphaComponent(0.52),
+                    appShelfLabelText: NSColor.white.withAlphaComponent(0.66),
+                    appShelfIndexText: NSColor.white.withAlphaComponent(0.40),
+                    appShelfIndexHighlightedText: NSColor.white.withAlphaComponent(0.58),
+                    appShelfBackgroundSelected: NSColor(calibratedRed: 92 / 255, green: 171 / 255, blue: 255 / 255, alpha: 0.22),
+                    appShelfBackgroundHovered: NSColor(calibratedRed: 92 / 255, green: 171 / 255, blue: 255 / 255, alpha: 0.18),
+                    appShelfBackgroundSpaceFocused: NSColor(calibratedRed: 92 / 255, green: 171 / 255, blue: 255 / 255, alpha: 0.20),
+                    closeFeedbackBackground: NSColor(calibratedRed: 36 / 255, green: 43 / 255, blue: 58 / 255, alpha: 0.96),
+                    closeFeedbackBorder: NSColor.white.withAlphaComponent(0.18),
+                    closeFeedbackText: NSColor.white.withAlphaComponent(0.76),
+                    shinePeak: NSColor.white.withAlphaComponent(0.10)
+                )
+            }
+        }
     }
 
     private enum WaterfallMetrics {
@@ -468,6 +638,7 @@
     }
 
     override func scrollWheel(with event: NSEvent) {
+        clearWindowIndexKeyPending()
         refreshHoverTarget(at: event.locationInWindow)
 
         let dominantDelta = abs(event.scrollingDeltaX) >= abs(event.scrollingDeltaY)
@@ -523,17 +694,27 @@
 
     override func mouseMoved(with event: NSEvent) {
         guard debugHoveredAppGroupIndex == nil else { return }
+        clearWindowIndexKeyPending()
 
         let toggleHovered = viewModeToggleButtonContains(windowLocation: event.locationInWindow)
+        let themeHovered = themeToggleButtonContains(windowLocation: event.locationInWindow)
         if !toggleHovered {
             suppressViewModeToggleHoverPreview = false
+        }
+        if !themeHovered {
+            suppressThemeToggleHoverPreview = false
         }
         let shouldShowToggleHoverPreview = toggleHovered && !suppressViewModeToggleHoverPreview
         if isViewModeToggleButtonHovered != shouldShowToggleHoverPreview {
             isViewModeToggleButtonHovered = shouldShowToggleHoverPreview
             needsLayout = true
         }
-        if toggleHovered {
+        let shouldShowThemeHoverPreview = themeHovered && !suppressThemeToggleHoverPreview
+        if isThemeToggleButtonHovered != shouldShowThemeHoverPreview {
+            isThemeToggleButtonHovered = shouldShowThemeHoverPreview
+            needsLayout = true
+        }
+        if toggleHovered || themeHovered {
             hoveredCloseTarget = nil
             setHoverTarget(.none)
             return
@@ -549,8 +730,11 @@
 
     override func mouseExited(with event: NSEvent) {
         guard debugHoveredAppGroupIndex == nil else { return }
+        clearWindowIndexKeyPending()
         isViewModeToggleButtonHovered = false
         suppressViewModeToggleHoverPreview = false
+        isThemeToggleButtonHovered = false
+        suppressThemeToggleHoverPreview = false
         hoveredCloseTarget = nil
         setHoverTarget(.none)
     }
@@ -564,6 +748,7 @@
             ])
             return
         }
+        clearWindowIndexKeyPending()
 
         if handleCloseConfirmationMouseDown(at: event.locationInWindow) {
             return
@@ -571,6 +756,11 @@
 
         if viewModeToggleButtonContains(windowLocation: event.locationInWindow) {
             clickViewModeToggleButton(source: "mouse")
+            return
+        }
+
+        if themeToggleButtonContains(windowLocation: event.locationInWindow) {
+            clickThemeToggleButton(source: "mouse")
             return
         }
 
@@ -618,11 +808,49 @@
         layoutSubtreeIfNeeded()
         for command in commands {
             let measurementStart = CACurrentMediaTime()
-            performKeyboardCommand(command)
+            if !performDebugPhysicalIndexKeyCommand(command) {
+                performKeyboardCommand(command)
+            }
             layoutSubtreeIfNeeded()
             CATransaction.flush()
             keyboardResponseLatencyMilliseconds.append(milliseconds(since: measurementStart))
         }
+    }
+
+    private func performDebugPhysicalIndexKeyCommand(_ rawCommand: String) -> Bool {
+        let command = rawCommand.trimmingCharacters(in: .whitespacesAndNewlines)
+        let uppercased = command.uppercased()
+        let prefixes = ["PHYSICAL-INDEX:", "PHYSICAL-INDEX-", "KEYDOWN:", "KEYDOWN-"]
+        guard let prefix = prefixes.first(where: { uppercased.hasPrefix($0) }) else {
+            return false
+        }
+
+        let symbolStart = command.index(command.startIndex, offsetBy: prefix.count)
+        guard let symbol = appShelfIndexSymbol(fromKeyboardCommand: String(command[symbolStart...])),
+              let keyCode = Self.appShelfIndexKeyCodes[symbol],
+              let event = NSEvent.keyEvent(
+                with: .keyDown,
+                location: .zero,
+                modifierFlags: [.option],
+                timestamp: ProcessInfo.processInfo.systemUptime,
+                windowNumber: window?.windowNumber ?? 0,
+                context: nil,
+                characters: symbol.lowercased(),
+                charactersIgnoringModifiers: symbol.lowercased(),
+                isARepeat: false,
+                keyCode: keyCode
+              )
+        else {
+            recordKeyboardCommand("invalidPhysicalIndex:\(command)")
+            selectionChangedByLastCommand = false
+            return true
+        }
+
+        let previousSuppressEventInput = suppressEventInput
+        suppressEventInput = false
+        keyDown(with: event)
+        suppressEventInput = previousSuppressEventInput
+        return true
     }
 
     func performDebugMouseCommands(_ commands: [String]) {
@@ -695,6 +923,15 @@
         waterfallColumnScrollOffsets = [:]
         horizontalMasonryScrollOffset = 0
         horizontalMasonryContentHeight = 0
+        needsLayout = true
+    }
+
+    func setTheme(_ theme: ThemePreference) {
+        let normalizedTheme = Self.normalizedQuickSwitchTheme(theme)
+        guard themePreference != normalizedTheme else { return }
+
+        themePreference = normalizedTheme
+        applyThemeToBackdrop()
         needsLayout = true
     }
 
@@ -845,6 +1082,11 @@
             keyboardCommandsApplied = []
             lastKeyboardCommand = nil
             lastKeyboardAppIndexCommand = nil
+            appShelfIndexKeyDownCount = 0
+            lastAppShelfIndexKeySymbol = nil
+            clearWindowIndexKeyPending()
+            lastWindowIndexKeyCommand = nil
+            lastWindowIndexKeyCommitCode = nil
             lastBoundaryBounceAxis = nil
             lastBoundaryBounceDirection = nil
             boundaryBounceCount = 0
@@ -1206,6 +1448,20 @@
             "viewModeToggleStandardBlueColor": colorDictionary(from: viewModeToggleBlueColor.cgColor),
             "viewModeToggleGlyphLineWidth": Double(ViewModeToggleMetrics.glyphLineWidth),
             "viewModeToggleAccessibilityLabel": viewModeToggleAccessibilityLabel,
+            "themeCurrentPreference": themePreference.rawValue,
+            "themeResolved": resolvedTheme.rawValue,
+            "themeNextPreference": nextThemePreference.rawValue,
+            "themeToggleButtonVisible": !themeToggleButtonLayer.isHidden,
+            "themeToggleButtonHovered": isThemeToggleButtonHovered,
+            "themeToggleHoverPreviewSuppressed": suppressThemeToggleHoverPreview,
+            "themeToggleButtonFrame": dictionary(from: themeToggleButtonLayer.frame),
+            "themeToggleHitSize": Double(ViewModeToggleMetrics.hitSize),
+            "themeToggleVisualSize": Double(ViewModeToggleMetrics.visualSize),
+            "themeToggleIconKind": "halfDisk",
+            "themeToggleAccessibilityLabel": themeToggleAccessibilityLabel,
+            "darkBackdropLayerCount": darkBackdropLayerCount,
+            "darkBackdropLayersVisible": darkBackdropLayersVisible,
+            "darkBackdropBackgroundGradientColors": backgroundGradientColorReports(),
             "settingsButtonVisible": false,
             "spaceFocusAppGroupIndexes": spaceFocusedAppGroupIndexes(),
             "appHoverAssociatedSpaceIDs": appHoverAssociatedSpaceIDs.sorted(),
@@ -1269,9 +1525,16 @@
             "selectedWindowID": effectiveSelection?.windowID ?? NSNull(),
             "keyboardFocusedAppGroupIndex": keyboardFocusedAppGroupIndex ?? NSNull(),
             "keyboardFocusedWindowID": keyboardFocusedWindowID ?? NSNull(),
+            "horizontalAppDefaultWindowID": horizontalAppDefaultWindowID ?? NSNull(),
             "keyboardCommandsApplied": keyboardCommandsApplied,
             "lastKeyboardCommand": lastKeyboardCommand ?? NSNull(),
             "lastKeyboardAppIndexCommand": lastKeyboardAppIndexCommand ?? NSNull(),
+            "appShelfIndexKeyDownCount": appShelfIndexKeyDownCount,
+            "lastAppShelfIndexKeySymbol": lastAppShelfIndexKeySymbol ?? NSNull(),
+            "windowIndexKeyPendingAppGroupIndex": windowIndexKeyPending?.appGroupIndex ?? NSNull(),
+            "windowIndexKeyPendingAppSymbol": windowIndexKeyPending?.appSymbol ?? NSNull(),
+            "lastWindowIndexKeyCommand": lastWindowIndexKeyCommand ?? NSNull(),
+            "lastWindowIndexKeyCommitCode": lastWindowIndexKeyCommitCode ?? NSNull(),
             "lastBoundaryBounceAxis": lastBoundaryBounceAxis ?? NSNull(),
             "lastBoundaryBounceDirection": lastBoundaryBounceDirection ?? NSNull(),
             "boundaryBounceCount": boundaryBounceCount,
@@ -1351,6 +1614,7 @@
         if let indexSymbol = appShelfIndexSymbol(fromKeyboardCommand: command) {
             let recordedCommand = "app:\(indexSymbol)"
             recordKeyboardCommand(recordedCommand)
+            clearWindowIndexKeyPending()
             if !focusAppShelfItemForKeyboard(indexSymbol: indexSymbol, commandLabel: recordedCommand) {
                 selectionChangedByLastCommand = false
             }
@@ -1359,6 +1623,7 @@
 
         switch command {
         case "left":
+            clearWindowIndexKeyPending()
             recordKeyboardCommand("left")
             if isHorizontalMasonryMode {
                 moveSelection(.left)
@@ -1366,6 +1631,7 @@
                 selectionChangedByLastCommand = false
             }
         case "right":
+            clearWindowIndexKeyPending()
             recordKeyboardCommand("right")
             if isHorizontalMasonryMode {
                 moveSelection(.right)
@@ -1373,6 +1639,7 @@
                 selectionChangedByLastCommand = false
             }
         case "up":
+            clearWindowIndexKeyPending()
             recordKeyboardCommand("up")
             if isHorizontalMasonryMode {
                 moveSelection(.up)
@@ -1380,6 +1647,7 @@
                 moveVerticalSelectionWithinFocusedColumn(.up)
             }
         case "down":
+            clearWindowIndexKeyPending()
             recordKeyboardCommand("down")
             if isHorizontalMasonryMode {
                 moveSelection(.down)
@@ -1387,19 +1655,22 @@
                 moveVerticalSelectionWithinFocusedColumn(.down)
             }
         case "enter", "return", "commit":
+            clearWindowIndexKeyPending()
             recordKeyboardCommand("enter")
             selectionChangedByLastCommand = false
             commitCurrentSelection()
         case "tab":
+            clearWindowIndexKeyPending()
             if isHorizontalMasonryMode {
                 recordKeyboardCommand("tab")
-                moveSelection(.right)
+                moveHorizontalMasonryTabSelection()
             } else {
                 tabIgnoredCount += 1
                 recordKeyboardCommand("tabIgnored")
                 selectionChangedByLastCommand = false
             }
         default:
+            clearWindowIndexKeyPending()
             recordKeyboardCommand("unknown:\(command)")
             selectionChangedByLastCommand = false
         }
@@ -1411,7 +1682,6 @@
     }
 
     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,
@@ -1420,7 +1690,53 @@
             return false
         }
 
+        appShelfIndexKeyDownCount += 1
+        lastAppShelfIndexKeySymbol = symbol
+        if flags.contains(.option), handleWindowIndexKey(symbol: symbol) {
+            return true
+        }
+        clearWindowIndexKeyPending()
         performKeyboardCommand(symbol)
+        return true
+    }
+
+    private func handleWindowIndexKey(symbol: String) -> Bool {
+        let now = CACurrentMediaTime()
+        if let pending = validWindowIndexKeyPending(now: now) {
+            let code = "\(pending.appSymbol)\(symbol)"
+            if let card = waterfallCard(appGroupIndex: pending.appGroupIndex, windowIndexSymbol: symbol) {
+                recordKeyboardCommand("window:\(code)")
+                lastWindowIndexKeyCommand = "window:\(code)"
+                lastWindowIndexKeyCommitCode = code
+                clearWindowIndexKeyPending()
+                commitKeyboardWindowCard(card, trigger: "windowIndexKey")
+                return true
+            }
+
+            recordKeyboardCommand("windowInvalid:\(code)")
+            lastWindowIndexKeyCommand = "windowInvalid:\(code)"
+            lastWindowIndexKeyCommitCode = nil
+            selectionChangedByLastCommand = false
+            clearWindowIndexKeyPending()
+            return true
+        }
+
+        let recordedCommand = "app:\(symbol)"
+        recordKeyboardCommand(recordedCommand)
+        lastWindowIndexKeyCommand = nil
+        lastWindowIndexKeyCommitCode = nil
+        if focusAppShelfItemForKeyboard(indexSymbol: symbol, commandLabel: recordedCommand),
+           let ordinal = Self.appShelfIndexSymbols.firstIndex(of: symbol),
+           ordinal < appShelfItems.count {
+            setWindowIndexKeyPending(
+                appSymbol: symbol,
+                appGroupIndex: appShelfItems[ordinal].item.appGroupIndex,
+                startedAt: now
+            )
+        } else {
+            selectionChangedByLastCommand = false
+            clearWindowIndexKeyPending()
+        }
         return true
     }
 
@@ -1451,6 +1767,47 @@
         )
     }
 
+    private func validWindowIndexKeyPending(now: CFTimeInterval) -> WindowIndexKeyPending? {
+        guard let pending = windowIndexKeyPending else { return nil }
+        guard now - pending.startedAt <= Self.windowIndexKeyPendingInterval else {
+            clearWindowIndexKeyPending()
+            return nil
+        }
+        return pending
+    }
+
+    private func setWindowIndexKeyPending(appSymbol: String, appGroupIndex: Int, startedAt: CFTimeInterval) {
+        windowIndexKeyPendingClearTask?.cancel()
+        windowIndexKeyPending = WindowIndexKeyPending(
+            appSymbol: appSymbol,
+            appGroupIndex: appGroupIndex,
+            startedAt: startedAt
+        )
+        windowIndexKeyPendingClearTask = Task { @MainActor [weak self] in
+            do {
+                try await Task.sleep(nanoseconds: UInt64(Self.windowIndexKeyPendingInterval * 1_000_000_000))
+            } catch {
+                return
+            }
+            guard let self,
+                  let pending = self.windowIndexKeyPending,
+                  pending.appSymbol == appSymbol,
+                  pending.appGroupIndex == appGroupIndex,
+                  pending.startedAt == startedAt
+            else {
+                return
+            }
+            self.windowIndexKeyPending = nil
+            self.windowIndexKeyPendingClearTask = nil
+        }
+    }
+
+    private func clearWindowIndexKeyPending() {
+        windowIndexKeyPendingClearTask?.cancel()
+        windowIndexKeyPendingClearTask = nil
+        windowIndexKeyPending = nil
+    }
+
     @discardableResult
     private func focusAppShelfItemForKeyboard(
         appGroupIndex: Int,
@@ -1469,6 +1826,9 @@
         clearKeyboardBoundaryFeedback()
         ensureAppShelfItemVisible(appGroupIndex)
         layoutSubtreeIfNeeded()
+        if isHorizontalMasonryMode {
+            _ = selectHorizontalMasonryDefaultWindowForApp(appGroupIndex)
+        }
         hoverAppGroup(appGroupIndex, source: .keyboard)
         needsLayout = true
         return true
@@ -1496,6 +1856,53 @@
     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) {
@@ -1641,6 +2048,7 @@
             .trimmingCharacters(in: .whitespacesAndNewlines)
             .lowercased()
         guard !command.isEmpty else { return }
+        clearWindowIndexKeyPending()
 
         let parts = command.split(separator: ":").map(String.init)
         switch parts.first {
@@ -1714,11 +2122,22 @@
             recordMouseCommand("hover-view-toggle")
             suppressViewModeToggleHoverPreview = false
             isViewModeToggleButtonHovered = true
+            isThemeToggleButtonHovered = false
             hoveredCloseTarget = nil
             setHoverTarget(.none, source: .debug)
         case "click-view-toggle", "click-settings":
             recordMouseCommand("click-view-toggle")
             clickViewModeToggleButton(source: "debug")
+        case "hover-theme-toggle":
+            recordMouseCommand("hover-theme-toggle")
+            suppressThemeToggleHoverPreview = false
+            isThemeToggleButtonHovered = true
+            isViewModeToggleButtonHovered = false
+            hoveredCloseTarget = nil
+            setHoverTarget(.none, source: .debug)
+        case "click-theme-toggle":
+            recordMouseCommand("click-theme-toggle")
+            clickThemeToggleButton(source: "debug")
         case "hover-card" where parts.count == 3:
             guard let appGroupIndex = Int(parts[1]), let windowIndex = Int(parts[2]) else {
                 recordMouseCommand("invalid:\(command)")
@@ -1951,6 +2370,34 @@
         commitWindowCard(card, trigger: "windowCard")
     }
 
+    private func commitKeyboardWindowCard(_ card: WaterfallCardLayers, trigger: String) {
+        let selection = QuickSwitchSelection(
+            appGroupIndex: card.item.appGroupIndex,
+            windowIndex: card.item.windowIndex,
+            windowID: card.item.window.id
+        )
+        DevelopmentDiagnostics.log("quickSwitch.view.commitKeyboardWindow", [
+            "trigger": trigger,
+            "appGroupIndex": selection.appGroupIndex,
+            "windowIndex": selection.windowIndex,
+            "windowID": selection.windowID,
+            "appName": card.item.window.app.name,
+            "appPID": card.item.window.app.processIdentifier,
+            "titleHash": DevelopmentDiagnostics.stableFingerprint(card.item.window.title),
+            "titleLength": card.item.window.title.count,
+            "titleIsEmpty": card.item.window.title.isEmpty,
+            "isMinimized": card.item.window.isMinimized,
+            "isFullscreen": card.item.window.isFullscreen,
+            "identifierSource": String(describing: card.item.window.identifierSource)
+        ])
+        currentSelection = selection
+        columnSelectionHistory[selection.appGroupIndex] = selection.windowIndex
+        lastCommittedSelection = selection
+        lastCommitSource = .keyboard
+        ensureCurrentSelectionVisible()
+        onCommitSelection?(selection, .keyboard)
+    }
+
     private func commitWindowCard(_ card: WaterfallCardLayers, trigger: String) {
         let selection = QuickSwitchSelection(
             appGroupIndex: card.item.appGroupIndex,
@@ -2040,6 +2487,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)
         }
@@ -2089,29 +2541,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
     }
 
@@ -2599,7 +3382,7 @@
     }
 
     private func setupBackdropBlurView() {
-        backdropBlurView.material = .fullScreenUI
+        backdropBlurView.material = resolvedTheme == .dark ? .hudWindow : .fullScreenUI
         backdropBlurView.blendingMode = .behindWindow
         backdropBlurView.state = .active
         backdropBlurView.isEmphasized = false
@@ -2617,19 +3400,91 @@
         addSubview(layerHostView, positioned: .above, relativeTo: backdropBlurView)
     }
 
+    private func applyThemeToBackdrop() {
+        let palette = themePalette
+        backdropBlurView.material = resolvedTheme == .dark ? .hudWindow : .fullScreenUI
+        backgroundLayer.colors = palette.backgroundGradientColors.map(\.cgColor)
+        backgroundLayer.locations = resolvedTheme == .dark
+            ? [0, 0.44, 0.72, 1].map(NSNumber.init(value:))
+            : [0, 1].map(NSNumber.init(value:))
+        safeAreaFillLayer.backgroundColor = palette.safeAreaFill.cgColor
+
+        let showsDarkBackdrop = resolvedTheme == .dark
+        darkAmbientLeftLayer.isHidden = !showsDarkBackdrop
+        darkAmbientCenterLayer.isHidden = !showsDarkBackdrop
+        darkAmbientRightLayer.isHidden = !showsDarkBackdrop
+        darkVignetteLayer.isHidden = !showsDarkBackdrop
+        guard showsDarkBackdrop else { return }
+
+        darkAmbientLeftLayer.colors = [
+            NSColor(calibratedRed: 72 / 255, green: 56 / 255, blue: 145 / 255, alpha: 0.34).cgColor,
+            NSColor(calibratedRed: 20 / 255, green: 28 / 255, blue: 76 / 255, alpha: 0.17).cgColor,
+            NSColor.clear.cgColor
+        ]
+        darkAmbientCenterLayer.colors = [
+            NSColor(calibratedRed: 14 / 255, green: 92 / 255, blue: 130 / 255, alpha: 0.26).cgColor,
+            NSColor(calibratedRed: 12 / 255, green: 54 / 255, blue: 89 / 255, alpha: 0.16).cgColor,
+            NSColor.clear.cgColor
+        ]
+        darkAmbientRightLayer.colors = [
+            NSColor(calibratedRed: 4 / 255, green: 92 / 255, blue: 108 / 255, alpha: 0.20).cgColor,
+            NSColor(calibratedRed: 0 / 255, green: 44 / 255, blue: 54 / 255, alpha: 0.15).cgColor,
+            NSColor.clear.cgColor
+        ]
+        darkVignetteLayer.colors = [
+            NSColor.black.withAlphaComponent(0.48).cgColor,
+            NSColor.clear.cgColor,
+            NSColor.black.withAlphaComponent(0.28).cgColor
+        ]
+        darkVignetteLayer.locations = [0, 0.36, 1].map(NSNumber.init(value:))
+    }
+
+    private func layoutBackdropLayers() {
+        applyThemeToBackdrop()
+        guard resolvedTheme == .dark else { return }
+
+        let width = max(1, bounds.width)
+        let height = max(1, bounds.height)
+        darkAmbientLeftLayer.frame = CGRect(
+            x: -width * 0.18,
+            y: -height * 0.10,
+            width: width * 0.82,
+            height: height * 1.24
+        )
+        darkAmbientCenterLayer.frame = CGRect(
+            x: width * 0.24,
+            y: height * 0.10,
+            width: width * 0.52,
+            height: height * 0.74
+        )
+        darkAmbientRightLayer.frame = CGRect(
+            x: width * 0.50,
+            y: -height * 0.12,
+            width: width * 0.72,
+            height: height * 1.26
+        )
+        darkVignetteLayer.frame = bounds
+    }
+
     private func setupLayers() {
         guard let rootLayer = layerHostView.layer else { return }
 
         rootLayer.masksToBounds = true
-        backgroundLayer.colors = [
-            NSColor.windowBackgroundColor.withAlphaComponent(0.58).cgColor,
-            NSColor.controlBackgroundColor.withAlphaComponent(0.48).cgColor
-        ]
         backgroundLayer.startPoint = CGPoint(x: 0.5, y: 1.0)
         backgroundLayer.endPoint = CGPoint(x: 0.5, y: 0.0)
         rootLayer.addSublayer(backgroundLayer)
+        for ambientLayer in darkBackdropAmbientLayers {
+            ambientLayer.type = .radial
+            ambientLayer.startPoint = CGPoint(x: 0.5, y: 0.5)
+            ambientLayer.endPoint = CGPoint(x: 1.0, y: 1.0)
+            ambientLayer.isHidden = true
+            rootLayer.addSublayer(ambientLayer)
+        }
+        darkVignetteLayer.startPoint = CGPoint(x: 0.5, y: 1.0)
+        darkVignetteLayer.endPoint = CGPoint(x: 0.5, y: 0.0)
+        darkVignetteLayer.isHidden = true
+        rootLayer.addSublayer(darkVignetteLayer)
 
-        safeAreaFillLayer.backgroundColor = NSColor.black.cgColor
         rootLayer.addSublayer(safeAreaFillLayer)
 
         glassLayer.cornerRadius = 0
@@ -2686,6 +3541,18 @@
         viewModeToggleIconLayer.contentsScale = backingScaleFactor
         viewModeToggleButtonLayer.addSublayer(viewModeToggleIconLayer)
         glassLayer.addSublayer(viewModeToggleButtonLayer)
+
+        themeToggleButtonLayer.cornerRadius = 10
+        themeToggleButtonLayer.masksToBounds = false
+        themeToggleButtonLayer.borderWidth = 1
+        themeToggleButtonLayer.shadowColor = NSColor.black.cgColor
+        themeToggleButtonLayer.shadowOffset = CGSize(width: 0, height: -2)
+        themeToggleButtonLayer.zPosition = 170
+        themeToggleIconLayer.contentsScale = backingScaleFactor
+        themeToggleButtonLayer.addSublayer(themeToggleIconLayer)
+        glassLayer.addSublayer(themeToggleButtonLayer)
+
+        applyThemeToBackdrop()
     }
 
     private func rebuildAppShelfItems() {
@@ -2726,7 +3593,7 @@
                 string: item.app.name,
                 fontSize: 11,
                 weight: .regular,
-                color: .secondaryLabelColor,
+                color: themePalette.appShelfLabelText,
                 alignment: .center
             )
 
@@ -2778,8 +3645,8 @@
             container.name = column.app.name
             container.cornerRadius = 14
             container.masksToBounds = true
-            container.backgroundColor = NSColor.controlBackgroundColor.withAlphaComponent(0.56).cgColor
-            container.borderColor = NSColor.separatorColor.withAlphaComponent(0.34).cgColor
+            container.backgroundColor = themePalette.columnBackground.cgColor
+            container.borderColor = themePalette.columnBorder.cgColor
             container.borderWidth = 1
 
             let cardsClip = CALayer()
@@ -2787,21 +3654,21 @@
             cardsClip.backgroundColor = NSColor.clear.cgColor
 
             let header = CALayer()
-            header.backgroundColor = NSColor.controlBackgroundColor.withAlphaComponent(0.68).cgColor
+            header.backgroundColor = themePalette.columnHeaderBackground.cgColor
             header.zPosition = 40
 
             let appName = makeTextLayer(
                 string: column.app.name,
                 fontSize: 13,
                 weight: .semibold,
-                color: .labelColor,
+                color: themePalette.columnText,
                 alignment: .center
             )
             let count = makeTextLayer(
                 string: "\(column.windows.count)",
                 fontSize: 11,
                 weight: .medium,
-                color: .secondaryLabelColor,
+                color: themePalette.columnSecondaryText,
                 alignment: .right
             )
 
@@ -2833,14 +3700,15 @@
                     string: window.window.title.isEmpty ? "Untitled Window" : window.window.title,
                     fontSize: 12,
                     weight: .medium,
-                    color: .labelColor
+                    color: themePalette.cardText
                 )
                 title.truncationMode = .middle
                 let meta = makeTextLayer(
                     string: waterfallMetaText(for: window),
                     fontSize: 10,
                     weight: .regular,
-                    color: .secondaryLabelColor
+                    color: themePalette.cardSecondaryText,
+                    alignment: .right
                 )
                 let appIcon = CALayer()
                 appIcon.contentsGravity = .resizeAspect
@@ -2853,13 +3721,13 @@
                     string: waterfallStateText(for: window),
                     fontSize: 10,
                     weight: .medium,
-                    color: .secondaryLabelColor,
+                    color: themePalette.cardSecondaryText,
                     alignment: .right
                 )
                 let shine = CAGradientLayer()
                 shine.colors = [
                     NSColor.white.withAlphaComponent(0.00).cgColor,
-                    NSColor.white.withAlphaComponent(0.16).cgColor,
+                    themePalette.shinePeak.cgColor,
                     NSColor.white.withAlphaComponent(0.00).cgColor
                 ]
                 shine.startPoint = CGPoint(x: 0, y: 1)
@@ -2923,7 +3791,7 @@
             groupContainer.masksToBounds = false
             groupContainer.borderWidth = 0
             groupContainer.borderColor = NSColor.clear.cgColor
-            groupContainer.backgroundColor = NSColor.windowBackgroundColor.cgColor
+            groupContainer.backgroundColor = themePalette.displayGroupBackground.cgColor
             groupContainer.shadowColor = NSColor.black.cgColor
             groupContainer.shadowOpacity = 0
             groupContainer.shadowRadius = 0
@@ -2944,20 +3812,20 @@
                     string: space.label,
                     fontSize: 15,
                     weight: .semibold,
-                    color: .labelColor
+                    color: themePalette.spaceLanePrimaryText
                 )
                 let countLayer = makeTextLayer(
                     string: "\(space.windowCount)",
                     fontSize: 12,
                     weight: .medium,
-                    color: .secondaryLabelColor,
+                    color: themePalette.spaceLaneSecondaryText,
                     alignment: .center
                 )
                 let appLayer = makeTextLayer(
                     string: appIdentifierText(for: space),
                     fontSize: 12,
                     weight: space.type == .fullscreen ? .medium : .regular,
-                    color: space.type == .fullscreen ? .labelColor : .secondaryLabelColor,
+                    color: space.type == .fullscreen ? themePalette.spaceLanePrimaryText : themePalette.spaceLaneSecondaryText,
                     alignment: space.type == .fullscreen ? .center : .left
                 )
                 let splitAppLayers = splitViewAppNames(for: space).map { name in
@@ -2965,7 +3833,7 @@
                         string: name,
                         fontSize: 12,
                         weight: .medium,
-                        color: .labelColor,
+                        color: themePalette.spaceLanePrimaryText,
                         alignment: .center
                     )
                 }
@@ -3018,6 +3886,7 @@
         CATransaction.setDisableActions(true)
 
         backgroundLayer.frame = bounds
+        layoutBackdropLayers()
 
         let safeAreaTopInset = topSafeAreaInset
         safeAreaFillLayer.frame = CGRect(
@@ -3061,6 +3930,7 @@
         layoutCloseConfirmation()
         layoutCloseFeedback()
         layoutViewModeToggleButton()
+        layoutThemeToggleButton()
 
         CATransaction.commit()
     }
@@ -3082,7 +3952,7 @@
         let isSelectedState = viewModeToggleVisualStateIsSelected(visualState)
         viewModeToggleButtonLayer.backgroundColor = (isSelectedState
             ? viewModeToggleBlueColor
-            : NSColor.windowBackgroundColor.withAlphaComponent(isViewModeToggleButtonHovered ? 0.76 : 0.58)
+            : toggleIdleBackgroundColor(hovered: isViewModeToggleButtonHovered)
         ).cgColor
         viewModeToggleButtonLayer.borderColor = (isSelectedState
             ? viewModeToggleBlueColor.withAlphaComponent(0.96)
@@ -3096,6 +3966,45 @@
         let iconInset = ViewModeToggleMetrics.iconInset
         viewModeToggleIconLayer.frame = viewModeToggleButtonLayer.bounds.insetBy(dx: iconInset, dy: iconInset)
         layoutViewModeToggleIcon()
+    }
+
+    private func layoutThemeToggleButton() {
+        let size = ViewModeToggleMetrics.visualSize
+        let topMargin = topSafeAreaInset + RootLayoutMetrics.topContentMargin
+        let viewModeFrame = viewModeToggleButtonLayer.frame
+        let fallbackX = max(
+            RootLayoutMetrics.horizontalMargin,
+            glassLayer.bounds.width - RootLayoutMetrics.horizontalMargin - size * 2 - ThemeToggleMetrics.buttonGap
+        )
+        let x = max(
+            RootLayoutMetrics.horizontalMargin,
+            (viewModeFrame.width > 0 ? viewModeFrame.minX : fallbackX + size + ThemeToggleMetrics.buttonGap)
+                - ThemeToggleMetrics.buttonGap
+                - size
+        )
+        let y = max(
+            RootLayoutMetrics.bottomMargin,
+            glassLayer.bounds.height - topMargin - size
+        )
+        themeToggleButtonLayer.frame = CGRect(x: x, y: y, width: size, height: size)
+        themeToggleButtonLayer.cornerRadius = ViewModeToggleMetrics.cornerRadius
+        let isSelectedState = resolvedTheme == .dark
+        themeToggleButtonLayer.backgroundColor = (isSelectedState
+            ? viewModeToggleBlueColor
+            : themeToggleIdleBackgroundColor
+        ).cgColor
+        themeToggleButtonLayer.borderColor = (isSelectedState
+            ? viewModeToggleBlueColor.withAlphaComponent(0.96)
+            : viewModeToggleBlueColor.withAlphaComponent(isThemeToggleButtonHovered ? 0.72 : 0.34)
+        ).cgColor
+        themeToggleButtonLayer.shadowOpacity = isSelectedState ? 0.18 : (isThemeToggleButtonHovered ? 0.12 : 0.06)
+        themeToggleButtonLayer.shadowRadius = isSelectedState
+            ? ViewModeToggleMetrics.selectedShadowRadius
+            : ViewModeToggleMetrics.idleShadowRadius
+        themeToggleIconLayer.contentsScale = backingScaleFactor
+        let iconInset = ViewModeToggleMetrics.iconInset
+        themeToggleIconLayer.frame = themeToggleButtonLayer.bounds.insetBy(dx: iconInset, dy: iconInset)
+        layoutThemeToggleIcon()
     }
 
     private func layoutViewModeToggleIcon() {
@@ -3135,6 +4044,88 @@
         }
 
         CATransaction.commit()
+    }
+
+    private func layoutThemeToggleIcon() {
+        CATransaction.begin()
+        CATransaction.setDisableActions(true)
+        themeToggleIconLayer.sublayers?.forEach { $0.removeFromSuperlayer() }
+
+        let bounds = themeToggleIconLayer.bounds
+        guard bounds.width > 0, bounds.height > 0 else {
+            CATransaction.commit()
+            return
+        }
+
+        let isSelectedState = resolvedTheme == .dark
+        let strokeColor = isSelectedState
+            ? NSColor.white.withAlphaComponent(0.98)
+            : viewModeToggleBlueColor.withAlphaComponent(0.96)
+        let lightFillColor = isSelectedState
+            ? NSColor.white.withAlphaComponent(0.22)
+            : viewModeToggleBlueColor.withAlphaComponent(0.06)
+        let darkFillColor = isSelectedState
+            ? NSColor.white.withAlphaComponent(0.96)
+            : viewModeToggleBlueColor.withAlphaComponent(0.82)
+        let glyphRect = centeredSquare(in: bounds).insetBy(dx: 0.75, dy: 0.75)
+        addThemeToggleHalfDiskGlyph(
+            in: glyphRect,
+            strokeColor: strokeColor,
+            lightFillColor: lightFillColor,
+            darkFillColor: darkFillColor
+        )
+
+        CATransaction.commit()
+    }
+
+    private func addThemeToggleHalfDiskGlyph(
+        in rect: CGRect,
+        strokeColor: NSColor,
+        lightFillColor: NSColor,
+        darkFillColor: NSColor
+    ) {
+        let circlePath = CGPath(
+            ellipseIn: rect,
+            transform: nil
+        )
+        let baseLayer = CAShapeLayer()
+        baseLayer.contentsScale = backingScaleFactor
+        baseLayer.frame = themeToggleIconLayer.bounds
+        baseLayer.path = circlePath
+        baseLayer.fillColor = lightFillColor.cgColor
+        baseLayer.strokeColor = NSColor.clear.cgColor
+        themeToggleIconLayer.addSublayer(baseLayer)
+
+        let radius = min(rect.width, rect.height) / 2
+        let center = CGPoint(x: rect.midX, y: rect.midY)
+        let halfPath = CGMutablePath()
+        halfPath.move(to: CGPoint(x: center.x, y: center.y + radius))
+        halfPath.addArc(
+            center: center,
+            radius: radius,
+            startAngle: .pi / 2,
+            endAngle: .pi * 1.5,
+            clockwise: false
+        )
+        halfPath.closeSubpath()
+
+        let halfLayer = CAShapeLayer()
+        halfLayer.contentsScale = backingScaleFactor
+        halfLayer.frame = themeToggleIconLayer.bounds
+        halfLayer.path = halfPath
+        halfLayer.fillColor = darkFillColor.cgColor
+        halfLayer.strokeColor = NSColor.clear.cgColor
+        themeToggleIconLayer.addSublayer(halfLayer)
+
+        let outlineLayer = CAShapeLayer()
+        outlineLayer.contentsScale = backingScaleFactor
+        outlineLayer.frame = themeToggleIconLayer.bounds
+        outlineLayer.path = circlePath
+        outlineLayer.fillColor = NSColor.clear.cgColor
+        outlineLayer.strokeColor = strokeColor.cgColor
+        outlineLayer.lineWidth = ViewModeToggleMetrics.glyphLineWidth
+        outlineLayer.lineJoin = .round
+        themeToggleIconLayer.addSublayer(outlineLayer)
     }
 
     private func addVerticalColumnsToggleGlyph(
@@ -3380,7 +4371,7 @@
                 || segment.space.id == currentViewModel?.lockedSpaceID
         }
         let hasCurrentSegment = group.display.spaces.contains { $0.isCurrent }
-        group.containerLayer.backgroundColor = NSColor.windowBackgroundColor.cgColor
+        group.containerLayer.backgroundColor = themePalette.displayGroupBackground.cgColor
         group.containerLayer.borderColor = NSColor.clear.cgColor
         group.containerLayer.borderWidth = 0
         group.containerLayer.shadowOpacity = 0
@@ -3411,8 +4402,8 @@
                 : hasWindows
                     ? spaceLaneOccupiedColor.withAlphaComponent(isCurrent ? 0.54 : 0.44)
                 : isCurrent
-                    ? NSColor.labelColor.withAlphaComponent(0.34)
-                : NSColor.separatorColor.withAlphaComponent(0.34)
+                    ? themePalette.spaceLanePrimaryText.withAlphaComponent(0.34)
+                : themePalette.columnBorder.withAlphaComponent(resolvedTheme == .dark ? 0.58 : 0.34)
         ).cgColor
         if isLocked {
             applySpaceLaneSolidFill(
@@ -3463,17 +4454,41 @@
             )
             : nil
 
-        applySpaceLaneContentVisualState(segment, isLocked: isLocked)
+        applySpaceLaneContentVisualState(
+            segment,
+            isLocked: isLocked,
+            usesLightActiveFill: resolvedTheme == .dark && hasWindows && !isLocked && (isActive || isAssociated)
+        )
     }
 
-    private func applySpaceLaneContentVisualState(_ segment: SpaceLaneSegmentLayers, isLocked: Bool) {
-        let primaryTextColor: NSColor = isLocked ? .white : .labelColor
+    private func applySpaceLaneContentVisualState(
+        _ segment: SpaceLaneSegmentLayers,
+        isLocked: Bool,
+        usesLightActiveFill: Bool
+    ) {
+        let primaryTextColor: NSColor = isLocked
+            ? .white
+            : usesLightActiveFill
+                ? NSColor.black.withAlphaComponent(0.82)
+                : themePalette.spaceLanePrimaryText
         let secondaryTextColor: NSColor = isLocked
             ? .white
-            : .secondaryLabelColor
+            : usesLightActiveFill
+                ? NSColor.black.withAlphaComponent(0.58)
+                : themePalette.spaceLaneSecondaryText
+        let markerTextColor: NSColor = isLocked
+            ? .white
+            : usesLightActiveFill
+                ? NSColor.black.withAlphaComponent(0.62)
+                : themePalette.spaceLaneSecondaryText.withAlphaComponent(segment.space.isCurrent ? 0.72 : 0.54)
+        let blockColor: NSColor = isLocked
+            ? .white
+            : usesLightActiveFill
+                ? NSColor.black.withAlphaComponent(0.20)
+                : spaceLaneOccupiedColor.withAlphaComponent(segment.space.isCurrent ? 0.72 : 0.58)
 
         segment.labelLayer.foregroundColor = primaryTextColor.cgColor
-        segment.countLayer.foregroundColor = (isLocked ? NSColor.white : .secondaryLabelColor).cgColor
+        segment.countLayer.foregroundColor = secondaryTextColor.cgColor
         segment.appLayer.foregroundColor = (segment.space.type == .fullscreen
             ? primaryTextColor
             : secondaryTextColor
@@ -3483,16 +4498,10 @@
         }
 
         for block in segment.windowBlocks {
-            block.backgroundColor = (isLocked
-                ? NSColor.white
-                : spaceLaneOccupiedColor.withAlphaComponent(segment.space.isCurrent ? 0.72 : 0.58)
-            ).cgColor
+            block.backgroundColor = blockColor.cgColor
         }
 
-        (segment.fullscreenMarkerLayer as? CAShapeLayer)?.strokeColor = (isLocked
-            ? NSColor.white
-            : NSColor.secondaryLabelColor.withAlphaComponent(segment.space.isCurrent ? 0.42 : 0.28)
-        ).cgColor
+        (segment.fullscreenMarkerLayer as? CAShapeLayer)?.strokeColor = markerTextColor.cgColor
     }
 
     private func shouldScrollSpaceLane(for event: NSEvent) -> Bool {
@@ -3577,6 +4586,18 @@
             .contains(locationInGlass)
     }
 
+    private func themeToggleButtonContains(windowLocation: CGPoint) -> Bool {
+        let locationInView = convert(windowLocation, from: nil)
+        let locationInGlass = CGPoint(
+            x: locationInView.x - glassLayer.frame.minX,
+            y: locationInView.y - glassLayer.frame.minY
+        )
+        let hitOutset = (ViewModeToggleMetrics.hitSize - ViewModeToggleMetrics.visualSize) / 2
+        return themeToggleButtonLayer.frame
+            .insetBy(dx: -hitOutset, dy: -hitOutset)
+            .contains(locationInGlass)
+    }
+
     private func clickViewModeToggleButton(source: String) {
         DevelopmentDiagnostics.log("quickSwitch.view.clickWaterfallViewModeToggle", [
             "source": source,
@@ -3590,6 +4611,21 @@
         isViewModeToggleButtonHovered = false
         suppressViewModeToggleHoverPreview = true
         onToggleWaterfallViewMode?()
+    }
+
+    private func clickThemeToggleButton(source: String) {
+        DevelopmentDiagnostics.log("quickSwitch.view.clickThemeToggle", [
+            "source": source,
+            "currentTheme": resolvedTheme.rawValue,
+            "targetTheme": nextThemePreference.rawValue
+        ])
+        lastMouseCommand = "click-theme-toggle"
+        if !mouseCommandsApplied.contains("click-theme-toggle") {
+            mouseCommandsApplied.append("click-theme-toggle")
+        }
+        isThemeToggleButtonHovered = false
+        suppressThemeToggleHoverPreview = true
+        onToggleTheme?()
     }
 
     private func appShelfItem(at windowLocation: CGPoint) -> AppShelfItemLayers? {
@@ -3636,6 +4672,15 @@
             .first(where: { $0.column.appGroupIndex == appGroupIndex })?
             .cards
             .first(where: { $0.item.windowIndex == windowIndex })
+    }
+
+    private func waterfallCard(appGroupIndex: Int, windowIndexSymbol: String) -> WaterfallCardLayers? {
+        guard let ordinal = Self.appShelfIndexSymbols.firstIndex(of: windowIndexSymbol),
+              ordinal < Self.appShelfIndexSymbols.count
+        else {
+            return nil
+        }
+        return waterfallCard(appGroupIndex: appGroupIndex, windowIndex: ordinal)
     }
 
     private func waterfallCard(windowID: UInt32) -> WaterfallCardLayers? {
@@ -3816,6 +4861,7 @@
             highlighted: showsSelectedVisual || isHovered
         )
         item.labelLayer.contentsScale = backingScaleFactor
+        item.labelLayer.foregroundColor = themePalette.appShelfLabelText.cgColor
         item.labelLayer.frame = CGRect(x: 0, y: 0, width: bounds.width, height: 14)
         item.badgeLayer.string = badgeText
         item.badgeLayer.isHidden = badgeText.isEmpty
@@ -3843,11 +4889,11 @@
     }
 
     private var appShelfIndexColor: NSColor {
-        NSColor.labelColor.withAlphaComponent(0.48)
+        themePalette.appShelfIndexText
     }
 
     private var appShelfIndexHighlightedColor: NSColor {
-        NSColor.labelColor.withAlphaComponent(0.58)
+        themePalette.appShelfIndexHighlightedText
     }
 
     private func appShelfIndexFont(size: CGFloat) -> NSFont {
@@ -4072,13 +5118,13 @@
 
     private func appShelfBackgroundColor(selected: Bool, hovered: Bool, spaceFocused: Bool) -> NSColor {
         if selected {
-            return NSColor.controlAccentColor.withAlphaComponent(0.14)
+            return themePalette.appShelfBackgroundSelected
         }
         if hovered {
-            return NSColor.controlAccentColor.withAlphaComponent(0.13)
+            return themePalette.appShelfBackgroundHovered
         }
         if spaceFocused {
-            return NSColor.controlAccentColor.withAlphaComponent(0.14)
+            return themePalette.appShelfBackgroundSpaceFocused
         }
         return .clear
     }
@@ -4103,7 +5149,7 @@
     }
 
     private var waterfallAppHoverHeaderFillColor: NSColor {
-        NSColor.systemGray.withAlphaComponent(0.22)
+        themePalette.columnHeaderHoverBackground
     }
 
     private var appShelfMaxScrollOffset: CGFloat {
@@ -4318,7 +5364,7 @@
     private func layoutWaterfallColumn(_ column: WaterfallColumnLayers) {
         column.containerLayer.cornerRadius = 14
         column.containerLayer.masksToBounds = true
-        column.containerLayer.backgroundColor = NSColor.controlBackgroundColor.withAlphaComponent(0.56).cgColor
+        column.containerLayer.backgroundColor = themePalette.columnBackground.cgColor
         column.containerLayer.shadowOpacity = 0
         column.containerLayer.shadowRadius = 0
         column.containerLayer.shadowOffset = .zero
@@ -4338,8 +5384,8 @@
         let isSpaceFocused = spaceFocusWindowCount(for: column.column.appGroupIndex) > 0
         let isHovered = column.column.appGroupIndex == effectiveHoveredAppGroupIndex
         column.containerLayer.borderColor = (isSpaceFocused
-            ? NSColor.separatorColor.withAlphaComponent(0.38)
-            : NSColor.separatorColor.withAlphaComponent(0.24)
+            ? themePalette.columnBorder.withAlphaComponent(resolvedTheme == .dark ? 0.34 : 0.38)
+            : themePalette.columnBorder
         ).cgColor
         column.containerLayer.borderWidth = 1
         column.headerLayer.frame = CGRect(
@@ -4351,8 +5397,8 @@
         column.headerLayer.backgroundColor = (isHovered
             ? waterfallAppHoverHeaderFillColor
             : (isSpaceFocused
-                ? NSColor.systemFill.withAlphaComponent(0.10)
-                : NSColor.controlBackgroundColor.withAlphaComponent(0.52))
+                ? themePalette.columnHeaderSpaceFocusedBackground
+                : themePalette.columnHeaderBackground)
         ).cgColor
         column.appNameLayer.frame = CGRect(
             x: WaterfallMetrics.columnHeaderTextInset,
@@ -4360,14 +5406,14 @@
             width: max(1, bounds.width - WaterfallMetrics.columnHeaderTextInset * 2),
             height: 16
         )
-        column.appNameLayer.foregroundColor = NSColor.labelColor.cgColor
+        column.appNameLayer.foregroundColor = themePalette.columnText.cgColor
         column.countLayer.frame = CGRect(
             x: bounds.width - 48,
             y: bounds.height - 24,
             width: 36,
             height: 16
         )
-        column.countLayer.foregroundColor = NSColor.secondaryLabelColor.cgColor
+        column.countLayer.foregroundColor = themePalette.columnSecondaryText.cgColor
 
         let appGroupIndex = column.column.appGroupIndex
         let verticalOffset = clampedWaterfallColumnOffset(
@@ -4403,10 +5449,13 @@
         let isSelected = card.item.window.id == effectiveSelection?.windowID
         let isHovered = card.item.window.id == hoveredWindowID
         let isKeyboardFocused = card.item.window.id == keyboardFocusedWindowID
+        let isHorizontalAppDefaultFocused = isHorizontalAppDefaultCard(card)
         let isAppLinked = isWaterfallCardAppLinked(card)
         applyWaterfallCardVisualState(
             card,
-            selected: shouldShowSelectedVisual(isSelected: isSelected, isHovered: isHovered) || isKeyboardFocused,
+            selected: shouldShowSelectedVisual(isSelected: isSelected, isHovered: isHovered)
+                || isKeyboardFocused
+                || isHorizontalAppDefaultFocused,
             hovered: isHovered,
             appLinked: isAppLinked
         )
@@ -4441,18 +5490,21 @@
             width: max(1, titleBarFrame.width - 68),
             height: 16
         )
+        card.titleLayer.foregroundColor = themePalette.cardText.cgColor
         card.metaLayer.frame = CGRect(
             x: titleBarFrame.maxX - 38,
             y: titleBarFrame.minY + 6,
             width: 30,
             height: 14
         )
+        card.metaLayer.foregroundColor = themePalette.cardSecondaryText.cgColor
         card.stateLayer.frame = CGRect(
             x: thumbnailFrame.maxX - 86,
             y: thumbnailFrame.minY + 6,
             width: 78,
             height: 14
         )
+        card.stateLayer.foregroundColor = themePalette.cardSecondaryText.cgColor
         layoutCloseButton(
             card.closeButton,
             target: .window(
@@ -4469,6 +5521,11 @@
             width: max(36, min(96, bounds.width * 0.24)),
             height: bounds.height
         )
+        card.shineLayer.colors = [
+            NSColor.white.withAlphaComponent(0.00).cgColor,
+            themePalette.shinePeak.cgColor,
+            NSColor.white.withAlphaComponent(0.00).cgColor
+        ]
     }
 
     private func applyWaterfallCardVisualState(
@@ -4479,14 +5536,14 @@
     ) {
         let isSpaceFocused = isWaterfallCardSpaceFocused(card)
         card.containerLayer.backgroundColor = (selected
-            ? NSColor.windowBackgroundColor.withAlphaComponent(0.94)
+            ? themePalette.cardSelectedBackground
             : hovered
                 ? accentTintedWindowBackground(fraction: 0.09, alpha: 0.95)
                 : appLinked
                     ? accentTintedWindowBackground(fraction: 0.08, alpha: 0.93)
                 : isSpaceFocused
                     ? accentTintedWindowBackground(fraction: 0.10, alpha: 0.94)
-                : NSColor.windowBackgroundColor.withAlphaComponent(0.82)
+                : themePalette.cardBackground
         ).cgColor
         card.containerLayer.borderColor = (selected
             ? NSColor.controlAccentColor.withAlphaComponent(0.52)
@@ -4500,7 +5557,16 @@
         ).cgColor
         card.containerLayer.borderWidth = (selected || hovered || appLinked || isSpaceFocused) ? 1.5 : 1
         card.containerLayer.shadowColor = NSColor.black.cgColor
-        card.containerLayer.shadowOpacity = selected ? 0.24 : hovered ? 0.14 : appLinked ? 0.16 : isSpaceFocused ? 0.20 : 0
+        let darkShadowBoost: Float = resolvedTheme == .dark ? 0.08 : 0
+        card.containerLayer.shadowOpacity = selected
+            ? 0.24 + darkShadowBoost
+            : hovered
+                ? 0.14 + darkShadowBoost
+                : appLinked
+                    ? 0.16 + darkShadowBoost
+                    : isSpaceFocused
+                        ? 0.20 + darkShadowBoost
+                        : 0
         card.containerLayer.shadowRadius = selected ? 22 : hovered ? 17 : appLinked ? 18 : isSpaceFocused ? 24 : 0
         card.containerLayer.shadowOffset = selected
             ? CGSize(width: 0, height: -6)
@@ -4524,9 +5590,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
@@ -4632,9 +5701,16 @@
         )
         layers.backgroundLayer.frame = layers.containerLayer.bounds
         layers.backgroundLayer.path = bubblePath
+        layers.backgroundLayer.fillColor = themePalette.closeFeedbackBackground.withAlphaComponent(resolvedTheme == .dark ? 0.98 : 0.985).cgColor
+        layers.backgroundLayer.strokeColor = themePalette.closeFeedbackBorder.withAlphaComponent(resolvedTheme == .dark ? 0.78 : 1).cgColor
         layers.containerLayer.shadowPath = bubblePath
         layers.titleLayer.string = confirmationTitle(for: request)
         layers.messageLayer.string = confirmationMessage(for: request)
+        layers.titleLayer.foregroundColor = (resolvedTheme == .dark
+            ? NSColor.white.withAlphaComponent(0.92)
+            : NSColor.labelColor
+        ).cgColor
+        layers.messageLayer.foregroundColor = themePalette.closeFeedbackText.cgColor
         layers.titleLayer.frame = CGRect(x: contentFrame.minX + 22, y: height - 48, width: contentFrame.width - 44, height: 22)
         layers.messageLayer.frame = CGRect(x: contentFrame.minX + 22, y: height - 78, width: contentFrame.width - 44, height: 21)
 
@@ -4645,12 +5721,22 @@
         ).cgColor
         layers.checkboxLayer.borderColor = (pendingCloseOptOut
             ? NSColor.controlAccentColor.withAlphaComponent(0.95)
-            : NSColor.separatorColor.withAlphaComponent(0.48)
+            : themePalette.closeFeedbackBorder.withAlphaComponent(resolvedTheme == .dark ? 0.80 : 0.48)
         ).cgColor
         layers.checkboxMarkLayer.string = pendingCloseOptOut ? "✓" : ""
         layers.checkboxMarkLayer.frame = CGRect(x: 0, y: 1, width: 18, height: 16)
+        layers.checkboxLabelLayer.foregroundColor = themePalette.closeFeedbackText.cgColor
         layers.checkboxLabelLayer.frame = CGRect(x: contentFrame.minX + 48, y: 80, width: contentFrame.width - 70, height: 19)
 
+        layers.cancelButtonLayer.backgroundColor = (resolvedTheme == .dark
+            ? NSColor.white.withAlphaComponent(0.10)
+            : NSColor.systemFill.withAlphaComponent(0.16)
+        ).cgColor
+        layers.cancelButtonLayer.borderColor = themePalette.closeFeedbackBorder.withAlphaComponent(resolvedTheme == .dark ? 0.70 : 0.22).cgColor
+        layers.cancelButtonTextLayer.foregroundColor = (resolvedTheme == .dark
+            ? NSColor.white.withAlphaComponent(0.86)
+            : NSColor.labelColor
+        ).cgColor
         layers.cancelButtonLayer.frame = CGRect(x: contentFrame.maxX - 164, y: 22, width: 74, height: 32)
         layers.cancelButtonTextLayer.frame = layers.cancelButtonLayer.bounds.insetBy(dx: 0, dy: 7)
         layers.confirmButtonLayer.frame = CGRect(x: contentFrame.maxX - 78, y: 22, width: 56, height: 32)
@@ -4665,9 +5751,9 @@
         closeFeedbackTextLayer.string = feedback.message
         switch feedback.kind {
         case .progress:
-            closeFeedbackLayer.backgroundColor = NSColor.windowBackgroundColor.withAlphaComponent(0.94).cgColor
-            closeFeedbackLayer.borderColor = NSColor.separatorColor.withAlphaComponent(0.28).cgColor
-            closeFeedbackTextLayer.foregroundColor = NSColor.secondaryLabelColor.withAlphaComponent(0.96).cgColor
+            closeFeedbackLayer.backgroundColor = themePalette.closeFeedbackBackground.cgColor
+            closeFeedbackLayer.borderColor = themePalette.closeFeedbackBorder.cgColor
+            closeFeedbackTextLayer.foregroundColor = themePalette.closeFeedbackText.cgColor
         case .failure:
             closeFeedbackLayer.backgroundColor = NSColor.systemRed.withAlphaComponent(0.10).cgColor
             closeFeedbackLayer.borderColor = NSColor.systemRed.withAlphaComponent(0.32).cgColor
@@ -5055,8 +6141,9 @@
     }
 
     private func accentTintedWindowBackground(fraction: CGFloat, alpha: CGFloat) -> NSColor {
-        let color = NSColor.windowBackgroundColor.blended(withFraction: fraction, of: NSColor.controlAccentColor)
-            ?? NSColor.windowBackgroundColor
+        let baseColor = resolvedTheme == .dark ? themePalette.cardBackground : NSColor.windowBackgroundColor
+        let color = baseColor.blended(withFraction: fraction, of: NSColor.controlAccentColor)
+            ?? baseColor
         return color.withAlphaComponent(alpha)
     }
 
@@ -5070,6 +6157,10 @@
 
         if isHorizontalMasonryMode {
             return true
+        }
+
+        if keyboardFocusedWindowID != nil {
+            return false
         }
 
         return waterfallColumns
@@ -5104,12 +6195,45 @@
         waterfallViewMode == .horizontalMasonry
     }
 
+    private var resolvedTheme: QuickSwitchResolvedTheme {
+        themePreference == .dark ? .dark : .light
+    }
+
+    private var themePalette: QuickSwitchThemePalette {
+        QuickSwitchThemePalette.palette(for: resolvedTheme)
+    }
+
+    private var darkBackdropAmbientLayers: [CAGradientLayer] {
+        [darkAmbientLeftLayer, darkAmbientCenterLayer, darkAmbientRightLayer]
+    }
+
+    private static func normalizedQuickSwitchTheme(_ theme: ThemePreference) -> ThemePreference {
+        theme == .dark ? .dark : .light
+    }
+
+    private var nextThemePreference: ThemePreference {
+        resolvedTheme == .dark ? .light : .dark
+    }
+
     private var nextWaterfallViewMode: QuickSwitchWaterfallViewMode {
         isHorizontalMasonryMode ? .verticalColumns : .horizontalMasonry
     }
 
     private var viewModeToggleBlueColor: NSColor {
         NSColor(deviceRed: 135.0 / 255.0, green: 200.0 / 255.0, blue: 1, alpha: 1)
+    }
+
+    private var themeToggleIdleBackgroundColor: NSColor {
+        toggleIdleBackgroundColor(hovered: isThemeToggleButtonHovered)
+    }
+
+    private func toggleIdleBackgroundColor(hovered: Bool) -> NSColor {
+        switch resolvedTheme {
+        case .light:
+            return NSColor.windowBackgroundColor.withAlphaComponent(hovered ? 0.76 : 0.58)
+        case .dark:
+            return NSColor(calibratedRed: 24 / 255, green: 34 / 255, blue: 54 / 255, alpha: hovered ? 0.76 : 0.58)
+        }
     }
 
     private var viewModeToggleVisualState: ViewModeToggleVisualState {
@@ -5138,6 +6262,15 @@
             return "切换到纵栏瀑布"
         case .horizontalMasonry:
             return "切换到横栏瀑布"
+        }
+    }
+
+    private var themeToggleAccessibilityLabel: String {
+        switch nextThemePreference {
+        case .dark:
+            return "切换到深色皮肤"
+        case .light, .system:
+            return "切换到浅色皮肤"
         }
     }
 
@@ -5183,7 +6316,26 @@
     }
 
     private func waterfallMetaText(for card: QuickSwitchWindowCardViewModel) -> String {
-        card.primarySpaceLabel ?? "No Space"
+        windowShortcutCode(for: card) ?? ""
+    }
+
+    private func windowShortcutCode(for card: QuickSwitchWindowCardViewModel) -> String? {
+        guard let appOrdinal = appShelfItems.firstIndex(where: { $0.item.appGroupIndex == card.appGroupIndex }),
+              let appSymbol = singleIndexSymbol(forOrdinal: appOrdinal),
+              let windowSymbol = singleIndexSymbol(forOrdinal: card.windowIndex)
+        else {
+            return nil
+        }
+        return "\(appSymbol)\(windowSymbol)"
+    }
+
+    private func singleIndexSymbol(forOrdinal ordinal: Int) -> String? {
+        guard ordinal >= 0,
+              ordinal < Self.appShelfIndexSymbols.count
+        else {
+            return nil
+        }
+        return Self.appShelfIndexSymbols[ordinal]
     }
 
     private func waterfallStateText(for card: QuickSwitchWindowCardViewModel) -> String {
@@ -5202,7 +6354,7 @@
     }
 
     private var spaceLaneOccupiedColor: NSColor {
-        if effectiveAppearance.bestMatch(from: [.darkAqua, .aqua]) == .darkAqua {
+        if resolvedTheme == .dark {
             return NSColor(calibratedRed: 10 / 255, green: 132 / 255, blue: 1, alpha: 1)
         }
 
@@ -5210,7 +6362,7 @@
     }
 
     private var spaceLaneLockedFillColor: NSColor {
-        if effectiveAppearance.bestMatch(from: [.darkAqua, .aqua]) == .darkAqua {
+        if resolvedTheme == .dark {
             return NSColor(calibratedRed: 58 / 255, green: 148 / 255, blue: 1, alpha: 0.86)
         }
 
@@ -5218,9 +6370,9 @@
     }
 
     private func spaceLaneIdleOccupiedGradientColors() -> [NSColor] {
-        if effectiveAppearance.bestMatch(from: [.darkAqua, .aqua]) == .darkAqua {
-            let blue = NSColor(calibratedRed: 36 / 255, green: 54 / 255, blue: 72 / 255, alpha: 1)
-            let surface = NSColor.windowBackgroundColor.withAlphaComponent(1)
+        if resolvedTheme == .dark {
+            let blue = NSColor(calibratedRed: 18 / 255, green: 42 / 255, blue: 70 / 255, alpha: 0.92)
+            let surface = NSColor(calibratedRed: 22 / 255, green: 34 / 255, blue: 50 / 255, alpha: 0.78)
             return [blue, surface]
         }
 
@@ -5233,7 +6385,7 @@
     private func applySpaceLaneGradientFill(to layer: CALayer, colors: [NSColor]) {
         if let gradientLayer = layer as? CAGradientLayer {
             gradientLayer.colors = colors.map(\.cgColor)
-            gradientLayer.locations = [0, 1]
+            gradientLayer.locations = [0, 1].map(NSNumber.init(value:))
             gradientLayer.startPoint = CGPoint(x: 0.5, y: 1.0)
             gradientLayer.endPoint = CGPoint(x: 0.5, y: 0.0)
         }
@@ -5703,11 +6855,13 @@
                 "titleIsEmpty": card.item.window.title.isEmpty,
                 "primarySpaceID": card.item.primarySpaceID ?? NSNull(),
                 "primarySpaceLabel": card.item.primarySpaceLabel ?? NSNull(),
+                "windowShortcutCode": waterfallMetaText(for: card.item),
                 "isMinimized": card.item.window.isMinimized,
                 "isFullscreen": card.item.window.isFullscreen,
                 "identifierSource": "\(card.item.window.identifierSource)",
                 "isSelected": card.item.window.id == effectiveSelection?.windowID,
                 "isKeyboardFocused": card.item.window.id == keyboardFocusedWindowID,
+                "isHorizontalAppDefault": isHorizontalAppDefaultCard(card),
                 "visualStates": waterfallCardVisualStates(for: card),
                 "thumbnailStrategy": thumbnailStrategyString(for: card.item.window),
                 "screenshotSource": screenshotSourceString(screenshotSource, for: card.item.window),
@@ -5732,6 +6886,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"
@@ -5827,14 +6982,20 @@
         let isSelected = card.item.window.id == effectiveSelection?.windowID
         let isHovered = card.item.window.id == hoveredWindowID
         let isKeyboardFocused = card.item.window.id == keyboardFocusedWindowID
+        let isHorizontalAppDefaultFocused = isHorizontalAppDefaultCard(card)
         let isAppLinked = isWaterfallCardAppLinked(card)
-        if shouldShowSelectedVisual(isSelected: isSelected, isHovered: isHovered) || isKeyboardFocused {
+        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")
@@ -5892,6 +7053,10 @@
                 }
                 let isAppAssociated = appHoverAssociatedSpaceIDs.contains(space.id)
                 let isWindowAssociated = space.id == windowHoverAssociatedSpaceID
+                let isLocked = space.id == currentViewModel?.lockedSpaceID
+                let isActive = space.id == activeSpaceFocusID || isLocked
+                let isAssociated = (isAppAssociated || isWindowAssociated) && !isActive
+                let usesLightActiveFill = resolvedTheme == .dark && space.windowCount > 0 && !isLocked && (isActive || isAssociated)
                 let group = spaceLaneDisplayGroup(containingSpaceID: space.id)
                 let visibleFrame = segment.containerLayer.frame.offsetBy(
                     dx: (group?.containerLayer.frame.minX ?? 0) + spaceLaneContentLayer.frame.minX,
@@ -5910,6 +7075,8 @@
                     "label": space.label,
                     "type": spaceTypeName(space.type),
                     "visualStates": visualStates(for: space),
+                    "usesLightActiveFill": usesLightActiveFill,
+                    "foregroundContrastStyle": usesLightActiveFill ? "darkOnLight" : "themeDefault",
                     "fullscreenMarkerVisible": segment.fullscreenMarkerLayer != nil,
                     "fullscreenMarkerKind": fullscreenMarkerKind(
                         markerLayer: segment.fullscreenMarkerLayer,
@@ -6070,6 +7237,20 @@
         }
     }
 
+    private var darkBackdropLayerCount: Int {
+        darkBackdropAmbientLayers.count + 1
+    }
+
+    private var darkBackdropLayersVisible: Bool {
+        resolvedTheme == .dark
+            && darkBackdropAmbientLayers.allSatisfy { !$0.isHidden }
+            && !darkVignetteLayer.isHidden
+    }
+
+    private func backgroundGradientColorReports() -> [[String: Double]] {
+        gradientColorDictionaries(from: backgroundLayer)
+    }
+
     private func spaceLaneFillKind(for layer: CALayer) -> String {
         if !gradientColorDictionaries(from: layer).isEmpty {
             return "gradient"

--
Gitblit v1.9.3