@m4trix/core 0.9.0 → 0.11.0

package/dist/index.js

@@ -1,25 +1,8 @@
-import { useRef, useState, useCallback, useEffect } from 'react';
-import { io } from 'socket.io-client';
-import { css, LitElement, html } from 'lit';
-import { property, state, customElement } from 'lit/decorators.js';
-import { createRef, ref } from 'lit/directives/ref.js';
-import { createTimeline } from 'animejs';
 import { ToolMessage, AIMessage, HumanMessage } from '@langchain/core/messages';
-import { Brand, Schema, Effect, pipe, PubSub, Queue, Cause } from 'effect';
+import { Brand, Schema, Tracer, Layer, Effect, pipe, Exit, PubSub, Queue, Cause } from 'effect';
 export { Schema as S } from 'effect';
 import { randomUUID } from 'crypto';
 
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __decorateClass = (decorators, target, key, kind) => {
-  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
-  for (var i = decorators.length - 1, decorator; i >= 0; i--)
-    if (decorator = decorators[i])
-      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
-  if (kind && result)
-    __defProp(target, key, result);
-  return result;
-};
 var __accessCheck = (obj, member, msg) => {
   if (!member.has(obj))
     throw TypeError("Cannot " + msg);
@@ -39,1608 +22,6 @@ var __privateSet = (obj, member, value, setter) => {
   return value;
 };
 
-// src/utility/Logger.ts
-var _Logger = class _Logger {
-  constructor(namespace = "") {
-    this.namespace = namespace;
-  }
-  static enableGlobalLogging() {
-    _Logger.globalEnabled = true;
-  }
-  static disableGlobalLogging() {
-    _Logger.globalEnabled = false;
-  }
-  formatPrefix() {
-    return this.namespace ? `[${this.namespace}]` : "";
-  }
-  logIfEnabled(level, ...args) {
-    if (!_Logger.globalEnabled)
-      return;
-    const prefix = this.formatPrefix();
-    if (prefix) {
-      console[level](prefix, ...args);
-    } else {
-      console[level](...args);
-    }
-  }
-  log(...args) {
-    this.logIfEnabled("log", ...args);
-  }
-  debug(...args) {
-    this.logIfEnabled("debug", ...args);
-  }
-  info(...args) {
-    this.logIfEnabled("info", ...args);
-  }
-  warn(...args) {
-    this.logIfEnabled("warn", ...args);
-  }
-  error(...args) {
-    this.logIfEnabled("error", ...args);
-  }
-};
-_Logger.globalEnabled = false;
-var Logger = _Logger;
-
-// src/react/adapter/VoiceEndpointAdapter.ts
-var VoiceEndpointAdapter = class {
-  constructor(config) {
-    this.logger = new Logger("SuTr > EndpointAdapter");
-    this.config = config;
-  }
-};
-var BaseVoiceEndpointAdapter = class extends VoiceEndpointAdapter {
-  constructor(config) {
-    super(config);
-  }
-  /**
-   * Send a voice file to the API endpoint and return a Pump stream of audio chunks
-   */
-  async sendVoiceFile({
-    blob,
-    metadata
-  }) {
-    const formData = new FormData();
-    formData.append("audio", blob);
-    if (metadata) {
-      formData.append("metadata", JSON.stringify(metadata));
-    }
-    this.logger.debug("Sending voice file to", this.config.endpoint, formData);
-    const response = await fetch(
-      `${this.config.baseUrl || ""}${this.config.endpoint}`,
-      {
-        method: "POST",
-        headers: this.config.headers,
-        body: formData
-      }
-    );
-    if (!response.ok) {
-      throw new Error(`API error: ${response.status} ${await response.text()}`);
-    }
-    if (!response.body) {
-      throw new Error("No response body");
-    }
-    return response;
-  }
-};
-
-// src/react/utility/audio/InputAudioController.ts
-var InputAudioController = class {
-  constructor() {
-    this.logger = new Logger("@m4trix/core > InputAudioController");
-  }
-};
-
-// src/react/utility/audio/WebAudioInputAudioController.ts
-var DEFAULT_SLICING_INTERVAL = 3e3;
-var WebAudioInputAudioController = class extends InputAudioController {
-  constructor(audioConfig = {}) {
-    super();
-    this.audioConfig = audioConfig;
-    // ─── Recording state ─────────────────────────────────────────────────────
-    this.audioContextState = {
-      context: null,
-      source: null,
-      analyser: null
-    };
-    this.mediaRecorder = null;
-    this.recordedChunks = [];
-    this.recordingStream = null;
-  }
-  get audioContext() {
-    return this.audioContextState.context;
-  }
-  async createAudioContext() {
-    const context = new AudioContext({
-      sampleRate: this.audioConfig.sampleRate || 16e3,
-      latencyHint: "interactive"
-    });
-    const analyser = context.createAnalyser();
-    analyser.fftSize = 2048;
-    return { context, source: null, analyser };
-  }
-  async cleanupAudioContext() {
-    this.logger.debug("Cleaning up audio context");
-    const { source, context } = this.audioContextState;
-    if (source)
-      source.disconnect();
-    if (context)
-      await context.close();
-    this.audioContextState = { context: null, source: null, analyser: null };
-  }
-  async startRecording({
-    onRecordedChunk,
-    onError
-  } = {}) {
-    try {
-      this.logger.debug("Starting recording");
-      this.recordedChunks = [];
-      const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
-      this.recordingStream = stream;
-      if (!this.audioContextState.context) {
-        this.audioContextState = await this.createAudioContext();
-      }
-      this.mediaRecorder = new MediaRecorder(stream, {
-        mimeType: "audio/webm;codecs=opus"
-      });
-      this.mediaRecorder.ondataavailable = (e) => {
-        if (e.data.size > 0) {
-          this.recordedChunks.push(e.data);
-          onRecordedChunk?.(e.data);
-          this.logger.debug("Recorded chunk", e.data.size);
-        }
-      };
-      this.mediaRecorder.start(DEFAULT_SLICING_INTERVAL);
-      this.logger.debug("MediaRecorder started");
-    } catch (err) {
-      const error = err instanceof Error ? err : new Error("Failed to start recording");
-      this.logger.error(error);
-      onError?.(error);
-    }
-  }
-  async stopRecording({
-    onRecordingCompleted
-  } = {}) {
-    this.logger.debug("Stopping recording");
-    if (!this.mediaRecorder || this.mediaRecorder.state === "inactive")
-      return;
-    await new Promise((resolve) => {
-      this.mediaRecorder.onstop = async () => {
-        if (this.recordedChunks.length) {
-          const blob = new Blob(this.recordedChunks, { type: "audio/webm" });
-          onRecordingCompleted?.(blob);
-          this.logger.debug("Recording completed", blob.size);
-        }
-        this.recordingStream?.getTracks().forEach((t) => t.stop());
-        this.recordingStream = null;
-        await this.cleanupAudioContext();
-        resolve();
-      };
-      this.mediaRecorder.stop();
-    });
-  }
-  /**
-   * Cleans up all audio recording resources.
-   */
-  cleanup() {
-    this.cleanupAudioContext();
-    if (this.mediaRecorder && this.mediaRecorder.state !== "inactive") {
-      this.mediaRecorder.stop();
-    }
-    if (this.recordingStream) {
-      this.recordingStream.getTracks().forEach((t) => t.stop());
-      this.recordingStream = null;
-    }
-  }
-};
-
-// src/react/utility/audio/OutputAudioController.ts
-var OutputAudioController = class {
-  constructor(loggerName) {
-    this.logger = new Logger(loggerName);
-  }
-};
-
-// src/react/utility/audio/AudioElementOutputAudioController.ts
-var AudioElementOutputAudioController = class extends OutputAudioController {
-  constructor() {
-    super("@m4trix/core > WebApiOutputAudioController");
-    // ─── Playback state ──────────────────────────────────────────────────────
-    this.currentHtmlAudio = null;
-    this.currentAudioUrl = null;
-  }
-  // ─── One-shot playback ────────────────────────────────────────────────────
-  /**
-   * Play either a Blob or a URL string.
-   * Uses <audio> under the hood for maximum browser compatibility.
-   */
-  async playAudio({
-    source,
-    onComplete
-  }) {
-    if (this.currentHtmlAudio) {
-      this.currentHtmlAudio.pause();
-      this.currentHtmlAudio.src = "";
-      if (this.currentAudioUrl && source instanceof Blob) {
-        URL.revokeObjectURL(this.currentAudioUrl);
-      }
-    }
-    const audio = new Audio();
-    this.currentHtmlAudio = audio;
-    let url;
-    if (source instanceof Blob) {
-      url = URL.createObjectURL(source);
-      this.currentAudioUrl = url;
-      audio.onended = () => {
-        URL.revokeObjectURL(url);
-        onComplete?.();
-      };
-    } else {
-      url = source;
-    }
-    audio.src = url;
-    try {
-      await audio.play();
-    } catch (err) {
-      this.logger.error("Playback failed, user gesture may be required", err);
-    }
-  }
-  // ─── Streaming playback ──────────────────────────────────────────────────
-  /**
-   * Stream audio from a Response via MediaSource Extensions.
-   * @param params.response The fetch Response whose body is an audio stream
-   * @param params.mimeCodec MIME type+codec string, e.g. 'audio/mpeg'
-   * @param params.onComplete Optional callback once the stream ends
-   */
-  async playAudioStream({
-    response,
-    mimeCodec = "audio/mpeg",
-    onComplete
-  }) {
-    if (!response.ok || !response.body) {
-      throw new Error(`Invalid response (${response.status})`);
-    }
-    if (typeof MediaSource === "undefined" || !MediaSource.isTypeSupported(mimeCodec)) {
-      throw new Error(`Unsupported MIME type or codec: ${mimeCodec}`);
-    }
-    await this.stopPlayback();
-    const mediaSource = new MediaSource();
-    const url = URL.createObjectURL(mediaSource);
-    this.currentAudioUrl = url;
-    const audio = new Audio(url);
-    this.currentHtmlAudio = audio;
-    audio.autoplay = true;
-    audio.onended = () => {
-      URL.revokeObjectURL(url);
-      this.currentAudioUrl = null;
-      onComplete?.();
-    };
-    mediaSource.addEventListener(
-      "sourceopen",
-      () => {
-        const sourceBuffer = mediaSource.addSourceBuffer(mimeCodec);
-        const reader = response.body.getReader();
-        const pump = async () => {
-          const { done, value } = await reader.read();
-          if (done) {
-            mediaSource.endOfStream();
-            return;
-          }
-          if (value) {
-            sourceBuffer.appendBuffer(value);
-          }
-          if (sourceBuffer.updating) {
-            sourceBuffer.addEventListener("updateend", pump, { once: true });
-          } else {
-            pump();
-          }
-        };
-        pump();
-      },
-      { once: true }
-    );
-    try {
-      await audio.play();
-    } catch (err) {
-      this.logger.error(
-        "Streaming playback failed, user gesture may be required",
-        err
-      );
-    }
-  }
-  // ─── Chunk-based streaming playback ─────────────────────────────────────
-  /**
-   * Initialize a streaming audio context for chunk-based playback.
-   * This creates the necessary MediaSource and SourceBuffer for subsequent chunk additions.
-   * Returns functions to add chunks and end the stream, encapsulated in a closure.
-   *
-   * @param mimeCodec MIME type+codec string, e.g. 'audio/mpeg'
-   * @param onComplete Optional callback once the stream ends
-   * @returns Object containing functions to add chunks and end the stream
-   */
-  async initializeChunkStream({
-    onComplete,
-    mimeCodec = "audio/mpeg"
-  }) {
-    this.logger.debug(`Initializing chunk stream with codec: ${mimeCodec}`);
-    if (typeof MediaSource === "undefined") {
-      throw new Error("MediaSource API is not supported in this browser");
-    }
-    if (!MediaSource.isTypeSupported(mimeCodec)) {
-      this.logger.warn(
-        `Codec ${mimeCodec} not supported, falling back to standard audio/mpeg`
-      );
-      mimeCodec = "audio/mpeg";
-      if (!MediaSource.isTypeSupported(mimeCodec)) {
-        throw new Error(
-          "Neither the specified codec nor the fallback codec are supported"
-        );
-      }
-    }
-    await this.stopPlayback();
-    const mediaSource = new MediaSource();
-    let sourceBuffer = null;
-    const url = URL.createObjectURL(mediaSource);
-    this.currentAudioUrl = url;
-    const audio = new Audio(url);
-    this.currentHtmlAudio = audio;
-    audio.autoplay = false;
-    audio.controls = true;
-    audio.style.display = "none";
-    document.body.appendChild(audio);
-    let playbackStarted = false;
-    let hasReceivedFirstChunk = false;
-    let receivedChunksCount = 0;
-    const pendingChunks = [];
-    let isProcessingQueue = false;
-    this.logger.debug("Waiting for MediaSource to open...");
-    await new Promise((resolve, reject) => {
-      const timeout = setTimeout(() => {
-        reject(new Error("MediaSource failed to open (timeout)"));
-      }, 5e3);
-      mediaSource.addEventListener(
-        "sourceopen",
-        () => {
-          clearTimeout(timeout);
-          this.logger.debug("MediaSource open event received");
-          try {
-            sourceBuffer = mediaSource.addSourceBuffer(mimeCodec);
-            if (mediaSource.duration === Infinity || isNaN(mediaSource.duration)) {
-              mediaSource.duration = 1e3;
-            }
-            this.logger.debug("SourceBuffer created successfully");
-            resolve();
-          } catch (err) {
-            reject(new Error(`Failed to create SourceBuffer: ${err}`));
-          }
-        },
-        { once: true }
-      );
-    });
-    const logger = this.logger;
-    const processQueue = async () => {
-      if (!sourceBuffer || pendingChunks.length === 0 || isProcessingQueue) {
-        return;
-      }
-      isProcessingQueue = true;
-      try {
-        while (pendingChunks.length > 0) {
-          if (sourceBuffer.updating) {
-            await new Promise((resolve) => {
-              sourceBuffer.addEventListener("updateend", () => resolve(), {
-                once: true
-              });
-            });
-          }
-          const nextChunk = pendingChunks.shift();
-          if (!nextChunk)
-            continue;
-          try {
-            sourceBuffer.appendBuffer(nextChunk);
-            logger.debug(
-              `Processed queued chunk of size ${nextChunk.byteLength}`
-            );
-            if (!playbackStarted && hasReceivedFirstChunk) {
-              await tryStartPlayback();
-            }
-            await new Promise((resolve) => {
-              sourceBuffer.addEventListener("updateend", () => resolve(), {
-                once: true
-              });
-            });
-          } catch (err) {
-            logger.error("Error appending queued chunk to source buffer", err);
-          }
-        }
-      } finally {
-        isProcessingQueue = false;
-      }
-    };
-    const tryStartPlayback = async () => {
-      if (playbackStarted)
-        return;
-      playbackStarted = true;
-      logger.debug("Attempting to start audio playback...");
-      if (receivedChunksCount < 3 && audio.buffered.length > 0 && audio.buffered.end(0) < 0.5) {
-        logger.debug("Not enough data buffered yet, delaying playback");
-        return;
-      }
-      try {
-        if (audio.readyState === 0) {
-          logger.debug(
-            "Audio element not ready yet, waiting for canplay event"
-          );
-          await new Promise((resolve) => {
-            audio.addEventListener("canplay", () => resolve(), { once: true });
-          });
-        }
-        await audio.play();
-        logger.debug("Successfully started audio playback");
-      } catch (err) {
-        logger.error("Failed to start playback", err);
-        document.addEventListener(
-          "click",
-          async () => {
-            try {
-              await audio.play();
-              logger.debug("Started playback after user interaction");
-            } catch (innerErr) {
-              logger.error(
-                "Still failed to play after user interaction",
-                innerErr
-              );
-            }
-          },
-          { once: true }
-        );
-      }
-    };
-    const addChunkToStream = async (chunk) => {
-      if (!sourceBuffer) {
-        throw new Error(
-          "Streaming context was closed or not properly initialized."
-        );
-      }
-      let arrayBufferChunk;
-      if (chunk instanceof Blob) {
-        logger.debug("Converting Blob to ArrayBuffer");
-        arrayBufferChunk = await chunk.arrayBuffer();
-      } else {
-        arrayBufferChunk = chunk;
-      }
-      if (!arrayBufferChunk || arrayBufferChunk.byteLength === 0) {
-        logger.warn("Received empty chunk, skipping");
-        return;
-      }
-      if (!hasReceivedFirstChunk) {
-        hasReceivedFirstChunk = true;
-        logger.debug(
-          `First chunk received, size: ${arrayBufferChunk.byteLength} bytes`
-        );
-      }
-      receivedChunksCount++;
-      pendingChunks.push(arrayBufferChunk);
-      logger.debug(
-        `Added chunk #${receivedChunksCount} to queue (size: ${arrayBufferChunk.byteLength} bytes)`
-      );
-      await processQueue();
-      if (!playbackStarted && hasReceivedFirstChunk && receivedChunksCount >= 3) {
-        await tryStartPlayback();
-      }
-    };
-    const endChunkStream = () => {
-      if (mediaSource && mediaSource.readyState === "open") {
-        try {
-          if (pendingChunks.length > 0 || sourceBuffer && sourceBuffer.updating) {
-            logger.debug("Waiting for pending chunks before ending stream");
-            setTimeout(() => endChunkStream(), 200);
-            return;
-          }
-          if (hasReceivedFirstChunk) {
-            mediaSource.endOfStream();
-            logger.debug("MediaSource stream ended successfully");
-          } else {
-            logger.warn("Stream ended without receiving any chunks");
-          }
-        } catch (err) {
-          logger.error("Error ending MediaSource stream", err);
-        }
-      }
-      audio.onended = null;
-      if (audio.parentNode) {
-        audio.parentNode.removeChild(audio);
-      }
-      if (this.currentAudioUrl === url) {
-        this.currentAudioUrl = null;
-        URL.revokeObjectURL(url);
-      }
-      sourceBuffer = null;
-    };
-    audio.onended = () => {
-      logger.debug("Audio playback completed");
-      endChunkStream();
-      onComplete?.();
-    };
-    return {
-      addChunkToStream,
-      endChunkStream
-    };
-  }
-  /**
-   * Stop any ongoing HTMLAudioElement playback.
-   */
-  async stopPlayback() {
-    if (this.currentHtmlAudio) {
-      try {
-        this.currentHtmlAudio.pause();
-        this.currentHtmlAudio.src = "";
-      } catch (err) {
-        this.logger.error("Error stopping playback", err);
-      }
-      this.currentHtmlAudio = null;
-    }
-    if (this.currentAudioUrl) {
-      URL.revokeObjectURL(this.currentAudioUrl);
-      this.currentAudioUrl = null;
-    }
-  }
-  /**
-   * Cleans up all audio playback resources.
-   */
-  cleanup() {
-    this.stopPlayback();
-  }
-};
-
-// src/react/hooks/use-conversation/useConversation.ts
-Logger.enableGlobalLogging();
-function useConversation(endpoint, {
-  onStartRecording,
-  onStopRecording,
-  onReceive,
-  autoPlay = true,
-  downstreamMode = "STREAM",
-  onError,
-  audioConfig = {},
-  requestData = {},
-  endpointConfig = {}
-}) {
-  const { current: logger } = useRef(
-    new Logger("@m4trix/core > useConversation")
-  );
-  const inputAudioControllerRef = useRef(void 0);
-  const outputAudioControllerRef = useRef(
-    void 0
-  );
-  const endpointAdapterRef = useRef(
-    void 0
-  );
-  const [voiceAgentState, setVoiceAgentState] = useState("READY");
-  const [error, setError] = useState(null);
-  const handleError = useCallback(
-    (state2, err) => {
-      setError(err);
-      logger.error(`Error during ${state2}:`, err);
-      onError?.(state2, err);
-    },
-    [onError]
-  );
-  const startRecording = useCallback(() => {
-    if (inputAudioControllerRef.current) {
-      try {
-        logger.debug("Starting recording");
-        setVoiceAgentState("RECORDING");
-        inputAudioControllerRef.current.startRecording({
-          onError: (err) => {
-            handleError("RECORDING", err);
-          }
-        });
-        onStartRecording?.();
-      } catch (err) {
-        if (err instanceof Error) {
-          handleError("RECORDING", err);
-        }
-      }
-    }
-  }, [onStartRecording, handleError]);
-  const stopRecording = useCallback(async () => {
-    if (inputAudioControllerRef.current) {
-      try {
-        logger.debug("Stopping recording");
-        await inputAudioControllerRef.current.stopRecording({
-          onRecordingCompleted: async (allData) => {
-            setVoiceAgentState("PROCESSING");
-            try {
-              const response = await endpointAdapterRef.current?.sendVoiceFile({
-                blob: allData,
-                metadata: requestData
-              });
-              if (!response) {
-                throw new Error("No response received from endpoint");
-              }
-              setVoiceAgentState("RESPONDING");
-              if (autoPlay) {
-                if (downstreamMode === "STREAM") {
-                  await outputAudioControllerRef.current?.playAudioStream({
-                    response,
-                    onComplete: () => {
-                      setVoiceAgentState("READY");
-                    }
-                  });
-                } else if (downstreamMode === "DOWNLOAD") {
-                  const responseBlob = await response.blob();
-                  await outputAudioControllerRef.current?.playAudio({
-                    source: responseBlob,
-                    onComplete: () => {
-                      setVoiceAgentState("READY");
-                    }
-                  });
-                }
-              } else {
-                setVoiceAgentState("READY");
-              }
-              onReceive?.(
-                allData,
-                async () => {
-                  if (outputAudioControllerRef.current) {
-                    if (downstreamMode === "STREAM") {
-                      return outputAudioControllerRef.current.playAudioStream({
-                        response,
-                        onComplete: () => {
-                          setVoiceAgentState("READY");
-                        }
-                      });
-                    } else {
-                      const responseBlob = await response.blob();
-                      return outputAudioControllerRef.current.playAudio({
-                        source: responseBlob,
-                        onComplete: () => {
-                          setVoiceAgentState("READY");
-                        }
-                      });
-                    }
-                  }
-                },
-                async () => {
-                  if (outputAudioControllerRef.current) {
-                    return outputAudioControllerRef.current.stopPlayback();
-                  }
-                }
-              );
-            } catch (err) {
-              if (err instanceof Error) {
-                handleError("PROCESSING", err);
-              }
-              setVoiceAgentState("READY");
-            }
-          }
-        });
-        onStopRecording?.();
-      } catch (err) {
-        if (err instanceof Error) {
-          handleError("RECORDING", err);
-        }
-      }
-    }
-  }, [
-    onStopRecording,
-    requestData,
-    autoPlay,
-    downstreamMode,
-    handleError,
-    onReceive
-  ]);
-  useEffect(() => {
-    if (endpointAdapterRef.current) {
-      return;
-    }
-    try {
-      const endpointAdapter = endpointConfig.endpointAdapter ? endpointConfig.endpointAdapter : new BaseVoiceEndpointAdapter({
-        baseUrl: endpointConfig.baseUrl,
-        endpoint,
-        headers: endpointConfig.headers
-      });
-      endpointAdapterRef.current = endpointAdapter;
-      if (!inputAudioControllerRef.current) {
-        inputAudioControllerRef.current = new WebAudioInputAudioController(
-          audioConfig
-        );
-      }
-      if (!outputAudioControllerRef.current) {
-        outputAudioControllerRef.current = new AudioElementOutputAudioController();
-      }
-    } catch (err) {
-      if (err instanceof Error) {
-        handleError("READY", err);
-      }
-    }
-  }, [endpoint, endpointConfig, audioConfig, handleError]);
-  useEffect(() => {
-    return () => {
-      inputAudioControllerRef.current?.cleanup();
-      outputAudioControllerRef.current?.cleanup();
-    };
-  }, []);
-  return {
-    startRecording,
-    stopRecording,
-    voiceAgentState,
-    error,
-    audioContext: inputAudioControllerRef.current?.audioContext || null
-  };
-}
-
-// src/react/adapter/socket/VoiceSocketAdapter.ts
-var VoiceSocketAdapter = class {
-  constructor(config) {
-    this._isConnected = false;
-    this.logger = new Logger("@m4trix/core > VoiceSocketAdapter");
-    this.emitter = new Emitter();
-    this.config = config;
-  }
-  on(event, listener) {
-    this.emitter.on(event, listener);
-  }
-  off(event, listener) {
-    this.emitter.off(event, listener);
-  }
-  once(event, listener) {
-    this.emitter.once(event, listener);
-  }
-  emit(event, data) {
-    this.emitter.emit(event, data);
-  }
-  isConnected() {
-    return this._isConnected;
-  }
-};
-var Emitter = class {
-  constructor() {
-    this.target = new EventTarget();
-  }
-  on(type, listener) {
-    this.target.addEventListener(type, listener);
-  }
-  off(type, listener) {
-    this.target.removeEventListener(type, listener);
-  }
-  once(type, listener) {
-    const wrapper = (event) => {
-      this.off(type, wrapper);
-      listener(event.detail);
-    };
-    this.on(type, wrapper);
-  }
-  emit(type, detail) {
-    this.target.dispatchEvent(new CustomEvent(type, { detail }));
-  }
-};
-var VoiceSocketIOAdapter = class extends VoiceSocketAdapter {
-  constructor(config) {
-    super(config);
-    this.socket = null;
-  }
-  async connect() {
-    return new Promise((resolve, reject) => {
-      if (!this.socket) {
-        this.socket = io(this.config.baseUrl, {
-          extraHeaders: this.config.headers,
-          autoConnect: true
-        });
-      }
-      this.socket.on("connect", () => {
-        this._isConnected = true;
-        this.logger.debug("Connected to socket");
-        this.emit("connect");
-        resolve();
-      });
-      this.socket.on("disconnect", () => {
-        this._isConnected = false;
-        this.emit("disconnect");
-        this.logger.debug("Disconnected from socket");
-        if (this.config.autoReconnect)
-          this.connect();
-      });
-      this.socket.on("connect_error", (error) => {
-        this.logger.error("Error connecting to socket", error);
-        this.emit("error", error);
-        reject(error);
-      });
-      this.socket.on("voice:chunk_received", (chunk) => {
-        this.logger.debug("Received voice chunk", chunk.byteLength);
-        this.onVoiceChunkReceived(chunk);
-      });
-      this.socket.on("voice:received_end_of_response_stream", () => {
-        this.logger.debug("Received end of response stream");
-        this.onReceivedEndOfResponseStream();
-      });
-      this.socket.on("voice:file_received", (blob) => {
-        this.logger.debug("Received voice file");
-        this.onVoiceFileReceived(blob);
-      });
-      this.socket.on("control-message", (message) => {
-        this.logger.debug("Received control message", message);
-        this.emit("control-message", message);
-      });
-    });
-  }
-  disconnect() {
-    this.socket?.disconnect();
-    this.socket = null;
-    this._isConnected = false;
-  }
-  exposeSocket() {
-    return this.socket;
-  }
-  async sendVoiceChunk(chunk, metadata) {
-    this.logger.debug(
-      "Sending voice chunk %i",
-      chunk instanceof Blob ? chunk.size : chunk.byteLength
-    );
-    if (!this.socket || !this.isConnected)
-      throw new Error("Socket not connected");
-    let chunkToSend;
-    if (chunk instanceof Blob) {
-      chunkToSend = await chunk.arrayBuffer();
-    } else {
-      chunkToSend = chunk;
-    }
-    this.logger.debug("[Socket] Sending voice chunk", chunkToSend.byteLength);
-    this.socket.emit("voice:send_chunk", chunkToSend, metadata);
-    this.emit("chunk_sent", chunk);
-  }
-  sendVoiceFile(blob, metadata) {
-    this.logger.debug("Sending voice file", blob, metadata);
-    if (!this.socket || !this.isConnected)
-      throw new Error("Socket not connected");
-    this.socket.emit("voice:send_file", blob, metadata);
-    this.emit("file-sent", blob);
-  }
-  commitVoiceMessage() {
-    if (!this.socket || !this.isConnected)
-      throw new Error("Socket not connected");
-    this.socket.emit("voice:commit");
-  }
-  onVoiceChunkReceived(chunk) {
-    this.emit("chunk-received", chunk);
-  }
-  onVoiceFileReceived(blob) {
-    this.emit("file-received", blob);
-  }
-  onReceivedEndOfResponseStream() {
-    this.emit("received-end-of-response-stream");
-  }
-};
-
-// src/react/utility/audio/WebAudioOutputAudioController.ts
-var STREAM_SAMPLE_RATE = 24e3;
-var CHANNELS = 1;
-var SLICE_DURATION_S = 0.25;
-var FRAMES_PER_SLICE = Math.floor(STREAM_SAMPLE_RATE * SLICE_DURATION_S);
-var BYTES_PER_SLICE = FRAMES_PER_SLICE * 2;
-var SCHED_TOLERANCE = 0.05;
-var WebAudioOutputAudioController = class extends OutputAudioController {
-  constructor() {
-    super("@m4trix/core > WebAudioOutputAudioController");
-    this.audioCtx = new AudioContext();
-    this.gain = this.audioCtx.createGain();
-    this.nextPlayTime = 0;
-    this.activeSources = /* @__PURE__ */ new Set();
-    this.userGestureHookAttached = false;
-    this.gain.connect(this.audioCtx.destination);
-    this.resetScheduler();
-  }
-  // ─────────────────────────────────────────────────────────────────────
-  // One‑shot playback
-  // ─────────────────────────────────────────────────────────────────────
-  async playAudio({
-    source,
-    onComplete
-  }) {
-    await this.stopPlayback();
-    const buf = await this.sourceToArrayBuffer(source);
-    const decoded = await this.decode(buf);
-    await this.ensureContextRunning();
-    const src = this.createSource(decoded, this.audioCtx.currentTime);
-    src.onended = () => {
-      this.activeSources.delete(src);
-      onComplete?.();
-    };
-  }
-  async playAudioStream() {
-  }
-  // ─────────────────────────────────────────────────────────────────────
-  // PCM streaming
-  // ─────────────────────────────────────────────────────────────────────
-  async initializeChunkStream({
-    onComplete
-  }) {
-    await this.stopPlayback();
-    await this.ensureContextRunning();
-    this.resetScheduler();
-    let streamEnded = false;
-    let pending = new Uint8Array(0);
-    const addChunkToStream = async (pkt) => {
-      if (streamEnded) {
-        this.logger.warn("Attempt to add chunk after stream ended \u2013 ignoring.");
-        return;
-      }
-      const bytes = new Uint8Array(
-        pkt instanceof Blob ? await pkt.arrayBuffer() : pkt
-      );
-      if (bytes.length === 0)
-        return;
-      const merged = new Uint8Array(pending.length + bytes.length);
-      merged.set(pending);
-      merged.set(bytes, pending.length);
-      pending = merged;
-      if (pending.length % 2 === 1)
-        return;
-      while (pending.length >= BYTES_PER_SLICE) {
-        const sliceBytes = pending.slice(0, BYTES_PER_SLICE);
-        pending = pending.slice(BYTES_PER_SLICE);
-        const aligned = sliceBytes.buffer.slice(
-          sliceBytes.byteOffset,
-          sliceBytes.byteOffset + sliceBytes.byteLength
-        );
-        const int16 = new Int16Array(aligned);
-        const buf = this.audioCtx.createBuffer(
-          CHANNELS,
-          int16.length,
-          STREAM_SAMPLE_RATE
-        );
-        const data = buf.getChannelData(0);
-        for (let i = 0; i < int16.length; i++)
-          data[i] = int16[i] / 32768;
-        this.scheduleBuffer(buf);
-      }
-    };
-    const endChunkStream = () => {
-      if (streamEnded)
-        return;
-      streamEnded = true;
-      if (onComplete) {
-        if (this.activeSources.size === 0)
-          onComplete();
-        else {
-          const last = Array.from(this.activeSources).pop();
-          if (last) {
-            const prev = last.onended;
-            last.onended = (e) => {
-              if (prev)
-                prev.call(last, e);
-              onComplete();
-            };
-          }
-        }
-      }
-    };
-    return { addChunkToStream, endChunkStream };
-  }
-  // ─────────────────────────────────────────────────────────────────────
-  // Buffer scheduling helpers
-  // ─────────────────────────────────────────────────────────────────────
-  scheduleBuffer(buf) {
-    if (this.nextPlayTime < this.audioCtx.currentTime + SCHED_TOLERANCE) {
-      this.nextPlayTime = this.audioCtx.currentTime + SCHED_TOLERANCE;
-    }
-    this.createSource(buf, this.nextPlayTime);
-    this.nextPlayTime += buf.duration;
-  }
-  createSource(buf, when) {
-    const src = this.audioCtx.createBufferSource();
-    src.buffer = buf;
-    src.connect(this.gain);
-    src.start(when);
-    this.activeSources.add(src);
-    src.onended = () => {
-      this.activeSources.delete(src);
-    };
-    return src;
-  }
-  resetScheduler() {
-    this.nextPlayTime = this.audioCtx.currentTime;
-  }
-  // ─── External resource helpers ───────────────────────────────────────
-  sourceToArrayBuffer(src) {
-    return typeof src === "string" ? fetch(src).then((r) => {
-      if (!r.ok)
-        throw new Error(`${r.status}`);
-      return r.arrayBuffer();
-    }) : src.arrayBuffer();
-  }
-  decode(buf) {
-    return new Promise(
-      (res, rej) => this.audioCtx.decodeAudioData(buf, res, rej)
-    );
-  }
-  // ─── Lifecycle methods ───────────────────────────────────────────────
-  async stopPlayback() {
-    for (const src of this.activeSources) {
-      try {
-        src.stop();
-      } catch {
-      }
-      src.disconnect();
-    }
-    this.activeSources.clear();
-    this.resetScheduler();
-  }
-  cleanup() {
-    this.stopPlayback();
-    if (this.audioCtx.state !== "closed")
-      this.audioCtx.close();
-  }
-  // ─── Autoplay‑policy helper ──────────────────────────────────────────
-  async ensureContextRunning() {
-    if (this.audioCtx.state !== "suspended")
-      return;
-    try {
-      await this.audioCtx.resume();
-    } catch {
-    }
-    if (this.audioCtx.state === "running")
-      return;
-    if (!this.userGestureHookAttached) {
-      this.userGestureHookAttached = true;
-      const resume = async () => {
-        try {
-          await this.audioCtx.resume();
-        } catch {
-        }
-        if (this.audioCtx.state === "running")
-          document.removeEventListener("click", resume);
-      };
-      document.addEventListener("click", resume);
-    }
-  }
-};
-
-// src/react/hooks/use-conversation/useSocketConversation.ts
-Logger.enableGlobalLogging();
-function useSocketConversation({
-  scope,
-  onStartRecording,
-  onStopRecording,
-  onReceive,
-  upstreamMode = "STREAM_WHILE_TALK",
-  onError,
-  audioConfig = {},
-  socketConfig = {}
-}) {
-  const { current: logger } = useRef(
-    new Logger("SuTr > useSocketConversation")
-  );
-  const inputAudioControllerRef = useRef(void 0);
-  const outputAudioControllerRef = useRef(
-    void 0
-  );
-  const socketAdapterRef = useRef(void 0);
-  const [socket, setSocket] = useState(null);
-  const [voiceAgentState, setVoiceAgentState] = useState("READY");
-  const [error, setError] = useState(null);
-  const shouldStreamWhileTalk = upstreamMode === "STREAM_WHILE_TALK";
-  const handleError = useCallback(
-    (state2, err) => {
-      setError(err);
-      logger.error(`Error during ${state2}:`, err);
-      onError?.(state2, err);
-    },
-    [onError]
-  );
-  const subscribeToSocketEventsForChunkDownstreaming = useCallback(
-    async (socketAdapter) => {
-      logger.debug("Setting up audio stream for receiving chunks");
-      try {
-        const { addChunkToStream, endChunkStream } = await outputAudioControllerRef.current.initializeChunkStream({
-          mimeCodec: "audio/mpeg",
-          onComplete: () => {
-            logger.debug("Audio stream playback completed");
-            setVoiceAgentState("READY");
-          }
-        });
-        let chunkCount = 0;
-        const chunkReceivedEmitter = async (chunk) => {
-          if (chunk instanceof ArrayBuffer) {
-            chunkCount++;
-            logger.debug(
-              `Received voice chunk #${chunkCount} from socket, size: ${chunk.byteLength} bytes`
-            );
-            if (!chunk || chunk.byteLength === 0) {
-              logger.warn("Received empty chunk, skipping");
-              return;
-            }
-            try {
-              await addChunkToStream(chunk);
-              logger.debug(
-                `Successfully added chunk #${chunkCount} to audio stream`
-              );
-            } catch (err) {
-              logger.error(
-                `Failed to add chunk #${chunkCount} to audio stream`,
-                err
-              );
-              if (err instanceof Error) {
-                handleError("DOWNSTREAMING", err);
-              }
-            }
-          }
-        };
-        socketAdapter.on("chunk-received", chunkReceivedEmitter);
-        const endOfStreamEmitter = () => {
-          logger.debug(
-            `Received end of stream signal after ${chunkCount} chunks, ending chunk stream`
-          );
-          endChunkStream();
-          setVoiceAgentState("READY");
-        };
-        socketAdapter.on("received-end-of-response-stream", endOfStreamEmitter);
-        return () => {
-          logger.debug("Cleaning up socket event listeners");
-          socketAdapter.off("chunk-received", chunkReceivedEmitter);
-          socketAdapter.off(
-            "received-end-of-response-stream",
-            endOfStreamEmitter
-          );
-          endChunkStream();
-        };
-      } catch (err) {
-        if (err instanceof Error) {
-          handleError("DOWNSTREAMING", err);
-        }
-        return () => {
-        };
-      }
-    },
-    [handleError]
-  );
-  const hookupSocketAdapter = useCallback(
-    async (socketAdapter) => {
-      logger.debug("Connecting to socket...");
-      try {
-        await socketAdapter.connect();
-        socketAdapter.on("connect", () => {
-          logger.debug("Socket adapter connected");
-          setVoiceAgentState("READY");
-        });
-        socketAdapter.on("disconnect", () => {
-          logger.debug("Socket adapter disconnected");
-        });
-        socketAdapter.on("error", (err) => {
-          if (err instanceof Error) {
-            handleError(voiceAgentState, err);
-          } else {
-            handleError(voiceAgentState, new Error("Unknown error"));
-          }
-        });
-        setSocket(socketAdapter.exposeSocket());
-      } catch (err) {
-        if (err instanceof Error) {
-          handleError("READY", err);
-        }
-      }
-    },
-    [handleError, voiceAgentState]
-  );
-  const startRecording = useCallback(() => {
-    if (inputAudioControllerRef.current) {
-      try {
-        logger.debug("Starting recording");
-        setVoiceAgentState("RECORDING");
-        inputAudioControllerRef.current.startRecording({
-          onRecordedChunk: async (chunk) => {
-            if (shouldStreamWhileTalk) {
-              try {
-                await socketAdapterRef.current?.sendVoiceChunk(chunk);
-              } catch (err) {
-                if (err instanceof Error) {
-                  handleError("RECORDING", err);
-                }
-              }
-            }
-          }
-        });
-        onStartRecording?.();
-      } catch (err) {
-        if (err instanceof Error) {
-          handleError("RECORDING", err);
-        }
-      }
-    }
-  }, [onStartRecording, shouldStreamWhileTalk, handleError]);
-  const stopRecording = useCallback(async () => {
-    if (inputAudioControllerRef.current) {
-      try {
-        logger.debug("Stopping recording");
-        await inputAudioControllerRef.current.stopRecording({
-          onRecordingCompleted: async (allData) => {
-            setVoiceAgentState("PROCESSING");
-            try {
-              if (shouldStreamWhileTalk) {
-                logger.debug("Committing voice message");
-                await socketAdapterRef.current?.commitVoiceMessage();
-              } else {
-                await socketAdapterRef.current?.sendVoiceFile(allData);
-              }
-              setVoiceAgentState("DOWNSTREAMING");
-              await subscribeToSocketEventsForChunkDownstreaming(
-                socketAdapterRef.current
-              );
-              onReceive?.(
-                allData,
-                async () => {
-                  if (outputAudioControllerRef.current) {
-                    return outputAudioControllerRef.current.stopPlayback();
-                  }
-                },
-                async () => {
-                  if (outputAudioControllerRef.current) {
-                    return outputAudioControllerRef.current.stopPlayback();
-                  }
-                }
-              );
-            } catch (err) {
-              if (err instanceof Error) {
-                handleError("PROCESSING", err);
-              }
-            }
-          }
-        });
-        onStopRecording?.();
-      } catch (err) {
-        if (err instanceof Error) {
-          handleError("RECORDING", err);
-        }
-      }
-    }
-  }, [
-    onStopRecording,
-    handleError,
-    subscribeToSocketEventsForChunkDownstreaming,
-    onReceive
-  ]);
-  useEffect(() => {
-    if (socketAdapterRef.current) {
-      return;
-    }
-    try {
-      const socketAdapter = socketConfig.socketAdapter ? socketConfig.socketAdapter : new VoiceSocketIOAdapter({
-        scope,
-        baseUrl: socketConfig.baseUrl || "",
-        headers: socketConfig.headers
-      });
-      socketAdapterRef.current = socketAdapter;
-      if (!socketAdapter.isConnected()) {
-        hookupSocketAdapter(socketAdapter);
-      }
-      if (!inputAudioControllerRef.current) {
-        inputAudioControllerRef.current = new WebAudioInputAudioController(
-          audioConfig
-        );
-      }
-      if (!outputAudioControllerRef.current) {
-        outputAudioControllerRef.current = new WebAudioOutputAudioController();
-      }
-    } catch (err) {
-      if (err instanceof Error) {
-        handleError("READY", err);
-      }
-    }
-  }, [scope, socketConfig, hookupSocketAdapter, audioConfig, handleError]);
-  useEffect(() => {
-    return () => {
-      inputAudioControllerRef.current?.cleanup();
-      outputAudioControllerRef.current?.cleanup();
-      if (socketAdapterRef.current) {
-        socketAdapterRef.current.disconnect();
-        socketAdapterRef.current = void 0;
-      }
-    };
-  }, []);
-  return {
-    startRecording,
-    stopRecording,
-    voiceAgentState,
-    error,
-    audioContext: inputAudioControllerRef.current?.audioContext || null,
-    socket
-  };
-}
-var AiCursorComponentStyle = css`
-  :host {
-    --ai-local-cursor-size: var(--sk-ai-cursor-size, 1rem);
-    --ai-local-cursor-label-padding: var(
-      --sk-ai-cursor-label-padding,
-      0.25rem 0.25rem
-    );
-    --ai-local-cursor-border-radius: var(--sk-ai-cursor-border-radius, 0.25rem);
-    --ai-local-label-offset: var(--sk-ai-cursor-label-offset, 1rem);
-
-    --ai-local-label-font-size: var(--sk-ai-cursor-label-font-size, 12px);
-    --ai-local-label-font-weight: var(--sk-ai-cursor-label-font-weight, bold);
-    --ai-local-label-color: var(--sk-ai-cursor-label-color, white);
-    --ai-local-label-background-color: var(
-      --sk-ai-cursor-label-background-color,
-      black
-    );
-    --ai-local-label-border-color: var(
-      --sk-ai-cursor-label-border-color,
-      white
-    );
-    --ai-local-label-border-width: var(
-      --sk-ai-cursor-label-border-width,
-      0.1rem
-    );
-
-    color: black;
-    stroke: white;
-    position: absolute;
-    /* Insetting in the parent element (body) */
-    top: 0;
-    left: 0;
-    bottom: 0;
-    right: 0;
-    pointer-events: none;
-    width: var(--ai-local-cursor-size);
-    height: var(--ai-local-cursor-size);
-  }
-
-  #cursor-graphic-parent {
-    position: absolute;
-    top: 0;
-    left: 0;
-  }
-
-  #label-text {
-    position: absolute;
-    color: white;
-    font-size: 12px;
-    font-weight: bold;
-    padding: var(--ai-local-cursor-label-padding);
-    border-radius: var(--ai-local-cursor-border-radius);
-
-    white-space: nowrap;
-    overflow: hidden;
-    text-overflow: ellipsis;
-
-    width: fit-content;
-    min-width: fit-content;
-    top: var(--ai-local-label-offset);
-    left: var(--ai-local-label-offset);
-
-    border: var(--ai-local-label-border-width) solid
-      var(--ai-local-label-border-color);
-    background-color: var(--ai-local-label-background-color);
-    color: var(--ai-local-label-color);
-    font-size: var(--ai-local-label-font-size);
-    font-weight: var(--ai-local-label-font-weight);
-  }
-`;
-
-// src/ui/ai-cursor/rendering/AiCursorComponent.ts
-var AiCursorComponent = class extends LitElement {
-  constructor() {
-    super();
-    this.eventHooks = {
-      defineSetPosition: () => {
-      },
-      defineAddPositionToQueue: () => {
-      },
-      definePlayQueue: () => {
-      },
-      defineSetShowCursor: () => {
-      }
-    };
-    this.isShowingCursor = true;
-    this.labelText = "AI Cursor";
-    this.cursorPosition = [0, 0];
-    this._cursorRef = createRef();
-    this._labelRef = createRef();
-  }
-  updated(_changedProperties) {
-    if (_changedProperties.has("_cursorRef")) {
-      if (this._cursorRef.value) {
-        this.hookUpCallbacks();
-      } else {
-        this._timeline?.pause();
-        this._timeline?.refresh();
-      }
-    }
-    super.updated(_changedProperties);
-  }
-  render() {
-    const cursorSvg = html`
-      <svg
-        width=${24}
-        height=${24}
-        viewBox="0 0 100 100"
-        fill="none"
-        xmlns="http://www.w3.org/2000/svg"
-      >
-        <g clip-path="url(#clip0_3576_285)">
-          <path
-            class="cursor-path"
-            d="M2.14849 7.04749C1.35153 4.07321 4.07319 1.35155 7.04747 2.14851L77.3148 20.9766C80.2891 21.7735 81.2853 25.4914 79.108 27.6687L27.6687 79.108C25.4914 81.2853 21.7735 80.2891 20.9766 77.3149L2.14849 7.04749Z"
-            fill="currentColor"
-          />
-        </g>
-        <defs>
-          <clipPath id="clip0_3576_285">
-            <rect width="100" height="100" fill="white" />
-          </clipPath>
-        </defs>
-      </svg>
-    `;
-    return html`
-      <span
-        id="cursor-graphic-parent"
-        ${ref(this._cursorRef)}
-        ?hidden=${!this.isShowingCursor}
-      >
-        ${cursorSvg}
-        <span
-          ${ref(this._labelRef)}
-          id="label-text"
-          ?hidden=${!this.isShowingCursor}
-          >${this.labelText}</span
-        >
-      </span>
-    `;
-  }
-  // private methods
-  /**
-   * The primary way to control the cursor is using an external API.
-   * This interface exposes controlling methods. The Lit Component itself is
-   * intended to be a controlled component.
-   */
-  hookUpCallbacks() {
-    const animationTarget = this._cursorRef.value;
-    if (!animationTarget) {
-      return;
-    }
-    this._timeline = createTimeline({ defaults: { duration: 750 } });
-    if (!this._timeline) {
-      return;
-    }
-    this.eventHooks.defineSetPosition((position) => {
-      this._timeline?.add(animationTarget, {
-        translateX: position[0],
-        translateY: position[1],
-        duration: 1
-      });
-      this._timeline?.play();
-    });
-    this.eventHooks.defineAddPositionToQueue((position) => {
-      this._timeline?.add(animationTarget, {
-        translateX: position[0],
-        translateY: position[1],
-        duration: 1e3
-      });
-    });
-    this.eventHooks.defineSetShowCursor((show) => {
-      this.isShowingCursor = show;
-    });
-    this.eventHooks.definePlayQueue(() => {
-      this._timeline?.play();
-    });
-  }
-  // Getters
-  get cursorRef() {
-    return this._cursorRef.value;
-  }
-  get labelRef() {
-    return this._labelRef.value;
-  }
-};
-// Define scoped styles right with your component, in plain CSS
-AiCursorComponent.styles = AiCursorComponentStyle;
-__decorateClass([
-  property({
-    type: Object
-  })
-], AiCursorComponent.prototype, "eventHooks", 2);
-__decorateClass([
-  property({ type: Boolean })
-], AiCursorComponent.prototype, "isShowingCursor", 2);
-__decorateClass([
-  property({ type: String })
-], AiCursorComponent.prototype, "labelText", 2);
-__decorateClass([
-  property({ type: Array })
-], AiCursorComponent.prototype, "cursorPosition", 2);
-__decorateClass([
-  state()
-], AiCursorComponent.prototype, "_cursorRef", 2);
-__decorateClass([
-  state()
-], AiCursorComponent.prototype, "_labelRef", 2);
-AiCursorComponent = __decorateClass([
-  customElement("ai-cursor")
-], AiCursorComponent);
-
-// src/ui/ai-cursor/rendering/index.ts
-var mountAiCursor = (aiCursorProps) => {
-  const root = document.body;
-  const cursor = document.createElement("ai-cursor");
-  cursor.eventHooks = aiCursorProps.eventHooks;
-  root.appendChild(cursor);
-};
-
-// src/ui/ai-cursor/AiCursor.ts
-var AiCursor = class _AiCursor {
-  constructor() {
-  }
-  // Static constructors
-  static spawn() {
-    const newCursor = new _AiCursor();
-    newCursor.mount();
-    return newCursor;
-  }
-  jumpTo(target) {
-    const position = targetToPosition(target);
-    if (position) {
-      this.setPosition?.(position);
-    }
-  }
-  moveTo(target) {
-    const position = targetToPosition(target);
-    if (position) {
-      this.addPositionToQueue?.(position);
-      this.playQueue?.();
-    }
-  }
-  scheduleMoves(targets) {
-    targets.forEach((target) => {
-      const position = targetToPosition(target);
-      if (position) {
-        this.addPositionToQueue?.(position);
-      }
-    });
-    this.playQueue?.();
-  }
-  show() {
-    this.setShowCursor?.(true);
-  }
-  hide() {
-    this.setShowCursor?.(false);
-  }
-  mount() {
-    mountAiCursor({
-      eventHooks: {
-        defineSetPosition: (callback) => {
-          this.setPosition = callback;
-        },
-        defineAddPositionToQueue: (callback) => {
-          this.addPositionToQueue = callback;
-        },
-        definePlayQueue: (callback) => {
-          this.playQueue = callback;
-        },
-        defineSetShowCursor: (callback) => {
-          this.setShowCursor = callback;
-        }
-      }
-    });
-  }
-};
-function calculateClickPositionFromElement(element) {
-  const rect = element.getBoundingClientRect();
-  return [rect.left + rect.width / 2, rect.top + rect.height / 2];
-}
-function targetToPosition(target) {
-  if (Array.isArray(target) && target.length === 2 && typeof target[0] === "number" && typeof target[1] === "number") {
-    return target;
-  } else if (target instanceof HTMLElement) {
-    return calculateClickPositionFromElement(target);
-  } else if (typeof target === "string") {
-    const element = document.querySelector(target);
-    if (element) {
-      return calculateClickPositionFromElement(element);
-    }
-  }
-  return void 0;
-}
-
 // src/stream/Pump.ts
 var Pump = class _Pump {
   constructor(src) {
@@ -2826,7 +1207,16 @@ var createEventPlane = (options) => Effect.gen(function* () {
   };
   const publishToPubSub = (channel, envelope) => PubSub.publish(getPubsub(channel), envelope);
   const publish = (channel, envelope) => Effect.sync(() => recordEvent(envelope)).pipe(
-    Effect.flatMap(() => publishToPubSub(channel, envelope))
+    Effect.flatMap(() => publishToPubSub(channel, envelope)),
+    Effect.withSpan("event.publish", {
+      attributes: {
+        "event.name": envelope.name,
+        "event.payload": payloadForSpan(envelope.payload),
+        channel,
+        runId: envelope.meta.runId,
+        contextId: envelope.meta.contextId
+      }
+    })
   );
   const publishToChannels = (targetChannels, envelope) => Effect.sync(() => recordEvent(envelope)).pipe(
     Effect.flatMap(
@@ -2835,7 +1225,15 @@ var createEventPlane = (options) => Effect.gen(function* () {
         { concurrency: "unbounded" }
       )
     ),
-    Effect.map((results) => results.every(Boolean))
+    Effect.map((results) => results.every(Boolean)),
+    Effect.withSpan("event.publish", {
+      attributes: {
+        "event.name": envelope.name,
+        "event.payload": payloadForSpan(envelope.payload),
+        runId: envelope.meta.runId,
+        contextId: envelope.meta.contextId
+      }
+    })
   );
   const subscribe = (channel) => PubSub.subscribe(getPubsub(channel));
   const getRunEvents = (runId, contextId) => {
@@ -2868,8 +1266,17 @@ var createEventPlane = (options) => Effect.gen(function* () {
     shutdown
   };
 });
-var runSubscriber = (agent, publishesTo, dequeue, plane, emitQueue) => Effect.gen(function* () {
+function payloadForSpan(payload, maxLen = 500) {
+  try {
+    const s = JSON.stringify(payload);
+    return s.length > maxLen ? `${s.slice(0, maxLen)}...` : s;
+  } catch {
+    return String(payload);
+  }
+}
+var runSubscriber = (agent, publishesTo, dequeue, plane, emitQueue, channelName) => Effect.gen(function* () {
   const listensTo = agent.getListensTo?.() ?? [];
+  const agentId = agent.getId();
   const processOne = () => Effect.gen(function* () {
     const envelope = yield* Queue.take(dequeue);
     if (listensTo.length > 0 && !listensTo.includes(envelope.name)) {
@@ -2880,34 +1287,51 @@ var runSubscriber = (agent, publishesTo, dequeue, plane, emitQueue) => Effect.ge
       envelope.meta.contextId
     );
     const contextEvents = plane.getContextEvents(envelope.meta.contextId);
-    yield* Effect.tryPromise({
-      try: () => agent.invoke({
-        triggerEvent: envelope,
-        emit: (userEvent) => {
-          const fullEnvelope = {
-            name: userEvent.name,
-            meta: envelope.meta,
-            payload: userEvent.payload
-          };
-          if (emitQueue) {
-            Effect.runPromise(
-              Queue.offer(emitQueue, {
-                channels: publishesTo,
-                envelope: fullEnvelope
-              })
-            ).catch(() => {
-            });
-          } else {
-            Effect.runFork(
-              plane.publishToChannels(publishesTo, fullEnvelope)
-            );
-          }
-        },
-        runEvents,
-        contextEvents
-      }),
-      catch: (e) => e
-    });
+    yield* Effect.withSpan("agent.listen", {
+      attributes: {
+        agentId,
+        "event.name": envelope.name,
+        "event.payload": payloadForSpan(envelope.payload),
+        ...channelName !== void 0 && { channel: channelName }
+      }
+    })(
+      Effect.withSpan("agent.invoke", {
+        attributes: {
+          agentId,
+          "event.name": envelope.name,
+          "event.payload": payloadForSpan(envelope.payload)
+        }
+      })(
+        Effect.tryPromise({
+          try: () => agent.invoke({
+            triggerEvent: envelope,
+            emit: (userEvent) => {
+              const fullEnvelope = {
+                name: userEvent.name,
+                meta: envelope.meta,
+                payload: userEvent.payload
+              };
+              if (emitQueue) {
+                Effect.runPromise(
+                  Queue.offer(emitQueue, {
+                    channels: publishesTo,
+                    envelope: fullEnvelope
+                  })
+                ).catch(() => {
+                });
+              } else {
+                Effect.runFork(
+                  plane.publishToChannels(publishesTo, fullEnvelope)
+                );
+              }
+            },
+            runEvents,
+            contextEvents
+          }),
+          catch: (e) => e
+        })
+      )
+    );
   }).pipe(
     Effect.catchAllCause(
       (cause) => Cause.isInterrupted(cause) ? Effect.void : Effect.sync(() => {
@@ -2929,7 +1353,8 @@ var run = (network, plane, options) => Effect.gen(function* () {
         reg.publishesTo,
         dequeue,
         plane,
-        emitQueue
+        emitQueue,
+        channel.name
       );
     }
   }
@@ -3003,7 +1428,8 @@ function expose(network, options) {
     select,
     plane: providedPlane,
     onRequest,
-    triggerEvents
+    triggerEvents,
+    tracingLayer
   } = options;
   const triggerEventDef = triggerEvents?.[0];
   const triggerEventName = triggerEventDef?.name ?? "request";
@@ -3017,7 +1443,7 @@ function expose(network, options) {
     const payload = await extractPayload(req);
     const signal = req.request?.signal;
     const program = Effect.gen(function* () {
-      const plane = providedPlane ?? (yield* createEventPlane({ network }));
+      const plane = providedPlane ?? (yield* createEventPlane({ network, store: network.getStore() }));
       if (!providedPlane) {
         const emitQueue = yield* Queue.unbounded();
         yield* Effect.fork(
@@ -3085,7 +1511,8 @@ function expose(network, options) {
       }
       return stream;
     });
-    return Effect.runPromise(program.pipe(Effect.scoped));
+    const runnable = tracingLayer ? program.pipe(Effect.provide(tracingLayer), Effect.scoped) : program.pipe(Effect.scoped);
+    return Effect.runPromise(runnable);
   };
   return {
     protocol: "sse",
@@ -3117,6 +1544,7 @@ var AgentNetwork = class _AgentNetwork {
     this.channels = /* @__PURE__ */ new Map();
     this.agentRegistrations = /* @__PURE__ */ new Map();
     this.spawnerRegistrations = [];
+    this._store = createInMemoryNetworkStore();
   }
   /* ─── Public Static Factory ─── */
   static setup(callback) {
@@ -3204,6 +1632,10 @@ var AgentNetwork = class _AgentNetwork {
   getSpawnerRegistrations() {
     return this.spawnerRegistrations;
   }
+  /** Store defined at network setup time. Shared across all event planes created for this network. */
+  getStore() {
+    return this._store;
+  }
   /**
    * Expose the network as a streamable API (e.g. SSE). Returns an ExposedAPI
    * that adapters (NextEndpoint, ExpressEndpoint) consume to produce streamed
@@ -3229,7 +1661,11 @@ var AgentNetwork = class _AgentNetwork {
   }
   runScoped(network, capacity) {
     return Effect.gen(function* () {
-      const plane = yield* createEventPlane({ network, capacity });
+      const plane = yield* createEventPlane({
+        network,
+        capacity,
+        store: network.getStore()
+      });
       yield* Effect.fork(run(network, plane));
       return plane;
     });
@@ -3387,6 +1823,157 @@ var AgentFactory = class _AgentFactory {
     );
   }
 };
+var CAMEL_CASE_REGEX = /^[a-z][a-zA-Z0-9]*$/;
+var LayerName = Brand.refined(
+  (s) => typeof s === "string" && CAMEL_CASE_REGEX.test(s),
+  (s) => Brand.error(`Expected camelCase (e.g. myLayerFoo), got: ${s}`)
+);
+var SkillDependency = {
+  of(config) {
+    const name = LayerName(config.name);
+    const decode = Schema.decodeUnknown(config.shape);
+    return {
+      _tag: "SkillDependencyDef",
+      name,
+      _name: config.name,
+      shape: config.shape,
+      decode
+    };
+  }
+};
+function toLayerArray(layers) {
+  if (layers.length === 1 && Array.isArray(layers[0])) {
+    return layers[0];
+  }
+  return [...layers];
+}
+function assertUniqueLayerNames(layers) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const dep of layers) {
+    const key = dep.name;
+    if (seen.has(key)) {
+      throw new Error(`Duplicate layer name: ${key}`);
+    }
+    seen.add(key);
+  }
+}
+var Skill = class _Skill {
+  constructor(params) {
+    this._inputSchema = params.inputSchema;
+    this._chunkSchema = params.chunkSchema;
+    this._doneSchema = params.doneSchema;
+    this._layers = params.layers;
+    this._defineFn = params.defineFn;
+  }
+  getState() {
+    return {
+      inputSchema: this._inputSchema,
+      chunkSchema: this._chunkSchema,
+      doneSchema: this._doneSchema,
+      layers: this._layers,
+      defineFn: this._defineFn
+    };
+  }
+  static of(_options) {
+    return new _Skill({
+      layers: []
+    });
+  }
+  input(schema) {
+    return new _Skill({
+      ...this.getState(),
+      inputSchema: schema
+    });
+  }
+  chunk(schema) {
+    return new _Skill({
+      ...this.getState(),
+      chunkSchema: schema
+    });
+  }
+  done(schema) {
+    return new _Skill({
+      ...this.getState(),
+      doneSchema: schema
+    });
+  }
+  use(...layers) {
+    const normalized = toLayerArray(layers);
+    const allLayers = [...this._layers, ...normalized];
+    assertUniqueLayerNames(allLayers);
+    return new _Skill({
+      ...this.getState(),
+      layers: allLayers
+    });
+  }
+  define(fn) {
+    const state = this.getState();
+    const inputSchema = state.inputSchema;
+    const chunkSchema = state.chunkSchema;
+    const doneSchema = state.doneSchema;
+    const defineFn = fn;
+    if (!inputSchema || !chunkSchema || !doneSchema || !defineFn) {
+      throw new Error(
+        "Skill.define requires input(), chunk(), and done() to be called before define()"
+      );
+    }
+    const decodeInput = Schema.decodeUnknown(inputSchema);
+    const decodeChunk = Schema.decodeUnknown(chunkSchema);
+    const decodeDone = Schema.decodeUnknown(doneSchema);
+    const runDefine = async (input, runtime) => {
+      const layersObj = runtime?.layers ?? {};
+      const chunks = [];
+      const emit = (chunk) => {
+        const decoded = Effect.runSync(
+          decodeChunk(chunk)
+        );
+        chunks.push(decoded);
+      };
+      const done = await defineFn({
+        input,
+        emit,
+        layers: layersObj
+      });
+      const decodedDone = Effect.runSync(
+        decodeDone(done)
+      );
+      return { chunks, done: decodedDone };
+    };
+    return {
+      invokeStream: async function* (input, runtime) {
+        const decodedInput = Effect.runSync(
+          decodeInput(input)
+        );
+        const layersObj = runtime?.layers ?? {};
+        const chunks = [];
+        const emit = (chunk) => {
+          const decoded = Effect.runSync(
+            decodeChunk(chunk)
+          );
+          chunks.push(decoded);
+        };
+        const done = await defineFn({
+          input: decodedInput,
+          emit,
+          layers: layersObj
+        });
+        const decodedDone = Effect.runSync(
+          decodeDone(done)
+        );
+        for (const c of chunks) {
+          yield c;
+        }
+        yield { _tag: "Done", done: decodedDone };
+      },
+      invoke: async (input, runtime) => {
+        const decodedInput = Effect.runSync(
+          decodeInput(input)
+        );
+        return runDefine(decodedInput, runtime);
+      }
+    };
+  }
+};
 
 // src/matrix/io/protocols/sse.ts
 function formatSSE(envelope) {
@@ -3524,7 +2111,79 @@ var ExpressEndpoint = {
     };
   }
 };
+var randomHexString = (length) => {
+  const chars = "abcdef0123456789";
+  let result = "";
+  for (let i = 0; i < length; i++) {
+    result += chars.charAt(Math.floor(Math.random() * chars.length));
+  }
+  return result;
+};
+var ConsoleSpan = class {
+  constructor(name, parent, context, links, startTime, kind, depth) {
+    this.name = name;
+    this.parent = parent;
+    this.context = context;
+    this.startTime = startTime;
+    this.kind = kind;
+    this.depth = depth;
+    this._tag = "Span";
+    this.sampled = true;
+    this.attributes = /* @__PURE__ */ new Map();
+    this.links = [];
+    this.traceId = parent._tag === "Some" ? parent.value.traceId : randomHexString(32);
+    this.spanId = randomHexString(16);
+    this.links = Array.from(links);
+    this.status = { _tag: "Started", startTime };
+  }
+  end(endTime, exit) {
+    if (this.status._tag === "Ended")
+      return;
+    const startTime = this.status.startTime;
+    const durationNs = endTime - startTime;
+    const durationMs = Number(durationNs) / 1e6;
+    const indent = "  ".repeat(this.depth);
+    const attrs = Object.fromEntries(this.attributes);
+    const status = Exit.isSuccess(exit) ? "ok" : "error";
+    console.log(
+      `${indent}[trace] ${this.name} ${durationMs.toFixed(2)}ms (${status})`,
+      Object.keys(attrs).length > 0 ? attrs : ""
+    );
+    this.status = { _tag: "Ended", startTime, endTime, exit };
+  }
+  attribute(key, value) {
+    this.attributes.set(key, value);
+  }
+  event(_name, _startTime, _attributes) {
+  }
+  addLinks(links) {
+    this.links.push(...links);
+  }
+};
+function getDepth(parent) {
+  if (parent._tag === "None")
+    return 0;
+  const p = parent.value;
+  if (p._tag === "ExternalSpan")
+    return 0;
+  return 1 + getDepth(p.parent);
+}
+var consoleTracer = Tracer.make({
+  span: (name, parent, context, links, startTime, kind) => new ConsoleSpan(
+    name,
+    parent,
+    context,
+    links,
+    startTime,
+    kind,
+    getDepth(parent)
+  ),
+  context: (f) => f()
+});
+var consoleTracerLayer = Layer.setTracer(
+  consoleTracer
+);
 
-export { Agent, AgentFactory, AgentNetwork, AgentNetworkEvent, AiCursor, BaseVoiceEndpointAdapter, Channel, ChannelName, ConfiguredChannel, Emitter, EventMetaSchema, ExposeAuthError, ExpressEndpoint, InputAudioController, NextEndpoint, Pump, Sink, SocketIoFactory, TransformMessages, VoiceEndpointAdapter, VoiceSocketAdapter, ensureFullWords, formatSSE, httpStreamResponse, isHttpStreamSink, toSSEStream, useConversation, useSocketConversation };
+export { Agent, AgentFactory, AgentNetwork, AgentNetworkEvent, Channel, ChannelName, ConfiguredChannel, EventMetaSchema, ExposeAuthError, ExpressEndpoint, LayerName, NextEndpoint, Pump, Sink, Skill, SkillDependency, SocketIoFactory, TransformMessages, consoleTracer, consoleTracerLayer, ensureFullWords, formatSSE, httpStreamResponse, isHttpStreamSink, toSSEStream };
 //# sourceMappingURL=out.js.map
 //# sourceMappingURL=index.js.map