@soederpop/luca 0.0.2

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

@@ -0,0 +1,176 @@
+# YAML (features.yaml)
+
+The YAML feature provides utilities for parsing and stringifying YAML data. This feature wraps the js-yaml library to provide convenient methods for converting between YAML strings and JavaScript objects. It's automatically attached to Node containers for easy access.
+
+## Usage
+
+```ts
+container.feature('yaml')
+```
+
+## Methods
+
+### stringify
+
+Converts a JavaScript object to a YAML string. This method serializes JavaScript data structures into YAML format, which is human-readable and commonly used for configuration files.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `data` | `any` | ✓ | The data to convert to YAML format |
+
+**Returns:** `string`
+
+```ts
+const config = {
+ name: 'MyApp',
+ version: '1.0.0',
+ settings: {
+   debug: true,
+   ports: [3000, 3001]
+ }
+}
+
+const yamlString = yaml.stringify(config)
+console.log(yamlString)
+// Output:
+// name: MyApp
+// version: 1.0.0
+// settings:
+//   debug: true
+//   ports:
+//     - 3000
+//     - 3001
+```
+
+
+
+### parse
+
+Parses a YAML string into a JavaScript object. This method deserializes YAML content into JavaScript data structures. It supports all standard YAML features including nested objects, arrays, and various data types.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `yamlStr` | `string` | ✓ | The YAML string to parse |
+
+**Returns:** `T`
+
+```ts
+const yamlContent = `
+ name: MyApp
+ version: 1.0.0
+ settings:
+   debug: true
+   ports:
+     - 3000
+     - 3001
+`
+
+// Parse with type inference
+const config = yaml.parse(yamlContent)
+console.log(config.name) // 'MyApp'
+
+// Parse with explicit typing
+interface AppConfig {
+ name: string
+ version: string
+ settings: {
+   debug: boolean
+   ports: number[]
+ }
+}
+
+const typedConfig = yaml.parse<AppConfig>(yamlContent)
+console.log(typedConfig.settings.ports) // [3000, 3001]
+```
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+
+## Examples
+
+**features.yaml**
+
+```ts
+const yamlFeature = container.feature('yaml')
+
+// Parse YAML string to object
+const config = yamlFeature.parse(`
+ name: MyApp
+ version: 1.0.0
+ settings:
+   debug: true
+`)
+
+// Convert object to YAML string
+const yamlString = yamlFeature.stringify(config)
+console.log(yamlString)
+```
+
+
+
+**stringify**
+
+```ts
+const config = {
+ name: 'MyApp',
+ version: '1.0.0',
+ settings: {
+   debug: true,
+   ports: [3000, 3001]
+ }
+}
+
+const yamlString = yaml.stringify(config)
+console.log(yamlString)
+// Output:
+// name: MyApp
+// version: 1.0.0
+// settings:
+//   debug: true
+//   ports:
+//     - 3000
+//     - 3001
+```
+
+
+
+**parse**
+
+```ts
+const yamlContent = `
+ name: MyApp
+ version: 1.0.0
+ settings:
+   debug: true
+   ports:
+     - 3000
+     - 3001
+`
+
+// Parse with type inference
+const config = yaml.parse(yamlContent)
+console.log(config.name) // 'MyApp'
+
+// Parse with explicit typing
+interface AppConfig {
+ name: string
+ version: string
+ settings: {
+   debug: boolean
+   ports: number[]
+ }
+}
+
+const typedConfig = yaml.parse<AppConfig>(yamlContent)
+console.log(typedConfig.settings.ports) // [3000, 3001]
+```
+

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

@@ -0,0 +1,47 @@
+# 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
+
+## Usage
+
+```ts
+container.feature('assetLoader')
+```
+
+## Methods
+
+### removeStylesheet
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `href` | `string` | ✓ | Parameter href |
+
+**Returns:** `void`
+
+
+
+### loadScript
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `url` | `string` | ✓ | Parameter url |
+
+**Returns:** `Promise<void>`
+
+
+
+### unpkg
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `packageName` | `string` | ✓ | Parameter packageName |
+| `globalName` | `string` | ✓ | Parameter globalName |
+
+**Returns:** `Promise<any>`
+

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

