@soederpop/luca 0.0.2

package/docs/examples/ui.md

@@ -0,0 +1,80 @@
+---
+title: "ui"
+tags: [ui, terminal, colors, ascii-art, core]
+lastTested: null
+lastTestPassed: null
+---
+
+# ui
+
+Terminal UI utilities including colors, ASCII art, gradients, and markdown rendering.
+
+## Overview
+
+The `ui` feature is a core feature, auto-enabled on every container. You can access it directly as a global or via `container.feature('ui')`. It provides chalk-based color styling, figlet-powered ASCII art, color gradient effects, and terminal markdown rendering. Use it to make CLI output readable and visually organized.
+
+## Text Colors
+
+The `colors` getter provides the full chalk API for coloring and styling terminal text.
+
+```ts
+const { colors } = ui
+console.log(colors.green('Success: all tests passed'))
+console.log(colors.red('Error: file not found'))
+console.log(colors.yellow('Warning: deprecated API'))
+console.log(colors.bold.cyan('Info: build complete'))
+```
+
+Colors can be chained with styles like `bold`, `italic`, `underline`, and `dim`.
+
+## ASCII Art
+
+Use `asciiArt()` to render text in large figlet fonts. Pass the text and a font name.
+
+```ts
+const art = ui.asciiArt('LUCA', 'Standard')
+console.log(art)
+```
+
+The `fonts` getter lists all available figlet fonts if you want to explore options.
+
+## Banner with Gradient
+
+Use `banner()` to combine ASCII art with a color gradient for eye-catching headers.
+
+```ts
+const result = ui.banner('Hello', { font: 'Small', colors: ['cyan', 'blue', 'magenta'] })
+console.log(result)
+```
+
+The gradient is applied automatically across the lines of the ASCII art.
+
+## Color Gradients
+
+Use `applyGradient()` to apply color transitions to any text. Choose between horizontal (per-character) and vertical (per-line) directions.
+
+```ts
+const horizontal = ui.applyGradient('Horizontal gradient across this text', ['red', 'yellow', 'green'], 'horizontal')
+console.log(horizontal)
+
+const lines = 'Line one\nLine two\nLine three\nLine four'
+const vertical = ui.applyGradient(lines, ['cyan', 'blue', 'magenta'], 'vertical')
+console.log(vertical)
+```
+
+Horizontal gradients color each character individually. Vertical gradients color each line uniformly.
+
+## Markdown Rendering
+
+Use `markdown()` to render a markdown string for terminal display with formatting preserved.
+
+```ts
+const md = ui.markdown('## Features\n\n- **Bold** text\n- `inline code`\n- Regular paragraph text\n')
+console.log(md)
+```
+
+This uses marked-terminal under the hood to produce styled terminal output from markdown source.
+
+## Summary
+
+This demo covered text coloring with chalk, ASCII art generation with figlet, gradient banners, horizontal and vertical color gradients, and markdown rendering. The `ui` feature handles all the visual polish for terminal applications.

package/docs/examples/vault.md

@@ -0,0 +1,70 @@
+---
+title: "Vault"
+tags: [vault, encryption, security, crypto]
+lastTested: null
+lastTestPassed: null
+---
+
+# vault
+
+AES-256-GCM encryption and decryption for sensitive data. Encrypt strings and get them back with a simple two-method API.
+
+## Overview
+
+The `vault` feature is on-demand. It generates or accepts a secret key and provides `encrypt()` and `decrypt()` methods using AES-256-GCM, an authenticated encryption scheme. Use it to protect sensitive configuration values, tokens, or any data that should not be stored in plaintext.
+
+## Enabling the Vault
+
+Create a vault instance. It will generate a secret key automatically.
+
+```ts
+const vault = container.feature('vault')
+console.log('Vault enabled:', vault.state.get('enabled'))
+```
+
+The vault is ready to use immediately after creation.
+
+## Encrypting a String
+
+Pass any plaintext string to `encrypt()` and receive an opaque encrypted payload.
+
+```ts
+const secret = 'my-database-password-12345'
+const encrypted = vault.encrypt(secret)
+console.log('Original:', secret)
+console.log('Encrypted:', encrypted)
+console.log('Encrypted length:', encrypted.length)
+```
+
+The encrypted output is a base64-encoded string containing the IV, auth tag, and ciphertext. It is safe to store in config files or databases.
+
+## Decrypting Back to Plaintext
+
+Use `decrypt()` with the same vault instance to recover the original value.
+
+```ts
+const decrypted = vault.decrypt(encrypted)
+console.log('Decrypted:', decrypted)
+console.log('Round-trip matches:', decrypted === secret)
+```
+
+The decrypted value is identical to the original input.
+
+## Encrypting Multiple Values
+
+Each call to `encrypt()` produces a unique ciphertext, even for the same input, because a fresh IV is generated every time.
+
+```ts
+const a = vault.encrypt('same-input')
+const b = vault.encrypt('same-input')
+console.log('Encryption A:', a)
+console.log('Encryption B:', b)
+console.log('Same ciphertext?', a === b)
+console.log('Both decrypt correctly?', vault.decrypt(a) === vault.decrypt(b))
+```
+
+This property (semantic security) means an attacker cannot tell if two ciphertexts contain the same plaintext.
+
+## Summary
+
+This demo covered enabling the vault, encrypting strings, decrypting them back, and verifying that repeated encryption produces unique ciphertexts. The `vault` feature provides straightforward authenticated encryption for any sensitive data your application handles.

