@arach/lattices 0.1.0

package/README.md

@@ -0,0 +1,157 @@
+<picture>
+  <img alt="lattice" src="www/public/og.png" />
+</picture>
+
+# lattice
+
+Declarative tmux sessions for developers.
+
+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.
+
+## Install
+
+```sh
+npm install -g lattice
+```
+
+## Quick start
+
+```sh
+cd my-project
+lattice
+```
+
+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.
+
+## How it works
+
+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
+
+## Configuration
+
+Drop a `.lattice.json` in your project root:
+
+```json
+{
+  "ensure": true,
+  "panes": [
+    { "name": "claude", "cmd": "claude", "size": 60 },
+    { "name": "server", "cmd": "pnpm dev" },
+    { "name": "tests",  "cmd": "pnpm test --watch" }
+  ]
+}
+```
+
+### 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) |
+
+### Layouts
+
+```
+2 panes — side-by-side          3+ panes — main-vertical
+
+┌──────────┬─────────┐         ┌──────────┬─────────┐
+│  claude   │ server  │         │  claude   │ server  │
+│  (60%)   │ (40%)   │         │  (60%)   ├─────────┤
+└──────────┴─────────┘         │          │ tests   │
+                                └──────────┴─────────┘
+```
+
+## Auto-detection
+
+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
+```
+
+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.
+
+## Tab groups
+
+Bundle related projects as tabs within a single terminal window.
+Configure in `~/.lattice/workspace.json`:
+
+```json
+{
+  "name": "my-setup",
+  "groups": [
+    {
+      "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" }
+      ]
+    }
+  ]
+}
+```
+
+Each tab gets its own tmux window with pane layout from its `.lattice.json`.
+
+```sh
+lattice groups            # List groups with status
+lattice group talkie      # Launch or attach
+lattice tab talkie iOS    # Switch to a tab
+```
+
+Groups can also be referenced in [workspace layers](https://lattice.dev/docs/layers) to tile a whole group into a screen position.
+
+## CLI reference
+
+```
+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
+```
+
+## Requirements
+
+- **tmux** — `brew install tmux`
+- **Node.js** 18+
+- **macOS** (the CLI is macOS-only, the menu bar app requires arm64)
+
+## License
+
+MIT

package/app/Lattices.app/Contents/Info.plist

@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>CFBundleIdentifier</key>
+    <string>com.arach.lattices</string>
+    <key>CFBundleName</key>
+    <string>Lattices</string>
+    <key>CFBundleExecutable</key>
+    <string>Lattices</string>
+    <key>CFBundleIconFile</key>
+    <string>AppIcon</string>
+    <key>CFBundlePackageType</key>
+    <string>APPL</string>
+    <key>CFBundleVersion</key>
+    <string>1</string>
+    <key>CFBundleShortVersionString</key>
+    <string>0.1.0</string>
+    <key>LSUIElement</key>
+    <true/>
+    <key>NSSupportsAutomaticTermination</key>
+    <true/>
+</dict>
+</plist>

package/app/Package.swift

@@ -0,0 +1,13 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+let package = Package(
+    name: "Lattices",
+    platforms: [.macOS(.v13)],
+    targets: [
+        .executableTarget(
+            name: "Lattices",
+            path: "Sources"
+        )
+    ]
+)

package/app/Sources/App.swift

@@ -0,0 +1,49 @@
+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)
+    }
+}

package/app/Sources/AppDelegate.swift

@@ -0,0 +1,104 @@
+import AppKit
+
+/// Registers the global hotkey (Cmd+Shift+D) on launch.
+/// The menu bar itself is handled by SwiftUI's MenuBarExtra.
+class AppDelegate: NSObject, NSApplicationDelegate {
+
+    /// 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
+        let desired: NSApplication.ActivationPolicy = hasVisibleWindow ? .regular : .accessory
+        if NSApp.activationPolicy() != desired {
+            NSApp.setActivationPolicy(desired)
+            if desired == .regular {
+                NSApp.activate(ignoringOtherApps: true)
+            }
+        }
+    }
+
+    func applicationDidFinishLaunching(_ notification: Notification) {
+        NSApp.setActivationPolicy(.accessory)
+        NSApp.appearance = NSAppearance(named: .darkAqua)
+
+        CommandPaletteWindow.shared.configure(scanner: ProjectScanner.shared)
+
+        // 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() }
+
+        // Layer-switching hotkeys
+        let workspace = WorkspaceManager.shared
+        let layerCount = (workspace.config?.layers ?? []).count
+        for (i, action) in HotkeyAction.layerActions.prefix(layerCount).enumerated() {
+            let index = i
+            store.register(action: action) { workspace.tileLayer(index: index) }
+        }
+
+        // Tiling hotkeys
+        let tileMap: [(HotkeyAction, TilePosition)] = [
+            (.tileLeft, .left), (.tileRight, .right),
+            (.tileMaximize, .maximize), (.tileCenter, .center),
+            (.tileTopLeft, .topLeft), (.tileTopRight, .topRight),
+            (.tileBottomLeft, .bottomLeft), (.tileBottomRight, .bottomRight),
+            (.tileTop, .top), (.tileBottom, .bottom),
+            (.tileLeftThird, .leftThird), (.tileCenterThird, .centerThird),
+            (.tileRightThird, .rightThird),
+        ]
+        for (action, position) in tileMap {
+            store.register(action: action) { WindowTiler.tileFrontmostViaAX(to: position) }
+        }
+        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
+        DesktopModel.shared.start()
+        TmuxModel.shared.start()
+        ProcessModel.shared.start()
+        LatticesApi.setup()
+        DaemonServer.shared.start()
+
+        // --diagnostics flag: auto-open diagnostics panel on launch
+        if CommandLine.arguments.contains("--diagnostics") {
+            DispatchQueue.main.asyncAfter(deadline: .now() + 0.5) {
+                DiagnosticWindow.shared.show()
+            }
+        }
+
+        // --screen-map flag: auto-open screen map on launch
+        if CommandLine.arguments.contains("--screen-map") {
+            DispatchQueue.main.asyncAfter(deadline: .now() + 0.5) {
+                ScreenMapWindowController.shared.show()
+            }
+        }
+    }
+
+    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()
+    }
+}

package/app/Sources/AppShellView.swift

@@ -0,0 +1,62 @@
+import SwiftUI
+
+// MARK: - Navigation Pages
+
+enum AppPage: String, CaseIterable {
+    case screenMap
+    case settings
+    case docs
+
+    var label: String {
+        switch self {
+        case .screenMap: return "Screen Map"
+        case .settings:  return "Settings"
+        case .docs:      return "Docs"
+        }
+    }
+
+    var icon: String {
+        switch self {
+        case .screenMap: return "rectangle.3.group"
+        case .settings:  return "gearshape"
+        case .docs:      return "book"
+        }
+    }
+}
+
+// MARK: - App Shell View
+
+struct AppShellView: View {
+    @ObservedObject var controller: ScreenMapController
+    @ObservedObject var windowController = ScreenMapWindowController.shared
+
+    var body: some View {
+        contentArea
+            .background(Palette.bg)
+    }
+
+    // MARK: - Content Area
+
+    @ViewBuilder
+    private var contentArea: some View {
+        switch windowController.activePage {
+        case .screenMap:
+            ScreenMapView(controller: controller, onNavigate: { page in
+                windowController.activePage = page
+            })
+        case .settings:
+            SettingsContentView(
+                prefs: Preferences.shared,
+                scanner: ProjectScanner.shared,
+                onBack: { windowController.activePage = .screenMap; controller.enter() }
+            )
+        case .docs:
+            SettingsContentView(
+                page: .docs,
+                prefs: Preferences.shared,
+                scanner: ProjectScanner.shared,
+                onBack: { windowController.activePage = .screenMap; controller.enter() }
+            )
+        }
+    }
+}

package/app/Sources/AppTypeClassifier.swift

@@ -0,0 +1,70 @@
+import Foundation
+
+enum AppType: String, CaseIterable {
+    case terminal
+    case editor
+    case browser
+    case chat
+    case media
+    case design
+    case system
+    case other
+
+    var label: String { rawValue }
+}
+
+enum AppTypeClassifier {
+    private static let nameMap: [String: AppType] = [
+        // Terminals
+        "iTerm2": .terminal, "Terminal": .terminal, "Alacritty": .terminal,
+        "kitty": .terminal, "Warp": .terminal, "Hyper": .terminal,
+        "WezTerm": .terminal, "Rio": .terminal, "Ghostty": .terminal,
+
+        // Editors / IDEs
+        "Xcode": .editor, "Code": .editor, "Visual Studio Code": .editor,
+        "Cursor": .editor, "Sublime Text": .editor, "TextEdit": .editor,
+        "Nova": .editor, "BBEdit": .editor, "Zed": .editor,
+        "IntelliJ IDEA": .editor, "WebStorm": .editor, "PyCharm": .editor,
+        "CLion": .editor, "GoLand": .editor, "RustRover": .editor,
+        "Android Studio": .editor, "Fleet": .editor, "Neovide": .editor,
+
+        // Browsers
+        "Safari": .browser, "Google Chrome": .browser, "Firefox": .browser,
+        "Arc": .browser, "Brave Browser": .browser, "Microsoft Edge": .browser,
+        "Orion": .browser, "Vivaldi": .browser, "Opera": .browser,
+        "Chrome": .browser, "Zen Browser": .browser,
+
+        // Chat / Communication
+        "Slack": .chat, "Discord": .chat, "Messages": .chat,
+        "Telegram": .chat, "WhatsApp": .chat, "Signal": .chat,
+        "Teams": .chat, "Microsoft Teams": .chat, "Zoom": .chat,
+        "FaceTime": .chat, "Skype": .chat,
+
+        // Media
+        "Spotify": .media, "Music": .media, "QuickTime Player": .media,
+        "VLC": .media, "IINA": .media, "Podcasts": .media,
+        "Photos": .media, "Preview": .media, "mpv": .media,
+
+        // Design
+        "Figma": .design, "Sketch": .design, "Pixelmator Pro": .design,
+        "Affinity Designer 2": .design, "Affinity Photo 2": .design,
+        "Adobe Photoshop": .design, "Adobe Illustrator": .design,
+        "Blender": .design, "OmniGraffle": .design,
+
+        // System
+        "Finder": .system, "System Preferences": .system, "System Settings": .system,
+        "Activity Monitor": .system, "Console": .system, "Disk Utility": .system,
+        "Keychain Access": .system,
+    ]
+
+    static func classify(_ appName: String) -> AppType {
+        if let exact = nameMap[appName] { return exact }
+        // Substring fallback
+        let lower = appName.lowercased()
+        if lower.contains("terminal") || lower.contains("term") { return .terminal }
+        if lower.contains("code") || lower.contains("studio") || lower.contains("edit") { return .editor }
+        if lower.contains("chrome") || lower.contains("firefox") || lower.contains("safari") || lower.contains("browser") { return .browser }
+        if lower.contains("slack") || lower.contains("discord") || lower.contains("chat") || lower.contains("teams") { return .chat }
+        return .other
+    }
+}

package/app/Sources/AppWindowShell.swift

@@ -0,0 +1,63 @@
+import AppKit
+import SwiftUI
+
+/// Shared factory for standalone NSWindow chrome.
+/// Every managed window (Screen Map, Settings, Diagnostics, etc.) uses this
+/// to get consistent title bar styling, dark appearance, and positioning.
+struct AppWindowShell {
+
+    struct Config {
+        var title: String
+        var titleVisible: Bool = true
+        var initialSize: NSSize
+        var minSize: NSSize
+        var maxSize: NSSize
+        var miniaturizable: Bool = true
+    }
+
+    /// Create a styled NSWindow hosting a SwiftUI root view.
+    static func makeWindow<V: View>(config: Config, rootView: V) -> NSWindow {
+        let hosting = NSHostingView(rootView: rootView.preferredColorScheme(.dark))
+        hosting.frame = NSRect(origin: .zero, size: config.initialSize)
+
+        var styleMask: NSWindow.StyleMask = [.titled, .closable, .resizable]
+        if config.miniaturizable { styleMask.insert(.miniaturizable) }
+
+        let w = NSWindow(
+            contentRect: NSRect(origin: .zero, size: config.initialSize),
+            styleMask: styleMask,
+            backing: .buffered,
+            defer: false
+        )
+        w.contentView = hosting
+        w.title = config.title
+        w.titlebarAppearsTransparent = true
+        w.titleVisibility = config.titleVisible ? .visible : .hidden
+        w.isReleasedWhenClosed = false
+        w.backgroundColor = NSColor(red: 0.11, green: 0.11, blue: 0.12, alpha: 1.0)
+        w.appearance = NSAppearance(named: .darkAqua)
+        w.minSize = config.minSize
+        w.maxSize = config.maxSize
+        return w
+    }
+
+    /// Center the window on screen, nudged 8% above vertical center.
+    /// Clamps to 92% screen width / 85% screen height.
+    static func positionCentered(_ window: NSWindow) {
+        guard let screen = NSScreen.main else { return }
+        let frame = screen.visibleFrame
+        let size = window.frame.size
+        let w = min(size.width, frame.width * 0.92)
+        let h = min(size.height, frame.height * 0.85)
+        let x = frame.midX - w / 2
+        let y = frame.midY - h / 2 + (frame.height * 0.08)
+        window.setFrame(NSRect(x: x, y: y, width: w, height: h), display: true)
+    }
+
+    /// Bring the window to front and update activation policy.
+    static func present(_ window: NSWindow) {
+        window.makeKeyAndOrderFront(nil)
+        NSApp.activate(ignoringOtherApps: true)
+        AppDelegate.updateActivationPolicy()
+    }
+}