luca 2.0.0 → 3.0.0

package/docs/apis/features/node/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/node/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/node/yaml-tree.md

@@ -0,0 +1,85 @@
+# YamlTree (features.yamlTree)
+
+YamlTree Feature - A powerful YAML file tree loader and processor This feature provides functionality to recursively load YAML files from a directory structure and build a hierarchical tree representation. It automatically processes file paths to create a nested object structure where file paths become object property paths. **Key Features:** - Recursive YAML file discovery in directory trees - Automatic path-to-property mapping using camelCase conversion - Integration with FileManager for efficient file operations - State-based tree storage and retrieval - Support for both .yml and .yaml file extensions
+
+## Usage
+
+```ts
+container.feature('yamlTree')
+```
+
+## Methods
+
+### loadTree
+
+Loads a tree of YAML files from the specified base path and stores them in state. This method recursively scans the provided directory for YAML files (.yml and .yaml), processes their content, and builds a hierarchical object structure. File paths are converted to camelCase property names, and the resulting tree is stored in the feature's state. **Path Processing:** - Removes the base path prefix from file paths - Converts directory/file names to camelCase - Creates nested objects based on directory structure - Removes file extensions (.yml/.yaml) **Example:** ``` config/ database/ production.yml  -> tree.config.database.production staging.yml     -> tree.config.database.staging api/ endpoints.yaml  -> tree.config.api.endpoints ```
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `basePath` | `string` | ✓ | The root directory path to scan for YAML files |
+| `key` | `string` |  | The key to store the tree under in state (defaults to first segment of basePath) |
+
+**Returns:** `void`
+
+```ts
+// Load all YAML files from 'config' directory into state.config
+await yamlTree.loadTree('config');
+
+// Load with custom key
+await yamlTree.loadTree('app/settings', 'appSettings');
+
+// Access the loaded data
+const dbConfig = yamlTree.tree.config.database.production;
+```
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `tree` | `any` | Gets the current tree data, excluding the 'enabled' state property. Returns a clean copy of the tree data without internal state management properties. This provides access to only the YAML tree data that has been loaded. |
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+
+## Examples
+
+**features.yamlTree**
+
+```ts
+const yamlTree = container.feature('yamlTree', { enable: true });
+await yamlTree.loadTree('config', 'appConfig');
+const configData = yamlTree.tree.appConfig;
+```
+
+
+
+**loadTree**
+
+```ts
+// Load all YAML files from 'config' directory into state.config
+await yamlTree.loadTree('config');
+
+// Load with custom key
+await yamlTree.loadTree('app/settings', 'appSettings');
+
+// Access the loaded data
+const dbConfig = yamlTree.tree.config.database.production;
+```
+
+
+
+**tree**
+
+```ts
+await yamlTree.loadTree('config');
+const allTrees = yamlTree.tree;
+// Returns: { config: { database: { ... }, api: { ... } } }
+```
+

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,59 @@
+# AssetLoader (features.assetLoader)
+
+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
+
+```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>`
+
+
+
+## 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

@@ -0,0 +1,192 @@
+# 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
+
+
+
+### 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 |
+|----------|------|-------------|
+| `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,54 @@
+# Esbuild (features.esbuild)
+
+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
+
+```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. |
+
+## Examples
+
+**features.esbuild**
+
+```ts
+const esbuild = container.feature('esbuild')
+await esbuild.start()
+const result = await esbuild.compile('const x: number = 1')
+console.log(result.code)
+```
+