@soederpop/luca 0.0.5 → 0.0.7

package/docs/apis/features/node/sqlite.md

@@ -122,25 +122,47 @@ db.close()
 
 ### query
 
-Event emitted by Sqlite
+Emitted after a SELECT-like query completes successfully
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | The SQL query text that was executed |
+| `arg1` | `array` | Bound parameter values |
+| `arg2` | `number` | Number of rows returned |
 
 
 
 ### error
 
-Event emitted by Sqlite
+Emitted when a SQL operation fails
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `any` | The error that occurred |
 
 
 
 ### execute
 
-Event emitted by Sqlite
+Emitted after a write/update/delete statement completes successfully
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | The SQL statement text that was executed |
+| `arg1` | `array` | Bound parameter values |
+| `arg2` | `number` | Number of rows changed |
 
 
 
 ### closed
 
-Event emitted by Sqlite
+Emitted when the database connection is closed
 
 
 

package/docs/apis/features/node/telegram.md

@@ -189,31 +189,56 @@ Print a diagnostic summary of the bot's current state.
 
 ### stopped
 
-Event emitted by Telegram
+Bot stopped
 
 
 
 ### command
 
-Event emitted by Telegram
+Command triggered: [name, Context]
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` |  |
+| `arg1` | `any` |  |
 
 
 
 ### started
 
-Event emitted by Telegram
+Bot started receiving updates
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `mode` | `string` |  |
 
 
 
 ### webhook_ready
 
-Event emitted by Telegram
+Webhook registered and ready
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` |  |
 
 
 
 ### error
 
-Event emitted by Telegram
+Error occurred
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `any` |  |
 
 
 

package/docs/apis/features/node/tts.md

