@lattices/cli 0.5.0 → 0.6.1

package/docs/tiling-reference.md

@@ -62,11 +62,13 @@ All valid position strings that `TilePosition` accepts:
 
 ### Custom Grid Syntax
 
-For arbitrary grids: `grid:CxR:C,R`
+For arbitrary grids: compact `CxR:C,R` or canonical `grid:CxR:C,R`
 
 - `C` = total columns, `R` = total rows
-- `C,R` = target cell (0-indexed position)
-- Example: `grid:5x3:2,1` = center cell of a 5×3 grid
+- Compact `CxR:C,R` starts at 1 from the top-left
+- Canonical `grid:CxR:C,R` starts at 0 for API/wire compatibility
+- Example: `5x3:3,2` or `grid:5x3:2,1` = center cell of a 5×3 grid
+- Spans can use two inclusive corners, such as `4x4:1,1-2,2`
 
 Parsed by `PlacementSpec` / `parseGridString()` into fractional `(x, y, w, h)`.
 

package/docs/voice.md

@@ -4,7 +4,7 @@ description: Natural language voice control for window management
 order: 7
 ---
 
-Voice commands let you control Lattices by speaking. Press **Hyper+3**
+Voice commands let you control Lattices by speaking. Press **Hyper+D**
 to open the voice command window, hold **Option** to speak, release to
 stop. Lattices transcribes your speech via Vox,
 matches it to an intent, and executes it.
@@ -13,7 +13,7 @@ matches it to an intent, and executes it.
 
 1. Install Vox (provides mic + transcription)
 2. Connect an Assistant provider in **Settings > AI**
-3. Press **Hyper+3** to open the voice command window
+3. Press **Hyper+D** to open the voice command window
 4. Hold **Option** and speak a command
 5. Release **Option** — Lattices transcribes and executes
 
@@ -21,7 +21,7 @@ matches it to an intent, and executes it.
 
 | Key | Action |
 |-----|--------|
-| **Hyper+3** | Open/close voice command window |
+| **Hyper+D** | Open/close voice command window |
 | **⌥ (hold)** | Push-to-talk — hold to record, release to stop |
 | **Tab** | Arm/disarm the mic |
 | **Escape** | Cancel recording or dismiss window |

package/package.json

