@lattices/cli 0.4.13 → 0.5.0

package/docs/api.md

@@ -167,9 +167,10 @@ agent-visible UI. Use `overlay.publish` for transient passive visuals,
 and `overlay.actor.*` for persistent, movable actor surfaces.
 
 Persistent actors are useful for representing agents or processes on the
-desktop. Each actor has a stable `id`, can be moved independently, can be
-dragged by the user, and can be hidden/restored with **Hyper+8**. Right-click
-an actor to close that specific actor.
+desktop. Each actor has a stable `id`, can be moved independently through the
+API, dragged by the user, hidden/restored with **Hyper+B**, and closed with
+right-click. Click event callbacks and action surfaces are planned follow-on
+capabilities.
 
 | Method | Type | Description |
 |--------|------|-------------|
@@ -177,6 +178,8 @@ an actor to close that specific actor.
 | `overlay.clear` | write | Clear one overlay layer by id, or clear an owner namespace |
 | `overlay.actor.publish` | write | Create or update a persistent generative overlay actor |
 | `overlay.actor.moveTo` | write | Move an actor with app-owned easing |
+| `overlay.actor.hud` | write | Attach, update, or clear a hover web HUD for an actor |
+| `overlay.actor.visibility` | write | Show, hide, toggle, or inspect the sticky actor layer |
 
 #### `overlay.publish`
 
@@ -229,11 +232,29 @@ omit `ttlMs` or pass `0`, and `dismissible` defaults to `false`.
 | `state` | string | no | Actor state or animation name |
 | `name` | string | no | Actor display name |
 | `message` | string | no | Attached message text |
+| `targetApp` | string | no | App name to activate when the actor is clicked |
+| `targetBundleId` | string | no | Bundle identifier to activate when the actor is clicked |
+| `targetAppPath` | string | no | `.app` bundle path to open when the actor is clicked |
+| `scale` | double | no | Actor scale multiplier |
+| `labelHidden` | bool | no | Hide the actor label/message |
+| `closeOnActivate` | bool | no | Remove the actor after activating its target app |
+| `hudUrl` | string | no | URL to render in a transparent hover HUD web view |
+| `hudHTML` | string | no | Inline HTML to render in a transparent hover HUD web view |
+| `hudWidth` | double | no | Hover HUD width |
+| `hudHeight` | double | no | Hover HUD height |
+| `hudReadAccess` | string | no | Local folder a file-backed HUD may read |
 | `placement` | string | no | `top`, `bottom`, `center`, `cursor`, or `point` |
 | `x`, `y` | double | no | Screen-local point for `point` placement |
 | `ttlMs` | int | no | Time to live; `0` means persistent |
 | `dismissible` | bool | no | Whether click-away dismissal removes the actor |
 
+Bundled sprite assets:
+
+| Asset | Notes |
+|-------|-------|
+| `assistant-spark` | Animated states include `idle`, `run_right`, `run_left`, `waving`, `jumping`, `failed`, `waiting`, `running`, and `review` |
+| `scout-ranger` | Bundled sprite asset with default frame fallback |
+
 Example:
 
 ```js
@@ -277,6 +298,117 @@ await daemonCall('overlay.actor.moveTo', {
 })
 ```
 
