luca 2.0.0 → 3.0.2

package/src/web/features/helpers.ts

@@ -0,0 +1,291 @@
+import { z } from 'zod'
+import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
+import { Feature } from '../feature.js'
+import { Client } from '../../client.js'
+import { allHelperInstances } from '../../container.js'
+import type { Helper } from '../../helper.js'
+import type { Registry } from '../../registry.js'
+import type { AssetLoader } from './asset-loader.js'
+
+export const HelpersStateSchema = FeatureStateSchema.extend({
+  discovered: z.record(z.string(), z.boolean()).default({}).describe('Which registry types have been discovered'),
+  registered: z.array(z.string()).default([]).describe('Names of project-level helpers that were discovered (type.name)'),
+  manifestLoaded: z.boolean().default(false).describe('Whether the manifest has been fetched'),
+})
+
+export type HelpersState = z.infer<typeof HelpersStateSchema>
+
+export const HelpersOptionsSchema = FeatureOptionsSchema.extend({
+  manifestURL: z.string().optional().describe('URL to fetch the helpers manifest from. Defaults to /.well-known/luca.manifest.json'),
+})
+
+export type HelpersOptions = z.infer<typeof HelpersOptionsSchema>
+
+export const HelpersEventsSchema = FeatureEventsSchema.extend({
+  discovered: z.tuple([
+    z.string().describe('Registry type that was discovered'),
+    z.array(z.string()).describe('Names of newly registered helpers'),
+  ]).describe('Emitted after a registry type has been discovered'),
+  registered: z.tuple([
+    z.string().describe('Registry type'),
+    z.string().describe('Helper name'),
+  ]).describe('Emitted when a single helper is registered'),
+  manifestLoaded: z.tuple([
+    z.any().describe('The parsed manifest object'),
+  ]).describe('Emitted when the manifest is successfully fetched'),
+  manifestError: z.tuple([
+    z.any().describe('The error that occurred'),
+  ]).describe('Emitted when the manifest fetch fails'),
+})
+
+type RegistryType = 'features' | 'clients'
+
+interface ManifestEntry {
+  id: string
+  description?: string
+  url: string
+}
+
+interface Manifest {
+  features?: Record<string, ManifestEntry>
+  clients?: Record<string, ManifestEntry>
+}
+
+/**
+ * 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.
+ *
+ * @example
+ * ```typescript
+ * 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)
+ * ```
+ */
+export class Helpers extends Feature<HelpersState, HelpersOptions> {
+  static override shortcut = 'features.helpers' as const
+  static override description = 'Unified gateway for discovering and registering project-level helpers via HTTP manifest'
+  static override stateSchema = HelpersStateSchema
+  static override optionsSchema = HelpersOptionsSchema
+  static override eventsSchema = HelpersEventsSchema
+
+  static { Feature.register(this as any, 'helpers') }
+
+  private _manifest: Manifest | null = null
+
+  private get registryMap(): Record<RegistryType, { registry: Registry<any> }> {
+    return {
+      features: { registry: this.container.features as any },
+      clients: { registry: (this.container as any).clients as Registry<any> },
+    }
+  }
+
+  /** The URL to fetch the helpers manifest from. */
+  get manifestURL(): string {
+    return this.options.manifestURL || '/.well-known/luca.manifest.json'
+  }
+
+  /**
+   * Set a new manifest URL. Invalidates any cached manifest.
+   *
+   * @param url - The new URL to fetch the manifest from
+   */
+  setManifestURL(url: string) {
+    this.options.manifestURL = url
+    this._manifest = null
+    this.state.set('manifestLoaded', false)
+  }
+
+  /**
+   * Returns all instantiated helper instances across all types, optionally filtered by class.
+   *
+   * @param FilterClass - When provided, only instances of this class are returned.
+   *
+   * @example
+   * ```typescript
+   * // All instances of any type
+   * container.helpers.getInstances()
+   *
+   * // All Assistant instances
+   * const assistants = container.helpers.getInstances(Assistant)
+   * ```
+   */
+  getInstances(): Helper[]
+  getInstances<T extends Helper>(FilterClass: new (...args: any[]) => T): T[]
+  getInstances<T extends Helper>(FilterClass?: new (...args: any[]) => T): Helper[] | T[] {
+    return FilterClass ? allHelperInstances(FilterClass) : allHelperInstances()
+  }
+
+  /**
+   * 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.
+   */
+  get available(): Record<string, string[]> {
+    const result: Record<string, string[]> = {}
+    for (const [type, { registry }] of Object.entries(this.registryMap)) {
+      result[type] = registry.available
+    }
+    return result
+  }
+
+  /**
+   * Fetch and cache the manifest JSON. Returns cached version on subsequent calls
+   * unless invalidated by setManifestURL().
+   */
+  private async fetchManifest(): Promise<Manifest> {
+    if (this._manifest) {
+      return this._manifest
+    }
+
+    try {
+      const response = await fetch(this.manifestURL)
+
+      if (!response.ok) {
+        const err = new Error(`Manifest fetch failed: ${response.status} ${response.statusText}`)
+        this.emit('manifestError' as any, err)
+        return {}
+      }
+
+      const manifest = await response.json() as Manifest
+      this._manifest = manifest
+      this.state.set('manifestLoaded', true)
+      this.emit('manifestLoaded' as any, manifest)
+      return manifest
+    } catch (err: any) {
+      this.emit('manifestError' as any, err)
+      return {}
+    }
+  }
+
+  /**
+   * Get the AssetLoader instance from the container.
+   */
+  private get assetLoader(): AssetLoader {
+    return this.container.feature('assetLoader') as unknown as AssetLoader
+  }
+
+  /**
+   * 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.
+   *
+   * @param type - Which type of helpers to discover ('features' or 'clients')
+   * @returns Names of helpers that were discovered and registered
+   */
+  async discover(type: RegistryType): Promise<string[]> {
+    const discovered = this.state.get('discovered') || {}
+
+    if (discovered[type]) {
+      return []
+    }
+
+    const manifest = await this.fetchManifest()
+    const entries = manifest[type] || {}
+    const { registry } = this.registryMap[type]
+    const newNames: string[] = []
+
+    for (const [name, entry] of Object.entries(entries)) {
+      const beforeNames = new Set(registry.available)
+
+      try {
+        await this.assetLoader.loadScript(entry.url)
+      } catch (err: any) {
+        console.warn(`Helpers: failed to load ${type}/${name} from ${entry.url}: ${err.message}`)
+        continue
+      }
+
+      const afterNames = registry.available
+      const added = afterNames.filter((n: string) => !beforeNames.has(n))
+
+      if (added.length > 0) {
+        for (const addedName of added) {
+          newNames.push(addedName)
+          this.emit('registered' as any, type, addedName)
+        }
+      } else if (registry.has(name)) {
+        // Script may have already been registered under the expected name
+        if (!beforeNames.has(name)) {
+          newNames.push(name)
+          this.emit('registered' as any, type, name)
+        }
+      }
+    }
+
+    this.state.set('discovered', { ...this.state.get('discovered'), [type]: true })
+
+    const existing = this.state.get('registered') || []
+    this.state.set('registered', [...existing, ...newNames.map(n => `${type}.${n}`)])
+
+    this.emit('discovered' as any, type, newNames)
+
+    return newNames
+  }
+
+  /**
+   * Discover all helper types from the manifest.
+   *
+   * @returns Map of registry type to discovered helper names
+   */
+  async discoverAll(): Promise<Record<string, string[]>> {
+    const results: Record<string, string[]> = {}
+
+    for (const type of ['features', 'clients'] as RegistryType[]) {
+      results[type] = await this.discover(type)
+    }
+
+    return results
+  }
+
+  /**
+   * Convenience method to discover only features.
+   */
+  async discoverFeatures(): Promise<string[]> {
+    return this.discover('features')
+  }
+
+  /**
+   * Convenience method to discover only clients.
+   */
+  async discoverClients(): Promise<string[]> {
+    return this.discover('clients')
+  }
+
+  /**
+   * Look up a helper class by type and name.
+   *
+   * @param type - The registry type
+   * @param name - The helper name within that registry
+   * @returns The helper constructor
+   */
+  lookup(type: RegistryType, name: string): any {
+    const { registry } = this.registryMap[type]
+    return registry.lookup(name)
+  }
+
+  /**
+   * Get the introspection description for a specific helper.
+   *
+   * @param type - The registry type
+   * @param name - The helper name
+   * @returns Markdown description of the helper's interface
+   */
+  describe(type: RegistryType, name: string): string {
+    const { registry } = this.registryMap[type]
+    return registry.describe(name)
+  }
+}
+
+export default Helpers

