@guidekit/vanilla 0.1.0-beta.1 → 0.1.0-beta.3

package/dist/index.global.js

@@ -2170,7 +2170,7 @@ var GuideKit = (() => {
     "../vad/dist/index.js"() {
       "use strict";
       init_ort_node_min();
-      VAD_VERSION = "0.1.0";
+      VAD_VERSION = "0.1.0-beta.2";
       LOG_PREFIX = "[GuideKit:VAD]";
       DEFAULT_MODEL_URL = "https://cdn.jsdelivr.net/npm/@ricky0123/vad-web@0.0.20/dist/silero_vad_v5.onnx";
       CACHE_NAME = `guidekit-vad-v${VAD_VERSION}`;
@@ -2298,8 +2298,8 @@ var GuideKit = (() => {
           const feeds = {
             input: inputTensor,
             sr: srTensor,
-            h: this._h,
-            c: this._c
+            h0: this._h,
+            c0: this._c
           };
           const results = await this._session.run(feeds);
           this._h = results["hn"];
@@ -2330,9 +2330,9 @@ var GuideKit = (() => {
           this._resetStates();
           this._isCalibrating = true;
           this._calibrationSamples = [];
-          this._calibrationFramesNeeded = Math.ceil(
+          this._calibrationFramesNeeded = Math.max(1, Math.floor(
             CALIBRATION_DURATION_MS / 1e3 * this._sampleRate / FRAME_SIZE
-          );
+          ));
           this._log("Calibrating noise floor for", this._calibrationFramesNeeded, "frames");
           this._setupAudioPipeline(stream);
         }
@@ -3729,8 +3729,8 @@ var GuideKit = (() => {
         if (el.closest("[data-guidekit-ignore]")) return;
         const style = window.getComputedStyle(el);
         const position = style.position;
-        const zIndex = parseInt(style.zIndex, 10);
-        if ((position === "fixed" || position === "absolute") && !isNaN(zIndex) && zIndex >= 1e3) {
+        const zIndex = parseInt(style.zIndex, 10) || 0;
+        if ((position === "fixed" || position === "absolute") && !Number.isNaN(zIndex) && zIndex >= 1e3) {
           const visible = isElementVisible(el);
           if (!visible) return;
           const overlayType = this.classifyOverlay(el, style);
@@ -3758,10 +3758,10 @@ var GuideKit = (() => {
         return "dropdown";
       const width = parseFloat(style.width);
       const height = parseFloat(style.height);
-      if (typeof window !== "undefined" && !isNaN(width) && !isNaN(height) && width > window.innerWidth * 0.5 && height > window.innerHeight * 0.5) {
+      if (typeof window !== "undefined" && !Number.isNaN(width) && !Number.isNaN(height) && width > window.innerWidth * 0.5 && height > window.innerHeight * 0.5) {
         return "modal";
       }
-      if (!isNaN(width) && width < 400) return "popover";
+      if (!Number.isNaN(width) && width < 400) return "popover";
       return null;
     }
     // -------------------------------------------------------------------------
@@ -4382,7 +4382,9 @@ ${recapLines.join("\n")}`,
     // 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;
@@ -4461,353 +4463,8 @@ ${recapLines.join("\n")}`,
       this.name = "ContentFilterError";
     }
   };
-  var DEFAULT_OPENAI_MODEL = "gpt-4o";
-  var DEFAULT_TIMEOUT_MS = 15e3;
-  var OPENAI_CHAT_URL = "https://api.openai.com/v1/chat/completions";
-  var OpenAIAdapter = class {
-    apiKey;
-    model;
-    constructor(config) {
-      this.apiKey = config.apiKey;
-      this.model = config.model ?? DEFAULT_OPENAI_MODEL;
-    }
-    // -----------------------------------------------------------------------
-    // LLMProviderAdapter implementation
-    // -----------------------------------------------------------------------
-    /**
-     * Convert GuideKit tool definitions into OpenAI's `tools` format.
-     * Each tool is wrapped as `{ type: 'function', function: { name, description, parameters } }`.
-     */
-    formatTools(tools) {
-      if (tools.length === 0) return void 0;
-      return tools.map((tool) => ({
-        type: "function",
-        function: {
-          name: tool.name,
-          description: tool.description,
-          parameters: tool.parameters
-        }
-      }));
-    }
-    /**
-     * Convert an array of `ConversationTurn` objects into OpenAI's messages
-     * format with `role: 'user' | 'assistant'`.
-     */
-    formatConversation(history) {
-      return history.map((turn) => ({
-        role: turn.role,
-        content: turn.content
-      }));
-    }
-    /**
-     * Parse an OpenAI SSE streaming response into an async iterable of
-     * `TextChunk` and `ToolCall` objects.
-     *
-     * The OpenAI streaming endpoint sends each chunk as a JSON object
-     * 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`.
-     */
-    async *parseResponse(stream) {
-      const reader = stream.getReader();
-      const decoder = new TextDecoder();
-      let buffer = "";
-      const pendingToolCalls = /* @__PURE__ */ new Map();
-      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]") {
-              if (jsonStr === "[DONE]") {
-                yield* this.flushPendingToolCalls(pendingToolCalls);
-                yield { text: "", done: true };
-              }
-              continue;
-            }
-            let parsed;
-            try {
-              parsed = JSON.parse(jsonStr);
-            } catch {
-              continue;
-            }
-            yield* this.extractChunks(parsed, pendingToolCalls);
-          }
-        }
-        if (buffer.trim().startsWith("data:")) {
-          const jsonStr = buffer.trim().slice(5).trim();
-          if (jsonStr === "[DONE]") {
-            yield* this.flushPendingToolCalls(pendingToolCalls);
-            yield { text: "", done: true };
-          } else if (jsonStr !== "") {
-            try {
-              const parsed = JSON.parse(jsonStr);
-              yield* this.extractChunks(parsed, pendingToolCalls);
-            } catch {
-            }
-          }
-        }
-        yield* this.flushPendingToolCalls(pendingToolCalls);
-      } finally {
-        reader.releaseLock();
-      }
-    }
-    /**
-     * Format a tool result so it can be sent back to OpenAI as a
-     * `tool` role message with the `tool_call_id`.
-     */
-    formatToolResult(callId, result) {
-      return {
-        role: "tool",
-        tool_call_id: callId,
-        content: typeof result === "string" ? result : JSON.stringify(result)
-      };
-    }
-    // -----------------------------------------------------------------------
-    // Streaming request
-    // -----------------------------------------------------------------------
-    /**
-     * Build and execute a streaming request to the OpenAI Chat Completions API.
-     * Returns the raw `ReadableStream` for the response body together with
-     * the raw Response object.
-     */
-    async streamRequest(params) {
-      const messages = [
-        { role: "system", content: params.systemPrompt },
-        ...params.contents
-      ];
-      const body = {
-        model: this.model,
-        messages,
-        stream: true,
-        temperature: 0.7,
-        top_p: 0.95
-      };
-      if (params.tools) {
-        body.tools = params.tools;
-      }
-      const timeoutMs = params.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-      const controller = new AbortController();
-      const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
-      if (params.signal) {
-        params.signal.addEventListener(
-          "abort",
-          () => controller.abort(params.signal.reason),
-          { once: true }
-        );
-      }
-      let response;
-      try {
-        response = await fetch(OPENAI_CHAT_URL, {
-          method: "POST",
-          headers: {
-            "Content-Type": "application/json",
-            Authorization: `Bearer ${this.apiKey}`
-          },
-          body: JSON.stringify(body),
-          signal: controller.signal
-        });
-      } catch (error) {
-        clearTimeout(timeoutId);
-        if (error instanceof DOMException && error.name === "AbortError") {
-          if (params.signal?.aborted) {
-            throw error;
-          }
-          throw new TimeoutError({
-            code: ErrorCodes.TIMEOUT_LLM_RESPONSE,
-            message: `OpenAI request timed out after ${timeoutMs}ms`,
-            provider: "openai",
-            recoverable: true,
-            suggestion: "Try again or increase the timeout.",
-            operationName: "openai.chatCompletions",
-            timeoutMs
-          });
-        }
-        throw new NetworkError({
-          code: ErrorCodes.NETWORK_CONNECTION_LOST,
-          message: `Failed to connect to OpenAI API: ${error.message}`,
-          provider: "openai",
-          suggestion: "Check your network connection and try again.",
-          cause: error instanceof Error ? error : void 0
-        });
-      }
-      clearTimeout(timeoutId);
-      if (!response.ok) {
-        await this.handleHttpError(response);
-      }
-      if (!response.body) {
-        throw new NetworkError({
-          code: ErrorCodes.NETWORK_CONNECTION_LOST,
-          message: "OpenAI response body is null -- streaming unavailable.",
-          provider: "openai",
-          suggestion: "Retry the request."
-        });
-      }
-      return { stream: response.body, response };
-    }
-    // -----------------------------------------------------------------------
-    // Internal helpers
-    // -----------------------------------------------------------------------
-    /**
-     * Extract `TextChunk` and accumulate `ToolCall` data from a single parsed
-     * OpenAI SSE JSON object.
-     *
-     * OpenAI tool calls arrive incrementally: the first chunk for a tool call
-     * carries the `id` and `function.name`, while subsequent chunks append to
-     * `function.arguments`. We accumulate these in `pendingToolCalls` and only
-     * yield complete `ToolCall` objects when the finish_reason is 'tool_calls'
-     * or when flushed.
-     */
-    *extractChunks(parsed, pendingToolCalls) {
-      const choices = parsed.choices;
-      if (!choices || choices.length === 0) return;
-      for (const choice of choices) {
-        const delta = choice.delta;
-        const finishReason = choice.finish_reason;
-        if (delta) {
-          if (typeof delta.content === "string" && delta.content !== "") {
-            yield {
-              text: delta.content,
-              done: false
-            };
-          }
-          const toolCallDeltas = delta.tool_calls;
-          if (toolCallDeltas) {
-            for (const tc of toolCallDeltas) {
-              const existing = pendingToolCalls.get(tc.index);
-              if (existing) {
-                if (tc.function?.arguments) {
-                  existing.argumentsJson += tc.function.arguments;
-                }
-              } else {
-                pendingToolCalls.set(tc.index, {
-                  id: tc.id ?? "",
-                  name: tc.function?.name ?? "",
-                  argumentsJson: tc.function?.arguments ?? ""
-                });
-              }
-            }
-          }
-        }
-        if (finishReason === "tool_calls") {
-          yield* this.flushPendingToolCalls(pendingToolCalls);
-        }
-        if (finishReason === "stop") {
-          yield { text: "", done: true };
-        }
-      }
-    }
-    /**
-     * Flush all accumulated pending tool calls as complete `ToolCall` objects.
-     */
-    *flushPendingToolCalls(pendingToolCalls) {
-      const sorted = [...pendingToolCalls.entries()].sort(
-        ([a], [b]) => a - b
-      );
-      for (const [, tc] of sorted) {
-        let args = {};
-        try {
-          args = JSON.parse(tc.argumentsJson);
-        } catch {
-        }
-        yield {
-          id: tc.id,
-          name: tc.name,
-          arguments: args
-        };
-      }
-      pendingToolCalls.clear();
-    }
-    /**
-     * Extract token usage from a parsed OpenAI response chunk.
-     * Usage data typically appears in the final chunk when `stream_options`
-     * includes `include_usage`, or in the non-streaming response.
-     * Returns `null` if no usage data is present.
-     */
-    extractUsage(parsed) {
-      const usage = parsed.usage;
-      if (!usage) return null;
-      return {
-        prompt: usage.prompt_tokens ?? 0,
-        completion: usage.completion_tokens ?? 0,
-        total: usage.total_tokens ?? 0
-      };
-    }
-    /**
-     * Check whether a parsed OpenAI chunk indicates the response was
-     * blocked by a content filter.
-     *
-     * OpenAI signals content filtering through:
-     * - `choices[].finish_reason === 'content_filter'`
-     * - `choices[].content_filter_results` with `filtered: true`
-     */
-    isContentFiltered(parsed) {
-      const choices = parsed.choices;
-      if (!choices || choices.length === 0) return false;
-      return choices.some((choice) => {
-        if (choice.finish_reason === "content_filter") return true;
-        const filterResults = choice.content_filter_results;
-        if (filterResults) {
-          return Object.values(filterResults).some((r) => r.filtered === true);
-        }
-        return false;
-      });
-    }
-    /**
-     * Translate an HTTP error response from OpenAI into the appropriate
-     * GuideKit error class.
-     */
-    async handleHttpError(response) {
-      let errorBody = "";
-      try {
-        errorBody = await response.text();
-      } catch {
-      }
-      const status = response.status;
-      if (status === 401 || status === 403) {
-        throw new AuthenticationError({
-          code: ErrorCodes.AUTH_INVALID_KEY,
-          message: `OpenAI API authentication failed (${status}): ${errorBody}`,
-          provider: "openai",
-          suggestion: "Verify your OpenAI API key is correct and has not expired."
-        });
-      }
-      if (status === 429) {
-        const retryAfterHeader = response.headers.get("retry-after");
-        const retryAfterMs = retryAfterHeader ? parseInt(retryAfterHeader, 10) * 1e3 : 6e4;
-        throw new RateLimitError({
-          code: ErrorCodes.RATE_LIMIT_PROVIDER,
-          message: `OpenAI API rate limit exceeded (429): ${errorBody}`,
-          provider: "openai",
-          recoverable: true,
-          suggestion: `Rate limited by OpenAI. Retry after ${Math.ceil(retryAfterMs / 1e3)}s.`,
-          retryAfterMs
-        });
-      }
-      if (status >= 500) {
-        throw new NetworkError({
-          code: ErrorCodes.NETWORK_CONNECTION_LOST,
-          message: `OpenAI API server error (${status}): ${errorBody}`,
-          provider: "openai",
-          suggestion: "The OpenAI API is experiencing issues. Please try again later."
-        });
-      }
-      throw new NetworkError({
-        code: ErrorCodes.NETWORK_CONNECTION_LOST,
-        message: `OpenAI API request failed (${status}): ${errorBody}`,
-        provider: "openai",
-        suggestion: "Check the request parameters and try again."
-      });
-    }
-  };
   var DEFAULT_GEMINI_MODEL = "gemini-2.5-flash";
-  var DEFAULT_TIMEOUT_MS2 = 15e3;
+  var DEFAULT_TIMEOUT_MS = 15e3;
   var GEMINI_BASE_URL = "https://generativelanguage.googleapis.com/v1beta/models";
   var DEFAULT_SAFETY_SETTINGS = [
     { category: "HARM_CATEGORY_HARASSMENT", threshold: "BLOCK_ONLY_HIGH" },
@@ -4821,10 +4478,20 @@ ${recapLines.join("\n")}`,
   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 = emptyUsage();
     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
     // -----------------------------------------------------------------------
@@ -4839,7 +4506,11 @@ ${recapLines.join("\n")}`,
           functionDeclarations: tools.map((tool) => ({
             name: tool.name,
             description: tool.description,
-            parameters: tool.parameters
+            parameters: {
+              type: "object",
+              properties: { ...tool.parameters },
+              required: tool.required ?? []
+            }
           }))
         }
       ];
@@ -4861,11 +4532,16 @@ ${recapLines.join("\n")}`,
      * 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 = emptyUsage();
       try {
         while (true) {
           const { done, value } = await reader.read();
@@ -4884,6 +4560,18 @@ ${recapLines.join("\n")}`,
             } 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);
           }
         }