+#### `overlay.actor.hud`
+
+Attach a transparent, blurred hover HUD to an actor. The HUD is backed by a
+native `WKWebView`, so apps can point it at a local static HTML dashboard or,
+in development, a local URL.
+
+**Params**:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string | yes | Actor id |
+| `hudUrl` | string | no | URL or file path to render |
+| `hudHTML` | string | no | Inline HTML to render instead of a URL |
+| `hudTitle` | string | no | HUD title metadata |
+| `hudWidth` | double | no | HUD width |
+| `hudHeight` | double | no | HUD height |
+| `hudReadAccess` | string | no | Local folder a file-backed HUD may read |
+| `clear` | bool | no | Remove the actor HUD |
+
+Example:
+
+```js
+await daemonCall('overlay.actor.hud', {
+  id: 'switch-talkie',
+  hudUrl: '/Users/you/dev/talkie/.lattices/hud/index.html',
+  hudReadAccess: '/Users/you/Library/Application Support/Talkie/HUD',
+  hudWidth: 380,
+  hudHeight: 260
+})
+```
+
+#### `overlay.actor.visibility`
+
+Show, hide, toggle, or inspect the persistent actor layer without destroying
+the actors. This is the daemon equivalent of the app's **Hyper+B** shortcut.
+
+**Params**:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `action` | string | no | `show`, `hide`, `toggle`, or `status` |
+| `visible` | bool | no | Set layer visibility directly |
+| `hidden` | bool | no | Set layer hidden state directly |
+| `feedback` | bool | no | Show a short desktop feedback toast |
+
+Example:
+
+```js
+await daemonCall('overlay.actor.visibility', { action: 'toggle' })
+```
+
+### Static HUD Manifests
+
+Apps and projects can expose a local hover dashboard without running a web
+server by publishing a static bundle at:
+
+```txt
+.lattices/hud/
+  manifest.json
+  index.html
+  assets/
+```
+
+Minimal manifest:
+
+```json
+{
+  "version": 1,
+  "id": "talkie",
+  "name": "Talkie",
+  "bundleId": "com.usabletalkie.Talkie",
+  "icon": "./assets/icon.png",
+  "entry": "./index.html",
+  "readAccess": "~/Library/Application Support/Talkie/HUD",
+  "surface": { "width": 380, "height": 260 },
+  "actor": {
+    "labelHidden": true,
+    "click": "activateApp"
+  },
+  "sources": [
+    {
+      "path": "~/Library/Application Support/Talkie/HUD/activity.jsonl",
+      "format": "jsonl",
+      "schema": "talkie.activity.v1",
+      "presentation": "timeline"
+    }
+  ]
+}
+```
+
+The CLI resolves this manifest into `overlay.actor.publish` with a file-backed
+HUD URL. The macOS app loads `entry` through `WKWebView.loadFileURL`, allowing
+read access to the HUD folder by default, or to the manifest's `readAccess`
+folder when one is declared.
+
+`sources` is descriptive metadata for app-owned state, logs, or event streams.
+Lattices does not append to those logs. The app writes them in its normal
+runtime location, and the custom HUD renderer decides how to present them.
+
+Useful commands:
+
+```bash
+lattices hud register .lattices/hud/manifest.json --publish
+lattices hud publish talkie
+lattices hud sync
+lattices hud discover ~/dev --register
+```
+
+For packaged apps, keep the renderer files in the app bundle and point mutable
+sources at an app-owned folder such as `~/Library/Application Support/...`.
+
 ---
 
 ## System

package/docs/app.md

@@ -79,6 +79,27 @@ Available when `layers` are configured in `~/.lattices/workspace.json`
 | Refresh Projects  | Re-scan for .lattices.json configs        |
 | Quit Lattices      | Exit the menu bar app                    |
 
+## Overlay actors and HUDs
+
+Persistent overlay actors can be hidden or restored with **Hyper+B**. Apps can
+publish a static hover dashboard by exposing:
+
+```txt
+.lattices/hud/manifest.json
+```
+
+Register and publish one:
+
+```bash
+lattices hud register .lattices/hud/manifest.json --publish
+```
+
+The manifest points to a local `index.html`, optional icon, app activation
+target, HUD dimensions, and optional app-owned `sources` metadata for logs or
+state files. Lattices hosts the actor and loads the dashboard through a
+transparent `WKWebView`; the app owns the renderer and writes its own logs in
+the places it already uses.
+
 ## Project discovery
 
 The app scans a configurable root directory (up to 3 levels deep)
@@ -153,8 +174,9 @@ Press **Hyper+3** to open the voice command window. Hold **Option** to
 speak, release to stop. Lattices transcribes via Vox, matches to an
 intent, and executes. Built-in commands: find, show, open, tile, kill, scan.
 
-A Claude Haiku advisor runs in parallel, offering follow-up suggestions
-in the AI corner. Configure the model and budget in Settings > AI.
+The provider-backed assistant can run in parallel, offering follow-up
+suggestions in the AI corner. Configure the provider and credentials in
+Settings > AI.
 
 ## Settings
 
@@ -208,12 +230,12 @@ The trackpad proxy toggle lives here. Paired devices still need the
 
 | Setting              | Default        | Description                              |
 |----------------------|----------------|------------------------------------------|
-| Claude CLI path      | Auto-detected  | Path to `claude` binary                  |
-| Advisor model        | Haiku          | `haiku` (fast) or `sonnet` (smarter)     |
-| Budget per session   | $0.50          | Max spend per Claude CLI invocation      |
+| Assistant provider   | OpenAI Codex   | Provider used by in-app chat and provider-backed voice advice |
+| Pi runtime           | Auto-detected  | Runtime install/refresh controls for provider chat |
+| Provider credentials | Not set        | OAuth sign-in or local API-key storage for the selected provider |
 
