@lattices/cli 0.4.1 → 0.4.5

package/app/Sources/MouseFinder.swift

@@ -1,23 +1,78 @@
 import AppKit
 import CoreGraphics
 
-/// Locates the mouse cursor with an animated sonar pulse overlay.
-/// "Find" shows rings at the current cursor position.
-/// "Summon" warps the cursor to screen center (or a given point).
+private enum SpotlightConfig {
+    static let overlayAlpha: CGFloat = 0.75
+    static let dimAlpha: CGFloat = 0.85
+    static let spotlightRadius: CGFloat = 200
+    static let sonarDelay: TimeInterval = 1.0
+    static let totalDuration: TimeInterval = 2.5
+    static let fadeInDuration: TimeInterval = 0.15
+    static let fadeOutDuration: TimeInterval = 0.4
+    static let accentColor = NSColor(calibratedRed: 0.4, green: 0.7, blue: 1.0, alpha: 1.0)
+}
+
+private struct DotMatrixConfig {
+    var dotRadius: CGFloat = 2.2
+    var dotSpacing: CGFloat = 6.0
+    var arrowCols: Int = 13
+    var arrowRows: Int = 7   // must be odd
+
+    static let shared: DotMatrixConfig = {
+        let path = NSHomeDirectory() + "/.lattices/mouse-finder.json"
+        guard FileManager.default.fileExists(atPath: path),
+              let data = try? Data(contentsOf: URL(fileURLWithPath: path)),
+              let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any]
+        else { return DotMatrixConfig() }
+
+        var config = DotMatrixConfig()
+        if let v = json["dotRadius"] as? Double { config.dotRadius = CGFloat(v) }
+        if let v = json["dotSpacing"] as? Double { config.dotSpacing = CGFloat(v) }
+        if let v = json["arrowCols"] as? Int { config.arrowCols = max(3, v) }
+        if let v = json["arrowRows"] as? Int { config.arrowRows = max(3, v | 1) }
+        return config
+    }()
+
+    func generatePattern() -> [(col: Int, row: Int)] {
+        let center = arrowRows / 2
+        let shaftHalf = center / 2
+        var dots: [(Int, Int)] = []
+
+        for r in 0..<arrowRows {
+            let d = abs(r - center)
+            if d <= shaftHalf {
+                for c in 0...(arrowCols - 1 - d) { dots.append((c, r)) }
+            } else {
+                let headTip = arrowCols - 1 - d
+                let headStart = max(0, headTip - 1)
+                for c in headStart...headTip { dots.append((c, r)) }
+            }
+        }
+        return dots
+    }
+}
+
+/// Locates the mouse cursor with a spotlight + sonar pulse effect.
+/// Dims all screens, spotlights the cursor area, shows directional arrows on off-screens,
+/// then plays sonar rings on top.
 final class MouseFinder {
     static let shared = MouseFinder()
 
     private var overlayWindows: [NSWindow] = []
+    private var sonarWindows: [NSWindow] = []
     private var dismissTimer: Timer?
     private var animationTimer: Timer?
+    private var sonarDelayTimer: Timer?
     private var animationStart: CFTimeInterval = 0
     private let animationDuration: CFTimeInterval = 1.5
+    private var globalEventMonitor: Any?
+    private var localEventMonitor: Any?
 
     // MARK: - Find (highlight current position)
 
     func find() {
         let pos = NSEvent.mouseLocation
-        showSonar(at: pos)
+        showSpotlight(at: pos)
     }
 
     // MARK: - Summon (warp to center of the screen the mouse is on, or a specific point)
@@ -32,30 +87,90 @@ final class MouseFinder {
             target = NSPoint(x: frame.midX, y: frame.midY)
         }
 
-        // CGWarpMouseCursorPosition uses top-left origin
         let primaryHeight = NSScreen.screens.first?.frame.height ?? 0
         let cgPoint = CGPoint(x: target.x, y: primaryHeight - target.y)
         CGWarpMouseCursorPosition(cgPoint)
-        // Re-associate mouse with cursor position after warp
         CGAssociateMouseAndMouseCursorPosition(1)
 
-        showSonar(at: target)
+        showSpotlight(at: target, mode: .summon)
     }
 