@@ -4892,8 +4580,21 @@ ${recapLines.join("\n")}`,
           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;
             }
           }
         }
@@ -4924,15 +4625,21 @@ ${recapLines.join("\n")}`,
     /**
      * 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,
@@ -4943,7 +4650,7 @@ ${recapLines.join("\n")}`,
       if (params.tools) {
         body.tools = params.tools;
       }
-      const timeoutMs = params.timeoutMs ?? DEFAULT_TIMEOUT_MS2;
+      const timeoutMs = params.timeoutMs ?? DEFAULT_TIMEOUT_MS;
       const controller = new AbortController();
       const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
       if (params.signal) {
@@ -5000,7 +4707,7 @@ ${recapLines.join("\n")}`,
       return { stream: response.body, response };
     }
     // -----------------------------------------------------------------------
-    // Internal helpers
+    // Public helpers (LLMProviderAdapter interface)
     // -----------------------------------------------------------------------
     /**
      * Extract `TextChunk` and `ToolCall` items from a single parsed Gemini
@@ -5173,7 +4880,8 @@ ${recapLines.join("\n")}`,
     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() {
@@ -5184,139 +4892,42 @@ ${recapLines.join("\n")}`,
     // -----------------------------------------------------------------------
     /**
      * 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 = [];
+      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);
+        }
+      }
+      this.callbacks.onChunk?.({ text: "", done: true });
       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 {
-            }
-          }
-        }
-      } 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 });
+      if ("lastUsage" in adapter) {
+        usage = adapter.lastUsage;
       }
       if (usage.total > 0) {
         this.callbacks.onTokenUsage?.(usage);
@@ -5328,25 +4939,30 @@ ${recapLines.join("\n")}`,
     }
     /**
      * 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: myCustomAdapter }`
      */
     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. */