package/docs/examples/vm.md

@@ -0,0 +1,86 @@
+---
+title: "vm"
+tags: [vm, sandbox, evaluation, core]
+lastTested: null
+lastTestPassed: null
+---
+
+# vm
+
+JavaScript VM for evaluating code in isolated contexts with shared or independent state.
+
+## Overview
+
+The `vm` feature is a core feature, auto-enabled on every container. You can access it directly as a global or via `container.feature('vm')`. It provides methods for running JavaScript in sandboxed contexts, passing variables in, and optionally preserving state across multiple runs. Use it for plugin systems, dynamic code evaluation, or testing snippets in isolation.
+
+## Simple Expression Evaluation
+
+Use `runSync()` to evaluate a JavaScript expression and get the result back immediately.
+
+```ts
+const sum = vm.runSync('2 + 3 * 4')
+console.log('2 + 3 * 4 =', sum)
+
+const greeting = vm.runSync('`Hello ${name}!`', { name: 'Luca' })
+console.log(greeting)
+```
+
+The second argument is an optional context object whose keys become variables in the evaluated code.
+
+## Running with Context Variables
+
+Use `run()` for async evaluation with injected variables. This is the async equivalent of `runSync()`.
+
+```ts
+const result = await vm.run('numbers.reduce((a, b) => a + b, 0)', {
+  numbers: [10, 20, 30, 40]
+})
+console.log('Sum of [10, 20, 30, 40]:', result)
+```
+
+Any JavaScript value can be passed through the context -- arrays, objects, functions, and primitives.
+
+## Getting the Context Back
+
+Use `performSync()` to run code and get both the result and the modified context. This lets you inspect variables that were set during execution.
+
+```ts
+const { result, context } = vm.performSync('x = x * 2; x + 1', { x: 21 })
+console.log('Result:', result)
+console.log('x after execution:', context.x)
+```
+
+The context is mutated in place, so you can see side effects of the evaluated code.
+
+## Shared State Across Runs
+
+Use `createContext()` to build a persistent context that carries state across multiple evaluations.
+
+```ts
+const ctx = vm.createContext({ counter: 0 })
+vm.runSync('counter += 1', ctx)
+vm.runSync('counter += 1', ctx)
+vm.runSync('counter += 10', ctx)
+console.log('Counter after 3 runs:', vm.runSync('counter', ctx))
+```
+
+The same context object is reused, so variables accumulate across calls.
+
+## Error Handling
+
+When evaluated code might throw, wrap the call in a try/catch to handle it gracefully.
+
+```ts
+try {
+  vm.runSync('undefinedFunction()')
+} catch (err) {
+  console.log('Error caught:', err.constructor.name)
+  console.log('Message:', err.message)
+}
+```
+
+This keeps a bad snippet from crashing the rest of your program.
+
+## Summary
+
+This demo covered synchronous and async expression evaluation, passing context variables into the sandbox, inspecting mutated context after execution, maintaining shared state across runs, and safe error handling. The `vm` feature is the foundation for dynamic code execution in any Luca application.

package/docs/examples/window-manager.md

