@arach/lattices 0.1.0 → 0.2.1

package/README.md

@@ -1,39 +1,68 @@
 <picture>
-  <img alt="lattice" src="www/public/og.png" />
+  <img alt="lattices" src="site/public/og.png" />
 </picture>
 
-# lattice
+# lattices
 
-Declarative tmux sessions for developers.
+macOS workspace manager. Menu bar app, CLI, and a WebSocket API
+so your AI agents can control the desktop.
 
-One command to create a named tmux session with your tools running. Auto-detects your stack, fully configurable with `.lattice.json`, and a native macOS menu bar app.
+Window tiling, project discovery, workspace layers, on-screen OCR,
+and optionally tmux-powered persistent sessions. 30 RPC methods
+over WebSocket. One JSON config file.
 
 ## Install
 
 ```sh
-npm install -g lattice
+npm install -g @arach/lattices
 ```
 
 ## Quick start
 
 ```sh
-cd my-project
-lattice
+# Launch the menu bar app
+lattices app
+
+# Open the command palette from anywhere
+# Cmd+Shift+M
+```
+
+The app scans your projects, tiles windows, and gives you a command
+palette for everything. Add tmux if you want persistent terminal
+sessions:
+
+```sh
+brew install tmux
+cd my-project && lattices
 ```
 
-That's it. lattice creates a tmux session named after your project with Claude Code on the left and your dev server on the right. It detects your package manager and dev command automatically.
+That creates a tmux session with Claude Code on the left and your
+dev server on the right. Detach, close your laptop, come back later,
+reattach. Everything is where you left it.
+
+## What it does
+
+**Menu bar app** sits in your menu bar. Command palette, window tiling,
+project discovery, workspace layers, OCR, and the daemon API. Works
+with or without tmux.
+
+**CLI** for tiling, session management, OCR queries, and tab groups.
 
-## How it works
+**Daemon API** on `ws://127.0.0.1:9399`. 30 RPC methods and 5
+real-time events. Agents can discover projects, tile windows, launch
+sessions, switch layers, and read on-screen text.
 
-1. **Run `lattice`** in any project directory
-2. A named tmux session is created with configured panes
-3. Commands start running in each pane immediately
-4. Detach with `Ctrl+b d`, reattach by running `lattice` again
-5. Sessions persist in the background until you kill them
+```js
+import { daemonCall } from '@arach/lattices/daemon-client'
+
+const windows = await daemonCall('windows.list')
+await daemonCall('session.launch', { path: '/Users/you/dev/frontend' })
+await daemonCall('window.tile', { session: 'frontend-a1b2c3', position: 'left' })
+```
 
 ## Configuration
 
-Drop a `.lattice.json` in your project root:
+Drop a `.lattices.json` in your project root:
 
 ```json
 {
@@ -46,111 +75,93 @@ Drop a `.lattice.json` in your project root:
 }
 ```
 
-### Pane options
-
-| Field  | Description                              |
-|--------|------------------------------------------|
-| `name` | Label for the pane (for your reference)  |
-| `cmd`  | Command to run in the pane               |
-| `size` | Width % for the first pane (default: 60) |
-
-### Session options
-
-| Field     | Description                                                                 |
-|-----------|-----------------------------------------------------------------------------|
-| `ensure`  | Auto-restart exited commands on reattach                                    |
-| `prefill` | Type exited commands into panes on reattach without running (you hit Enter) |
+Or skip it. Without a config, lattices reads your `package.json` and
+picks the right dev command automatically.
 
 ### Layouts
 
 ```
-2 panes — side-by-side          3+ panes — main-vertical
-
-┌──────────┬─────────┐         ┌──────────┬─────────┐
-│  claude   │ server  │         │  claude   │ server  │
-│  (60%)   │ (40%)   │         │  (60%)   ├─────────┤
-└──────────┴─────────┘         │          │ tests   │
-                                └──────────┴─────────┘
-```
-
-## Auto-detection
+2 panes              3+ panes
 
-Without a config file, lattice reads your `package.json` and picks the right command:
-
-- Checks `scripts.dev`, `scripts.start`, `scripts.serve`, `scripts.watch`
-- Detects package manager from lock files (pnpm, bun, yarn, npm)
-- Falls back to a shell if no dev command is found
-
-## Menu bar app
-
-A macOS companion app for managing sessions without touching the terminal.
-
-```sh
-lattice app          # Launch (builds from source or downloads binary)
-lattice app build    # Force rebuild from source
-lattice app quit     # Stop the menu bar app
+┌──────────┬───────┐ ┌──────────┬───────┐
+│  claude  │server │ │  claude  │server │
+│  (60%)   │(40%)  │ │  (60%)   ├───────┤
+└──────────┴───────┘ │          │tests  │
+                     └──────────┴───────┘
 ```
 
