@lattices/cli 0.4.14 → 0.5.0

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

@@ -1,124 +0,0 @@
-import Foundation
-
-/// Self-healing circuit breaker for session-wide `CGEventTap`s.
-///
-/// macOS disables a tap (`tapDisabledByTimeout`) when its callback exceeds
-/// the OS budget. The naive recovery — re-enable and continue — fights the
-/// OS in a loop when the underlying cause is still present, and the system
-/// input pipeline keeps stuttering.
-///
-/// This breaker counts trips inside a rolling window and backs off in
-/// escalating cooldowns: 30s → 2 min → permanent (until app restart or
-/// manual re-arm). During cooldown the tap stays disabled — input flows
-/// through the OS without our interference. On cooldown expiry, `rearm`
-/// fires on the main queue to re-enable the tap.
-///
-/// Thread-safe; `recordTrip()` is safe to call from the event-tap thread.
-final class EventTapBreaker {
-    enum State: Equatable {
-        case armed
-        case paused(cooldownSec: Int)
-        case disabled
-    }
-
-    private let label: String
-    private let trippedWindow: TimeInterval = 600          // 10 min rolling window
-    private let cooldowns: [TimeInterval] = [30, 120]      // trip 1 → 30s, trip 2 → 2 min, trip 3+ → permanent
-
-    private let lock = NSLock()
-    private var tripsInWindow: [Date] = []
-    private var permanentlyDisabled = false
-    private var pendingRearm: DispatchWorkItem?
-    private var _state: State = .armed
-
-    /// Called on the main queue when a cooldown elapses. Caller wires this
-    /// to `CGEvent.tapEnable(tap:, enable: true)`.
-    var rearm: (() -> Void)?
-
-    /// Called on the main queue whenever `state` transitions. UI uses this
-    /// to surface "paused" / "disabled" messages and re-enable affordances.
-    var onStateChanged: ((State) -> Void)?
-
-    init(label: String) {
-        self.label = label
-    }
-
-    var state: State {
-        lock.lock(); defer { lock.unlock() }
-        return _state
-    }
-
-    /// Record that the OS just delivered `.tapDisabledByTimeout`. Schedules
-    /// a re-enable after the appropriate cooldown, or marks the breaker
-    /// permanently open after too many trips.
-    @discardableResult
-    func recordTrip() -> Bool {
-        lock.lock()
-        if permanentlyDisabled { lock.unlock(); return false }
-
-        let now = Date()
-        tripsInWindow.removeAll { now.timeIntervalSince($0) > trippedWindow }
-        tripsInWindow.append(now)
-
-        let count = tripsInWindow.count
-        if count > cooldowns.count {
-            permanentlyDisabled = true
-            pendingRearm?.cancel()
-            pendingRearm = nil
-            _state = .disabled
-            lock.unlock()
-            DiagnosticLog.shared.error("\(label): tap tripped \(count)× in \(Int(trippedWindow))s — disabled until app restart or manual re-arm")
-            notifyStateChanged(.disabled)
-            return false
-        }
-
-        let cooldown = cooldowns[count - 1]
-        _state = .paused(cooldownSec: Int(cooldown))
-        let nextState: State = .paused(cooldownSec: Int(cooldown))
-
-        pendingRearm?.cancel()
-        let work = DispatchWorkItem { [weak self] in
-            guard let self else { return }
-            DiagnosticLog.shared.info("\(self.label): tap auto-recovering")
-            self.lock.lock()
-            self._state = .armed
-            self.lock.unlock()
-            self.notifyStateChanged(.armed)
-            self.rearm?()
-        }
-        pendingRearm = work
-        lock.unlock()
-
-        DiagnosticLog.shared.warn("\(label): tap disabled by OS (trip #\(count)) — paused for \(Int(cooldown))s")
-        notifyStateChanged(nextState)
-        DispatchQueue.main.asyncAfter(deadline: .now() + cooldown, execute: work)
-        return false
-    }
-
-    /// Clears all trip history and any pending cooldown. Caller should
-    /// re-enable the tap after this to actually recover.
-    /// Use cases: tap (re)install, manual re-arm from Settings.
-    func reset() {
-        lock.lock()
-        let wasNotArmed = _state != .armed
-        pendingRearm?.cancel()
-        pendingRearm = nil
-        tripsInWindow.removeAll()
-        permanentlyDisabled = false
-        _state = .armed
-        lock.unlock()
-        if wasNotArmed {
-            DiagnosticLog.shared.info("\(label): tap state reset (armed)")
-            notifyStateChanged(.armed)
-        }
-    }
-
-    private func notifyStateChanged(_ newState: State) {
-        guard let callback = onStateChanged else { return }
-        if Thread.isMainThread {
-            callback(newState)
-        } else {
-            DispatchQueue.main.async { callback(newState) }
-        }
-    }
-}

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

