@lattices/cli 0.4.10 → 0.4.11

package/apps/mac/Sources/Core/Input/MouseGestureController.swift

@@ -0,0 +1,2259 @@
+import AppKit
+import Combine
+import CoreGraphics
+
+private enum MouseGestureAccessory {
+    case mic
+}
+
+private enum MouseGestureOverlayStyle: Equatable {
+    case drawing
+    case thinLine
+    case thickLine
+}
+
+private enum MouseGestureVisualPhase: String {
+    case started
+    case updated
+    case recognized
+    case completed
+}
+
+/// Captured CGEvent fields safe to ferry across an async dispatch boundary.
+/// CGEvent itself is reference-counted; the tap callback only borrows the
+/// event for the duration of its return, so we copy what we need into a
+/// value type before hopping to main.
+private struct MouseEventSnapshot {
+    let location: CGPoint
+    let flags: CGEventFlags
+    let buttonNumber: Int64
+}
+
+private struct MouseGestureOverlayTheme {
+    let graphite: NSColor
+    let graphiteDark: NSColor
+    let accent: NSColor
+    let highlight: NSColor
+    let failure: NSColor
+
+    static let graffiti = MouseGestureOverlayTheme(
+        graphite: NSColor(calibratedRed: 0.66, green: 0.69, blue: 0.73, alpha: 1.0),
+        graphiteDark: NSColor(calibratedRed: 0.16, green: 0.17, blue: 0.19, alpha: 1.0),
+        accent: NSColor(calibratedRed: 0.34, green: 0.78, blue: 1.0, alpha: 1.0),
+        highlight: NSColor(calibratedRed: 0.82, green: 0.94, blue: 1.0, alpha: 1.0),
+        failure: NSColor(calibratedRed: 0.98, green: 0.52, blue: 0.42, alpha: 1.0)
+    )
+}
+
+final class MouseGestureController: ObservableObject {
+    static let shared = MouseGestureController()
+
+    /// Live state of the event-tap circuit breaker. SettingsView observes
+    /// this to surface "paused" / "disabled" status and a re-arm button.
+    @Published private(set) var breakerState: EventTapBreaker.State = .armed
+
+    private struct GestureOutcome {
+        let label: String
+        let success: Bool
+        let accessory: MouseGestureAccessory?
+    }
+
+    private final class GestureSession {
+        let buttonNumber: Int64
+        let startPoint: CGPoint
+        let overlay: MouseGestureOverlay
+        var currentPoint: CGPoint
+        var lockedDirection: MouseGestureDirection?
+        var pathPoints: [GesturePathPoint]
+        var visual: MouseShortcutVisualDefinition?
+
+        init(buttonNumber: Int64, startPoint: CGPoint, overlay: MouseGestureOverlay) {
+            self.buttonNumber = buttonNumber
+            self.startPoint = startPoint
+            self.overlay = overlay
+            self.currentPoint = startPoint
+            self.lockedDirection = nil
+            self.pathPoints = [
+                GesturePathPoint(point: startPoint, timestamp: Date().timeIntervalSinceReferenceDate)
+            ]
+            self.visual = nil
+        }
+
+        func recordPoint(_ point: CGPoint) {
+            if let last = pathPoints.last {
+                let dx = point.x - last.x
+                let dy = point.y - last.y
+                guard sqrt(dx * dx + dy * dy) >= 2 else { return }
+            }
+            pathPoints.append(GesturePathPoint(point: point, timestamp: Date().timeIntervalSinceReferenceDate))
+        }
+    }
+
+    private static let syntheticMarker: Int64 = 0x4C474D47
+
+    private var eventTap: CFMachPort?
+    private var runLoopSource: CFRunLoopSource?
+    private var session: GestureSession?
+    private var retainedOverlays: [ObjectIdentifier: MouseGestureOverlay] = [:]
+    private var staleSessionTimer: Timer?
+    private var subscriptions: Set<AnyCancellable> = []
+    private var installedObservers = false
+    private let shapeRecognizer = ShapeRecognizer()
+    private let breaker = EventTapBreaker(label: "MouseGesture")
+    private let budgetMeter = TapBudgetMeter(label: "MouseGesture")
+
+    private struct TapTrackingState {
+        let buttonNumber: Int64
+        let startPoint: CGPoint
+        let nativeClickPassthrough: Bool
+        let startedAt: CFAbsoluteTime
+    }
+
+    // Tap-thread-side mirror of "which button (if any) is currently being
+    // tracked as a gesture". The tap callback runs on EventTapThread; main
+    // owns the full GestureSession but the tap thread needs a fast,
+    // synchronous answer to "should I consume this drag/up event?". Lock
+    // protects cross-thread access (tap thread reads/writes; main writes
+    // via clearSession(clearTracking:) or processMouseDownConsume's bail path).
+    private let trackingLock = NSLock()
+    private var tapTrackingState: TapTrackingState?
+    private var lastTrackingStaleLogAt: CFAbsoluteTime = 0
+    private let maxTapThreadTrackingDuration: TimeInterval = 3.0
+
+    private func currentTrackingState() -> TapTrackingState? {
+        trackingLock.lock()
+        defer { trackingLock.unlock() }
+        let now = CFAbsoluteTimeGetCurrent()
+        if let state = tapTrackingState,
+           now - state.startedAt > maxTapThreadTrackingDuration {
+            let staleButton = state.buttonNumber
+            tapTrackingState = nil
+            if now - lastTrackingStaleLogAt > 1 {
+                lastTrackingStaleLogAt = now
+                DispatchQueue.main.async {
+                    DiagnosticLog.shared.warn("MouseGesture: stale tap-side tracking cleared for button=\(staleButton)")
+                }
+            }
+            return nil
+        }
+        return tapTrackingState
+    }
+
+    private func currentTrackingButton() -> Int64? {
+        currentTrackingState()?.buttonNumber
+    }
+
+    private func setTrackingButton(
+        _ value: Int64?,
+        startPoint: CGPoint = .zero,
+        nativeClickPassthrough: Bool = false
+    ) {
+        trackingLock.lock()
+        if let value {
+            tapTrackingState = TapTrackingState(
+                buttonNumber: value,
+                startPoint: startPoint,
+                nativeClickPassthrough: nativeClickPassthrough,
+                startedAt: CFAbsoluteTimeGetCurrent()
+            )
+        } else {
+            tapTrackingState = nil
+        }
+        trackingLock.unlock()
+    }
+
+    private init() {
+        breaker.onStateChanged = { [weak self] newState in
+            self?.breakerState = newState
+        }
+    }
+
+    func start() {
+        installObserversIfNeeded()
+        refresh()
+    }
+
+    func stop() {
+        clearSession()
+        removeEventTap()
+    }
+
+    func resetForSystemInputBoundary(reason: String) {
+        dispatchPrecondition(condition: .onQueue(.main))
+        clearSession()
+        breaker.reset()
+        if let eventTap {
+            CGEvent.tapEnable(tap: eventTap, enable: true)
+        } else {
+            refresh()
+        }
+        DiagnosticLog.shared.warn("MouseGesture: reset for \(reason)")
+    }
+
+    static func resolveDirection(
+        delta: CGPoint,
+        threshold: CGFloat = 68,
+        axisBias: CGFloat = 1.2
+    ) -> MouseGestureDirection? {
+        let absX = abs(delta.x)
+        let absY = abs(delta.y)
+        guard max(absX, absY) >= threshold else { return nil }
+
+        if absX >= absY * axisBias {
+            return delta.x >= 0 ? .right : .left
+        }
+
+        if absY >= absX * axisBias {
+            return delta.y >= 0 ? .down : .up
+        }
+
+        return nil
+    }
+
+    private func installObserversIfNeeded() {
+        guard !installedObservers else { return }
+        installedObservers = true
+
+        Preferences.shared.$mouseGesturesEnabled
+            .receive(on: RunLoop.main)
+            .sink { [weak self] _ in self?.refresh() }
+            .store(in: &subscriptions)
+
+        PermissionChecker.shared.$accessibility
+            .receive(on: RunLoop.main)
+            .sink { [weak self] _ in self?.refresh() }
+            .store(in: &subscriptions)
+
+        MouseInputEventViewer.shared.$isCaptureActive
+            .receive(on: RunLoop.main)
+            .sink { [weak self] _ in self?.refresh() }
+            .store(in: &subscriptions)
+    }
+
+    private func refresh() {
+        let shouldCapture = MouseInputEventViewer.shared.isCaptureActive || Preferences.shared.mouseGesturesEnabled
+        guard shouldCapture, PermissionChecker.shared.accessibility else {
+            clearSession()
+            removeEventTap()
+            return
+        }
+
+        if eventTap == nil {
+            installEventTap()
+        } else if let eventTap {
+            CGEvent.tapEnable(tap: eventTap, enable: true)
+        }
+    }
+
+    /// Re-enable the tap after a breaker trip, clearing trip history.
+    /// Settings UI calls this when the user explicitly chooses to recover
+    /// from a `disabled` state.
+    func reArmAfterBreakerTrip() {
+        dispatchPrecondition(condition: .onQueue(.main))
+        breaker.reset()
+        if let tap = eventTap {
+            CGEvent.tapEnable(tap: tap, enable: true)
+        }
+    }
+
+    private func installEventTap() {
+        // Fresh install is a clean slate — drop any stale trip history so
+        // the new tap's first failure is judged on its own merits.
+        breaker.reset()
+
+        var mask = CGEventMask(0)
+        mask |= CGEventMask(1) << CGEventType.leftMouseDown.rawValue
+        mask |= CGEventMask(1) << CGEventType.leftMouseUp.rawValue
+        mask |= CGEventMask(1) << CGEventType.rightMouseDown.rawValue
+        mask |= CGEventMask(1) << CGEventType.rightMouseDragged.rawValue
+        mask |= CGEventMask(1) << CGEventType.rightMouseUp.rawValue
+        mask |= CGEventMask(1) << CGEventType.otherMouseDown.rawValue
+        mask |= CGEventMask(1) << CGEventType.otherMouseDragged.rawValue
+        mask |= CGEventMask(1) << CGEventType.otherMouseUp.rawValue
+
+        let tap = CGEvent.tapCreate(
+            tap: .cgSessionEventTap,
+            place: .headInsertEventTap,
+            options: .defaultTap,
+            eventsOfInterest: mask,
+            callback: Self.eventTapCallback,
+            userInfo: UnsafeMutableRawPointer(Unmanaged.passUnretained(self).toOpaque())
+        )
+
+        guard let tap else {
+            DiagnosticLog.shared.warn("MouseGesture: failed to install mouse shortcut event tap")
+            return
+        }
+
+        let source = CFMachPortCreateRunLoopSource(kCFAllocatorDefault, tap, 0)
+        eventTap = tap
+        runLoopSource = source
+
+        if let source {
+            EventTapThread.shared.add(source: source)
+        }
+        CGEvent.tapEnable(tap: tap, enable: true)
+        breaker.rearm = { [weak self] in
+            guard let self, let tap = self.eventTap else { return }
+            CGEvent.tapEnable(tap: tap, enable: true)
+        }
+        DiagnosticLog.shared.info("MouseGesture: mouse shortcut event tap installed")
+    }
+
+    private func removeEventTap() {
+        if let source = runLoopSource {
+            EventTapThread.shared.remove(source: source)
+        }
+        runLoopSource = nil
+        if let tap = eventTap {
+            CFMachPortInvalidate(tap)
+        }
+        eventTap = nil
+    }
+
+    private static let eventTapCallback: CGEventTapCallBack = { _, type, event, userInfo in
+        guard let userInfo else { return Unmanaged.passUnretained(event) }
+        let controller = Unmanaged<MouseGestureController>.fromOpaque(userInfo).takeUnretainedValue()
+        return controller.handleEvent(type: type, event: event)
+    }
+
+    private func handleEvent(type: CGEventType, event: CGEvent) -> Unmanaged<CGEvent>? {
+        let started = CFAbsoluteTimeGetCurrent()
+        defer {
+            let elapsedMs = (CFAbsoluteTimeGetCurrent() - started) * 1000
+            budgetMeter.record(durationMs: elapsedMs)
+        }
+
+        if type == .tapDisabledByTimeout {
+            // OS killed the tap because a callback was too slow. Run through
+            // the breaker — it backs off in escalating cooldowns rather than
+            // re-enabling immediately and getting killed again.
+            breaker.recordTrip()
+            return Unmanaged.passUnretained(event)
+        }
+        if type == .tapDisabledByUserInput {
+            // User-driven disable (rare). Re-enable directly, no cooldown.
+            if let eventTap {
+                CGEvent.tapEnable(tap: eventTap, enable: true)
+            }
+            return Unmanaged.passUnretained(event)
+        }
+
+        if event.getIntegerValueField(.eventSourceUserData) == Self.syntheticMarker {
+            return Unmanaged.passUnretained(event)
+        }
+
+        if isEmergencyMouseReset(type: type, event: event) {
+            setTrackingButton(nil)
+            DispatchQueue.main.async { [weak self] in
+                self?.clearSession()
+                InputCaptureResetCenter.reset(reason: "Hyper mouse click")
+            }
+            return Unmanaged.passUnretained(event)
+        }
+
+        switch type {
+        case .leftMouseDown, .leftMouseUp:
+            return handlePassiveMouseButtonEvent(type: type, event: event)
+        case .rightMouseDown:
+            return handleMouseDown(event, buttonNumber: Int64(CGMouseButton.right.rawValue))
+        case .rightMouseDragged:
+            return handleMouseDragged(event, buttonNumber: Int64(CGMouseButton.right.rawValue))
+        case .rightMouseUp:
+            return handleMouseUp(event, buttonNumber: Int64(CGMouseButton.right.rawValue))
+        default:
+            break
+        }
+
+        let buttonNumber = event.getIntegerValueField(.mouseEventButtonNumber)
+        if buttonNumber < 2 {
+            return Unmanaged.passUnretained(event)
+        }
+
+        switch type {
+        case .otherMouseDown:
+            return handleMouseDown(event, buttonNumber: buttonNumber)
+        case .otherMouseDragged:
+            return handleMouseDragged(event, buttonNumber: buttonNumber)
+        case .otherMouseUp:
+            return handleMouseUp(event, buttonNumber: buttonNumber)
+        default:
+            return Unmanaged.passUnretained(event)
+        }
+    }
+
+    // MARK: - Tap-thread dispatch
+    //
+    // handle* methods run on EventTapThread. They compute the consume/pass
+    // verdict from cheap, thread-safe reads, capture the event into a
+    // MouseEventSnapshot, and hand the heavy work to main async — so a slow
+    // main thread never adds latency to mouse events at the head-insert tap.
+
+    private func handlePassiveMouseButtonEvent(type: CGEventType, event: CGEvent) -> Unmanaged<CGEvent>? {
+        let snapshot = MouseEventSnapshot(
+            location: event.location,
+            flags: event.flags,
+            buttonNumber: event.getIntegerValueField(.mouseEventButtonNumber)
+        )
+        DispatchQueue.main.async { [weak self] in
+            self?.processPassiveMouseButton(type: type, snapshot: snapshot)
+        }
+        return Unmanaged.passUnretained(event)
+    }
+
+    private func isEmergencyMouseReset(type: CGEventType, event: CGEvent) -> Bool {
+        switch type {
+        case .leftMouseDown, .rightMouseDown, .otherMouseDown:
+            return event.flags.intersection(.latticesHyper) == .latticesHyper
+        default:
+            return false
+        }
+    }
+
+    private func processPassiveMouseButton(type: CGEventType, snapshot: MouseEventSnapshot) {
+        dispatchPrecondition(condition: .onQueue(.main))
+        guard MouseInputEventViewer.shared.isCaptureActive else { return }
+
+        let phase: String
+        switch type {
+        case .leftMouseDown, .rightMouseDown:
+            phase = "down"
+        case .leftMouseUp, .rightMouseUp:
+            phase = "up"
+        default:
+            return
+        }
+
+        recordObservedEvent(
+            phase: phase,
+            button: MouseShortcutButton(rawButtonNumber: Int(snapshot.buttonNumber)),
+            location: snapshot.location,
+            delta: .zero,
+            modifiers: snapshot.flags,
+            candidate: nil,
+            match: nil,
+            note: "pass-through primary button",
+            appInfo: currentAppInfo()
+        )
+    }
+
+    private func handleMouseDown(_ event: CGEvent, buttonNumber: Int64) -> Unmanaged<CGEvent>? {
+        let snapshot = MouseEventSnapshot(
+            location: event.location,
+            flags: event.flags,
+            buttonNumber: buttonNumber
+        )
+        // NSScreen.screens reads are safe off-main; Preferences/Store snapshot
+        // reads are lock-protected (see MouseShortcutStore).
+        let button = MouseShortcutButton(rawButtonNumber: Int(buttonNumber))
+        let needsNativeClickCapture = MouseShortcutStore.shared.hasEnabledRule(button: button, kind: .click)
+            || MouseShortcutStore.shared.hasEnabledRule(button: button, kind: .shape)
+        let nativeClickPassthrough = buttonNumber >= 2 && !needsNativeClickCapture
+        let canRecognize = Preferences.shared.mouseGesturesEnabled
+            && MouseShortcutStore.shared.watchedButtonNumbers.contains(buttonNumber)
+        let onScreen = (screen(containing: snapshot.location) != nil)
+
+        if !onScreen {
+            DispatchQueue.main.async { [weak self] in
+                self?.processMouseDownPassthrough(snapshot: snapshot, reason: .offScreen)
+            }
+            return Unmanaged.passUnretained(event)
+        }
+        if !canRecognize {
+            DispatchQueue.main.async { [weak self] in
+                self?.processMouseDownPassthrough(snapshot: snapshot, reason: .notMapped)
+            }
+            return Unmanaged.passUnretained(event)
+        }
+
+        // Mark this button as actively tracked before the OS sees a follow-up
+        // drag/up — the tap thread reads this on subsequent events to decide
+        // whether to consume them.
+        setTrackingButton(
+            buttonNumber,
+            startPoint: snapshot.location,
+            nativeClickPassthrough: nativeClickPassthrough
+        )
+        DispatchQueue.main.async { [weak self] in
+            self?.processMouseDownConsume(
+                snapshot: snapshot,
+                nativeClickPassthrough: nativeClickPassthrough
+            )
+        }
+        return nativeClickPassthrough ? Unmanaged.passUnretained(event) : nil
+    }
+
+    private enum MouseDownPassthroughReason {
+        case offScreen
+        case notMapped
+    }
+
+    private func processMouseDownPassthrough(snapshot: MouseEventSnapshot, reason: MouseDownPassthroughReason) {
+        dispatchPrecondition(condition: .onQueue(.main))
+        let button = MouseShortcutButton(rawButtonNumber: Int(snapshot.buttonNumber))
+        let appInfo = currentAppInfo()
+        switch reason {
+        case .offScreen:
+            DiagnosticLog.shared.info("MouseGesture: ignored click at \(format(snapshot.location)) (off-screen)")
+            recordObservedEvent(
+                phase: "down",
+                button: button,
+                location: snapshot.location,
+                delta: .zero,
+                modifiers: snapshot.flags,
+                candidate: nil,
+                match: nil,
+                note: "off-screen",
+                appInfo: appInfo
+            )
+            clearSession()
+        case .notMapped:
+            recordObservedEvent(
+                phase: "down",
+                button: button,
+                location: snapshot.location,
+                delta: .zero,
+                modifiers: snapshot.flags,
+                candidate: nil,
+                match: nil,
+                note: "button not mapped",
+                appInfo: appInfo
+            )
+        }
+    }
+
+    private func processMouseDownConsume(snapshot: MouseEventSnapshot, nativeClickPassthrough: Bool) {
+        dispatchPrecondition(condition: .onQueue(.main))
+        MouseShortcutStore.shared.reloadIfNeeded()
+        let button = MouseShortcutButton(rawButtonNumber: Int(snapshot.buttonNumber))
+        let appInfo = currentAppInfo()
+
+        guard let screen = screen(containing: snapshot.location) else {
+            // Screens changed between tap-thread verdict and main; treat as
+            // off-screen and clear the tap-side tracking we eagerly set.
+            setTrackingButton(nil)
+            recordObservedEvent(
+                phase: "down",
+                button: button,
+                location: snapshot.location,
+                delta: .zero,
+                modifiers: snapshot.flags,
+                candidate: nil,
+                match: nil,
+                note: "off-screen (post-dispatch)",
+                appInfo: appInfo
+            )
+            clearSession()
+            return
+        }
+
+        clearSession(clearTracking: false)
+        let overlay = MouseGestureOverlay(screen: screen)
+        overlay.onDismiss = { [weak self, weak overlay] in
+            guard let self, let overlay else { return }
+            self.releaseOverlay(overlay)
+        }
+        let newSession = GestureSession(buttonNumber: snapshot.buttonNumber, startPoint: snapshot.location, overlay: overlay)
+        newSession.visual = MouseShortcutStore.shared.visualHint(for: button)
+        session = newSession
+        scheduleStaleSessionCleanup(for: newSession)
+        DiagnosticLog.shared.info("MouseGesture: began at \(format(snapshot.location)) button=\(snapshot.buttonNumber)")
+        recordObservedEvent(
+            phase: "down",
+            button: button,
+            location: snapshot.location,
+            delta: .zero,
+            modifiers: snapshot.flags,
+            candidate: nil,
+            match: nil,
+            note: nativeClickPassthrough ? "tracking; native click passes through" : "tracking",
+            appInfo: appInfo
+        )
+    }
+
+    private func handleMouseDragged(_ event: CGEvent, buttonNumber: Int64) -> Unmanaged<CGEvent>? {
+        guard currentTrackingButton() == buttonNumber else {
+            return Unmanaged.passUnretained(event)
+        }
+        let snapshot = MouseEventSnapshot(
+            location: event.location,
+            flags: event.flags,
+            buttonNumber: buttonNumber
+        )
+        DispatchQueue.main.async { [weak self] in
+            self?.processMouseDragged(snapshot: snapshot)
+        }
+        return nil
+    }
+
+    private func processMouseDragged(snapshot: MouseEventSnapshot) {
+        dispatchPrecondition(condition: .onQueue(.main))
+        guard let session, session.buttonNumber == snapshot.buttonNumber else {
+            return
+        }
+        MouseShortcutStore.shared.reloadIfNeeded()
+
+        session.currentPoint = snapshot.location
+        session.recordPoint(snapshot.location)
+        scheduleStaleSessionCleanup(for: session)
+        let button = MouseShortcutButton(rawButtonNumber: Int(snapshot.buttonNumber))
+        let delta = CGPoint(
+            x: snapshot.location.x - session.startPoint.x,
+            y: snapshot.location.y - session.startPoint.y
+        )
+        let tuning = MouseShortcutStore.shared.tuning
+        let direction = Self.resolveDirection(delta: delta, threshold: tuning.dragThreshold, axisBias: tuning.axisBias)
+
+        if direction != session.lockedDirection {
+            session.lockedDirection = direction
+            if let direction {
+                let triggerEvent = MouseShortcutTriggerEvent(button: button, kind: .drag, direction: direction, device: nil)
+                let match = MouseShortcutStore.shared.match(for: triggerEvent)
+                DiagnosticLog.shared.info("MouseGesture: locked \(label(for: direction)) via \(triggerEvent.triggerName)")
+                recordObservedEvent(
+                    phase: "drag",
+                    button: button,
+                    location: snapshot.location,
+                    delta: delta,
+                    modifiers: snapshot.flags,
+                    candidate: triggerEvent.triggerName,
+                    match: match,
+                    note: match == nil ? "no rule" : "candidate",
+                    appInfo: currentAppInfo()
+                )
+            }
+        }
+
+        if let direction {
+            let dominantDistance = max(abs(delta.x), abs(delta.y))
+            let previewProgress = previewProgress(
+                dominantDistance: dominantDistance,
+                threshold: tuning.dragThreshold
+            )
+            session.overlay.track(
+                origin: session.startPoint,
+                direction: direction,
+                label: nil,
+                style: overlayStyle(for: button),
+                visual: session.visual,
+                visualPhase: .updated,
+                shape: nil,
+                success: nil,
+                pathPoints: session.pathPoints,
+                progress: previewProgress
+            )
+        } else {
+            session.overlay.track(
+                origin: session.startPoint,
+                direction: nil,
+                label: nil,
+                style: overlayStyle(for: button),
+                visual: session.visual,
+                visualPhase: .updated,
+                shape: nil,
+                success: nil,
+                pathPoints: session.pathPoints,
+                progress: 0
+            )
+        }
+    }
+
+    private func handleMouseUp(_ event: CGEvent, buttonNumber: Int64) -> Unmanaged<CGEvent>? {
+        let snapshot = MouseEventSnapshot(
+            location: event.location,
+            flags: event.flags,
+            buttonNumber: buttonNumber
+        )
+        guard let trackingState = currentTrackingState(),
+              trackingState.buttonNumber == buttonNumber else {
+            DispatchQueue.main.async { [weak self] in
+                self?.processMouseUpNoSession(snapshot: snapshot)
+            }
+            return Unmanaged.passUnretained(event)
+        }
+
+        if trackingState.nativeClickPassthrough {
+            let delta = CGPoint(
+                x: snapshot.location.x - trackingState.startPoint.x,
+                y: snapshot.location.y - trackingState.startPoint.y
+            )
+            let tuning = MouseShortcutStore.shared.tuning
+            let direction = Self.resolveDirection(delta: delta, threshold: tuning.dragThreshold, axisBias: tuning.axisBias)
+            if direction == nil {
+                setTrackingButton(nil)
+                DispatchQueue.main.async { [weak self] in
+                    self?.processMouseUpNativeClickPassthrough(snapshot: snapshot)
+                }
+                return Unmanaged.passUnretained(event)
+            }
+        }
+
+        // Clear tap-side tracking so a subsequent drag/up for this button
+        // falls through.
+        setTrackingButton(nil)
+        DispatchQueue.main.async { [weak self] in
+            self?.processMouseUp(snapshot: snapshot)
+        }
+        return nil
+    }
+
+    private func processMouseUpNoSession(snapshot: MouseEventSnapshot) {
+        dispatchPrecondition(condition: .onQueue(.main))
+        recordObservedEvent(
+            phase: "up",
+            button: MouseShortcutButton(rawButtonNumber: Int(snapshot.buttonNumber)),
+            location: snapshot.location,
+            delta: .zero,
+            modifiers: snapshot.flags,
+            candidate: nil,
+            match: nil,
+            note: "no active session",
+            appInfo: currentAppInfo()
+        )
+    }
+
+    private func processMouseUpNativeClickPassthrough(snapshot: MouseEventSnapshot) {
+        dispatchPrecondition(condition: .onQueue(.main))
+        guard let activeSession = session,
+              activeSession.buttonNumber == snapshot.buttonNumber else {
+            recordObservedEvent(
+                phase: "up",
+                button: MouseShortcutButton(rawButtonNumber: Int(snapshot.buttonNumber)),
+                location: snapshot.location,
+                delta: .zero,
+                modifiers: snapshot.flags,
+                candidate: nil,
+                match: nil,
+                note: "native click passthrough",
+                appInfo: currentAppInfo()
+            )
+            return
+        }
+
+        let delta = CGPoint(
+            x: snapshot.location.x - activeSession.startPoint.x,
+            y: snapshot.location.y - activeSession.startPoint.y
+        )
+        recordObservedEvent(
+            phase: "up",
+            button: MouseShortcutButton(rawButtonNumber: Int(snapshot.buttonNumber)),
+            location: snapshot.location,
+            delta: delta,
+            modifiers: snapshot.flags,
+            candidate: nil,
+            match: nil,
+            note: "native click passthrough",
+            appInfo: currentAppInfo()
+        )
+        clearSession()
+    }
+
+    private func processMouseUp(snapshot: MouseEventSnapshot) {
+        dispatchPrecondition(condition: .onQueue(.main))
+        MouseShortcutStore.shared.reloadIfNeeded()
+        let button = MouseShortcutButton(rawButtonNumber: Int(snapshot.buttonNumber))
+        let appInfo = currentAppInfo()
+
+        guard let session, session.buttonNumber == snapshot.buttonNumber else {
+            // Session was cleared between the tap-thread dispatch and now.
+            return
+        }
+        session.currentPoint = snapshot.location
+        session.recordPoint(snapshot.location)
+
+        let delta = CGPoint(
+            x: snapshot.location.x - session.startPoint.x,
+            y: snapshot.location.y - session.startPoint.y
+        )
+        let tuning = MouseShortcutStore.shared.tuning
+        let direction = Self.resolveDirection(delta: delta, threshold: tuning.dragThreshold, axisBias: tuning.axisBias)
+        self.session = nil
+        staleSessionTimer?.invalidate()
+        staleSessionTimer = nil
+
+        let shapeResult = shapeRecognizer.recognize(points: session.pathPoints)
+        if let shape = shapeResult.shape {
+            let shapeTrigger = MouseShortcutTriggerEvent(button: button, kind: .shape, shape: shape)
+            let shapeMatch = MouseShortcutStore.shared.match(for: shapeTrigger)
+            if let shapeMatch {
+                let commitDirection = shapeResult.segments.last?.direction ?? direction ?? .right
+                let dismissBeforeAction = shouldDismissOverlayBeforeAction(match: shapeMatch)
+                if dismissBeforeAction {
+                    session.overlay.dismiss(immediately: true)
+                }
+
+                DispatchQueue.main.async { [weak self] in
+                    guard let self else { return }
+                    if !dismissBeforeAction {
+                        self.retainOverlay(session.overlay)
+                    }
+                    let outcome = self.performAction(match: shapeMatch, startPoint: session.startPoint)
+                    DiagnosticLog.shared.info("MouseGesture: \(shape.displayName) -> \(outcome.label) -> \(outcome.success ? "ok" : "blocked")")
+                    self.recordObservedEvent(
+                        phase: "up",
+                        button: button,
+                        location: snapshot.location,
+                        delta: delta,
+                        modifiers: snapshot.flags,
+                        candidate: shapeTrigger.triggerName,
+                        match: shapeMatch,
+                        note: "shape fired confidence=\(String(format: "%.2f", Double(shapeResult.confidence)))",
+                        appInfo: appInfo
+                    )
+                    if !dismissBeforeAction {
+                        session.overlay.commit(
+                            origin: session.startPoint,
+                            direction: commitDirection,
+                            label: outcome.label,
+                            success: outcome.success,
+                            style: self.overlayStyle(for: button),
+                            visual: shapeMatch.rule.visual ?? session.visual,
+                            visualPhase: .completed,
+                            shape: shape,
+                            pathPoints: session.pathPoints,
+                            accessory: outcome.accessory
+                        )
+                    }
+                }
+                return
+            }
+        }
+
+        guard let direction else {
+            let clickTrigger = MouseShortcutTriggerEvent(button: button, kind: .click, direction: nil, device: nil)
+            let clickMatch = MouseShortcutStore.shared.match(for: clickTrigger)
+            DiagnosticLog.shared.info("MouseGesture: released without a gesture at \(format(snapshot.location))")
+            recordObservedEvent(
+                phase: "up",
+                button: button,
+                location: snapshot.location,
+                delta: delta,
+                modifiers: snapshot.flags,
+                candidate: clickMatch != nil ? clickTrigger.triggerName : nil,
+                match: clickMatch,
+                note: clickMatch != nil ? "click action" : "replay click",
+                appInfo: appInfo
+            )
+            if let clickMatch {
+                DispatchQueue.main.async { [weak self] in
+                    guard let self else { return }
+                    session.overlay.dismiss(immediately: true)
+                    let outcome = self.performAction(match: clickMatch, startPoint: session.startPoint)
+                    DiagnosticLog.shared.info("MouseGesture: \(outcome.label) -> \(outcome.success ? "ok" : "blocked")")
+                }
+            } else {
+                DispatchQueue.main.async { [weak self] in
+                    session.overlay.dismiss()
+                    self?.replayMouseClick(
+                        buttonNumber: snapshot.buttonNumber,
+                        at: session.startPoint,
+                        flags: snapshot.flags
+                    )
+                }
+            }
+            return
+        }
+
+        let triggerEvent = MouseShortcutTriggerEvent(button: button, kind: .drag, direction: direction, device: nil)
+        let match = MouseShortcutStore.shared.match(for: triggerEvent)
+        let dismissBeforeAction = shouldDismissOverlayBeforeAction(match: match)
+        if dismissBeforeAction {
+            session.overlay.dismiss(immediately: true)
+        }
+
+        DispatchQueue.main.async { [weak self] in
+            guard let self else { return }
+            if !dismissBeforeAction {
+                self.retainOverlay(session.overlay)
+            }
+            let outcome = self.performAction(match: match, startPoint: session.startPoint)
+            DiagnosticLog.shared.info("MouseGesture: \(outcome.label) -> \(outcome.success ? "ok" : "blocked")")
+            self.recordObservedEvent(
+                phase: "up",
+                button: button,
+                location: snapshot.location,
+                delta: delta,
+                modifiers: snapshot.flags,
+                candidate: triggerEvent.triggerName,
+                match: match,
+                note: outcome.success ? "fired" : "blocked",
+                appInfo: appInfo
+            )
+            if !dismissBeforeAction {
+                session.overlay.commit(
+                    origin: session.startPoint,
+                    direction: direction,
+                    label: outcome.label,
+                    success: outcome.success,
+                    style: self.overlayStyle(for: button),
+                    visual: match?.rule.visual ?? session.visual,
+                    visualPhase: .completed,
+                    shape: nil,
+                    pathPoints: session.pathPoints,
+                    accessory: outcome.accessory
+                )
+            }
+        }
+    }
+
+    private func performAction(match: MouseShortcutMatchResult?, startPoint: CGPoint) -> GestureOutcome {
+        guard let match else {
+            return GestureOutcome(label: "No Shortcut Assigned", success: false, accessory: nil)
+        }
+
+        switch match.action.type {
+        case .spacePrevious:
+            guard WindowTiler.adjacentSpaceTarget(offset: -1, from: startPoint) != nil else {
+                return GestureOutcome(label: "No Previous Space", success: false, accessory: nil)
+            }
+            let switched = WindowTiler.switchToAdjacentSpace(offset: -1, from: startPoint)
+            return GestureOutcome(label: switched ? "Previous Space" : "Previous Space Blocked", success: switched, accessory: nil)
+        case .spaceNext:
+            guard WindowTiler.adjacentSpaceTarget(offset: 1, from: startPoint) != nil else {
+                return GestureOutcome(label: "No Next Space", success: false, accessory: nil)
+            }
+            let switched = WindowTiler.switchToAdjacentSpace(offset: 1, from: startPoint)
+            return GestureOutcome(label: switched ? "Next Space" : "Next Space Blocked", success: switched, accessory: nil)
+        case .screenMapToggle:
+            ScreenMapWindowController.shared.showScreenMapOverview()
+            return GestureOutcome(label: "Screen Map Overview", success: true, accessory: nil)
+        case .dictationStart:
+            let sent = sendDictationShortcut()
+            return GestureOutcome(
+                label: sent ? "Dictation" : "Permission Needed",
+                success: sent,
+                accessory: sent ? .mic : nil
+            )
+        case .shortcutSend:
+            let sent = sendShortcut(match.action.shortcut)
+            return GestureOutcome(
+                label: sent ? match.action.label : "Shortcut Blocked",
+                success: sent,
+                accessory: nil
+            )
+        case .appActivate:
+            let activated = activateApplication(named: match.action.app)
+            let appLabel = match.action.app?.trimmingCharacters(in: .whitespacesAndNewlines)
+            return GestureOutcome(
+                label: activated ? "\(appLabel?.isEmpty == false ? appLabel! : "App") Focused" : "App Activation Blocked",
+                success: activated,
+                accessory: nil
+            )
+        }
+    }
+
+    private func label(for direction: MouseGestureDirection) -> String {
+        switch direction {
+        case .left:
+            return "Previous Space"
+        case .right:
+            return "Next Space"
+        case .up:
+            return "Up"
+        case .down:
+            return "Screen Map Overview"
+        }
+    }
+
+    private func overlayStyle(for button: MouseShortcutButton) -> MouseGestureOverlayStyle {
+        switch button {
+        case .button4:
+            return .thinLine
+        case .button5:
+            return .thickLine
+        case .middle:
+            return .drawing
+        case .right, .number:
+            return .drawing
+        }
+    }
+
+    private func clearSession(clearTracking: Bool = true) {
+        staleSessionTimer?.invalidate()
+        staleSessionTimer = nil
+        session?.overlay.dismiss(immediately: true)
+        session = nil
+        // Keep tap-side tracking in sync with main-side session lifetime so a
+        // subsequent drag/up isn't consumed for a session that no longer
+        // exists.
+        if clearTracking {
+            setTrackingButton(nil)
+        }
+    }
+
+    private func replayMouseClick(buttonNumber: Int64, at point: CGPoint, flags: CGEventFlags) {
+        let events: [CGEventType]
+        if buttonNumber == Int64(CGMouseButton.right.rawValue) {
+            events = [.rightMouseDown, .rightMouseUp]
+        } else {
+            events = [.otherMouseDown, .otherMouseUp]
+        }
+        for type in events {
+            guard let mouseButton = CGMouseButton(rawValue: UInt32(buttonNumber)) else { continue }
+            guard let event = CGEvent(
+                mouseEventSource: nil,
+                mouseType: type,
+                mouseCursorPosition: point,
+                mouseButton: mouseButton
+            ) else { continue }
+
+            event.setIntegerValueField(CGEventField.mouseEventButtonNumber, value: buttonNumber)
+            event.setIntegerValueField(CGEventField.eventSourceUserData, value: Self.syntheticMarker)
+            event.flags = flags
+            event.post(tap: CGEventTapLocation.cghidEventTap)
+        }
+    }
+
+    private func screen(containing cgPoint: CGPoint) -> NSScreen? {
+        let primaryHeight = NSScreen.screens.first?.frame.height ?? 0
+        let nsPoint = NSPoint(x: cgPoint.x, y: primaryHeight - cgPoint.y)
+        return NSScreen.screens.first(where: { $0.frame.contains(nsPoint) }) ?? NSScreen.main ?? NSScreen.screens.first
+    }
+
+    private func format(_ point: CGPoint) -> String {
+        "\(Int(point.x)),\(Int(point.y))"
+    }
+
+    private func shouldDismissOverlayBeforeAction(match _: MouseShortcutMatchResult?) -> Bool {
+        true
+    }
+
+    private func previewProgress(dominantDistance: CGFloat, threshold: CGFloat) -> CGFloat {
+        guard dominantDistance > threshold else { return 0 }
+        let overshoot = dominantDistance - threshold
+        let normalized = min(1, max(0, overshoot / 90))
+        return 0.32 + normalized * 0.68
+    }
+
+    private func retainOverlay(_ overlay: MouseGestureOverlay) {
+        retainedOverlays[ObjectIdentifier(overlay)] = overlay
+    }
+
+    private func releaseOverlay(_ overlay: MouseGestureOverlay) {
+        retainedOverlays.removeValue(forKey: ObjectIdentifier(overlay))
+    }
+
+    private func scheduleStaleSessionCleanup(for session: GestureSession) {
+        staleSessionTimer?.invalidate()
+        let timer = Timer(timeInterval: 3.0, repeats: false) { [weak self, weak session] _ in
+            guard let self, let session, self.session === session else { return }
+            DiagnosticLog.shared.warn("MouseGesture: stale gesture session dismissed")
+            self.clearSession()
+        }
+        staleSessionTimer = timer
+        RunLoop.main.add(timer, forMode: .common)
+    }
+
+    private func currentAppInfo() -> (name: String?, bundleId: String?) {
+        let app = NSWorkspace.shared.frontmostApplication
+        return (app?.localizedName, app?.bundleIdentifier)
+    }
+
+    private func recordObservedEvent(
+        phase: String,
+        button: MouseShortcutButton,
+        location: CGPoint,
+        delta: CGPoint,
+        modifiers: CGEventFlags,
+        candidate: String?,
+        match: MouseShortcutMatchResult?,
+        note: String?,
+        appInfo: (name: String?, bundleId: String?)
+    ) {
+        guard MouseInputEventViewer.shared.isCaptureActive else { return }
+        let sourceState = Int(modifiers.rawValue)
+        MouseInputEventViewer.shared.record(
+            MouseShortcutObservedEvent(
+                timestamp: Date(),
+                phase: phase,
+                buttonNumber: button.rawButtonNumber,
+                location: location,
+                delta: delta,
+                modifiers: NSEvent.ModifierFlags(rawValue: UInt(modifiers.rawValue)),
+                frontmostAppName: appInfo.name,
+                frontmostBundleId: appInfo.bundleId,
+                candidateTrigger: candidate,
+                device: nil,
+                matchedRuleSummary: match?.rule.summary,
+                willFire: match != nil,
+                note: note.map { "\($0) | flags=\(sourceState)" } ?? "flags=\(sourceState)"
+            )
+        )
+    }
+
+    private func sendShortcut(_ shortcut: MouseShortcutKeyStroke?) -> Bool {
+        guard let shortcut else { return false }
+        if sendShortcutWithCGEvent(shortcut) {
+            return true
+        }
+
+        let modifiers = shortcut.modifiers.map(\.appleScriptToken).joined(separator: ", ")
+        let command: String
+
+        if let keyCode = shortcut.keyCode {
+            command = modifiers.isEmpty
+                ? "key code \(keyCode)"
+                : "key code \(keyCode) using {\(modifiers)}"
+        } else if let key = shortcut.key {
+            command = modifiers.isEmpty
+                ? "keystroke \"\(key)\""
+                : "keystroke \"\(key)\" using {\(modifiers)}"
+        } else {
+            return false
+        }
+
+        let script = """
+        tell application "System Events"
+            \(command)
+        end tell
+        return "ok"
+        """
+        let result = ProcessQuery.shell(["/usr/bin/osascript", "-e", script])
+        if result != "ok" {
+            DiagnosticLog.shared.warn("MouseGesture: AppleScript shortcut send failed for \(shortcut.displayLabel)")
+        }
+        return result == "ok"
+    }
+
+    private func sendDictationShortcut() -> Bool {
+        sendShortcut(
+            MouseShortcutKeyStroke(
+                key: "a",
+                keyCode: 0,
+                modifiers: [.command, .shift]
+            )
+        )
+    }
+
+    private func sendShortcutWithCGEvent(_ shortcut: MouseShortcutKeyStroke) -> Bool {
+        guard let keyCode = shortcut.keyCode.map(CGKeyCode.init) ?? keyCode(for: shortcut.key) else {
+            return false
+        }
+        guard let source = CGEventSource(stateID: .combinedSessionState),
+              let down = CGEvent(keyboardEventSource: source, virtualKey: keyCode, keyDown: true),
+              let up = CGEvent(keyboardEventSource: source, virtualKey: keyCode, keyDown: false) else {
+            DiagnosticLog.shared.warn("MouseGesture: CGEvent shortcut source unavailable for \(shortcut.displayLabel)")
+            return false
+        }
+
+        let flags = cgEventFlags(for: shortcut.modifiers)
+        down.flags = flags
+        up.flags = flags
+        down.setIntegerValueField(.eventSourceUserData, value: Self.syntheticMarker)
+        up.setIntegerValueField(.eventSourceUserData, value: Self.syntheticMarker)
+        down.post(tap: .cghidEventTap)
+        usleep(12_000)
+        up.post(tap: .cghidEventTap)
+        return true
+    }
+
+    private func cgEventFlags(for modifiers: [MouseShortcutModifier]) -> CGEventFlags {
+        var flags: CGEventFlags = []
+        for modifier in modifiers {
+            switch modifier {
+            case .command:
+                flags.insert(.maskCommand)
+            case .option:
+                flags.insert(.maskAlternate)
+            case .control:
+                flags.insert(.maskControl)
+            case .shift:
+                flags.insert(.maskShift)
+            }
+        }
+        return flags
+    }
+
+    private func keyCode(for key: String?) -> CGKeyCode? {
+        guard let key = key?.trimmingCharacters(in: .whitespacesAndNewlines).lowercased(),
+              !key.isEmpty else {
+            return nil
+        }
+        let codes: [String: CGKeyCode] = [
+            "a": 0, "s": 1, "d": 2, "f": 3, "h": 4, "g": 5, "z": 6, "x": 7,
+            "c": 8, "v": 9, "b": 11, "q": 12, "w": 13, "e": 14, "r": 15,
+            "y": 16, "t": 17, "1": 18, "2": 19, "3": 20, "4": 21, "6": 22,
+            "5": 23, "=": 24, "9": 25, "7": 26, "-": 27, "8": 28, "0": 29,
+            "]": 30, "o": 31, "u": 32, "[": 33, "i": 34, "p": 35, "enter": 36,
+            "return": 36, "l": 37, "j": 38, "'": 39, "k": 40, ";": 41,
+            "\\": 42, ",": 43, "/": 44, "n": 45, "m": 46, ".": 47, "tab": 48,
+            "space": 49, "`": 50, "delete": 51, "backspace": 51, "escape": 53,
+            "esc": 53, "left": 123, "right": 124, "down": 125, "up": 126,
+        ]
+        return codes[key]
+    }
+
+    private func activateApplication(named appName: String?) -> Bool {
+        guard let appName, !appName.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else {
+            return false
+        }
+
+        if let running = NSWorkspace.shared.runningApplications.first(where: { app in
+            app.localizedName?.localizedCaseInsensitiveCompare(appName) == .orderedSame
+                || app.bundleIdentifier?.localizedCaseInsensitiveContains(appName) == true
+        }) {
+            return running.activate(options: [.activateAllWindows, .activateIgnoringOtherApps])
+        }
+
+        let fileManager = FileManager.default
+        let trimmedName = appName.trimmingCharacters(in: .whitespacesAndNewlines)
+        let appFilenames = trimmedName.hasSuffix(".app") ? [trimmedName] : [trimmedName + ".app", trimmedName]
+        let roots = [
+            "/Applications",
+            "/System/Applications",
+            fileManager.homeDirectoryForCurrentUser.appendingPathComponent("Applications").path,
+        ]
+
+        for root in roots {
+            for filename in appFilenames {
+                let url = URL(fileURLWithPath: root).appendingPathComponent(filename)
+                guard fileManager.fileExists(atPath: url.path) else { continue }
+                NSWorkspace.shared.openApplication(at: url, configuration: NSWorkspace.OpenConfiguration())
+                return true
+            }
+        }
+
+        _ = ProcessQuery.shell(["/usr/bin/open", "-a", trimmedName])
+        return true
+    }
+}
+
+private final class MouseGestureOverlay {
+    private let committedHoldDuration: TimeInterval = 0.0
+    private let fadeDuration: TimeInterval = 0.03
+    private let accessoryCommittedHoldDuration: TimeInterval = 0.0
+    private let accessoryAnimationDuration: TimeInterval = 0.10
+
+    private let screen: NSScreen
+    private let window: NSWindow
+    private let overlayView: MouseGestureOverlayView
+    private var fadeTimer: Timer?
+    var onDismiss: (() -> Void)?
+
+    init(screen: NSScreen) {
+        self.screen = screen
+        self.window = NSWindow(
+            contentRect: screen.frame,
+            styleMask: .borderless,
+            backing: .buffered,
+            defer: false
+        )
+        self.overlayView = MouseGestureOverlayView(frame: NSRect(origin: .zero, size: screen.frame.size))
+
+        window.isOpaque = false
+        window.backgroundColor = .clear
+        window.level = NSWindow.Level(rawValue: Int(CGWindowLevelForKey(.maximumWindow)))
+        window.hasShadow = false
+        window.ignoresMouseEvents = true
+        window.collectionBehavior = [.canJoinAllSpaces, .stationary, .fullScreenAuxiliary]
+        window.contentView = overlayView
+        window.orderFrontRegardless()
+    }
+
+    func track(
+        origin: CGPoint,
+        direction: MouseGestureDirection?,
+        label: String?,
+        style: MouseGestureOverlayStyle,
+        visual: MouseShortcutVisualDefinition?,
+        visualPhase: MouseGestureVisualPhase,
+        shape: GestureShapeLabel?,
+        success: Bool?,
+        pathPoints: [GesturePathPoint],
+        progress: CGFloat
+    ) {
+        fadeTimer?.invalidate()
+        window.alphaValue = 1
+        let localPath = localPath(from: pathPoints)
+        if direction != nil || localPath.count > 1 {
+            overlayView.state = .tracking(
+                origin: localPoint(from: origin),
+                direction: direction,
+                label: label,
+                style: style,
+                visual: visual,
+                visualPhase: visualPhase,
+                shape: shape,
+                success: success,
+                path: localPath,
+                progress: progress
+            )
+        } else {
+            overlayView.state = .idle
+        }
+        overlayView.needsDisplay = true
+    }
+
+    func commit(
+        origin: CGPoint,
+        direction: MouseGestureDirection,
+        label: String,
+        success: Bool,
+        style: MouseGestureOverlayStyle,
+        visual: MouseShortcutVisualDefinition?,
+        visualPhase: MouseGestureVisualPhase,
+        shape: GestureShapeLabel?,
+        pathPoints: [GesturePathPoint],
+        accessory: MouseGestureAccessory?
+    ) {
+        fadeTimer?.invalidate()
+        window.alphaValue = 1
+        overlayView.state = .committed(
+            origin: localPoint(from: origin),
+            direction: direction,
+            label: label,
+            success: success,
+            style: style,
+            visual: visual,
+            visualPhase: visualPhase,
+            shape: shape,
+            path: localPath(from: pathPoints),
+            accessory: accessory,
+            accessoryAnimationDuration: accessoryAnimationDuration
+        )
+        overlayView.needsDisplay = true
+
+        let postReplayHoldDuration = accessory == nil ? committedHoldDuration : accessoryCommittedHoldDuration
+        let totalVisibleDuration = overlayView.replayLeadInDuration + postReplayHoldDuration
+        let timer = Timer(timeInterval: totalVisibleDuration, repeats: false) { [weak self] _ in
+            self?.dismiss()
+        }
+        fadeTimer = timer
+        RunLoop.main.add(timer, forMode: .common)
+    }
+
+    func dismiss(immediately: Bool = false) {
+        fadeTimer?.invalidate()
+        fadeTimer = nil
+
+        if immediately {
+            window.orderOut(nil)
+            finishDismissal()
+            return
+        }
+
+        NSAnimationContext.runAnimationGroup({ ctx in
+            ctx.duration = fadeDuration
+            window.animator().alphaValue = 0
+        }, completionHandler: { [weak self] in
+            self?.window.orderOut(nil)
+            self?.finishDismissal()
+        })
+    }
+
+    private func localPoint(from cgPoint: CGPoint) -> CGPoint {
+        let primaryHeight = NSScreen.screens.first?.frame.height ?? screen.frame.height
+        let nsY = primaryHeight - cgPoint.y
+        return CGPoint(x: cgPoint.x - screen.frame.minX, y: nsY - screen.frame.minY)
+    }
+
+    private func localPath(from pathPoints: [GesturePathPoint]) -> [CGPoint] {
+        pathPoints.map { localPoint(from: $0.cgPoint) }
+    }
+
+    private func finishDismissal() {
+        let callback = onDismiss
+        onDismiss = nil
+        callback?()
+    }
+}
+
+private final class MouseGestureOverlayView: NSView {
+    private let theme = MouseGestureOverlayTheme.graffiti
+
+    enum State {
+        case idle
+        case tracking(
+            origin: CGPoint,
+            direction: MouseGestureDirection?,
+            label: String?,
+            style: MouseGestureOverlayStyle,
+            visual: MouseShortcutVisualDefinition?,
+            visualPhase: MouseGestureVisualPhase,
+            shape: GestureShapeLabel?,
+            success: Bool?,
+            path: [CGPoint],
+            progress: CGFloat
+        )
+        case committed(
+            origin: CGPoint,
+            direction: MouseGestureDirection,
+            label: String,
+            success: Bool,
+            style: MouseGestureOverlayStyle,
+            visual: MouseShortcutVisualDefinition?,
+            visualPhase: MouseGestureVisualPhase,
+            shape: GestureShapeLabel?,
+            path: [CGPoint],
+            accessory: MouseGestureAccessory?,
+            accessoryAnimationDuration: TimeInterval
+        )
+    }
+
+    var state: State = .idle {
+        didSet {
+            updateArrowAnimation(from: oldValue, to: state)
+            updateAccessoryAnimation()
+        }
+    }
+    private var accessoryAnimationTimer: Timer?
+    private var accessoryAnimationStartedAt: Date?
+    private var accessoryAnimationDuration: TimeInterval = 0
+    private var arrowAnimationTimer: Timer?
+    private var arrowAnimationStartedAt: Date?
+    private var arrowAnimationDuration: TimeInterval = 0
+    private var committedStartProgress: CGFloat = 0
+    private var accessoryAnimationDelay: TimeInterval = 0
+    private let committedArrowAnimationDuration: TimeInterval = 0.06
+    private let arrowAnimationDelay: TimeInterval = 0.012
+    private let labelRevealThreshold: CGFloat = 0.8
+
+    var replayLeadInDuration: TimeInterval {
+        if committedStartProgress >= labelRevealThreshold {
+            return 0
+        }
+        let remainingProgress = max(0, 1 - committedStartProgress)
+        return arrowAnimationDelay + committedArrowAnimationDuration * remainingProgress
+    }
+
+    override var isFlipped: Bool {
+        false
+    }
+
+    override func viewDidMoveToWindow() {
+        super.viewDidMoveToWindow()
+        if window == nil {
+            arrowAnimationTimer?.invalidate()
+            arrowAnimationTimer = nil
+            accessoryAnimationTimer?.invalidate()
+            accessoryAnimationTimer = nil
+        }
+    }
+
+    override func draw(_ dirtyRect: NSRect) {
+        guard let ctx = NSGraphicsContext.current?.cgContext else { return }
+        ctx.clear(bounds)
+
+        switch state {
+        case .idle:
+            break
+        case .tracking(let origin, let direction, let label, let style, let visual, let visualPhase, let shape, let success, let path, let progress):
+            drawOrigin(at: origin, in: ctx, alpha: 0.88)
+            if path.count > 1 {
+                drawGesturePath(
+                    path,
+                    fallbackOrigin: origin,
+                    direction: direction,
+                    label: label,
+                    success: true,
+                    committed: false,
+                    style: style,
+                    accessory: nil,
+                    progressOverride: progress,
+                    in: ctx
+                )
+                drawVisualPOCIfNeeded(
+                    visual,
+                    phase: visualPhase,
+                    shape: shape,
+                    success: success,
+                    points: path,
+                    label: label,
+                    in: ctx
+                )
+            } else if let direction {
+                drawArrow(
+                    from: origin,
+                    direction: direction,
+                    label: label,
+                    success: true,
+                    committed: false,
+                    style: style,
+                    accessory: nil,
+                    progressOverride: progress,
+                    in: ctx
+                )
+            }
+        case .committed(let origin, let direction, let label, let success, let style, let visual, let visualPhase, let shape, let path, let accessory, _):
+            drawOrigin(at: origin, in: ctx, alpha: 1.0)
+            if path.count > 1 {
+                drawGesturePath(
+                    path,
+                    fallbackOrigin: origin,
+                    direction: direction,
+                    label: label,
+                    success: success,
+                    committed: true,
+                    style: style,
+                    accessory: accessory,
+                    progressOverride: nil,
+                    in: ctx
+                )
+                drawVisualPOCIfNeeded(
+                    visual,
+                    phase: visualPhase,
+                    shape: shape,
+                    success: success,
+                    points: path,
+                    label: label,
+                    in: ctx
+                )
+            } else {
+                drawArrow(
+                    from: origin,
+                    direction: direction,
+                    label: label,
+                    success: success,
+                    committed: true,
+                    style: style,
+                    accessory: accessory,
+                    progressOverride: nil,
+                    in: ctx
+                )
+            }
+        }
+    }
+
+    private func drawOrigin(at point: CGPoint, in ctx: CGContext, alpha: CGFloat) {
+        ctx.setFillColor(NSColor(calibratedRed: 0.48, green: 0.76, blue: 1.0, alpha: alpha * 0.18).cgColor)
+        ctx.fillEllipse(in: CGRect(x: point.x - 18, y: point.y - 18, width: 36, height: 36))
+
+        ctx.setFillColor(NSColor(calibratedRed: 0.62, green: 0.84, blue: 1.0, alpha: alpha * 0.95).cgColor)
+        ctx.fillEllipse(in: CGRect(x: point.x - 5, y: point.y - 5, width: 10, height: 10))
+    }
+
+    private func drawArrow(
+        from origin: CGPoint,
+        direction: MouseGestureDirection,
+        label: String?,
+        success: Bool,
+        committed: Bool,
+        style: MouseGestureOverlayStyle,
+        accessory: MouseGestureAccessory?,
+        progressOverride: CGFloat?,
+        in ctx: CGContext
+    ) {
+        let baseLength: CGFloat = 118
+        let arrowProgress = progressOverride ?? currentArrowProgress(committed: committed)
+        let clampedProgress = min(1, max(0, arrowProgress))
+        let length = baseLength * (committed ? max(0.14, clampedProgress) : (0.34 + 0.66 * clampedProgress))
+        let vector = arrowVector(for: direction, length: length)
+        let end = CGPoint(x: origin.x + vector.x, y: origin.y + vector.y)
+        let accent = success
+            ? NSColor(calibratedRed: 0.45, green: 0.80, blue: 1.0, alpha: 1.0)
+            : NSColor(calibratedRed: 0.98, green: 0.52, blue: 0.42, alpha: 1.0)
+        let strokeAlpha = committed ? 0.92 : (0.48 + 0.44 * clampedProgress)
+        let glowAlpha = committed ? 0.2 : (0.08 + 0.08 * clampedProgress)
+        let metrics = arrowMetrics(for: style)
+
+        ctx.saveGState()
+        ctx.setLineCap(.round)
+
+        let glowPath = CGMutablePath()
+        glowPath.move(to: origin)
+        glowPath.addLine(to: end)
+        ctx.addPath(glowPath)
+        ctx.setLineWidth(metrics.glowWidth)
+        ctx.setStrokeColor(accent.withAlphaComponent(glowAlpha).cgColor)
+        ctx.strokePath()
+
+        let linePath = CGMutablePath()
+        linePath.move(to: origin)
+        linePath.addLine(to: end)
+        ctx.addPath(linePath)
+        ctx.setLineWidth(metrics.lineWidth)
+        ctx.setStrokeColor(accent.withAlphaComponent(strokeAlpha).cgColor)
+        ctx.strokePath()
+
+        drawArrowHead(at: end, direction: direction, color: accent, size: metrics.headSize)
+        if let label, (!committed || clampedProgress >= labelRevealThreshold) {
+            drawLabel(label, from: origin, to: end, direction: direction, color: accent)
+        }
+        if committed, let accessory, clampedProgress >= labelRevealThreshold {
+            drawAccessory(accessory, from: origin, to: end, direction: direction, color: accent, in: ctx)
+        }
+        ctx.restoreGState()
+    }
+
+    private func drawGesturePath(
+        _ points: [CGPoint],
+        fallbackOrigin: CGPoint,
+        direction: MouseGestureDirection?,
+        label: String?,
+        success: Bool,
+        committed: Bool,
+        style: MouseGestureOverlayStyle,
+        accessory: MouseGestureAccessory?,
+        progressOverride: CGFloat?,
+        in ctx: CGContext
+    ) {
+        guard points.count > 1 else { return }
+        let accent = success ? theme.accent : theme.failure
+        let stroke = success ? theme.graphite : theme.failure
+        let metrics = arrowMetrics(for: style)
+        let pathProgress = progressOverride ?? currentArrowProgress(committed: committed)
+        let clampedProgress = min(1, max(0, pathProgress))
+        let strokeAlpha = committed ? 0.92 : (0.48 + 0.44 * clampedProgress)
+        let glowAlpha = committed ? 0.28 : (0.12 + 0.12 * clampedProgress)
+        let visiblePoints = visiblePathPoints(points, progress: committed ? clampedProgress : 1)
+        guard visiblePoints.count > 1 else { return }
+
+        let path = smoothedGesturePath(from: visiblePoints)
+
+        ctx.saveGState()
+        ctx.setLineCap(.round)
+        ctx.setLineJoin(.round)
+
+        drawGestureGuideDots(around: visiblePoints, accent: accent, in: ctx)
+
+        ctx.addPath(path)
+        ctx.setLineWidth(metrics.glowWidth + 10)
+        ctx.setStrokeColor(theme.graphiteDark.withAlphaComponent(committed ? 0.44 : 0.30).cgColor)
+        ctx.strokePath()
+
+        ctx.addPath(path)
+        ctx.setLineWidth(metrics.glowWidth)
+        ctx.setStrokeColor(accent.withAlphaComponent(glowAlpha).cgColor)
+        ctx.strokePath()
+
+        ctx.addPath(path)
+        ctx.setLineWidth(metrics.lineWidth)
+        ctx.setStrokeColor(stroke.withAlphaComponent(strokeAlpha).cgColor)
+        ctx.strokePath()
+
+        ctx.addPath(path)
+        ctx.setLineWidth(max(1, metrics.lineWidth * 0.28))
+        ctx.setStrokeColor((success ? theme.highlight : accent).withAlphaComponent(success ? strokeAlpha * 0.62 : strokeAlpha).cgColor)
+        ctx.strokePath()
+
+        let end = visiblePoints.last ?? fallbackOrigin
+        let resolvedDirection = direction ?? pathDirection(from: visiblePoints)
+        if let resolvedDirection {
+            drawArrowHead(at: end, direction: resolvedDirection, color: stroke, size: metrics.headSize)
+            if let label, (!committed || clampedProgress >= labelRevealThreshold) {
+                drawLabel(label, from: fallbackOrigin, to: end, direction: resolvedDirection, color: accent)
+            }
+            if committed, let accessory, clampedProgress >= labelRevealThreshold {
+                drawAccessory(accessory, from: fallbackOrigin, to: end, direction: resolvedDirection, color: accent, in: ctx)
+            }
+        }
+        ctx.restoreGState()
+    }
+
+    private func drawGestureGuideDots(around points: [CGPoint], accent: NSColor, in ctx: CGContext) {
+        guard !points.isEmpty else { return }
+        let minX = (points.map(\.x).min() ?? 0) - 34
+        let maxX = (points.map(\.x).max() ?? 0) + 34
+        let minY = (points.map(\.y).min() ?? 0) - 34
+        let maxY = (points.map(\.y).max() ?? 0) + 34
+        let spacing: CGFloat = 34
+        let dotRadius: CGFloat = 2.2
+        let startX = floor(minX / spacing) * spacing
+        let startY = floor(minY / spacing) * spacing
+
+        var y = startY
+        while y <= maxY {
+            var x = startX
+            while x <= maxX {
+                let point = CGPoint(x: x, y: y)
+                let distance = nearestDistance(from: point, to: points)
+                let closeness = max(0, 1 - min(distance / 96, 1))
+                let alpha = 0.08 + closeness * 0.20
+                let radius = dotRadius + closeness * 1.2
+                ctx.setFillColor(accent.withAlphaComponent(alpha).cgColor)
+                ctx.fillEllipse(in: CGRect(x: x - radius, y: y - radius, width: radius * 2, height: radius * 2))
+                x += spacing
+            }
+            y += spacing
+        }
+    }
+
+    private func nearestDistance(from point: CGPoint, to points: [CGPoint]) -> CGFloat {
+        points.reduce(CGFloat.greatestFiniteMagnitude) { nearest, candidate in
+            let dx = point.x - candidate.x
+            let dy = point.y - candidate.y
+            return min(nearest, sqrt(dx * dx + dy * dy))
+        }
+    }
+
+    private func drawVisualPOCIfNeeded(
+        _ visual: MouseShortcutVisualDefinition?,
+        phase: MouseGestureVisualPhase,
+        shape: GestureShapeLabel?,
+        success: Bool?,
+        points: [CGPoint],
+        label: String?,
+        in ctx: CGContext
+    ) {
+        guard let visual, visual.isLottiePOC, let end = points.last else { return }
+        let marker = visual.marker(phase: phase.rawValue, shape: shape, success: success) ?? fallbackMarker(phase: phase, success: success)
+        let previous = points.dropLast().last ?? end
+        let velocity = CGPoint(x: end.x - previous.x, y: end.y - previous.y)
+        let speed = min(1, sqrt(velocity.x * velocity.x + velocity.y * velocity.y) / 42)
+        let anchor = CGPoint(x: end.x + 28, y: end.y + 22 - speed * 8)
+        drawLottieCatPOC(marker: marker, at: anchor, velocity: velocity, label: label, in: ctx)
+    }
+
+    private func fallbackMarker(phase: MouseGestureVisualPhase, success: Bool?) -> String {
+        switch phase {
+        case .started:
+            return "curious"
+        case .updated:
+            return "follow"
+        case .recognized:
+            return "pounce"
+        case .completed:
+            return success == false ? "confused" : "celebrate"
+        }
+    }
+
+    private func drawLottieCatPOC(
+        marker: String,
+        at center: CGPoint,
+        velocity: CGPoint,
+        label: String?,
+        in ctx: CGContext
+    ) {
+        let mood = marker.lowercased()
+        let bodyColor = NSColor(calibratedRed: 0.13, green: 0.14, blue: 0.16, alpha: 0.92)
+        let faceColor = theme.highlight.withAlphaComponent(0.94)
+        let accent = mood.contains("confused") ? theme.failure : theme.accent
+        let tilt = max(-0.34, min(0.34, velocity.x / 160))
+        let hop: CGFloat = mood.contains("pounce") || mood.contains("celebrate") ? 7 : 0
+        let headCenter = CGPoint(x: center.x, y: center.y + hop)
+        let headRadius: CGFloat = mood.contains("pounce") ? 16 : 14
+
+        ctx.saveGState()
+        ctx.translateBy(x: headCenter.x, y: headCenter.y)
+        ctx.rotate(by: tilt)
+        ctx.translateBy(x: -headCenter.x, y: -headCenter.y)
+
+        ctx.setFillColor(theme.graphiteDark.withAlphaComponent(0.24).cgColor)
+        ctx.fillEllipse(in: CGRect(x: headCenter.x - 22, y: headCenter.y - 18, width: 44, height: 36))
+
+        let leftEar = CGMutablePath()
+        leftEar.move(to: CGPoint(x: headCenter.x - 12, y: headCenter.y + 9))
+        leftEar.addLine(to: CGPoint(x: headCenter.x - 7, y: headCenter.y + 25))
+        leftEar.addLine(to: CGPoint(x: headCenter.x - 1, y: headCenter.y + 11))
+        leftEar.closeSubpath()
+        ctx.addPath(leftEar)
+        ctx.setFillColor(bodyColor.cgColor)
+        ctx.fillPath()
+
+        let rightEar = CGMutablePath()
+        rightEar.move(to: CGPoint(x: headCenter.x + 12, y: headCenter.y + 9))
+        rightEar.addLine(to: CGPoint(x: headCenter.x + 7, y: headCenter.y + 25))
+        rightEar.addLine(to: CGPoint(x: headCenter.x + 1, y: headCenter.y + 11))
+        rightEar.closeSubpath()
+        ctx.addPath(rightEar)
+        ctx.setFillColor(bodyColor.cgColor)
+        ctx.fillPath()
+
+        ctx.setFillColor(bodyColor.cgColor)
+        ctx.fillEllipse(in: CGRect(x: headCenter.x - headRadius, y: headCenter.y - headRadius, width: headRadius * 2, height: headRadius * 2))
+        ctx.setStrokeColor(accent.withAlphaComponent(0.72).cgColor)
+        ctx.setLineWidth(1.4)
+        ctx.strokeEllipse(in: CGRect(x: headCenter.x - headRadius, y: headCenter.y - headRadius, width: headRadius * 2, height: headRadius * 2))
+
+        let eyeY = headCenter.y + 2
+        let blink = mood.contains("pounce") || mood.contains("celebrate")
+        drawCatEye(at: CGPoint(x: headCenter.x - 5, y: eyeY), blink: blink, color: faceColor, in: ctx)
+        drawCatEye(at: CGPoint(x: headCenter.x + 5, y: eyeY), blink: blink, color: faceColor, in: ctx)
+
+        ctx.setStrokeColor(faceColor.withAlphaComponent(0.82).cgColor)
+        ctx.setLineWidth(1)
+        let mouth = CGMutablePath()
+        mouth.move(to: CGPoint(x: headCenter.x - 3, y: headCenter.y - 5))
+        mouth.addQuadCurve(to: CGPoint(x: headCenter.x + 3, y: headCenter.y - 5), control: CGPoint(x: headCenter.x, y: headCenter.y - (mood.contains("confused") ? 2 : 8)))
+        ctx.addPath(mouth)
+        ctx.strokePath()
+
+        if mood.contains("celebrate"), let label {
+            drawCatToast(label, near: CGPoint(x: headCenter.x + 18, y: headCenter.y + 18), color: accent)
+        }
+
+        ctx.restoreGState()
+    }
+
+    private func drawCatEye(at point: CGPoint, blink: Bool, color: NSColor, in ctx: CGContext) {
+        ctx.setStrokeColor(color.cgColor)
+        ctx.setFillColor(color.cgColor)
+        if blink {
+            ctx.setLineWidth(1.4)
+            let path = CGMutablePath()
+            path.move(to: CGPoint(x: point.x - 2.4, y: point.y))
+            path.addLine(to: CGPoint(x: point.x + 2.4, y: point.y))
+            ctx.addPath(path)
+            ctx.strokePath()
+        } else {
+            ctx.fillEllipse(in: CGRect(x: point.x - 1.7, y: point.y - 1.7, width: 3.4, height: 3.4))
+        }
+    }
+
+    private func drawCatToast(_ label: String, near point: CGPoint, color: NSColor) {
+        let shortLabel = label.replacingOccurrences(of: " Focused", with: "!")
+        let font = NSFont.monospacedSystemFont(ofSize: 9, weight: .bold)
+        let attributed = NSAttributedString(
+            string: shortLabel,
+            attributes: [
+                .font: font,
+                .foregroundColor: theme.highlight.withAlphaComponent(0.96),
+            ]
+        )
+        let size = attributed.size()
+        let rect = CGRect(x: point.x, y: point.y, width: size.width + 12, height: size.height + 7)
+        let bubble = NSBezierPath(roundedRect: rect, xRadius: 8, yRadius: 8)
+        theme.graphiteDark.withAlphaComponent(0.72).setFill()
+        bubble.fill()
+        color.withAlphaComponent(0.5).setStroke()
+        bubble.lineWidth = 1
+        bubble.stroke()
+        attributed.draw(in: CGRect(x: rect.minX + 6, y: rect.minY + 3.5, width: size.width, height: size.height))
+    }
+
+    private func smoothedGesturePath(from points: [CGPoint]) -> CGPath {
+        let path = CGMutablePath()
+        guard let first = points.first else { return path }
+        path.move(to: first)
+
+        guard points.count > 2 else {
+            if let last = points.last {
+                path.addLine(to: last)
+            }
+            return path
+        }
+
+        for index in 0..<(points.count - 1) {
+            let previous = points[max(index - 1, 0)]
+            let current = points[index]
+            let next = points[index + 1]
+            let nextNext = points[min(index + 2, points.count - 1)]
+            let tension: CGFloat = 0.34
+            let control1 = CGPoint(
+                x: current.x + (next.x - previous.x) * tension,
+                y: current.y + (next.y - previous.y) * tension
+            )
+            let control2 = CGPoint(
+                x: next.x - (nextNext.x - current.x) * tension,
+                y: next.y - (nextNext.y - current.y) * tension
+            )
+            path.addCurve(to: next, control1: control1, control2: control2)
+        }
+        return path
+    }
+
+    private func visiblePathPoints(_ points: [CGPoint], progress: CGFloat) -> [CGPoint] {
+        guard progress < 1, points.count > 2 else { return points }
+        let clamped = min(1, max(0.04, progress))
+        let count = max(2, Int(ceil(CGFloat(points.count) * clamped)))
+        return Array(points.prefix(count))
+    }
+
+    private func pathDirection(from points: [CGPoint]) -> MouseGestureDirection? {
+        guard points.count >= 2 else { return nil }
+        let window = points.suffix(min(6, points.count))
+        guard let first = window.first, let last = window.last else { return nil }
+        let delta = CGPoint(x: last.x - first.x, y: last.y - first.y)
+        return MouseGestureController.resolveDirection(delta: delta, threshold: 4, axisBias: 1.0)
+    }
+
+    private func arrowMetrics(for style: MouseGestureOverlayStyle) -> (lineWidth: CGFloat, glowWidth: CGFloat, headSize: CGFloat) {
+        switch style {
+        case .thinLine:
+            return (2.4, 7, 10)
+        case .thickLine:
+            return (8.5, 20, 18)
+        case .drawing:
+            return (5, 16, 15)
+        }
+    }
+
+    private func drawArrowHead(at end: CGPoint, direction: MouseGestureDirection, color: NSColor, size: CGFloat) {
+        let path = NSBezierPath()
+
+        switch direction {
+        case .left:
+            path.move(to: CGPoint(x: end.x - size, y: end.y))
+            path.line(to: CGPoint(x: end.x + size * 0.2, y: end.y + size * 0.72))
+            path.line(to: CGPoint(x: end.x + size * 0.2, y: end.y - size * 0.72))
+        case .right:
+            path.move(to: CGPoint(x: end.x + size, y: end.y))
+            path.line(to: CGPoint(x: end.x - size * 0.2, y: end.y + size * 0.72))
+            path.line(to: CGPoint(x: end.x - size * 0.2, y: end.y - size * 0.72))
+        case .up:
+            path.move(to: CGPoint(x: end.x, y: end.y + size))
+            path.line(to: CGPoint(x: end.x - size * 0.72, y: end.y - size * 0.2))
+            path.line(to: CGPoint(x: end.x + size * 0.72, y: end.y - size * 0.2))
+        case .down:
+            path.move(to: CGPoint(x: end.x, y: end.y - size))
+            path.line(to: CGPoint(x: end.x - size * 0.72, y: end.y + size * 0.2))
+            path.line(to: CGPoint(x: end.x + size * 0.72, y: end.y + size * 0.2))
+        }
+
+        path.close()
+        color.withAlphaComponent(0.96).setFill()
+        path.fill()
+    }
+
+    private func drawLabel(_ label: String, from origin: CGPoint, to end: CGPoint, direction: MouseGestureDirection, color: NSColor) {
+        let display = labelComponents(for: label)
+        let titleFont = NSFont.systemFont(ofSize: 15, weight: .heavy)
+        let kickerFont = NSFont.monospacedSystemFont(ofSize: 8, weight: .bold)
+        let titleAttributes: [NSAttributedString.Key: Any] = [
+            .font: titleFont,
+            .foregroundColor: theme.highlight.withAlphaComponent(0.98),
+        ]
+        let kickerAttributes: [NSAttributedString.Key: Any] = [
+            .font: kickerFont,
+            .foregroundColor: color.withAlphaComponent(0.84),
+        ]
+        let title = NSAttributedString(string: display.title, attributes: titleAttributes)
+        let kicker = display.kicker.map { NSAttributedString(string: $0, attributes: kickerAttributes) }
+        let titleSize = title.size()
+        let kickerSize = kicker?.size() ?? .zero
+        let gap: CGFloat = kicker == nil ? 0 : 2
+        let textSize = CGSize(
+            width: max(titleSize.width, kickerSize.width),
+            height: titleSize.height + gap + kickerSize.height
+        )
+        let paddingX: CGFloat = 14
+        let paddingY: CGFloat = 8
+        let tickWidth: CGFloat = 6
+        let bubbleSize = CGSize(
+            width: textSize.width + paddingX * 2 + tickWidth,
+            height: textSize.height + paddingY * 2
+        )
+        let bubbleOrigin = labelOrigin(from: origin, to: end, direction: direction, bubbleSize: bubbleSize)
+        let rect = CGRect(
+            x: bubbleOrigin.x,
+            y: bubbleOrigin.y,
+            width: bubbleSize.width,
+            height: bubbleSize.height
+        )
+
+        ctxSaveForLabel(rotationDegrees: -4, around: CGPoint(x: rect.midX, y: rect.midY))
+
+        let shadowRect = rect.insetBy(dx: -5, dy: -5)
+        let shadow = NSBezierPath(roundedRect: shadowRect, xRadius: 15, yRadius: 15)
+        theme.graphiteDark.withAlphaComponent(0.24).setFill()
+        shadow.fill()
+
+        let bg = NSBezierPath(roundedRect: rect, xRadius: 13, yRadius: 13)
+        theme.graphiteDark.withAlphaComponent(0.82).setFill()
+        bg.fill()
+
+        let border = NSBezierPath(roundedRect: rect, xRadius: 13, yRadius: 13)
+        theme.graphite.withAlphaComponent(0.46).setStroke()
+        border.lineWidth = 1.2
+        border.stroke()
+
+        let tickRect = CGRect(
+            x: rect.minX + 8,
+            y: rect.midY - 7,
+            width: 3,
+            height: 14
+        )
+        let tick = NSBezierPath(roundedRect: tickRect, xRadius: 1.5, yRadius: 1.5)
+        color.withAlphaComponent(0.82).setFill()
+        tick.fill()
+
+        let titleRect = CGRect(
+            x: rect.minX + paddingX + tickWidth,
+            y: rect.minY + paddingY + kickerSize.height + gap,
+            width: titleSize.width,
+            height: titleSize.height
+        )
+        title.draw(in: titleRect)
+
+        if let kicker {
+            let kickerRect = CGRect(
+                x: rect.minX + paddingX + tickWidth + 1,
+                y: rect.minY + paddingY,
+                width: kickerSize.width,
+                height: kickerSize.height
+            )
+            kicker.draw(in: kickerRect)
+        }
+
+        NSGraphicsContext.current?.cgContext.restoreGState()
+    }
+
+    private func labelComponents(for label: String) -> (title: String, kicker: String?) {
+        if label.hasSuffix(" Focused") {
+            return (String(label.dropLast(" Focused".count)), "FOCUSED")
+        }
+        return (label, nil)
+    }
+
+    private func ctxSaveForLabel(rotationDegrees: CGFloat, around center: CGPoint) {
+        guard let ctx = NSGraphicsContext.current?.cgContext else { return }
+        ctx.saveGState()
+        ctx.translateBy(x: center.x, y: center.y)
+        ctx.rotate(by: rotationDegrees * .pi / 180)
+        ctx.translateBy(x: -center.x, y: -center.y)
+    }
+
+    private func labelOrigin(from origin: CGPoint, to end: CGPoint, direction: MouseGestureDirection, bubbleSize: CGSize) -> CGPoint {
+        let midpoint = CGPoint(x: (origin.x + end.x) / 2, y: (origin.y + end.y) / 2)
+        let proposedOrigin: CGPoint
+
+        switch direction {
+        case .left, .right:
+            proposedOrigin = CGPoint(x: midpoint.x - bubbleSize.width / 2, y: midpoint.y + 18)
+        case .up, .down:
+            proposedOrigin = CGPoint(x: midpoint.x + 20, y: midpoint.y - bubbleSize.height / 2)
+        }
+
+        let minX: CGFloat = 12
+        let minY: CGFloat = 12
+        let maxX = max(minX, bounds.width - bubbleSize.width - 12)
+        let maxY = max(minY, bounds.height - bubbleSize.height - 12)
+
+        return CGPoint(
+            x: min(max(proposedOrigin.x, minX), maxX),
+            y: min(max(proposedOrigin.y, minY), maxY)
+        )
+    }
+
+    private func arrowVector(for direction: MouseGestureDirection, length: CGFloat) -> CGPoint {
+        switch direction {
+        case .left:
+            return CGPoint(x: -length, y: 0)
+        case .right:
+            return CGPoint(x: length, y: 0)
+        case .up:
+            return CGPoint(x: 0, y: length)
+        case .down:
+            return CGPoint(x: 0, y: -length)
+        }
+    }
+
+    private func updateArrowAnimation(from oldState: State, to newState: State) {
+        let oldDirection = stateDirection(from: oldState)
+        let newDirection = stateDirection(from: newState)
+        let oldCommitted = isCommitted(state: oldState)
+        let newCommitted = isCommitted(state: newState)
+
+        if newCommitted, newDirection != nil {
+            let shouldRestart = oldDirection != newDirection || !oldCommitted
+            if shouldRestart {
+                let previousProgress = trackingProgress(from: oldState)
+                committedStartProgress = max(0, min(1, previousProgress ?? 0))
+                if committedStartProgress >= 0.94 {
+                    arrowAnimationTimer?.invalidate()
+                    arrowAnimationTimer = nil
+                    arrowAnimationStartedAt = nil
+                    arrowAnimationDuration = 0
+                    committedStartProgress = 1
+                } else {
+                    startArrowAnimation(duration: committedArrowAnimationDuration)
+                }
+            }
+            return
+        }
+
+        arrowAnimationTimer?.invalidate()
+        arrowAnimationTimer = nil
+        arrowAnimationStartedAt = nil
+        arrowAnimationDuration = 0
+        committedStartProgress = 0
+    }
+
+    private func startArrowAnimation(duration: TimeInterval) {
+        arrowAnimationTimer?.invalidate()
+        arrowAnimationStartedAt = Date()
+        arrowAnimationDuration = duration
+
+        let timer = Timer(timeInterval: 1.0 / 60.0, repeats: true) { [weak self] timer in
+            guard let self else {
+                timer.invalidate()
+                return
+            }
+            self.needsDisplay = true
+            let elapsed = Date().timeIntervalSince(self.arrowAnimationStartedAt ?? Date())
+            if elapsed >= self.replayLeadInDuration {
+                timer.invalidate()
+                self.arrowAnimationTimer = nil
+            }
+        }
+        arrowAnimationTimer = timer
+        RunLoop.main.add(timer, forMode: .common)
+    }
+
+    private func currentArrowProgress(committed: Bool) -> CGFloat {
+        guard committed,
+              let startedAt = arrowAnimationStartedAt,
+              arrowAnimationDuration > 0 else {
+            return committed ? (committedStartProgress > 0 ? committedStartProgress : 1) : 1
+        }
+
+        let delayedElapsed = Date().timeIntervalSince(startedAt) - arrowAnimationDelay
+        guard delayedElapsed > 0 else { return committedStartProgress }
+        let normalized = min(1, max(0, delayedElapsed / arrowAnimationDuration))
+        let animated = easeOut(normalized)
+        return committedStartProgress + (1 - committedStartProgress) * animated
+    }
+
+    private func updateAccessoryAnimation() {
+        accessoryAnimationTimer?.invalidate()
+        accessoryAnimationTimer = nil
+        accessoryAnimationStartedAt = nil
+        accessoryAnimationDuration = 0
+        accessoryAnimationDelay = 0
+
+        if case .committed(_, _, _, _, _, _, _, _, _, let accessory, let duration) = state, accessory != nil {
+            accessoryAnimationStartedAt = Date()
+            accessoryAnimationDuration = duration
+            accessoryAnimationDelay = replayLeadInDuration * 0.86
+            let timer = Timer(timeInterval: 1.0 / 60.0, repeats: true) { [weak self] timer in
+                guard let self else {
+                    timer.invalidate()
+                    return
+                }
+                self.needsDisplay = true
+                let elapsed = Date().timeIntervalSince(self.accessoryAnimationStartedAt ?? Date())
+                if elapsed >= self.accessoryAnimationDelay + self.accessoryAnimationDuration {
+                    timer.invalidate()
+                    self.accessoryAnimationTimer = nil
+                }
+            }
+            accessoryAnimationTimer = timer
+            RunLoop.main.add(timer, forMode: .common)
+        }
+    }
+
+    private func drawAccessory(
+        _ accessory: MouseGestureAccessory,
+        from origin: CGPoint,
+        to end: CGPoint,
+        direction: MouseGestureDirection,
+        color: NSColor,
+        in ctx: CGContext
+    ) {
+        guard let startedAt = accessoryAnimationStartedAt, accessoryAnimationDuration > 0 else { return }
+        let delayedElapsed = Date().timeIntervalSince(startedAt) - accessoryAnimationDelay
+        guard delayedElapsed > 0 else { return }
+        let progress = min(1, max(0, delayedElapsed / accessoryAnimationDuration))
+        let scale = 0.82 + 0.18 * easeOut(progress)
+        let fadeStart: CGFloat = 0.58
+        let alphaProgress = progress <= fadeStart ? 1 : 1 - ((progress - fadeStart) / (1 - fadeStart))
+        let alpha = max(0, min(1, alphaProgress))
+        guard alpha > 0 else { return }
+
+        let center = accessoryCenter(from: end, direction: direction)
+        let badgeDiameter: CGFloat = 34 * scale
+        let badgeRect = CGRect(
+            x: center.x - badgeDiameter / 2,
+            y: center.y - badgeDiameter / 2,
+            width: badgeDiameter,
+            height: badgeDiameter
+        )
+
+        let badge = NSBezierPath(ovalIn: badgeRect)
+        NSColor.black.withAlphaComponent(0.46 * alpha).setFill()
+        badge.fill()
+
+        color.withAlphaComponent(0.32 * alpha).setStroke()
+        badge.lineWidth = 1
+        badge.stroke()
+
+        switch accessory {
+        case .mic:
+            drawMicGlyph(in: badgeRect.insetBy(dx: badgeDiameter * 0.26, dy: badgeDiameter * 0.2), color: color.withAlphaComponent(0.96 * alpha), in: ctx)
+        }
+    }
+
+    private func accessoryCenter(from end: CGPoint, direction: MouseGestureDirection) -> CGPoint {
+        switch direction {
+        case .up:
+            return CGPoint(x: end.x, y: end.y + 34)
+        case .down:
+            return CGPoint(x: end.x, y: end.y - 34)
+        case .left:
+            return CGPoint(x: end.x - 34, y: end.y)
+        case .right:
+            return CGPoint(x: end.x + 34, y: end.y)
+        }
+    }
+
+    private func drawMicGlyph(in rect: CGRect, color: NSColor, in ctx: CGContext) {
+        ctx.saveGState()
+        color.setStroke()
+        color.withAlphaComponent(0.22).setFill()
+
+        let bodyWidth = rect.width * 0.42
+        let bodyHeight = rect.height * 0.54
+        let bodyRect = CGRect(
+            x: rect.midX - bodyWidth / 2,
+            y: rect.maxY - bodyHeight,
+            width: bodyWidth,
+            height: bodyHeight
+        )
+        let body = NSBezierPath(roundedRect: bodyRect, xRadius: bodyWidth / 2, yRadius: bodyWidth / 2)
+        body.lineWidth = 1.6
+        body.fill()
+        body.stroke()
+
+        let stem = NSBezierPath()
+        stem.move(to: CGPoint(x: rect.midX, y: bodyRect.minY))
+        stem.line(to: CGPoint(x: rect.midX, y: rect.minY + rect.height * 0.24))
+        stem.lineWidth = 1.8
+        stem.lineCapStyle = .round
+        stem.stroke()
+
+        let arcRect = CGRect(
+            x: rect.midX - rect.width * 0.28,
+            y: rect.minY + rect.height * 0.18,
+            width: rect.width * 0.56,
+            height: rect.height * 0.42
+        )
+        let arc = NSBezierPath()
+        arc.appendArc(
+            withCenter: CGPoint(x: arcRect.midX, y: arcRect.midY + arcRect.height * 0.08),
+            radius: arcRect.width / 2,
+            startAngle: 200,
+            endAngle: -20,
+            clockwise: true
+        )
+        arc.lineWidth = 1.6
+        arc.lineCapStyle = .round
+        arc.stroke()
+
+        let base = NSBezierPath()
+        base.move(to: CGPoint(x: rect.midX - rect.width * 0.22, y: rect.minY + rect.height * 0.14))
+        base.line(to: CGPoint(x: rect.midX + rect.width * 0.22, y: rect.minY + rect.height * 0.14))
+        base.lineWidth = 1.6
+        base.lineCapStyle = .round
+        base.stroke()
+        ctx.restoreGState()
+    }
+
+    private func easeOut(_ t: CGFloat) -> CGFloat {
+        1 - pow(1 - t, 3)
+    }
+
+    private func stateDirection(from state: State) -> MouseGestureDirection? {
+        switch state {
+        case .idle:
+            return nil
+        case .tracking(_, let direction, _, _, _, _, _, _, _, _):
+            return direction
+        case .committed(_, let direction, _, _, _, _, _, _, _, _, _):
+            return direction
+        }
+    }
+
+    private func isCommitted(state: State) -> Bool {
+        if case .committed = state {
+            return true
+        }
+        return false
+    }
+
+    private func trackingProgress(from state: State) -> CGFloat? {
+        if case .tracking(_, _, _, _, _, _, _, _, _, let progress) = state {
+            return progress
+        }
+        return nil
+    }
+}