@yak-io/javascript 0.6.0 → 0.8.0

package/README.md

@@ -0,0 +1,181 @@
+# @yak-io/javascript
+
+Framework-agnostic core SDK for embedding the Yak chat widget. This package provides the low-level client and DOM rendering layer. Most developers should use a framework-specific package (`@yak-io/react`, `@yak-io/vue`, etc.) instead.
+
+## When to use this package directly
+
+- You are building a vanilla JS / TypeScript app
+- You are building a new framework adapter
+- You need the server-side handler utilities (`./server` export) outside Next.js
+
+## Installation
+
+```bash
+pnpm add @yak-io/javascript
+```
+
+## Quickstart — Vanilla JS
+
+```ts
+import { YakEmbed } from "@yak-io/javascript";
+
+const embed = new YakEmbed({
+  appId: "your-app-id",
+  theme: { position: "bottom-right", colorMode: "system" },
+  trigger: { label: "Ask with AI" },
+  getConfig: async () => ({
+    routes: {
+      routes: [
+        { path: "/", title: "Home", description: "Landing page" },
+        { path: "/docs", title: "Docs", description: "Documentation" },
+      ],
+      generated_at: new Date().toISOString(),
+    },
+    tools: {
+      tools: [
+        {
+          name: "tasks.list",
+          displayName: "List Tasks",
+          description: "Return all tasks",
+          inputSchema: { type: "object", properties: {} },
+        },
+      ],
+      generated_at: new Date().toISOString(),
+    },
+  }),
+  onToolCall: async (name, args) => {
+    if (name === "tasks.list") {
+      return { tasks: [] };
+    }
+    throw new Error(`Unknown tool: ${name}`);
+  },
+  onRedirect: (path) => {
+    window.location.assign(path);
+  },
+});
+
+embed.mount();
+```
+
+## Server-side utilities
+
+Use `@yak-io/javascript/server` to build framework-agnostic API handlers:
+
+```ts
+import { createYakHandler } from "@yak-io/javascript/server";
+
+// Works with any Request/Response runtime (Remix, Fastify, etc.)
+const { GET, POST } = createYakHandler({
+  routes: [
+    { path: "/", title: "Home" },
+    { path: "/tasks", title: "Tasks" },
+  ],
+  tools: {
+    getTools: async () => [
+      {
+        name: "tasks.list",
+        displayName: "List Tasks",
+        description: "Return all tasks",
+        inputSchema: { type: "object", properties: {} },
+      },
+    ],
+    executeTool: async (name, args) => {
+      if (name === "tasks.list") return { tasks: [] };
+      throw new Error(`Unknown tool: ${name}`);
+    },
+  },
+});
+```
+
+## API Reference
+
+### `YakEmbed`
+
+High-level class that handles DOM rendering (panel, iframe, trigger button) and client wiring.
+
+```ts
+new YakEmbed(config: YakEmbedConfig)
+```
+
+**Key methods:**
+
+| Method | Description |
+|--------|-------------|
+| `mount()` | Injects the widget into the DOM |
+| `destroy()` | Removes the widget from the DOM |
+| `open()` | Open the chat panel |
+| `close()` | Close the chat panel |
+| `toggle()` | Toggle open/close |
+| `openWithPrompt(prompt)` | Open and pre-fill a prompt |
+| `getState()` | Get current `{ isOpen, isReady }` state |
+| `onStateChange(fn)` | Subscribe to state changes, returns unsubscribe |
+| `getClient()` | Access the underlying `YakClient` |
+
+**Configuration (`YakEmbedConfig`):**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `appId` | `string` | Your Yak app ID |
+| `theme` | `Theme` | Position, color mode, and widget colors |
+| `trigger` | `boolean \| TriggerButtonConfig` | Show built-in trigger button |
+| `getConfig` | `ChatConfigProvider` | Async function returning routes + tools config |
+| `chatConfig` | `ChatConfig` | Static config (alternative to `getConfig`) |
+| `onToolCall` | `ToolCallHandler` | Handle tool calls from the assistant |
+| `onGraphQLSchemaCall` | `GraphQLSchemaHandler` | Handle GraphQL schema tool calls |
+| `onRESTSchemaCall` | `RESTSchemaHandler` | Handle REST/OpenAPI schema tool calls |
+| `onRedirect` | `(path: string) => void` | Handle navigation requests |
+| `onToolCallComplete` | `(event: ToolCallEvent) => void` | Called after each tool call |
+| `options.disableRestartButton` | `boolean` | Hide the restart session button |
+
+### `YakClient`
+
+Low-level iframe communication client. Use `YakEmbed` for most cases.
+
+### Logging utilities
+
+```ts
+import { enableYakLogging, disableYakLogging, isYakLoggingEnabled } from "@yak-io/javascript";
+
+enableYakLogging();   // Turn on verbose SDK logging
+disableYakLogging();  // Turn off SDK logging
+isYakLoggingEnabled(); // Returns current state
+```
+
+In development, set `window.__YAK_INTERNAL_DEV__ = true` before mounting to connect to a locally running chat UI.
+
+## Types
+
+All types are exported from the package root:
+
+```ts
+import type {
+  ChatConfig,
+  ChatConfigProvider,
+  RouteManifest,
+  RouteInfo,
+  ToolManifest,
+  ToolDefinition,
+  ToolCallHandler,
+  ToolCallEvent,
+  ToolCallPayload,
+  ToolCallResult,
+  GraphQLSchemaHandler,
+  RESTSchemaHandler,
+  GraphQLRequest,
+  RESTRequest,
+  SchemaSource,
+  GraphQLSchemaSource,
+  OpenAPISchemaSource,
+  Theme,
+  ThemeColors,
+  TriggerButtonConfig,
+  WidgetPosition,
+  YakClientConfig,
+  YakEmbedConfig,
+  YakEmbedState,
+} from "@yak-io/javascript";
+```
+
+## License
+
+Proprietary — see LICENSE file.