@@ -1,54 +0,0 @@
-import Foundation
-import CoreFoundation
-
-/// Hosts a long-lived thread + CFRunLoop dedicated to CGEventTap callbacks,
-/// so taps installed at `.headInsertEventTap` don't add main-thread latency
-/// to every keyboard/mouse event in the user's session.
-///
-/// Callbacks fire on this thread — callers must hop AppKit/UI work back to
-/// main themselves (DispatchQueue.main.async).
-final class EventTapThread {
-    static let shared = EventTapThread()
-
-    private let lock = NSLock()
-    private var runLoop: CFRunLoop?
-
-    private init() {
-        let ready = DispatchSemaphore(value: 0)
-        let thread = Thread { [unowned self] in
-            let loop = CFRunLoopGetCurrent()
-            // Keep the run loop alive across add/remove cycles by anchoring a
-            // no-op port; otherwise CFRunLoopRun() returns when the last
-            // source is removed.
-            let keepalive = NSMachPort()
-            RunLoop.current.add(keepalive, forMode: .common)
-            self.lock.lock()
-            self.runLoop = loop
-            self.lock.unlock()
-            ready.signal()
-            CFRunLoopRun()
-        }
-        thread.qualityOfService = .userInteractive
-        thread.name = "com.arach.lattices.EventTapThread"
-        thread.start()
-        ready.wait()
-    }
-
-    func add(source: CFRunLoopSource) {
-        lock.lock()
-        let loop = runLoop
-        lock.unlock()
-        guard let loop else { return }
-        CFRunLoopAddSource(loop, source, .commonModes)
-        CFRunLoopWakeUp(loop)
-    }
-
-    func remove(source: CFRunLoopSource) {
-        lock.lock()
-        let loop = runLoop
-        lock.unlock()
-        guard let loop else { return }
-        CFRunLoopRemoveSource(loop, source, .commonModes)
-        CFRunLoopWakeUp(loop)
-    }
-}

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

@@ -1,20 +0,0 @@
-import Foundation
-
-enum InputCaptureResetCenter {
-    static func reset(reason: String) {
-        if Thread.isMainThread {
-            performReset(reason: reason)
-        } else {
-            DispatchQueue.main.async {
-                performReset(reason: reason)
-            }
-        }
-    }
-
-    private static func performReset(reason: String) {
-        DiagnosticLog.shared.warn("InputCapture: reset for \(reason)")
-        ScreenOverlayCanvasController.shared.resetInputCapture(reason: reason)
-        MouseGestureController.shared.resetForSystemInputBoundary(reason: reason)
-        KeyboardRemapController.shared.resetForSystemInputBoundary(reason: reason)
-    }
-}

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