-Features:
-- See all projects and their session status at a glance
-- Launch, attach, or detach sessions with a click
-- **Command palette** (`Cmd+Shift+M`): Raycast-style launcher for all actions — fuzzy search, keyboard navigation, instant access to projects, window tiling, and settings
-- Auto-scans your project directories
-- Built with SwiftUI, runs natively on macOS
-
-The app tries to compile from source first (requires Xcode CLI tools), falling back to a pre-built arm64 binary from GitHub releases.
+## Workspace layers
 
-## Tab groups
+Group projects into switchable contexts. `Cmd+Option+1` tiles your
+frontend and API side by side. `Cmd+Option+2` switches to the mobile
+stack. All sessions stay alive across switches.
 
-Bundle related projects as tabs within a single terminal window.
-Configure in `~/.lattice/workspace.json`:
+Configure in `~/.lattices/workspace.json`:
 
 ```json
 {
-  "name": "my-setup",
-  "groups": [
+  "layers": [
     {
-      "id": "talkie",
-      "label": "Talkie",
-      "tabs": [
-        { "path": "/Users/you/dev/talkie-ios", "label": "iOS" },
-        { "path": "/Users/you/dev/talkie-web", "label": "Website" },
-        { "path": "/Users/you/dev/talkie-api", "label": "API" }
+      "id": "web", "label": "Web",
+      "projects": [
+        { "path": "/Users/you/dev/frontend", "tile": "left" },
+        { "path": "/Users/you/dev/api", "tile": "right" }
       ]
     }
   ]
 }
 ```
 
-Each tab gets its own tmux window with pane layout from its `.lattice.json`.
+## Tab groups
+
+Bundle related repos as tabs in one session. Each tab gets its own
+pane layout from its `.lattices.json`.
 
 ```sh
-lattice groups            # List groups with status
-lattice group talkie      # Launch or attach
-lattice tab talkie iOS    # Switch to a tab
+lattices group talkie      # Launch iOS, macOS, Web, API as tabs
+lattices tab talkie iOS    # Switch to the iOS tab
 ```
 
