@lattices/cli 0.3.0

package/app/Sources/DesktopModelTypes.swift

@@ -0,0 +1,71 @@
+import Foundation
+
+struct WindowEntry: Codable, Identifiable {
+    let wid: UInt32
+    let app: String
+    let pid: Int32
+    let title: String
+    let frame: WindowFrame
+    let spaceIds: [Int]
+    let isOnScreen: Bool
+    let latticesSession: String?
+
+    var id: UInt32 { wid }
+}
+
+struct WindowFrame: Codable, Equatable {
+    let x: Double
+    let y: Double
+    let w: Double
+    let h: Double
+}
+
+// MARK: - Desktop Inventory Snapshot
+
+struct DesktopInventorySnapshot {
+    let displays: [DisplayInfo]
+    let timestamp: Date
+
+    struct DisplayInfo: Identifiable {
+        let id: String           // display UUID or index
+        let name: String         // e.g. "Built-in Retina", "LG UltraFine"
+        let resolution: (w: Int, h: Int)
+        let visibleFrame: (w: Int, h: Int)
+        let isMain: Bool
+        let spaceCount: Int
+        let currentSpaceIndex: Int
+        let spaces: [SpaceGroup]
+    }
+
+    struct SpaceGroup: Identifiable {
+        let id: Int              // CGS space ID
+        let index: Int           // 1-based index within display
+        let isCurrent: Bool
+        let apps: [AppGroup]
+    }
+
+    struct AppGroup: Identifiable {
+        let id: String           // unique key (spaceId-appName)
+        let appName: String
+        let windows: [InventoryWindowInfo]
+    }
+
+    struct InventoryWindowInfo: Identifiable {
+        let id: UInt32           // CGWindowID
+        let pid: Int32           // owner PID for AX operations
+        let title: String
+        let frame: WindowFrame
+        let tilePosition: TilePosition?
+        let isLattices: Bool
+        let latticesSession: String?
+        let spaceIndex: Int?     // 1-based space index within display
+        let isOnScreen: Bool     // on current space
+        var inventoryPath: InventoryPath?
+        var appName: String?     // owner app name for filtering
+    }
+
+    /// Flat list of all windows across all displays/spaces/apps
+    var allWindows: [InventoryWindowInfo] {
+        displays.flatMap { $0.spaces.flatMap { $0.apps.flatMap { $0.windows } } }
+    }
+}

package/app/Sources/DiagnosticLog.swift

