@arach/lattices 0.2.0 → 0.6.1

package/docs/mouse-gestures.md

@@ -0,0 +1,244 @@
+---
+title: Mouse Gestures
+description: Hold a mouse button, draw a shape or direction, release — runs matched actions like a window manager power-user shortcut system.
+order: 4.2
+---
+
+# Mouse Gestures
+
+## Concept
+
+Mouse gestures are a user-level shortcut system for the macOS app. Hold a
+configured mouse button, draw a direction or shape, then release to run the
+matched action.
+
+The app code owns the recognizer, action dispatcher, and JSON schema. The
+gesture mappings are data, so agents can define or change hotkeys without
+adding a named action in Swift. Your actual gesture mappings live in:
+
+```bash
+~/.lattices/mouse-shortcuts.json
+```
+
+That file is machine-local preference data. It is not project config, and it
+should not be committed to this repository unless you are intentionally adding
+an example fixture or changing the schema.
+
+## Config Ownership
+
+There are two layers:
+
+- **Code defaults** in `MouseGestureConfig.swift` provide a minimal starter
+  config when no user file exists.
+- **User rules** in `~/.lattices/mouse-shortcuts.json` are the source of truth
+  after the file has been created.
+
+Do not add personal shortcuts by changing `MouseGestureConfig.swift`. Add them
+to the user JSON file instead. The Settings UI can open that file from
+**Settings -> Shortcuts -> Mouse Gestures -> Configure...**.
+
+Agents should usually write these rules through the daemon:
+
+```js
+await daemonCall('mouse.shortcuts.upsert', { rule })
+```
+
+The daemon persists the rule, snapshots the old config, and refreshes the
+running app immediately. If a tool edits `~/.lattices/mouse-shortcuts.json`
+directly, call `mouse.shortcuts.reload` afterward; no app restart is required.
+
+## Lightweight History
+
+Lattices keeps local snapshots of your mouse shortcut config before risky
+changes:
+
+```bash
+~/.lattices/mouse-shortcuts.history/
+```
+
+Snapshots are written before external edits are reloaded and before Settings
+restores defaults or restores a previous snapshot. The newest 40 snapshots are
+kept. Use **History** in Settings to open the folder, or **Undo Last** to
+restore the latest snapshot.
+
+## Button Names
+
+The config accepts these common button names:
+
+| Config value | Meaning |
+|---|---|
+| `middle` | Middle button / wheel click |
+| `back` | Back side button, often mouse button 4 |
+| `forward` | Forward side button, often mouse button 5 |
+| `right` | Right mouse button |
+| `buttonN` | Explicit numbered button fallback |
+
+Normal clicks pass through when a configured button is only being watched for
+drag or shape gestures. Once movement crosses the gesture threshold and matches
+a real gesture, Lattices claims the interaction.
+
+Browser frontmost apps are bypassed so native middle-click, Back, and Forward
+button behavior stays intact. This avoids half-claimed side-button gestures
+accidentally navigating while you are drawing a shape.
+
+## Trigger Kinds
+
+Rules match one of three trigger kinds:
+
+| Kind | Required fields | Example |
+|---|---|---|
+| `click` | `button` | Middle click sends paste |
+| `drag` | `button`, `direction` | Middle drag left switches Space |
+| `shape` | `button`, `shape` | Back-button L shape activates iTerm |
+
+Directions are `up`, `down`, `left`, and `right`.
+
+Useful shapes include:
+
+| Shape | Motion |
+|---|---|
+| `l-shape-down-right` | Down, then right |
+| `l-shape-down-left` | Down, then left |
+| `l-shape-up-right` | Up, then right |
+| `l-shape-up-left` | Up, then left |
+| `reverse-l-right-down` | Right, then down |
+| `reverse-l-left-down` | Left, then down |
+| `v-shape` | Down, then up |
+| `reverse-v` | Up, then down |
+| `circle` | A loose closed loop |
+
+The circle recognizer is intentionally generous: it looks for broad circular
+motion, a reasonably closed path, and enough turn coverage rather than a
+geometrically perfect circle.
+
+## Default: Dictation Gesture
+
+New default configs use a plain shortcut action for dictation. The middle-button
+up gesture sends the Lattices voice command hotkey, currently Hyper+D:
+
+```json
+{
+  "id": "dictation",
+  "enabled": true,
+  "device": "any",
+  "trigger": {
+    "button": "middle",
+    "kind": "drag",
+    "direction": "up"
+  },
+  "action": {
+    "type": "shortcut.send",
+    "shortcut": {
+      "key": "d",
+      "keyCode": 2,
+      "modifiers": ["control", "option", "shift", "command"]
+    }
+  }
+}
+```
+
+## Default: Screenshot Area Gesture
+
+New default configs include a back-button circle gesture for the macOS
+screenshot area picker (`Command` + `Shift` + `4`):
+
+```json
+{
+  "id": "back-circle-screenshot-area",
+  "enabled": true,
+  "device": "any",
+  "trigger": {
+    "button": "back",
+    "kind": "shape",
+    "shape": "circle"
+  },
+  "action": {
+    "type": "shortcut.send",
+    "shortcut": {
+      "key": "4",
+      "keyCode": 21,
+      "modifiers": ["command", "shift"]
+    }
+  },
+  "visual": {
+    "renderer": "matrix",
+    "theme": "lattices"
+  }
+}
+```
+
+## Actions
+
+Supported action types include:
+
+| Type | Purpose |
+|---|---|
+| `space.previous` | Switch to the previous macOS Space |
+| `space.next` | Switch to the next macOS Space |
+| `screenmap.toggle` | Open the Screen Map overview |
+| `dictation.start` | Legacy compatibility alias that presses the configured Voice Command hotkey |
+| `shortcut.send` | Send a keyboard shortcut |
+| `app.activate` | Activate an app by name |
+
+## Example: Enter Gesture
+
+This is a user-level rule, not a code default. Add it to
+`~/.lattices/mouse-shortcuts.json` if you want the back button plus a quick
+down-then-left shape to press Enter:
+
+```json
+{
+  "id": "back-down-left-enter",
+  "enabled": true,
+  "device": "any",
+  "trigger": {
+    "button": "back",
+    "kind": "shape",
+    "shape": "l-shape-down-left"
+  },
+  "action": {
+    "type": "shortcut.send",
+    "shortcut": {
+      "key": "enter",
+      "keyCode": 36,
+      "modifiers": []
+    }
+  }
+}
+```
+
+## Visuals
+
+Rules may include an optional `visual` block for feedback. Visuals are
+decorative: they must never decide whether a gesture matches or whether an
+action runs. If a visual asset is missing or slow, the gesture should still
+execute through the native action path.
+
+Shape gestures can opt into native matrix completion feedback with
+`"visual": { "renderer": "matrix" }`. When enabled, Lattices smooths the
+captured path, replays it briefly inside a small 3x3 rounded-cell matrix, then
+snaps into a compact confirmation glyph and action label. This is feedback
+only; the matched rule has already dispatched.
+
+## Implementation
+
+- `apps/mac/Sources/Core/Input/MouseGestureController.swift` owns the CGEvent
+  tap, gesture session state, passthrough behavior, and action dispatch.
+- `apps/mac/Sources/Core/Input/MouseGestureConfig.swift` defines the Codable
+  schema and initial fallback defaults.
+- `apps/mac/Sources/Core/Input/MouseShortcutStore.swift` loads the user-level
+  JSON file and provides thread-safe snapshots to the event tap.
+- `apps/mac/Sources/Core/Input/ShapeRecognizer.swift` converts raw gesture
+  paths into direction and shape labels.
+
+## Safety
+
+The controller installs a session-wide CGEvent tap. To avoid blocking the
+system input pipeline:
+
+- The tap callback does only cheap work and dispatches heavier work async.
+- A circuit breaker handles OS tap timeout events and pauses gestures when
+  needed.
+- Short, unmatched clicks are replayed or passed through so native app behavior
+  remains intact.
+- The emergency reset chord clears stuck input capture state.

