@soederpop/luca 0.0.29 → 0.0.31

package/src/bootstrap/generated.ts

@@ -1,5 +1,5 @@
 // Auto-generated bootstrap content
-// Generated at: 2026-03-24T01:41:40.771Z
+// Generated at: 2026-03-24T09:08:07.564Z
 // Source: docs/bootstrap/*.md, docs/bootstrap/templates/*, docs/examples/*.md, docs/tutorials/*.md
 //
 // Do not edit manually. Run: luca build-bootstrap
@@ -2773,132 +2773,6 @@ Supported loaders include \`ts\` (default), \`tsx\`, \`jsx\`, and \`js\`.
 ## Summary
 
 This demo covered synchronous and asynchronous transpilation, minification, and using different source loaders. The \`esbuild\` feature gives you runtime TypeScript-to-JavaScript compilation with zero configuration.
-`,
-  "window-manager.md": `---
-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()\`.
 `,
   "proc.md": `---
 title: "proc"
@@ -3052,187 +2926,6 @@ console.log('Downloader is ready. Call downloader.download(url, path) to fetch f
 ## Summary
 
 This demo covered the \`downloader\` feature, which provides a simple one-method API for fetching remote files and saving them locally. It handles HTTP requests, buffering, and file writing, making it the right choice for any task that involves pulling assets from the network.
-`,
-  "window-manager-layouts.md": `---
-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.
 `,
   "google-docs.md": `---
 title: "Google Docs"
@@ -7441,6 +7134,241 @@ const docs = container.inspectAsText()
 \`\`\`
 
 This is what makes Luca especially powerful for AI agents -- they can discover the entire API surface at runtime without reading documentation.
+`,
+  "20-browser-esm.md": `---
+title: "Browser: Import Luca from esm.sh"
+tags:
+  - browser
+  - esm
+  - web
+  - quickstart
+  - cdn
+---
+# Browser: Import Luca from esm.sh
+
+You can use Luca in any browser environment — no bundler, no build step. Import it from [esm.sh](https://esm.sh) and you get the singleton container on \`window.luca\`, ready to go. All the same APIs apply.
+
+## Basic Setup
+
+\`\`\`html
+<script type="module">
+  import "https://esm.sh/@soederpop/luca/web"
+
+  const container = window.luca
+  console.log(container.uuid) // unique container ID
+  console.log(container.features.available) // ['assetLoader', 'voice', 'speech', 'network', 'vault', 'vm', 'esbuild', 'helpers', 'containerLink']
+</script>
+\`\`\`
+
+The import triggers module evaluation, which creates the \`WebContainer\` singleton and attaches it to \`window.luca\`. That's it.
+
+If you prefer a named import:
+
+\`\`\`html
+<script type="module">
+  import container from "https://esm.sh/@soederpop/luca/web"
+  // container === window.luca
+</script>
+\`\`\`
+
+## Using Features
+
+Once you have the container, features work exactly like they do on the server — lazy-loaded via \`container.feature()\`.
+
+\`\`\`html
+<script type="module">
+  import "https://esm.sh/@soederpop/luca/web"
+  const { luca: container } = window
+
+  // Load a script from a CDN
+  const assetLoader = container.feature('assetLoader')
+  await assetLoader.loadScript('https://cdn.jsdelivr.net/npm/chart.js')
+
+  // Load a stylesheet
+  await assetLoader.loadStylesheet('https://cdn.jsdelivr.net/npm/water.css@2/out/water.css')
+
+  // Text-to-speech
+  const speech = container.feature('speech')
+  speech.speak('Hello from Luca')
+
+  // Voice recognition
+  const voice = container.feature('voice')
+  voice.on('transcript', ({ text }) => console.log('Heard:', text))
+  voice.start()
+</script>
+\`\`\`
+
+## State and Events
+
+The container is a state machine and event bus. This works identically to the server.
+
+\`\`\`html
+<script type="module">
+  import container from "https://esm.sh/@soederpop/luca/web"
+
+  // Listen for state changes
+  container.on('stateChanged', ({ changes }) => {
+    console.log('State changed:', changes)
+  })
+
+  // Feature-level state and events
+  const voice = container.feature('voice')
+  voice.on('stateChanged', ({ changes }) => {
+    document.getElementById('status').textContent = changes.listening ? 'Listening...' : 'Idle'
+  })
+</script>
+\`\`\`
+
+## REST Client
+
+Make HTTP requests with the built-in REST client. Methods return parsed JSON directly.
+
+\`\`\`html
+<script type="module">
+  import container from "https://esm.sh/@soederpop/luca/web"
+
+  const api = container.client('rest', { baseURL: 'https://jsonplaceholder.typicode.com' })
+  const posts = await api.get('/posts')
+  console.log(posts) // array of post objects, not a Response wrapper
+</script>
+\`\`\`
+
+## WebSocket Client
+
+Connect to a WebSocket server:
+
+\`\`\`html
+<script type="module">
+  import container from "https://esm.sh/@soederpop/luca/web"
+
+  const socket = container.client('socket', { url: 'ws://localhost:3000' })
+  socket.on('message', (data) => console.log('Received:', data))
+  socket.send({ type: 'hello' })
+</script>
+\`\`\`
+
+## Extending: Custom Features
+
+The container exposes the \`Feature\` class directly, so you can create your own features without any additional imports.
+
+\`\`\`html
+<script type="module">
+  import container from "https://esm.sh/@soederpop/luca/web"
+
+  const { Feature } = container
+
+  class Theme extends Feature {
+    static shortcut = 'features.theme'
+    static { Feature.register(this, 'theme') }
+
+    get current() {
+      return this.state.get('mode') || 'light'
+    }
+
+    toggle() {
+      const next = this.current === 'light' ? 'dark' : 'light'
+      this.state.set('mode', next)
+      document.documentElement.setAttribute('data-theme', next)
+      this.emit('themeChanged', { mode: next })
+    }
+  }
+
+  const theme = container.feature('theme')
+  theme.on('themeChanged', ({ mode }) => console.log('Theme:', mode))
+  theme.toggle() // => Theme: dark
+</script>
+\`\`\`
+
+## Utilities
+
+The container's built-in utilities are available in the browser too.
+
+\`\`\`html
+<script type="module">
+  import container from "https://esm.sh/@soederpop/luca/web"
+
+  // UUID generation
+  const id = container.utils.uuid()
+
+  // Lodash helpers
+  const { groupBy, keyBy, pick } = container.utils.lodash
+
+  // String utilities
+  const { camelCase, kebabCase } = container.utils.stringUtils
+</script>
+\`\`\`
+
+## Full Example: A Minimal App
+
+\`\`\`html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Luca Browser Demo</title>
+</head>
+<body>
+  <h1>Luca Browser Demo</h1>
+  <button id="speak">Speak</button>
+  <button id="theme">Toggle Theme</button>
+  <pre id="output"></pre>
+
+  <script type="module">
+    import container from "https://esm.sh/@soederpop/luca/web"
+
+    const log = (msg) => {
+      document.getElementById('output').textContent += msg + '\\n'
+    }
+
+    // Load a stylesheet
+    const assets = container.feature('assetLoader')
+    await assets.loadStylesheet('https://cdn.jsdelivr.net/npm/water.css@2/out/water.css')
+
+    // Custom feature
+    const { Feature } = container
+
+    class Theme extends Feature {
+      static shortcut = 'features.theme'
+      static { Feature.register(this, 'theme') }
+
+      toggle() {
+        const next = (this.state.get('mode') || 'light') === 'light' ? 'dark' : 'light'
+        this.state.set('mode', next)
+        document.documentElement.style.colorScheme = next
+        this.emit('themeChanged', { mode: next })
+      }
+    }
+
+    const theme = container.feature('theme')
+    theme.on('themeChanged', ({ mode }) => log(\`Theme: \${mode}\`))
+
+    // Speech
+    const speech = container.feature('speech')
+
+    document.getElementById('speak').onclick = () => speech.speak('Hello from Luca')
+    document.getElementById('theme').onclick = () => theme.toggle()
+
+    log(\`Container ID: \${container.uuid}\`)
+    log(\`Features: \${container.features.available.join(', ')}\`)
+  </script>
+</body>
+</html>
+\`\`\`
+
+Save this as an HTML file, open it in a browser, and everything works — no npm, no bundler, no build step.
+
+## Gotchas
+
+- **esm.sh caches aggressively.** Pin a version if you need stability: \`https://esm.sh/@soederpop/luca@0.0.29/web\`
+- **Browser features only.** The web container doesn't include node-specific features like \`fs\`, \`git\`, \`proc\`, or \`docker\`. If you need server features, run Luca on the server and connect via the REST or WebSocket clients.
+- **\`window.luca\` is the singleton.** Don't call \`createContainer()\` — it just warns and returns the same instance. If you need isolation, use \`container.subcontainer()\`.
+- **CORS applies.** REST client requests from the browser are subject to browser CORS rules. Your API must send the right headers.
+
+## What's Next
+
+- [State and Events](./05-state-and-events.md) — deep dive into the state machine and event bus (works identically in the browser)
+- [Creating Features](./10-creating-features.md) — full anatomy of a feature with schemas, state, and events
+- [Clients](./09-clients.md) — REST and WebSocket client APIs
 `,
   "15-project-patterns.md": `---
 title: Project Patterns and Recipes

package/src/cli/build-info.ts

@@ -1,4 +1,4 @@
 // Generated at compile time — do not edit manually
-export const BUILD_SHA = 'c1e466d'
+export const BUILD_SHA = 'ff23ed7'
 export const BUILD_BRANCH = 'main'
-export const BUILD_DATE = '2026-03-24T01:41:40Z'
+export const BUILD_DATE = '2026-03-24T09:08:07Z'

package/src/clients/rest.ts

@@ -50,7 +50,7 @@ export class RestClient<
     }
   }
 
-  async beforeRequest() {
+  async beforeRequest(): Promise<void> {
   }
 
   /** Whether JSON content-type headers should be set automatically. */
@@ -71,7 +71,7 @@ export class RestClient<
    * @param options - Additional axios request config
    * @returns Parsed response body
    */
-  async patch(url: string, data: any = {}, options: AxiosRequestConfig = {}) {
+  async patch(url: string, data: any = {}, options: AxiosRequestConfig = {}): Promise<any> {
     await this.beforeRequest();
     return this.axios({
       ...options,
@@ -98,7 +98,7 @@ export class RestClient<
    * @param options - Additional axios request config
    * @returns Parsed response body
    */
-  async put(url: string, data: any = {}, options: AxiosRequestConfig = {}) {
+  async put(url: string, data: any = {}, options: AxiosRequestConfig = {}): Promise<any> {
     await this.beforeRequest();
     return this.axios({
       ...options,
@@ -125,7 +125,7 @@ export class RestClient<
    * @param options - Additional axios request config
    * @returns Parsed response body
    */
-  async post(url: string, data: any = {}, options: AxiosRequestConfig = {}) {
+  async post(url: string, data: any = {}, options: AxiosRequestConfig = {}): Promise<any> {
     await this.beforeRequest();
     return this.axios({
       ...options,
@@ -152,7 +152,7 @@ export class RestClient<
    * @param options - Additional axios request config
    * @returns Parsed response body
    */
-  async delete(url: string, params: any = {}, options: AxiosRequestConfig = {}) {
+  async delete(url: string, params: any = {}, options: AxiosRequestConfig = {}): Promise<any> {
     await this.beforeRequest();
     return this.axios({
       ...options,
@@ -179,7 +179,7 @@ export class RestClient<
    * @param options - Additional axios request config
    * @returns Parsed response body
    */
-  async get(url: string, params: any = {}, options: AxiosRequestConfig = {}) {
+  async get(url: string, params: any = {}, options: AxiosRequestConfig = {}): Promise<any> {
     await this.beforeRequest()
     return this.axios({
       ...options,
@@ -198,7 +198,7 @@ export class RestClient<
   }
 
   /** Handle an axios error by emitting 'failure' and returning the error as JSON. */
-  async handleError(error: AxiosError) {
+  async handleError(error: AxiosError): Promise<object> {
     this.emit('failure', error)
     return error.toJSON();
   }

package/src/command.ts

@@ -109,7 +109,26 @@ export class Command<
 		const named = this._normalizeInput(raw, dispatchSource)
 
 		// Validate against argsSchema
-		const parsed = Cls.argsSchema.parse(named)
+		let parsed: any
+		try {
+			parsed = Cls.argsSchema.parse(named)
+		} catch (err: any) {
+			if (err?.name === 'ZodError' && dispatchSource === 'cli') {
+				const ui = (this.container as any).feature('ui')
+				const cmdName = Cls.shortcut?.replace('commands.', '') || 'unknown'
+				const issues = err.issues || []
+
+				ui.print.red(`\n  Error: Invalid options for "${cmdName}"\n`)
+				for (const issue of issues) {
+					const path = issue.path?.length ? issue.path.join('.') : 'input'
+					ui.print(`  ${ui.colors.yellow('→')} ${ui.colors.bold(path)}: ${issue.message}`)
+				}
+				ui.print('')
+				ui.print.dim(`  Run ${ui.colors.cyan(`luca ${cmdName} --help`)} for usage info.\n`)
+				process.exit(1)
+			}
+			throw err
+		}
 
 		// For headless dispatch, capture stdout/stderr
 		if (dispatchSource !== 'cli') {