@@ -1,69 +0,0 @@
-import CoreGraphics
-import Foundation
-
-enum KeyboardRemapKey: String, Codable, Equatable {
-    case capsLock = "caps_lock"
-
-    var keyCode: Int64 {
-        switch self {
-        case .capsLock: return 57
-        }
-    }
-
-    var displayLabel: String {
-        switch self {
-        case .capsLock: return "Caps Lock"
-        }
-    }
-}
-
-enum KeyboardRemapAction: String, Codable, Equatable {
-    case escape
-    case hyper
-
-    var displayLabel: String {
-        switch self {
-        case .escape: return "Escape"
-        case .hyper: return "Hyper"
-        }
-    }
-}
-
-struct KeyboardRemapRule: Codable, Equatable, Identifiable {
-    var id: String
-    var enabled: Bool
-    var from: KeyboardRemapKey
-    var toIfHeld: KeyboardRemapAction
-    var toIfAlone: KeyboardRemapAction?
-
-    var summaryLine: String {
-        let held = "hold \(from.displayLabel) -> \(toIfHeld.displayLabel)"
-        guard let alone = toIfAlone else { return held }
-        return "\(held), tap -> \(alone.displayLabel)"
-    }
-}
-
-struct KeyboardRemapConfig: Codable, Equatable {
-    var rules: [KeyboardRemapRule]
-
-    static let defaults = KeyboardRemapConfig(
-        rules: [
-            KeyboardRemapRule(
-                id: "caps_lock_hyper_escape",
-                enabled: true,
-                from: .capsLock,
-                toIfHeld: .hyper,
-                toIfAlone: .escape
-            )
-        ]
-    )
-}
-
-extension CGEventFlags {
-    static let latticesHyper: CGEventFlags = [
-        .maskCommand,
-        .maskControl,
-        .maskAlternate,
-        .maskShift,
-    ]
-}

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