@@ -0,0 +1,125 @@
+---
+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()`.

package/docs/examples/yaml-tree.md

@@ -0,0 +1,93 @@
+---
+title: "YAML Tree"
+tags: [yamlTree, yaml, files, data-loading]
+lastTested: null
+lastTestPassed: null
+---
+
+# yamlTree
+
+Load YAML files from directory structures into a nested object tree.
+
+## Overview
+
+The `yamlTree` feature is an on-demand feature that recursively scans a directory for `.yml` and `.yaml` files and builds a hierarchical JavaScript object from them. It works identically to `jsonTree` but for YAML content. File paths are converted to camelCased property paths, so `config/database/production.yml` becomes `tree.config.database.production`. This is useful for projects that store configuration, infrastructure definitions, or data in YAML format.
+
+## Feature Documentation
+
+Let us inspect the feature's built-in documentation.
+
+```ts
+const desc = container.features.describe('yamlTree')
+console.log(desc)
+```
+
+Like jsonTree, the key method is `loadTree(basePath, key?)` and the data is accessed through the `tree` getter.
+
+## Enabling the Feature
+
+Enable yamlTree and check its initial state.
+
+```ts
+const yamlTree = container.feature('yamlTree', { enable: true })
+console.log('yamlTree enabled:', yamlTree.state.enabled)
+console.log('Initial tree:', JSON.stringify(yamlTree.tree))
+```
+
+The tree starts empty until you load directories into it.
+
+## Loading YAML Files
+
+We can attempt to load YAML files from the project. If the project has any `.yml` or `.yaml` files, they will appear in the tree.
+
+```ts
+await yamlTree.loadTree('.', 'root')
+const keys = Object.keys(yamlTree.tree.root || {})
+console.log('Keys loaded under root:', keys.length ? keys.join(', ') : '(no YAML files found)')
+```
+
+If no YAML files are found, the tree for that key will be empty. This is expected for projects that do not use YAML.
+
+## How It Compares to jsonTree
+
+The yamlTree and jsonTree features share the same design pattern:
+
+- Both recursively scan directories
+- Both convert file paths to camelCased property paths
+- Both store results in a `tree` getter
+- Both accept a custom key for namespacing
+
+The only difference is the file extensions they look for and the parser they use.
+
+```ts
+const comparison = {
+  jsonTree: { extensions: ['.json'], parser: 'JSON.parse' },
+  yamlTree: { extensions: ['.yml', '.yaml'], parser: 'YAML parser' },
+}
+for (const [name, info] of Object.entries(comparison)) {
+  console.log(`${name}: scans ${info.extensions.join(', ')} files, uses ${info.parser}`)
+}
+```
+
+## Path Transformation Rules
+
+The same path transformation rules apply as in jsonTree:
+
+- Directory names become nested object properties
+- File names (without extension) become leaf properties
+- All names are converted to camelCase
+
+```ts
+const mappings = {
+  'infra/k8s/deployment.yml': 'tree.infra.k8s.deployment',
+  'config/app-settings.yaml': 'tree.config.appSettings',
+  'data/seed/users.yml': 'tree.data.seed.users',
+}
+for (const [file, path] of Object.entries(mappings)) {
+  console.log(`${file} => ${path}`)
+}
+```
+
+## Summary
+
+This demo covered the `yamlTree` feature, which scans directories for YAML files (.yml and .yaml) and builds a nested object tree. It follows the same pattern as `jsonTree` and is ideal for projects that rely on YAML for configuration, infrastructure definitions, or structured data.

package/docs/examples/yaml.md

@@ -0,0 +1,104 @@
+---
+title: "YAML"
+tags: [yaml, parsing, serialization, config]
+lastTested: null
+lastTestPassed: null
+---
+
+# yaml
+
+Parse YAML strings into JavaScript objects and serialize objects back to YAML. A thin wrapper around js-yaml.
+
+## Overview
+
+The `yaml` feature is on-demand. It provides two methods: `parse()` and `stringify()`. Use it any time you need to read or write YAML configuration files, convert between formats, or work with YAML data in memory.
+
+## Parsing a YAML String
+
+Start by enabling the feature and parsing some YAML.
+
+```ts
+const yml = container.feature('yaml')
+const config = yml.parse(`
+name: my-app
+version: 2.1.0
+database:
+  host: localhost
+  port: 5432
+features:
+  - auth
+  - logging
+  - caching
+`)
+console.log('Parsed name:', config.name)
+console.log('Parsed db host:', config.database.host)
+console.log('Parsed features:', config.features)
+```
+
+The parser handles nested objects, arrays, numbers, and booleans automatically.
+
+## Serializing an Object to YAML
+
+Use `stringify()` to convert a JavaScript object into a YAML-formatted string.
+
+```ts
+const output = yml.stringify({
+  server: { host: '0.0.0.0', port: 3000 },
+  logging: { level: 'info', pretty: true },
+  cors: { origins: ['https://example.com', 'https://app.example.com'] }
+})
+console.log('YAML output:')
+console.log(output)
+```
+
+The output is human-readable and suitable for writing to configuration files.
+
+## Round-Trip Conversion
+
+A common pattern is reading YAML, modifying data, and writing it back. Here we verify that a round-trip preserves data.
+
+```ts
+const original = `
+environment: production
+replicas: 3
+resources:
+  cpu: 500m
+  memory: 256Mi
+`
+const parsed = yml.parse(original)
+parsed.replicas = 5
+parsed.resources.memory = '512Mi'
+const updated = yml.stringify(parsed)
+console.log('Updated YAML:')
+console.log(updated)
+const reparsed = yml.parse(updated)
+console.log('Replicas after round-trip:', reparsed.replicas)
+console.log('Memory after round-trip:', reparsed.resources.memory)
+```
+
+The data survives the parse-modify-stringify cycle intact.
+
+## Working with Complex Structures
+
+YAML handles deeply nested and mixed-type structures well.
+
+```ts
+const complex = yml.stringify({
+  users: [
+    { name: 'Alice', roles: ['admin', 'editor'], active: true },
+    { name: 'Bob', roles: ['viewer'], active: false },
+  ],
+  settings: {
+    maxRetries: 3,
+    timeout: null,
+    nested: { deep: { value: 42 } }
+  }
+})
+console.log(complex)
+```
+
+Nulls, booleans, numbers, and nested arrays all serialize cleanly.
+
+## Summary
+
+This demo covered parsing YAML strings, serializing objects to YAML, round-trip conversion, and handling complex nested structures. The `yaml` feature gives you a clean two-method API for all YAML operations.