@soederpop/luca 0.0.28 → 0.0.30

package/docs/examples/window-manager-layouts.md

@@ -1,180 +0,0 @@
----
-title: "Window Manager Layouts"
-tags: [windowManager, layout, native, ipc, macos, multi-window]
-lastTested: null
-lastTestPassed: null
----
-
-# Window Manager Layouts
-
-Spawn and manage multiple windows at once using the layout API. Layouts let you declare groups of browser and terminal windows that open in parallel, or sequence multiple groups so each batch waits for the previous one to finish.
-
-## Overview
-
-The `windowManager` feature exposes two layout methods:
-
-- **`spawnLayout(config)`** — spawns all entries in parallel, returns `WindowHandle[]`
-- **`spawnLayouts(configs)`** — spawns multiple layouts sequentially (each layout's windows still spawn in parallel), returns `WindowHandle[][]`
-
-Each entry in a layout is a `LayoutEntry` — either a browser window or a TTY window. Type detection is automatic: if the entry has a `command` field or `type: 'tty'`, it's a terminal. Otherwise it's a browser window.
-
-## Setup
-
-```ts
-const wm = container.feature('windowManager', {
-  autoListen: true,
-  requestTimeoutMs: 10000
-})
-console.log('Window Manager ready')
-```
-
-## Single Layout — Parallel Windows
-
-Spawn a mix of browser and terminal windows that all open at the same time.
-
-```ts 
-const handles = await wm.spawnLayout([
-  { url: 'https://github.com', width: '50%', height: '100%', x: 0, y: 0 },
-  { url: 'https://soederpop.com', width: '50%', height: '100%', x: '50%', y: 0 },
-  { command: 'top', title: 'System Monitor', width: 900, height: 400, x: 0, y: 720 },
-])
-
-console.log('Spawned', handles.length, 'windows')
-handles.forEach((h, i) => console.log(`  [${i}] windowId: ${h.windowId}`))
-```
-
-All three windows open simultaneously. The returned `handles` array preserves the same order as the config entries, so `handles[0]` corresponds to the GitHub window, `handles[1]` to HN, and `handles[2]` to htop.
-
-## Percentage-Based Dimensions
-
-Dimensions (`width`, `height`, `x`, `y`) accept percentage strings resolved against the primary display. This makes layouts portable across different screen resolutions.
-
-```ts skip
-// Side-by-side: two windows each taking half the screen
-const handles = await wm.spawnLayout([
-  { url: 'https://github.com', width: '50%', height: '100%', x: '0%', y: '0%' },
-  { url: 'https://news.ycombinator.com', width: '50%', height: '100%', x: '50%', y: '0%' },
-])
-```
-
-You can mix absolute and percentage values freely:
-
-```ts skip
-const handles = await wm.spawnLayout([
-  { url: 'https://example.com', width: '75%', height: 600, x: '12.5%', y: 50 },
-  { command: 'htop', width: '100%', height: '30%', x: '0%', y: '70%' },
-])
-```
-
-## Explicit Type Field
-
-You can be explicit about entry types using the `type` field. This is equivalent to the implicit detection but more readable when mixing window types.
-
-```ts skip
-const handles = await wm.spawnLayout([
-  { type: 'window', url: 'https://example.com', width: 800, height: 600 },
-  { type: 'tty', command: 'tail -f /var/log/system.log', title: 'Logs' },
-])
-
-console.log('Browser window:', handles[0].windowId)
-console.log('TTY window:', handles[1].windowId)
-```
-
-## Sequential Layouts
-
-Use `spawnLayouts()` when you need windows to appear in stages. Each layout batch spawns in parallel, but the next batch waits until the previous one is fully ready.
-
-```ts skip
-const [dashboards, tools] = await wm.spawnLayouts([
-  // First batch: main content
-  [
-    { url: 'https://grafana.internal/d/api-latency', width: 960, height: 800, x: 0, y: 0 },
-    { url: 'https://grafana.internal/d/error-rate', width: 960, height: 800, x: 970, y: 0 },
-  ],
-  // Second batch: supporting tools (opens after dashboards are ready)
-  [
-    { command: 'htop', title: 'CPU', width: 640, height: 400, x: 0, y: 820 },
-    { command: 'tail -f /var/log/system.log', title: 'Logs', width: 640, height: 400, x: 650, y: 820 },
-  ],
-])
-
-console.log('Dashboards:', dashboards.map(h => h.windowId))
-console.log('Tools:', tools.map(h => h.windowId))
-```
-
-This is useful when the second batch depends on the first being visible — for example, positioning tool windows below dashboard windows.
-
-## Lifecycle Events on Layout Handles
-
-Every handle returned from a layout supports the same event API as a single `spawn()` call. You can listen for `close` and `terminalExited` events on each handle independently.
-
-```ts skip
-const handles = await wm.spawnLayout([
-  { url: 'https://example.com', width: 800, height: 600 },
-  { command: 'sleep 5 && echo done', title: 'Short Task' },
-])
-
-const [browser, terminal] = handles
-
-browser.on('close', () => console.log('Browser window closed'))
-
-terminal.on('terminalExited', (info) => {
-  console.log('Terminal process finished:', info)
-})
-```
-
-## Window Chrome Options
-
-Layout entries support all the same window chrome options as regular `spawn()` calls.
-
-```ts skip
-const handles = await wm.spawnLayout([
-  {
-    url: 'https://example.com',
-    width: 400,
-    height: 300,
-    alwaysOnTop: true,
-    window: {
-      decorations: 'hiddenTitleBar',
-      transparent: true,
-      shadow: true,
-      opacity: 0.9,
-    }
-  },
-  {
-    url: 'https://example.com/overlay',
-    width: 200,
-    height: 100,
-    window: {
-      decorations: 'none',
-      clickThrough: true,
-      transparent: true,
-    }
-  },
-])
-```
-
-## Operating on All Handles
-
-Since layouts return arrays of `WindowHandle`, you can easily batch operations across all windows.
-
-```ts skip
-const handles = await wm.spawnLayout([
-  { url: 'https://example.com/a', width: 600, height: 400 },
-  { url: 'https://example.com/b', width: 600, height: 400 },
-  { url: 'https://example.com/c', width: 600, height: 400 },
-])
-
-// Navigate all windows to the same URL
-await Promise.all(handles.map(h => h.navigate('https://example.com/updated')))
-
-// Screenshot all windows
-await Promise.all(handles.map((h, i) => h.screengrab(`./layout-${i}.png`)))
-
-// Close all windows
-await Promise.all(handles.map(h => h.close()))
-```
-
-## Summary
-
-The layout API builds on top of `spawn()` and `spawnTTY()` to orchestrate multi-window setups. Use `spawnLayout()` for a single batch of parallel windows, and `spawnLayouts()` when you need staged sequences. Every returned handle supports the full `WindowHandle` API — events, navigation, eval, screenshots, and more.

package/docs/examples/window-manager.md

@@ -1,125 +0,0 @@
----
-title: "Window Manager"
-tags: [windowManager, native, ipc, macos, browser, window]
-lastTested: null
-lastTestPassed: null
----
-
-# windowManager
-
-Native window control via LucaVoiceLauncher IPC. Communicates with the macOS launcher app over a Unix domain socket using NDJSON to spawn, navigate, screenshot, and manage native browser windows.
-
-## Overview
-
-Use the `windowManager` feature when you need to control native browser windows from Luca. It acts as an IPC server that the LucaVoiceLauncher macOS app connects to. Through this connection you can spawn windows with configurable chrome, navigate URLs, evaluate JavaScript, capture screenshots, and record video.
-
-Requires the LucaVoiceLauncher native macOS app to be running and connected.
-
-## Enabling the Feature
-
-```ts
-const wm = container.feature('windowManager', {
-  autoListen: false,
-  requestTimeoutMs: 10000
-})
-console.log('Window Manager feature created')
-console.log('Listening:', wm.isListening)
-console.log('Client connected:', wm.isClientConnected)
-```
-
-## API Documentation
-
-```ts
-const info = await container.features.describe('windowManager')
-console.log(info)
-```
-
-## Spawning Windows
-
-Create native browser windows with configurable dimensions and chrome.
-
-```ts skip
-const result = await wm.spawn({
-  url: 'https://google.com',
-  width: 1024,
-  height: 768,
-  alwaysOnTop: true,
-  window: { decorations: 'hiddenTitleBar', shadow: true }
-})
-console.log('Window ID:', result.windowId)
-```
-
-The `spawn()` method sends a dispatch to the native app and waits for acknowledgement. Window options include position, size, transparency, click-through, and title bar style.
-
-## Navigation and JavaScript Evaluation
-
-Control window content after spawning.
-
-```ts skip
-const handle = wm.window(result.windowId)
-await handle.navigate('https://news.ycombinator.com')
-console.log('Navigated')
-
-const title = await handle.eval('document.title')
-console.log('Page title:', title)
-
-await handle.focus()
-await handle.close()
-```
-
-The `window()` method returns a `WindowHandle` for chainable operations on a specific window. Use `eval()` to run JavaScript in the window's web view.
-
-## Screenshots and Video
-
-Capture visual output from windows.
-
-```ts skip
-await wm.screengrab({
-  windowId: result.windowId,
-  path: './screenshot.png'
-})
-console.log('Screenshot saved')
-
-await wm.video({
-  windowId: result.windowId,
-  path: './recording.mp4',
-  durationMs: 5000
-})
-console.log('Video recorded')
-```
-
-Screenshots are saved as PNG. Video recording captures for the specified duration.
-
-## Terminal Windows
-
-Spawn native terminal windows that render command output with ANSI support.
-
-```ts skip
-const tty = await wm.spawnTTY({
-  command: 'htop',
-  title: 'System Monitor',
-  width: 900,
-  height: 600,
-  cols: 120,
-  rows: 40
-})
-console.log('TTY window:', tty.windowId)
-```
-
-Terminal windows are read-only displays of process output. Closing the window terminates the process.
-
-## IPC Communication
-
-Other features can send arbitrary messages over the socket connection.
-
-```ts skip
-wm.listen()
-wm.on('message', (msg) => console.log('App says:', msg))
-wm.send({ id: 'abc', status: 'ready', speech: 'Window manager online' })
-```
-
-The `message` event fires for any non-windowAck message from the native app.
-
-## Summary
-
-The `windowManager` feature provides native window control through IPC with the LucaVoiceLauncher app. Spawn browser windows, navigate, evaluate JS, capture screenshots, and record video. Supports terminal windows for command output. Key methods: `spawn()`, `navigate()`, `eval()`, `screengrab()`, `video()`, `spawnTTY()`, `window()`.

package/docs/window-manager-fix.md

@@ -1,249 +0,0 @@
-# Window Manager Fix
-
-## Problem
-
-The current `windowManager` design allows any Luca process to call `listen()` on the same well-known Unix socket:
-
-- `~/Library/Application Support/LucaVoiceLauncher/ipc-window.sock`
-
-That means unrelated commands can compete for ownership of the app-facing socket. The current implementation makes this worse by doing the following on startup:
-
-1. If the socket path exists, `unlinkSync(socketPath)`.
-2. Bind a new server at the same path.
-
-This creates a race where one Luca process can steal the socket from another. The native `LucaVoiceLauncher` app then disconnects from the old server and reconnects to whichever process currently owns the path. If that process exits, the app falls into reconnect loops.
-
-This is the root cause of the observed behavior where:
-
-- the launcher sometimes connects successfully
-- the connection then drops unexpectedly
-- repeated `ipc connect failed` messages appear in the launcher log
-
-## Design Goal
-
-We want:
-
-- one stable owner of the app-facing socket
-- many independent Luca commands able to trigger window actions
-- optional failover if the main owner dies
-- support for multiple launcher app clients over time, and optionally at once
-
-The key design rule is:
-
-> Many clients is fine. Many servers competing for the same well-known socket is not.
-
-## Recommended Architecture
-
-### 1. Single broker for the app socket
-
-Only one broker process may own:
-
-- `ipc-window.sock`
-
-The broker is responsible for:
-
-- accepting native launcher app connections
-- tracking connected app clients
-- routing window commands to the selected app client
-- receiving `windowAck`, `windowClosed`, and `terminalExited`
-- routing responses and lifecycle events back to the original requester
-
-### 2. Separate control channel for Luca commands
-
-Luca commands should not bind the app-facing socket directly.
-
-Instead, they should talk to the broker over a separate channel, for example:
-
-- `~/Library/Application Support/LucaVoiceLauncher/ipc-window-control.sock`
-
-This control channel is for producers:
-
-- `luca main`
-- `luca workflow run ...`
-- `luca present`
-- scripts
-- background jobs
-
-These producers send requests to the broker, and the broker fans them out to the connected app client.
-
-### 3. Broker supports multiple app clients
-
-The broker should replace the current single `_client` field with a registry:
-
-```ts
-Map<string, ClientConnection>
-```
-
-Each client should have:
-
-- `clientId`
-- `socket`
-- `buffer`
-- metadata if useful later, such as display, role, labels, or lastSeenAt
-
-This allows:
-
-- multiple launcher app instances
-- reconnect without confusing request ownership
-- future routing by target client
-
-## Routing Model
-
-### Producer -> broker
-
-Producer sends a request like:
-
-```json
-{
-  "type": "windowRequest",
-  "requestId": "uuid",
-  "originId": "uuid",
-  "targetClientId": "optional",
-  "window": {
-    "action": "open",
-    "url": "https://example.com"
-  }
-}
-```
-
-### Broker -> app client
-
-Broker forwards the request to the chosen app client, preserving `requestId`.
-
-### App client -> broker
-
-App replies with:
-
-- `windowAck`
-- `windowClosed`
-- `terminalExited`
-
-### Broker -> producer
-
-Broker routes:
-
-- the `windowAck` back to the producer that originated the request
-- lifecycle events either to the originating producer, or to any subscribed producer
-
-## Client Selection Policy
-
-The simplest policy is:
-
-- use the most recently connected healthy app client
-
-Later policies can support:
-
-- explicit `targetClientId`
-- labels like `role=presenter`
-- display-aware routing
-- sticky routing based on `windowId -> clientId`
-
-## Leader Election / Failover
-
-If we want multiple `windowManager` instances to exist, they must not all behave as brokers.
-
-Instead:
-
-1. Try connecting to the broker control socket.
-2. If broker exists, act as a producer client.
-3. If broker does not exist, try to acquire a broker lock.
-4. If lock succeeds, become broker and bind both sockets.
-5. If lock fails, retry broker connection and act as producer.
-
-Possible lock mechanisms:
-
-- lock file with `flock`
-- lock directory with atomic `mkdir`
-- local TCP/Unix registration endpoint
-
-The important constraint is:
-
-- only the elected broker binds `ipc-window.sock`
-
-All other instances must route through it.
-
-## Why not let many processes bind the same socket?
-
-Because Unix domain socket paths are singular ownership points. A path is not a shared bus.
-
-If multiple processes all call `listen()` against the same path and delete stale files optimistically, they will:
-
-- steal the path from each other
-- disconnect the app unexpectedly
-- lose in-flight requests
-- create non-deterministic routing
-
-This is fundamentally the wrong abstraction.
-
-## Backward-Compatible Migration
-
-We can migrate without breaking the public `windowManager.spawn()` API.
-
-### Phase 1
-
-- Introduce a broker mode internally.
-- Add `ipc-window-control.sock`.
-- Keep the existing app protocol unchanged.
-- Make `windowManager.spawn()` talk to the broker when possible.
-
-### Phase 2
-
-- Prevent non-broker processes from binding `ipc-window.sock`.
-- Replace blind `unlinkSync(socketPath)` with active listener detection.
-- Add broker election and failover.
-
-### Phase 3
-
-- Add multi-client routing.
-- Add subscriptions for lifecycle events.
-- Add explicit target selection if needed.
-
-## Minimal Fix if We Need Something Fast
-
-If we do not implement the full broker immediately, we should at least stop destroying active listeners.
-
-`listen()` should:
-
-1. Attempt to connect to the existing socket.
-2. If a listener is alive, do not unlink or rebind.
-3. If the socket is dead, clean it up and bind.
-
-This does not solve multi-producer routing, but it prevents random Luca commands from stealing the app socket from a healthy broker.
-
-## Proposed Internal Refactor
-
-Current state:
-
-- one process tries to be both broker and producer
-- one `_client`
-- one app-facing socket
-
-Target state:
-
-- broker owns app-facing socket
-- producers use control socket
-- broker stores:
-  - `clients: Map<clientId, ClientConnection>`
-  - `pendingRequests: Map<requestId, PendingRequest>`
-  - `requestOrigins: Map<requestId, originConnection>`
-  - `windowOwners: Map<windowId, clientId>`
-
-That separation gives us:
-
-- stable app connectivity
-- multi-command triggering
-- failover
-- room for multi-client routing
-
-## Summary
-
-The right fix is not “allow many `listen()` calls on the same socket.”
-
-The right fix is:
-
-- one elected broker owns the app socket
-- many Luca processes talk to the broker
-- many app clients may connect to the broker
-- failover is implemented through broker election, not socket contention
-
-That preserves a stable connection for the launcher app while still allowing multiple people, commands, or workflows to trigger window operations.

package/scripts/test-window-manager-lifecycle.ts

@@ -1,86 +0,0 @@
-import { NodeContainer } from '../src/node/container'
-
-const args = new Set(process.argv.slice(2))
-const socketArg = process.argv.slice(2).find((arg) => arg.startsWith('--socket='))
-const socketPath = socketArg?.slice('--socket='.length)
-const shouldSpawnTTY = args.has('--spawn-tty')
-const shouldSpawnWindow = args.has('--spawn-window')
-
-const container = new NodeContainer({ cwd: process.cwd() })
-const wm = socketPath
-  ? container.feature('windowManager', { socketPath })
-  : container.feature('windowManager')
-
-wm.listen()
-
-const logCount = () => {
-  console.log(`[state] windowCount=${wm.state.get('windowCount')}`)
-}
-
-wm.on('clientConnected', () => {
-  console.log('[clientConnected] native launcher connected')
-})
-
-wm.on('clientDisconnected', () => {
-  console.log('[clientDisconnected] native launcher disconnected')
-})
-
-wm.on('windowAck', (msg) => {
-  console.log('[windowAck]', JSON.stringify(msg))
-  logCount()
-})
-
-wm.on('windowClosed', (msg) => {
-  console.log('[windowClosed]', JSON.stringify(msg))
-  logCount()
-})
-
-wm.on('terminalExited', (msg) => {
-  console.log('[terminalExited]', JSON.stringify(msg))
-})
-
-wm.on('message', (msg) => {
-  if (msg?.type === 'windowAck' || msg?.type === 'windowClosed' || msg?.type === 'terminalExited') {
-    return
-  }
-  console.log('[message]', JSON.stringify(msg))
-})
-
-let spawned = false
-wm.on('clientConnected', async () => {
-  if (spawned) return
-  spawned = true
-
-  if (shouldSpawnWindow) {
-    const opened = await wm.spawn({
-      url: 'https://example.com',
-      width: 900,
-      height: 620,
-    })
-    console.log('[spawn-window]', opened)
-  }
-
-  if (shouldSpawnTTY) {
-    const tty = await wm.spawnTTY({
-      command: 'zsh',
-      args: ['-lc', 'echo "window-manager lifecycle demo"; sleep 2; exit 7'],
-      title: 'WM Lifecycle Demo',
-      cols: 110,
-      rows: 32,
-      width: 960,
-      height: 620,
-      cwd: process.cwd(),
-    })
-    console.log('[spawn-tty]', tty)
-  }
-})
-
-await container.sleep(150)
-
-console.log(`[ready] listening=${wm.isListening} socket=${wm.state.get('socketPath') ?? '<unset>'}`)
-if (!wm.isListening) {
-  console.log(`[error] ${wm.state.get('lastError') ?? 'windowManager failed to bind socket'}`)
-  console.log('[hint] try: bun run scripts/test-window-manager-lifecycle.ts --socket=/tmp/ipc-window.sock')
-}
-console.log('[usage] bun run scripts/test-window-manager-lifecycle.ts [--spawn-tty] [--spawn-window] [--socket=/path/to/ipc-window.sock]')
-console.log('[ready] waiting for native app connection...')

package/scripts/test-window-manager.ts

@@ -1,43 +0,0 @@
-import { NodeContainer } from '../src/node/container'
-
-const container = new NodeContainer({ cwd: process.cwd() })
-const wm = container.feature('windowManager')
-
-await wm.listen()
-console.log('Listening:', wm.isListening)
-console.log('Socket path:', wm.state.get('socketPath'))
-
-wm.on('clientConnected', () => {
-  console.log('App connected')
-})
-
-wm.on('message', (msg) => {
-  console.log('Message from app:', msg)
-})
-
-wm.on('clientDisconnected', () => {
-  console.log('App disconnected')
-})
-
-// Wait for the app, then spawn a TTY running luca serve in the writing assistant playground
-wm.on('clientConnected', async () => {
-  const result = await wm.spawnTTY({
-    command: 'luca',
-    args: ['serve', '--any-port'],
-    cwd: '/Users/jon/@soederpop/playground/writing-assistant',
-    title: 'Writing Assistant Server',
-    cols: 120,
-    rows: 40,
-    width: 1000,
-    height: 700,
-  })
-
-  console.log('Spawned TTY:', result)
-
-  if (result.windowId) {
-    console.log(`Window ID: ${result.windowId}`)
-    console.log(`PID: ${result.pid}`)
-  }
-})
-
-console.log('Waiting for native app to connect...')