@@ -0,0 +1,271 @@
+import AppKit
+import SwiftUI
+
+// MARK: - Log Store
+
+final class DiagnosticLog: ObservableObject {
+    static let shared = DiagnosticLog()
+
+    struct Entry: Identifiable {
+        let id = UUID()
+        let time: Date
+        let message: String
+        let level: Level
+
+        enum Level { case info, success, warning, error }
+
+        var icon: String {
+            switch level {
+            case .info:    return "›"
+            case .success: return "✓"
+            case .warning: return "⚠"
+            case .error:   return "✗"
+            }
+        }
+    }
+
+    @Published var entries: [Entry] = []
+    private let maxEntries = 80
+
+    func log(_ message: String, level: Entry.Level = .info) {
+        let entry = Entry(time: Date(), message: message, level: level)
+        DispatchQueue.main.async {
+            self.entries.append(entry)
+            if self.entries.count > self.maxEntries {
+                self.entries.removeFirst(self.entries.count - self.maxEntries)
+            }
+        }
+    }
+
+    func info(_ msg: String)    { log(msg, level: .info) }
+    func success(_ msg: String) { log(msg, level: .success) }
+    func warn(_ msg: String)    { log(msg, level: .warning) }
+    func error(_ msg: String)   { log(msg, level: .error) }
+    func clear()                { DispatchQueue.main.async { self.entries.removeAll() } }
+
+    // MARK: - Per-Action Timing
+
+    struct TimedAction {
+        let label: String
+        let start: Date
+    }
+
+    func startTimed(_ label: String) -> TimedAction {
+        info("▸ \(label)")
+        return TimedAction(label: label, start: Date())
+    }
+
+    func finish(_ action: TimedAction) {
+        let ms = Date().timeIntervalSince(action.start) * 1000
+        success("▸ \(action.label) — \(String(format: "%.0f", ms))ms")
+    }
+}
+
+// MARK: - Diagnostic Window
+
+final class DiagnosticWindow {
+    static let shared = DiagnosticWindow()
+
+    private var window: NSWindow?
+    private var keyMonitor: Any?
+    private let log = DiagnosticLog.shared
+
+    var isVisible: Bool { window?.isVisible ?? false }
+
+    func toggle() {
+        if let w = window, w.isVisible {
+            dismiss()
+        } else {
+            show()
+        }
+    }
+
+    func dismiss() {
+        window?.orderOut(nil)
+        if let monitor = keyMonitor {
+            NSEvent.removeMonitor(monitor)
+            keyMonitor = nil
+        }
+    }
+
+    func show() {
+        if let w = window {
+            w.orderFrontRegardless()
+            return
+        }
+
+        let view = DiagnosticOverlayView()
+
+        let hosting = NSHostingController(rootView: view)
+        let screen = NSScreen.main
+        let screenFrame = screen?.visibleFrame ?? NSRect(x: 0, y: 0, width: 1920, height: 1080)
+        let panelWidth: CGFloat = 480
+        let panelHeight: CGFloat = max(600, floor(screenFrame.height * 0.55))
+        hosting.preferredContentSize = NSSize(width: panelWidth, height: panelHeight)
+
+        let w = NSPanel(
+            contentRect: NSRect(x: 0, y: 0, width: panelWidth, height: panelHeight),
+            styleMask: [.titled, .closable, .resizable, .utilityWindow, .nonactivatingPanel],
+            backing: .buffered,
+            defer: false
+        )
+        w.contentViewController = hosting
+        w.title = "Lattices Diagnostics"
+        w.titlebarAppearsTransparent = true
+        w.isMovableByWindowBackground = true
+        w.level = .floating
+        w.isOpaque = false
+        w.backgroundColor = NSColor(red: 0.1, green: 0.1, blue: 0.12, alpha: 1.0)
+        w.hasShadow = true
+        w.alphaValue = 1.0
+        w.collectionBehavior = [.canJoinAllSpaces, .fullScreenAuxiliary]
+
+        // Position: right edge, vertically centered
+        let x = screenFrame.maxX - panelWidth - 12
+        let y = screenFrame.minY + floor((screenFrame.height - panelHeight) / 2)
+        w.setFrameOrigin(NSPoint(x: x, y: y))
+
+        w.orderFrontRegardless()
+        window = w
+
+        // Escape key → dismiss
+        keyMonitor = NSEvent.addLocalMonitorForEvents(matching: .keyDown) { [weak self] event in
+            guard event.keyCode == 53,
+                  let win = self?.window,
+                  event.window === win || win.isKeyWindow else { return event }
+            self?.dismiss()
+            return nil
+        }
+
+        // Startup log
+        let diag = DiagnosticLog.shared
+        diag.info("Diagnostics opened")
+        diag.info("Terminal: \(Preferences.shared.terminal.rawValue) (\(Preferences.shared.terminal.bundleId))")
+        diag.info("Installed: \(Terminal.installed.map(\.rawValue).joined(separator: ", "))")
+
+        // Show running sessions
+        let task = Process()
+        task.executableURL = URL(fileURLWithPath: "/opt/homebrew/bin/tmux")
+        task.arguments = ["list-sessions", "-F", "#{session_name}"]
+        let pipe = Pipe()
+        task.standardOutput = pipe
+        task.standardError = FileHandle.nullDevice
+        try? task.run()
+        task.waitUntilExit()
+        let sessions = String(data: pipe.fileHandleForReading.readDataToEndOfFile(), encoding: .utf8)?.trimmingCharacters(in: .whitespacesAndNewlines) ?? "none"
+        diag.info("tmux sessions: \(sessions)")
+    }
+}
+
+// MARK: - SwiftUI Overlay
+
+struct DiagnosticOverlayView: View {
+    @StateObject private var log = DiagnosticLog.shared
+    @State private var autoScroll = true
+    @State private var refreshTick = 0
+
+    private static let timeFmt: DateFormatter = {
+        let f = DateFormatter()
+        f.dateFormat = "HH:mm:ss.SSS"
+        return f
+    }()
+
+    // Fallback timer to catch any missed updates
+    private let refreshTimer = Timer.publish(every: 0.5, on: .main, in: .common).autoconnect()
+
+    var body: some View {
+        VStack(spacing: 0) {
+            // Header
+            HStack {
+                Text("DIAGNOSTICS")
+                    .font(.system(size: 10, weight: .bold, design: .monospaced))
+                    .foregroundColor(.green.opacity(0.8))
+                Spacer()
+                let _ = refreshTick  // force re-render on timer
+                Text("\(log.entries.count) events")
+                    .font(.system(size: 9, design: .monospaced))
+                    .foregroundColor(.white.opacity(0.4))
+                Button("Copy") {
+                    let text = log.entries.map { entry in
+                        let t = Self.timeFmt.string(from: entry.time)
+                        return "\(t) \(entry.icon) \(entry.message)"
+                    }.joined(separator: "\n")
+                    NSPasteboard.general.clearContents()
+                    NSPasteboard.general.setString(text, forType: .string)
+                }
+                .font(.system(size: 9, design: .monospaced))
+                .foregroundColor(.white.opacity(0.5))
+                .buttonStyle(.plain)
+                Button("Clear") { log.clear() }
+                    .font(.system(size: 9, design: .monospaced))
+                    .foregroundColor(.white.opacity(0.5))
+                    .buttonStyle(.plain)
+            }
+            .padding(.horizontal, 10)
+            .padding(.vertical, 6)
+            .background(Color.black.opacity(0.3))
+            .onReceive(refreshTimer) { _ in refreshTick += 1 }
+
+            // Log entries
+            ScrollViewReader { proxy in
+                ScrollView {
+                    LazyVStack(alignment: .leading, spacing: 1) {
+                        ForEach(log.entries) { entry in
+                            logRow(entry)
+                                .id(entry.id)
+                        }
+                    }
+                    .padding(.horizontal, 8)
+                    .padding(.vertical, 4)
+                }
+                .onChange(of: log.entries.count) { _ in
+                    if autoScroll, let last = log.entries.last {
+                        withAnimation(.easeOut(duration: 0.1)) {
+                            proxy.scrollTo(last.id, anchor: .bottom)
+                        }
+                    }
+                }
+            }
+        }
+        .frame(minWidth: 420, idealWidth: 480, minHeight: 400, idealHeight: 600)
+        .background(Color.black.opacity(0.75))
+    }
+
+    private func logRow(_ entry: DiagnosticLog.Entry) -> some View {
+        HStack(alignment: .top, spacing: 6) {
+            Text(Self.timeFmt.string(from: entry.time))
+                .font(.system(size: 9, design: .monospaced))
+                .foregroundColor(.white.opacity(0.3))
+
+            Text(entry.icon)
+                .font(.system(size: 9, design: .monospaced))
+                .foregroundColor(iconColor(entry.level))
+                .frame(width: 10)
+
+            Text(entry.message)
+                .font(.system(size: 10, design: .monospaced))
+                .foregroundColor(textColor(entry.level))
+                .lineLimit(3)
+                .fixedSize(horizontal: false, vertical: true)
+        }
+        .padding(.vertical, 1)
+    }
+
+    private func iconColor(_ level: DiagnosticLog.Entry.Level) -> Color {
+        switch level {
+        case .info:    return .white.opacity(0.5)
+        case .success: return .green
+        case .warning: return .yellow
+        case .error:   return .red
+        }
+    }
+
+    private func textColor(_ level: DiagnosticLog.Entry.Level) -> Color {
+        switch level {
+        case .info:    return .white.opacity(0.7)
+        case .success: return .green.opacity(0.9)
+        case .warning: return .yellow.opacity(0.9)
+        case .error:   return .red.opacity(0.9)
+        }
+    }
+}