package/docs/ocr.md

@@ -59,22 +59,34 @@ contextual snippets.
 ### From the CLI
 
 ```bash
+# Search windows by title, app, session, and OCR content
+lattices search "error"
+
+# Deep search — also inspects terminal tabs and processes
+lattices search "myproject" --deep
+
+# Same as --deep (all search sources)
+lattices search "myproject" --all
+
+# Search + focus + tile the top result
+lattices place "myproject" left
+
 # View current OCR snapshot
-lattices ocr
+lattices scan
 
-# Search OCR history
-lattices ocr search "error OR failed"
+# Search OCR history directly (FTS5 syntax)
+lattices scan search "error OR failed"
 
 # Trigger an immediate deep scan
-lattices ocr scan
+lattices scan deep
 
 # View OCR history for a specific window ID
-lattices ocr history 12345
+lattices scan history 12345
 ```
 
-### From the daemon API
+### From the agent API
 
-Agents can query OCR data through four daemon methods:
+Agents can query OCR data through four API methods:
 
 | Method | Description |
 |--------|-------------|
@@ -88,7 +100,7 @@ Agents can query OCR data through four daemon methods:
 Returns the latest OCR results for all on-screen windows.
 
 ```js
-import { daemonCall } from '@arach/lattices/daemon-client'
+import { daemonCall } from '@lattices/cli'
 
 const snapshot = await daemonCall('ocr.snapshot')
 // [{ wid, app, title, frame, fullText, blocks, timestamp }, ...]
@@ -158,7 +170,7 @@ Entries older than 3 days are automatically deleted.
 A typical agent workflow: trigger a scan, then search for relevant content.
 
 ```js
-import { daemonCall } from '@arach/lattices/daemon-client'
+import { daemonCall } from '@lattices/cli'
 
 // Trigger a fresh scan
 await daemonCall('ocr.scan')

package/docs/overview.md