-Shows live session stats: context usage %, session cost, and learned
-pattern count.
+Shows assistant readiness, runtime availability, and selected-provider
+authentication state.
 
 ### Shortcuts
 
@@ -228,7 +250,7 @@ Shows keyboard shortcut reference:
 | Hyper+4            | Desktop inventory    |
 | Hyper+5            | Omni search          |
 | Hyper+6            | Cheat sheet          |
-| Hyper+8            | Hide/show persistent overlay actors |
+| Hyper+B            | Hide/show persistent overlay actors |
 | Cmd+Option+1/2/3  | Switch workspace layer |
 | Ctrl+B  D         | Detach from session  |
 | Ctrl+B  X         | Kill current pane    |

package/docs/config.md

@@ -146,6 +146,10 @@ Run `lattices init` in your project directory to generate a starter
 | `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> --wid`    | Print matching window IDs only (pipeable)        |

package/docs/mouse-gestures.md

@@ -1,79 +1,207 @@
+---
+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
 
-Hold a mouse button → drag in a direction → release to execute an action.
-The MX Master 3S back-side button (button 3) triggers grid layouts.
-
-## Button Mapping
-
-Defaults — remap by editing `~/.lattices/mouse-shortcuts.json`:
-
-- **Button 3 (Back)** — grid layouts (Maximize / 2×2 / 3×3 / 4×4)
+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.
 
-## Gesture Detection
+The app code owns the recognizer, action dispatcher, and JSON schema. Your
+actual gesture mappings live in:
 
-1. Button held → start tracking mouse movement
-2. After 30px of movement, commit to a direction (↑ ← → ↓)
-3. Show HUD feedback badge: current direction + predicted action
-4. Release → execute the action
-
-If released before 30px threshold → no action (treated as a normal click).
+```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...**.
+
+## 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: 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
 
-### Button 3 — Grid / Tile
-
-| Direction | Action | Result |
-|-----------|--------|--------|
-| ↑ Up | Maximize | Frontmost window fills the screen |
-| ← Left | 2×2 grid | Distribute frontmost 4 windows |
-| → Right | 3×3 grid | Distribute frontmost 9 windows |
-| ↓ Down | 4×4 grid | Distribute frontmost 16 windows |
+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` | Start dictation |
+| `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.
 
-Grid distributes the visible non-Lattices windows to fill the grid cells on
-the screen the cursor is on.
-
-## HUD Feedback
+## Implementation
 
-While dragging:
-- Small floating badge near the cursor: direction arrow + action name
-- Floats above all windows, fades out on release
+- `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: self-healing event tap
+## Safety
 
 The controller installs a session-wide CGEvent tap. To avoid blocking the
 system input pipeline:
 
-- The tap callback never blocks — actions dispatch async to the main queue.
-- A circuit breaker trips on (a) OS `tapDisabledByTimeout` events, or
-  (b) any single action that exceeds 500ms.
-- Cooldowns escalate inside a 10-minute rolling window: **30s → 2min →
-  permanent** (until config reload or app restart).
-- A center-screen badge surfaces "Mouse gestures paused — resuming in Ns"
-  on trip and "Mouse gestures resumed" on auto-recover. All trips log to
-  `~/.lattices/lattices.log`.
-
-## Implementation
-
-- `apps/mac/Sources/MouseGestureController.swift` — CGEvent tap, gesture
-  state machine, breaker.
-- Tile actions go through `WindowTiler.tileFrontmostViaAX(...)`.
-- Grid actions enumerate visible windows via `DesktopModel.shared.allWindows()`
-  and batch-move them with `WindowTiler.batchMoveAndRaiseWindows(...)`.
-
-## Settings UI
-
-**Settings → Shortcuts → Mouse Gestures**:
-
-- Button 3 grid card showing the active mapping
-- Hint to edit `~/.lattices/mouse-shortcuts.json` for remapping
-
-## Edge Cases
-
-- Multiple monitors: gesture executes on the screen the cursor starts on
-- Button held + cursor leaves the screen: still tracks; action applies
-  to the starting screen
-- Short press (< 30px movement): ignored, treated as a normal click
-- Slow action / OS tap timeout: breaker trips, gestures pause briefly,
-  then auto-recover
+- 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/proposals/LAT-004-interactive-overlay-actors.md

@@ -192,7 +192,7 @@ Expected interactions:
 
 Dismissal should normally dismiss the current message/surface, not delete the actor.
 Persistent actors can be parked globally with the overlay actor hotkey
-without clearing their ids or state. The initial shortcut is **Hyper+8**.
+without clearing their ids or state. The initial shortcut is **Hyper+B**.
 
 ## Motion