@@ -1,346 +0,0 @@
-import AppKit
-import Combine
-import CoreGraphics
-
-final class KeyboardRemapController: ObservableObject {
-    static let shared = KeyboardRemapController()
-
-    /// 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 static let syntheticMarker: Int64 = 0x4C4B524D
-
-    private var eventTap: CFMachPort?
-    private var runLoopSource: CFRunLoopSource?
-    private var subscriptions: Set<AnyCancellable> = []
-    private var installedObservers = false
-    private var capsLayerActive = false
-    private var capsUsedAsModifier = false
-    private var capsLayerActivatedAt: CFAbsoluteTime?
-    private var capsLayerLastEventAt: CFAbsoluteTime?
-    private var bypassUntil: CFAbsoluteTime = 0
-    private var lastCapsLayerStaleLogAt: CFAbsoluteTime = 0
-    private var pressedKeyCodes: [Int64: CFAbsoluteTime] = [:]
-    private let breaker = EventTapBreaker(label: "KeyboardRemap")
-    private let budgetMeter = TapBudgetMeter(label: "KeyboardRemap")
-    private let maxCapsLayerIdleDuration: TimeInterval = 2.0
-    private let maxCapsLayerHeldDuration: TimeInterval = 20.0
-    private let maxTrackedKeyDownDuration: TimeInterval = 120.0
-    private let emergencyBypassDuration: TimeInterval = 3.0
-
-    private init() {
-        breaker.onStateChanged = { [weak self] newState in
-            self?.breakerState = newState
-        }
-    }
-
-    /// 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)
-        }
-    }
-
-    func start() {
-        installObserversIfNeeded()
-        refresh()
-    }
-
-    func stop() {
-        removeEventTap()
-        clearCapsLayer()
-    }
-
-    func resetForSystemInputBoundary(reason: String) {
-        dispatchPrecondition(condition: .onQueue(.main))
-        clearCapsLayer()
-        pressedKeyCodes.removeAll()
-        breaker.reset()
-        if let eventTap {
-            CGEvent.tapEnable(tap: eventTap, enable: true)
-        } else {
-            refresh()
-        }
-        DiagnosticLog.shared.warn("KeyboardRemap: reset for \(reason)")
-    }
-
-    private func installObserversIfNeeded() {
-        guard !installedObservers else { return }
-        installedObservers = true
-
-        Preferences.shared.$keyboardRemapsEnabled
-            .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)
-    }
-
-    private func refresh() {
-        guard Preferences.shared.keyboardRemapsEnabled,
-              PermissionChecker.shared.accessibility else {
-            removeEventTap()
-            return
-        }
-
-        KeyboardRemapStore.shared.ensureConfigFile()
-        if eventTap == nil {
-            installEventTap()
-        } else if let eventTap {
-            CGEvent.tapEnable(tap: eventTap, 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.keyDown.rawValue
-        mask |= CGEventMask(1) << CGEventType.keyUp.rawValue
-        mask |= CGEventMask(1) << CGEventType.flagsChanged.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("KeyboardRemap: failed to install keyboard 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("KeyboardRemap: keyboard 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<KeyboardRemapController>.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.
-            clearCapsLayer()
-            breaker.recordTrip()
-            return Unmanaged.passUnretained(event)
-        }
-        if type == .tapDisabledByUserInput {
-            // User-driven disable (rare). Re-enable directly, no cooldown.
-            clearCapsLayer()
-            if let eventTap {
-                CGEvent.tapEnable(tap: eventTap, enable: true)
-            }
-            return Unmanaged.passUnretained(event)
-        }
-
-        if event.getIntegerValueField(.eventSourceUserData) == Self.syntheticMarker {
-            return Unmanaged.passUnretained(event)
-        }
-
-        expireStalePressedKeys(now: started)
-        updatePressedKeys(type: type, keyCode: event.getIntegerValueField(.keyboardEventKeycode), now: started)
-        if shouldTriggerEmergencyReset(type: type, event: event) {
-            emergencyClear(now: started)
-            InputCaptureResetCenter.reset(reason: "keyboard emergency chord")
-            return Unmanaged.passUnretained(event)
-        }
-
-        if started < bypassUntil {
-            return Unmanaged.passUnretained(event)
-        }
-
-        KeyboardRemapStore.shared.scheduleReloadCheckIfNeeded()
-        guard let rule = KeyboardRemapStore.shared.capsLockRule,
-              rule.toIfHeld == .hyper else {
-            return Unmanaged.passUnretained(event)
-        }
-
-        let keyCode = event.getIntegerValueField(.keyboardEventKeycode)
-        if type == .flagsChanged, keyCode == rule.from.keyCode {
-            return handleCapsLockFlagsChanged(event, rule: rule)
-        }
-
-        reconcileCapsLayer(event: event, type: type, now: started)
-        guard capsLayerActive else {
-            return Unmanaged.passUnretained(event)
-        }
-
-        switch type {
-        case .keyDown:
-            if keyCode == 53 {
-                emergencyClear(now: started)
-                return Unmanaged.passUnretained(event)
-            }
-            capsUsedAsModifier = true
-            capsLayerLastEventAt = started
-            event.flags = normalizedFlags(event.flags).union(.latticesHyper)
-            return Unmanaged.passUnretained(event)
-        case .keyUp:
-            capsLayerLastEventAt = started
-            event.flags = normalizedFlags(event.flags).union(.latticesHyper)
-            return Unmanaged.passUnretained(event)
-        default:
-            return Unmanaged.passUnretained(event)
-        }
-    }
-
-    private func handleCapsLockFlagsChanged(_ event: CGEvent, rule: KeyboardRemapRule) -> Unmanaged<CGEvent>? {
-        let isDown = event.flags.contains(.maskAlphaShift)
-        if isDown {
-            capsLayerActive = true
-            capsUsedAsModifier = false
-            let now = CFAbsoluteTimeGetCurrent()
-            capsLayerActivatedAt = now
-            capsLayerLastEventAt = now
-            DiagnosticLog.shared.info("KeyboardRemap: Caps Lock layer active")
-        } else {
-            let shouldTap = capsLayerActive && !capsUsedAsModifier && rule.toIfAlone == .escape
-            clearCapsLayer()
-            if shouldTap {
-                postKeyTap(keyCode: 53)
-            }
-            DiagnosticLog.shared.info("KeyboardRemap: Caps Lock layer inactive")
-        }
-
-        return nil
-    }
-
-    private func clearCapsLayer() {
-        capsLayerActive = false
-        capsUsedAsModifier = false
-        capsLayerActivatedAt = nil
-        capsLayerLastEventAt = nil
-    }
-
-    private func reconcileCapsLayer(event: CGEvent, type: CGEventType, now: CFAbsoluteTime) {
-        guard capsLayerActive else { return }
-
-        // If a release event was dropped, later key events often arrive
-        // without the physical Caps flag. Treat that as an input boundary and
-        // fail open before rewriting the user's key.
-        if type == .keyDown || type == .keyUp,
-           !event.flags.contains(.maskAlphaShift) {
-            clearCapsLayer(reason: "physical Caps flag cleared", now: now)
-            return
-        }
-
-        if let lastEventAt = capsLayerLastEventAt,
-           now - lastEventAt > maxCapsLayerIdleDuration {
-            clearCapsLayer(reason: "idle", now: now)
-            return
-        }
-
-        if let activatedAt = capsLayerActivatedAt,
-           now - activatedAt > maxCapsLayerHeldDuration {
-            clearCapsLayer(reason: "held too long", now: now)
-        }
-    }
-
-    private func clearCapsLayer(reason: String, now: CFAbsoluteTime) {
-        clearCapsLayer()
-        if now - lastCapsLayerStaleLogAt > 1 {
-            lastCapsLayerStaleLogAt = now
-            DiagnosticLog.shared.warn("KeyboardRemap: Caps Lock layer cleared (\(reason))")
-        }
-    }
-
-    private func emergencyClear(now: CFAbsoluteTime) {
-        clearCapsLayer()
-        pressedKeyCodes.removeAll()
-        bypassUntil = now + emergencyBypassDuration
-        DiagnosticLog.shared.warn("KeyboardRemap: emergency bypass via Escape")
-    }
-
-    private func updatePressedKeys(type: CGEventType, keyCode: Int64, now: CFAbsoluteTime) {
-        switch type {
-        case .keyDown:
-            pressedKeyCodes[keyCode] = now
-        case .keyUp:
-            pressedKeyCodes.removeValue(forKey: keyCode)
-        default:
-            break
-        }
-    }
-
-    private func expireStalePressedKeys(now: CFAbsoluteTime) {
-        let staleKeys = pressedKeyCodes.filter { now - $0.value > maxTrackedKeyDownDuration }.map(\.key)
-        guard !staleKeys.isEmpty else { return }
-        for keyCode in staleKeys {
-            pressedKeyCodes.removeValue(forKey: keyCode)
-        }
-        DiagnosticLog.shared.warn("KeyboardRemap: cleared stale key-down state for \(staleKeys.count) key(s)")
-    }
-
-    private func shouldTriggerEmergencyReset(type: CGEventType, event: CGEvent) -> Bool {
-        guard type == .keyDown else { return false }
-        let keyCode = event.getIntegerValueField(.keyboardEventKeycode)
-        let flags = event.flags
-        return keyCode == 40
-            && pressedKeyCodes[53] != nil
-            && flags.contains(.maskShift)
-    }
-
-    private func normalizedFlags(_ flags: CGEventFlags) -> CGEventFlags {
-        var normalized = flags
-        normalized.remove(.maskAlphaShift)
-        return normalized
-    }
-
-    private func postKeyTap(keyCode: CGKeyCode) {
-        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 {
-            return
-        }
-        down.setIntegerValueField(.eventSourceUserData, value: Self.syntheticMarker)
-        up.setIntegerValueField(.eventSourceUserData, value: Self.syntheticMarker)
-        down.post(tap: .cghidEventTap)
-        up.post(tap: .cghidEventTap)
-    }
-}