package/dist/client.d.ts

@@ -1,6 +1,6 @@
 import type { ChatConfig } from "./types/config.js";
-import type { Theme } from "./types/messaging.js";
-import type { ToolCallHandler, ToolCallEventListener, GraphQLSchemaHandler, RESTSchemaHandler } from "./types/tools.js";
+import type { Theme, UserIdentity } from "./types/messaging.js";
+import type { GraphQLSchemaHandler, RESTSchemaHandler, ToolCallEventListener, ToolCallHandler } from "./types/tools.js";
 declare global {
     interface Window {
         __YAK_INTERNAL_DEV__?: boolean;
@@ -104,6 +104,28 @@ export interface YakClientConfig {
         /** Disable the restart session button in the header */
         disableRestartButton?: boolean;
     };
+    /**
+     * Signed end-user identity. When supplied, the widget persists conversations
+     * server-side keyed to this user and surfaces a history pane. The `hash`
+     * must be HMAC-SHA256(apiSecret, id) computed on the integrator's backend —
+     * never expose `apiSecret` to the browser.
+     *
+     * @example
+     * ```ts
+     * // Integrator backend (Node.js)
+     * const hash = crypto
+     *   .createHmac("sha256", process.env.YAK_API_SECRET)
+     *   .update(currentUser.id)
+     *   .digest("hex");
+     *
+     * // Browser
+     * new YakClient({
+     *   appId: "app_abc",
+     *   user: { id: currentUser.id, hash },
+     * });
+     * ```
+     */
+    user?: UserIdentity;
 }
 export declare class YakClient {
     private config;

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAA8C,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAC9F,OAAO,KAAK,EACV,eAAe,EACf,qBAAqB,EACrB,oBAAoB,EACpB,iBAAiB,EAGlB,MAAM,kBAAkB,CAAC;AAM1B,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,oBAAoB,CAAC,EAAE,OAAO,CAAC;QAC/B,uBAAuB,CAAC,EAAE,OAAO,CAAC;KACnC;CACF;AA+BD,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B;;;;;;;;;;;;;;;;;;OAkBG;IACH,mBAAmB,CAAC,EAAE,oBAAoB,CAAC;IAC3C;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,gBAAgB,CAAC,EAAE,iBAAiB,CAAC;IACrC,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB;;;;;;;;;;;;OAYG;IACH,kBAAkB,CAAC,EAAE,qBAAqB,CAAC;IAC3C,iCAAiC;IACjC,OAAO,CAAC,EAAE;QACR,uDAAuD;QACvD,oBAAoB,CAAC,EAAE,OAAO,CAAC;KAChC,CAAC;CACH;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,WAAW,CAAmD;IACtE,OAAO,CAAC,sBAAsB,CAAS;IACvC,OAAO,CAAC,OAAO,CAAO;IACtB,OAAO,CAAC,oBAAoB,CAAa;IACzC,OAAO,CAAC,QAAQ,CAAiC;gBAErC,MAAM,EAAE,eAAe;IAQ5B,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,eAAe,CAAC;IAOvD;;;OAGG;IACI,eAAe,IAAI,MAAM;IAIhC;;;;;;;;;OASG;IACI,WAAW,IAAI,MAAM;IAuB5B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAoBzB;;OAEG;IACI,QAAQ,IAAI,MAAM;IAIzB;;OAEG;IACI,QAAQ,IAAI,KAAK,GAAG,SAAS;IAIpC;;;;;;;;;;OAUG;IACI,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAavC;;;OAGG;IACI,SAAS,IAAI,IAAI;IAYxB;;OAEG;IACI,OAAO,IAAI,OAAO;IAIlB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAOrC,aAAa,CAAC,MAAM,EAAE,OAAO;IAa7B,KAAK;IAOL,OAAO;IAQd,OAAO,CAAC,cAAc;IA+BtB,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,cAAc,CAGpB;IAGF,OAAO,CAAC,aAAa,CA+GnB;IAEF,OAAO,CAAC,kBAAkB;IAkC1B,OAAO,CAAC,eAAe;YAoBT,cAAc;YA4Bd,uBAAuB;YAuBvB,oBAAoB;IAuBlC,OAAO,CAAC,sBAAsB;IAuB9B;;;OAGG;IACH,OAAO,CAAC,cAAc;IAatB,OAAO,CAAC,mBAAmB;IAU3B;;;OAGG;IACH,OAAO,CAAC,iBAAiB;CAsB1B"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAGV,KAAK,EACL,YAAY,EACb,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAEV,oBAAoB,EAEpB,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EAChB,MAAM,kBAAkB,CAAC;AAuD1B,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,oBAAoB,CAAC,EAAE,OAAO,CAAC;QAC/B,uBAAuB,CAAC,EAAE,OAAO,CAAC;KACnC;CACF;AA+BD,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B;;;;;;;;;;;;;;;;;;OAkBG;IACH,mBAAmB,CAAC,EAAE,oBAAoB,CAAC;IAC3C;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,gBAAgB,CAAC,EAAE,iBAAiB,CAAC;IACrC,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB;;;;;;;;;;;;OAYG;IACH,kBAAkB,CAAC,EAAE,qBAAqB,CAAC;IAC3C,iCAAiC;IACjC,OAAO,CAAC,EAAE;QACR,uDAAuD;QACvD,oBAAoB,CAAC,EAAE,OAAO,CAAC;KAChC,CAAC;IACF;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,IAAI,CAAC,EAAE,YAAY,CAAC;CACrB;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,WAAW,CAAmD;IACtE,OAAO,CAAC,sBAAsB,CAAS;IACvC,OAAO,CAAC,OAAO,CAAO;IACtB,OAAO,CAAC,oBAAoB,CAAa;IACzC,OAAO,CAAC,QAAQ,CAAiC;gBAErC,MAAM,EAAE,eAAe;IAQ5B,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,eAAe,CAAC;IAUvD;;;OAGG;IACI,eAAe,IAAI,MAAM;IAIhC;;;;;;;;;OASG;IACI,WAAW,IAAI,MAAM;IAuB5B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAoBzB;;OAEG;IACI,QAAQ,IAAI,MAAM;IAIzB;;OAEG;IACI,QAAQ,IAAI,KAAK,GAAG,SAAS;IAIpC;;;;;;;;;;OAUG;IACI,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAavC;;;OAGG;IACI,SAAS,IAAI,IAAI;IAYxB;;OAEG;IACI,OAAO,IAAI,OAAO;IAIlB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAOrC,aAAa,CAAC,MAAM,EAAE,OAAO;IAa7B,KAAK;IAOL,OAAO;IAQd,OAAO,CAAC,cAAc;IA+BtB,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,cAAc,CAGpB;IAEF,OAAO,CAAC,aAAa,CAkInB;IAEF,OAAO,CAAC,kBAAkB;IAwC1B,OAAO,CAAC,eAAe;YAoBT,cAAc;YA4Bd,uBAAuB;YAuBvB,oBAAoB;IAuBlC,OAAO,CAAC,sBAAsB;IAuB9B;;;OAGG;IACH,OAAO,CAAC,cAAc;IAatB,OAAO,CAAC,mBAAmB;IAU3B;;;OAGG;IACH,OAAO,CAAC,iBAAiB;CAsB1B"}

package/dist/client.js

@@ -1,6 +1,61 @@
-import { extractPageContext, debounce } from "./page-context.js";
+import { isYakLoggingEnabled, logger } from "./logger.js";
+import { debounce, extractPageContext } from "./page-context.js";
 import { EMBED_PROTOCOL_VERSION } from "./version.js";
-import { logger, isYakLoggingEnabled } from "./logger.js";
+/** localStorage key for the per-app signed session token. */
+const SESSION_STORAGE_KEY = (appId) => `yak:session:${appId}`;
+/** localStorage key for the per-app active-conversation pointer. */
+const CONVERSATION_POINTER_KEY = (appId) => `yak:conversation:${appId}`;
+/** Read a stored session token for this app, if any. SSR-safe. */
+function readStoredSessionToken(appId) {
+    if (typeof window === "undefined" || typeof window.localStorage === "undefined")
+        return undefined;
+    try {
+        return window.localStorage.getItem(SESSION_STORAGE_KEY(appId)) ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function writeStoredSessionToken(appId, token) {
+    if (typeof window === "undefined" || typeof window.localStorage === "undefined")
+        return;
+    try {
+        window.localStorage.setItem(SESSION_STORAGE_KEY(appId), token);
+    }
+    catch {
+        // localStorage can throw in private-browsing modes; silently ignore.
+    }
+}
+function readStoredConversationPointer(appId) {
+    if (typeof window === "undefined" || typeof window.localStorage === "undefined")
+        return undefined;
+    try {
+        return window.localStorage.getItem(CONVERSATION_POINTER_KEY(appId)) ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function writeStoredConversationPointer(appId, pointer) {
+    if (typeof window === "undefined" || typeof window.localStorage === "undefined")
+        return;
+    try {
+        window.localStorage.setItem(CONVERSATION_POINTER_KEY(appId), pointer);
+    }
+    catch {
+        // localStorage can throw in private-browsing modes; silently ignore.
+    }
+}
+function clearStoredConversationPointer(appId) {
+    if (typeof window === "undefined" || typeof window.localStorage === "undefined")
+        return;
+    try {
+        window.localStorage.removeItem(CONVERSATION_POINTER_KEY(appId));
+    }
+    catch {
+        // localStorage can throw in private-browsing modes; silently ignore.
+    }
+}
 /**
  * Determines the iframe origin based on the current environment.
  * - Internal dev (localhost on *.yak.* domain) -> http://localhost:3001
@@ -43,7 +98,10 @@ export class YakClient {
     }
     updateConfig(newConfig) {
         this.config = { ...this.config, ...newConfig };
-        if (this.readyTarget && this.config.chatConfig) {
+        // Resend config when the iframe is ready and we have anything to deliver —
+        // tool/route manifests, or a user identity that needs to land in the
+        // widget so persistence/history light up.
+        if (this.readyTarget && (this.config.chatConfig || this.config.user)) {
             this.sendConfigToIframe(this.readyTarget.window, this.readyTarget.origin);
         }
     }
@@ -220,7 +278,6 @@ export class YakClient {
         logger.debug("Navigation detected, sending page context");
         this.sendPageContext();
     };
-    // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: message handler requires branching per message type
     handleMessage = (event) => {
         if (typeof window === "undefined")
             return;
@@ -304,6 +361,24 @@ export class YakClient {
                 }
                 break;
             }
+            case "yak:session": {
+                const { sessionToken } = message.payload;
+                logger.debug("Session token received from iframe; persisting");
+                writeStoredSessionToken(this.config.appId, sessionToken);
+                break;
+            }
+            case "yak:conversation": {
+                const { pointer } = message.payload;
+                if (pointer === null) {
+                    logger.debug("Conversation pointer cleared by iframe");
+                    clearStoredConversationPointer(this.config.appId);
+                }
+                else {
+                    logger.debug("Conversation pointer received from iframe; persisting");
+                    writeStoredConversationPointer(this.config.appId, pointer);
+                }
+                break;
+            }
             case "yak:close": {
                 logger.debug("Close message received from iframe");
                 this.config.onClose?.();
@@ -319,6 +394,8 @@ export class YakClient {
         const loggingEnabled = typeof window !== "undefined" && typeof window.__YAK_LOGGING_ENABLED__ === "boolean"
             ? window.__YAK_LOGGING_ENABLED__
             : undefined;
+        const storedSessionToken = readStoredSessionToken(this.config.appId);
+        const storedConversationPointer = readStoredConversationPointer(this.config.appId);
         const configMessage = {
             type: "yak:config",
             payload: {
@@ -330,6 +407,9 @@ export class YakClient {
                 schemaSources: this.config.chatConfig?.schemaSources ?? undefined,
                 options: this.config.options,
                 loggingEnabled,
+                user: this.config.user,
+                sessionToken: storedSessionToken,
+                conversationPointer: storedConversationPointer,
             },
         };
         logger.debug("Posting config to iframe origin:", {

package/dist/embed.d.ts

@@ -1,7 +1,9 @@
 import { YakClient, type YakClientConfig } from "./client.js";
+import type { ChatConfigProvider } from "./types/config.js";
+import { type VoiceMachine } from "./voice-machine.js";
+import { type VoiceStateListener, YakVoiceSession } from "./voice-session.js";
+export type WidgetMode = "chat" | "voice" | "both";
 export type TriggerButtonConfig = {
-    /** Label displayed on the trigger button. Default: "Ask with AI" */
-    label?: string;
     /** Custom color overrides for light mode */
     lightButton?: {
         background?: string;
@@ -20,6 +22,20 @@ export type YakEmbedConfig = YakClientConfig & {
     target?: HTMLElement;
     /** Show the floating trigger button. Default: true */
     trigger?: boolean | TriggerButtonConfig;
+    /**
+     * Which experiences this widget exposes.
+     *   "chat"  — chat icon only (opens the chat iframe).
+     *   "voice" — voice icon only (starts a WebRTC voice session).
+     *   "both"  — both icons in one pill.
+     * Default: "chat".
+     */
+    mode?: WidgetMode;
+    /**
+     * Async provider for chat config (routes + tools). Used by the voice
+     * session on every `start()` and by the iframe via postMessage. Takes
+     * precedence over the static `chatConfig` on `YakClientConfig`.
+     */
+    getConfig?: ChatConfigProvider;
 };
 export type YakEmbedState = {
     isOpen: boolean;
@@ -28,14 +44,16 @@ export type YakEmbedState = {
 };
 export type YakEmbedStateListener = (state: YakEmbedState) => void;
 /**
- * Drop-in widget that renders the yak chat iframe + optional trigger button.
- * Wraps YakClient with DOM rendering, lazy iframe mounting, and consistent styling.
+ * Drop-in widget that renders the yak trigger pill plus, depending on mode,
+ * the chat iframe panel and/or a WebRTC voice session. Composes both
+ * `YakClient` (chat) and `YakVoiceSession` (voice) under one trigger.
  *
  * @example
  * ```ts
  * const embed = new YakEmbed({
  *   appId: "my-app",
- *   theme: { position: "bottom-right" },
+ *   mode: "both",
+ *   theme: { position: "bottom-left" },
  *   onToolCall: async (name, args) => { ... },
  * });
  * embed.mount();
@@ -43,29 +61,40 @@ export type YakEmbedStateListener = (state: YakEmbedState) => void;
  */
 export declare class YakEmbed {
     private readonly client;
+    private readonly voice;
     private readonly config;
+    private readonly mode;
     private styleEl;
     private panelRoot;
     private container;
     private iframe;
-    private triggerButton;
+    private triggerEl;
+    private chatButton;
+    private voiceButton;
     private isOpen;
     private isReady;
     private isExpanded;
     private hasBeenOpened;
     private pendingPrompt;
     private mounted;
+    private voiceMachine;
     private stateListeners;
+    private voiceListeners;
+    private unsubscribeVoice;
     private mobileQuery;
     private mobileHandler;
     private expandHandler;
     constructor(config: YakEmbedConfig);
     /** The underlying headless YakClient for advanced usage */
     getClient(): YakClient;
+    /** The underlying voice session — null when mode === "chat". */
+    getVoiceSession(): YakVoiceSession | null;
+    /** Current widget mode (immutable for the lifetime of the embed). */
+    getMode(): WidgetMode;
     /**
      * Mount the widget into the DOM. Call once after construction.
-     * Inserts styles and trigger button (if enabled). The iframe is lazily
-     * created on the first call to open().
+     * Inserts styles and trigger button (if enabled). The chat iframe is
+     * lazily created on the first call to open().
      */
     mount(target?: HTMLElement): void;
     /** Remove all DOM elements and event listeners. */
@@ -82,12 +111,24 @@ export declare class YakEmbed {
     getState(): YakEmbedState;
     /** Subscribe to state changes. Returns an unsubscribe function. */
     onStateChange(listener: YakEmbedStateListener): () => void;
+    /** Start a voice session. Must be invoked from a user gesture. */
+    voiceStart(): Promise<void>;
+    /** Stop the current voice session. */
+    voiceStop(): Promise<void>;
+    /** Toggle: start if idle/error, stop if active. */
+    voiceToggle(): Promise<void>;
+    /** Current voice machine snapshot. */
+    getVoiceState(): VoiceMachine;
+    /** Subscribe to voice state changes. */
+    onVoiceStateChange(listener: VoiceStateListener): () => void;
     private createPanel;
     private createTrigger;
     private buildTriggerClasses;
     private applyTriggerCustomColors;
     private updatePanelState;
-    private updateTriggerState;
+    private updateChatButtonState;
+    private updateVoiceButtonState;
+    private iconForVoiceState;
     private sendPendingPrompt;
     private sendFocusIfOpen;
     private notifyMobileState;

package/dist/embed.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"embed.d.ts","sourceRoot":"","sources":["../src/embed.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAM9D,MAAM,MAAM,mBAAmB,GAAG;IAChC,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,WAAW,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACvE,2CAA2C;IAC3C,UAAU,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACvE,CAAC;AAIF,MAAM,MAAM,cAAc,GAAG,eAAe,GAAG;IAC7C,wEAAwE;IACxE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,sDAAsD;IACtD,OAAO,CAAC,EAAE,OAAO,GAAG,mBAAmB,CAAC;CACzC,CAAC;AAIF,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,OAAO,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;AAgNnE;;;;;;;;;;;;;GAaG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IAGxC,OAAO,CAAC,OAAO,CAAiC;IAChD,OAAO,CAAC,SAAS,CAA+B;IAChD,OAAO,CAAC,SAAS,CAA+B;IAChD,OAAO,CAAC,MAAM,CAAkC;IAChD,OAAO,CAAC,aAAa,CAAkC;IAGvD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,OAAO,CAAS;IAGxB,OAAO,CAAC,cAAc,CAAoC;IAC1D,OAAO,CAAC,WAAW,CAA+B;IAClD,OAAO,CAAC,aAAa,CAAmD;IACxE,OAAO,CAAC,aAAa,CAA4C;gBAErD,MAAM,EAAE,cAAc;IAsBlC,2DAA2D;IACpD,SAAS,IAAI,SAAS;IAM7B;;;;OAIG;IACI,KAAK,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI;IA8BxC,mDAAmD;IAC5C,OAAO,IAAI,IAAI;IAoCtB,2EAA2E;IACpE,IAAI,IAAI,IAAI;IAkBnB,gFAAgF;IACzE,KAAK,IAAI,IAAI;IAQpB,0CAA0C;IACnC,MAAM,IAAI,IAAI;IAQrB,mDAAmD;IAC5C,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAM3C,oCAAoC;IAC7B,QAAQ,IAAI,aAAa;IAIhC,mEAAmE;IAC5D,aAAa,CAAC,QAAQ,EAAE,qBAAqB,GAAG,MAAM,IAAI;IASjE,OAAO,CAAC,WAAW;IA2CnB,OAAO,CAAC,aAAa;IAyCrB,OAAO,CAAC,mBAAmB;IAuB3B,OAAO,CAAC,wBAAwB;IA2BhC,OAAO,CAAC,gBAAgB;IASxB,OAAO,CAAC,kBAAkB;IA2B1B,OAAO,CAAC,iBAAiB;IAOzB,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,iBAAiB;IAMzB,OAAO,CAAC,sBAAsB;IAS9B,OAAO,CAAC,eAAe;CAUxB"}
+{"version":3,"file":"embed.d.ts","sourceRoot":"","sources":["../src/embed.ts"],"names":[],"mappings":"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"}