@yak-io/javascript 0.7.0 → 0.9.0

package/README.md

@@ -1,80 +1,152 @@
 # @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.
+> 📚 **Full documentation:** https://docs.yak.io/docs/sdks/javascript
+>
+> 🤖 **For LLMs / AI agents:** https://docs.yak.io/llms.txt
 
-## When to use this package directly
+Framework-agnostic core SDK for [Yak](https://docs.yak.io) — an embeddable AI assistant (text chat **and** push-to-talk voice) for web apps. This package is the low-level runtime that every framework SDK (`@yak-io/react`, `@yak-io/vue`, …) is built on. It owns iframe messaging, the WebRTC voice session, DOM rendering of the trigger pill + chat panel, and an optional server handler.
 
-- 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
+**Use this package directly when** you're on vanilla JS/TS, building a new framework adapter, or need the server handler (`@yak-io/javascript/server`) outside Next.js. On a supported framework, prefer that framework's package instead.
 
 ```bash
 pnpm add @yak-io/javascript
 ```
 
-## Quickstart — Vanilla JS
+## Exports
+
+| Export | Kind | Purpose |
+| --- | --- | --- |
+| `YakEmbed` | class | Drop-in widget: trigger pill + chat panel + voice, all wired. Start here. |
+| `YakClient` | class | Headless chat-only iframe client (no DOM). Advanced. |
+| `YakVoiceSession` | class | Headless WebRTC voice session. Advanced. |
+| `enableYakLogging` / `disableYakLogging` / `isYakLoggingEnabled` | fn | Toggle verbose SDK logging. |
+| `EMBED_PROTOCOL_VERSION` | const | Host ↔ iframe protocol version. |
+| Types | — | `YakEmbedConfig`, `YakClientConfig`, `Theme`, `WidgetMode`, `VoiceState`, `VoiceMachine`, `ToolCallEvent`, `ChatConfig`, and more (see [Types](#types)). |
+| `@yak-io/javascript/server` | subpath | `createYakHandler` + route/tool source types (see [Server](#server-side-handler)). |
+
+## Quickstart
 
 ```ts
 import { YakEmbed } from "@yak-io/javascript";
 
 const embed = new YakEmbed({
   appId: "your-app-id",
+  mode: "both", // "chat" | "voice" | "both" — default "chat"
+  trigger: true, // render the floating launcher pill
   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}`);
+  // Routes + tools the assistant may use. Usually fetched from your server.
+  getConfig: async () => {
+    const res = await fetch("/api/yak");
+    return res.json(); // ChatConfig: { routes, tools? }
   },
-  onRedirect: (path) => {
-    window.location.assign(path);
+  // Execute a tool the assistant decides to call.
+  onToolCall: async (name, args) => {
+    const res = await fetch("/api/yak", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ name, args }),
+    });
+    const data = await res.json();
+    if (!data.ok) throw new Error(data.error);
+    return data.result;
   },
 });
 
-embed.mount();
+embed.mount(); // inject into the DOM
+```
+
+## Programmatic control
+
+Every method works whether or not the trigger pill is shown — pass `trigger: false` to drive a fully custom UI.
+
+```ts
+// Chat
+embed.open();
+embed.close();
+embed.toggle();
+embed.openWithPrompt("How do I export my data?");
+
+// Voice (requires mode "voice" or "both"; must be called from a user gesture)
+await embed.voiceStart();
+await embed.voiceStop();
+await embed.voiceToggle();
+
+// State
+embed.getState(); // { isOpen, isReady, isLoading, isExpanded }
+const stop = embed.onStateChange((s) => console.log(s.isLoading));
+const stopVoice = embed.onVoiceStateChange((m) => console.log(m.state));
 ```
 
-## Server-side utilities
+`isLoading` is `isOpen && !isReady` — true from the moment the panel opens until the iframe handshakes ready. Drive a custom loading spinner off it instead of re-deriving the condition. For voice, the equivalent "still spinning up" check is `getVoiceState().state === "connecting"`.
 
-Use `@yak-io/javascript/server` to build framework-agnostic API handlers:
+## API reference
+
+### `new YakEmbed(config)`
+
+**Config** (`YakEmbedConfig`):
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `appId` | `string` | — | Your Yak app ID (required). |
+| `mode` | `"chat" \| "voice" \| "both"` | `"chat"` | Which surfaces the widget exposes. |
+| `trigger` | `boolean \| TriggerButtonConfig` | `true` | Show the floating pill. `false` = headless. `TriggerButtonConfig` recolors it. |
+| `theme` | `Theme` | — | Position, color mode, and colors. |
+| `getConfig` | `ChatConfigProvider` | — | Async provider of `{ routes, tools? }`. Called on open and on each voice start. |
+| `onToolCall` | `ToolCallHandler` | — | Executes a tool the assistant calls. |
+| `onGraphQLSchemaCall` | `GraphQLSchemaHandler` | — | Handles GraphQL schema tool calls. |
+| `onRESTSchemaCall` | `RESTSchemaHandler` | — | Handles REST/OpenAPI schema tool calls. |
+| `onRedirect` | `(path: string) => void` | `window.location.assign` | Handle navigation requested by the assistant. |
+| `onToolCallComplete` | `(event: ToolCallEvent) => void` | — | Fires after every tool call (use for cache invalidation). |
+| `user` | `UserIdentity` | — | Signed end-user identity for server-side conversation persistence. See [end-user identity](https://docs.yak.io/docs/customization/end-user-identity). |
+| `target` | `HTMLElement` | `document.body` | Where to mount the widget DOM. |
+| `options.disableRestartButton` | `boolean` | `false` | Hide the restart-session button in the header. |
+
+**Methods:** `mount()`, `destroy()`, `open()`, `close()`, `toggle()`, `openWithPrompt(prompt)`, `getState()`, `onStateChange(fn)`, `voiceStart()`, `voiceStop()`, `voiceToggle()`, `getVoiceState()`, `onVoiceStateChange(fn)`, `getClient()`, `getVoiceSession()`, `getMode()`.
+
+### `Theme`
+
+```ts
+type Theme = {
+  position?: WidgetPosition;            // default "bottom-left"
+  colorMode?: "light" | "dark" | "system";
+  displayMode?: "chatbox" | "drawer";   // floating panel vs full-height side drawer
+  fullscreen?: boolean;
+  light?: ThemeColors;                  // { background?, border?, messageBackground?, ... }
+  dark?: ThemeColors;
+};
+// WidgetPosition: top-left | top-center | top-right | left-center | right-center
+//               | bottom-left | bottom-center | bottom-right
+```
+
+### `VoiceState` / `VoiceMachine`
+
+```ts
+type VoiceState = "idle" | "connecting" | "listening" | "thinking" | "speaking" | "error";
+interface VoiceMachine { state: VoiceState; errorMessage?: string }
+```
+
+### `YakClient` / `YakVoiceSession`
+
+Headless building blocks used internally by `YakEmbed`. Reach for them only when composing a bespoke integration — most apps should use `YakEmbed`.
+
+## Server-side handler
+
+`@yak-io/javascript/server` builds a framework-agnostic `Request`/`Response` handler (Remix, Fastify, Hono, plain Node, …):
 
 ```ts
 import { createYakHandler } from "@yak-io/javascript/server";
 