@@ -5497,7 +5113,7 @@ ${recapLines.join("\n")}`,
           break;
         }
       }
-      if (rounds >= this.maxRounds && allToolCalls.length > 0) {
+      if (rounds >= this.maxRounds) {
         this.log(
           `Max rounds (${this.maxRounds}) reached. Returning current text.`
         );
@@ -5600,6 +5216,19 @@ ${recapLines.join("\n")}`,
           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,
@@ -6783,7 +6412,277 @@ ${callDescriptions}` : callDescriptions;
       }
     }
   };
-  var LOG_PREFIX7 = "[GuideKit:TTS]";
+  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 int16;
+  }
+  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;
+    language;
+    debugEnabled;
+    // ---- Internal state ------------------------------------------------------
+    wsManager = null;
+    _connected = false;
+    _suspended = false;
+    /** Registered transcript callbacks. */
+    transcriptCallbacks = /* @__PURE__ */ new Set();
+    // -------------------------------------------------------------------------
+    // Constructor
+    // -------------------------------------------------------------------------
+    constructor(options) {
+      this.apiKey = options.apiKey;
+      this.language = options.language ?? DEFAULT_LANGUAGE2;
+      this.debugEnabled = options.debug ?? false;
+      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 ElevenLabs' real-time STT endpoint.
+     *
+     * 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) {
+        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.replace(this.apiKey, "***"));
+      this.wsManager = new WebSocketManager({
+        url,
+        protocols: [],
+        debug: this.debugEnabled,
+        label: "ElevenLabs-STT"
+      });
+      this.wsManager.onOpen(() => {
+        this._connected = true;
+        this.log("Connected");
+      });
+      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 audio data to ElevenLabs for transcription.
+     *
+     * 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.
+     */
+    sendAudio(audioData) {
+      if (!this._connected || !this.wsManager || this._suspended) {
+        return;
+      }
+      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 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 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("Sending commit_audio and closing");
+      try {
+        this.wsManager.send(JSON.stringify({ type: "commit_audio" }));
+      } 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.transcriptCallbacks.clear();
+    }
+    /**
+     * Suspend the adapter (e.g. when the device goes offline).
+     *
+     * Marks the adapter as suspended so that incoming `sendAudio` calls are
+     * silently dropped. The WebSocket itself is left open.
+     */
+    suspend() {
+      if (this._suspended) return;
+      this._suspended = true;
+      this.log("Suspended");
+    }
+    /**
+     * Resume after a prior `suspend()`.
+     */
+    resume() {
+      if (!this._suspended) return;
+      this._suspended = false;
+      this.log("Resumed");
+    }
+    // -------------------------------------------------------------------------
+    // Message handling
+    // -------------------------------------------------------------------------
+    /**
+     * Parse incoming ElevenLabs JSON messages and emit transcript events.
+     *
+     * 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") {
+        return;
+      }
+      let parsed;
+      try {
+        parsed = JSON.parse(event.data);
+      } catch {
+        this.log("Failed to parse message", event.data);
+        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);
+      }
+    }
+  };
+  var LOG_PREFIX8 = "[GuideKit:TTS]";
   var DEFAULT_VOICE_ID = "21m00Tcm4TlvDq8ikWAM";
   var DEFAULT_MODEL_ID = "eleven_flash_v2_5";
   var DEFAULT_STABILITY = 0.5;
@@ -7025,47 +6924,701 @@ ${callDescriptions}` : callDescriptions;
         this.log("Failed to parse message", event.data);
         return;
       }
