docs: update results map QA evidence

Ariver

2026-06-29 1d03f5b6b433b062a098bf7899a349d550aafac7

 C1.source/Sources/Aligner/QuickSwitchRootView.swift

@@ -58,6 +58,7 @@
    private var appShelfContentWidth: CGFloat = 0
    private var appShelfScrollOffset: CGFloat = 0
    private var appShelfTrackingArea: NSTrackingArea?
    private var lastKnownMouseWindowLocation: CGPoint?
    private var hoveredAppGroupIndex: Int?
    private var hoveredWindowID: UInt32?
    private var hoveredSpaceID: UInt64?
@@ -416,6 +417,27 @@
        static let compressedIndexFontSize: CGFloat = 14
        static let indexWidth: CGFloat = 18
        static let indexHeight: CGFloat = 24
        static let magneticFirstNeighborInfluence: CGFloat = 0
        static let magneticSecondNeighborInfluence: CGFloat = 0
        static let magneticHoverLift: CGFloat = 4
        static let magneticFirstNeighborLift: CGFloat = 0
        static let magneticSecondNeighborLift: CGFloat = 0
        static let magneticAnimationDuration: CFTimeInterval = 0.16
        static let magneticAnimationTimingName = CAMediaTimingFunctionName.easeOut
        static let closeButtonHitOutset: CGFloat = 0
    }

    private struct AppShelfMagneticState {
        let influence: CGFloat
        let lift: CGFloat

        var isActive: Bool {
            influence > 0
        }

        var isNeighbor: Bool {
            influence > 0 && influence < 1
        }
    }

    private enum RootLayoutMetrics {
@@ -737,6 +759,7 @@

    override func mouseMoved(with event: NSEvent) {
        guard debugHoveredAppGroupIndex == nil else { return }
        lastKnownMouseWindowLocation = event.locationInWindow
        clearWindowIndexKeyPending()

        let toggleHovered = viewModeToggleButtonContains(windowLocation: event.locationInWindow)
@@ -773,6 +796,7 @@

    override func mouseExited(with event: NSEvent) {
        guard debugHoveredAppGroupIndex == nil else { return }
        lastKnownMouseWindowLocation = nil
        clearWindowIndexKeyPending()
        isViewModeToggleButtonHovered = false
        suppressViewModeToggleHoverPreview = false
@@ -791,51 +815,75 @@
            ])
            return
        }

        if handleMouseDown(at: event.locationInWindow, clickCount: max(1, event.clickCount), allowBackgroundClick: true) {
            return
        }

        super.mouseDown(with: event)
    }

    @discardableResult
    private func handleMouseDown(at windowLocation: CGPoint, clickCount: Int, allowBackgroundClick: Bool) -> Bool {
        clearWindowIndexKeyPending()

        if handleCloseConfirmationMouseDown(at: event.locationInWindow) {
            return
        if handleCloseConfirmationMouseDown(at: windowLocation) {
            return true
        }

        if viewModeToggleButtonContains(windowLocation: event.locationInWindow) {
        if viewModeToggleButtonContains(windowLocation: windowLocation) {
            clickViewModeToggleButton(source: "mouse")
            return
            return true
        }

        if themeToggleButtonContains(windowLocation: event.locationInWindow) {
        if themeToggleButtonContains(windowLocation: windowLocation) {
            clickThemeToggleButton(source: "mouse")
            return
            return true
        }

        if let closeTarget = closeButtonTarget(at: event.locationInWindow) {
        if let closeTarget = waterfallCloseButtonTarget(at: windowLocation) {
            beginCloseConfirmation(for: closeTarget)
            return
            return true
        }

        if let card = waterfallCard(at: event.locationInWindow) {
        if let card = waterfallCard(at: windowLocation) {
            clickWindowCard(card)
            return
            return true
        }

        if let segment = spaceLaneSegment(at: event.locationInWindow) {
            clickSpaceLaneSegment(segment, clickCount: max(1, event.clickCount))
            return
        if let segment = spaceLaneSegment(at: windowLocation) {
            clickSpaceLaneSegment(segment, clickCount: max(1, clickCount))
            return true
        }

        if let item = appShelfItem(at: event.locationInWindow) {
        if let item = appShelfIconItem(at: windowLocation) {
            if let closeTarget = appShelfCloseButtonTarget(at: windowLocation) {
                beginCloseConfirmation(for: closeTarget)
            } else {
                clickAppShelfItem(item)
            }
            return true
        }

        if let closeTarget = closeButtonTarget(at: windowLocation) {
            beginCloseConfirmation(for: closeTarget)
            return true
        }

        if let item = appShelfItem(at: windowLocation) {
            clickAppShelfItem(item)
            return
            return true
        }

        DevelopmentDiagnostics.log("quickSwitch.view.mouseDown.miss", [
            "x": event.locationInWindow.x,
            "y": event.locationInWindow.y,
            "x": windowLocation.x,
            "y": windowLocation.y,
            "bounds": NSStringFromRect(bounds)
        ])
        if !suppressEventBackgroundClicks, onBackgroundClick?() == true {
            return
        if allowBackgroundClick, !suppressEventBackgroundClicks, onBackgroundClick?() == true {
            return true
        }
        super.mouseDown(with: event)
        return false
    }

    func setDebugHoveredAppGroupIndex(_ index: Int?) {
@@ -1176,6 +1224,7 @@

        needsLayout = true
        ensureCurrentSelectionVisible(horizontalIntent: .alignWithAppShelf(animated: false))
        refreshHoverTargetAfterViewRebuild()
        needsLayout = true
        if animatedProjection, let transitionSnapshot {
            layoutSubtreeIfNeeded()
@@ -1538,6 +1587,14 @@
            "appShelfHoverIconSize": Double(AppShelfMetrics.hoverIconSize),
            "appShelfSelectedIconSize": Double(AppShelfMetrics.selectedIconSize),
            "appShelfMinIconSize": Double(AppShelfMetrics.minIconSize),
            "appShelfMagneticHoverEnabled": appShelfMagneticHoverEnabled,
            "appShelfMagneticFirstNeighborInfluence": Double(AppShelfMetrics.magneticFirstNeighborInfluence),
            "appShelfMagneticSecondNeighborInfluence": Double(AppShelfMetrics.magneticSecondNeighborInfluence),
            "appShelfMagneticHoverLift": Double(AppShelfMetrics.magneticHoverLift),
            "appShelfMagneticFirstNeighborLift": Double(AppShelfMetrics.magneticFirstNeighborLift),
            "appShelfMagneticSecondNeighborLift": Double(AppShelfMetrics.magneticSecondNeighborLift),
            "appShelfMagneticAnimationDurationMilliseconds": Double(AppShelfMetrics.magneticAnimationDuration * 1_000),
            "appShelfMagneticAnimationTimingName": AppShelfMetrics.magneticAnimationTimingName.rawValue,
            "appShelfItems": appShelfItemReports(),
            "waterfallFrame": dictionary(from: waterfallLayer.frame),
            "waterfallViewMode": waterfallViewMode.rawValue,
@@ -2147,6 +2204,11 @@
            }
            recordMouseCommand("hover-app:\(appGroupIndex)")
            hoverAppGroup(appGroupIndex)
        case "reapply-view-model":
            if let currentViewModel {
                apply(viewModel: currentViewModel)
            }
            recordMouseCommand("reapply-view-model")
        case "click-app" where parts.count == 2:
            guard let appGroupIndex = Int(parts[1]) else {
                recordMouseCommand("invalid:\(command)")
@@ -2154,6 +2216,20 @@
            }
            recordMouseCommand("click-app:\(appGroupIndex)")
            clickAppShelfItem(appGroupIndex: appGroupIndex)
        case "click-app-center" where parts.count == 2:
            guard let appGroupIndex = Int(parts[1]) else {
                recordMouseCommand("invalid:\(command)")
                return
            }
            recordMouseCommand("click-app-center:\(appGroupIndex)")
            clickAppShelfItemViaMouse(appGroupIndex: appGroupIndex, probe: .iconCenter)
        case "click-app-near-close" where parts.count == 2:
            guard let appGroupIndex = Int(parts[1]) else {
                recordMouseCommand("invalid:\(command)")
                return
            }
            recordMouseCommand("click-app-near-close:\(appGroupIndex)")
            clickAppShelfItemViaMouse(appGroupIndex: appGroupIndex, probe: .nearCloseOutsideHit)
        case "hover-app-close" where parts.count == 2:
            guard let appGroupIndex = Int(parts[1]) else {
                recordMouseCommand("invalid:\(command)")
@@ -2294,6 +2370,7 @@
    }

    private func hoverAppGroup(_ appGroupIndex: Int, source: HoverTargetSource = .debug) {
        lastKnownMouseWindowLocation = appShelfItemCenterWindowLocation(for: appGroupIndex)
        updateHoverState(
            appGroupIndex: appGroupIndex,
            windowID: nil,
@@ -2416,6 +2493,64 @@
        }
    }

    private enum AppShelfMouseClickProbe {
        case iconCenter
        case nearCloseOutsideHit
    }

    private func clickAppShelfItemViaMouse(appGroupIndex: Int, probe: AppShelfMouseClickProbe) {
        guard let windowLocation = appShelfSyntheticMouseDownLocation(for: appGroupIndex, probe: probe) else {
            DevelopmentDiagnostics.log("quickSwitch.view.clickAppShelfViaMouse.missingLocation", [
                "appGroupIndex": appGroupIndex
            ])
            return
        }
        _ = handleMouseDown(at: windowLocation, clickCount: 1, allowBackgroundClick: false)
    }

    private func appShelfSyntheticMouseDownLocation(
        for appGroupIndex: Int,
        probe: AppShelfMouseClickProbe
    ) -> CGPoint? {
        layoutSubtreeIfNeeded()
        guard let item = appShelfItems.first(where: { $0.item.appGroupIndex == appGroupIndex }) else {
            return nil
        }

        let iconFrame = item.iconLayer.frame
        let closeFrame = item.closeButton.containerLayer.frame
        let pointInItem: CGPoint
        switch probe {
        case .iconCenter:
            pointInItem = CGPoint(x: iconFrame.midX, y: iconFrame.midY)
        case .nearCloseOutsideHit:
            let fallbackPoint = CGPoint(
                x: iconFrame.maxX - 4,
                y: iconFrame.maxY - 14
            )
            if closeFrame.width > 0, closeFrame.height > 0 {
                let candidate = CGPoint(x: closeFrame.minX - 4, y: closeFrame.midY)
                pointInItem = iconFrame.contains(candidate) ? candidate : fallbackPoint
            } else {
                pointInItem = fallbackPoint
            }
        }

        let pointInView = CGPoint(
            x: glassLayer.frame.minX
                + shelfLayer.frame.minX
                + appShelfContentLayer.frame.minX
                + item.containerLayer.frame.minX
                + pointInItem.x,
            y: glassLayer.frame.minY
                + shelfLayer.frame.minY
                + appShelfContentLayer.frame.minY
                + item.containerLayer.frame.minY
                + pointInItem.y
        )
        return convert(pointInView, to: nil)
    }

    private func scrollAppShelf(to targetOffset: CGFloat) {
        layoutSubtreeIfNeeded()
        let previousOffset = appShelfScrollOffset
@@ -2536,8 +2671,26 @@

    private func refreshHoverTarget(at windowLocation: CGPoint) {
        guard debugHoveredAppGroupIndex == nil else { return }
        lastKnownMouseWindowLocation = windowLocation
        let target = resolveHoverTarget(at: windowLocation)
        setHoverTarget(target, alignsWaterfallWithAppShelf: target.shouldAlignWaterfallWithAppShelf)
    }

    private func refreshHoverTargetAfterViewRebuild() {
        guard debugHoveredAppGroupIndex == nil, currentViewModel != nil else { return }

        layoutSubtreeIfNeeded()
        let windowLocation = lastKnownMouseWindowLocation ?? window?.mouseLocationOutsideOfEventStream
        guard let windowLocation else { return }

        let locationInView = convert(windowLocation, from: nil)
        guard bounds.contains(locationInView) else {
            lastKnownMouseWindowLocation = nil
            setHoverTarget(.none)
            return
        }

        refreshHoverTarget(at: windowLocation)
    }

    private func resolveHoverTarget(at windowLocation: CGPoint) -> HoverTarget {
@@ -4717,42 +4870,90 @@
    }

    private func appShelfItem(at windowLocation: CGPoint) -> AppShelfItemLayers? {
        let locationInView = convert(windowLocation, from: nil)
        let locationInShelfContent = CGPoint(
            x: locationInView.x - glassLayer.frame.minX - shelfLayer.frame.minX - appShelfContentLayer.frame.minX,
            y: locationInView.y - glassLayer.frame.minY - shelfLayer.frame.minY - appShelfContentLayer.frame.minY
        )
        let locationInShelfContent = appShelfContentLocation(at: windowLocation)

        return appShelfItems.first { item in
            item.containerLayer.frame.contains(locationInShelfContent)
            interactiveFrame(for: item.containerLayer).contains(locationInShelfContent)
        }
    }

    private func appShelfIconItem(at windowLocation: CGPoint) -> AppShelfItemLayers? {
        let locationInAppShelfContent = appShelfContentLocation(at: windowLocation)

        return appShelfItems.first { item in
            let itemFrame = interactiveFrame(for: item.containerLayer)
            let locationInItem = CGPoint(
                x: locationInAppShelfContent.x - itemFrame.minX,
                y: locationInAppShelfContent.y - itemFrame.minY
            )
            return interactiveFrame(for: item.iconLayer).contains(locationInItem)
        }
    }

    private func appShelfContentLocation(at windowLocation: CGPoint) -> CGPoint {
        let locationInView = convert(windowLocation, from: nil)
        let glassFrame = interactiveFrame(for: glassLayer)
        let shelfFrame = interactiveFrame(for: shelfLayer)
        let appShelfContentFrame = interactiveFrame(for: appShelfContentLayer)

        return CGPoint(
            x: locationInView.x - glassFrame.minX - shelfFrame.minX - appShelfContentFrame.minX,
            y: locationInView.y - glassFrame.minY - shelfFrame.minY - appShelfContentFrame.minY
        )
    }

    private func appShelfItemCenterWindowLocation(for appGroupIndex: Int) -> CGPoint? {
        guard let item = appShelfItems.first(where: { $0.item.appGroupIndex == appGroupIndex }) else {
            return nil
        }

        let pointInView = CGPoint(
            x: glassLayer.frame.minX
                + shelfLayer.frame.minX
                + appShelfContentLayer.frame.minX
                + item.containerLayer.frame.midX,
            y: glassLayer.frame.minY
                + shelfLayer.frame.minY
                + appShelfContentLayer.frame.minY
                + item.containerLayer.frame.midY
        )
        return convert(pointInView, to: nil)
    }

    private func waterfallCard(at windowLocation: CGPoint) -> WaterfallCardLayers? {
        let locationInView = convert(windowLocation, from: nil)
        let glassFrame = interactiveFrame(for: glassLayer)
        let waterfallFrame = interactiveFrame(for: waterfallLayer)
        let waterfallContentFrame = interactiveFrame(for: waterfallContentLayer)
        let locationInWaterfallContent = CGPoint(
            x: locationInView.x - glassLayer.frame.minX - waterfallLayer.frame.minX - waterfallContentLayer.frame.minX,
            y: locationInView.y - glassLayer.frame.minY - waterfallLayer.frame.minY - waterfallContentLayer.frame.minY
            x: locationInView.x - glassFrame.minX - waterfallFrame.minX - waterfallContentFrame.minX,
            y: locationInView.y - glassFrame.minY - waterfallFrame.minY - waterfallContentFrame.minY
        )

        for column in waterfallColumns where column.containerLayer.frame.contains(locationInWaterfallContent) {
        for column in waterfallColumns where interactiveFrame(for: column.containerLayer).contains(locationInWaterfallContent) {
            let columnFrame = interactiveFrame(for: column.containerLayer)
            let cardsClipFrame = interactiveFrame(for: column.cardsClipLayer)
            let locationInColumn = CGPoint(
                x: locationInWaterfallContent.x - column.containerLayer.frame.minX,
                y: locationInWaterfallContent.y - column.containerLayer.frame.minY
                x: locationInWaterfallContent.x - columnFrame.minX,
                y: locationInWaterfallContent.y - columnFrame.minY
            )
            guard column.cardsClipLayer.frame.contains(locationInColumn) else {
            guard cardsClipFrame.contains(locationInColumn) else {
                continue
            }
            let locationInCardsClip = CGPoint(
                x: locationInColumn.x - column.cardsClipLayer.frame.minX,
                y: locationInColumn.y - column.cardsClipLayer.frame.minY
                x: locationInColumn.x - cardsClipFrame.minX,
                y: locationInColumn.y - cardsClipFrame.minY
            )
            if let card = column.cards.first(where: { $0.containerLayer.frame.contains(locationInCardsClip) }) {
            if let card = column.cards.first(where: { interactiveFrame(for: $0.containerLayer).contains(locationInCardsClip) }) {
                return card
            }
        }

        return nil
    }

    private func interactiveFrame(for layer: CALayer) -> CGRect {
        layer.presentation()?.frame ?? layer.frame
    }

    private func waterfallCard(appGroupIndex: Int, windowIndex: Int) -> WaterfallCardLayers? {
@@ -4889,50 +5090,69 @@
        let isHovered = item.item.appGroupIndex == effectiveHoveredAppGroupIndex
        let showsSelectedVisual = shouldShowSelectedVisual(isSelected: isSelected, isHovered: isHovered)
        let isSpaceFocused = spaceFocusWindowCount(for: item.item.appGroupIndex) > 0
        let magneticState = appShelfMagneticState(for: item)
        let visualIconSize = appShelfVisualIconSize(
            forBaseIconSize: iconSize,
            selected: showsSelectedVisual,
            hovered: isHovered,
            spaceFocused: isSpaceFocused
            spaceFocused: isSpaceFocused,
            magneticState: magneticState
        )
        let backgroundPadding: CGFloat = (showsSelectedVisual || isHovered)
            ? 4
            : isSpaceFocused
                ? 6
                : 2
        let backgroundPadding: CGFloat = isSpaceFocused ? 6 : 2
        let iconX = (bounds.width - visualIconSize) / 2
        let iconY = bounds.height - visualIconSize - 2
        let iconY = bounds.height - visualIconSize - 2 + magneticState.lift
        let badgeText = appShelfBadgeText(for: item)
        let badgeWidth = max(18, CGFloat(badgeText.count) * 7 + 8)

        let previousBackgroundFrame = item.backgroundLayer.presentation()?.frame ?? item.backgroundLayer.frame
        let previousIconFrame = item.iconLayer.presentation()?.frame ?? item.iconLayer.frame
        let previousIndexFrame = item.indexLayer.presentation()?.frame ?? item.indexLayer.frame
        let previousBadgeFrame = item.badgeLayer.presentation()?.frame ?? item.badgeLayer.frame
        let previousCloseFrame = item.closeButton.containerLayer.presentation()?.frame
            ?? item.closeButton.containerLayer.frame

        item.containerLayer.zPosition = appShelfZPosition(
            selected: showsSelectedVisual,
            hovered: isHovered,
            spaceFocused: isSpaceFocused
            spaceFocused: isSpaceFocused,
            magneticState: magneticState
        )
        item.backgroundLayer.backgroundColor = appShelfBackgroundColor(
            selected: showsSelectedVisual,
            hovered: isHovered,
            spaceFocused: isSpaceFocused
            spaceFocused: isSpaceFocused,
            magneticState: magneticState
        ).cgColor
        item.backgroundLayer.borderColor = (showsSelectedVisual
            ? NSColor.controlAccentColor.withAlphaComponent(0.40)
            : isHovered
                ? NSColor.controlAccentColor.withAlphaComponent(0.36)
                : NSColor.clear
        ).cgColor
        item.backgroundLayer.borderWidth = (showsSelectedVisual || isHovered) ? 1 : 0
        item.backgroundLayer.borderColor = NSColor.clear.cgColor
        item.backgroundLayer.borderWidth = 0
        item.containerLayer.borderColor = NSColor.clear.cgColor
        item.containerLayer.borderWidth = 0
        item.iconLayer.borderColor = NSColor.clear.cgColor
        item.iconLayer.borderWidth = 0
        item.backgroundLayer.shadowColor = NSColor.black.cgColor
        item.backgroundLayer.shadowOpacity = showsSelectedVisual ? 0.11 : isHovered ? 0.07 : isSpaceFocused ? 0.18 : 0
        item.backgroundLayer.shadowRadius = showsSelectedVisual ? 10 : isHovered ? 8 : isSpaceFocused ? 18 : 0
        item.backgroundLayer.shadowOffset = CGSize(width: 0, height: isSpaceFocused ? -4 : -2)
        item.backgroundLayer.shadowOpacity = appShelfShadowOpacity(
            selected: showsSelectedVisual,
            hovered: isHovered,
            spaceFocused: isSpaceFocused,
            magneticState: magneticState
        )
        item.backgroundLayer.shadowRadius = appShelfShadowRadius(
            selected: showsSelectedVisual,
            hovered: isHovered,
            spaceFocused: isSpaceFocused,
            magneticState: magneticState
        )
        item.backgroundLayer.shadowOffset = CGSize(
            width: 0,
            height: isSpaceFocused ? -4 : magneticState.isNeighbor ? -1 : -2
        )
        item.backgroundLayer.frame = CGRect(
            x: iconX - backgroundPadding,
            y: iconY - backgroundPadding,
            width: visualIconSize + backgroundPadding * 2,
            height: visualIconSize + backgroundPadding * 2
        )
        item.backgroundLayer.shadowPath = (showsSelectedVisual || isHovered || isSpaceFocused)
        item.backgroundLayer.shadowPath = isSpaceFocused
            ? CGPath(
                roundedRect: item.backgroundLayer.bounds,
                cornerWidth: item.backgroundLayer.cornerRadius,
@@ -4974,6 +5194,12 @@
        )
        item.selectedIndicatorLayer.frame = .zero
        item.selectedIndicatorLayer.backgroundColor = NSColor.clear.cgColor

        animateAppShelfLayerFrame(item.backgroundLayer, from: previousBackgroundFrame)
        animateAppShelfLayerFrame(item.iconLayer, from: previousIconFrame)
        animateAppShelfLayerFrame(item.indexLayer, from: previousIndexFrame)
        animateAppShelfLayerFrame(item.badgeLayer, from: previousBadgeFrame)
        animateAppShelfLayerFrame(item.closeButton.containerLayer, from: previousCloseFrame)
    }

    private var appShelfIndexColor: NSColor {
@@ -5056,6 +5282,75 @@

    private var effectiveHoveredAppGroupIndex: Int? {
        debugHoveredAppGroupIndex ?? hoveredAppGroupIndex
    }

    private var appShelfMagneticHoverEnabled: Bool {
        !NSWorkspace.shared.accessibilityDisplayShouldReduceMotion
    }

    private func appShelfMagneticState(for item: AppShelfItemLayers) -> AppShelfMagneticState {
        guard appShelfMagneticHoverEnabled,
              let hoveredAppGroupIndex = effectiveHoveredAppGroupIndex,
              item.item.appGroupIndex == hoveredAppGroupIndex
        else {
            return AppShelfMagneticState(influence: 0, lift: 0)
        }

        return AppShelfMagneticState(
            influence: 1,
            lift: AppShelfMetrics.magneticHoverLift
        )
    }

    private func animateAppShelfLayerFrame(_ layer: CALayer, from previousFrame: CGRect) {
        guard appShelfMagneticHoverEnabled,
              previousFrame.width > 0,
              previousFrame.height > 0,
              appShelfFrameIsFinite(previousFrame),
              appShelfFrameIsFinite(layer.frame)
        else {
            layer.removeAnimation(forKey: "appShelfMagneticPosition")
            layer.removeAnimation(forKey: "appShelfMagneticBounds")
            return
        }

        let previousPosition = CGPoint(x: previousFrame.midX, y: previousFrame.midY)
        let previousBounds = CGRect(origin: .zero, size: previousFrame.size)
        let nextPosition = layer.position
        let nextBounds = layer.bounds
        let moved = abs(previousPosition.x - nextPosition.x) > 0.25
            || abs(previousPosition.y - nextPosition.y) > 0.25
        let resized = abs(previousBounds.width - nextBounds.width) > 0.25
            || abs(previousBounds.height - nextBounds.height) > 0.25

        guard moved || resized else { return }

        let timing = CAMediaTimingFunction(name: AppShelfMetrics.magneticAnimationTimingName)
        if moved {
            let animation = CABasicAnimation(keyPath: "position")
            animation.fromValue = previousPosition
            animation.toValue = nextPosition
            animation.duration = AppShelfMetrics.magneticAnimationDuration
            animation.timingFunction = timing
            animation.isRemovedOnCompletion = true
            layer.add(animation, forKey: "appShelfMagneticPosition")
        }
        if resized {
            let animation = CABasicAnimation(keyPath: "bounds")
            animation.fromValue = previousBounds
            animation.toValue = nextBounds
            animation.duration = AppShelfMetrics.magneticAnimationDuration
            animation.timingFunction = timing
            animation.isRemovedOnCompletion = true
            layer.add(animation, forKey: "appShelfMagneticBounds")
        }
    }

    private func appShelfFrameIsFinite(_ frame: CGRect) -> Bool {
        frame.origin.x.isFinite
            && frame.origin.y.isFinite
            && frame.size.width.isFinite
            && frame.size.height.isFinite
    }

    private var activeSpaceFocusID: UInt64? {
@@ -5178,7 +5473,8 @@
        forBaseIconSize iconSize: CGFloat,
        selected: Bool,
        hovered: Bool,
        spaceFocused: Bool
        spaceFocused: Bool,
        magneticState: AppShelfMagneticState
    ) -> CGFloat {
        if selected || hovered {
            return AppShelfMetrics.selectedIconSize
@@ -5186,10 +5482,19 @@
        if spaceFocused {
            return min(AppShelfMetrics.selectedIconSize, iconSize + 8)
        }
        return iconSize
        guard magneticState.isNeighbor else {
            return iconSize
        }
        let growth = AppShelfMetrics.hoverIconSize - iconSize
        return iconSize + growth * magneticState.influence
    }

    private func appShelfZPosition(selected: Bool, hovered: Bool, spaceFocused: Bool) -> CGFloat {
    private func appShelfZPosition(
        selected: Bool,
        hovered: Bool,
        spaceFocused: Bool,
        magneticState: AppShelfMagneticState
    ) -> CGFloat {
        switch (selected, hovered, spaceFocused) {
        case (true, true, _):
            return 30
@@ -5200,21 +5505,44 @@
        case (false, false, true):
            return 12
        case (false, false, false):
            return 0
            return magneticState.isNeighbor ? 6 + magneticState.influence : 0
        }
    }

    private func appShelfBackgroundColor(selected: Bool, hovered: Bool, spaceFocused: Bool) -> NSColor {
        if selected {
            return themePalette.appShelfBackgroundSelected
        }
        if hovered {
            return themePalette.appShelfBackgroundHovered
        }
    private func appShelfBackgroundColor(
        selected: Bool,
        hovered: Bool,
        spaceFocused: Bool,
        magneticState: AppShelfMagneticState
    ) -> NSColor {
        if spaceFocused {
            return themePalette.appShelfBackgroundSpaceFocused
        }
        return .clear
    }

    private func appShelfShadowOpacity(
        selected: Bool,
        hovered: Bool,
        spaceFocused: Bool,
        magneticState: AppShelfMagneticState
    ) -> Float {
        if spaceFocused {
            return 0.18
        }
        return 0
    }

    private func appShelfShadowRadius(
        selected: Bool,
        hovered: Bool,
        spaceFocused: Bool,
        magneticState: AppShelfMagneticState
    ) -> CGFloat {
        if spaceFocused {
            return 18
        }
        return 0
    }

    private func appShelfBadgeText(for item: AppShelfItemLayers) -> String {
@@ -6133,11 +6461,7 @@
    }

    private func appShelfCloseButtonTarget(at windowLocation: NSPoint) -> CloseTarget? {
        let locationInView = convert(windowLocation, from: nil)
        let locationInAppShelfContent = CGPoint(
            x: locationInView.x - glassLayer.frame.minX - shelfLayer.frame.minX - appShelfContentLayer.frame.minX,
            y: locationInView.y - glassLayer.frame.minY - shelfLayer.frame.minY - appShelfContentLayer.frame.minY
        )
        let locationInAppShelfContent = appShelfContentLocation(at: windowLocation)

        for item in appShelfItems {
            let target = CloseTarget.app(appGroupIndex: item.item.appGroupIndex)
@@ -6145,43 +6469,59 @@
                  canClose(app: item.item.app)
            else { continue }

            let itemFrame = interactiveFrame(for: item.containerLayer)
            let closeFrame = interactiveFrame(for: item.closeButton.containerLayer)
            let locationInItem = CGPoint(
                x: locationInAppShelfContent.x - item.containerLayer.frame.minX,
                y: locationInAppShelfContent.y - item.containerLayer.frame.minY
                x: locationInAppShelfContent.x - itemFrame.minX,
                y: locationInAppShelfContent.y - itemFrame.minY
            )
            if item.closeButton.containerLayer.frame.insetBy(dx: -8, dy: -8).contains(locationInItem) {
            if appShelfCloseHitFrame(for: closeFrame).contains(locationInItem) {
                return target
            }
        }
        return nil
    }

    private func appShelfCloseHitFrame(for closeFrame: CGRect) -> CGRect {
        closeFrame.insetBy(
            dx: -AppShelfMetrics.closeButtonHitOutset,
            dy: -AppShelfMetrics.closeButtonHitOutset
        )
    }

    private func waterfallCloseButtonTarget(at windowLocation: NSPoint) -> CloseTarget? {
        let locationInView = convert(windowLocation, from: nil)
        let glassFrame = interactiveFrame(for: glassLayer)
        let waterfallFrame = interactiveFrame(for: waterfallLayer)
        let waterfallContentFrame = interactiveFrame(for: waterfallContentLayer)
        let locationInWaterfallContent = CGPoint(
            x: locationInView.x - glassLayer.frame.minX - waterfallLayer.frame.minX - waterfallContentLayer.frame.minX,
            y: locationInView.y - glassLayer.frame.minY - waterfallLayer.frame.minY - waterfallContentLayer.frame.minY
            x: locationInView.x - glassFrame.minX - waterfallFrame.minX - waterfallContentFrame.minX,
            y: locationInView.y - glassFrame.minY - waterfallFrame.minY - waterfallContentFrame.minY
        )

        for column in waterfallColumns where column.containerLayer.frame.contains(locationInWaterfallContent) {
        for column in waterfallColumns where interactiveFrame(for: column.containerLayer).contains(locationInWaterfallContent) {
            let columnFrame = interactiveFrame(for: column.containerLayer)
            let cardsClipFrame = interactiveFrame(for: column.cardsClipLayer)
            let locationInColumn = CGPoint(
                x: locationInWaterfallContent.x - column.containerLayer.frame.minX,
                y: locationInWaterfallContent.y - column.containerLayer.frame.minY
                x: locationInWaterfallContent.x - columnFrame.minX,
                y: locationInWaterfallContent.y - columnFrame.minY
            )
            guard column.cardsClipLayer.frame.contains(locationInColumn) else {
            guard cardsClipFrame.contains(locationInColumn) else {
                continue
            }
            let locationInCardsClip = CGPoint(
                x: locationInColumn.x - column.cardsClipLayer.frame.minX,
                y: locationInColumn.y - column.cardsClipLayer.frame.minY
                x: locationInColumn.x - cardsClipFrame.minX,
                y: locationInColumn.y - cardsClipFrame.minY
            )
            for card in column.cards where card.containerLayer.frame.contains(locationInCardsClip) {
            for card in column.cards where interactiveFrame(for: card.containerLayer).contains(locationInCardsClip) {
                guard card.closeButton.containerLayer.opacity > 0 else { continue }
                let cardFrame = interactiveFrame(for: card.containerLayer)
                let closeFrame = interactiveFrame(for: card.closeButton.containerLayer)
                let locationInCard = CGPoint(
                    x: locationInCardsClip.x - card.containerLayer.frame.minX,
                    y: locationInCardsClip.y - card.containerLayer.frame.minY
                    x: locationInCardsClip.x - cardFrame.minX,
                    y: locationInCardsClip.y - cardFrame.minY
                )
                if card.closeButton.containerLayer.frame.insetBy(dx: -8, dy: -8).contains(locationInCard) {
                if closeFrame.insetBy(dx: -8, dy: -8).contains(locationInCard) {
                    return .window(
                        appGroupIndex: card.item.appGroupIndex,
                        windowIndex: card.item.windowIndex,
@@ -6872,6 +7212,7 @@
    private func appShelfItemReports() -> [[String: Any]] {
        appShelfItems.enumerated().map { index, item in
            let visibleFrame = item.containerLayer.frame.offsetBy(dx: appShelfContentLayer.frame.minX, dy: 0)
            let magneticState = appShelfMagneticState(for: item)
            return [
                "index": index,
                "name": item.item.app.name,
@@ -6882,13 +7223,25 @@
                "isSelected": item.item.appGroupIndex == effectiveSelection?.appGroupIndex,
                "isHovered": item.item.appGroupIndex == effectiveHoveredAppGroupIndex,
                "isSpaceFocused": spaceFocusWindowCount(for: item.item.appGroupIndex) > 0,
                "isMagneticNeighbor": magneticState.isNeighbor,
                "magneticInfluence": Double(magneticState.influence),
                "magneticLift": Double(magneticState.lift),
                "visualStates": appShelfVisualStates(for: item),
                "zPosition": Double(item.containerLayer.zPosition),
                "hasMinimizedWindows": item.item.hasMinimizedWindows,
                "hasFullscreenWindows": item.item.hasFullscreenWindows,
                "frame": dictionary(from: item.containerLayer.frame),
                "visibleFrame": dictionary(from: visibleFrame),
                "containerBorderWidth": Double(item.containerLayer.borderWidth),
                "containerBorderColor": colorDictionary(from: item.containerLayer.borderColor),
                "iconFrame": dictionary(from: item.iconLayer.frame),
                "iconBorderWidth": Double(item.iconLayer.borderWidth),
                "iconBorderColor": colorDictionary(from: item.iconLayer.borderColor),
                "backgroundFrame": dictionary(from: item.backgroundLayer.frame),
                "backgroundColor": colorDictionary(from: item.backgroundLayer.backgroundColor),
                "backgroundBorderWidth": Double(item.backgroundLayer.borderWidth),
                "backgroundShadowOpacity": Double(item.backgroundLayer.shadowOpacity),
                "backgroundShadowRadius": Double(item.backgroundLayer.shadowRadius),
                "indexText": item.indexLayer.string ?? "",
                "indexFrame": dictionary(from: item.indexLayer.frame),
                "indexVisible": !item.indexLayer.isHidden && item.indexLayer.opacity > 0,
@@ -6901,6 +7254,7 @@
                "badgeText": item.badgeLayer.string ?? "",
                "closeButtonVisible": item.closeButton.containerLayer.opacity > 0,
                "closeButtonFrame": dictionary(from: item.closeButton.containerLayer.frame),
                "closeButtonHitFrame": dictionary(from: appShelfCloseHitFrame(for: item.closeButton.containerLayer.frame)),
                "closeButtonSize": Double(item.closeButton.containerLayer.bounds.width),
                "closeButtonFillColor": colorDictionary(from: item.closeButton.containerLayer.backgroundColor),
                "closeButtonGlyphColor": colorDictionary(from: item.closeButton.glyphLayer.strokeColor),
@@ -6913,6 +7267,7 @@
        var states: [String] = []
        let isSelected = item.item.appGroupIndex == effectiveSelection?.appGroupIndex
        let isHovered = item.item.appGroupIndex == effectiveHoveredAppGroupIndex
        let magneticState = appShelfMagneticState(for: item)
        if shouldShowSelectedVisual(isSelected: isSelected, isHovered: isHovered) {
            states.append("selected")
        } else if isSelected {
@@ -6921,6 +7276,9 @@
        if isHovered {
            states.append("hover")
        }
        if magneticState.isNeighbor {
            states.append("magneticNeighbor")
        }
        if spaceFocusWindowCount(for: item.item.appGroupIndex) > 0 {
            states.append("spaceFocused")
            let direction = spaceFocusDirection(for: item.item.appGroupIndex)