package/app/Sources/EventBus.swift

@@ -0,0 +1,30 @@
+import Foundation
+
+enum ModelEvent {
+    case windowsChanged(windows: [WindowEntry], added: [UInt32], removed: [UInt32])
+    case tmuxChanged(sessions: [TmuxSession])
+    case layerSwitched(index: Int)
+    case processesChanged(interesting: [Int])
+    case ocrScanComplete(windowCount: Int, totalBlocks: Int)
+}
+
+final class EventBus {
+    static let shared = EventBus()
+    private var handlers: [(ModelEvent) -> Void] = []
+    private let lock = NSLock()
+
+    func subscribe(_ handler: @escaping (ModelEvent) -> Void) {
+        lock.lock()
+        handlers.append(handler)
+        lock.unlock()
+    }
+
+    func post(_ event: ModelEvent) {
+        lock.lock()
+        let copy = handlers
+        lock.unlock()
+        for handler in copy {
+            handler(event)
+        }
+    }
+}

package/app/Sources/HotkeyManager.swift

@@ -0,0 +1,254 @@
+import Carbon
+import AppKit
+import Foundation
+
+/// Global callback registry keyed by hotkey ID
+private var hotkeyCallbacks: [UInt32: () -> Void] = [:]
+
+/// Whether the global Carbon event handler has been installed
+private var eventHandlerInstalled = false
+
+class HotkeyManager {
+    static let shared = HotkeyManager()
+    private var hotKeyRefs: [UInt32: EventHotKeyRef] = [:]
+
+    private func ensureEventHandler() {
+        guard !eventHandlerInstalled else { return }
+        eventHandlerInstalled = true
+
+        var eventType = EventTypeSpec(
+            eventClass: OSType(kEventClassKeyboard),
+            eventKind: UInt32(kEventHotKeyPressed)
+        )
+
+        InstallEventHandler(
+            GetApplicationEventTarget(),
+            { (_: EventHandlerCallRef?, event: EventRef?, _: UnsafeMutableRawPointer?) -> OSStatus in
+                guard let event else { return OSStatus(eventNotHandledErr) }
+                var hotkeyID = EventHotKeyID()
+                GetEventParameter(
+                    event,
+                    EventParamName(kEventParamDirectObject),
+                    EventParamType(typeEventHotKeyID),
+                    nil,
+                    MemoryLayout<EventHotKeyID>.size,
+                    nil,
+                    &hotkeyID
+                )
+                hotkeyCallbacks[hotkeyID.id]?()
+                return noErr
+            },
+            1,
+            &eventType,
+            nil,
+            nil
+        )
+    }
+
+    /// Register Cmd+Shift+M as the global hotkey (palette toggle)
+    func register(callback: @escaping () -> Void) {
+        ensureEventHandler()
+
+        let id: UInt32 = 1
+        hotkeyCallbacks[id] = callback
+
+        let hotKeyID = EventHotKeyID(
+            signature: OSType(0x444D5558),  // "DMUX"
+            id: id
+        )
+
+        var ref: EventHotKeyRef?
+        RegisterEventHotKey(
+            46,  // 'M'
+            UInt32(cmdKey | shiftKey),
+            hotKeyID,
+            GetApplicationEventTarget(),
+            0,
+            &ref
+        )
+        if let ref { hotKeyRefs[id] = ref }
+    }
+
+    /// Register Hyper+1 (Cmd+Ctrl+Option+Shift+1) for command mode
+    func registerCommandMode(callback: @escaping () -> Void) {
+        ensureEventHandler()
+        let id: UInt32 = 200
+        hotkeyCallbacks[id] = callback
+        let hotKeyID = EventHotKeyID(
+            signature: OSType(0x444D5558),  // "DMUX"
+            id: id
+        )
+        var ref: EventHotKeyRef?
+        RegisterEventHotKey(
+            18,  // '1' key
+            UInt32(cmdKey | controlKey | optionKey | shiftKey),  // Hyper
+            hotKeyID,
+            GetApplicationEventTarget(),
+            0,
+            &ref
+        )
+        if let ref { hotKeyRefs[id] = ref }
+    }
+
+    /// Register Hyper+2 (Cmd+Ctrl+Option+Shift+2) for bezel mode
+    func registerBezelHotkey(callback: @escaping () -> Void) {
+        ensureEventHandler()
+        let id: UInt32 = 201
+        hotkeyCallbacks[id] = callback
+        let hotKeyID = EventHotKeyID(
+            signature: OSType(0x444D5558),  // "DMUX"
+            id: id
+        )
+        var ref: EventHotKeyRef?
+        RegisterEventHotKey(
+            19,  // '2' key
+            UInt32(cmdKey | controlKey | optionKey | shiftKey),  // Hyper
+            hotKeyID,
+            GetApplicationEventTarget(),
+            0,
+            &ref
+        )
+        if let ref { hotKeyRefs[id] = ref }
+    }
+
+    /// Register Cmd+Option+1/2/3... hotkeys for layer switching
+    func registerLayerHotkeys(count: Int, callback: @escaping (Int) -> Void) {
+        ensureEventHandler()
+
+        // Key codes for number keys 1-9
+        let keyCodes: [UInt32] = [18, 19, 20, 21, 23, 22, 26, 28, 25]
+        let limit = min(count, keyCodes.count)
+
+        for i in 0..<limit {
+            let id: UInt32 = 101 + UInt32(i)
+
+            // Unregister existing if re-registering
+            if let existing = hotKeyRefs[id] {
+                UnregisterEventHotKey(existing)
+                hotKeyRefs.removeValue(forKey: id)
+            }
+
+            let layerIndex = i
+            hotkeyCallbacks[id] = { callback(layerIndex) }
+
+            let hotKeyID = EventHotKeyID(
+                signature: OSType(0x444D5558),  // "DMUX"
+                id: id
+            )
+
+            var ref: EventHotKeyRef?
+            RegisterEventHotKey(
+                keyCodes[i],
+                UInt32(cmdKey | optionKey),
+                hotKeyID,
+                GetApplicationEventTarget(),
+                0,
+                &ref
+            )
+            if let ref { hotKeyRefs[id] = ref }
+        }
+    }
+
+    /// Register a single global hotkey with a given ID, key code, and Carbon modifier mask
+    func registerSingle(id: UInt32, keyCode: UInt32, modifiers: UInt32, callback: @escaping () -> Void) {
+        ensureEventHandler()
+
+        if let existing = hotKeyRefs[id] {
+            UnregisterEventHotKey(existing)
+            hotKeyRefs.removeValue(forKey: id)
+        }
+
+        hotkeyCallbacks[id] = callback
+
+        let hotKeyID = EventHotKeyID(
+            signature: OSType(0x444D5558),  // "DMUX"
+            id: id
+        )
+
+        var ref: EventHotKeyRef?
+        let status = RegisterEventHotKey(
+            keyCode,
+            modifiers,
+            hotKeyID,
+            GetApplicationEventTarget(),
+            0,
+            &ref
+        )
+        if let ref {
+            hotKeyRefs[id] = ref
+        } else {
+            DiagnosticLog.shared.warn("HotkeyManager: failed to register id=\(id) keyCode=\(keyCode) mods=\(modifiers) status=\(status)")
+        }
+    }
+
+    /// Unregister all global hotkeys and clear callbacks
+    func unregisterAll() {
+        for (id, ref) in hotKeyRefs {
+            UnregisterEventHotKey(ref)
+            hotkeyCallbacks.removeValue(forKey: id)
+        }
+        hotKeyRefs.removeAll()
+    }
+
+    /// Register Ctrl+Option window tiling hotkeys (Magnet-style)
+    func registerTileHotkeys() {
+        let mods = UInt32(controlKey | optionKey)
+
+        // Ctrl+Option+← → left
+        registerSingle(id: 300, keyCode: 123, modifiers: mods) {
+            WindowTiler.tileFrontmostViaAX(to: .left)
+        }
+        // Ctrl+Option+→ → right
+        registerSingle(id: 301, keyCode: 124, modifiers: mods) {
+            WindowTiler.tileFrontmostViaAX(to: .right)
+        }
+        // Ctrl+Option+Return → maximize
+        registerSingle(id: 302, keyCode: 36, modifiers: mods) {
+            WindowTiler.tileFrontmostViaAX(to: .maximize)
+        }
+        // Ctrl+Option+C → center
+        registerSingle(id: 303, keyCode: 8, modifiers: mods) {
+            WindowTiler.tileFrontmostViaAX(to: .center)
+        }
+        // Ctrl+Option+U → top-left
+        registerSingle(id: 304, keyCode: 32, modifiers: mods) {
+            WindowTiler.tileFrontmostViaAX(to: .topLeft)
+        }
+        // Ctrl+Option+I → top-right
+        registerSingle(id: 305, keyCode: 34, modifiers: mods) {
+            WindowTiler.tileFrontmostViaAX(to: .topRight)
+        }
+        // Ctrl+Option+J → bottom-left
+        registerSingle(id: 306, keyCode: 38, modifiers: mods) {
+            WindowTiler.tileFrontmostViaAX(to: .bottomLeft)
+        }
+        // Ctrl+Option+K → bottom-right
+        registerSingle(id: 307, keyCode: 40, modifiers: mods) {
+            WindowTiler.tileFrontmostViaAX(to: .bottomRight)
+        }
+        // Ctrl+Option+↑ → top
+        registerSingle(id: 308, keyCode: 126, modifiers: mods) {
+            WindowTiler.tileFrontmostViaAX(to: .top)
+        }
+        // Ctrl+Option+↓ → bottom
+        registerSingle(id: 309, keyCode: 125, modifiers: mods) {
+            WindowTiler.tileFrontmostViaAX(to: .bottom)
+        }
+        // Ctrl+Option+D → distribute visible windows
+        registerSingle(id: 310, keyCode: 2, modifiers: mods) {
+            WindowTiler.distributeVisible()
+        }
+        // Ctrl+Option+1 → left third
+        registerSingle(id: 311, keyCode: 18, modifiers: mods) {
+            WindowTiler.tileFrontmostViaAX(to: .leftThird)
+        }
+        // Ctrl+Option+2 → center third
+        registerSingle(id: 312, keyCode: 19, modifiers: mods) {
+            WindowTiler.tileFrontmostViaAX(to: .centerThird)
+        }
+        // Ctrl+Option+3 → right third
+        registerSingle(id: 313, keyCode: 20, modifiers: mods) {
+            WindowTiler.tileFrontmostViaAX(to: .rightThird)
+        }
+    }
+}