-      if (parsed["error"] !== void 0) {
-        this.log("ElevenLabs error:", parsed["error"]);
-        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);
+      }
+    }
+  };
+  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);
+      }
+    }
+  };
+  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.
      *
@@ -7077,39 +7630,28 @@ ${callDescriptions}` : callDescriptions;
         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);
       }
     }
   };
-  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;
@@ -7217,17 +7759,42 @@ ${callDescriptions}` : callDescriptions;
           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");
     }
     // ────────────────────────────────────────────────────────────────────
@@ -7367,10 +7934,11 @@ ${callDescriptions}` : callDescriptions;
     // ────────────────────────────────────────────────────────────────────
     // 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");
@@ -7414,11 +7982,24 @@ ${callDescriptions}` : callDescriptions;
           }
           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();
+        }
       });
     }
     // ────────────────────────────────────────────────────────────────────
@@ -7447,7 +8028,9 @@ ${callDescriptions}` : callDescriptions;
         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();
       }
     }
@@ -7536,7 +8119,7 @@ ${callDescriptions}` : callDescriptions;
         try {
           cb(next, prev);
         } catch (err) {
-          console.error(LOG_PREFIX8, "State change callback threw:", err);
+          console.error(LOG_PREFIX11, "State change callback threw:", err);
         }
       }
     }