package/src/web/features/network.ts

@@ -0,0 +1,85 @@
+/// <reference lib="dom" />
+import { z } from 'zod'
+import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
+import { Feature } from "../feature.js";
+import type { ContainerContext } from "../container.js";
+
+export const NetworkStateSchema = FeatureStateSchema.extend({
+  offline: z.boolean().describe('Whether the browser is currently offline'),
+})
+
+export const NetworkOptionsSchema = FeatureOptionsSchema.extend({})
+
+export const NetworkEventsSchema = FeatureEventsSchema.extend({
+  online: z.tuple([]).describe('Fires when the browser regains network connectivity'),
+  offline: z.tuple([]).describe('Fires when the browser loses network connectivity'),
+}).describe('Network events')
+
+export type NetworkState = z.infer<typeof NetworkStateSchema>
+export type NetworkOptions = z.infer<typeof NetworkOptionsSchema>
+
+/**
+ * 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.
+ *
+ * @extends Feature
+ *
+ * @example
+ * ```typescript
+ * 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')
+ * })
+ * ```
+ */
+export class Network<
+  T extends NetworkState = NetworkState,
+  K extends NetworkOptions = NetworkOptions
+> extends Feature<T, K> {
+  static override stateSchema = NetworkStateSchema
+  static override optionsSchema = NetworkOptionsSchema
+  static override eventsSchema = NetworkEventsSchema
+  static override shortcut = "features.network" as const
+
+  static { Feature.register(this as any, 'network') }
+  
+  constructor(options: K, context: ContainerContext) {
+    super(options, context);
+    this.state.set("offline", !navigator.onLine);
+  }
+
+  /** Whether the browser is currently offline. */
+  get isOffline() {
+    return this.state.get("offline") === true;
+  }
+
+  /** Whether the browser is currently online. */
+  get isOnline() {
+    return this.state.get("offline") === false;
+  }
+
+  private handleConnectionChange = () => {
+    const isOffline = !navigator.onLine;
+    this.state.set('offline', isOffline)
+    this.emit(isOffline ? "offline" : "online");
+  };
+
+  start() {
+    window.addEventListener("online", this.handleConnectionChange);
+    window.addEventListener("offline", this.handleConnectionChange);
+    return this
+  }
+
+  disable() {
+    window.removeEventListener("online", this.handleConnectionChange);
+    window.removeEventListener("offline", this.handleConnectionChange);
+    return this
+  }
+}
+
+export default Network