@@ -0,0 +1,133 @@
+# ContainerLink (features.containerLink)
+
+ContainerLink (Web-side) — WebSocket client that connects to a node host. Connects to a ContainerLink host over WebSocket. The host can evaluate code in this container, and the web side can emit structured events to the host. The web side can NEVER eval code in the host — trust is strictly one-way.
+
+## Usage
+
+```ts
+container.feature('containerLink', {
+  // Port for the WebSocket server
+  port,
+  // Interval in ms between heartbeat pings
+  heartbeatInterval,
+  // Max missed pongs before disconnecting a client
+  maxMissedHeartbeats,
+})
+```
+
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `port` | `number` | Port for the WebSocket server |
+| `heartbeatInterval` | `number` | Interval in ms between heartbeat pings |
+| `maxMissedHeartbeats` | `number` | Max missed pongs before disconnecting a client |
+
+## Methods
+
+### connect
+
+Connect to the host WebSocket server and perform registration.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `hostUrl` | `string` |  | Override the configured host URL |
+
+**Returns:** `Promise<this>`
+
+
+
+### disconnect
+
+Disconnect from the host.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `reason` | `string` |  | Optional reason string |
+
+**Returns:** `void`
+
+
+
+### emitToHost
+
+Send a structured event to the host container.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `eventName` | `string` | ✓ | Name of the event |
+| `data` | `any` |  | Optional event data |
+
+**Returns:** `void`
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `isConnected` | `boolean` | Whether currently connected to the host. |
+| `token` | `string | undefined` | The auth token received from the host. |
+| `hostId` | `string | undefined` | The host container's UUID. |
+
+## Events (Zod v4 schema)
+
+### connected
+
+Event emitted by ContainerLink
+
+
+
+### disconnected
+
+Event emitted by ContainerLink
+
+
+
+### evalRequest
+
+Event emitted by ContainerLink
+
+
+
+### reconnecting
+
+Event emitted by ContainerLink
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+| `connectionCount` | `number` | Number of currently connected web containers |
+| `port` | `number` | Port the WebSocket server is listening on |
+| `listening` | `boolean` | Whether the WebSocket server is listening |
+
+## Examples
+
+**features.containerLink**
+
+```ts
+const link = container.feature('containerLink', {
+ enable: true,
+ hostUrl: 'ws://localhost:8089',
+})
+await link.connect()
+
+// Send events to the host
+link.emitToHost('click', { x: 100, y: 200 })
+
+// Listen for eval requests before they execute
+link.on('evalRequest', (code, requestId) => {
+ console.log('Host is evaluating:', code)
+})
+```
+

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

@@ -0,0 +1,59 @@
+# Esbuild (features.esbuild)
+
+Esbuild helper
+
+## Usage
+
+```ts
+container.feature('esbuild')
+```
+
+## Methods
+
+### compile
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `code` | `string` | ✓ | Parameter code |
+| `options` | `esbuild.TransformOptions` |  | Parameter options |
+
+**Returns:** `void`
+
+
+
+### clearCache
+
+**Returns:** `void`
+
+
+
+### start
+
+**Returns:** `void`
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `assetLoader` | `any` | Returns the assetLoader feature for loading external libraries from unpkg. |
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+
+## Examples
+
+**features.esbuild**
+
+```ts
+const esbuild = container.feature('esbuild')
+const result = esbuild.transformSync('const x: number = 1')
+console.log(result.code) // 'const x = 1;\n'
+```
+

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

@@ -0,0 +1,135 @@
+# Helpers (features.helpers)
+
+The Helpers feature discovers and loads project-level helpers from a JSON manifest served over HTTP. Scripts are injected via AssetLoader and self-register into the container's registries. This is the web equivalent of the node Helpers feature, which scans the filesystem. Instead of filesystem scanning, this feature fetches a manifest from a well-known URL and uses AssetLoader.loadScript() to inject each helper's script tag.
+
+## Usage
+
+```ts
+container.feature('helpers', {
+  // Root directory to scan for helper folders. Defaults to container.cwd
+  rootDir,
+})
+```
+
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `rootDir` | `string` | Root directory to scan for helper folders. Defaults to container.cwd |
+
+## Methods
+
+### setManifestURL
+
+Set a new manifest URL. Invalidates any cached manifest.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `url` | `string` | ✓ | The new URL to fetch the manifest from |
+
+**Returns:** `void`
+
+
+
+### discover
+
+Discover and register helpers of the given type from the manifest. Fetches the manifest, then for each entry of the requested type, loads the script via AssetLoader and checks what got newly registered.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `type` | `RegistryType` | ✓ | Which type of helpers to discover ('features' or 'clients') |
+
+**Returns:** `Promise<string[]>`
+
+
+
+### discoverAll
+
+Discover all helper types from the manifest.
+
+**Returns:** `Promise<Record<string, string[]>>`
+
+
+
+### discoverFeatures
+
+Convenience method to discover only features.
+
+**Returns:** `Promise<string[]>`
+
+
+
+### discoverClients
+
+Convenience method to discover only clients.
+
+**Returns:** `Promise<string[]>`
+
+
+
+### lookup
+
+Look up a helper class by type and name.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `type` | `RegistryType` | ✓ | The registry type |
+| `name` | `string` | ✓ | The helper name within that registry |
+
+**Returns:** `any`
+
+
+
+### describe
+
+Get the introspection description for a specific helper.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `type` | `RegistryType` | ✓ | The registry type |
+| `name` | `string` | ✓ | The helper name |
+
+**Returns:** `string`
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `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. |
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+| `discovered` | `object` | Which registry types have been discovered |
+| `registered` | `array` | Names of project-level helpers that were discovered (type.name) |
+
+## Examples
+
+**features.helpers**
+
+```ts
+const helpers = container.feature('helpers', { enable: true })
+
+// Discover all helper types from the manifest
+await helpers.discoverAll()
+
+// Discover a specific type
+await helpers.discover('features')
+
+// Unified view of all available helpers
+console.log(helpers.available)
+```
+

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

@@ -0,0 +1,30 @@
+# Network (features.network)
+
+Network helper
+
+## Usage
+
+```ts
+container.feature('network')
+```
+
+## Methods
+
+### start
+
+**Returns:** `void`
+
+
+
+### disable
+
+**Returns:** `void`
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `isOffline` | `any` | Whether the browser is currently offline. |
+| `isOnline` | `any` | Whether the browser is currently online. |

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

@@ -0,0 +1,55 @@
+# Speech (features.speech)
+
+Speech helper
+
+## Usage
+
+```ts
+container.feature('speech')
+```
+
+## Methods
+
+### loadVoices
+
+**Returns:** `void`
+
+
+
+### setDefaultVoice
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `name` | `string` | ✓ | Parameter name |
+
+**Returns:** `void`
+
+
+
+### cancel
+
+**Returns:** `void`
+
+
+
+### say
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `text` | `string` | ✓ | Parameter text |
+| `options` | `{ voice?: Voice }` |  | Parameter options |
+
+**Returns:** `void`
+
+
+
+## Getters
+
+| 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. |

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

@@ -0,0 +1,64 @@
+# WebVault (features.vault)
+
+WebVault helper
+
+## Usage
+
+```ts
+container.feature('vault')
+```
+
+## Methods
+
+### secret
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `{ refresh = false, set = true }` | `any` |  | Parameter { refresh = false, set = true } |
+
+**Returns:** `Promise<ArrayBuffer>`
+
+
+
+### decrypt
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `payload` | `string` | ✓ | Parameter payload |
+
+**Returns:** `void`
+
+
+
+### encrypt
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `payload` | `string` | ✓ | Parameter payload |
+
+**Returns:** `void`
+
+
+
+## Examples
+
+**features.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'
+```
+