@hubtalk-ai/web-sdk 0.2.0 → 0.3.0

package/README.md

@@ -1,17 +1,24 @@
 # @hubtalk-ai/web-sdk
 
-Browser SDK for running a WebRTC voice call with a HubTalk AI Conversation
-Flow agent from your own website. It is a thin wrapper over
-[`livekit-client`](https://github.com/livekit/client-sdk-js) and the
-platform's existing voice path (`POST /v1/calls/web`): the SDK has no
-transport of its own, holds no API key, and never calls the platform's HTTP
-API — see §9 “Web calls” of the partner integration guide
-(`docs/integration-guide.md` in the platform repository) for the
-backend → frontend → SDK sequence.
+*[Русская версия — `README.ru.md`](README.ru.md).*
 
-## Installation
+Browser SDK for a voice call with a HubTalk AI Conversation Flow agent,
+straight from your own website. A thin wrapper over
+[`livekit-client`](https://github.com/livekit/client-sdk-js): it holds no
+Web API key and never calls the platform's HTTP API.
+
+The integration is three steps:
+
+1. Your backend calls `POST /v1/calls/web` with the workspace's Web API key —
+   `agent_id` in the body, plus the call's dynamic variables if you use them.
+2. The platform answers `201` with the session: `{access_token, url, …}`.
+3. Your page hands that body to `startCall()` — from there the conversation
+   runs between the browser and the platform, and state arrives as events.
+
+The Web API key stays on your server and never reaches the browser. The
+endpoint's contract is published in the platform's schema: `{BASE_URL}/docs`.
 
-With a bundler:
+## Installation
 
 ```bash
 npm install @hubtalk-ai/web-sdk
@@ -21,8 +28,8 @@ npm install @hubtalk-ai/web-sdk
 import { VoiceClient } from '@hubtalk-ai/web-sdk';
 ```
 
-Without a build step, load the self-contained bundle (carries its own copy
-of `livekit-client`):
+Without a bundler, load the self-contained bundle with its own copy of
+`livekit-client`:
 
 ```html
 <script src="voice-client.bundle.js"></script>
@@ -34,8 +41,6 @@ of `livekit-client`):
 ## Quickstart
 
 ```ts
-import { VoiceClient } from '@hubtalk-ai/web-sdk';
-
 const client = new VoiceClient();
 
 startCallButton.addEventListener('click', async () => {
@@ -44,16 +49,16 @@ startCallButton.addEventListener('click', async () => {
   await client.startCall(session);
 });
 
-client.on('connectionStateChanged', ({ state }) => console.log('connection:', state));
-client.on('agentSpeakingStarted', () => console.log('agent speaking'));
+client.on('transcript', ({ role, text, final, id }) => renderBubble(id, role, text, final));
 client.on('callEnded', ({ reason }) => console.log('call ended:', reason));
 
 endCallButton.addEventListener('click', () => client.stopCall());
 ```
 
-**`startCall` must run inside a user gesture handler** (a click, a tap) — the
-browser's autoplay policy requires it for the agent's audio to play without
-being blocked, and getting microphone permission works the same way.
+**Call `startCall` inside a click or tap handler** — the browser requires that
+gesture both for the agent's audio and for microphone access. On iOS Safari a
+network request between the click and `startCall()` can consume the gesture:
+fetch the session ahead of time.
 
 ## API
 
@@ -61,449 +66,307 @@ being blocked, and getting microphone permission works the same way.
 
 | Option | Type | Default | Description |
 |---|---|---|---|
-| `audioContainer` | `HTMLElement` | a hidden `<div>` the SDK creates | Where agent `<audio>` elements are appended. |
-| `logger` | `{ error, debug }` | `console` | Custom log sink; the SDK still masks tokens before calling it. |
+| `audioContainer` | `HTMLElement` | a hidden `<div>` the SDK creates | Where the agent's `<audio>` elements go. |
+| `logger` | `{ error, debug }` | `console` | Your own log sink; tokens are masked either way. |
 | `logLevel` | `'silent' \| 'error' \| 'debug'` | `'error'` | Verbose logging is opt-in. |
-| `connectTimeoutMs` | `number` | livekit-client default (15s) | Peer connection / WebSocket connect timeout. |
+| `connectTimeoutMs` | `number` | 15s | Connection timeout. |
 
 ### Methods
 
 | Method | Behavior |
 |---|---|
-| `startCall({ accessToken, url }, options?)` | Connects and publishes the microphone. Accepts either `{accessToken, url}` or the raw `POST /v1/calls/web` response body (`{access_token, url, …}`) — extra fields are ignored. Resolves once the microphone is published. A second call while a call is active rejects with `ALREADY_IN_CALL`. `options.audio: false` starts a chat-only call — see below. |
-| `stopCall()` | Ends the call. Idempotent — resolves without an `error` event if no call is active. Cancels an in-flight `startCall` if called during `connecting`. |
-| `getState()` | Connection axis: `idle \| connecting \| connected \| reconnecting \| disconnected \| error`. |
-| `getAgentState()` | Agent-activity axis: `unknown \| initializing \| listening \| thinking \| speaking`. Independent of the connection axis. |
-| `sendText(text)` | Sends a typed reply into the conversation (topic `lk.chat`). The agent interrupts its speech and answers it as it would answer speech. Rejects with `NOT_IN_CALL` outside a call; an empty or whitespace-only string is a silent no-op; anything longer than 1000 characters is truncated. Your own message is **not** inserted into the chat by the SDK — it comes back as a `transcript` event with `role: 'user'`. |
-| `getCallId()` | The call's room name (same value as `call_id` in `GET /v1/calls/{call_id}`), or `null` before connecting. |
-| `on(event, handler)` / `off(event, handler)` / `once(event, handler)` | Subscribe / unsubscribe / subscribe-once. |
-| `destroy()` | Stops the call, removes every subscription, releases all resources. The instance is not usable afterward. |
+| `startCall(session, options?)` | Connects and publishes the microphone. Takes the `POST /v1/calls/web` response as it comes (extra fields ignored), or `{accessToken, url}`. A second call during an active one rejects with `ALREADY_IN_CALL`. `options.audio: false` starts a chat-only call. |
+| `stopCall()` | Ends the call. With no call active it does nothing and raises no error. |
+| `sendText(text)` | Sends the visitor's typed reply; the agent interrupts its speech and answers it as it would answer speech. Outside a call it rejects with `NOT_IN_CALL`; anything past 1000 characters is truncated. The SDK does not insert your message into the chat — it comes back as a `transcript` event with `role: 'user'`. |
+| `getState()` | Connection state: `idle \| connecting \| connected \| reconnecting \| disconnected \| error`. |
+| `getAgentState()` | What the agent is doing: `unknown \| initializing \| listening \| thinking \| speaking`. |
+| `getCallId()` | The call id (the same one `GET /v1/calls/{call_id}` takes), or `null` before connecting. |
+| `on` / `off` / `once` | Subscribe, unsubscribe, subscribe once. |
+| `destroy()` | Stops the call and releases everything; the instance is not usable afterward. |
 
 ### Events
 
 | Event | Payload |
 |---|---|
 | `callStarted` | `{ callId }` |
-| `callEnded` | `{ callId, reason }` — `reason`: `local` (`stopCall`), `remote` (the agent/flow ended it), `connection_lost`, `error` |
+| `callEnded` | `{ callId, reason }` — `local` (`stopCall`), `remote` (the agent ended it), `connection_lost`, `error` |
 | `connectionStateChanged` | `{ state, previous }` |
 | `agentStateChanged` | `{ state, previous }` |
 | `agentSpeakingStarted` / `agentSpeakingStopped` | `{}` |
-| `transcript` | `{ role, text, final, id }` — `role`: `user` \| `agent`; `text` is the reply so far; `final: false` while it is still growing; `id` is the segment id — deltas of one reply share it, so render one bubble per `id`. Agent text arrives as it is **spoken**, so an interrupted reply never shows its unspoken tail. |
-| `error` | `VoiceError` — see below |
+| `transcript` | `{ role, text, final, id }` — a line of the conversation; `role`: `user` \| `agent`. While `final: false` the line is still growing: render one bubble per `id`. |
+| `error` | `VoiceError` |
 
 ### Chat-only calls
 
-`startCall(session, { audio: false })` runs the same call without audio: no
-microphone is published, and the agent's audio is subscribed but never played,
-so the browser never asks for microphone permission and nothing is heard. Text
-keeps working in both directions — `sendText()` and the `transcript` event —
-which makes it the mode for a visitor who cannot or will not talk.
+`startCall(session, { audio: false })` runs the same call without microphone
+or sound: the browser asks for no permission and the conversation happens in
+text (`sendText()` and `transcript`). It is the mode for a visitor who cannot
+or will not talk. The agent still synthesizes speech, so the text arrives at
+speaking pace and the call costs the same as a voice one.
 
 ```ts
 await client.startCall(session, { audio: false });
 ```
 
-Two consequences of that mode, both worth knowing before you ship it:
-
-- Neither `MICROPHONE_PERMISSION_DENIED` nor `MICROPHONE_UNAVAILABLE` can
-  occur, and `WEBRTC_UNSUPPORTED` no longer requires `getUserMedia` — only a
-  secure context and `RTCPeerConnection`, which LiveKit needs for the data
-  channel either way.
-- The agent's audio is **subscribed and discarded**, not left unsubscribed.
-  That is not waste for its own sake: in `livekit-agents`, the agent's audio
-  output blocks on its track being subscribed
-  (`_ParticipantAudioOutput.capture_frame` awaits a future that only
-  `publication.wait_for_subscription()` resolves), and the agent's transcript
-  is routed through a synchronizer bound to that same output. With no
-  subscriber the first frame of speech blocks forever and the agent's text
-  never arrives at all — while the echo of the visitor's own typed replies
-  still does, because that goes out on a separate, unsynchronized path.
-- The agent therefore still synthesizes speech nobody hears, and LiveKit paces
-  the transcript to that playback. So the text arrives at speaking speed
-  rather than as fast as the model produces it, and the call costs the same in
-  TTS as a voice call. Removing both is a platform-side change — the agent
-  needs `RoomOutputOptions(audio_enabled=False)` — not an SDK one.
-
 ### Error codes
 
-Every failure is a structured `VoiceError`: `{ code, message, state, cause? }`
-— `cause` is the original browser/`livekit-client` error, for your own logs.
-
-| Code | When | Resulting state |
-|---|---|---|
-| `INVALID_PARAMS` | `accessToken` or `url` missing/empty | `error` |
-| `WEBRTC_UNSUPPORTED` | No WebRTC support, or not a secure context (HTTPS) | `error` |
-| `MICROPHONE_PERMISSION_DENIED` | Microphone access denied (voice calls only) | `error` |
-| `MICROPHONE_UNAVAILABLE` | No usable microphone device (voice calls only) | `error` |
-| `TOKEN_EXPIRED` | Token's `exp` already passed (checked locally before connecting) | `error` |
-| `TOKEN_INVALID` | Server rejected the token | `error` |
-| `CONNECTION_FAILED` | Could not establish the connection | `error` |
-| `CONNECTION_LOST` | Reconnect attempts exhausted after a successful connection | `disconnected` |
-| `ALREADY_IN_CALL` | `startCall` called while a call is already active | unchanged |
-| `NOT_IN_CALL` | `sendText` called outside an active call | unchanged |
-| `SERVER_ERROR` | Any other signalling/service failure | `error` |
-
-## Browser matrix
-
-Bounded by [`livekit-client`](https://github.com/livekit/client-sdk-js)'s own
-WebRTC support matrix. **Not yet verified against a live deployment** —
-tracked as an open pre-check of the source requirement (`docs/patches/patch132-web-voice-sdk.md`
-§7.3); this table is filled in once that manual pass runs, before the first
-release.
-
-| Browser | Verified |
-|---|---|
-| Chrome (desktop) | — |
-| Firefox (desktop) | — |
-| Safari (desktop) | — |
-| Chrome (Android) | — |
-| Safari (iOS) | — |
+Every failure is a `VoiceError`: `{ code, message, state, cause? }`. Match on
+`code`; `message` is a diagnostic line, and the visitor-facing text is yours.
 
-iOS Safari needs special attention: both microphone publish and
-`startAudio()` must run strictly inside the user gesture, no exceptions.
+| Code | When |
+|---|---|
+| `INVALID_PARAMS` | The session carries no `access_token` or `url` |
+| `WEBRTC_UNSUPPORTED` | No WebRTC support, or the page is not on HTTPS |
+| `MICROPHONE_PERMISSION_DENIED` | The visitor denied the microphone |
+| `MICROPHONE_UNAVAILABLE` | No microphone, or it is busy |
+| `TOKEN_EXPIRED` | The session expired before the call started |
+| `TOKEN_INVALID` | The server rejected the session token |
+| `CONNECTION_FAILED` | Could not connect |
+| `CONNECTION_LOST` | The connection dropped and did not come back |
+| `ALREADY_IN_CALL` | A call is already running |
+| `NOT_IN_CALL` | `sendText` outside a call |
+| `SERVER_ERROR` | Any other service failure |
+
+A session token lives 2 hours and is never refreshed: mint a fresh session
+per call rather than holding one on an open page.
 
 ## Share links
 
-You do not always need a backend of your own. The platform's cabinet can
-issue a temporary link to one published agent — an expiry, a cap on calls
-and one-click revocation — and the page behind that link mints the session
-itself. Whoever opens it talks to the agent with no account, no API key and
-no setup.
-
-That page is part of the platform, and it drives the call through this SDK
-without a single change to it: the response it mints has the same shape as
-`POST /v1/calls/web`, so `startCall(session)` takes it as it comes. Nothing
-in the SDK knows about links, and nothing here holds the link token — the
-same rule as for the API key.
+You do not always need a backend. The platform's cabinet issues a temporary
+link to one published agent — with an expiry, a cap on calls and one-click
+revocation. The page behind the link mints the session itself and drives the
+call through this same SDK, so anyone can talk to the agent with no account,
+no key and no setup.
 
 Use a share link when someone just needs to hear the agent. Use your own
-backend, as in `example/server.py`, when the call has to start from your
-site, under your own domain, with variables your system knows.
-
-## What this SDK does not do (phase 1)
-
-- No chat or call-button UI — you build the interface, the SDK reports state
-  and takes text. `example/index.html` shows the wiring, it is not a
-  shipped component. The reference widget of the example pages is not
-  shipped either: copy it, do not import it.
-- No link handling — a share link is opened by the platform's own page, and
-  `startCall` takes the session that page already minted. There is no
-  `startCall({ demoToken })` and the SDK never presents a secret.
-- No transcript history — the SDK holds no list of replies; whoever renders
-  them keeps them.
-- No dynamic variables of its own — they are set once, by your backend, in
-  the `POST /v1/calls/web` body that mints the session. By the time the SDK
-  has that session the variables are fixed, and there is no API to read or
-  change them. `example/server.py` shows the backend side.
-- No `cf.voice`: node names and cascade transitions stay internal. Post-call
-  data comes from `GET /v1/calls/{call_id}` or a
-  `call_ended`/`call_analyzed` webhook.
-- No rate limit on `sendText` — every message is an LLM turn and TTS
-  synthesis, so a page that sends in a loop spends the workspace's money.
-- No token refresh — a call cannot outlive the token's TTL
-  (`expires_in` in the `POST /v1/calls/web` response).
-- No video, DTMF, custom TURN/ICE, or client-side audio processing.
-
-## Development
-
-```bash
-npm install
-npm run lint
-npm run format:check
-npm run build   # dist/index.js (ESM) + dist/voice-client.bundle.js (script tag) + dist/*.d.ts
-
-python3 example/server.py --selftest   # the demo backend's field/merge logic
-```
+backend when the call starts from your site, on your domain, with variables
+your system knows.
 
-`--selftest` is the check that guards the parts of `example/server.py` with
-branches in them: `@today` and keyless fields in `demo_fields`, the
-allowlist in `merge_variables`, and every shipped scenario file parsing into
-a renderable form. It starts no server and needs no `.env`.
+## Example integration
 
-### Running the example pages
-
-`example/server.py` is the backend half of the example: it holds the API key,
-mints a room through `POST /v1/calls/web` and serves the pages. Standard
-library only, no dependencies. Every call parameter comes from `.env` — copy
-`.env.example` and fill it in:
-
-```
-CFLOW_API_URL=http://localhost:8100
-CFLOW_API_KEY=cfk_…
-CFLOW_AGENT_ID=my_agent_v1      # fallback when the page sends no agent_id
-# optional JSON objects, passed straight to POST /v1/calls/web
-# CFLOW_DYNAMIC_VARIABLES={"name": "Aigerim"}
-# CFLOW_METADATA={"source": "example"}
-# optional: which scenario to open with, and per-half overrides of it
-# CFLOW_DEMO_SCENARIO=missed-deposit
-# CFLOW_DEMO_FIELDS=[{"key":"rl_clientName","label":"Client name","default":"John"}]
-# CFLOW_DEMO_HERO={"headline":"Missed deposit follow-up"}
-```
-
-**One file per demo scenario.** `example/scenarios/<id>.json` declares the
-dynamic variables the pages let a visitor edit — the ones the agent may
-reference as `{{key}}` — plus the copy of the call page's left column. The id
-is the file name. Two ship filled in:
-
-| id | Shows |
-|---|---|
-| `missed-deposit` | a client whose scheduled deposit was returned; 14 variables |
-| `identity-verification` | verifying the client, then their enrolled creditor accounts; 21 variables |
-
-**Exactly one is active, and the server picks it** — the one whose file says
-`"default": true`, or `CFLOW_DEMO_SCENARIO`. That is not a missing feature:
-these variables are the variables of the agent in `CFLOW_AGENT_ID`, and one
-agent is configured at a time, so a page-level switch could only ever produce
-variables the running agent never references. The scenario travels with the
-agent, in `.env`. Relying on file order for the default would let a new file
-quietly replace what a live demo shows, hence the explicit marker.
-
-A new demo is a new file plus one `.env` line — no HTML.
-
-Per field: `key`, `label`, and optionally `default` (`"@today"` resolves to
-today's date on the server), `placeholder`, `type`, `readonly`, `half` (two
-fields share a row).
-
-The server serves the active scenario from `GET /api/config`, `/` and `/call`
-render it (`/free` declares its own), and `POST /api/session` accepts values
-**only** for that scenario's keys — a key belonging to another scenario is
-dropped like an invented one, and everything else in
-`CFLOW_DYNAMIC_VARIABLES` stays server-side. That
-filter is not demo scaffolding: a production backend owes the same guarantee,
-since the browser names values and never the contract.
-
-**Three pages, one widget.** `/` is the widget on a host page, `/call` the
-call as the whole page, `/free` the widget with nothing configured — the
-agent name and every dynamic variable are typed into the form, `+ Variable`
-adds a key/value row.
-
-The allowlist follows the agent, not the page: a request for the agent in
-`CFLOW_AGENT_ID`, on `.env`'s own key, is filtered against the active
-scenario's keys, and a request for any other agent — or on a key the page
-brought — has its keys sent through unfiltered. That is what makes `/free`
-work — it brings its own agent, whose contract the active scenario does not
-describe — and it is why naming a different agent on `/` or `/call` drops the
-filter too.
-
-**Which agent is called.** The page names it: `const AGENT_ID = '…'` in the
-widget options of `example/index.html` and `example/call-details.html`, sent
-as `agent_id` in `POST /api/session`. It is the agent's **name**, the same
-string `CFLOW_AGENT_ID` holds — not a uuid. Left empty — the shipped
-default — the form grows an Agent name input and the visitor names it per
-call. That input rides the same form as the variables but is never one of
-them: it carries the reserved key `__agent_id` (`HtDemo.AGENT_KEY`), which
-the wiring strips out before posting. The server falls back to
-`CFLOW_AGENT_ID` only when the request names no agent, and answers 503 when
-neither does.
-
-**Which organisation the call runs as.** The key decides, and `.env`'s
-`CFLOW_API_KEY` is again only the fallback: `/free` carries an **Organisation
-API key** field in the middle of the page — not in the widget, since the key
-is not a call parameter — and a key typed there is sent as `api_key` and used
-for that call instead. One deployment can therefore demo any organisation
-without an `.env` edit and a restart. No organisation id goes with it:
-`POST /v1/calls/web` authenticates on the bearer key alone. The field is a
-demo affordance and not a template — a production backend holds its key
-server-side and never lets the browser name one — and the server's own key
-still never travels to a page.
+`example/` holds a working backend-plus-page pair to start from: `server.py`
+keeps the Web API key and mints the session, and the pages show a call
+widget. `/` and `/avatar` use the optional shipped widget; the other layouts
+remain examples built on the headless client.
 
 ```bash
-npm run build                 # the page loads ../dist/voice-client.bundle.js
-python3 example/server.py     # http://localhost:8000/, /call and /free
+npm install && npm run build
+cp .env.example .env       # CFLOW_API_URL, CFLOW_API_KEY, CFLOW_AGENT_ID
+python3 example/server.py  # http://localhost:8000/
 ```
 
-Real environment variables win over `.env`, so `CFLOW_AGENT_ID=other python3
-example/server.py` overrides one parameter for a single run.
-
-Every press of Call asks the server for a fresh room. That is what keeps the
-short-lived LiveKit `access_token` fresh: a page left open for longer than the
-token TTL still starts a working call. The browser never talks to `/v1`
-directly, so no `CFLOW_CORS_ORIGINS` entry is needed — and the API key never
-reaches the page. That is the shape a production integration has too, with
-your own backend in place of `server.py`; `startCall()` accepts the
-`POST /v1/calls/web` response as-is.
-
-The example server exposes only the three example pages, their stylesheet
-(`example/widget.css`), their shared wiring (`example/demo-call.js`), the
-bundle and the two `/api/*` endpoints (the scenario files are read on the
-server, never served); it never serves the project directory
-or `.env`. Every page offers both a voice call and a chat-only one:
-
 | Page | What it shows |
 |---|---|
-| `/` | a demo site with the call widget pinned in the corner — the call starts from the launcher, and “Call details” inside the panel holds the dynamic variables |
-| `/call` | the call as the whole page: a branded column plus the same form, switching to the conversation once the call starts |
-| `/free` | the corner widget with nothing configured — agent name and variables are typed in, `+ Variable` adds a row; the organisation's API key is a field in the page itself |
-
-All three are clean URLs — no `.html`, since these links get pasted to
-clients. The old paths (`/index.html`, `/call-details.html`,
-`/free-form.html`, anything under `/example/`) answer `301` to the short
-form, so a link already shared keeps working.
-
-On iOS Safari, note that the network round trip between the click and
-`startCall()` can consume the user gesture that audio playback requires. A
-widget that has to support iOS should fetch the session before the click and
-hand it straight to `startCall()`.
+| `/` | a site with the call widget pinned in the corner |
+| `/avatar` | draggable avatar mode: the live AI avatar once the call connects, a bundled presenter clip as the failover |
+| `/call` | the call as the whole page, with a branded column |
+| `/free` | the same with nothing configured: agent, variables and key typed in |
+| `/file` | `/free`, plus an mp3 or wav file played into the call in place of the microphone |
 
-### Embedding the widget
+What to carry over into your own integration: the Web API key lives only on
+the server, the browser names only variable values, and the server accepts
+values only for the variables it declared itself. The shared widget is `src/widget.ts`; `example/demo-widget.js` supplies the
+backend callback and uses `example/demo-call.js` for scenario fields.
 
-The SDK is headless: it ships no markup, no CSS and no themes. Your page owns
-every pixel. `example/index.html` together with `example/widget.css` is a
-reference you copy into your project and edit — not a component the package
-delivers.
+### Demo box
 
-**Markup.** The widget is a launcher plus a panel, both inside one root
-element that carries the tokens:
-
-```html
-<div class="ht-widget">
-  <button class="ht-launcher" id="launcher">…</button>
-  <section class="ht-panel" id="panel" hidden>
-    <header class="ht-head">
-      <span class="ht-title">Voice agent</span>
-      <span class="ht-pill" id="pill">Ready</span>
-      <span class="ht-timer" id="timer" hidden>0:00</span>
-      <button class="ht-icon" id="collapse">…</button>
-    </header>
-    <details class="ht-details" id="details" open>
-      <summary>Call details</summary>
-      <div class="ht-fields" id="fields"></div>
-    </details>
-    <div class="ht-log" id="log"></div>
-    <div class="ht-debug" id="state"></div>
-    <div class="ht-composer">
-      <input id="message" disabled />
-      <button class="ht-icon" id="send" disabled>…</button>
-    </div>
-    <div class="ht-actions">
-      <button class="ht-btn" id="call">Call</button>
-      <button class="ht-btn ht-btn-ghost" id="chat">Chat</button>
-      <button class="ht-btn ht-btn-danger" id="hangup" disabled>Hang up</button>
-    </div>
-  </section>
-</div>
-```
-
-The `<details>` block is where the dynamic variables are typed; the widget
-hides it for the duration of a call. `Chat` is the same call with
-`{ audio: false }` — see “Chat-only calls” above.
-
-**The wiring is shared, not duplicated.** `example/demo-call.js` holds the
-part that is identical on all three example pages — transcript bubbles, the
-timer, the composer, session creation, `startCall` — and each page passes its
-own nodes and its own layout hooks:
-
-```js
-HtDemo.mountCall({
-  client: new VoiceClient(),
-  agentId: AGENT_ID, // '' → the form asks the visitor for an Agent name
-  refs: { pill, timer, state, log, empty, message, send, call, chat, hangup, liveDot },
-  readVariables: () => HtDemo.readValues(fieldsEl),
-  onCallStarted: () => { /* your layout switch */ },
-  onCallEnded: (reason) => { /* and back */ },
-});
-```
-
-Every `refs` node is optional — a page passes what its markup has, and the
-wiring skips the rest. `mountCall` returns `{ startVoice, startChatOnly,
-stop, render }` for a page that wants to drive the call from something other
-than the `call` / `chat` / `hangup` buttons.
-
-The rest of `HtDemo` is the form half, which is why no page repeats it:
-
-| Helper | Does |
-|---|---|
-| `loadConfig()` | `GET /api/config` — the active scenario's `fields` and `hero` |
-| `renderFields(container, fields, agentId)` | the variable inputs, preceded by an Agent name input when `agentId` is empty |
-| `readValues(container)` | what the visitor typed, keyed by dynamic variable, read off the DOM |
-| `applyHero(root, hero)` | fills every `[data-hero="<key>"]` node, keeping the markup's own copy as the fallback |
-| `createSession(variables, agentId)` | `POST /api/session` |
-
-**Wiring.** Which SDK event drives which node:
-
-| Event | Node |
-|---|---|
-| `connectionStateChanged`, `agentStateChanged` | the state pill and the raw debug line |
-| `transcript` | one bubble per segment `id`; `final: false` renders as interim |
-| `callStarted` | clears the log, starts the timer, enables the composer and Hang up |
-| `callEnded` | stops the timer, disables the composer, appends why it ended |
-| `error` | stops the timer, hides the live dot, appends the code plus its English line to the log |
-
-Collapsing the panel is presentation only — never call `stopCall()` from it,
-or a visitor loses the conversation by tidying the widget away.
-
-**Restyling.** Override the tokens on `.ht-widget`; nothing else needs
-touching:
-
-| Token | What it paints |
-|---|---|
-| `--accent`, `--accent-contrast` | the launcher, the Call button, the visitor's bubbles |
-| `--bg-panel`, `--bg-elev` | the panel surface and the agent's bubbles |
-| `--text`, `--text-dim` | primary and secondary text |
-| `--border` | every hairline |
-| `--radius`, `--radius-sm` | corner softness |
-| `--hero-bg`, `--hero-text` | the branded column of the call page (deliberately the same in both schemes — a brand block does not invert) |
-
-```css
-.ht-widget {
-  --accent: #1f6feb;
-  --accent-contrast: #ffffff;
-  --radius: 8px;
-}
-```
-
-The file ships both palettes and follows `prefers-color-scheme`; override a
-token inside your own media query to diverge per scheme.
-
-**Boundaries.** The tokens are declared on the `.ht-demo` / `.ht-call` /
-`.ht-widget` roots rather than on `:root`, and every class carries the `ht-`
-prefix — loading the file cannot repaint your site. Copy the `.ht-widget`
-block plus the shared form primitives (`.ht-details`, `.ht-fields`,
-`.ht-field*`, `.ht-btn*`) and leave the `.ht-demo` / `.ht-call` page sections
-behind. The package does not serve the stylesheet: copy it into your own
-build.
-
-### Deploying the example
-
-The deployment script builds the SDK and runs the example server on the same
-machine. Put the required API configuration in `.env` at the project root.
+The example server runs under the
+`example/hubtalk-webrtc-example.service` unit (fix `User` and
+`WorkingDirectory` before installing it elsewhere), behind an HTTPS proxy —
+browsers need a secure context. A sample proxy config is
+`example/caller-widget.demo.cyberdev.kz.Caddyfile`.
 
 ```bash
-scripts/deploy-example.sh
+npm run build   # required: dist/ is gitignored, so git pull never updates the bundle
+sudo systemctl restart hubtalk-webrtc-example
 ```
 
-Set `PORT` to choose a port (default `8000`). For public access, put this
-server behind an HTTPS reverse proxy, since browsers require a secure context
-for microphone and WebRTC access.
+## Optional widget (VPT-857)
 
-### Running with systemd
+**What you get today.** Avatar mode works against any current HubTalk
+platform: the circle plays the bundled clip failover (poster, listening loop,
+speaking loop, Video.js) and the call is the ordinary voice call. The live AI
+avatar described further down needs platform support that is not deployed
+yet; until it is, every call shows the clips, and nothing in your integration
+changes when it arrives — the widget switches to live video by itself.
 
-The included unit runs the example after the network is available and restarts
-it after a failure. It ships configured for the demo box — user
-`cybernet-adm`, checkout at `/home/cybernet-adm/hubtalk-web-sdk` — so edit
-`User` and `WorkingDirectory` before installing it anywhere else. It passes
-no `EnvironmentFile`: the server reads `.env` from the checkout itself.
+**Try it in five minutes.**
 
-```bash
-sudo cp example/hubtalk-webrtc-example.service /etc/systemd/system/
-sudo systemctl daemon-reload
-sudo systemctl enable --now hubtalk-webrtc-example
-sudo systemctl status hubtalk-webrtc-example
+1. `npm ci && npm run build` in this repository.
+2. Copy `.env.example` to `.env` in the repository root and fill in the Web API key
+   and the agent name.
+3. `python3 example/server.py`, then open `http://127.0.0.1:8000/avatar`.
+   `/` is the same widget in standard mode, `/free` the hand-written example.
+4. Press the circle to call, press it again to mute, open Chat for the
+   transcript and End call. Replace the three files in `example/` with your
+   own poster and silent clips (see `example/AVATAR-MEDIA.md`) to see your
+   presenter.
+
+```ts
+import {
+  mountWidget,
+  type WidgetOptions,
+  type WidgetHandle,
+  type AvatarMedia,
+  type CreateSessionContext,
+} from '@hubtalk-ai/web-sdk/widget';
+import '@hubtalk-ai/web-sdk/widget.css';
+
+const widget = mountWidget({
+  container: document.getElementById('support')!,
+  mode: 'avatar', // omit for the standard launcher and call/chat panel
+  async createSession({ avatar }: CreateSessionContext) {
+    // avatar is true in avatar mode: forward it to your backend, which sets
+    // `avatar: true` on POST /v1/calls/web (see "Live avatar" below)
+    const response = await fetch('/api/session', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ avatar }),
+    });
+    if (!response.ok) throw new Error('Session unavailable');
+    return response.json(); // { access_token, url }, never a Web API key
+  },
+  // the clip FAILOVER, shown whenever there is no live avatar video
+  avatar: {
+    posterUrl: '/presenter/poster.jpg',
+    listeningVideoUrl: '/presenter/listening.mp4',
+    speakingVideoUrl: '/presenter/speaking.mp4',
+    size: 140, // circle diameter in px, optional; this is the default
+  },
+});
+// On page/component teardown:
+widget.destroy(); // idempotent; stops the call and disposes owned DOM/media
 ```
 
-**`dist/` is gitignored, so `git pull` never updates the bundle the browser
-loads.** A pull plus a restart keeps serving the SDK that was last built on
-that machine — the page works, it is just the previous code, which is a very
-quiet way to lose an afternoon. Always build:
+Without a frontend build, host these two files from `dist/`:
 
-```bash
-npm run build
-sudo systemctl restart hubtalk-webrtc-example
+```html
+<link rel="stylesheet" href="/sdk/widget.css">
+<div id="support"></div>
+<script src="/sdk/widget.bundle.js"></script>
+<script>
+  const widget = HubTalkWidget.mountWidget({
+    container: document.getElementById('support'),
+    createSession: async () => {
+      const response = await fetch('/api/session', { method: 'POST' });
+      if (!response.ok) throw new Error('Session unavailable');
+      return response.json();
+    }
+  });
+</script>
 ```
 
-Two guards make that hard to forget: the unit re-copied from
-`example/hubtalk-webrtc-example.service` rebuilds on every restart
-(`ExecStartPre`), and the server prints a loud warning at startup when
-`dist/voice-client.bundle.js` is older than `src/`. The pages and the bundle
-are served `Cache-Control: no-store`, so a plain reload is enough — no
-Ctrl+F5.
+Both distributions expose `mountWidget(options: WidgetOptions): WidgetHandle`.
+`WidgetOptions` requires `container` and `createSession`; `mode` defaults to
+`standard`. Avatar mode additionally requires all three `AvatarMedia` URLs
+(the failover media); optional `avatar.size` sets the circle diameter in
+pixels (default 140, phones show 6/7 of it) — or set `--ht-avatar-size` on
+`.ht-widget` from your CSS. `createSession` is called with
+`{ avatar: boolean }` — `true` in avatar mode, `false` in standard mode;
+callbacks that ignore the argument keep working. Optional
+`renderCallDetails(container)` mounts your form once; `createSession` reads
+its current values from a closure. The widget hides the form while a call
+runs and restores it on end. See `example/demo-widget.js`.
+
+### Live avatar
+
+In avatar mode the circle shows the **live video of an AI avatar** — a
+LiveKit avatar worker that joins the call on the agent's behalf and publishes
+video lip-synced to the agent's voice (provider Anam; the stock face "Layla"
+by default, configurable per agent). Three things must all be true for it to
+start, otherwise the call runs audio-only and the widget shows the clip
+failover:
+
+1. your backend forwards the widget's ask as `"avatar": true` in the body of
+   `POST /v1/calls/web` (the platform treats it as a request, not a
+   guarantee; the response shape does not change);
+2. the agent's **Avatar** setting is enabled in the HubTalk editor
+   (Settings → Additional → AI avatar; off by default, cascade pipeline only);
+3. the platform contour has the avatar provider configured.
+
+Media precedence, highest first: **live video** → **clip failover**
+(`listeningVideoUrl`/`speakingVideoUrl`) → **poster**. Falling back to clips
+is a normal state, not an error: it covers the time before the call, the
+seconds while the avatar joins, an agent with the avatar off, a slow or
+unavailable provider, and a live video that drops mid-call. While live video
+plays, the clip player pauses and hides (and is not loaded at all if no clip
+was needed before); when it drops, the clips resume. The live `<video>` is
+muted, inline and without controls — the voice always comes from the SDK's
+audio path, never from a video element, so it is heard exactly once.
+
+Headless integrations get the same signal from `VoiceClient`:
+`agentVideoChanged: { available }` fires when the worker's video track is
+subscribed or goes away (reset to `false` on call end, failed startup and
+`destroy()`), and `attachAgentVideo(element)` attaches the current and any
+later track to your `<video>` and returns a detach function (a no-op outside
+a call). The worker is the remote participant of kind `agent` whose
+`lk.publish_on_behalf` attribute equals the agent's identity; agent state
+stays on the agent's own `lk.agent.state`.
+
+**Disclosure.** A visible **AI avatar** label shows on the circle while live
+video plays and is also the circle's accessible description. There is no
+burned-in watermark. Telling visitors that they talk to an AI, where your
+jurisdiction requires it, stays the integrator's duty; the label helps but
+does not replace it.
+
+Live video arrives over the existing LiveKit connection: no new CSP origin
+is needed beyond the `connect-src` and `media-src blob:` entries below. The
+agent's voice and the avatar video pass through the provider's cloud —
+check that with your data-protection owner before enabling the setting on a
+regulated deployment.
+
+The circle starts a voice call, then toggles **only your microphone**. Agent
+audio keeps playing. The separate Chat launcher toggles the panel; End call
+inside ends the call. The panel's Chat control starts a text-only call.
+Keyboard Enter/Space activates buttons; focus remains visible. Dragging does
+not start/mute a call. Position is clamped to the viewport and is not saved.
+The panel and avatar stay separately reachable on mobile.
+
+For the clip failover, supply a poster and silent H.264 MP4 loops of the
+**same cleared person**. The clips do not synchronize phonemes: the speaking
+loop follows agent state. Rings/status text distinguish speech, listening,
+muted, idle and connecting. Thinking/initializing are not labelled listening.
+Clip loading/failure, blocked clip autoplay and reduced motion use the poster
+while call controls remain available; reduced motion keeps the live video
+and disables ring animation. The example bundles a presenter cut from a
+Pexels clip (Pexels License, provenance and the regenerating script in
+`example/AVATAR-MEDIA.md`); it is example media, not a cleared likeness for
+your site — replace it with your own.
+
+Video.js **8.24.0** is pinned. ESM dynamically imports it only for avatar mode,
+and only the first time a clip is needed. The self-contained IIFE includes the
+player code and initializes it only for avatar mode; its full download cost
+applies to either widget mode. Root ESM
+and `voice-client.bundle.js` have no widget/Video.js imports. Widget CSS is
+explicit and scoped; `sideEffects` preserves CSS in consumer builds.
+
+Serve over HTTPS. Allow your SDK host in `script-src`/`style-src`, poster host
+in `img-src`, clip host in `media-src`, and your backend and LiveKit HTTPS/WSS
+origins in `connect-src`. WebRTC playback also needs `media-src blob:`; the
+widget/Video.js uses inline style attributes for positioning, so permit them
+with `style-src-attr 'unsafe-inline'`. Do not enable arbitrary remote origins.
+A restrictive host media policy may force poster fallback. No CDN is required.
+
+### Microphone and playback controls
+
+`VoiceClient.isMicrophoneEnabled()` starts false. Await
+`setMicrophoneEnabled(enabled)` to change an active audio call. The
+`microphoneStateChanged` event carries `{ enabled }` after confirmation and
+resets to false on termination. Failed toggles preserve the last confirmed
+state and the call. Connecting/reconnecting, text-only and inactive calls
+reject these controls with `NOT_IN_CALL` without changing call state.
+
+Browser playback permission is separate from microphone permission. The
+initial gesture may be lost while your backend creates a session, especially
+on iOS. `audioPlaybackBlocked` leaves the call connected; the widget presents
+**Enable sound**, whose tap calls `resumeAudio()`. A repeated block rejects
+with `AUDIO_PLAYBACK_BLOCKED`, keeps the prompt and never republishes the mic.
+A denied microphone still fails voice startup. `stopCall()` ends the call;
+muting does not.
+
+### Validation
+
+Run `npm test`, `npm run lint`, `npm run format:check`, `npm run build`.
+Browser checks: `npx playwright install chromium webkit && npm run test:browser`.
+With installed Chrome: `PLAYWRIGHT_CHROME_CHANNEL=chrome npm run test:browser -- --project=chromium`.
+See `VALIDATION.md` for measured build sizes and outstanding device/live-call gates.