package/src/web/features/speech.ts

@@ -0,0 +1,104 @@
+import { z } from 'zod'
+import { FeatureStateSchema, FeatureOptionsSchema } from '../../schemas/base.js'
+import { Feature } from "../feature.js";
+import { type ContainerContext } from "../container.js";
+
+export const SpeechOptionsSchema = FeatureOptionsSchema.extend({
+  voice: z.string().optional().describe('The voice to use for the speech'),
+})
+
+export const SpeechStateSchema = FeatureStateSchema.extend({
+  defaultVoice: z.string().describe('Name of the currently selected default voice'),
+  voices: z.array(z.any().describe('Voice object')).optional().describe('Available speech synthesis voices'),
+})
+
+export type SpeechOptions = z.infer<typeof SpeechOptionsSchema>
+export type SpeechState = z.infer<typeof SpeechStateSchema>
+
+type Voice = {
+  voiceURI: string;
+  name: string;
+  lang: string;
+  localService: boolean;
+  default: boolean;
+};  
+
+/**
+ * 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.
+ *
+ * @extends Feature
+ *
+ * @example
+ * ```typescript
+ * 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!')
+ * ```
+ */
+export class Speech<
+  T extends SpeechState = SpeechState,
+  K extends SpeechOptions = SpeechOptions
+> extends Feature<T, K> {
+
+  static override stateSchema = SpeechStateSchema
+  static override optionsSchema = SpeechOptionsSchema
+  static override shortcut = "features.speech" as const
+
+  static { Feature.register(this as any, 'speech') }
+  
+  constructor(options: K, context: ContainerContext) {
+    super(options,context)  
+
+    if(options.voice) {
+      this.state.set("defaultVoice", options.voice)
+    }
+
+    this.loadVoices()
+  }
+  
+  /** Returns the array of available speech synthesis voices. */
+  get voices() {
+    return this.state.get('voices') || []
+  }
+
+  /** Returns the Voice object matching the currently selected default voice name. */
+  get defaultVoice() {
+    return this.voices.find(v => v.name === this.state.get("defaultVoice"))
+  }
+
+  loadVoices() {
+    const voices = speechSynthesis.getVoices();
+    this.state.set("voices", voices);
+
+    if (!this.state.get("defaultVoice") && voices.length > 0) {
+      const defaultVoice = voices.find(v => v.default)!
+      this.state.set("defaultVoice", defaultVoice.name);
+    }
+  }
+
+  setDefaultVoice(name: string) {
+    const voice = this.voices.find(v => v.name === name)!
+    this.state.set("defaultVoice", voice.name);
+  }
+  
+  cancel() {
+    speechSynthesis.cancel()
+    return this
+  }
+
+  say(text: string, options: { voice?: Voice } = {}) {
+    const utterance = new SpeechSynthesisUtterance(text);
+    const voice = options.voice || this.defaultVoice 
+    utterance.voice = voice || this.voices[0]! 
+    speechSynthesis.speak(utterance);
+  }
+}
+
+export default Speech;

