@lattices/cli 0.4.14 → 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,3 +1,9 @@
+---
+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
@@ -30,6 +36,20 @@ 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:
@@ -46,6 +66,10 @@ 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:
@@ -58,7 +82,7 @@ Rules match one of three trigger kinds:
 
 Directions are `up`, `down`, `left`, and `right`.
 
-Useful two-movement shapes include:
+Useful shapes include:
 
 | Shape | Motion |
 |---|---|
@@ -70,6 +94,41 @@ Useful two-movement shapes include:
 | `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
 

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