@@ -7667,7 +8250,7 @@ ${callDescriptions}` : callDescriptions;
         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") {
@@ -7770,8 +8353,14 @@ ${callDescriptions}` : callDescriptions;
      * 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;
@@ -7780,7 +8369,7 @@ ${callDescriptions}` : callDescriptions;
         copy,
         (decodedBuffer) => {
           if (this._state !== "speaking" || !this._audioContext) {
-            onDone?.();
+            safeOnDone?.();
             return;
           }
           const source = ctx.createBufferSource();
@@ -7793,8 +8382,8 @@ ${callDescriptions}` : callDescriptions;
             if (this._lastScheduledSource === source) {
               this._lastScheduledSource = null;
             }
-            if (onDone) {
-              onDone();
+            if (safeOnDone) {
+              safeOnDone();
             }
           };
           const now = ctx.currentTime;
@@ -7810,7 +8399,7 @@ ${callDescriptions}` : callDescriptions;
         },
         (err) => {
           this._log("Failed to decode audio chunk:", err);
-          onDone?.();
+          safeOnDone?.();
         }
       );
     }
@@ -7869,11 +8458,11 @@ ${callDescriptions}` : callDescriptions;
     // ════════════════════════════════════════════════════════════════════
     _log(...args) {
       if (this._debug) {
-        console.debug(LOG_PREFIX8, ...args);
+        console.debug(LOG_PREFIX11, ...args);
       }
     }
   };
