@lattices/cli 0.4.0 → 0.4.2

package/bin/lattices.ts

@@ -56,7 +56,7 @@ function requireTmux(command: string | undefined): void {
   const isImplicitCreate = command && !tmuxRequiredCommands.has(command)
     && !["search", "s", "focus", "place", "tile", "t", "windows", "window",
          "voice", "call", "layer", "layers", "diag", "diagnostics", "scan",
-         "ocr", "daemon", "dev", "app", "help", "-h", "--help"].includes(command);
+         "ocr", "daemon", "dev", "app", "mouse", "help", "-h", "--help"].includes(command);
 
   if (command && !tmuxRequiredCommands.has(command) && !isImplicitCreate) return;
 
@@ -831,6 +831,18 @@ function restartPane(target?: string): void {
 
 // ── Daemon-aware commands ────────────────────────────────────────────
 
+async function mouseCommand(sub?: string): Promise<void> {
+  const { daemonCall } = await getDaemonClient();
+  if (sub === "summon") {
+    const result = await daemonCall("mouse.summon") as any;
+    console.log(`🎯 Mouse summoned to (${result.x}, ${result.y})`);
+  } else {
+    // Default: find
+    const result = await daemonCall("mouse.find") as any;
+    console.log(`🔍 Mouse at (${result.x}, ${result.y})`);
+  }
+}
+
 async function daemonStatusCommand(): Promise<void> {
   try {
     const { daemonCall } = await getDaemonClient();
@@ -1189,10 +1201,37 @@ async function callCommand(method?: string, ...rest: string[]): Promise<void> {
   }
 }
 
-async function layerCommand(index?: string): Promise<void> {
+async function layerCommand(sub?: string, ...rest: string[]): Promise<void> {
   try {
     const { daemonCall } = await getDaemonClient();
-    if (index === undefined || index === null || index === "") {
+
+    // ── Subcommands ──
+    if (sub === "create") {
+      await layerCreateCommand(rest);
+      return;
+    }
+    if (sub === "snap") {
+      await layerSnapCommand(rest[0]);
+      return;
+    }
+    if (sub === "session" || sub === "sessions") {
+      await layerSessionCommand(rest[0]);
+      return;
+    }
+    if (sub === "clear") {
+      await daemonCall("session.layers.clear");
+      console.log("Cleared all session layers.");
+      return;
+    }
+    if (sub === "delete" || sub === "rm") {
+      if (!rest[0]) { console.log("Usage: lattices layer delete <name>"); return; }
+      await daemonCall("session.layers.delete", { name: rest[0] });
+      console.log(`Deleted session layer "${rest[0]}".`);
+      return;
+    }
+
+    // ── List or switch (original behavior) ──
+    if (sub === undefined || sub === null || sub === "") {
       const result = await daemonCall("layers.list") as any;
       if (!result.layers.length) {
         console.log("No layers configured.");
@@ -1205,19 +1244,144 @@ async function layerCommand(index?: string): Promise<void> {
       }
       return;
     }
-    const idx = parseInt(index, 10);
+    const idx = parseInt(sub, 10);
     if (!isNaN(idx)) {
       await daemonCall("layer.activate", { index: idx, mode: "launch" });
       console.log(`Activated layer ${idx}`);
     } else {
-      await daemonCall("layer.activate", { name: index, mode: "launch" });
-      console.log(`Activated layer "${index}"`);
+      await daemonCall("layer.activate", { name: sub, mode: "launch" });
+      console.log(`Activated layer "${sub}"`);
     }
   } catch (e: unknown) {
     console.log(`Error: ${(e as Error).message}`);
   }
 }
 
+// ── Layer create: build a session layer from window specs ────────────
+// Usage: lattices layer create <name> [wid:123 wid:456 ...]
+//        lattices layer create <name> --json '[{"app":"Chrome","tile":"left"},...]'
+async function layerCreateCommand(args: string[]): Promise<void> {
+  const { daemonCall } = await getDaemonClient();
+  const name = args[0];
+  if (!name) {
+    console.log("Usage: lattices layer create <name> [wid:123 ...] [--json '<specs>']");
+    return;
+  }
+
+  const jsonIdx = args.indexOf("--json");
+  if (jsonIdx !== -1 && args[jsonIdx + 1]) {
+    // JSON mode: parse window specs with tile positions
+    const specs = JSON.parse(args[jsonIdx + 1]) as Array<{
+      wid?: number; app?: string; title?: string; tile?: string;
+    }>;
+
+    // Collect wids, resolve app-based specs
+    const windowIds: number[] = [];
+    const windows: Array<{ app: string; contentHint?: string }> = [];
+    const tiles: Array<{ wid?: number; app?: string; title?: string; tile: string }> = [];
+
+    for (const spec of specs) {
+      if (spec.wid) {
+        windowIds.push(spec.wid);
+        if (spec.tile) tiles.push({ wid: spec.wid, tile: spec.tile });
+      } else if (spec.app) {
+        windows.push({ app: spec.app, contentHint: spec.title });
+        if (spec.tile) tiles.push({ app: spec.app, title: spec.title, tile: spec.tile });
+      }
+    }
+
+    const result = await daemonCall("session.layers.create", {
+      name,
+      ...(windowIds.length ? { windowIds } : {}),
+      ...(windows.length ? { windows } : {}),
+    }) as any;
+
+    console.log(`Created session layer "${name}" with ${specs.length} window(s).`);
+
+    // Apply tile positions
+    for (const t of tiles) {
+      try {
+        await daemonCall("window.place", {
+          ...(t.wid ? { wid: t.wid } : { app: t.app, title: t.title }),
+          placement: t.tile,
+        });
+      } catch { /* window may not be resolved yet */ }
+    }
+
+    if (tiles.length) console.log(`Tiled ${tiles.length} window(s).`);
+    return;
+  }
+
+  // Simple wid mode: lattices layer create <name> wid:123 wid:456
+  const wids = args.slice(1)
+    .filter(a => a.startsWith("wid:"))
+    .map(a => parseInt(a.slice(4), 10))
+    .filter(n => !isNaN(n));
+
+  const result = await daemonCall("session.layers.create", {
+    name,
+    ...(wids.length ? { windowIds: wids } : {}),
+  }) as any;
+
+  console.log(`Created session layer "${name}"${wids.length ? ` with ${wids.length} window(s)` : ""}.`);
+}
+
+// ── Layer snap: snapshot current visible windows into a session layer ─
+async function layerSnapCommand(name?: string): Promise<void> {
+  const { daemonCall } = await getDaemonClient();
+  const layerName = name || `snap-${new Date().toISOString().slice(11, 19).replace(/:/g, "")}`;
+
+  // Get all current windows
+  const windows = await daemonCall("windows.list") as any[];
+  const visibleWids = windows
+    .filter((w: any) => !w.isMinimized && w.app !== "lattices")
+    .map((w: any) => w.wid);
+
+  if (!visibleWids.length) {
+    console.log("No visible windows to snapshot.");
+    return;
+  }
+
+  await daemonCall("session.layers.create", {
+    name: layerName,
+    windowIds: visibleWids,
+  });
+
+  console.log(`Snapped ${visibleWids.length} window(s) → session layer "${layerName}".`);
+}
+
+// ── Layer session: list or switch session layers ─────────────────────
+async function layerSessionCommand(nameOrIndex?: string): Promise<void> {
+  const { daemonCall } = await getDaemonClient();
+  const result = await daemonCall("session.layers.list") as any;
+
+  if (!nameOrIndex) {
+    // List session layers
+    if (!result.layers.length) {
+      console.log("No session layers. Create one with: lattices layer create <name>");
+      return;
+    }
+    console.log("Session layers:\n");
+    for (let i = 0; i < result.layers.length; i++) {
+      const l = result.layers[i];
+      const active = i === result.activeIndex ? " \x1b[32m● active\x1b[0m" : "";
+      const winCount = l.windows?.length || 0;
+      console.log(`  [${i}] ${l.name}  (${winCount} windows)${active}`);
+    }
+    return;
+  }
+
+  // Switch by index or name
+  const idx = parseInt(nameOrIndex, 10);
+  if (!isNaN(idx)) {
+    await daemonCall("session.layers.switch", { index: idx });
+    console.log(`Switched to session layer ${idx}.`);
+  } else {
+    await daemonCall("session.layers.switch", { name: nameOrIndex });
+    console.log(`Switched to session layer "${nameOrIndex}".`);
+  }
+}
+
 async function diagCommand(limit?: string): Promise<void> {
   try {
     const { daemonCall } = await getDaemonClient();
@@ -1549,6 +1713,11 @@ Usage:
   lattices tile <position>    Tile the frontmost window (left, right, top, etc.)
   lattices distribute         Smart-grid all visible windows (daemon required)
   lattices layer [name|index]  List layers or switch by name/index (daemon required)
+  lattices layer create <name> [wid:N ...] [--json '<specs>']  Create a session layer
+  lattices layer snap [name]   Snapshot visible windows into a session layer
+  lattices layer session [n]   List or switch session layers (runtime, no restart)
+  lattices layer delete <name> Delete a session layer
+  lattices layer clear         Clear all session layers
   lattices voice status       Voice provider status
   lattices voice simulate <t> Parse and execute a voice command
   lattices voice intents      List all available intents
@@ -1563,6 +1732,8 @@ Usage:
   lattices dev build          Build the project (swift/node/rust/go/make)
   lattices dev restart        Build + restart (swift app) or just build
   lattices dev type           Print detected project type
+  lattices mouse              Find mouse — sonar pulse at cursor position
+  lattices mouse summon       Summon mouse to screen center
   lattices daemon status      Show daemon status
   lattices diag [limit]       Show diagnostic log entries
   lattices app                Launch the menu bar companion app
@@ -1975,7 +2146,7 @@ switch (command) {
     break;
   case "layer":
   case "layers":
-    await layerCommand(args[1]);
+    await layerCommand(args[1], ...args.slice(2));
     break;
   case "diag":
   case "diagnostics":
@@ -1985,6 +2156,9 @@ switch (command) {
   case "ocr":
     await scanCommand(args[1], ...args.slice(2));
     break;
+  case "mouse":
+    await mouseCommand(args[1]);
+    break;
   case "daemon":
     if (args[1] === "status") {
       await daemonStatusCommand();

package/docs/agent-layer-guide.md

@@ -0,0 +1,207 @@
+# Agent Guide: Generating Layers
+
+How to create and manage Lattices workspace layers programmatically. This guide is for AI agents (Claude Code, etc.) that want to generate layers from high-level user descriptions.
+
+## Quick Reference
+
+```bash
+# See what's on screen
+lattices windows --json
+
+# Create a layer with tiling
+lattices layer create "Design" --json '[
+  {"app": "Figma", "tile": "left"},
+  {"app": "Google Chrome", "title": "Tailwind", "tile": "right"}
+]'
+
+# Snapshot current windows as a layer
+lattices layer snap "my-context"
+
+# List / switch / delete session layers
+lattices layer session
+lattices layer session "Design"
+lattices layer delete "Design"
+lattices layer clear
+```
+
+## How It Works
+
+There are two kinds of layers:
+
+| Type | Storage | Requires restart? | How to create |
+|------|---------|-------------------|---------------|
+| **Config layers** | `~/.lattices/workspace.json` | Yes (or refresh) | Edit JSON file |
+| **Session layers** | In-memory (daemon) | No | CLI or daemon API |
+
+**Session layers are what you want.** They're created via TypeScript CLI commands, take effect immediately, and don't require restarting anything.
+
+## Step-by-Step: Generating a Layer
+
+### 1. Discover what's available
+
+```bash
+lattices windows --json
+```
+
+Returns an array of window objects:
+```json
+[
+  {
+    "wid": 1234,
+    "app": "iTerm2",
+    "title": "lattices — zsh",
+    "latticesSession": "lattices-abc123",
+    "frame": { "x": 0, "y": 25, "w": 960, "h": 1050 },
+    "spaceIds": [1]
+  },
+  {
+    "wid": 5678,
+    "app": "Google Chrome",
+    "title": "GitHub - arach/lattices",
+    "frame": { "x": 960, "y": 25, "w": 960, "h": 1050 },
+    "spaceIds": [1]
+  }
+]
+```
+
+Key fields for matching:
+- `wid` — unique window ID (most precise)
+- `app` — application name
+- `title` — window title (use for disambiguation when multiple windows of same app)
+- `latticesSession` — tmux session name (for terminal windows)
+
+### 2. Decide on a layout
+
+Pick tile positions based on how many windows and what makes sense:
+
+| Windows | Good layout | Tile values |
+|---------|-------------|-------------|
+| 2 | Side by side | `left`, `right` |
+| 2 | Stacked | `top`, `bottom` |
+| 3 | Main + sidebar | `left` (60%), `top-right`, `bottom-right` |
+| 3 | Columns | `left-third`, `center-third`, `right-third` |
+| 4 | Quadrants | `top-left`, `top-right`, `bottom-left`, `bottom-right` |
+| 1 | Focused | `maximize` or `center` |
+
+Full position reference:
+- **Halves**: `left`, `right`, `top`, `bottom`
+- **Quarters**: `top-left`, `top-right`, `bottom-left`, `bottom-right`
+- **Thirds**: `left-third`, `center-third`, `right-third`
+- **Sixths**: `top-left-third`, `top-center-third`, `top-right-third`, `bottom-left-third`, `bottom-center-third`, `bottom-right-third`
+- **Fourths**: `first-fourth`, `second-fourth`, `third-fourth`, `last-fourth`
+- **Special**: `maximize`, `center`
+- **Custom grid**: `grid:CxR:C,R` (e.g. `grid:5x3:2,1`)
+
+### 3. Create the layer
+
+**Option A: By window ID (most reliable)**
+```bash
+lattices layer create "Coding" --json '[
+  {"wid": 1234, "tile": "left"},
+  {"wid": 5678, "tile": "right"}
+]'
+```
+
+**Option B: By app name (survives window recreation)**
+```bash
+lattices layer create "Research" --json '[
+  {"app": "Google Chrome", "title": "docs", "tile": "left"},
+  {"app": "Notes", "tile": "right"}
+]'
+```
+
+**Option C: Simple wid list (no tiling)**
+```bash
+lattices layer create "Focus" wid:1234 wid:5678
+```
+
+**Option D: Snapshot everything visible**
+```bash
+lattices layer snap "Current Context"
+```
+
+### 4. Switch between layers
+
+```bash
+lattices layer session          # list all session layers
+lattices layer session "Coding" # switch to "Coding"
+lattices layer session 0        # switch by index
+```
+
+## Daemon API (Advanced)
+
+For finer control, use raw daemon calls:
+
+```bash
+# Create layer with window IDs
+lattices call session.layers.create '{"name":"Coding","windowIds":[1234,5678]}'
+
+# Create layer with app references
+lattices call session.layers.create '{"name":"Design","windows":[{"app":"Figma"},{"app":"Google Chrome","contentHint":"Tailwind"}]}'
+
+# Tile a specific window
+lattices call window.place '{"wid":1234,"placement":"left"}'
+
+# Switch layer
+lattices call session.layers.switch '{"name":"Coding"}'
+
+# List session layers
+lattices call session.layers.list
+
+# Delete
+lattices call session.layers.delete '{"name":"old-layer"}'
+```
+
+## Composing Layers from Intent
+
+When a user says something high-level, here's how to think about it:
+
+### "Make me a coding layer"
+1. Find terminal windows (iTerm2, Terminal, Warp, etc.)
+2. Find browser windows with dev-related titles (GitHub, docs, localhost)
+3. Main editor/terminal on `left`, reference material on `right`
+
+### "Set up a design layer"
+1. Find design tools (Figma, Sketch, Adobe XD)
+2. Find browser windows with design references
+3. Design tool `left` (or `maximize`), references `right`
+
+### "Create a writing layer"
+1. Find text editors, notes apps (Notes, Obsidian, iA Writer, VS Code with .md)
+2. Find research/reference windows
+3. Writing app `left` or `center`, references `right`
+
+### "Give me a communication layer"
+1. Find messaging apps (Slack, Discord, Messages)
+2. Find email (Mail, Gmail in browser)
+3. Arrange by priority — primary tool `left`, secondary `right`
+
+### "Split my work into layers by project"
+1. Group windows by project (match on title keywords, session names, or app)
+2. Create one layer per project group
+3. Use the 3-window layout pattern: main `left`, support `top-right`, `bottom-right`
+
+## App Grouping Heuristics
+
+When deciding which windows go together:
+
+| Category | Common apps | Goes well with |
+|----------|-------------|----------------|
+| **Code** | iTerm2, Terminal, VS Code, Xcode | Chrome (docs/GitHub), Simulator |
+| **Design** | Figma, Sketch, Pixelmator | Chrome (design systems), Preview |
+| **Writing** | Notes, Obsidian, iA Writer | Chrome (research), Preview |
+| **Communication** | Slack, Discord, Messages, Mail | Calendar, Notes |
+| **Media** | Spotify, Music, Podcasts | (background, no tile needed) |
+| **Reference** | Chrome, Safari, Preview, Finder | (depends on content) |
+
+Browser windows are chameleons — use `title` matching to assign them to the right layer based on their content.
+
+## Tips
+
+- Prefer `wid` when the windows are already open — it's unambiguous.
+- Use `app` + `title` when you want the layer to survive window restarts.
+- Don't put more than 4-5 windows in a single layer — it gets cramped.
+- Background apps (music, etc.) usually don't need to be in any layer.
+- The `snap` command is great for "save what I have now" scenarios.
+- Session layers are ephemeral — they live until the daemon restarts. For permanent layers, edit `~/.lattices/workspace.json`.
+- You can create multiple layers in sequence, then switch between them with `lattices layer session <name>`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lattices/cli",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Agentic window manager for macOS — programmable workspace, smart layouts, managed tmux sessions, and a 35+-method agent API",
   "bin": {
     "lattices": "./bin/lattices.ts",
@@ -27,15 +27,22 @@
   },
   "scripts": {
     "dev": "bun --cwd docs-site dev",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "build:app-bundle": "bash ./bin/lattices-dev build",
+    "prepack": "bash ./bin/lattices-dev build"
   },
   "type": "module",
   "os": ["darwin"],
   "files": [
     "bin",
+    "app/Info.plist",
+    "app/Lattices.app",
+    "app/Lattices.entitlements",
     "app/Package.swift",
+    "app/Resources",
     "app/Sources",
-    "app/Lattices.app/Contents/Info.plist",
+    "app/Tests",
+    "assets/AppIcon.icns",
     "docs"
   ],
   "devDependencies": {
@@ -48,6 +55,7 @@
     "@ai-sdk/openai": "^3.0.41",
     "@ai-sdk/xai": "^3.0.67",
     "@arach/speakeasy": "^0.2.8",
-    "ai": "^6.0.116"
+    "ai": "^6.0.116",
+    "zod": "^3.25.76"
   }
 }