@@ -4,9 +4,9 @@ description: What lattices is and who it's for
 order: 0
 ---
 
-lattices is a macOS developer workspace manager. A native menu bar app
-handles window tiling, project navigation, on-screen OCR, and optionally
-tmux-powered terminal sessions. Your AI coding agents can use it too.
+lattices is an agentic window manager for macOS. It provides a programmable
+workspace, smart layout management, and managed tmux sessions — all
+controllable from the CLI or a 35+-method agent API.
 
 ## The problem
 
@@ -20,60 +20,79 @@ to see what's on screen, arrange windows, or jump between projects.
 
 ## The solution
 
-lattices fixes both sides:
+lattices addresses both sides with three layers:
 
-- The menu bar app tiles windows, navigates projects, and manages
-  workspace layers through a command palette. Add tmux if you want
-  persistent terminal sessions with auto-layout.
-- The daemon API exposes 30 RPC methods over WebSocket. Agents can
-  discover projects, tile windows, switch layers, read on-screen text
-  via OCR, and launch sessions programmatically.
+### Programmable workspace
+
+The CLI and agent API expose everything: query what's on screen, search
+window text, tile layouts, manage sessions. Claude Code skills, MCP servers,
+or your own scripts can drive your desktop the same way you do. Your
+workspace becomes infrastructure you can observe and control programmatically.
+
+### Smart layout manager
+
+A native menu bar app tracks every window across all your monitors. Tile
+with hotkeys, organize into switchable layers, snap to grids. It reads
+your windows too — extracting text from UI elements every 60 seconds and
+running Vision OCR on background windows every 2 hours. Everything is
+searchable.
+
+### Managed tmux sessions
+
+We make tmux easy. Declare your dev environment in a `.lattices.json`:
+which panes, which commands, what layout. lattices builds it, runs it,
+and keeps it alive. Use your own terminal — sessions survive reboots
+and you can reattach anytime.
 
 ## What's included
 
 | Component | Description |
 |-----------|-------------|
-| **CLI** | The `lattices` command. Tile windows, manage sessions, control the workspace from your terminal |
-| **Menu bar app** | Native macOS companion. Command palette, window tiling, project discovery |
-| **Daemon API** | WebSocket server on `ws://127.0.0.1:9399`. 30 methods, 5 real-time events |
-| **OCR engine** | Reads text from visible windows using Apple Vision, indexes it with FTS5 |
+| **CLI** | The `lattices` command. Tile windows, manage sessions, scan screen text, control the workspace from your terminal |
+| **Menu bar app** | Native macOS companion. Command palette, window tiling, project discovery, screen text indexing |
+| **Agent API** | WebSocket server on `ws://127.0.0.1:9399`. 35+ methods, 5 real-time events |
+| **Screen scanner** | Reads text from visible windows using Accessibility API (60s) and Apple Vision OCR (2h), indexes with FTS5 |
 | **Node.js client** | Zero-dependency `daemonCall()` helper for scripting |
 
 ## Example
 
 ```bash
-cd ~/my-project && lattices
+cd ~/my-project && lattices start
 ```
 
 Agents get the same control programmatically:
 
 ```js
-import { daemonCall } from '@arach/lattices/daemon-client'
+import { daemonCall } from '@lattices/cli'
 await daemonCall('session.launch', { path: '/Users/you/dev/frontend' })
-await daemonCall('window.tile', { session: 'frontend-a1b2c3', position: 'left' })
+await daemonCall('window.place', {
+  session: 'frontend-a1b2c3',
+  placement: { kind: 'tile', value: 'left' }
+})
 ```
 
 ## Who it's for
 
 - Developers who juggle multiple projects and want faster window management
-- People building AI agents that need to control the desktop
+- People building AI agents that need to observe and control the desktop
 - Power users who work across multiple macOS Spaces
-- tmux users who want persistent, auto-configured terminal sessions
+- Anyone who wants persistent, auto-configured terminal sessions
 
 ## Requirements
 
-- macOS 13.0+
+- macOS 26.0+
 - Node.js 18+
 
 ### Dev dependencies
 
-- Swift 5.9+ — only to build the menu bar app from source
+- Swift 6.2 / Xcode 26+ — only to build the menu bar app from source
 - tmux — needed for persistent terminal sessions (`brew install tmux`)
 
 ## Next steps
 
 - [Quickstart](/docs/quickstart): install and run your first session in 2 minutes
 - [Configuration](/docs/config): `.lattices.json` format and CLI commands
-- [Screen OCR](/docs/ocr): Vision-powered screen reading and full-text search
+- [Screen scanning](/docs/ocr): AX text extraction, Vision OCR, and full-text search
 - [Concepts](/docs/concepts): architecture, glossary, and how it all works
-- [Daemon API](/docs/api): RPC method reference for agents and scripts
+- [Agent Guide](/docs/agents): canonical action contracts for voice, CLI, and daemon clients
+- [Agent API](/docs/api): RPC method reference for agents and scripts