@zeroweight/renderer 0.2.0

package/README.md

@@ -0,0 +1,158 @@
+# @zeroweight/renderer
+
+Universal avatar rendering engine. Framework-agnostic — use via CDN `<script>` tag or ES module import.
+
+## Installation
+
+### CDN (Script Tag)
+
+```html
+<script src="https://unpkg.com/@zeroweight/renderer/dist/zeroweight-renderer.umd.js"></script>
+```
+
+Or via jsDelivr:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@zeroweight/renderer/dist/zeroweight-renderer.umd.js"></script>
+```
+
+### npm / yarn
+
+```bash
+npm install @zeroweight/renderer
+```
+
+## Quick Start
+
+### Via `<script>` tag
+
+```html
+<canvas id="avatar" width="640" height="480"></canvas>
+
+<script src="https://unpkg.com/@zeroweight/renderer/dist/zeroweight-renderer.umd.js"></script>
+<script>
+  const { ZeroWeightRenderer, ActionQueue, VoiceActivityDetector } = window.ZeroWeightRenderer;
+
+  const renderer = new ZeroWeightRenderer();
+  const canvas = document.getElementById('avatar');
+
+  // Init with your avatar bundle payload
+  await renderer.init(canvas, { payload: bundleData });
+
+  // Play actions
+  renderer.play('speaking');
+  renderer.play('wave_hand', 'listening'); // oneshot with fallback
+
+  // Clean up
+  renderer.destroy();
+</script>
+```
+
+### Via ES module
+
+```js
+import {
+  ZeroWeightRenderer,
+  ActionQueue,
+  VoiceActivityDetector,
+} from "@zeroweight/renderer";
+
+const renderer = new ZeroWeightRenderer();
+await renderer.init(canvas, { payload: bundleData });
+```
+
+## API
+
+### `ZeroWeightRenderer`
+
+The core rendering engine. Handles WASM initialization, canvas setup, render loop, and action management.
+
+```js
+const renderer = new ZeroWeightRenderer();
+```
+
+| Method                      | Description                                        |
+| --------------------------- | -------------------------------------------------- |
+| `init(canvas, config)`      | Initialize with a canvas element and bundle config |
+| `play(actionId, fallback?)` | Play an action (e.g. `"speaking"`, `"wave_hand"`)  |
+| `interrupt()`               | Interrupt the current action                       |
+| `destroy()`                 | Clean up all resources                             |
+
+| Property     | Description                                                      |
+| ------------ | ---------------------------------------------------------------- |
+| `state`      | Current state: `"idle"` \| `"loading"` \| `"ready"` \| `"error"` |
+| `isReady`    | `true` when engine is ready                                      |
+| `dimensions` | Avatar intrinsic `{ width, height }`                             |
+
+**Events:** `ready`, `actionLoaded`, `allActionsLoaded`, `dimensions`, `error`, `stateChanged`
+
+```js
+renderer.on("ready", () => console.log("Engine ready!"));
+renderer.on("dimensions", (w, h) => console.log(`Avatar: ${w}x${h}`));
+```
+
+### `ActionQueue`
+
+Centralized action dispatch with turn-based queuing for speech synchronization.
+
+```js
+const queue = new ActionQueue((actionId, fallback) => {
+  renderer.play(actionId, fallback);
+});
+
+queue.dispatch("wave_hand"); // Execute or queue
+queue.setTurnActive(true); // Start speaking turn
+queue.setSpeechState("speaking"); // Update speech state
+queue.forceListening(); // Reset to listening
+```
+
+### `VoiceActivityDetector`
+
+Amplitude-based VAD using Web Audio API with hysteresis for lipsync.
+
+```js
+const vad = new VoiceActivityDetector({
+  threshold: 0.008,
+  speechStartFrames: 1,
+  speechPauseFrames: 30,
+  turnEndFrames: 50,
+});
+
+vad.on("speechStart", () => queue.setTurnActive(true));
+vad.on("turnEnd", () => queue.setTurnActive(false));
+
+vad.start(mediaStreamTrack);
+```
+
+## Usage Tiers
+
+| Tier               | What you get                                                           | Use case                 |
+| ------------------ | ---------------------------------------------------------------------- | ------------------------ |
+| **Tier 1 (Raw)**   | `ZeroWeightRenderer` only                                              | Custom engine control    |
+| **Tier 2 (Queue)** | + `ActionQueue` + `VoiceActivityDetector`                              | Speech-synced avatars    |
+| **Tier 3 (React)** | [`@zeroweight/react`](https://www.npmjs.com/package/@zeroweight/react) | Drop-in React components |
+
+## Build from Source
+
+```bash
+git clone <repo-url>
+cd zeroweight-renderer
+npm install
+npm run build
+```
+
+Output in `dist/`:
+
+- `zeroweight-renderer.umd.js` — UMD bundle (script tag)
+- `zeroweight-renderer.es.js` — ES module
+- `index.d.ts` — TypeScript declarations
+
+## Deploy
+
+```bash
+npm publish --access public
+```
+
+## License
+
+MIT

package/dist/ActionQueue.d.ts

@@ -0,0 +1,85 @@
+/**
+ * zeroweight-renderer — ActionQueue
+ *
+ * Centralized action dispatch + queue system.
+ * ALL calls to the rendering engine go through this single coordinator.
+ *
+ * Key concepts:
+ * - "Turn": The entire speaking episode. While a turn is active, non-speaking
+ *   actions are queued and only executed after the turn ends.
+ * - "Speech state": Within a turn, the avatar can be "speaking" or "pause"
+ *   (natural breath/pause). Pauses change the avatar's visual pose but don't
+ *   drain the queue.
+ * - "Idle": No active turn. Actions execute immediately.
+ */
+import type { ActionMetadata, ActionQueueEvents, SpeechState } from "./types";
+/** Function that actually executes an action on the engine. */
+export type ActionExecutor = (actionId: string, fallbackAction?: string) => void;
+export declare class ActionQueue {
+    private executor;
+    private turnActive;
+    private speechState;
+    private currentAction;
+    private pendingQueue;
+    private actionMetadata;
+    private pulseTimer;
+    private pulseCount;
+    private static readonly PULSE_INTERVAL_MS;
+    private static readonly PULSE_MAX_COUNT;
+    private listeners;
+    constructor(executor: ActionExecutor);
+    /**
+     * Register action metadata so the queue knows which actions are looped vs oneshot.
+     */
+    setActionMetadata(metadata: Record<string, ActionMetadata>): void;
+    /**
+     * The SINGLE entry point for dispatching actions.
+     * All action requests MUST go through this method.
+     */
+    dispatch(actionId: string): void;
+    /**
+     * Mark whether a speaking turn is active.
+     * When a turn starts, speaking actions execute immediately and non-speech
+     * actions are queued. When a turn ends, the queue is drained.
+     */
+    setTurnActive(active: boolean): void;
+    /**
+     * Update the visual speech state within an active turn.
+     * "speaking" = avatar is speaking
+     * "pause" = natural pause, avatar goes to resting pose (but queue doesn't drain)
+     */
+    setSpeechState(state: SpeechState): void;
+    /**
+     * Force transition to listening and clear the queue.
+     * Used on disconnect, audio loss, etc.
+     */
+    forceListening(): void;
+    /**
+     * Get current state for debugging/UI purposes.
+     */
+    getState(): {
+        turnActive: boolean;
+        speechState: SpeechState;
+        currentAction: string;
+        queueLength: number;
+        queuedActions: string[];
+    };
+    on<K extends keyof ActionQueueEvents>(event: K, callback: ActionQueueEvents[K]): void;
+    off<K extends keyof ActionQueueEvents>(event: K, callback: ActionQueueEvents[K]): void;
+    private emit;
+    private isSpeechAction;
+    private executeOnEngine;
+    /**
+     * Pulse mechanism: re-sends the desired action multiple times at short intervals
+     * to ensure the renderer catches it after its 5-frame (~200ms) transition window.
+     * Duplicate triggers are idempotent on the renderer side — safe to call repeatedly.
+     */
+    private startPulse;
+    private stopPulse;
+    /**
+     * Drain queued actions after a turn ends. Each queued action plays as a
+     * oneshot, then we return to listening.
+     */
+    private drainQueue;
+}
+//# sourceMappingURL=ActionQueue.d.ts.map

package/dist/ActionQueue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ActionQueue.d.ts","sourceRoot":"","sources":["../src/ActionQueue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE9E,+DAA+D;AAC/D,MAAM,MAAM,cAAc,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;AAEjF,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAiB;IAGjC,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,aAAa,CAAe;IACpC,OAAO,CAAC,YAAY,CAAgB;IACpC,OAAO,CAAC,cAAc,CAAsC;IAK5D,OAAO,CAAC,UAAU,CAA+C;IACjE,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAAM;IAC/C,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAM;IAG7C,OAAO,CAAC,SAAS,CAAmE;gBAExE,QAAQ,EAAE,cAAc;IAMpC;;OAEG;IACH,iBAAiB,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,IAAI;IAIjE;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IA6BhC;;;;OAIG;IACH,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI;IA2BpC;;;;OAIG;IACH,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAwBxC;;;OAGG;IACH,cAAc,IAAI,IAAI;IAUtB;;OAEG;IACH,QAAQ;;;;;;;IAYR,EAAE,CAAC,CAAC,SAAS,MAAM,iBAAiB,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,IAAI;IAOrF,GAAG,CAAC,CAAC,SAAS,MAAM,iBAAiB,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,IAAI;IAOtF,OAAO,CAAC,IAAI;IAWZ,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,eAAe;IAavB;;;;OAIG;IACH,OAAO,CAAC,UAAU;IAkBlB,OAAO,CAAC,SAAS;IAQjB;;;OAGG;IACH,OAAO,CAAC,UAAU;CAuCnB"}

package/dist/VoiceActivityDetector.d.ts

@@ -0,0 +1,54 @@
+/**
+ * zeroweight-renderer — VoiceActivityDetector
+ *
+ * Amplitude-based VAD using Web Audio API with hysteresis to prevent
+ * flickering between speaking/listening states during natural speech pauses.
+ *
+ * State machine:
+ *   IDLE ──(amplitude > threshold for N frames)──> SPEAKING
+ *   SPEAKING ──(amplitude < threshold for M frames)──> PAUSED  (turn stays active)
+ *   PAUSED ──(amplitude > threshold for N frames)──> SPEAKING  (resumed)
+ *   PAUSED ──(amplitude < threshold for L frames total)──> IDLE  (turn ended)
+ *   SPEAKING ──(amplitude < threshold for L frames)──> IDLE  (turn ended, skipped pause)
+ *
+ * "Pause" means the avatar can visually transition to a resting pose, but the
+ * speaking turn is still active (action queue is NOT drained).
+ * "Turn end" means the speaking turn is over and the action queue can drain.
+ */
+import type { VADConfig, VADEvents } from "./types";
+type VADState = "idle" | "speaking" | "paused";
+export declare class VoiceActivityDetector {
+    private config;
+    private state;
+    private audioCtx;
+    private analyser;
+    private source;
+    private dataArray;
+    private intervalId;
+    private aboveCount;
+    private belowCount;
+    private listeners;
+    constructor(config?: VADConfig);
+    /**
+     * Start monitoring a MediaStreamTrack for voice activity.
+     */
+    start(track: MediaStreamTrack): void;
+    /**
+     * Stop monitoring and clean up resources.
+     */
+    stop(): void;
+    /**
+     * Force-end the current turn (e.g., when LiveKit state changes to non-speaking).
+     */
+    endTurn(): void;
+    /**
+     * Get the current VAD state.
+     */
+    getState(): VADState;
+    on<K extends keyof VADEvents>(event: K, callback: VADEvents[K]): void;
+    off<K extends keyof VADEvents>(event: K, callback: VADEvents[K]): void;
+    private emit;
+    private analyse;
+}
+export {};
+//# sourceMappingURL=VoiceActivityDetector.d.ts.map

package/dist/VoiceActivityDetector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VoiceActivityDetector.d.ts","sourceRoot":"","sources":["../src/VoiceActivityDetector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEpD,KAAK,QAAQ,GAAG,MAAM,GAAG,UAAU,GAAG,QAAQ,CAAC;AAW/C,qBAAa,qBAAqB;IAChC,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,KAAK,CAAoB;IAGjC,OAAO,CAAC,QAAQ,CAA6B;IAC7C,OAAO,CAAC,QAAQ,CAA6B;IAC7C,OAAO,CAAC,MAAM,CAA2C;IACzD,OAAO,CAAC,SAAS,CAA0C;IAG3D,OAAO,CAAC,UAAU,CAA+C;IAGjE,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,UAAU,CAAK;IAGvB,OAAO,CAAC,SAAS,CAAmD;gBAExD,MAAM,CAAC,EAAE,SAAS;IAM9B;;OAEG;IACH,KAAK,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI;IAsBpC;;OAEG;IACH,IAAI,IAAI,IAAI;IAqBZ;;OAEG;IACH,OAAO,IAAI,IAAI;IASf;;OAEG;IACH,QAAQ,IAAI,QAAQ;IAMpB,EAAE,CAAC,CAAC,SAAS,MAAM,SAAS,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI;IAOrE,GAAG,CAAC,CAAC,SAAS,MAAM,SAAS,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI;IAOtE,OAAO,CAAC,IAAI;IAWZ,OAAO,CAAC,OAAO;CAuDhB"}

package/dist/ZeroWeightRenderer.d.ts

@@ -0,0 +1,78 @@
+/**
+ * zeroweight-renderer — ZeroWeightRenderer
+ *
+ * Raw rendering engine wrapper. Framework-agnostic.
+ * Handles WASM initialization, canvas setup, render loop, action loading,
+ * and provides a clean API for playing actions.
+ *
+ * Usage (vanilla JS / CDN):
+ *   const renderer = new ZeroWeightRenderer();
+ *   await renderer.init(canvas, { payload: bundleData });
+ *   renderer.play('speaking');
+ *   renderer.play('wave_hand', 'listening');
+ *   renderer.destroy();
+ */
+import type { RendererConfig, RendererEvents, RendererState, ActionMetadata } from "./types";
+export declare class ZeroWeightRenderer {
+    private engine;
+    private canvas;
+    private container;
+    private rafId;
+    private resizeObserver;
+    private _state;
+    private loadedActions;
+    private actionMetadata;
+    private _dimensions;
+    private listeners;
+    private cancelled;
+    /**
+     * Initialize the renderer with a canvas and bundle config.
+     *
+     * @param canvas - The canvas element to render to.
+     *   If inside a container, the canvas will auto-resize to fill it.
+     * @param config - Renderer configuration with bundle payload.
+     * @returns A promise that resolves when the engine is ready.
+     */
+    init(canvas: HTMLCanvasElement, config: RendererConfig): Promise<void>;
+    /**
+     * Play an action on the avatar.
+     *
+     * @param actionId - The action to play (e.g. "speaking", "wave_hand").
+     * @param fallbackAction - Optional fallback action to play after a oneshot.
+     */
+    play(actionId: string, fallbackAction?: string): void;
+    /**
+     * Interrupt the current action.
+     */
+    interrupt(): void;
+    /**
+     * Load a single action by its config.
+     * Useful for lazy-loading actions after init.
+     */
+    loadAction(id: string, config: any): Promise<void>;
+    /**
+     * Destroy the renderer and clean up all resources.
+     */
+    destroy(): void;
+    get state(): RendererState;
+    get dimensions(): {
+        width: number;
+        height: number;
+    } | null;
+    get isReady(): boolean;
+    getLoadedActions(): Set<string>;
+    getActionMetadata(): Record<string, ActionMetadata>;
+    /**
+     * Direct access to the underlying engine instance (advanced usage).
+     */
+    getEngine(): any;
+    on<K extends keyof RendererEvents>(event: K, callback: RendererEvents[K]): void;
+    off<K extends keyof RendererEvents>(event: K, callback: RendererEvents[K]): void;
+    private emit;
+    private setState;
+    private startRenderLoop;
+    private setupResizeObserver;
+    private handleResize;
+    private loadRemainingActions;
+}
+//# sourceMappingURL=ZeroWeightRenderer.d.ts.map

package/dist/ZeroWeightRenderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ZeroWeightRenderer.d.ts","sourceRoot":"","sources":["../src/ZeroWeightRenderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,cAAc,EACd,aAAa,EACb,cAAc,EACf,MAAM,SAAS,CAAC;AAKjB,qBAAa,kBAAkB;IAE7B,OAAO,CAAC,MAAM,CAAkD;IAChE,OAAO,CAAC,MAAM,CAAkC;IAChD,OAAO,CAAC,SAAS,CAA4B;IAG7C,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,cAAc,CAA+B;IAGrD,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,aAAa,CAAkC;IACvD,OAAO,CAAC,cAAc,CAGpB;IACF,OAAO,CAAC,WAAW,CAAkD;IAGrE,OAAO,CAAC,SAAS,CAA6D;IAG9E,OAAO,CAAC,SAAS,CAAS;IAI1B;;;;;;;OAOG;IACG,IAAI,CAAC,MAAM,EAAE,iBAAiB,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IA4D5E;;;;;OAKG;IACH,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI;IAiBrD;;OAEG;IACH,SAAS,IAAI,IAAI;IAQjB;;;OAGG;IACG,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAcxD;;OAEG;IACH,OAAO,IAAI,IAAI;IAuBf,IAAI,KAAK,IAAI,aAAa,CAEzB;IAED,IAAI,UAAU,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAEzD;IAED,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,gBAAgB,IAAI,GAAG,CAAC,MAAM,CAAC;IAI/B,iBAAiB,IAAI,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC;IAInD;;OAEG;IACH,SAAS,IAAI,GAAG;IAMhB,EAAE,CAAC,CAAC,SAAS,MAAM,cAAc,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,IAAI;IAO/E,GAAG,CAAC,CAAC,SAAS,MAAM,cAAc,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,IAAI;IAOhF,OAAO,CAAC,IAAI;IAWZ,OAAO,CAAC,QAAQ;IAMhB,OAAO,CAAC,eAAe;IAUvB,OAAO,CAAC,mBAAmB;IAQ3B,OAAO,CAAC,YAAY;YAmBN,oBAAoB;CA8CnC"}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * zeroweight-renderer
+ *
+ * Universal avatar rendering library.
+ * Framework-agnostic — works via CDN <script> tag or ES module import.
+ *
+ * Usage tiers:
+ *   Tier 1 (Raw):   ZeroWeightRenderer only — play/interrupt/destroy
+ *   Tier 2 (Queue): + ActionQueue for managed dispatch + VoiceActivityDetector for lipsync
+ *   Tier 3 (React): Import from @zeroweight/react for full drop-in components
+ */
+export { ZeroWeightRenderer } from "./ZeroWeightRenderer";
+export { ActionQueue } from "./ActionQueue";
+export type { ActionExecutor } from "./ActionQueue";
+export { VoiceActivityDetector } from "./VoiceActivityDetector";
+export * from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,cAAc,SAAS,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * zeroweight-renderer — Types & Interfaces
+ *
+ * Framework-agnostic types for the avatar rendering library.
+ */
+export type ActionKind = "looped" | "oneshot" | "image";
+export interface ActionMetadata {
+    kind: ActionKind;
+}
+export type RendererState = "idle" | "loading" | "ready" | "error";
+export interface RendererConfig {
+    /** The bundle payload data (from API). */
+    payload: any;
+    /** Scale factor for mobile downscaling. Default: auto-detect. */
+    scale?: number;
+    /** Override mobile detection. */
+    forceMobile?: boolean;
+}
+export interface RendererEvents {
+    /** Engine fully initialized and first action ("listening") is ready. */
+    ready: () => void;
+    /** A background action finished loading. */
+    actionLoaded: (actionId: string, remaining: number) => void;
+    /** All background actions have been loaded. */
+    allActionsLoaded: () => void;
+    /** Avatar intrinsic dimensions are known. */
+    dimensions: (width: number, height: number) => void;
+    /** An error occurred. */
+    error: (error: Error) => void;
+    /** Renderer state changed. */
+    stateChanged: (state: RendererState) => void;
+}
+export type SpeechState = "speaking" | "pause" | "idle";
+export interface ActionQueueEvents {
+    /** An action was executed on the engine. */
+    actionExecuted: (actionId: string, fallback?: string) => void;
+    /** Speech state changed. */
+    speechStateChanged: (state: SpeechState) => void;
+    /** Turn started or ended. */
+    turnChanged: (active: boolean) => void;
+    /** Queue was drained after turn end. */
+    queueDrained: () => void;
+}
+export interface VADConfig {
+    /** RMS amplitude threshold (0-1). Default: 0.01 */
+    threshold?: number;
+    /** Analysis interval in ms. Default: 50 */
+    analyseIntervalMs?: number;
+    /** Consecutive frames above threshold to trigger speech start. Default: 3 (~150ms) */
+    speechStartFrames?: number;
+    /** Consecutive frames below threshold to trigger speech pause (visual only). Default: 8 (~400ms) */
+    speechPauseFrames?: number;
+    /** Consecutive frames below threshold to trigger turn end (queue drains). Default: 16 (~800ms) */
+    turnEndFrames?: number;
+    /** FFT size for the analyser node. Default: 256 */
+    fftSize?: number;
+}
+export interface VADEvents {
+    /** Speech started (above threshold for speechStartFrames). */
+    speechStart: () => void;
+    /** Speech paused (below threshold for speechPauseFrames, but turn still active). */
+    speechPause: () => void;
+    /** Speech resumed after a pause within the same turn. */
+    speechResume: () => void;
+    /** Turn ended (below threshold for turnEndFrames). */
+    turnEnd: () => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;AAExD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,UAAU,CAAC;CAClB;AAID,MAAM,MAAM,aAAa,GACrB,MAAM,GACN,SAAS,GACT,OAAO,GACP,OAAO,CAAC;AAIZ,MAAM,WAAW,cAAc;IAC7B,0CAA0C;IAC1C,OAAO,EAAE,GAAG,CAAC;IACb,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAID,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,4CAA4C;IAC5C,YAAY,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5D,+CAA+C;IAC/C,gBAAgB,EAAE,MAAM,IAAI,CAAC;IAC7B,6CAA6C;IAC7C,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACpD,yBAAyB;IACzB,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAC9B,8BAA8B;IAC9B,YAAY,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;CAC9C;AAID,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,OAAO,GAAG,MAAM,CAAC;AAExD,MAAM,WAAW,iBAAiB;IAChC,4CAA4C;IAC5C,cAAc,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9D,4BAA4B;IAC5B,kBAAkB,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;IACjD,6BAA6B;IAC7B,WAAW,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IACvC,wCAAwC;IACxC,YAAY,EAAE,MAAM,IAAI,CAAC;CAC1B;AAID,MAAM,WAAW,SAAS;IACxB,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,sFAAsF;IACtF,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,oGAAoG;IACpG,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,kGAAkG;IAClG,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,SAAS;IACxB,8DAA8D;IAC9D,WAAW,EAAE,MAAM,IAAI,CAAC;IACxB,oFAAoF;IACpF,WAAW,EAAE,MAAM,IAAI,CAAC;IACxB,yDAAyD;IACzD,YAAY,EAAE,MAAM,IAAI,CAAC;IACzB,sDAAsD;IACtD,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB"}