-Groups can also be referenced in [workspace layers](https://lattice.dev/docs/layers) to tile a whole group into a screen position.
+## Screen OCR
+
+The app reads text from visible windows using Apple Vision and indexes
+it with FTS5 full-text search. Agents can search for error messages,
+read terminal output, or find content across all your windows.
+
+```js
+await daemonCall('ocr.scan')
+const errors = await daemonCall('ocr.search', { query: 'error OR failed' })
+```
 
-## CLI reference
+## CLI
 
 ```
-lattice                    Create or reattach to a session for the current project
-lattice init               Generate a .lattice.json config
-lattice ls                 List active tmux sessions
-lattice kill [name]        Kill a session (defaults to current project)
-lattice group [id]         List tab groups or launch/attach a group
-lattice groups             List all tab groups with status
-lattice tab <group> [tab]  Switch tab within a group (by label or index)
-lattice app                Launch the menu bar companion app
-lattice help               Show help
+lattices                    Create or reattach to session
+lattices init               Generate .lattices.json
+lattices ls                 List active sessions
+lattices kill [name]        Kill a session
+lattices tile <position>    Tile frontmost window
+lattices group [id]         Launch or attach a tab group
+lattices tab <group> [tab]  Switch tab within a group
+lattices ocr                View current OCR snapshot
+lattices ocr search <query> Search OCR history
+lattices app                Launch the menu bar app
+lattices help               Show help
 ```
 
 ## Requirements
 
-- **tmux** — `brew install tmux`
-- **Node.js** 18+
-- **macOS** (the CLI is macOS-only, the menu bar app requires arm64)
+- macOS 13.0+
+- Node.js 18+
+
+### Optional
+
+- tmux for persistent terminal sessions (`brew install tmux`)
+- Swift 5.9+ to build the menu bar app from source
+
+## Docs
+
+Full documentation at [lattices.dev/docs](https://lattices.dev/docs/overview).
 
 ## License
 

package/app/Sources/ActionRow.swift

@@ -0,0 +1,61 @@
+import SwiftUI
+
+/// A single action row with shortcut badge, label, optional icon, and hotkey hint.
+struct ActionRow: View {
+    let shortcut: String
+    let label: String
+    var hotkey: String? = nil
+    var icon: String? = nil
+    var accentColor: Color = Palette.textDim
+    var action: () -> Void
+
+    @State private var isHovered = false
+
+    var body: some View {
+        Button(action: action) {
+            HStack(spacing: 10) {
+                // Shortcut badge
+                Text(shortcut)
+                    .font(Typo.monoBold(10))
+                    .foregroundColor(accentColor)
+                    .frame(width: 18, height: 18)
+                    .background(
+                        RoundedRectangle(cornerRadius: 4)
+                            .fill(accentColor.opacity(0.12))
+                    )
+
+                // Icon
+                if let icon {
+                    Image(systemName: icon)
+                        .font(.system(size: 11, weight: .medium))
+                        .foregroundColor(isHovered ? Palette.text : Palette.textDim)
+                        .frame(width: 14)
+                }
+
+                // Label
+                Text(label)
+                    .font(Typo.mono(12))
+                    .foregroundColor(isHovered ? Palette.text : Palette.textDim)
+                    .lineLimit(1)
+
+                Spacer()
+
+                // Hotkey
+                if let hotkey {
+                    Text(hotkey)
+                        .font(Typo.mono(10))
+                        .foregroundColor(Palette.textMuted)
+                }
+            }
+            .padding(.horizontal, 10)
+            .padding(.vertical, 6)
+            .background(
+                RoundedRectangle(cornerRadius: 5)
+                    .fill(isHovered ? Palette.surfaceHov : Color.clear)
+            )
+            .contentShape(Rectangle())
+        }
+        .buttonStyle(.plain)
+        .onHover { isHovered = $0 }
+    }
+}

package/app/Sources/App.swift

@@ -3,47 +3,8 @@ import SwiftUI
 @main
 struct LatticesApp: App {
     @NSApplicationDelegateAdaptor(AppDelegate.self) var delegate
-    @StateObject private var scanner = ProjectScanner.shared
-
-    /// 3×3 grid icon for the menu bar — L-shape bright, rest dim (template for auto light/dark)
-    private static let menuBarIcon: NSImage = {
-        let size: CGFloat = 18
-        let img = NSImage(size: NSSize(width: size, height: size), flipped: false) { _ in
-            let pad: CGFloat = 2
-            let gap: CGFloat = 1.5
-            let cellSize = (size - 2 * pad - 2 * gap) / 3
-
-            // L-shape: left column + bottom row are solid, rest are dim
-            let solidCells: Set<Int> = [0, 3, 6, 7, 8]  // (0,0),(1,0),(2,0),(2,1),(2,2)
-
-            for row in 0..<3 {
-                for col in 0..<3 {
-                    let idx = row * 3 + col
-                    let x = pad + CGFloat(col) * (cellSize + gap)
-                    let y = pad + CGFloat(row) * (cellSize + gap)
-                    let rect = NSRect(x: x, y: y, width: cellSize, height: cellSize)
-
-                    if solidCells.contains(idx) {
-                        NSColor.black.setFill()
-                    } else {
-                        NSColor.black.withAlphaComponent(0.25).setFill()
-                    }
-                    let path = NSBezierPath(roundedRect: rect, xRadius: 0.8, yRadius: 0.8)
-                    path.fill()
-                }
-            }
-            return true
-        }
-        img.isTemplate = true
-        return img
-    }()
 
     var body: some Scene {
-        MenuBarExtra {
-            MainView(scanner: scanner)
-        } label: {
-            Image(nsImage: Self.menuBarIcon)
-        }
-        .menuBarExtraStyle(.window)
+        Settings { EmptyView() }
     }
 }

package/app/Sources/AppDelegate.swift

@@ -1,18 +1,55 @@
 import AppKit
+import SwiftUI
 
-/// Registers the global hotkey (Cmd+Shift+D) on launch.
-/// The menu bar itself is handled by SwiftUI's MenuBarExtra.
-class AppDelegate: NSObject, NSApplicationDelegate {
+/// Manages the NSStatusItem (menu bar icon), left-click popover, and right-click context menu.
+/// Replaces the previous SwiftUI MenuBarExtra approach for full click-event control.
+class AppDelegate: NSObject, NSApplicationDelegate, NSPopoverDelegate {
+
+    private var statusItem: NSStatusItem!
+    private var popover: NSPopover?
+    private var contextMenu: NSMenu!
+
+    /// 3×3 grid icon for the menu bar — L-shape bright, rest dim (template for auto light/dark)
+    private static let menuBarIcon: NSImage = {
+        let size: CGFloat = 18
+        let img = NSImage(size: NSSize(width: size, height: size), flipped: true) { _ in
+            let pad: CGFloat = 2
+            let gap: CGFloat = 1.5
+            let cellSize = (size - 2 * pad - 2 * gap) / 3
+
+            let solidCells: Set<Int> = [0, 3, 6, 7, 8]
+
+            for row in 0..<3 {
+                for col in 0..<3 {
+                    let idx = row * 3 + col
+                    let x = pad + CGFloat(col) * (cellSize + gap)
+                    let y = pad + CGFloat(row) * (cellSize + gap)
+                    let rect = NSRect(x: x, y: y, width: cellSize, height: cellSize)
+
+                    if solidCells.contains(idx) {
+                        NSColor.black.setFill()
+                    } else {
+                        NSColor.black.withAlphaComponent(0.25).setFill()
+                    }
+                    let path = NSBezierPath(roundedRect: rect, xRadius: 0.8, yRadius: 0.8)
+                    path.fill()
+                }
+            }
+            return true
+        }
+        img.isTemplate = true
+        return img
+    }()
 
     /// Toggle between .accessory (hidden from Dock/Cmd+Tab) and .regular (visible)
     /// based on whether any managed windows are open.
-    /// Call this after showing or dismissing a window.
     static func updateActivationPolicy() {
         let hasVisibleWindow =
             CommandModeWindow.shared.isVisible ||
             CommandPaletteWindow.shared.isVisible ||
             MainWindow.shared.isVisible ||
-            ScreenMapWindowController.shared.isVisible
+            ScreenMapWindowController.shared.isVisible ||
+            OmniSearchWindow.shared.isVisible
         let desired: NSApplication.ActivationPolicy = hasVisibleWindow ? .regular : .accessory
         if NSApp.activationPolicy() != desired {
             NSApp.setActivationPolicy(desired)
@@ -26,14 +63,29 @@ class AppDelegate: NSObject, NSApplicationDelegate {
         NSApp.setActivationPolicy(.accessory)
         NSApp.appearance = NSAppearance(named: .darkAqua)
 
-        CommandPaletteWindow.shared.configure(scanner: ProjectScanner.shared)
+        // --- Status item ---
+        statusItem = NSStatusBar.system.statusItem(withLength: NSStatusItem.squareLength)
+        if let button = statusItem.button {
+            button.image = Self.menuBarIcon
+            button.action = #selector(statusItemClicked(_:))
+            button.sendAction(on: [.leftMouseUp, .rightMouseUp])
+            button.target = self
+        }
+
+        // --- Context menu (right-click) ---
+        contextMenu = buildContextMenu()
+
+        // --- Hotkey registration ---
+        let scanner = ProjectScanner.shared
+        CommandPaletteWindow.shared.configure(scanner: scanner)
 
-        // Register all hotkeys via HotkeyStore (user-configurable bindings)
         let store = HotkeyStore.shared
         store.register(action: .palette) { CommandPaletteWindow.shared.toggle() }
         store.register(action: .screenMap) { ScreenMapWindowController.shared.toggle() }
         store.register(action: .bezel) { WindowBezel.showBezelForFrontmostWindow() }
         store.register(action: .cheatSheet) { CheatSheetHUD.shared.toggle() }
+        store.register(action: .desktopInventory) { CommandModeWindow.shared.toggle() }
+        store.register(action: .omniSearch) { OmniSearchWindow.shared.toggle() }
 
         // Layer-switching hotkeys
         let workspace = WorkspaceManager.shared
@@ -58,21 +110,13 @@ class AppDelegate: NSObject, NSApplicationDelegate {
         }
         store.register(action: .tileDistribute) { WindowTiler.distributeVisible() }
 
-        // Style the MenuBarExtra panel when it appears
-        NotificationCenter.default.addObserver(
-            forName: NSWindow.didBecomeKeyNotification,
-            object: nil,
-            queue: .main
-        ) { note in
-            guard let panel = note.object as? NSPanel else { return }
-            Self.stylePanel(panel)
-        }
-
         // Check macOS permissions (Accessibility, Screen Recording)
         PermissionChecker.shared.check()
 
         // Start daemon services
+        OcrStore.shared.open()
         DesktopModel.shared.start()
+        OcrModel.shared.start()
         TmuxModel.shared.start()
         ProcessModel.shared.start()
         LatticesApi.setup()
@@ -93,12 +137,98 @@ class AppDelegate: NSObject, NSApplicationDelegate {
         }
     }
 
-    private static func stylePanel(_ panel: NSPanel) {
-        let bg = NSColor(red: 0.11, green: 0.11, blue: 0.12, alpha: 1.0)
-        panel.backgroundColor = bg
-        panel.isOpaque = false
-        panel.hasShadow = true
-        panel.becomesKeyOnlyIfNeeded = false
-        panel.invalidateShadow()
+    // MARK: - Status item click handler
+
+    @objc private func statusItemClicked(_ sender: Any?) {
+        guard let event = NSApp.currentEvent, let button = statusItem.button else { return }
+
+        if event.type == .rightMouseUp {
+            // Right-click → context menu
+            contextMenu.popUp(positioning: nil, at: NSPoint(x: 0, y: button.bounds.height + 4), in: button)
+        } else {
+            // Left-click → toggle popover
+            if let shown = popover, shown.isShown {
+                shown.performClose(sender)
+            } else {
+                let p = makePopover()
+                p.show(relativeTo: button.bounds, of: button, preferredEdge: .minY)
+                p.contentViewController?.view.window?.makeKey()
+            }
+        }
+    }
+
+    /// Dismiss the popover programmatically (e.g. from the pop-out button).
+    func dismissPopover() {
+        popover?.performClose(nil)
     }
+
+    /// Create a fresh popover each time so the SwiftUI view tree isn't kept alive
+    /// when the popover is closed — prevents continuous CPU usage from @Published updates.
+    private func makePopover() -> NSPopover {
+        let p = NSPopover()
+        p.contentViewController = NSHostingController(rootView: MainView(scanner: ProjectScanner.shared))
+        p.behavior = .transient
+        p.contentSize = NSSize(width: 380, height: 520)
+        p.appearance = NSAppearance(named: .darkAqua)
+        p.delegate = self
+        popover = p
+        return p
+    }
+
+    func popoverDidClose(_ notification: Notification) {
+        // Tear down the SwiftUI view tree so observed models stop driving re-renders
+        popover?.contentViewController = nil
+        popover = nil
+    }
+
+    // MARK: - Context menu
+
+    private func buildContextMenu() -> NSMenu {
+        let menu = NSMenu()
+
+        let actions: [(String, String, Selector)] = [
+            ("Command Palette", "⌘⇧M", #selector(menuCommandPalette)),
+            ("Screen Map", "", #selector(menuScreenMap)),
+            ("Desktop Inventory", "", #selector(menuDesktopInventory)),
+            ("Window Bezel", "", #selector(menuWindowBezel)),
+            ("Cheat Sheet", "", #selector(menuCheatSheet)),
+            ("Omni Search", "", #selector(menuOmniSearch)),
+        ]
+        for (title, shortcut, action) in actions {
+            let item = NSMenuItem(title: title, action: action, keyEquivalent: "")
+            item.target = self
+            if !shortcut.isEmpty {
+                // Display-only; the actual hotkey is global
+            }
+            menu.addItem(item)
+        }
+
+        menu.addItem(.separator())
+
+        let settings = NSMenuItem(title: "Settings…", action: #selector(menuSettings), keyEquivalent: ",")
+        settings.target = self
+        menu.addItem(settings)
+
+        let diag = NSMenuItem(title: "Diagnostics", action: #selector(menuDiagnostics), keyEquivalent: "")
+        diag.target = self
+        menu.addItem(diag)
+
+        menu.addItem(.separator())
+
+        let quit = NSMenuItem(title: "Quit Lattices", action: #selector(menuQuit), keyEquivalent: "q")
+        quit.target = self
+        menu.addItem(quit)
+
+        return menu
+    }
+
+    @objc private func menuCommandPalette() { CommandPaletteWindow.shared.toggle() }
+    @objc private func menuScreenMap() { ScreenMapWindowController.shared.toggle() }
+    @objc private func menuDesktopInventory() { CommandModeWindow.shared.toggle() }
+    @objc private func menuWindowBezel() { WindowBezel.showBezelForFrontmostWindow() }
+    @objc private func menuCheatSheet() { CheatSheetHUD.shared.toggle() }
+    @objc private func menuOmniSearch() { OmniSearchWindow.shared.toggle() }
+    @objc private func menuSettings() { SettingsWindowController.shared.show() }
+    @objc private func menuDiagnostics() { DiagnosticWindow.shared.toggle() }
+    @objc private func menuQuit() { NSApp.terminate(nil) }
 }

package/app/Sources/CheatSheetHUD.swift

@@ -231,6 +231,7 @@ struct CheatSheetView: View {
             shortcutRow(action: .screenMap)
             shortcutRow(action: .bezel)
             shortcutRow(action: .cheatSheet)
+            shortcutRow(action: .desktopInventory)
         }
     }