@guidekit/core 0.1.0-beta.1 → 0.1.0-beta.2

package/dist/index.js

@@ -1091,7 +1091,7 @@ var DOMScanner = class {
       if (el.closest("[data-guidekit-ignore]")) return;
       const style = window.getComputedStyle(el);
       const position = style.position;
-      const zIndex = parseInt(style.zIndex, 10);
+      const zIndex = parseInt(style.zIndex, 10) || 0;
       if ((position === "fixed" || position === "absolute") && !isNaN(zIndex) && zIndex >= 1e3) {
         const visible = isElementVisible(el);
         if (!visible) return;
@@ -1748,7 +1748,9 @@ var ErrorCodes = {
   // Content
   CONTENT_FILTER_TRIGGERED: "CONTENT_FILTER_TRIGGERED",
   // Privacy
-  PRIVACY_HOOK_CANCELLED: "PRIVACY_HOOK_CANCELLED"
+  PRIVACY_HOOK_CANCELLED: "PRIVACY_HOOK_CANCELLED",
+  // General
+  UNKNOWN: "UNKNOWN"
 };
 var GuideKitError = class extends Error {
   code;
@@ -1841,13 +1843,27 @@ function isGuideKitError(error) {
 var DEFAULT_OPENAI_MODEL = "gpt-4o";
 var DEFAULT_TIMEOUT_MS = 15e3;
 var OPENAI_CHAT_URL = "https://api.openai.com/v1/chat/completions";
+function emptyUsage() {
+  return { prompt: 0, completion: 0, total: 0 };
+}
 var OpenAIAdapter = class {
   apiKey;
   model;
+  /** Tracks whether the last extractChunks call emitted a done chunk. */
+  lastExtractEmittedDone = false;
+  /**
+   * Token usage extracted from the most recent `parseResponse` call.
+   * Updated as each SSE chunk is parsed.
+   */
+  _lastUsage = emptyUsage();
   constructor(config) {
     this.apiKey = config.apiKey;
     this.model = config.model ?? DEFAULT_OPENAI_MODEL;
   }
+  /** Token usage from the most recent parseResponse call. */
+  get lastUsage() {
+    return this._lastUsage;
+  }
   // -----------------------------------------------------------------------
   // LLMProviderAdapter implementation
   // -----------------------------------------------------------------------
@@ -1862,7 +1878,11 @@ var OpenAIAdapter = class {
       function: {
         name: tool.name,
         description: tool.description,
-        parameters: tool.parameters
+        parameters: {
+          type: "object",
+          properties: { ...tool.parameters },
+          required: tool.required ?? []
+        }
       }
     }));
   }
@@ -1884,11 +1904,17 @@ var OpenAIAdapter = class {
    * prefixed by `data: `. The final line is `data: [DONE]`.
    * Text content arrives in `choices[0].delta.content` and tool calls
    * arrive in `choices[0].delta.tool_calls`.
+   *
+   * This method also:
+   * - Detects content filtering and throws `ContentFilterError`.
+   * - Tracks token usage (accessible via `lastUsage` after iteration).
    */
   async *parseResponse(stream) {
     const reader = stream.getReader();
     const decoder = new TextDecoder();
     let buffer = "";
+    let doneEmitted = false;
+    this._lastUsage = emptyUsage();
     const pendingToolCalls = /* @__PURE__ */ new Map();
     try {
       while (true) {
@@ -1904,7 +1930,10 @@ var OpenAIAdapter = class {
           if (jsonStr === "" || jsonStr === "[DONE]") {
             if (jsonStr === "[DONE]") {
               yield* this.flushPendingToolCalls(pendingToolCalls);
-              yield { text: "", done: true };
+              if (!doneEmitted) {
+                doneEmitted = true;
+                yield { text: "", done: true };
+              }
             }
             continue;
           }
@@ -1914,19 +1943,53 @@ var OpenAIAdapter = class {
           } catch {
             continue;
           }
-          yield* this.extractChunks(parsed, pendingToolCalls);
+          if (this.isContentFiltered(parsed)) {
+            throw new ContentFilterError({
+              code: ErrorCodes.CONTENT_FILTER_TRIGGERED,
+              message: "Response was blocked by provider content safety filter.",
+              provider: "openai",
+              suggestion: "Rephrase your question or adjust safety settings."
+            });
+          }
+          const chunkUsage = this.extractUsage(parsed);
+          if (chunkUsage) {
+            this._lastUsage = chunkUsage;
+          }
+          yield* this.extractChunks(parsed, pendingToolCalls, doneEmitted);
+          if (!doneEmitted && this.lastExtractEmittedDone) {
+            doneEmitted = true;
+          }
         }
       }
       if (buffer.trim().startsWith("data:")) {
         const jsonStr = buffer.trim().slice(5).trim();
         if (jsonStr === "[DONE]") {
           yield* this.flushPendingToolCalls(pendingToolCalls);
-          yield { text: "", done: true };
+          if (!doneEmitted) {
+            doneEmitted = true;
+            yield { text: "", done: true };
+          }
         } else if (jsonStr !== "") {
           try {
             const parsed = JSON.parse(jsonStr);
-            yield* this.extractChunks(parsed, pendingToolCalls);
-          } catch {
+            if (this.isContentFiltered(parsed)) {
+              throw new ContentFilterError({
+                code: ErrorCodes.CONTENT_FILTER_TRIGGERED,
+                message: "Response was blocked by provider content safety filter.",
+                provider: "openai",
+                suggestion: "Rephrase your question or adjust safety settings."
+              });
+            }
+            const chunkUsage = this.extractUsage(parsed);
+            if (chunkUsage) {
+              this._lastUsage = chunkUsage;
+            }
+            yield* this.extractChunks(parsed, pendingToolCalls, doneEmitted);
+            if (!doneEmitted && this.lastExtractEmittedDone) {
+              doneEmitted = true;
+            }
+          } catch (error) {
+            if (error instanceof ContentFilterError) throw error;
           }
         }
       }
@@ -1955,10 +2018,14 @@ var OpenAIAdapter = class {
    * the raw Response object.
    */
   async streamRequest(params) {
+    const contentsArray = params.contents;
     const messages = [
       { role: "system", content: params.systemPrompt },
-      ...params.contents
+      ...contentsArray
     ];
+    if (params.userMessage) {
+      messages.push({ role: "user", content: params.userMessage });
+    }
     const body = {
       model: this.model,
       messages,
@@ -2041,7 +2108,8 @@ var OpenAIAdapter = class {
    * yield complete `ToolCall` objects when the finish_reason is 'tool_calls'
    * or when flushed.
    */
-  *extractChunks(parsed, pendingToolCalls) {
+  *extractChunks(parsed, pendingToolCalls, doneEmitted) {
+    this.lastExtractEmittedDone = false;
     const choices = parsed.choices;
     if (!choices || choices.length === 0) return;
     for (const choice of choices) {
@@ -2075,7 +2143,8 @@ var OpenAIAdapter = class {
       if (finishReason === "tool_calls") {
         yield* this.flushPendingToolCalls(pendingToolCalls);
       }
-      if (finishReason === "stop") {
+      if (finishReason === "stop" && !doneEmitted && !this.lastExtractEmittedDone) {
+        this.lastExtractEmittedDone = true;
         yield { text: "", done: true };
       }
     }
@@ -2091,7 +2160,8 @@ var OpenAIAdapter = class {
       let args = {};
       try {
         args = JSON.parse(tc.argumentsJson);
-      } catch {
+      } catch (_e) {
+        console.warn("[GuideKit:LLM] Failed to parse tool call arguments:", tc.argumentsJson);
       }
       yield {
         id: tc.id,
@@ -2194,16 +2264,26 @@ var DEFAULT_SAFETY_SETTINGS = [
   { category: "HARM_CATEGORY_SEXUALLY_EXPLICIT", threshold: "BLOCK_ONLY_HIGH" },
   { category: "HARM_CATEGORY_DANGEROUS_CONTENT", threshold: "BLOCK_ONLY_HIGH" }
 ];
-function emptyUsage() {
+function emptyUsage2() {
   return { prompt: 0, completion: 0, total: 0 };
 }
 var GeminiAdapter = class {
   apiKey;
   model;
+  /**
+   * Token usage extracted from the most recent `parseResponse` call.
+   * Updated as each SSE chunk is parsed; the final value reflects the
+   * cumulative usage metadata sent by Gemini (typically in the last chunk).
+   */
+  _lastUsage = emptyUsage2();
   constructor(config) {
     this.apiKey = config.apiKey;
     this.model = config.model ?? DEFAULT_GEMINI_MODEL;
   }
+  /** Token usage from the most recent parseResponse call. */
+  get lastUsage() {
+    return this._lastUsage;
+  }
   // -----------------------------------------------------------------------
   // LLMProviderAdapter implementation
   // -----------------------------------------------------------------------
@@ -2218,7 +2298,11 @@ var GeminiAdapter = class {
         functionDeclarations: tools.map((tool) => ({
           name: tool.name,
           description: tool.description,
-          parameters: tool.parameters
+          parameters: {
+            type: "object",
+            properties: { ...tool.parameters },
+            required: tool.required ?? []
+          }
         }))
       }
     ];
@@ -2240,11 +2324,16 @@ var GeminiAdapter = class {
    * The Gemini `streamGenerateContent?alt=sse` endpoint sends each chunk
    * as a JSON object prefixed by `data: `. We parse line-by-line, extract
    * text parts and function call parts, and yield the appropriate types.
+   *
+   * This method also:
+   * - Detects content filtering and throws `ContentFilterError`.
+   * - Tracks token usage (accessible via `lastUsage` after iteration).
    */
   async *parseResponse(stream) {
     const reader = stream.getReader();
     const decoder = new TextDecoder();
     let buffer = "";
+    this._lastUsage = emptyUsage2();
     try {
       while (true) {
         const { done, value } = await reader.read();
@@ -2263,6 +2352,18 @@ var GeminiAdapter = class {
           } catch {
             continue;
           }
+          if (this.isContentFiltered(parsed)) {
+            throw new ContentFilterError({
+              code: ErrorCodes.CONTENT_FILTER_TRIGGERED,
+              message: "Response was blocked by provider content safety filter.",
+              provider: "gemini",
+              suggestion: "Rephrase your question or adjust safety settings."
+            });
+          }
+          const chunkUsage = this.extractUsage(parsed);
+          if (chunkUsage) {
+            this._lastUsage = chunkUsage;
+          }
           yield* this.extractChunks(parsed);
         }
       }
@@ -2271,8 +2372,21 @@ var GeminiAdapter = class {
         if (jsonStr !== "" && jsonStr !== "[DONE]") {
           try {
             const parsed = JSON.parse(jsonStr);
+            if (this.isContentFiltered(parsed)) {
+              throw new ContentFilterError({
+                code: ErrorCodes.CONTENT_FILTER_TRIGGERED,
+                message: "Response was blocked by provider content safety filter.",
+                provider: "gemini",
+                suggestion: "Rephrase your question or adjust safety settings."
+              });
+            }
+            const chunkUsage = this.extractUsage(parsed);
+            if (chunkUsage) {
+              this._lastUsage = chunkUsage;
+            }
             yield* this.extractChunks(parsed);
-          } catch {
+          } catch (error) {
+            if (error instanceof ContentFilterError) throw error;
           }
         }
       }
@@ -2303,15 +2417,21 @@ var GeminiAdapter = class {
   /**
    * Build and execute a streaming request to the Gemini API.
    * Returns the raw `ReadableStream` for the response body together with
-   * a promise that resolves to token usage extracted from the final chunk.
+   * the raw Response object.
+   *
+   * Note: The Gemini API key is passed as a URL query parameter (`key=`).
+   * This is inherent to the Gemini REST SSE endpoint design; the key is
+   * transmitted over HTTPS so it remains encrypted in transit. (H3)
    */
   async streamRequest(params) {
+    const contentsArray = params.contents;
+    const fullContents = params.userMessage ? [...contentsArray, { role: "user", parts: [{ text: params.userMessage }] }] : contentsArray;
     const url = `${GEMINI_BASE_URL}/${this.model}:streamGenerateContent?alt=sse&key=${this.apiKey}`;
     const body = {
       systemInstruction: {
         parts: [{ text: params.systemPrompt }]
       },
-      contents: params.contents,
+      contents: fullContents,
       safetySettings: DEFAULT_SAFETY_SETTINGS,
       generationConfig: {
         temperature: 0.7,
@@ -2379,7 +2499,7 @@ var GeminiAdapter = class {
     return { stream: response.body, response };
   }
   // -----------------------------------------------------------------------
-  // Internal helpers
+  // Public helpers (LLMProviderAdapter interface)
   // -----------------------------------------------------------------------
   /**
    * Extract `TextChunk` and `ToolCall` items from a single parsed Gemini
@@ -2552,7 +2672,8 @@ var LLMOrchestrator = class {
   updateConfig(config) {
     this._config = config;
     this._adapter = this.createAdapter(config);
-    this.log(`Config updated: provider=${config.provider}`);
+    const label = "provider" in config ? config.provider : "custom adapter";
+    this.log(`Config updated: ${label}`);
   }
   /** Get the current provider adapter. */
   get adapter() {
@@ -2563,139 +2684,42 @@ var LLMOrchestrator = class {
   // -----------------------------------------------------------------------
   /**
    * Execute a streaming LLM request and collect the results.
+   *
+   * This method is fully adapter-agnostic: it delegates streaming,
+   * response parsing, content-filter detection, and usage extraction
+   * entirely to the active `LLMProviderAdapter`. No provider-specific
+   * SSE parsing lives in the orchestrator.
    */
   async executeStream(params, _isRetry) {
-    const geminiAdapter = this._adapter;
-    const historyContents = geminiAdapter.formatConversation(params.history);
-    const contents = [
-      ...historyContents,
-      { role: "user", parts: [{ text: params.userMessage }] }
-    ];
-    const tools = params.tools && params.tools.length > 0 ? geminiAdapter.formatTools(params.tools) : void 0;
-    const { stream } = await geminiAdapter.streamRequest({
+    const adapter = this._adapter;
+    const historyContents = adapter.formatConversation(params.history);
+    const tools = params.tools && params.tools.length > 0 ? adapter.formatTools(params.tools) : void 0;
+    const { stream } = await adapter.streamRequest({
       systemPrompt: params.systemPrompt,
-      contents,
+      contents: historyContents,
+      userMessage: params.userMessage,
       tools,
       signal: params.signal
     });
     let fullText = "";
     const toolCalls = [];
-    let usage = emptyUsage();
-    let wasContentFiltered = false;
-    const reader = stream.getReader();
-    const decoder = new TextDecoder();
-    let buffer = "";
-    try {
-      while (true) {
-        const { done, value } = await reader.read();
-        if (done) break;
-        buffer += decoder.decode(value, { stream: true });
-        const lines = buffer.split("\n");
-        buffer = lines.pop() ?? "";
-        for (const line of lines) {
-          const trimmed = line.trim();
-          if (!trimmed.startsWith("data:")) continue;
-          const jsonStr = trimmed.slice(5).trim();
-          if (jsonStr === "" || jsonStr === "[DONE]") continue;
-          let parsed;
-          try {
-            parsed = JSON.parse(jsonStr);
-          } catch {
-            continue;
-          }
-          if (geminiAdapter.isContentFiltered(parsed)) {
-            wasContentFiltered = true;
-            break;
-          }
-          const chunkUsage = geminiAdapter.extractUsage(parsed);
-          if (chunkUsage) {
-            usage = chunkUsage;
-          }
-          const candidates = parsed.candidates;
-          if (!candidates || candidates.length === 0) continue;
-          for (const candidate of candidates) {
-            const content = candidate.content;
-            if (!content?.parts) continue;
-            const finishReason = candidate.finishReason;
-            const isDone = finishReason === "STOP" || finishReason === "MAX_TOKENS";
-            for (const part of content.parts) {
-              if (typeof part.text === "string") {
-                fullText += part.text;
-                const chunk = { text: part.text, done: isDone };
-                this.callbacks.onChunk?.(chunk);
-              }
-              if (part.functionCall) {
-                const fc = part.functionCall;
-                const toolCall = {
-                  id: fc.name,
-                  name: fc.name,
-                  arguments: fc.args ?? {}
-                };
-                toolCalls.push(toolCall);
-                this.callbacks.onToolCall?.(toolCall);
-              }
-            }
-          }
-        }
-        if (wasContentFiltered) break;
-      }
-      if (!wasContentFiltered && buffer.trim().startsWith("data:")) {
-        const jsonStr = buffer.trim().slice(5).trim();
-        if (jsonStr !== "" && jsonStr !== "[DONE]") {
-          try {
-            const parsed = JSON.parse(jsonStr);
-            if (geminiAdapter.isContentFiltered(parsed)) {
-              wasContentFiltered = true;
-            } else {
-              const chunkUsage = geminiAdapter.extractUsage(parsed);
-              if (chunkUsage) usage = chunkUsage;
-              const candidates = parsed.candidates;
-              if (candidates) {
-                for (const candidate of candidates) {
-                  const content = candidate.content;
-                  if (!content?.parts) continue;
-                  const finishReason = candidate.finishReason;
-                  const isDone = finishReason === "STOP" || finishReason === "MAX_TOKENS";
-                  for (const part of content.parts) {
-                    if (typeof part.text === "string") {
-                      fullText += part.text;
-                      const chunk = {
-                        text: part.text,
-                        done: isDone
-                      };
-                      this.callbacks.onChunk?.(chunk);
-                    }
-                    if (part.functionCall) {
-                      const fc = part.functionCall;
-                      const toolCall = {
-                        id: fc.name,
-                        name: fc.name,
-                        arguments: fc.args ?? {}
-                      };
-                      toolCalls.push(toolCall);
-                      this.callbacks.onToolCall?.(toolCall);
-                    }
-                  }
-                }
-              }
-            }
-          } catch {
-          }
+    for await (const item of adapter.parseResponse(stream)) {
+      if ("name" in item && "arguments" in item) {
+        const toolCall = item;
+        toolCalls.push(toolCall);
+        this.callbacks.onToolCall?.(toolCall);
+      } else {
+        const chunk = item;
+        if (chunk.text) {
+          fullText += chunk.text;
         }
+        this.callbacks.onChunk?.(chunk);
       }
-    } finally {
-      reader.releaseLock();
-    }
-    if (wasContentFiltered) {
-      throw new ContentFilterError({
-        code: ErrorCodes.CONTENT_FILTER_TRIGGERED,
-        message: "Response was blocked by Gemini content safety filter.",
-        provider: "gemini",
-        suggestion: "Rephrase your question or adjust safety settings."
-      });
     }
-    if (fullText.length > 0) {
-      this.callbacks.onChunk?.({ text: "", done: true });
+    this.callbacks.onChunk?.({ text: "", done: true });
+    let usage = emptyUsage2();
+    if ("lastUsage" in adapter) {
+      usage = adapter.lastUsage;
     }
     if (usage.total > 0) {
       this.callbacks.onTokenUsage?.(usage);
@@ -2707,25 +2731,30 @@ var LLMOrchestrator = class {
   }
   /**
    * Create the appropriate adapter for the given config.
-   * Currently only Gemini is implemented; other providers will be added
-   * as the SDK evolves.
+   *
+   * Built-in providers:
+   * - `'gemini'` — uses the bundled `GeminiAdapter`.
+   *
+   * Custom adapters:
+   * - Pass `{ adapter: myAdapter }` to use any `LLMProviderAdapter`.
+   *   Example: `llm: { adapter: new OpenAIAdapter({ ... }) }`
    */
   createAdapter(config) {
+    if ("adapter" in config) {
+      return config.adapter;
+    }
     switch (config.provider) {
       case "gemini":
         return new GeminiAdapter(config);
-      case "openai":
-        return new OpenAIAdapter(config);
       default:
         throw new Error(
-          `LLM provider "${config.provider}" is not yet supported. Currently only "gemini" and "openai" are implemented.`
+          `LLM provider "${config.provider}" is not yet supported. Use { adapter: yourAdapter } for custom providers.`
         );
     }
   }
   /** Convenience accessor for the current provider name. */
   get providerName() {
-    if (this._config.provider === "gemini") return "gemini";
-    if (this._config.provider === "openai") return "openai";
+    if ("provider" in this._config) return this._config.provider;
     return void 0;
   }
   /** Log a debug message if debug mode is enabled. */
@@ -2878,7 +2907,7 @@ var ToolExecutor = class {
         break;
       }
     }
-    if (rounds >= this.maxRounds && allToolCalls.length > 0) {
+    if (rounds >= this.maxRounds) {
       this.log(
         `Max rounds (${this.maxRounds}) reached. Returning current text.`
       );
@@ -2981,6 +3010,19 @@ var ToolExecutor = class {
         return s.value;
       }
       const tc = toolCalls[i];
+      if (!tc) {
+        const errorMsg2 = s.reason instanceof Error ? s.reason.message : String(s.reason);
+        return {
+          toolCallId: `unknown-${i}`,
+          record: {
+            name: "unknown",
+            args: {},
+            result: void 0,
+            durationMs: 0,
+            error: errorMsg2
+          }
+        };
+      }
       const errorMsg = s.reason instanceof Error ? s.reason.message : String(s.reason);
       return {
         toolCallId: tc.id,
@@ -4173,64 +4215,62 @@ var DeepgramSTT = class {
   }
 };
 
-// src/voice/elevenlabs-tts.ts
-var LOG_PREFIX7 = "[GuideKit:TTS]";
-var DEFAULT_VOICE_ID = "21m00Tcm4TlvDq8ikWAM";
-var DEFAULT_MODEL_ID = "eleven_flash_v2_5";
-var DEFAULT_STABILITY = 0.5;
-var DEFAULT_SIMILARITY_BOOST = 0.75;
-function base64ToArrayBuffer(base64) {
-  const binaryString = atob(base64);
-  const length = binaryString.length;
-  const bytes = new Uint8Array(length);
-  for (let i = 0; i < length; i++) {
-    bytes[i] = binaryString.charCodeAt(i);
+// src/voice/elevenlabs-stt.ts
+var LOG_PREFIX7 = "[GuideKit:ElevenLabs-STT]";
+var ELEVENLABS_STT_ENDPOINT = "wss://api.elevenlabs.io/v1/speech-to-text/realtime";
+var DEFAULT_LANGUAGE2 = "en";
+var INACTIVITY_TIMEOUT_S = 30;
+var SAMPLE_RATE = 16e3;
+function float32ToInt162(float32) {
+  const int16 = new Int16Array(float32.length);
+  for (let i = 0; i < float32.length; i++) {
+    const s = Math.max(-1, Math.min(1, float32[i]));
+    int16[i] = s < 0 ? s * 32768 : s * 32767;
   }
-  return bytes.buffer;
+  return int16;
 }
-var ElevenLabsTTS = class {
-  // ---- Configuration ------------------------------------------------------
+function int16ToBase64(int16) {
+  const bytes = new Uint8Array(int16.buffer);
+  const CHUNK_SIZE = 8192;
+  let binary = "";
+  for (let i = 0; i < bytes.length; i += CHUNK_SIZE) {
+    const chunk = bytes.subarray(i, i + CHUNK_SIZE);
+    binary += String.fromCharCode(...chunk);
+  }
+  return btoa(binary);
+}
+var ElevenLabsSTT = class {
+  // ---- Configuration -------------------------------------------------------
   apiKey;
-  voiceId;
-  modelId;
+  language;
   debugEnabled;
-  // ---- Internal state -----------------------------------------------------
+  // ---- Internal state ------------------------------------------------------
   wsManager = null;
   _connected = false;
   _suspended = false;
-  /**
-   * Whether the BOS (beginning-of-stream) handshake has been sent for the
-   * current WebSocket session. ElevenLabs requires the first message to
-   * contain voice settings and the API key before any text chunks.
-   */
-  bosSent = false;
-  /** Registered audio-event callbacks. */
-  audioCallbacks = /* @__PURE__ */ new Set();
-  // -----------------------------------------------------------------------
+  /** Registered transcript callbacks. */
+  transcriptCallbacks = /* @__PURE__ */ new Set();
+  // -------------------------------------------------------------------------
   // Constructor
-  // -----------------------------------------------------------------------
+  // -------------------------------------------------------------------------
   constructor(options) {
     this.apiKey = options.apiKey;
-    this.voiceId = options.voiceId ?? DEFAULT_VOICE_ID;
-    this.modelId = options.modelId ?? DEFAULT_MODEL_ID;
+    this.language = options.language ?? DEFAULT_LANGUAGE2;
     this.debugEnabled = options.debug ?? false;
-    this.log("ElevenLabsTTS created", {
-      voiceId: this.voiceId,
-      modelId: this.modelId
-    });
+    this.log("ElevenLabsSTT created", { language: this.language });
   }
-  // -----------------------------------------------------------------------
+  // -------------------------------------------------------------------------
   // Public API
-  // -----------------------------------------------------------------------
+  // -------------------------------------------------------------------------
   /** Whether the WebSocket is currently connected and ready. */
   get isConnected() {
     return this._connected;
   }
   /**
-   * Open a WebSocket connection to the ElevenLabs streaming TTS endpoint.
+   * Open a WebSocket connection to ElevenLabs' real-time STT endpoint.
    *
-   * Resolves once the connection is established and the BOS handshake has
-   * been sent. Rejects if the connection cannot be established.
+   * Resolves once the connection is established and the socket is ready to
+   * receive audio frames. Rejects if the connection cannot be established.
    */
   async connect() {
     if (this._connected) {
@@ -4242,17 +4282,16 @@ var ElevenLabsTTS = class {
       return;
     }
     const url = this.buildUrl();
-    this.log("Connecting to", url);
+    this.log("Connecting to", url.replace(this.apiKey, "***"));
     this.wsManager = new WebSocketManager({
       url,
       protocols: [],
       debug: this.debugEnabled,
-      label: "ElevenLabs-TTS"
+      label: "ElevenLabs-STT"
     });
     this.wsManager.onOpen(() => {
       this._connected = true;
-      this.sendBOS();
-      this.log("Connected and BOS sent");
+      this.log("Connected");
     });
     this.wsManager.onMessage((event) => {
       this.handleMessage(event);
@@ -4267,67 +4306,54 @@ var ElevenLabsTTS = class {
     return this.wsManager.connect();
   }
   /**
-   * Send text to be synthesised into speech.
-   *
-   * May be called multiple times to stream text incrementally. Each call
-   * sends a text chunk with `try_trigger_generation: true` so ElevenLabs
-   * can begin synthesising as soon as it has enough context.
-   *
-   * Call {@link flush} when the complete utterance has been sent.
-   */
-  speak(text) {
-    if (!this._connected || !this.wsManager || this._suspended) {
-      this.log("Cannot speak \u2014 not connected or suspended");
-      return;
-    }
-    if (!text) {
-      return;
-    }
-    const message = JSON.stringify({
-      text,
-      try_trigger_generation: true
-    });
-    this.log("Sending text chunk:", text.slice(0, 80) + (text.length > 80 ? "..." : ""));
-    this.wsManager.send(message);
-  }
-  /**
-   * Signal the end of text input for the current utterance.
+   * Send audio data to ElevenLabs for transcription.
    *
-   * Sends the EOS (end-of-stream) marker to ElevenLabs. The server will
-   * flush any remaining audio and send a final chunk with `isFinal: true`.
+   * Accepts either `Float32Array` (Web Audio API output) or `Int16Array`
+   * (already encoded as linear16). Float32 data is automatically converted
+   * to Int16 before encoding. Audio is sent as a base64-encoded JSON message.
    */
-  flush() {
+  sendAudio(audioData) {
     if (!this._connected || !this.wsManager || this._suspended) {
-      this.log("Cannot flush \u2014 not connected or suspended");
       return;
     }
-    const message = JSON.stringify({ text: "" });
-    this.log("Sending EOS (flush)");
-    this.wsManager.send(message);
+    const int16 = audioData instanceof Float32Array ? float32ToInt162(audioData) : audioData;
+    const base64 = int16ToBase64(int16);
+    this.wsManager.send(
+      JSON.stringify({
+        type: "input_audio_chunk",
+        audio: base64,
+        sample_rate: SAMPLE_RATE
+      })
+    );
   }
   /**
-   * Register a callback to receive audio output events.
+   * Register a callback to receive transcript events.
    *
    * @returns An unsubscribe function. Calling it more than once is safe.
    */
-  onAudio(callback) {
-    this.audioCallbacks.add(callback);
+  onTranscript(callback) {
+    this.transcriptCallbacks.add(callback);
     let removed = false;
     return () => {
       if (removed) return;
       removed = true;
-      this.audioCallbacks.delete(callback);
+      this.transcriptCallbacks.delete(callback);
     };
   }
-  /** Gracefully close the connection by sending EOS then closing. */
+  /**
+   * Gracefully close the connection.
+   *
+   * Sends a `commit_audio` message so ElevenLabs can finalise any pending
+   * transcription before the socket is torn down.
+   */
   close() {
     if (!this._connected || !this.wsManager) {
       this.log("Not connected \u2014 nothing to close");
       return;
     }
-    this.log("Closing connection");
+    this.log("Sending commit_audio and closing");
     try {
-      this.wsManager.send(JSON.stringify({ text: "" }));
+      this.wsManager.send(JSON.stringify({ type: "commit_audio" }));
     } catch {
     }
     this.wsManager.close();
@@ -4341,14 +4367,13 @@ var ElevenLabsTTS = class {
       this.wsManager = null;
     }
     this.cleanup();
-    this.audioCallbacks.clear();
+    this.transcriptCallbacks.clear();
   }
   /**
    * Suspend the adapter (e.g. when the device goes offline).
    *
-   * Marks the adapter as suspended so that calls to `speak()` and `flush()`
-   * are silently dropped. The WebSocket itself is left open; ElevenLabs
-   * will close it after an inactivity timeout if the network went away.
+   * Marks the adapter as suspended so that incoming `sendAudio` calls are
+   * silently dropped. The WebSocket itself is left open.
    */
   suspend() {
     if (this._suspended) return;
@@ -4356,54 +4381,22 @@ var ElevenLabsTTS = class {
     this.log("Suspended");
   }
   /**
-   * Resume after a prior `suspend()`. If the underlying connection is
-   * still alive, the adapter returns to normal operation. If the connection
-   * was lost while suspended, callers should `close()` / `destroy()` and
-   * create a new instance.
+   * Resume after a prior `suspend()`.
    */
   resume() {
     if (!this._suspended) return;
     this._suspended = false;
     this.log("Resumed");
   }
-  // -----------------------------------------------------------------------
-  // BOS handshake
-  // -----------------------------------------------------------------------
-  /**
-   * Send the BOS (beginning-of-stream) message.
-   *
-   * This must be the very first message on a new WebSocket session. It
-   * carries the API key and voice settings.
-   */
-  sendBOS() {
-    if (!this.wsManager || this.bosSent) {
-      return;
-    }
-    const bos = JSON.stringify({
-      text: " ",
-      voice_settings: {
-        stability: DEFAULT_STABILITY,
-        similarity_boost: DEFAULT_SIMILARITY_BOOST
-      },
-      xi_api_key: this.apiKey
-    });
-    this.wsManager.send(bos);
-    this.bosSent = true;
-    this.log("BOS handshake sent");
-  }
-  // -----------------------------------------------------------------------
+  // -------------------------------------------------------------------------
   // Message handling
-  // -----------------------------------------------------------------------
+  // -------------------------------------------------------------------------
   /**
-   * Parse incoming ElevenLabs JSON messages and emit audio events.
-   *
-   * ElevenLabs sends messages with the following shape:
-   * ```json
-   * { "audio": "base64encoded...", "isFinal": false }
-   * ```
+   * Parse incoming ElevenLabs JSON messages and emit transcript events.
    *
-   * When `isFinal` is `true`, the server has finished synthesising the
-   * current utterance (i.e. after EOS was sent).
+   * ElevenLabs sends two transcript message types:
+   * - `partial_transcript`: interim result, `isFinal = false`
+   * - `committed_transcript`: final result, `isFinal = true`
    */
   handleMessage(event) {
     if (typeof event.data !== "string") {
@@ -4416,47 +4409,1026 @@ var ElevenLabsTTS = class {
       this.log("Failed to parse message", event.data);
       return;
     }
-    if (parsed["error"] !== void 0) {
-      this.log("ElevenLabs error:", parsed["error"]);
-      return;
+    const type = parsed["type"];
+    if (type === "committed_transcript" || type === "partial_transcript") {
+      this.handleTranscriptMessage(parsed, type === "committed_transcript");
+    } else {
+      this.log("Received message", type, parsed);
+    }
+  }
+  /**
+   * Extract transcript data from a transcript message and notify subscribers.
+   */
+  handleTranscriptMessage(parsed, isFinal) {
+    const result = parsed["result"];
+    const text = result?.text ?? "";
+    const confidence = result?.confidence ?? 0;
+    if (text.trim() === "") {
+      return;
+    }
+    const transcriptEvent = {
+      text,
+      isFinal,
+      confidence,
+      timestamp: Date.now()
+    };
+    this.log(
+      isFinal ? "Final transcript:" : "Interim transcript:",
+      text,
+      `(${(confidence * 100).toFixed(1)}%)`
+    );
+    this.emitTranscript(transcriptEvent);
+  }
+  // -------------------------------------------------------------------------
+  // Subscriber notification
+  // -------------------------------------------------------------------------
+  /**
+   * Emit a transcript event to all registered callbacks.
+   *
+   * Errors thrown by individual callbacks are caught and logged so one
+   * misbehaving subscriber does not prevent others from receiving the event.
+   */
+  emitTranscript(event) {
+    for (const cb of this.transcriptCallbacks) {
+      try {
+        cb(event);
+      } catch (err) {
+        console.error(LOG_PREFIX7, "Transcript callback threw:", err);
+      }
+    }
+  }
+  // -------------------------------------------------------------------------
+  // URL building
+  // -------------------------------------------------------------------------
+  /** Build the ElevenLabs streaming STT endpoint URL with auth query params. */
+  buildUrl() {
+    const params = new URLSearchParams({
+      xi_api_key: this.apiKey,
+      language: this.language,
+      inactivity_timeout: String(INACTIVITY_TIMEOUT_S)
+    });
+    return `${ELEVENLABS_STT_ENDPOINT}?${params.toString()}`;
+  }
+  // -------------------------------------------------------------------------
+  // Cleanup
+  // -------------------------------------------------------------------------
+  /** Reset internal state after disconnection. */
+  cleanup() {
+    this._connected = false;
+  }
+  // -------------------------------------------------------------------------
+  // Logging
+  // -------------------------------------------------------------------------
+  /** Conditional debug logging. */
+  log(...args) {
+    if (this.debugEnabled) {
+      console.debug(LOG_PREFIX7, ...args);
+    }
+  }
+};
+
+// src/voice/elevenlabs-tts.ts
+var LOG_PREFIX8 = "[GuideKit:TTS]";
+var DEFAULT_VOICE_ID = "21m00Tcm4TlvDq8ikWAM";
+var DEFAULT_MODEL_ID = "eleven_flash_v2_5";
+var DEFAULT_STABILITY = 0.5;
+var DEFAULT_SIMILARITY_BOOST = 0.75;
+function base64ToArrayBuffer(base64) {
+  const binaryString = atob(base64);
+  const length = binaryString.length;
+  const bytes = new Uint8Array(length);
+  for (let i = 0; i < length; i++) {
+    bytes[i] = binaryString.charCodeAt(i);
+  }
+  return bytes.buffer;
+}
+var ElevenLabsTTS = class {
+  // ---- Configuration ------------------------------------------------------
+  apiKey;
+  voiceId;
+  modelId;
+  debugEnabled;
+  // ---- Internal state -----------------------------------------------------
+  wsManager = null;
+  _connected = false;
+  _suspended = false;
+  /**
+   * Whether the BOS (beginning-of-stream) handshake has been sent for the
+   * current WebSocket session. ElevenLabs requires the first message to
+   * contain voice settings and the API key before any text chunks.
+   */
+  bosSent = false;
+  /** Registered audio-event callbacks. */
+  audioCallbacks = /* @__PURE__ */ new Set();
+  // -----------------------------------------------------------------------
+  // Constructor
+  // -----------------------------------------------------------------------
+  constructor(options) {
+    this.apiKey = options.apiKey;
+    this.voiceId = options.voiceId ?? DEFAULT_VOICE_ID;
+    this.modelId = options.modelId ?? DEFAULT_MODEL_ID;
+    this.debugEnabled = options.debug ?? false;
+    this.log("ElevenLabsTTS created", {
+      voiceId: this.voiceId,
+      modelId: this.modelId
+    });
+  }
+  // -----------------------------------------------------------------------
+  // Public API
+  // -----------------------------------------------------------------------
+  /** Whether the WebSocket is currently connected and ready. */
+  get isConnected() {
+    return this._connected;
+  }
+  /**
+   * Open a WebSocket connection to the ElevenLabs streaming TTS endpoint.
+   *
+   * Resolves once the connection is established and the BOS handshake has
+   * been sent. Rejects if the connection cannot be established.
+   */
+  async connect() {
+    if (this._connected) {
+      this.log("Already connected \u2014 skipping");
+      return;
+    }
+    if (typeof WebSocket === "undefined") {
+      this.log("WebSocket API not available (SSR?) \u2014 cannot connect");
+      return;
+    }
+    const url = this.buildUrl();
+    this.log("Connecting to", url);
+    this.wsManager = new WebSocketManager({
+      url,
+      protocols: [],
+      debug: this.debugEnabled,
+      label: "ElevenLabs-TTS"
+    });
+    this.wsManager.onOpen(() => {
+      this._connected = true;
+      this.sendBOS();
+      this.log("Connected and BOS sent");
+    });
+    this.wsManager.onMessage((event) => {
+      this.handleMessage(event);
+    });
+    this.wsManager.onClose((code, reason) => {
+      this.log("Connection closed", { code, reason });
+      this.cleanup();
+    });
+    this.wsManager.onError((event) => {
+      this.log("WebSocket error", event);
+    });
+    return this.wsManager.connect();
+  }
+  /**
+   * Send text to be synthesised into speech.
+   *
+   * May be called multiple times to stream text incrementally. Each call
+   * sends a text chunk with `try_trigger_generation: true` so ElevenLabs
+   * can begin synthesising as soon as it has enough context.
+   *
+   * Call {@link flush} when the complete utterance has been sent.
+   */
+  speak(text) {
+    if (!this._connected || !this.wsManager || this._suspended) {
+      this.log("Cannot speak \u2014 not connected or suspended");
+      return;
+    }
+    if (!text) {
+      return;
+    }
+    const message = JSON.stringify({
+      text,
+      try_trigger_generation: true
+    });
+    this.log("Sending text chunk:", text.slice(0, 80) + (text.length > 80 ? "..." : ""));
+    this.wsManager.send(message);
+  }
+  /**
+   * Signal the end of text input for the current utterance.
+   *
+   * Sends the EOS (end-of-stream) marker to ElevenLabs. The server will
+   * flush any remaining audio and send a final chunk with `isFinal: true`.
+   */
+  flush() {
+    if (!this._connected || !this.wsManager || this._suspended) {
+      this.log("Cannot flush \u2014 not connected or suspended");
+      return;
+    }
+    const message = JSON.stringify({ text: "" });
+    this.log("Sending EOS (flush)");
+    this.wsManager.send(message);
+  }
+  /**
+   * Register a callback to receive audio output events.
+   *
+   * @returns An unsubscribe function. Calling it more than once is safe.
+   */
+  onAudio(callback) {
+    this.audioCallbacks.add(callback);
+    let removed = false;
+    return () => {
+      if (removed) return;
+      removed = true;
+      this.audioCallbacks.delete(callback);
+    };
+  }
+  /** Gracefully close the connection by sending EOS then closing. */
+  close() {
+    if (!this._connected || !this.wsManager) {
+      this.log("Not connected \u2014 nothing to close");
+      return;
+    }
+    this.log("Closing connection");
+    try {
+      this.wsManager.send(JSON.stringify({ text: "" }));
+    } catch {
+    }
+    this.wsManager.close();
+    this.cleanup();
+  }
+  /** Force-destroy the connection without a graceful handshake. */
+  destroy() {
+    this.log("Destroying");
+    if (this.wsManager) {
+      this.wsManager.destroy();
+      this.wsManager = null;
+    }
+    this.cleanup();
+    this.audioCallbacks.clear();
+  }
+  /**
+   * Suspend the adapter (e.g. when the device goes offline).
+   *
+   * Marks the adapter as suspended so that calls to `speak()` and `flush()`
+   * are silently dropped. The WebSocket itself is left open; ElevenLabs
+   * will close it after an inactivity timeout if the network went away.
+   */
+  suspend() {
+    if (this._suspended) return;
+    this._suspended = true;
+    this.log("Suspended");
+  }
+  /**
+   * Resume after a prior `suspend()`. If the underlying connection is
+   * still alive, the adapter returns to normal operation. If the connection
+   * was lost while suspended, callers should `close()` / `destroy()` and
+   * create a new instance.
+   */
+  resume() {
+    if (!this._suspended) return;
+    this._suspended = false;
+    this.log("Resumed");
+  }
+  // -----------------------------------------------------------------------
+  // BOS handshake
+  // -----------------------------------------------------------------------
+  /**
+   * Send the BOS (beginning-of-stream) message.
+   *
+   * This must be the very first message on a new WebSocket session. It
+   * carries the API key and voice settings.
+   */
+  sendBOS() {
+    if (!this.wsManager || this.bosSent) {
+      return;
+    }
+    const bos = JSON.stringify({
+      text: " ",
+      voice_settings: {
+        stability: DEFAULT_STABILITY,
+        similarity_boost: DEFAULT_SIMILARITY_BOOST
+      },
+      xi_api_key: this.apiKey
+    });
+    this.wsManager.send(bos);
+    this.bosSent = true;
+    this.log("BOS handshake sent");
+  }
+  // -----------------------------------------------------------------------
+  // Message handling
+  // -----------------------------------------------------------------------
+  /**
+   * Parse incoming ElevenLabs JSON messages and emit audio events.
+   *
+   * ElevenLabs sends messages with the following shape:
+   * ```json
+   * { "audio": "base64encoded...", "isFinal": false }
+   * ```
+   *
+   * When `isFinal` is `true`, the server has finished synthesising the
+   * current utterance (i.e. after EOS was sent).
+   */
+  handleMessage(event) {
+    if (typeof event.data !== "string") {
+      return;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(event.data);
+    } catch {
+      this.log("Failed to parse message", event.data);
+      return;
+    }
+    if (parsed["error"] !== void 0) {
+      this.log("ElevenLabs error:", parsed["error"]);
+      return;
+    }
+    if (parsed["audio"] === void 0 || parsed["audio"] === null) {
+      this.log("Non-audio message received", parsed);
+      return;
+    }
+    const audioBase64 = parsed["audio"];
+    const isFinal = parsed["isFinal"] === true;
+    if (!audioBase64 || audioBase64.length === 0) {
+      if (isFinal) {
+        this.emitAudio({
+          audio: new ArrayBuffer(0),
+          isFinal: true,
+          timestamp: Date.now()
+        });
+      }
+      return;
+    }
+    let audioBuffer;
+    try {
+      audioBuffer = base64ToArrayBuffer(audioBase64);
+    } catch (err) {
+      this.log("Failed to decode base64 audio", err);
+      return;
+    }
+    const audioEvent = {
+      audio: audioBuffer,
+      isFinal,
+      timestamp: Date.now()
+    };
+    this.log(
+      isFinal ? "Final audio chunk:" : "Audio chunk:",
+      `${audioBuffer.byteLength} bytes`
+    );
+    this.emitAudio(audioEvent);
+  }
+  // -----------------------------------------------------------------------
+  // Subscriber notification
+  // -----------------------------------------------------------------------
+  /**
+   * Emit an audio event to all registered callbacks.
+   *
+   * Errors thrown by individual callbacks are caught and logged so one
+   * misbehaving subscriber does not prevent others from receiving the event.
+   */
+  emitAudio(event) {
+    for (const cb of this.audioCallbacks) {
+      try {
+        cb(event);
+      } catch (err) {
+        console.error(LOG_PREFIX8, "Audio callback threw:", err);
+      }
+    }
+  }
+  // -----------------------------------------------------------------------
+  // URL building
+  // -----------------------------------------------------------------------
+  /** Build the ElevenLabs streaming TTS endpoint URL. */
+  buildUrl() {
+    const params = new URLSearchParams({
+      model_id: this.modelId
+    });
+    return `wss://api.elevenlabs.io/v1/text-to-speech/${encodeURIComponent(this.voiceId)}/stream-input?${params.toString()}`;
+  }
+  // -----------------------------------------------------------------------
+  // Cleanup
+  // -----------------------------------------------------------------------
+  /** Reset internal state after disconnection. */
+  cleanup() {
+    this._connected = false;
+    this.bosSent = false;
+  }
+  // -----------------------------------------------------------------------
+  // Logging
+  // -----------------------------------------------------------------------
+  /** Conditional debug logging. */
+  log(...args) {
+    if (this.debugEnabled) {
+      console.debug(LOG_PREFIX8, ...args);
+    }
+  }
+};
+
+// src/voice/web-speech-stt.ts
+var LOG_PREFIX9 = "[GuideKit:WebSpeech-STT]";
+var DEFAULT_LANGUAGE3 = "en-US";
+var WebSpeechSTT = class {
+  // ---- Configuration -------------------------------------------------------
+  language;
+  continuous;
+  interimResultsEnabled;
+  debugEnabled;
+  // ---- Internal state ------------------------------------------------------
+  recognition = null;
+  _connected = false;
+  _suspended = false;
+  /**
+   * Whether we intentionally stopped recognition. Used to distinguish
+   * between intentional stop and unexpected end (for auto-restart in
+   * continuous mode).
+   */
+  _intentionalStop = false;
+  /** Registered transcript callbacks. */
+  transcriptCallbacks = /* @__PURE__ */ new Set();
+  // -------------------------------------------------------------------------
+  // Constructor
+  // -------------------------------------------------------------------------
+  constructor(options = {}) {
+    this.language = options.language ?? DEFAULT_LANGUAGE3;
+    this.continuous = options.continuous ?? true;
+    this.interimResultsEnabled = options.interimResults ?? true;
+    this.debugEnabled = options.debug ?? false;
+    this.log("WebSpeechSTT created", {
+      language: this.language,
+      continuous: this.continuous,
+      interimResults: this.interimResultsEnabled
+    });
+  }
+  // -------------------------------------------------------------------------
+  // Static methods
+  // -------------------------------------------------------------------------
+  /**
+   * Check whether the Web Speech API SpeechRecognition is supported in the
+   * current environment. Safe to call in SSR (returns false).
+   */
+  static isSupported() {
+    if (typeof window === "undefined") return false;
+    return typeof window["SpeechRecognition"] !== "undefined" || typeof globalThis.webkitSpeechRecognition !== "undefined";
+  }
+  // -------------------------------------------------------------------------
+  // Public API
+  // -------------------------------------------------------------------------
+  /** Whether recognition is currently active and connected. */
+  get isConnected() {
+    return this._connected;
+  }
+  /**
+   * Start speech recognition.
+   *
+   * Creates the SpeechRecognition instance and begins listening. Resolves
+   * once the recognition session has started. Rejects if the API is not
+   * supported or the browser denies permission.
+   */
+  async connect() {
+    if (this._connected) {
+      this.log("Already connected \u2014 skipping");
+      return;
+    }
+    if (typeof window === "undefined") {
+      this.log("SSR environment detected \u2014 cannot connect");
+      return;
+    }
+    const SpeechRecognitionClass = this.resolveSpeechRecognition();
+    if (!SpeechRecognitionClass) {
+      throw new Error(
+        "Web Speech API (SpeechRecognition) is not supported in this browser."
+      );
+    }
+    this.recognition = new SpeechRecognitionClass();
+    this.recognition.lang = this.language;
+    this.recognition.continuous = this.continuous;
+    this.recognition.interimResults = this.interimResultsEnabled;
+    this.recognition.maxAlternatives = 1;
+    this.recognition.onstart = () => {
+      this._connected = true;
+      this._intentionalStop = false;
+      this.log("Recognition started");
+    };
+    this.recognition.onresult = (event) => {
+      this.handleResult(event);
+    };
+    this.recognition.onerror = (event) => {
+      this.handleError(event);
+    };
+    this.recognition.onend = () => {
+      this.log("Recognition ended");
+      const wasConnected = this._connected;
+      this._connected = false;
+      if (this.continuous && !this._intentionalStop && !this._suspended && wasConnected) {
+        this.log("Auto-restarting continuous recognition");
+        try {
+          this.recognition?.start();
+        } catch {
+          this.log("Failed to auto-restart recognition");
+        }
+      }
+    };
+    return new Promise((resolve, reject) => {
+      const onStart = () => {
+        cleanup();
+        resolve();
+      };
+      const onError = (event) => {
+        cleanup();
+        reject(new Error(`SpeechRecognition error: ${event.error} \u2014 ${event.message}`));
+      };
+      const cleanup = () => {
+        if (this.recognition) {
+          this.recognition.removeEventListener("start", onStart);
+          this.recognition.removeEventListener("error", onError);
+        }
+      };
+      this.recognition.addEventListener("start", onStart, { once: true });
+      this.recognition.addEventListener("error", onError, { once: true });
+      try {
+        this.recognition.start();
+      } catch (err) {
+        cleanup();
+        reject(err);
+      }
+    });
+  }
+  /**
+   * Send audio data. No-op for Web Speech API since it captures audio
+   * directly from the microphone via the browser's internal pipeline.
+   *
+   * Provided for interface compatibility with WebSocket-based STT adapters
+   * (DeepgramSTT, ElevenLabsSTT).
+   */
+  sendAudio(_audioData) {
+  }
+  /**
+   * Register a callback to receive transcript events.
+   *
+   * @returns An unsubscribe function. Calling it more than once is safe.
+   */
+  onTranscript(callback) {
+    this.transcriptCallbacks.add(callback);
+    let removed = false;
+    return () => {
+      if (removed) return;
+      removed = true;
+      this.transcriptCallbacks.delete(callback);
+    };
+  }
+  /**
+   * Gracefully stop recognition.
+   *
+   * Calls `stop()` on the SpeechRecognition instance which allows it to
+   * deliver any pending final results before ending.
+   */
+  close() {
+    if (!this.recognition) {
+      this.log("Not connected \u2014 nothing to close");
+      return;
+    }
+    this.log("Closing recognition");
+    this._intentionalStop = true;
+    try {
+      this.recognition.stop();
+    } catch {
+    }
+    this.cleanup();
+  }
+  /** Force-destroy the recognition without waiting for pending results. */
+  destroy() {
+    this.log("Destroying");
+    this._intentionalStop = true;
+    if (this.recognition) {
+      try {
+        this.recognition.abort();
+      } catch {
+      }
+      this.recognition.onresult = null;
+      this.recognition.onerror = null;
+      this.recognition.onend = null;
+      this.recognition.onstart = null;
+      this.recognition = null;
+    }
+    this.cleanup();
+    this.transcriptCallbacks.clear();
+  }
+  /**
+   * Suspend the adapter (e.g. when the device goes offline).
+   *
+   * Stops recognition and marks the adapter as suspended so that auto-restart
+   * does not trigger.
+   */
+  suspend() {
+    if (this._suspended) return;
+    this._suspended = true;
+    this._intentionalStop = true;
+    if (this.recognition && this._connected) {
+      try {
+        this.recognition.stop();
+      } catch {
+      }
+    }
+    this.log("Suspended");
+  }
+  /**
+   * Resume after a prior `suspend()`. Restarts recognition if it was
+   * running before suspension.
+   */
+  resume() {
+    if (!this._suspended) return;
+    this._suspended = false;
+    this._intentionalStop = false;
+    this.log("Resumed");
+    if (this.recognition && !this._connected) {
+      try {
+        this.recognition.start();
+      } catch {
+        this.log("Failed to restart recognition after resume");
+      }
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Result handling
+  // -------------------------------------------------------------------------
+  /**
+   * Handle SpeechRecognition result events.
+   *
+   * The `results` property is a SpeechRecognitionResultList containing all
+   * results accumulated during this recognition session. We only process
+   * results from `resultIndex` onward to avoid re-emitting old results.
+   */
+  handleResult(event) {
+    for (let i = event.resultIndex; i < event.results.length; i++) {
+      const result = event.results[i];
+      if (!result) continue;
+      const alternative = result[0];
+      if (!alternative) continue;
+      const transcript = alternative.transcript;
+      if (!transcript || transcript.trim() === "") continue;
+      const isFinal = result.isFinal;
+      const confidence = alternative.confidence > 0 ? alternative.confidence : 0.85;
+      const transcriptEvent = {
+        text: transcript,
+        isFinal,
+        confidence,
+        timestamp: Date.now()
+      };
+      this.log(
+        isFinal ? "Final transcript:" : "Interim transcript:",
+        transcript,
+        `(${(confidence * 100).toFixed(1)}%)`
+      );
+      this.emitTranscript(transcriptEvent);
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Error handling
+  // -------------------------------------------------------------------------
+  /**
+   * Handle SpeechRecognition errors.
+   *
+   * Some errors are recoverable (e.g. `no-speech`) and some are fatal
+   * (e.g. `not-allowed`). For recoverable errors in continuous mode,
+   * recognition will auto-restart via the `onend` handler.
+   */
+  handleError(event) {
+    const errorType = event.error;
+    this.log("Recognition error:", errorType, event.message);
+    if (errorType === "no-speech" || errorType === "aborted") {
+      this.log("Non-fatal error \u2014 will recover");
+      return;
+    }
+    if (errorType === "network") {
+      this.log("Network error \u2014 recognition may auto-restart");
+      return;
+    }
+    if (errorType === "not-allowed" || errorType === "service-not-allowed" || errorType === "language-not-supported") {
+      this._intentionalStop = true;
+      this.log("Fatal recognition error \u2014 stopping");
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Subscriber notification
+  // -------------------------------------------------------------------------
+  /**
+   * Emit a transcript event to all registered callbacks.
+   *
+   * Errors thrown by individual callbacks are caught and logged so one
+   * misbehaving subscriber does not prevent others from receiving the event.
+   */
+  emitTranscript(event) {
+    for (const cb of this.transcriptCallbacks) {
+      try {
+        cb(event);
+      } catch (err) {
+        console.error(LOG_PREFIX9, "Transcript callback threw:", err);
+      }
+    }
+  }
+  // -------------------------------------------------------------------------
+  // SpeechRecognition resolution
+  // -------------------------------------------------------------------------
+  /**
+   * Resolve the SpeechRecognition constructor, with the webkit-prefixed
+   * fallback. Returns null if not available.
+   */
+  resolveSpeechRecognition() {
+    if (typeof window === "undefined") return null;
+    const win = window;
+    if (typeof win["SpeechRecognition"] !== "undefined") {
+      return win["SpeechRecognition"];
+    }
+    if (typeof globalThis.webkitSpeechRecognition !== "undefined") {
+      return globalThis.webkitSpeechRecognition;
+    }
+    return null;
+  }
+  // -------------------------------------------------------------------------
+  // Cleanup
+  // -------------------------------------------------------------------------
+  /** Reset internal state after disconnection. */
+  cleanup() {
+    this._connected = false;
+  }
+  // -------------------------------------------------------------------------
+  // Logging
+  // -------------------------------------------------------------------------
+  /** Conditional debug logging. */
+  log(...args) {
+    if (this.debugEnabled) {
+      console.debug(LOG_PREFIX9, ...args);
+    }
+  }
+};
+
+// src/voice/web-speech-tts.ts
+var LOG_PREFIX10 = "[GuideKit:WebSpeech-TTS]";
+var DEFAULT_RATE = 1;
+var DEFAULT_PITCH = 1;
+var DEFAULT_LANGUAGE4 = "en-US";
+var WebSpeechTTS = class {
+  // ---- Configuration -------------------------------------------------------
+  voiceName;
+  rate;
+  pitch;
+  language;
+  debugEnabled;
+  // ---- Internal state ------------------------------------------------------
+  _connected = false;
+  _suspended = false;
+  /** Cached voice object resolved from voiceName. */
+  _resolvedVoice = null;
+  /** Whether voices have been loaded (they load async in some browsers). */
+  _voicesLoaded = false;
+  /** Registered audio-event callbacks. */
+  audioCallbacks = /* @__PURE__ */ new Set();
+  // -------------------------------------------------------------------------
+  // Constructor
+  // -------------------------------------------------------------------------
+  constructor(options = {}) {
+    this.voiceName = options.voice ?? null;
+    this.rate = options.rate ?? DEFAULT_RATE;
+    this.pitch = options.pitch ?? DEFAULT_PITCH;
+    this.language = options.language ?? DEFAULT_LANGUAGE4;
+    this.debugEnabled = options.debug ?? false;
+    this.log("WebSpeechTTS created", {
+      voice: this.voiceName,
+      rate: this.rate,
+      pitch: this.pitch,
+      language: this.language
+    });
+  }
+  // -------------------------------------------------------------------------
+  // Static methods
+  // -------------------------------------------------------------------------
+  /**
+   * Check whether the Web Speech API SpeechSynthesis is supported in the
+   * current environment. Safe to call in SSR (returns false).
+   */
+  static isSupported() {
+    if (typeof window === "undefined") return false;
+    return typeof window.speechSynthesis !== "undefined";
+  }
+  // -------------------------------------------------------------------------
+  // Public API
+  // -------------------------------------------------------------------------
+  /** Whether the adapter is connected (ready for speech). */
+  get isConnected() {
+    return this._connected;
+  }
+  /**
+   * Initialize the adapter.
+   *
+   * Loads available voices and resolves the requested voice name. Voice
+   * loading is async in some browsers (notably Chrome) so we wait for
+   * the `voiceschanged` event if needed.
+   */
+  async connect() {
+    if (this._connected) {
+      this.log("Already connected \u2014 skipping");
+      return;
+    }
+    if (typeof window === "undefined" || typeof window.speechSynthesis === "undefined") {
+      this.log("SpeechSynthesis not available \u2014 cannot connect");
+      return;
+    }
+    await this.loadVoices();
+    if (this.voiceName) {
+      this._resolvedVoice = this.findVoice(this.voiceName);
+      if (this._resolvedVoice) {
+        this.log("Resolved voice:", this._resolvedVoice.name);
+      } else {
+        this.log("Requested voice not found:", this.voiceName, "\u2014 using browser default");
+      }
+    }
+    this._connected = true;
+    this.log("Connected");
+  }
+  /**
+   * Speak the given text using the browser's speech synthesis engine.
+   *
+   * Returns a Promise that resolves when the utterance completes or is
+   * cancelled. Rejects if an error occurs during synthesis.
+   *
+   * Also emits audio events to registered callbacks for VoicePipeline
+   * compatibility.
+   */
+  speak(text) {
+    if (!this._connected || this._suspended) {
+      this.log("Cannot speak \u2014 not connected or suspended");
+      return;
+    }
+    if (!text || !text.trim()) {
+      return;
+    }
+    if (typeof window === "undefined" || typeof window.speechSynthesis === "undefined") {
+      return;
+    }
+    const synth = window.speechSynthesis;
+    const utterance = new SpeechSynthesisUtterance(text);
+    utterance.lang = this.language;
+    utterance.rate = this.rate;
+    utterance.pitch = this.pitch;
+    if (this._resolvedVoice) {
+      utterance.voice = this._resolvedVoice;
+    }
+    utterance.onstart = () => {
+      this.log("Utterance started:", text.slice(0, 80) + (text.length > 80 ? "..." : ""));
+      this.emitAudio({
+        audio: new ArrayBuffer(0),
+        isFinal: false,
+        timestamp: Date.now()
+      });
+    };
+    utterance.onend = () => {
+      this.log("Utterance ended");
+      this.emitAudio({
+        audio: new ArrayBuffer(0),
+        isFinal: true,
+        timestamp: Date.now()
+      });
+    };
+    utterance.onerror = (event) => {
+      if (event.error === "canceled") {
+        this.log("Utterance cancelled");
+        this.emitAudio({
+          audio: new ArrayBuffer(0),
+          isFinal: true,
+          timestamp: Date.now()
+        });
+        return;
+      }
+      this.log("Utterance error:", event.error);
+      this.emitAudio({
+        audio: new ArrayBuffer(0),
+        isFinal: true,
+        timestamp: Date.now()
+      });
+    };
+    this.log("Speaking:", text.slice(0, 80) + (text.length > 80 ? "..." : ""));
+    synth.speak(utterance);
+  }
+  /**
+   * Flush / finalize the current utterance.
+   *
+   * No-op for Web Speech API since each speak() call is a complete
+   * utterance. Provided for interface compatibility with ElevenLabsTTS.
+   */
+  flush() {
+  }
+  /**
+   * Register a callback to receive audio output events.
+   *
+   * For Web Speech API, these events have empty audio buffers and are
+   * used to signal utterance start/end for VoicePipeline state management.
+   *
+   * @returns An unsubscribe function. Calling it more than once is safe.
+   */
+  onAudio(callback) {
+    this.audioCallbacks.add(callback);
+    let removed = false;
+    return () => {
+      if (removed) return;
+      removed = true;
+      this.audioCallbacks.delete(callback);
+    };
+  }
+  /** Stop current speech synthesis and cancel any queued utterances. */
+  stop() {
+    if (typeof window === "undefined" || typeof window.speechSynthesis === "undefined") {
+      return;
+    }
+    this.log("Stopping speech synthesis");
+    window.speechSynthesis.cancel();
+  }
+  /** Gracefully close the adapter. */
+  close() {
+    this.log("Closing");
+    this.stop();
+    this.cleanup();
+  }
+  /** Force-destroy the adapter. */
+  destroy() {
+    this.log("Destroying");
+    this.stop();
+    this.cleanup();
+    this.audioCallbacks.clear();
+  }
+  /**
+   * Suspend the adapter (e.g. when the device goes offline).
+   *
+   * Pauses any active speech synthesis and marks the adapter as suspended.
+   */
+  suspend() {
+    if (this._suspended) return;
+    this._suspended = true;
+    if (typeof window !== "undefined" && typeof window.speechSynthesis !== "undefined") {
+      window.speechSynthesis.pause();
+    }
+    this.log("Suspended");
+  }
+  /**
+   * Resume after a prior `suspend()`.
+   */
+  resume() {
+    if (!this._suspended) return;
+    this._suspended = false;
+    if (typeof window !== "undefined" && typeof window.speechSynthesis !== "undefined") {
+      window.speechSynthesis.resume();
     }
-    if (parsed["audio"] === void 0 || parsed["audio"] === null) {
-      this.log("Non-audio message received", parsed);
+    this.log("Resumed");
+  }
+  // -------------------------------------------------------------------------
+  // Voice loading
+  // -------------------------------------------------------------------------
+  /**
+   * Load available voices from the browser.
+   *
+   * In Chrome and some other browsers, voices load asynchronously after
+   * the page loads. We wait for the `voiceschanged` event with a timeout.
+   */
+  async loadVoices() {
+    if (this._voicesLoaded) return;
+    if (typeof window === "undefined" || typeof window.speechSynthesis === "undefined") return;
+    const synth = window.speechSynthesis;
+    let voices = synth.getVoices();
+    if (voices.length > 0) {
+      this._voicesLoaded = true;
+      this.log("Voices loaded:", voices.length, "available");
       return;
     }
-    const audioBase64 = parsed["audio"];
-    const isFinal = parsed["isFinal"] === true;
-    if (!audioBase64 || audioBase64.length === 0) {
-      if (isFinal) {
-        this.emitAudio({
-          audio: new ArrayBuffer(0),
-          isFinal: true,
-          timestamp: Date.now()
-        });
-      }
-      return;
+    await new Promise((resolve) => {
+      const onVoicesChanged = () => {
+        synth.removeEventListener("voiceschanged", onVoicesChanged);
+        clearTimeout(timeout);
+        voices = synth.getVoices();
+        this._voicesLoaded = true;
+        this.log("Voices loaded (async):", voices.length, "available");
+        resolve();
+      };
+      const timeout = setTimeout(() => {
+        synth.removeEventListener("voiceschanged", onVoicesChanged);
+        this._voicesLoaded = true;
+        this.log("Voices loading timed out \u2014 proceeding with defaults");
+        resolve();
+      }, 2e3);
+      synth.addEventListener("voiceschanged", onVoicesChanged);
+    });
+  }
+  /**
+   * Find a voice by name (case-insensitive partial match).
+   */
+  findVoice(name) {
+    if (typeof window === "undefined" || typeof window.speechSynthesis === "undefined") {
+      return null;
     }
-    let audioBuffer;
-    try {
-      audioBuffer = base64ToArrayBuffer(audioBase64);
-    } catch (err) {
-      this.log("Failed to decode base64 audio", err);
-      return;
+    const voices = window.speechSynthesis.getVoices();
+    const lowerName = name.toLowerCase();
+    const exact = voices.find((v) => v.name.toLowerCase() === lowerName);
+    if (exact) return exact;
+    const partial = voices.find((v) => v.name.toLowerCase().includes(lowerName));
+    if (partial) return partial;
+    if (lowerName.includes("-") || lowerName.length <= 5) {
+      const langMatch = voices.find((v) => v.lang.toLowerCase().startsWith(lowerName));
+      if (langMatch) return langMatch;
     }
-    const audioEvent = {
-      audio: audioBuffer,
-      isFinal,
-      timestamp: Date.now()
-    };
-    this.log(
-      isFinal ? "Final audio chunk:" : "Audio chunk:",
-      `${audioBuffer.byteLength} bytes`
-    );
-    this.emitAudio(audioEvent);
+    return null;
   }
-  // -----------------------------------------------------------------------
+  // -------------------------------------------------------------------------
   // Subscriber notification
-  // -----------------------------------------------------------------------
+  // -------------------------------------------------------------------------
   /**
    * Emit an audio event to all registered callbacks.
    *
@@ -4468,41 +5440,30 @@ var ElevenLabsTTS = class {
       try {
         cb(event);
       } catch (err) {
-        console.error(LOG_PREFIX7, "Audio callback threw:", err);
+        console.error(LOG_PREFIX10, "Audio callback threw:", err);
       }
     }
   }
-  // -----------------------------------------------------------------------
-  // URL building
-  // -----------------------------------------------------------------------
-  /** Build the ElevenLabs streaming TTS endpoint URL. */
-  buildUrl() {
-    const params = new URLSearchParams({
-      model_id: this.modelId
-    });
-    return `wss://api.elevenlabs.io/v1/text-to-speech/${encodeURIComponent(this.voiceId)}/stream-input?${params.toString()}`;
-  }
-  // -----------------------------------------------------------------------
+  // -------------------------------------------------------------------------
   // Cleanup
-  // -----------------------------------------------------------------------
-  /** Reset internal state after disconnection. */
+  // -------------------------------------------------------------------------
+  /** Reset internal state. */
   cleanup() {
     this._connected = false;
-    this.bosSent = false;
   }
-  // -----------------------------------------------------------------------
+  // -------------------------------------------------------------------------
   // Logging
-  // -----------------------------------------------------------------------
+  // -------------------------------------------------------------------------
   /** Conditional debug logging. */
   log(...args) {
     if (this.debugEnabled) {
-      console.debug(LOG_PREFIX7, ...args);
+      console.debug(LOG_PREFIX10, ...args);
     }
   }
 };
 
 // src/voice/index.ts
-var LOG_PREFIX8 = "[GuideKit:Voice]";
+var LOG_PREFIX11 = "[GuideKit:Voice]";
 var JITTER_BUFFER_MS = 150;
 var ECHO_WINDOW_MS = 3e3;
 var ECHO_OVERLAP_THRESHOLD = 0.6;
@@ -4610,17 +5571,42 @@ var VoicePipeline = class {
         cause: err instanceof Error ? err : void 0
       });
     }
-    this._stt = new DeepgramSTT({
-      apiKey: this._sttConfig.apiKey,
-      model: this._sttConfig.model,
-      debug: this._debug
-    });
-    this._tts = new ElevenLabsTTS({
-      apiKey: this._ttsConfig.apiKey,
-      voiceId: this._ttsConfig.voiceId,
-      modelId: this._ttsConfig.modelId,
-      debug: this._debug
-    });
+    if (this._sttConfig.provider === "deepgram") {
+      this._stt = new DeepgramSTT({
+        apiKey: this._sttConfig.apiKey,
+        model: this._sttConfig.model,
+        debug: this._debug
+      });
+    } else if (this._sttConfig.provider === "elevenlabs") {
+      this._stt = new ElevenLabsSTT({
+        apiKey: this._sttConfig.apiKey,
+        language: this._sttConfig.language,
+        debug: this._debug
+      });
+    } else {
+      this._stt = new WebSpeechSTT({
+        language: this._sttConfig.language,
+        continuous: this._sttConfig.continuous,
+        interimResults: this._sttConfig.interimResults,
+        debug: this._debug
+      });
+    }
+    if (this._ttsConfig.provider === "elevenlabs") {
+      this._tts = new ElevenLabsTTS({
+        apiKey: this._ttsConfig.apiKey,
+        voiceId: this._ttsConfig.voiceId,
+        modelId: "modelId" in this._ttsConfig ? this._ttsConfig.modelId : void 0,
+        debug: this._debug
+      });
+    } else {
+      this._tts = new WebSpeechTTS({
+        voice: this._ttsConfig.voice,
+        rate: this._ttsConfig.rate,
+        pitch: this._ttsConfig.pitch,
+        language: this._ttsConfig.language,
+        debug: this._debug
+      });
+    }
     this._log("Initialization complete");
   }
   // ────────────────────────────────────────────────────────────────────
@@ -4760,10 +5746,11 @@ var VoicePipeline = class {
   // ────────────────────────────────────────────────────────────────────
   // speak()
   // ────────────────────────────────────────────────────────────────────
-  /** Speak text via ElevenLabs TTS. */
+  /** Speak text via TTS (ElevenLabs or Web Speech API). */
   async speak(text) {
     if (this._destroyed || !text.trim()) return;
-    if (!this._tts || !this._audioContext) {
+    const isWebSpeechTTS = this._tts instanceof WebSpeechTTS;
+    if (!this._tts || !this._audioContext && !isWebSpeechTTS) {
       this._log("TTS or AudioContext not available \u2014 cannot speak");
       this._bus.emit("voice:degraded", { reason: "TTS not available", fallback: "text" });
       this._setState("idle");
@@ -4807,11 +5794,24 @@ var VoicePipeline = class {
         }
         resolve();
       };
-      this._unsubTTSAudio = this._tts.onAudio((event) => {
-        this._handleTTSAudio(event, done);
-      });
-      this._tts.speak(text);
-      this._tts.flush();
+      if (isWebSpeechTTS) {
+        this._unsubTTSAudio = this._tts.onAudio(
+          (event) => {
+            if (event.isFinal) {
+              done();
+            }
+          }
+        );
+        this._tts.speak(text);
+      } else {
+        this._unsubTTSAudio = this._tts.onAudio(
+          (event) => {
+            this._handleTTSAudio(event, done);
+          }
+        );
+        this._tts.speak(text);
+        this._tts.flush();
+      }
     });
   }
   // ────────────────────────────────────────────────────────────────────
@@ -4840,7 +5840,9 @@ var VoicePipeline = class {
       this._pendingLLMAbort.abort();
       this._pendingLLMAbort = null;
     }
-    if (this._tts?.isConnected) {
+    if (this._tts instanceof WebSpeechTTS) {
+      this._tts.stop();
+    } else if (this._tts?.isConnected) {
       this._tts.close();
     }
   }
@@ -4929,7 +5931,7 @@ var VoicePipeline = class {
       try {
         cb(next, prev);
       } catch (err) {
-        console.error(LOG_PREFIX8, "State change callback threw:", err);
+        console.error(LOG_PREFIX11, "State change callback threw:", err);
       }
     }
   }
@@ -5060,7 +6062,7 @@ var VoicePipeline = class {
       try {
         cb(text, isFinal);
       } catch (err) {
-        console.error(LOG_PREFIX8, "Transcript callback threw:", err);
+        console.error(LOG_PREFIX11, "Transcript callback threw:", err);
       }
     }
     if (isFinal && this._state === "listening") {
@@ -5163,8 +6165,14 @@ var VoicePipeline = class {
    * sequential playback via AudioBufferSourceNode.
    */
   _decodeAndSchedule(audioData, onDone) {
+    let onDoneCalled = false;
+    const safeOnDone = onDone ? () => {
+      if (onDoneCalled) return;
+      onDoneCalled = true;
+      onDone();
+    } : void 0;
     if (!this._audioContext || this._state !== "speaking") {
-      onDone?.();
+      safeOnDone?.();
       return;
     }
     const ctx = this._audioContext;
@@ -5173,7 +6181,7 @@ var VoicePipeline = class {
       copy,
       (decodedBuffer) => {
         if (this._state !== "speaking" || !this._audioContext) {
-          onDone?.();
+          safeOnDone?.();
           return;
         }
         const source = ctx.createBufferSource();
@@ -5186,8 +6194,8 @@ var VoicePipeline = class {
           if (this._lastScheduledSource === source) {
             this._lastScheduledSource = null;
           }
-          if (onDone) {
-            onDone();
+          if (safeOnDone) {
+            safeOnDone();
           }
         };
         const now = ctx.currentTime;
@@ -5203,7 +6211,7 @@ var VoicePipeline = class {
       },
       (err) => {
         this._log("Failed to decode audio chunk:", err);
-        onDone?.();
+        safeOnDone?.();
       }
     );
   }
@@ -5262,13 +6270,13 @@ var VoicePipeline = class {
   // ════════════════════════════════════════════════════════════════════
   _log(...args) {
     if (this._debug) {
-      console.debug(LOG_PREFIX8, ...args);
+      console.debug(LOG_PREFIX11, ...args);
     }
   }
 };
 
 // src/visual/index.ts
-var LOG_PREFIX9 = "[GuideKit:Visual]";
+var LOG_PREFIX12 = "[GuideKit:Visual]";
 var DEFAULT_OVERLAY_COLOR = "rgba(0, 0, 0, 0.5)";
 var DEFAULT_SPOTLIGHT_COLOR = "#4a9eed";
 var DEFAULT_ANIMATION_DURATION = 300;
@@ -6185,16 +7193,16 @@ var VisualGuidance = class {
     if (!this.debug) return;
     if (typeof console !== "undefined") {
       if (data) {
-        console.log(`${LOG_PREFIX9} ${message}`, data);
+        console.log(`${LOG_PREFIX12} ${message}`, data);
       } else {
-        console.log(`${LOG_PREFIX9} ${message}`);
+        console.log(`${LOG_PREFIX12} ${message}`);
       }
     }
   }
 };
 
 // src/awareness/index.ts
-var LOG_PREFIX10 = "[GuideKit:Awareness]";
+var LOG_PREFIX13 = "[GuideKit:Awareness]";
 var DEFAULT_IDLE_TIMEOUT_MS = 6e4;
 var DEFAULT_DWELL_TIMEOUT_MS = 8e3;
 var DEFAULT_RAGE_CLICK_THRESHOLD = 3;
@@ -6556,13 +7564,13 @@ var AwarenessSystem = class {
   /** Conditional debug logging. */
   log(...args) {
     if (this.debugEnabled) {
-      console.debug(LOG_PREFIX10, ...args);
+      console.debug(LOG_PREFIX13, ...args);
     }
   }
 };
 
 // src/awareness/proactive.ts
-var LOG_PREFIX11 = "[GuideKit:Proactive]";
+var LOG_PREFIX14 = "[GuideKit:Proactive]";
 var STORAGE_KEY = "guidekit:visited";
 var SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1e3;
 var DWELL_COOLDOWNS = [3e4, 6e4, 12e4];
@@ -6600,7 +7608,7 @@ var ProactiveTriggerEngine = class {
   set quietMode(value) {
     this._quietMode = value;
     if (this.debug) {
-      console.debug(LOG_PREFIX11, `Quiet mode ${value ? "enabled" : "disabled"}`);
+      console.debug(LOG_PREFIX14, `Quiet mode ${value ? "enabled" : "disabled"}`);
     }
   }
   // ---- Lifecycle -----------------------------------------------------------
@@ -6630,7 +7638,7 @@ var ProactiveTriggerEngine = class {
       })
     );
     if (this.debug) {
-      console.debug(LOG_PREFIX11, "Started \u2014 subscribed to awareness & dom events");
+      console.debug(LOG_PREFIX14, "Started \u2014 subscribed to awareness & dom events");
     }
   }
   /** Unsubscribe all bus listeners and clear internal state. */
@@ -6645,7 +7653,7 @@ var ProactiveTriggerEngine = class {
     this.formTimers.clear();
     this.started = false;
     if (this.debug) {
-      console.debug(LOG_PREFIX11, "Stopped \u2014 all listeners removed");
+      console.debug(LOG_PREFIX14, "Stopped \u2014 all listeners removed");
     }
   }
   /** Alias for {@link stop}. */
@@ -6680,7 +7688,7 @@ var ProactiveTriggerEngine = class {
     }, FORM_ABANDON_MS);
     this.formTimers.set(formSelector, timer);
     if (this.debug) {
-      console.debug(LOG_PREFIX11, `Form interaction started: ${formSelector}`);
+      console.debug(LOG_PREFIX14, `Form interaction started: ${formSelector}`);
     }
   }
   /** Reset all cooldowns and internal tracking state (useful for testing). */
@@ -6694,7 +7702,7 @@ var ProactiveTriggerEngine = class {
     }
     this.formTimers.clear();
     if (this.debug) {
-      console.debug(LOG_PREFIX11, "All cooldowns and state reset");
+      console.debug(LOG_PREFIX14, "All cooldowns and state reset");
     }
   }
   // ---- Internal handlers ---------------------------------------------------
@@ -6711,22 +7719,23 @@ var ProactiveTriggerEngine = class {
           message: "First-time visitor detected. Show a visual greeting (no audio)."
         }, "greeting");
         if (this.debug) {
-          console.debug(LOG_PREFIX11, "First visit \u2014 greeting triggered");
+          console.debug(LOG_PREFIX14, "First visit \u2014 greeting triggered");
         }
         return;
       }
       const visitedAt = parseInt(visited, 10);
-      if (!Number.isNaN(visitedAt)) {
-        const elapsed = Date.now() - visitedAt;
-        if (elapsed <= SEVEN_DAYS_MS && this.debug) {
-          console.debug(LOG_PREFIX11, "Return visitor within 7 days \u2014 silent");
-        } else if (this.debug) {
-          console.debug(LOG_PREFIX11, "Return visitor after 7 days");
-        }
+      if (Number.isNaN(visitedAt)) {
+        return;
+      }
+      const elapsed = Date.now() - visitedAt;
+      if (elapsed <= SEVEN_DAYS_MS && this.debug) {
+        console.debug(LOG_PREFIX14, "Return visitor within 7 days \u2014 silent");
+      } else if (this.debug) {
+        console.debug(LOG_PREFIX14, "Return visitor after 7 days");
       }
     } catch {
       if (this.debug) {
-        console.warn(LOG_PREFIX11, "localStorage unavailable \u2014 skipping greeting check");
+        console.warn(LOG_PREFIX14, "localStorage unavailable \u2014 skipping greeting check");
       }
     }
   }
@@ -6744,7 +7753,7 @@ var ProactiveTriggerEngine = class {
     const count = this.dwellCounts.get(sectionId) ?? 0;
     if (count >= DWELL_COOLDOWNS.length + 1) {
       if (this.debug) {
-        console.debug(LOG_PREFIX11, `Dwell cap reached for section "${sectionId}" \u2014 suppressed`);
+        console.debug(LOG_PREFIX14, `Dwell cap reached for section "${sectionId}" \u2014 suppressed`);
       }
       return;
     }
@@ -6754,7 +7763,7 @@ var ProactiveTriggerEngine = class {
       const lastFired = this.cooldowns.get(key) ?? 0;
       if (Date.now() - lastFired < cooldownMs) {
         if (this.debug) {
-          console.debug(LOG_PREFIX11, `Dwell cooldown active for "${sectionId}" \u2014 suppressed`);
+          console.debug(LOG_PREFIX14, `Dwell cooldown active for "${sectionId}" \u2014 suppressed`);
         }
         return;
       }
@@ -6770,7 +7779,7 @@ var ProactiveTriggerEngine = class {
     const sectionKey = selector;
     if (this.frustrationFired.has(sectionKey)) {
       if (this.debug) {
-        console.debug(LOG_PREFIX11, `Frustration already fired for "${selector}" \u2014 suppressed`);
+        console.debug(LOG_PREFIX14, `Frustration already fired for "${selector}" \u2014 suppressed`);
       }
       return;
     }
@@ -6786,7 +7795,7 @@ var ProactiveTriggerEngine = class {
     const key = "navigation-commentary";
     if (this.isCooldownActive(key, NAVIGATION_COOLDOWN_MS)) {
       if (this.debug) {
-        console.debug(LOG_PREFIX11, "Navigation cooldown active \u2014 suppressed");
+        console.debug(LOG_PREFIX14, "Navigation cooldown active \u2014 suppressed");
       }
       return;
     }
@@ -6809,7 +7818,7 @@ var ProactiveTriggerEngine = class {
   fireTrigger(partial, cooldownKey) {
     if (this._quietMode) {
       if (this.debug) {
-        console.debug(LOG_PREFIX11, `Quiet mode \u2014 suppressed trigger: ${partial.type}`);
+        console.debug(LOG_PREFIX14, `Quiet mode \u2014 suppressed trigger: ${partial.type}`);
       }
       return;
     }
@@ -6819,13 +7828,13 @@ var ProactiveTriggerEngine = class {
     };
     this.cooldowns.set(cooldownKey, trigger.timestamp);
     if (this.debug) {
-      console.debug(LOG_PREFIX11, "Trigger fired:", trigger.type, trigger);
+      console.debug(LOG_PREFIX14, "Trigger fired:", trigger.type, trigger);
     }
     if (this.onTrigger) {
       try {
         this.onTrigger(trigger);
       } catch (err) {
-        console.error(LOG_PREFIX11, "onTrigger callback error:", err);
+        console.error(LOG_PREFIX14, "onTrigger callback error:", err);
       }
     }
   }
@@ -6838,7 +7847,7 @@ var ProactiveTriggerEngine = class {
 };
 
 // src/llm/rate-limiter.ts
-var LOG_PREFIX12 = "[GuideKit:RateLimiter]";
+var LOG_PREFIX15 = "[GuideKit:RateLimiter]";
 var DEFAULT_MAX_LLM_CALLS_PER_MINUTE = 10;
 var DEFAULT_MAX_STT_MINUTES_PER_SESSION = 60;
 var DEFAULT_MAX_TTS_CHARS_PER_SESSION = 5e4;
@@ -6933,7 +7942,19 @@ var RateLimiter = class {
   get sttMinutesUsed() {
     let totalMs = this.sttMs;
     if (this.sttStartedAt !== null) {
-      totalMs += Date.now() - this.sttStartedAt;
+      const activeMs = Date.now() - this.sttStartedAt;
+      const maxSessionMs = this.maxSTTMinutesPerSession * 6e4;
+      const maxActiveMs = maxSessionMs * 2;
+      if (activeMs > maxActiveMs) {
+        console.warn(
+          `${LOG_PREFIX15} STT stream running for ${Math.round(activeMs / 6e4)}min without sttStop() \u2014 capping at 2x session limit (${this.maxSTTMinutesPerSession * 2}min).`
+        );
+        this.sttMs += maxActiveMs;
+        this.sttStartedAt = null;
+        totalMs = this.sttMs;
+      } else {
+        totalMs += activeMs;
+      }
     }
     return totalMs / 6e4;
   }
@@ -7005,7 +8026,7 @@ var RateLimiter = class {
   }
   log(...args) {
     if (this.debug) {
-      console.debug(LOG_PREFIX12, ...args);
+      console.debug(LOG_PREFIX15, ...args);
     }
   }
 };
@@ -7238,7 +8259,7 @@ var BUILTIN_LOCALES = {
   pt
 };
 var SUPPORTED_LOCALE_CODES = new Set(Object.keys(BUILTIN_LOCALES));
-var LOG_PREFIX13 = "[GuideKit:I18n]";
+var LOG_PREFIX16 = "[GuideKit:I18n]";
 function isSupportedLocale(code) {
   return SUPPORTED_LOCALE_CODES.has(code);
 }
@@ -7276,7 +8297,7 @@ var I18n = class {
     this.strings = strings;
     this.resolvedLocale = resolvedLocale;
     if (this.debug) {
-      console.debug(`${LOG_PREFIX13} Initialized with locale "${this.resolvedLocale}"`);
+      console.debug(`${LOG_PREFIX16} Initialized with locale "${this.resolvedLocale}"`);
     }
   }
   // -------------------------------------------------------------------------
@@ -7287,9 +8308,9 @@ var I18n = class {
     const value = this.strings[key];
     if (value === void 0) {
       if (this.debug) {
-        console.warn(`${LOG_PREFIX13} Missing translation key "${key}"`);
+        console.warn(`${LOG_PREFIX16} Missing translation key "${key}"`);
       }
-      return en[key] ?? key;
+      return en[key] ?? (typeof process !== "undefined" && process.env?.NODE_ENV === "production" ? key : `[MISSING: ${key}]`);
     }
     return value;
   }
@@ -7303,7 +8324,7 @@ var I18n = class {
     this.strings = strings;
     this.resolvedLocale = resolvedLocale;
     if (this.debug) {
-      console.debug(`${LOG_PREFIX13} Locale changed to "${this.resolvedLocale}"`);
+      console.debug(`${LOG_PREFIX16} Locale changed to "${this.resolvedLocale}"`);
     }
   }
   /** The current resolved locale code (e.g. 'en', 'fr', or 'custom'). */
@@ -7323,7 +8344,7 @@ var I18n = class {
     if (locale === "auto") {
       const detected = detectLocaleFromDocument();
       if (this.debug) {
-        console.debug(`${LOG_PREFIX13} Auto-detected locale "${detected}"`);
+        console.debug(`${LOG_PREFIX16} Auto-detected locale "${detected}"`);
       }
       return {
         strings: BUILTIN_LOCALES[detected],
@@ -7338,7 +8359,7 @@ var I18n = class {
     }
     if (this.debug) {
       console.warn(
-        `${LOG_PREFIX13} Unknown locale "${String(locale)}", falling back to "en"`
+        `${LOG_PREFIX16} Unknown locale "${String(locale)}", falling back to "en"`
       );
     }
     return {
@@ -7349,7 +8370,7 @@ var I18n = class {
 };
 
 // src/auth/token-manager.ts
-var LOG_PREFIX14 = "[GuideKit:Auth]";
+var LOG_PREFIX17 = "[GuideKit:Auth]";
 var REFRESH_THRESHOLD = 0.8;
 var MAX_RETRY_ATTEMPTS = 3;
 var RETRY_BASE_MS = 1e3;
@@ -7628,7 +8649,7 @@ var TokenManager = class {
   }
   log(message) {
     if (this.debug) {
-      console.debug(`${LOG_PREFIX14} ${message}`);
+      console.debug(`${LOG_PREFIX17} ${message}`);
     }
   }
 };
@@ -7760,6 +8781,11 @@ var GuideKitCore = class {
         debug: this._debug
       });
       await this.tokenManager.start();
+      if (!this._options.llm) {
+        console.warn(
+          "[GuideKit] tokenEndpoint provided without llm config. The session token handles auth only \u2014 llm: { provider, apiKey } is still required for LLM calls. See: https://guidekit.dev/docs/provider#token-endpoint"
+        );
+      }
       this.resourceManager.register({
         name: "token-manager",
         cleanup: () => this.tokenManager?.destroy()
@@ -7882,21 +8908,50 @@ var GuideKitCore = class {
       }
     });
     this.registerBuiltinTools();
-    if (this._options.stt && this._options.tts) {
-      const sttConfig = this._options.stt;
-      const ttsConfig = this._options.tts;
-      if (sttConfig.provider === "deepgram" && ttsConfig.provider === "elevenlabs") {
+    {
+      const sttConfig = this._options.stt ?? { provider: "web-speech" };
+      const ttsConfig = this._options.tts ?? { provider: "web-speech" };
+      let voiceSttConfig;
+      let voiceTtsConfig;
+      if (sttConfig.provider === "deepgram") {
+        voiceSttConfig = {
+          provider: "deepgram",
+          apiKey: sttConfig.apiKey,
+          model: sttConfig.model
+        };
+      } else if (sttConfig.provider === "elevenlabs") {
+        voiceSttConfig = {
+          provider: "elevenlabs",
+          apiKey: sttConfig.apiKey,
+          language: sttConfig.language
+        };
+      } else {
+        voiceSttConfig = {
+          provider: "web-speech",
+          language: sttConfig.language,
+          continuous: sttConfig.continuous,
+          interimResults: sttConfig.interimResults
+        };
+      }
+      if (ttsConfig.provider === "elevenlabs") {
+        voiceTtsConfig = {
+          provider: "elevenlabs",
+          apiKey: ttsConfig.apiKey,
+          voiceId: "voiceId" in ttsConfig ? ttsConfig.voiceId : void 0
+        };
+      } else {
+        voiceTtsConfig = {
+          provider: "web-speech",
+          voice: ttsConfig.voice,
+          rate: ttsConfig.rate,
+          pitch: ttsConfig.pitch,
+          language: ttsConfig.language
+        };
+      }
+      try {
         this.voicePipeline = new VoicePipeline({
-          sttConfig: {
-            provider: "deepgram",
-            apiKey: sttConfig.apiKey,
-            model: "model" in sttConfig ? sttConfig.model : void 0
-          },
-          ttsConfig: {
-            provider: "elevenlabs",
-            apiKey: ttsConfig.apiKey,
-            voiceId: "voiceId" in ttsConfig ? ttsConfig.voiceId : void 0
-          },
+          sttConfig: voiceSttConfig,
+          ttsConfig: voiceTtsConfig,
           debug: this._debug
         });
         this.voicePipeline.onStateChange((state, previous) => {
@@ -7929,6 +8984,11 @@ var GuideKitCore = class {
           name: "voice-pipeline",
           cleanup: () => this.voicePipeline?.destroy()
         });
+      } catch (_err) {
+        this.voicePipeline = null;
+        if (this._debug) {
+          console.debug("[GuideKit:Core] Voice pipeline unavailable in this environment");
+        }
       }
     }
     const session = this.contextManager.restoreSession();
@@ -8053,7 +9113,7 @@ var GuideKitCore = class {
       return responseText;
     } catch (error) {
       const err = error instanceof GuideKitError ? error : new GuideKitError({
-        code: "UNKNOWN",
+        code: ErrorCodes.UNKNOWN,
         message: error instanceof Error ? error.message : "Unknown error",
         recoverable: false,
         suggestion: "Check the console for details."
@@ -8309,172 +9369,11 @@ var GuideKitCore = class {
     };
   }
   /**
-   * Register all built-in tool handlers with the ToolExecutor.
-   * Called once during init() after VisualGuidance and all subsystems are ready.
+   * Unified built-in tool specifications — single source of truth for both
+   * tool definitions (sent to LLM) and handler registration.
    */
-  registerBuiltinTools() {
-    if (!this.toolExecutor) return;
-    this.toolExecutor.registerTool({
-      name: "highlight",
-      execute: async (args) => {
-        const sectionId = args.sectionId;
-        const selector = args.selector;
-        const tooltip = args.tooltip;
-        const position = args.position;
-        const result = this.highlight({ sectionId, selector, tooltip, position });
-        return { success: result };
-      }
-    });
-    this.toolExecutor.registerTool({
-      name: "dismissHighlight",
-      execute: async () => {
-        this.dismissHighlight();
-        return { success: true };
-      }
-    });
-    this.toolExecutor.registerTool({
-      name: "scrollToSection",
-      execute: async (args) => {
-        const sectionId = args.sectionId;
-        const offset = args.offset;
-        this.scrollToSection(sectionId, offset);
-        return { success: true };
-      }
-    });
-    this.toolExecutor.registerTool({
-      name: "navigate",
-      execute: async (args) => {
-        const href = args.href;
-        const result = await this.navigate(href);
-        return { success: result, navigatedTo: result ? href : null };
-      }
-    });
-    this.toolExecutor.registerTool({
-      name: "startTour",
-      execute: async (args) => {
-        const sectionIds = args.sectionIds;
-        const mode = args.mode ?? "manual";
-        this.startTour(sectionIds, mode);
-        return { success: true, steps: sectionIds.length };
-      }
-    });
-    this.toolExecutor.registerTool({
-      name: "readPageContent",
-      execute: async (args) => {
-        const sectionId = args.sectionId;
-        const query = args.query;
-        const model = this._currentPageModel;
-        if (!model) return { error: "No page model available" };
-        if (sectionId) {
-          const section = model.sections.find((s) => s.id === sectionId);
-          if (section) {
-            const contentMapResult = await this.contextManager.getContent(sectionId);
-            return {
-              sectionId: section.id,
-              label: section.label,
-              summary: section.summary,
-              contentMap: contentMapResult
-            };
-          }
-          return { error: `Section "${sectionId}" not found` };
-        }
-        if (query) {
-          const queryLower = query.toLowerCase();
-          const matches = model.sections.filter(
-            (s) => s.label?.toLowerCase().includes(queryLower) || s.summary?.toLowerCase().includes(queryLower)
-          );
-          return {
-            query,
-            results: matches.slice(0, 5).map((s) => ({
-              sectionId: s.id,
-              label: s.label,
-              snippet: s.summary?.slice(0, 200)
-            }))
-          };
-        }
-        return { error: "Provide either sectionId or query" };
-      }
-    });
-    this.toolExecutor.registerTool({
-      name: "getVisibleSections",
-      execute: async () => {
-        const model = this._currentPageModel;
-        if (!model) return { sections: [] };
-        return {
-          sections: model.sections.slice(0, 10).map((s) => ({
-            id: s.id,
-            label: s.label,
-            selector: s.selector,
-            score: s.score
-          }))
-        };
-      }
-    });
-    this.toolExecutor.registerTool({
-      name: "clickElement",
-      execute: async (args) => {
-        if (typeof document === "undefined") return { success: false, error: "Not in browser" };
-        const selector = args.selector;
-        const el = document.querySelector(selector);
-        if (!el) return { success: false, error: `Element not found: ${selector}` };
-        if (!(el instanceof HTMLElement)) return { success: false, error: "Element is not clickable" };
-        const clickableRules = this._options.options?.clickableSelectors;
-        const isInDevAllowList = clickableRules?.allow?.some((pattern) => {
-          try {
-            return el.matches(pattern);
-          } catch {
-            return selector === pattern;
-          }
-        }) ?? false;
-        if (!isInDevAllowList) {
-          const defaultDenied = DEFAULT_CLICK_DENY.some((pattern) => {
-            try {
-              return el.matches(pattern);
-            } catch {
-              return false;
-            }
-          });
-          if (defaultDenied) {
-            return { success: false, error: `Selector "${selector}" matches the default deny list. Add it to clickableSelectors.allow to override.` };
-          }
-        }
-        if (clickableRules?.deny?.length) {
-          const denied = clickableRules.deny.some((pattern) => {
-            try {
-              return el.matches(pattern);
-            } catch {
-              return selector === pattern;
-            }
-          });
-          if (denied) {
-            return { success: false, error: `Selector "${selector}" is blocked by the deny list.` };
-          }
-        }
-        if (clickableRules?.allow?.length && !isInDevAllowList) {
-          return { success: false, error: `Selector "${selector}" is not in the allowed clickable selectors list.` };
-        }
-        el.click();
-        return { success: true };
-      }
-    });
-    this.toolExecutor.registerTool({
-      name: "executeCustomAction",
-      execute: async (args) => {
-        const actionId = args.actionId;
-        const params = args.params ?? {};
-        const action = this.customActions.get(actionId);
-        if (!action) return { error: `Unknown action: ${actionId}` };
-        try {
-          const result = await action.handler(params);
-          return { success: true, result };
-        } catch (err) {
-          return { success: false, error: err instanceof Error ? err.message : String(err) };
-        }
-      }
-    });
-  }
-  getToolDefinitions() {
-    const builtinTools = [
+  getBuiltinToolSpecs() {
+    return [
       {
         name: "highlight",
         description: "Spotlight an element on the page to draw the user's attention. Use sectionId to highlight a page section, or selector for a specific CSS selector. Optionally add a tooltip with explanation text.",
@@ -8484,13 +9383,27 @@ var GuideKitCore = class {
           tooltip: { type: "string", description: "Text to show in tooltip" },
           position: { type: "string", enum: ["top", "bottom", "left", "right", "auto"], description: "Tooltip position" }
         },
-        schemaVersion: 1
+        required: [],
+        schemaVersion: 1,
+        execute: async (args) => {
+          const sectionId = args.sectionId;
+          const selector = args.selector;
+          const tooltip = args.tooltip;
+          const position = args.position;
+          const result = this.highlight({ sectionId, selector, tooltip, position });
+          return { success: result };
+        }
       },
       {
         name: "dismissHighlight",
         description: "Remove the current spotlight overlay.",
         parameters: {},
-        schemaVersion: 1
+        required: [],
+        schemaVersion: 1,
+        execute: async () => {
+          this.dismissHighlight();
+          return { success: true };
+        }
       },
       {
         name: "scrollToSection",
@@ -8499,7 +9412,14 @@ var GuideKitCore = class {
           sectionId: { type: "string", description: "ID of the section to scroll to" },
           offset: { type: "number", description: "Pixel offset for sticky headers" }
         },
-        schemaVersion: 1
+        required: ["sectionId"],
+        schemaVersion: 1,
+        execute: async (args) => {
+          const sectionId = args.sectionId;
+          const offset = args.offset;
+          this.scrollToSection(sectionId, offset);
+          return { success: true };
+        }
       },
       {
         name: "navigate",
@@ -8507,7 +9427,13 @@ var GuideKitCore = class {
         parameters: {
           href: { type: "string", description: "URL or path to navigate to (same-origin only)" }
         },
-        schemaVersion: 1
+        required: ["href"],
+        schemaVersion: 1,
+        execute: async (args) => {
+          const href = args.href;
+          const result = await this.navigate(href);
+          return { success: result, navigatedTo: result ? href : null };
+        }
       },
       {
         name: "startTour",
@@ -8516,7 +9442,14 @@ var GuideKitCore = class {
           sectionIds: { type: "array", items: { type: "string" }, description: "Section IDs in tour order" },
           mode: { type: "string", enum: ["auto", "manual"], description: "auto advances automatically; manual waits for user" }
         },
-        schemaVersion: 1
+        required: ["sectionIds"],
+        schemaVersion: 1,
+        execute: async (args) => {
+          const sectionIds = args.sectionIds;
+          const mode = args.mode ?? "manual";
+          this.startTour(sectionIds, mode);
+          return { success: true, steps: sectionIds.length };
+        }
       },
       {
         name: "readPageContent",
@@ -8525,13 +9458,61 @@ var GuideKitCore = class {
           sectionId: { type: "string", description: "Section ID to read" },
           query: { type: "string", description: "Keyword to search for across sections" }
         },
-        schemaVersion: 1
+        required: [],
+        schemaVersion: 1,
+        execute: async (args) => {
+          const sectionId = args.sectionId;
+          const query = args.query;
+          const model = this._currentPageModel;
+          if (!model) return { error: "No page model available" };
+          if (sectionId) {
+            const section = model.sections.find((s) => s.id === sectionId);
+            if (section) {
+              const contentMapResult = await this.contextManager.getContent(sectionId);
+              return {
+                sectionId: section.id,
+                label: section.label,
+                summary: section.summary,
+                contentMap: contentMapResult
+              };
+            }
+            return { error: `Section "${sectionId}" not found` };
+          }
+          if (query) {
+            const queryLower = query.toLowerCase();
+            const matches = model.sections.filter(
+              (s) => s.label?.toLowerCase().includes(queryLower) || s.summary?.toLowerCase().includes(queryLower)
+            );
+            return {
+              query,
+              results: matches.slice(0, 5).map((s) => ({
+                sectionId: s.id,
+                label: s.label,
+                snippet: s.summary?.slice(0, 200)
+              }))
+            };
+          }
+          return { error: "Provide either sectionId or query" };
+        }
       },
       {
         name: "getVisibleSections",
         description: "Get the list of sections currently visible in the user viewport.",
         parameters: {},
-        schemaVersion: 1
+        required: [],
+        schemaVersion: 1,
+        execute: async () => {
+          const model = this._currentPageModel;
+          if (!model) return { sections: [] };
+          return {
+            sections: model.sections.slice(0, 10).map((s) => ({
+              id: s.id,
+              label: s.label,
+              selector: s.selector,
+              score: s.score
+            }))
+          };
+        }
       },
       {
         name: "clickElement",
@@ -8539,7 +9520,52 @@ var GuideKitCore = class {
         parameters: {
           selector: { type: "string", description: "CSS selector of the element to click" }
         },
-        schemaVersion: 1
+        required: ["selector"],
+        schemaVersion: 1,
+        execute: async (args) => {
+          if (typeof document === "undefined") return { success: false, error: "Not in browser" };
+          const selector = args.selector;
+          const el = document.querySelector(selector);
+          if (!el) return { success: false, error: `Element not found: ${selector}` };
+          if (!(el instanceof HTMLElement)) return { success: false, error: "Element is not clickable" };
+          const clickableRules = this._options.options?.clickableSelectors;
+          const isInDevAllowList = clickableRules?.allow?.some((pattern) => {
+            try {
+              return el.matches(pattern);
+            } catch {
+              return selector === pattern;
+            }
+          }) ?? false;
+          if (!isInDevAllowList) {
+            const defaultDenied = DEFAULT_CLICK_DENY.some((pattern) => {
+              try {
+                return el.matches(pattern);
+              } catch {
+                return false;
+              }
+            });
+            if (defaultDenied) {
+              return { success: false, error: `Selector "${selector}" matches the default deny list. Add it to clickableSelectors.allow to override.` };
+            }
+          }
+          if (clickableRules?.deny?.length) {
+            const denied = clickableRules.deny.some((pattern) => {
+              try {
+                return el.matches(pattern);
+              } catch {
+                return selector === pattern;
+              }
+            });
+            if (denied) {
+              return { success: false, error: `Selector "${selector}" is blocked by the deny list.` };
+            }
+          }
+          if (clickableRules?.allow?.length && !isInDevAllowList) {
+            return { success: false, error: `Selector "${selector}" is not in the allowed clickable selectors list.` };
+          }
+          el.click();
+          return { success: true };
+        }
       },
       {
         name: "executeCustomAction",
@@ -8548,9 +9574,37 @@ var GuideKitCore = class {
           actionId: { type: "string", description: "ID of the custom action" },
           params: { type: "object", description: "Parameters for the action" }
         },
-        schemaVersion: 1
+        required: ["actionId"],
+        schemaVersion: 1,
+        execute: async (args) => {
+          const actionId = args.actionId;
+          const params = args.params ?? {};
+          const action = this.customActions.get(actionId);
+          if (!action) return { error: `Unknown action: ${actionId}` };
+          try {
+            const result = await action.handler(params);
+            return { success: true, result };
+          } catch (err) {
+            return { success: false, error: err instanceof Error ? err.message : String(err) };
+          }
+        }
       }
     ];
+  }
+  /**
+   * Register all built-in tool handlers with the ToolExecutor.
+   * Called once during init() after VisualGuidance and all subsystems are ready.
+   */
+  registerBuiltinTools() {
+    if (!this.toolExecutor) return;
+    for (const spec of this.getBuiltinToolSpecs()) {
+      this.toolExecutor.registerTool({ name: spec.name, execute: spec.execute });
+    }
+  }
+  getToolDefinitions() {
+    const builtinTools = this.getBuiltinToolSpecs().map(
+      ({ execute: _execute, ...def }) => def
+    );
     for (const [actionId, action] of this.customActions) {
       builtinTools.push({
         name: `action_${actionId}`,
@@ -8563,6 +9617,6 @@ var GuideKitCore = class {
   }
 };
 
-export { AuthenticationError, AwarenessSystem, BrowserSupportError, ConfigurationError, ConnectionManager, ContentFilterError, ContextManager, DOMScanner, ErrorCodes, EventBus, GeminiAdapter, GuideKitCore, GuideKitError, I18n, InitializationError, LLMOrchestrator, NavigationController, NetworkError, OpenAIAdapter, PermissionError, ProactiveTriggerEngine, RateLimitError, RateLimiter, ResourceExhaustedError, ResourceManager, SingletonGuard, TimeoutError, TokenManager, ToolExecutor, VisualGuidance, createEventBus, isGuideKitError };
+export { AuthenticationError, AwarenessSystem, BrowserSupportError, ConfigurationError, ConnectionManager, ContentFilterError, ContextManager, DOMScanner, ErrorCodes, EventBus, GeminiAdapter, GuideKitCore, GuideKitError, I18n, InitializationError, LLMOrchestrator, NavigationController, NetworkError, OpenAIAdapter, PermissionError, ProactiveTriggerEngine, RateLimitError, RateLimiter, ResourceExhaustedError, ResourceManager, SingletonGuard, TimeoutError, TokenManager, ToolExecutor, VisualGuidance, VoicePipeline, WebSpeechSTT, WebSpeechTTS, createEventBus, isGuideKitError };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map