@lattices/cli 0.4.5 → 0.4.6

package/docs/component-extraction-roadmap.md

@@ -0,0 +1,392 @@
+# Component Extraction Roadmap
+
+This note turns a codebase review into an incremental component plan for `lattices`.
+
+The goal is not to rewrite the app around a new architecture in one move. The goal is to extract a few reusable primitives that make future features cheaper:
+
+- a cmdcmd-style visual window or session switcher
+- one shared action model across hotkeys, palette, voice, daemon, and companion
+- less duplicated window lookup, space lookup, and preview logic
+
+## Why this exists
+
+Three pressure points showed up repeatedly:
+
+1. `WindowTiler.swift` acts like several libraries at once.
+2. action definitions exist in multiple parallel forms.
+3. overlay and panel shells are repeatedly rebuilt per surface.
+
+The result is that new UX surfaces often have to re-solve the same problems:
+
+- how to find a target window
+- how to map a user intent to a canonical action
+- how to show a floating interactive surface
+- how to capture and render previews
+
+## Current duplication seams
+
+### 1. Window and session lookup
+
+The same session-tagged window matching idea appears in multiple places:
+
+- `DesktopModel.windowForSession(...)`
+- tag parsing during desktop polling
+- CG window lookup paths in `WindowTiler`
+- AX window lookup paths in `WindowTiler`
+
+This is the strongest candidate for a single reusable locator.
+
+### 2. Space topology and window membership
+
+Display-space maps, current-space discovery, and window-space membership are rebuilt in several flows instead of being queried from one read model.
+
+This makes space-aware features harder than they need to be:
+
+- move window to space
+- present window on the current space
+- show where a session already lives
+- build a visual desktop map
+
+### 3. Window presentation and motion
+
+`tile`, `present`, `batchMoveAndRaiseWindows`, and related paths all contain their own versions of:
+
+- resolve target
+- move or resize
+- raise
+- activate app
+- mark interaction
+
+That sequencing should be owned by one operation layer.
+
+### 4. Preview capture and preview rendering
+
+The codebase already has useful preview pieces, but they live in separate pockets:
+
+- `WindowPreviewStore` in `HUDRightBar.swift`
+- preview placeholder and preview card variants in HUD
+- separate preview capture in `ScreenMapState.swift`
+
+This is a strong signal that preview should become its own reusable subsystem.
+
+### 5. Action definitions
+
+Action and intent metadata currently live in several places:
+
+- `HotkeyStore.swift`
+- `PaletteCommand.swift`
+- `IntentEngine.swift`
+- `Intents/LatticeIntent.swift`
+- `LatticesApi.swift`
+
+The sharpest duplication is that `IntentEngine.swift` and `Intents/LatticeIntent.swift` each define their own intent schema.
+
+### 6. Overlay and panel shells
+
+There is already a useful shared primitive for normal app windows in `AppWindowShell.swift`, but overlay surfaces still rebuild similar shell code:
+
+- `CommandPaletteWindow.swift`
+- `OmniSearchWindow.swift`
+- `VoiceCommandWindow.swift`
+- `LauncherHUD.swift`
+
+The repeated shell concerns are:
+
+- `NSPanel` setup
+- blur and rounded-mask container setup
+- screen placement
+- activation and dismissal behavior
+- event monitor lifecycle
+
+## Proposed reusable components
+
+This is the target component map.
+
+### Desktop substrate
+
+#### `SessionWindowLocator`
+
+Responsibility:
+
+- resolve a lattices session, title tag, app target, or explicit window id into a canonical window target
+- try fast cache lookup first
+- fall back through CG and AX in one place
+
+Why:
+
+- removes repeated session-tag matching logic
+- gives palette, daemon, voice, HUD, and future switchers the same targeting rules
+
+#### `SpaceTopologySnapshot`
+
+Responsibility:
+
+- expose a single read model for displays, spaces, current space, and window-to-space membership
+
+Why:
+
+- prevents repeated recomputation of display-space facts
+- makes space-aware UIs easier to build
+
+#### `WindowPresenter`
+
+Responsibility:
+
+- own the canonical move, resize, raise, activate, and interaction-marking flow
+- support both single-window and batched operations
+
+Why:
+
+- centralizes the side-effect sequence
+- makes future planners and higher-level actions less fragile
+
+#### `WindowPreviewProvider`
+
+Responsibility:
+
+- capture, cache, and serve still previews or live previews for windows
+- separate capture policy from UI rendering
+
+Why:
+
+- avoids HUD and Screen Map each inventing preview behavior
+- directly supports a visual selector or session fan-out
+
+### Action substrate
+
+#### `ActionRegistry`
+
+Responsibility:
+
+- define canonical verbs once
+- own parameter metadata, user-facing labels, phrase templates, and execution hooks
+
+Minimal shape:
+
+```swift
+enum ActionID: String {
+    case openPalette
+    case openSearch
+    case focusWindow
+    case placeWindow
+    case launchProject
+    case switchLayer
+    case killSession
+    case refreshProjects
+}
+
+struct ActionParam {
+    let name: String
+    let type: ActionParamType
+    let required: Bool
+    let values: [String]?
+}
+
+struct ActionDef {
+    let id: ActionID
+    let title: String
+    let params: [ActionParam]
+    let hotkey: HotkeyMeta?
+    let palette: PaletteMeta?
+    let phrases: [String]
+    let run: (ActionContext) throws -> JSON
+}
+```
+
+Why:
+
+- one action identity across hotkeys, palette, voice, daemon, and companion
+- palette rows become runtime bindings of a verb to a target, not bespoke actions
+
+#### `ActionContext`
+
+Responsibility:
+
+- carry structured arguments plus source information like `hotkey`, `palette`, `voice-local`, `daemon`, or `companion`
+
+Why:
+
+- makes execution and logging more consistent
+
+### Overlay substrate
+
+#### `OverlayPanelShell`
+
+Responsibility:
+
+- build a reusable floating `NSPanel` shell from configuration
+- own blur or plain background, corner radius, window level, collection behavior, and hosting setup
+
+Why:
+
+- extracts the shared Spotlight-style panel construction path
+
+#### `OverlayPlacement`
+
+Responsibility:
+
+- centralize placement policies like centered, spotlight offset, top-center, or mouse-screen placement
+
+Why:
+
+- removes repeated `visibleFrame` math
+
+#### `OverlayLifecycleController`
+
+Responsibility:
+
+- own local event monitors, Escape dismissal, deactivate behavior, and cleanup
+
+Why:
+
+- reduces panel-specific lifecycle glue
+
+### UI primitives
+
+#### `WindowPreviewCard`
+
+Responsibility:
+
+- render a window preview, loading state, and unavailable state consistently
+
+Why:
+
+- low-risk first UI extraction
+- immediately reduces duplicated HUD preview rendering
+
+## Recommended extraction order
+
+The sequence below favors leverage without taking unnecessary risk.
+
+### Slice 1: `WindowPreviewCard`
+
+Extract the repeated preview body and placeholder logic from HUD into a shared SwiftUI component.
+
+Why first:
+
+- UI-only
+- already duplicated
+- does not disturb CGS, AX, or window mutation paths
+
+### Slice 2: `OverlayPanelShell`
+
+Extract the shared panel-construction path from `CommandPaletteWindow` and `OmniSearchWindow`.
+
+Why second:
+
+- those two surfaces are the cleanest near-duplicates
+- builds a reusable shell for a future visual selector
+
+### Slice 3: unify intent schema
+
+Remove the parallel intent-definition structures by expanding or reusing the types in `Intents/LatticeIntent.swift` and pointing them at existing execution handlers.
+
+Why third:
+
+- high leverage
+- removes one entire duplicate definition system
+- proves the registry shape before migrating hotkeys or palette
+
+### Slice 4: `SessionWindowLocator`
+
+Centralize session-tagged lookup across DesktopModel and WindowTiler.
+
+Why fourth:
+
+- strongest desktop duplication seam
+- unlocks cleaner action execution and better future switcher targeting
+
+### Slice 5: `SpaceTopologySnapshot`
+
+Create one query layer for display and space topology.
+
+Why fifth:
+
+- stabilizes space-aware features before touching more motion logic
+
+### Slice 6: `WindowPresenter`
+
+Unify move, resize, raise, activate, and interaction-marking flows.
+
+Why sixth:
+
+- this is higher risk because it sits directly on side effects
+- it is safer after lookup and topology are centralized
+
+### Slice 7: `WindowPreviewProvider`
+
+Lift preview capture and caching out of HUD-specific code and reconcile it with Screen Map preview capture.
+
+Why seventh:
+
+- more useful after overlay shell and preview card exist
+- becomes the substrate for a visual window or session chooser
+
+## Features this should unlock
+
+Once the components above exist, the app can add new surfaces with much less bespoke code.
+
+### cmdcmd-style visual switcher
+
+Use:
+
+- `OverlayPanelShell`
+- `OverlayPlacement`
+- `SessionWindowLocator`
+- `WindowPreviewProvider`
+- `WindowPresenter`
+
+Possible behavior:
+
+- fan out lattices sessions or all windows
+- show live or cached previews
+- focus, tile, move to space, or close from one surface
+
+### Shared action surfaces
+
+Use:
+
+- `ActionRegistry`
+- `ActionContext`
+
+Possible behavior:
+
+- define `placeWindow` once
+- trigger it from voice, hotkey, palette, daemon, or companion
+- keep labels and phrases aligned across surfaces
+
+### Stronger planning and preview
+
+Use:
+
+- `ActionRegistry`
+- `WindowPresenter`
+- `SpaceTopologySnapshot`
+
+Possible behavior:
+
+- preview a multi-window action before applying it
+- build transactional-feeling UI around batched movement
+
+## Things not to do yet
+
+- do not rewrite `WindowTiler.swift` in one shot
+- do not migrate every overlay surface onto one abstraction immediately
+- do not force the palette to become purely registry-generated before the action model is proven
+
+The safer path is:
+
+1. extract small reusable pieces
+2. move one production surface onto them
+3. verify behavior
+4. repeat
+
+## Summary
+
+The strongest architectural opportunity here is not one big framework. It is three small substrates:
+
+- desktop targeting and motion
+- action definition and routing
+- overlay panel construction
+
+If those become reusable, `lattices` gets a much cleaner path to new features without making every new surface solve the same desktop and execution problems again.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lattices/cli",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "description": "Agentic window manager for macOS — programmable workspace, smart layouts, managed tmux sessions, and a 35+-method agent API",
   "bin": {
     "lattices": "./bin/lattices.ts",
@@ -28,6 +28,8 @@
   },
   "scripts": {
     "dev": "bun --cwd docs-site dev",
+    "test:e2e": "node --experimental-strip-types --test test/e2e-daemon.test.mjs",
+    "test:e2e:voice": "node --experimental-strip-types test/eval-voice.js",
     "typecheck": "tsc --noEmit",
     "build:app-bundle": "bash ./bin/lattices-dev build",
     "prepack": "bash ./bin/lattices-dev build"

package/app/Sources/CommandPaletteWindow.swift

@@ -1,134 +0,0 @@
-import AppKit
-import SwiftUI
-
-/// NSPanel subclass that accepts key events even without a titlebar
-private class KeyablePanel: NSPanel {
-    override var canBecomeKey: Bool { true }
-    override var canBecomeMain: Bool { true }
-}
-
-final class CommandPaletteWindow {
-    static let shared = CommandPaletteWindow()
-
-    private var panel: NSPanel?
-    private var scanner: ProjectScanner?
-
-    func configure(scanner: ProjectScanner) {
-        self.scanner = scanner
-    }
-
-    var isVisible: Bool { panel?.isVisible ?? false }
-
-    func toggle() {
-        if let p = panel, p.isVisible {
-            dismiss()
-        } else {
-            show()
-        }
-    }
-
-    func show() {
-        // Always rebuild for fresh command state
-        dismiss()
-
-        guard let scanner = scanner else { return }
-
-        // Ensure projects are up to date (full scan if list is empty,
-        // e.g. palette opened via hotkey before main popover appeared)
-        if scanner.projects.isEmpty {
-            scanner.scan()
-        } else {
-            scanner.refreshStatus()
-        }
-
-        let commands = CommandBuilder.build(scanner: scanner)
-        let view = CommandPaletteView(commands: commands) { [weak self] in
-            self?.dismiss()
-        }
-        .preferredColorScheme(.dark)
-
-        let hosting = NSHostingView(rootView: view)
-        hosting.translatesAutoresizingMaskIntoConstraints = false
-
-        let panel = KeyablePanel(
-            contentRect: NSRect(x: 0, y: 0, width: 540, height: 440),
-            styleMask: [.nonactivatingPanel],
-            backing: .buffered,
-            defer: false
-        )
-
-        panel.isOpaque = false
-        panel.backgroundColor = .clear
-        panel.hasShadow = true
-        panel.level = .floating
-        panel.isMovableByWindowBackground = true
-        panel.hidesOnDeactivate = true
-        panel.collectionBehavior = [.canJoinAllSpaces, .fullScreenAuxiliary]
-        panel.isReleasedWhenClosed = false
-
-        // Use NSVisualEffectView as contentView with a maskImage to communicate
-        // the rounded shape to the window server (layer.cornerRadius only clips
-        // at the view level — the window backing store stays rectangular)
-        let cornerRadius: CGFloat = 14
-
-        let effectView = NSVisualEffectView()
-        effectView.blendingMode = .behindWindow
-        effectView.material = .popover
-        effectView.state = .active
-        effectView.wantsLayer = true
-        effectView.maskImage = Self.maskImage(cornerRadius: cornerRadius)
-
-        panel.contentView = effectView
-
-        effectView.addSubview(hosting)
-        NSLayoutConstraint.activate([
-            hosting.leadingAnchor.constraint(equalTo: effectView.leadingAnchor),
-            hosting.trailingAnchor.constraint(equalTo: effectView.trailingAnchor),
-            hosting.topAnchor.constraint(equalTo: effectView.topAnchor),
-            hosting.bottomAnchor.constraint(equalTo: effectView.bottomAnchor),
-        ])
-
-        // Center horizontally, slightly above vertical center (Spotlight-style)
-        if let screen = NSScreen.main {
-            let screenFrame = screen.visibleFrame
-            let x = screenFrame.midX - 270
-            let y = screenFrame.midY - 220 + (screenFrame.height * 0.1)
-            panel.setFrameOrigin(NSPoint(x: x, y: y))
-        }
-
-        panel.makeKeyAndOrderFront(nil)
-        NSApp.activate(ignoringOtherApps: true)
-
-        self.panel = panel
-        AppDelegate.updateActivationPolicy()
-    }
-
-    func dismiss() {
-        panel?.orderOut(nil)
-        panel = nil
-        AppDelegate.updateActivationPolicy()
-    }
-
-    /// Stretchable mask image for rounded corners — capInsets preserve the
-    /// corner arcs while the center stretches to any window size
-    private static func maskImage(cornerRadius: CGFloat) -> NSImage {
-        let edgeLength = 2.0 * cornerRadius + 1.0
-        let maskImage = NSImage(
-            size: NSSize(width: edgeLength, height: edgeLength),
-            flipped: false
-        ) { rect in
-            let path = NSBezierPath(roundedRect: rect, xRadius: cornerRadius, yRadius: cornerRadius)
-            NSColor.black.set()
-            path.fill()
-            return true
-        }
-        maskImage.capInsets = NSEdgeInsets(
-            top: cornerRadius,
-            left: cornerRadius,
-            bottom: cornerRadius,
-            right: cornerRadius
-        )
-        maskImage.resizingMode = .stretch
-        return maskImage
-    }
-}

package/app/Sources/OmniSearchWindow.swift

@@ -1,165 +0,0 @@
-import AppKit
-import SwiftUI
-
-private final class OmniSearchPanel: NSPanel {
-    override var canBecomeKey: Bool { true }
-    override var canBecomeMain: Bool { true }
-
-    override func sendEvent(_ event: NSEvent) {
-        if event.type == .leftMouseDown || event.type == .rightMouseDown {
-            if !NSApp.isActive {
-                NSApp.activate(ignoringOtherApps: true)
-            }
-            if !isKeyWindow {
-                makeKey()
-            }
-        }
-        super.sendEvent(event)
-    }
-}
-
-private final class OmniSearchHostingView<Content: View>: NSHostingView<Content> {
-    override func acceptsFirstMouse(for event: NSEvent?) -> Bool { true }
-    override var focusRingType: NSFocusRingType { get { .none } set {} }
-}
-
-final class OmniSearchWindow {
-    static let shared = OmniSearchWindow()
-
-    private var panel: NSPanel?
-    private var keyMonitor: Any?
-    private var state: OmniSearchState?
-
-    var isVisible: Bool { panel?.isVisible ?? false }
-
-    func toggle() {
-        if isVisible {
-            dismiss()
-        } else {
-            show()
-        }
-    }
-
-    func show() {
-        if let p = panel, p.isVisible {
-            p.makeKeyAndOrderFront(nil)
-            NSApp.activate(ignoringOtherApps: true)
-            return
-        }
-
-        // Fresh state each time
-        let searchState = OmniSearchState()
-        state = searchState
-
-        let view = OmniSearchView(state: searchState) { [weak self] in
-            self?.dismiss()
-        }
-        .preferredColorScheme(.dark)
-
-        let hosting = OmniSearchHostingView(rootView: view)
-        hosting.translatesAutoresizingMaskIntoConstraints = false
-
-        let p = OmniSearchPanel(
-            contentRect: NSRect(x: 0, y: 0, width: 520, height: 480),
-            styleMask: [.titled, .closable, .resizable, .utilityWindow, .nonactivatingPanel],
-            backing: .buffered,
-            defer: false
-        )
-        p.title = "Search"
-        p.titlebarAppearsTransparent = true
-        p.titleVisibility = .hidden
-        p.isMovableByWindowBackground = true
-        p.level = .floating
-        p.isOpaque = false
-        p.backgroundColor = NSColor(red: 0.11, green: 0.11, blue: 0.12, alpha: 1.0)
-        p.hasShadow = true
-        p.appearance = NSAppearance(named: .darkAqua)
-        p.collectionBehavior = [.canJoinAllSpaces, .fullScreenAuxiliary]
-        p.minSize = NSSize(width: 400, height: 300)
-        p.maxSize = NSSize(width: 700, height: 700)
-        p.hidesOnDeactivate = false
-        p.becomesKeyOnlyIfNeeded = false
-
-        let effectView = NSVisualEffectView()
-        effectView.blendingMode = .behindWindow
-        effectView.material = .popover
-        effectView.state = .active
-        effectView.wantsLayer = true
-        effectView.maskImage = Self.maskImage(cornerRadius: 14)
-        p.contentView = effectView
-
-        effectView.addSubview(hosting)
-        NSLayoutConstraint.activate([
-            hosting.leadingAnchor.constraint(equalTo: effectView.leadingAnchor),
-            hosting.trailingAnchor.constraint(equalTo: effectView.trailingAnchor),
-            hosting.topAnchor.constraint(equalTo: effectView.topAnchor),
-            hosting.bottomAnchor.constraint(equalTo: effectView.bottomAnchor),
-        ])
-
-        // Center on screen
-        if let screen = NSScreen.main {
-            let visibleFrame = screen.visibleFrame
-            let x = visibleFrame.midX - 260
-            let y = visibleFrame.midY + 60  // slightly above center
-            p.setFrameOrigin(NSPoint(x: x, y: y))
-        }
-
-        p.makeKeyAndOrderFront(nil)
-        NSApp.activate(ignoringOtherApps: true)
-        panel = p
-
-        // Key monitor: Escape → dismiss, arrow keys → navigate, Enter → activate
-        keyMonitor = NSEvent.addLocalMonitorForEvents(matching: .keyDown) { [weak self] event in
-            guard self?.panel?.isKeyWindow == true else { return event }
-
-            switch event.keyCode {
-            case 53: // Escape
-                self?.dismiss()
-                return nil
-            case 125: // ↓
-                self?.state?.moveSelection(1)
-                return nil
-            case 126: // ↑
-                self?.state?.moveSelection(-1)
-                return nil
-            case 36: // Enter
-                self?.state?.activateSelected()
-                self?.dismiss()
-                return nil
-            default:
-                return event
-            }
-        }
-    }
-
-    func dismiss() {
-        panel?.orderOut(nil)
-        panel = nil
-        state = nil
-        if let monitor = keyMonitor {
-            NSEvent.removeMonitor(monitor)
-            keyMonitor = nil
-        }
-    }
-
-    private static func maskImage(cornerRadius: CGFloat) -> NSImage {
-        let edgeLength = 2.0 * cornerRadius + 1.0
-        let maskImage = NSImage(
-            size: NSSize(width: edgeLength, height: edgeLength),
-            flipped: false
-        ) { rect in
-            let path = NSBezierPath(roundedRect: rect, xRadius: cornerRadius, yRadius: cornerRadius)
-            NSColor.black.set()
-            path.fill()
-            return true
-        }
-        maskImage.capInsets = NSEdgeInsets(
-            top: cornerRadius,
-            left: cornerRadius,
-            bottom: cornerRadius,
-            right: cornerRadius
-        )
-        maskImage.resizingMode = .stretch
-        return maskImage
-    }
-}