-    // MARK: - Sonar Animation
+    // MARK: - Spotlight Effect
 
-    private func showSonar(at nsPoint: NSPoint) {
+    private func showSpotlight(at nsPoint: NSPoint, mode: SpotlightMode = .find) {
         dismiss()
 
         let screens = NSScreen.screens
         guard !screens.isEmpty else { return }
 
+        let cursorScreen = screens.first(where: { $0.frame.contains(nsPoint) }) ?? screens[0]
+        let otherScreens = screens.filter { $0 !== cursorScreen }
+        let windowLevel = NSWindow.Level(rawValue: Int(CGWindowLevelForKey(.maximumWindow)))
+
+        // Spotlight overlay on cursor screen
+        let localCursor = NSPoint(
+            x: nsPoint.x - cursorScreen.frame.origin.x,
+            y: nsPoint.y - cursorScreen.frame.origin.y
+        )
+        let spotlightWindow = makeOverlayWindow(frame: cursorScreen.frame, level: windowLevel)
+        spotlightWindow.contentView = SpotlightView(
+            frame: NSRect(origin: .zero, size: cursorScreen.frame.size),
+            cursorPoint: localCursor,
+            mode: mode
+        )
+        overlayWindows.append(spotlightWindow)
+
+        // Dim overlays with directional arrows on other screens
+        for screen in otherScreens {
+            let screenCenter = NSPoint(
+                x: screen.frame.midX,
+                y: screen.frame.midY
+            )
+            let angle = atan2(nsPoint.y - screenCenter.y, nsPoint.x - screenCenter.x)
+
+            let dimWindow = makeOverlayWindow(frame: screen.frame, level: windowLevel)
+            dimWindow.contentView = DimOverlayView(
+                frame: NSRect(origin: .zero, size: screen.frame.size),
+                cursorAngle: angle
+            )
+            overlayWindows.append(dimWindow)
+        }
+
+        // Fade all in
+        for window in overlayWindows {
+            window.alphaValue = 0
+            window.orderFrontRegardless()
+            NSAnimationContext.runAnimationGroup { ctx in
+                ctx.duration = SpotlightConfig.fadeInDuration
+                window.animator().alphaValue = 1.0
+            }
+        }
+
+        installEventMonitors()
+
+        // Start sonar after delay
+        sonarDelayTimer = Timer.scheduledTimer(withTimeInterval: SpotlightConfig.sonarDelay, repeats: false) { [weak self] _ in
+            self?.showSonar(at: nsPoint)
+        }
+
+        // Auto-dismiss
+        dismissTimer = Timer.scheduledTimer(withTimeInterval: SpotlightConfig.totalDuration, repeats: false) { [weak self] _ in
+            self?.fadeOut()
+        }
+    }
+
+    // MARK: - Sonar Animation (plays on top of spotlight)
+
+    private func showSonar(at nsPoint: NSPoint) {
+        let screens = NSScreen.screens
+        guard !screens.isEmpty else { return }
+
         let ringCount = 3
         let maxRadius: CGFloat = 120
         let totalSize = maxRadius * 2 + 20
+        let sonarLevel = NSWindow.Level(rawValue: Int(CGWindowLevelForKey(.maximumWindow)) + 1)
 
         for screen in screens {
-            // Only show on screens near the cursor
             let extendedBounds = screen.frame.insetBy(dx: -maxRadius, dy: -maxRadius)
             guard extendedBounds.contains(nsPoint) else { continue }
 
@@ -74,7 +189,7 @@ final class MouseFinder {
             )
             window.isOpaque = false
             window.backgroundColor = .clear
-            window.level = NSWindow.Level(rawValue: Int(CGWindowLevelForKey(.maximumWindow)))
+            window.level = sonarLevel
             window.hasShadow = false
             window.ignoresMouseEvents = true
             window.collectionBehavior = [.canJoinAllSpaces, .stationary]
@@ -88,16 +203,14 @@ final class MouseFinder {
 
             window.alphaValue = 0
             window.orderFrontRegardless()
-            overlayWindows.append(window)
+            sonarWindows.append(window)
 
-            // Fade in
             NSAnimationContext.runAnimationGroup { ctx in
                 ctx.duration = 0.1
                 window.animator().alphaValue = 1.0
             }
         }
 
-        // Animate the rings expanding using CACurrentMediaTime for state
         animationStart = CACurrentMediaTime()
         let interval = 1.0 / 60.0
 
@@ -106,7 +219,7 @@ final class MouseFinder {
             let elapsed = CACurrentMediaTime() - self.animationStart
             let progress = CGFloat(min(elapsed / self.animationDuration, 1.0))
 
-            for window in self.overlayWindows {
+            for window in self.sonarWindows {
                 (window.contentView as? SonarView)?.progress = progress
                 window.contentView?.needsDisplay = true
             }
@@ -116,18 +229,15 @@ final class MouseFinder {
                 self.animationTimer = nil
             }
         }
-
-        // Auto-dismiss after animation + hold
-        dismissTimer = Timer.scheduledTimer(withTimeInterval: 2.5, repeats: false) { [weak self] _ in
-            self?.fadeOut()
-        }
     }
 
+    // MARK: - Lifecycle
+
     private func fadeOut() {
-        let windows = overlayWindows
+        let allWindows = overlayWindows + sonarWindows
         NSAnimationContext.runAnimationGroup({ ctx in
-            ctx.duration = 0.4
-            for window in windows {
+            ctx.duration = SpotlightConfig.fadeOutDuration
+            for window in allWindows {
                 window.animator().alphaValue = 0
             }
         }, completionHandler: { [weak self] in
@@ -136,14 +246,57 @@ final class MouseFinder {
     }
 
     func dismiss() {
+        removeEventMonitors()
         animationTimer?.invalidate()
         animationTimer = nil
         dismissTimer?.invalidate()
         dismissTimer = nil
-        for window in overlayWindows {
+        sonarDelayTimer?.invalidate()
+        sonarDelayTimer = nil
+        for window in overlayWindows + sonarWindows {
             window.orderOut(nil)
         }
         overlayWindows.removeAll()
+        sonarWindows.removeAll()
+    }
+
+    // MARK: - Event Monitors
+
+    private func installEventMonitors() {
+        globalEventMonitor = NSEvent.addGlobalMonitorForEvents(
+            matching: [.leftMouseDown, .rightMouseDown, .keyDown]
+        ) { [weak self] _ in
+            self?.dismiss()
+        }
+        localEventMonitor = NSEvent.addLocalMonitorForEvents(
+            matching: [.leftMouseDown, .rightMouseDown, .keyDown]
+        ) { [weak self] event in
+            self?.dismiss()
+            return event
+        }
+    }
+
+    private func removeEventMonitors() {
+        if let m = globalEventMonitor { NSEvent.removeMonitor(m); globalEventMonitor = nil }
+        if let m = localEventMonitor { NSEvent.removeMonitor(m); localEventMonitor = nil }
+    }
+
+    // MARK: - Helpers
+
+    private func makeOverlayWindow(frame: NSRect, level: NSWindow.Level) -> NSWindow {
+        let window = NSWindow(
+            contentRect: frame,
+            styleMask: .borderless,
+            backing: .buffered,
+            defer: false
+        )
+        window.isOpaque = false
+        window.backgroundColor = .clear
+        window.level = level
+        window.hasShadow = false
+        window.ignoresMouseEvents = true
+        window.collectionBehavior = [.canJoinAllSpaces, .stationary]
+        return window
     }
 
     private func mouseScreen() -> NSScreen {
@@ -152,6 +305,164 @@ final class MouseFinder {
     }
 }
 
+// MARK: - Spotlight View (radial gradient cutout on cursor screen)
+
+enum SpotlightMode {
+    case find    // single arrow at screen center pointing TO the cursor
+    case summon  // four arrows around the cursor pointing INWARD ("conjured here")
+}
+
+private class SpotlightView: NSView {
+    let cursorPoint: CGPoint
+    let mode: SpotlightMode
+    private let config = DotMatrixConfig.shared
+    private lazy var dotPattern = config.generatePattern()
+
+    init(frame: NSRect, cursorPoint: CGPoint, mode: SpotlightMode = .find) {
+        self.cursorPoint = cursorPoint
+        self.mode = mode
+        super.init(frame: frame)
+    }
+
+    required init?(coder: NSCoder) { fatalError() }
+
+    override func draw(_ dirtyRect: NSRect) {
+        guard let ctx = NSGraphicsContext.current?.cgContext else { return }
+
+        ctx.setFillColor(NSColor.black.withAlphaComponent(SpotlightConfig.overlayAlpha).cgColor)
+        ctx.fill(bounds)
+
+        // Punch a radial gradient hole using destinationOut blend mode
+        ctx.setBlendMode(.destinationOut)
+
+        let colorSpace = CGColorSpaceCreateDeviceRGB()
+        let components: [CGFloat] = [
+            1, 1, 1, 1.0,
+            1, 1, 1, 0.8,
+            1, 1, 1, 0.0,
+        ]
+        let locations: [CGFloat] = [0.0, 0.3, 1.0]
+
+        guard let gradient = CGGradient(
+            colorSpace: colorSpace,
+            colorComponents: components,
+            locations: locations,
+            count: 3
+        ) else { return }
+
+        ctx.drawRadialGradient(
+            gradient,
+            startCenter: cursorPoint,
+            startRadius: 0,
+            endCenter: cursorPoint,
+            endRadius: SpotlightConfig.spotlightRadius,
+            options: []
+        )
+
+        ctx.setBlendMode(.normal)
+
+        switch mode {
+        case .find:
+            // Single arrow at screen center pointing toward the cursor.
+            let center = CGPoint(x: bounds.midX, y: bounds.midY)
+            let angle = atan2(cursorPoint.y - center.y, cursorPoint.x - center.x)
+            drawDotMatrixArrow(in: ctx, at: center, angle: angle)
+
+        case .summon:
+            // Four arrows around the cursor, all heads pointing inward toward it —
+            // the visual joke is that the mouse was just summoned here, so everything
+            // is converging on the new cursor position.
+            let arrowLen = CGFloat(config.arrowCols - 1) * config.dotSpacing
+            let offset = arrowLen / 2 + SpotlightConfig.spotlightRadius * 0.55
+            let placements: [(CGPoint, CGFloat)] = [
+                (CGPoint(x: cursorPoint.x, y: cursorPoint.y + offset), -.pi / 2), // above → points down
+                (CGPoint(x: cursorPoint.x, y: cursorPoint.y - offset),  .pi / 2), // below → points up
+                (CGPoint(x: cursorPoint.x - offset, y: cursorPoint.y),  0),       // left  → points right
+                (CGPoint(x: cursorPoint.x + offset, y: cursorPoint.y),  .pi),     // right → points left
+            ]
+            for (origin, angle) in placements {
+                drawDotMatrixArrow(in: ctx, at: origin, angle: angle)
+            }
+        }
+    }
+
+    private func drawDotMatrixArrow(in ctx: CGContext, at point: CGPoint, angle: CGFloat) {
+        ctx.saveGState()
+        ctx.translateBy(x: point.x, y: point.y)
+        ctx.rotate(by: angle)
+
+        let originX = -CGFloat(config.arrowCols - 1) * config.dotSpacing / 2
+        let originY = -CGFloat(config.arrowRows - 1) * config.dotSpacing / 2
+
+        for (col, row) in dotPattern {
+            let x = originX + CGFloat(col) * config.dotSpacing
+            let y = originY + CGFloat(row) * config.dotSpacing
+
+            let t = CGFloat(col) / CGFloat(max(1, config.arrowCols - 1))
+            let alpha = 0.35 + t * 0.5
+
+            ctx.setFillColor(SpotlightConfig.accentColor.withAlphaComponent(alpha).cgColor)
+            ctx.fillEllipse(in: CGRect(
+                x: x - config.dotRadius,
+                y: y - config.dotRadius,
+                width: config.dotRadius * 2,
+                height: config.dotRadius * 2
+            ))
+        }
+
+        ctx.restoreGState()
+    }
+}
+
+// MARK: - Dim Overlay View (dark fill + dot matrix arrow centered on off-screens)
+
+private class DimOverlayView: NSView {
+    let cursorAngle: CGFloat
+    private let config = DotMatrixConfig.shared
+    private lazy var dotPattern = config.generatePattern()
+
+    init(frame: NSRect, cursorAngle: CGFloat) {
+        self.cursorAngle = cursorAngle
+        super.init(frame: frame)
+    }
+
+    required init?(coder: NSCoder) { fatalError() }
+
+    override func draw(_ dirtyRect: NSRect) {
+        guard let ctx = NSGraphicsContext.current?.cgContext else { return }
+
+        ctx.setFillColor(NSColor.black.withAlphaComponent(SpotlightConfig.dimAlpha).cgColor)
+        ctx.fill(bounds)
+
+        let center = CGPoint(x: bounds.midX, y: bounds.midY)
+
+        ctx.saveGState()
+        ctx.translateBy(x: center.x, y: center.y)
+        ctx.rotate(by: cursorAngle)
+
+        let originX = -CGFloat(config.arrowCols - 1) * config.dotSpacing / 2
+        let originY = -CGFloat(config.arrowRows - 1) * config.dotSpacing / 2
+
+        for (col, row) in dotPattern {
+            let x = originX + CGFloat(col) * config.dotSpacing
+            let y = originY + CGFloat(row) * config.dotSpacing
+
+            let t = CGFloat(col) / CGFloat(max(1, config.arrowCols - 1))
+            let alpha = 0.35 + t * 0.5
+
+            ctx.setFillColor(SpotlightConfig.accentColor.withAlphaComponent(alpha).cgColor)
+            ctx.fillEllipse(in: CGRect(
+                x: x - config.dotRadius,
+                y: y - config.dotRadius,
+                width: config.dotRadius * 2,
+                height: config.dotRadius * 2
+            ))
+        }
+
+        ctx.restoreGState()
+    }
+}
+
 // MARK: - Sonar Ring View
 
 private class SonarView: NSView {
@@ -172,7 +483,6 @@ private class SonarView: NSView {
 
         let center = CGPoint(x: bounds.midX, y: bounds.midY)
 
-        // Draw rings from outermost to innermost
         for i in 0..<ringCount {
             let ringDelay = CGFloat(i) * 0.15
             let denom = 1.0 - ringDelay * CGFloat(ringCount - 1) / CGFloat(ringCount)
@@ -180,13 +490,10 @@ private class SonarView: NSView {
 
             guard ringProgress > 0 else { continue }
 
-            // Ease out cubic
             let eased = 1.0 - pow(1.0 - ringProgress, 3)
-
             let radius = maxRadius * eased
             let alpha = (1.0 - eased) * 0.8
 
-            // Ring stroke
             ctx.setStrokeColor(NSColor(calibratedRed: 0.4, green: 0.7, blue: 1.0, alpha: alpha).cgColor)
             ctx.setLineWidth(2.5 - CGFloat(i) * 0.5)
             ctx.addEllipse(in: CGRect(
@@ -198,7 +505,6 @@ private class SonarView: NSView {
             ctx.strokePath()
         }
 
-        // Center dot — stays visible
         let dotRadius: CGFloat = 6
         let dotAlpha = max(0.3, 1.0 - progress * 0.5)
         ctx.setFillColor(NSColor(calibratedRed: 0.4, green: 0.7, blue: 1.0, alpha: dotAlpha).cgColor)
@@ -209,7 +515,6 @@ private class SonarView: NSView {
             height: dotRadius * 2
         ))
 
-        // Outer glow on center dot
         ctx.setFillColor(NSColor(calibratedRed: 0.4, green: 0.7, blue: 1.0, alpha: dotAlpha * 0.2).cgColor)
         let glowRadius: CGFloat = 12
         ctx.fillEllipse(in: CGRect(