package/src/web/features/vault.ts

@@ -0,0 +1,207 @@
+// @ts-nocheck
+import { z } from 'zod'
+import { FeatureStateSchema, FeatureOptionsSchema } from '../../schemas/base.js'
+import { Feature } from '../feature.js'
+
+export const WebVaultStateSchema = FeatureStateSchema.extend({
+  secret: z.string().optional().describe('Base64-encoded AES-GCM encryption secret key'),
+})
+
+export const WebVaultOptionsSchema = FeatureOptionsSchema.extend({
+  secret: z.string().optional().describe('Pre-existing base64-encoded secret key to use'),
+})
+
+export type WebVaultState = z.infer<typeof WebVaultStateSchema>
+export type WebVaultOptions = z.infer<typeof WebVaultOptionsSchema>
+
+/**
+ * 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.
+ *
+ * @extends Feature
+ *
+ * @example
+ * ```typescript
+ * const vault = container.feature('vault')
+ * const encrypted = await vault.encrypt('secret data')
+ * const decrypted = await vault.decrypt(encrypted)
+ * console.log(decrypted) // 'secret data'
+ * ```
+ */
+export class WebVault extends Feature<WebVaultState, WebVaultOptions> {
+  static override stateSchema = WebVaultStateSchema
+  static override optionsSchema = WebVaultOptionsSchema
+  static override shortcut = "features.vault" as const
+
+  static { Feature.register(this, 'vault') }
+  
+  async secret({ refresh = false, set = true } = {}) : Promise<ArrayBuffer> {
+    if (!this.state.get('secret') && this.options.secret) {
+      this.state.set('secret', this.options.secret)
+    }
+
+    if (!refresh && this.state.get('secret')) {
+      return base64ToArrayBuffer(this.state.get('secret')!)
+    }
+
+    const val = await generateSecretKey()   
+    const asString = arrayBufferToBase64(val)
+
+    if(set && !this.state.get('secret')) {
+      this.state.set('secret', asString)
+    }
+    
+    return val
+  }
+ 
+  async decrypt(payload: string) {
+    const parts = payload.split("\n------\n")
+    const iv = base64ToUint8Array(parts[1]!)
+    const ciphertext = base64ToArrayBuffer(parts[0]!)
+    const secret = await this.secret()
+    
+    console.log(ciphertext, secret, iv)
+    return await decrypt(ciphertext, secret, iv)
+  }
+
+  async encrypt(payload: string) {
+    const secret = await this.secret()
+    console.log("encrypting", payload, secret)
+    const { iv, ciphertext, } = await encrypt(payload, secret)
+
+    return [
+      arrayBufferToBase64(ciphertext),
+      uint8ArrayToBase64(iv)
+    ].join("\n------\n")
+  }
+  
+  utils = {
+    arrayToString: arrayBufferToBase64,
+    stringToArray: base64ToArrayBuffer,
+    uintToString: uint8ArrayToBase64,
+  }
+}
+
+export default WebVault
+
+async function generateSecretKey(): Promise<ArrayBuffer> {
+  const key = await crypto.subtle.generateKey(
+    { name: "AES-GCM", length: 256 },
+    true,
+    ["encrypt", "decrypt"]
+  );
+  const secretKey = await crypto.subtle.exportKey("raw", key);
+  return secretKey;
+}
+
+async function encrypt(plaintext: string, secretKey: ArrayBuffer): Promise<{ iv: Uint8Array; ciphertext: ArrayBuffer }> {
+  const encoder = new TextEncoder();
+  const encodedText = encoder.encode(plaintext);
+  const key = await crypto.subtle.importKey(
+    "raw",
+    secretKey,
+    { name: "AES-GCM" },
+    false,
+    ["encrypt", "decrypt"]
+  );
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const ciphertext = await crypto.subtle.encrypt(
+    { name: "AES-GCM", iv },
+    key,
+    encodedText
+  );
+  return { iv, ciphertext };
+}
+
+async function decrypt(ciphertext: ArrayBuffer, secretKey: ArrayBuffer, iv: Uint8Array): Promise<string> {
+  const key = await crypto.subtle.importKey(
+    "raw",
+    secretKey,
+    { name: "AES-GCM" },
+    false,
+    ["encrypt", "decrypt"]
+  );
+  const plaintextArrayBuffer = await crypto.subtle.decrypt(
+    { name: "AES-GCM", iv },
+    key,
+    ciphertext
+  );
+  const decoder = new TextDecoder();
+  const plaintext = decoder.decode(plaintextArrayBuffer);
+  return plaintext;
+}
+
+function arrayBufferToBase64(buffer: ArrayBuffer): string {
+  const bytes = new Uint8Array(buffer);
+  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+  let base64 = "";
+
+  for (let i = 0; i < bytes.byteLength; i += 3) {
+    const a = bytes[i];
+    const b = bytes[i + 1];
+    const c = bytes[i + 2];
+
+    const index1 = a >> 2;
+    const index2 = ((a & 0x03) << 4) | (b >> 4);
+    const index3 = isNaN(b!) ? 64 : ((b & 0x0f) << 2) | (c >> 6);
+    const index4 = isNaN(b!) || isNaN(c!) ? 64 : c & 0x3f;
+
+    base64 += chars[index1] + chars[index2] + chars[index3] + chars[index4];
+  }
+
+  return base64.replace('undefined', '==');
+}
+
+function uint8ArrayToBase64(u: Uint8Array): string {
+  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+  let base64 = "";
+
+  for (let i = 0; i < u.byteLength; i += 3) {
+    const a = u[i];
+    const b = u[i + 1];
+    const c = u[i + 2];
+
+    const index1 = a >> 2;
+    const index2 = ((a & 0x03) << 4) | (b >> 4);
+    const index3 = isNaN(b!) ? 64 : ((b & 0x0f) << 2) | (c >> 6);
+    const index4 = isNaN(b!) || isNaN(c!) ? 64 : c & 0x3f;
+
+    base64 += chars[index1]! + chars[index2]! + chars[index3]! + chars[index4]!;
+  }
+
+  return base64;
+}
+
+function base64ToArrayBuffer(base64: string): ArrayBuffer {
+  const uint8Array = base64ToUint8Array(base64)!;
+  return uint8Array.buffer as ArrayBuffer;
+}
+
+function base64ToUint8Array(base64: string): Uint8Array {
+  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+  const lookup = new Uint8Array(256);
+  
+  for (let i = 0; i < chars.length; i++) {
+    lookup[chars.charCodeAt(i)] = i;
+  }
+
+  const padding = base64.endsWith("==") ? 2 : base64.endsWith("=") ? 1 : 0;
+  const length = (base64.length * 3 / 4) - padding;
+  const bytes = new Uint8Array(length);
+
+  for (let i = 0, j = 0; i < base64.length; i += 4, j += 3) {
+    const index1 = lookup[base64.charCodeAt(i)];
+    const index2 = lookup[base64.charCodeAt(i + 1)];
+    const index3 = lookup[base64.charCodeAt(i + 2)];
+    const index4 = lookup[base64.charCodeAt(i + 3)];
+
+    bytes[j] = (index1 << 2) | (index2 >> 4);
+    if (j + 1 < length) bytes[j + 1] = ((index2 & 0x0f) << 4) | (index3 >> 2);
+    if (j + 2 < length) bytes[j + 2] = ((index3 & 0x03) << 6) | index4;
+  }
+
+  return bytes;
+}