@@ -69,13 +69,28 @@ const path = await tts.synthesize('Hello world', {
 
 ### synthesized
 
-Event emitted by TTS
+Emitted when audio synthesis completes
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | The text that was synthesized |
+| `arg1` | `string` | Path to the generated audio file |
+| `arg2` | `string` | Voice used |
+| `arg3` | `number` | Duration of the API call in milliseconds |
 
 
 
 ### error
 
-Event emitted by TTS
+Emitted when synthesis fails
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `any` | The error |
 
 
 

package/docs/apis/features/node/ui.md

@@ -1,6 +1,6 @@
 # UI (features.ui)
 
-UI Feature - Interactive Terminal User Interface Builder This feature provides comprehensive tools for creating beautiful, interactive terminal experiences. It combines several popular libraries (chalk, figlet, inquirer) into a unified interface for building professional CLI applications with colors, ASCII art, and interactive prompts. **Core Capabilities:** - Rich color management using chalk library - ASCII art generation with multiple fonts - Interactive prompts and wizards - Automatic color assignment for consistent theming - Text padding and formatting utilities - Gradient text effects (horizontal and vertical) - Banner creation with styled ASCII art **Color System:** - Full chalk API access for complex styling - Automatic color assignment with palette cycling - Consistent color mapping for named entities - Support for hex colors and gradients **ASCII Art Features:** - Multiple font options via figlet - Automatic font discovery and caching - Banner creation with color gradients - Text styling and effects **Interactive Elements:** - Wizard creation with inquirer integration - External editor integration - User input validation and processing **Usage Examples:** **Basic Colors:** ```typescript const ui = container.feature('ui'); // Direct color usage ui.print.red('Error message'); ui.print.green('Success!'); // Complex styling console.log(ui.colors.blue.bold.underline('Important text')); ``` **ASCII Art Banners:** ```typescript const banner = ui.banner('MyApp', { font: 'Big', colors: ['red', 'white', 'blue'] }); console.log(banner); ``` **Interactive Wizards:** ```typescript const answers = await ui.wizard([ { type: 'input', name: 'name', message: 'Your name?' }, { type: 'confirm', name: 'continue', message: 'Continue?' } ]); ``` **Automatic Color Assignment:** ```typescript const userColor = ui.assignColor('john'); const adminColor = ui.assignColor('admin'); console.log(userColor('John\'s message')); console.log(adminColor('Admin notice')); ```
+UI Feature - Interactive Terminal User Interface Builder Unified interface for building professional CLI experiences using chalk (colors/styles), figlet (ASCII art), and inquirer (interactive prompts). Provides rich color management, automatic color assignment, text gradients, banner generation, padding utilities, markdown rendering, and interactive wizards.
 
 ## Usage
 

package/docs/apis/features/node/vault.md

@@ -1,6 +1,6 @@
 # WebVault (features.vault)
 
-WebVault helper
+AES-256-GCM encryption and decryption for the browser using the Web Crypto API. Generates or accepts a secret key and provides `encrypt()` / `decrypt()` methods that work entirely client-side. Keys are stored as base64-encoded state so they can persist across sessions when needed.
 
 ## Usage
 
@@ -52,13 +52,8 @@ container.feature('vault')
 
 ```ts
 const vault = container.feature('vault')
-
-// Encrypt sensitive data
-const encrypted = vault.encrypt('sensitive information')
-console.log(encrypted) // Base64 encoded encrypted data
-
-// Decrypt the data
-const decrypted = vault.decrypt(encrypted)
-console.log(decrypted) // 'sensitive information'
+const encrypted = await vault.encrypt('secret data')
+const decrypted = await vault.decrypt(encrypted)
+console.log(decrypted) // 'secret data'
 ```
 

package/docs/apis/features/node/vm.md

@@ -1,6 +1,6 @@
 # VM (features.vm)
 
-The VM features providers a virtual machine for executing JavaScript code in a sandboxed environment. The Vm feature automatically injects the container.context object into the global scope, so these things can be referenced in the code and the code can use anything provided by the container.
+Sandboxed JavaScript execution environment for the browser. Automatically injects the container's context object into the global scope, so evaluated code can use anything provided by the container. Useful for live code playgrounds, plugin systems, and dynamic script evaluation.
 
 ## Usage
 
@@ -69,16 +69,7 @@ container.feature('vm', {
 
 ```ts
 const vm = container.feature('vm')
-
-// Execute simple code
-const result = vm.run('1 + 2 + 3')
-console.log(result) // 6
-
-// Execute code with custom context
-const result2 = vm.run('greeting + " " + name', { 
- greeting: 'Hello', 
- name: 'World' 
-})
-console.log(result2) // 'Hello World'
+const result = vm.run('1 + 2 + 3') // 6
+const greeting = vm.run('container.uuid') // accesses container globals
 ```
 

package/docs/apis/features/node/window-manager.md

@@ -74,10 +74,10 @@ Spawn a new native browser window. Sends a window dispatch to the app and waits
 | Property | Type | Description |
 |----------|------|-------------|
 | `url` | `string` |  |
-| `width` | `number` |  |
-| `height` | `number` |  |
-| `x` | `number` |  |
-| `y` | `number` |  |
+| `width` | `DimensionValue` |  |
+| `height` | `DimensionValue` |  |
+| `x` | `DimensionValue` |  |
+| `y` | `DimensionValue` |  |
 | `alwaysOnTop` | `boolean` |  |
 | `window` | `{
     decorations?: 'normal' | 'hiddenTitleBar' | 'none'
@@ -88,7 +88,7 @@ Spawn a new native browser window. Sends a window dispatch to the app and waits
     clickThrough?: boolean
   }` |  |
 
-**Returns:** `Promise<WindowAckResult>`
+**Returns:** `Promise<WindowHandle>`
 
 
 
@@ -113,13 +113,13 @@ Spawn a native terminal window running a command. The terminal is read-only —
 | `cols` | `number` | Initial terminal columns. |
 | `rows` | `number` | Initial terminal rows. |
 | `title` | `string` | Window title. |
-| `width` | `number` | Window width in points. |
-| `height` | `number` | Window height in points. |
-| `x` | `number` | Window x position. |
-| `y` | `number` | Window y position. |
+| `width` | `DimensionValue` | Window width in points. |
+| `height` | `DimensionValue` | Window height in points. |
+| `x` | `DimensionValue` | Window x position. |
+| `y` | `DimensionValue` | Window y position. |
 | `window` | `SpawnOptions['window']` | Chrome options (decorations, alwaysOnTop, etc.) |
 
-**Returns:** `Promise<WindowAckResult>`
+**Returns:** `Promise<WindowHandle>`
 
 
 
@@ -227,7 +227,7 @@ Record a video from a window to disk.
 
 ### window
 
-Get a WindowHandle for chainable operations on a specific window.
+Get a WindowHandle for chainable operations on a specific window. Returns the tracked handle if one exists, otherwise creates a new one.
 
 **Parameters:**
 
@@ -239,6 +239,49 @@ Get a WindowHandle for chainable operations on a specific window.
 
 
 
+### spawnLayout
+
+Spawn multiple windows in parallel from a layout configuration. Returns handles in the same order as the config entries.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `config` | `LayoutEntry[]` | ✓ | Array of layout entries (window or tty) |
+
+**Returns:** `Promise<WindowHandle[]>`
+
+```ts
+const handles = await wm.spawnLayout([
+ { type: 'window', url: 'https://google.com', width: 800, height: 600 },
+ { type: 'tty', command: 'htop' },
+ { url: 'https://github.com' }, // defaults to window
+])
+```
+
+
+
+### spawnLayouts
+
+Spawn multiple layouts sequentially. Each layout's windows spawn in parallel, but the next layout waits for the previous one to fully complete.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `configs` | `LayoutEntry[][]` | ✓ | Array of layout configurations |
+
+**Returns:** `Promise<WindowHandle[][]>`
+
+```ts
+const [firstBatch, secondBatch] = await wm.spawnLayouts([
+ [{ url: 'https://google.com' }, { url: 'https://github.com' }],
+ [{ type: 'tty', command: 'htop' }],
+])
+```
+
+
+
 ### send
 
 Write an NDJSON message to the connected app client. Public so other features can send arbitrary protocol messages over the same socket.
@@ -264,43 +307,85 @@ Write an NDJSON message to the connected app client. Public so other features ca
 
 ### listening
 
-Event emitted by WindowManager
+Emitted when the IPC server starts listening
 
 
 
 ### clientConnected
 
-Event emitted by WindowManager
+Emitted when the native app connects
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `any` | The client socket |
 
 
 
 ### clientDisconnected
 
-Event emitted by WindowManager
+Emitted when the native app disconnects
 
 
 
 ### windowAck
 
-Event emitted by WindowManager
+Emitted when a window ack is received from the app
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `any` | The window ack payload |
 
 
 
 ### windowClosed
 
-Event emitted by WindowManager
+Emitted when the native app reports a window closed event
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `any` | Window lifecycle payload emitted when a window closes |
 
 
 
 ### terminalExited
 
-Event emitted by WindowManager
+Emitted when the native app reports a terminal process exit event
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `any` | Terminal lifecycle payload emitted when a terminal process exits |
 
 
 
 ### message
 
-Event emitted by WindowManager
+Emitted for any incoming message that is not a windowAck
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `any` | The parsed message object |
+
+
+
+### error
+
+Emitted on error
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `any` | The error |
 
 
 
@@ -322,8 +407,8 @@ Event emitted by WindowManager
 ```ts
 const wm = container.feature('windowManager', { enable: true, autoListen: true })
 
-const result = await wm.spawn({ url: 'https://google.com', width: 800, height: 600 })
-const handle = wm.window(result.windowId)
+const handle = await wm.spawn({ url: 'https://google.com', width: 800, height: 600 })
+handle.on('close', (msg) => console.log('window closed'))
 await handle.navigate('https://news.ycombinator.com')
 const title = await handle.eval('document.title')
 await handle.close()
@@ -335,3 +420,26 @@ wm.on('message', (msg) => console.log('App says:', msg))
 wm.send({ id: 'abc', status: 'processing', speech: 'Working on it' })
 ```
 
+
+
+**spawnLayout**
+
+```ts
+const handles = await wm.spawnLayout([
+ { type: 'window', url: 'https://google.com', width: 800, height: 600 },
+ { type: 'tty', command: 'htop' },
+ { url: 'https://github.com' }, // defaults to window
+])
+```
+
+
+
+**spawnLayouts**
+
+```ts
+const [firstBatch, secondBatch] = await wm.spawnLayouts([
+ [{ url: 'https://google.com' }, { url: 'https://github.com' }],
+ [{ type: 'tty', command: 'htop' }],
+])
+```
+

package/docs/apis/features/web/asset-loader.md

@@ -1,6 +1,6 @@
 # AssetLoader (features.assetLoader)
 
-The AssetLoader provides an API for injecting scripts and stylesheets into the page. It also provides a convenient way of loading any library from unpkg.com
+Injects scripts and stylesheets into the page at runtime. Provides helpers for loading external libraries from unpkg.com, injecting arbitrary script/link tags, and managing load state. Used by other web features (e.g. Esbuild) to pull in dependencies on demand.
 
 ## Usage
 
@@ -45,3 +45,15 @@ container.feature('assetLoader')
 
 **Returns:** `Promise<any>`
 
+
+
+## Examples
+
+**features.assetLoader**
+
+```ts
+const loader = container.feature('assetLoader')
+await loader.loadScript('https://unpkg.com/lodash')
+await AssetLoader.loadStylesheet('https://unpkg.com/normalize.css')
+```
+

package/docs/apis/features/web/container-link.md

@@ -102,6 +102,65 @@ Event emitted by ContainerLink
 
 
 
+### disconnection
+
+Emitted when a web container disconnects
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | Container UUID |
+| `arg1` | `string` | Reason |
+
+
+
+### error
+
+Event emitted by ContainerLink
+
+
+
+### connection
+
+Emitted when a web container connects and registers
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | Container UUID |
+| `arg1` | `any` | Connection metadata |
+
+
+
+### evalResult
+
+Emitted when an eval result is received
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | Request ID |
+| `arg1` | `any` | Result or error |
+
+
+
+### event
+
+Emitted when a web container sends a structured event
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | Container UUID |
+| `arg1` | `string` | Event name |
+| `arg2` | `any` | Event data |
+
+
+
 ## State (Zod v4 schema)
 
 | Property | Type | Description |

package/docs/apis/features/web/esbuild.md

@@ -1,6 +1,6 @@
 # Esbuild (features.esbuild)
 
-Esbuild helper
+Browser-side TypeScript/ESM compilation feature using esbuild-wasm. Loads esbuild's WebAssembly build via the AssetLoader, then provides `compile()` and `transform()` methods that work entirely in the browser. Useful for live playgrounds, in-browser REPLs, and client-side bundling.
 
 ## Usage
 
@@ -53,7 +53,8 @@ container.feature('esbuild')
 
 ```ts
 const esbuild = container.feature('esbuild')
-const result = esbuild.transformSync('const x: number = 1')
-console.log(result.code) // 'const x = 1;\n'
+await esbuild.start()
+const result = await esbuild.compile('const x: number = 1')
+console.log(result.code)
 ```
 

package/docs/apis/features/web/helpers.md

@@ -108,6 +108,35 @@ Get the introspection description for a specific helper.
 | `manifestURL` | `string` | The URL to fetch the helpers manifest from. |
 | `available` | `Record<string, string[]>` | Returns a unified view of all available helpers across all registries. Each key is a registry type, each value is the list of helper names in that registry. |
 
+## Events (Zod v4 schema)
+
+### discovered
+
+Emitted after a registry type has been discovered
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | Registry type that was discovered |
+| `arg1` | `array` | Names of newly registered helpers |
+
+
+
+### registered
+
+Emitted when a single helper is registered
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | Registry type |
+| `arg1` | `string` | Helper name |
+| `arg2` | `any` | The helper class or module |
+
+
+
 ## State (Zod v4 schema)
 
 | Property | Type | Description |

package/docs/apis/features/web/network.md

@@ -1,6 +1,6 @@
 # Network (features.network)
 
-Network helper
+Tracks browser online/offline connectivity state. Listens for the browser's `online` and `offline` events and keeps the feature state in sync. Other features can observe the `offline` state value or listen for change events to react to connectivity changes.
 
 ## Usage
 
@@ -27,4 +27,18 @@ container.feature('network')
 | Property | Type | Description |
 |----------|------|-------------|
 | `isOffline` | `any` | Whether the browser is currently offline. |
-| `isOnline` | `any` | Whether the browser is currently online. |
+| `isOnline` | `any` | Whether the browser is currently online. |
+
+## Examples
+
+**features.network**
+
+```ts
+const network = container.feature('network')
+console.log(network.state.get('offline')) // false when online
+
+network.on('stateChanged', ({ offline }) => {
+ console.log(offline ? 'Went offline' : 'Back online')
+})
+```
+

package/docs/apis/features/web/speech.md

@@ -1,6 +1,6 @@
 # Speech (features.speech)
 
-Speech helper
+Text-to-speech synthesis using the Web Speech API (SpeechSynthesis). Wraps the browser's built-in speech synthesis, providing voice selection, queue management, and state tracking. Voices are discovered on init and exposed via state for UI binding.
 
 ## Usage
 
@@ -52,4 +52,18 @@ container.feature('speech')
 | Property | Type | Description |
 |----------|------|-------------|
 | `voices` | `any` | Returns the array of available speech synthesis voices. |
-| `defaultVoice` | `any` | Returns the Voice object matching the currently selected default voice name. |
+| `defaultVoice` | `any` | Returns the Voice object matching the currently selected default voice name. |
+
+## Examples
+
+**features.speech**
+
+```ts
+const speech = container.feature('speech')
+speech.say('Hello from the browser!')
+
+// Choose a specific voice
+const speech = container.feature('speech', { voice: 'Google UK English Female' })
+speech.say('Cheerio!')
+```
+

package/docs/apis/features/web/vault.md

@@ -1,6 +1,6 @@
 # WebVault (features.vault)
 
-WebVault helper
+AES-256-GCM encryption and decryption for the browser using the Web Crypto API. Generates or accepts a secret key and provides `encrypt()` / `decrypt()` methods that work entirely client-side. Keys are stored as base64-encoded state so they can persist across sessions when needed.
 
 ## Usage
 
@@ -52,13 +52,8 @@ container.feature('vault')
 
 ```ts
 const vault = container.feature('vault')
-
-// Encrypt sensitive data
-const encrypted = vault.encrypt('sensitive information')
-console.log(encrypted) // Base64 encoded encrypted data
-
-// Decrypt the data
-const decrypted = vault.decrypt(encrypted)
-console.log(decrypted) // 'sensitive information'
+const encrypted = await vault.encrypt('secret data')
+const decrypted = await vault.decrypt(encrypted)
+console.log(decrypted) // 'secret data'
 ```