svelte-elevenlabs 0.5.1 → 0.6.0

package/README.md

@@ -1,5 +1,9 @@
 # svelte-elevenlabs
 
+[![ConversationWidget running a live ElevenLabs session](https://raw.githubusercontent.com/GABRYCA/svelte-elevenlabs/main/docs/media/conversation-widget-demo.gif)](https://github.com/GABRYCA/svelte-elevenlabs/blob/main/docs/media/conversation-widget-demo.mp4)
+
+A live session recorded from the showcase at `/demo`. Click the preview for the MP4 with sound.
+
 > **This is an independent community project. Not affiliated with or endorsed by ElevenLabs Inc.**
 
 A Svelte 5 library and SvelteKit 3 showcase for ElevenLabs Conversational AI. One controller opens a low-latency voice or text session, exposes reactive call state, streams PCM audio over a WebSocket, and releases its sockets, media tracks, audio nodes, and timers on teardown.
@@ -31,7 +35,7 @@ The showcase server and package tooling run on **Node 22.17 or newer** and **Bun
 - **Ready-made UI.** `<AudioVisualizer>` and `<ConversationWidget>` consume the same controller. The widget supports voice, text, feedback, playback volume, device selection, transcripts, queue state, and theming through CSS custom properties.
 - **Safe signed URLs.** The included SvelteKit route validates `agent_` and `seng_` ids, sets `Cache-Control: no-store`, and keeps `ELEVENLABS_API_KEY` on the server. The static Pages build removes the route and disables signed mode in the UI.
 
-The repository also contains a runnable SvelteKit 3 showcase in `src/routes`. It demonstrates the controller, signed and public connection modes, voice and text sessions, device controls, feedback, and the diagnostic console.
+The repository also contains a runnable SvelteKit 3 showcase in `src/routes`. It demonstrates the controller, signed and public connection modes, voice and text sessions, device controls, feedback, and the diagnostic console. The `/demo` page renders `<ConversationWidget>` on its own, with a focus view for recording, and the `svelte-elevenlabs agents` command installs a reviewed guide for coding agents.
 
 ## Documentation
 
@@ -39,6 +43,7 @@ The showcase ships a documentation section at [gabryca.github.io/svelte-elevenla
 
 - **Start here:** overview, install, and quickstart.
 - **Guides:** sessions, audio, client tools, components, and signed URLs.
+- **Tooling:** the agent kit for coding agents.
 - **Reference:** API reference and troubleshooting.
 
 Run `bun run dev` and open `http://localhost:5173/docs` to read it locally. The static Pages build includes the same pages and respects `PAGES_BASE_PATH`, while the signed URL guide explains why that route only exists on the Node or Bun server.
@@ -55,6 +60,36 @@ The same material is published as plain Markdown for coding agents and other lan
 
 The files are prerendered, so they exist in the Node, Bun, and static Pages builds. Absolute links follow `PAGES_BASE_PATH`, and the reference version is read from `package.json`.
 
+The agent kit is a shorter, decision-focused companion for project work. It installs into the consumer project instead of replacing these endpoints.
+
+## Agent kit
+
+The package ships a canonical guide for coding agents and a small installer that writes it into the file each tool already reads.
+
+```sh
+# Bun
+bunx svelte-elevenlabs agents install
+
+# npm
+npx svelte-elevenlabs agents install
+```
+
+With no target names, the command detects Claude Code, Cursor, OpenCode, GitHub Copilot, Windsurf, Cline, Gemini CLI, and `AGENTS.md` aware tools in the current project. When it cannot detect one, it adds a managed block to `AGENTS.md`. Choose targets explicitly when you want more:
+
+```sh
+bunx svelte-elevenlabs agents install claude cursor opencode
+bunx svelte-elevenlabs agents install --all
+bunx svelte-elevenlabs agents install claude --dry-run
+```
+
+Targets are `claude`, `cursor`, `opencode`, `copilot`, `windsurf`, `cline`, `gemini`, and `agents`. Shared files such as `AGENTS.md`, `GEMINI.md`, and `.github/copilot-instructions.md` keep their existing content. The installer updates only the block between `svelte-elevenlabs:agent-kit:start` and `svelte-elevenlabs:agent-kit:end`. Dedicated skill and rule files are skipped when they already exist without a managed block unless you pass `--force`.
+
+Use `agents list` to print every destination path and `agents print` to send the guide to standard output. The canonical source is [`agent-kit/instructions.md`](https://github.com/GABRYCA/svelte-elevenlabs/blob/main/agent-kit/instructions.md), and the full guide is at [gabryca.github.io/svelte-elevenlabs/docs/agents](https://gabryca.github.io/svelte-elevenlabs/docs/agents).
+
+## Live demo
+
+The showcase includes a focus view at [gabryca.github.io/svelte-elevenlabs/demo](https://gabryca.github.io/svelte-elevenlabs/demo). It renders `<ConversationWidget>` against a live agent with the same controller as the main console. The Node and Bun builds use signed URLs; the static Pages build uses a public agent id.
+
 ## Requirements
 
 | Requirement | Version or note                                                             |
@@ -640,9 +675,18 @@ The project uses SvelteKit 3, whose Vite configuration lives in `vite.config.ts`
 
 The release workflow runs on every push to `main`, tags new package versions, publishes GitHub releases, deploys Pages, and uploads build artifacts. Pull request CI runs the same checks without touching ElevenLabs quota. Both install with a frozen lockfile.
 
-### Package layout
+### Repository layout
 
 ```text
+agent-kit/
+  instructions.md                 # canonical guide for coding agents
+  README.md                       # install notes and target table
+bin/
+  svelte-elevenlabs.js            # dependency free agents CLI
+docs/media/
+  conversation-widget-demo.gif    # README preview
+  conversation-widget-demo.mp4    # clip with sound
+  conversation-widget-demo-poster.jpg
 src/
   env.ts                          # explicit public demo env for SvelteKit 3
   lib/
@@ -659,12 +703,16 @@ src/
   routes/
     +layout.ts                    # prerender only in Pages mode
     +page.svelte                  # live signal-console showcase
+    demo/+page.svelte             # ConversationWidget demo and focus view
+    docs/agents/+page.svelte      # agent kit documentation
     api/signed-url/+server.ts     # server-only signed URL exchange
 ```
 
+The published tarball contains `dist`, `agent-kit`, `bin`, `README.md`, and `LICENSE`. The showcase in `src` and the media in `docs` stay in the repository.
+
 ## Publishing
 
-The package version is `0.5.1`. `prepack` runs `svelte-kit sync`, `svelte-package`, and `publint`, so `dist` is rebuilt from source before every publish.
+The package version is `0.6.0`. `prepack` runs `svelte-kit sync`, `svelte-package`, and `publint`, so `dist` is rebuilt from source before every publish.
 
 ```sh
 bun run prepack
@@ -672,7 +720,7 @@ npm pack --dry-run
 npm publish --access public
 ```
 
-`publishConfig.access` is already `public`. The published files are limited to `dist`, and the package exposes the root entry plus the `audio`, `types`, and `package.json` subpaths.
+`publishConfig.access` is already `public`. The published files include `dist`, `agent-kit`, and `bin`. The package exposes the root entry plus the `audio`, `types`, and `package.json` subpaths, and the `svelte-elevenlabs` bin entry provides the agent kit command.
 
 When you push a version bump to `main`, the release workflow creates the `v<version>` tag, publishes the GitHub release, and attaches the same tarball that `bun pm pack` produces. You can still publish to npm manually from that tarball.
 

package/agent-kit/README.md

@@ -0,0 +1,97 @@
+# Agent kit
+
+Rules, snippets, and a one-command installer that teach coding agents how to use
+`svelte-elevenlabs` correctly.
+
+Coding agents often guess API names, forget that `useConversation` must run
+during component initialisation, or move an API key into a client component.
+This kit gives them one accurate source file and places it where Claude Code,
+Cursor, OpenCode, GitHub Copilot, Windsurf, Cline, Gemini CLI, and generic
+`AGENTS.md` aware tools already look.
+
+## Install
+
+Run the command inside the SvelteKit project that uses the package:
+
+```sh
+# Bun
+bunx svelte-elevenlabs agents install
+
+# npm
+npx svelte-elevenlabs agents install
+```
+
+With no target names the command detects the agents configured in the project.
+When it cannot detect one, it adds a managed block to `AGENTS.md`.
+
+Choose targets explicitly when you want more than detection finds:
+
+```sh
+bunx svelte-elevenlabs agents install claude cursor opencode
+bunx svelte-elevenlabs agents install --all
+bunx svelte-elevenlabs agents install claude --dry-run
+bunx svelte-elevenlabs agents install claude --force
+```
+
+Use `agents list` to see every target and destination path, and `agents print`
+to send the guide to standard output:
+
+```sh
+bunx svelte-elevenlabs agents list
+bunx svelte-elevenlabs agents print cursor
+```
+
+## Targets
+
+| Name       | Tool                                                | Destination                                   |
+| ---------- | --------------------------------------------------- | --------------------------------------------- |
+| `claude`   | Claude Code                                         | `.claude/skills/svelte-elevenlabs/SKILL.md`   |
+| `cursor`   | Cursor                                              | `.cursor/rules/svelte-elevenlabs.mdc`         |
+| `opencode` | OpenCode                                            | `.opencode/skills/svelte-elevenlabs/SKILL.md` |
+| `copilot`  | GitHub Copilot                                      | `.github/copilot-instructions.md`             |
+| `windsurf` | Windsurf                                            | `.windsurf/rules/svelte-elevenlabs.md`        |
+| `cline`    | Cline                                               | `.clinerules/svelte-elevenlabs.md`            |
+| `gemini`   | Gemini CLI                                          | `GEMINI.md`                                   |
+| `agents`   | Codex, OpenCode, Jules, and other `AGENTS.md` tools | `AGENTS.md`                                   |
+
+Shared files such as `AGENTS.md`, `GEMINI.md`, and the Copilot instructions keep
+your existing content. The installer adds or updates a marked block between
+`svelte-elevenlabs:agent-kit:start` and `svelte-elevenlabs:agent-kit:end`.
+Running the command again replaces only that block.
+
+Dedicated skill and rule files are only overwritten with `--force`.
+
+## Manual installation
+
+If you cannot run the command, copy the contents of
+[`instructions.md`](./instructions.md) into the file your tool reads. For a
+Claude Code or OpenCode skill, add this frontmatter above it:
+
+```yaml
+---
+name: svelte-elevenlabs
+description: Build or review Svelte 5 ElevenLabs Conversational AI voice and text sessions with svelte-elevenlabs.
+license: MIT
+---
+```
+
+The canonical guide is also published at
+[gabryca.github.io/svelte-elevenlabs/docs/agents](https://gabryca.github.io/svelte-elevenlabs/docs/agents),
+and the full API reference is at
+[llms-full.txt](https://gabryca.github.io/svelte-elevenlabs/llms-full.txt).
+
+## What the guide covers
+
+- The non negotiable rules for secrets, lifecycle, and secure contexts.
+- A minimal voice component and a signed URL server route.
+- `ConversationWidget`, `AudioVisualizer`, and `ConversationProvider`.
+- Text only sessions and typed turns.
+- Client tools, MCP approvals, feedback, and device controls.
+- The reactive controller surface and the options that change behavior.
+- Error codes and a review checklist.
+
+## Safety
+
+The agent kit never contains an API key and never asks an agent to create one in
+the browser. Signed URL work stays on the server. The kit is plain Markdown, so
+you can review every line before you commit it.

package/agent-kit/instructions.md

@@ -0,0 +1,472 @@
+# svelte-elevenlabs agent guide
+
+This guide is for coding agents that add, review, or repair an ElevenLabs
+Conversational AI integration in a Svelte 5 or SvelteKit project. It is
+installed by the `svelte-elevenlabs agents` command and is safe to keep under
+version control.
+
+Package: `svelte-elevenlabs`
+Canonical documentation: https://gabryca.github.io/svelte-elevenlabs/docs
+Complete machine reference: https://gabryca.github.io/svelte-elevenlabs/llms-full.txt
+Live demo: https://gabryca.github.io/svelte-elevenlabs/demo
+Source and issues: https://github.com/GABRYCA/svelte-elevenlabs
+
+## What the package does
+
+`svelte-elevenlabs` is an independent, MIT licensed Svelte 5 library for
+ElevenLabs Conversational AI. One controller owns the browser side of a voice
+or text session:
+
+- The WebSocket handshake with the Conversational AI endpoint.
+- Microphone capture, low-pass filtering, resampling, PCM16 framing, and base64
+  transport.
+- Agent playback on one audio clock, with immediate barge-in flushing.
+- Transcripts, latency, queue state, device controls, client tools, feedback,
+  and typed turns.
+- Teardown of sockets, media tracks, worklet URLs, timers, and audio contexts.
+
+The package is not an official ElevenLabs SDK. It follows the public
+Conversational AI WebSocket protocol and reports failures with stable error
+codes.
+
+## Rules that must not be broken
+
+1. Never expose `ELEVENLABS_API_KEY` in a client component, a `PUBLIC_*`
+   variable, a route response, a log line, or a static build. Only a server
+   route may read `process.env.ELEVENLABS_API_KEY`.
+2. Call `useConversation` during component initialisation, directly inside
+   `<script>`. Do not call it inside `onMount`, an event handler, a loop, or a
+   conditional that can change later. It registers an `$effect` teardown.
+3. Call `startConversation` from a user gesture such as a click or tap. Do not
+   start a voice session during server-side rendering, module evaluation, or
+   page load.
+4. Use `createConversation` outside a component and call `destroy()` yourself
+   when the owner is disposed. This applies to stores, tests, workers, and
+   custom lifecycle code.
+5. Use a `.svelte.ts` or `.svelte.js` file when a module needs runes. A plain
+   `.ts` module cannot use `$state`, `$derived`, or `$effect`.
+6. In a reusable package, keep `$app/*` and `$env/*` imports out of the
+   library entry. The `svelte-elevenlabs` package itself follows this rule.
+7. Prefer signed URLs for private agents and production traffic. A public agent
+   id is acceptable for a demo only.
+8. Text only sessions still need a valid agent and an open WebSocket. They skip
+   microphone permission and Web Audio setup.
+9. Do not invent method names or options. Use the API in this guide or read the
+   installed TypeScript declarations before writing code.
+10. Keep compatibility with Svelte 5, Node 22.17 or newer, and Bun 1.4 or newer.
+    Do not add a dependency when a small local function will do.
+
+## Requirements
+
+| Requirement | Version or note                                                             |
+| ----------- | --------------------------------------------------------------------------- |
+| Svelte      | 5.x peer dependency                                                         |
+| SvelteKit   | Optional, needed for the signed URL route and server rendering              |
+| Node        | 22.17 or newer for a server build and package tooling                       |
+| Bun         | 1.4 or newer for the included scripts                                       |
+| Browser     | WebSocket. Voice also needs Web Audio, `getUserMedia`, and a secure context |
+| ElevenLabs  | An agent id. Signed mode also needs a workspace API key                     |
+
+The microphone requires HTTPS or localhost. The controller reports an
+`insecure-context` error when the page is not in a secure context.
+
+## Install
+
+```sh
+# Bun
+bun add svelte-elevenlabs
+
+# npm
+npm install svelte-elevenlabs
+```
+
+The package is ESM only. The root entry contains Svelte components, so use a
+Svelte aware bundler. Node scripts and tests can import the Node safe subpaths:
+
+```ts
+import { parseAudioFormat, resampleLinear } from 'svelte-elevenlabs/audio';
+import type { AudioFormat, ConversationOptions } from 'svelte-elevenlabs/types';
+```
+
+## Minimal voice component
+
+```svelte
+<script lang="ts">
+	import { useConversation } from 'svelte-elevenlabs';
+
+	const conversation = useConversation({
+		agentId: 'agent_your_public_id',
+		onError: (error) => console.error('[voice]', error.code, error.message)
+	});
+
+	function toggle(): void {
+		if (conversation.status === 'disconnected') {
+			void conversation.startConversation();
+			return;
+		}
+
+		conversation.stopConversation();
+	}
+</script>
+
+<button type="button" onclick={toggle} aria-busy={conversation.status === 'connecting'}>
+	{conversation.status === 'connected' ? 'End conversation' : 'Start conversation'}
+</button>
+
+{#if conversation.error}
+	<p role="alert">{conversation.error}</p>
+{/if}
+```
+
+`startConversation` resolves after metadata negotiation or after a start
+failure. Connection and audio failures are published through `error`,
+`errorCode`, and `onError` instead of rejecting, so a `void` call is safe.
+
+## Signed URL server route
+
+Create `src/routes/api/signed-url/+server.ts`. Keep the key on the server and
+return only the short-lived URL.
+
+```ts
+import { json } from '@sveltejs/kit';
+import type { RequestHandler } from './$types';
+
+const ORIGIN = 'https://api.elevenlabs.io';
+const AGENT_ID = /^(agent|seng)_[A-Za-z0-9]+$/;
+
+export const prerender = false;
+
+export const GET: RequestHandler = async ({ url, fetch, request, setHeaders }) => {
+	setHeaders({ 'cache-control': 'no-store' });
+
+	const agentId = url.searchParams.get('agent_id')?.trim() ?? '';
+	if (!AGENT_ID.test(agentId)) {
+		return json(
+			{ error: { message: 'Add a valid agent_id query parameter.' } },
+			{ status: 400, headers: { 'cache-control': 'no-store' } }
+		);
+	}
+
+	const apiKey = process.env.ELEVENLABS_API_KEY?.trim() ?? '';
+	if (!apiKey) {
+		return json(
+			{ error: { message: 'ELEVENLABS_API_KEY is missing on the server.' } },
+			{ status: 500, headers: { 'cache-control': 'no-store' } }
+		);
+	}
+
+	const upstream = await fetch(
+		`${ORIGIN}/v1/convai/conversation/get-signed-url?agent_id=${agentId}`,
+		{
+			headers: { accept: 'application/json', 'xi-api-key': apiKey },
+			signal: request.signal
+		}
+	);
+
+	if (!upstream.ok) {
+		return json(
+			{ error: { message: 'ElevenLabs could not create a signed URL.' } },
+			{ status: 502, headers: { 'cache-control': 'no-store' } }
+		);
+	}
+
+	const body: unknown = await upstream.json().catch(() => null);
+	const signedUrl =
+		typeof body === 'object' && body !== null && 'signed_url' in body ? body.signed_url : null;
+
+	if (typeof signedUrl !== 'string' || !signedUrl.startsWith('wss://')) {
+		return json(
+			{ error: { message: 'ElevenLabs returned an unexpected payload.' } },
+			{ status: 502, headers: { 'cache-control': 'no-store' } }
+		);
+	}
+
+	return json({ signed_url: signedUrl }, { headers: { 'cache-control': 'no-store' } });
+};
+```
+
+Then start the session with signed mode:
+
+```ts
+await conversation.startConversation('agent_your_private_id', { signed: true });
+```
+
+The default endpoint is `/api/signed-url`. Set `signedUrlEndpoint` when your
+route lives elsewhere. A signed URL is a credential. Do not log it or send it
+to a third party.
+
+For a static build there is no server route. Use a public agent id, or let the
+visitor paste a signed URL they already have. Never put the API key in a static
+artifact.
+
+## Ready-made UI
+
+```svelte
+<script lang="ts">
+	import { ConversationWidget, useConversation } from 'svelte-elevenlabs';
+
+	const conversation = useConversation({ agentId: 'agent_your_public_id' });
+</script>
+
+<ConversationWidget
+	controller={conversation}
+	title="Support line"
+	subtitle="Voice or text"
+	signed={false}
+/>
+```
+
+`ConversationWidget` owns its own controller when `controller` is omitted. When
+you pass a controller, the widget mirrors it and shares its state with the rest
+of the page. The visualizer is also available on its own:
+
+```svelte
+<script lang="ts">
+	import { AudioVisualizer, useConversation } from 'svelte-elevenlabs';
+
+	const conversation = useConversation({ agentId: 'agent_your_public_id' });
+</script>
+
+<AudioVisualizer {conversation} height={212} />
+```
+
+The components use scoped styles. In a Tailwind 4 app, add the package output to
+the source scan so utility class names are discovered:
+
+```css
+@import 'tailwindcss';
+@source '../node_modules/svelte-elevenlabs/dist';
+```
+
+## Text only sessions
+
+```svelte
+<script lang="ts">
+	import { useConversation } from 'svelte-elevenlabs';
+
+	const conversation = useConversation({
+		agentId: 'agent_your_public_id',
+		textOnly: true
+	});
+
+	let draft = $state('');
+
+	function send(event: SubmitEvent): void {
+		event.preventDefault();
+		if (conversation.sendUserMessage(draft)) draft = '';
+	}
+</script>
+
+<button type="button" onclick={() => conversation.startConversation()}> Open chat </button>
+
+<form onsubmit={send}>
+	<input bind:value={draft} aria-label="Message" />
+	<button type="submit">Send</button>
+</form>
+```
+
+A per session override is available when one controller needs both modes:
+
+```ts
+await conversation.startConversation('agent_your_public_id', { textOnly: true });
+```
+
+## Provider and client tools
+
+Use the provider when several components need the same session. Use
+`useConversationClientTool` for a tool that should disappear when its component
+unmounts.
+
+```svelte
+<!-- OrderTool.svelte -->
+<script lang="ts">
+	import { useConversationClientTool } from 'svelte-elevenlabs';
+
+	useConversationClientTool('get_order', async ({ orderId }) => {
+		return { orderId, status: 'shipped' };
+	});
+</script>
+
+<span>Order tool ready</span>
+```
+
+```svelte
+<!-- App.svelte -->
+<script lang="ts">
+	import { ConversationProvider, ConversationWidget } from 'svelte-elevenlabs';
+	import OrderTool from './OrderTool.svelte';
+</script>
+
+<ConversationProvider options={{ agentId: 'agent_your_public_id' }}>
+	<OrderTool />
+	<ConversationWidget />
+</ConversationProvider>
+```
+
+Tool names must match the tool names configured on the ElevenLabs agent. A
+named tool takes precedence over the `onClientToolCall` fallback. The handler
+may return a string or a JSON serialisable value.
+
+## Lifecycle and cleanup
+
+`useConversation` registers an `$effect` teardown. It closes the socket, stops
+media tracks, disconnects the audio graph, revokes worklet URLs, clears timers,
+aborts signed URL requests, and closes both audio contexts.
+
+Use `createConversation` when you own the lifecycle:
+
+```ts
+import { createConversation } from 'svelte-elevenlabs';
+
+const conversation = createConversation({ agentId: 'agent_your_public_id' });
+
+try {
+	await conversation.startConversation();
+} finally {
+	conversation.stopConversation();
+	conversation.destroy();
+}
+```
+
+Do not reuse a destroyed controller. Create a new one.
+
+## Controller surface
+
+Read these fields directly in Svelte markup. They are reactive state or derived
+values.
+
+| Field               | Meaning                                                                                      |
+| ------------------- | -------------------------------------------------------------------------------------------- |
+| `status`            | `'disconnected'`, `'connecting'`, or `'connected'`                                           |
+| `mode`              | High level mode: `'disconnected'`, `'connecting'`, `'ready'`, `'listening'`, or `'speaking'` |
+| `isSpeaking`        | Agent playback is scheduled or audible                                                       |
+| `isListening`       | The microphone is live and the agent can hear it                                             |
+| `isUserSpeaking`    | Local voice activity detection sees speech                                                   |
+| `isMuted`           | Outgoing microphone audio is muted                                                           |
+| `isTextOnly`        | The current or next session is text only                                                     |
+| `volume`            | Combined input and output level from 0 to 1                                                  |
+| `inputVolume`       | Microphone level from 0 to 1                                                                 |
+| `outputVolume`      | Agent playback level from 0 to 1                                                             |
+| `transcripts`       | Stable streaming transcript entries                                                          |
+| `messageCount`      | Number of retained transcript entries                                                        |
+| `error`             | Human readable message, safe to render                                                       |
+| `errorCode`         | Stable machine readable failure category                                                     |
+| `latency`           | Time to first audio in milliseconds, or `null`                                               |
+| `latencyHistory`    | Recent first audio measurements                                                              |
+| `conversationId`    | ElevenLabs conversation id, or `null`                                                        |
+| `inputAudioFormat`  | Negotiated microphone format, or `null`                                                      |
+| `outputAudioFormat` | Negotiated agent format, or `null`                                                           |
+| `queueStatus`       | Server queue state, or `null`                                                                |
+| `interruptions`     | Number of accepted barge-in events                                                           |
+| `canSendFeedback`   | A response id is available for feedback                                                      |
+| `vadScore`          | Server-side voice activity score                                                             |
+| `contextUsage`      | LLM context usage when the server reports it                                                 |
+| `outputGain`        | Playback gain from 0 to 1                                                                    |
+| `inputDeviceId`     | Selected microphone id, or `null`                                                            |
+| `outputDeviceId`    | Selected output device id, or `null`                                                         |
+
+Common methods:
+
+| Method                                               | Purpose                                                               |
+| ---------------------------------------------------- | --------------------------------------------------------------------- |
+| `startConversation(target?, { signed?, textOnly? })` | Open a session                                                        |
+| `stopConversation()`                                 | End a session and keep transcripts                                    |
+| `endSession()`                                       | Alias for `stopConversation()`                                        |
+| `destroy()`                                          | Release everything and mark the controller unusable                   |
+| `toggleMute()`                                       | Toggle outgoing microphone audio                                      |
+| `setMuted(muted)`                                    | Set mute explicitly                                                   |
+| `setVolume(value)`                                   | Set playback gain from 0 to 1                                         |
+| `sendUserMessage(text)`                              | Add a typed user turn on the same socket                              |
+| `sendContextualUpdate(text, contextId?)`             | Give the agent context without interrupting speech                    |
+| `sendFeedback(like, eventId?)`                       | Submit response feedback                                              |
+| `sendUserActivity()`                                 | Tell the agent the user is still active, throttled to once per second |
+| `changeInputDevice(id?)`                             | Switch the microphone during a voice session                          |
+| `changeOutputDevice(id?)`                            | Route playback to another output device                               |
+| `listAudioDevices()`                                 | Read available input and output devices                               |
+| `registerClientTool(name, handler)`                  | Register a named tool and receive an unregister function              |
+| `sendMCPToolApprovalResult(toolCallId, approved)`    | Answer an MCP approval request manually                               |
+| `clearTranscripts()`                                 | Remove transcript entries                                             |
+| `clearError()`                                       | Clear the current error message and code                              |
+
+## Options that matter
+
+| Option                     | Default             | Notes                                                            |
+| -------------------------- | ------------------- | ---------------------------------------------------------------- |
+| `agentId`                  | None                | Default public agent id                                          |
+| `signedUrl`                | None                | Default signed WebSocket URL                                     |
+| `signedUrlEndpoint`        | `'/api/signed-url'` | Same origin exchange route                                       |
+| `serverLocation`           | US origin           | `'eu-residency'`, `'in-residency'`, or `'global'` for public ids |
+| `textOnly`                 | `false`             | Skip microphone and audio contexts                               |
+| `micMuted`                 | `false`             | Start with microphone muted                                      |
+| `outputVolume`             | `1`                 | Initial playback gain                                            |
+| `inputChunkDurationMs`     | `100`               | Clamped to 50 to 250                                             |
+| `interruptOnUserSpeech`    | `true`              | Flush agent audio when local VAD detects speech                  |
+| `vadThreshold`             | `0.075`             | Normalised RMS threshold                                         |
+| `maxTranscripts`           | `250`               | Minimum retained value is 20                                     |
+| `autoCleanup`              | `true`              | Only used by `useConversation`                                   |
+| `debug`                    | `false`             | Protocol logs through `console.debug`                            |
+| `clientTools`              | None                | Named client tool handlers                                       |
+| `onClientToolCall`         | None                | Fallback handler                                                 |
+| `onError`                  | None                | Called with a `ConversationError`                                |
+| `onTranscript`             | None                | Called on every transcript change                                |
+| `onInterruption`           | None                | Called on server or local barge-in                               |
+| `onStatusChange`           | None                | Called when the connection status changes                        |
+| `onMCPToolApprovalRequest` | None                | Decide whether an MCP tool may proceed                           |
+
+## Errors
+
+`ConversationError` exposes a stable `code` and a human readable `message`. The
+controller also publishes the same values as `errorCode` and `error` and calls
+`onError`.
+
+Common codes:
+
+- `not-supported`: the browser or requested transport is not available.
+- `insecure-context`: the page is not HTTPS or localhost.
+- `permission-denied`: microphone permission was refused.
+- `audio-failed`: an audio context, worklet, or playback operation failed.
+- `invalid-target`: the agent id or URL is malformed.
+- `signed-url-failed`: the server exchange failed.
+- `connection-failed`: the socket could not open.
+- `connection-timeout`: the handshake did not finish in time.
+- `server-closed`: the server closed the socket.
+- `protocol-error`: the server sent an event the client could not parse.
+- `device-not-found`: the selected device disappeared.
+- `device-busy`: the device could not be opened.
+- `device-constraints`: the device rejected the requested constraints.
+- `device-switch-failed`: a live device switch did not complete.
+
+Render `error` for people. Use `errorCode` for branching and analytics. Never
+show a raw signed URL or API key in an error surface.
+
+## Review checklist
+
+Before finishing a change, verify:
+
+- The API key appears only in server code.
+- `useConversation` is called during component initialisation.
+- The start action runs from a user gesture.
+- A voice session has a visible stop action.
+- `error` and `status` are rendered with accessible text.
+- Buttons have `type="button"` unless they submit a form.
+- Status text uses a polite live region.
+- Text only mode works without a microphone.
+- A custom controller created with `createConversation` is destroyed.
+- No `PUBLIC_*` variable contains a secret.
+- The Tailwind source path is present when the widget is used in a Tailwind 4 app.
+- The build passes `bun run check` and `bun run test` when this is the package repository.
+
+## Documentation map
+
+- Install: https://gabryca.github.io/svelte-elevenlabs/docs/install
+- Quickstart: https://gabryca.github.io/svelte-elevenlabs/docs/quickstart
+- Sessions: https://gabryca.github.io/svelte-elevenlabs/docs/sessions
+- Audio: https://gabryca.github.io/svelte-elevenlabs/docs/audio
+- Client tools: https://gabryca.github.io/svelte-elevenlabs/docs/client-tools
+- Components: https://gabryca.github.io/svelte-elevenlabs/docs/components
+- Signed URLs: https://gabryca.github.io/svelte-elevenlabs/docs/signed-urls
+- Agent kit: https://gabryca.github.io/svelte-elevenlabs/docs/agents
+- API reference: https://gabryca.github.io/svelte-elevenlabs/docs/reference
+- Troubleshooting: https://gabryca.github.io/svelte-elevenlabs/docs/troubleshooting
+- Live demo: https://gabryca.github.io/svelte-elevenlabs/demo
+- Full machine reference: https://gabryca.github.io/svelte-elevenlabs/llms-full.txt

package/bin/svelte-elevenlabs.js

@@ -0,0 +1,528 @@
+#!/usr/bin/env node
+/**
+ * Install the svelte-elevenlabs agent guide into a consumer project.
+ *
+ * The command is intentionally dependency free so it runs with Node 22.17 or
+ * newer and Bun 1.4 or newer. It writes only local Markdown files, never calls
+ * the network, and never asks for an API key.
+ */
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(HERE, '..');
+const KIT_ROOT = join(ROOT, 'agent-kit');
+const GUIDE_PATH = join(KIT_ROOT, 'instructions.md');
+const PACKAGE_PATH = join(ROOT, 'package.json');
+
+const START_MARKER = '<!-- svelte-elevenlabs:agent-kit:start -->';
+const END_MARKER = '<!-- svelte-elevenlabs:agent-kit:end -->';
+
+const CLAUDE_DESCRIPTION =
+	'Build or review Svelte 5 ElevenLabs Conversational AI voice and text sessions with the svelte-elevenlabs package. Use for ConversationWidget, AudioVisualizer, signed URL routes, client tools, and audio cleanup.';
+
+/**
+ * @typedef {'claude' | 'cursor' | 'opencode' | 'copilot' | 'windsurf' | 'cline' | 'gemini' | 'agents'} TargetName
+ */
+
+/**
+ * @typedef {object} AgentTarget
+ * @property {TargetName} name Stable name used on the command line.
+ * @property {string} label Human readable tool name.
+ * @property {string} path File path relative to the consumer project.
+ * @property {boolean} shared Whether the file is shared with the project and must keep its content.
+ * @property {string} [frontmatter] YAML frontmatter required by the tool.
+ */
+
+/** @type {AgentTarget[]} */
+const TARGETS = [
+	{
+		name: 'claude',
+		label: 'Claude Code',
+		path: '.claude/skills/svelte-elevenlabs/SKILL.md',
+		shared: false,
+		frontmatter: `---\nname: svelte-elevenlabs\ndescription: ${CLAUDE_DESCRIPTION}\nlicense: MIT\n---\n\n`
+	},
+	{
+		name: 'cursor',
+		label: 'Cursor',
+		path: '.cursor/rules/svelte-elevenlabs.mdc',
+		shared: false,
+		frontmatter: `---\ndescription: ${CLAUDE_DESCRIPTION}\nglobs: src/**/*.svelte, src/**/*.ts, src/**/*.js\nalwaysApply: false\n---\n\n`
+	},
+	{
+		name: 'opencode',
+		label: 'OpenCode',
+		path: '.opencode/skills/svelte-elevenlabs/SKILL.md',
+		shared: false,
+		frontmatter: `---\nname: svelte-elevenlabs\ndescription: ${CLAUDE_DESCRIPTION}\nlicense: MIT\n---\n\n`
+	},
+	{
+		name: 'copilot',
+		label: 'GitHub Copilot',
+		path: '.github/copilot-instructions.md',
+		shared: true
+	},
+	{
+		name: 'windsurf',
+		label: 'Windsurf',
+		path: '.windsurf/rules/svelte-elevenlabs.md',
+		shared: false,
+		frontmatter: `---\ntrigger: model_decision\ndescription: ${CLAUDE_DESCRIPTION}\nglobs: src/**/*.svelte, src/**/*.ts\n---\n\n`
+	},
+	{
+		name: 'cline',
+		label: 'Cline',
+		path: '.clinerules/svelte-elevenlabs.md',
+		shared: false
+	},
+	{
+		name: 'gemini',
+		label: 'Gemini CLI',
+		path: 'GEMINI.md',
+		shared: true
+	},
+	{
+		name: 'agents',
+		label: 'AGENTS.md aware tools',
+		path: 'AGENTS.md',
+		shared: true
+	}
+];
+
+/** Aliases accepted on the command line. */
+const ALIASES = new Map([
+	['claude-code', 'claude'],
+	['github-copilot', 'copilot'],
+	['codex', 'agents'],
+	['generic', 'agents']
+]);
+
+/** Error type used for expected command line failures. */
+class AgentKitError extends Error {}
+
+/**
+ * Read the package version without assuming a JSON import attribute.
+ *
+ * @returns {string} Version from `package.json`.
+ */
+function readVersion() {
+	try {
+		const pkg = JSON.parse(readFileSync(PACKAGE_PATH, 'utf8'));
+		return typeof pkg.version === 'string' ? pkg.version : '0.0.0';
+	} catch {
+		return '0.0.0';
+	}
+}
+
+/**
+ * Read the canonical agent guide.
+ *
+ * @returns {string} Guide body without a trailing newline.
+ */
+function readGuide() {
+	if (!existsSync(GUIDE_PATH)) {
+		throw new AgentKitError(
+			`The agent guide is missing at ${GUIDE_PATH}. Reinstall svelte-elevenlabs and try again.`
+		);
+	}
+
+	return readFileSync(GUIDE_PATH, 'utf8').trimEnd();
+}
+
+/**
+ * Find one target by name or alias.
+ *
+ * @param {string} name Raw target name.
+ * @returns {AgentTarget} Matching target.
+ */
+function findTarget(name) {
+	const normalized = ALIASES.get(name) ?? name;
+	const target = TARGETS.find((entry) => entry.name === normalized);
+	if (!target) {
+		throw new AgentKitError(
+			`Unknown agent target "${name}". Use one of: ${TARGETS.map((entry) => entry.name).join(', ')}.`
+		);
+	}
+	return target;
+}
+
+/**
+ * Build the managed block for one target.
+ *
+ * @param {AgentTarget} target Target being rendered.
+ * @param {string} guide Canonical guide body.
+ * @param {string} version Package version.
+ * @returns {string} Markdown block with start and end markers.
+ */
+function renderBlock(target, guide, version) {
+	return `${START_MARKER}\n<!-- Generated by svelte-elevenlabs v${version}. Re-run the agents install command to update this block. -->\n\n${guide}\n${END_MARKER}`;
+}
+
+/**
+ * Render the complete content for a target.
+ *
+ * @param {AgentTarget} target Target being rendered.
+ * @param {string} guide Canonical guide body.
+ * @param {string} version Package version.
+ * @returns {string} Complete file content with a trailing newline.
+ */
+function renderTarget(target, guide, version) {
+	const block = renderBlock(target, guide, version);
+	const content = target.frontmatter ? `${target.frontmatter}${block}` : block;
+	return `${content}\n`;
+}
+
+/**
+ * Replace an existing managed block without touching the rest of a file.
+ *
+ * @param {string} existing Current file content.
+ * @param {string} block New managed block.
+ * @returns {string} Updated content.
+ */
+function replaceBlock(existing, block) {
+	const start = existing.indexOf(START_MARKER);
+	const end = existing.indexOf(END_MARKER, start);
+
+	if (!existing.trim()) return `${block}\n`;
+
+	if (start === -1) return `${existing.replace(/\s+$/, '')}\n\n${block}\n`;
+
+	if (end === -1) {
+		throw new AgentKitError(
+			'Found a start marker without an end marker. Remove the incomplete block and try again.'
+		);
+	}
+
+	return `${existing.slice(0, start)}${block}${existing.slice(end + END_MARKER.length)}`;
+}
+
+/**
+ * Write one target and report what happened.
+ *
+ * @param {AgentTarget} target Target to write.
+ * @param {object} options Install options.
+ * @param {string} options.cwd Consumer project root.
+ * @param {string} options.guide Canonical guide body.
+ * @param {string} options.version Package version.
+ * @param {boolean} options.force Overwrite dedicated files without markers.
+ * @param {boolean} options.dryRun Report without writing.
+ * @returns {{ target: AgentTarget, path: string, status: string, detail?: string }} Result for the summary.
+ */
+function installTarget(target, { cwd, guide, version, force, dryRun }) {
+	const absolutePath = join(cwd, target.path);
+	const exists = existsSync(absolutePath);
+	const current = exists ? readFileSync(absolutePath, 'utf8') : '';
+	const rendered = renderTarget(target, guide, version);
+	const block = renderBlock(target, guide, version);
+	let next = rendered;
+	let status = exists ? 'updated' : 'created';
+	let detail = '';
+
+	if (target.shared) {
+		next = replaceBlock(current, block);
+		if (exists) status = current.includes(START_MARKER) ? 'updated' : 'appended';
+	} else if (exists && current.includes(START_MARKER)) {
+		next = replaceBlock(current, block);
+	} else if (exists && !current.includes(START_MARKER)) {
+		if (!force) {
+			return {
+				target,
+				path: target.path,
+				status: 'skipped',
+				detail: 'the file exists without a managed block. Re-run with --force to replace it.'
+			};
+		}
+		status = 'replaced';
+	}
+
+	if (dryRun) {
+		const labels = {
+			created: 'would create',
+			updated: 'would update',
+			appended: 'would append',
+			replaced: 'would replace',
+			unchanged: 'unchanged',
+			skipped: 'would skip'
+		};
+		return {
+			target,
+			path: target.path,
+			status: labels[status] ?? status,
+			detail
+		};
+	}
+
+	if (next !== current) {
+		mkdirSync(dirname(absolutePath), { recursive: true });
+		writeFileSync(absolutePath, next, 'utf8');
+	} else {
+		status = 'unchanged';
+	}
+
+	return { target, path: target.path, status, detail };
+}
+
+/**
+ * Detect agent configuration files in a project.
+ *
+ * @param {string} cwd Consumer project root.
+ * @returns {TargetName[]} Detected targets in display order.
+ */
+function detectTargets(cwd) {
+	const detected = [];
+
+	if (existsSync(join(cwd, '.claude'))) detected.push('claude');
+	if (existsSync(join(cwd, '.cursor')) || existsSync(join(cwd, '.cursorrules'))) {
+		detected.push('cursor');
+	}
+	if (
+		existsSync(join(cwd, '.opencode')) ||
+		existsSync(join(cwd, 'opencode.json')) ||
+		existsSync(join(cwd, 'opencode.jsonc'))
+	) {
+		detected.push('opencode');
+	}
+	if (existsSync(join(cwd, '.github', 'copilot-instructions.md'))) detected.push('copilot');
+	if (existsSync(join(cwd, '.windsurf'))) detected.push('windsurf');
+	if (existsSync(join(cwd, '.clinerules'))) detected.push('cline');
+	if (existsSync(join(cwd, 'GEMINI.md'))) detected.push('gemini');
+	if (existsSync(join(cwd, 'AGENTS.md'))) detected.push('agents');
+
+	return detected;
+}
+
+/**
+ * Parse command line arguments.
+ *
+ * @param {string[]} argv Arguments after the executable name.
+ * @returns {{ command: string, subcommand: string, targets: string[], all: boolean, force: boolean, dryRun: boolean, cwd: string, help: boolean }} Parsed options.
+ */
+function parseArgs(argv) {
+	const options = {
+		command: argv[0] ?? 'help',
+		subcommand: argv[1] ?? '',
+		targets: [],
+		all: false,
+		force: false,
+		dryRun: false,
+		cwd: process.cwd(),
+		help: false
+	};
+
+	const start = options.command === 'agents' ? 2 : 1;
+
+	for (let index = start; index < argv.length; index += 1) {
+		const argument = argv[index];
+
+		if (argument === '--all') {
+			options.all = true;
+			continue;
+		}
+		if (argument === '--force') {
+			options.force = true;
+			continue;
+		}
+		if (argument === '--dry-run') {
+			options.dryRun = true;
+			continue;
+		}
+		if (argument === '--help' || argument === '-h') {
+			options.help = true;
+			continue;
+		}
+		if (argument === '--cwd') {
+			const value = argv[index + 1];
+			if (!value) throw new AgentKitError('--cwd needs a directory path.');
+			options.cwd = resolve(value);
+			index += 1;
+			continue;
+		}
+		if (argument.startsWith('--cwd=')) {
+			options.cwd = resolve(argument.slice('--cwd='.length));
+			continue;
+		}
+		if (argument === '--tool' || argument === '--target') {
+			const value = argv[index + 1];
+			if (!value) throw new AgentKitError('--tool needs a target name.');
+			options.targets.push(...value.split(','));
+			index += 1;
+			continue;
+		}
+		if (argument.startsWith('--tool=') || argument.startsWith('--target=')) {
+			options.targets.push(...argument.slice(argument.indexOf('=') + 1).split(','));
+			continue;
+		}
+		if (argument.startsWith('-')) {
+			throw new AgentKitError(`Unknown option "${argument}". Run svelte-elevenlabs agents --help.`);
+		}
+
+		options.targets.push(...argument.split(','));
+	}
+
+	options.targets = [...new Set(options.targets.map((entry) => entry.trim()).filter(Boolean))];
+	return options;
+}
+
+/**
+ * Print command help.
+ */
+function printHelp() {
+	console.log(`svelte-elevenlabs agent kit
+
+Usage:
+  svelte-elevenlabs agents list
+  svelte-elevenlabs agents install [targets] [--all] [--force] [--dry-run]
+  svelte-elevenlabs agents print [target]
+
+Targets:
+  ${TARGETS.map((target) => target.name).join(', ')}
+
+Examples:
+  svelte-elevenlabs agents install
+  svelte-elevenlabs agents install claude cursor opencode
+  svelte-elevenlabs agents install --all
+  svelte-elevenlabs agents install claude --dry-run
+  svelte-elevenlabs agents print cursor
+
+With no target names, the command detects configured agents and falls back to
+AGENTS.md. Shared files keep their existing content. Re-running the command
+updates only the managed block between the svelte-elevenlabs markers.`);
+}
+
+/**
+ * Print every target and its destination.
+ */
+function listTargets() {
+	console.log('Available agent targets:\n');
+	for (const target of TARGETS) {
+		console.log(`  ${target.name.padEnd(9)} ${target.label.padEnd(28)} ${target.path}`);
+	}
+	console.log('\nUse "svelte-elevenlabs agents install --all" to install every target.');
+}
+
+/**
+ * Run the agents command.
+ *
+ * @param {object} options Parsed options.
+ */
+function runAgents(options) {
+	if (
+		!options.subcommand ||
+		options.subcommand === 'help' ||
+		options.subcommand === '--help' ||
+		options.subcommand === '-h' ||
+		options.help
+	) {
+		printHelp();
+		return;
+	}
+
+	const version = readVersion();
+
+	if (options.subcommand === 'list') {
+		listTargets();
+		return;
+	}
+
+	const guide = readGuide();
+
+	if (options.subcommand === 'print') {
+		const requested = options.targets[0];
+		if (!requested) {
+			process.stdout.write(`${guide}\n`);
+			return;
+		}
+		const target = findTarget(requested);
+		process.stdout.write(renderTarget(target, guide, version));
+		return;
+	}
+
+	if (options.subcommand !== 'install') {
+		throw new AgentKitError(
+			`Unknown agents command "${options.subcommand}". Use list, install, or print.`
+		);
+	}
+
+	if (!options.cwd || !existsSync(options.cwd) || !statSync(options.cwd).isDirectory()) {
+		throw new AgentKitError(`The project directory does not exist: ${options.cwd}`);
+	}
+
+	const detected = detectTargets(options.cwd);
+	const requested = options.all
+		? TARGETS.map((target) => target.name)
+		: options.targets.length > 0
+			? options.targets.map((name) => findTarget(name).name)
+			: detected;
+
+	const selected = requested.length > 0 ? requested : ['agents'];
+	const unique = [...new Set(selected)];
+	const results = unique.map((name) =>
+		installTarget(findTarget(name), {
+			cwd: options.cwd,
+			guide,
+			version,
+			force: options.force,
+			dryRun: options.dryRun
+		})
+	);
+
+	console.log(
+		`${options.dryRun ? 'Agent kit dry run' : 'Agent kit installed'} for ${results.length} ${
+			results.length === 1 ? 'target' : 'targets'
+		}:\n`
+	);
+
+	for (const result of results) {
+		const displayPath = relative(options.cwd, join(options.cwd, result.path)).replaceAll('\\', '/');
+		const suffix = result.detail ? ` (${result.detail})` : '';
+		console.log(`  ${result.status.padEnd(13)} ${displayPath}${suffix}`);
+	}
+
+	if (requested.length === 0) {
+		console.log(
+			'\nNo agent configuration was detected, so the guide was added to AGENTS.md. Use --all or name a tool to install more targets.'
+		);
+	}
+
+	if (!options.dryRun) {
+		console.log('\nRestart your agent session, then ask it to use svelte-elevenlabs.');
+	}
+}
+
+/**
+ * Entry point with human readable failure handling.
+ */
+function main() {
+	const options = parseArgs(process.argv.slice(2));
+
+	if (options.command === 'help' || options.command === '--help' || options.command === '-h') {
+		printHelp();
+		return;
+	}
+
+	if (options.command !== 'agents') {
+		throw new AgentKitError(
+			`Unknown command "${options.command}". Use "svelte-elevenlabs agents --help".`
+		);
+	}
+
+	runAgents(options);
+}
+
+process.stdout.on('error', (error) => {
+	if (error.code === 'EPIPE') process.exit(0);
+	throw error;
+});
+
+try {
+	main();
+} catch (error) {
+	if (error instanceof AgentKitError) {
+		console.error(`[svelte-elevenlabs] ${error.message}`);
+	} else {
+		console.error('[svelte-elevenlabs] The agent kit command failed.', error);
+	}
+	process.exitCode = 1;
+}

package/dist/audio/audioManager.js

@@ -27,6 +27,14 @@ const DEFAULT_SAMPLE_RATE = 16_000;
 const DEFAULT_CHUNK_MS = 100;
 const VAD_ATTACK_FRAMES = 2;
 const VAD_RELEASE_FRAMES = 8;
+/** Keep dropping agent chunks for a moment after a barge-in or user speech. */
+const PLAYBACK_SUPPRESSION_MS = 300;
+/**
+ * Wait this long after the last scheduled chunk before reporting idle.
+ * TTS streams sentence by sentence, and the gap between sentences can be
+ * close to a second, so a short gap does not mean the response is finished.
+ */
+const PLAYBACK_IDLE_GRACE_MS = 1_000;
 /** Stop every track on a media stream, even after the manager was closed. */
 function stopStream(stream) {
     if (!stream)
@@ -661,10 +669,12 @@ export class AudioManager {
         if (!ctx || !master)
             return false;
         const parsed = typeof format === 'string' ? parseAudioFormat(format) : format;
-        // Drop late chunks while the user is actively barging in.
+        // Drop late chunks while the user is barging in, and for a short
+        // grace period after the interruption. Checking only the timestamp
+        // let agent audio resume after 300 ms even while the user was still
+        // speaking.
         if (this.#options.interruptOnUserSpeech !== false &&
-            this.#userSpeaking &&
-            performance.now() < this.#suppressPlaybackUntil) {
+            (this.#userSpeaking || performance.now() < this.#suppressPlaybackUntil)) {
             return false;
         }
         try {
@@ -688,10 +698,11 @@ export class AudioManager {
             if (this.#nextStartTime < now) {
                 this.#nextStartTime = now + 0.02;
             }
-            // Recover from a long stall instead of scheduling seconds into the future.
-            if (this.#nextStartTime - now > 1.5) {
-                this.#nextStartTime = now + 0.02;
-            }
+            // Fast TTS streams can deliver many seconds of audio in a few
+            // seconds. Keep every chunk in order; resetting the cursor here
+            // collapsed the backlog into overlapping audio and made responses
+            // sound truncated. A real stall is handled by the branch above
+            // when the context clock catches up with the scheduled cursor.
             const startAt = this.#nextStartTime;
             source.start(startAt);
             this.#nextStartTime = startAt + buffer.duration;
@@ -747,7 +758,7 @@ export class AudioManager {
         }
         this.#playback.clear();
         this.#nextStartTime = 0;
-        this.#suppressPlaybackUntil = performance.now() + 300;
+        this.#suppressPlaybackUntil = performance.now() + PLAYBACK_SUPPRESSION_MS;
         this.#setOutputActive(false);
     }
     /**
@@ -1100,7 +1111,8 @@ export class AudioManager {
             this.#speechFrames += 1;
             if (!this.#userSpeaking && this.#speechFrames >= VAD_ATTACK_FRAMES) {
                 this.#setUserSpeaking(true);
-                if (this.#options.interruptOnUserSpeech !== false && this.#outputActive) {
+                if (this.#options.interruptOnUserSpeech !== false &&
+                    (this.#outputActive || this.#playback.size > 0)) {
                     this.flushPlayback();
                     this.#options.onLocalInterruption?.();
                 }
@@ -1123,6 +1135,9 @@ export class AudioManager {
         if (!speaking) {
             this.#speechFrames = 0;
             this.#silenceFrames = 0;
+            // Drop stale chunks from the interrupted response that may still
+            // be in flight after the user stops speaking.
+            this.#suppressPlaybackUntil = performance.now() + PLAYBACK_SUPPRESSION_MS;
         }
         this.#options.onUserSpeakingChange?.(speaking);
     }
@@ -1141,7 +1156,7 @@ export class AudioManager {
         if (this.#idleTimer)
             clearTimeout(this.#idleTimer);
         const generation = this.#playbackGeneration;
-        const delay = Math.max(0, (this.#nextStartTime - ctx.currentTime) * 1000) + 140;
+        const delay = Math.max(0, (this.#nextStartTime - ctx.currentTime) * 1000) + PLAYBACK_IDLE_GRACE_MS;
         this.#idleTimer = setTimeout(() => {
             if (this.#closed || generation !== this.#playbackGeneration)
                 return;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "svelte-elevenlabs",
-	"version": "0.5.1",
+	"version": "0.6.0",
 	"description": "A community-driven Svelte 5 library and starter kit for ElevenLabs Conversational AI and low-latency audio streaming.",
 	"license": "MIT",
 	"author": "AnonymousGCA (https://github.com/GABRYCA)",
@@ -20,6 +20,9 @@
 	},
 	"type": "module",
 	"packageManager": "bun@1.4.3",
+	"bin": {
+		"svelte-elevenlabs": "./bin/svelte-elevenlabs.js"
+	},
 	"engines": {
 		"node": ">=22.17.0",
 		"bun": ">=1.4.0"
@@ -60,6 +63,8 @@
 	},
 	"files": [
 		"dist",
+		"agent-kit",
+		"bin",
 		"!dist/**/*.test.*",
 		"!dist/**/*.spec.*"
 	],