-// Works with any Request/Response runtime (Remix, Fastify, etc.)
-const { GET, POST } = createYakHandler({
+export const { GET, POST } = createYakHandler({
+  // GET returns the route + tool manifest the assistant sees.
   routes: [
     { path: "/", title: "Home" },
     { path: "/tasks", title: "Tasks" },
   ],
+  // POST executes a tool call.
   tools: {
     getTools: async () => [
       {
         name: "tasks.list",
-        displayName: "List Tasks",
         description: "Return all tasks",
         inputSchema: { type: "object", properties: {} },
       },
@@ -87,61 +159,17 @@ const { GET, POST } = createYakHandler({
 });
 ```
 
-## API Reference
-
-### `YakEmbed`
-
-High-level class that handles DOM rendering (panel, iframe, trigger button) and client wiring.
+`routes` and `tools` each accept a single source or an array of sources, so you can compose filesystem routes with adapters like [`@yak-io/trpc`](https://docs.yak.io/docs/tool-adapters/trpc) or [`@yak-io/prismic`](https://docs.yak.io/docs/cms/prismic).
 
-```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
+## Logging
 
 ```ts
 import { enableYakLogging, disableYakLogging, isYakLoggingEnabled } from "@yak-io/javascript";
 
-enableYakLogging();   // Turn on verbose SDK logging
-disableYakLogging();  // Turn off SDK logging
-isYakLoggingEnabled(); // Returns current state
+enableYakLogging(); // verbose SDK logs
 ```
 
-In development, set `window.__YAK_INTERNAL_DEV__ = true` before mounting to connect to a locally running chat UI.
+In development, set `window.__YAK_INTERNAL_DEV__ = true` before `mount()` to connect to a locally running chat UI.
 
 ## Types
 
@@ -149,6 +177,16 @@ All types are exported from the package root:
 
 ```ts
 import type {
+  YakEmbedConfig,
+  YakEmbedState,
+  YakClientConfig,
+  WidgetMode,
+  Theme,
+  ThemeColors,
+  WidgetPosition,
+  TriggerButtonConfig,
+  VoiceState,
+  VoiceMachine,
   ChatConfig,
   ChatConfigProvider,
   RouteManifest,
@@ -157,25 +195,12 @@ import type {
   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.
+Proprietary — see [LICENSE](./LICENSE).

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,15 @@
 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";
+/**
+ * Which experiences the widget exposes:
+ * - `chat` — chat icon only (opens the chat iframe panel). The default.
+ * - `voice` — voice icon only (starts a WebRTC voice session).
+ * - `both` — both icons, sharing one trigger pill.
+ */
+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,22 +28,47 @@ 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 = {
+    /** Whether the chat panel is open. */
     isOpen: boolean;
+    /** Whether the chat iframe has handshaked and can receive messages. */
     isReady: boolean;
+    /**
+     * Whether the chat is opening but not yet interactive — `isOpen && !isReady`.
+     * Stays true from the moment the panel opens until the iframe reports ready,
+     * so custom triggers can show a spinner without re-deriving it.
+     */
+    isLoading: boolean;
+    /** Whether the panel is expanded to (near) full-screen. */
     isExpanded: boolean;
 };
 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 +76,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 +126,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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"}