@@ -1,7 +1,15 @@
 {
   "name": "@lattices/cli",
-  "version": "0.5.0",
-  "description": "The agentic workspace manager for macOS — turn your desktop into a coherent API",
+  "version": "0.6.1",
+  "description": "macOS workspace manager — menu bar app, CLI, and WebSocket daemon API for tiling, search, layers, and agent control",
+  "homepage": "https://lattices.dev",
+  "bugs": {
+    "url": "https://github.com/arach/lattices/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "packageManager": "bun@1.3.11",
   "engines": {
     "node": ">=18"
@@ -11,13 +19,19 @@
     "lattices-app": "./bin/lattices-app.ts"
   },
   "keywords": [
+    "lattices",
+    "macos",
+    "workspace",
+    "window-manager",
     "tmux",
+    "daemon",
+    "ai-agents",
     "claude",
-    "dev-server",
     "developer-tools",
     "cli",
     "terminal",
-    "multiplexer"
+    "ocr",
+    "tiling"
   ],
   "repository": {
     "type": "git",
@@ -27,16 +41,21 @@
   "exports": {
     ".": "./bin/client.ts",
     "./assistant-intelligence": "./bin/assistant-intelligence.ts",
+    "./cua": "./bin/cua.ts",
     "./daemon-client": "./bin/daemon-client.ts",
     "./project-twin": "./bin/project-twin.ts"
   },
   "scripts": {
     "dev": "bun --cwd apps/site dev",
     "site:build": "bun --cwd apps/site build",
+    "studio:dev": "bun --cwd apps/studio dev",
+    "studio:build": "bun --cwd apps/studio build",
     "docs:agent": "bun --cwd apps/site agent-docs",
     "check": "bun run check:types && bun run check:app",
     "check:types": "tsc --noEmit",
     "check:app": "env CLANG_MODULE_CACHE_PATH=/tmp/lattices-clang-cache SWIFTPM_TESTS_MODULECACHE=/tmp/lattices-swiftpm-cache swift build --package-path apps/mac",
+    "test": "node --experimental-strip-types --test tests/cli.test.mjs",
+    "test:cli": "node --experimental-strip-types --test tests/cli.test.mjs",
     "test:e2e": "node --experimental-strip-types --test tests/e2e-daemon.test.mjs",
     "test:e2e:voice": "node --experimental-strip-types tests/eval-voice.js",
     "typecheck": "bun run check:types",
@@ -47,9 +66,14 @@
     "prepack": "bash ./bin/lattices-build package"
   },
   "type": "module",
-  "os": ["darwin"],
+  "os": [
+    "darwin"
+  ],
   "files": [
     "bin",
+    "packages/npm/sdk/cua.mjs",
+    "packages/npm/sdk/cua.d.ts",
+    "packages/npm/sdk/cua.d.mts",
     "apps/mac/Info.plist",
     "apps/mac/Lattices.app",
     "apps/mac/Lattices.entitlements",

package/packages/npm/sdk/cua.d.mts

@@ -0,0 +1 @@
+export * from "./cua.d.ts";

package/packages/npm/sdk/cua.d.ts

@@ -0,0 +1,188 @@
+import type { z } from "zod";
+
+export type ComputerTreatment = "observe" | "stage" | "present" | "execute";
+export type ComputerClickTransport =
+  | "auto"
+  | "ax"
+  | "accessibility"
+  | "pointer"
+  | "mouse"
+  | "hardware";
+export type CursorStyle = "spotlight" | "pulse" | "marker";
+export type CursorShape =
+  | "arrow"
+  | "chevron"
+  | "facet"
+  | "shard"
+  | "wedge"
+  | "prism"
+  | "notch"
+  | "needle"
+  | "petal"
+  | "kite";
+export type CursorSize = "tiny" | "small" | "regular" | "large";
+export type CursorTrail = "none" | "thread" | "ribbon" | "spark" | "comet" | "route";
+export type CursorMotion =
+  | "glide"
+  | "snap"
+  | "float"
+  | "rush"
+  | "crawl"
+  | "accelerate"
+  | "teleport"
+  | "spring"
+  | "magnet"
+  | "slingshot";
+export type CursorTrajectory = "straight" | "soft" | "arc" | "swoop" | "overshoot";
+export type CursorGlow = "none" | "soft" | "halo" | "comet";
+export type CursorIdle =
+  | "still"
+  | "breathe"
+  | "wiggle"
+  | "orbit"
+  | "hover"
+  | "nod"
+  | "drift"
+  | "shimmer"
+  | "blink"
+  | "tremble";
+export type CursorEdge =
+  | "none"
+  | "pulse"
+  | "ripple"
+  | "tick"
+  | "reticle"
+  | "blink"
+  | "spark"
+  | "underline"
+  | "echo"
+  | "scan"
+  | "pin";
+export type CursorSound = "none" | "tick" | "click" | "engage" | "chime";
+export type CaptionPlacement =
+  | "top-left"
+  | "top-right"
+  | "bottom-left"
+  | "bottom-right"
+  | "top-center"
+  | "top"
+  | "center"
+  | "middle"
+  | "near-cursor"
+  | "cursor";
+
+export interface WindowTarget {
+  wid?: number;
+  app?: string;
+  title?: string;
+}
+
+export interface ActionBase {
+  treatment?: ComputerTreatment;
+  dryRun?: boolean;
+  capture?: boolean;
+  source?: string;
+}
+
+export interface PointTarget {
+  x?: number;
+  y?: number;
+  xRatio?: number;
+  yRatio?: number;
+}
+
+export interface ComputerClickParams extends WindowTarget, PointTarget, ActionBase {
+  button?: "left" | "right" | "secondary" | "context";
+  transport?: ComputerClickTransport;
+  axLabel?: string;
+  targetText?: string;
+  noFocus?: boolean;
+  label?: string;
+}
+
+export interface ComputerMagicCursorParams extends WindowTarget, PointTarget, ActionBase {
+  style?: CursorStyle;
+  appearance?: CursorStyle;
+  shape?: CursorShape;
+  angleDeg?: number;
+  size?: CursorSize;
+  color?: string;
+  durationMs?: number;
+  label?: string;
+  caption?: string;
+  captionTitle?: string;
+  captionBody?: string;
+  captionDetail?: string;
+  captionTags?: string;
+  captionMode?: "auto" | "selection";
+  captionEyebrow?: string;
+  captionLeadMs?: number;
+  captionSound?: CursorSound;
+  captionPlacement?: CaptionPlacement;
+  captionMargin?: number;
+  captionX?: number;
+  captionY?: number;
+  captionXRatio?: number;
+  captionYRatio?: number;
+  captionLeftRatio?: number;
+  captionTopRatio?: number;
+  sound?: CursorSound;
+  sfx?: CursorSound;
+  showCaption?: boolean;
+  captionSelections?: boolean;
+  treatmentLabel?: string;
+  variant?: string;
+  trail?: CursorTrail;
+  pathStyle?: CursorTrail;
+  motion?: CursorMotion;
+  trajectory?: CursorTrajectory;
+  glow?: CursorGlow;
+  bloom?: CursorGlow;
+  idle?: CursorIdle;
+  settle?: CursorIdle;
+  presence?: CursorIdle;
+  edge?: CursorEdge;
+  edgeEffect?: CursorEdge;
+  arrival?: CursorEdge;
+  typewriter?: boolean;
+  typing?: boolean;
+  typeIntervalMs?: number;
+  typingIntervalMs?: number;
+  text?: string;
+  append?: boolean;
+  fromX?: number;
+  fromY?: number;
+  fromXRatio?: number;
+  fromYRatio?: number;
+}
+
+export interface CuaClientOptions {
+  defaultTimeoutMs?: number;
+}
+
+export interface CuaClient {
+  click(params: ComputerClickParams): Promise<unknown>;
+  magicCursor(params: ComputerMagicCursorParams): Promise<unknown>;
+}
+
+export declare const computerTreatmentSchema: z.ZodType<ComputerTreatment>;
+export declare const computerClickTransportSchema: z.ZodType<ComputerClickTransport>;
+export declare const cursorStyleSchema: z.ZodType<CursorStyle>;
+export declare const cursorShapeSchema: z.ZodType<CursorShape>;
+export declare const cursorSizeSchema: z.ZodType<CursorSize>;
+export declare const cursorTrailSchema: z.ZodType<CursorTrail>;
+export declare const cursorMotionSchema: z.ZodType<CursorMotion>;
+export declare const cursorTrajectorySchema: z.ZodType<CursorTrajectory>;
+export declare const cursorGlowSchema: z.ZodType<CursorGlow>;
+export declare const cursorIdleSchema: z.ZodType<CursorIdle>;
+export declare const cursorEdgeSchema: z.ZodType<CursorEdge>;
+export declare const cursorSoundSchema: z.ZodType<CursorSound>;
+export declare const captionPlacementSchema: z.ZodType<CaptionPlacement>;
+export declare const computerClickParamsSchema: z.ZodType<ComputerClickParams>;
+export declare const computerMagicCursorParamsSchema: z.ZodType<ComputerMagicCursorParams>;
+
+export declare function createCuaClient(options?: CuaClientOptions): CuaClient;
+export declare function click(params: ComputerClickParams): Promise<unknown>;
+export declare function magicCursor(params: ComputerMagicCursorParams): Promise<unknown>;
+
+export declare const cua: CuaClient;

package/packages/npm/sdk/cua.mjs

@@ -0,0 +1,376 @@
+import { randomBytes } from "node:crypto";
+import { createConnection } from "node:net";
+
+import { z } from "zod";
+
+const DAEMON_HOST = "127.0.0.1";
+const DAEMON_PORT = 9399;
+
+export const computerTreatmentSchema = z.enum([
+  "observe",
+  "stage",
+  "present",
+  "execute",
+]);
+
+export const computerClickTransportSchema = z.enum([
+  "auto",
+  "ax",
+  "accessibility",
+  "pointer",
+  "mouse",
+  "hardware",
+]);
+
+export const cursorStyleSchema = z.enum(["spotlight", "pulse", "marker"]);
+export const cursorShapeSchema = z.enum([
+  "arrow",
+  "chevron",
+  "facet",
+  "shard",
+  "wedge",
+  "prism",
+  "notch",
+  "needle",
+  "petal",
+  "kite",
+]);
+export const cursorSizeSchema = z.enum(["tiny", "small", "regular", "large"]);
+export const cursorTrailSchema = z.enum(["none", "thread", "ribbon", "spark", "comet", "route"]);
+export const cursorMotionSchema = z.enum([
+  "glide",
+  "snap",
+  "float",
+  "rush",
+  "crawl",
+  "accelerate",
+  "teleport",
+  "spring",
+  "magnet",
+  "slingshot",
+]);
+export const cursorTrajectorySchema = z.enum(["straight", "soft", "arc", "swoop", "overshoot"]);
+export const cursorGlowSchema = z.enum(["none", "soft", "halo", "comet"]);
+export const cursorIdleSchema = z.enum([
+  "still",
+  "breathe",
+  "wiggle",
+  "orbit",
+  "hover",
+  "nod",
+  "drift",
+  "shimmer",
+  "blink",
+  "tremble",
+]);
+export const cursorEdgeSchema = z.enum([
+  "none",
+  "pulse",
+  "ripple",
+  "tick",
+  "reticle",
+  "blink",
+  "spark",
+  "underline",
+  "echo",
+  "scan",
+  "pin",
+]);
+export const cursorSoundSchema = z.enum(["none", "tick", "click", "engage", "chime"]);
+export const captionPlacementSchema = z.enum([
+  "top-left",
+  "top-right",
+  "bottom-left",
+  "bottom-right",
+  "top-center",
+  "top",
+  "center",
+  "middle",
+  "near-cursor",
+  "cursor",
+]);
+
+const ratioSchema = z.number().min(0).max(1);
+const pointSchema = z.number().finite();
+
+const windowTargetSchema = z.object({
+  wid: z.number().int().positive().optional(),
+  app: z.string().min(1).optional(),
+  title: z.string().optional(),
+});
+
+const actionBaseSchema = z.object({
+  treatment: computerTreatmentSchema.optional(),
+  dryRun: z.boolean().optional(),
+  capture: z.boolean().optional(),
+  source: z.string().optional(),
+});
+
+const pointTargetSchema = z.object({
+  x: pointSchema.optional(),
+  y: pointSchema.optional(),
+  xRatio: ratioSchema.optional(),
+  yRatio: ratioSchema.optional(),
+});
+
+const cursorAppearanceSchema = z.object({
+  style: cursorStyleSchema.optional(),
+  appearance: cursorStyleSchema.optional(),
+  shape: cursorShapeSchema.optional(),
+  angleDeg: z.number().finite().optional(),
+  size: cursorSizeSchema.optional(),
+  color: z.string().min(1).optional(),
+  durationMs: z.number().int().positive().optional(),
+  label: z.string().optional(),
+  caption: z.string().optional(),
+  captionTitle: z.string().optional(),
+  captionBody: z.string().optional(),
+  captionDetail: z.string().optional(),
+  captionTags: z.string().optional(),
+  captionMode: z.enum(["auto", "selection"]).optional(),
+  captionEyebrow: z.string().optional(),
+  captionLeadMs: z.number().finite().nonnegative().optional(),
+  captionSound: cursorSoundSchema.optional(),
+  captionPlacement: captionPlacementSchema.optional(),
+  captionMargin: z.number().finite().nonnegative().optional(),
+  captionX: z.number().finite().optional(),
+  captionY: z.number().finite().optional(),
+  captionXRatio: ratioSchema.optional(),
+  captionYRatio: ratioSchema.optional(),
+  captionLeftRatio: ratioSchema.optional(),
+  captionTopRatio: ratioSchema.optional(),
+  sound: cursorSoundSchema.optional(),
+  sfx: cursorSoundSchema.optional(),
+  showCaption: z.boolean().optional(),
+  captionSelections: z.boolean().optional(),
+  treatmentLabel: z.string().optional(),
+  variant: z.string().optional(),
+  trail: cursorTrailSchema.optional(),
+  pathStyle: cursorTrailSchema.optional(),
+  motion: cursorMotionSchema.optional(),
+  trajectory: cursorTrajectorySchema.optional(),
+  glow: cursorGlowSchema.optional(),
+  bloom: cursorGlowSchema.optional(),
+  idle: cursorIdleSchema.optional(),
+  settle: cursorIdleSchema.optional(),
+  presence: cursorIdleSchema.optional(),
+  edge: cursorEdgeSchema.optional(),
+  edgeEffect: cursorEdgeSchema.optional(),
+  arrival: cursorEdgeSchema.optional(),
+  typewriter: z.boolean().optional(),
+  typing: z.boolean().optional(),
+  typeIntervalMs: z.number().finite().positive().optional(),
+  typingIntervalMs: z.number().finite().positive().optional(),
+});
+
+export const computerClickParamsSchema = windowTargetSchema
+  .merge(pointTargetSchema)
+  .merge(actionBaseSchema)
+  .merge(cursorAppearanceSchema.pick({ label: true }))
+  .extend({
+    button: z.enum(["left", "right", "secondary", "context"]).optional(),
+    transport: computerClickTransportSchema.optional(),
+    axLabel: z.string().min(1).optional(),
+    targetText: z.string().min(1).optional(),
+    noFocus: z.boolean().optional(),
+  });
+
+export const computerMagicCursorParamsSchema = windowTargetSchema
+  .merge(pointTargetSchema)
+  .merge(actionBaseSchema)
+  .merge(cursorAppearanceSchema)
+  .extend({
+    text: z.string().optional(),
+    append: z.boolean().optional(),
+    fromX: pointSchema.optional(),
+    fromY: pointSchema.optional(),
+    fromXRatio: ratioSchema.optional(),
+    fromYRatio: ratioSchema.optional(),
+  });
+
+export function createCuaClient(options = {}) {
+  const defaultTimeoutMs = options.defaultTimeoutMs ?? 30_000;
+
+  async function call(method, params, timeoutMs = defaultTimeoutMs) {
+    return daemonCall(method, params, timeoutMs);
+  }
+
+  return {
+    click(params) {
+      return call("computer.click", computerClickParamsSchema.parse(params));
+    },
+    magicCursor(params) {
+      return call("computer.magicCursor", computerMagicCursorParamsSchema.parse(params));
+    },
+  };
+}
+
+export const cua = createCuaClient();
+
+export function click(params) {
+  return cua.click(params);
+}
+
+export function magicCursor(params) {
+  return cua.magicCursor(params);
+}
+
+async function daemonCall(method, params = null, timeoutMs = 3000) {
+  const id = randomBytes(4).toString("hex");
+  const request = JSON.stringify({ id, method, params: params ?? null });
+
+  return new Promise((resolve, reject) => {
+    const socket = createConnection({ host: DAEMON_HOST, port: DAEMON_PORT });
+    let settled = false;
+    let buffer = Buffer.alloc(0);
+    let upgraded = false;
+
+    const timer = setTimeout(() => {
+      if (!settled) {
+        settled = true;
+        socket.destroy();
+        reject(new Error("Daemon request timed out"));
+      }
+    }, timeoutMs);
+
+    const cleanup = () => {
+      clearTimeout(timer);
+      socket.destroy();
+    };
+
+    socket.on("error", (err) => {
+      if (!settled) {
+        settled = true;
+        cleanup();
+        reject(err);
+      }
+    });
+
+    socket.on("connect", () => {
+      const key = randomBytes(16).toString("base64");
+      const upgrade = [
+        "GET / HTTP/1.1",
+        `Host: ${DAEMON_HOST}:${DAEMON_PORT}`,
+        "Upgrade: websocket",
+        "Connection: Upgrade",
+        `Sec-WebSocket-Key: ${key}`,
+        "Sec-WebSocket-Version: 13",
+        "",
+        "",
+      ].join("\r\n");
+      socket.write(upgrade);
+    });
+
+    socket.on("data", (chunk) => {
+      buffer = Buffer.concat([buffer, chunk]);
+
+      if (!upgraded) {
+        const headerEnd = buffer.indexOf("\r\n\r\n");
+        if (headerEnd === -1) return;
+        const header = buffer.subarray(0, headerEnd).toString();
+        if (!header.includes("101")) {
+          settled = true;
+          cleanup();
+          reject(new Error("WebSocket upgrade failed"));
+          return;
+        }
+        upgraded = true;
+        buffer = buffer.subarray(headerEnd + 4);
+        sendFrame(socket, request);
+      }
+
+      while (true) {
+        const result = parseFrame(buffer);
+        if (!result) break;
+        buffer = result.rest;
+
+        try {
+          const parsed = JSON.parse(result.payload);
+          if (parsed.event || parsed.id !== id) continue;
+          if (!settled) {
+            settled = true;
+            cleanup();
+            if (parsed.error) {
+              reject(new Error(parsed.error));
+            } else {
+              resolve(parsed.result);
+            }
+          }
+          return;
+        } catch {
+          if (!settled) {
+            settled = true;
+            cleanup();
+            reject(new Error("Invalid JSON response from daemon"));
+          }
+          return;
+        }
+      }
+    });
+  });
+}
+
+function sendFrame(socket, text) {
+  const payload = Buffer.from(text, "utf8");
+  const mask = randomBytes(4);
+  const len = payload.length;
+
+  let header;
+  if (len < 126) {
+    header = Buffer.alloc(2);
+    header[0] = 0x81;
+    header[1] = 0x80 | len;
+  } else if (len < 65536) {
+    header = Buffer.alloc(4);
+    header[0] = 0x81;
+    header[1] = 0x80 | 126;
+    header.writeUInt16BE(len, 2);
+  } else {
+    header = Buffer.alloc(10);
+    header[0] = 0x81;
+    header[1] = 0x80 | 127;
+    header.writeBigUInt64BE(BigInt(len), 2);
+  }
+
+  const masked = Buffer.alloc(payload.length);
+  for (let i = 0; i < payload.length; i++) {
+    masked[i] = payload[i] ^ mask[i % 4];
+  }
+
+  socket.write(Buffer.concat([header, mask, masked]));
+}
+
+function parseFrame(buf) {
+  if (buf.length < 2) return null;
+
+  const isMasked = (buf[1] & 0x80) !== 0;
+  let payloadLen = buf[1] & 0x7f;
+  let offset = 2;
+
+  if (payloadLen === 126) {
+    if (buf.length < 4) return null;
+    payloadLen = buf.readUInt16BE(2);
+    offset = 4;
+  } else if (payloadLen === 127) {
+    if (buf.length < 10) return null;
+    payloadLen = Number(buf.readBigUInt64BE(2));
+    offset = 10;
+  }
+
+  if (isMasked) offset += 4;
+  if (buf.length < offset + payloadLen) return null;
+
+  let payload = buf.subarray(offset, offset + payloadLen);
+  if (isMasked) {
+    const maskKey = buf.subarray(offset - 4, offset);
+    payload = Buffer.alloc(payloadLen);
+    for (let i = 0; i < payloadLen; i++) {
+      payload[i] = buf[offset + i] ^ maskKey[i % 4];
+    }
+  }
+
+  return {
+    payload: payload.toString("utf8"),
+    rest: buf.subarray(offset + payloadLen),
+  };
+}