-  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;
@@ -8790,14 +9379,14 @@ ${callDescriptions}` : callDescriptions;
       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}`);
         }
       }
     }
   };
-  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;
@@ -9159,11 +9748,11 @@ ${callDescriptions}` : callDescriptions;
     /** Conditional debug logging. */
     log(...args) {
       if (this.debugEnabled) {
-        console.debug(LOG_PREFIX10, ...args);
+        console.debug(LOG_PREFIX13, ...args);
       }
     }
   };
-  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];
@@ -9201,7 +9790,7 @@ ${callDescriptions}` : callDescriptions;
     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 -----------------------------------------------------------
@@ -9231,7 +9820,7 @@ ${callDescriptions}` : callDescriptions;
         })
       );
       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. */
@@ -9246,7 +9835,7 @@ ${callDescriptions}` : callDescriptions;
       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}. */
@@ -9281,7 +9870,7 @@ ${callDescriptions}` : callDescriptions;
       }, 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). */
@@ -9295,7 +9884,7 @@ ${callDescriptions}` : callDescriptions;
       }
       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 ---------------------------------------------------
@@ -9312,22 +9901,23 @@ ${callDescriptions}` : callDescriptions;
             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");
         }
       }
     }
@@ -9345,7 +9935,7 @@ ${callDescriptions}` : callDescriptions;
       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;
       }
