@arach/lattices 0.2.1 → 0.6.1

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/docs/concepts.md

@@ -10,11 +10,11 @@ order: 6
 |------|------------|
 | **Command Palette** | The menu bar app's primary interface (**Cmd+Shift+M**). Searchable list of actions: launch, tile, sync, restart, settings. |
 | **Window Tiling** | Snap terminal windows to preset screen positions (halves, quarters, thirds, maximize, center). Works from the CLI (`lattices tile`) or the command palette. |
-| **Daemon** | WebSocket server (`ws://127.0.0.1:9399`) inside the menu bar app. Exposes 30 RPC methods and 5 real-time events for programmatic control. See the [API reference](/docs/api). |
-| **Agent** | Any program that calls the daemon API autonomously — an AI coding agent, a shell script, a CI pipeline, or a custom tool. |
+| **Agent API** | WebSocket server (`ws://127.0.0.1:9399`) inside the menu bar app. Exposes 35+ RPC methods and 5 real-time events for programmatic control. See the [API reference](/docs/api). |
+| **Agent** | Any program that calls the agent API autonomously — an AI coding agent, a shell script, a CI pipeline, or a custom tool. |
 | **Session** | A persistent tmux workspace that lives in the background. Survives terminal crashes, disconnects, and closing your laptop. One session per project. Requires tmux. |
-| **Pane** | A single terminal view inside a session. A typical setup has two panes side by side — Claude Code on the left, dev server on the right. Requires tmux. |
-| **Attach / Detach** | Attaching connects your terminal to an existing session. Detaching disconnects but keeps the session alive — your dev server keeps running, Claude keeps thinking. Requires tmux. |
+| **Pane** | A single terminal view inside a session. A typical setup has two panes side by side — shell on the left, dev server on the right. Requires tmux. |
+| **Attach / Detach** | Attaching connects your terminal to an existing session. Detaching disconnects but keeps the session alive — your shell and dev server keep running. Requires tmux. |
 | **Sync / Reconcile** | `lattices sync` brings a running session back in line with its declared config — recreates missing panes, re-applies layout, restores labels, re-runs commands in idle panes. Requires tmux. |
 | **Ensure / Prefill** | Two modes for restoring exited commands on reattach. **Ensure** auto-reruns the command. **Prefill** types it but waits for you to press Enter. Set via `.lattices.json`. Requires tmux. |
 | **tmux** | Terminal multiplexer (optional). Provides persistent sessions, pane layouts, and command restoration. Install with `brew install tmux` if you want session management. |
@@ -23,9 +23,9 @@ order: 6
 
 1. You create a `.lattices.json` file in your project root (or run `lattices init`)
 2. The menu bar app discovers the project and adds it to the command palette
-3. You can tile windows, switch layers, search via OCR, and use the daemon API
-4. With tmux installed, `lattices` also creates persistent terminal sessions:
-   - Each pane gets its command (claude, dev server, tests, etc.)
+3. You can tile windows, switch layers, search via OCR, and use the agent API
+4. With tmux installed, `lattices start` also creates persistent terminal sessions:
+   - Each pane gets its command (shell, dev server, tests, etc.)
    - The session persists in the background until you kill it
    - You can attach/detach from any terminal at any time
    - If `ensure` is enabled, exited commands auto-restart on reattach
@@ -35,13 +35,14 @@ order: 6
 <img src="/architecture.svg" alt="lattices architecture diagram" style="margin: 2rem 0; max-width: 100%;" />
 
 - The menu bar app is the core. It provides the command palette,
-  window tiling, OCR, project discovery, and the daemon (a WebSocket
+  window tiling, OCR, project discovery, and the agent API (a WebSocket
   server on `ws://127.0.0.1:9399`). It works with or without tmux.
 - The CLI handles tiling, OCR queries, and (when tmux is installed)
   session management via `tmux` shell commands.
-- Agents and scripts connect to the daemon over WebSocket. They can
+- Agents and scripts connect to the agent API over WebSocket. They can
   do everything the app and CLI can do: discover projects, tile windows,
   switch layers, read on-screen text, and subscribe to real-time events.
+  See the [Agent API reference](/docs/api).
 - When tmux is installed, the app and CLI can also launch, sync, and
   manage persistent terminal sessions. All layers share the same session
   naming convention so they always agree on which session belongs to
@@ -93,7 +94,7 @@ and other macOS window managers.
 
 ### Ensure/prefill restoration (requires tmux)
 
-When you run `lattices` (no arguments) and a session already exists:
+When you run `lattices start` and a session already exists:
 
 1. lattices checks the `ensure` / `prefill` flag in `.lattices.json`
 2. For each pane, it queries `#{pane_current_command}` via tmux
@@ -105,14 +106,14 @@ When you run `lattices` (no arguments) and a session already exists:
 
 ## Agent control
 
-The daemon API gives agents the same control as a human using the
+The agent API gives agents the same control as a human using the
 menu bar app. An agent can list projects and windows, launch sessions,
 tile windows to screen positions, subscribe to real-time events
 (`windows.changed`, `tmux.changed`, `layer.switched`), and sync
 sessions back to their declared config.
 
 A typical orchestrator sets up a multi-project workspace in a few
-`daemonCall()` invocations. See the [Daemon API reference](/docs/api)
+`daemonCall()` invocations. See the [Agent API reference](/docs/api)
 for the full method list and code examples.
 
 ## Key shortcuts (inside tmux)

package/docs/config.md

@@ -14,7 +14,7 @@ workspace layout. lattices reads this file when creating a session.
 ```json
 {
   "panes": [
-    { "name": "claude", "cmd": "claude" },
+    { "name": "shell" },
     { "name": "server", "cmd": "pnpm dev" }
   ]
 }
@@ -26,7 +26,7 @@ workspace layout. lattices reads this file when creating a session.
 {
   "ensure": true,
   "panes": [
-    { "name": "claude", "cmd": "claude", "size": 60 },
+    { "name": "shell", "size": 60 },
     { "name": "server", "cmd": "pnpm dev" },
     { "name": "tests",  "cmd": "pnpm test --watch" }
   ]
@@ -72,7 +72,7 @@ lattices picks a layout based on how many panes you define:
 
 ```
 ┌──────────┬─────────┐
-│  claude  │ server  │
+│  shell   │ server  │
 │  (60%)   │ (40%)   │
 └──────────┴─────────┘
 ```
@@ -83,7 +83,7 @@ Horizontal split. First pane on the left, second on the right.
 
 ```
 ┌──────────┬─────────┐
-│  claude  │ server  │
+│  shell   │ server  │
 │  (60%)   ├─────────┤
 │          │ tests   │
 └──────────┴─────────┘
@@ -96,7 +96,7 @@ on the right.
 
 ```
 ┌──────────┬─────────┐
-│  claude  │ server  │
+│  shell   │ server  │
 │  (60%)   ├─────────┤
 │          │ tests   │
 │          ├─────────┤
@@ -109,10 +109,10 @@ on the right.
 If there's no `.lattices.json`, lattices still works. It will:
 
 1. Create a 2-pane layout (60/40 split)
-2. Run `claude` in the left pane
-3. Auto-detect your dev command from package.json scripts:
+2. Open a shell in the left pane
+3. Auto-detect your dev command from package.json scripts and run it on the right:
    - Looks for: `dev`, `start`, `serve`, `watch` (in that order)
-   - Detects package manager: pnpm > bun > yarn > npm
+   - Detects package manager: bun > pnpm > yarn > npm
 
 ## Creating a config
 
@@ -124,17 +124,42 @@ Run `lattices init` in your project directory to generate a starter
 
 | Command                    | Description                                      |
 |----------------------------|--------------------------------------------------|
-| `lattices`                   | Create or attach to session for current project   |
+| `lattices`                   | Show workspace status and common commands         |
+| `lattices start`             | Create or attach to session for current project   |
+| `lattices tmux`              | Alias for `lattices start`                        |
 | `lattices init`              | Generate .lattices.json config for this project     |
 | `lattices ls`                | List active sessions (requires tmux)              |
 | `lattices kill [name]`       | Kill a session (defaults to current project)      |
 | `lattices sync`              | Reconcile session to match declared config        |
 | `lattices restart [pane]`    | Restart a pane's process (by name or index)       |
 | `lattices tile <position>`   | Tile the frontmost window to a screen position    |
+| `lattices tile family [app] [region]` | Smart-grid the frontmost app family, or a named app |
+| `lattices distribute [app] [region]` | Smart-grid visible windows or just one app      |
 | `lattices group [id]`        | List tab groups or launch/attach a group          |
 | `lattices groups`            | List all tab groups with status                   |
 | `lattices tab <group> [tab]` | Switch tab within a group (by label or index)     |
 | `lattices app`               | Launch the menu bar companion app                 |
+| `lattices app update`        | Download the latest menu bar app and relaunch     |
+| `lattices app build`         | Rebuild the menu bar app from source              |
+| `lattices app restart`       | Rebuild and relaunch the menu bar app             |
+| `lattices layer [name\|index]` | Switch to a workspace layer by name or index      |
+| `lattices windows [--json]`  | List all visible windows                          |
+| `lattices window assign <wid> <layer>` | Tag a window to a layer                |
+| `lattices window map [--json]` | Show all window→layer assignments                |
+| `lattices actor toggle`      | Hide/show persistent overlay actors               |
+| `lattices hud register [manifest]` | Register a `.lattices/hud/manifest.json`   |
+| `lattices hud publish [id\|manifest]` | Publish a static HUD actor to the desktop |
+| `lattices hud sync`          | Publish all registered HUD actors                 |
+| `lattices search <query>`      | Search windows by title, app, session, OCR       |
+| `lattices search <q> --deep`   | Deep search: index + live terminal inspection    |
+| `lattices search <q> --all`    | Same as `--deep` (all search sources)            |
+| `lattices search <q> --wid`    | Print matching window IDs only (pipeable)        |
+| `lattices place <query> [pos]` | Deep search + focus + tile (default: bottom-right)|
+| `lattices focus <session>`   | Focus a session's window and switch Spaces        |
+| `lattices scan search <query>` | Search indexed screen text                       |
+| `lattices diag [limit]`       | Show recent diagnostic entries                   |
+| `lattices app`               | Launch the menu bar companion app                 |
+| `lattices app update`        | Download the latest menu bar app and relaunch     |
 | `lattices app build`         | Rebuild the menu bar app from source              |
 | `lattices app restart`       | Rebuild and relaunch the menu bar app             |
 | `lattices app quit`          | Stop the menu bar app                             |
@@ -143,6 +168,29 @@ Run `lattices init` in your project directory to generate a starter
 Aliases: `ls`/`list`, `kill`/`rm`, `sync`/`reconcile`,
 `restart`/`respawn`, `tile`/`t`.
 
+## Keyboard remaps
+
+The menu bar app can create a lightweight keyboard layer from
+`~/.lattices/keyboard-remaps.json`. The default config is:
+
+```json
+{
+  "rules": [
+    {
+      "enabled": true,
+      "from": "caps_lock",
+      "id": "caps_lock_hyper_escape",
+      "toIfAlone": "escape",
+      "toIfHeld": "hyper"
+    }
+  ]
+}
+```
+
+It is enabled by default and can be turned off from Settings -> General ->
+Keyboard remaps. Hold Caps Lock to send Hyper (`Control` + `Option` +
+`Shift` + `Command`), or tap Caps Lock alone to send Escape.
+
 ## Machine-readable output
 
 ### `--json` flag
@@ -159,7 +207,7 @@ into `jq` or consuming from scripts.
 
 ### Daemon responses
 
-All daemon API calls return JSON natively. If you need structured data
+All agent API calls return JSON natively. If you need structured data
 from lattices, the daemon is easier than parsing stdout. See the
 [API reference](/docs/api).
 
@@ -233,3 +281,28 @@ Aliases: `left-half`/`left`, `right-half`/`right`, `top-half`/`top`,
 
 Tiling respects the menu bar and dock. It uses the visible desktop
 area, not the full screen.
+
+For arbitrary cells, use compact `CxR:c,r` with 1-indexed coordinates
+from the top-left, or canonical `grid:CxR:c,r` with 0-indexed coordinates.
+Example: `lattices tile 4x4:1,2`.
+
+### Smart app tiling
+
+Use `lattices tile family` when you want lattices to arrange a whole
+window family instead of just moving the frontmost window.
+
+Examples:
+
+```bash
+lattices tile family
+lattices tile family right
+lattices tile family iTerm2
+lattices tile family "Google Chrome" left
+```
+
+- With no app name, `family` means the **frontmost app**. If iTerm is
+  frontmost, lattices grids your visible iTerm windows.
+- If you pass a region (`left`, `right`, `top`, `bottom`, etc.), the
+  smart grid is constrained to that part of the screen.
+- `lattices distribute` uses the same smart grid engine, but defaults to
+  **all visible windows** instead of the current app family.