# sv11-ui

> Full documentation corpus. Generated from https://sv11.ui.twango.dev/docs.

# Introduction

> A component registry for building AI agent interfaces with Svelte 5.

sv11-ui is a component registry for building AI agent interfaces — a Svelte 5 port of [elevenlabs/ui](https://github.com/elevenlabs/ui), built on top of [shadcn-svelte](https://shadcn-svelte.com/). It provides pre-built components for voice, chat, transcription, audio, and visualization.

Components are distributed via the `shadcn-svelte` CLI:

```bash
npx shadcn-svelte@latest add https://sv11.ui.twango.dev/r/<component>.json
```

For example, to install the [Orb](/docs/components/orb) component, you can run:

```bash
npx shadcn-svelte@latest add https://sv11.ui.twango.dev/r/orb.json
```

```svelte
<script lang="ts">
	import { Button } from "$lib/registry/ui/button/index.js";
	import { Orb, type OrbAgentState } from "$lib/registry/ui/orb/index.js";
	import { cn } from "$lib/utils.js";

	let { small = false }: { small?: boolean } = $props();

	const ALL_ORBS: Array<[string, string]> = [
		["#CADCFC", "#A0B9D1"],
		["#F6E7D8", "#E0CFC2"],
		["#E5E7EB", "#9CA3AF"],
	];

	const orbs = $derived(small ? [ALL_ORBS[0]] : ALL_ORBS);

	let agent = $state<OrbAgentState>(null);
</script>

<div class="bg-card w-full rounded-lg border p-6">
	<div class="mb-4">
		<h3 class="text-lg font-semibold">Agent Orbs</h3>
		<p class="text-muted-foreground text-sm">Interactive orb visualization with agent states</p>
	</div>

	<div class="space-y-4">
		<div class="flex justify-center gap-8">
			{#each orbs as colors, index (index)}
				<div class={cn("relative", small || index === 1 ? "block" : "hidden md:block")}>
					<div
						class="bg-muted relative h-32 w-32 rounded-full p-1 shadow-[inset_0_2px_8px_rgba(0,0,0,0.1)] dark:shadow-[inset_0_2px_8px_rgba(0,0,0,0.5)]"
					>
						<div
							class="bg-background h-full w-full overflow-hidden rounded-full shadow-[inset_0_0_12px_rgba(0,0,0,0.05)] dark:shadow-[inset_0_0_12px_rgba(0,0,0,0.3)]"
						>
							<Orb {colors} seed={(index + 1) * 1000} agentState={agent} />
						</div>
					</div>
				</div>
			{/each}
		</div>

		<div class="flex flex-wrap justify-center gap-2">
			<Button size="sm" variant="outline" onclick={() => (agent = null)} disabled={agent === null}>
				Idle
			</Button>
			<Button
				size="sm"
				variant="outline"
				onclick={() => (agent = "listening")}
				disabled={agent === "listening"}
			>
				Listening
			</Button>
			<Button
				size="sm"
				variant="outline"
				onclick={() => (agent = "talking")}
				disabled={agent === "talking"}
			>
				Talking
			</Button>
		</div>
	</div>
</div>
```

## Features

- **Provider-agnostic** — Wire up your own backend (ElevenLabs, OpenAI, Deepgram, custom, etc.) via `ConversationAdapter`, `TranscriptionAdapter`, and `Voice` interfaces.
- **Svelte 5** — Built with runes, snippets, and modern Svelte patterns.
- **Tailwind CSS 4** — Styled with tailwind-variants and tailwind-merge.
- **Accessible** — Built on bits-ui primitives.

Browse the full list of components at [/docs/components](/docs/components), or view the [source code](https://github.com/twangodev/sv11-ui) on GitHub.

---

# Setup

> Getting started with sv11-ui.

sv11-ui components are distributed through the `shadcn-svelte` CLI. Each component is published as a registry entry that the CLI fetches and writes into your project alongside any required dependencies.

```bash
npx shadcn-svelte@latest add https://sv11.ui.twango.dev/r/orb.json
```

## Prerequisites

Before installing sv11-ui, make sure your environment meets the following requirements:

- [Node.js](https://nodejs.org/) version 18 or later
- A [SvelteKit 2](https://svelte.dev/docs/kit) project
- [Svelte 5](https://svelte.dev/) with runes
- [Tailwind CSS 4](https://tailwindcss.com/) configured
- [shadcn-svelte](https://shadcn-svelte.com/) initialized in your project. If it isn't set up yet, running an install command will prompt you through initialization.

## Installing components

Install a single component by passing its registry URL to the `shadcn-svelte` CLI:

```bash
npx shadcn-svelte@latest add https://sv11.ui.twango.dev/r/<component-name>.json
```

For example, to add the message component:

```bash
npx shadcn-svelte@latest add https://sv11.ui.twango.dev/r/message.json
```

To install every sv11-ui component at once, use the `all` entry:

```bash
npx shadcn-svelte@latest add https://sv11.ui.twango.dev/r/all.json
```

The CLI downloads the component source, resolves any registry or npm dependencies, and writes the files into your project (typically under `src/lib/registry/ui/<name>/`). Once the command completes, import the component and use it in your code.

---

# Usage

> How to use sv11-ui components in your SvelteKit application.

Once a sv11-ui component is installed, you can import it and use it in your application like any other Svelte component. The components are copied into your codebase (not hidden in a library), so you can freely edit them to suit your specific needs.

---

## Example

After installing sv11-ui components, you can use them in your application like any other Svelte component. For example:

```svelte
<script lang="ts">
	import { Orb } from "$lib/registry/ui/orb";
	import { Card } from "$lib/registry/ui/card";
</script>

<Card class="flex items-center justify-center p-8">
	<Orb />
</Card>
```

---

# Providers

> Provider-agnostic adapter interfaces for wiring sv11 components to any backend.

sv11 components do not ship with backend bindings. Instead, they consume small TypeScript adapter interfaces — you pass an object that conforms to the interface, and the component calls into it. Components plus adapters equal a working system, and you are free to wrap ElevenLabs, OpenAI, Deepgram, the Web Speech API, or any custom service.

## ConversationAdapter

Used by [ConversationBar](/docs/components/conversation-bar) to drive real-time agent conversations. Handles the full duplex session lifecycle — connecting, streaming messages in both directions, and muting the microphone.

```ts
export interface ConversationAdapter {
	connect(config: ConversationConfig): Promise<void>;
	disconnect(): void;
	sendMessage(text: string): void;
	sendContextualUpdate(text: string): void;
	setMuted(muted: boolean): void;
}
```

The `config` passed to `connect()` is the callback bundle the adapter fires as the session progresses:

```ts
export interface ConversationConfig {
	onConnect: () => void;
	onDisconnect: () => void;
	onMessage: (message: ConversationMessage) => void;
	onError: (error: Error) => void;
	onStatusChange: (status: AgentConnectionState) => void;
	onModeChange?: (mode: ConversationMode) => void;
}
```

Messages use a simple source-tagged shape:

```ts
export interface ConversationMessage {
	source: "user" | "ai";
	message: string;
}
```

Status and mode are narrow string-literal unions:

```ts
export type AgentConnectionState = "disconnected" | "connecting" | "connected" | "disconnecting";

export type ConversationMode = "speaking" | "listening";
```

### Method responsibilities

- **`connect(config)`** — Open the underlying transport, begin capturing microphone audio, and wire every event from the backend to the matching callback in `config`. Resolve once the session is live; reject on auth, permission, or initialization errors.
- **`disconnect()`** — Tear down the session and release the microphone. Fire `onStatusChange` through `disconnecting` and end with `onDisconnect`.
- **`sendMessage(text)`** — Send a user-authored text turn that the agent should treat as spoken input and respond to.
- **`sendContextualUpdate(text)`** — Send out-of-band context the agent should be aware of but not respond to directly (e.g. page navigation, UI state).
- **`setMuted(muted)`** — Mute or unmute the local microphone without dropping the session.

## TranscriptionAdapter

Used by [SpeechInput](/docs/components/speech-input) to stream speech-to-text. The adapter owns the STT socket and emits partial and committed transcripts as they arrive.

```ts
export interface TranscriptionAdapter {
	/**
	 * Open connection and start capturing audio. Resolves when ready
	 * (i.e. when `onConnect` has fired or the connection is established).
	 * Rejects on authentication, permission, or initialization errors.
	 */
	start(callbacks: TranscriptionAdapterCallbacks): Promise<void>;
	/**
	 * Close the connection cleanly. Any in-flight partial transcript is
	 * preserved by the component and passed to the user's `onStop` callback.
	 */
	stop(): void;
	/**
	 * Close the connection AND discard any in-flight partial transcript.
	 * The component clears partial + committed state before firing `onCancel`.
	 */
	cancel(): void;
}
```

```ts
export interface TranscriptionAdapterCallbacks {
	onPartialTranscript?: (text: string) => void;
	onCommittedTranscript?: (text: string) => void;
	onConnect?: () => void;
	onDisconnect?: () => void;
	onError?: (error: Error) => void;
}
```

### Contract details

- **`start()` resolution timing** — The returned promise must only resolve once the connection is actually ready for audio (i.e. after `onConnect` has fired or the transport is confirmed open). Rejection is reserved for authentication, permission, or initialization failures so the component can surface them to the user.
- **`stop()` vs `cancel()`** — Both close the connection, but they differ in how the component treats any partial transcript still in flight. `stop()` preserves that partial and forwards it to the user's `onStop` callback, so it is the right choice when the user is committing what they said. `cancel()` causes the component to clear partial and committed state before firing `onCancel`, so it is the right choice when the user is throwing the utterance away.
- **Partial vs committed** — Call `onPartialTranscript` for interim hypotheses that may still change, and `onCommittedTranscript` once the provider finalizes a segment.

## Voice

Used by [VoicePicker](/docs/components/voice-picker) to render voice selection UIs. This is a plain data shape rather than a behavioral interface — you load voices from your provider and map them onto this type.

```ts
export type Voice = {
	id: string;
	name: string;
	previewUrl?: string;
	description?: string;
	labels?: VoiceLabels;
};

export type VoiceLabels = {
	accent?: string;
	gender?: string;
	age?: string;
	description?: string;
	descriptive?: string;
	"use case"?: string;
	use_case?: string;
	[key: string]: string | undefined;
};
```

Providing `previewUrl` is what enables the built-in audio preview in `VoicePicker` — omit it and the preview control is hidden. `labels` is an open-ended map with a few conventional keys; anything extra on it is still accepted for filtering and display.

## Writing your own adapter

An adapter is any object that matches the interface — there is no base class, no decorator, no registration step. Wrap any SDK (ElevenLabs, OpenAI Realtime, Deepgram, Whisper, the Web Speech API, a custom WebSocket) in a module that exposes the right methods and forwards events to the supplied callbacks. For ready-made recipes per provider, see [/docs/adapters](/docs/adapters).

```svelte
<script lang="ts">
	import { ConversationBar, type ConversationAdapter } from "$lib/registry/ui/conversation-bar";

	declare const adapter: ConversationAdapter;
</script>

<ConversationBar {adapter} />
```

---

# Theming

> Customize sv11-ui components using CSS variables and component-level color props.

sv11-ui components follow shadcn-svelte's CSS variable convention. Theming means overriding CSS custom properties such as `--background`, `--foreground`, `--primary`, and `--accent` on `:root` and `.dark`. Most components read these tokens directly, so customizing your palette in one place restyles every component at once.

A handful of visualization components (orb, matrix, waveform) also expose their own color props, since their visual language doesn't map cleanly onto the shadcn token set.

## CSS variables

Tokens are declared in your project's `src/app.css`. The shadcn-svelte CLI wires the standard token set into your project when you initialize it; sv11-ui components reuse those same names.

Colors are expressed in the [OKLCH](https://oklch.com/) color space. The light palette lives on `:root`, the dark palette on `.dark`:

```css title="src/app.css"
:root {
	--radius: 0.625rem;
	--background: oklch(1 0 0);
	--foreground: oklch(0.145 0 0);
	--primary: oklch(0.205 0 0);
	--primary-foreground: oklch(0.985 0 0);
	--accent: oklch(0.97 0 0);
	--accent-foreground: oklch(0.205 0 0);
	--muted: oklch(0.97 0 0);
	--muted-foreground: oklch(0.556 0 0);
	--border: oklch(0.922 0 0);
	--ring: oklch(0.708 0 0);
	/* ...card, popover, secondary, destructive, chart-*, sidebar-* */
}

.dark {
	--background: oklch(0.145 0 0);
	--foreground: oklch(0.985 0 0);
	--primary: oklch(0.922 0 0);
	--primary-foreground: oklch(0.205 0 0);
	/* ... */
}
```

In addition to the standard shadcn-svelte tokens, sv11-ui declares a few documentation-oriented variables (`--surface`, `--surface-foreground`, `--code`, `--code-foreground`, `--code-highlight`, `--code-number`) and a brand accent (`--svelte-orange`) used by the docs site. Components themselves do not depend on these.

## Customizing tokens

To recolor components, override the variables in your own `app.css`. For example, to change the primary color:

```css title="src/app.css"
:root {
	--primary: oklch(0.55 0.2 250);
	--primary-foreground: oklch(0.985 0 0);
}

.dark {
	--primary: oklch(0.7 0.18 250);
	--primary-foreground: oklch(0.145 0 0);
}
```

Every component that references `bg-primary` or `text-primary-foreground` updates automatically.

## Component-specific theming

The following components expose dedicated color props because their rendering (WebGL shaders, SVG pixels, canvas bars) doesn't fit the shadcn token model. All other sv11-ui components inherit their colors from the standard tokens above.

### Orb

The orb accepts a `colors` prop — a tuple of two color strings that are fed into the shader as `uColor1` and `uColor2`:

```svelte
<script lang="ts">
	import { Orb } from "$lib/registry/ui/orb";
</script>

<Orb colors={["#CADCFC", "#A0B9D1"]} />
```

The default palette is `["#CADCFC", "#A0B9D1"]`. Any CSS color string accepted by `THREE.Color` works (hex, `rgb(...)`, named colors).

### Matrix

The matrix LED display accepts a `palette` prop with `on` and `off` colors for lit and unlit pixels:

```svelte
<script lang="ts">
	import { Matrix } from "$lib/registry/ui/matrix";
</script>

<Matrix rows={7} cols={7} palette={{ on: "oklch(0.7 0.2 150)", off: "var(--muted-foreground)" }} />
```

The default is `{ on: "currentColor", off: "var(--muted-foreground)" }`, so if you don't pass a palette the lit pixels follow the element's `color`, making the matrix themeable via any Tailwind text utility (`class="text-primary"`, `class="text-destructive"`, etc.).

### Waveform and LiveWaveform

Both `Waveform` and `LiveWaveform` accept an optional `barColor` prop. When omitted, bars are drawn using the canvas's computed `--foreground` value:

```svelte
<script lang="ts">
	import { Waveform } from "$lib/registry/ui/waveform";
	import { LiveWaveform } from "$lib/registry/ui/live-waveform";
</script>

<Waveform data={samples} barColor="oklch(0.55 0.2 250)" />
<LiveWaveform active barColor="var(--primary)" />
```

Because the default resolves from CSS, you can also tint the waveform by setting `color` on a parent element or passing a Tailwind text utility.

## Dark mode

sv11-ui ships with both light and dark palettes out of the box. See [Dark mode](/docs/dark-mode) for how to wire up a theme toggle.

---

For a deeper reference on the underlying token system, see [shadcn-svelte's theming docs](https://shadcn-svelte.com/docs/theming).

---

# Colors

> The semantic color tokens sv11-ui components are built on.

sv11-ui components are styled entirely with semantic color tokens — the same
[shadcn-svelte](https://shadcn-svelte.com/docs/theming) theming layer — rather
than hard-coded colors. Each token is a CSS variable exposed as a Tailwind color
(e.g. `--primary` → `bg-primary`, `text-primary`), so components adapt
automatically to light/dark mode and any custom theme.

Click a swatch to copy its Tailwind class.

### Base

- `--background` → `bg-background`
- `--foreground` → `text-foreground`
- `--card` → `bg-card`
- `--card-foreground` → `text-card-foreground`
- `--popover` → `bg-popover`
- `--popover-foreground` → `text-popover-foreground`
- `--border` → `bg-border`
- `--input` → `bg-input`
- `--ring` → `bg-ring`

### Semantic

- `--primary` → `bg-primary`
- `--primary-foreground` → `text-primary-foreground`
- `--secondary` → `bg-secondary`
- `--secondary-foreground` → `text-secondary-foreground`
- `--muted` → `bg-muted`
- `--muted-foreground` → `text-muted-foreground`
- `--accent` → `bg-accent`
- `--accent-foreground` → `text-accent-foreground`
- `--destructive` → `bg-destructive`

### Charts

- `--chart-1` → `bg-chart-1`
- `--chart-2` → `bg-chart-2`
- `--chart-3` → `bg-chart-3`
- `--chart-4` → `bg-chart-4`
- `--chart-5` → `bg-chart-5`

### Sidebar

- `--sidebar` → `bg-sidebar`
- `--sidebar-foreground` → `text-sidebar-foreground`
- `--sidebar-primary` → `bg-sidebar-primary`
- `--sidebar-primary-foreground` → `text-sidebar-primary-foreground`
- `--sidebar-accent` → `bg-sidebar-accent`
- `--sidebar-accent-foreground` → `text-sidebar-accent-foreground`
- `--sidebar-border` → `bg-sidebar-border`
- `--sidebar-ring` → `bg-sidebar-ring`

## Using tokens

Reference tokens through Tailwind utilities:

```svelte
<div class="bg-card text-card-foreground border-border rounded-lg border">
	<button class="bg-primary text-primary-foreground">Action</button>
</div>
```

Or directly as CSS variables:

```css
.custom {
	background-color: var(--muted);
	color: var(--muted-foreground);
}
```

## Customizing

Override any token in your global stylesheet to retheme every component at once.
See [Theming](/docs/theming) for the full setup and [Dark Mode](/docs/dark-mode)
for light/dark switching.

```css
:root {
	--primary: oklch(0.55 0.22 264);
	--primary-foreground: oklch(0.98 0 0);
}
```

---

# Dark Mode

> Add light and dark themes to a sv11-ui project with mode-watcher.

sv11-ui relies on [`mode-watcher`](https://github.com/svecosystem/mode-watcher) to toggle a `.dark` class on the `<html>` element and persist the user's choice across sessions. Every component's dark styles are scoped to that class, so wiring mode-watcher into your root layout is all that's needed for themes to work.

## Install mode-watcher

```bash
npm install mode-watcher
```

## Add the watcher

Render `<ModeWatcher />` once near the top of your root layout so the class is applied and persisted before the rest of the tree renders:

```svelte
<script lang="ts">
	import "../app.css";
	import { ModeWatcher } from "mode-watcher";

	let { children } = $props();
</script>

<ModeWatcher />
{@render children()}
```

The sv11-ui docs site renders it with `defaultMode="system"` and `disableTransitions`, which honors the user's OS preference on first load and suppresses the color-flash animation when the class flips:

```svelte
<ModeWatcher defaultMode="system" disableTransitions />
```

See the [mode-watcher documentation](https://mode-watcher.svecosystem.com) for the full list of props.

## CSS setup

sv11-ui's Tailwind entrypoint declares a custom variant that activates whenever an element has an ancestor with the `.dark` class:

```css
@custom-variant dark (&:is(.dark *));
```

The `:root` block defines the light-mode tokens, and a `.dark { ... }` block overrides them when the class is present. For example:

```css
:root {
	--primary: oklch(0.205 0 0);
}

.dark {
	--primary: oklch(0.922 0 0);
}
```

Because every token is swapped in one place, you generally won't need to write your own `dark:` utilities — the existing components already pick up the right values automatically. If you are using a `data-theme` attribute or a different selector, sv11's dark styles will not activate.

## Building a toggle

`mode-watcher` exposes a `toggleMode` helper that flips between light and dark. Paired with a button from the registry, a minimal toggle looks like this:

```svelte
<script lang="ts">
	import { toggleMode } from "mode-watcher";
	import { Button } from "$lib/registry/ui/button";
</script>

<Button variant="ghost" size="icon" onclick={toggleMode}>
	<span class="sr-only">Toggle theme</span>
</Button>
```

This is the same pattern the sv11-ui docs site uses in its header mode switcher.

## Reading the current mode

When a component needs to branch on the active theme — for example to swap a shader uniform or an image source — import the reactive `mode` store and read `mode.current`:

```svelte
<script lang="ts">
	import { mode } from "mode-watcher";

	let isDark = $derived(mode.current === "dark");
</script>
```

`mode.current` is reactive, so anything derived from it updates automatically when the user toggles themes.

---

# Troubleshooting

> Common issues when installing and using sv11-ui components.

## Why are my components not styled?

sv11-ui assumes a Tailwind CSS 4 project with shadcn-svelte's base layer in place. Make sure the CSS entrypoint you import from your root layout (typically `src/app.css`) includes both Tailwind and the shadcn-svelte base styles:

```css
@import "tailwindcss";
@import "shadcn-svelte/tailwind.css";
```

Without the shadcn-svelte import, the CSS variables (`--background`, `--foreground`, `--primary`, etc.) that sv11 components rely on will be undefined and components will render unstyled.

---

## I ran the install command but nothing was added to my project

sv11-ui distributes components through the `shadcn-svelte` CLI. Double-check that:

- Your current working directory is the root of your project (where `package.json` lives).
- `components.json` exists and is configured. If it isn't, the CLI will prompt you to initialize it the first time you run an `add` command.
- You're pinning `shadcn-svelte@latest` so the CLI understands the current registry schema:

```bash
npx shadcn-svelte@latest add https://sv11.ui.twango.dev/r/orb.json
```

---

## Theme switching doesn't work — my app stays in light mode

sv11-ui uses a `.dark` class on the `<html>` element, managed by [`mode-watcher`](https://github.com/svecosystem/mode-watcher). Two things need to be in place:

- Your root layout must render `<ModeWatcher />` so the class is applied and persisted:

```svelte
<script lang="ts">
	import { ModeWatcher } from "mode-watcher";
</script>

<ModeWatcher defaultMode="system" disableTransitions />
```

- Your CSS must declare a dark variant bound to that class. sv11's `app.css` uses:

```css
@custom-variant dark (&:is(.dark *));
```

If you are using a `data-theme` attribute or a different selector, component dark-mode styles will not activate.

---

## Component imports fail with "module not found"

SvelteKit uses the `$lib` alias, not `@/`. Registry components land under `src/lib/registry/ui/<name>/` and should be imported via `$lib/registry/ui/<name>`:

```svelte
<script lang="ts">
	import { Orb } from "$lib/registry/ui/orb";
</script>
```

The `$lib` alias is provided by SvelteKit out of the box and points at `src/lib`. If you've overridden it or added custom aliases, check the `kit.alias` block in your `svelte.config.js` and make sure `$lib` still resolves to `src/lib`.

---

## Still stuck?

If all else fails, feel free to open an issue on [GitHub](https://github.com/twangodev/sv11-ui/issues).

---

# Changelog

> Release history for sv11-ui, auto-generated from conventional commits.

## Unreleased

### Bug Fixes

- **voice-chat:** Update sendMessage function signature ([#34](https://github.com/twangodev/sv11-ui/pull/34)) ([a259774](https://github.com/twangodev/sv11-ui/commit/a259774d86fa3452ae9c46e259973db9553aa3fd))
- **docs:** Add gap between page header and content ([#30](https://github.com/twangodev/sv11-ui/pull/30)) ([86669bb](https://github.com/twangodev/sv11-ui/commit/86669bbfa1190cef2f83c2043af6b9b035337496))
- **speaker-01:** Prevent mount effect from rewinding track switches ([#24](https://github.com/twangodev/sv11-ui/pull/24)) ([acbf05f](https://github.com/twangodev/sv11-ui/commit/acbf05ff6fcc8c56975d6410a0f0b883fae94c64))
- **changelog:** Linkify PR numbers in git-cliff output ([#23](https://github.com/twangodev/sv11-ui/pull/23)) ([78216e4](https://github.com/twangodev/sv11-ui/commit/78216e414336868d2e64499ee0d0318625cd409d))
- **orb:** Flip color ramp on dark-mode toggle ([#17](https://github.com/twangodev/sv11-ui/pull/17)) ([19d5b1e](https://github.com/twangodev/sv11-ui/commit/19d5b1e254ae381282bbaf78473e1a8efc082c7c))
- Adjust class attribute for GitHub link component to improve styling ([8b9d27e](https://github.com/twangodev/sv11-ui/commit/8b9d27eb0a0ad413b91cb930fa6127e1048e07da))
- Further finetune perlin-noise.png ([b7ec1d5](https://github.com/twangodev/sv11-ui/commit/b7ec1d59ef4308c733372dfc5ed7865789d061c5))
- Tune perlin-noise.png ([fe4745c](https://github.com/twangodev/sv11-ui/commit/fe4745c81d74ea0af8c038462dbe73e1056eda4d))
- Update shimmering-text status in README.md ([7a43f39](https://github.com/twangodev/sv11-ui/commit/7a43f39f3525b1f2fc1a5513b5141489f62ce341))
- Enhance message content styles for user and assistant variants ([949a0b2](https://github.com/twangodev/sv11-ui/commit/949a0b2fcf7a3936f8373251047700e556782c76))
- Update URLs to use the new subdomain for site configuration and documentation ([536ddb2](https://github.com/twangodev/sv11-ui/commit/536ddb21f77ac47dfed57a14d836f2f765eac363))
- Rename animation control variables for clarity and add fly transition to demo ([a5b5024](https://github.com/twangodev/sv11-ui/commit/a5b502483734ec7554a4da28c308a4761a6cc40b))
- **style:** Add missing newline for improved readability in site-footer.svelte ([575c8e7](https://github.com/twangodev/sv11-ui/commit/575c8e73761d0cc194e63db13a2e3de3950b1a63))
- Update message demo and update response features to match reference ([a7a9c8f](https://github.com/twangodev/sv11-ui/commit/a7a9c8fd8db73c3ae6938d2256b905e492e25b10))
- Update footer links for correct attribution and improve text clarity ([1341ef0](https://github.com/twangodev/sv11-ui/commit/1341ef0bd1a01626341844746547a574340d3771))
- Add missing newlines at the end of several markdown and Svelte files ([f1aa252](https://github.com/twangodev/sv11-ui/commit/f1aa252d2c76e14a62008db16270be7dd40e8e18))
- Remote duplicate title and descriptions for components ([b169370](https://github.com/twangodev/sv11-ui/commit/b16937059dca0fbc14fd9458290499af22df733f))

### Features

- **blocks:** Add voice-chat-03 ([#31](https://github.com/twangodev/sv11-ui/pull/31)) ([6b6a81a](https://github.com/twangodev/sv11-ui/commit/6b6a81a847c1861edf9bd294e2eb8ff95bd05a4d))
- **docs:** Render components grid on /docs/components index ([#29](https://github.com/twangodev/sv11-ui/pull/29)) ([194f758](https://github.com/twangodev/sv11-ui/commit/194f7586b07d3128a67d3aadd61fba59b23a0d4c))
- **docs:** Add Copy Page button + LLM-friendly markdown twins ([#28](https://github.com/twangodev/sv11-ui/pull/28)) ([9f788fa](https://github.com/twangodev/sv11-ui/commit/9f788faef8c84eb26fde2fda9ef853e6d7373574))
- **logo:** Redesign mark as sv wordmark ([#27](https://github.com/twangodev/sv11-ui/pull/27)) ([86de789](https://github.com/twangodev/sv11-ui/commit/86de7895f5783777e9cc946a718779d59896c44d))
- **speaker-01:** Port scrollable scratch waveform from elevenlabs ([#18](https://github.com/twangodev/sv11-ui/pull/18)) ([ff3a177](https://github.com/twangodev/sv11-ui/commit/ff3a17712b9dca91df65265000c83c2f6e194eef))
- Auto-generated /changelog page via git-cliff ([#16](https://github.com/twangodev/sv11-ui/pull/16)) ([56e8852](https://github.com/twangodev/sv11-ui/commit/56e88528a1d9df7099bdd25068f8e16d75aad0b8))
- Docs autogen pipeline + site buildout (landing, blocks, command palette) ([#15](https://github.com/twangodev/sv11-ui/pull/15)) ([2822b97](https://github.com/twangodev/sv11-ui/commit/2822b9734f67ff0305089e0776e955dc570f0016))
- Update user message styling with global CSS variables for improved theming ([13f15b1](https://github.com/twangodev/sv11-ui/commit/13f15b17e2da59592d4ba89ba0edde829a4c33ea))
- Add documentation for custom and ElevenLabs adapters, dark mode theming, and update navigation structure ([a0e30c4](https://github.com/twangodev/sv11-ui/commit/a0e30c4f75b6b31bfa64912d6bef56a7eb2b877b))
- Add getting started, setup, troubleshooting, and usage documentation for svagent-ui components ([3283bb4](https://github.com/twangodev/sv11-ui/commit/3283bb4e3d4417f193915f4c50a872c8f8fed867))
- Enhance audio player and visualizer components with additional state management and dynamic properties ([e40b557](https://github.com/twangodev/sv11-ui/commit/e40b5570f943d7d15c672d4028f234e7ea5aa8b4))
- Add audio-related UI components to registry.json ([e166def](https://github.com/twangodev/sv11-ui/commit/e166deffe3ee28493c910ba0461b233e9f3b9f02))
- Add predev and prebuild scripts to package.json ([34e6deb](https://github.com/twangodev/sv11-ui/commit/34e6deb772665cb0ff60e7d5bf433f37b88e1170))
- Add external script for analytics integration ([571921b](https://github.com/twangodev/sv11-ui/commit/571921ba4465a278c368e173b3284d3af11ca805))
- Add Voice Picker component with audio preview and selection functionality ([c0aab06](https://github.com/twangodev/sv11-ui/commit/c0aab0677f0c77028d0c5e066fb4fe67485896a8))
- Enhance Orb component with tone mapping and color space adjustments ([8e14b4c](https://github.com/twangodev/sv11-ui/commit/8e14b4c644fac8bb2d5712ebf920b1b812eb5304))
- Add Orb component with 3D animation and audio reactivity using Three.js ([6919e88](https://github.com/twangodev/sv11-ui/commit/6919e88b1501b7b02a8a2a98d77e448cc68b8c12))
- Add Conversation Bar component with voice and text modes, supporting provider-agnostic integration ([12adb6a](https://github.com/twangodev/sv11-ui/commit/12adb6ae1ebf6fa9aef54021aeaaccca0d1c73e0))
- Add Speech Input component with provider-agnostic transcription adapter and demo ([7b277ce](https://github.com/twangodev/sv11-ui/commit/7b277ce82a0544e0d8f460e9d0b22d7130db2b1c))
- Implement Transcript Viewer component with audio synchronization and word highlighting ([cbcfdc0](https://github.com/twangodev/sv11-ui/commit/cbcfdc09c99bb4a3b9aeb9380b82ed9fdf6467ab))
- Add Bar Visualizer component for audio frequency band visualization with animated state transitions ([a1d9122](https://github.com/twangodev/sv11-ui/commit/a1d9122e7d4d30c62385b58c583319dddd68a5f3))
- Add Matrix component for retro LED display with animations and customizable patterns ([3d65a53](https://github.com/twangodev/sv11-ui/commit/3d65a531e12ed8a30c423fc981c17abd319b7c08))
- Add Mic Selector component for audio device selection with mute toggle and live waveform preview ([44192bf](https://github.com/twangodev/sv11-ui/commit/44192bf2d2f40d36e550ff5513cb5e433eac6362))
- Add Voice Button component with live waveform feedback for voice recording ([4b5968e](https://github.com/twangodev/sv11-ui/commit/4b5968eddc38ad2ca18a306643b9dabd299def5c))
- Add vite-plugin-devtools-json for enhanced development experience ([c61dbce](https://github.com/twangodev/sv11-ui/commit/c61dbcedd76cafbc4fd547a4639d57ac225296da))
- Add Live Waveform component for real-time audio visualization and microphone input ([e0c9e41](https://github.com/twangodev/sv11-ui/commit/e0c9e419c0dbaaf1541575fc71cd8309dc4365cf))
- Add Waveform component with audio visualization and recording features ([38dca04](https://github.com/twangodev/sv11-ui/commit/38dca041d3373aa42d8182f54d438111f72cefd2))
- Update audio player status to 'Done' in README ([5f69d6e](https://github.com/twangodev/sv11-ui/commit/5f69d6ee3feaea97b7bc7a43b2ec58851693660b))
- Add Dependabot configuration for npm and GitHub Actions updates ([ff67bb4](https://github.com/twangodev/sv11-ui/commit/ff67bb44d4dd89b259d1e796d05ca7410923c2f8))
- Add Audio Player component with playback controls and demo ([8d2fbd8](https://github.com/twangodev/sv11-ui/commit/8d2fbd8f6929493bc197ab1f7e35464599926e2a))
- Add Conversation component with context management and demo ([6fea65e](https://github.com/twangodev/sv11-ui/commit/6fea65ea65fe336b89e61a46d55bc519ff5732c0))
- Add Scrub Bar component with context management and demo ([befb5f2](https://github.com/twangodev/sv11-ui/commit/befb5f253fbcf478f98d69f8dbbbb09b7191ff3f))
- Add lint:fix script to package.json for automated code formatting and linting ([a0ad951](https://github.com/twangodev/sv11-ui/commit/a0ad951f23eef6c0f35afe5062a7990c99a80387))
- Add Message and Response components with corresponding documentation and demos ([557f6b3](https://github.com/twangodev/sv11-ui/commit/557f6b3e830cc223b8d07b597e22e1b54caf5593))
- Add GitHub Actions workflow for Svelte project with linting, type checking, build, and deployment steps ([9677189](https://github.com/twangodev/sv11-ui/commit/9677189a593375172e1b96a849a434f0e6eaa416))
- Port shadcn-svelte docs site infrastructure ([51b9cb9](https://github.com/twangodev/sv11-ui/commit/51b9cb9a814d2390788127fcb268a7dc8059efeb))
- Add ShimmeringText component with animation effects ([9b352b8](https://github.com/twangodev/sv11-ui/commit/9b352b8492e222039b944bb7eb6bbdf1e71cf11a))
- Add Message, MessageContent, and MessageAvatar components for chat interface ([104587e](https://github.com/twangodev/sv11-ui/commit/104587ea3525869a47a5bf99bacf0fe9ba57b411))
- Add Avatar component with image and fallback support ([e42aa3a](https://github.com/twangodev/sv11-ui/commit/e42aa3a043f379e2851c9ea1c21c6e2b195da9fa))
- Add Response component with Streamdown integration ([11ddcfb](https://github.com/twangodev/sv11-ui/commit/11ddcfbe96787be56f5ca5e42ec9db3e4880360e))
- Add useIsMobile hook to determine mobile viewport status ([2e88991](https://github.com/twangodev/sv11-ui/commit/2e88991448424b40d5e79dd7394e49ba1ea1a7fe))
- Add useDebounce hook for debouncing values with a specified delay ([4a26386](https://github.com/twangodev/sv11-ui/commit/4a263869a10f451c6870931fc2d7a0a1c1de319e))

---

# llms.txt

> Machine-readable documentation for LLMs and AI coding tools.

sv11-ui publishes its documentation in formats that large language models and AI
coding tools can consume directly, so assistants like Claude, ChatGPT, Cursor,
and v0 can answer questions and generate code with accurate, up-to-date context.

## llms.txt

The [`/llms.txt`](/llms.txt) file is an index of the entire documentation,
following the [llmstxt.org](https://llmstxt.org) convention. It lists every page
grouped by section, with links to the clean Markdown version of each.

```text
https://sv11.ui.twango.dev/llms.txt
```

## llms-full.txt

The [`/llms-full.txt`](/llms-full.txt) file inlines the full text of every
documentation page into a single file — useful for dropping the whole corpus
into a model's context window in one shot.

```text
https://sv11.ui.twango.dev/llms-full.txt
```

## Markdown twins

Every documentation page has a plain-Markdown twin: append `.md` to any docs URL.

```text
https://sv11.ui.twango.dev/docs/components/orb        # HTML page
https://sv11.ui.twango.dev/docs/components/orb.md     # Markdown twin
```

The twins expand the interactive examples into real `svelte` code fences and
render the component API as a Markdown table, so a model sees usable source
rather than rendered widgets.

## Copy Page

Each documentation page has a **Copy Page** button in its header. It copies the
page's Markdown to your clipboard, and its dropdown offers **View as Markdown**,
**Open in ChatGPT**, and **Open in Claude** — each pre-loaded with the page so
you can start asking questions immediately.

---

# Adapters

> Recipes for wiring common voice and transcription providers into sv11 components.

sv11's voice and conversation components accept adapter objects that bridge a specific backend to a provider-agnostic interface. This section will collect recipes for implementing those adapters against common SDKs.

The interface definitions themselves live on the [Providers](/docs/providers) page — the recipes here assume you have already read that reference.

## Recipes

- [ElevenLabs](/docs/adapters/elevenlabs) — **TODO**
- [Custom](/docs/adapters/custom) — **TODO**

OpenAI and Deepgram recipes are planned.

An adapter is just any object that matches the published interface, so you can wrap any SDK, HTTP endpoint, or WebSocket protocol the same way.

---

# Custom

> Build a ConversationAdapter against your own backend.

> **TODO:** Recipe content pending.

This recipe will show how to implement a [`ConversationAdapter`](/docs/providers) against a custom backend — for example, a WebSocket protocol, a streaming HTTP endpoint, or an in-process mock.

Planned content:

- Minimal WebSocket skeleton mapping connection lifecycle to `onStatusChange` / `onConnect` / `onDisconnect`
- Wire format for emitting `ConversationMessage` objects through `onMessage`
- Optional `onModeChange` handling for backends that distinguish speaking vs listening
- Patterns for `sendMessage`, `sendContextualUpdate`, and `setMuted`

Until this page is filled in, see [Providers](/docs/providers) for the interface definitions.

---

# ElevenLabs

> Wrap the @elevenlabs/client SDK in a ConversationAdapter.

> **TODO:** Recipe content pending.

This recipe will show how to wrap [`@elevenlabs/client`](https://www.npmjs.com/package/@elevenlabs/client) in a [`ConversationAdapter`](/docs/providers) so that ElevenLabs Agents plug into [ConversationBar](/docs/components/conversation-bar) without modifying any sv11 code.

Planned content:

- Installing `@elevenlabs/client`
- A factory function that maps ElevenLabs session events to the `ConversationConfig` callbacks (`onConnect`, `onDisconnect`, `onMessage`, `onError`, `onStatusChange`, `onModeChange`)
- Public vs private agent auth (signed URLs vs bare `agentId`)
- Usage with `<ConversationBar {adapter} />`

Until this page is filled in, see [Providers](/docs/providers) for the interface definitions and [Custom](/docs/adapters/custom) for the general pattern.

---

# Components

> Browse the available components in sv11-ui.

Browse the available components. Each is provider-agnostic and composable — wire them to any backend via the [adapter interfaces](/docs/providers).

<ComponentsList />

---

# Audio Player

> A composable audio playback component with play/pause, seek, time display, and playback speed controls.

```svelte
<script lang="ts">
	import { Card } from "$lib/registry/ui/card/index.js";
	import * as AudioPlayer from "$lib/registry/ui/audio-player/index.js";
	import { exampleTracks } from "$lib/registry/ui/audio-player/index.js";
	import { ScrollArea } from "$lib/registry/ui/scroll-area/index.js";
	import AudioPlayerDemoPlayer from "./audio-player-demo-player.svelte";
	import AudioPlayerDemoSong from "./audio-player-demo-song.svelte";
</script>

<Card class="w-full overflow-hidden p-0">
	<AudioPlayer.Root>
		<div class="flex flex-col lg:h-[180px] lg:flex-row">
			<div class="bg-muted/50 flex flex-col overflow-hidden lg:h-full lg:w-64">
				<ScrollArea class="h-48 w-full lg:h-full">
					<div class="space-y-1 p-3">
						{#each exampleTracks as song, index (song.id)}
							<AudioPlayerDemoSong {song} trackNumber={index + 1} />
						{/each}
					</div>
				</ScrollArea>
			</div>
			<AudioPlayerDemoPlayer />
		</div>
	</AudioPlayer.Root>
</Card>
```

## Installation

```bash
npx shadcn-svelte@latest add https://sv11.ui.twango.dev/r/audio-player.json
```

## Usage

```svelte
<script lang="ts">
	import { AudioPlayer } from "$lib/registry/ui/audio-player";
</script>

<AudioPlayer />
```

```svelte
<script lang="ts">
	import * as AudioPlayer from "$lib/registry/ui/audio-player";
</script>

<AudioPlayer.Root>
	<div class="flex items-center gap-4">
		<AudioPlayer.Button />
		<AudioPlayer.Time />
		<AudioPlayer.Progress class="flex-1" />
		<AudioPlayer.Duration />
	</div>
</AudioPlayer.Root>
```

## Examples

### Basic Usage

Pass an `AudioPlayerItem` to `AudioPlayer.Button` via the `item` prop. Activating the button loads and plays that track; the root swaps `src` automatically.

```svelte
<script lang="ts">
	import * as AudioPlayer from "$lib/registry/ui/audio-player";

	const track = {
		id: "track-1",
		src: "/audio/song.mp3",
		data: { title: "My Song", artist: "Artist Name" },
	};
</script>

<AudioPlayer.Root>
	<AudioPlayer.Button item={track} />
	<AudioPlayer.Progress />
</AudioPlayer.Root>
```

### Multiple Tracks

A single `AudioPlayer.Root` can front many tracks. Each per-track `AudioPlayer.Button` only toggles playback for its own item — the shared `Progress`, `Time`, and `Duration` track whatever is currently active.

```svelte
<script lang="ts">
	import * as AudioPlayer from "$lib/registry/ui/audio-player";

	const tracks = [
		{ id: "1", src: "/audio/track1.mp3", data: { title: "Track 1" } },
		{ id: "2", src: "/audio/track2.mp3", data: { title: "Track 2" } },
		{ id: "3", src: "/audio/track3.mp3", data: { title: "Track 3" } },
	];
</script>

<AudioPlayer.Root>
	<div class="space-y-4">
		{#each tracks as track (track.id)}
			<div class="flex items-center gap-4">
				<AudioPlayer.Button item={track} />
				<span class="text-sm">{track.data.title}</span>
			</div>
		{/each}
		<AudioPlayer.Progress class="w-full" />
		<div class="flex gap-2 text-sm">
			<AudioPlayer.Time />
			<span>/</span>
			<AudioPlayer.Duration />
		</div>
	</div>
</AudioPlayer.Root>
```

### Playback Speed

Drop in `AudioPlayer.Speed` for a dropdown picker, or `AudioPlayer.SpeedButtonGroup` for an inline segmented control. Both write to the same shared `playbackRate` and persist across track swaps.

```svelte
<script lang="ts">
	import * as AudioPlayer from "$lib/registry/ui/audio-player";
</script>

<AudioPlayer.Root>
	<div class="flex items-center gap-4">
		<AudioPlayer.Button />
		<AudioPlayer.Time />
		<AudioPlayer.Progress class="flex-1" />
		<AudioPlayer.Duration />
		<AudioPlayer.Speed />
	</div>
	<AudioPlayer.SpeedButtonGroup speeds={[0.5, 1, 1.5, 2]} />
</AudioPlayer.Root>
```

### Custom Controls

`useAudioPlayer()` exposes the underlying state and imperative controls. Use it for bespoke UI — custom transport buttons, jump controls, speed presets — while the root still manages the `<audio>` element. `useAudioPlayer()` calls `getContext` at init time, so it must live in a component rendered inside `<AudioPlayer.Root>`.

```svelte
<!-- CustomControls.svelte -->
<script lang="ts">
	import { useAudioPlayer } from "$lib/registry/ui/audio-player";
	import { Button } from "$lib/registry/ui/button";

	const player = useAudioPlayer();
</script>

<div class="space-y-4">
	<Button onclick={() => (player.isPlaying ? player.pause() : player.play())}>
		{player.isPlaying ? "Pause" : "Play"}
	</Button>

	<Button onclick={() => player.seek(0)}>Restart</Button>

	<Button
		onclick={() => {
			if (player.duration) player.seek(player.duration * 0.5);
		}}
	>
		Jump to 50%
	</Button>

	<Button onclick={() => player.setPlaybackRate(1.5)}>Speed 1.5x</Button>
</div>
```

```svelte
<script lang="ts">
	import * as AudioPlayer from "$lib/registry/ui/audio-player";
	import CustomControls from "./CustomControls.svelte";
</script>

<AudioPlayer.Root>
	<CustomControls />
</AudioPlayer.Root>
```

### Error Handling

The root surfaces the `<audio>` element's `MediaError` through `player.error`. Read it from `useAudioPlayer()` inside a child component to render a fallback when loading fails. Like the custom-controls example above, the fragment must be rendered inside `<AudioPlayer.Root>` so the hook resolves its context.

```svelte
<!-- ErrorBanner.svelte -->
<script lang="ts">
	import * as AudioPlayer from "$lib/registry/ui/audio-player";
	import { useAudioPlayer } from "$lib/registry/ui/audio-player";

	const player = useAudioPlayer();
</script>

{#if player.error}
	<div class="text-red-500">
		Failed to load: {player.activeItem?.src}
		<br />
		Error: {player.error.message}
	</div>
{:else}
	<AudioPlayer.Button />
{/if}
```

```svelte
<script lang="ts">
	import * as AudioPlayer from "$lib/registry/ui/audio-player";
	import ErrorBanner from "./ErrorBanner.svelte";
</script>

<AudioPlayer.Root>
	<ErrorBanner />
</AudioPlayer.Root>
```

## API Reference

In addition to the root, the registry ships `AudioPlayerButton`, `AudioPlayerProgress`, `AudioPlayerTime`, `AudioPlayerDuration`, `AudioPlayerSpeed`, and `AudioPlayerSpeedButtonGroup` — see [source](https://github.com/twangodev/sv11-ui/tree/main/src/lib/registry/ui/audio-player) for their props.

| Prop | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `children?` | `Snippet` | — | Sub-components that read the shared player state via context (e.g. `<AudioPlayer.Button />`, `<AudioPlayer.Progress />`). |

## Notes

- `AudioPlayer.Root` renders a single hidden `<audio crossorigin="anonymous">` element and shares its state via context, so every sub-component reads the same track.
- A `requestAnimationFrame` loop syncs `currentTime`, `duration`, `readyState`, `networkState`, `paused`, `playbackRate`, and `error` onto the shared state each frame, keeping UI updates smooth even across rapid seeks.
- `AudioPlayer.Button` toggles between the global track and a specific `item`. When `item` is set, the button only shows active/buffering states while that track is the active one.
- `AudioPlayer.Progress` pauses during pointer interaction and resumes after release if playback was active. Pressing space on a focused thumb toggles play/pause instead of nudging the value.
- `AudioPlayer.Speed` uses the dropdown primitive and shows "Normal" for 1x; `AudioPlayer.SpeedButtonGroup` renders a flat row of buttons for a more compact picker.
- Playback rate persists across track swaps: changing tracks preserves the last-set `playbackRate` on the underlying element.
- `useAudioPlayer<TData>()` is generic over the `data` payload carried on each `AudioPlayerItem`, so you get typed access to metadata (titles, artwork, etc.) alongside the `src`.

---

# Bar Visualizer

> Audio frequency band visualizer with agent state animations. Renders a row of animated bars driven by a MediaStream via Web Audio's AnalyserNode, with built-in demo mode.

```svelte
<script lang="ts">
	import { BarVisualizer, type AgentState } from "$lib/registry/ui/bar-visualizer/index.js";
	import { Button } from "$lib/registry/ui/button/index.js";
	import {
		Card,
		CardContent,
		CardDescription,
		CardHeader,
		CardTitle,
	} from "$lib/registry/ui/card/index.js";

	let state = $state<AgentState>("listening");

	const states: AgentState[] = ["connecting", "initializing", "listening", "speaking", "thinking"];

	function labelFor(s: AgentState): string {
		return s.charAt(0).toUpperCase() + s.slice(1);
	}
</script>

<Card>
	<CardHeader>
		<CardTitle>Audio Frequency Visualizer</CardTitle>
		<CardDescription>
			Real-time frequency band visualization with animated state transitions
		</CardDescription>
	</CardHeader>
	<CardContent>
		<div class="space-y-4">
			<BarVisualizer
				{state}
				demo
				barCount={20}
				minHeight={15}
				maxHeight={90}
				class="h-40 max-w-full"
			/>

			<div class="flex flex-wrap gap-2">
				{#each states as s (s)}
					<Button
						size="sm"
						variant={state === s ? "default" : "outline"}
						onclick={() => (state = s)}
					>
						{labelFor(s)}
					</Button>
				{/each}
			</div>
		</div>
	</CardContent>
</Card>
```

## Installation

```bash
npx shadcn-svelte@latest add https://sv11.ui.twango.dev/r/bar-visualizer.json
```

## Usage

```svelte
<script lang="ts">
	import { BarVisualizer } from "$lib/registry/ui/bar-visualizer";
</script>

<BarVisualizer />
```

## Examples

### Basic Usage

Pipe a live `MediaStream` into the visualizer. The FFT slice is analysed on every frame and mapped onto `barCount` bars.

```svelte
<script lang="ts">
	import { BarVisualizer } from "$lib/registry/ui/bar-visualizer";

	let stream: MediaStream | null = $state(null);
</script>

<BarVisualizer state="listening" barCount={15} mediaStream={stream} />
```

### Demo Mode

Set `demo` to swap live audio for a synthetic oscillating pattern. Handy for previews where no microphone is available.

```svelte
<BarVisualizer state="speaking" demo centerAlign />
```

### Agent State

Drive the highlight sequence and animation cadence from an agent lifecycle value. `"thinking"` pulses, `"connecting"` sweeps, `"listening"` and `"speaking"` emphasise the active bars.

```svelte
<script lang="ts">
	import { BarVisualizer, type AgentState } from "$lib/registry/ui/bar-visualizer";

	let state: AgentState = $state("connecting");
</script>

<BarVisualizer {state} demo />
```

### Height Range

Tune the usable vertical band by adjusting `minHeight` and `maxHeight` (both percentages of the container).

```svelte
<BarVisualizer state="speaking" demo minHeight={15} maxHeight={90} />
```

## API Reference

| Prop | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `state?` | `AgentState` | — | Voice-agent lifecycle state. Drives the bar highlight sequence and animation cadence. Leave undefined for a static row. |
| `barCount?` | `number` | `15` | Number of bars to render across the visualizer. |
| `mediaStream?` | `MediaStream \| null` | — | Live audio source used for FFT analysis. Ignored when `demo` is `true`. Pass `null` to disable analysis without unmounting. |
| `minHeight?` | `number` | `20` | Minimum bar height as a percentage of the container. |
| `maxHeight?` | `number` | `100` | Maximum bar height as a percentage of the container. |
| `demo?` | `boolean` | `false` | When `true`, replaces the FFT feed with a synthetic oscillating pattern. Useful for previews and documentation. |
| `centerAlign?` | `boolean` | `false` | Align bars from the vertical center rather than growing up from the bottom. |
| `ref?` | `HTMLDivElement \| null` | `$bindable(null)` | Bound reference to the root container element. |

## Notes

- Analysis uses a Web Audio `AnalyserNode` with `fftSize: 2048`, sampling a mid-range slice of the spectrum and averaging each chunk into a bar.
- `demo` overrides `mediaStream` — the synthetic pattern is always active when `demo` is `true`, regardless of stream.
- The state sequencer runs independently of volume sampling, so `state` animates even without audio input.
- Bars update on `requestAnimationFrame` with a throttled diff check (changes under `0.01` are ignored) to minimise re-renders.
- `centerAlign` swaps the flex alignment from `items-end` to `items-center`, growing bars equally above and below the midline.

---

# Conversation

> A scroll-aware chat container that auto-sticks to the bottom as new messages stream in.

```svelte
<script lang="ts">
	import MessageCircleIcon from "@lucide/svelte/icons/message-circle";
	import * as Conversation from "$lib/registry/ui/conversation/index.js";
	import { Message, MessageContent } from "$lib/registry/ui/message/index.js";
	import { Response } from "$lib/registry/ui/response/index.js";

	type Turn = { id: string; role: "user" | "assistant"; text: string };

	const allMessages: Turn[] = [
		{ id: "1", role: "user", text: "Hey, I need help with my order" },
		{
			id: "2",
			role: "assistant",
			text: "Hi! I'd be happy to help you with your order. Could you please provide your order number?",
		},
		{ id: "3", role: "user", text: "It's ORDER-12345" },
		{
			id: "4",
			role: "assistant",
			text: "Thank you! Let me pull up your order details. I can see that your order was placed on March 15th and is currently being processed. It should ship within the next 1-2 business days. Is there anything specific you'd like to know about this order?",
		},
		{ id: "5", role: "user", text: "Can I change the shipping address?" },
		{
			id: "6",
			role: "assistant",
			text: "Absolutely! Since the order hasn't shipped yet, I can update the shipping address for you. What would you like the new address to be?",
		},
	];

	let messages: Turn[] = $state([]);
	let streamingMessageIndex: number | null = $state(null);
	let streamingContent = $state("");

	$effect(() => {
		const timeouts: ReturnType<typeof setTimeout>[] = [];
		const intervals: ReturnType<typeof setInterval>[] = [];
		let currentMessageIndex = 0;

		const addNextMessage = () => {
			if (currentMessageIndex >= allMessages.length) return;

			const message = allMessages[currentMessageIndex];

			if (message.role === "assistant") {
				streamingMessageIndex = currentMessageIndex;
				streamingContent = "";

				const words = message.text.split(" ");
				let wordIndex = 0;

				const streamInterval = setInterval(() => {
					if (wordIndex < words.length) {
						streamingContent += (wordIndex === 0 ? "" : " ") + words[wordIndex];
						wordIndex++;
					} else {
						clearInterval(streamInterval);
						messages = [...messages, message];
						streamingMessageIndex = null;
						streamingContent = "";
						currentMessageIndex++;
						timeouts.push(setTimeout(addNextMessage, 500));
					}
				}, 100);

				intervals.push(streamInterval);
			} else {
				messages = [...messages, message];
				currentMessageIndex++;
				timeouts.push(setTimeout(addNextMessage, 800));
			}
		};

		timeouts.push(setTimeout(addNextMessage, 1000));

		return () => {
			timeouts.forEach(clearTimeout);
			intervals.forEach(clearInterval);
		};
	});
</script>

<div
	class="bg-card relative mx-auto h-full min-h-0 w-full max-w-2xl flex-1 overflow-hidden rounded-lg border"
>
	<Conversation.Root class="absolute inset-0">
		<Conversation.Content>
			{#if messages.length === 0 && streamingMessageIndex === null}
				<Conversation.EmptyState
					title="Start a conversation"
					description="This is a simulated conversation"
				>
					{#snippet icon()}
						<MessageCircleIcon class="size-12" />
					{/snippet}
				</Conversation.EmptyState>
			{:else}
				{#each messages as message (message.id)}
					<Message from={message.role}>
						<MessageContent>
							<Response content={message.text} />
						</MessageContent>
					</Message>
				{/each}
				{#if streamingMessageIndex !== null}
					{@const streamingMsg = allMessages[streamingMessageIndex]}
					<Message from={streamingMsg.role}>
						<MessageContent>
							<Response content={streamingContent || "\u200B"} />
						</MessageContent>
					</Message>
				{/if}
			{/if}
		</Conversation.Content>
		<Conversation.ScrollButton />
	</Conversation.Root>
</div>
```

## Installation

```bash
npx shadcn-svelte@latest add https://sv11.ui.twango.dev/r/conversation.json
```

## Usage

```svelte
<script lang="ts">
	import { Conversation } from "$lib/registry/ui/conversation";
</script>

<Conversation />
```

## Examples

### Basic Usage

Wrap your message list in `Conversation.Root` and `Conversation.Content`. Include `Conversation.ScrollButton` to give users a way back to the latest turn after they scroll up.

```svelte
<script lang="ts">
	import * as Conversation from "$lib/registry/ui/conversation";

	type Turn = { id: string; content: string };
	let messages: Turn[] = $state([]);
</script>

<Conversation.Root>
	<Conversation.Content>
		{#each messages as message (message.id)}
			<div>{message.content}</div>
		{/each}
	</Conversation.Content>
	<Conversation.ScrollButton />
</Conversation.Root>
```

### With Empty State

Render `Conversation.EmptyState` when the message list is empty. It accepts `title`, `description`, and an `icon` snippet.

```svelte
<script lang="ts">
	import MessageCircleIcon from "@lucide/svelte/icons/message-circle";
	import * as Conversation from "$lib/registry/ui/conversation";

	type Turn = { id: string; content: string };
	let messages: Turn[] = $state([]);
</script>

<Conversation.Root>
	<Conversation.Content>
		{#if messages.length === 0}
			<Conversation.EmptyState
				title="No messages yet"
				description="Start a conversation to see messages here"
			>
				{#snippet icon()}
					<MessageCircleIcon class="size-12" />
				{/snippet}
			</Conversation.EmptyState>
		{:else}
			{#each messages as message (message.id)}
				<div>{message.content}</div>
			{/each}
		{/if}
	</Conversation.Content>
	<Conversation.ScrollButton />
</Conversation.Root>
```

## API Reference

| Prop | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `children?` | `Snippet` | — | Conversation body — typically a `Conversation.Content` and optional `Conversation.ScrollButton`. |
| `initial?` | `ScrollBehavior` | `"smooth"` | Scroll behavior used on first mount to anchor to the bottom. |
| `resize?` | `ScrollBehavior` | `"smooth"` | Scroll behavior used when content resizes (e.g. new messages streamed in) while the user is anchored to the bottom. |

## Notes

- Built on [`stick-to-bottom-svelte`](https://www.npmjs.com/package/stick-to-bottom-svelte) for smooth scroll anchoring.
- Automatically stays pinned to the bottom as new content is appended, unless the user has scrolled up.
- `Conversation.ScrollButton` only appears when the user is not at the bottom. It calls `scrollToBottom()` on the parent context.
- `Conversation.EmptyState` accepts either strings or `Snippet`s for `title` and `description`, plus a separate `icon` snippet. Passing `children` overrides the entire default layout.
- Sub-components (`Content`, `ScrollButton`, `EmptyState`) read the parent context and will throw if used outside `Conversation.Root`.
- Pair with [`Message`](/docs/components/message) for styled user/assistant turns, or render any custom markup inside `Conversation.Content`.

---

# Conversation Bar

> A compact conversation input bar with voice and text modes. Provider-agnostic — pass a ConversationAdapter wired to ElevenLabs, OpenAI Realtime, or any voice/chat backend.

```svelte
<script lang="ts">
	import InfoIcon from "@lucide/svelte/icons/info";
	import {
		ConversationBar,
		type ConversationAdapter,
	} from "$lib/registry/ui/conversation-bar/index.js";

	let toastMessage = $state<string | null>(null);
	let toastTimer: ReturnType<typeof setTimeout> | null = null;

	function showToast(message: string) {
		if (toastTimer !== null) clearTimeout(toastTimer);
		toastMessage = message;
		toastTimer = setTimeout(() => {
			toastMessage = null;
			toastTimer = null;
		}, 3500);
	}

	const demoAdapter: ConversationAdapter = {
		async connect() {
			throw new Error("This is a demo — no conversation backend is wired up.");
		},
		disconnect() {},
		sendMessage() {},
		sendContextualUpdate() {},
		setMuted() {},
	};
</script>

<div class="flex w-full flex-col gap-3">
	<div class="relative mx-auto w-full max-w-md">
		<ConversationBar adapter={demoAdapter} onError={(err) => showToast(err.message)} />

		{#if toastMessage}
			<div
				class="bg-foreground text-background animate-in fade-in slide-in-from-bottom-2 pointer-events-none absolute -top-2 right-0 -translate-y-full rounded-md px-3 py-2 text-xs shadow-lg duration-200"
				role="status"
			>
				{toastMessage}
			</div>
		{/if}
	</div>

	<div
		class="border-border bg-muted/40 text-muted-foreground mx-auto flex max-w-md items-start gap-3 rounded-md border p-3 text-xs"
		role="note"
	>
		<InfoIcon class="text-foreground mt-0.5 size-3.5 shrink-0" />
		<p>
			<code class="bg-muted rounded px-1 py-0.5">ConversationBar</code> is provider-agnostic — pass
			a <code class="bg-muted rounded px-1 py-0.5">ConversationAdapter</code> wired to ElevenLabs, OpenAI
			Realtime, or any other voice/chat backend. This demo has no backend hooked up.
		</p>
	</div>
</div>
```

## Installation

```bash
npx shadcn-svelte@latest add https://sv11.ui.twango.dev/r/conversation-bar.json
```

## Usage

```svelte
<script lang="ts">
	import { ConversationBar } from "$lib/registry/ui/conversation-bar";
</script>

<ConversationBar />
```

`<ConversationBar>` requires an `adapter` prop — see [Providers](/docs/providers#conversationadapter) for the interface and [Adapters](/docs/adapters) for provider recipes.

## Examples

### Basic Usage

Pass any object that matches `ConversationAdapter` and wire up the lifecycle callbacks you care about.

```svelte
<script lang="ts">
	import { ConversationBar } from "$lib/registry/ui/conversation-bar";
	import type { ConversationAdapter } from "$lib/registry/ui/conversation-bar";

	const adapter: ConversationAdapter = createMyAdapter(/* ... */);
</script>

<ConversationBar
	{adapter}
	onConnect={() => console.log("Connected")}
	onDisconnect={() => console.log("Disconnected")}
	onMessage={(message) => console.log("Message:", message)}
	onError={(error) => console.error("Error:", error)}
/>
```

### Custom Styling

Merge extra classes onto the container with `class`, and onto the inner waveform container with `waveformClassName`.

```svelte
<ConversationBar
	{adapter}
	class="max-w-2xl"
	waveformClassName="bg-gradient-to-r from-blue-500 to-purple-500"
/>
```

### Custom Disconnected Label

Replace the placeholder text shown in the waveform slot while the session is idle.

```svelte
<ConversationBar {adapter} disconnectedText="Tap to call support" />
```

### Collecting Messages

Accumulate the incoming `ConversationMessage` stream into reactive state — handy for pairing `ConversationBar` with a transcript or chat view.

```svelte
<script lang="ts">
	import { ConversationBar } from "$lib/registry/ui/conversation-bar";
	import type { ConversationAdapter, ConversationMessage } from "$lib/registry/ui/conversation-bar";

	const adapter: ConversationAdapter = createMyAdapter(/* ... */);
	let messages: ConversationMessage[] = $state([]);
</script>

<ConversationBar {adapter} onMessage={(m) => (messages = [...messages, m])} />
```

## API Reference

| Prop | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `adapter` | `ConversationAdapter` | — | Backend bridge that owns the session lifecycle — connecting, streaming messages, and muting. Conforms to [`ConversationAdapter`](/docs/providers#conversationadapter). |
| `disconnectedText?` | `string` | `"Customer Support"` | Label shown in the waveform slot while the session is disconnected. |
| `waveformClassName?` | `string` | — | Extra classes merged onto the inner waveform container. |
| `onConnect?` | `() => void` | — | Fired after the adapter reports a successful connection. |
| `onDisconnect?` | `() => void` | — | Fired after the adapter reports disconnection. |
| `onError?` | `(error: Error) => void` | — | Fired when the adapter surfaces an error or `connect()` rejects. |
| `onMessage?` | `(message: ConversationMessage) => void` | — | Fired for each message emitted by the adapter (both user and AI turns). |
| `onSendMessage?` | `(message: string) => void` | — | Fired after a text-input message has been handed off to the adapter. |
| `ref?` | `HTMLDivElement \| null` | `$bindable(null)` | Bindable ref to the root `<div>` element. |

## Notes

- Every method on `ConversationAdapter` is driven from user interaction: the mic, keyboard, phone, and send buttons call `setMuted`, `sendContextualUpdate`, `disconnect`/`connect`, and `sendMessage` respectively.
- The component tracks an internal `sessionId` so late callbacks from a prior `connect()` are ignored — swapping adapters or rapid connect/disconnect cycles cannot leak stale state into the UI.
- Text input fires `sendContextualUpdate(text)` on every keystroke while the keyboard is open, and `sendMessage(text)` on `Enter` (shift-enter inserts a newline). Adapters that do not implement contextual updates can make `sendContextualUpdate` a no-op.
- The waveform visualizes the active microphone stream while `connected && !muted`. The mic, keyboard, and end-call buttons are disabled outside the `connected` state.
- `onDestroy` calls `adapter.disconnect()` if a session is still active, so unmounting the component always releases the underlying resources.
- `adapter` is a required prop on `ConversationBarProps`, so TypeScript will flag its omission at compile time. At runtime, pressing the phone button without an adapter would throw from `connect()` — the demo on this page uses a stub adapter that always rejects there to illustrate the `onError` path.

---

# Live Waveform

> Real-time canvas-based audio waveform visualizer with microphone input and customizable rendering modes.

```svelte
<script lang="ts">
	import { Button } from "$lib/registry/ui/button/index.js";
	import { Card, CardHeader, CardTitle, CardDescription } from "$lib/registry/ui/card/index.js";
	import { LiveWaveform } from "$lib/registry/ui/live-waveform/index.js";

	let active = $state(false);
	let processing = $state(false);
	let mode = $state<"static" | "scrolling">("static");

	function handleToggleActive() {
		active = !active;
		if (active) {
			processing = false;
		}
	}

	function handleToggleProcessing() {
		processing = !processing;
		if (processing) {
			active = false;
		}
	}
</script>

<Card class="w-full p-6">
	<CardHeader class="p-0 pb-4">
		<CardTitle>Live Audio Waveform</CardTitle>
		<CardDescription>
			Real-time microphone input visualization with audio reactivity
		</CardDescription>
	</CardHeader>

	<div class="space-y-4">
		<LiveWaveform
			{active}
			{processing}
			{mode}
			height={80}
			barWidth={3}
			barGap={2}
			fadeEdges
			barColor="gray"
			historySize={120}
		/>

		<div class="flex flex-wrap justify-center gap-2">
			<Button size="sm" variant={active ? "default" : "outline"} onclick={handleToggleActive}>
				{active ? "Stop" : "Start"} Listening
			</Button>
			<Button
				size="sm"
				variant={processing ? "default" : "outline"}
				onclick={handleToggleProcessing}
			>
				{processing ? "Stop" : "Start"} Processing
			</Button>
			<Button
				size="sm"
				variant="outline"
				onclick={() => (mode = mode === "static" ? "scrolling" : "static")}
			>
				Mode: {mode === "static" ? "Static" : "Scrolling"}
			</Button>
		</div>
	</div>
</Card>
```

## Installation

```bash
npx shadcn-svelte@latest add https://sv11.ui.twango.dev/r/live-waveform.json
```

## Usage

```svelte
<script lang="ts">
	import { LiveWaveform } from "$lib/registry/ui/live-waveform";
</script>

<LiveWaveform />
```

## Examples

### Static Mode

Render a symmetric frequency-band visualization with bars in fixed positions.

```svelte
<script lang="ts">
	import { LiveWaveform } from "$lib/registry/ui/live-waveform";
</script>

<LiveWaveform active mode="static" />
```

### Scrolling Mode

Render the volume average as a timeline that scrolls right-to-left.

```svelte
<script lang="ts">
	import { LiveWaveform } from "$lib/registry/ui/live-waveform";
</script>

<LiveWaveform active mode="scrolling" />
```

### Processing State

`processing` animates a placeholder wave while you wait for audio. The bars ease back to idle when both `active` and `processing` turn off.

```svelte
<script lang="ts">
	import { LiveWaveform } from "$lib/registry/ui/live-waveform";
</script>

<LiveWaveform processing mode="static" />
```

### Custom Styling

Every rendering parameter is a plain prop — adjust bar geometry, color, height, and edge fade inline.

```svelte
<script lang="ts">
	import { LiveWaveform } from "$lib/registry/ui/live-waveform";
</script>

<LiveWaveform
	active
	barWidth={4}
	barHeight={6}
	barGap={2}
	barColor="#3b82f6"
	height={100}
	fadeEdges
/>
```

## API Reference

| Prop | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `active?` | `boolean` | `false` | When `true`, requests microphone access and drives the waveform from live audio input. Toggling off stops the stream and closes the audio context. |
| `processing?` | `boolean` | `false` | When `true` (and `active` is `false`), renders an animated placeholder wave pattern. Use this to signal a processing or awaiting state. |
| `deviceId?` | `string` | — | Specific `MediaDeviceInfo.deviceId` to capture from. Omit to use the default microphone. |
| `barWidth?` | `number` | `3` | Width of each bar in pixels. |
| `barHeight?` | `number` | `4` | Minimum bar height in pixels. Bars are drawn at least this tall even when their value is near zero. |
| `barGap?` | `number` | `1` | Gap between bars in pixels. |
| `barRadius?` | `number` | `1.5` | Corner radius applied to each bar. |
| `barColor?` | `string` | — | Custom bar color. Falls back to the canvas's computed `color` when unset. |
| `fadeEdges?` | `boolean` | `true` | Fade the left and right edges of the waveform via a destination-out gradient mask. |
| `fadeWidth?` | `number` | `24` | Width of the edge fade region in pixels. |
| `height?` | `string \| number` | `64` | Height of the waveform container. Numbers are treated as pixels; strings are passed through as a CSS length. |
| `sensitivity?` | `number` | `1` | Amplitude multiplier applied to normalized frequency data before rendering. Higher values make quiet sounds visible. |
| `smoothingTimeConstant?` | `number` | `0.8` | Smoothing factor forwarded to the underlying `AnalyserNode` in `[0, 1]`. Higher values produce smoother transitions. |
| `fftSize?` | `number` | `256` | FFT size forwarded to the underlying `AnalyserNode`. Must be a power of two. |
| `historySize?` | `number` | `60` | Maximum number of samples retained in scrolling mode. |
| `updateRate?` | `number` | `30` | Minimum interval in milliseconds between audio samples. |
| `mode?` | `"scrolling" \| "static"` | `"static"` | `"static"` renders a symmetric frequency-band visualization; `"scrolling"` renders the volume average as a timeline that scrolls right-to-left. |
| `onError?` | `(error: Error) => void` | — | Called when microphone setup fails (e.g. permission denied). |
| `onStreamReady?` | `(stream: MediaStream) => void` | — | Called with the captured `MediaStream` once the microphone is ready. |
| `onStreamEnd?` | `() => void` | — | Called when the stream is stopped or `active` flips back to `false`. |

## Notes

- Uses the Web Audio API via `AnalyserNode` for real-time frequency analysis.
- Automatically requests microphone permission when `active` becomes `true` and tears down the stream and audio context when it flips back to `false`.
- Canvas rendering is HiDPI-aware — internal `ResizeObserver` scales the drawing buffer by `devicePixelRatio`.
- `mode="static"` draws symmetric frequency bars in fixed positions; `mode="scrolling"` maintains a `historySize`-length ring buffer of volume averages that scrolls right-to-left.
- `processing` smoothly crossfades from the last active frame into the synthetic wave, and a fade-out pass clears the canvas when both flags are off.
- `deviceId` selects a specific input via `MediaDeviceInfo.deviceId`; omit to use the default microphone.
- `onStreamReady` / `onStreamEnd` / `onError` are fire-and-forget callbacks for wiring the lifecycle into app state.

---

# Matrix

> Retro dot-matrix LED display with circular cells and smooth animations. Supports static patterns, animated frame sequences, and VU meter mode.

```svelte
<script lang="ts" module>
	import { pulse, snake, wave, type Frame } from "$lib/registry/ui/matrix/index.js";

	const heart: Frame[] = (() => {
		const frames: Frame[] = [];
		const totalFrames = 30;

		const shape = [
			[0, 1, 1, 0, 1, 1, 0],
			[1, 1, 1, 1, 1, 1, 1],
			[1, 1, 1, 1, 1, 1, 1],
			[0, 1, 1, 1, 1, 1, 0],
			[0, 0, 1, 1, 1, 0, 0],
			[0, 0, 0, 1, 0, 0, 0],
			[0, 0, 0, 0, 0, 0, 0],
		];

		for (let f = 0; f < totalFrames; f++) {
			const frame: Frame = Array(7)
				.fill(0)
				.map(() => Array(7).fill(0));

			const phase = (f / totalFrames) * Math.PI * 2;
			const intensity = ((Math.sin(phase) + 1) / 2) * 0.3 + 0.7;

			for (let r = 0; r < 7; r++) {
				for (let c = 0; c < 7; c++) {
					if (shape[r][c]) {
						frame[r][c] = intensity;
					}
				}
			}

			frames.push(frame);
		}
		return frames;
	})();

	const sandTimer: Frame[] = (() => {
		const frames: Frame[] = [];
		const totalFrames = 60;

		for (let f = 0; f < totalFrames; f++) {
			const frame: Frame = Array(7)
				.fill(0)
				.map(() => Array(7).fill(0));

			frame[0][2] = 1;
			frame[0][3] = 1;
			frame[0][4] = 1;
			frame[1][2] = 1;
			frame[1][4] = 1;
			frame[5][2] = 1;
			frame[5][4] = 1;
			frame[6][2] = 1;
			frame[6][3] = 1;
			frame[6][4] = 1;

			const progress = f / totalFrames;

			const topSand = Math.floor((1 - progress) * 8);
			for (let i = 0; i < topSand; i++) {
				if (i < 3) frame[1][3] = 1;
				if (i >= 3) frame[2][3] = 1;
			}

			const bottomSand = Math.floor(progress * 8);
			for (let i = 0; i < bottomSand; i++) {
				if (i < 3) frame[5][3] = 1;
				if (i >= 3 && i < 6) frame[4][3] = 1;
				if (i >= 6) frame[3][3] = 0.5;
			}

			frames.push(frame);
		}
		return frames;
	})();

	const spinner: Frame[] = (() => {
		const frames: Frame[] = [];
		const segments = 8;

		for (let f = 0; f < segments; f++) {
			const frame: Frame = Array(7)
				.fill(0)
				.map(() => Array(7).fill(0));

			const positions = [
				[1, 3],
				[1, 4],
				[2, 5],
				[3, 5],
				[4, 5],
				[5, 4],
				[5, 3],
				[5, 2],
				[4, 1],
				[3, 1],
				[2, 1],
				[1, 2],
			];

			for (let i = 0; i < 3; i++) {
				const idx = (f + i) % positions.length;
				const [r, c] = positions[idx];
				frame[r][c] = 1 - i * 0.3;
			}

			frames.push(frame);
		}
		return frames;
	})();

	const corners: Frame[] = (() => {
		const frames: Frame[] = [];
		for (let i = 0; i < 16; i++) {
			const frame: Frame = Array(7)
				.fill(0)
				.map(() => Array(7).fill(0));
			const progress = i / 16;

			for (let r = 0; r < 7; r++) {
				for (let c = 0; c < 7; c++) {
					const distFromCorner = Math.min(
						Math.sqrt(r * r + c * c),
						Math.sqrt(r * r + (6 - c) * (6 - c)),
						Math.sqrt((6 - r) * (6 - r) + c * c),
						Math.sqrt((6 - r) * (6 - r) + (6 - c) * (6 - c))
					);
					const threshold = progress * 8;
					if (distFromCorner <= threshold) {
						frame[r][c] = Math.max(0, 1 - Math.abs(distFromCorner - threshold));
					}
				}
			}
			frames.push(frame);
		}
		return frames;
	})();

	const sweep: Frame[] = (() => {
		const frames: Frame[] = [];
		for (let i = 0; i < 14; i++) {
			const frame: Frame = Array(7)
				.fill(0)
				.map(() => Array(7).fill(0));
			for (let r = 0; r < 7; r++) {
				for (let c = 0; c < 7; c++) {
					if (r + c === i) {
						frame[r][c] = 1;
					} else if (r + c === i - 1) {
						frame[r][c] = 0.5;
					} else if (r + c === i + 1) {
						frame[r][c] = 0.5;
					}
				}
			}
			frames.push(frame);
		}
		return frames;
	})();

	const expand: Frame[] = (() => {
		const frames: Frame[] = [];
		for (let i = 0; i <= 6; i++) {
			const frame: Frame = Array(7)
				.fill(0)
				.map(() => Array(7).fill(0));
			for (let r = 3 - i; r <= 3 + i; r++) {
				for (let c = 3 - i; c <= 3 + i; c++) {
					if (r >= 0 && r < 7 && c >= 0 && c < 7) {
						if (r === 3 - i || r === 3 + i || c === 3 - i || c === 3 + i) {
							frame[r][c] = 1;
						}
					}
				}
			}
			frames.push(frame);
		}
		for (let i = 5; i >= 0; i--) {
			const frame: Frame = Array(7)
				.fill(0)
				.map(() => Array(7).fill(0));
			for (let r = 3 - i; r <= 3 + i; r++) {
				for (let c = 3 - i; c <= 3 + i; c++) {
					if (r >= 0 && r < 7 && c >= 0 && c < 7) {
						if (r === 3 - i || r === 3 + i || c === 3 - i || c === 3 + i) {
							frame[r][c] = 1;
						}
					}
				}
			}
			frames.push(frame);
		}
		return frames;
	})();

	const burst: Frame[] = (() => {
		const frames: Frame[] = [];
		for (let f = 0; f < 8; f++) {
			const frame: Frame = Array(7)
				.fill(0)
				.map(() => Array(7).fill(0));

			const intensity = f < 4 ? f / 3 : (7 - f) / 3;

			if (f < 6) {
				for (let r = 0; r < 7; r++) {
					for (let c = 0; c < 7; c++) {
						const distance = Math.sqrt(Math.pow(r - 3, 2) + Math.pow(c - 3, 2));
						if (Math.abs(distance - f * 0.8) < 1.2) {
							frame[r][c] = intensity;
						}
					}
				}
			}

			frames.push(frame);
		}
		return frames;
	})();

	function createUnifiedPattern(frameIndex: number): Frame[] {
		const totalRows = 21;
		const totalCols = 21;
		const pattern: number[][] = [];

		for (let row = 0; row < totalRows; row++) {
			pattern[row] = [];
			for (let col = 0; col < totalCols; col++) {
				const centerX = totalCols / 2;
				const centerY = totalRows / 2;
				const distance = Math.sqrt(Math.pow(col - centerX, 2) + Math.pow(row - centerY, 2));
				const wave = Math.sin(distance * 0.5 - frameIndex * 0.2);
				const value = (wave + 1) / 2;
				pattern[row][col] = value;
			}
		}

		const matrices: Frame[] = [];
		for (let matrixRow = 0; matrixRow < 3; matrixRow++) {
			for (let matrixCol = 0; matrixCol < 3; matrixCol++) {
				const matrixFrame: Frame = [];
				for (let row = 0; row < 7; row++) {
					matrixFrame[row] = [];
					for (let col = 0; col < 7; col++) {
						const globalRow = matrixRow * 7 + row;
						const globalCol = matrixCol * 7 + col;
						matrixFrame[row][col] = pattern[globalRow][globalCol];
					}
				}
				matrices.push(matrixFrame);
			}
		}

		return matrices;
	}

	const configurations = [
		{ animation: pulse, fps: 16 },
		{ animation: wave, fps: 20 },
		{ animation: spinner, fps: 10 },
		{ animation: snake, fps: 15 },
		{ animation: heart, fps: 12 },
		{ animation: sandTimer, fps: 12 },
		{ animation: corners, fps: 10 },
		{ animation: sweep, fps: 14 },
		{ animation: expand, fps: 12 },
	];
</script>

<script lang="ts">
	import { Matrix } from "$lib/registry/ui/matrix/index.js";

	type Mode = "individual" | "unified" | "burst";

	let mode = $state<Mode>("individual");
	let unifiedFrame = $state(0);

	// Mode sequencing — timeout chain
	$effect(() => {
		const delays: Record<Mode, number> = {
			individual: 6000,
			unified: 5000,
			burst: 1000,
		};
		const next: Record<Mode, Mode> = {
			individual: "unified",
			unified: "burst",
			burst: "individual",
		};
		const currentMode = mode;
		const timeout = setTimeout(() => {
			mode = next[currentMode];
		}, delays[currentMode]);
		return () => clearTimeout(timeout);
	});

	// Unified mode frame tick
	$effect(() => {
		if (mode !== "unified") return;
		let frame = 0;
		const animate = setInterval(() => {
			frame += 1;
			unifiedFrame = frame;
		}, 50);
		return () => clearInterval(animate);
	});

	const unifiedPatterns = $derived(mode === "unified" ? createUnifiedPattern(unifiedFrame) : []);

	function getPatternForMatrix(index: number): Frame | undefined {
		if (mode === "unified") return unifiedPatterns[index];
		return undefined;
	}

	function getFramesForMatrix(index: number): Frame[] | undefined {
		if (mode === "individual") return configurations[index].animation;
		if (mode === "burst") return burst;
		return undefined;
	}

	function getFps(index: number): number {
		if (mode === "burst") return 30;
		return configurations[index].fps;
	}
</script>

<div class="flex min-h-[600px] w-full flex-col items-center justify-center p-8">
	<div
		class="grid gap-1.5 transition-all duration-1000"
		style="grid-template-columns: repeat(3, 1fr); grid-template-rows: repeat(3, 1fr);"
	>
		{#each [0, 1, 2, 3, 4, 5, 6, 7, 8] as index (index)}
			<div class="flex items-center justify-center transition-all duration-1000">
				<Matrix
					rows={7}
					cols={7}
					frames={getFramesForMatrix(index)}
					pattern={getPatternForMatrix(index)}
					fps={getFps(index)}
					size={10}
					gap={2}
					ariaLabel={`Matrix ${index + 1}`}
				/>
			</div>
		{/each}
	</div>
</div>
```

## Installation

```bash
npx shadcn-svelte@latest add https://sv11.ui.twango.dev/r/matrix.json
```

## Usage

```svelte
<script lang="ts">
	import { Matrix } from "$lib/registry/ui/matrix";
</script>

<Matrix />
```

## Examples

### Static Pattern

Render a single frame by passing `pattern`. The built-in `digits` preset ships as a `Frame[]` indexed by numeral.

```svelte
<script lang="ts">
	import { Matrix, digits } from "$lib/registry/ui/matrix";
</script>

<Matrix rows={7} cols={5} pattern={digits[5]} ariaLabel="Number five" />
```

### Animated Display

Pass a `Frame[]` to `frames` and the matrix steps through them at `fps`.

```svelte
<script lang="ts">
	import { Matrix, wave } from "$lib/registry/ui/matrix";
</script>

<Matrix rows={7} cols={7} frames={wave} fps={20} loop ariaLabel="Wave animation" />
```

### VU Meter

Set `mode="vu"` and pass per-column `levels` in `[0, 1]`. Each column fills from the bottom.

```svelte
<Matrix
	rows={7}
	cols={12}
	mode="vu"
	levels={[0.1, 0.6, 0.9, 0.7, 0.4, 0.8, 0.5, 0.3, 0.6, 0.9, 0.5, 0.2]}
/>
```

### Custom Pattern

Hand-author a `Frame` (a 2D array of brightness values) for bespoke glyphs.

```svelte
<script lang="ts">
	import { Matrix, type Frame } from "$lib/registry/ui/matrix";

	const heart: Frame = [
		[0, 1, 1, 0, 1, 1, 0],
		[1, 1, 1, 1, 1, 1, 1],
		[1, 1, 1, 1, 1, 1, 1],
		[0, 1, 1, 1, 1, 1, 0],
		[0, 0, 1, 1, 1, 0, 0],
		[0, 0, 0, 1, 0, 0, 0],
	];
</script>

<Matrix
	rows={6}
	cols={7}
	pattern={heart}
	size={14}
	gap={2}
	palette={{ on: "hsl(0 84% 60%)", off: "hsl(0 84% 20%)" }}
/>
```

### Custom Palette

Swap the `on` / `off` colors to theme the display. Classic phosphor green:

```svelte
<Matrix
	rows={7}
	cols={7}
	frames={wave}
	fps={20}
	palette={{ on: "hsl(142 76% 36%)", off: "hsl(142 76% 10%)" }}
/>
```

### Frame Change Callback

`onFrame` fires whenever the active frame index advances, useful for syncing external UI.

```svelte
<script lang="ts">
	import { Matrix, loader } from "$lib/registry/ui/matrix";

	let currentFrame = $state(0);
</script>

<Matrix rows={7} cols={7} frames={loader} fps={12} onFrame={(i) => (currentFrame = i)} />
<p>Frame: {currentFrame}</p>
```

### Live VU Meter

Feed `levels` from reactive state to animate the meter at render time.

```svelte
<script lang="ts">
	import { Matrix } from "$lib/registry/ui/matrix";

	let levels = $state<number[]>(Array(12).fill(0));

	$effect(() => {
		const id = setInterval(() => {
			levels = Array.from({ length: 12 }, () => Math.random());
		}, 50);
		return () => clearInterval(id);
	});
</script>

<Matrix rows={7} cols={12} mode="vu" {levels} size={10} gap={2} />
```

### Custom Animation

Build an animation by supplying your own frame array.

```svelte
<script lang="ts">
	import { Matrix, type Frame } from "$lib/registry/ui/matrix";

	const frames: Frame[] = [
		[
			[1, 0, 1],
			[0, 1, 0],
			[1, 0, 1],
		],
		[
			[0, 1, 0],
			[1, 0, 1],
			[0, 1, 0],
		],
	];
</script>

<Matrix rows={3} cols={3} {frames} fps={2} loop />
```

## API Reference

| Prop | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `rows` | `number` | — | Number of rows in the matrix grid. |
| `cols` | `number` | — | Number of columns in the matrix grid. |
| `pattern?` | `Frame` | — | Static pattern to display. A 2D array of brightness values in `[0, 1]`. When set, animation is disabled and `frames` is ignored. |
| `frames?` | `Frame[]` | — | Ordered frames to loop through for animation. Ignored when `pattern` is provided. |
| `fps?` | `number` | `12` | Playback rate in frames per second when animating `frames`. |
| `autoplay?` | `boolean` | `true` | Start animating automatically on mount. Ignored when a static `pattern` is provided. |
| `loop?` | `boolean` | `true` | Loop the frame sequence. When `false`, animation halts on the last frame. |
| `size?` | `number` | `10` | Cell diameter in pixels. |
| `gap?` | `number` | `2` | Gap between cells in pixels. |
| `palette?` | `{ on: string; off: string }` | `on: "currentColor", off: "var(--muted-foreground)"` | CSS colors for active and inactive cells. Defaults map `on` to the current text color and `off` to the muted foreground token. |
| `brightness?` | `number` | `1` | Global brightness multiplier applied to every cell, clamped to `[0, 1]`. |
| `ariaLabel?` | `string` | — | ARIA label for the container. Falls back to `"matrix display"` when omitted. |
| `onFrame?` | `(index: number) => void` | — | Invoked whenever the active frame index changes during animation. |
| `mode?` | `MatrixMode` | `"default"` | Rendering mode. `"vu"` reads `levels` each render to draw a bottom-anchored meter instead of `frames` or `pattern`. |
| `levels?` | `number[]` | — | Per-column level values in `[0, 1]` used when `mode="vu"`. Ignored in other modes. |
| `ref?` | `HTMLDivElement \| null` | `$bindable(null)` | Bound reference to the root container element. |

## Notes

- Ships with built-in presets: `digits`, `loader`, `pulse`, `snake`, `wave`, `chevronLeft`, `chevronRight`, and a `vu()` helper for generating VU frames from level arrays.
- A `Frame` is `number[][]` indexed as `[row][col]`, with brightness in `[0, 1]`. Frames smaller than `rows` x `cols` are padded with zeros via the internal `ensureFrameSize` helper.
- When `pattern` is set, animation is disabled regardless of `frames`, `autoplay`, or `loop`.
- `mode="vu"` takes precedence over both `pattern` and `frames` when `levels` is non-empty.
- Animation uses a fixed-timestep accumulator on `requestAnimationFrame`, keeping frame cadence stable under variable paint rates.
- Cells render as SVG `<circle>` elements with a gradient fill plus a Gaussian-blur glow filter on active pixels.
- The container advertises `role="img"` and uses the provided `ariaLabel` (falling back to `"matrix display"`). Because `role="img"` is treated as an atomic graphic, per-frame updates are not re-announced — supply an `ariaLabel` that describes the overall display rather than per-frame content.

---

# Message

> A chat message component with avatar and content slots.

```svelte
<script lang="ts">
	import { Message, MessageContent } from "$lib/registry/ui/message/index.js";
	import { Response } from "$lib/registry/ui/response/index.js";

	const assistantMessage = `To create a new **voice agent**, head to the [Acme dashboard](https://example.com/agents). Then follow these steps:

1. Sign in to your provider dashboard.
2. Click **New Agent** to start.
3. Give your agent a name and description.
4. Configure its behavior, knowledge sources, and voice.
5. Save it — and your agent is ready to use.`;

	let content = $state("\u200B");

	$effect(() => {
		let index = 0;
		const step = 2;
		const interval = setInterval(() => {
			if (index < assistantMessage.length) {
				index = Math.min(index + step, assistantMessage.length);
				content = assistantMessage.slice(0, index);
			} else {
				clearInterval(interval);
			}
		}, 40);
		return () => clearInterval(interval);
	});
</script>

<div class="flex h-full max-h-[400px] w-full max-w-2xl flex-col overflow-hidden">
	<div class="flex flex-col gap-4 overflow-y-auto px-4 py-4">
		<div class="flex-shrink-0">
			<Message from="user">
				<MessageContent>
					<Response content="How do I create an agent?" />
				</MessageContent>
			</Message>
		</div>
		<div class="flex-shrink-0">
			<Message from="assistant">
				<MessageContent>
					<Response {content} />
				</MessageContent>
			</Message>
		</div>
	</div>
</div>
```

## Installation

```bash
npx shadcn-svelte@latest add https://sv11.ui.twango.dev/r/message.json
```

## Usage

```svelte
<script lang="ts">
	import { Message } from "$lib/registry/ui/message";
</script>

<Message />
```

## Examples

### Basic Usage

Compose `Message` with `MessageAvatar` and `MessageContent`. The `from` prop drives alignment and which group-scoped styles apply to descendants.

```svelte
<script lang="ts">
	import * as Message from "$lib/registry/ui/message";
</script>

<Message.Root from="user">
	<Message.Avatar src="/user-avatar.jpg" name="John" />
	<Message.Content>Hello, how can I help you?</Message.Content>
</Message.Root>

<Message.Root from="assistant">
	<Message.Avatar src="/assistant-avatar.jpg" name="AI" />
	<Message.Content>I'm here to assist you with any questions!</Message.Content>
</Message.Root>
```

### Message Variants

`MessageContent` accepts a `variant` prop. The default `"contained"` gives each message a filled bubble; `"flat"` drops the background on assistant messages for a minimal transcript look.

```svelte
<script lang="ts">
	import * as Message from "$lib/registry/ui/message";
</script>

<Message.Root from="user">
	<Message.Avatar src="/user-avatar.jpg" />
	<Message.Content variant="contained">This is a contained message with background</Message.Content>
</Message.Root>

<Message.Root from="assistant">
	<Message.Avatar src="/assistant-avatar.jpg" />
	<Message.Content variant="flat">This is a flat message with minimal styling</Message.Content>
</Message.Root>
```

### In a Conversation

`Message` pairs with `Conversation` for auto-sticking scroll behavior as new turns stream in.

```svelte
<script lang="ts">
	import * as Conversation from "$lib/registry/ui/conversation";
	import * as Message from "$lib/registry/ui/message";

	type Turn = {
		id: string;
		from: "user" | "assistant";
		avatarUrl: string;
		name: string;
		content: string;
	};

	let messages: Turn[] = $state([]);
</script>

<Conversation.Root>
	<Conversation.Content>
		{#each messages as message (message.id)}
			<Message.Root from={message.from}>
				<Message.Avatar src={message.avatarUrl} name={message.name} />
				<Message.Content>{message.content}</Message.Content>
			</Message.Root>
		{/each}
	</Conversation.Content>
</Conversation.Root>
```

## API Reference

| Prop | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `from` | `"user" \| "assistant"` | — | Determines the message's alignment and which group-scoped styles (`is-user` / `is-assistant`) apply to `MessageContent` and `MessageAvatar` descendants. |
| `children?` | `Snippet` | — | Message body — typically a `MessageContent` and/or `MessageAvatar`. |

## Notes

- Uses CSS group selectors (`group-[.is-user]` / `group-[.is-assistant]`) so `MessageContent` and `MessageAvatar` style themselves based on the parent `Message`'s `from` prop.
- User messages align to the right; assistant messages align to the left.
- `MessageContent`'s `"contained"` variant uses `bg-primary` for the user and `bg-secondary` for the assistant. `"flat"` keeps the user bubble and removes the assistant background.
- `MessageAvatar` wraps the `Avatar` primitive — it renders a fallback with the first two characters of `name` (or `ME` if `name` is omitted) when the image fails to load.
- Combines cleanly with the [`Response`](/docs/components/response) component for streaming markdown content inside `MessageContent`.

---

# Mic Selector

> Dropdown for selecting an input audio device with mute toggle and live waveform preview of the selected microphone.

```svelte
<script lang="ts">
	import Disc from "@lucide/svelte/icons/disc";
	import Pause from "@lucide/svelte/icons/pause";
	import Play from "@lucide/svelte/icons/play";
	import Trash2 from "@lucide/svelte/icons/trash-2";
	import { Button } from "$lib/registry/ui/button/index.js";
	import { Card } from "$lib/registry/ui/card/index.js";
	import { LiveWaveform } from "$lib/registry/ui/live-waveform/index.js";
	import { MicSelector } from "$lib/registry/ui/mic-selector/index.js";
	import { Separator } from "$lib/registry/ui/separator/index.js";
	import { cn } from "$lib/utils.js";

	type RecordingState = "idle" | "loading" | "recording" | "recorded" | "playing";

	let selectedDevice = $state("");
	let isMuted = $state(false);
	let recordingState = $state<RecordingState>("idle");
	let audioBlob = $state<Blob | null>(null);

	let mediaRecorder: MediaRecorder | null = null;
	let audioChunks: Blob[] = [];
	let audioElement: HTMLAudioElement | null = null;

	async function startRecording() {
		try {
			recordingState = "loading";

			const stream = await navigator.mediaDevices.getUserMedia({
				audio: selectedDevice ? { deviceId: { exact: selectedDevice } } : true,
			});

			const recorder = new MediaRecorder(stream);
			mediaRecorder = recorder;
			audioChunks = [];

			recorder.ondataavailable = (event) => {
				if (event.data.size > 0) {
					audioChunks.push(event.data);
				}
			};

			recorder.onstop = () => {
				const blob = new Blob(audioChunks, { type: "audio/webm" });
				audioBlob = blob;
				stream.getTracks().forEach((track) => track.stop());
				recordingState = "recorded";
			};

			recorder.start();
			recordingState = "recording";
		} catch (error) {
			console.error("Error starting recording:", error);
			recordingState = "idle";
		}
	}

	function stopRecording() {
		if (mediaRecorder && recordingState === "recording") {
			mediaRecorder.stop();
		}
	}

	function playRecording() {
		if (!audioBlob) return;

		const audio = new Audio(URL.createObjectURL(audioBlob));
		audioElement = audio;

		audio.onended = () => {
			recordingState = "recorded";
		};

		audio.play();
		recordingState = "playing";
	}

	function pausePlayback() {
		if (audioElement) {
			audioElement.pause();
			recordingState = "recorded";
		}
	}

	function restart() {
		if (audioElement) {
			audioElement.pause();
			audioElement = null;
		}
		audioBlob = null;
		audioChunks = [];
		recordingState = "idle";
	}

	// Stop recording when muted
	$effect(() => {
		if (isMuted && recordingState === "recording") {
			stopRecording();
		}
	});

	// Cleanup on unmount
	$effect(() => {
		return () => {
			if (mediaRecorder) {
				mediaRecorder.stop();
			}
			if (audioElement) {
				audioElement.pause();
			}
		};
	});

	const showWaveform = $derived(recordingState === "recording" && !isMuted);
	const showProcessing = $derived(recordingState === "loading" || recordingState === "playing");
	const showRecorded = $derived(recordingState === "recorded");
</script>

<div class="flex min-h-[200px] w-full items-center justify-center p-4">
	<Card class="m-0 w-full max-w-2xl border p-0 shadow-lg">
		<div class="flex w-full flex-wrap items-center justify-between gap-2 p-2">
			<div class="h-8 w-full min-w-0 flex-1 md:w-[200px] md:flex-none">
				<div
					class="bg-foreground/5 text-foreground/70 flex h-full items-center gap-2 rounded-md py-1"
				>
					<div class="h-full min-w-0 flex-1">
						<div
							class="relative flex h-full w-full shrink-0 items-center justify-center overflow-hidden rounded-sm"
						>
							{#key recordingState}
								<LiveWaveform
									active={showWaveform}
									processing={showProcessing}
									deviceId={selectedDevice}
									barWidth={3}
									barGap={1}
									barRadius={4}
									fadeEdges={true}
									fadeWidth={24}
									sensitivity={1.8}
									smoothingTimeConstant={0.85}
									height={20}
									mode="scrolling"
									class={cn(
										"h-full w-full transition-opacity duration-300",
										recordingState === "idle" && "opacity-0"
									)}
								/>
							{/key}
							{#if recordingState === "idle"}
								<div class="absolute inset-0 flex items-center justify-center">
									<span class="text-foreground/50 text-xs font-medium">Start Recording</span>
								</div>
							{/if}
							{#if showRecorded}
								<div class="absolute inset-0 flex items-center justify-center">
									<span class="text-foreground/50 text-xs font-medium">Ready to Play</span>
								</div>
							{/if}
						</div>
					</div>
				</div>
			</div>
			<div class="flex w-full flex-wrap items-center justify-center gap-1 md:w-auto">
				<MicSelector
					value={selectedDevice}
					onValueChange={(v) => (selectedDevice = v)}
					muted={isMuted}
					onMutedChange={(m) => (isMuted = m)}
					disabled={recordingState === "recording" || recordingState === "loading"}
				/>
				<Separator orientation="vertical" class="mx-1 -my-2.5" />
				<div class="flex">
					{#if recordingState === "idle"}
						<Button
							variant="ghost"
							size="icon"
							onclick={startRecording}
							disabled={isMuted}
							aria-label="Start recording"
						>
							<Disc class="size-5" />
						</Button>
					{/if}
					{#if recordingState === "loading" || recordingState === "recording"}
						<Button
							variant="ghost"
							size="icon"
							onclick={stopRecording}
							disabled={recordingState === "loading"}
							aria-label="Stop recording"
						>
							<Pause class="size-5" />
						</Button>
					{/if}
					{#if showRecorded}
						<Button variant="ghost" size="icon" onclick={playRecording} aria-label="Play recording">
							<Play class="size-5" />
						</Button>
					{/if}
					{#if recordingState === "playing"}
						<Button variant="ghost" size="icon" onclick={pausePlayback} aria-label="Pause playback">
							<Pause class="size-5" />
						</Button>
					{/if}
					<Separator orientation="vertical" class="mx-1 -my-2.5" />
					<Button
						variant="ghost"
						size="icon"
						onclick={restart}
						disabled={recordingState === "idle" ||
							recordingState === "loading" ||
							recordingState === "recording"}
						aria-label="Delete recording"
					>
						<Trash2 class="size-5" />
					</Button>
				</div>
			</div>
		</div>
	</Card>
</div>
```

## Installation

```bash
npx shadcn-svelte@latest add https://sv11.ui.twango.dev/r/mic-selector.json
```

## Usage

```svelte
<script lang="ts">
	import { MicSelector } from "$lib/registry/ui/mic-selector";
</script>

<MicSelector />
```

## Examples

### Basic Usage

Drop the selector in. It auto-selects the first available microphone and manages mute state internally.

```svelte
<script lang="ts">
	import { MicSelector } from "$lib/registry/ui/mic-selector";
</script>

<MicSelector />
```

### Controlled

Bind the selected `deviceId` to local state to react to device changes elsewhere in your UI.

```svelte
<script lang="ts">
	import { MicSelector } from "$lib/registry/ui/mic-selector";

	let selectedDevice = $state("");
</script>

<MicSelector value={selectedDevice} onValueChange={(id) => (selectedDevice = id)} />
```

### With Mute Control

Pair the mute callback with your own mute state so recording controls can react to it.

```svelte
<script lang="ts">
	import { MicSelector } from "$lib/registry/ui/mic-selector";

	let selectedDevice = $state("");
	let isMuted = $state(false);
</script>

<MicSelector
	value={selectedDevice}
	onValueChange={(id) => (selectedDevice = id)}
	muted={isMuted}
	onMutedChange={(m) => (isMuted = m)}
/>
```

### Custom Styling

Pass a `class` to restyle the trigger button.

```svelte
<MicSelector class="w-full max-w-md" />
```

### Using the Hook

The exported `useAudioDevices` hook powers the dropdown and can be reused to render your own UI. Call it from a component's script setup phase — its reactive effects bind to the caller's scope.

```svelte
<script lang="ts">
	import { useAudioDevices } from "$lib/registry/ui/mic-selector";

	const audio = useAudioDevices();
</script>

{#if audio.loading}
	<p>Loading devices...</p>
{:else if audio.error}
	<p>Error: {audio.error}</p>
{:else}
	<ul>
		{#each audio.devices as device (device.deviceId)}
			<li>{device.label}</li>
		{/each}
	</ul>
{/if}
```

## API Reference

| Prop | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `value?` | `string` | — | Selected microphone `deviceId`. Leave unset for uncontrolled mode — the first available device is auto-selected. |
| `onValueChange?` | `(deviceId: string) => void` | — | Called when the user picks a different microphone from the dropdown. |
| `muted?` | `boolean` | — | Mute state. Leave unset for uncontrolled mode, where the component tracks mute internally. |
| `onMutedChange?` | `(muted: boolean) => void` | — | Called when the user toggles the mute button. |
| `disabled?` | `boolean` | — | Disables the trigger button. |
| `class?` | `string` | — | — |

## Notes

- The trigger uses the `LiveWaveform` component inside the dropdown to preview the selected microphone in real time.
- On first open, the dropdown calls `navigator.mediaDevices.getUserMedia` to request microphone permission so device labels can be populated.
- The hook re-enumerates devices on `devicechange` events, so hot-plugging a headset updates the list without a refresh.
- Device labels are cleaned of parenthesized metadata (for example `"(Built-in)"`) before being displayed.
- Works in both controlled and uncontrolled modes for `value` and `muted` independently — omit either pair to let the component track state internally.
- The preview waveform only animates while the dropdown is open and the mic is not muted, so an idle selector does not hold an audio stream.

---

# Orb

> A 3D animated orb with audio reactivity, custom colors, and agent state visualization built with Three.js.

```svelte
<script lang="ts">
	import { Button } from "$lib/registry/ui/button/index.js";
	import { Orb, type OrbAgentState } from "$lib/registry/ui/orb/index.js";
	import { cn } from "$lib/utils.js";

	let { small = false }: { small?: boolean } = $props();

	const ALL_ORBS: Array<[string, string]> = [
		["#CADCFC", "#A0B9D1"],
		["#F6E7D8", "#E0CFC2"],
		["#E5E7EB", "#9CA3AF"],
	];

	const orbs = $derived(small ? [ALL_ORBS[0]] : ALL_ORBS);

	let agent = $state<OrbAgentState>(null);
</script>

<div class="bg-card w-full rounded-lg border p-6">
	<div class="mb-4">
		<h3 class="text-lg font-semibold">Agent Orbs</h3>
		<p class="text-muted-foreground text-sm">Interactive orb visualization with agent states</p>
	</div>

	<div class="space-y-4">
		<div class="flex justify-center gap-8">
			{#each orbs as colors, index (index)}
				<div class={cn("relative", small || index === 1 ? "block" : "hidden md:block")}>
					<div
						class="bg-muted relative h-32 w-32 rounded-full p-1 shadow-[inset_0_2px_8px_rgba(0,0,0,0.1)] dark:shadow-[inset_0_2px_8px_rgba(0,0,0,0.5)]"
					>
						<div
							class="bg-background h-full w-full overflow-hidden rounded-full shadow-[inset_0_0_12px_rgba(0,0,0,0.05)] dark:shadow-[inset_0_0_12px_rgba(0,0,0,0.3)]"
						>
							<Orb {colors} seed={(index + 1) * 1000} agentState={agent} />
						</div>
					</div>
				</div>
			{/each}
		</div>

		<div class="flex flex-wrap justify-center gap-2">
			<Button size="sm" variant="outline" onclick={() => (agent = null)} disabled={agent === null}>
				Idle
			</Button>
			<Button
				size="sm"
				variant="outline"
				onclick={() => (agent = "listening")}
				disabled={agent === "listening"}
			>
				Listening
			</Button>
			<Button
				size="sm"
				variant="outline"
				onclick={() => (agent = "talking")}
				disabled={agent === "talking"}
			>
				Talking
			</Button>
		</div>
	</div>
</div>
```

## Installation

```bash
npx shadcn-svelte@latest add https://sv11.ui.twango.dev/r/orb.json
```

## Usage

```svelte
<script lang="ts">
	import { Orb } from "$lib/registry/ui/orb";
</script>

<Orb />
```

## Examples

### Custom Colors

Pass a two-tuple of hex colors to replace the default gradient.

```svelte
<Orb colors={["#FF6B6B", "#4ECDC4"]} />
```

### Audio Reactivity

Sample live input and output volumes every frame by passing `getInputVolume` and `getOutputVolume`. Each should return a normalized value in `[0, 1]`.

```svelte
<script lang="ts">
	import { Orb } from "$lib/registry/ui/orb";

	function getInputVolume() {
		// Return normalized microphone volume between 0 and 1.
		return 0.5;
	}

	function getOutputVolume() {
		// Return normalized agent-output volume between 0 and 1.
		return 0.7;
	}
</script>

<Orb {getInputVolume} {getOutputVolume} />
```

### Custom Seed

Pass a `seed` for a deterministic orb shape — useful when you want a specific look to persist across reloads.

```svelte
<Orb seed={12345} />
```

### Agent State

Drive the orb's visual behavior from an agent lifecycle value. Pass `null` to render the idle state.

```svelte
<script lang="ts">
	import { Orb } from "$lib/registry/ui/orb";
	import type { OrbAgentState } from "$lib/registry/ui/orb";

	let agentState: OrbAgentState = $state(null);
</script>

<Orb {agentState} />
```

### Manual Volume Control

Switch `volumeMode` to `"manual"` and drive reactivity from reactive state instead of live audio streams.

```svelte
<script lang="ts">
	import { Orb } from "$lib/registry/ui/orb";

	let inputVolume = $state(0.5);
	let outputVolume = $state(0.7);
</script>

<Orb volumeMode="manual" manualInput={inputVolume} manualOutput={outputVolume} />
```

## API Reference

| Prop | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `colors?` | `[string, string]` | `["#CADCFC", "#A0B9D1"]` | Two hex colors sampled across the orb's gradient. Update reactively to animate between palettes. |
| `seed?` | `number` | — | Seed for the orb's internal noise, determining its overall shape. Defaults to a stable per-instance random value so multiple orbs on one page look distinct. |
| `agentState?` | `OrbAgentState` | `null` | Drives the orb's visual behavior to reflect the agent lifecycle. Pass `null` to render the idle state. |
| `volumeMode?` | `"auto" \| "manual"` | `"auto"` | `"auto"` uses the active microphone and output audio streams to drive reactivity. `"manual"` reads `manualInput` / `manualOutput` (or the `get*Volume` callbacks) instead. |
| `manualInput?` | `number` | — | Manual input volume in `[0, 1]`. Only read when `volumeMode="manual"`. |
| `manualOutput?` | `number` | — | Manual output volume in `[0, 1]`. Only read when `volumeMode="manual"`. |
| `getInputVolume?` | `() => number` | — | Called every frame to sample input volume in `[0, 1]`. Takes precedence over `manualInput` when both are provided. |
| `getOutputVolume?` | `() => number` | — | Called every frame to sample output volume in `[0, 1]`. Takes precedence over `manualOutput` when both are provided. |

## Notes

- Built on [Three.js](https://threejs.org/) and [@threlte/core](https://threlte.xyz/) for performant WebGL rendering from Svelte.
- Pass functions (`getInputVolume` / `getOutputVolume`) for live audio, or `manualInput` / `manualOutput` with `volumeMode="manual"` for direct control. The callbacks take precedence when both are set.
- Reactive props (`colors`, `agentState`) update smoothly — you can animate palette transitions by mutating `$state` without remounting.
- `seed` defaults to a stable per-instance random value, so multiple orbs on the same page render distinct shapes by default.
- Canvas resizing is handled internally — the orb fills its container and re-renders on layout changes.

---

# Response

> A streaming-friendly text response component for AI agent output.

```svelte
<script lang="ts">
	import { Response } from "$lib/registry/ui/response/index.js";

	const markdown = `### Welcome

This is a **rich markdown** showcase with multiple features.

---

## Data Table

| Name  | Role     | Status |
|-------|----------|--------|
| Alice | Engineer | Active |
| Bob   | Designer | Active |
| Carol | PM       | Active |

## Inspiration

> *Simplicity is the ultimate sophistication.*
> — Leonardo da Vinci

## Inline and Block Code

Use \`let total = items.length\` to count elements.

\`\`\`python
def greet(name):
    return f"Hello, {name}!"
print(greet("World"))
\`\`\`
`;

	let content = $state("");

	$effect(() => {
		let index = 0;
		const step = 3;
		const interval = setInterval(() => {
			if (index < markdown.length) {
				index = Math.min(index + step, markdown.length);
				content = markdown.slice(0, index);
			} else {
				clearInterval(interval);
			}
		}, 30);
		return () => clearInterval(interval);
	});
</script>

<div class="h-full min-h-0 w-full overflow-hidden">
	<Response {content} class="h-full overflow-auto p-10" />
</div>
```

## Installation

```bash
npx shadcn-svelte@latest add https://sv11.ui.twango.dev/r/response.json
```

## Usage

```svelte
<script lang="ts">
	import { Response } from "$lib/registry/ui/response";
</script>

<Response />
```

## Examples

### Basic Usage

Pass a string to the `content` prop. Any markdown is rendered to HTML on the fly.

```svelte
<script lang="ts">
	import { Response } from "$lib/registry/ui/response";
</script>

<Response content="This is a simple text response." />
```

### With Markdown

Full markdown is supported — headings, lists, tables, blockquotes, inline code, and fenced code blocks.

```svelte
<script lang="ts">
	import { Response } from "$lib/registry/ui/response";

	const content = `# Heading

This is a paragraph with **bold** and *italic* text.

- List item 1
- List item 2
- List item 3

\`\`\`javascript
const greeting = "Hello, world!";
console.log(greeting);
\`\`\`
`;
</script>

<Response {content} />
```

### Streaming Response

Drive `content` from `$state` and append tokens as they arrive. `Response` forwards `parseIncompleteMarkdown` to Streamdown so partial syntax renders cleanly.

```svelte
<script lang="ts">
	import { Response } from "$lib/registry/ui/response";

	let content = $state("");

	function handleToken(token: string) {
		content += token;
	}
</script>

<Response {content} />
```

### With Message Component

Compose inside a `Message` to render streaming assistant output next to an avatar.

```svelte
<script lang="ts">
	import * as Message from "$lib/registry/ui/message";
	import { Response } from "$lib/registry/ui/response";

	let { streamingResponse }: { streamingResponse: string } = $props();
</script>

<Message.Root from="assistant">
	<Message.Avatar src="/ai-avatar.jpg" name="AI" />
	<Message.Content>
		<Response content={streamingResponse} />
	</Message.Content>
</Message.Root>
```

## API Reference

| Prop | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `class?` | `string` | — | Extra classes merged onto the root `Streamdown` container. Top and bottom margins are stripped from the first and last children. |

## Notes

- Wraps [`svelte-streamdown`](https://github.com/technologiestiftung/svelte-streamdown) with the `shadcn` base theme and preregistered `code`, `mermaid`, and `math` block renderers.
- All Streamdown props pass through — including `content`, `parseIncompleteMarkdown`, `animation`, `theme`, `shikiTheme`, `allowedLinkPrefixes`, and others. See the upstream Streamdown docs for the full surface.
- Top and bottom margins are stripped from the first and last children so the component drops cleanly into any container.
- Optimized for character-by-character streaming — safe to mutate `content` on every token.
- Pairs naturally with the `Message` component for chat-style assistant output.

---

# Scrub Bar

> An audio timeline scrubber with progress, draggable thumb, and time labels.

```svelte
<script lang="ts">
	import * as ScrubBar from "$lib/registry/ui/scrub-bar/index.js";

	let value = $state(30);
	let isScrubbing = $state(false);
	const duration = 100;
</script>

<div class="flex w-full max-w-sm flex-col items-center gap-4 p-4">
	<ScrubBar.Root
		{duration}
		{value}
		onScrub={(t) => (value = t)}
		onScrubStart={() => (isScrubbing = true)}
		onScrubEnd={() => (isScrubbing = false)}
		class="w-full"
	>
		<ScrubBar.TimeLabel time={value} class="w-10 text-center" />
		<ScrubBar.Track class="mx-2">
			<ScrubBar.Progress />
			<ScrubBar.Thumb class="bg-primary" data-scrubbing={isScrubbing} />
		</ScrubBar.Track>
		<ScrubBar.TimeLabel time={duration} class="w-10 text-center" />
	</ScrubBar.Root>
</div>
```

## Installation

```bash
npx shadcn-svelte@latest add https://sv11.ui.twango.dev/r/scrub-bar.json
```

## Usage

```svelte
<script lang="ts">
	import { ScrubBar } from "$lib/registry/ui/scrub-bar";
</script>

<ScrubBar />
```

## Examples

### Basic Usage

Compose `Root`, `Track`, `Progress`, `Thumb`, and `TimeLabel` to build a standard scrub bar.

```svelte
<script lang="ts">
	import * as ScrubBar from "$lib/registry/ui/scrub-bar";

	let value = $state(30);
	const duration = 100;
</script>

<ScrubBar.Root {duration} {value} onScrub={(t) => (value = t)}>
	<ScrubBar.TimeLabel time={value} />
	<ScrubBar.Track class="mx-2">
		<ScrubBar.Progress />
		<ScrubBar.Thumb />
	</ScrubBar.Track>
	<ScrubBar.TimeLabel time={duration} />
</ScrubBar.Root>
```

### Scrub Start and End

Wire `onScrubStart` and `onScrubEnd` to pause playback while the user drags the thumb, then resume on release.

```svelte
<script lang="ts">
	import * as ScrubBar from "$lib/registry/ui/scrub-bar";

	let value = $state(30);
	let isScrubbing = $state(false);
	const duration = 100;
</script>

<ScrubBar.Root
	{duration}
	{value}
	onScrub={(t) => (value = t)}
	onScrubStart={() => (isScrubbing = true)}
	onScrubEnd={() => (isScrubbing = false)}
>
	<ScrubBar.TimeLabel time={value} />
	<ScrubBar.Track class="mx-2">
		<ScrubBar.Progress />
		<ScrubBar.Thumb data-scrubbing={isScrubbing} />
	</ScrubBar.Track>
	<ScrubBar.TimeLabel time={duration} />
</ScrubBar.Root>
```

### Custom Time Format

Pass a `format` function to `TimeLabel` to render time in your preferred format. The default is `m:ss`.

```svelte
<script lang="ts">
	import * as ScrubBar from "$lib/registry/ui/scrub-bar";

	function formatHMS(time: number) {
		const hours = Math.floor(time / 3600);
		const minutes = Math.floor((time % 3600) / 60);
		const seconds = Math.floor(time % 60);
		return `${hours}:${minutes.toString().padStart(2, "0")}:${seconds.toString().padStart(2, "0")}`;
	}

	let value = $state(125);
	const duration = 3720;
</script>

<ScrubBar.Root {duration} {value} onScrub={(t) => (value = t)}>
	<ScrubBar.TimeLabel time={value} format={formatHMS} />
	<ScrubBar.Track class="mx-2">
		<ScrubBar.Progress />
		<ScrubBar.Thumb />
	</ScrubBar.Track>
	<ScrubBar.TimeLabel time={duration} format={formatHMS} />
</ScrubBar.Root>
```

## API Reference

| Prop | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `duration` | `number` | — | Total duration of the timeline, in seconds. |
| `value` | `number` | — | Current playback time, in seconds. |
| `onScrub?` | `(time: number) => void` | — | Called with the new time (in seconds) as the user scrubs. |
| `onScrubStart?` | `() => void` | — | Called when the user presses down on the track or thumb. |
| `onScrubEnd?` | `() => void` | — | Called when the user releases the pointer after scrubbing. |
| `children?` | `Snippet` | — | — |

## Notes

- `ScrubBar.Root` publishes context via `setScrubBarContext`; sub-components (`Track`, `Progress`, `Thumb`) must be rendered inside it or they will throw.
- `Track` handles pointer events directly on `window` once a drag starts, so dragging outside the track still updates the value until pointer-up.
- Scrubbing is driven by pointer coordinates clamped to the track's bounding rect, so the resulting time is always within `[0, duration]`.
- `Progress` wraps the shared `Progress` primitive and forwards its props, except `value` — which is supplied by context.
- `Thumb` positions itself with an inline `left: <progress>%` style; restyle via `class` rather than overriding `left` directly.
- `TimeLabel` uses `tabular-nums` so digits do not shift as the current time updates.

---

# Shimmering Text

> An animated shimmering text effect, ideal for loading and "thinking" states.

```svelte
<script lang="ts">
	import { ShimmeringText } from "$lib/registry/ui/shimmering-text/index.js";
	import { fly } from "svelte/transition";

	const phrases = [
		"Agent is thinking...",
		"Processing your request...",
		"Analyzing the data...",
		"Generating response...",
		"Almost there...",
	];

	let currentIndex = $state(0);

	$effect(() => {
		const interval = setInterval(() => {
			currentIndex = (currentIndex + 1) % phrases.length;
		}, 3000);
		return () => clearInterval(interval);
	});
</script>

<div class="bg-card w-full rounded-lg border p-6">
	<div class="mb-4">
		<h3 class="text-lg font-semibold">Text Shimmer Effect</h3>
		<p class="text-muted-foreground text-sm">Animated gradient text with automatic cycling</p>
	</div>

	<div class="space-y-4">
		<div class="bg-muted/10 relative flex items-center justify-center rounded-lg py-8">
			{#key currentIndex}
				<div
					class="absolute"
					in:fly={{ y: 10, duration: 300, delay: 300 }}
					out:fly={{ y: -10, duration: 300 }}
				>
					<ShimmeringText text={phrases[currentIndex]} />
				</div>
			{/key}
		</div>
	</div>
</div>
```

## Installation

```bash
npx shadcn-svelte@latest add https://sv11.ui.twango.dev/r/shimmering-text.json
```

## Usage

```svelte
<script lang="ts">
	import { ShimmeringText } from "$lib/registry/ui/shimmering-text";
</script>

<ShimmeringText />
```

## Examples

### Basic Usage

Pass any string to `text` and the shimmer begins as soon as the element enters the viewport.

```svelte
<script lang="ts">
	import { ShimmeringText } from "$lib/registry/ui/shimmering-text";
</script>

<ShimmeringText text="Hello, World!" />
```

### Custom Duration and Colors

Slow the sweep down with `duration` and override the gradient with `color` (base) and `shimmerColor` (highlight).

```svelte
<ShimmeringText text="Custom Shimmer" duration={3} color="#6B7280" shimmerColor="#3B82F6" />
```

### Trigger on Viewport Entry

Set `once` to `true` so the animation fires a single time when the element scrolls into view.

```svelte
<ShimmeringText text="Appears when scrolled into view" startOnView once />
```

### Repeating Animation

Control the repeat loop with `repeat` and `repeatDelay`.

```svelte
<ShimmeringText text="Repeating Shimmer" repeat repeatDelay={1} duration={2} />
```

### With Custom Styling

Merge Tailwind utilities through `class` and widen the highlight with `spread`.

```svelte
<ShimmeringText text="Large Heading" class="text-4xl font-bold" spread={3} />
```

## API Reference

| Prop | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `text` | `string` | — | Text to display with the shimmer effect. |
| `duration?` | `number` | `2` | Duration of one shimmer sweep in seconds. |
| `delay?` | `number` | `0` | Seconds to wait before the first sweep begins. |
| `repeat?` | `boolean` | `true` | Whether the shimmer sweep loops indefinitely. |
| `repeatDelay?` | `number` | `0.5` | Pause between repeats in seconds when `repeat` is `true`. |
| `class?` | `string` | — | Extra classes merged onto the root `<span>`. |
| `startOnView?` | `boolean` | `true` | When `true`, the animation only starts once the element scrolls into view. When `false`, it begins on mount. |
| `once?` | `boolean` | `false` | When `true`, the animation fires a single time and never again. When `false`, it replays each time the element re-enters the viewport. |
| `inViewMargin?` | `NonNullable<Parameters<typeof inView>[2]>["margin"]` | — | Root margin passed to the underlying Motion `inView` observer — used to shrink or expand the viewport trigger area (e.g. `"0px 0px -10%"`). |
| `spread?` | `number` | `2` | Spread multiplier applied to the shimmer highlight width. The final spread scales with text length (`text.length * spread` pixels). |
| `color?` | `string` | — | Base text color. Defaults to `var(--muted-foreground)`. |
| `shimmerColor?` | `string` | — | Highlight gradient color. Defaults to `var(--foreground)`. |

## Notes

- Built on [Motion](https://motion.dev/) — uses `animate` for the sweep and `inView` for viewport detection.
- The shimmer is a CSS gradient painted over the text via `background-clip: text`, so it inherits font weight, kerning, and line-height from surrounding styles.
- Spread scales with text length (`text.length * spread` pixels) so short and long strings read consistently.
- `color` and `shimmerColor` set the `--base-color` and `--shimmer-color` custom properties; leaving them unset falls back to `var(--muted-foreground)` and `var(--foreground)`, which already track light/dark mode.
- When `startOnView` is `true` and `once` is `false`, the animation resumes each time the element re-enters the viewport.
- The element is rendered as an inline `<span>`, so it composes with surrounding text nodes.

---

# Speech Input

> A compact speech-to-text input component with a provider-agnostic transcription adapter. Ships with a Web Speech API adapter for demos; users supply their own for ElevenLabs Scribe, Deepgram, or other providers.

```svelte
<script lang="ts">
	import InfoIcon from "@lucide/svelte/icons/info";
	import {
		SpeechInput,
		SpeechInputRecordButton,
		SpeechInputPreview,
		SpeechInputCancelButton,
		type TranscriptionAdapter,
	} from "$lib/registry/ui/speech-input/index.js";
	import { Textarea } from "$lib/registry/ui/textarea/index.js";

	let value = $state("");
	let toastMessage = $state<string | null>(null);
	let toastTimer: ReturnType<typeof setTimeout> | null = null;

	function showToast(message: string) {
		if (toastTimer !== null) clearTimeout(toastTimer);
		toastMessage = message;
		toastTimer = setTimeout(() => {
			toastMessage = null;
			toastTimer = null;
		}, 3500);
	}

	// Stub adapter for the demo: throws so the SpeechInput surfaces an error
	// via the component's onError callback. The textarea + buttons render
	// exactly as they would with a real adapter — only the recognition step
	// is replaced with the toast.
	const demoAdapter: TranscriptionAdapter = {
		async start() {
			throw new Error("This is a demo — no speech-to-text backend is wired up.");
		},
		stop() {},
		cancel() {},
	};
</script>

<div class="flex w-full flex-col gap-3">
	<div class="relative">
		<Textarea
			bind:value
			placeholder="Jot down some thoughts..."
			class="min-h-[120px] resize-none rounded-2xl px-3.5 pt-3 pb-14"
		/>
		<div class="absolute right-3 bottom-3 flex items-center gap-2">
			<SpeechInput size="sm" adapter={demoAdapter} onError={(err) => showToast(err.message)}>
				<SpeechInputCancelButton />
				<SpeechInputPreview placeholder="Listening..." />
				<SpeechInputRecordButton />
			</SpeechInput>
		</div>

		{#if toastMessage}
			<div
				class="bg-foreground text-background animate-in fade-in slide-in-from-bottom-2 pointer-events-none absolute -top-2 right-0 -translate-y-full rounded-md px-3 py-2 text-xs shadow-lg duration-200"
				role="status"
			>
				{toastMessage}
			</div>
		{/if}
	</div>

	<div
		class="border-border bg-muted/40 text-muted-foreground flex items-start gap-3 rounded-md border p-3 text-xs"
		role="note"
	>
		<InfoIcon class="text-foreground mt-0.5 size-3.5 shrink-0" />
		<p>
			<code class="bg-muted rounded px-1 py-0.5">SpeechInput</code> is provider-agnostic — pass a
			<code class="bg-muted rounded px-1 py-0.5">TranscriptionAdapter</code> wired to ElevenLabs, Deepgram,
			OpenAI, or any other backend. This demo has no STT hooked up.
		</p>
	</div>
</div>
```

## Installation

```bash
npx shadcn-svelte@latest add https://sv11.ui.twango.dev/r/speech-input.json
```

## Usage

```svelte
<script lang="ts">
	import { SpeechInput } from "$lib/registry/ui/speech-input";
</script>

<SpeechInput />
```

`<SpeechInput>` requires an `adapter` prop — see [Providers](/docs/providers#transcriptionadapter) for the interface and [Adapters](/docs/adapters) for provider recipes.

## Examples

### Basic Usage

Compose `SpeechInput` with the record button, preview, and cancel button. Pass any object that matches `TranscriptionAdapter`.

```svelte
<script lang="ts">
	import * as SpeechInput from "$lib/registry/ui/speech-input";
	import type { TranscriptionAdapter } from "$lib/registry/ui/speech-input";

	const adapter: TranscriptionAdapter = createMyAdapter(/* ... */);
</script>

<SpeechInput.Root
	{adapter}
	onChange={(data) => console.log(data.transcript)}
	onStop={(data) => console.log("Final:", data.transcript)}
>
	<SpeechInput.RecordButton />
	<SpeechInput.Preview placeholder="Start speaking..." />
	<SpeechInput.CancelButton />
</SpeechInput.Root>
```

### With Form Input

Use `onStop` to append the committed transcript onto an external text field.

```svelte
<script lang="ts">
	import * as SpeechInput from "$lib/registry/ui/speech-input";
	import type { TranscriptionAdapter } from "$lib/registry/ui/speech-input";

	const adapter: TranscriptionAdapter = createMyAdapter(/* ... */);
	let value = $state("");
</script>

<div class="flex items-center gap-2">
	<input bind:value class="flex-1 rounded border px-3 py-2" />
	<SpeechInput.Root {adapter} onStop={(data) => (value = `${value} ${data.transcript}`.trim())}>
		<SpeechInput.RecordButton />
		<SpeechInput.Preview />
		<SpeechInput.CancelButton />
	</SpeechInput.Root>
</div>
```

### Reversed Layout

Child order is the layout order — put the cancel button first if you want it to lead.

```svelte
<SpeechInput.Root {adapter}>
	<SpeechInput.CancelButton />
	<SpeechInput.Preview />
	<SpeechInput.RecordButton />
</SpeechInput.Root>
```

### Minimal (Record Button Only)

Drop the preview and cancel slots for an icon-only recorder; the transcript is still delivered via `onStop`.

```svelte
<SpeechInput.Root {adapter} onStop={(data) => console.log(data.transcript)}>
	<SpeechInput.RecordButton />
</SpeechInput.Root>
```

### Custom Placeholder

`SpeechInputPreview` shows its `placeholder` text until the first partial transcript arrives.

```svelte
<SpeechInput.Root {adapter}>
	<SpeechInput.RecordButton />
	<SpeechInput.Preview placeholder="Say something..." />
	<SpeechInput.CancelButton />
</SpeechInput.Root>
```

### Using the Hook

`useSpeechInput()` reads the context set up by `SpeechInput.Root`, so child components can render their own UI against the shared state.

```svelte
<script lang="ts">
	import { useSpeechInput } from "$lib/registry/ui/speech-input";

	const state = useSpeechInput();
</script>

<p>
	Status: {state.error
		? `Error: ${state.error}`
		: state.isConnecting
			? "Connecting"
			: state.isConnected
				? "Recording"
				: "Idle"}
</p>
<p>Transcript: {state.transcript}</p>
```

## API Reference

| Prop | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `adapter` | `TranscriptionAdapter` | — | STT backend bridge that owns the transcription session. Conforms to [`TranscriptionAdapter`](/docs/providers#transcriptionadapter). |
| `size?` | `ButtonSize` | `"default"` | Shared size applied to `SpeechInputRecordButton` and `SpeechInputCancelButton` via context. |
| `onStart?` | `(data: SpeechInputData) => void` | — | Fired once the adapter reports the connection is ready for audio. |
| `onStop?` | `(data: SpeechInputData) => void` | — | Fired when the user stops recording. Receives a snapshot of the transcript — any in-flight partial is preserved. |
| `onCancel?` | `(data: SpeechInputData) => void` | — | Fired when the user cancels recording. Receives the snapshot taken before partial + committed state is cleared. |
| `onChange?` | `(data: SpeechInputData) => void` | — | Fired on every partial or committed transcript update. |
| `onError?` | `(error: Error) => void` | — | Fired when the adapter surfaces an error or `start()` rejects. |
| `children?` | `Snippet` | — | Compound children — typically `SpeechInputRecordButton`, `SpeechInputPreview`, and `SpeechInputCancelButton` in any order. |
| `ref?` | `HTMLDivElement \| null` | `$bindable(null)` | Bindable ref to the root `<div>` element. |

## Notes

- The component is a compound primitive — `SpeechInput.Root` wires context and the adapter; `SpeechInputRecordButton`, `SpeechInputPreview`, and `SpeechInputCancelButton` read that context. Sub-components must be rendered inside a root or their `useSpeechInput()` call will throw.
- The adapter reference is stored as a plain private field (not reactive) — swapping adapters mid-recording is unsupported and takes effect on the next `start()`.
- An internal request-id invalidates late callbacks, so a `stop()` or `cancel()` during connection reliably wins even if the adapter's `onConnect` fires after.
- `stop()` preserves the in-flight partial transcript and forwards it to `onStop`; `cancel()` clears partial + committed state before firing `onCancel`. Choose based on whether the user is committing or discarding the utterance.
- Teardown uses `onDestroy` rather than `$effect` cleanup so dev-mode HMR and parent re-renders do not cancel an active recording.
- The record button is disabled while `state.isConnecting`; the cancel button is inert unless `state.isConnected`.

---

# Transcript Viewer

> Synchronized transcript with audio playback. Highlights each word as it's spoken, supports seeking via scrub bar, and exposes a compound-component API with provider-agnostic character-alignment data.

```svelte
<script lang="ts" module>
	import type { CharacterAlignment } from "$lib/registry/ui/transcript-viewer/index.js";

	// Hoisted to module scope so the prop reference is stable across renders
	// while alignment is loading — otherwise the root's segment-recompute
	// effect would re-run every time the demo component updates.
	const EMPTY_ALIGNMENT: CharacterAlignment = {
		characters: [],
		characterStartTimesSeconds: [],
		characterEndTimesSeconds: [],
	};
</script>

<script lang="ts">
	import { onMount } from "svelte";
	import PlayIcon from "@lucide/svelte/icons/play";
	import PauseIcon from "@lucide/svelte/icons/pause";
	import {
		TranscriptViewer,
		TranscriptViewerAudio,
		TranscriptViewerWords,
		TranscriptViewerPlayPauseButton,
		TranscriptViewerScrubBar,
	} from "$lib/registry/ui/transcript-viewer/index.js";
	import { Skeleton } from "$lib/registry/ui/skeleton/index.js";

	const audioSrc = "https://sv11.ui.twango.dev/audio/transcript-viewer.wav";
	let alignment = $state<CharacterAlignment | undefined>(undefined);

	onMount(() => {
		fetch("https://sv11.ui.twango.dev/audio/transcript-viewer-alignment.json")
			.then((res) => (res.ok ? res.json() : Promise.reject(new Error(res.statusText))))
			.then((data: CharacterAlignment) => {
				alignment = data;
			})
			.catch((err) => {
				console.error("Failed to load transcript alignment:", err);
			});
	});
</script>

<div class="flex w-full flex-col gap-4">
	<TranscriptViewer
		class="bg-card w-full rounded-xl border p-4"
		{audioSrc}
		audioType="audio/wav"
		alignment={alignment ?? EMPTY_ALIGNMENT}
	>
		<TranscriptViewerAudio class="sr-only" />
		{#if alignment}
			<TranscriptViewerWords />
			<div class="flex items-center gap-3">
				<TranscriptViewerScrubBar />
			</div>
		{:else}
			<div class="flex w-full flex-col gap-3">
				<Skeleton class="h-5 w-full" />
				<Skeleton class="mb-4 h-5 w-1/2" />
				<Skeleton class="h-2 w-full" />
				<div class="-mt-1 flex items-center justify-between">
					<Skeleton class="h-2 w-6" />
					<Skeleton class="h-2 w-6" />
				</div>
			</div>
		{/if}
		<TranscriptViewerPlayPauseButton
			class="w-full cursor-pointer"
			size="default"
			disabled={!alignment}
		>
			{#snippet children({ isPlaying })}
				{#if isPlaying}
					<PauseIcon class="size-4" /> Pause
				{:else}
					<PlayIcon class="size-4" /> Play
				{/if}
			{/snippet}
		</TranscriptViewerPlayPauseButton>
	</TranscriptViewer>
</div>
```

## Installation

```bash
npx shadcn-svelte@latest add https://sv11.ui.twango.dev/r/transcript-viewer.json
```

## Usage

```svelte
<script lang="ts">
	import { TranscriptViewer } from "$lib/registry/ui/transcript-viewer";
</script>

<TranscriptViewer />
```

```svelte
<script lang="ts">
	import * as TranscriptViewer from "$lib/registry/ui/transcript-viewer";
	import type { CharacterAlignment } from "$lib/registry/ui/transcript-viewer";

	let {
		audioSrc,
		alignment,
	}: {
		audioSrc: string;
		alignment: CharacterAlignment;
	} = $props();
</script>

<TranscriptViewer.Root {audioSrc} {alignment}>
	<TranscriptViewer.Audio />
	<TranscriptViewer.Words />
	<div class="flex items-center gap-3">
		<TranscriptViewer.PlayPauseButton />
		<TranscriptViewer.ScrubBar />
	</div>
</TranscriptViewer.Root>
```

## Examples

### Custom Audio Type

Pass `audioType` when the source is not MP3 so the browser picks the right decoder.

```svelte
<TranscriptViewer.Root {audioSrc} {alignment} audioType="audio/wav">
	<TranscriptViewer.Audio />
	<TranscriptViewer.Words />
	<TranscriptViewer.ScrubBar />
</TranscriptViewer.Root>
```

### Custom Word and Gap Rendering

`TranscriptViewerWords` accepts `renderWord` and `renderGap` snippets for per-segment overrides. Each receives the segment and its `status` — `"spoken"`, `"current"`, or `"unspoken"`.

```svelte
<script lang="ts">
	import * as TranscriptViewer from "$lib/registry/ui/transcript-viewer";
	import type { CharacterAlignment } from "$lib/registry/ui/transcript-viewer";

	let {
		audioSrc,
		alignment,
	}: {
		audioSrc: string;
		alignment: CharacterAlignment;
	} = $props();
</script>

<TranscriptViewer.Root {audioSrc} {alignment}>
	<TranscriptViewer.Audio />
	<TranscriptViewer.Words>
		{#snippet renderWord({ word, status })}
			<span
				class:font-semibold={status === "current"}
				class:text-primary={status === "spoken"}
				class:text-muted-foreground={status === "unspoken"}
			>
				{word.text}
			</span>
		{/snippet}
	</TranscriptViewer.Words>
	<TranscriptViewer.ScrubBar />
</TranscriptViewer.Root>
```

### Playback Callbacks

The root forwards the underlying `<audio>` lifecycle via `onPlay`, `onPause`, `onTimeUpdate`, `onEnded`, and `onDurationChange` — useful for analytics or syncing external state.

```svelte
<script lang="ts">
	import * as TranscriptViewer from "$lib/registry/ui/transcript-viewer";
	import type { CharacterAlignment } from "$lib/registry/ui/transcript-viewer";

	let {
		audioSrc,
		alignment,
	}: {
		audioSrc: string;
		alignment: CharacterAlignment;
	} = $props();

	let currentTime = $state(0);
</script>

<TranscriptViewer.Root
	{audioSrc}
	{alignment}
	onPlay={() => console.log("Playing")}
	onPause={() => console.log("Paused")}
	onTimeUpdate={(t) => (currentTime = t)}
	onEnded={() => console.log("Ended")}
>
	<TranscriptViewer.Audio />
	<TranscriptViewer.Words />
	<TranscriptViewer.ScrubBar />
</TranscriptViewer.Root>
```

### Custom Play/Pause Button

`TranscriptViewerPlayPauseButton` accepts a children snippet that receives `{ isPlaying }`, so you can render your own label and icons while keeping the shared click behavior.

```svelte
<script lang="ts">
	import PauseIcon from "@lucide/svelte/icons/pause";
	import PlayIcon from "@lucide/svelte/icons/play";
	import * as TranscriptViewer from "$lib/registry/ui/transcript-viewer";
	import type { CharacterAlignment } from "$lib/registry/ui/transcript-viewer";

	let {
		audioSrc,
		alignment,
	}: {
		audioSrc: string;
		alignment: CharacterAlignment;
	} = $props();
</script>

<TranscriptViewer.Root {audioSrc} {alignment}>
	<TranscriptViewer.Audio />
	<TranscriptViewer.Words />
	<TranscriptViewer.PlayPauseButton>
		{#snippet children({ isPlaying })}
			{#if isPlaying}
				<PauseIcon class="size-4" /> Pause
			{:else}
				<PlayIcon class="size-4" /> Play
			{/if}
		{/snippet}
	</TranscriptViewer.PlayPauseButton>
</TranscriptViewer.Root>
```

### Accessing Viewer State

`useTranscriptViewer()` returns the shared reactive state inside any descendant — useful for custom transport UI that needs to observe `currentWord`, `currentTime`, `isPlaying`, or jump to a specific word via `seekToWord`.

```svelte
<script lang="ts">
	import { useTranscriptViewer } from "$lib/registry/ui/transcript-viewer";

	const state = useTranscriptViewer();
</script>

<div>
	Current word: {state.currentWord?.text ?? "—"}
	<button onclick={() => state.seekToWord(0)}>Restart transcript</button>
</div>
```

## API Reference

### `TranscriptViewer` (root)

| Prop | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `audioSrc` | `string` | — | URL of the audio file that backs the transcript. |
| `audioType?` | `AudioType` | `"audio/mpeg"` | MIME type emitted on the inner `<source>` element. Set this when serving non-MP3 audio so the browser picks the right decoder. |
| `alignment` | `CharacterAlignment` | — | Character-level alignment used to compute word boundaries and drive highlighting. Shape matches ElevenLabs' `CharacterAlignmentResponseModel`; reshape other providers' output to the same structure. |
| `segmentComposer?` | `SegmentComposer` | — | Override the default word/gap segmentation. Receives the raw alignment and returns the composed `segments` and `words` arrays. |
| `hideAudioTags?` | `boolean` | `true` | When `true`, ElevenLabs-style tags like `[excited]` are stripped from the rendered transcript. |
| `onPlay?` | `() => void` | — | Called when the audio starts playing. |
| `onPause?` | `() => void` | — | Called when the audio is paused. |
| `onTimeUpdate?` | `(time: number) => void` | — | Called with the current playback time (in seconds) on every audio `timeupdate`. |
| `onEnded?` | `() => void` | — | Called when playback reaches the end of the track. |
| `onDurationChange?` | `(duration: number) => void` | — | Called with the total duration (in seconds) once metadata is available. |
| `children?` | `Snippet` | — | Sub-components composed inside the root (e.g. `<TranscriptViewerAudio />`, `<TranscriptViewerWords />`, `<TranscriptViewerScrubBar />`). |
| `ref?` | `HTMLDivElement \| null` | `$bindable(null)` | Bind to the underlying wrapper `<div>` element. |

Each row below also accepts the standard `HTMLAttributes` for its host element (e.g. `class`, `style`, `data-*`, event handlers) unless otherwise noted.

### `TranscriptViewerAudio`

Renders the underlying `<audio>` element driven by the root's state. Extends `Omit<HTMLAudioAttributes, "src" | "children">` — `src` comes from the root's `audioSrc`.

| Prop   | Type                       | Default | Description                                             |
| ------ | -------------------------- | ------- | ------------------------------------------------------- |
| `ref?` | `HTMLAudioElement \| null` | `null`  | Bindable reference to the underlying `<audio>` element. |

### `TranscriptViewerWords`

Renders the word/gap segments. Extends `HTMLAttributes<HTMLDivElement>`.

| Prop              | Type                                                                      | Default | Description                                                                 |
| ----------------- | ------------------------------------------------------------------------- | ------- | --------------------------------------------------------------------------- |
| `renderWord?`     | `Snippet<[{ word: TranscriptWord; status: TranscriptViewerWordStatus }]>` | —       | Custom snippet for a single word. Receives the word and its current status. |
| `renderGap?`      | `Snippet<[{ segment: GapSegment; status: TranscriptViewerWordStatus }]>`  | —       | Custom snippet for inter-word gaps.                                         |
| `wordClassNames?` | `string`                                                                  | —       | Extra classes applied to each word span.                                    |
| `gapClassNames?`  | `string`                                                                  | —       | Extra classes applied to each gap span.                                     |

### `TranscriptViewerWord`

The span rendered per word when no custom `renderWord` is supplied. Extends `Omit<HTMLAttributes<HTMLSpanElement>, "children">`.

| Prop        | Type                         | Default | Description                                   |
| ----------- | ---------------------------- | ------- | --------------------------------------------- |
| `word`      | `TranscriptWord`             | —       | The word segment to render.                   |
| `status`    | `TranscriptViewerWordStatus` | —       | One of `"spoken"`, `"current"`, `"unspoken"`. |
| `children?` | `Snippet`                    | —       | Override the default text with custom markup. |

### `TranscriptViewerPlayPauseButton`

Play/pause toggle wired to the root's `isPlaying` state. Extends `Omit<ButtonProps, "children">`, so it inherits `variant`, `size`, etc. from the button primitive.

| Prop        | Type                                | Default | Description                                                               |
| ----------- | ----------------------------------- | ------- | ------------------------------------------------------------------------- |
| `children?` | `Snippet<[{ isPlaying: boolean }]>` | —       | Override the default play/pause icon. Receives the live `isPlaying` flag. |

### `TranscriptViewerScrubBar`

Time-aware scrub bar composed over the standalone `ScrubBar` primitive. Extends `Omit<HTMLAttributes<HTMLDivElement>, "children">`.

| Prop                 | Type      | Default | Description                                       |
| -------------------- | --------- | ------- | ------------------------------------------------- |
| `showTimeLabels?`    | `boolean` | `true`  | Render the leading/trailing time labels.          |
| `labelsClassName?`   | `string`  | —       | Classes forwarded to the time-label row.          |
| `trackClassName?`    | `string`  | —       | Classes forwarded to the inner `ScrubBarTrack`.   |
| `progressClassName?` | `string`  | —       | Classes forwarded to the `ScrubBarProgress` fill. |
| `thumbClassName?`    | `string`  | —       | Classes forwarded to the `ScrubBarThumb`.         |

## Notes

- `alignment` shape mirrors ElevenLabs' `CharacterAlignmentResponseModel` — three parallel arrays (`characters`, `characterStartTimesSeconds`, `characterEndTimesSeconds`) indexed per character. Reshape data from other providers (OpenAI, Deepgram, custom) to the same structure.
- The root composes character alignment into word and gap segments internally via `composeSegments`, or a custom `segmentComposer` when provided. Recomposition runs whenever `alignment` changes.
- When `hideAudioTags` is `true` (default), anything inside `[...]` brackets — e.g. ElevenLabs' `[excited]` style tags — is stripped from the rendered transcript.
- The audio element is owned by `TranscriptViewerAudio`. The root wires up `play`, `pause`, `timeupdate`, `seeked`, `durationchange`, and `loadedmetadata` listeners plus a `requestAnimationFrame` loop to drive `currentTime` and the active word index.
- The active-word walk is incremental: normal playback advances via a forward scan, and seeks fall back to a binary search over the word list.
- `TranscriptViewerScrubBar` composes the standalone `ScrubBar` primitive with time labels and suspends `timeupdate`-driven UI updates while the user is scrubbing so the thumb doesn't fight the pointer.
- Words take one of three statuses — `"spoken"`, `"current"`, `"unspoken"` — which you can target via the built-in Tailwind classes on `TranscriptViewerWord` or render yourself through `renderWord` / `renderGap` snippets.

---

# Voice Button

> Stateful button with integrated live waveform feedback for voice recording, success/error states, and keyboard shortcut slots.

```svelte
<script lang="ts">
	import { VoiceButton, type VoiceButtonState } from "$lib/registry/ui/voice-button/index.js";

	let state = $state<VoiceButtonState>("idle");

	function handlePress() {
		if (state === "idle") {
			state = "recording";
		} else if (state === "recording") {
			state = "processing";
			setTimeout(() => {
				state = "success";
				setTimeout(() => {
					state = "idle";
				}, 1500);
			}, 1000);
		}
	}

	$effect(() => {
		function onKeyDown(e: KeyboardEvent) {
			if (e.altKey && e.code === "Space") {
				e.preventDefault();
				handlePress();
			}
		}
		window.addEventListener("keydown", onKeyDown);
		return () => window.removeEventListener("keydown", onKeyDown);
	});
</script>

<VoiceButton label="Voice" trailing="⌥Space" {state} onPress={handlePress} class="min-w-[180px]" />
```

## Installation

```bash
npx shadcn-svelte@latest add https://sv11.ui.twango.dev/r/voice-button.json
```

## Usage

```svelte
<script lang="ts">
	import { VoiceButton } from "$lib/registry/ui/voice-button";
</script>

<VoiceButton />
```

## Examples

### Basic Usage

Drive the button through its lifecycle by passing a reactive `state`.

```svelte
<script lang="ts">
	import { VoiceButton, type VoiceButtonState } from "$lib/registry/ui/voice-button";

	let state = $state<VoiceButtonState>("idle");

	function handlePress() {
		if (state === "idle") {
			state = "recording";
		} else {
			state = "processing";
		}
	}
</script>

<VoiceButton {state} onPress={handlePress} />
```

### With Label and Keyboard Shortcut

Use `label` for leading text and `trailing` to surface a keyboard shortcut. The trailing slot is hidden while the waveform is active.

```svelte
<VoiceButton
	state="idle"
	label="Press to speak"
	trailing="⌥Space"
	onPress={() => console.log("Button pressed")}
/>
```

### Different States

Each state renders a distinct visual: the waveform activates on `recording`, continues through `processing`, and a check or X flashes for `success` and `error` before returning to idle visuals.

```svelte
<script lang="ts">
	import { VoiceButton } from "$lib/registry/ui/voice-button";
</script>

<VoiceButton state="idle" />
<VoiceButton state="recording" />
<VoiceButton state="processing" />
<VoiceButton state="success" />
<VoiceButton state="error" />
```

### Icon Button

Set `size="icon"` and pass an `icon` snippet for compact, icon-only layouts.

```svelte
<script lang="ts">
	import MicIcon from "@lucide/svelte/icons/mic";
	import { VoiceButton } from "$lib/registry/ui/voice-button";
</script>

<VoiceButton state="idle" size="icon">
	{#snippet icon()}
		<MicIcon />
	{/snippet}
</VoiceButton>
```

### Custom Styling

Merge extra classes onto the button with `class`, and onto the inner waveform container with `waveformClassName`.

```svelte
<VoiceButton
	state="recording"
	variant="default"
	size="lg"
	class="w-full"
	waveformClassName="bg-primary/10"
/>
```

### Auto-transitioning States

Chain state transitions from `onPress` to model a full record → process → success flow.

```svelte
<script lang="ts">
	import { VoiceButton, type VoiceButtonState } from "$lib/registry/ui/voice-button";

	let state = $state<VoiceButtonState>("idle");

	function handlePress() {
		if (state === "idle") {
			state = "recording";
		} else if (state === "recording") {
			state = "processing";
			setTimeout(() => {
				state = "success";
			}, 2000);
		}
	}
</script>

<VoiceButton {state} onPress={handlePress} />
```

## API Reference

| Prop | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `state?` | `VoiceButtonState` | `"idle"` | Current state of the voice button. Drives the internal waveform, success/error feedback, and disabled behavior. |
| `onPress?` | `() => void` | — | Called when the button is clicked, after any native `onclick` handler. |
| `onclick?` | `(e: MouseEvent) => void` | — | Native click handler invoked before `onPress`. |
| `label?` | `string \| Snippet` | — | Leading content rendered on non-icon sizes. Accepts a string or a snippet. |
| `trailing?` | `string \| Snippet` | — | Trailing content rendered on the right (e.g. a keyboard shortcut). Hidden while the waveform is active. Accepts a string or a snippet. |
| `icon?` | `Snippet` | — | Icon snippet rendered when `size="icon"` and no waveform is active. |
| `waveformClassName?` | `string` | — | Extra classes forwarded to the waveform container. |
| `feedbackDuration?` | `number` | `1500` | Milliseconds to display the success/error state before returning to idle visuals. |

## Notes

- Built on top of the shadcn-svelte `Button` primitive, so every button `variant` and `size` — including `"icon"` — works as expected.
- The integrated [`LiveWaveform`](/docs/components/live-waveform) samples the active microphone stream directly while `state` is `"recording"` or `"processing"`.
- `success` and `error` auto-clear after `feedbackDuration` (default `1500`ms); drive `state` back to `"idle"` from your side on the same cadence if you want the button fully reset.
- While `state="processing"`, the button is rendered disabled regardless of the `disabled` prop.
- `onPress` fires after any `onclick` handler you pass — both are invoked.

---

# Voice Picker

> A searchable voice selector with audio preview and Orb visualization. Provider-agnostic — pass any voices matching the Voice interface from ElevenLabs, OpenAI, Cartesia, or a custom backend.

```svelte
<script lang="ts">
	import { VoicePicker, type Voice } from "$lib/registry/ui/voice-picker/index.js";

	const voices: Voice[] = [
		{
			id: "alpha",
			name: "Alpha",
			previewUrl: "https://sv11.ui.twango.dev/audio/alpha.mp3",
			labels: { accent: "american", gender: "male", age: "middle_aged" },
		},
		{
			id: "bravo",
			name: "Bravo",
			previewUrl: "https://sv11.ui.twango.dev/audio/bravo.mp3",
			labels: { accent: "british", gender: "female", age: "young" },
		},
		{
			id: "charlie",
			name: "Charlie",
			previewUrl: "https://sv11.ui.twango.dev/audio/charlie.mp3",
			labels: { accent: "australian", gender: "male", age: "old" },
		},
	];

	let selectedVoice = $state<string>("alpha");
	let open = $state(false);
</script>

<div class="w-full max-w-lg">
	<VoicePicker
		{voices}
		value={selectedVoice}
		onValueChange={(v) => {
			selectedVoice = v;
			open = true;
		}}
		{open}
		onOpenChange={(o) => (open = o)}
		placeholder="Select a voice..."
	/>
</div>
```

## Installation

```bash
npx shadcn-svelte@latest add https://sv11.ui.twango.dev/r/voice-picker.json
```

## Usage

```svelte
<script lang="ts">
	import { VoicePicker } from "$lib/registry/ui/voice-picker";
</script>

<VoicePicker />
```

## Examples

### Basic Usage

Pass an array of `Voice` objects and bind `value`/`onValueChange` to track the selected voice ID.

```svelte
<script lang="ts">
	import { VoicePicker, type Voice } from "$lib/registry/ui/voice-picker";

	const voices: Voice[] = [
		{
			id: "21m00Tcm4TlvDq8ikWAM",
			name: "Rachel",
			previewUrl: "https://example.com/rachel-preview.mp3",
			labels: { accent: "american", gender: "female", age: "young" },
		},
	];

	let selectedVoice = $state("");
</script>

<VoicePicker {voices} value={selectedVoice} onValueChange={(v) => (selectedVoice = v)} />
```

### Controlled vs Uncontrolled

Pass both `value` and `onValueChange` for a fully controlled picker, or just `onValueChange` to observe selections without owning the state.

```svelte
<script lang="ts">
	import { VoicePicker, type Voice } from "$lib/registry/ui/voice-picker";

	let { voices }: { voices: Voice[] } = $props();
	let selectedVoice = $state("");
</script>

<!-- Controlled -->
<VoicePicker {voices} value={selectedVoice} onValueChange={(v) => (selectedVoice = v)} />

<!-- Uncontrolled -->
<VoicePicker {voices} onValueChange={(voiceId) => console.log("Selected:", voiceId)} />
```

### Control Open State

Pair `open` with `onOpenChange` to drive the popover externally — useful if you want to open the picker from another control.

```svelte
<script lang="ts">
	import { VoicePicker, type Voice } from "$lib/registry/ui/voice-picker";

	let { voices }: { voices: Voice[] } = $props();
	let open = $state(false);
	let selectedVoice = $state("");
</script>

<VoicePicker
	{voices}
	{open}
	onOpenChange={(o) => (open = o)}
	value={selectedVoice}
	onValueChange={(v) => (selectedVoice = v)}
/>
```

### Custom Placeholder

Override the trigger text shown before the user selects a voice.

```svelte
<VoicePicker
	{voices}
	placeholder="Choose your voice..."
	value={selectedVoice}
	onValueChange={(v) => (selectedVoice = v)}
/>
```

### Loading Voices from a Provider

Map any provider's voice shape into the `Voice` interface once, then hand the array to `VoicePicker`. Below is a sketch for ElevenLabs — the same pattern applies to OpenAI, Cartesia, or a custom backend.

```svelte
<script lang="ts">
	import { onMount } from "svelte";
	import { VoicePicker, type Voice } from "$lib/registry/ui/voice-picker";

	let voices = $state<Voice[]>([]);
	let selectedVoice = $state("");

	onMount(async () => {
		const res = await fetch("/api/voices");
		const data = await res.json();
		voices = data.voices.map((v: { voice_id: string; name: string; preview_url?: string }) => ({
			id: v.voice_id,
			name: v.name,
			previewUrl: v.preview_url,
		}));
	});
</script>

<VoicePicker {voices} value={selectedVoice} onValueChange={(v) => (selectedVoice = v)} />
```

## API Reference

| Prop | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `voices` | `Voice[]` | — | Voices to display in the picker. Any object conforming to `Voice` works. |
| `value?` | `string` | — | Selected voice ID for controlled usage. |
| `onValueChange?` | `(value: string) => void` | — | Called with the voice ID when the user picks a voice. |
| `placeholder?` | `string` | `"Select a voice..."` | Placeholder shown on the trigger when no voice is selected. |
| `class?` | `string` | — | Extra classes forwarded to the trigger button. |
| `open?` | `boolean` | — | Controlled popover open state. Leave undefined for uncontrolled. |
| `onOpenChange?` | `(open: boolean) => void` | — | Called when the popover open state changes. |

## Notes

- Built on the shadcn-svelte `Command` and `Popover` primitives plus sv11's [`AudioPlayer`](/docs/components/audio-player) — search, keyboard nav, and shared playback state come from those components.
- Each row renders an [`Orb`](/docs/components/orb); the selected voice also shows one on the trigger (hardcoded to the `"thinking"` state, purely decorative).
- Preview playback is driven by `AudioPlayer`, so only one voice plays at a time across the picker.
- Voices without a `previewUrl` still render, but the hover play/pause overlay is suppressed.
- Search filtering draws on each voice's `name` plus the common `labels` keys (`accent`, `gender`, `age`, `description`, `use case`).
- Works controlled (`value` + `onValueChange`), uncontrolled (`onValueChange` only), or with an externally-driven popover (`open` + `onOpenChange`).
- The `Voice` type is provider-agnostic — see [Providers](/docs/providers) for the full shape and how to map your backend onto it.

---

# Waveform

> Canvas-based audio waveform visualization components with recording, playback scrubbing, and microphone input support.

```svelte
<script lang="ts">
	import { Card, CardHeader, CardTitle, CardDescription } from "$lib/registry/ui/card/index.js";
	import { ScrollingWaveform } from "$lib/registry/ui/waveform/index.js";
</script>

<Card class="w-full p-6">
	<CardHeader class="p-0 pb-4">
		<CardTitle>Waveform</CardTitle>
		<CardDescription>Real-time audio visualization with smooth scrolling animation</CardDescription>
	</CardHeader>
	<ScrollingWaveform height={80} barWidth={3} barGap={2} speed={30} fadeEdges barColor="gray" />
</Card>
```

## Installation

```bash
npx shadcn-svelte@latest add https://sv11.ui.twango.dev/r/waveform.json
```

## Usage

```svelte
<script lang="ts">
	import { Waveform } from "$lib/registry/ui/waveform";
</script>

<Waveform />
```

## Examples

### Basic Usage

Pass an array of values in `[0, 1]` to render a static bar chart.

```svelte
<script lang="ts">
	import { Waveform } from "$lib/registry/ui/waveform";

	const data = Array.from({ length: 50 }, () => Math.random());
</script>

<Waveform {data} height={100} barWidth={4} barGap={2} />
```

### Scrolling Animation

`ScrollingWaveform` continuously scrolls auto-generated bars from right to left.

```svelte
<script lang="ts">
	import { ScrollingWaveform } from "$lib/registry/ui/waveform";
</script>

<ScrollingWaveform height={80} speed={50} barCount={60} fadeEdges />
```

### Microphone Input

`MicrophoneWaveform` captures live input and renders a symmetric frequency visualization.

```svelte
<script lang="ts">
	import { MicrophoneWaveform } from "$lib/registry/ui/waveform";

	let isRecording = $state(false);
</script>

<MicrophoneWaveform
	active={isRecording}
	height={100}
	sensitivity={1.5}
	onError={(error) => console.error("Microphone error:", error)}
/>
```

### Static Waveform

`StaticWaveform` generates deterministic bars from a seed — useful for placeholders.

```svelte
<script lang="ts">
	import { StaticWaveform } from "$lib/registry/ui/waveform";
</script>

<StaticWaveform bars={40} seed={42} />
```

### Audio Scrubber

`AudioScrubber` turns a waveform into an interactive seek control.

```svelte
<script lang="ts">
	import { AudioScrubber } from "$lib/registry/ui/waveform";

	const data = Array.from({ length: 100 }, () => 0.2 + Math.random() * 0.6);
	let currentTime = $state(0);
	const duration = 100;

	function handleSeek(time: number) {
		currentTime = time;
	}
</script>

<AudioScrubber
	{data}
	{currentTime}
	{duration}
	onSeek={handleSeek}
	height={60}
	barWidth={3}
	barGap={1}
/>
```

### Voice Recorder

`RecordingWaveform` captures mic input, stores the full history, and lets the user scrub through the recording once stopped.

```svelte
<script lang="ts">
	import { RecordingWaveform } from "$lib/registry/ui/waveform";
	import { Button } from "$lib/registry/ui/button";

	let recording = $state(false);
</script>

<div class="space-y-4">
	<RecordingWaveform
		{recording}
		height={100}
		onRecordingComplete={(data) => {
			console.log("Recording complete", data);
		}}
	/>
	<Button onclick={() => (recording = !recording)}>
		{recording ? "Stop" : "Start"} Recording
	</Button>
</div>
```

### Live Microphone with Playback

`LiveMicrophoneWaveform` pairs a scrolling live feed with post-recording scrub-and-playback.

```svelte
<script lang="ts">
	import { LiveMicrophoneWaveform } from "$lib/registry/ui/waveform";

	let active = $state(false);
</script>

<LiveMicrophoneWaveform {active} enableAudioPlayback playbackRate={1} />
```

## API Reference

| Prop | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `data?` | `number[]` | `[]` | Array of normalized bar values in `[0, 1]`. The component samples from this array to fill the available width. |
| `barWidth?` | `number` | `4` | Width of each bar in pixels. |
| `barHeight?` | `number` | `4` | Minimum bar height in pixels. Bars are drawn at least this tall even when their value is near zero. |
| `barGap?` | `number` | `2` | Gap between bars in pixels. |
| `barRadius?` | `number` | `2` | Corner radius applied to each bar. Set to `0` for square bars. |
| `barColor?` | `string` | — | Custom bar color. Falls back to the canvas's computed `--foreground` CSS variable when unset. |
| `fadeEdges?` | `boolean` | `true` | Fade the left and right edges of the waveform via a destination-out gradient mask. |
| `fadeWidth?` | `number` | `24` | Width of the edge fade region in pixels. |
| `height?` | `string \| number` | `128` | Height of the waveform container. Numbers are treated as pixels; strings are passed through as a CSS length. |
| `active?` | `boolean` | — | Marks the waveform as actively capturing or rendering audio. Rendered as `data-active` on the root element for CSS styling hooks. |
| `onBarClick?` | `(index: number, value: number) => void` | — | Called when a bar is clicked with the data index and its value. |

## Notes

- All variants render to HTML5 Canvas and drive animations with `requestAnimationFrame` for smooth 60fps updates.
- Bar color defaults to the computed `--foreground` CSS variable — override via `barColor` to break out of the theme.
- Canvas sizing is handled internally via `ResizeObserver` and accounts for `devicePixelRatio` on high-DPI displays.
- Microphone-backed variants (`MicrophoneWaveform`, `RecordingWaveform`, `LiveMicrophoneWaveform`) request user permission when their `active` / `recording` prop becomes `true` and release the stream when it flips back to `false`.
- `AudioScrubber` only updates its internal position from `currentTime` while the user is not dragging — local state takes over during interaction to avoid feedback loops.
- `ScrollingWaveform` synthesizes data when `data` is empty; pass values to drive it from your own source.