@@ -9355,7 +9945,7 @@ ${callDescriptions}` : callDescriptions;
         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;
         }
@@ -9371,7 +9961,7 @@ ${callDescriptions}` : callDescriptions;
       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;
       }
@@ -9387,7 +9977,7 @@ ${callDescriptions}` : callDescriptions;
       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;
       }
@@ -9410,7 +10000,7 @@ ${callDescriptions}` : callDescriptions;
     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;
       }
@@ -9420,13 +10010,13 @@ ${callDescriptions}` : callDescriptions;
       };
       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);
         }
       }
     }
@@ -9437,7 +10027,7 @@ ${callDescriptions}` : callDescriptions;
       return Date.now() - lastFired < cooldownMs;
     }
   };
-  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;
@@ -9532,7 +10122,19 @@ ${callDescriptions}` : callDescriptions;
     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;
     }
@@ -9604,7 +10206,7 @@ ${callDescriptions}` : callDescriptions;
     }
     log(...args) {
       if (this.debug) {
-        console.debug(LOG_PREFIX12, ...args);
+        console.debug(LOG_PREFIX15, ...args);
       }
     }
   };
@@ -9835,7 +10437,7 @@ ${callDescriptions}` : callDescriptions;
     pt: pt2
   };
   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);
   }
@@ -9873,7 +10475,7 @@ ${callDescriptions}` : callDescriptions;
       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}"`);
       }
     }
     // -------------------------------------------------------------------------
@@ -9884,9 +10486,9 @@ ${callDescriptions}` : callDescriptions;
       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;
     }
@@ -9900,7 +10502,7 @@ ${callDescriptions}` : callDescriptions;
       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'). */
@@ -9920,7 +10522,7 @@ ${callDescriptions}` : callDescriptions;
       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],
@@ -9935,7 +10537,7 @@ ${callDescriptions}` : callDescriptions;
       }
       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 {
@@ -9944,7 +10546,7 @@ ${callDescriptions}` : callDescriptions;
       };
     }
   };
-  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;
@@ -10223,7 +10825,7 @@ ${callDescriptions}` : callDescriptions;
     }
     log(message) {
       if (this.debug) {
-        console.debug(`${LOG_PREFIX14} ${message}`);
+        console.debug(`${LOG_PREFIX17} ${message}`);
       }
     }
   };
@@ -10353,6 +10955,11 @@ ${callDescriptions}` : callDescriptions;
           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()
@@ -10475,21 +11082,50 @@ ${callDescriptions}` : callDescriptions;
         }
       });
       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) => {
@@ -10522,6 +11158,11 @@ ${callDescriptions}` : callDescriptions;
             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();
@@ -10646,7 +11287,7 @@ ${callDescriptions}` : callDescriptions;
         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."
@@ -10902,172 +11543,11 @@ ${callDescriptions}` : callDescriptions;
       };
     }
     /**
-     * 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.",
@@ -11077,13 +11557,27 @@ ${callDescriptions}` : callDescriptions;
             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",
@@ -11092,7 +11586,14 @@ ${callDescriptions}` : callDescriptions;
             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",
@@ -11100,7 +11601,13 @@ ${callDescriptions}` : callDescriptions;
           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",
@@ -11109,7 +11616,14 @@ ${callDescriptions}` : callDescriptions;
             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",
@@ -11118,13 +11632,61 @@ ${callDescriptions}` : callDescriptions;
             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",
@@ -11132,7 +11694,52 @@ ${callDescriptions}` : callDescriptions;
           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",
@@ -11141,9 +11748,37 @@ ${callDescriptions}` : callDescriptions;
             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}`,
@@ -11608,7 +12243,7 @@ ${callDescriptions}` : callDescriptions;
       );
     }
   }
-  var VERSION = "0.1.0-beta.1";
+  var VERSION = "0.1.0-beta.2";
   return __toCommonJS(index_exports);
 })();
 /*! Bundled license information: