luca 2.0.0 → 3.0.0

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

@@ -0,0 +1,164 @@
+# 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. |
+
+## 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 |
+|----------|------|-------------|
+| `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,44 @@
+# Network (features.network)
+
+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
+
+```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. |
+
+## 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

@@ -0,0 +1,69 @@
+# Speech (features.speech)
+
+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
+
+```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. |
+
+## 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

@@ -0,0 +1,59 @@
+# WebVault (features.vault)
+
+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
+
+```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')
+const encrypted = await vault.encrypt('secret data')
+const decrypted = await vault.decrypt(encrypted)
+console.log(decrypted) // 'secret data'
+```
+

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

@@ -0,0 +1,75 @@
+# VM (features.vm)
+
+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
+
+```ts
+container.feature('vm', {
+  // Default context object to inject into the VM execution environment
+  context,
+})
+```
+
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `context` | `any` | Default context object to inject into the VM execution environment |
+
+## Methods
+
+### createScript
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `code` | `string` | ✓ | Parameter code |
+
+**Returns:** `void`
+
+
+
+### createContext
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `ctx` | `any` |  | Parameter ctx |
+
+**Returns:** `void`
+
+
+
+### run
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `code` | `string` | ✓ | Parameter code |
+| `ctx` | `any` |  | Parameter ctx |
+| `options` | `any` |  | Parameter options |
+
+**Returns:** `void`
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+
+## Examples
+
+**features.vm**
+
+```ts
+const vm = container.feature('vm')
+const result = vm.run('1 + 2 + 3') // 6
+const greeting = vm.run('container.uuid') // accesses container globals
+```
+

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

@@ -0,0 +1,84 @@
+# VoiceRecognition (features.voice)
+
+Speech-to-text recognition using the Web Speech API (SpeechRecognition). Wraps the browser's built-in speech recognition, supporting continuous listening, interim results, and language selection. Recognized text is accumulated in state and emitted as events for real-time transcription UIs.
+
+## Usage
+
+```ts
+container.feature('voice')
+```
+
+## Methods
+
+### whenFinished
+
+**Returns:** `void`
+
+
+
+### start
+
+**Returns:** `void`
+
+
+
+### stop
+
+**Returns:** `void`
+
+
+
+### abort
+
+**Returns:** `void`
+
+
+
+### clearTranscript
+
+**Returns:** `void`
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `listening` | `any` | Whether the speech recognizer is currently listening for audio input. |
+| `transcript` | `any` | Returns the accumulated final transcript text from recognition results. |
+
+## Events (Zod v4 schema)
+
+### start
+
+Event emitted by VoiceRecognition
+
+
+
+### stop
+
+Event emitted by VoiceRecognition
+
+
+
+### abort
+
+Event emitted by VoiceRecognition
+
+
+
+## Examples
+
+**features.voice**
+
+```ts
+const voice = container.feature('voice', { continuous: true, autoListen: true })
+
+voice.on('transcript', ({ text }) => {
+ console.log('Heard:', text)
+})
+
+// Or start manually
+voice.start()
+```
+

package/docs/apis/servers/express.md

@@ -0,0 +1,171 @@
+# ExpressServer (servers.express)
+
+Express.js HTTP server with automatic endpoint mounting, CORS, and SPA history fallback. Wraps an Express application with convention-based endpoint discovery. Endpoints defined as modules are automatically mounted as routes. Supports static file serving, CORS configuration, and single-page app history fallback out of the box.
+
+## Usage
+
+```ts
+container.server('express', {
+  // Port number to listen on
+  port,
+  // Hostname or IP address to bind to
+  host,
+  // Whether to enable CORS middleware
+  cors,
+  // Path to serve static files from
+  static,
+  // Serve index.html for unmatched routes (SPA history fallback)
+  historyFallback,
+  // (app: Express, server: Server) => Express
+  create,
+  // (options: StartOptions, server: Server) => Promise<any>
+  beforeStart,
+})
+```
+
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `port` | `number` | Port number to listen on |
+| `host` | `string` | Hostname or IP address to bind to |
+| `cors` | `boolean` | Whether to enable CORS middleware |
+| `static` | `string` | Path to serve static files from |
+| `historyFallback` | `boolean` | Serve index.html for unmatched routes (SPA history fallback) |
+| `create` | `any` | (app: Express, server: Server) => Express |
+| `beforeStart` | `any` | (options: StartOptions, server: Server) => Promise<any> |
+
+## Methods
+
+### start
+
+Start the Express HTTP server. A runtime `port` overrides the constructor option and is written to state so `server.port` always reflects reality.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `options` | `StartOptions` |  | Optional runtime overrides for port and host |
+
+**Returns:** `Promise<this>`
+
+
+
+### stop
+
+**Returns:** `Promise<this>`
+
+
+
+### configure
+
+**Returns:** `Promise<this>`
+
+
+
+### useEndpoint
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `endpoint` | `Endpoint` | ✓ | Parameter endpoint |
+
+**Returns:** `this`
+
+
+
+### useEndpoints
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `dir` | `string` | ✓ | Parameter dir |
+
+**Returns:** `Promise<this>`
+
+
+
+### reloadEndpoint
+
+Reload a mounted endpoint by its file path. Re-reads the module through the helpers VM loader so the next request picks up the new handlers.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `filePath` | `string` | ✓ | Absolute path to the endpoint file |
+
+**Returns:** `Promise<Endpoint | null>`
+
+
+
+### useEndpointModules
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `modules` | `EndpointModule[]` | ✓ | Parameter modules |
+
+**Returns:** `Promise<this>`
+
+
+
+### serveOpenAPISpec
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `options` | `{ title?: string; version?: string; description?: string }` |  | Parameter options |
+
+**Returns:** `this`
+
+
+
+### generateOpenAPISpec
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `options` | `{ title?: string; version?: string; description?: string }` |  | Parameter options |
+
+**Returns:** `Record<string, any>`
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `express` | `typeof express` |  |
+| `hooks` | `{ create: (app: Express, server: Server) => Express; beforeStart: (options: any, server: Server) => any }` |  |
+| `app` | `Express` |  |
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `port` | `number` | The port the server is bound to |
+| `listening` | `boolean` | Whether the server is actively listening for connections |
+| `configured` | `boolean` | Whether the server has been configured |
+| `stopped` | `boolean` | Whether the server has been stopped |
+
+## Examples
+
+**servers.express**
+
+```ts
+const server = container.server('express', { cors: true, static: './public' })
+await server.start({ port: 3000 })
+
+// Mount endpoints programmatically
+server.mount(myEndpoint)
+
+// Access the underlying Express app
+server.app.get('/health', (req, res) => res.json({ ok: true }))
+```
+