# Bring your own data

Bring your own data [#bring-your-own-data]

LocalMode UI components are **presentational**. None of them load a model, run inference, or own message history — they render the props you pass and call back when the user acts. After `shadcn add`, the components have **no `@localmode/*` runtime dependency**: you supply the data.

This page documents the contract — the shapes each family expects — so you can wire components to a LocalMode hook, a cloud backend, or a hard-coded fixture interchangeably.

<Callout type="info" title="The mental model">
  A LocalMode hook (e.g. `useChat`, `useClassify`, `useModelLoad`) is the *recommended* producer of
  these shapes, but it is never required. Anything that can produce the shape below — a `fetch()`, an
  AI-SDK part, a constant — drives the component identically.
</Callout>

Conversation [#conversation]

The chat surfaces render message and streaming state.

| Component                            | Key props                           | Shape                                                                                                                                                                                                      |
| ------------------------------------ | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Message` / `MessageContent`         | `role`, `content`                   | `role: 'user' \| 'assistant' \| 'system'`; `content` is a markdown `string` or `MessagePart[]` (`{ type: 'text', text }` / `{ type: 'image', data, mimeType }` / `{ type: 'file', name, data, mimeType }`) |
| `Response`                           | `children`, `streaming`             | a markdown `string` + a `boolean`                                                                                                                                                                          |
| `PromptInput`                        | `onSubmit`, `streaming`, `onStop`   | `onSubmit(text: string, attachments)`, a `boolean`, a `() => void`                                                                                                                                         |
| `Tool` / `ToolHeader` / `ToolOutput` | `name`, `status`, `input`, `output` | a `ToolCall` (`{ name, status, input?, output?, error? }`) — `status` is one of `'pending' \| 'running' \| 'streaming' \| 'completed' \| 'error'`, with arbitrary JSON in/out                              |
| `Reasoning` / `ReasoningContent`     | `streaming`, `children`             | `streaming: boolean`; the thinking text is a `string` passed as `ReasoningContent`'s children                                                                                                              |
| `Sources` / `Source`                 | `count`, `source`                   | `SourcesTrigger` takes `count: number`; each `Source` takes a `SourceItem` (`{ id, title, url?, score?, excerpt? }`)                                                                                       |

```tsx
// Static fixture — no hook, no backend:
<Message role="assistant">
  <MessageAvatar role="assistant" />
  <MessageContent role="assistant" content="Hello from **any** source." />
</Message>
```

See [Use with the Vercel AI SDK](/docs/use-with-ai-sdk) for a full cloud-backed example.

Results & Insights [#results--insights]

Scored-output displays render plain numbers and labels.

| Component               | Shape                                                                                                                                |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `ConfidenceScoreBadge`  | `score: number` (0–1), optional `thresholds`                                                                                         |
| `ScoredResultBarList`   | `results: Array<{ label: string; score: number }>`                                                                                   |
| `TopResultCard`         | `{ label: string; score: number }`                                                                                                   |
| `CosineSimilarityMeter` | `similarity: number` (0–1, clamped)                                                                                                  |
| `EntityStatsBar`        | `entities: Array<{ type: string; text?; score? }>` (counts computed internally) — or a pre-computed `counts: Record<string, number>` |

```tsx
// Any classifier, search ranker, or constant produces this:
<ScoredResultBarList results={[
  { label: 'positive', score: 0.92 },
  { label: 'neutral', score: 0.06 },
  { label: 'negative', score: 0.02 },
]} />
```

Input Controls [#input-controls]

| Component              | Shape                                                                      |
| ---------------------- | -------------------------------------------------------------------------- |
| `CharLimitIndicator`   | `charCount: number`, `maxLength: number`                                   |
| `ParameterSlider`      | `value: number`, `onChange`, `min`, `max`                                  |
| `SegmentedModePicker`  | `items: Array<{ id, label }>`, `selectedId`, `onSelect`                    |
| `LanguagePairSelector` | `languages`, `sourceCode`, `targetCode`, `onSwap`, `onSelectSource/Target` |

Media & Vision [#media--vision]

| Component                | Shape                                                                                                             |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `BoundingBoxOverlay`     | `detections: Array<{ label, score?, box: { x, y, width, height } }>` + the image's `naturalWidth`/`naturalHeight` |
| `BeforeAfterImageViewer` | `originalSrc` + optional `processedSrc` (two image sources)                                                       |
| `ImageResultGallery`     | `cards: Array<{ id, src, label?, score? }>`                                                                       |

Data & Documents [#data--documents]

| Component                        | Shape                                                                                                                                        |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `FileDropzone` / `MediaDropzone` | `accept`, `maxSize`, + the valid-files callback (`onUpload` on `FileDropzone`, `onFiles` on `MediaDropzone`) — validation is generic (no AI) |
| `IndexedDocumentCard`            | `{ filename, chunkCount, pageCount?, sizeBytes?, … }`                                                                                        |
| `CategoryFacetList`              | `categories: string[]` + optional `counts: Record<string, number>` + `selected`/`onSelect`                                                   |

Audio [#audio]

| Component                                  | Shape                                                                    |
| ------------------------------------------ | ------------------------------------------------------------------------ |
| `WaveformActivityBars`                     | a `volume: number` (`0–1`) or a `state` agent-state string               |
| `VoicePicker`                              | `voices: Array<{ id, name, gender, languageLabel }>`                     |
| `AudioScrubPlayer` / `TranscribedNoteCard` | `audio`: a `Blob \| string` (rendered via the copy-owned `useObjectUrl`) |

Artifacts & Canvas [#artifacts--canvas]

| Component           | Shape            |
| ------------------- | ---------------- |
| `DataTableArtifact` | rows + columns   |
| `ChartArtifact`     | a series array   |
| `CodeDiffViewer`    | two code strings |

Security & Privacy [#security--privacy]

| Component                     | Shape                                                                                                                                              |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PasswordStrengthBar`         | `value: number` (0–100) — the app computes it (e.g. via `@localmode/core` `deriveKey` flow, or any estimator)                                      |
| `DifferentialPrivacyControls` | `enabled`/`onEnabledChange` + `epsilon`/`onEpsilonChange`, plus an optional `budget` object (`{ consumed, maxEpsilon }`) — all supplied by the app |

Local-First (the on-device tier) [#local-first-the-on-device-tier]

The local-first family is presentational too — it renders model/storage/capability state you pass — but it *describes* on-device AI, so it pairs naturally with the LocalMode hooks. A cloud app generally wouldn't install this family, with one exception:

* **`ContextUsageMeter`** takes the token fields (`inputTokens`, `outputTokens`, `reasoningTokens`, `cachedTokens`) and `contextWindow` directly as flat props — usable with **any** LLM's usage data, local or cloud. (The lower-level `Context` compound root instead takes a nested `usage={{ … }}` object for `ContextTrigger` / `ContextContent` / `ContextInputUsage` / `ContextOutputUsage`.)

```tsx
<ContextUsageMeter inputTokens={1200} outputTokens={340} contextWindow={8192} />
```

The invariant [#the-invariant]

Every non-local-first component compiles and runs with **zero `@localmode/*` packages** installed. If you ever find a component that won't, it's a bug — file it. The recommended pairing is the LocalMode hooks; the requirement is only that you pass the shape.

See also [#see-also]

* [Use with the Vercel AI SDK](/docs/use-with-ai-sdk) — a full cloud-backed chat driving these shapes from an `@ai-sdk/react` message stream.
* Live, fully-wired reference implementations in the [`/blocks` gallery](/blocks): the [chat block](/blocks/chat) drives the Conversation shapes from on-device models, and the knowledge blocks ([semantic search](/blocks/knowledge/semantic-search), [RAG chat](/blocks/knowledge/rag-chat)) drive the Results and Data & Documents shapes from your own documents. Blocks are the wiring layer, so they *do* pull the LocalMode hooks — read them as worked examples of what a producer for each shape looks like.

# Components

Components [#components]

Every component below is copy-owned and installed with the shadcn CLI under the `@localmode/ui` namespace. Click through for the live preview, install command, props, and usage.

# Device Badge

Device Badge [#device-badge]

The **Device Badge** surfaces a browser AI capability — WebGPU, WASM, or IndexedDB storage — as a themed status pill. It reads the device's capabilities via the copy-owned `useCapabilities()` hook (from the `@localmode/ui/lib/use-environment` lib, installed automatically) and shows green when the capability is available, amber when it is not, and a pulsing muted dot while detection is in flight.

**When to use it:** gate a model-download UI behind device support (e.g. "WebGPU available → offer the fast WebGPU model; otherwise fall back to WASM"), or show users why a feature is or isn't available on their device.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/device-badge`

Full source: https://localmode.ai/r/ui/device-badge.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/device-badge
```

Dependencies [#dependencies]

**Data source:** detects capabilities entirely in the browser — no backend, no model download. Capability detection is provided by the copy-owned `@localmode/ui/lib/use-environment` lib (`useCapabilities`, `detectCapabilities`), installed automatically as a registry dependency, so the component is portable to any React app.

* `@localmode/ui/lib/use-environment` — the copy-owned `useCapabilities()` hook + `detectCapabilities()` (installed automatically as a registry dependency)
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `device-badge.tsx` — the component
* `lib/use-environment.ts` — the copy-owned capability hooks (if not already present)
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**DeviceBadge**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `capability` | `"storage" \| "wasm" \| "webgpu"` | `"webgpu"` | Which capability to surface. `webgpu` reports GPU acceleration availability; `wasm` reports WebAssembly support; `storage` reports IndexedDB persistence. |
| `label` | `string` | — | Label shown before the status. Defaults to a human-readable capability name. |
| `compact` | `boolean` | `false` | When true, render a compact dot-only badge without the text label. |

Examples [#examples]

Default (WebGPU) [#default-webgpu]

```tsx
import { DeviceBadge } from '@/components/device-badge';

export function Example() {
  return <DeviceBadge />;
}
```

Gate a model choice [#gate-a-model-choice]

```tsx
import { DeviceBadge } from '@/components/device-badge';
import { useCapabilities } from '@/lib/use-environment';

export function ModelPicker() {
  const { capabilities } = useCapabilities();
  const hasWebGPU = Boolean(capabilities?.features.webgpu);

  return (
    <div className="flex items-center gap-3">
      <DeviceBadge capability="webgpu" />
      <button disabled={!hasWebGPU}>Load WebGPU model</button>
    </div>
  );
}
```

Compact (dot only) [#compact-dot-only]

```tsx
<DeviceBadge capability="storage" compact />
```

Customization [#customization]

The badge is styled entirely with shadcn/ui CSS-variable utilities (`border-border`, `bg-card`, `text-card-foreground`, `text-muted-foreground`), so it inherits your theme. The status colors use Tailwind's `emerald` / `amber` palettes directly — swap those classes in the copied `device-badge.tsx` to match your design system, or wire them to your own tokens.

Because you own the file, you can also extend `DeviceBadgeProps` to surface any capability returned by `detectCapabilities()` (e.g. `sharedarraybuffer`, `webworkers`) by adding an entry to the internal capability map.

# Introduction

LocalMode UI [#localmode-ui]

**LocalMode UI** is a shadcn-style registry of copy-owned, composable AI UI primitives for the browser. It is the UI layer on top of [`@localmode/core`](https://localmode.dev/docs/core) and the [`@localmode/react`](https://localmode.dev/docs/react) hooks — chat surfaces, model-download progress, device-capability gates, and the other local-first surfaces that have no off-the-shelf equivalent.

<Callout type="info" title="Local-first by default">
  Every component runs entirely in the browser. Inference happens on-device — no servers, no API
  keys, and data never leaves the user's device.
</Callout>

<Callout type="info" title="…and cloud-compatible by contract">
  The components are presentational — they render plain props and own no orchestration state — so
  they install with **zero `@localmode/*` packages** and work with any backend. Pair them with the
  LocalMode hooks (recommended) or drive them from the [Vercel AI SDK](/docs/use-with-ai-sdk) or
  [your own data](/docs/bring-your-own-data).
</Callout>

How it works [#how-it-works]

LocalMode UI is **not** an npm package. Like shadcn/ui, you install components with the shadcn CLI and **own the copied code**. Components are styled with shadcn/ui CSS variables (`bg-background`, `text-primary`, …), so they drop into your existing shadcn project and inherit your theme automatically.

```bash
npx shadcn@latest add @localmode/ui/device-badge
```

The `@localmode/ui` namespace [#the-localmodeui-namespace]

All UI registry items live under the `ui/*` path so they stay distinct from the `@localmode/*` npm packages (core / react / providers). The item-naming scheme is:

| Pattern                   | Installs           | Example                              |
| ------------------------- | ------------------ | ------------------------------------ |
| `ui/all`                  | The whole catalog  | `@localmode/ui/all`                  |
| `ui/<family>`             | A whole family     | `@localmode/ui/conversation`         |
| `ui/<family>/<component>` | A single component | `@localmode/ui/conversation/message` |

The shadcn namespace key is the single token `@localmode`; the `ui/` separation lives in the item name.

Next steps [#next-steps]

<Cards>
  <Card title="Installation" href="/docs/installation" description="Configure the @localmode namespace in your components.json and install your first component." />

  <Card title="Components" href="/docs/components" description="Browse every available Element, grouped by category." />

  <Card title="Device Badge" href="/docs/device-badge" description="The seed component — a local-first capability badge driven by useCapabilities()." />

  <Card title="Core Docs" href="https://localmode.dev/docs" description="The @localmode engine and the 59 React hooks these components are built on." />
</Cards>

# Installation

Installation [#installation]

LocalMode UI components are distributed through a [shadcn registry](https://ui.shadcn.com/docs/registry). You install them with the shadcn CLI and own the copied code.

Prerequisites [#prerequisites]

You need a project with [shadcn/ui set up](https://ui.shadcn.com/docs/installation) (Tailwind CSS 4 with CSS variables and a `components.json`). LocalMode UI components are styled with the same CSS-variable tokens, so they inherit your theme.

1\. Add the `@localmode` namespace [#1-add-the-localmode-namespace]

Map the single-token `@localmode` namespace to the registry in your project's `components.json`:

```json title="components.json"
{
  "registries": {
    "@localmode": "https://localmode.ai/r/{name}.json"
  }
}
```

For private/premium items (future), use the object form with a token:

```json title="components.json"
{
  "registries": {
    "@localmode": {
      "url": "https://localmode.ai/r/{name}.json",
      "headers": { "Authorization": "Bearer ${LOCALMODE_TOKEN}" }
    }
  }
}
```

2\. Install a component [#2-install-a-component]

```bash
npx shadcn@latest add @localmode/ui/device-badge
```

This copies the component's files into your project and installs any npm dependencies it declares (many components — like `device-badge` — declare none; others pull only small libraries such as `lucide-react`). No `@localmode/*` package is installed. Cross-namespace `registryDependencies` (like the shared `cn()` util) are resolved automatically.

3\. Install a whole family or everything [#3-install-a-whole-family-or-everything]

The registry ships aggregate items so you can install in bulk:

```bash
# A single component
npx shadcn@latest add @localmode/ui/device-badge

# An entire family (e.g. once the conversation family ships)
npx shadcn@latest add @localmode/ui/conversation

# The whole catalog
npx shadcn@latest add @localmode/ui/all
```

<Callout type="warn" title="These components run models in the browser">
  LocalMode UI components perform on-device inference. The first time a component loads its model,
  it downloads from a model host (e.g. HuggingFace) and caches it. After that it works offline.
</Callout>

# Use with an AI agent (MCP)

Use with an AI agent (MCP) [#use-with-an-ai-agent-mcp]

LocalMode UI is a standard shadcn registry, so it works with the **shadcn MCP server out of the box** — no LocalMode-specific server to run. Once configured, an AI coding agent can search the catalog, read component descriptions, and install items into your project on request.

<Callout type="info" title="Why this works with zero extra setup">
  The shadcn MCP server reads any registry that exposes a root `registry.json`. LocalMode UI serves
  its catalog at <code>[https://localmode.ai/registry.json](https://localmode.ai/registry.json)</code> and each item at
  <code>/r/\<name>.json</code>, so the MCP can discover and install everything under the
  `@localmode` namespace.
</Callout>

1\. Add the registry to your project [#1-add-the-registry-to-your-project]

In your project's `components.json`, map the single-token `@localmode` namespace to the registry endpoint:

```json
{
  "registries": {
    "@localmode": "https://localmode.ai/r/{name}.json"
  }
}
```

2\. Initialize the shadcn MCP for your client [#2-initialize-the-shadcn-mcp-for-your-client]

```bash
npx shadcn@latest mcp init --client claude
```

Swap `claude` for `cursor`, `vscode`, or `codex` as needed. This registers the shadcn MCP server with your agent; it can now read every registry configured in `components.json`, including `@localmode`.

3\. Ask the agent [#3-ask-the-agent]

With the MCP connected, prompt your agent in natural language. Because every item ships a precise description, the agent can resolve components by intent, not just by exact name:

* *"Add the model-download-progress component from @localmode/ui."*
* *"Install the @localmode/ui conversation family so I can build a chat."*
* *"Find a LocalMode UI component that shows a confidence score and add it."*
* *"Scaffold a local-first chat using @localmode/ui components."*
* *"Install the @localmode/ui chat block."* — composed, ready-to-run blocks live in the same catalog and install the same way (e.g. `@localmode/ui/blocks/knowledge/semantic-search`).

The agent searches the catalog, picks the matching item(s), and runs the install — copying the owned `.tsx` into your project exactly as a manual `shadcn add` would.

What the agent sees [#what-the-agent-sees]

* **The catalog**: [`/registry.json`](/registry.json) — every item with its title, description, dependencies, and `registryDependencies`.
* **Per-item JSON**: `/r/ui/<family>/<component>.json` — the files and metadata the CLI installs.
* **Aggregates**: `@localmode/ui/all` and `@localmode/ui/<family>` for bulk installs.
* **Composed blocks**: `@localmode/ui/blocks/<category>/<block>` (e.g. `blocks/chat`, `blocks/knowledge/rag-chat`, `blocks/vision/object-detector`) — full, wired mini-apps in the same catalog. They're excluded from the aggregates by design, so an agent only installs one when asked for it by name.

Other agent-readable resources [#other-agent-readable-resources]

Beyond MCP, the site publishes plain-text indexes agents can ingest directly:

* [`llms.txt`](/llms.txt) — the catalog as a markdown index.
* [`llms-full.txt`](/llms-full.txt) — the full component reference.
* Every docs page is available as raw markdown via its **View as Markdown** action.

See also [#see-also]

* [Installation](/docs/installation) — manual setup and `components.json`.
* [Bring your own data](/docs/bring-your-own-data) — the prop contracts an agent-installed component renders.

# Use with the Vercel AI SDK

Use with the Vercel AI SDK [#use-with-the-vercel-ai-sdk]

LocalMode UI components are **presentational and hook-driven**: they render plain prop shapes and emit callbacks, owning no model, no inference, and no message history. That means the same conversation elements work with **any** backend — the [Vercel AI SDK](https://sdk.vercel.ai), direct OpenAI/Anthropic calls, or your own cloud API — not just LocalMode.

After installing, the components have **no `@localmode/*` dependency** to remove: nothing in the catalog imports a LocalMode package at runtime. You wire your own data source.

<Callout type="info" title="Local-first by design, cloud-compatible by contract">
  LocalMode UI leads with on-device inference via the `@localmode/react` hooks — that's the
  recommended pairing. But the components render plain props, so a cloud backend works just as
  well. This page shows the Vercel AI SDK; the same shapes apply to any source.
</Callout>

Install the elements [#install-the-elements]

```bash
npx shadcn@latest add @localmode/ui/conversation
```

This installs the conversation family (chat shell, message, response, prompt input, tool, reasoning, sources, branch) into your project. No LocalMode package is added.

A complete chat on `@ai-sdk/react` [#a-complete-chat-on-ai-sdkreact]

The only difference from a LocalMode chat is the logic line — `useChat` from `@ai-sdk/react` (which hits your `/api/chat` route) instead of `@localmode/react` — and a few lines mapping the SDK's message parts onto the component props.

```tsx
'use client';

import { useChat } from '@ai-sdk/react'; // cloud logic instead of @localmode/react
import {
  Conversation,
  ConversationContent,
} from '@/components/conversation';
import { Message, MessageAvatar, MessageContent } from '@/components/message';
import {
  PromptInput,
  PromptInputTextarea,
  PromptInputTools,
  PromptInputSubmit,
} from '@/components/prompt-input';

// Map an @ai-sdk/react message's parts onto MessageContent's `content` prop.
const textOf = (m) =>
  m.parts.filter((p) => p.type === 'text').map((p) => p.text).join('');

export default function Chat() {
  const { messages, status, sendMessage, stop } = useChat(); // hits /api/chat
  const streaming = status === 'streaming';

  return (
    <>
      <Conversation streaming={streaming}>
        <ConversationContent>
          {messages.map((m) => (
            <Message key={m.id} role={m.role}>
              <MessageAvatar role={m.role} />
              <MessageContent role={m.role} content={textOf(m)} />
            </Message>
          ))}
        </ConversationContent>
      </Conversation>

      <PromptInput
        streaming={streaming}
        onStop={stop}
        onSubmit={(text) => sendMessage({ text })}
      >
        <PromptInputTextarea />
        <PromptInputTools>
          <PromptInputSubmit />
        </PromptInputTools>
      </PromptInput>
    </>
  );
}
```

That's the whole integration: `messages` → `Message`/`MessageContent`, `status` → `streaming`, `sendMessage`/`stop` → `PromptInput`. The components never knew which backend produced the data.

<Callout type="info" title="Live streaming cursor">
  `MessageContent` renders finished markdown. For a blinking cursor on the *in-flight*
  assistant message, swap it for the `Response` renderer — a standalone streaming-aware
  markdown component (`<Response streaming>{textOf(m)}</Response>`), installed via
  `@localmode/ui/conversation/response`.
</Callout>

Mapping the richer parts [#mapping-the-richer-parts]

The Vercel AI SDK emits tool invocations, reasoning, and sources as message *parts*. Each maps cleanly onto a LocalMode element.

Tool invocations → `Tool` [#tool-invocations--tool]

```tsx
import { Tool, ToolHeader, ToolContent, ToolInput, ToolOutput } from '@/components/tool';

// Inside the message map, for each part where p.type === 'tool-<name>'.
// The tool name lives in the part's `type` (`tool-${name}`), not a `toolName` field.
const toolName = p.type.replace('tool-', '');

<Tool defaultOpen>
  <ToolHeader name={toolName} status={mapToolStatus(p.state)} />
  <ToolContent>
    <ToolInput input={p.input} />
    <ToolOutput output={p.output} error={p.errorText} />
  </ToolContent>
</Tool>;

// AI SDK tool-part `state` → the component's `ToolStatus` taxonomy
function mapToolStatus(state: string) {
  switch (state) {
    case 'input-streaming':
      return 'streaming';
    case 'input-available':
      return 'running';
    case 'output-available':
      return 'completed';
    case 'output-error':
      return 'error';
    default:
      return 'pending';
  }
}
```

Reasoning parts → `Reasoning` [#reasoning-parts--reasoning]

```tsx
import { Reasoning, ReasoningTrigger, ReasoningContent } from '@/components/reasoning';

const reasoning = m.parts
  .filter((p) => p.type === 'reasoning')
  .map((p) => p.text)
  .join('');

{reasoning && (
  <Reasoning>
    <ReasoningTrigger />
    <ReasoningContent>{reasoning}</ReasoningContent>
  </Reasoning>
)}
```

Source parts → `Sources` [#source-parts--sources]

```tsx
import { Sources, SourcesTrigger, SourcesContent, Source } from '@/components/sources';

const sources = m.parts.filter((p) => p.type === 'source-url');

{sources.length > 0 && (
  <Sources>
    <SourcesTrigger count={sources.length} />
    <SourcesContent>
      {sources.map((s) => (
        <Source
          key={s.sourceId}
          source={{ id: s.sourceId, url: s.url, title: s.title ?? s.url }}
        />
      ))}
    </SourcesContent>
  </Sources>
)}
```

`Branch` and `ChainOfThought` map the same way — from the SDK's message alternatives and step lists onto the components' props.

What changes vs. LocalMode [#what-changes-vs-localmode]

|                      | LocalMode (recommended)           | Vercel AI SDK                  |
| -------------------- | --------------------------------- | ------------------------------ |
| Logic hook           | `useChat` from `@localmode/react` | `useChat` from `@ai-sdk/react` |
| Where inference runs | on-device (no server)             | your API route / provider      |
| Component code       | **identical**                     | **identical**                  |
| Data mapping         | none (shapes match the hooks)     | \~3 lines per part type        |

The components are the constant. Pick the logic layer that fits your app — and reach for the [local-first families](/docs/local-first) (model download, capability gates, on-device storage observability) that no cloud UI library ships.

See also [#see-also]

* [Chat block](/blocks/chat) — a live, fully-wired reference doing the local counterpart of this page: the same conversation elements driven by 76 on-device models across four providers (with vision, reasoning, and agent mode). Install it with `npx shadcn@latest add @localmode/ui/blocks/chat`.
* [Bring your own data](/docs/bring-your-own-data) — the generic prop contract and per-family shape tables, for any backend or static fixtures.
* [Conversation components](/docs/conversation) — the full family reference.

# Artifact

Artifact [#artifact]

The **Artifact** is a Claude-style docked side-panel/canvas: a vertical surface with a header (title + description), an action toolbar (copy / download / refresh / close), and a scrollable content region. It renders generated output — code, a markdown doc, an SVG, raw HTML — *beside* the chat instead of inline in the message stream.

It is composed from sub-parts: `Artifact` (root) → `ArtifactHeader` → `ArtifactTitle` / `ArtifactDescription` and `ArtifactActions` → `ArtifactAction` / `ArtifactClose`, plus `ArtifactContent` for the scrollable body.

**Bring your own content.** The shell is purely presentational — it renders whatever content you pass in, from any backend. A local language model is a recommended (optional) producer: drive it with [`useGenerateText()`](https://localmode.dev/docs/react) / [`useGenerateObject()`](https://localmode.dev/docs/react) and there is &#x2A;*no server, no sandbox, no remote execution.** Copy writes to the clipboard, download produces a real `Blob`, and refresh re-runs your generation — all in-browser.

**When to use it:** show a generated file/document in a dedicated canvas that the user can copy, download, or regenerate, separate from the conversational stream.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/artifacts/artifact`

Full source: https://localmode.ai/r/ui/artifacts/artifact.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/artifacts/artifact
```

Dependencies [#dependencies]

* **Data source:** the canvas renders whatever content you pass it — works with any backend. Recommended LocalMode producers: `useGenerateText()` / `useGenerateObject()` from `@localmode/react` (optional).
* `@localmode/ui/lib/browser-utils` — the copy-owned `downloadBlob` helper for artifact export (installed automatically as a registry dependency)
* `lucide-react` — toolbar icons
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `artifact.tsx` — the canvas shell and all sub-parts
* `lib/browser-utils.ts` — the copy-owned file helpers (if not already present)
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**Artifact**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | `true` | When false, the canvas is hidden (returns `null`). Lets the host toggle the docked panel open/closed. Defaults to `true`. |

ArtifactAction [#artifactaction]

**ArtifactAction**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | — | **Required.** Accessible label for the icon button (also used as the tooltip). |
| `icon` | `ReactNode` | — | Icon to render. Defaults are wired by convention: pass `content` to make a copy/download action, or `onClick` for a custom (e.g. refresh) action. |
| `content` | `string` | — | String content the action operates on. When provided without `fileName`, clicking copies it to the clipboard. When provided with `fileName`, clicking downloads it as a real `Blob`. Both happen entirely client-side. |
| `fileName` | `string` | — | When set (with `content`), the action downloads `content` as this file. |
| `mimeType` | `string` | `"text/plain"` | MIME type for the downloaded blob. |

ArtifactClose [#artifactclose]

**ArtifactClose**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | `"Close"` | Accessible label. |

Examples [#examples]

Drive the canvas from a local model [#drive-the-canvas-from-a-local-model]

```tsx
import { useGenerateText } from '@localmode/react';
import { transformers } from '@localmode/transformers';
import {
  Artifact,
  ArtifactHeader,
  ArtifactTitle,
  ArtifactDescription,
  ArtifactActions,
  ArtifactAction,
  ArtifactClose,
  ArtifactContent,
} from '@/components/artifacts/artifact';

export function GeneratedCodeCanvas() {
  const model = transformers.languageModel('onnx-community/granite-4.0-350m-ONNX-web');
  const { data, isLoading, execute } = useGenerateText({ model, maxTokens: 200 });
  const code = data?.text ?? '';

  return (
    <Artifact className="h-96 w-[28rem]">
      <ArtifactHeader>
        <div>
          <ArtifactTitle>generated.ts</ArtifactTitle>
          <ArtifactDescription>From a local model run</ArtifactDescription>
        </div>
        <ArtifactActions>
          {/* content only → copy to clipboard */}
          <ArtifactAction content={code} label="Copy" />
          {/* content + fileName → download a Blob */}
          <ArtifactAction content={code} fileName="generated.ts" label="Download" />
          {/* onClick only → custom action (re-run) */}
          <ArtifactAction onClick={() => execute('Write a slugify function')} label="Refresh" />
          <ArtifactClose onClick={close} />
        </ArtifactActions>
      </ArtifactHeader>
      <ArtifactContent>
        {isLoading ? <p>Generating…</p> : <pre>{code}</pre>}
      </ArtifactContent>
    </Artifact>
  );
}
```

Toggle the panel open/closed [#toggle-the-panel-openclosed]

```tsx
<Artifact open={isOpen}>{/* … */}</Artifact>
```

When `open` is `false`, the canvas renders `null`. Wire `ArtifactClose`'s `onClick` to your state setter to hide it.

Toolbar action behaviors [#toolbar-action-behaviors]

`ArtifactAction` picks a built-in behavior from its props — all client-side:

| Props                    | Behavior                                                  |
| ------------------------ | --------------------------------------------------------- |
| `content` only           | Copy `content` to the clipboard (shows a transient check) |
| `content` + `fileName`   | Download `content` as a `Blob` named `fileName`           |
| `onClick` (no `content`) | Run your callback (e.g. refresh re-runs generation)       |

Local-first boundary [#local-first-boundary]

This is a **local canvas**. It does not embed a Sandbox, a Web Preview iframe, a Terminal, Test Results, a Commit/Package-Info panel, a File Tree, or Env Vars — those members of external artifact catalogs require remote code execution, deploys, or CI/VCS tooling and are deliberately out of scope (no server / no API key / no telemetry). See [Out of scope](#out-of-scope) below.

Out of scope [#out-of-scope]

The following server/IDE-centric artifact members from external AI-UI libraries are **refused** in LocalMode because they reintroduce a server/cloud dependency:

* **Sandbox** / **Terminal** — remote/cloud code execution.
* **Web Preview** — deployed-app iframe.
* **Test Results** / **Stack Trace** / **Commit** / **Package Info** / **File Tree** / **Env Vars** — CI/VCS/IDE dev tooling.

A live **JSXPreview** (generative-UI: rendering model-emitted JSX/JSON) is **deferred, not refused** — it is local-first-capable and high-interest, but rendering arbitrary model-emitted UI carries arbitrary-code-execution risk and needs a safe allowlist/sandbox design first. Tracked as a future change.

Customization [#customization]

The shell is styled entirely with shadcn/ui CSS-variable utilities (`bg-card`, `text-card-foreground`, `border-border`, `bg-primary`, `hover:bg-accent`), so it inherits your theme. Because you own the file, swap the `lucide-react` icons, adjust the toolbar layout, or render markdown/SVG/HTML inside `ArtifactContent` however you like.

# Chart Artifact

Chart Artifact [#chart-artifact]

The **Chart Artifact** is a client-side data-viz chart rendered from **local** data. It supports six types — `line`, `bar`, `area`, `scatter`, `radar`, `gauge` — and targets genuinely on-device metrics:

* **radar** — evaluation curves: precision / recall / F1 / accuracy from [`useEvaluateModel()`](https://localmode.dev/docs/react).
* **scatter** — 2D embedding projections (PCA / UMAP).
* **line / area** — drift-over-time ([`useReindex()`](https://localmode.dev/docs/react)), latency / tok-s trends.
* **bar** — embedding-similarity distributions, per-class counts.
* **gauge** — a single normalized score (e.g. overall F1).

It is **not** a generic BI widget — its value is visualizing what runs in the browser. The renderer is a **minimal, dependency-free inline SVG** (no charting library), so the copied component stays small and tree-shakeable. Colors come from `currentColor` + shadcn/ui tokens, so charts inherit your theme.

**Local content only.** No server, no sandbox — you pass in local numbers and it draws them.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/artifacts/chart-artifact`

Full source: https://localmode.ai/r/ui/artifacts/chart-artifact.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/artifacts/chart-artifact
```

Dependencies [#dependencies]

* **Data source:** draws the `ChartPoint[]` you pass — works with any backend (any in-memory numbers). Recommended LocalMode producers: `useEvaluateModel()` / `useReindex()` from `@localmode/react` for eval curves and drift series (optional).
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

> No charting library is installed — the chart is rendered with inline SVG.

Files installed [#files-installed]

* `chart-artifact.tsx` — the component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**ChartArtifact**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `ChartType` | — | **Required.** Chart kind. |
| `data` | `array` | — | **Required.** Data points. Shape requirements vary by `type` (see each field's docs). |
| `width` | `number` | `360` | Drawing width in px. |
| `height` | `number` | `220` | Drawing height in px. |
| `max` | `number` | — | For `gauge`: the maximum value (the dial's full-scale). Defaults to the single data point's `value` if ≤ 1 then 1, else the value itself. |
| `title` | `string` | — | Accessible label / title for the chart region. |

ChartPoint [#chartpoint]

**ChartPoint**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `x` | `number` | — | Numeric x value (line/area/scatter). |
| `y` | `number` | — | Numeric y/value. |
| `label` | `string` | — | Category label (bar/radar axes). |
| `value` | `number` | — | Numeric value (bar/radar/gauge). |

Examples [#examples]

Radar of precision / recall / F1 (from `useEvaluateModel`) [#radar-of-precision--recall--f1-from-useevaluatemodel]

```tsx
import { useEvaluateModel } from '@localmode/react';
import { ChartArtifact } from '@/components/artifacts/chart-artifact';

export function EvalRadar({ result }) {
  // result is a real evaluateModel() output
  const data = [
    { label: 'Precision', value: result.metrics.precision },
    { label: 'Recall', value: result.metrics.recall },
    { label: 'F1', value: result.metrics.f1 },
  ];
  return <ChartArtifact type="radar" title="Eval (P / R / F1)" data={data} />;
}
```

Scatter of a 2D embedding projection [#scatter-of-a-2d-embedding-projection]

```tsx
// projection = real local embeddings reduced to 2D (PCA / UMAP)
<ChartArtifact
  type="scatter"
  title="Embedding projection"
  data={projection.map(([x, y]) => ({ x, y }))}
/>
```

Line / area for drift or latency [#line--area-for-drift-or-latency]

```tsx
<ChartArtifact type="area" data={driftOverTime.map((d, i) => ({ x: i, y: d }))} />
```

Gauge for a single score [#gauge-for-a-single-score]

```tsx
<ChartArtifact type="gauge" data={[{ value: 0.87 }]} />
```

Data shapes by type [#data-shapes-by-type]

| Type                        | Expected `ChartPoint` fields                         |
| --------------------------- | ---------------------------------------------------- |
| `line` / `area` / `scatter` | `{ x, y }`                                           |
| `bar`                       | `{ label, value }`                                   |
| `radar`                     | `{ label, value }` (values typically 0–1)            |
| `gauge`                     | a single `{ value }` (0–`max`, default full-scale 1) |

Local-first boundary [#local-first-boundary]

This is a **local** chart. It draws numbers your app computed on-device (evaluation metrics, embedding projections, drift, latency). It makes no network requests and pulls in no charting dependency.

Customization [#customization]

The chart uses `currentColor` for the series (defaults to `text-primary`) and shadcn/ui token classes for grid/axis text, so it inherits your theme. Because you own the file, restyle the series color, adjust `width` / `height`, add tooltips, or render the chart inside an [`Artifact`](/docs/artifacts/artifact) canvas.

# Code Diff Viewer

Code Diff Viewer [#code-diff-viewer]

The **Code Diff Viewer** shows a line-level diff of two **local** strings — additions in green, deletions in red — in either a **unified** (single-column) or **split** (side-by-side) layout. The diff is computed in-browser with a dependency-free longest-common-subsequence algorithm. There is **no ML hook and no server**.

It is the text/code analog of the image-only `BeforeAfterImageViewer`. Use it for the before/after of:

* **PII redaction** — `redactPII()` raw → redacted.
* **Translation** — `translate()` source → target.
* **Any text transform** — prompt edits, formatting, rewrites.

**Local content only.** You pass two strings; it draws the diff. Nothing leaves the device.

**When to use it:** make a text transformation legible — show exactly what your local pipeline changed.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/artifacts/code-diff-viewer`

Full source: https://localmode.ai/r/ui/artifacts/code-diff-viewer.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/artifacts/code-diff-viewer
```

Dependencies [#dependencies]

* **Data source:** diffs the two strings you pass — works with any backend; the diff itself needs no hook. Recommended LocalMode producers: `redactPII()` / `translate()` from `@localmode/core` to generate the before/after strings (optional).
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

> No diff library is installed — the line diff is computed in-component (LCS).

Files installed [#files-installed]

* `code-diff-viewer.tsx` — the component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**CodeDiffViewer**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `original` | `string` | — | **Required.** The original ("before") string. |
| `modified` | `string` | — | **Required.** The modified ("after") string. |
| `mode` | `"split" \| "unified"` | `"unified"` | Display mode. |
| `originalLabel` | `string` | `"Original"` | Label for the original side (split header / unified caption). |
| `modifiedLabel` | `string` | `"Modified"` | Label for the modified side. |
| `showLineNumbers` | `boolean` | `true` | When false, line numbers are hidden. |

Examples [#examples]

PII-redaction before/after [#pii-redaction-beforeafter]

```tsx
import { redactPII } from '@localmode/core';
import { CodeDiffViewer } from '@/components/artifacts/code-diff-viewer';

export function RedactionDiff({ raw }: { raw: string }) {
  const redacted = redactPII(raw);
  return (
    <CodeDiffViewer
      original={raw}
      modified={redacted}
      originalLabel="Raw"
      modifiedLabel="Redacted"
    />
  );
}
```

Translation source/target (split view) [#translation-sourcetarget-split-view]

```tsx
<CodeDiffViewer
  original={source}
  modified={translated}
  mode="split"
  originalLabel="English"
  modifiedLabel="French"
/>
```

Unified vs split [#unified-vs-split]

```tsx
<CodeDiffViewer original={a} modified={b} mode="unified" />
<CodeDiffViewer original={a} modified={b} mode="split" />
```

Local-first boundary [#local-first-boundary]

This is a **local** diff. It takes two in-memory strings and computes the diff client-side. It needs no model, makes no network request, and runs no remote tooling.

Customization [#customization]

Additions/deletions use Tailwind's `emerald` / `red` palettes; everything else is shadcn/ui CSS-variable utilities (`bg-card`, `border-border`, `text-muted-foreground`), so it inherits your theme. Because you own the file, swap the highlight colors, hide line numbers via `showLineNumbers={false}`, or render the viewer inside an [`Artifact`](/docs/artifacts/artifact) canvas.

# Data Table Artifact

Data Table Artifact [#data-table-artifact]

The **Data Table Artifact** is a docked-canvas, sortable data table for any **local** row data: VectorDB search results, a model catalog, evaluation rows, or the array output of [`generateObject()`](https://localmode.dev/docs/react). Click a column header to sort the rows ascending → descending → unsorted — all computed in-browser, never on a server.

It is distinct from the inline `ScoredResultBarList` (a message-stream primitive): this is a *docked canvas* table you place beside the chat.

**Local content only.** No server, no sandbox. Sorting reorders a copy of your rows client-side; the input array is untouched.

**When to use it:** render a structured result set the user can scan and re-sort — e.g. a model picker, retrieval results, or an extracted-records table from a `generateObject()` call.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/artifacts/data-table-artifact`

Full source: https://localmode.ai/r/ui/artifacts/data-table-artifact.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/artifacts/data-table-artifact
```

Dependencies [#dependencies]

* **Data source:** renders the rows you pass and sorts them client-side — works with any backend (any in-memory array). Recommended LocalMode producers: `useGenerateObject()` from `@localmode/react` or VectorDB search results (optional).
* `lucide-react` — sort-direction icons
* `ui/table` — the shadcn/ui table primitive (installed automatically as a registry dependency)
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `data-table-artifact.tsx` — the component (uses the `ui/table` primitive)
* `ui/table.tsx` — the shadcn/ui table primitive (registry dependency)
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**DataTableArtifact**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `rows` | `array` | — | **Required.** The rows to render. Sorting reorders a copy; the input array is untouched. |
| `columns` | `array` | — | Column definitions. When omitted, columns are inferred from the keys of the first row. |
| `caption` | `ReactNode` | — | Optional caption rendered under the table. |
| `initialSortKey` | `string & keyof Row` | — | Initial sort column key. |
| `initialSortDirection` | `"desc" \| "asc"` | `"asc"` | Initial sort direction. |
| `emptyMessage` | `ReactNode` | `"No data"` | Message shown when `rows` is empty. |

DataTableColumn [#datatablecolumn]

**DataTableColumn**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `key` | `string & keyof Row` | — | **Required.** Key into the row object (used as the default accessor and sort key). |
| `header` | `string` | — | Header label. Defaults to `key`. |
| `cell` | `function` | — | Custom cell renderer. Defaults to `String(row[key])`. |
| `sortable` | `boolean` | `true` | When false, the column header is not clickable to sort. |
| `align` | `"center" \| "right" \| "left"` | `"left"` | Align the column's text. |

Examples [#examples]

From a `generateObject()` array [#from-a-generateobject-array]

```tsx
import { useGenerateObject, jsonSchema } from '@localmode/react';
import { z } from 'zod';
import { DataTableArtifact } from '@/components/artifacts/data-table-artifact';

const schema = jsonSchema(
  z.object({ rows: z.array(z.object({ name: z.string(), score: z.number() })) }),
);

export function ExtractedTable({ model }) {
  const { data, execute } = useGenerateObject({ model, schema });
  const rows = data?.object.rows ?? [];

  return (
    <DataTableArtifact
      rows={rows}
      columns={[
        { key: 'name', header: 'Name' },
        { key: 'score', header: 'Score', align: 'right' },
      ]}
    />
  );
}
```

From VectorDB search results [#from-vectordb-search-results]

```tsx
<DataTableArtifact
  rows={results.map((r) => ({ id: r.id, score: r.score, title: r.metadata.title }))}
  initialSortKey="score"
  initialSortDirection="desc"
  columns={[
    { key: 'title', header: 'Title' },
    { key: 'score', header: 'Similarity', align: 'right', cell: (r) => r.score.toFixed(3) },
    { key: 'id', header: 'ID' },
  ]}
/>
```

Inferred columns [#inferred-columns]

Omit `columns` and the table infers them from the first row's keys:

```tsx
<DataTableArtifact rows={rows} />
```

Sorting [#sorting]

Clicking a sortable header cycles **ascending → descending → unsorted**. Numbers, strings (natural/numeric-aware), booleans, and `Date` values are compared correctly; `null`/`undefined` sort first. Set `sortable: false` on a column to disable it, and `initialSortKey` / `initialSortDirection` to start pre-sorted.

Local-first boundary [#local-first-boundary]

This is a **local** table. It renders data your app already has in memory (VectorDB results, model catalogs, `generateObject()` output) and sorts it client-side. It does not fetch from a server or run remote queries.

Customization [#customization]

Styled with shadcn/ui CSS-variable utilities via the `ui/table` primitive, so it inherits your theme. Because you own the file, provide a custom `cell` renderer per column (badges, links, formatted numbers), adjust alignment, or wrap it inside an [`Artifact`](/docs/artifacts/artifact) canvas.

# Audio Scrub Player

Audio Scrub Player [#audio-scrub-player]

**Audio Scrub Player** is a composable scrubbable player for local `Blob` / object-URL audio such as Kokoro TTS output ([`useSynthesizeSpeech`](https://localmode.dev/docs/react)) or a recording. It provides play/pause, a draggable seek bar, and a time/duration readout, and manages its own `<audio>` element and object-URL lifecycle. The draggable `ScrubBar` is exported standalone for reuse over any time-based source.

**When to use it:** play back a locally-synthesized or recorded clip with precise scrubbing — without the inconsistent look of native `<audio controls>`.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/audio/audio-scrub-player`

Full source: https://localmode.ai/r/ui/audio/audio-scrub-player.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/audio/audio-scrub-player
```

Data source & dependencies [#data-source--dependencies]

**Data source:** plays any `Blob` / object-URL you pass — works with any backend. Recommended producer: `useSynthesizeSpeech` output (local Blob) from `@localmode/react` (on-device, optional).

* `@localmode/ui/lib/browser-utils` — `useObjectUrl` for Blob lifecycle (installed automatically as a registry dependency)
* `clsx` + `tailwind-merge` — via the shared `cn()` util
* No external player dependency — native `<audio>` + custom controls

Files installed [#files-installed]

* `audio-scrub-player.tsx` — `AudioScrubPlayer` + `ScrubBar`
* `lib/browser-utils.ts` — generic browser helpers (`useObjectUrl`)
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**AudioScrubPlayer**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `audio` | `object \| string` | — | **Required.** Local audio to play — a `Blob` (e.g. Kokoro output / a recording) or URL. |
| `autoPlay` | `boolean` | `false` | Auto-play once loaded. |

**ScrubBar**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `currentTime` | `number` | — | **Required.** Current playback position in seconds. |
| `duration` | `number` | — | **Required.** Total duration in seconds. |
| `onSeek` | `function` | — | **Required.** Fired continuously while dragging, and on click, with the new time. |
| `onSeekEnd` | `function` | — | Fired once when a drag gesture ends (useful to commit a seek). |

Examples [#examples]

Play Kokoro output [#play-kokoro-output]

```tsx
import { AudioScrubPlayer } from '@/components/audio-scrub-player';
import { useSynthesizeSpeech } from '@localmode/react';
import { transformers } from '@localmode/transformers';

export function Speak({ text }: { text: string }) {
  const { data, execute } = useSynthesizeSpeech({
    model: transformers.textToSpeech('onnx-community/Kokoro-82M-v1.0-ONNX'),
  });

  return (
    <>
      <button onClick={() => execute(text)}>Synthesize</button>
      {data && <AudioScrubPlayer audio={data.audio} />}
    </>
  );
}
```

Use the standalone ScrubBar [#use-the-standalone-scrubbar]

```tsx
import { ScrubBar } from '@/components/audio-scrub-player';

<ScrubBar currentTime={time} duration={duration} onSeek={setTime} />
```

Customization [#customization]

`AudioScrubPlayer` owns its `<audio>` and reads `duration` / `currentTime` from the media events, so it works with any decodable Blob or URL. `ScrubBar` is controlled (pointer + keyboard, with `ArrowLeft`/`ArrowRight` for ±5s) — drop it into your own player shell if you need a different layout. The progress fill uses `bg-primary`; the thumb uses `border-primary` / `bg-background`.

# Mic Selector

Mic Selector [#mic-selector]

**Mic Selector** is a microphone input-device picker with permission handling and device enumeration. It is fully offline — it uses only the browser device APIs (`getUserMedia` for the one-time permission prompt, `enumerateDevices` for the list, and a `devicechange` listener to stay current). Selecting a device emits its `deviceId`, which flows straight into [`useVoiceRecorder({ deviceId })`](https://localmode.dev/docs/react) — the recorder requests `{ deviceId: { exact } }`, so the selected microphone is actually used (recording errors rather than silently falling back when the device is unavailable).

Pairs with [`useVoiceRecorder` / `useLiveTranscribe`](https://localmode.dev/docs/react), `VoiceButton`, and `VoiceOrb`.

**When to use it:** let users choose which microphone feeds a voice agent or transcription pipeline.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/audio/mic-selector`

Full source: https://localmode.ai/r/ui/audio/mic-selector.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/audio/mic-selector
```

Data source & dependencies [#data-source--dependencies]

**Data source:** enumerates devices via the browser `MediaDevices` API and emits the chosen `deviceId` — works with any backend. Recommended consumer: feed it into `useVoiceRecorder({ deviceId })` (pairs with `useLiveTranscribe`) from `@localmode/react` (on-device, optional).

* `clsx` + `tailwind-merge` — via the shared `cn()` util
* No external dependency — browser `MediaDevices` API only

Files installed [#files-installed]

* `mic-selector.tsx` — the component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**MicSelector**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | — | Selected device id (controlled). |
| `onValueChange` | `function` | — | Fired with the chosen device id. |
| `label` | `string` | `"Microphone"` | Accessible label. |

Examples [#examples]

Route the chosen device into a recorder [#route-the-chosen-device-into-a-recorder]

```tsx
import { MicSelector } from '@/components/mic-selector';
import { useVoiceRecorder } from '@localmode/react';

export function Capture() {
  const [deviceId, setDeviceId] = useState('');
  const recorder = useVoiceRecorder(deviceId ? { deviceId } : undefined);

  return (
    <div className="flex items-center gap-2">
      <MicSelector value={deviceId} onValueChange={setDeviceId} />
      <button onClick={recorder.startRecording}>Start</button>
    </div>
  );
}
```

`useVoiceRecorder` forwards `deviceId` to `getUserMedia` as `{ deviceId: { exact: deviceId } }` and surfaces a failure on `recorder.error` instead of silently recording from the wrong microphone. While recording, `recorder.stream` exposes the live `MediaStream` and `recorder.getVolume()` returns the RMS input level for meters.

Customization [#customization]

Device labels are empty until permission is granted — the component shows an "Allow microphone" button until then, and surfaces a "Permission denied" message on rejection. It releases the mic immediately after reading labels (it only needs permission, not a live stream). The `devicechange` listener keeps the list current when devices are plugged/unplugged.

# Streaming Speech Panel

Streaming Speech Panel [#streaming-speech-panel]

**Streaming Speech Panel** visualizes a streaming text-to-speech run. While synthesis or playback is active it shows a waveform + spinner, a synthesizing/playing label, the processed-clause count, and the current clause in a highlighted "now playing" box. When the stream completes it shows the clause-count summary, a "generated locally" privacy note, and a Download WAV action.

Drive it from [`useStreamSpeech()`](https://localmode.dev/docs/react) (`isSynthesizing`, `isPlaying`, `currentClause`, `clauses`) and wire `onDownload` to `downloadBlob`.

**When to use it:** give live feedback during clause-by-clause Kokoro streaming and offer a one-click WAV export.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/audio/streaming-speech-panel`

Full source: https://localmode.ai/r/ui/audio/streaming-speech-panel.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/audio/streaming-speech-panel
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders the streaming-TTS state you pass and emits `onDownload` — works with any backend. Recommended producer: `useStreamSpeech` (with the Kokoro TTS model from `@localmode/transformers`) from `@localmode/react` (on-device, optional); wire `onDownload` to your own download handler (e.g. the `downloadBlob` helper).

* `clsx` + `tailwind-merge` — via the shared `cn()` util

Files installed [#files-installed]

* `streaming-speech-panel.tsx` — the component
* `waveform-activity-bars.tsx` — the active-state indicator (registry dependency)
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**StreamingSpeechPanel**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `isSynthesizing` | `boolean` | — | **Required.** True while clauses are being synthesized. |
| `isPlaying` | `boolean` | — | **Required.** True while synthesized clauses are playing. |
| `currentClause` | `object \| null` | — | **Required.** The clause currently being played, or `null`. |
| `clauses` | `array` | — | **Required.** All clauses observed so far during the active stream. |
| `onDownload` | `function` | — | Fired when the user clicks "Download WAV" in the finished state. Wire this to `downloadBlob(wavBlob, 'speech.wav')`. Omit to hide the download action. |

Examples [#examples]

Wired to useStreamSpeech [#wired-to-usestreamspeech]

```tsx
import { StreamingSpeechPanel } from '@/components/streaming-speech-panel';
import { useStreamSpeech, downloadBlob } from '@localmode/react';
import { transformers } from '@localmode/transformers';

export function Reader({ text }: { text: string }) {
  const speech = useStreamSpeech({
    model: transformers.textToSpeech('onnx-community/Kokoro-82M-v1.0-ONNX'),
    voice: 'af_heart',
  });

  return (
    <>
      <button onClick={() => speech.speak(text)}>Read aloud</button>
      <StreamingSpeechPanel
        isSynthesizing={speech.isSynthesizing}
        isPlaying={speech.isPlaying}
        currentClause={speech.currentClause}
        clauses={speech.clauses}
        onDownload={() => downloadBlob(wavBlob, 'speech.wav')}
      />
    </>
  );
}
```

Customization [#customization]

The panel renders three states — active, finished, and ready — driven entirely by the `isSynthesizing` / `isPlaying` / `clauses` props. The privacy note is plain text in the copied file; reword it to match your product voice. The Download action only fires `onDownload`; assemble the WAV from the streamed clauses (or capture the played audio) on your side and call `downloadBlob`.

# Synced Transcript Viewer

Synced Transcript Viewer [#synced-transcript-viewer]

**Synced Transcript Viewer** plays local audio and highlights each word in lockstep with playback using word-level alignment timestamps. The playback-time → word-index mapping is pure client-side (binary search on the `timeupdate` position). Clicking a word seeks the audio to its start.

Feed `words` from [`useTranscribe`](https://localmode.dev/docs/react) with `returnTimestamps: 'word'` (segments arrive on `data.segments`) and `audio` from the same local recording / TTS Blob.

**When to use it:** a read-along transcript for a meeting recording, podcast, or voice note where users want to follow — and jump around in — the audio.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/audio/synced-transcript-viewer`

Full source: https://localmode.ai/r/ui/audio/synced-transcript-viewer.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/audio/synced-transcript-viewer
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders the `words` (with timestamps) + `audio` you pass — works with any backend. Recommended producer: `useTranscribe({ returnTimestamps: 'word' })` (with the Whisper STT model from `@localmode/transformers`) from `@localmode/react` (on-device, optional).

* `@localmode/ui/lib/browser-utils` — `useObjectUrl` for Blob lifecycle (installed automatically as a registry dependency)
* `clsx` + `tailwind-merge` — via the shared `cn()` util

Files installed [#files-installed]

* `synced-transcript-viewer.tsx` — the component
* `lib/browser-utils.ts` — generic browser helpers (`useObjectUrl`)
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**SyncedTranscriptViewer**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `words` | `array` | — | **Required.** The time-aligned words to render. |
| `audio` | `object \| string` | — | Local audio to play — a `Blob` (e.g. a recording) or URL. Optional: when omitted, drive the highlight externally via {@link SyncedTranscriptViewerProps.activeIndex}. |
| `activeIndex` | `number` | — | Controlled active-word index. When provided (not `undefined`), it OVERRIDES the internal audio-`currentTime`-derived index — e.g. driven by streaming STT progress or TTS boundary events. Use `-1` for no highlighted word. |
| `onSeekWord` | `function` | — | Called when a word is clicked (when no `audio` is provided). Wire this to seek your external driver (e.g. re-speak from that word). |

Examples [#examples]

Read-along from a transcription [#read-along-from-a-transcription]

```tsx
import { SyncedTranscriptViewer, type TimedWord } from '@/components/synced-transcript-viewer';
import { useTranscribe } from '@localmode/react';
import { transformers } from '@localmode/transformers';

export function ReadAlong({ audio }: { audio: Blob }) {
  const { data, execute } = useTranscribe({
    model: transformers.speechToText('onnx-community/whisper-base'),
    returnTimestamps: 'word',
  });

  // Word-level segments arrive on data.segments — map them into TimedWord[].
  const words: TimedWord[] = (data?.segments ?? []).map((s) => ({
    text: s.text,
    start: s.start,
    end: s.end,
  }));

  return (
    <>
      <button onClick={() => execute(audio)}>Transcribe</button>
      {words.length > 0 && <SyncedTranscriptViewer words={words} audio={audio} />}
    </>
  );
}
```

`returnTimestamps` can also be overridden per call: `execute(audio, { returnTimestamps: 'word' })`.

Customization [#customization]

The active-word lookup is a binary search over `start` times, so it stays cheap for long transcripts. Past / active / upcoming words get distinct classes (`text-foreground`, `bg-primary text-primary-foreground`, `text-muted-foreground`) — restyle them in the copied file. If your timestamps are segment-level rather than per-word, split each segment's text across its `[start, end]` window before passing it in.

# Transcribed Note Card

Transcribed Note Card [#transcribed-note-card]

**Transcribed Note Card** is a list item that pairs transcribed text with inline audio playback. It has two variants from one component:

* **Placeholder** (`transcribing`) — a waveform row + a "Transcribing…" label, the canonical loading state for a `useOperationList`-backed STT list where items stream in.
* **Populated** — a relative timestamp (hover → absolute), the transcript body, a native `<audio>` footer, and a hover-revealed delete.

Drive it from [`useTranscribe`](https://localmode.dev/docs/react) + `useOperationList`.

**When to use it:** render a growing list of voice notes / meeting snippets where each item starts as a placeholder and morphs into the finished transcription.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/audio/transcribed-note-card`

Full source: https://localmode.ai/r/ui/audio/transcribed-note-card.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/audio/transcribed-note-card
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders the transcript text + audio Blob you pass — works with any backend. Recommended producer: `useTranscribe` + `useOperationList` (with the Whisper STT model from `@localmode/transformers`) from `@localmode/react` (on-device, optional).

* `@localmode/ui/lib/browser-utils` — `useObjectUrl` for Blob lifecycle (installed automatically as a registry dependency)
* `clsx` + `tailwind-merge` — via the shared `cn()` util

Files installed [#files-installed]

* `transcribed-note-card.tsx` — the component
* `waveform-activity-bars.tsx` — the placeholder indicator (registry dependency)
* `lib/browser-utils.ts` — generic browser helpers (`useObjectUrl`)
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**TranscribedNoteCard**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `transcribing` | `boolean` | — | When true, render the "transcribing…" placeholder (waveform + label) instead of the populated card. Flip to false once `useTranscribe` resolves. |
| `text` | `string` | — | The transcribed text (shown once `transcribing` is false). |
| `timestamp` | `object` | — | When the note was created — shown as relative time, absolute on hover. |
| `audio` | `object \| string \| null` | — | Local audio for inline playback (a `Blob` or object URL). |
| `onDelete` | `function` | — | Fired when the hover-revealed delete control is clicked. Omit to hide it. |

Examples [#examples]

A streaming transcription list [#a-streaming-transcription-list]

```tsx
import { TranscribedNoteCard } from '@/components/transcribed-note-card';
import { useOperationList, useVoiceRecorder } from '@localmode/react';
import { transcribe } from '@localmode/core';
import { transformers } from '@localmode/transformers';

export function VoiceNotes() {
  const recorder = useVoiceRecorder();
  const { items, isLoading, execute, removeItem } = useOperationList({
    fn: (audio: Blob, signal) =>
      transcribe({ model: transformers.speechToText('onnx-community/whisper-base'), audio, abortSignal: signal }),
    transform: (result, audio) => ({ id: crypto.randomUUID(), text: result.text, audio, timestamp: new Date() }),
  });

  return (
    <div className="flex flex-col gap-3">
      {isLoading && <TranscribedNoteCard transcribing />}
      {items.map((note) => (
        <TranscribedNoteCard
          key={note.id}
          text={note.text}
          audio={note.audio}
          timestamp={note.timestamp}
          onDelete={() => removeItem((n) => n.id === note.id)}
        />
      ))}
    </div>
  );
}
```

Customization [#customization]

The relative-time formatter lives in the copied file — swap it for your own (or a library) if you need finer granularity. The delete control is hover-revealed via `group-hover`; remove the `opacity-0` classes to keep it always visible. Pass either a `Blob` or an object-URL string for `audio`.

# Voice Button

Voice Button [#voice-button]

**Voice Button** is a press-to-record / release-to-transcribe push-to-talk control with an explicit visual state machine: `idle → recording` (animated pulse rings + live waveform) `→ processing` (loader) `→ success` / `error`. Recording is the app's job ([`useVoiceRecorder`](https://localmode.dev/docs/react) → `getUserMedia` / `MediaRecorder`); transcription routes to local Whisper ([`useTranscribe`](https://localmode.dev/docs/react)). This component renders the state and emits press/release events.

**When to use it:** a single hands-on-keyboard (or touch) affordance to capture and transcribe a short spoken phrase — search-by-voice, quick notes, command input.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/audio/voice-button`

Full source: https://localmode.ai/r/ui/audio/voice-button.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/audio/voice-button
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders the recording state you pass and emits press/release events — works with any backend. Recommended producer: `useVoiceRecorder` (recording, `deviceId` selection, live `getVolume()`) + `useTranscribe` (with the Whisper STT model from `@localmode/transformers`) from `@localmode/react` (on-device, optional).

* `clsx` + `tailwind-merge` — via the shared `cn()` util

Files installed [#files-installed]

* `voice-button.tsx` — the component
* `waveform-activity-bars.tsx` — the in-button recording waveform (registry dependency)
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**VoiceButton**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `state` | `VoiceButtonState` | — | **Required.** The current state in the push-to-talk machine. Controlled by the app: `idle → recording` on press, `processing` while Whisper runs, then `success`/`error`. |
| `onStart` | `function` | — | Fired when the user presses to start recording (from `idle`). |
| `onStop` | `function` | — | Fired when the user releases / clicks to stop recording. |
| `volume` | `number` | — | Live mic volume in `[0, 1]` for the in-button waveform during recording. Wire it to `useVoiceRecorder().getVolume()` sampled in a `requestAnimationFrame` loop (or any local `AnalyserNode` source). |
| `label` | `string` | — | Label shown next to the icon. Defaults to a state-appropriate string. |
| `size` | `number` | `56` | Diameter in pixels. |

Examples [#examples]

Push-to-talk with local Whisper [#push-to-talk-with-local-whisper]

```tsx
import { VoiceButton, type VoiceButtonState } from '@/components/voice-button';
import { useVoiceRecorder, useTranscribe } from '@localmode/react';
import { transformers } from '@localmode/transformers';

export function VoiceSearch({ onResult }: { onResult: (text: string) => void }) {
  const [state, setState] = useState<VoiceButtonState>('idle');
  const [volume, setVolume] = useState(0);
  const recorder = useVoiceRecorder();
  const stt = useTranscribe({ model: transformers.speechToText('onnx-community/whisper-base') });

  // Sample the live mic level while recording to drive the in-button waveform.
  useEffect(() => {
    if (!recorder.isRecording) return;
    let raf = requestAnimationFrame(function tick() {
      setVolume(recorder.getVolume());
      raf = requestAnimationFrame(tick);
    });
    return () => cancelAnimationFrame(raf);
  }, [recorder.isRecording]);

  return (
    <VoiceButton
      state={state}
      volume={volume}
      onStart={() => { setState('recording'); recorder.startRecording(); }}
      onStop={async () => {
        setState('processing');
        const blob = await recorder.stopRecording();
        const res = blob ? await stt.execute(blob) : null;
        if (res) { onResult(res.text); setState('success'); } else { setState('error'); }
        setTimeout(() => setState('idle'), 1500);
      }}
    />
  );
}
```

Customization [#customization]

The button is fully controlled — you own the `state` and decide when to advance the machine. The recording state shows the in-button `WaveformActivityBars`; pass `volume` (0..1) from `useVoiceRecorder().getVolume()` (sampled in a `requestAnimationFrame` loop, as above) to make it react to real mic loudness — no hand-rolled `AnalyserNode` needed. State colors use `bg-primary` / `bg-destructive` / `bg-emerald-600` — swap in the copied file to match your tokens.

# Voice Comparison Panel

Voice Comparison Panel [#voice-comparison-panel]

**Voice Comparison Panel** is an A/B voice comparison surface. Two labeled columns each carry a language-grouped voice select and a native `<audio>` player (shown once audio is set), plus a shared comparison textarea and a Compare button with a loading state.

Wire `onCompare` to synthesize the shared text through both voices — one `useSynthesizeSpeech` hook, two `execute(text, { voice })` calls — and pass the resulting Blobs back via `columnA.audio` / `columnB.audio`.

**When to use it:** let users hear the same line in two Kokoro voices side by side before choosing one.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/audio/voice-comparison-panel`

Full source: https://localmode.ai/r/ui/audio/voice-comparison-panel.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/audio/voice-comparison-panel
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders the two voice columns + audio Blobs you pass and emits `onCompare` — works with any backend. Recommended producer: `useSynthesizeSpeech` (per-call `{ voice }` overrides, with the Kokoro TTS model + voice catalog from `@localmode/transformers`) from `@localmode/react` (on-device, optional).

* `@localmode/ui/lib/browser-utils` — `useObjectUrl` for Blob lifecycle (installed automatically as a registry dependency)
* `clsx` + `tailwind-merge` — via the shared `cn()` util

Files installed [#files-installed]

* `voice-comparison-panel.tsx` — the component
* `voice-picker.tsx` — the language-grouped select used in each column (registry dependency)
* `lib/browser-utils.ts` — generic browser helpers (`useObjectUrl`)
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**VoiceComparisonPanel**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `voices` | `array` | — | **Required.** The voices available in both column pickers. |
| `columnA` | `object` | — | **Required.** State for column A. |
| `columnB` | `object` | — | **Required.** State for column B. |
| `onVoiceAChange` | `function` | — | Fired when column A's voice changes. |
| `onVoiceBChange` | `function` | — | Fired when column B's voice changes. |
| `text` | `string` | — | **Required.** The shared comparison text. |
| `onTextChange` | `function` | — | Fired when the shared text changes. |
| `onCompare` | `function` | — | Fired when Compare is clicked — synthesize both columns from `text`. |
| `loading` | `boolean` | — | True while a comparison is synthesizing (disables Compare, shows loader). |
| `labels` | `[string, string]` | `["Voice A", "Voice B"]` | Labels for the two columns. |

Examples [#examples]

Compare two voices [#compare-two-voices]

```tsx
import { VoiceComparisonPanel } from '@/components/voice-comparison-panel';
import { useSynthesizeSpeech } from '@localmode/react';
import { transformers, KOKORO_VOICES } from '@localmode/transformers';

export function Compare() {
  const [a, setA] = useState('af_heart');
  const [b, setB] = useState('am_adam');
  const [text, setText] = useState('Run models entirely in your browser.');
  const [audioA, setAudioA] = useState<Blob | null>(null);
  const [audioB, setAudioB] = useState<Blob | null>(null);
  const [loading, setLoading] = useState(false);

  const tts = useSynthesizeSpeech({ model: transformers.textToSpeech('onnx-community/Kokoro-82M-v1.0-ONNX') });

  const compare = async () => {
    setLoading(true);
    // One hook, two per-call voice overrides (sequential — TTS runs one at a time).
    const ra = await tts.execute(text, { voice: a });
    const rb = await tts.execute(text, { voice: b });
    setAudioA(ra?.audio ?? null);
    setAudioB(rb?.audio ?? null);
    setLoading(false);
  };

  return (
    <VoiceComparisonPanel
      voices={KOKORO_VOICES}
      columnA={{ voiceId: a, audio: audioA }}
      columnB={{ voiceId: b, audio: audioB }}
      onVoiceAChange={setA}
      onVoiceBChange={setB}
      text={text}
      onTextChange={setText}
      onCompare={compare}
      loading={loading}
    />
  );
}
```

Customization [#customization]

Each column accepts a `Blob` or an object-URL string for `audio`; the component manages the object-URL lifecycle when given a Blob. Relabel the columns via `labels`. Add more columns by composing additional `VoicePicker` + `<audio>` pairs in the copied file.

# Voice Orb

Voice Orb [#voice-orb]

**Voice Orb** is an animated canvas visualizer for voice agents. It reflects discrete agent states (`idle` / `connecting` / `listening` / `thinking` / `speaking` / `muted`) and reacts to input/output audio volume through `getInputVolume()` / `getOutputVolume()` callbacks. Visual state is fully decoupled from the audio source — the orb reads volume through the callbacks, which you can feed from [`useVoiceRecorder().getVolume()`](https://localmode.dev/docs/react) (mic input) or a Web Audio `AnalyserNode` (e.g. on the TTS output node).

Drive `state` from [`useLiveTranscribe()` / `useTurnTaker()`](https://localmode.dev/docs/react) and `getInputVolume` from `useVoiceRecorder().getVolume()`.

**When to use it:** the centerpiece of a hands-free voice-agent UI, showing the agent's state and "loudness" at a glance.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/audio/voice-orb`

Full source: https://localmode.ai/r/ui/audio/voice-orb.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/audio/voice-orb
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders the `state` you pass and reads volume through callbacks — works with any backend. Recommended producer: `useLiveTranscribe` / `useTurnTaker` for agent state and `useVoiceRecorder().getVolume()` for input volume from `@localmode/react` (on-device, optional).

* `clsx` + `tailwind-merge` — via the shared `cn()` util
* No external visualizer dependency — pure Canvas 2D

Files installed [#files-installed]

* `voice-orb.tsx` — the component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**VoiceOrb**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `state` | `"muted" \| "speaking" \| "thinking" \| "listening" \| "connecting" \| "idle"` | `"idle"` | The current agent state. Drives the orb's base animation independently of any audio source. |
| `getInputVolume` | `function` | — | Returns the current input (microphone) volume in `[0, 1]`. Called on every animation frame. Wire it to `useVoiceRecorder().getVolume()` (or a local Web Audio `AnalyserNode` over `getUserMedia`) so the listening state pulses with real mic loudness. The orb never touches the audio source itself. |
| `getOutputVolume` | `function` | — | Returns the current output (agent speech) volume in `[0, 1]`. Drives the speaking state. Wire it to an `AnalyserNode` on the TTS output node. |
| `size` | `number` | `128` | Diameter in pixels. |
| `color` | `string` | `"var(--primary)"` | Core color (CSS color). |
| `glowColor` | `string` | `same as `color`` | Outer gradient/glow color (CSS color). |

Examples [#examples]

Driven by the recorder's live volume [#driven-by-the-recorders-live-volume]

```tsx
import { VoiceOrb } from '@/components/voice-orb';
import { useVoiceRecorder } from '@localmode/react';

export function Agent({ state }: { state: 'listening' | 'speaking' | 'idle' }) {
  const recorder = useVoiceRecorder();

  // The orb polls getInputVolume() on every animation frame; getVolume()
  // returns the live RMS input level in [0, 1] while recording (0 otherwise).
  return (
    <>
      <button onClick={recorder.isRecording ? () => recorder.stopRecording() : recorder.startRecording}>
        {recorder.isRecording ? 'Stop' : 'Listen'}
      </button>
      <VoiceOrb state={state} getInputVolume={recorder.getVolume} />
    </>
  );
}
```

For the speaking state, feed `getOutputVolume` from an `AnalyserNode` on your TTS output node — the agent's speech is not a microphone stream, so the recorder doesn't cover it.

Customization [#customization]

The orb draws to a single canvas; tune the per-state pulse speed and base radius in `STATE_CONFIG`, or swap the radial gradient for your brand colors via `color` / `glowColor` (both accept CSS `var(--…)` tokens, resolved against the live canvas). Because volume comes through callbacks, the orb never touches your audio graph — point it at input, output, or any custom amplitude source.

# Voice Picker

Voice Picker [#voice-picker]

**Voice Picker** is TTS voice selection from one data contract. Ships three pieces:

* `VoicePicker` — a compact `<select>` partitioned into `<optgroup>` by language, each option showing the voice name + a gender glyph.
* `VoiceCard` — a rich card: voice name, color-coded gender badge, monospace voice id, and a circular play/stop preview button with a loading state.
* `VoiceGrid` — language-grouped grid of cards with a count header and a search box.

All three consume one `VoiceOption[]` contract (`id`, `name`, `gender`, `languageLabel`), which matches the `KokoroVoice` shape from `@localmode/transformers` (29 English voices).

**When to use it:** let users pick — and preview — a Kokoro voice before synthesizing, in either a compact (select) or rich (grid) surface.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/audio/voice-picker`

Full source: https://localmode.ai/r/ui/audio/voice-picker.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/audio/voice-picker
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders the `VoiceOption[]` you pass and emits selection/preview events — works with any backend. Recommended producer: `useSynthesizeSpeech` for inline preview (`execute(text, { voice })` overrides the voice per call) with the Kokoro TTS model + `KOKORO_VOICES` catalog from `@localmode/transformers`, via `@localmode/react` (on-device, optional).

* `clsx` + `tailwind-merge` — via the shared `cn()` util

Files installed [#files-installed]

* `voice-picker.tsx` — `VoicePicker`, `VoiceCard`, `VoiceGrid`
* `waveform-activity-bars.tsx` — used by the preview button's loading state (registry dependency)
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**VoicePicker**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `voices` | `array` | — | **Required.** The voices to choose from. |
| `value` | `string` | — | Currently selected voice id. |
| `onValueChange` | `function` | — | Fired with the chosen voice id. |
| `disabled` | `boolean` | — | Disable the control. |
| `label` | `string` | `"Voice"` | Accessible label. |

**VoiceGrid**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `voices` | `array` | — | **Required.** The voices to render as cards. |
| `value` | `string` | — | Currently selected voice id. |
| `onValueChange` | `function` | — | Fired when a card is selected. |
| `onPreview` | `function` | — | Fired when a card's preview is pressed. |
| `loadingVoiceId` | `string \| null` | — | The voice id currently synthesizing a preview. |
| `playingVoiceId` | `string \| null` | — | The voice id currently playing a preview. |
| `filterable` | `boolean` | `true` | When true, show a search box that filters voices by name / id. |

**VoiceCard**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `voice` | `object` | — | **Required.** The voice this card represents. |
| `selected` | `boolean` | — | Whether this card is the selected voice. |
| `onSelect` | `function` | — | Fired when the card body is clicked (selection). |
| `onPreview` | `function` | — | Fired when the preview button is pressed. Receives the voice id; the app synthesizes a local sample (e.g. via `useSynthesizeSpeech`). Omit to hide the preview button. |
| `loading` | `boolean` | — | True while this voice's preview is being synthesized. |
| `playing` | `boolean` | — | True while this voice's preview is playing (toggles to a stop affordance). |

Examples [#examples]

Compact select [#compact-select]

```tsx
import { VoicePicker } from '@/components/voice-picker';
import { KOKORO_VOICES } from '@localmode/transformers';

export function Example() {
  const [voice, setVoice] = useState('af_heart');
  return <VoicePicker voices={KOKORO_VOICES} value={voice} onValueChange={setVoice} />;
}
```

Grid with local preview [#grid-with-local-preview]

```tsx
import { VoiceGrid } from '@/components/voice-picker';
import { useSynthesizeSpeech } from '@localmode/react';
import { transformers, KOKORO_VOICES } from '@localmode/transformers';

export function VoiceBrowser() {
  const [voice, setVoice] = useState<string>();
  const [previewing, setPreviewing] = useState<string | null>(null);
  const tts = useSynthesizeSpeech({ model: transformers.textToSpeech('onnx-community/Kokoro-82M-v1.0-ONNX') });

  const preview = async (id: string) => {
    setPreviewing(id);
    const res = await tts.execute('Hello from LocalMode.', { voice: id }); // per-call voice override
    if (res) new Audio(URL.createObjectURL(res.audio)).play();
    setPreviewing(null);
  };

  return (
    <VoiceGrid
      voices={KOKORO_VOICES}
      value={voice}
      onValueChange={setVoice}
      onPreview={preview}
      loadingVoiceId={previewing}
    />
  );
}
```

`useSynthesizeSpeech` accepts `voice` / `speed` / `pitch` at the hook level and per call — `execute(text, { voice })` is what makes inline per-voice previews possible from a single hook instance.

Customization [#customization]

Voices are grouped by `languageLabel`, so any provider that exposes that field groups correctly. Gender badge colors use Tailwind's `pink` / `sky` palettes — swap them in the copied file to match your design system. The grid's search filters on `name` and `id`; widen the predicate in `VoiceGrid` if you add more searchable metadata.

Accessibility [#accessibility]

A `VoiceCard` exposes its preview and selection as **two distinct sibling buttons** — it never nests an interactive element inside another (no `<button>` inside a `role="button"` card), which would be an invalid, non-operable a11y tree. The optional preview button plays a locally-synthesized sample; the selection button is labelled `"Select {name}"` and announces its state with `aria-pressed`, so screen readers convey which voice is active and both actions are independently focusable and keyboard-operable.

# Waveform Activity Bars

Waveform Activity Bars [#waveform-activity-bars]

**Waveform Activity Bars** render a row of narrow vertical bars with a staggered, sinusoid-derived pulse. It needs no audio data — use it as an "active processing" cue, an idle empty-state illustration, or (with an explicit `state` + a `volume` callback) a voice-agent visualizer that reacts to live microphone or output loudness.

The required `@keyframes` ships inside the component (injected once into `document.head`), so it animates standalone after `shadcn add`.

**When to use it:** show that STT/TTS is working (`useTranscribe` / `useStreamSpeech` / `useVoiceRecorder` activity), fill an empty audio surface, or visualize agent states (connecting / listening / thinking / speaking).

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/audio/waveform-activity-bars`

Full source: https://localmode.ai/r/ui/audio/waveform-activity-bars.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/audio/waveform-activity-bars
```

Dependencies [#dependencies]

* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)
* No external audio dependency — it is pure CSS

Files installed [#files-installed]

* `waveform-activity-bars.tsx` — the component (bundles its keyframe)
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**WaveformActivityBars**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `barCount` | `number` | `5` | Number of vertical bars to render. When a `state` is set and this is omitted, each state picks a distinct count (e.g. fewer for `idle`, more for `speaking`); an explicit value always wins. |
| `active` | `boolean` | `true` | When true, bars animate with a staggered pulse; when false they render as a static idle illustration. Ignored when an explicit `state` is set. |
| `state` | `"playback" \| "record" \| "speaking" \| "thinking" \| "listening" \| "connecting" \| "idle"` | — | Explicit agent / processing state. Takes precedence over `active` and lets the same component double as a voice-agent visualizer. |
| `color` | `string` | `"var(--primary)"` | Bar color. Any CSS color. When a `state` is set and this is omitted, each state uses a semantic color (muted for `idle`/`connecting`, primary for `listening`, amber for `thinking`, emerald for `speaking`); an explicit value always wins. Defaults to the theme's primary token when no `state`. |
| `height` | `number` | `24` | Max bar height in pixels (the row height). |
| `volume` | `number` | — | Optional live volume in the `[0, 1]` range. When provided the bars scale to the measured amplitude, decoupling the visual from any specific audio source — feed it from a Web Audio `AnalyserNode` (`getInputVolume()` / `getOutputVolume()`). |
| `label` | `string` | `"audio activity"` | Accessible label for the row. |

Examples [#examples]

Active processing indicator [#active-processing-indicator]

```tsx
import { WaveformActivityBars } from '@/components/waveform-activity-bars';

export function Example() {
  return <WaveformActivityBars active />;
}
```

Driven by a transcription hook [#driven-by-a-transcription-hook]

```tsx
import { WaveformActivityBars } from '@/components/waveform-activity-bars';
import { useTranscribe } from '@localmode/react';

export function TranscribeIndicator({ model }) {
  const { isLoading } = useTranscribe({ model });
  return <WaveformActivityBars active={isLoading} />;
}
```

Voice-agent state + live volume [#voice-agent-state--live-volume]

```tsx
// Feed `volume` (0..1) from useVoiceRecorder().getVolume() — sample it in a
// requestAnimationFrame loop while recording (or use any AnalyserNode source).
<WaveformActivityBars state="listening" volume={recorder.getVolume()} />
```

Customization [#customization]

The bars are positioned with Tailwind utilities and colored via the `color` prop (defaults to `var(--primary)`), so they inherit your theme. The pulse keyframe (`lm-waveform-pulse`) is injected once; if you prefer it in your global stylesheet, move the `KEYFRAME_CSS` block into `globals.css` and delete the injection effect from the copied file.

When a `volume` is supplied the component switches from time-based animation to amplitude-based scaling — the bars track measured loudness instead of wall-clock time, keeping the visual decoupled from the audio source.

# Actions

Actions [#actions]

The **Actions** primitives are message-level controls. `Actions` is the row (with optional hover-reveal); `Action` is an accessible icon button with a tooltip; `CopyAction` handles clipboard + copied state; `RegenerateAction` and `ReadAloudAction` (wire to local Kokoro TTS) cover common cases; `ActionsMenu` groups secondary actions behind a "more" menu; and `FeedbackBar` is an on-device thumbs up/down that stays local — no telemetry.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/conversation/actions`

Full source: https://localmode.ai/r/ui/conversation/actions.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/conversation/actions
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders plain props and emits callbacks (`onRegenerate`, read-aloud) — works with any backend. Recommended producer: your chat + `useSynthesizeSpeech` from `@localmode/react` (on-device, optional).

* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `actions.tsx` — `Actions`, `Action`, `CopyAction`, `RegenerateAction`, `ReadAloudAction`, `ActionsMenu`, `FeedbackBar`
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**CopyAction**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `text` | `string` | — | **Required.** Text to copy to the clipboard. |
| `label` | `string` | `"Copy"` | Tooltip label. |
| `variant` | `"ghost" \| "secondary" \| "outline" \| "destructive" \| "default" \| "link" \| null` | — | — |
| `size` | `"icon-lg" \| "icon-sm" \| "icon-xs" \| "icon" \| "lg" \| "sm" \| "xs" \| "default" \| null` | — | — |
| `asChild` | `boolean` | — | — |

Examples [#examples]

A message action row [#a-message-action-row]

```tsx
import { Actions, CopyAction, FeedbackBar, RegenerateAction } from '@/components/actions';

<Actions hoverReveal>
  <CopyAction text={message.text} />
  <RegenerateAction onRegenerate={() => regenerate(message.id)} />
  <FeedbackBar onFeedback={(v) => saveFeedbackLocally(message.id, v)} />
</Actions>
```

Customization [#customization]

`Action` wraps a `TooltipProvider` so it works standalone. `FeedbackBar` reports via callback only — persist it to local IndexedDB if you want it to survive reloads. Read-aloud is presentational: drive `onReadAloud` from `useSynthesizeSpeech`.

These primitives are presentational and hook-driven: they render props and emit callbacks, holding only local view state. The orchestration state (e.g. `useChat`) lives in your app. Every surface uses shadcn/ui CSS-variable utilities, so it inherits your theme — restyle the copied file freely.

# Agent Step Timeline

Agent Step Timeline [#agent-step-timeline]

The **AgentStepTimeline** is a vertical timeline of ReAct agent steps. Each step is a collapsible card (color-coded tool badge via an optional `toolColorMap`, formatted args, observation with show-more, index, elapsed-ms). A `finish` step renders a success-styled final-answer card; the timeline auto-scrolls, shows a "Thinking…" row while running, and a terminal finish-reason badge (`max_steps` / `timeout` / `loop_detected` / `error`). It supports nested sub-agent/handoff rendering. Data source: `useAgent`.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/conversation/agent-step-timeline`

Full source: https://localmode.ai/r/ui/conversation/agent-step-timeline.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/conversation/agent-step-timeline
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders the agent-step shape (`steps`, `isRunning`, run result) you pass — works with any backend. Recommended producer: `useAgent` from `@localmode/react` (on-device, optional).

* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `agent-step-timeline.tsx` — `AgentStepTimeline` + `AgentStepCard`
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**AgentStepTimeline**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `steps` | `array` | — | **Required.** The agent steps (e.g. `useAgent().steps`). |
| `isRunning` | `boolean` | — | Whether the agent loop is still running (e.g. `useAgent().isRunning`). |
| `finishReason` | `"error" \| "aborted" \| "loop_detected" \| "timeout" \| "max_steps" \| "finish"` | — | Terminal reason once the run ends. |
| `toolColorMap` | `ToolColorMap` | — | Optional per-tool badge colors. |
| `autoScroll` | `boolean` | `true` | Auto-scroll to the newest step while running. |

Examples [#examples]

Drive a live ReAct loop [#drive-a-live-react-loop]

```tsx
import { useAgent } from '@localmode/react';
import { AgentStepTimeline } from '@/components/agent-step-timeline';

const { steps, isRunning, result } = useAgent({ model, tools });

<AgentStepTimeline steps={steps} isRunning={isRunning} finishReason={result?.finishReason} />
```

Customization [#customization]

Pass a `toolColorMap` (`{ toolName: "tailwind classes" }`) to color tool badges. Each step may carry `subSteps` for nested sub-agent runs, which render indented inside the parent step.

These primitives are presentational and hook-driven: they render props and emit callbacks, holding only local view state. The orchestration state (e.g. `useAgent`) lives in your app. Every surface uses shadcn/ui CSS-variable utilities, so it inherits your theme — restyle the copied file freely.

Accessibility [#accessibility]

Each expandable step is a real disclosure: the toggle carries `aria-expanded` (reflecting open/closed) and, when open, `aria-controls` pointing at the revealed detail region's id, so assistive tech announces the collapse state and the relationship. Finish steps that have no collapsible body omit `aria-expanded` rather than exposing an inert toggle.

# Branch

Branch [#branch]

The **Branch** primitives page between alternative regenerated/edited assistant responses for a single turn. `Branch` holds the active index; `BranchMessages` shows only the active variant; `BranchSelector` groups `BranchPrevious` / `BranchPage` / `BranchNext` and hides itself when only one variant exists. It wraps an existing `Message` non-intrusively and is pure client state. Data source: `useChat` — `regenerate()` produces the variants, and `variants` / `variantIndex` / `setVariantIndex` drive the navigator directly.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/conversation/branch`

Full source: https://localmode.ai/r/ui/conversation/branch.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/conversation/branch
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders the variants/index you pass and emits index changes — works with any backend. Recommended producer: `useChat`'s `regenerate()` / `variants` / `variantIndex` / `setVariantIndex` from `@localmode/react` (on-device, optional).

* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `branch.tsx` — `Branch`, `BranchMessages`, `BranchSelector`, `BranchPrevious`, `BranchNext`, `BranchPage`
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**Branch**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `count` | `number` | — | **Required.** Number of variants for this turn. |
| `defaultIndex` | `number` | `last (count - 1)` | Default active variant index. |
| `index` | `number` | — | Controlled active index. |
| `onIndexChange` | `function` | — | Reports active-index changes. |

Examples [#examples]

Page between `useChat` variants [#page-between-usechat-variants]

```tsx
import { useChat } from '@localmode/react';
import {
  Branch, BranchMessages, BranchNext, BranchPage, BranchPrevious, BranchSelector,
} from '@/components/branch';
import { Message, MessageContent } from '@/components/message';

export function LastTurn({ model }) {
  const { regenerate, variants, variantIndex, setVariantIndex } = useChat({ model });

  return (
    <Branch
      count={variants.length}
      index={variantIndex}
      onIndexChange={setVariantIndex}
    >
      <BranchMessages>
        {variants.map((text, i) => (
          <Message key={i} role="assistant"><MessageContent content={text} /></Message>
        ))}
      </BranchMessages>
      <BranchSelector>
        <BranchPrevious /><BranchPage /><BranchNext />
      </BranchSelector>
      <button onClick={() => regenerate()}>Regenerate</button>
    </Branch>
  );
}
```

`useChat().regenerate()` re-runs the last turn and appends the new reply to `variants` (the original reply is frozen as `variants[0]` on first regeneration). Controlled `index={variantIndex}` / `onIndexChange={setVariantIndex}` keeps the navigator and the hook in sync — `setVariantIndex` also swaps the last assistant message's content, so the rest of your thread renders the active variant with zero changes.

Customization [#customization]

Branch state is local by default; pass controlled `index`/`onIndexChange` (e.g. `useChat`'s `variantIndex` / `setVariantIndex`) to persist the active variant alongside your thread state.

These primitives are presentational and hook-driven: they render props and emit callbacks, holding only local view state. The orchestration state (e.g. `useChat`) lives in your app. Every surface uses shadcn/ui CSS-variable utilities, so it inherits your theme — restyle the copied file freely.

# Chain of Thought

Chain of Thought [#chain-of-thought]

The **ChainOfThought** primitives render a structured step-by-step reasoning timeline (distinct from free-text `Reasoning`): discrete labeled steps with per-step status (complete / active / pending), custom icons, and nested content slots for embedded retrieved sources (`ChainOfThoughtSearchResults`) and images (`ChainOfThoughtImage`). It collapses to a single line on completion. It is presentational — you build the labeled steps and pass them in. A common producer is reasoning-mode generation (`<think>` content parsed from `useGenerateText`'s `text`) plus local RAG retrieval.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/conversation/chain-of-thought`

Full source: https://localmode.ai/r/ui/conversation/chain-of-thought.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/conversation/chain-of-thought
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders the labeled steps you pass — works with any backend. Recommended producer: reasoning-mode `<think>` content parsed from `useGenerateText`'s `text` in `@localmode/react`, mapped into steps yourself (on-device, optional).

* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `chain-of-thought.tsx` — `ChainOfThought`, `ChainOfThoughtHeader`, `ChainOfThoughtContent`, `ChainOfThoughtStep`, `ChainOfThoughtSearchResults`, `ChainOfThoughtSearchResult`, `ChainOfThoughtImage`
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**ChainOfThoughtStep**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | — | **Required.** Step label. |
| `status` | `"complete" \| "active" \| "pending"` | `"complete"` | Per-step status. |
| `icon` | `ReactNode` | — | Optional custom leading icon (overrides the status icon). |

Examples [#examples]

Itemized reasoning with sources [#itemized-reasoning-with-sources]

```tsx
import {
  ChainOfThought, ChainOfThoughtContent, ChainOfThoughtHeader,
  ChainOfThoughtSearchResult, ChainOfThoughtSearchResults, ChainOfThoughtStep,
} from '@/components/chain-of-thought';

<ChainOfThought done={!isStreaming}>
  <ChainOfThoughtHeader />
  <ChainOfThoughtContent>
    <ChainOfThoughtStep label="Search local docs" status="complete">
      <ChainOfThoughtSearchResults>
        <ChainOfThoughtSearchResult>handbook.pdf</ChainOfThoughtSearchResult>
      </ChainOfThoughtSearchResults>
    </ChainOfThoughtStep>
    <ChainOfThoughtStep label="Synthesize answer" status="active" />
  </ChainOfThoughtContent>
</ChainOfThought>
```

Customization [#customization]

Pass a custom `icon` per step to override the status glyph. Use `ChainOfThoughtImage` to embed a local image (e.g. a retrieved figure) inside a step. For free-text think tokens, use [Reasoning](/docs/conversation/reasoning) instead.

These primitives are presentational and hook-driven: they render props and emit callbacks, holding only local view state. The orchestration state (e.g. `useGenerateText`) lives in your app. Every surface uses shadcn/ui CSS-variable utilities, so it inherits your theme — restyle the copied file freely.

# Code Block

Code Block [#code-block]

The **CodeBlock** primitive renders syntax-highlighted code with a language label and a working copy-to-clipboard control. Highlighting uses `shiki` loaded lazily on the client (so it never blocks render); until it resolves, a plain themed `<pre>` is shown.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/conversation/code-block`

Full source: https://localmode.ai/r/ui/conversation/code-block.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/conversation/code-block
```

Dependencies [#dependencies]

* `shiki` — lazy syntax highlighting (already used by the docs site)
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `code-block.tsx` — `CodeBlock`
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**CodeBlock**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `code` | `string` | — | **Required.** The code to render. |
| `language` | `string` | `"text"` | Language id (e.g. "ts", "python"). |
| `hideLabel` | `boolean` | `false` | Hide the language label. |

Examples [#examples]

Highlight a snippet [#highlight-a-snippet]

```tsx
import { CodeBlock } from '@/components/code-block';

<CodeBlock language="ts" code={`const x = 1;`} />
```

Customization [#customization]

Change the Shiki theme in the dynamic import, or delete the import entirely to ship a zero-dependency plain `<pre>` — the copy + label behavior is independent of highlighting.

These primitives are presentational and hook-driven: they render props and emit callbacks, holding only local view state. The orchestration state lives in your app. Every surface uses shadcn/ui CSS-variable utilities, so it inherits your theme — restyle the copied file freely.

# Conversation

Conversation [#conversation]

The **Conversation** primitive is the scrollable message-display surface for a chat. It auto-pins to the newest content while local tokens stream, releases the pin when the user scrolls up (surfacing a scroll-to-bottom control), and re-pins when the user returns to the bottom. It is presentational — it renders the children/messages you pass in and owns no message state. Wire it to [`useChat().messages`](https://localmode.dev/docs/react) from `@localmode/react`.

It ships five parts: `Conversation` (the container), `ConversationContent` (padded column), `ConversationScrollAnchor` (the pin point, rendered last), `ConversationScrollButton` (the floating control), and `ConversationEmptyState` (the no-messages slot).

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/conversation/conversation`

Full source: https://localmode.ai/r/ui/conversation/conversation.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/conversation/conversation
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders plain props — works with any backend. Recommended producer: `useChat` from `@localmode/react` (on-device). For a cloud example, see [Use with the Vercel AI SDK](/docs/use-with-ai-sdk).

* `button` (shadcn/ui) — the scroll-to-bottom control

Files installed [#files-installed]

* `conversation.tsx` — the container + sub-parts
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**Conversation**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `streaming` | `boolean` | `false` | When true (typically `useChat().isStreaming`), the view auto-pins to the bottom as content grows — unless the user has scrolled up. |

Examples [#examples]

Wire to `useChat` [#wire-to-usechat]

```tsx
import { useChat } from '@localmode/react';
import {
  Conversation,
  ConversationContent,
  ConversationEmptyState,
  ConversationScrollAnchor,
  ConversationScrollButton,
} from '@/components/conversation';
import { Message, MessageContent } from '@/components/message';

export function Chat({ model }) {
  const { messages, isStreaming } = useChat({ model });

  return (
    <Conversation streaming={isStreaming}>
      <ConversationContent>
        {messages.length === 0 && <ConversationEmptyState />}
        {messages.map((m) => (
          <Message key={m.id} role={m.role}>
            <MessageContent role={m.role} content={m.content} />
          </Message>
        ))}
        <ConversationScrollAnchor />
      </ConversationContent>
      <ConversationScrollButton />
    </Conversation>
  );
}
```

Customization [#customization]

You own the copied `conversation.tsx`, so you can change the max width of `ConversationContent`, the pin threshold in the scroll handler, or the position of `ConversationScrollButton`. All surfaces are styled with shadcn/ui CSS-variable utilities so they inherit your theme.

# In-Message Error

In-Message Error [#in-message-error]

The **InMessageError** is an accessible per-message error/retry block rendered inline on a failed assistant message — not a global toast. It auto-extracts a readable message from the error and classifies common local-inference failures (OOM, WebGPU lost, model load) into a short hint, with a retry action that re-invokes generation. Data source: `useChat` (error state).

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/conversation/in-message-error`

Full source: https://localmode.ai/r/ui/conversation/in-message-error.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/conversation/in-message-error
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders the error + retry callback you pass — works with any backend. Recommended producer: `useChat().error` and `useChat().regenerate()` from `@localmode/react` (on-device, optional).

* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `in-message-error.tsx` — `InMessageError` + `extractErrorMessage`
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**InMessageError**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `error` | `unknown` | — | **Required.** The error to surface (string or Error). |
| `onRetry` | `function` | — | Retry handler — re-invokes the failed generation. |
| `retryLabel` | `string` | `"Retry"` | Retry button label. |

Examples [#examples]

Inline error on a failed turn [#inline-error-on-a-failed-turn]

```tsx
import { useChat } from '@localmode/react';
import { InMessageError } from '@/components/in-message-error';

const { status, error, regenerate } = useChat({ model });

{status === 'error' && error && (
  <InMessageError error={error} onRetry={() => regenerate()} />
)}
```

`useChat().regenerate()` re-runs the last turn in place — on failure it restores the previous reply, so retry is safe to wire directly.

Customization [#customization]

The `classify()` helper maps error text to friendly hints — extend it for your provider’s error strings. `extractErrorMessage` is exported for reuse elsewhere.

These primitives are presentational and hook-driven: they render props and emit callbacks, holding only local view state. The orchestration state (e.g. `useChat`) lives in your app. Every surface uses shadcn/ui CSS-variable utilities, so it inherits your theme — restyle the copied file freely.

# Inline Citation

Inline Citation [#inline-citation]

The **InlineCitation** primitives embed numbered/superscript citation markers in prose that open a hovercard showing the cited local chunk (title, excerpt, quoted snippet), with a carousel paging multiple sources for one claim. Distinct from the list-style `SourceCitationList`, citations reference locally-stored chunks only — no remote unfurl. Data source: `useSemanticSearch`.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/conversation/inline-citation`

Full source: https://localmode.ai/r/ui/conversation/inline-citation.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/conversation/inline-citation
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders the cited-chunk shape you pass — works with any backend. Recommended producer: local chunk provenance from `useSemanticSearch` in `@localmode/react` (on-device, optional).

* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `inline-citation.tsx` — `InlineCitation`, `InlineCitationCard`, `InlineCitationCardTrigger`, `InlineCitationCardBody`, `InlineCitationCarousel`, `InlineCitationSource`, `InlineCitationQuote`
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**InlineCitationCardTrigger**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `ReactNode` | — | **Required.** The marker number/label (e.g. `1`). |

Examples [#examples]

A cited claim [#a-cited-claim]

```tsx
import {
  InlineCitation, InlineCitationCard, InlineCitationCardBody, InlineCitationCardTrigger,
  InlineCitationCarousel, InlineCitationQuote, InlineCitationSource,
} from '@/components/inline-citation';

LocalMode runs in your browser
<InlineCitation>
  <InlineCitationCard>
    <InlineCitationCardTrigger label={1} />
    <InlineCitationCardBody>
      <InlineCitationCarousel count={1}>
        <InlineCitationSource title="architecture.md" excerpt="Execution model">
          <InlineCitationQuote>All inference executes on-device.</InlineCitationQuote>
        </InlineCitationSource>
      </InlineCitationCarousel>
    </InlineCitationCardBody>
  </InlineCitationCard>
</InlineCitation>.
```

Customization [#customization]

The marker is a focusable `<sup>` so it works by hover and keyboard. Pass `count > 1` to `InlineCitationCarousel` with multiple `InlineCitationSource` children to page sources for one claim.

These primitives are presentational and hook-driven: they render props and emit callbacks, holding only local view state. The orchestration state (e.g. `useSemanticSearch`) lives in your app. Every surface uses shadcn/ui CSS-variable utilities, so it inherits your theme — restyle the copied file freely.

# Loader

Loader [#loader]

The **Loader** is a small family of busy visuals shown while a local model warms up or streams its first token. Pick a `variant` (dots / pulse / typing / spinner), or use `Shimmer` to render skeleton-text lines for content that is expected but not yet arrived.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/conversation/loader`

Full source: https://localmode.ai/r/ui/conversation/loader.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/conversation/loader
```

Dependencies [#dependencies]

* *None* — pure presentational component
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `loader.tsx` — `Loader` + `Shimmer`
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**Loader**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"spinner" \| "typing" \| "pulse" \| "dots"` | `"dots"` | Which animated indicator to show. |
| `label` | `string` | — | Optional label rendered after the indicator (e.g. "Thinking…"). |

Examples [#examples]

Typing indicator while pending [#typing-indicator-while-pending]

```tsx
import { Loader } from '@/components/loader';

{isStreaming && lastMessage.content === '' && <Loader variant="typing" label="Thinking…" />}
```

Shimmer skeleton [#shimmer-skeleton]

```tsx
import { Shimmer } from '@/components/loader';

<Shimmer lines={4} />
```

Customization [#customization]

The dot animation uses an inline `@keyframes` block so the component is self-contained. Swap the `bg-current`/`bg-muted` tokens or the variant set to match your design system.

These primitives are presentational and hook-driven: they render props and emit callbacks, holding only local view state. The orchestration state lives in your app. Every surface uses shadcn/ui CSS-variable utilities, so it inherits your theme — restyle the copied file freely.

# Message

Message [#message]

The **Message** primitive is the role-aware chat row. It exposes `data-role` for theming, renders content as a markdown string or `ContentPart[]` (matching `@localmode/react`'s message model), and supports contained vs. flat variants. Image parts render as thumbnails with a fullscreen dialog; file parts render a download chip — both from local bytes. `MessageAvatar` renders the role avatar, and `Checkpoint` is an inter-message savepoint marker enabling rollback/restore.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/conversation/message`

Full source: https://localmode.ai/r/ui/conversation/message.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/conversation/message
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders a markdown `string` or `ContentPart[]` you pass — works with any backend. Recommended producer: `useChat` from `@localmode/react` (on-device). See [Use with the Vercel AI SDK](/docs/use-with-ai-sdk) for a cloud mapping.

* `@localmode/ui/lib/browser-utils` — `formatBytes` for file-size chips (installed automatically as a registry dependency)
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `message.tsx` — `Message`, `MessageContent`, `MessageAvatar`, `Checkpoint`
* `lib/markdown.tsx` — the streaming-safe markdown renderer
* `lib/browser-utils.ts` — generic browser helpers (`formatBytes` for file-size chips)
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**MessageContent**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `content` | `array \| string` | — | **Required.** Message content — a markdown string or `ContentPart[]`. |
| `variant` | `"flat" \| "contained"` | `"contained"` | Bubble style. `contained` draws a themed bubble; `flat` renders inline with no background (useful for assistant prose). |
| `role` | `"system" \| "assistant" \| "user"` | — | Role, used for bubble theming when contained. |

Examples [#examples]

Render a message from `useChat` [#render-a-message-from-usechat]

```tsx
import { Message, MessageAvatar, MessageContent } from '@/components/message';

export function Bubble({ message }) {
  return (
    <Message role={message.role}>
      <MessageAvatar role={message.role} />
      <MessageContent role={message.role} content={message.content} />
    </Message>
  );
}
```

Checkpoint / restore [#checkpoint--restore]

```tsx
import { Checkpoint } from '@/components/message';

<Checkpoint label="Saved" onRestore={() => rollbackThreadTo(checkpointId)} />
```

Customization [#customization]

Swap the `contained`/`flat` bubble classes, change the avatar fallbacks, or extend `MessagePart` to add new part types (the component already handles `text`, `image`, and `file`). The markdown renderer in `lib/markdown.tsx` is dependency-free; replace it with `streamdown` or `react-markdown` + `remark-gfm` if you want richer rendering.

These primitives are presentational and hook-driven: they render props and emit callbacks, holding only local view state. The orchestration state (e.g. `useChat`) lives in your app. Every surface uses shadcn/ui CSS-variable utilities, so it inherits your theme — restyle the copied file freely.

# Multi-Step Pipeline Tracker

Multi-Step Pipeline Tracker [#multi-step-pipeline-tracker]

The **MultiStepPipelineTracker** is a horizontal numbered-step progress indicator (active / completed / pending) that maps directly to `usePipeline`'s `onProgress` (`{ currentStep, completed, total }`). `StagePipelineTracker` is a single-stage label + 0–100 bar for ingest; `StepsPlan` is a vertical connector-bar outline with expandable per-step detail; and `InferenceQueueSurface` visualizes pending tasks grouped by priority (interactive / background) over `useInferenceQueue`.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/conversation/pipeline-tracker`

Full source: https://localmode.ai/r/ui/conversation/pipeline-tracker.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/conversation/pipeline-tracker
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders the step/progress shape you pass — works with any backend. Recommended producer: `usePipeline` progress and `useInferenceQueue` from `@localmode/react` (on-device, optional).

* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `pipeline-tracker.tsx` — `MultiStepPipelineTracker`, `StagePipelineTracker`, `StepsPlan`, `InferenceQueueSurface`
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**MultiStepPipelineTracker**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `steps` | `array` | — | **Required.** Ordered step labels. |
| `completed` | `number` | — | **Required.** Number of completed steps (e.g. `progress.completed`). |
| `currentStep` | `string` | — | The currently active step label (e.g. `progress.currentStep`). |

Examples [#examples]

Track pipeline progress [#track-pipeline-progress]

```tsx
import { usePipeline } from '@localmode/react';
import { MultiStepPipelineTracker } from '@/components/pipeline-tracker';

const { progress } = usePipeline(steps);

<MultiStepPipelineTracker
  steps={['Chunk', 'Embed', 'Index']}
  completed={progress?.completed ?? 0}
  currentStep={progress?.currentStep}
/>
```

Customization [#customization]

Use `StagePipelineTracker` for single-stage ingest with a percentage bar, or `StepsPlan` for an editable plan outline. The queue surface is presentational over `useInferenceQueue` — map your pending tasks into `QueuedTask[]`.

These primitives are presentational and hook-driven: they render props and emit callbacks, holding only local view state. The orchestration state (e.g. `usePipeline`) lives in your app. Every surface uses shadcn/ui CSS-variable utilities, so it inherits your theme — restyle the copied file freely.

# Prompt Input Attachments

Prompt Input Attachments [#prompt-input-attachments]

**PromptInputAttachments** adds image/file attachment to the composer via file picker, paste, and drag-and-drop. It renders preview thumbnails with per-item removal, a hovercard preview, media-category auto-detection (image / video / audio / document), and upload-state chips. Attachments match the standard base64 image content model, using the copy-owned `readFileAsDataUrl` helper from `lib/browser-utils`.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/conversation/prompt-input-attachments`

Full source: https://localmode.ai/r/ui/conversation/prompt-input-attachments.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/conversation/prompt-input-attachments
```

Data source & dependencies [#data-source--dependencies]

**Data source:** emits attachment changes and reads local files — works with any backend. Recommended producer: `useChat` from `@localmode/react` (on-device, optional).

* `@localmode/ui/lib/browser-utils` — `readFileAsDataUrl` for file reading (installed automatically as a registry dependency)
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `prompt-input-attachments.tsx` — `PromptInputAttachments`
* `lib/browser-utils.ts` — generic browser helpers (`readFileAsDataUrl`)
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**PromptInputAttachments**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `array` | — | Current attachments (controlled). Falls back to the provider when omitted. |
| `onChange` | `function` | — | Reports the new attachment list after add/remove (controlled). |
| `accept` | `string` | `"image/*"` | Accept filter for the picker / drop. |
| `multiple` | `boolean` | `true` | Allow multiple files. |

Examples [#examples]

Inside a `PromptInputProvider` [#inside-a-promptinputprovider]

```tsx
import {
  PromptInput,
  PromptInputProvider,
  PromptInputSubmit,
  PromptInputTextarea,
  PromptInputTools,
} from '@/components/prompt-input';
import { PromptInputAttachments } from '@/components/prompt-input-attachments';

<PromptInputProvider>
  <PromptInputAttachments />
  <PromptInput onSubmit={(text, attachments) => send(text, { images: attachments })}>
    <PromptInputTextarea />
    <PromptInputTools><span /><PromptInputSubmit /></PromptInputTools>
  </PromptInput>
</PromptInputProvider>
```

Customization [#customization]

Change the `accept` filter, the thumbnail size, or the `mediaCategory` mapping. The provider integration means attachments clear automatically on submit; drop the provider and use the controlled `value`/`onChange` props for fully external control.

These primitives are presentational and hook-driven: they render props and emit callbacks, holding only local view state. The orchestration state (e.g. `useChat`) lives in your app. Every surface uses shadcn/ui CSS-variable utilities, so it inherits your theme — restyle the copied file freely.

# Prompt Input

Prompt Input [#prompt-input]

The **PromptInput** is the chat composer. It manages its own textarea state by default — auto-resize, Enter to submit, Shift+Enter for a newline — and swaps its submit control for a stop control while streaming. It exposes `onSubmit(text, attachments?)` and optional controlled `value` / `onValueChange`. A `PromptInputProvider` hoists composer state for external control, `PromptInputMic` toggles local Whisper dictation, and `PromptInputAddButton` anchors a slash-command / + picker.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/conversation/prompt-input`

Full source: https://localmode.ai/r/ui/conversation/prompt-input.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/conversation/prompt-input
```

Data source & dependencies [#data-source--dependencies]

**Data source:** emits `onSubmit(text, attachments)` / `onStop` — wire to any backend. Recommended producer: `useChat` from `@localmode/react` (on-device). See [Use with the Vercel AI SDK](/docs/use-with-ai-sdk).

* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `prompt-input.tsx` — `PromptInput`, `PromptInputTextarea`, `PromptInputSubmit`, `PromptInputTools`, `PromptInputProvider`, `PromptInputMic`, `PromptInputAddButton`
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**PromptInput**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onSubmit` | `function` | — | **Required.** Fired with the trimmed text (and attachments) on submit. |
| `value` | `string` | — | Controlled value (optional). |
| `onValueChange` | `function` | — | Reports edits in controlled mode. |
| `streaming` | `boolean` | `false` | When true, the submit control becomes a stop control. |
| `onStop` | `function` | — | Fired when the user activates the stop control. |
| `attachments` | `array` | — | Attachments to include in the next submit (from `PromptInputAttachments`). |
| `disabled` | `boolean` | — | Disable the whole composer. |

Examples [#examples]

Wire to `useChat` [#wire-to-usechat]

```tsx
import { useChat } from '@localmode/react';
import {
  PromptInput,
  PromptInputSubmit,
  PromptInputTextarea,
  PromptInputTools,
} from '@/components/prompt-input';

export function Composer({ model }) {
  const { send, cancel, isStreaming } = useChat({ model });
  return (
    <PromptInput streaming={isStreaming} onStop={cancel} onSubmit={(text) => send(text)}>
      <PromptInputTextarea placeholder="Ask anything…" />
      <PromptInputTools>
        <span />
        <PromptInputSubmit />
      </PromptInputTools>
    </PromptInput>
  );
}
```

Customization [#customization]

A `CharLimitIndicator` from the input-controls family slots into `PromptInputTools`; until it is installed, drop in a simple `text.length` counter. Adjust `maxHeight` on the textarea, or wire `PromptInputMic.onToggle` to a `useVoiceRecorder` + `transcribe` flow to fill the input from local speech.

These primitives are presentational and hook-driven: they render props and emit callbacks, holding only local view state. The orchestration state (e.g. `useChat`) lives in your app. Every surface uses shadcn/ui CSS-variable utilities, so it inherits your theme — restyle the copied file freely.

# Reasoning

Reasoning [#reasoning]

The **Reasoning** primitive renders the model's own thinking tokens (DeepSeek-R1 style) in a collapsible region. It auto-expands while tokens stream — showing an elapsed timer — and auto-collapses when the final answer arrives. The compact `ThinkingBar` variant is a one-line status strip with inline stop/expand. Together with `ChainOfThought` it forms a three-tier thinking taxonomy: `ThinkingBar` → `Reasoning` → `ChainOfThought`.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/conversation/reasoning`

Full source: https://localmode.ai/r/ui/conversation/reasoning.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/conversation/reasoning
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders a reasoning `string` you pass — works with any backend. Recommended producer: a reasoning-capable model via `@localmode/react` (on-device). See [Use with the Vercel AI SDK](/docs/use-with-ai-sdk#reasoning-parts--reasoning).

* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `reasoning.tsx` — `Reasoning`, `ReasoningTrigger`, `ReasoningContent`, `ThinkingBar`
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**Reasoning**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `streaming` | `boolean` | — | Whether reasoning tokens are still streaming. Drives auto-expand/collapse. |
| `open` | `boolean` | — | Controlled open state (optional). |
| `onOpenChange` | `function` | — | Reports open changes. |
| `durationMs` | `number` | — | Provide a fixed elapsed time (ms) instead of the internal timer. |

Examples [#examples]

Stream reasoning tokens [#stream-reasoning-tokens]

```tsx
import { Reasoning, ReasoningContent, ReasoningTrigger } from '@/components/reasoning';

<Reasoning streaming={isThinking}>
  <ReasoningTrigger />
  <ReasoningContent>{thinkTokens}</ReasoningContent>
</Reasoning>
```

Customization [#customization]

Pass `durationMs` to display a known elapsed time instead of the internal timer, or control `open`/`onOpenChange` to override the auto-expand/collapse behavior.

These primitives are presentational and hook-driven: they render props and emit callbacks, holding only local view state. The orchestration state (e.g. `useGenerateText`) lives in your app. Every surface uses shadcn/ui CSS-variable utilities, so it inherits your theme — restyle the copied file freely.

# Response

Response [#response]

The **Response** primitive renders streamed assistant text as markdown and shows a blinking cursor while content is still arriving. It tolerates partial/incomplete markdown — an unterminated code fence mid-stream renders without breaking layout. An optional client-side typewriter reveal animates already-resolved text, and `renderMath` / `renderMermaid` props route `$$…$$` and \`\`\`mermaid blocks to swappable renderers (declare `katex` / `mermaid` in your project if you supply them).

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/conversation/response`

Full source: https://localmode.ai/r/ui/conversation/response.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/conversation/response
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders the markdown `string` you stream in — works with any backend. Recommended producer: the token stream from `useChat` / `useGenerateText` in `@localmode/react` (on-device, optional).

* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `response.tsx` — the streaming renderer
* `lib/markdown.tsx` — the streaming-safe markdown renderer
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**Response**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `string` | — | **Required.** The (possibly partial) markdown content to render. |
| `streaming` | `boolean` | `false` | Whether content is still arriving. When true a blinking cursor is shown after the text and removed on completion. |
| `typewriter` | `boolean` | `false` | Reveal already-resolved text one character at a time. Ignored while `streaming` (live token streams reveal naturally). |
| `typewriterSpeed` | `number` | `2` | Characters revealed per tick when `typewriter` is enabled. |
| `renderMath` | `BlockRenderer` | — | Optional LaTeX/math block renderer (e.g. a KaTeX-backed function). When provided, `$$…$$` blocks are routed to it. Declare `katex` in your project if you supply one. |
| `renderMermaid` | `BlockRenderer` | — | Optional Mermaid diagram renderer. When provided, ```mermaid fences are routed to it. Declare `mermaid` in your project if you supply one. |

Examples [#examples]

Stream tokens [#stream-tokens]

```tsx
import { Response } from '@/components/response';

<Response streaming={isStreaming}>{assistantText}</Response>
```

With KaTeX math [#with-katex-math]

```tsx
// npm i katex
import katex from 'katex';
import 'katex/dist/katex.min.css';

const renderMath = (src: string) => (
  <span dangerouslySetInnerHTML={{ __html: katex.renderToString(src) }} />
);

<Response renderMath={renderMath}>{text}</Response>
```

Customization [#customization]

The cursor is a themed `<span>` — restyle or replace it. The math/diagram renderers are intentionally not bundled; pass your own to keep the installed footprint minimal. The markdown subset lives in `lib/markdown.tsx`.

These primitives are presentational and hook-driven: they render props and emit callbacks, holding only local view state. The orchestration state (e.g. `useChat`) lives in your app. Every surface uses shadcn/ui CSS-variable utilities, so it inherits your theme — restyle the copied file freely.

# Scroll To Bottom Button

Scroll To Bottom Button [#scroll-to-bottom-button]

The **ScrollToBottomButton** is a floating scroll-to-bottom affordance tied to a chat container’s scroll state. It appears when the user scrolls up from the bottom and scrolls to + pins the latest content on click. Pass a `containerRef`, or let it find the nearest scrollable ancestor. `ScrollAnchor` is the zero-height pin element you place at the end of the message list. Data source: `useChat` (token-stream growth).

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/conversation/scroll-to-bottom-button`

Full source: https://localmode.ai/r/ui/conversation/scroll-to-bottom-button.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/conversation/scroll-to-bottom-button
```

Data source & dependencies [#data-source--dependencies]

**Data source:** observes a scroll container you pass — works with any backend. Recommended producer: the streaming chat container fed by `useChat` from `@localmode/react` (on-device, optional).

* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `scroll-to-bottom-button.tsx` — `ScrollToBottomButton` + `ScrollAnchor`
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**ScrollToBottomButton**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `containerRef` | `object` | — | The scroll container to observe. When omitted, the nearest scrollable ancestor of the button is used. |
| `threshold` | `number` | `24` | Distance (px) from the bottom under which the button hides. |
| `variant` | `"ghost" \| "secondary" \| "outline" \| "destructive" \| "default" \| "link" \| null` | — | — |
| `size` | `"icon-lg" \| "icon-sm" \| "icon-xs" \| "icon" \| "lg" \| "sm" \| "xs" \| "default" \| null` | — | — |
| `asChild` | `boolean` | — | — |

Examples [#examples]

Attach to a scroll container [#attach-to-a-scroll-container]

```tsx
import { ScrollAnchor, ScrollToBottomButton } from '@/components/scroll-to-bottom-button';

<div className="relative">
  <div ref={scrollRef} className="overflow-y-auto">
    {messages.map((m) => <Bubble key={m.id} {...m} />)}
    <ScrollAnchor />
  </div>
  <ScrollToBottomButton containerRef={scrollRef} />
</div>
```

Customization [#customization]

This is the standalone counterpart to the built-in `ConversationScrollButton`; use it when your chat surface is not the `Conversation` container. Adjust the `threshold` for how far up the user must scroll before it appears.

These primitives are presentational and hook-driven: they render props and emit callbacks, holding only local view state. The orchestration state (e.g. `useChat`) lives in your app. Every surface uses shadcn/ui CSS-variable utilities, so it inherits your theme — restyle the copied file freely.

# Source Citation List

Source Citation List [#source-citation-list]

The **SourceCitationList** extends `Sources` for in-message attribution. It renders retrieved RAG passages behind a collapsible "Show N sources" toggle, each with a numbered badge, a similarity score (flat text + radial confidence ring via `ConfidenceRing`), and clamped body text with a staggered fade-in. Data source: a `Source[]` (`{ text, score }`) from `useSemanticSearch` / `useAnswerQuestion` / `useAskDocument`.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/conversation/source-citation-list`

Full source: https://localmode.ai/r/ui/conversation/source-citation-list.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/conversation/source-citation-list
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders a `Source[]` (`{ text, score }`) you pass — works with any backend. Recommended producer: `useSemanticSearch` / `useAnswerQuestion` / `useAskDocument` from `@localmode/react` (on-device, optional).

* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `source-citation-list.tsx` — `SourceCitationList` + `ConfidenceRing`
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**SourceCitationList**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `sources` | `array` | — | **Required.** The retrieved sources to attribute. |
| `defaultOpen` | `boolean` | `false` | Open by default. |

Examples [#examples]

Attribute an answer [#attribute-an-answer]

```tsx
import { SourceCitationList } from '@/components/source-citation-list';

<SourceCitationList
  sources={results.map((r) => ({ title: r.metadata.title, text: r.text, score: r.score }))}
/>
```

Customization [#customization]

The `ConfidenceRing` is a dependency-free SVG — reuse it standalone for any 0–1 score. Adjust the `line-clamp` or the stagger delay in the copied file.

These primitives are presentational and hook-driven: they render props and emit callbacks, holding only local view state. The orchestration state (e.g. `useSemanticSearch`) lives in your app. Every surface uses shadcn/ui CSS-variable utilities, so it inherits your theme — restyle the copied file freely.

# Sources

Sources [#sources]

The **Sources** primitives render retrieval citations from local RAG results (e.g. `useSemanticSearch`). `Sources` is the collapsible container; `SourcesTrigger` shows the count; each `Source` renders a favicon/title/excerpt chip and a 0–1 relevance score. An optional tabbed layout switches between Web / Images / News-style result variants. All favicons/images come from already-stored local metadata — there is no remote unfurl.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/conversation/sources`

Full source: https://localmode.ai/r/ui/conversation/sources.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/conversation/sources
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders a list of `{ href, title }` you pass — works with any backend. Recommended producer: `useSemanticSearch` from `@localmode/react` (on-device). See [Use with the Vercel AI SDK](/docs/use-with-ai-sdk#source-parts--sources).

* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `sources.tsx` — `Sources`, `SourcesTrigger`, `SourcesContent`, `Source`
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**Source**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `source` | `object` | — | **Required.** The source to render. |

Examples [#examples]

From local search results [#from-local-search-results]

```tsx
import { Source, Sources, SourcesContent, SourcesTrigger } from '@/components/sources';

<Sources>
  <SourcesTrigger count={results.length} />
  <SourcesContent>
    {results.map((r) => (
      <Source key={r.id} source={{ id: r.id, title: r.metadata.title, excerpt: r.text, score: r.score }} />
    ))}
  </SourcesContent>
</Sources>
```

Customization [#customization]

Enable the tabbed layout by passing `tabbed` + `sources` to `SourcesContent`. Favicons render from `faviconUrl` in your stored metadata — leave it unset for the default globe icon.

These primitives are presentational and hook-driven: they render props and emit callbacks, holding only local view state. The orchestration state (e.g. `useSemanticSearch`) lives in your app. Every surface uses shadcn/ui CSS-variable utilities, so it inherits your theme — restyle the copied file freely.

# Structured Output Viewer

Structured Output Viewer [#structured-output-viewer]

The **StructuredOutputViewer** extends `Response` for `useGenerateObject`. It pretty-prints the extracted JSON in a scrollable block, pairs it with an independently-usable `InferenceStats` footer (token count, wall-clock duration, attempt/retry count), and offers a navigable typed `SchemaTree` view so output can be inspected both as data and as its schema shape.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/conversation/structured-output-viewer`

Full source: https://localmode.ai/r/ui/conversation/structured-output-viewer.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/conversation/structured-output-viewer
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders the parsed object + usage you pass — works with any backend. Recommended producer: `useGenerateObject` result + usage from `@localmode/react` (on-device, optional).

* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `structured-output-viewer.tsx` — `StructuredOutputViewer`, `InferenceStats`, `SchemaTree`
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**StructuredOutputViewer**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `object` | `unknown` | — | **Required.** The generated object (from `useGenerateObject`). |
| `usage` | `object` | — | Token usage to surface in the footer. |
| `durationMs` | `number` | — | Wall-clock duration in milliseconds. |
| `attempts` | `number` | — | Number of attempts/retries. |

Examples [#examples]

Render a generated object [#render-a-generated-object]

```tsx
import { useGenerateObject } from '@localmode/react';
import { StructuredOutputViewer } from '@/components/structured-output-viewer';

const { data } = useGenerateObject({ model, schema });

{data && <StructuredOutputViewer object={data.object} usage={data.usage} durationMs={elapsed} />}
```

Customization [#customization]

`InferenceStats` is exported separately — drop it beneath any `useGenerateText` result for the same tokens/duration footer. `SchemaTree` derives its tree from the value's runtime shape; swap it to read your Zod/JSON schema directly if you prefer the declared shape.

These primitives are presentational and hook-driven: they render props and emit callbacks, holding only local view state. The orchestration state (e.g. `useGenerateObject`) lives in your app. Every surface uses shadcn/ui CSS-variable utilities, so it inherits your theme — restyle the copied file freely.

# Suggestions

Suggestions [#suggestions]

The **Suggestions** primitive renders a horizontal, scrollable rail of prompt chips. Each `Suggestion` invokes a callback with its text — wire it to your composer to seed the input or send directly.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/conversation/suggestions`

Full source: https://localmode.ai/r/ui/conversation/suggestions.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/conversation/suggestions
```

Dependencies [#dependencies]

* *None* — pure presentational component
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `suggestions.tsx` — `Suggestions` + `Suggestion`
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**Suggestion**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `suggestion` | `string` | — | **Required.** The suggestion text (also the default label). |
| `onSelect` | `function` | — | Invoked with the suggestion text on activation. |
| `variant` | `"ghost" \| "secondary" \| "outline" \| "destructive" \| "default" \| "link" \| null` | — | — |
| `size` | `"icon-lg" \| "icon-sm" \| "icon-xs" \| "icon" \| "lg" \| "sm" \| "xs" \| "default" \| null` | — | — |
| `asChild` | `boolean` | — | — |

Examples [#examples]

Seed the input [#seed-the-input]

```tsx
import { Suggestion, Suggestions } from '@/components/suggestions';

<Suggestions>
  {prompts.map((p) => (
    <Suggestion key={p} suggestion={p} onSelect={setInput} />
  ))}
</Suggestions>
```

Customization [#customization]

Chips are `button`s under the hood, so size/variant flow through. The rail hides its scrollbar by default; remove those utilities to show it.

These primitives are presentational and hook-driven: they render props and emit callbacks, holding only local view state. The orchestration state lives in your app. Every surface uses shadcn/ui CSS-variable utilities, so it inherits your theme — restyle the copied file freely.

# System Notice Banner

System Notice Banner [#system-notice-banner]

The **SystemNoticeBanner** is an in-conversation banner notice rendered inside the chat surface (not as a message bubble) for local-first state changes: offline/online transitions, model switch, capability-unavailable, WebGPU→WASM fallback, cache eviction, or download-required notices. The `kind` sets the icon, tone, and default copy. Data source: `useNetworkStatus` / `useCapabilities`.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/conversation/system-notice-banner`

Full source: https://localmode.ai/r/ui/conversation/system-notice-banner.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/conversation/system-notice-banner
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders the `kind` + copy you pass — works with any backend. Recommended producer: `useNetworkStatus` / `useCapabilities` from `@localmode/react` (on-device, optional).

* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `system-notice-banner.tsx` — `SystemNoticeBanner`
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**SystemNoticeBanner**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `kind` | `"info" \| "download-required" \| "eviction" \| "model-switch" \| "capability-unavailable" \| "fallback" \| "online" \| "offline"` | `"info"` | The notice kind (sets the icon, tone, and default copy). |
| `tone` | `"warning" \| "info"` | — | Override the tone independently of `kind`. |
| `message` | `string` | — | Notice text (falls back to the kind's default copy). |
| `action` | `ReactNode` | — | Optional trailing action (e.g. a "Download" or "Retry" button). |
| `onDismiss` | `function` | — | When provided, renders a dismiss control. |

Examples [#examples]

Surface offline state inline [#surface-offline-state-inline]

```tsx
import { useNetworkStatus } from '@localmode/react';
import { SystemNoticeBanner } from '@/components/system-notice-banner';

const { isOnline } = useNetworkStatus();

{!isOnline && <SystemNoticeBanner kind="offline" />}
```

Customization [#customization]

Override the `message`, `tone`, or `action` per notice. The default copy lives in `KIND_META` — edit it or add new `NoticeKind`s for your app’s own states.

These primitives are presentational and hook-driven: they render props and emit callbacks, holding only local view state. The orchestration state (e.g. `useNetworkStatus`) lives in your app. Every surface uses shadcn/ui CSS-variable utilities, so it inherits your theme — restyle the copied file freely.

# Task

Task [#task]

The **Task** primitive renders a multi-step agent process as an ordered list of steps. Each `TaskItem` shows its index, tool, status, and — when expanded — args and observation, with the `finish` step styled as the distinguished final answer. Its data shape mirrors `@localmode/react` `useAgent` steps (`{ index, type, toolName, toolArgs, observation, result }`) so agent UIs wire up without adapters.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/conversation/task`

Full source: https://localmode.ai/r/ui/conversation/task.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/conversation/task
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders the step list you pass — works with any backend. Recommended producer: `useAgent().steps` from `@localmode/react` (on-device, optional).

* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `task.tsx` — `Task` + `TaskItem`
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**TaskItem**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `step` | `object` | — | **Required.** The step to render. |

Examples [#examples]

Render agent steps [#render-agent-steps]

```tsx
import { useAgent } from '@localmode/react';
import { Task, TaskItem } from '@/components/task';

const { steps } = useAgent({ model, tools });

<Task>
  {steps.map((s) => <TaskItem key={s.index} step={s} />)}
</Task>
```

Customization [#customization]

For a richer vertical timeline with durations, finish-reason badges, and nested sub-agents, use [Agent Step Timeline](/docs/conversation/agent-step-timeline). `Task` is the lighter, list-style option.

These primitives are presentational and hook-driven: they render props and emit callbacks, holding only local view state. The orchestration state (e.g. `useAgent`) lives in your app. Every surface uses shadcn/ui CSS-variable utilities, so it inherits your theme — restyle the copied file freely.

# Tool Approval

Tool Approval [#tool-approval]

The **ToolApproval** primitive is a human-in-the-loop confirmation card that gates a tool call before it executes. It shows the pending tool + args with approve/reject buttons, then re-renders read-only as an immutable "receipt" of the decision. It pairs with the `Tool` primitive and feeds the choice back into the agent loop via callbacks. Data source: `useAgent` (ReAct tool calls).

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/conversation/tool-approval`

Full source: https://localmode.ai/r/ui/conversation/tool-approval.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/conversation/tool-approval
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders the pending call and emits the approve/reject decision — works with any backend. Recommended producer: resume the `useAgent` loop on the decision (optionally logging to the audit log) via `@localmode/react` (on-device, optional).

* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `tool-approval.tsx` — `ToolApproval`
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**ToolApproval**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `toolName` | `string` | — | **Required.** The tool name awaiting approval. |
| `args` | `Record<string, unknown>` | — | The proposed arguments. |
| `decision` | `"rejected" \| "approved" \| null` | — | A controlled decision; when set, the card renders read-only as a receipt. |
| `onApprove` | `function` | — | Fires when the user approves — proceed with the tool call. |
| `onReject` | `function` | — | Fires when the user rejects — skip/abort the tool call. |

Examples [#examples]

Gate a sensitive tool [#gate-a-sensitive-tool]

```tsx
import { ToolApproval } from '@/components/tool-approval';

<ToolApproval
  toolName="send_email"
  args={pendingCall.args}
  decision={decision}
  onApprove={() => resume('approved')}
  onReject={() => resume('rejected')}
/>
```

Customization [#customization]

Pass a controlled `decision` to render the receipt from persisted state; leave it unset to let the card manage its own approve/reject state. Pair it with the audit-log primitives to record an immutable approval trail.

These primitives are presentational and hook-driven: they render props and emit callbacks, holding only local view state. The orchestration state (e.g. `useAgent`) lives in your app. Every surface uses shadcn/ui CSS-variable utilities, so it inherits your theme — restyle the copied file freely.

# Tool

Tool [#tool]

The **Tool** primitive renders a single tool invocation. `ToolHeader` shows the name and a status badge (pending / running / streaming / completed / error); `ToolContent` hosts expandable `ToolInput` (JSON params) and `ToolOutput` (result or error). A per-tool renderer registry lets you customize specific tools, `ToolFallback`/`ToolView` cover unregistered ones, and `ToolGroup` collapses consecutive calls behind a stacked-icon summary. Data source: `useAgent` / wllama/transformers tool calling.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/conversation/tool`

Full source: https://localmode.ai/r/ui/conversation/tool.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/conversation/tool
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders a tool-call shape (name/input/output/state) you pass — works with any backend. Recommended producer: `useAgent` from `@localmode/react` (on-device). See [Use with the Vercel AI SDK](/docs/use-with-ai-sdk#tool-invocations--tool) for AI-SDK tool parts.

* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `tool.tsx` — `Tool`, `ToolHeader`, `ToolContent`, `ToolInput`, `ToolOutput`, `ToolFallback`, `ToolView`, `ToolGroup`
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**ToolHeader**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` | — | **Required.** Tool name. |
| `status` | `ToolStatus` | — | **Required.** Current status. |

Examples [#examples]

A single tool call [#a-single-tool-call]

```tsx
import { Tool, ToolContent, ToolHeader, ToolInput, ToolOutput } from '@/components/tool';

<Tool defaultOpen>
  <ToolHeader name={call.name} status={call.status} />
  <ToolContent>
    <ToolInput input={call.input} />
    <ToolOutput output={call.output} error={call.error} />
  </ToolContent>
</Tool>
```

Custom renderer registry [#custom-renderer-registry]

```tsx
import { ToolView } from '@/components/tool';

const registry = {
  search_documents: (call) => <MySearchCard call={call} />,
};

<ToolView call={call} registry={registry} />
```

Customization [#customization]

The status badge colors map through `STATUS_META`; edit it to match your palette. Pass a registry to `ToolView`/`ToolGroup` to render specific tools with custom UIs while everything else falls back to the generic card.

These primitives are presentational and hook-driven: they render props and emit callbacks, holding only local view state. The orchestration state (e.g. `useAgent`) lives in your app. Every surface uses shadcn/ui CSS-variable utilities, so it inherits your theme — restyle the copied file freely.

# Category Facet List

Category Facet List [#category-facet-list]

The **Category Facet List** is a filterable facet for narrowing a result set by category. It renders a single-select **list** or **pill** row with per-category count badges, an active highlight, and an "All"/clear affordance. Single-select with deselect: re-clicking the active category clears it.

It is deliberately **domain-decoupled** — it takes `categories`, `counts`, `selected`, and `onSelect`, so the same primitive serves [`useSemanticSearch()`](https://localmode.dev/docs/react) metadata filtering (wire `onSelect` to `search(query, { filter })`), zero-shot classification labels, NER entity-type filters, and document categories alike.

**When to use it:** filter semantic-search results by a metadata facet (semantic-search, product-search), or filter classification/NER output by label. Derive `counts` from your result set and feed `selected`/`onSelect` from local state.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/data-documents/category-facet-list`

Full source: https://localmode.ai/r/ui/data-documents/category-facet-list.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/data-documents/category-facet-list
```

Dependencies [#dependencies]

* **Data source:** renders the plain `categories` / `counts` / `selected` props you pass — works with any backend; recommended LocalMode producer: `useSemanticSearch` results' metadata (optional).
* `lucide-react` — the active-state check icon
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `category-facet-list.tsx` — the component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**CategoryFacetList**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `categories` | `array` | — | **Required.** The category values to render, in display order. |
| `counts` | `Record<string, number> \| false` | — | Per-category item counts, keyed by category. Missing keys render `0`. Pass `false` to hide count badges entirely. |
| `selected` | `string \| null` | — | **Required.** The currently selected category, or `null` when none is selected ("All"). Single-select: re-selecting the active category deselects it. |
| `onSelect` | `function` | — | **Required.** Called with the next selection: the clicked category, or `null` when the active category is re-clicked or "All" is activated. |
| `variant` | `"pills" \| "list"` | `"list"` | Layout: a vertical list (default) or a wrapping row of pills. |
| `allLabel` | `string` | `"All"` | Label for the clear-selection affordance. |
| `showAll` | `boolean` | `true` | Show the "All"/clear affordance. |

Examples [#examples]

Filter `useSemanticSearch` results [#filter-usesemanticsearch-results]

```tsx
import { CategoryFacetList } from '@/components/category-facet-list';
import { useSemanticSearch } from '@localmode/react';

export function Facets({ db, model, query }: { db: any; model: any; query: string }) {
  const { results, usage, search } = useSemanticSearch({ model, db });
  const [selected, setSelected] = useState<string | null>(null);

  const counts = results.reduce<Record<string, number>>((acc, r) => {
    const c = String(r.metadata.category ?? 'uncategorized');
    acc[c] = (acc[c] ?? 0) + 1;
    return acc;
  }, {});

  // Selecting a facet re-runs the search with a metadata filter applied
  // inside the vector DB — not a client-side post-filter of stale results.
  const select = (category: string | null) => {
    setSelected(category);
    search(query, category ? { filter: { category } } : undefined);
  };

  return (
    <>
      <CategoryFacetList
        categories={Object.keys(counts)}
        counts={counts}
        selected={selected}
        onSelect={select}
      />
      {usage && (
        <span className="text-xs text-muted-foreground">
          {Math.round(usage.embedDurationMs + usage.searchDurationMs)} ms
        </span>
      )}
    </>
  );
}
```

`useSemanticSearch` accepts a hook-level `filter` / `threshold` (applied to every search) and per-call overrides via `search(query, { filter, threshold, topK })`. The `usage` from the last completed search (`{ embeddingTokens, embedDurationMs, searchDurationMs }`) feeds a latency badge.

Horizontal pills [#horizontal-pills]

```tsx
<CategoryFacetList
  variant="pills"
  categories={['Privacy', 'Security', 'Performance']}
  counts={{ Privacy: 12, Security: 8, Performance: 5 }}
  selected={selected}
  onSelect={setSelected}
/>
```

No counts, no "All" [#no-counts-no-all]

```tsx
<CategoryFacetList
  categories={labels}
  counts={false}
  showAll={false}
  selected={selected}
  onSelect={setSelected}
/>
```

Customization [#customization]

The facet is styled with shadcn/ui CSS-variable utilities (`bg-accent`, `text-accent-foreground`, `bg-primary`, `text-primary-foreground`, `bg-muted`), so the active highlight and count badges inherit your theme. The `list` variant shows a leading check on the active row; the `pills` variant fills the active pill with the primary color.

Selection is fully controlled: `selected` is the active category or `null` ("All"), and `onSelect` receives the next selection (`null` when the active item is re-clicked or "All" is activated). Because you own the file, you can add multi-select, sort categories by count, or swap the count badge styling in the copied `category-facet-list.tsx`.

# Chunk Boundary Visualizer

Chunk Boundary Visualizer [#chunk-boundary-visualizer]

The **Chunk Boundary Visualizer** shows how a document was split into chunks. Each chunk renders as a distinct alternating-accent segment with a monospace `C1`/`C2` badge; in **semantic mode**, the inter-chunk boundary similarity (e.g. `sim: 0.74`) appears as a faint label between segments — lower values mark stronger topic breaks.

It takes a decoupled `ChunkInfo[]` (`text`, `chunkIndex`, `rightSimilarity`) plus the active mode, so it pairs directly with [`useSemanticChunk()`](https://localmode.dev/docs/react) from `@localmode/react`: map its `Chunk[]` output into `ChunkInfo[]`, pulling `rightSimilarity` from `chunk.metadata.semanticBoundaries`. It is display-only — it owns no chunking logic.

**When to use it:** a RAG ingest UI or a chunking playground where you want users to see *why* the document split where it did (e.g. tuning the semantic threshold).

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/data-documents/chunk-boundary-visualizer`

Full source: https://localmode.ai/r/ui/data-documents/chunk-boundary-visualizer.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/data-documents/chunk-boundary-visualizer
```

Dependencies [#dependencies]

* **Data source:** renders the plain `ChunkInfo[]` you pass — works with any chunker; recommended LocalMode producer: `useSemanticChunk` output mapped to `ChunkInfo[]` (optional).
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `chunk-boundary-visualizer.tsx` — the component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**ChunkBoundaryVisualizer**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `chunks` | `array` | — | **Required.** The chunks to visualize, in order. Map `useSemanticChunk`'s `Chunk[]` into `ChunkInfo[]` (pulling `rightSimilarity` from `metadata.semanticBoundaries`). |
| `mode` | `object & string \| "recursive" \| "fixed" \| "semantic"` | `"semantic"` | The active chunking mode. In `"semantic"`, inter-chunk similarity labels render between segments; other modes hide them. |
| `maxCharsPerChunk` | `number` | — | Truncate each chunk's preview to this many characters (`0`/undefined shows the full text). |

Examples [#examples]

Visualize `useSemanticChunk` output [#visualize-usesemanticchunk-output]

```tsx
import { ChunkBoundaryVisualizer } from '@/components/chunk-boundary-visualizer';
import { useSemanticChunk } from '@localmode/react';

export function ChunkingPlayground({ model }: { model: any }) {
  const { data: chunks, execute } = useSemanticChunk({ model, threshold: 0.4 });

  return (
    <div>
      <button onClick={() => execute(documentText)}>Chunk</button>
      <ChunkBoundaryVisualizer
        mode="semantic"
        chunks={(chunks ?? []).map((c) => ({
          text: c.text,
          chunkIndex: c.index,
          rightSimilarity: c.metadata?.semanticBoundaries?.rightSimilarity ?? null,
        }))}
      />
    </div>
  );
}
```

Fixed mode (segments only) [#fixed-mode-segments-only]

```tsx
{/* boundary labels are hidden when mode !== "semantic" */}
<ChunkBoundaryVisualizer mode="fixed" chunks={chunks} />
```

Truncate long chunks [#truncate-long-chunks]

```tsx
<ChunkBoundaryVisualizer
  mode="semantic"
  maxCharsPerChunk={160}
  chunks={chunks}
/>
```

Customization [#customization]

Segments cycle through four soft accent tints (`sky` / `violet` / `emerald` / `amber` at low opacity) with shadcn/ui CSS-variable text and borders, so they read as distinct while inheriting your theme. The `C#` badge uses a `font-mono` chip; the boundary label is a faint `sim: 0.NN` between thin rules.

Boundary similarity labels render only when `mode === "semantic"`, the chunk is not the last, and `rightSimilarity` is a finite number — so non-semantic modes show clean segments without labels. Because you own the file, you can swap the `SEGMENT_TINTS` palette, color-code boundaries by threshold, or render the full text instead of truncating in the copied `chunk-boundary-visualizer.tsx`.

# File Dropzone

File Dropzone [#file-dropzone]

The **File Dropzone** is a generic, format-agnostic drag-and-drop + click-to-browse upload zone built for non-image files — PDFs, CSV/JSON vector exports, audio, and the like. It validates every file with the copy-owned `validateFile()` helper against an `accept` MIME list and a `maxSize`, emitting only the valid files via `onUpload(files)`; rejected files go to `onReject`. The helper is installed automatically as a registry dependency, so the dropzone is portable — no `@localmode/react` requirement.

It is intentionally distinct from media-vision's `MediaDropzone`: there are **no image-preview semantics** here (no thumbnails). Two focused primitives beat one prop-bloated dropzone, and both reuse `validateFile`.

**When to use it:** ingest documents into a RAG pipeline (pdf-search), import vector exports (data-migrator), or accept meeting recordings (meeting-assistant) — anywhere you take non-image files and need accept-list + size validation with a processing overlay.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/data-documents/file-dropzone`

Full source: https://localmode.ai/r/ui/data-documents/file-dropzone.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/data-documents/file-dropzone
```

Dependencies [#dependencies]

* **Data source:** validates and emits the `File[]` you drop — works in any React app; no backend or model required.
* `@localmode/ui/lib/browser-utils` — the copy-owned `validateFile()` helper (installed automatically as a registry dependency)
* `lucide-react` — the upload / spinner icons
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `file-dropzone.tsx` — the component
* `lib/browser-utils.ts` — the copy-owned file helpers (if not already present)
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**FileDropzone**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onUpload` | `function` | — | **Required.** Called with the files that passed validation (accept-list + max-size). Only valid files are included. |
| `onReject` | `function` | — | Called when one or more dropped/selected files fail validation. Optional — use it to surface per-file errors. |
| `accept` | `array` | — | Accepted MIME types, e.g. `['application/pdf', 'text/csv', 'application/json']`. Passed to the native input's `accept` attribute (as a comma-joined list) and enforced by `validateFile`. When omitted, all types are accepted. |
| `maxSize` | `number` | — | Maximum file size in bytes. Files larger than this are rejected. |
| `multiple` | `boolean` | `true` | Allow selecting more than one file at a time. |
| `disabled` | `boolean` | `false` | Disable the zone (blocks drag and click). Combine with `processing` for an "uploading…" state. |
| `processing` | `boolean` | `false` | Show the processing overlay and block input. Use while files are being indexed/parsed. |
| `processingLabel` | `string` | `"Processing…"` | Message shown in the processing overlay. |
| `label` | `string` | `"Drop files or click to browse"` | Primary call-to-action text. |
| `hint` | `string` | — | Secondary hint line. Defaults to a human-readable summary of `accept` and `maxSize`. |

Examples [#examples]

Accept PDF / CSV / JSON [#accept-pdf--csv--json]

```tsx
import { FileDropzone } from '@/components/file-dropzone';

export function Ingest() {
  return (
    <FileDropzone
      accept={['application/pdf', 'text/csv', 'application/json']}
      maxSize={10_000_000}
      onUpload={(files) => ingest(files)}
      onReject={(rejected) => rejected.forEach((r) => console.warn(r.reason))}
    />
  );
}
```

Processing overlay [#processing-overlay]

```tsx
const [busy, setBusy] = useState(false);

<FileDropzone
  accept={['application/pdf']}
  processing={busy}
  processingLabel="Indexing…"
  onUpload={async (files) => {
    setBusy(true);
    await indexAll(files);
    setBusy(false);
  }}
/>
```

Single-file, custom hint [#single-file-custom-hint]

```tsx
<FileDropzone
  accept={['application/json']}
  multiple={false}
  label="Drop a vector export"
  hint="One .json file, up to 50MB"
  maxSize={50_000_000}
  onUpload={([file]) => importExport(file)}
/>
```

Customization [#customization]

The zone is styled with shadcn/ui CSS-variable utilities (`border-border`, `bg-card`, `bg-accent`, `text-muted-foreground`, `bg-primary/5`), so the dashed border, hover highlight, drag state, and overlay all inherit your theme. Because you own the file, you can swap the `UploadCloud` icon, change the `min-h-40` footprint, or extend the validation (e.g. dedupe by name) in the copied `file-dropzone.tsx`.

The `hint` line defaults to a human-readable summary derived from `accept` (extensions) and `maxSize`; pass an explicit `hint` to override it.

# Format Detection Badge

Format Detection Badge [#format-detection-badge]

The **Format Detection Badge** displays an auto-detected data format — `PINECONE`, `CHROMA`, `CSV`, `JSONL`, or any custom format — as a small color-coded pill. Pair it with [`useImportExport()`](https://localmode.dev/docs/react) from `@localmode/react`: after `parsePreview()` returns a `parseResult`, render `parseResult.format` to confirm the source format before importing.

It is fully self-contained and presentational — pass a `format` string and an optional `colorMap`. Unknown formats fall back to a neutral style, and a nullish `format` renders a pulsing "detecting…" state.

**When to use it:** confirm the detected format of a dropped vector export in a data-migration or import-preview UI. It is also consumed by the local-first `VectorImportFlow` (the import preview shows the detected format) as a registry dependency.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/data-documents/format-detection-badge`

Full source: https://localmode.ai/r/ui/data-documents/format-detection-badge.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/data-documents/format-detection-badge
```

Dependencies [#dependencies]

* **Data source:** renders the plain `format` string you pass — works with any backend; recommended LocalMode producer: `useImportExport`'s `parseResult.format` (optional).
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `format-detection-badge.tsx` — the component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**FormatDetectionBadge**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `format` | `object & string \| "jsonl" \| "csv" \| "chroma" \| "pinecone" \| null` | — | The detected data format (e.g. `"pinecone"`, `"chroma"`, `"csv"`, `"jsonl"`). The value is matched case-insensitively against the color map; the label is rendered upper-cased. When `null`/`undefined`, a neutral "detecting…" state renders instead. |
| `colorMap` | `Record<string, object>` | — | Per-format color map. Merged over {@link DEFAULT_FORMAT_COLORS}, so you can override a single format or add new ones. Keys are lower-cased before lookup. |
| `hideDot` | `boolean` | `false` | Hide the leading status dot. |
| `pendingLabel` | `string` | `"detecting…"` | Text shown while no format has been detected yet (`format` is nullish). |

Examples [#examples]

Drive it from `useImportExport` [#drive-it-from-useimportexport]

```tsx
import { FormatDetectionBadge } from '@/components/format-detection-badge';
import { useImportExport } from '@localmode/react';

export function ImportPreview({ db, content }: { db: any; content: string }) {
  const { parsePreview, parseResult } = useImportExport({ db });

  return (
    <div className="flex items-center gap-2">
      <button onClick={() => parsePreview({ content })}>Detect format</button>
      <FormatDetectionBadge format={parseResult?.format} />
    </div>
  );
}
```

Custom format + color [#custom-format--color]

```tsx
<FormatDetectionBadge
  format="parquet"
  colorMap={{
    parquet: {
      badge: 'bg-rose-500/10 text-rose-700 border-rose-500/30 dark:text-rose-300',
      dot: 'bg-rose-500',
    },
  }}
/>
```

Pending / unknown [#pending--unknown]

```tsx
{/* nullish format → pulsing "detecting…" */}
<FormatDetectionBadge format={null} />

{/* unknown format → neutral fallback */}
<FormatDetectionBadge format="avro" />
```

Customization [#customization]

The badge merges your `colorMap` over the built-in `DEFAULT_FORMAT_COLORS`, so you can override a single format or add new ones without editing the component. Each entry is a `{ badge, dot }` pair of Tailwind class strings — the `badge` classes set the tinted background/text/border and the `dot` sets the leading marker color. The neutral fallback and the pending state use shadcn/ui CSS variables (`bg-muted`, `text-muted-foreground`, `border-border`), so they inherit your theme.

Because you own the file, you can also export `DEFAULT_FORMAT_COLORS` and reuse the same map elsewhere (e.g. an import-flow legend).

# Indexed Document Card

Indexed Document Card [#indexed-document-card]

The **Indexed Document Card** is a consistent visual unit for a single document indexed into a VectorDB. It shows a truncated filename (full name in a native tooltip), the chunk count, an optional page count and file size, and a delete control that reveals on hover/focus and shows a spinner while the removal is in flight.

It is presentational: the page/chunk counts come from your app's ingest state — for example the length of [`useSemanticChunk()`](https://localmode.dev/docs/react) output plus a PDF page count — not a single hook, so the prop contract is explicit and any RAG / knowledge-base app fits.

**When to use it:** render the list of indexed files in a RAG sidebar or knowledge-base manager, with per-document delete. Pairs with RAG ingest (the `MultiStepPipelineTracker` from the conversation family).

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/data-documents/indexed-document-card`

Full source: https://localmode.ai/r/ui/data-documents/indexed-document-card.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/data-documents/indexed-document-card
```

Dependencies [#dependencies]

* **Data source:** renders the plain filename, counts, and size props you pass — works with any backend; recommended LocalMode producer: `useSemanticChunk` output length for the chunk count (optional).
* `lucide-react` — the document / delete / spinner icons
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `indexed-document-card.tsx` — the component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**IndexedDocumentCard**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `filename` | `string` | — | **Required.** Display name of the indexed document (e.g. `"report.pdf"`). |
| `chunkCount` | `number` | — | **Required.** Number of chunks the document was split into and stored in the VectorDB. Comes from your ingest state / `useSemanticChunk` output length. |
| `pageCount` | `number` | — | Number of pages, if known (e.g. from PDF extraction). Omit to hide. |
| `sizeBytes` | `number` | — | Original file size in bytes. Omit to hide. |
| `onDelete` | `function` | — | Called when the user activates the delete control. Wire it to your VectorDB delete; while it runs, pass `deleting` to show the loading state. |
| `deleting` | `boolean` | `false` | Show the delete control in a loading state and disable it (the removal is in flight). |

Examples [#examples]

Render an indexed document [#render-an-indexed-document]

```tsx
import { IndexedDocumentCard } from '@/components/indexed-document-card';

<IndexedDocumentCard
  filename="annual-report-2024.pdf"
  pageCount={42}
  chunkCount={128}
  sizeBytes={2_400_000}
  onDelete={() => removeFromVectorDB(doc.id)}
/>;
```

Wire delete to your VectorDB [#wire-delete-to-your-vectordb]

```tsx
const [removingId, setRemovingId] = useState<string | null>(null);

{docs.map((doc) => (
  <IndexedDocumentCard
    key={doc.id}
    filename={doc.filename}
    chunkCount={doc.chunks}
    pageCount={doc.pages}
    sizeBytes={doc.size}
    deleting={removingId === doc.id}
    onDelete={async () => {
      setRemovingId(doc.id);
      await db.delete(doc.id);
      setRemovingId(null);
    }}
  />
))}
```

From `useSemanticChunk` output [#from-usesemanticchunk-output]

```tsx
const { data: chunks } = useSemanticChunk({ model });

<IndexedDocumentCard
  filename={file.name}
  chunkCount={chunks?.length ?? 0}
  sizeBytes={file.size}
/>;
```

Customization [#customization]

The card is styled with shadcn/ui CSS-variable utilities (`border-border`, `bg-card`, `bg-muted`, `text-muted-foreground`, `hover:bg-destructive/10`), so it inherits your theme. The delete control hides until the card is hovered or the button is focused (and stays visible while `deleting`) via the `group/doc` hover scope — adjust that in the copied file if you want the control always visible.

The truncated filename uses a native `title` tooltip to keep the component dependency-free. Because you own the file, you can extend `IndexedDocumentCardProps` with extra metadata (e.g. indexed-at time, source type) and render it in the stats line.

# Char Limit Indicator

Char Limit Indicator [#char-limit-indicator]

The **Char Limit Indicator** is a compact character-count display: a radial progress ring (percentage of the limit consumed) paired with an `n/MAX` monospace counter. When `charCount` exceeds `maxLength`, the counter and ring switch to the error color and the ring shows a full circle.

The ring is a pure SVG implementation driven by shadcn/ui CSS variables (`text-primary`, `text-destructive`, `text-muted`) — no daisyUI, no canvas. It is self-contained: pass only `charCount` and `maxLength` and it derives the percentage internally, so it drops in beside any length-bounded textarea or [`PromptInput`](/docs/conversation/prompt-input).

**When to use it:** show how close a user is to a length limit (tweet box, prompt field, comment form) with an at-a-glance ring plus an exact count.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/input-controls/char-limit-indicator`

Full source: https://localmode.ai/r/ui/input-controls/char-limit-indicator.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/input-controls/char-limit-indicator
```

Dependencies [#dependencies]

* **Data source:** renders the `charCount` / `maxLength` props you pass — works with any backend (a plain `value.length`, a tokenizer, or a token-usage hook). Recommended LocalMode producer: `useChat` usage / token counting (optional).
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `char-limit-indicator.tsx` — the component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**CharLimitIndicator**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `charCount` | `number` | — | **Required.** Current number of characters in the bound input. |
| `maxLength` | `number` | — | **Required.** Maximum allowed characters. The ring fills as `charCount` approaches it. |
| `size` | `number` | `28` | Diameter of the ring in pixels. |
| `strokeWidth` | `number` | `3` | Stroke width of the ring in pixels. |
| `ringOnly` | `boolean` | `false` | When true, render only the ring (hide the `n/MAX` counter). |

Examples [#examples]

Beside a textarea [#beside-a-textarea]

```tsx
import { useState } from 'react';
import { CharLimitIndicator } from '@/components/char-limit-indicator';

export function Composer() {
  const [value, setValue] = useState('');
  const maxLength = 280;

  return (
    <div className="flex flex-col gap-2">
      <textarea value={value} onChange={(e) => setValue(e.target.value)} />
      <div className="flex justify-end">
        <CharLimitIndicator charCount={value.length} maxLength={maxLength} />
      </div>
    </div>
  );
}
```

Ring only [#ring-only]

```tsx
<CharLimitIndicator charCount={value.length} maxLength={280} ringOnly />
```

Customization [#customization]

The ring colors come straight from shadcn/ui CSS variables — `text-primary` under the limit, `text-destructive` over it, `text-muted` for the track — so the indicator inherits your theme automatically. Tune `size` and `strokeWidth` for the ring geometry; because you own the file, you can swap the over-limit color or add a near-limit warning band by editing the `overLimit` branch in `char-limit-indicator.tsx`.

# Copy Button

Copy Button [#copy-button]

The **Copy Button** copies its `value` to the clipboard and shows a 2-second
"Copied" confirmation before reverting. It disables itself when there is nothing
to copy, and treats an unavailable clipboard (insecure context or denied
permission) as a silent no-op — so it never throws in a hostile environment.

> **Presentational + controlled.** Pass the text via `value`; the button owns
> only its transient "Copied" state. Use it beside any generated text, code
> block, or result.

**When to use it:** anywhere the user should be able to copy a value with clear
visual confirmation — generated answers, model ids, export payloads, snippets.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/input-controls/copy-button`

Full source: https://localmode.ai/r/ui/input-controls/copy-button.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/input-controls/copy-button
```

Dependencies [#dependencies]

* **Data source:** copies the `value` string you pass — works with any backend.
* `lucide-react` — the copy / check icons
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `copy-button.tsx` — the component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**CopyButton**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | — | **Required.** The text written to the clipboard on click. |
| `disabled` | `boolean` | — | Disable the button (also disabled automatically when `value` is empty). |

Examples [#examples]

Copy a generated result [#copy-a-generated-result]

```tsx
import { CopyButton } from '@/components/copy-button';

export function ResultToolbar({ text }) {
  return <CopyButton value={text} />;
}
```

Force-disable while streaming [#force-disable-while-streaming]

```tsx
<CopyButton value={partial} disabled={isStreaming} />
```

Customization [#customization]

The button uses `border-border` / `hover:bg-muted` token utilities and merges
your `className`. Because you own the copied file, you can change the confirmation
duration (the `2000` ms timeout), swap the icons, or make it icon-only.

# Language Pair Selector

Language Pair Selector [#language-pair-selector]

The **Language Pair Selector** is a paired source/target language picker. The `pills` variant renders From/To pill toggles (flag + name) with a swap-languages button; the `compact` variant renders a grouped `{source} → {target}` pair of selects. It is fully controlled via `sourceCode` / `targetCode` and the `onSelectSource` / `onSelectTarget` / `onSwap` callbacks.

It is presentational and portable — feed the selected codes to any translation backend. With LocalMode you can (optionally) drive [`useTranslate()`](https://localmode.dev/docs/react) from `@localmode/react`, composed with [`useDetectLanguage()`](https://localmode.dev/docs/react) to auto-fill the source.

**When to use it:** any translation surface that lets the user choose a language pair and swap direction.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/input-controls/language-pair-selector`

Full source: https://localmode.ai/r/ui/input-controls/language-pair-selector.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/input-controls/language-pair-selector
```

Dependencies [#dependencies]

* **Data source:** renders the selected codes you pass and emits `onSelectSource` / `onSelectTarget` / `onSwap` callbacks — works with any backend. Recommended LocalMode producer: `useTranslate` (optionally composed with `useDetectLanguage`).
* `lucide-react` — the swap icon

Files installed [#files-installed]

* `language-pair-selector.tsx` — the component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**LanguagePairSelector**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `languages` | `array` | — | **Required.** All selectable languages, used for both source and target. |
| `sourceCode` | `string` | — | **Required.** Currently selected source code. |
| `targetCode` | `string` | — | **Required.** Currently selected target code. |
| `onSelectSource` | `function` | — | **Required.** Fired with the new source code. |
| `onSelectTarget` | `function` | — | **Required.** Fired with the new target code. |
| `onSwap` | `function` | — | **Required.** Fired when the swap button exchanges source and target. |
| `variant` | `"compact" \| "pills"` | `"pills"` | Layout variant. `pills` renders From/To pill toggles with a swap button; `compact` renders a grouped `{source} → {target}` pair of selects. |

Examples [#examples]

Drive a translation [#drive-a-translation]

```tsx
import { useState } from 'react';
import { useTranslate } from '@localmode/react';
import { transformers } from '@localmode/transformers';
import { LanguagePairSelector } from '@/components/language-pair-selector';

const LANGS = [
  { code: 'en', name: 'English', flag: '🇬🇧' },
  { code: 'fr', name: 'French', flag: '🇫🇷' },
];

export function Translator() {
  const [src, setSrc] = useState('en');
  const [tgt, setTgt] = useState('fr');
  const { execute, data } = useTranslate({
    model: transformers.translator(`Xenova/opus-mt-${src}-${tgt}`),
  });

  return (
    <LanguagePairSelector
      languages={LANGS}
      sourceCode={src}
      targetCode={tgt}
      onSelectSource={setSrc}
      onSelectTarget={setTgt}
      onSwap={() => { setSrc(tgt); setTgt(src); }}
    />
  );
}
```

Compact variant [#compact-variant]

```tsx
<LanguagePairSelector variant="compact" languages={LANGS} {...props} />
```

Customization [#customization]

`flag` is optional per language and renders before the name. The active pill uses `bg-primary/10 text-primary`; the compact variant uses native styled selects for a tight footprint. Everything is theme-driven via shadcn/ui CSS variables — edit the copied file to change the pill shape or wire the swap button to additional side effects.

# Mask Token Input

Mask Token Input [#mask-token-input]

The **Mask Token Input** is a textarea for fill-mask / cloze input. It detects a configurable mask token (default `[MASK]`), renders an inline highlighted preview with the mask span accented, shows a validation hint (`Mask detected` vs `Add [MASK]`), offers a randomize button that inserts a valid sample, and surfaces a Cmd+Enter badge for one-key submit.

It is presentational and portable — pair its `value` / `onSubmit` with any fill-mask backend to run predictions and render the returned fills. With LocalMode you can (optionally) wire it to [`useFillMask()`](https://localmode.dev/docs/react) from `@localmode/react`.

**When to use it:** any masked-language task — "The capital of France is `[MASK]`." → top predictions.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/input-controls/mask-token-input`

Full source: https://localmode.ai/r/ui/input-controls/mask-token-input.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/input-controls/mask-token-input
```

Dependencies [#dependencies]

* **Data source:** renders the `value` you pass and emits `onChange` / `onSubmit` callbacks — works with any backend. Recommended LocalMode producer: `useFillMask` (optional).
* No npm dependencies (only the shared `cn()` util via `@localmode/ui/lib/utils`).

Files installed [#files-installed]

* `mask-token-input.tsx` — the component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**MaskTokenInput**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | — | **Required.** Current text value (controlled). |
| `onChange` | `function` | — | **Required.** Fired with the new text on every edit. |
| `maskToken` | `string` | `"[MASK]"` | The mask token the fill-mask model expects. |
| `onSubmit` | `function` | — | Fired on Cmd/Ctrl+Enter (and via the inline hint button) when the value contains the mask token — wire this to your `useFillMask().execute(value)`. |
| `samples` | `array` | — | Sample sentences inserted by the randomize button. Each should contain the `maskToken`. If omitted, a small built-in set is used. |
| `placeholder` | `string` | — | Placeholder for the textarea. |
| `ariaLabel` | `string` | `"Fill-mask sentence"` | Accessible name for the textarea. The field has no associated visible `<label>`, so this is applied as its `aria-label`; override it to match a nearby heading in your layout. |
| `disabled` | `boolean` | — | Disable input and actions (e.g. while a prediction is running). |

Examples [#examples]

Wired to `useFillMask` [#wired-to-usefillmask]

```tsx
import { useState } from 'react';
import { useFillMask } from '@localmode/react';
import { transformers } from '@localmode/transformers';
import { MaskTokenInput } from '@/components/mask-token-input';

export function ClozeBox() {
  const [text, setText] = useState('The capital of France is [MASK].');
  const { data, isLoading, execute } = useFillMask({
    model: transformers.fillMask('Xenova/bert-base-uncased'),
    topK: 5,
  });

  return (
    <div className="flex flex-col gap-3">
      <MaskTokenInput value={text} onChange={setText} onSubmit={execute} disabled={isLoading} />
      {data?.predictions.map((p) => (
        <div key={p.token}>{p.token} — {(p.score * 100).toFixed(1)}%</div>
      ))}
    </div>
  );
}
```

Custom mask token [#custom-mask-token]

```tsx
<MaskTokenInput value={text} onChange={setText} maskToken="<mask>" />
```

Accessible name [#accessible-name]

The textarea has no visible `<label>`, so it ships with an `aria-label` (default `"Fill-mask sentence"`). Override `ariaLabel` to match a nearby heading in your layout.

```tsx
<MaskTokenInput value={text} onChange={setText} ariaLabel="Sentence to complete" />
```

Customization [#customization]

The mask span is highlighted with `bg-primary/15 text-primary`; the validation hint uses Tailwind's `emerald` / `amber` palettes. Pass your own `samples` (each containing the mask token) to control what Randomize inserts. Set `ariaLabel` to give the textarea a programmatic name. The component is theme-driven via shadcn/ui CSS variables — edit the copied `mask-token-input.tsx` to change the preview styling or add multi-mask support.

# Option List

Option List [#option-list]

The **Option List** is an inline multi-choice selection list presented in a chat / agent turn for the user to pick from — distinct from quick-reply suggestion chips. It shows up to `pageSize` (5–7) options at a time and paginates longer lists. The chosen option is meant to feed back into your agent inquiry loop — for example a local human-in-the-loop disambiguation step (optionally [`useAgent`](https://localmode.dev/docs/react)).

It is presentational; the agent loop is owned by the consumer.

**When to use it:** when a local agent needs the user to disambiguate among several candidates ("Which file did you mean?") before continuing.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/input-controls/option-list`

Full source: https://localmode.ai/r/ui/input-controls/option-list.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/input-controls/option-list
```

Dependencies [#dependencies]

* **Data source:** renders the `options` you pass and emits the `onSelect` callback — works with any backend or agent loop. Recommended LocalMode producer: `useAgent` inquiry/human-in-the-loop (optional).
* `lucide-react` — the pagination icons
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically)

Files installed [#files-installed]

* `option-list.tsx` — the component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**OptionList**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` | `array` | — | **Required.** The choices to present. Lists longer than `pageSize` paginate. |
| `onSelect` | `function` | — | **Required.** Fired with the chosen option when the user selects one. |
| `pageSize` | `number` | `6` | Maximum options shown per page before paginating. |
| `prompt` | `string` | — | Optional prompt rendered above the choices. |
| `selectedId` | `string` | — | Currently selected option id (renders that option as active). |
| `disabled` | `boolean` | — | Disable interaction (e.g. while the agent is thinking). |

Examples [#examples]

Feed a `useAgent` inquiry [#feed-a-useagent-inquiry]

```tsx
import { OptionList } from '@/components/option-list';

export function Disambiguator({ candidates, onPick }) {
  return (
    <OptionList
      prompt="Which file did you mean?"
      options={candidates}
      onSelect={(opt) => onPick(opt.id)} // resume the agent loop with the choice
    />
  );
}
```

Custom page size [#custom-page-size]

```tsx
<OptionList options={options} onSelect={onSelect} pageSize={5} />
```

Customization [#customization]

Lists longer than `pageSize` paginate automatically with Prev / Next controls. Each option can carry a `description` for a secondary line. Pass `selectedId` to render the chosen option as active. Everything is theme-driven via shadcn/ui CSS variables — edit the copied file to change the row layout or add keyboard navigation.

# Parameter Slider

Parameter Slider [#parameter-slider]

The **Parameter Slider** is an inline range slider with a live value readout for reversible adjustment of a local generation parameter — temperature, top-k, top-p, max tokens, GPU layers, KV-cache quant. It is fully controlled, and the emitted value feeds straight into your next local generation call.

It is built on the shadcn/ui [`Slider`](https://ui.shadcn.com/docs/components/slider) primitive, so it inherits your theme. Wire `value` / `onChange` into the options you pass to [`useGenerateText()`](https://localmode.dev/docs/react) or [`useChat()`](https://localmode.dev/docs/react).

**When to use it:** a settings panel or chat composer where the user tunes how the local model generates.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/input-controls/parameter-slider`

Full source: https://localmode.ai/r/ui/input-controls/parameter-slider.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/input-controls/parameter-slider
```

Dependencies [#dependencies]

* **Data source:** renders the controlled `value` you pass and emits `onChange` — works with any backend. Recommended LocalMode producer: feed the value into `useGenerateText` / `useChat` options (optional).
* `radix-ui` — the underlying slider primitive
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically)

Files installed [#files-installed]

* `parameter-slider.tsx` — the component
* `ui/slider.tsx` — the shadcn/ui slider primitive (registry dependency)
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**ParameterSlider**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | — | **Required.** Visible label (e.g. "Temperature", "Max tokens", "GPU layers"). |
| `value` | `number` | — | **Required.** Current value (controlled). |
| `onChange` | `function` | — | **Required.** Fired with the new value while dragging. |
| `min` | `number` | — | **Required.** Minimum value. |
| `max` | `number` | — | **Required.** Maximum value. |
| `step` | `number` | `1` | Step granularity. |
| `precision` | `number` | `0` | Decimal places to show in the live readout (useful for temperature/top-p). |
| `unit` | `string` | — | Optional unit suffix shown after the value (e.g. "tokens"). |
| `description` | `string` | — | Optional one-line description shown under the label. |
| `disabled` | `boolean` | — | Disable the slider. |

Examples [#examples]

Tune temperature for `useGenerateText` [#tune-temperature-for-usegeneratetext]

```tsx
import { useState } from 'react';
import { useGenerateText } from '@localmode/react';
import { ParameterSlider } from '@/components/parameter-slider';

export function GenSettings({ model }) {
  const [temp, setTemp] = useState(0.7);
  const { execute } = useGenerateText({ model, temperature: temp });

  return (
    <ParameterSlider
      label="Temperature"
      value={temp}
      onChange={setTemp}
      min={0}
      max={2}
      step={0.1}
      precision={1}
    />
  );
}
```

Integer parameter with a unit [#integer-parameter-with-a-unit]

```tsx
<ParameterSlider label="Max tokens" value={maxTokens} onChange={setMaxTokens} min={16} max={2048} step={16} unit="tokens" />
```

Customization [#customization]

Set `precision` for decimal readouts (temperature, top-p) and `unit` for a suffix. The slider track and thumb use shadcn/ui CSS variables (`bg-primary`, `border-primary`), so the control matches your theme. Because you own the file, you can add tick marks or snap-to presets by editing `parameter-slider.tsx`.

Accessibility [#accessibility]

The control renders the Radix `Slider` primitive **directly** (not a wrapped `<Slider>`) because Radix ignores `aria-label` on the Root — so the accessible name and formatted readout must land on the focusable Thumb, the element that actually carries `role="slider"`. The Thumb takes its `aria-label` from `label` and an `aria-valuetext` formatted with `precision` + `unit` (e.g. `"0.7"`, `"512 tokens"`), so screen readers announce the parameter name and a human-readable value instead of the raw number, and `getByRole('slider', { name: label })` resolves it uniquely.

# Prompt Enhance Button

Prompt Enhance Button [#prompt-enhance-button]

The **Prompt Enhance Button** is a one-click "enhance my prompt" control for a composer. It hands the user's draft to your rewrite backend via the `onEnhance` callback — optionally wired to [`useGenerateText()`](https://localmode.dev/docs/react) for a fully offline local rewrite — and applies the result. An optional few-shot example editor lets users teach the rewrite by example.

It is presentational + callback-driven; the rewrite runs on a local model in your app.

**When to use it:** a chat or generation composer where users want a quick, private way to sharpen a rough prompt.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/input-controls/prompt-enhance-button`

Full source: https://localmode.ai/r/ui/input-controls/prompt-enhance-button.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/input-controls/prompt-enhance-button
```

Dependencies [#dependencies]

* **Data source:** runs the rewrite through the `onEnhance` callback you supply and applies it via `onApply` — works with any backend. Recommended LocalMode producer: `useGenerateText` (optional).
* `lucide-react` — icons

Files installed [#files-installed]

* `prompt-enhance-button.tsx` — the component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**PromptEnhanceButton**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onEnhance` | `function` | — | **Required.** Enhance the given draft and resolve with the rewritten prompt. Wire this to a local generation call — e.g. `useGenerateText().execute(buildInstruction(draft))`. The `examples` are the current few-shot pairs (if the editor is enabled). |
| `draft` | `string` | — | **Required.** The current draft prompt to improve. |
| `onApply` | `function` | — | **Required.** Fired with the improved prompt when enhancement succeeds. |
| `showExampleEditor` | `boolean` | `false` | Show an inline few-shot example editor for interactive prompt tuning. |
| `label` | `string` | — | Button label. |
| `disabled` | `boolean` | — | Disable the control. |

Examples [#examples]

Enhance a draft locally [#enhance-a-draft-locally]

```tsx
import { useState } from 'react';
import { useGenerateText } from '@localmode/react';
import { transformers } from '@localmode/transformers';
import { PromptEnhanceButton } from '@/components/prompt-enhance-button';

export function Composer() {
  const [prompt, setPrompt] = useState('write about dogs');
  const { execute } = useGenerateText({
    model: transformers.languageModel('onnx-community/Qwen3-0.6B-ONNX'),
    maxTokens: 120,
  });

  return (
    <PromptEnhanceButton
      draft={prompt}
      onApply={setPrompt}
      onEnhance={async (draft) => {
        const r = await execute(
          `Rewrite this prompt to be clearer. Return only the improved prompt:\n${draft}`,
        );
        return r?.text.trim() ?? null;
      }}
    />
  );
}
```

With the few-shot editor [#with-the-few-shot-editor]

```tsx
<PromptEnhanceButton draft={prompt} onApply={setPrompt} onEnhance={enhance} showExampleEditor />
```

Customization [#customization]

The button surfaces its own loading + error state; you only supply `onEnhance` (returning the improved string) and `onApply`. The optional few-shot editor collects `draft → improved` pairs and passes them to `onEnhance` so you can include them in the local generation instruction. Everything is theme-driven via shadcn/ui CSS variables.

# Segmented Mode Picker

Segmented Mode Picker [#segmented-mode-picker]

The **Segmented Mode Picker** is a pill toggle for 2–4 mutually-exclusive named modes — OCR content-type, summary length, translation formality, and the like. It renders as a classic segmented control: a muted track with the active segment raised on a `bg-background&#x60; chip. It ships a typed &#x2A;*`TabBar`** variant: an underline tab bar with `disabledTabs` gating (e.g. an "Inspect" tab disabled until a model is selected).

Both are fully controlled and purely presentational.

**When to use it:** switch between a small fixed set of options that change how a task runs (length, format, mode).

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/input-controls/segmented-mode-picker`

Full source: https://localmode.ai/r/ui/input-controls/segmented-mode-picker.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/input-controls/segmented-mode-picker
```

Dependencies [#dependencies]

* **Data source:** renders the controlled `items` / `selectedId` you pass and emits `onSelect` — works with any backend. Recommended LocalMode producer: feed the selected mode into any task hook, e.g. `useSummarize` length (optional).
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `segmented-mode-picker.tsx` — both `SegmentedModePicker` and `TabBar`
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**SegmentedModePicker**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `array` | — | **Required.** The 2–4 mutually-exclusive modes to render. |
| `selectedId` | `TId` | — | **Required.** Currently selected mode id. |
| `onSelect` | `function` | — | **Required.** Fired with the selected mode id when the user activates a mode. |
| `accent` | `string` | `"bg-background text-foreground shadow-sm"` | Classes applied to the active segment. Defaults to a raised segmented-control look (`bg-background text-foreground shadow-sm`) that reads clearly on the muted track in both light and dark themes. |
| `aria-label` | `string` | — | Accessible label for the group. |

`TabBar` [#tabbar]

**TabBar**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tabs` | `array` | — | **Required.** The tabs to render. |
| `activeId` | `TId` | — | **Required.** Currently active tab id. |
| `onSelect` | `function` | — | **Required.** Fired with the tab id when a (non-disabled) tab is activated. |
| `disabledTabs` | `array` | — | Ids of tabs that are present but not selectable. |
| `aria-label` | `string` | — | Accessible label for the tablist. |

Examples [#examples]

Summary length picker [#summary-length-picker]

```tsx
import { useState } from 'react';
import { SegmentedModePicker } from '@/components/segmented-mode-picker';

export function LengthPicker() {
  const [mode, setMode] = useState<'short' | 'medium' | 'long'>('medium');
  return (
    <SegmentedModePicker
      items={[
        { id: 'short', label: 'Short' },
        { id: 'medium', label: 'Medium' },
        { id: 'long', label: 'Long' },
      ]}
      selectedId={mode}
      onSelect={setMode}
    />
  );
}
```

Typed `TabBar` with a disabled tab [#typed-tabbar-with-a-disabled-tab]

```tsx
<TabBar
  tabs={[
    { id: 'browse', label: 'Browse' },
    { id: 'inspect', label: 'Inspect' },
  ]}
  activeId={tab}
  onSelect={setTab}
  disabledTabs={['inspect']}
/>
```

Customization [#customization]

The active segment is raised on a `bg-background text-foreground shadow-sm` chip over the muted track by default; pass an `accent` class string to restyle it. Both components are generic over the id type, so `onSelect` is typed to your union. Everything is theme-driven via shadcn/ui CSS variables — edit the copied file to change spacing, sizing, or the underline treatment.

Accessibility [#accessibility]

The segmented control is a `role="radiogroup"` of `role="radio"` segments that announce their selected state via `aria-checked`; the `TabBar` variant is a `role="tablist"` of `role="tab"` items. The segment row `flex-wrap`s and its labels no longer `truncate`, so a long mode/VAD label wraps inside its segment (multi-line) instead of clipping at narrow widths (down to 375px). Selection is fully keyboard-operable and `getByRole('radio', { name })` resolves each segment.

# Slash Command Palette

Slash Command Palette [#slash-command-palette]

The **Slash Command Palette** is a command-palette dropdown triggered by "/" in the composer to pick tools or commands by name, category, description, and icon — designed to layer onto a [`PromptInput`](/docs/conversation/prompt-input) Tools slot. It is purely presentational over a local list: the consumer decides when to open it (e.g. when the composer value starts with "/") and what query to pass.

It is built on the shadcn/ui [`Command`](https://ui.shadcn.com/docs/components/command) (cmdk) primitive for fuzzy filtering and keyboard navigation, so it inherits your theme.

**When to use it:** a composer where typing "/" should reveal a pickable list of tools or commands.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/input-controls/slash-command-palette`

Full source: https://localmode.ai/r/ui/input-controls/slash-command-palette.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/input-controls/slash-command-palette
```

Dependencies [#dependencies]

* **Data source:** renders the `commands` list you pass and emits `onSelect` / `onDismiss` callbacks — works with any backend. Recommended LocalMode producer: a local tool/command list (e.g. an agent's tool registry) (optional).
* `cmdk` — the underlying command primitive
* `lucide-react` — icons
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically)

Files installed [#files-installed]

* `slash-command-palette.tsx` — the component
* `ui/command.tsx` — the shadcn/ui command primitive (registry dependency)
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**SlashCommandPalette**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `commands` | `array` | — | **Required.** The local list of commands/tools to offer. |
| `open` | `boolean` | — | **Required.** Whether the palette is shown (typically: composer value starts with "/"). |
| `query` | `string` | — | The current search query (typically the composer text after the "/"). Filters the list. |
| `onSelect` | `function` | — | **Required.** Fired with the chosen command when the user selects one. |
| `onDismiss` | `function` | — | **Required.** Fired when the palette should dismiss (Escape or selection). |

Examples [#examples]

Open when the composer starts with "/" [#open-when-the-composer-starts-with-]

```tsx
import { useState } from 'react';
import { Search, Image } from 'lucide-react';
import { SlashCommandPalette } from '@/components/slash-command-palette';

const COMMANDS = [
  { id: 'search', name: 'search', description: 'Search the web', category: 'Tools', icon: Search },
  { id: 'image', name: 'image', description: 'Generate an image', category: 'Tools', icon: Image },
];

export function Composer() {
  const [value, setValue] = useState('');
  const open = value.startsWith('/');

  return (
    <div className="relative">
      <input value={value} onChange={(e) => setValue(e.target.value)} />
      {open && (
        <SlashCommandPalette
          commands={COMMANDS}
          open={open}
          query={value.slice(1)}
          onSelect={(cmd) => setValue(`/${cmd.name} `)}
          onDismiss={() => setValue('')}
        />
      )}
    </div>
  );
}
```

Customization [#customization]

Commands are grouped by `category` (uncategorized commands fall under "Commands"). The palette filters on name + description via cmdk. Position it yourself (e.g. absolutely below the composer). Everything is theme-driven via shadcn/ui CSS variables — edit the copied file to change the row layout or add command shortcuts.

# System Prompt Editor

System Prompt Editor [#system-prompt-editor]

The **System Prompt Editor** is a controlled editor for a chat/completion system
prompt with quick-pick presets. Selecting a preset replaces the textarea value;
free-form edits that match no preset deselect all presets. It composes the
[Option List](/docs/input-controls/option-list) primitive for the presets and
exports `SYSTEM_PROMPT_PRESETS` and `DEFAULT_SYSTEM_PROMPT` as sensible defaults.

> **Presentational (value in, `onChange` out).** Persistence and model wiring
> stay in the consumer — the editor never touches storage. Recommended
> destination: the `systemPrompt` you pass to `useChat` / `useGenerateText`
> (a recommendation, never a requirement).

**When to use it:** any chat or generation surface that lets the user set or
switch the assistant's system prompt with a few opinionated presets.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/input-controls/system-prompt-editor`

Full source: https://localmode.ai/r/ui/input-controls/system-prompt-editor.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/input-controls/system-prompt-editor
```

Dependencies [#dependencies]

* **Data source:** fully controlled — emits `onChange(value)`; the consumer owns persistence and applies the value to a model. Recommended destination: `useChat` / `useGenerateText` `systemPrompt` (optional).
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)
* Composes `@localmode/ui/input-controls/option-list` (installed automatically as a registry dependency)

Files installed [#files-installed]

* `system-prompt-editor.tsx` — the component (exports `SYSTEM_PROMPT_PRESETS`, `DEFAULT_SYSTEM_PROMPT`)
* `option-list.tsx` — the composed preset list
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**SystemPromptEditor**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | — | **Required.** The current system prompt (controlled). |
| `onChange` | `function` | — | **Required.** Fired with the new prompt on every edit or preset selection. |
| `ariaLabel` | `string` | `"System prompt"` | Accessible name for the textarea, applied as its `aria-label` so the control has a programmatic name independent of the visible heading. |

**SystemPromptPreset**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` | — | **Required.** Stable preset identifier. |
| `label` | `string` | — | **Required.** Short visible label. |
| `description` | `string` | — | **Required.** One-line description shown under the label. |
| `prompt` | `string` | — | **Required.** The full system prompt applied on selection. |

Examples [#examples]

Wire to a chat system prompt (consumer owns persistence) [#wire-to-a-chat-system-prompt-consumer-owns-persistence]

```tsx
import { useState } from 'react';
import {
  SystemPromptEditor,
  DEFAULT_SYSTEM_PROMPT,
} from '@/components/system-prompt-editor';

export function PromptPanel() {
  const [prompt, setPrompt] = useState(
    () => localStorage.getItem('systemPrompt') ?? DEFAULT_SYSTEM_PROMPT,
  );
  return (
    <SystemPromptEditor
      value={prompt}
      onChange={(v) => {
        setPrompt(v);
        localStorage.setItem('systemPrompt', v); // persistence is yours
      }}
    />
  );
}
```

Extend the presets [#extend-the-presets]

`SYSTEM_PROMPT_PRESETS` is exported — spread it and add your own before rendering,
or edit the copied file directly.

Accessible name [#accessible-name]

The textarea carries an `aria-label` (default `"System prompt"`) so it has a
programmatic name independent of the visible heading. Override `ariaLabel` if
your surrounding copy names the field differently.

```tsx
<SystemPromptEditor value={prompt} onChange={setPrompt} ariaLabel="Assistant instructions" />
```

Customization [#customization]

The editor is purely presentational: value in, `onChange` out. Because you own
the copied file, add or remove presets, change the textarea rows, or attach your
own persistence and `useChat` wiring — the primitive stays free of orchestration
state.

# Text Processing Panel

Text Processing Panel [#text-processing-panel]

The **Text Processing Panel** is a two-column (stacked on mobile) single-input → single-output NLP shell. The left column is a labeled textarea with a live word count and an optional [`CharLimitIndicator`](/docs/input-controls/char-limit-indicator); the right column is a result pane (spinner while processing, pre-wrap text otherwise, or an empty slot) with a copy-with-feedback button. A run / cancel / clear toolbar sits below, and an optional `header` slot renders above both columns — drop a [`SegmentedModePicker`](/docs/input-controls/segmented-mode-picker) or [`LanguagePairSelector`](/docs/input-controls/language-pair-selector) there.

It is layout-only. Own the inference in your app by wiring the toolbar to any text-in/text-out hook — `useSummarize`, `useTranslate`, `useFillMask`, `useAnswerQuestion`, or `useGenerateText` — and passing `result` / `isProcessing` back in.

**When to use it:** the paste → process → copy layout that recurs across summarization, translation, QA-context, and generation utilities.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/input-controls/text-processing-panel`

Full source: https://localmode.ai/r/ui/input-controls/text-processing-panel.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/input-controls/text-processing-panel
```

Dependencies [#dependencies]

* **Data source:** layout-only — renders the `result` / `isProcessing` you pass and emits `onRun` / `onCancel` / `onClear` callbacks, so it works with any text-in/text-out backend. Recommended LocalMode producers: `useSummarize` / `useTranslate` / `useFillMask` / `useAnswerQuestion` / `useGenerateText` (optional).
* `CharLimitIndicator` — composed for the optional limit ring (installed automatically as a registry dependency)
* `lucide-react` — icons

Files installed [#files-installed]

* `text-processing-panel.tsx` — the component
* `char-limit-indicator.tsx` — composed for the optional limit ring (registry dependency)
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**TextProcessingPanel**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | — | **Required.** Input text (controlled). |
| `onChange` | `function` | — | **Required.** Fired with the new input text on every edit. |
| `result` | `string` | — | The processed result text (rendered pre-wrap in the result pane). |
| `isProcessing` | `boolean` | — | Whether a run is in progress (shows a spinner in the result pane). |
| `error` | `string` | — | Error message to surface under the result pane. |
| `onRun` | `function` | — | **Required.** Fired when the user activates Run. |
| `onCancel` | `function` | — | Fired when the user activates Cancel during processing. |
| `onClear` | `function` | — | Fired when the user activates Clear (reset input + result). |
| `inputLabel` | `string` | — | Label above the input column. |
| `resultLabel` | `string` | — | Label above the result column. |
| `placeholder` | `string` | — | Placeholder for the input textarea. |
| `maxLength` | `number` | — | When set, shows a {@link CharLimitIndicator} under the input. |
| `runLabel` | `string` | — | Run button text. |
| `header` | `ReactNode` | — | Optional header slot rendered above the two columns (tab bar, mode picker, language selector). |
| `emptyState` | `ReactNode` | — | Content shown in the result pane when there is no result yet. |

Examples [#examples]

Summarize [#summarize]

```tsx
import { useState } from 'react';
import { useSummarize } from '@localmode/react';
import { transformers } from '@localmode/transformers';
import { TextProcessingPanel } from '@/components/text-processing-panel';

export function Summarizer() {
  const [text, setText] = useState('');
  const { data, isLoading, execute, cancel, reset } = useSummarize({
    model: transformers.summarizer('Xenova/distilbart-cnn-6-6'),
  });

  return (
    <TextProcessingPanel
      value={text}
      onChange={setText}
      result={data?.summary}
      isProcessing={isLoading}
      onRun={() => execute({ text })}
      onCancel={cancel}
      onClear={reset}
      inputLabel="Article"
      resultLabel="Summary"
      runLabel="Summarize"
    />
  );
}
```

Translate (header slot) [#translate-header-slot]

```tsx
const { data, isLoading, execute } = useTranslate({ model });
<TextProcessingPanel
  value={text}
  onChange={setText}
  result={data?.translation}
  isProcessing={isLoading}
  onRun={() => execute({ text, sourceLanguage: src, targetLanguage: tgt })}
  header={<LanguagePairSelector {...pairProps} />}
/>
```

Customization [#customization]

Pass `maxLength` to show the `CharLimitIndicator` under the input. The result pane renders `result` pre-wrap; for richer output (lists, predictions) drop your own node into `emptyState` or format `result` before passing it in. Keep the inference in your app — the panel stays a layout shell with slots. Everything is theme-driven via shadcn/ui CSS variables.

Accessibility [#accessibility]

The input textarea has no rendered `<label>` element, so it takes its &#x2A;*accessible name from `inputLabel`** — the same string shown above the column is also wired as the textarea's `aria-label`. Give each panel a descriptive `inputLabel` ("Text to summarize", "Source text") and `getByLabel(inputLabel)` resolves the field uniquely across panels on the same page. The Copy button on the result pane is labelled `"Copy result"`.

# Event Log Viewer

Event Log Viewer [#event-log-viewer]

The **Event Log Viewer** renders a devtools event stream newest first: relative timestamps (absolute on hover), namespace-colored type badges (`vectordb:` emerald, `embedding:` sky, `model` violet, `queue` amber, `pipeline` fuchsia, `storage` orange), and the serialized payload per entry. A case-insensitive substring filter narrows by event type, the visible list is capped (default 100, overridable via `maxVisible`) with an overflow line for older hidden matches, and the "no events yet" and "no events matching filter" empty states are distinct. A Clear affordance renders only when `onClear` is provided. It preserves the filter + cap semantics of the deprecated `@localmode/devtools` widget's Events panel. Values are passed in as props — works with any backend; recommended data source: `useDevToolsEvents` from `@localmode/devtools/react` (on-device, optional).

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/devtools/event-log-viewer`

Full source: https://localmode.ai/r/ui/devtools/event-log-viewer.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/devtools/event-log-viewer
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders whatever `events` you pass — works with any backend or event bus. Recommended producer: the `useDevToolsEvents` hook from `@localmode/devtools/react` (on-device, optional); its `DevToolsEvent[]` output matches `DevToolsEventLike` field-for-field, so it feeds the `events` prop with no mapping layer.

* `lucide-react` — icons
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `event-log-viewer.tsx` — the `EventLogViewer` component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**EventLogViewer**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `events` | `array` | — | **Required.** The event stream, oldest first (the order `useDevToolsEvents` returns). Rendered newest first. |
| `maxVisible` | `number` | `100` | Maximum number of events visible at once, applied after filtering and keeping the newest. An overflow line reports how many older matches are hidden. |
| `filter` | `string` | — | Controlled filter value. Omit to let the component manage its own filter state internally. |
| `onFilterChange` | `function` | — | Called with the new filter text whenever the filter input changes. |
| `onClear` | `function` | — | When provided, a Clear button renders and invokes this callback. |

**DevToolsEventLike**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `number` | — | **Required.** Monotonically increasing event ID. |
| `type` | `string` | — | **Required.** Namespaced event type (e.g. `'vectordb:add'`, `'embedding:embedComplete'`). |
| `data` | `Record<string, unknown>` | — | **Required.** Event payload. |
| `timestamp` | `string` | — | **Required.** ISO 8601 timestamp. |

Examples [#examples]

Bound to the devtools event stream [#bound-to-the-devtools-event-stream]

Enable devtools once at app init (`enableDevTools()` from `@localmode/devtools`), then the hook streams the bridge's event buffer — oldest first, exactly what `events` expects:

```tsx
import { useDevToolsEvents } from '@localmode/devtools/react';
import { EventLogViewer } from '@/components/event-log-viewer';

function EventsTab() {
  const events = useDevToolsEvents();
  return <EventLogViewer events={events} maxVisible={100} />;
}
```

Pre-narrowed to one namespace [#pre-narrowed-to-one-namespace]

Pass the hook's own `types` filter to scope the stream before it reaches the viewer (the in-component filter then narrows further):

```tsx
const events = useDevToolsEvents({ types: ['vectordb'] });

<EventLogViewer events={events} />
```

Controlled filter with a clear affordance [#controlled-filter-with-a-clear-affordance]

Own the filter in the parent (e.g. to sync it with a URL param) and wire `onClear` to whatever resets your buffer:

```tsx
const [filter, setFilter] = useState('');

<EventLogViewer
  events={events}
  filter={filter}
  onFilterChange={setFilter}
  onClear={() => setEvents([])}
/>
```

Customization [#customization]

Type badges are colored by the namespace before the `:` in the event type — the `NAMESPACE_BADGES` map in the copied file is yours to extend with your own namespaces (unknown namespaces fall back to a neutral badge). The list scrolls internally past `max-h-96`; the overflow line reports matches hidden by `maxVisible`. Styled entirely with shadcn/ui CSS-variable utilities so it inherits your theme — because you own the copied file, every class, cap, and empty-state message is yours to change.

# DevTools

The **DevTools family** turns on-device AI observability into copy-owned UI. Each
primitive renders plain props — the recommended producers are the nine hooks on
`@localmode/devtools/react`, but any backend that shapes the same data works
("local-first by design, cloud-compatible by contract").

Components [#components]

| Component                                                         | Renders                                                       | Recommended hook          |
| ----------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------- |
| [Inference Queue Monitor](/docs/devtools/inference-queue-monitor) | Per-queue pending / active / completed / failed / avg-latency | `useDevToolsQueueStats`   |
| [Event Log Viewer](/docs/devtools/event-log-viewer)               | Newest-first namespaced event stream with filter + cap        | `useDevToolsEvents`       |
| [Pipeline Run Inspector](/docs/devtools/pipeline-run-inspector)   | Per-run status, progress, current step, durations             | `useDevToolsPipelineRuns` |
| [Model Cache Table](/docs/devtools/model-cache-table)             | Cached models: status, load time, last used, size, evict      | `useDevToolsModelCache`   |

Widget-parity map [#widget-parity-map]

This family (plus two reused local-first items) supersedes the deprecated
`DevToolsWidget`'s six panels:

| Widget panel | Successor                                                                                                                                                           |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Queue        | `ui/devtools/inference-queue-monitor`                                                                                                                               |
| Events       | `ui/devtools/event-log-viewer`                                                                                                                                      |
| Pipeline     | `ui/devtools/pipeline-run-inspector`                                                                                                                                |
| Models       | `ui/devtools/model-cache-table`                                                                                                                                     |
| Device       | [`ui/local-first/device-capability-grid`](/docs/local-first/device-capability-grid) (reused — device data is not devtools-specific)                                 |
| VectorDB     | [`ui/local-first/vector-storage-observability`](/docs/local-first/vector-storage-observability) (reused; per-collection op counts come from `useDevToolsVectorDBs`) |

Wiring [#wiring]

Collectors are off until you opt in — enable them once, then render hook
snapshots straight into the primitives:

```tsx
import { enableDevTools } from '@localmode/devtools';
import { useDevToolsQueueStats } from '@localmode/devtools/react';
import { InferenceQueueMonitor } from '@/components/inference-queue-monitor';

enableDevTools(); // e.g. behind your own debug toggle

export function QueuePanel() {
  const queues = useDevToolsQueueStats();
  return <InferenceQueueMonitor queues={queues} />;
}
```

The composed drawer [#the-composed-drawer]

A ready-made six-tab drawer (Queue / Events / Pipeline / Models / Device /
VectorDB) that wires all of the above ships as an installable block:

```bash
npx shadcn@latest add @localmode/ui/blocks/devtools-drawer
```

Blocks are the wiring layer, so the drawer legitimately depends on
`@localmode/devtools` — the four primitives above stay zero-`@localmode/*`.

# Inference Queue Monitor

Inference Queue Monitor [#inference-queue-monitor]

The **Inference Queue Monitor** renders one card per registered inference queue showing all five queue metrics — pending, active, completed, failed, and average latency. Non-zero active counts get a live accent (plus a pulsing "active" badge on the queue header), non-zero pending counts are highlighted, and non-zero failed counts render destructive. With no queues registered it shows an empty state pointing at `registerQueue()`. Stats are passed in as props — works with any backend (recommended producer: `useDevToolsQueueStats` from `@localmode/devtools/react`, whose snapshot spreads straight into `queues`).

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/devtools/inference-queue-monitor`

Full source: https://localmode.ai/r/ui/devtools/inference-queue-monitor.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/devtools/inference-queue-monitor
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders the per-queue stats record you pass — works with any backend. Recommended producer: `useDevToolsQueueStats` from `@localmode/devtools/react` (on-device, optional) — its `Record<string, QueueStats>` snapshot matches `queues` field-for-field, no mapping layer needed.

* `lucide-react` — icons
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `inference-queue-monitor.tsx` — the `InferenceQueueMonitor` component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**InferenceQueueMonitor**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `queues` | `Record<string, object>` | — | **Required.** Stats per registered queue, keyed by queue name. |

**QueueStatsLike**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `pending` | `number` | — | **Required.** Number of tasks waiting to execute. |
| `active` | `number` | — | **Required.** Number of tasks currently executing. |
| `completed` | `number` | — | **Required.** Total tasks completed successfully. |
| `failed` | `number` | — | **Required.** Total tasks that failed. |
| `avgLatencyMs` | `number` | — | **Required.** Average latency in milliseconds for completed tasks. |

Examples [#examples]

Wired to the LocalMode devtools bridge [#wired-to-the-localmode-devtools-bridge]

Enable devtools once, register each queue you create, then feed the hook's snapshot straight into the monitor:

```tsx
import { createInferenceQueue } from '@localmode/core';
import { enableDevTools, registerQueue } from '@localmode/devtools';
import { useDevToolsQueueStats } from '@localmode/devtools/react';

import { InferenceQueueMonitor } from '@/components/inference-queue-monitor';

// Once, at app init
enableDevTools();

// Wherever queues are created
const queue = createInferenceQueue({ concurrency: 1 });
registerQueue('embeddings', queue);

// The monitoring surface
function QueuePanel() {
  const queues = useDevToolsQueueStats();
  return <InferenceQueueMonitor queues={queues} />;
}
```

Any backend [#any-backend]

`queues` is just a record of per-queue counters — feed it from your own scheduler, a server metrics endpoint, or a test fixture:

```tsx
<InferenceQueueMonitor
  queues={{
    transcode: { pending: 3, active: 1, completed: 87, failed: 0, avgLatencyMs: 640 },
  }}
/>
```

Customization [#customization]

Active counts accent emerald (with a pulsing header badge while `active > 0`), pending counts accent amber, and failed counts use the theme's `destructive` token. Average latency renders as milliseconds below one second and seconds above. Styled entirely with shadcn/ui CSS-variable utilities so it inherits your theme — because you own the copied file, every class, accent color, and threshold is yours to change.

# Model Cache Table

Model Cache Table [#model-cache-table]

The **Model Cache Table** renders one row per cached model showing the model ID (monospace, truncated with a full-ID tooltip), a status badge (loaded / loading / error), the load duration (ms below one second, seconds above), and a relative last-used time. A size column renders only when at least one entry carries `sizeBytes` (human-formatted), and a per-row evict control renders only when `onEvict` is provided. With no models present it shows an empty state explaining that model loads are captured automatically once `enableDevTools()` runs. Entries are passed in as props — works with any backend (recommended producer: `useDevToolsModelCache` from `@localmode/devtools/react`, whose snapshot passes straight into `entries`).

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/devtools/model-cache-table`

Full source: https://localmode.ai/r/ui/devtools/model-cache-table.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/devtools/model-cache-table
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders the cached-model record you pass — works with any backend. Recommended producer: `useDevToolsModelCache` from `@localmode/devtools/react` (on-device, optional) — its `Record<string, ModelCacheInfo>` snapshot matches `entries` field-for-field, no mapping layer needed.

* `lucide-react` — icons
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `model-cache-table.tsx` — the `ModelCacheTable` component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**ModelCacheTable**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `entries` | `Record<string, object>` | — | **Required.** Cached-model entries, keyed by model ID. |
| `onEvict` | `function` | — | When provided, renders a per-row evict control invoking this callback. |

**ModelCacheEntryLike**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `modelId` | `string` | — | **Required.** Model identifier. |
| `status` | `"error" \| "loading" \| "loaded"` | — | **Required.** Current status. |
| `loadDurationMs` | `number` | — | **Required.** Load duration in milliseconds. |
| `lastUsed` | `string` | — | **Required.** Last time the model was used (ISO timestamp). |
| `sizeBytes` | `number` | — | On-disk size in bytes, when known. |

Examples [#examples]

Wired to the LocalMode devtools bridge [#wired-to-the-localmode-devtools-bridge]

Enable devtools once, then feed the hook's snapshot straight into the table — every model load, load failure, and inference use is captured automatically:

```tsx
import { enableDevTools } from '@localmode/devtools';
import { useDevToolsModelCache } from '@localmode/devtools/react';

import { ModelCacheTable } from '@/components/model-cache-table';

// Once, at app init (before loading models)
enableDevTools();

// The monitoring surface
function ModelsPanel() {
  const models = useDevToolsModelCache();
  return <ModelCacheTable entries={models} />;
}
```

With sizes and eviction [#with-sizes-and-eviction]

The bridge snapshot doesn't carry sizes or eviction today — supply `sizeBytes` from your own cache accounting and wire `onEvict` to your provider's cache management (e.g. `refreshModel()` from `@localmode/wllama`):

```tsx
<ModelCacheTable
  entries={{
    'my-model.gguf': {
      modelId: 'my-model.gguf',
      status: 'loaded',
      loadDurationMs: 2140,
      lastUsed: new Date().toISOString(),
      sizeBytes: 668_000_000,
    },
  }}
  onEvict={(modelId) => evictFromCache(modelId)}
/>
```

Any backend [#any-backend]

`entries` is just a record of per-model info — feed it from your own model manager, a server metrics endpoint, or a test fixture:

```tsx
<ModelCacheTable
  entries={{
    'sentence-encoder': {
      modelId: 'sentence-encoder',
      status: 'loaded',
      loadDurationMs: 640,
      lastUsed: '2026-07-03T09:30:00.000Z',
    },
  }}
/>
```

Customization [#customization]

Loaded models badge emerald, in-flight loads badge amber with a pulsing dot (and render an em dash instead of a load time), and failed loads use the theme's `destructive` token. Load durations render as milliseconds below one second and seconds above; last-used renders relative ("3m ago") with the exact timestamp on hover; sizes are human-formatted by a local `formatBytes`. The size column and the evict column each appear only when their data (`sizeBytes` on any entry) or callback (`onEvict`) is supplied. Styled entirely with shadcn/ui CSS-variable utilities so it inherits your theme — because you own the copied file, every class, tone, and threshold is yours to change.

# Pipeline Run Inspector

Pipeline Run Inspector [#pipeline-run-inspector]

The **Pipeline Run Inspector** renders one card per tracked pipeline run: the run name, a status badge (running pulses on the primary color, completed goes emerald, failed goes destructive), a progress bar derived from `completed`/`total`, the current step while running, and the total duration once done. When a run carries an optional `steps[]` array, an expandable per-step timing section renders each step's name, status, and duration; when absent, the aggregate view alone renders. With no runs, an empty state points at `createDevToolsProgressCallback()` as the instrumentation hint. The `runs` prop mirrors the `@localmode/devtools` `PipelineSnapshot` record (keyed by pipeline name), so `useDevToolsPipelineRuns()` output feeds it directly — no mapping layer.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/devtools/pipeline-run-inspector`

Full source: https://localmode.ai/r/ui/devtools/pipeline-run-inspector.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/devtools/pipeline-run-inspector
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders whatever `runs` record you pass — works with any backend. Recommended producer: `useDevToolsPipelineRuns()` from `@localmode/devtools/react` (on-device, optional); its snapshot record spreads straight into the `runs` prop.

* `lucide-react` — icons
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `pipeline-run-inspector.tsx` — the `PipelineRunInspector` component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**PipelineRunInspector**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `runs` | `Record<string, object>` | — | **Required.** Pipeline run snapshots keyed by pipeline name. |

**PipelineRunLike**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `currentStep` | `string` | — | **Required.** Current step name. |
| `completed` | `number` | — | **Required.** Number of steps completed. |
| `total` | `number` | — | **Required.** Total number of steps. |
| `status` | `PipelineRunStatus` | — | **Required.** Pipeline status. |
| `startedAt` | `string` | — | **Required.** When the pipeline started (ISO timestamp string). |
| `durationMs` | `number` | — | Total duration in milliseconds (set on completion). |
| `steps` | `array` | — | Optional per-step timings; per-step rows render only when present. |

**PipelineStepLike**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` | — | **Required.** Step name. |
| `durationMs` | `number` | — | Step duration in milliseconds (set once the step finished). |
| `status` | `PipelineRunStatus` | — | **Required.** Step status. |

Examples [#examples]

Bound to the devtools bridge [#bound-to-the-devtools-bridge]

```tsx
import { enableDevTools } from '@localmode/devtools';
import { useDevToolsPipelineRuns } from '@localmode/devtools/react';
import { PipelineRunInspector } from '@/components/pipeline-run-inspector';

enableDevTools(); // once, at app init

function PipelineTab() {
  const runs = useDevToolsPipelineRuns();
  return <PipelineRunInspector runs={runs} />;
}
```

Runs appear once a pipeline is instrumented with a devtools-aware progress callback:

```tsx
import { createDevToolsProgressCallback } from '@localmode/devtools';

await pipeline.run(input, {
  onProgress: createDevToolsProgressCallback('rag-ingest'),
});
```

Per-step timings [#per-step-timings]

The bridge snapshot is aggregate-only today (`currentStep`, `completed`/`total`, `durationMs`), and the card renders exactly that when `steps` is absent. If your wiring tracks individual step durations, attach them and the card grows an expandable "Step timings" section:

```tsx
<PipelineRunInspector
  runs={{
    'semantic-search': {
      currentStep: 'rerank',
      completed: 3,
      total: 3,
      status: 'completed',
      startedAt: '2026-07-03T09:11:40.000Z',
      durationMs: 1834,
      steps: [
        { name: 'embed', durationMs: 412, status: 'completed' },
        { name: 'search', durationMs: 96, status: 'completed' },
        { name: 'rerank', durationMs: 1326, status: 'completed' },
      ],
    },
  }}
/>
```

Customization [#customization]

Status styling is table-driven: `STATUS_BADGE_STYLES`, `PROGRESS_BAR_STYLES`, and `STEP_DOT_STYLES` map each status (`running` | `completed` | `idle` | `failed`) to utility classes — swap the emerald success accent or the running pulse there. Durations format via the local `formatDuration()` (ms → s → m s). Styled entirely with shadcn/ui CSS-variable utilities so it inherits your theme — because you own the copied file, every class and threshold is yours to change.

# Adaptive Batch Card

Adaptive Batch Card [#adaptive-batch-card]

The **Adaptive Batch Card** surfaces `useAdaptiveBatchSize` output: a prominent computed optimal batch number, a hardware summary (cores / RAM / GPU), the detection source (detected / estimated / override), and a collapsible reasoning string. A compact `AdaptiveBatchBadge` variant (e.g. "Batch: 32") offers a click-to-expand device-profile popover. Use it to explain why your `embedMany` / `ingest` batch size is what it is on this device.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/local-first/adaptive-batch-card`

Full source: https://localmode.ai/r/ui/local-first/adaptive-batch-card.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/local-first/adaptive-batch-card
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders the batch-size result you pass — works with any backend. Recommended producer: `useAdaptiveBatchSize` (backed by `computeOptimalBatchSize`) from `@localmode/react` (on-device, optional).

* `lucide-react` — icons
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `adaptive-batch-card.tsx` — `AdaptiveBatchCard` + `AdaptiveBatchBadge`
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**AdaptiveBatchCard**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `result` | `object` | — | **Required.** The adaptive batch result (from `useAdaptiveBatchSize`). |

**AdaptiveBatchResult**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `batchSize` | `number` | — | **Required.** The computed optimal batch size. |
| `reasoning` | `string` | — | **Required.** Human-readable explanation of how the batch size was computed. |
| `deviceProfile` | `object` | — | **Required.** Hardware values + their origin. |

Examples [#examples]

Bound to the hook [#bound-to-the-hook]

```tsx
const result = useAdaptiveBatchSize({ taskType: 'embedding', modelDimensions: 384 });
<AdaptiveBatchCard result={result} />
<AdaptiveBatchBadge result={result} />
```

Customization [#customization]

The `result` shape is exactly `useAdaptiveBatchSize`'s return (`{ batchSize, reasoning, deviceProfile }`), so you can pass it straight through. The badge popover summarizes the device profile. Styled entirely with shadcn/ui CSS-variable utilities so it inherits your theme — because you own the copied file, every class and threshold is yours to change.

# Browser Compat Card

Browser Compat Card [#browser-compat-card]

The **Browser Compat Card** is a per-model runnability report — the feasibility check you want *before* a multi-GB download. It combines a `RAMUsageBar` (model RAM vs device RAM), available storage, threading (cross-origin-isolation) status, estimated speed, and a warnings list. A `canRun` boolean gates a success vs error header. It extends the spirit of the Capability Gate. The `RAMUsageBar` is independently usable.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/local-first/browser-compat-card`

Full source: https://localmode.ai/r/ui/local-first/browser-compat-card.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/local-first/browser-compat-card
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders the device/model feasibility props you pass — works with any backend. Recommended producer: `useCapabilities` from `@localmode/react` (on-device, optional).

* `lucide-react` — icons
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `browser-compat-card.tsx` — `BrowserCompatCard` + `RAMUsageBar`
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**BrowserCompatCard**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `modelName` | `string` | — | **Required.** Model display name. |
| `requiredGB` | `number` | — | **Required.** Model memory requirement, in GB. |
| `deviceGB` | `number` | — | **Required.** Device RAM, in GB. |
| `availableStorageGB` | `number` | — | Available origin storage, in GB. |
| `crossOriginIsolated` | `boolean` | — | Whether the runtime is cross-origin isolated (multi-thread WASM). |
| `estimatedSpeed` | `string` | — | Estimated inference speed label (e.g. "Fast", "~20 tok/s"). |
| `warnings` | `array` | — | Warnings/recommendations explaining a fail or caveat. |
| `canRun` | `boolean` | — | Whether the model can run on this device. When omitted, derived as `deviceGB >= requiredGB`. |

**RAMUsageBar**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `requiredGB` | `number` | — | **Required.** Memory the model needs, in GB. |
| `deviceGB` | `number` | — | **Required.** Memory the device has, in GB. |

Examples [#examples]

Feasibility before download [#feasibility-before-download]

```tsx
<BrowserCompatCard modelName="Llama 3 8B" requiredGB={6} deviceGB={8} />
```

Standalone RAM bar [#standalone-ram-bar]

```tsx
<RAMUsageBar requiredGB={4} deviceGB={8} />
```

Customization [#customization]

When `canRun` is omitted it is derived as `deviceGB >= requiredGB`. The header and RAM bar turn destructive on a fail; pass a `warnings` array to explain why. Styled entirely with shadcn/ui CSS-variable utilities so it inherits your theme — because you own the copied file, every class and threshold is yours to change.

# Cache Badge

Cache Badge [#cache-badge]

The **Cache Badge** annotates a result as served from the semantic cache, optionally with the hit latency (e.g. "cached · 12ms"). Local apps cache responses on-device; surfacing a cache hit makes that invisible speedup legible. Drive `cached`/`latencyMs` from your `useSemanticCache` lookup result. It renders nothing when `cached` is false, so it is safe to drop next to any result.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/local-first/cache-badge`

Full source: https://localmode.ai/r/ui/local-first/cache-badge.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/local-first/cache-badge
```

Dependencies [#dependencies]

* `lucide-react` — icons
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `cache-badge.tsx` — the `CacheBadge` component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**CacheBadge**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `cached` | `boolean` | — | **Required.** Whether the annotated result was served from the semantic cache. When false, nothing renders. |
| `latencyMs` | `number` | — | Optional cache-hit latency in milliseconds (e.g. 12 → "cached · 12ms"). |
| `label` | `string` | `"cached"` | Label override for the cached state. |

Examples [#examples]

Annotate a cached reply [#annotate-a-cached-reply]

```tsx
const result = await cache.lookup({ prompt, modelId });
<CacheBadge cached={result.hit} latencyMs={result.durationMs} />
```

Customization [#customization]

Uses the `emerald` palette to read as a positive signal. Because it returns `null` when `cached` is false, you can render it unconditionally next to every result. Styled entirely with shadcn/ui CSS-variable utilities so it inherits your theme — because you own the copied file, every class and threshold is yours to change.

# Capability Gate

Capability Gate [#capability-gate]

The **Capability Gate** renders its children only when the device meets a stated requirement (e.g. `requires="webgpu"`), and otherwise renders a `fallback` slot with guidance. Local models have hard device requirements — LiteRT Gemma is WebGPU-only — so gating prevents a broken experience and gives a clear, themeable explanation instead. The capability check uses `useCapabilities`.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/local-first/capability-gate`

Full source: https://localmode.ai/r/ui/local-first/capability-gate.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/local-first/capability-gate
```

Data source & dependencies [#data-source--dependencies]

**Data source:** detects device capabilities via the bundled `useCapabilities` navigator hook — self-contained, works in any React app, no backend required. (It mirrors the detection `useCapabilities` from `@localmode/react` performs, plus copy-owned `camera`/`microphone` media-input availability entries via `enumerateDevices()` — never prompting.)

* `@localmode/ui/lib/use-environment` — the bundled `useCapabilities` navigator hook (installed automatically as a registry dependency)
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `capability-gate.tsx` — the `CapabilityGate` component
* `lib/use-environment.ts` — the bundled `useCapabilities` navigator hook
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**CapabilityGate**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `requires` | `GateCapability` | — | **Required.** The device capability the children require. |
| `children` | `ReactNode` | — | **Required.** Rendered only when the capability is supported. |
| `fallback` | `ReactNode` | — | Rendered when the capability is unsupported. Defaults to a themed notice explaining the requirement. |
| `pending` | `ReactNode` | — | Rendered while detection is in flight. Defaults to a muted placeholder. |

Examples [#examples]

Gate a WebGPU-only model [#gate-a-webgpu-only-model]

```tsx
<CapabilityGate
  requires="webgpu"
  fallback={<p>This model needs WebGPU. Try Chrome 113+.</p>}
>
  <FastWebGPUModel />
</CapabilityGate>
```

Gate a media surface (camera / microphone) [#gate-a-media-surface-camera--microphone]

The `camera` and `microphone` capabilities gate on media-input **availability** — a secure context, `navigator.mediaDevices.getUserMedia` present, and `enumerateDevices()` reporting at least one device of that kind. The detection never prompts the user. Runtime **permission denial** is deliberately not gated: request permission from your own start action and surface a `getUserMedia` rejection as a recoverable error with retry.

```tsx
<CapabilityGate
  requires="camera"
  fallback={<p>No camera detected on this device.</p>}
>
  <WebcamHandTracking /> {/* calls getUserMedia on its own Start action */}
</CapabilityGate>

<CapabilityGate requires="microphone">
  <RecordAndClassify />
</CapabilityGate>
```

Customization [#customization]

The default fallback and pending slots are themed amber/muted notices — pass your own `fallback`/`pending` nodes for full control. The `requires` union covers `webgpu`, `wasm`, `webnn`, `simd`, `threads`, `indexeddb`, `webworkers`, `sharedarraybuffer`, and the media-availability entries `camera` and `microphone`; add more by extending the `LABELS` map. Styled entirely with shadcn/ui CSS-variable utilities so it inherits your theme — because you own the copied file, every class and threshold is yours to change.

# Chrome AI Download Gate

Chrome AI Download Gate [#chrome-ai-download-gate]

Chrome's built-in AI APIs (`Summarizer`, `Translator`, `LanguageModel`) can exist in a browser while their on-device model has not been fetched yet. In that state `availability()` reports `'downloadable'`, and **Chrome refuses to start the download outside a user activation**. A button is therefore not a nicety here — it is the only way to trigger the download.

The **Chrome AI Download Gate** renders that button, the in-flight progress bar, the failed-attempt message, and the two terminal states (the API is absent, or this device cannot run it). It renders `null` once the model is `'available'`, because a ready capability needs no gate. **Chrome AI Ready Badge** is a compact confirmation you can show in its place.

It is presentational and hook-driven: bind `availability`, `progress`, and `isDownloading` to `useProviderFallback`'s Chrome state and pass its download action as `onDownload`. It owns no orchestration and starts nothing itself.

<Callout type="warn">
  The download is Chrome's, not your app's: it is shared across every site and happens once. Gemini Nano (the Prompt API) is roughly 1.5 GB; the Translator downloads a smaller pack **per language pair**, so availability must be re-probed whenever the pair changes.
</Callout>

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/local-first/chrome-ai-download-gate`

Full source: https://localmode.ai/r/ui/local-first/chrome-ai-download-gate.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/local-first/chrome-ai-download-gate
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders the `availability` you pass — works with any backend. Recommended producer: `useProviderFallback` from `@localmode/react` (on-device, optional), whose `chromeAvailability`, `chromeDownloadProgress`, `downloadingCapability`, and `requestChromeDownload` map one-to-one onto these props.

* `lucide-react` — icons
* `clsx` + `tailwind-merge` — via the shared `cn()` util

Files installed [#files-installed]

* `chrome-ai-download-gate.tsx` — `ChromeAIDownloadGate` + `ChromeAIReadyBadge`
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**ChromeAIDownloadGate**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `availability` | `ChromeAvailabilityState` | — | **Required.** Chrome's reported state for the capability this gate guards. |
| `label` | `string` | — | **Required.** Human-readable capability name (e.g. "Summarizer", "Gemini Nano"). |
| `size` | `string` | — | Approximate download size (e.g. "~1.5 GB"). Shown on the prompt. |
| `onDownload` | `function` | — | **Required.** Called when the user clicks Download. Chrome only starts the download from a user activation, so this MUST be wired to a real click — it cannot be triggered on mount. |
| `isDownloading` | `boolean` | — | True while the download is in flight. |
| `progress` | `number` | — | Download completion as a 0–1 fraction. Renders an indeterminate bar when omitted. |
| `error` | `string \| null` | — | Message shown when the last download attempt failed. |
| `fallbackLabel` | `string` | — | What the app will use instead while the model is missing (e.g. "Transformers.js"). |

**ChromeAIReadyBadge**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | — | **Required.** Capability name shown in the badge. |

Examples [#examples]

Wired to `useProviderFallback` [#wired-to-useproviderfallback]

`requestChromeDownload` must be called from the click handler — Chrome will reject a download started from an effect or on mount.

```tsx
import { useEffect } from 'react';
import { useProviderFallback } from '@localmode/react';
import { ChromeAIDownloadGate } from '@/components/chrome-ai-download-gate';

export function SummarizePanel() {
  const {
    chromeAvailability,
    refreshChromeAvailability,
    requestChromeDownload,
    chromeDownloadProgress,
    downloadingCapability,
    error,
  } = useProviderFallback({
    loadChromeAI: () => import('@localmode/chrome-ai'),
    loadTransformers: () => import('@localmode/transformers'),
  });

  // Reading availability() downloads nothing.
  useEffect(() => {
    void refreshChromeAvailability('summarize', { chromeStyle: 'tldr', length: 'medium' });
  }, [refreshChromeAvailability]);

  return (
    <ChromeAIDownloadGate
      availability={chromeAvailability.summarize ?? 'unsupported'}
      label="Chrome Summarizer"
      size="~1.5 GB, shared across every site"
      isDownloading={downloadingCapability === 'summarize'}
      progress={chromeDownloadProgress?.progress}
      error={error?.message ?? null}
      fallbackLabel="Transformers.js (DistilBART)"
      onDownload={() => {
        void requestChromeDownload('summarize', { chromeStyle: 'tldr', length: 'medium' });
      }}
    />
  );
}
```

Per-language-pair gating [#per-language-pair-gating]

The Translator downloads one pack per directed pair, so re-probe on every pair change and name the pair in the label.

```tsx
useEffect(() => {
  void refreshChromeAvailability('translate', { source, target });
}, [source, target, refreshChromeAvailability]);

<ChromeAIDownloadGate
  availability={chromeAvailability.translate ?? 'unsupported'}
  label={`Chrome Translator (${source}→${target})`}
  size="one language pack"
  isDownloading={downloadingCapability === 'translate'}
  progress={chromeDownloadProgress?.progress}
  onDownload={() => void requestChromeDownload('translate', { source, target })}
  fallbackLabel="Transformers.js (Opus-MT)"
/>;
```

Showing a ready state [#showing-a-ready-state]

The gate renders `null` when the model is `'available'`, so pair it with the badge:

```tsx
{chromeAvailability.summarize === 'available' ? (
  <ChromeAIReadyBadge label="Chrome Summarizer" />
) : (
  <ChromeAIDownloadGate {...gateProps} />
)}
```

States [#states]

| `availability` | What renders                                                               |
| -------------- | -------------------------------------------------------------------------- |
| `available`    | Nothing (`null`) — pair with `ChromeAIReadyBadge`                          |
| `downloadable` | Heading, size copy, and the **Download model** button                      |
| `downloading`  | Heading and a live progress bar (indeterminate when `progress` is omitted) |
| `unavailable`  | A terminal message: this device cannot run the model                       |
| `unsupported`  | A terminal message: this browser has no such API                           |

Customization [#customization]

The button's accessible name is deliberately the generic &#x2A;*"Download model"** rather than a name built from the capability label. A name like "Download Chrome Summarizer" contains the substring "Summarize", which would collide with a host block's own **Summarize** run button under role+name lookups and resolve two controls. The capability is named in the heading above the button instead. If you rename the button, keep it distinct from the run controls around it.

The progress bar is a plain `role="progressbar"` with `aria-valuenow`, and the status line is a `role="status"` live region, so screen readers announce the download without extra wiring.

# Context Usage Meter

Context Usage Meter [#context-usage-meter]

The **Context Usage Meter** is a token / context-window budget meter for local generation: a bar breaking down input / output / reasoning / cache token usage against the model's context-window limit (a hard local GGUF/LiteRT KV-cache constraint), warning as it approaches the limit. Feed it the `usage` from a generate result — or `useChat`'s per-turn `usage` / cumulative `totalUsage` (`{ inputTokens, outputTokens, totalTokens, durationMs }`). It is **local-only — there is no cost field**, and it complements the Storage Meter (disk) with a token-budget gauge. For a composable hovercard layout, use the lower-level `Context` / `ContextTrigger` / `ContextContent` / `ContextInputUsage` / `ContextOutputUsage` parts.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/local-first/context-usage-meter`

Full source: https://localmode.ai/r/ui/local-first/context-usage-meter.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/local-first/context-usage-meter
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders the `usage` shape you pass — works with any backend. Recommended producer: `useChat`'s `usage` (last turn) / `totalUsage` (cumulative), or a `useGenerateText` result's `usage`, from `@localmode/react` (on-device, optional).

* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `context-usage-meter.tsx` — `ContextUsageMeter` + `Context` / `ContextTrigger` / `ContextContent` / `ContextInputUsage` / `ContextOutputUsage`
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**ContextUsageMeter**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `contextWindow` | `number` | — | **Required.** The model's context-window limit in tokens. |
| `warnThreshold` | `number` | `0.85` | Fraction (0–1) at which the meter warns. |
| `inputTokens` | `number` | — | Prompt / input tokens. |
| `outputTokens` | `number` | — | Generated / output tokens. |
| `reasoningTokens` | `number` | — | Reasoning ("thinking") tokens, if the model emits them. |
| `cachedTokens` | `number` | — | Tokens served from the prompt cache. |

**Context**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `usage` | `object` | — | **Required.** Token usage breakdown (e.g. from a generate result's `usage`). |
| `contextWindow` | `number` | — | **Required.** The model's context-window limit in tokens. |
| `warnThreshold` | `number` | `0.85` | Fraction (0–1) at which the meter warns. |
| `children` | `ReactNode` | — | **Required.** Compound children (`ContextTrigger`, `ContextContent`, …). |

Examples [#examples]

Simple meter [#simple-meter]

```tsx
<ContextUsageMeter inputTokens={1200} outputTokens={300} contextWindow={8192} />
```

Wired to `useChat` usage [#wired-to-usechat-usage]

```tsx
import { useChat } from '@localmode/react';
import { ContextUsageMeter } from '@/components/context-usage-meter';

export function ChatBudget({ model }) {
  const { totalUsage } = useChat({ model });
  return (
    <ContextUsageMeter
      inputTokens={totalUsage.inputTokens}
      outputTokens={totalUsage.outputTokens}
      contextWindow={8192}
    />
  );
}
```

`useChat` exposes `usage` (the last completed turn) and `totalUsage` (a running sum across the conversation) — use `totalUsage` for a context-budget gauge and `usage` for a per-turn readout.

Composable parts [#composable-parts]

```tsx
<Context usage={result.usage} contextWindow={8192}>
  <ContextTrigger />
  <ContextContent>
    <ContextInputUsage />
    <ContextOutputUsage />
  </ContextContent>
</Context>
```

Customization [#customization]

The warn state (amber) triggers past `warnThreshold` (default `0.85`). There is deliberately **no cost field** — local inference has no per-token billing. Styled entirely with shadcn/ui CSS-variable utilities so it inherits your theme — because you own the copied file, every class and threshold is yours to change.

# Device Capability Grid

Device Capability Grid [#device-capability-grid]

The **Device Capability Grid** is the expanded sibling of the Device Badge: a full diagnostic card reading `useCapabilities`. It renders a stats bar (CPU cores / memory / GPU), a status row per feature flag (WebGPU, WASM, SIMD, Threads, IndexedDB, Web Workers), a storage row, and a browser/OS footer, with a spinner while detection runs. It does not replace the Device Badge.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/local-first/device-capability-grid`

Full source: https://localmode.ai/r/ui/local-first/device-capability-grid.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/local-first/device-capability-grid
```

Data source & dependencies [#data-source--dependencies]

**Data source:** detects device capabilities via the bundled `useCapabilities` navigator hook — self-contained, works in any React app, no backend required. (It mirrors the detection `useCapabilities` from `@localmode/react` performs.)

* `@localmode/ui/lib/use-environment` — the bundled `useCapabilities` navigator hook (installed automatically as a registry dependency)
* `lucide-react` — icons
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `device-capability-grid.tsx` — the `DeviceCapabilityGrid` component
* `lib/use-environment.ts` — the bundled `useCapabilities` navigator hook
* `lib/utils.ts` — the `cn()` helper (if not already present)

Examples [#examples]

Full diagnostic [#full-diagnostic]

```tsx
<DeviceCapabilityGrid />
```

Customization [#customization]

Each feature row shows a colored dot (emerald when on, muted when off). Add or remove flags by editing the `FEATURES` array in the copied file. Styled entirely with shadcn/ui CSS-variable utilities so it inherits your theme — because you own the copied file, every class and threshold is yours to change.

# Embedding Drift Banner

Embedding Drift Banner [#embedding-drift-banner]

The **Embedding Drift Banner** is a warning panel shown when the active embedding model is incompatible with vectors already stored (the model changed or dimensions mismatch). It explains the stored-vs-current model ids, shows a reindex progress bar + phase label while re-embedding, and offers "Re-embed All" / Cancel. Bind to `useReindex` + your compatibility check.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/local-first/embedding-drift-banner`

Full source: https://localmode.ai/r/ui/local-first/embedding-drift-banner.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/local-first/embedding-drift-banner
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders the drift/reindex state you pass and emits Re-embed/Cancel — works with any backend. Recommended producer: `useReindex` from `@localmode/react` (on-device, optional).

* `lucide-react` — icons
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `embedding-drift-banner.tsx` — the `EmbeddingDriftBanner` component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**EmbeddingDriftBanner**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `storedModelId` | `string` | — | **Required.** Model id used for the vectors already stored. |
| `currentModelId` | `string` | — | **Required.** The active embedding model id. |
| `isReindexing` | `boolean` | — | Whether a reindex is currently running. |
| `progress` | `object \| null` | — | Live reindex progress (null when not started). |
| `onReindex` | `function` | — | Fired when the user starts a re-embed. |
| `onCancel` | `function` | — | Fired when the user cancels a running reindex. |

**ReindexProgressLike**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `completed` | `number` | — | **Required.** Documents processed so far. |
| `total` | `number` | — | **Required.** Total documents to process. |
| `skipped` | `number` | — | Documents skipped (no text to re-embed). |
| `phase` | `"indexing" \| "embedding"` | — | **Required.** Current phase. |

Examples [#examples]

Bound to useReindex [#bound-to-usereindex]

```tsx
const { isReindexing, progress, reindex, cancel } = useReindex({ db, model });
<EmbeddingDriftBanner
  storedModelId={stored}
  currentModelId={current}
  isReindexing={isReindexing}
  progress={progress}
  onReindex={reindex}
  onCancel={cancel}
/>
```

Customization [#customization]

The banner uses the `amber` palette to read as a warning. The phase label maps `useReindex` phases (`embedding` / `indexing`) to human strings in `PHASE_LABEL`. Styled entirely with shadcn/ui CSS-variable utilities so it inherits your theme — because you own the copied file, every class and threshold is yours to change.

# Model Catalog Card

Model Catalog Card [#model-catalog-card]

The **Model Catalog Card** is a rich tile for a single model catalog entry (wllama / webllm / transformers / litert / mediapipe shapes): name, a size badge, an optional description, a metadata chip row (architecture, params, quantization, context), and a capability sub-row (tools / vision / embedding / reranking / reasoning) rendered conditionally from the entry's flags. It complements the Model Selector (a picker) — this is a presentation tile. It fires `onClick(id)` and supports a selected ring.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/local-first/model-catalog-card`

Full source: https://localmode.ai/r/ui/local-first/model-catalog-card.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/local-first/model-catalog-card
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders the catalog entry you pass — works with any backend. Recommended producer: `useModelRecommendations` / your registry data from `@localmode/react` (on-device, optional).

* `lucide-react` — icons
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `model-catalog-card.tsx` — the `ModelCatalogCard` component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**ModelCatalogCard**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `entry` | `object` | — | **Required.** The catalog entry to render. |
| `selected` | `boolean` | — | Whether this card is the selected one (adds an accent ring). |
| `onClick` | `function` | — | Fired with the entry id when the card is clicked. |

**CatalogEntry**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` | — | **Required.** Stable model id (passed to `onClick`). |
| `name` | `string` | — | **Required.** Display name. |
| `size` | `string` | — | Human-readable size (e.g. "1.2 GB"). |
| `description` | `string` | — | One-line description. |
| `architecture` | `string` | — | Architecture (e.g. "llama"). |
| `parameters` | `string` | — | Parameter count label (e.g. "1.2B"). |
| `quantization` | `string` | — | Quantization label (e.g. "Q4_K_M"). |
| `contextLength` | `number` | — | Context window in tokens. |
| `tools` | `boolean` | — | Capability flags. |
| `vision` | `boolean` | — | — |
| `embedding` | `boolean` | — | — |
| `reranking` | `boolean` | — | — |
| `reasoning` | `boolean` | — | — |

Examples [#examples]

A selectable tile [#a-selectable-tile]

```tsx
<ModelCatalogCard entry={entry} selected={entry.id === picked} onClick={setPicked} />
```

Customization [#customization]

Capability badges render only for the flags present on the entry — edit the `CAPABILITIES` array to add more (e.g. audio). The selected state adds a `ring-1 ring-primary`. Styled entirely with shadcn/ui CSS-variable utilities so it inherits your theme — because you own the copied file, every class and threshold is yours to change.

# Model Comparison Panel

Model Comparison Panel [#model-comparison-panel]

The **Model Comparison Panel** is a side-by-side comparison of two scored entries with labeled rows (Score, Size, Speed, Quality, Device, Dimensions) where winning rows are accent-highlighted and losing rows dimmed, plus an `onClear` dismissal. Win-highlighting is derived purely from props (no orchestration state). Bind to `useModelRecommendations`.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/local-first/model-comparison-panel`

Full source: https://localmode.ai/r/ui/local-first/model-comparison-panel.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/local-first/model-comparison-panel
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders the two scored entries you pass and emits `onClear` — works with any backend. Recommended producer: `useModelRecommendations` from `@localmode/react` (on-device, optional).

* `lucide-react` — icons
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `model-comparison-panel.tsx` — the `ModelComparisonPanel` component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**ModelComparisonPanel**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `entries` | `[object, object]` | — | **Required.** The two entries to compare. |
| `onClear` | `function` | — | Fired when the comparison is dismissed. |

**ComparisonEntry**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `modelId` | `string` | — | **Required.** Stable model id. |
| `name` | `string` | — | **Required.** Display name. |
| `score` | `number` | — | **Required.** Score (0–100). |
| `sizeMB` | `number` | — | Size in MB (numeric, for "smaller is better" comparison). |
| `size` | `string` | — | Human-readable size label (display). |
| `speedTier` | `"slow" \| "medium" \| "fast"` | — | Speed tier. |
| `qualityTier` | `"high" \| "low" \| "medium"` | — | Quality tier. |
| `device` | `"cpu" \| "wasm" \| "webgpu"` | — | Recommended device. |
| `dimensions` | `number` | — | Embedding dimensions. |

Examples [#examples]

Compare two models [#compare-two-models]

```tsx
<ModelComparisonPanel entries={[a, b]} onClear={() => setCompare(null)} />
```

Customization [#customization]

"Better" is higher for Score/Speed/Quality/Dimensions and lower for Size. The win highlight uses the `emerald` palette; the loser is dimmed. Styled entirely with shadcn/ui CSS-variable utilities so it inherits your theme — because you own the copied file, every class and threshold is yours to change.

# Model Downloader

Model Downloader [#model-downloader]

The **Model Downloader** is the single most defining LocalMode surface: the card a user sees while their model loads on **their** device. It renders the model name, size, context length, and category alongside a live progress bar, and clearly distinguishes a first-time download ("Downloading…") from a cache load ("Loading from cache…") and a ready state. A lower-level **Download Progress** renders just the bar + percentage.

It is presentational and hook-driven — bind `progress` to `useModelLoad`'s `progressValue` (its `percent` is a 0–1 fraction matching this component's `DownloadProgressValue` contract, with `loaded` / `total` bytes and a `cached` flag when known) and pass metadata from `useModelRecommendations` or your catalog. It does **not** initiate or own the download — `useModelLoad().load()` does.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/local-first/model-downloader`

Full source: https://localmode.ai/r/ui/local-first/model-downloader.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/local-first/model-downloader
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders the `progress` + metadata you pass — works with any backend. Recommended producer: `useModelLoad` (provider-model loads; `useModelStatus` for a read-only view, `useModelLoader` for raw `createModelLoader` file downloads) from `@localmode/react` (on-device, optional).

* `lucide-react` — icons
* `clsx` + `tailwind-merge` — via the shared `cn()` util

Files installed [#files-installed]

* `model-downloader.tsx` — `ModelDownloader` + `DownloadProgress`
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**ModelDownloader**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` | — | **Required.** Display name of the model (e.g. "Llama 3.2 1B Instruct"). |
| `size` | `string` | — | Human-readable download size (e.g. "1.2 GB"). |
| `contextLength` | `number` | — | Context window length in tokens (e.g. 8192). |
| `category` | `string` | — | Category / family label (e.g. "Chat", "Vision"). |
| `progress` | `object \| number` | — | **Required.** Progress value (a 0–1 fraction, or a {@link DownloadProgressValue}). When the value reports `cached`, the copy switches to a cache-load message. |
| `cached` | `boolean` | — | Whether the model is being loaded from cache (first-time download vs cache). Overrides `progress.cached` when set explicitly. |
| `ready` | `boolean` | — | Whether the model has finished loading and is ready for inference. |

**DownloadProgress**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `object \| number` | — | **Required.** Progress value (a 0–1 fraction, or a {@link DownloadProgressValue}). |
| `complete` | `boolean` | — | Render the completed appearance: a full emerald bar with a "Ready" label instead of a percentage. When omitted, completion is inferred at 100%. |

Examples [#examples]

Bound to `useModelLoad` [#bound-to-usemodelload]

```tsx
import { useModelLoad } from '@localmode/react';
import { wllama, isModelCached } from '@localmode/wllama';
import { ModelDownloader } from '@/components/model-downloader';

export function Loading() {
  const { status, progressValue } = useModelLoad({
    key: 'Llama-3.2-1B-Instruct-Q4_K_M',
    create: (onProgress) =>
      wllama.languageModel('Llama-3.2-1B-Instruct-Q4_K_M', { onProgress }),
    isCached: () => isModelCached('Llama-3.2-1B-Instruct-Q4_K_M'),
    autoLoad: true,
  });

  return (
    <ModelDownloader
      name="Llama 3.2 1B Instruct"
      size="1.2 GB"
      contextLength={8192}
      category="Chat"
      progress={progressValue}
      ready={status === 'ready'}
    />
  );
}
```

`useModelLoad` normalizes every provider's `onProgress` shape (transformers per-file, webllm percent, wllama/litert bytes) into one `progressValue` — `{ loaded?, total?, percent, cached? }` with `percent` as a 0–1 fraction — which drops straight into this component's `progress` prop. Its `cached` flag (from the `isCached` probe) switches the copy to "Loading from cache…" automatically.

Standalone progress bar [#standalone-progress-bar]

```tsx
<DownloadProgress value={0.42} />
```

Customization [#customization]

Styled entirely with shadcn/ui CSS variables (`bg-card`, `text-card-foreground`, `bg-primary`), so it inherits your theme. The cached state uses Tailwind's `emerald` palette — swap those classes in the copied file to match your design system. The progress shape accepts either a `0–1` fraction or a `{ loaded, total, percent, cached }` object, so it adapts to any provider's `onProgress` — `useModelLoad`'s `progressValue` matches this object shape exactly.

# Model Loading Panel

Model Loading Panel [#model-loading-panel]

The **Model Loading Panel** is the richer, blocking sibling of the Model Downloader: a full-height "waiting for model" splash that combines model metadata (size, context length, category, a cached-vs-downloading badge) with a progress bar and a two-path help message (first-download vs cache-load). It composes the lower-level `DownloadProgress` and binds to `useModelLoad` (`progressValue`, `cached`, `status`).

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/local-first/model-loading-panel`

Full source: https://localmode.ai/r/ui/local-first/model-loading-panel.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/local-first/model-loading-panel
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders the load state + metadata you pass — works with any backend. Recommended producer: `useModelLoad` (drive the load) / `useModelStatus` (read-only view of the same lifecycle) from `@localmode/react` (on-device, optional).

* `lucide-react` — icons
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Registry dependencies [#registry-dependencies]

* `@localmode/ui/local-first/model-downloader` — composes `DownloadProgress`

Files installed [#files-installed]

* `model-loading-panel.tsx` — the `ModelLoadingPanel` component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**ModelLoadingPanel**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` | — | **Required.** Model display name. |
| `size` | `string` | — | Human-readable size. |
| `contextLength` | `number` | — | Context window in tokens. |
| `category` | `string` | — | Category / family label. |
| `progress` | `object \| number` | — | **Required.** Progress value (0–1 fraction or {@link DownloadProgressValue}). |
| `cached` | `boolean` | — | Whether the model is loading from cache rather than downloading fresh. |

Examples [#examples]

Blocking load state [#blocking-load-state]

```tsx
import { useModelLoad } from '@localmode/react';
import { webllm, isModelCached } from '@localmode/webllm';
import { ModelLoadingPanel } from '@/components/model-loading-panel';

export function Gate({ children }) {
  const { status, progressValue } = useModelLoad({
    key: 'Llama-3.2-1B-Instruct-q4f16_1-MLC',
    create: (onProgress) =>
      webllm.languageModel('Llama-3.2-1B-Instruct-q4f16_1-MLC', { onProgress }),
    isCached: () => isModelCached('Llama-3.2-1B-Instruct-q4f16_1-MLC'),
    autoLoad: true,
  });

  if (status !== 'ready') {
    return <ModelLoadingPanel name="Llama 3.2 1B" size="1.2 GB" progress={progressValue} />;
  }
  return children;
}
```

`progressValue` (`{ loaded?, total?, percent, cached? }`, `percent` 0–1) drops straight into the panel's `progress` prop, and its `cached` flag (from the `isCached` probe) flips the help copy between the first-download and cache-load paths.

Customization [#customization]

The help copy switches on the `cached` flag (or `progress.cached` — set automatically when you pass `useModelLoad`'s `progressValue`). It reuses `DownloadProgress` from the Model Downloader item, which the CLI installs as a registry dependency. Styled entirely with shadcn/ui CSS-variable utilities so it inherits your theme — because you own the copied file, every class and threshold is yours to change.

# Model Metadata Card

Model Metadata Card [#model-metadata-card]

The **Model Metadata Card** (`GGUFMetadataCard`, with a `ModelMetadataCard` alias) is a structured key-value grid of parsed model metadata — architecture, parameter count, quantization, context length, embedding dimension, vocab size, head/layer counts, file size, and optional author/license — driven by a field-descriptor array so absent fields are skipped cleanly. Feed it `parseGGUFMetadata()` output from `@localmode/wllama` (or any object matching the `ModelMetadata` shape); the display is a generic metadata grid.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/local-first/model-metadata-card`

Full source: https://localmode.ai/r/ui/local-first/model-metadata-card.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/local-first/model-metadata-card
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders any object matching the `ModelMetadata` shape you pass — works with any backend. Recommended producer: `parseGGUFMetadata()` from `@localmode/wllama` (on-device, optional).

* `lucide-react` — icons
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `model-metadata-card.tsx` — `GGUFMetadataCard` (alias `ModelMetadataCard`)
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**GGUFMetadataCard**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `metadata` | `object` | — | **Required.** Parsed metadata fields. Absent optional fields are omitted from the grid. |
| `title` | `string` | `"Model metadata"` | Optional title. |

**ModelMetadata**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `architecture` | `string` | — | Architecture (e.g. "llama"). |
| `parameters` | `number \| string` | — | Parameter count (raw number or label). |
| `quantization` | `string` | — | Quantization scheme (e.g. "Q4_K_M"). |
| `contextLength` | `number` | — | Context length in tokens. |
| `embeddingDimension` | `number` | — | Embedding dimension. |
| `vocabSize` | `number` | — | Vocabulary size. |
| `headCount` | `number` | — | Number of attention heads. |
| `layerCount` | `number` | — | Number of transformer layers / blocks. |
| `fileSizeBytes` | `number` | — | File size in bytes. |
| `author` | `string` | — | Optional author / organization. |
| `license` | `string` | — | Optional license identifier. |

Examples [#examples]

Parsed GGUF metadata [#parsed-gguf-metadata]

```tsx
import { GGUFMetadataCard } from '@/components/model-metadata-card';
import { parseGGUFMetadata } from '@localmode/wllama';

const metadata = await parseGGUFMetadata(modelUrl);

<GGUFMetadataCard metadata={metadata} />
```

Customization [#customization]

Field formatting (bytes, large numbers) lives in the `FIELDS` descriptor array — add fields or change labels there. Parameters/file size are auto-formatted. Styled entirely with shadcn/ui CSS-variable utilities so it inherits your theme — because you own the copied file, every class and threshold is yours to change.

# Model Recommendation Card

Model Recommendation Card [#model-recommendation-card]

The **Model Recommendation Card** renders a single scored recommendation: a radial score dial (0–100), the model name, a monospace model id, a badge row (provider, size, speed/quality tiers, recommended device with a stable tier→color mapping), a description, and reason chips. When `onToggleCompare` is supplied it exposes a compare toggle. Bind to `useModelRecommendations`.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/local-first/model-recommendation-card`

Full source: https://localmode.ai/r/ui/local-first/model-recommendation-card.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/local-first/model-recommendation-card
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders the scored recommendation you pass and emits the compare toggle — works with any backend. Recommended producer: `useModelRecommendations` from `@localmode/react` (on-device, optional).

* `lucide-react` — icons
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `model-recommendation-card.tsx` — the `ModelRecommendationCard` component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**ModelRecommendationCard**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `recommendation` | `object` | — | **Required.** The recommendation to render. |
| `comparing` | `boolean` | — | Whether this card is selected for comparison. |
| `onToggleCompare` | `function` | — | When provided, shows a compare toggle that calls back with the model id. |

**ModelRecommendation**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `modelId` | `string` | — | **Required.** Stable model id. |
| `name` | `string` | — | **Required.** Display name. |
| `provider` | `string` | — | Provider (e.g. "transformers", "wllama"). |
| `size` | `string` | — | Human-readable size. |
| `score` | `number` | — | **Required.** Score in the 0–100 range. |
| `recommendedDevice` | `"cpu" \| "wasm" \| "webgpu"` | — | Recommended runtime device. |
| `speedTier` | `"slow" \| "medium" \| "fast"` | — | Speed tier. |
| `qualityTier` | `"high" \| "low" \| "medium"` | — | Quality tier. |
| `description` | `string` | — | One-line description. |
| `reasons` | `array` | — | Reasons the model was recommended. |

Examples [#examples]

Bound to recommendations [#bound-to-recommendations]

```tsx
const { recommendations } = useModelRecommendations({ task: 'embedding' });
{recommendations.map((r) => (
  <ModelRecommendationCard
    key={r.entry.modelId}
    recommendation={{ modelId: r.entry.modelId, name: r.entry.name, score: r.score, reasons: r.reasons }}
  />
))}
```

Customization [#customization]

The score dial color steps green/amber/rose by score; tier badge colors come from the `TIER_COLOR` map. Pass `onToggleCompare` to reveal the compare control. Styled entirely with shadcn/ui CSS-variable utilities so it inherits your theme — because you own the copied file, every class and threshold is yours to change.

# Model Search Browser

Model Search Browser [#model-search-browser]

The **Model Search Browser** is a cmdk-based searchable model-repo browser: a controlled search input, a sort selector (downloads / likes / last-modified), result rows (repo id, author, compact download/like counts, relative last-modified, capped tag badges), load-more pagination, and a per-repo expandable file list (filename, quantization badge, human-readable size) with per-file select actions — plus distinct loading, empty, and error-with-retry states.

It is purely presentational: every value arrives via props and every action leaves via a callback, so **any backend can feed it** — the HuggingFace Hub API, a private model registry, or static fixtures. The consumer owns all fetching, debouncing, and pagination state; cmdk's built-in filtering is disabled because results arrive pre-filtered from your backend.

**When to use it:** browsing a large remote model catalog (e.g. the 160K+ GGUF repos on HuggingFace) down to a concrete file the user can load.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/local-first/model-search-browser`

Full source: https://localmode.ai/r/ui/local-first/model-search-browser.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/local-first/model-search-browser
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders the `results` and `files` you pass and emits every action via callbacks — works with any backend. Recommended wiring: the HuggingFace Hub API (see the example below); a private registry endpoint or a static catalog works identically (optional).

* `cmdk` — the underlying command/list primitive
* `lucide-react` — icons
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `model-search-browser.tsx` — the `ModelSearchBrowser` component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**ModelSearchBrowser**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `query` | `string` | — | **Required.** The controlled search query. |
| `onQueryChange` | `function` | — | **Required.** Fired with the new query on every keystroke. |
| `sort` | `ModelSearchSort` | — | **Required.** The active sort order. |
| `onSortChange` | `function` | — | **Required.** Fired with the chosen sort order. |
| `results` | `array` | — | **Required.** The result rows to render (already searched/sorted by the backend). |
| `isLoading` | `boolean` | — | Whether a search (or the next page) is in flight — renders skeleton rows. |
| `error` | `string \| null` | — | Error message for the failed search — renders the error state. |
| `onRetry` | `function` | — | Fired by the error state's retry affordance. |
| `hasMore` | `boolean` | — | Whether more pages exist — renders the load-more affordance. |
| `onLoadMore` | `function` | — | Fired when the user asks for the next page. |
| `expandedRepoId` | `string \| null` | — | The repo id whose file list is expanded (null/undefined: none). |
| `onSelectRepo` | `function` | — | Fired with the clicked repo id, or null when the expanded row is collapsed. |
| `files` | `array \| null` | — | Files of the expanded repo (null while not yet available). |
| `filesLoading` | `boolean` | — | Whether the expanded repo's file list is loading. |
| `filesError` | `string \| null` | — | Error message for the failed file listing. |
| `onSelectFile` | `function` | — | Fired when the user picks a file inside the expanded repo. |

**ModelSearchResult**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `repoId` | `string` | — | **Required.** Stable repo id (e.g. "bartowski/Llama-3.2-1B-Instruct-GGUF"). |
| `author` | `string` | — | Repo author/organization. |
| `downloads` | `number` | — | Total download count (rendered compactly, e.g. "1.2M"). |
| `likes` | `number` | — | Like count (rendered compactly). |
| `lastModified` | `string` | — | Last-modified ISO timestamp (rendered as a relative time). |
| `tags` | `array` | — | Repo tags (capped with an overflow count). |

**ModelRepoFile**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `filename` | `string` | — | **Required.** File name (e.g. "Llama-3.2-1B-Instruct-Q4_K_M.gguf"). |
| `sizeBytes` | `number` | — | File size in bytes (rendered human-readable). |
| `quantLabel` | `string` | — | Quantization label badge (e.g. "Q4_K_M"). |

Examples [#examples]

Fixture-driven (any backend) [#fixture-driven-any-backend]

The component owns no fetching — hand it rows from anywhere:

```tsx
<ModelSearchBrowser
  query={query}
  onQueryChange={setQuery}
  sort={sort}
  onSortChange={setSort}
  results={results}
  expandedRepoId={expanded}
  onSelectRepo={setExpanded}
  files={files}
  onSelectFile={(repoId, file) => pick(`${repoId}:${file.filename}`)}
/>
```

Wiring to the HuggingFace API [#wiring-to-the-huggingface-api]

The component doesn't care where results come from — this recipe feeds it from the public HuggingFace Hub API, but swapping the two `fetch` calls for your own registry endpoint changes nothing else:

```tsx
import { useEffect, useState } from 'react';
import {
  ModelSearchBrowser,
  type ModelRepoFile,
  type ModelSearchResult,
  type ModelSearchSort,
} from '@/components/model-search-browser';

export function GGUFBrowser() {
  const [query, setQuery] = useState('');
  const [sort, setSort] = useState<ModelSearchSort>('downloads');
  const [results, setResults] = useState<ModelSearchResult[]>([]);
  const [isLoading, setLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);
  const [expanded, setExpanded] = useState<string | null>(null);
  const [files, setFiles] = useState<ModelRepoFile[] | null>(null);

  // Debounced, abortable search — the consumer owns all orchestration.
  useEffect(() => {
    const controller = new AbortController();
    const timer = setTimeout(async () => {
      setLoading(true);
      setError(null);
      try {
        const url = `https://huggingface.co/api/models?filter=gguf&search=${encodeURIComponent(query)}&sort=${sort}&direction=-1&limit=30`;
        const res = await fetch(url, { signal: controller.signal });
        if (!res.ok) throw new Error(`Search failed (HTTP ${res.status})`);
        const repos: {
          id: string;
          downloads?: number;
          likes?: number;
          lastModified?: string;
          tags?: string[];
        }[] = await res.json();
        setResults(
          repos.map((r) => ({
            repoId: r.id,
            author: r.id.split('/')[0],
            downloads: r.downloads,
            likes: r.likes,
            lastModified: r.lastModified,
            tags: r.tags,
          })),
        );
      } catch (e) {
        if (!controller.signal.aborted)
          setError(e instanceof Error ? e.message : 'Search failed');
      } finally {
        if (!controller.signal.aborted) setLoading(false);
      }
    }, 300);
    return () => {
      clearTimeout(timer);
      controller.abort();
    };
  }, [query, sort]);

  const selectRepo = async (repoId: string | null) => {
    setExpanded(repoId);
    setFiles(null);
    if (!repoId) return;
    const res = await fetch(`https://huggingface.co/api/models/${repoId}?blobs=true`);
    const repo: { siblings?: { rfilename: string; size?: number }[] } = await res.json();
    setFiles(
      (repo.siblings ?? [])
        .filter((s) => s.rfilename.endsWith('.gguf'))
        .map((s) => ({
          filename: s.rfilename,
          sizeBytes: s.size,
          quantLabel: s.rfilename.match(/(?:I?Q\d|F16|F32|BF16)[\w]*/i)?.[0]?.toUpperCase(),
        })),
    );
  };

  return (
    <ModelSearchBrowser
      query={query}
      onQueryChange={setQuery}
      sort={sort}
      onSortChange={setSort}
      results={results}
      isLoading={isLoading}
      error={error}
      onRetry={() => setQuery((q) => q.trim())}
      expandedRepoId={expanded}
      onSelectRepo={selectRepo}
      files={files}
      filesLoading={expanded !== null && files === null}
      onSelectFile={(repoId, file) => console.log(`load ${repoId}:${file.filename}`)}
    />
  );
}
```

Error state with retry [#error-state-with-retry]

Pass the failure message and a retry callback — the component renders the error panel and the retry affordance:

```tsx
<ModelSearchBrowser
  query={query}
  onQueryChange={setQuery}
  sort={sort}
  onSortChange={setSort}
  results={[]}
  error="Rate limited by the search API — try again in a minute."
  onRetry={refetch}
/>
```

Customization [#customization]

Result rows cap tags at 4 before collapsing into a `+N` overflow chip — change `MAX_TAGS` in the copied file. The sort labels live in the `SORT_OPTIONS` array; the compact-count, byte-size, and relative-time formatters (`formatCount`, `formatBytes`, `formatRelative`) are plain local functions you can swap for `Intl` variants. The list height is the `max-h-96` on `Command.List`. Styled entirely with shadcn/ui CSS-variable utilities so it inherits your theme — because you own the copied file, every class and threshold is yours to change.

# Model Selector

Model Selector [#model-selector]

The **Model Selector** renders a device-aware list of models grouped by category, with backend filter chips (WebGPU / ONNX / WASM / LiteRT) that show live counts, per-model badges (vision, tool-calling, cached), a download affordance for uncached models, and a delete-from-cache affordance for cached ones. Models that cannot run on the current device — e.g. a WebGPU-only model on a device without WebGPU — are visibly de-emphasized while their "Requires WebGPU" reason stays at full contrast. It emits `onSelect(modelId)` and owns no selection state.

The backend-filter row wraps at narrow widths and only appears when **two or more** backends are actually present — a single-backend catalog (e.g. a CLIP embedding pair) hides the row rather than surfacing disabled zero-count chips. The filter chips form a labelled `role="group"` and expose their pressed state via `aria-pressed`; the active model row is marked `aria-current`; the download/delete controls carry `aria-label`s and expand to a ≥44px touch target on mobile.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/local-first/model-selector`

Full source: https://localmode.ai/r/ui/local-first/model-selector.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/local-first/model-selector
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders the model list + `hasWebGPU` device-fit you pass and emits `onSelect(modelId)` — works with any backend. Recommended producer: `useCapabilities` (device-fit) and your `useModelRecommendations` data from `@localmode/react` (on-device, optional).

* `lucide-react` — icons
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `model-selector.tsx` — the `ModelSelector` component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**ModelSelector**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `models` | `array` | — | **Required.** The models to list. |
| `selectedId` | `string` | — | Currently selected model id (for the active ring). |
| `hasWebGPU` | `boolean` | — | Whether the current device supports WebGPU. Models whose backend is `webgpu` are de-emphasized when this is false. |
| `busyIds` | `object` | — | Set of model ids whose download/delete is in progress. |
| `onSelect` | `function` | — | Fired when a fit, available model is activated. |
| `onDownload` | `function` | — | Fired when the download affordance on an uncached model is activated. |
| `onDelete` | `function` | — | Fired when the delete-from-cache affordance on a cached model is activated. |

**SelectableModel**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` | — | **Required.** Stable model identifier passed to `onSelect`. |
| `name` | `string` | — | **Required.** Display name. |
| `backend` | `ModelBackend` | — | **Required.** Backend the model runs on (drives filter chips and device-fit). |
| `category` | `string` | — | **Required.** Category used for grouping (e.g. "Chat", "Vision"). |
| `size` | `string` | — | Human-readable size (e.g. "1.2 GB"). |
| `vision` | `boolean` | — | Whether the model supports image input. |
| `tools` | `boolean` | — | Whether the model supports tool / function calling. |
| `cached` | `boolean` | — | Whether the model is already cached on-device. |

Examples [#examples]

Bound to recommendations + capabilities [#bound-to-recommendations--capabilities]

```tsx
import { useCapabilities } from '@localmode/react';
import { ModelSelector } from '@/components/model-selector';

export function Sidebar({ models, onPick }) {
  const { capabilities } = useCapabilities();
  return (
    <ModelSelector
      models={models}
      hasWebGPU={Boolean(capabilities?.features.webgpu)}
      onSelect={onPick}
      onDownload={(id) => prefetch(id)}
      onDelete={(id) => evict(id)}
    />
  );
}
```

Customization [#customization]

The de-emphasis (a muted model name, with the amber "Requires WebGPU" reason kept at full — AA — contrast rather than dimmed by opacity) and the hint itself are derived from the `hasWebGPU` prop — extend `isUnfit` in the copied file to gate on other backends (e.g. WASM-only). The filter row is auto-hidden for single-backend catalogs (`presentBackends.length > 1`); drop that guard if you always want the row. Badge icons use `lucide-react`; the active filter chip uses `bg-primary`. Styled entirely with shadcn/ui CSS-variable utilities so it inherits your theme — because you own the copied file, every class and threshold is yours to change.

# Network Badge

Network Badge [#network-badge]

The **Network Badge** is a reactive online/offline indicator sourced from `useNetworkStatus`. Because local models keep working without a network, "offline" is informational, not an error — pair it with **Offline Ready**, which signals that the app's required model is cached on-device and can run with no connectivity.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/local-first/network-badge`

Full source: https://localmode.ai/r/ui/local-first/network-badge.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/local-first/network-badge
```

Data source & dependencies [#data-source--dependencies]

**Data source:** reads online/offline state via the bundled `useNetworkStatus` navigator hook — self-contained, works in any React app, no backend required. (It mirrors `useNetworkStatus` from `@localmode/react`.)

* `@localmode/ui/lib/use-environment` — the bundled `useNetworkStatus` navigator hook (installed automatically as a registry dependency)
* `lucide-react` — icons
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `network-badge.tsx` — `NetworkBadge` + `OfflineReady`
* `lib/use-environment.ts` — the bundled `useNetworkStatus` navigator hook
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**NetworkBadge**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `compact` | `boolean` | `false` | When true, render a compact dot-only badge without text. |

**OfflineReady**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `ready` | `boolean` | — | **Required.** Whether the model(s) the app needs are cached on-device. When true the app can run with no network. |
| `label` | `string` | — | Optional label override. |

Examples [#examples]

Online/offline + offline-ready [#onlineoffline--offline-ready]

```tsx
import { NetworkBadge, OfflineReady } from '@/components/network-badge';

<NetworkBadge />
<OfflineReady ready={isModelCached} />
```

Customization [#customization]

Both badges use shadcn/ui tokens with `emerald`/`amber` accents. `OfflineReady` takes a `ready` boolean from your cache check — when true the app can run fully offline. Styled entirely with shadcn/ui CSS-variable utilities so it inherits your theme — because you own the copied file, every class and threshold is yours to change.

# Provider Badge

Provider Badge [#provider-badge]

The **Provider Badge** displays the **resolved** provider identity — composing the
[Provider Fallback Badge](/docs/local-first/provider-fallback-badge) for the tier
and name — alongside the **model id that actually served** the request. While
`providerName` is `null` it shows a "Resolving provider…" placeholder, so the
badge never claims a provider before one has resolved.

> **How it differs from Provider Fallback Badge.** The
> [Provider Fallback Badge](/docs/local-first/provider-fallback-badge) is the
> lower-level **tier chip** (built-in vs download, plus the WASM threading
> variant). The Provider Badge **composes it** and adds two things the fallback
> badge does not: the **resolved provider identity** (with a Resolving state) and
> the **served model id**. Use the fallback badge when you only want the tier
> chip; use the Provider Badge when you want to surface which provider + model
> actually answered.

> **Presentational.** It takes generic display props (`providerName`, `tier`,
> `modelId`, `note`) — no block-local provider types. Feed it from your provider
> resolution (recommended: a provider-fallback resolver such as
> `useProviderFallback` from `@localmode/react`).

**When to use it:** a Chrome-AI ⇄ Transformers.js (or any two-tier) surface where
the user should see which provider and model actually served the last result.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/local-first/provider-badge`

Full source: https://localmode.ai/r/ui/local-first/provider-badge.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/local-first/provider-badge
```

Dependencies [#dependencies]

* **Data source:** renders the resolved provenance you pass — works with any backend. Recommended LocalMode source: `useProviderFallback().resolution` (optional).
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)
* Composes `@localmode/ui/local-first/provider-fallback-badge` (installed automatically as a registry dependency)

Files installed [#files-installed]

* `provider-badge.tsx` — the component
* `provider-fallback-badge.tsx` — the composed tier chip
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**ProviderBadge**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `providerName` | `string \| null` | — | **Required.** Resolved provider display name, or null while resolution is pending. |
| `tier` | `ProviderTier` | — | **Required.** The resolved provider's tier (drives the composed fallback badge). |
| `modelId` | `string \| null` | — | **Required.** The model id that actually served the most recent result, if any. |
| `note` | `string` | — | Optional note rendered after the badge (e.g. a provider disclaimer). |

Examples [#examples]

Show a resolved provider + served model [#show-a-resolved-provider--served-model]

```tsx
import { ProviderBadge } from '@/components/provider-badge';

<ProviderBadge providerName="Chrome AI" tier="built-in" modelId="gemini-nano" />
```

Drive it from a provider-fallback resolver [#drive-it-from-a-provider-fallback-resolver]

```tsx
import { useProviderFallback } from '@localmode/react';
import { ProviderBadge } from '@/components/provider-badge';

function SummarizerBadge() {
  const { resolution } = useProviderFallback();
  return (
    <ProviderBadge
      providerName={resolution?.provider === 'chrome-ai' ? 'Chrome AI' : resolution ? 'Transformers.js' : null}
      tier={resolution?.tier ?? 'download'}
      modelId={resolution?.modelId ?? null}
    />
  );
}
```

Customization [#customization]

The badge never estimates or probes — it reflects exactly the `providerName` /
`tier` / `modelId` you pass, so it can never claim a provider that did not serve
the request. Because you own the copied file, restyle the served-model line, add
a copy button, or change the "Resolving…" copy.

# Provider Fallback Badge

Provider Fallback Badge [#provider-fallback-badge]

The **Provider Fallback Badge** surfaces the active AI backend tier — a zero-download built-in (Chrome AI) vs a model-download provider (Transformers.js) — plus a WASM threading variant ("Multi-thread" when cross-origin isolated / SharedArrayBuffer is available, else "Single-thread"). It is a software-side sibling to the Device Badge (which surfaces hardware).

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/local-first/provider-fallback-badge`

Full source: https://localmode.ai/r/ui/local-first/provider-fallback-badge.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/local-first/provider-fallback-badge
```

Data source & dependencies [#data-source--dependencies]

**Data source:** reads the threading capability via the bundled `useCapabilities` navigator hook (the active-tier prop is yours to pass) — self-contained, works in any React app. (It mirrors `useCapabilities` from `@localmode/react`.)

* `@localmode/ui/lib/use-environment` — the bundled `useCapabilities` navigator hook (installed automatically as a registry dependency)
* `lucide-react` — icons
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `provider-fallback-badge.tsx` — the `ProviderFallbackBadge` component
* `lib/use-environment.ts` — the bundled `useCapabilities` navigator hook
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**ProviderFallbackBadge**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tier` | `ProviderTier` | — | **Required.** Active provider tier: a zero-download built-in (e.g. Chrome AI) vs a model-download provider (e.g. Transformers.js). |
| `providerName` | `string` | — | Provider display name (e.g. "Chrome AI", "Transformers.js"). |
| `crossOriginIsolated` | `boolean` | — | Override the cross-origin-isolation flag. When omitted the badge reads `useCapabilities` (and falls back to `globalThis.crossOriginIsolated`). |
| `hideThreading` | `boolean` | `false` | Hide the threading sub-badge. |

Examples [#examples]

Built-in vs download provider [#built-in-vs-download-provider]

```tsx
<ProviderFallbackBadge tier="built-in" providerName="Chrome AI" />
<ProviderFallbackBadge tier="download" providerName="Transformers.js" />
```

Customization [#customization]

The threading flag falls back to `useCapabilities` then `globalThis.crossOriginIsolated` when not passed. Hide the threading sub-badge with `hideThreading`. Styled entirely with shadcn/ui CSS-variable utilities so it inherits your theme — because you own the copied file, every class and threshold is yours to change.

# Semantic Cache Status Bar

Semantic Cache Status Bar [#semantic-cache-status-bar]

The **Semantic Cache Status Bar** complements the Cache Badge: a compact toolbar row for `useSemanticCache` showing entry count, hit-rate %, an icon-only clear-cache button (when entries > 0), and an enable/disable toggle (with a spinner while the embedding model loads). It pairs with a per-message `CachedAnnotation` ("Cached (38ms)"). Distinct from the Cache Badge (model-download cache), this surfaces semantic-cache hits on responses.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/local-first/semantic-cache-status-bar`

Full source: https://localmode.ai/r/ui/local-first/semantic-cache-status-bar.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/local-first/semantic-cache-status-bar
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders the cache `stats` you pass and emits clear/toggle — works with any backend. Recommended producer: `useSemanticCache` (backed by `createSemanticCache`) from `@localmode/react` (on-device, optional).

* `lucide-react` — icons
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `semantic-cache-status-bar.tsx` — `SemanticCacheStatusBar` + `CachedAnnotation`
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**SemanticCacheStatusBar**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `stats` | `object` | — | **Required.** Live cache stats (from `useSemanticCache`). |
| `enabled` | `boolean` | — | **Required.** Whether the cache is enabled. |
| `isLoading` | `boolean` | — | Whether the embedding model is still loading (shows a spinner). |
| `onToggle` | `function` | — | Fired when the enable/disable toggle is flipped. |
| `onClear` | `function` | — | Fired when the clear-cache button is pressed (shown when entries > 0). |

**CacheStatsLike**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `entries` | `number` | — | **Required.** Number of cached entries. |
| `hitRate` | `number` | — | **Required.** Hit rate in the 0–1 range. |

Examples [#examples]

Bound to useSemanticCache [#bound-to-usesemanticcache]

```tsx
const { stats, cache } = useSemanticCache({ embeddingModel });
<SemanticCacheStatusBar
  stats={stats}
  enabled={enabled}
  isLoading={!cache}
  onToggle={setEnabled}
  onClear={() => cache?.clear()}
/>
```

Customization [#customization]

The hit-rate reads `stats.hitRate` (0–1) and renders as a percentage. The toggle is a themed switch; show the spinner via `isLoading` while the embedding model loads. Styled entirely with shadcn/ui CSS-variable utilities so it inherits your theme — because you own the copied file, every class and threshold is yours to change.

# Storage Meter

Storage Meter [#storage-meter]

The **Storage Meter** shows origin / IndexedDB storage usage against quota as a meter, with a warning state past a configurable threshold. Storage estimates are approximate and blocked in some browsers (e.g. Safari private mode), so the component degrades to a graceful "unavailable" state rather than erroring. Bind it to `useStorageQuota` (the default) or pass an explicit `quota`.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/local-first/storage-meter`

Full source: https://localmode.ai/r/ui/local-first/storage-meter.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/local-first/storage-meter
```

Data source & dependencies [#data-source--dependencies]

**Data source:** reads `navigator.storage.estimate()` via the bundled `useStorageQuota` navigator hook (or pass an explicit `quota`) — self-contained, works in any React app. (It mirrors `useStorageQuota` from `@localmode/react`.)

* `@localmode/ui/lib/use-environment` — the bundled `useStorageQuota` navigator hook (installed automatically as a registry dependency)
* `@localmode/ui/lib/browser-utils` — `formatBytes` for the usage readout (installed automatically as a registry dependency)
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `storage-meter.tsx` — the `StorageMeter` component
* `lib/use-environment.ts` — the bundled `useStorageQuota` navigator hook
* `lib/browser-utils.ts` — generic browser helpers (`formatBytes`)
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**StorageMeter**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `warnThreshold` | `number` | `0.8` | Fraction (0–1) at which the meter enters its warning state. |
| `quota` | `object` | — | Override the live quota source (used / total bytes). When omitted the component reads `useStorageQuota()`. |

Examples [#examples]

Default (live quota) [#default-live-quota]

```tsx
<StorageMeter warnThreshold={0.9} />
```

Explicit quota [#explicit-quota]

```tsx
<StorageMeter quota={{ usedBytes: 1.9e9, quotaBytes: 2e9 }} />
```

Customization [#customization]

The warning state turns the bar amber and shows a hint past `warnThreshold` (default `0.8`). When no estimate is available the component renders a muted "Storage estimate unavailable" row — never an error. Styled entirely with shadcn/ui CSS-variable utilities so it inherits your theme — because you own the copied file, every class and threshold is yours to change.

# Vector Export Panel

Vector Export Panel [#vector-export-panel]

The **Vector Export Panel** is the counterpart to the [Vector Import Flow](/docs/local-first/vector-import-flow): a record/dimension count line, a row per export format (native JSON with vectors, CSV, JSONL — each with a label, description, and vectors-included / text-only indicator), per-format export actions emitting `onExport(formatId)`, a busy state that disables all actions (with a spinner on the active format), a zero-records disabled state, and an optional last-export banner (format, records, human-readable size, filename).

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/local-first/vector-export-panel`

Full source: https://localmode.ai/r/ui/local-first/vector-export-panel.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/local-first/vector-export-panel
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders the formats/counts/exporting/last-export state you pass and emits `onExport(formatId)` — works with any backend. Recommended producer: `useImportExport` (`exportCSV`, `exportJSONL`) from `@localmode/react` plus a native JSON export (on-device, optional).

* `lucide-react` — icons
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `vector-export-panel.tsx` — the `VectorExportPanel` component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**VectorExportPanel**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `formats` | `array` | — | **Required.** Export formats to offer, one action per format. |
| `recordCount` | `number` | — | **Required.** Number of records currently in the corpus. Zero disables all actions. |
| `dimensions` | `number` | — | Vector dimensions of the corpus (shown next to the record count). |
| `exporting` | `boolean \| string` | — | Busy state: `true` disables all actions; a format id additionally renders a spinner on that format's action. |
| `lastExport` | `object \| null` | — | Summary of the last completed export (shown as a result banner). |
| `onExport` | `function` | — | **Required.** Fired with the format id when the user activates a format's export action. |
| `disabled` | `boolean` | — | Disables all actions regardless of state. |

**ExportFormat**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` | — | **Required.** Stable format id (passed to `onExport`, e.g. `"native-json"`, `"csv"`, `"jsonl"`). |
| `label` | `string` | — | **Required.** Display label (e.g. "Native JSON"). |
| `description` | `string` | — | One-line description (e.g. "Full fidelity, re-importable"). |
| `vectors` | `boolean` | — | Whether the format includes vectors (renders a "Vectors" / "Text only" indicator when set). |

**LastExportSummary**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `formatId` | `string` | — | **Required.** The format that was exported. |
| `records` | `number` | — | **Required.** Number of records exported. |
| `bytes` | `number` | — | **Required.** Export size in bytes. |
| `filename` | `string` | — | Downloaded filename. |
| `at` | `string` | — | When the export finished (preformatted display string, e.g. "just now"). |

Examples [#examples]

Wiring to export functions [#wiring-to-export-functions]

Works with any export backend — pass a busy format id while the export runs, then a summary when it completes:

```tsx
const { exportCSV, exportJSONL } = useImportExport({ db });
const [exporting, setExporting] = useState<string | false>(false);
const [lastExport, setLastExport] = useState<LastExportSummary | null>(null);

const runExport = async (formatId: string) => {
  setExporting(formatId);
  try {
    const blob = formatId === 'csv' ? await exportCSV() : await exportJSONL();
    downloadBlob(blob, `vectors.${formatId}`);
    setLastExport({ formatId, records: count, bytes: blob.size, filename: `vectors.${formatId}` });
  } finally {
    setExporting(false);
  }
};

<VectorExportPanel
  formats={[
    { id: 'csv', label: 'CSV', vectors: false },
    { id: 'jsonl', label: 'JSONL', vectors: false },
  ]}
  recordCount={count}
  exporting={exporting}
  lastExport={lastExport}
  onExport={runExport}
/>
```

Disabling while other work runs [#disabling-while-other-work-runs]

```tsx
<VectorExportPanel formats={formats} recordCount={count} disabled={isImporting} onExport={runExport} />
```

Customization [#customization]

`exporting` accepts `true` (disable everything) or a format id (also spin that format's action). The vectors-included / text-only indicator renders only when a format sets `vectors`; the zero-records note and disabled state kick in at `recordCount === 0`. The size in the last-export banner is formatted by the local `formatBytes` helper — edit its thresholds or units freely. Styled entirely with shadcn/ui CSS-variable utilities so it inherits your theme — because you own the copied file, every class and threshold is yours to change.

# Vector Import Flow

Vector Import Flow [#vector-import-flow]

The **Vector Import Flow** wraps `useImportExport`: a preview panel (detected-format badge, total / with-vectors / text-only counts, detected dimensions, dimension-mismatch warning, Cancel/Confirm), a phased progress bar (parsing → validating → embedding → importing), a result stats banner (imported / skipped / re-embedded, format, duration), and a record-preview table for row-level sanity checks before a destructive ingest. It references the cross-family `FormatDetectionBadge` and inlines a minimal fallback so it builds independently.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/local-first/vector-import-flow`

Full source: https://localmode.ai/r/ui/local-first/vector-import-flow.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/local-first/vector-import-flow
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders the import preview/progress/result you pass and emits Cancel/Confirm — works with any backend. Recommended producer: `useImportExport` (backed by the import/export parsers) from `@localmode/react` (on-device, optional).

* `lucide-react` — icons
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Registry dependencies [#registry-dependencies]

* `@localmode/ui/data-documents/format-detection-badge` — the shared format badge (a minimal inline fallback ships with this item)

Files installed [#files-installed]

* `vector-import-flow.tsx` — the `VectorImportFlow` component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**VectorImportFlow**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `preview` | `object \| null` | — | Parse preview shown before a destructive import. |
| `targetDimensions` | `number` | — | Target VectorDB dimensions (for the mismatch warning). |
| `records` | `array` | — | Sample records for the preview table. |
| `progress` | `object \| null` | — | Live import progress. |
| `stats` | `object \| null` | — | Final import stats (shown when the import completes). |
| `isImporting` | `boolean` | — | Whether an import is running. |
| `onConfirm` | `function` | — | Fired to confirm the import. |
| `onCancel` | `function` | — | Fired to cancel/dismiss the preview. |

**ImportPreview**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `format` | `ExternalFormat` | — | **Required.** |
| `totalRecords` | `number` | — | **Required.** |
| `recordsWithVectors` | `number` | — | **Required.** |
| `recordsWithTextOnly` | `number` | — | **Required.** |
| `dimensions` | `number \| null` | — | **Required.** |

Examples [#examples]

Preview then import [#preview-then-import]

```tsx
const { parseResult, progress, stats, parsePreview, importData } = useImportExport({ db, model });
<VectorImportFlow
  preview={parseResult}
  targetDimensions={db.dimensions}
  progress={progress}
  stats={stats}
  onConfirm={() => importData({ content })}
/>
```

Customization [#customization]

The dimension-mismatch warning compares `preview.dimensions` against `targetDimensions`. Swap the inline `FormatBadge` for the installed `@localmode/ui/data-documents/format-detection-badge` when present. Styled entirely with shadcn/ui CSS-variable utilities so it inherits your theme — because you own the copied file, every class and threshold is yours to change.

# Vector Storage Observability

Vector Storage Observability [#vector-storage-observability]

The **Vector Storage Observability** set complements the Storage Meter (quota) with VectorDB-specific observability: a compression-stats badge (SQ8 ratio + before/after size, e.g. "4.0× — 15KB→3.7KB"), a three-tier storage estimate (Raw Float32 / SQ8 4× / PQ 8–32× with the active tier highlighted), and a GPU-aware search-latency badge (accented when WebGPU-accelerated). Values derive from compression stats and search timing, passed in as props (recommended producer: `getCompressionStats()` / `useStorageQuota` from `@localmode/react`, on-device, optional).

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/local-first/vector-storage-observability`

Full source: https://localmode.ai/r/ui/local-first/vector-storage-observability.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/local-first/vector-storage-observability
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders the compression stats + search timing you pass — works with any backend. Recommended producer: `getCompressionStats()` and `useStorageQuota` from `@localmode/react` (on-device, optional).

* `@localmode/ui/lib/browser-utils` — `formatBytes` for the size readouts (installed automatically as a registry dependency)
* `lucide-react` — icons
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `vector-storage-observability.tsx` — the `VectorStorageObservability` component
* `lib/browser-utils.ts` — generic browser helpers (`formatBytes`)
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**VectorStorageObservability**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `stats` | `object` | — | **Required.** Compression stats (from `getCompressionStats()`). |
| `tier` | `QuantizationTier` | — | **Required.** The active quantization tier. |
| `searchLatencyMs` | `number` | — | Last search latency in milliseconds. |
| `webgpuAccelerated` | `boolean` | — | Whether search ran on a WebGPU-accelerated distance kernel. |

**CompressionStatsLike**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `ratio` | `number` | — | **Required.** Compression ratio (original / compressed). |
| `originalSizeBytes` | `number` | — | **Required.** Estimated uncompressed size in bytes. |
| `compressedSizeBytes` | `number` | — | **Required.** Estimated compressed size in bytes. |
| `vectorCount` | `number` | — | Number of stored vectors. |

Examples [#examples]

Bound to compression stats [#bound-to-compression-stats]

```tsx
import { getCompressionStats } from '@localmode/core';

const stats = await getCompressionStats(db); // async — returns Promise<CompressionStats>

<VectorStorageObservability
  stats={stats}
  tier="sq8"
  searchLatencyMs={searchMs}
  webgpuAccelerated={usedGpu}
/>
```

Customization [#customization]

The latency badge accents (violet) when `webgpuAccelerated` is true. The three-tier estimate highlights the `tier` prop; non-active tiers dim. Styled entirely with shadcn/ui CSS-variable utilities so it inherits your theme — because you own the copied file, every class and threshold is yours to change.

# Before / After Image Viewer

Before / After Image Viewer [#before--after-image-viewer]

The **Before / After Image Viewer** compares an original image with a transformed result. It supports two modes: a **two-panel grid** (both images side-by-side, the result panel ring-highlighted and rendered on a checkerboard transparency background so alpha shows through), and a segmented **Original / Enhanced toggle** that swaps a single displayed image source.

It is presentational — both `originalSrc` and `processedSrc` are image source strings (data URL or object URL). Produce the result image with [`useImageToImage`](https://localmode.dev/docs/react) (upscaling / super-resolution), whose `UpscaleImageResult.image` is an `ImageData | Blob` you convert to an object URL (`URL.createObjectURL`) before passing it as `processedSrc`. It owns only the toggle's local UI state.

**When to use it:** background removers, photo enhancers / upscalers, segmentation viewers — any "here's your input, here's the result" comparison.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/media-vision/before-after-image-viewer`

Full source: https://localmode.ai/r/ui/media-vision/before-after-image-viewer.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/media-vision/before-after-image-viewer
```

Dependencies [#dependencies]

* **Data source:** renders the `originalSrc` / `processedSrc` image strings you pass — works with any backend that produces a transformed image. Recommended LocalMode producer: `useImageToImage` (upscale / super-resolution) from `@localmode/react` — convert its `image` (`ImageData | Blob`) to an object URL for `processedSrc`. For background removal, composite `useSegmentImage`'s `masks` onto the source into a transparent PNG first (optional).

* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `before-after-image-viewer.tsx` — the component (checkerboard CSS shipped inline)
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**BeforeAfterImageViewer**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `originalSrc` | `string` | — | **Required.** Source (data URL or URL) of the original image. |
| `processedSrc` | `string` | — | Source of the transformed result (upscaled, segmented, background-removed). When omitted, only the original is shown. |
| `mode` | `"toggle" \| "grid"` | `"grid"` | Layout. `"grid"` shows both panels side-by-side; `"toggle"` shows one image with a segmented Original/Enhanced switch. |
| `originalLabel` | `string` | `"Original"` | Label for the original panel/toggle. |
| `processedLabel` | `string` | `"Enhanced"` | Label for the result panel/toggle. |
| `checkerboard` | `boolean` | `true` | Render the result panel on a checkerboard transparency background so alpha shows through (segmentation / background removal). |
| `alt` | `string` | `""` | Base alt text for the subject. Distinct alts are derived for the two images so assistive tech never hears the same description for both — the original becomes `"{originalLabel}: {alt}"` and the result `"{processedLabel}: {alt}"`. Empty (the default) keeps both images decorative. Use {@link originalAlt} / {@link resultAlt} to set them explicitly. |
| `originalAlt` | `string` | — | Explicit alt for the original image. Overrides the value derived from {@link alt}. |
| `resultAlt` | `string` | — | Explicit alt for the processed/result image. Overrides the value derived from {@link alt}. |

Backing hooks [#backing-hooks]

Produce `processedSrc` with `useImageToImage` (upscale / super-resolution) from [`@localmode/react`](https://localmode.dev/docs/react): its `UpscaleImageResult.image` is an `ImageData | Blob`, so wrap it in an object URL (`URL.createObjectURL`) before passing it. For background removal, `useSegmentImage` returns `masks` (not a ready image) — composite a mask onto the source to build a transparent PNG, then pass that URL.

Examples [#examples]

Grid (default) [#grid-default]

```tsx
import { BeforeAfterImageViewer } from '@/components/before-after-image-viewer';
import { useImageToImage } from '@localmode/react';

const { data } = useImageToImage({ model });
// data.image is ImageData | Blob — turn the Blob result into a displayable URL
const processedSrc = data?.image instanceof Blob ? URL.createObjectURL(data.image) : undefined;

<BeforeAfterImageViewer originalSrc={inputDataUrl} processedSrc={processedSrc} />
```

Toggle mode [#toggle-mode]

```tsx
<BeforeAfterImageViewer
  originalSrc={inputDataUrl}
  processedSrc={processedSrc} // object URL from the upscale result Blob
  mode="toggle"
  processedLabel="Upscaled"
/>
```

Background-removal result on checkerboard [#background-removal-result-on-checkerboard]

```tsx
const { data } = useSegmentImage({ model });

// useSegmentImage returns `masks` (SegmentMask[]), not a ready image —
// composite a mask onto the source to produce a transparent-background PNG URL.
const cutoutUrl = data ? compositeMaskToTransparentPng(inputDataUrl, data.masks) : undefined;

<BeforeAfterImageViewer
  originalSrc={inputDataUrl}
  processedSrc={cutoutUrl}
  checkerboard // default — reveals the transparent background
/>
```

Accessibility [#accessibility]

The two images get **distinct** alt text so assistive tech never announces the same description for both. Pass a single `alt` and the viewer derives `"{originalLabel}: {alt}"` for the original and `"{processedLabel}: {alt}"` for the result; or set `originalAlt` / `resultAlt` explicitly for full control. An empty `alt` (the default) keeps both images decorative.

```tsx
<BeforeAfterImageViewer
  originalSrc={inputDataUrl}
  processedSrc={cutoutUrl}
  originalAlt="Original team photo"
  resultAlt="Team photo with the background removed"
/>
```

Customization [#customization]

The checkerboard is a self-contained inline CSS-gradient background, so the component works standalone after `shadcn add` with no global CSS. Adjust the checker size/color in the copied `before-after-image-viewer.tsx`, or set `checkerboard={false}` for opaque results. Panels use shadcn/ui tokens (`border-border`, `bg-card`, `ring-primary`).

# Bounding Box Overlay

Bounding Box Overlay [#bounding-box-overlay]

The **Bounding Box Overlay** renders detection results (`{ label, score, box }`) as absolutely-positioned, color-coded boxes with label chips over a parent image. Pixel-coordinate boxes are converted to **percentage offsets*&#x2A; using the image's natural width/height, so placement is correct at any display size — resize the container and the boxes stay aligned. A companion &#x2A;*`DetectionLabelLegend`** renders a wrapping strip of color → class pills that match the overlay colors.

The overlay consumes one shape — `{ label, score, box }`, where `box` is `{ x, y, width, height }` in natural image pixels. [`useDetectObjects`](https://localmode.dev/docs/react) returns this directly (`DetectObjectsResult.objects`, each a `DetectedObject`). `useDetectFace` returns boxes too (`FaceDetectionResultItem` has `box` + `score`, but no `label`), and `useDetectHands` / `useDetectPose` return landmark sets (`{ landmarks, worldLandmarks, … }`, no `box`) — for those, derive a `label` (and, for hands/pose, a `box` from the landmark extents) before passing them in.

**When to use it:** object/face detection viewers, pose/hand annotation, anything that draws boxes over a still image. (For real-time webcam landmark drawing, use the [Video Canvas](/docs/media-vision/video-canvas) instead.)

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/media-vision/bounding-box-overlay`

Full source: https://localmode.ai/r/ui/media-vision/bounding-box-overlay.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/media-vision/bounding-box-overlay
```

Dependencies [#dependencies]

* **Data source:** renders the `{ label, score, box }` detections you pass — works with any backend that returns boxes. Recommended LocalMode producer: `useDetectObjects` from `@localmode/react` (its `DetectedObject` matches this shape directly). `useDetectFace` boxes (no `label`) and `useDetectHands` / `useDetectPose` landmark output map in with a small adapter (optional).

* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `bounding-box-overlay.tsx` — `BoundingBoxOverlay` + `DetectionLabelLegend`
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**BoundingBoxOverlay**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `detections` | `array` | — | **Required.** Detections to render. Boxes are in natural-pixel coordinates. |
| `naturalWidth` | `number` | — | **Required.** The image's NATURAL width in pixels (e.g. `imgEl.naturalWidth`). Required to convert pixel boxes to display-independent percentage offsets. |
| `naturalHeight` | `number` | — | **Required.** The image's NATURAL height in pixels (e.g. `imgEl.naturalHeight`). |
| `hideLabels` | `boolean` | `false` | Hide the per-box label chip (border-only boxes). Useful for dense landmark/pose output. |

**DetectionLabelLegend**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `labels` | `array` | — | **Required.** Detected class labels (duplicates allowed — they are de-duplicated). Colors match {@link BoundingBoxOverlay} for the same label set/order. |

Backing hooks [#backing-hooks]

Feed it `{ label, score, box }` detections plus the image's `naturalWidth` / `naturalHeight` (read off the rendered `<img>`). `useDetectObjects` from [`@localmode/react`](https://localmode.dev/docs/react) returns `objects` in this shape directly; `useDetectFace` returns boxes without a `label`, and `useDetectHands` / `useDetectPose` return landmark sets (no `box`) — map those to `{ label, score, box }` before passing them in.

Examples [#examples]

Over a detection result [#over-a-detection-result]

```tsx
import { BoundingBoxOverlay, DetectionLabelLegend } from '@/components/bounding-box-overlay';
import { useDetectObjects } from '@localmode/react';

export function Example({ src }: { src: string }) {
  const imgRef = useRef<HTMLImageElement>(null);
  const { data } = useDetectObjects({ model });

  return (
    <>
      <div className="relative">
        <img ref={imgRef} src={src} alt="" className="w-full" />
        {data && (
          <BoundingBoxOverlay
            detections={data.objects}
            naturalWidth={imgRef.current?.naturalWidth ?? 0}
            naturalHeight={imgRef.current?.naturalHeight ?? 0}
          />
        )}
      </div>
      {data && <DetectionLabelLegend labels={data.objects.map((o) => o.label)} />}
    </>
  );
}
```

Boxes without label chips (dense output) [#boxes-without-label-chips-dense-output]

```tsx
// `detections` is already shaped as { label, score, box }[]
<BoundingBoxOverlay detections={detections} naturalWidth={w} naturalHeight={h} hideLabels />
```

Customization [#customization]

Colors come from Tailwind palette classes in the internal `COLOR_SLOTS` array — edit them in the copied `bounding-box-overlay.tsx` to match your design system; the legend reads the same map so the two stay in sync. The overlay is non-interactive (`pointer-events-none`) and fills its `relative` parent.

# Image Processing Overlay

Image Processing Overlay [#image-processing-overlay]

The **Image Processing Overlay*&#x2A; is a full-bleed overlay shown over a dimmed source image while vision inference runs: a spinner ring + centered icon, a status headline + optional sub-line, and an optional cancel link. A &#x2A;*`scan`** variant adds an animated scan-line sweep + scan-grid. It renders **nothing** when not processing — the element is absent from the DOM, not merely hidden.

Drive it with any vision hook's `isLoading` and wire the cancel link to the hook's `cancel` to abort the in-flight operation.

**When to use it:** over the source image of any model that takes a moment — detection, segmentation, OCR, captioning — to show progress without blocking the page.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/media-vision/image-processing-overlay`

Full source: https://localmode.ai/r/ui/media-vision/image-processing-overlay.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/media-vision/image-processing-overlay
```

Dependencies [#dependencies]

* **Data source:** driven purely by the `processing` boolean and the `onCancel` callback you pass — works with any backend's loading/cancel state. Recommended LocalMode producers: any vision hook's `isLoading` + `cancel` — `useDetectObjects` / `useSegmentImage` / `useCaptionImage` / `useImageToImage` from `@localmode/react` (optional).

* `lucide-react` — icons

* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `image-processing-overlay.tsx` — the component (scan keyframes shipped inline)
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**ImageProcessingOverlay**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `processing` | `boolean` | — | **Required.** Whether inference is running. When `false`, the overlay renders nothing (the element is absent from the DOM). Wire this to a vision hook's `isLoading` / `isProcessing`. |
| `status` | `string` | `"Processing image…"` | Headline status text. |
| `detail` | `string` | — | Optional sub-line under the status (e.g. model name or progress). |
| `variant` | `"scan" \| "spinner"` | `"spinner"` | Visual variant. `"spinner"` shows a spinner ring + icon; `"scan"` adds an animated scan-line/scan-grid sweep over the source. |
| `icon` | `ReactNode` | `a scan-line icon` | Icon rendered inside the spinner ring. |
| `onCancel` | `function` | — | When provided, render a "Cancel" link that calls this — wire it to the hook's `cancel` to abort the in-flight operation. |
| `cancelLabel` | `string` | `"Cancel"` | Cancel link label. |

Backing hooks [#backing-hooks]

Any vision hook from [`@localmode/react`](https://localmode.dev/docs/react) exposes `isLoading` and `cancel` — `useDetectObjects`, `useSegmentImage`, `useCaptionImage`, `useImageToImage`, … Pass `isLoading` to `processing` and `cancel` to `onCancel`.

Examples [#examples]

Over a dimmed image [#over-a-dimmed-image]

```tsx
import { ImageProcessingOverlay } from '@/components/image-processing-overlay';
import { useDetectObjects } from '@localmode/react';

export function Example({ src }: { src: string }) {
  const { isLoading, cancel } = useDetectObjects({ model });

  return (
    <div className="relative">
      <img src={src} alt="" className={isLoading ? 'opacity-50' : ''} />
      <ImageProcessingOverlay
        processing={isLoading}
        status="Detecting objects…"
        onCancel={cancel}
      />
    </div>
  );
}
```

Scan variant [#scan-variant]

```tsx
<ImageProcessingOverlay processing={isLoading} variant="scan" status="Scanning document…" />
```

Customization [#customization]

The scan-line/scan-grid keyframes are shipped inline (a scoped `<style>`), so the overlay animates standalone after `shadcn add` with no global CSS. Swap the icon via the `icon` prop, restyle the spinner ring, or tune the scan animation directly in the copied `image-processing-overlay.tsx`. The overlay inherits `rounded-[inherit]` from its container.

# Image Result Gallery

Image Result Gallery [#image-result-gallery]

The **Image Result Gallery** is a responsive grid/list of image result cards. Each card shows the image in an aspect container, an in-flight processing overlay, a **persistent metadata caption** (filename + category badge + a confidence score badge) that stays visible at rest on every viewport — scannable without a hover, so it is keyboard-, touch- and AT-reachable — a multi-select checkbox, and a delete affordance, with a staggered fade-in. Grid and list layouts share **one data contract** (`ImageResultCard`), so apps switch layout without reshaping data.

Per-card scores render through a self-contained fallback score badge so this component installs and builds on its own. Its color tiers are configurable via the `scoreThresholds` prop — pass CLIP-scaled breakpoints (e.g. `{ high: 0.35, medium: 0.2 }`) so cross-modal similarity scores (which land in \~0.15–0.35) aren't misread as red "low" failures. It also declares the richer [`ConfidenceScoreBadge`](/docs/results/confidence-score-badge) (Results family) as a registry dependency — when that is installed you can swap the internal badge for it.

**When to use it:** smart galleries, duplicate finders, product search, batch image classification/captioning — anywhere you display a set of image results with scores and selection.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/media-vision/image-result-gallery`

Full source: https://localmode.ai/r/ui/media-vision/image-result-gallery.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/media-vision/image-result-gallery
```

Dependencies [#dependencies]

* **Data source:** renders the `ImageResultCard[]` you pass — works with any backend that yields image results. Recommended LocalMode producers: `useClassifyImageZeroShot` (label + score), `useEmbedImage` (similarity results), or `useCaptionImage` (caption as the label) from `@localmode/react` (optional).

* `lucide-react` — icons

* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Registry dependencies [#registry-dependencies]

* `@localmode/ui/results/confidence-score-badge` — pulled in on install for the richer score badge (a minimal fallback is inlined so the gallery works standalone)

Files installed [#files-installed]

* `image-result-gallery.tsx` — the component (fade-in keyframes shipped inline)
* `confidence-score-badge.tsx` — the richer score badge (pulled in as a registry dependency)
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**ImageResultGallery**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `cards` | `array` | — | **Required.** The cards to render. |
| `layout` | `"list" \| "grid"` | `"grid"` | Layout. |
| `selectedIds` | `array` | — | Currently-selected card ids (controlled multi-select). |
| `scoreThresholds` | `object` | `{ high: 0.8, medium: 0.5 }` | Score-tier breakpoints for the per-card badge color. The default suits softmax probabilities (0–1); override it for compressed score ranges such as cross-modal CLIP similarity (~0.15–0.35). |
| `onSelect` | `function` | — | Called with a card id when its selection checkbox is toggled. |
| `onDelete` | `function` | — | Called with a card id when its delete affordance is clicked. |

**ImageResultCard**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` | — | **Required.** Stable identifier (used as the React key + selection/delete handle). |
| `src` | `string` | — | **Required.** Image source (data URL or URL). |
| `label` | `string` | — | Primary label/caption (e.g. top class, generated caption). |
| `category` | `string` | — | Secondary category/tag shown in the card metadata. |
| `score` | `number` | — | Confidence score in `[0, 1]`. When set, a score badge is shown. |
| `processing` | `boolean` | — | When true, render the per-card in-flight processing overlay. |

**ScoreThresholds**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `high` | `number` | `0.8` | Scores at or above this render as the high (emerald) tier. |
| `medium` | `number` | `0.5` | Scores at or above this (but below `high`) render as the medium (amber) tier. |

Backing hooks [#backing-hooks]

Build the cards from `useClassifyImageZeroShot` (label + score), `useEmbedImage` (similarity results), or `useCaptionImage` (caption as the label) from [`@localmode/react`](https://localmode.dev/docs/react).

Examples [#examples]

Grid with selection and delete [#grid-with-selection-and-delete]

```tsx
import { ImageResultGallery, type ImageResultCard } from '@/components/image-result-gallery';

export function Example({ cards }: { cards: ImageResultCard[] }) {
  const [selected, setSelected] = useState<string[]>([]);

  return (
    <ImageResultGallery
      cards={cards}
      layout="grid"
      selectedIds={selected}
      onSelect={(id, on) =>
        setSelected((prev) => (on ? [...prev, id] : prev.filter((x) => x !== id)))
      }
      onDelete={(id) => remove(id)}
    />
  );
}
```

List layout, same data [#list-layout-same-data]

```tsx
<ImageResultGallery cards={cards} layout="list" />
```

CLIP-scale similarity scores [#clip-scale-similarity-scores]

Cross-modal (text→image / image→image) CLIP similarity scores compress into roughly `0.15–0.35`. Pass tuned `scoreThresholds` so the strongest matches read as high/medium instead of a red "low" badge:

```tsx
<ImageResultGallery
  cards={searchResults}
  layout="grid"
  scoreThresholds={{ high: 0.35, medium: 0.2 }}
/>
```

From classification results [#from-classification-results]

```tsx
const { data } = useClassifyImageZeroShot({ model });

const cards: ImageResultCard[] = images.map((img) => ({
  id: img.id,
  src: img.src,
  label: img.top?.label,
  score: img.top?.score,
  processing: img.pending,
}));
```

Customization [#customization]

The staggered fade-in keyframes are shipped inline, so the gallery animates standalone after `shadcn add`. Adjust the grid column counts, the persistent caption gradient, or the score tiers (per-instance via `scoreThresholds`, or globally by editing the `ScoreBadge` tones) in the copied `image-result-gallery.tsx`. To use the full Results-family badge, install `@localmode/ui/results/confidence-score-badge` and replace the internal `ScoreBadge`.

Accessibility [#accessibility]

The metadata caption (filename + category + score) is **persistent** — it stays visible at rest on every viewport rather than appearing only on hover, so it is reachable by keyboard, touch, and assistive tech without a pointer. Each card `<img>` carries intrinsic `width` / `height` plus `loading="lazy"` and `decoding="async"`, so the grid reserves its aspect box up front (no cumulative layout shift as thumbnails decode). Score badges are colored by the `scoreThresholds` bands, so a low CLIP-scale similarity isn't misread as a red failure — pass CLIP-tuned breakpoints for cross-modal galleries.

# Media Dropzone

Media Dropzone [#media-dropzone]

The **Media Dropzone*&#x2A; is a drag-and-drop + click-to-browse upload zone for image/media files. It renders an idle state (icon + title + subtitle + accepted-formats hint), a drag-over state (highlight + tint + scale), and a processing state (spinner + label overlay), plus a compact &#x2A;*"add another"** variant for adding more files once some exist.

Files are validated with the copy-owned `validateFile` helper (from `@localmode/ui/lib/browser-utils`, installed automatically) against the `accept` list and `maxSize`; valid files are emitted via `onFiles(File[])` and rejected files via `onReject`. It is portable and presentational — no `@localmode/react` runtime requirement — so wire `processing` to any loading state and read the emitted files yourself.

**When to use it:** any image-AI surface — background removal, object detection, OCR, captioning, smart galleries — that takes an image from the user. It replaces the hand-rolled dropzone duplicated across many vision apps. For format-agnostic document uploads (PDF/CSV/JSON, no preview), use `FileDropzone` from the Data & Documents family instead.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/media-vision/media-dropzone`

Full source: https://localmode.ai/r/ui/media-vision/media-dropzone.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/media-vision/media-dropzone
```

Dependencies [#dependencies]

* **Data source:** validates files locally and emits them via `onFiles` / `onReject` — works with any backend; pass the emitted `File`s to whatever vision pipeline you use. Recommended LocalMode producers: any vision hook (`useDetectObjects` / `useSegmentImage` / `useCaptionImage`, …) from `@localmode/react` (optional).

* `@localmode/ui/lib/browser-utils` — the copy-owned `validateFile` helper (installed automatically as a registry dependency)

* `lucide-react` — icons

* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `media-dropzone.tsx` — the component
* `lib/browser-utils.ts` — the copy-owned file helpers (if not already present)
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**MediaDropzone**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onFiles` | `function` | — | **Required.** Called with the files that pass the accept-list + max-size validation. Always receives only valid files. |
| `onReject` | `function` | — | Called with files that fail validation, paired with the reason. Optional — use it to surface an inline error. |
| `accept` | `array` | `["image/png","image/jpeg","image/webp","image/gif"]` | Accepted MIME types, e.g. `['image/png', 'image/jpeg', 'image/webp']`. When omitted, any file type is accepted. |
| `maxSize` | `number` | `10000000` | Maximum file size in bytes. When omitted, no size limit is enforced. |
| `multiple` | `boolean` | `true` | Allow selecting / dropping more than one file at a time. |
| `processing` | `boolean` | `false` | When true, render a spinner + label overlay (e.g. while a model processes the dropped image). The zone stops accepting input while processing. |
| `processingLabel` | `string` | `"Processing…"` | Label shown while `processing` is true. |
| `addAnother` | `boolean` | `false` | When true, render the compact "add another" variant — a short, inline tile instead of the full hero zone. Use it once images already exist. |
| `title` | `string` | `"Drop an image here"` | Title shown in the idle state. |
| `subtitle` | `string` | `"or click to browse"` | Subtitle shown in the idle state. |
| `disabled` | `boolean` | `false` | Disable all interaction. |

Backing hooks [#backing-hooks]

Turn the emitted `File`s into data URLs with the copy-owned `readFileAsDataUrl` helper (from `@localmode/ui/lib/browser-utils`, installed automatically with this component) and pass them to any vision hook (`useDetectObjects`, `useSegmentImage`, `useCaptionImage`, … from `@localmode/react`, or your own backend).

Examples [#examples]

Basic [#basic]

```tsx
import { MediaDropzone } from '@/components/media-dropzone';
import { readFileAsDataUrl } from '@/lib/browser-utils';

export function Example() {
  return (
    <MediaDropzone
      accept={['image/png', 'image/jpeg']}
      maxSize={5_000_000}
      onFiles={async (files) => {
        const dataUrl = await readFileAsDataUrl(files[0]);
        // pass dataUrl to a vision hook…
      }}
    />
  );
}
```

Add-another variant [#add-another-variant]

```tsx
<MediaDropzone addAnother onFiles={(files) => append(files)} />
```

Processing state [#processing-state]

```tsx
const { isLoading } = useDetectObjects({ model });

<MediaDropzone processing={isLoading} processingLabel="Detecting…" onFiles={handleFiles} />
```

Customization [#customization]

The zone is styled with shadcn/ui CSS-variable utilities (`border-border`, `bg-card`, `bg-primary`, `text-muted-foreground`), so it inherits your theme. Because you own the file, adjust the `accept` default, swap the `UploadCloud` / `ImagePlus` icons, or restyle the drag-over highlight directly in the copied `media-dropzone.tsx`.

# useWebcam

useWebcam [#usewebcam]

`useWebcam` is a React hook that owns a `getUserMedia` video stream. `start()`
acquires the camera (or re-acquires after a denial — the retry path), `stop()`
releases every track, and unmount cleanup guarantees the camera light goes off
with the surface. A runtime permission denial surfaces as a recoverable `error`
(`permission` / `hardware` / `unknown`) rather than a thrown exception, so you can
render a retry action.

It returns `{ stream, isActive, error, start, stop, clearError }` and exports the
`WebcamError` / `WebcamErrorKind` types. It imports only React and browser APIs —
no dependencies, no `@localmode/*`.

> **Pairs with [Video Canvas](/docs/media-vision/video-canvas).** The Video Canvas
> is deliberately a shell ("the app owns acquisition + permissions"); this hook
> owns acquisition. Feed the returned `stream` into your `<video>` and drive an
> overlay from a vision model.

**When to use it:** any webcam-driven surface — object detection on a still, live
landmark/skeleton tracking, or a camera preview — where you want a small,
portable acquisition lifecycle with honest error handling.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/media-vision/use-webcam`

Full source: https://localmode.ai/r/ui/media-vision/use-webcam.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/media-vision/use-webcam
```

The hook installs to `hooks/use-webcam.ts` (the `registry:hook` install target).

Dependencies [#dependencies]

* **Data source:** none — it reads `navigator.mediaDevices.getUserMedia` directly. Works in any React app in a secure context.
* No npm or registry dependencies.

Files installed [#files-installed]

* `hooks/use-webcam.ts` — the hook

API [#api]

**UseWebcamOptions**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `width` | `number` | `1280` | Ideal capture width in pixels. |
| `height` | `number` | `720` | Ideal capture height in pixels. |

**WebcamError**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `kind` | `WebcamErrorKind` | — | **Required.** |
| `message` | `string` | — | **Required.** |

Examples [#examples]

Acquire and render a preview [#acquire-and-render-a-preview]

```tsx
import { useEffect, useRef } from 'react';
import { useWebcam } from '@/hooks/use-webcam';

export function CameraPreview() {
  const { stream, isActive, error, start, stop, clearError } = useWebcam({ width: 640 });
  const videoRef = useRef<HTMLVideoElement | null>(null);
  useEffect(() => {
    if (videoRef.current) videoRef.current.srcObject = stream;
  }, [stream]);

  return (
    <div>
      <button onClick={() => start()} disabled={isActive}>Start</button>
      <button onClick={stop} disabled={!isActive}>Stop</button>
      {error && (
        <p role="alert">
          {error.message} <button onClick={clearError}>Dismiss</button>
        </p>
      )}
      <video ref={videoRef} autoPlay muted playsInline />
    </div>
  );
}
```

Retry after a permission denial [#retry-after-a-permission-denial]

Because `start()` re-acquires, wiring the error's retry to `start()` is enough:

```tsx
{error?.kind === 'permission' && <button onClick={() => start()}>Retry</button>}
```

Customization [#customization]

The hook maps `NotAllowedError` / `SecurityError` to `permission`,
`NotFoundError` / `NotReadableError` / `OverconstrainedError` to `hardware`, and
everything else to `unknown`. Because you own the copied file, change the
constraints (resolution, `facingMode`), the error copy, or add audio capture.

# Video Canvas

Video Canvas [#video-canvas]

The **Video Canvas** is a mirrored 16:9 webcam surface: a `<video>` element with a **pixel-aligned transparent `<canvas>` overlay** for drawing landmark/skeleton annotations, an absolutely-positioned FPS-counter badge, and a child slot for status/badges. The canvas is kept sized to the video's intrinsic resolution, so the coordinates a tracker returns map 1:1 onto it; both layers share the same mirror transform, so the overlay stays aligned.

It is a **shell, not an acquisition engine** — the consuming app supplies the `stream` (`getUserMedia`) and wires a MediaPipe streaming tracker (`createHandTracker` / `createPoseTracker` / `createFaceTracker` / `createGestureTracker` from `@localmode/mediapipe`) via the experimental [`useStreamingTracker`](https://localmode.dev/docs/react) hook. The trackers own their own video frame loop — the app just draws each `results` batch onto the exposed canvas. This keeps the primitive presentational and free of device-permission logic.

**When to use it:** real-time hand/pose/face tracking, gesture recognition, any live-webcam annotation UI (MediaPipe Studio-style apps).

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/media-vision/video-canvas`

Full source: https://localmode.ai/r/ui/media-vision/video-canvas.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/media-vision/video-canvas
```

Dependencies [#dependencies]

* **Data source:** a presentational shell — you supply the `stream` (`getUserMedia`) and draw each tracker batch onto the exposed `<canvas>`; works with any frame source. Recommended LocalMode producer: the experimental `useStreamingTracker` from `@localmode/react` wired to a `@localmode/mediapipe` `create*Tracker` factory (optional).

* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `video-canvas.tsx` — the component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**VideoCanvas**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `stream` | `object \| null` | — | The webcam `MediaStream` (from `getUserMedia`). When set, it is attached to the `<video>` and playback starts. The app owns acquisition + permissions. |
| `onCanvasReady` | `function` | — | Called once the `<canvas>` 2D context is ready and sized to the video. Use it to grab the context you draw MediaPipe streaming-tracker results onto (e.g. from `useStreamingTracker`'s `onResults`). |
| `fps` | `number` | — | Measured frames-per-second to show in the badge. Hidden when undefined. |
| `mirrored` | `boolean` | `true` | Mirror the video + canvas horizontally (selfie view). Most webcam UIs want this. |
| `hideFps` | `boolean` | `false` | Hide the FPS badge even when `fps` is provided. |
| `children` | `ReactNode` | — | Status/badge content rendered in an absolutely-positioned slot over the video (e.g. a recognized-gesture chip). Not mirrored. |

Backing hooks [#backing-hooks]

Wire the experimental [`useStreamingTracker`](https://localmode.dev/docs/react) hook from `@localmode/react` to a `@localmode/mediapipe` streaming tracker factory (`createHandTracker`, `createPoseTracker`, `createFaceTracker`, `createGestureTracker`) running against the exposed `<video>` (`ref.current.video`). The tracker owns its own frame loop; the hook surfaces `{ status, results, fps, start, stop }` — draw each `results` batch onto the exposed `<canvas>` (`ref.current.canvas`) and feed `fps` to the badge. (The single-shot `useDetectHands` / `useDetectPose` / `useDetectFace` / `useRecognizeGesture` hooks are for still images, not the live loop.)

Examples [#examples]

Wire a webcam stream and tracker [#wire-a-webcam-stream-and-tracker]

```tsx
import { VideoCanvas, type VideoCanvasHandle } from '@/components/video-canvas';
import { useStreamingTracker } from '@localmode/react';
import { createHandTracker } from '@localmode/mediapipe';

export function Example() {
  const ref = useRef<VideoCanvasHandle>(null);
  const [stream, setStream] = useState<MediaStream | null>(null);

  const { results, fps, start } = useStreamingTracker({
    video: () => ref.current?.video ?? null,
    create: ({ video, onResults, onError }) =>
      createHandTracker({ video, onResults, onError }),
    onResults: (hands) => {
      const ctx = ref.current?.canvas?.getContext('2d');
      if (ctx) drawHandLandmarks(ctx, hands); // your draw helper
    },
  });

  useEffect(() => {
    navigator.mediaDevices.getUserMedia({ video: true }).then((s) => {
      setStream(s);
      start(); // tracker owns the frame loop from here
    });
  }, []);

  return (
    <VideoCanvas ref={ref} stream={stream} fps={fps}>
      <span className="rounded-full bg-emerald-500/90 px-2.5 py-1 text-xs text-white">
        ✋ Open palm
      </span>
    </VideoCanvas>
  );
}
```

`useStreamingTracker` is experimental: it creates the tracker lazily on the first `start()`, reuses it across start/stop cycles (the model stays warm), measures `fps` over a one-second window, and disposes the tracker on unmount.

Customization [#customization]

The component owns only the video/canvas composition, the mirror transform, and the FPS badge. Set `mirrored={false}` for non-selfie views, hide the badge with `hideFps`, and restyle the 16:9 shell in the copied `video-canvas.tsx`. You retain full control over acquisition and the draw loop.

> **Real-hardware dependency:** the live preview here uses a simulated marker. A real webcam stream requires `getUserMedia` and a user permission grant in the browser — wire that in your app.

# Confidence Score Badge

Confidence Score Badge [#confidence-score-badge]

The **Confidence Score Badge** is the shared scored-output atom across LocalMode Elements. It maps a 0–1 score to a semantic color tier — by default high ≥ 0.8 (success), medium ≥ 0.5 (warning), and low (muted) — and renders the formatted percentage as either a flat pill badge or a radial dial. The tier breakpoints are props, so apps with cosine vs dot-product score distributions can tune them.

**When to use it:** anywhere you surface a scalar confidence or similarity score — `useClassify`, `useClassifyZeroShot`, `useSemanticSearch`, `useAnswerQuestion`. It is also consumed cross-family (e.g. by `ScoredResultBarList`, `TopResultCard`, and media-vision's `ImageResultGallery`).

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/results/confidence-score-badge`

Full source: https://localmode.ai/r/ui/results/confidence-score-badge.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/results/confidence-score-badge
```

Dependencies [#dependencies]

* **Data source:** renders a single `score` (0–1) and optional `label` you pass — works with any backend. Recommended producers: `useClassify` / `useSemanticSearch` / `useAnswerQuestion` from `@localmode/react` (optional). See [Bring your own data](/docs/bring-your-own-data#results--insights).

* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `confidence-score-badge.tsx` — the component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**ConfidenceScoreBadge**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `score` | `number` | — | **Required.** Confidence/similarity score in the inclusive range 0–1. |
| `variant` | `"radial" \| "flat"` | `"flat"` | Render style. `flat` is a pill badge; `radial` is a circular dial that fills proportionally to the score. |
| `thresholds` | `object` | `{ high: 0.8, medium: 0.5 }` | Tier breakpoints. Tune these for distributions that differ from the default (e.g. dot-product vs cosine similarity). |
| `label` | `string` | — | Optional label rendered before the percentage in the flat variant (e.g. the predicted class name). |
| `size` | `number` | `56` | Diameter of the radial dial in pixels. Ignored by the flat variant. |
| `precision` | `number` | `0` | Number of fraction digits in the rendered percentage. |

Examples [#examples]

Flat badge with a label [#flat-badge-with-a-label]

```tsx
import { ConfidenceScoreBadge } from '@/components/confidence-score-badge';

export function Example() {
  return <ConfidenceScoreBadge score={0.92} label="positive" />;
}
```

Radial dial [#radial-dial]

```tsx
<ConfidenceScoreBadge score={0.63} variant="radial" size={64} />
```

Custom thresholds (tighter cosine distribution) [#custom-thresholds-tighter-cosine-distribution]

```tsx
<ConfidenceScoreBadge score={0.72} thresholds={{ high: 0.65, medium: 0.4 }} />
```

Customization [#customization]

The component is styled with shadcn/ui CSS-variable tokens (`bg-card`, `text-card-foreground`). The radial dial's fill uses a `conic-gradient` driven by CSS variables so it themes via the consumer's tokens. The per-tier colors map to Tailwind's `emerald` / `amber` palettes with a muted fallback — swap them in the copied `TIER_STYLES` map to match your design system. The exported `resolveTier()` helper lets you reuse the exact tiering logic for your own styling.

# Cosine Similarity Meter

Cosine Similarity Meter [#cosine-similarity-meter]

The **Cosine Similarity Meter** displays a cosine similarity score (0–1) as a large numeric value with a human-readable bucket label (e.g. "Very similar", "Unrelated") using configurable thresholds, plus a proportional half-ring arc gauge.

**When to use it:** when you compute the cosine similarity of two embeddings yourself (from `useEmbed` / `useEmbedImage`) and want to present it — semantic search relevance, duplicate detection, or cross-modal matching.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/results/cosine-similarity-meter`

Full source: https://localmode.ai/r/ui/results/cosine-similarity-meter.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/results/cosine-similarity-meter
```

Dependencies [#dependencies]

* **Data source:** renders a single `similarity` (0–1) you pass — works with any backend. Recommended producer: compute cosine yourself from embeddings (e.g. via `useEmbed` / `useEmbedImage` from `@localmode/react`, optional). See [Bring your own data](/docs/bring-your-own-data#results--insights).

* `clsx` + `tailwind-merge` — via the shared `cn()` util

Files installed [#files-installed]

* `cosine-similarity-meter.tsx` — the component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**CosineSimilarityMeter**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `similarity` | `number` | — | **Required.** Cosine similarity in the inclusive range 0–1 (the raw cosine of two embeddings, typically derived from `useEmbed` / `useEmbedImage`). |
| `buckets` | `array` | `the built-in 5-bucket scale` | Ordered, descending-by-`min` bucket definitions. The first bucket whose `min` the similarity meets or exceeds wins. |
| `caption` | `ReactNode` | — | Optional caption shown beneath the bucket label. |

Examples [#examples]

From two embeddings [#from-two-embeddings]

```tsx
import { CosineSimilarityMeter } from '@/components/cosine-similarity-meter';

function cosine(a: Float32Array, b: Float32Array) {
  let dot = 0, na = 0, nb = 0;
  for (let i = 0; i < a.length; i++) { dot += a[i] * b[i]; na += a[i] ** 2; nb += b[i] ** 2; }
  return dot / (Math.sqrt(na) * Math.sqrt(nb));
}

export function Example({ queryVec, docVec }) {
  return <CosineSimilarityMeter similarity={cosine(queryVec, docVec)} caption="query ↔ document" />;
}
```

Custom buckets [#custom-buckets]

```tsx
<CosineSimilarityMeter
  similarity={0.74}
  buckets={[
    { min: 0.7, label: 'Match', color: 'var(--color-emerald-500)' },
    { min: 0, label: 'No match', color: 'var(--color-muted-foreground)' },
  ]}
/>
```

Customization [#customization]

The arc gauge is a two-path SVG semicircle; the active arc's color comes from the resolved bucket and its length from the score. Bucket colors are wired to CSS variables so the meter themes via your tokens. The exported `resolveBucket()` helper lets you reuse the exact bucketing logic elsewhere.

# Editable Label Set

Editable Label Set [#editable-label-set]

The **Editable Label Set** is an editable collection of color-cycling removable chips for managing a candidate-label list. Chips reveal a remove control; an inline input adds new labels (Enter to commit, Backspace on empty to remove the last). It is fully controlled via `labels` / `onAdd` / `onRemove`, cycling a fixed color palette by index.

**When to use it:** editing the candidate labels you feed to `useClassifyZeroShot`, or any string-tag collection.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/results/editable-label-set`

Full source: https://localmode.ai/r/ui/results/editable-label-set.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/results/editable-label-set
```

Dependencies [#dependencies]

* **Data source:** fully controlled via the `labels` / `onAdd` / `onRemove` props you wire — works with any backend or local state. Recommended consumer: feed the labels to `useClassifyZeroShot` from `@localmode/react` (optional). See [Bring your own data](/docs/bring-your-own-data#results--insights).

* `lucide-react` — the remove (×) icon

* `clsx` + `tailwind-merge` — via the shared `cn()` util

Files installed [#files-installed]

* `editable-label-set.tsx` — the component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**EditableLabelSet**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `labels` | `array` | — | **Required.** The controlled list of labels. |
| `onAdd` | `function` | — | **Required.** Invoked with the trimmed new label when the user adds one. |
| `onRemove` | `function` | — | **Required.** Invoked with the label (and its index) when the user removes a chip. |
| `placeholder` | `string` | `"Add a label…"` | Placeholder for the inline add input. |
| `palette` | `array` | — | Color palette cycled by chip index. Each entry is a CSS color (defaults are wired to CSS variables so chips theme via the consumer's tokens). |
| `maxLabels` | `number` | — | Disable adding when the count reaches this limit. |

Examples [#examples]

Feeding zero-shot candidate labels [#feeding-zero-shot-candidate-labels]

```tsx
import { useState } from 'react';
import { EditableLabelSet } from '@/components/editable-label-set';
import { useClassifyZeroShot } from '@localmode/react';

export function Example({ model }) {
  const [labels, setLabels] = useState(['positive', 'negative', 'neutral']);
  const { execute } = useClassifyZeroShot({ model });

  return (
    <EditableLabelSet
      labels={labels}
      onAdd={(l) => setLabels((p) => [...p, l])}
      onRemove={(_, i) => setLabels((p) => p.filter((__, j) => j !== i))}
    />
  );
}
```

Cap the number of labels [#cap-the-number-of-labels]

```tsx
<EditableLabelSet labels={labels} onAdd={add} onRemove={remove} maxLabels={6} />
```

Customization [#customization]

Chips use a CSS-variable color palette cycled by index — pass your own `palette` to match your design system. Each chip carries its hue on the dot, border, and a subtle background tint, while the &#x2A;*label text stays `text-foreground`** so it clears WCAG AA (4.5:1) in both light and dark themes regardless of the palette hue. The container and input use shadcn/ui tokens (`bg-card`, `border-border`, `text-foreground`). Because the set is fully controlled, dedup and validation live in your `onAdd` handler.

# Entity Relationship Graph

Entity Relationship Graph [#entity-relationship-graph]

The **Entity Relationship Graph** is an interactive force-directed graph of typed nodes and relationship-labeled edges, supporting drag, zoom, pan, hover, click, and SVG/PNG export. The layout runs entirely client-side over local data using a lightweight in-component force simulation (no `d3-force` or other heavy dependency).

**When to use it:** visualizing VectorDB entity relationships, agent-memory connections, embedding clusters, or `useExtractEntities` (NER) co-occurrences — all from local data, with no network calls.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/results/entity-relationship-graph`

Full source: https://localmode.ai/r/ui/results/entity-relationship-graph.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/results/entity-relationship-graph
```

Dependencies [#dependencies]

* **Data source:** renders the `nodes` / `edges` arrays you pass — works with any backend. Recommended producer: `useExtractEntities` (NER co-occurrences) from `@localmode/react` (optional). See [Bring your own data](/docs/bring-your-own-data#results--insights).

* `clsx` + `tailwind-merge` — via the shared `cn()` util

Files installed [#files-installed]

* `entity-relationship-graph.tsx` — the component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**EntityRelationshipGraph**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `nodes` | `array` | — | **Required.** The typed nodes. |
| `edges` | `array` | — | **Required.** The labeled edges. |
| `registry` | `NodeTypeRegistry` | `the built-in PER/LOC/ORG/MISC registry` | Per-type node colors. Types absent from the registry use a default color. |
| `height` | `number` | `420` | Canvas height in pixels. |
| `onNodeClick` | `function` | — | Invoked when a node is clicked. |
| `showExport` | `boolean` | `true` | Whether to render the SVG/PNG export toolbar. |

Examples [#examples]

From NER co-occurrences [#from-ner-co-occurrences]

```tsx
import { EntityRelationshipGraph } from '@/components/entity-relationship-graph';

export function Example() {
  const nodes = [
    { id: 'ada', label: 'Ada Lovelace', type: 'PER' },
    { id: 'london', label: 'London', type: 'LOC' },
  ];
  const edges = [{ source: 'ada', target: 'london', label: 'lived in' }];
  return <EntityRelationshipGraph nodes={nodes} edges={edges} onNodeClick={(n) => console.log(n)} />;
}
```

Customization [#customization]

Node colors come from a per-type registry (defaults wired to CSS variables); pass your own `registry` to recolor. The force simulation (`layoutGraph`, exported) is a compact repulsion + edge-spring + center-gravity loop — tune the constants in the copied file for tighter or looser layouts. SVG and PNG export serialize the live SVG entirely in-browser; no network or third-party service is involved.

# Entity Stats Bar

Entity Stats Bar [#entity-stats-bar]

The **Entity Stats Bar** shows the total detected-entity count plus a per-type breakdown badge (colored dot + count + label) for each entity type. Counts are computed internally from a `DetectedEntity[]` (or pass a pre-computed `counts` map) against a color/label registry.

**When to use it:** summarizing the output of `useExtractEntities` (NER) — entity review, PII triage, or content moderation dashboards.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/results/entity-stats-bar`

Full source: https://localmode.ai/r/ui/results/entity-stats-bar.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/results/entity-stats-bar
```

Dependencies [#dependencies]

* **Data source:** renders the `entities` array (or a pre-computed `counts` map) you pass — works with any backend. Recommended producer: `useExtractEntities` (NER) from `@localmode/react` (optional). See [Bring your own data](/docs/bring-your-own-data#results--insights).

* `clsx` + `tailwind-merge` — via the shared `cn()` util

Files installed [#files-installed]

* `entity-stats-bar.tsx` — the component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**EntityStatsBar**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `entities` | `array` | — | The detected entities to count. Either pass `entities` (counts are computed internally) or a pre-computed `counts` map. |
| `counts` | `Record<string, number>` | — | Pre-computed per-type counts, as an alternative to `entities`. |
| `registry` | `EntityTypeRegistry` | `the built-in PER/LOC/ORG/MISC registry` | Per-type display config. Types absent from the registry still render with a default color. |
| `hideEmpty` | `boolean` | `true` | Whether to hide types with a zero count. |
| `itemNoun` | `string` | `"entity"` | Singular noun for the counted items, shown before the breakdown (e.g. "6 entities"). Non-NER consumers pass their own noun — e.g. `"result"` renders "6 results" / "1 result". The plural is derived automatically. |
| `itemNounPlural` | `string` | `pluralize(itemNoun)` | Plural form of {@link itemNoun}. Defaults to a regular English pluralization of `itemNoun` ("entity" → "entities", "result" → "results"); pass this only for irregular plurals. |

Examples [#examples]

From extracted entities [#from-extracted-entities]

```tsx
import { EntityStatsBar } from '@/components/entity-stats-bar';
import { useExtractEntities } from '@localmode/react';

export function Example({ model, text }) {
  const { data, execute } = useExtractEntities({ model });
  // Call execute(text) to run NER; `data` holds the result.
  return (
    <>
      <button onClick={() => execute(text)}>Extract</button>
      <EntityStatsBar entities={data?.entities ?? []} />
    </>
  );
}
```

Custom type registry [#custom-type-registry]

```tsx
<EntityStatsBar
  entities={entities}
  registry={{
    EMAIL: { label: 'Email', color: 'var(--color-rose-500)' },
    PHONE: { label: 'Phone', color: 'var(--color-sky-500)' },
  }}
/>
```

Non-NER labels (`itemNoun`) [#non-ner-labels-itemnoun]

The total defaults to the NER-flavored noun ("6 entities" / "1 entity"). Non-NER consumers — sentiment tallies, classification routes, dedupe groups — relabel it with `itemNoun`; the plural is derived automatically ("result" → "results"). Pass `itemNounPlural` only for irregular plurals.

```tsx
<EntityStatsBar
  counts={{ POSITIVE: 3, NEGATIVE: 3 }}
  registry={{
    POSITIVE: { label: 'Positive', color: 'var(--color-emerald-500)' },
    NEGATIVE: { label: 'Negative', color: 'var(--color-rose-500)' },
  }}
  itemNoun="result" // renders "6 results" / "1 result"
/>
```

Customization [#customization]

Each per-type badge takes its color from the registry (defaults wired to CSS variables) and falls back to a muted color for unregistered types. The container uses `bg-card` / `border-border`. Pass `hideEmpty={false}` to always show every registered type, even at a count of zero. Set `itemNoun` (and, for irregular plurals, `itemNounPlural`) to relabel the total for non-NER use. The exported `countByType()` helper computes the tally if you need it elsewhere.

# Error Alert

Error Alert [#error-alert]

The **Error Alert** is a compact, dismissible error surface with an optional
retry action. It renders a `role="alert"` region with the message, a **Retry**
button (shown only when you pass `onRetry`), and a dismiss control. It is the
single, deduplicated alert used across blocks for operation feedback.

> **Presentational.** The alert owns no operation state — you decide what retry
> and dismiss do. Wire it to any hook that surfaces an error string (e.g.
> `useGenerateText`, `useClassify`, `useTranslate` — a recommendation, never a
> requirement).

**When to use it:** any place a local operation can fail and the user should be
able to retry or dismiss the message inline, near the affected result.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/results/error-alert`

Full source: https://localmode.ai/r/ui/results/error-alert.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/results/error-alert
```

Dependencies [#dependencies]

* **Data source:** renders the `message` you pass and emits `onRetry` / `onDismiss` — works with any backend. Recommended LocalMode source: any hook's `error` string (optional).
* `lucide-react` — the alert / retry / dismiss icons
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `error-alert.tsx` — the component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**ErrorAlert**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `message` | `string` | — | **Required.** The error message to display. |
| `onRetry` | `function` | — | Optional retry handler — the Retry button renders only when provided. |
| `onDismiss` | `function` | — | **Required.** Dismiss the alert. |

Examples [#examples]

Retryable operation feedback [#retryable-operation-feedback]

```tsx
import { ErrorAlert } from '@/components/error-alert';

export function Result({ error, run, clear }) {
  if (!error) return null;
  return <ErrorAlert message={error} onRetry={run} onDismiss={clear} />;
}
```

Dismiss-only (no retry) [#dismiss-only-no-retry]

Omit `onRetry` and the Retry button is not rendered:

```tsx
<ErrorAlert message={error} onDismiss={() => setError(null)} />
```

Customization [#customization]

The alert uses `destructive` token utilities so it inherits your theme's error
color. Because you own the copied file, the layout, icon, and button styling are
all yours to change — swap the icons, add an error-code line, or wrap the message
in a `<pre>` for stack traces.

# Evaluation Metrics Dashboard

Evaluation Metrics Dashboard [#evaluation-metrics-dashboard]

The **Evaluation Metrics Dashboard** composes the displays that co-occur in a model-evaluation flow: a labeled KPI/stat-tile row (value + delta indicator), a responsive grid of metric cards (accuracy / precision / recall / F1), a color-coded N×N confusion matrix (diagonal success-tinted, off-diagonal error-tinted, intensity scaled to the max cell, with legend), a radar/spider sub-view, and a threshold-calibration panel. Every chart is a minimal in-component SVG implementation — no external chart library.

**When to use it:** rendering the output of `useEvaluateModel` together with `useCalibrateThreshold`. Each section is optional; pass only the data you have.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/results/evaluation-metrics-dashboard`

Full source: https://localmode.ai/r/ui/results/evaluation-metrics-dashboard.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/results/evaluation-metrics-dashboard
```

Dependencies [#dependencies]

* **Data source:** renders the `stats` / `metrics` / `confusionMatrix` / `calibration` props you pass (each section optional) — works with any backend. Recommended producers: `useEvaluateModel` and `useCalibrateThreshold` from `@localmode/react` (optional). See [Bring your own data](/docs/bring-your-own-data#results--insights).

* `clsx` + `tailwind-merge` — via the shared `cn()` util

Files installed [#files-installed]

* `evaluation-metrics-dashboard.tsx` — the component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**EvaluationMetricsDashboard**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `stats` | `array` | — | KPI stat-tile row (value + delta). |
| `metrics` | `array` | — | Metric cards (accuracy / precision / recall / F1, etc.). |
| `confusionMatrix` | `object` | — | Confusion matrix (color-scaled, with legend). |
| `radarMetrics` | `array` | — | Metrics to plot on the radar/spider sub-view. Defaults to the `metrics` array when omitted; pass an empty array to hide the radar. |
| `calibration` | `object` | — | Threshold-calibration panel data. |

Examples [#examples]

From an evaluation run [#from-an-evaluation-run]

`useEvaluateModel` returns `{ score, predictions, datasetSize, durationMs }` — one metric. Compose the rest from the `@localmode/core` evaluation helpers (`f1Score`, `confusionMatrix`, which returns `{ labels, matrix }`) over the same `predictions` and the expected labels.

```tsx
import { EvaluationMetricsDashboard } from '@/components/evaluation-metrics-dashboard';
import { f1Score, confusionMatrix } from '@localmode/core';

export function Example({ evaluation, expected, calibration }) {
  const cm = confusionMatrix(evaluation.predictions, expected);
  return (
    <EvaluationMetricsDashboard
      stats={[
        { label: 'Dataset', value: evaluation.datasetSize },
        { label: 'Duration', value: `${(evaluation.durationMs / 1000).toFixed(2)}s` },
      ]}
      metrics={[
        { label: 'Accuracy', value: evaluation.score },
        { label: 'F1', value: f1Score(evaluation.predictions, expected) },
      ]}
      confusionMatrix={{ labels: cm.labels, matrix: cm.matrix }}
      calibration={{ threshold: calibration.threshold, percentile: calibration.percentile, distribution: calibration.distribution }}
    />
  );
}
```

Customization [#customization]

Cell coloring uses `color-mix` over CSS-variable tokens (`--color-emerald-500` for the diagonal, `--color-rose-500` for off-diagonal), with opacity scaled to each cell relative to the matrix max. The radar polygon fills with `color-mix(... var(--color-primary) ...)`. Everything inherits your theme; adjust the section components in the copied file to add or reorder displays.

# Mode Error Boundary

Mode Error Boundary [#mode-error-boundary]

The **Mode Error Boundary** is a React error boundary that isolates a render
failure in its subtree. When a child throws during render, it catches the error
and renders a compact recoverable `role="alert"` notice with the message and a
**Reset** button that clears the error and re-renders the children — so a single
failing surface (one tab, one result panel) cannot blank the whole page.

> **Structural utility.** It is a copy-owned class error boundary with local prop
> shapes — no backend, no model, no `@localmode/*` dependency. Wrap any subtree
> whose render could throw.

**When to use it:** around each independently-rendered result surface (a tab, a
mode, a widget) so an error in one is contained and recoverable in place.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/results/mode-error-boundary`

Full source: https://localmode.ai/r/ui/results/mode-error-boundary.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/results/mode-error-boundary
```

Dependencies [#dependencies]

* **Data source:** none — it wraps children and catches their render errors. Works in any React app.
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `mode-error-boundary.tsx` — the component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**ModeErrorBoundary**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | — | **Required.** The subtree to isolate — a render error inside it is caught and recovered. |

Examples [#examples]

Isolate a result surface [#isolate-a-result-surface]

```tsx
import { ModeErrorBoundary } from '@/components/mode-error-boundary';

export function Mode({ data }) {
  return (
    <ModeErrorBoundary>
      <ResultSurface data={data} />
    </ModeErrorBoundary>
  );
}
```

Reset on input change [#reset-on-input-change]

Give the boundary a `key` tied to the input so switching inputs remounts it
fresh, clearing any prior error:

```tsx
<ModeErrorBoundary key={activeMode}>
  <ResultSurface data={data} />
</ModeErrorBoundary>
```

Customization [#customization]

The fallback notice uses `destructive` token utilities. Because you own the
copied file, you can change the message, add error logging in
`getDerivedStateFromError` / `componentDidCatch`, or replace the Reset button
with your own recovery affordance.

# Redacted Text Display

Redacted Text Display [#redacted-text-display]

The **Redacted Text Display** renders source text with detected entities replaced inline by color-coded redaction tokens (e.g. `[PER]`, `[LOC]`), each styled per entity type and tooltipped with its type. It includes a scanning loading skeleton and an empty placeholder. Pass the original text plus the detected entity spans (with `start`/`end` offsets); segmentation happens internally.

**When to use it:** reviewing the output of `useExtractEntities` for NER, PII redaction, or content moderation.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/results/redacted-text-display`

Full source: https://localmode.ai/r/ui/results/redacted-text-display.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/results/redacted-text-display
```

Dependencies [#dependencies]

* **Data source:** renders the `text` plus `entities` spans you pass — works with any backend. Recommended producer: `useExtractEntities` (NER) from `@localmode/react` (optional). See [Bring your own data](/docs/bring-your-own-data#results--insights).

* `clsx` + `tailwind-merge` — via the shared `cn()` util

Files installed [#files-installed]

* `redacted-text-display.tsx` — the component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**RedactedTextDisplay**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `text` | `string` | — | **Required.** The original source text. |
| `entities` | `array` | — | **Required.** The detected entity spans (each with `start`/`end` offsets). |
| `registry` | `EntityTypeRegistry` | `the built-in PER/LOC/ORG/MISC registry` | Per-type display config (label + color). Types absent from the registry render with a default color. |
| `isScanning` | `boolean` | `false` | When true, render a scanning skeleton instead of text. |
| `emptyState` | `ReactNode` | `"Nothing to display"` | Rendered when there is no text. |

Examples [#examples]

From extracted entities [#from-extracted-entities]

```tsx
import { RedactedTextDisplay } from '@/components/redacted-text-display';
import { useExtractEntities } from '@localmode/react';

export function Example({ model, text }) {
  const { data, isLoading, execute } = useExtractEntities({ model });
  // Call execute(text) to run NER; `data` holds the result.
  return (
    <>
      <button onClick={() => execute(text)}>Scan</button>
      <RedactedTextDisplay
        text={text}
        entities={data?.entities ?? []}
        isScanning={isLoading}
      />
    </>
  );
}
```

Custom type colors [#custom-type-colors]

```tsx
<RedactedTextDisplay
  text={text}
  entities={entities}
  registry={{ EMAIL: { label: 'Email', color: 'var(--color-rose-500)' } }}
/>
```

Customization [#customization]

Tokens are tinted with the registry color at low opacity (`color26`) over `bg-card`, falling back to a muted color for unregistered types. Tooltips use the native `title` attribute (no extra dependency). The exported `segmentText()` helper performs the offset-based interleaving — overlapping spans are resolved by keeping the earliest — so you can reuse or test it independently.

# Scored Result Bar List

Scored Result Bar List [#scored-result-bar-list]

The **Scored Result Bar List** renders any ranked `{label, score}` output as a vertical list: each row shows the label, a formatted confidence percentage (via `ConfidenceScoreBadge`), and an animated horizontal fill bar proportional to the 0–1 score, with the top row highlighted. It ships with a skeleton-loading state and an empty-state slot so it drops straight into async hook flows.

**When to use it:** one data contract serves every ranked-output hook — `useClassify`, `useClassifyZeroShot`, `useDetectObjects`, `useFillMask`, and reranked / `useSemanticSearch` results.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/results/scored-result-bar-list`

Full source: https://localmode.ai/r/ui/results/scored-result-bar-list.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/results/scored-result-bar-list
```

Dependencies [#dependencies]

* **Data source:** renders `Array<{ label, score }>` you pass — works with any backend (classifier, search ranker, or a constant). Recommended producers: `useClassify` / `useClassifyZeroShot` / `useSemanticSearch` from `@localmode/react`. See [Bring your own data](/docs/bring-your-own-data#results--insights).

* `ConfidenceScoreBadge` — the per-row percentage badge (installed automatically as a registry dependency)

* `clsx` + `tailwind-merge` — via the shared `cn()` util

Files installed [#files-installed]

* `scored-result-bar-list.tsx` — the component
* `confidence-score-badge.tsx` — the embedded badge
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**ScoredResultBarList**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `results` | `array` | — | **Required.** The scored results to render. Any ranked-output hook fits this contract: `useClassify` / `useClassifyZeroShot` / `useDetectObjects` / `useFillMask` / `useSemanticSearch`. |
| `isLoading` | `boolean` | `false` | When true, render staggered skeleton rows instead of results. |
| `skeletonRows` | `number` | `4` | Number of skeleton rows shown while loading. |
| `highlightTop` | `boolean` | `true` | Whether to highlight the top-ranked (first) row. |
| `sort` | `boolean` | `true` | Whether to sort results by score (descending) before rendering. Set false if the input is already ranked and you want to preserve its order. |
| `limit` | `number` | — | Maximum number of rows to render after sorting. |
| `emptyState` | `ReactNode` | `"No results"` | Rendered when there are no results and the list is not loading. |

Examples [#examples]

Zero-shot classification [#zero-shot-classification]

```tsx
import { ScoredResultBarList } from '@/components/scored-result-bar-list';
import { useClassifyZeroShot } from '@localmode/react';

export function Example({ model }) {
  const { data, isLoading } = useClassifyZeroShot({ model });
  // classifyZeroShot() returns parallel `labels` / `scores` arrays.
  const results = (data?.labels ?? []).map((label, i) => ({
    label,
    score: data.scores[i],
  }));
  return <ScoredResultBarList results={results} isLoading={isLoading} />;
}
```

Limit to the top 3, preserve input order [#limit-to-the-top-3-preserve-input-order]

```tsx
<ScoredResultBarList results={detections} sort={false} limit={3} />
```

Custom empty state [#custom-empty-state]

```tsx
<ScoredResultBarList results={[]} emptyState={<span>Run a query to see results</span>} />
```

Customization [#customization]

Each row uses shadcn/ui token utilities (`bg-card`, `border-border`, `bg-primary/5` for the top row). The proportional fill bar is a positioned `<div>` whose width is the row's score relative to the max — adjust its color classes in the copied file. The per-row percentage is delegated to `ConfidenceScoreBadge`, so tier colors stay consistent with the rest of your results UI.

# Threshold Calibration Panel

Threshold Calibration Panel [#threshold-calibration-panel]

The **Threshold Calibration Panel** renders a similarity-threshold calibration result: the empirically **calibrated threshold** side-by-side with the model's **preset default** (or an explicit no-preset state), the calibration **metadata** (percentile, sample size, model ID, distance function), the pairwise similarity **distribution statistics** (mean / median / std-dev / min / max / pair count), and a **preset-thresholds reference** list with the active model highlighted. Loading and empty states carry optional calibrate / cancel affordances.

**When to use it:** surfacing the output of `useCalibrateThreshold` — tuning a semantic-search relevance threshold to your corpus, or comparing an empirical threshold against a model's known-good default.

**Relationship to [Evaluation Metrics Dashboard](/docs/results/evaluation-metrics-dashboard):** that composite ships an optional embedded calibration sub-view. This standalone panel is the full-fidelity calibration surface — it adds the preset comparison, the preset reference list, and the calibrate / cancel affordances. Use the dashboard for a combined metrics + matrix + calibration overview; use this panel when calibration is the focus.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/results/threshold-calibration-panel`

Full source: https://localmode.ai/r/ui/results/threshold-calibration-panel.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/results/threshold-calibration-panel
```

Dependencies [#dependencies]

* **Data source:** renders the `calibration` object you pass — works with any backend. Recommended producer: `useCalibrateThreshold` from `@localmode/react` (optional). See [Bring your own data](/docs/bring-your-own-data#results--insights).

* `clsx` + `tailwind-merge` — via the shared `cn()` util

Files installed [#files-installed]

* `threshold-calibration-panel.tsx` — the component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**ThresholdCalibrationPanel**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `calibration` | `object \| null` | — | **Required.** The calibration result to render, or `null` for the empty / pre-run state. Recommended producer: `useCalibrateThreshold` from `@localmode/react` — but any backend that returns this shape works. |
| `presetThreshold` | `number` | — | The selected model's preset threshold, rendered side-by-side with the calibrated value. Omit to show an explicit "no preset" state. |
| `presets` | `array` | — | A reference list of known-good preset thresholds. The entry whose `modelId` matches `calibration.modelId` is highlighted. |
| `isCalibrating` | `boolean` | — | Whether a calibration run is in progress (renders the busy state). |
| `onCalibrate` | `function` | — | Fired when the user requests a (re)calibration from the empty/idle state. |
| `onCancel` | `function` | — | Fired when the user cancels an in-flight calibration. |

Examples [#examples]

Wired to `useCalibrateThreshold` [#wired-to-usecalibratethreshold]

The panel is backend-agnostic — pass any producer of the `CalibrationResult` shape. The recommended LocalMode wiring pairs `presetThreshold` with `getDefaultThreshold(modelId)` and `presets` with `MODEL_THRESHOLD_PRESETS`:

```tsx
import { ThresholdCalibrationPanel } from '@/components/threshold-calibration-panel';
import { useCalibrateThreshold } from '@localmode/react';
import { getDefaultThreshold, MODEL_THRESHOLD_PRESETS } from '@localmode/core';

export function Example({ model, corpus }) {
  const { calibration, isCalibrating, calibrate, cancel } = useCalibrateThreshold({
    model,
    percentile: 90,
  });

  const presets = Object.entries(MODEL_THRESHOLD_PRESETS).map(([modelId, threshold]) => ({
    modelId,
    threshold,
  }));

  return (
    <ThresholdCalibrationPanel
      calibration={calibration}
      presetThreshold={getDefaultThreshold(model.modelId)}
      presets={presets}
      isCalibrating={isCalibrating}
      onCalibrate={() => calibrate(corpus)}
      onCancel={cancel}
    />
  );
}
```

Read-only result [#read-only-result]

Omit the callbacks to render the panel as a static result surface:

```tsx
<ThresholdCalibrationPanel calibration={calibration} presetThreshold={0.5} />
```

Model without a preset [#model-without-a-preset]

When `presetThreshold` is omitted, the panel shows an explicit "no preset for this model" state instead of a comparison value:

```tsx
<ThresholdCalibrationPanel calibration={calibration} />
```

Customization [#customization]

Sections render only when their data is present, so the panel adapts to read-only, busy, and empty states. The calibrated value uses `bg-primary/5` + `text-primary` to stand out from the preset; the delta caption tints amber when the calibrated threshold sits above the preset and sky when below. The preset reference highlights the entry matching `calibration.modelId` with `bg-primary/10`. All colors are shadcn/ui CSS-variable tokens, so the panel inherits the consumer's theme.

# Top Result Card

Top Result Card [#top-result-card]

The **Top Result Card** highlights the single winning classification result: a large label, a prominent confidence dial (via `ConfidenceScoreBadge`), and a tier-tinted gradient-border glow. It is designed to pair above a `ScoredResultBarList`.

**When to use it:** any single-winner output — sentiment, intent, language detection, gesture, or the top result from `useClassifyZeroShot`.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/results/top-result-card`

Full source: https://localmode.ai/r/ui/results/top-result-card.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/results/top-result-card
```

Dependencies [#dependencies]

* **Data source:** renders the `label` + `score` (0–1) you pass — works with any backend. Recommended producer: `useClassifyZeroShot` (top result) from `@localmode/react` (optional). See [Bring your own data](/docs/bring-your-own-data#results--insights).

* `ConfidenceScoreBadge` — the radial confidence dial (installed automatically as a registry dependency)

* `clsx` + `tailwind-merge` — via the shared `cn()` util

Files installed [#files-installed]

* `top-result-card.tsx` — the component
* `confidence-score-badge.tsx` — the embedded dial
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**TopResultCard**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | — | **Required.** The winning label (sentiment, intent, language, gesture, …). |
| `score` | `number` | — | **Required.** The winning confidence score in the inclusive range 0–1. |
| `title` | `string` | `"Top result"` | Short heading above the result (e.g. "Predicted sentiment"). |
| `description` | `ReactNode` | — | Optional descriptive text shown beneath the result. |
| `thresholds` | `object` | `{ high: 0.8, medium: 0.5 }` | Tier breakpoints, forwarded to the embedded confidence badge and used to tint the glow. |

Examples [#examples]

Above a result list [#above-a-result-list]

```tsx
import { TopResultCard } from '@/components/top-result-card';
import { ScoredResultBarList } from '@/components/scored-result-bar-list';

export function Example({ results }) {
  const [top, ...rest] = [...results].sort((a, b) => b.score - a.score);
  return (
    <div className="space-y-4">
      {top && <TopResultCard title="Sentiment" label={top.label} score={top.score} />}
      <ScoredResultBarList results={rest} highlightTop={false} />
    </div>
  );
}
```

Customization [#customization]

The glow tint is derived from the score's confidence tier and applied via `box-shadow` plus a blurred radial accent, both wired to CSS variables. The card itself uses `bg-card` / `border-border` so it inherits your theme. Forward `thresholds` to keep the tier (and glow) consistent with the rest of your scored UI.

# Differential Privacy Controls

Differential Privacy Controls [#differential-privacy-controls]

The **Differential Privacy Controls** are a collapsible settings panel — an
enable toggle, an epsilon slider with a derived privacy-level label
(High/Balanced/Low), and a privacy-budget bar that turns warning then error as
the budget is consumed — plus a compact **DP Applied** provenance badge (lock
icon, epsilon used, embedding dimensionality) for rendering beneath protected
output.

> **No turnkey hook.** This primitive does no DP math. There is no
> `@localmode/react` hook behind it — the app owns the DP state, wiring
> [`dpEmbeddingMiddleware` / `dpClassificationMiddleware`](https://localmode.dev/docs/core)
> and a `createPrivacyBudget` tracker from `@localmode/core`, then passing
> `enabled`, `epsilon`, and the live `budget` in. The component only renders and
> reports user intent through the change callbacks.

**When to use it:** any local-first surface that perturbs embeddings or
classification results with differential privacy and wants the user to control
the privacy/accuracy tradeoff and see how much budget is left.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/security-privacy/differential-privacy-controls`

Full source: https://localmode.ai/r/ui/security-privacy/differential-privacy-controls.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/security-privacy/differential-privacy-controls
```

Dependencies [#dependencies]

* **Data source:** renders the `enabled` / `epsilon` / `budget` props you pass and emits change callbacks — works with any backend; the component does no DP math. Recommended LocalMode producers: `dpEmbeddingMiddleware` / `dpClassificationMiddleware` + `createPrivacyBudget` from `@localmode/core`, whose state you wire in (optional).
* `lucide-react` — the `ShieldCheck` / `ChevronDown` / `Lock` icons
* `radix-ui` — via the `Collapsible`, `Slider`, and `Switch` primitives
* `ui/collapsible`, `ui/slider`, `ui/switch`, `ui/badge` — the shadcn/ui base primitives (installed automatically as registry dependencies)
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `differential-privacy-controls.tsx` — the panel **and** the `DpAppliedBadge`
* `ui/collapsible.tsx`, `ui/slider.tsx`, `ui/switch.tsx`, `ui/badge.tsx` — base primitives (registry dependencies)
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

DifferentialPrivacyControls [#differentialprivacycontrols]

**DifferentialPrivacyControls**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `enabled` | `boolean` | — | **Required.** Whether differential privacy is enabled. Controlled by the app's DP state (typically whether `dpEmbeddingMiddleware` / `dpClassificationMiddleware` is wired into the pipeline). |
| `onEnabledChange` | `function` | — | **Required.** Called when the user toggles DP on or off. |
| `epsilon` | `number` | — | **Required.** Privacy parameter epsilon (privacy budget per query). Lower epsilon = more privacy, more noise. Matches `DPEmbeddingConfig.epsilon` / `DPClassificationConfig.epsilon` in `@localmode/core`. |
| `onEpsilonChange` | `function` | — | **Required.** Called when the user moves the epsilon slider. |
| `minEpsilon` | `number` | `0.1` | Minimum selectable epsilon. |
| `maxEpsilon` | `number` | `10` | Maximum selectable epsilon. |
| `step` | `number` | `0.1` | Slider step. |
| `budget` | `object` | — | Live privacy budget from the app's tracker (`createPrivacyBudget`). When provided, a budget bar is shown that turns warning then error as the consumed epsilon approaches the maximum. |
| `open` | `boolean` | `true` | Open state of the collapsible panel. Controlled only when paired with `onOpenChange`; without a handler it seeds the initial (uncontrolled) state so the trigger still expands/collapses. |
| `onOpenChange` | `function` | — | Called when the panel is expanded or collapsed. |

DpAppliedBadge [#dpappliedbadge]

**DpAppliedBadge**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `epsilon` | `number` | — | **Required.** Epsilon value applied to the protected output. |
| `dimensions` | `number` | — | Embedding dimensionality the noise was applied across (e.g. the embedding model's `dimensions`). Optional — omitted for non-vector outputs. |

Examples [#examples]

Driven by app DP state [#driven-by-app-dp-state]

The app owns the DP middleware and the budget tracker. The panel renders that
state and reports user changes:

```tsx
import { createPrivacyBudget } from '@localmode/core';
import { DifferentialPrivacyControls } from '@/components/differential-privacy-controls';

const budget = await createPrivacyBudget({ maxEpsilon: 10, persistKey: 'my-app' });

export function Settings() {
  const [enabled, setEnabled] = useState(true);
  const [epsilon, setEpsilon] = useState(1.0);
  const [consumed, setConsumed] = useState(budget.consumed());

  return (
    <DifferentialPrivacyControls
      enabled={enabled}
      onEnabledChange={setEnabled}
      epsilon={epsilon}
      onEpsilonChange={setEpsilon}
      budget={{ consumed, maxEpsilon: 10 }}
    />
  );
}
```

Each protected query consumes epsilon from the real tracker; reflect that into the
budget prop so the bar transitions ok → warning → error:

```tsx
// after a DP-protected embedding/classification runs
budget.consume(epsilon);
setConsumed(budget.consumed());
```

"DP Applied" provenance badge [#dp-applied-provenance-badge]

Render the badge beneath protected output **only when DP was actually applied**,
with the real epsilon and the embedding model's dimensionality:

```tsx
import { DpAppliedBadge } from '@/components/differential-privacy-controls';

{dpEnabled && <DpAppliedBadge epsilon={epsilon} dimensions={model.dimensions} />}
```

The badge fields must match the values emitted by the DP middleware run
(`DPEmbeddingConfig.epsilon`, the embedding model's `dimensions`) — never
placeholder values.

Disabled state [#disabled-state]

When the toggle is off, the slider and budget bar dim and you should not render
the `DpAppliedBadge` — no DP was applied, so showing provenance would be
misleading:

```tsx
<DifferentialPrivacyControls enabled={false} /* … */ />
{/* no DpAppliedBadge while disabled */}
```

Customization [#customization]

The panel is styled with shadcn/ui CSS-variable utilities (`bg-card`,
`border-border`, `text-muted-foreground`) and composes the `Collapsible`,
`Slider`, `Switch`, and `Badge` base primitives, so it inherits your theme. The
budget/level state colors use Tailwind's `red` / `amber` / `emerald` palettes
directly — swap those classes in the copied file to match your design system.

Because you own the file, you can adjust the epsilon→level thresholds
(`privacyLevelForEpsilon`) and the budget warning/error thresholds to match your
privacy policy.

Accessibility [#accessibility]

The ε control renders the Radix `Slider` primitive **directly** (Radix ignores
`aria-label` on the Root), so the accessible name and readout land on the
focusable Thumb — the `role="slider"` element. The Thumb carries a fixed
`aria-label` (`"Epsilon (privacy budget per query)"`) and an `aria-valuetext`
that spells out both the value and the derived privacy level (e.g. `"ε 1.0 —
High privacy"`), so screen readers announce the privacy trade-off, not just a
number. The spent-budget bar is a labelled `role="progressbar"` (`"Privacy
budget consumed"`). `getByRole('slider', { name: /epsilon/i })` resolves the
control uniquely.

# Lock Status Badge

Lock Status Badge [#lock-status-badge]

The **Lock Status Badge** is a compact chip that shows the session-lock state of
an encrypted vault: `locked`, `unlocked`, or `no-vault`. Each state has distinct
iconography and an accessible text label (state is announced as text, never color
alone).

> **Presentational and key-safe.** The badge holds no key material and performs no
> crypto — pass the current lock state in. Recommended LocalMode source: the
> `status` field of `useEncryptedVault` from `@localmode/react` (map its
> `'uninitialized' | 'locked' | 'unlocked'` onto `'no-vault' | 'locked' |
> 'unlocked'`) — a recommendation, never a requirement.

**When to use it:** any header, toolbar, or item list that needs to surface
whether an encrypted vault is currently locked.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/security-privacy/lock-status-badge`

Full source: https://localmode.ai/r/ui/security-privacy/lock-status-badge.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/security-privacy/lock-status-badge
```

Dependencies [#dependencies]

* **Data source:** renders the `status` you pass. Works with any backend. Recommended LocalMode hook: `useEncryptedVault` (optional).
* `lucide-react` — icons
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `lock-status-badge.tsx` — the component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**LockStatusBadge**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `status` | `LockStatus` | — | **Required.** The vault's session lock state. `no-vault` is the pre-initialization state (nothing to unlock yet); `locked` means an initialized vault whose key is not in memory; `unlocked` means the derived key is held in memory. |
| `label` | `string` | — | Override the default per-state text. The default labels are "Locked" / "Unlocked" / "No vault". |

Examples [#examples]

Reflect the vault's lock state [#reflect-the-vaults-lock-state]

```tsx
import { useEncryptedVault } from '@localmode/react';
import { LockStatusBadge } from '@/components/lock-status-badge';

export function VaultHeader() {
  const { status } = useEncryptedVault({ name: 'notes' });
  return <LockStatusBadge status={status === 'uninitialized' ? 'no-vault' : status} />;
}
```

Custom label [#custom-label]

```tsx
<LockStatusBadge status="unlocked" label="Session open" />
```

Customization [#customization]

Each state's icon and semantic token classes live in a small `STATUS_CONFIG` map
in the copied file — swap the icons, retune the colors, or change the default
labels to match your design system. Because you own the file, the state-to-token
mapping is yours to change.

# Passphrase Gate

Passphrase Gate [#passphrase-gate]

The **Passphrase Gate** is a controlled, presentational unlock/create screen for
a passphrase-protected surface. **Create** mode renders passphrase + confirmation
fields, enforces a minimum length, and shows strength by composing the
[Password Strength Bar](/docs/security-privacy/password-strength-bar) from
caller-computed props. **Unlock** mode renders a single field with a
caller-provided error surface (e.g. "Incorrect passphrase"). Submission emits the
passphrase via `onSubmit`.

> **Backend-agnostic.** The gate performs no crypto, no storage access, and holds
> no passphrase beyond its controlled field state — the app derives the key and
> drives the vault. Works with any backend; the recommended LocalMode hook is
> `useEncryptedVault` from `@localmode/react` (`unlock(passphrase)`, `status`,
> `error`) — a recommendation, never a requirement.

**When to use it:** any vault, encrypted-store, or key-derivation form that needs
a create-vs-unlock passphrase screen with strength feedback and error handling.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/security-privacy/passphrase-gate`

Full source: https://localmode.ai/r/ui/security-privacy/passphrase-gate.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/security-privacy/passphrase-gate
```

Dependencies [#dependencies]

* **Data source:** controlled and presentational — emits `onSubmit(passphrase)` and `onPassphraseChange(value)`; it never estimates strength or touches crypto. Recommended LocalMode hook: `useEncryptedVault` (optional).
* `lucide-react` — icons
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)
* Composes `@localmode/ui/security-privacy/password-strength-bar` (installed automatically as a registry dependency)

Files installed [#files-installed]

* `passphrase-gate.tsx` — the component
* `password-strength-bar.tsx` — the composed strength meter
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**PassphraseGate**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `mode` | `"unlock" \| "create"` | — | **Required.** `'create'` renders passphrase + confirmation fields with a strength meter; `'unlock'` renders a single passphrase field with an error surface. |
| `onSubmit` | `function` | — | **Required.** Fired with the entered passphrase when the (validated) form is submitted. The gate performs no crypto and retains no passphrase beyond its controlled field state. |
| `onPassphraseChange` | `function` | — | Fired on every keystroke in the primary passphrase field, so the app can compute and feed back `strength` (create mode) without the gate estimating anything. |
| `strength` | `object` | — | Caller-computed strength for the composed strength bar (create mode only). Omit to hide the bar. |
| `minLength` | `number` | `8` | Minimum passphrase length enforced in create mode (with mismatch/too-short feedback). |
| `error` | `string` | — | A caller-provided error to surface (e.g. "Incorrect passphrase" after a failed unlock). Re-enables input. |
| `isBusy` | `boolean` | — | When true, disables inputs and shows a busy spinner on submit. |
| `title` | `ReactNode` | — | Title slot (heading above the fields). |
| `description` | `ReactNode` | — | Description slot (sub-text under the title). |
| `submitLabel` | `string` | — | Submit-button label override. Defaults per mode. |

**PassphraseStrength**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number` | — | **Required.** Strength score, 0–100. |
| `label` | `string` | — | Human-readable label (e.g. "Weak", "Good", "Strong"). |
| `color` | `"success" \| "warning" \| "error"` | — | Semantic color token. |

Examples [#examples]

Wiring to an encrypted vault [#wiring-to-an-encrypted-vault]

The app owns the estimator and the vault; the gate only renders and reports intent:

```tsx
import { useEncryptedVault } from '@localmode/react';
import { PassphraseGate } from '@/components/passphrase-gate';

function estimate(value: string) {
  const classes =
    (/[a-z]/.test(value) ? 1 : 0) + (/[A-Z]/.test(value) ? 1 : 0) +
    (/[0-9]/.test(value) ? 1 : 0) + (/[^a-zA-Z0-9]/.test(value) ? 1 : 0);
  const score = Math.round((Math.min(value.length, 16) / 16) * 60 + (classes / 4) * 40);
  return { value: score, label: score < 40 ? 'Weak' : score < 70 ? 'Good' : 'Strong',
    color: score < 40 ? 'error' : score < 70 ? 'warning' : 'success' } as const;
}

export function VaultGate() {
  const { status, error, unlock } = useEncryptedVault({ name: 'notes' });
  const [strength, setStrength] = useState({ value: 0 });
  return (
    <PassphraseGate
      mode={status === 'uninitialized' ? 'create' : 'unlock'}
      onSubmit={unlock}
      onPassphraseChange={(v) => setStrength(estimate(v))}
      strength={strength}
      error={error?.name === 'VaultPassphraseError' ? 'Incorrect passphrase' : undefined}
    />
  );
}
```

Unlock mode with a busy state [#unlock-mode-with-a-busy-state]

```tsx
<PassphraseGate mode="unlock" isBusy={isDeriving} onSubmit={unlock} error={lastError} />
```

Customization [#customization]

Create mode gates submission until the passphrase reaches `minLength` (default 8)
and the confirmation matches; the strength bar renders only when you pass
`strength`. Unlock mode shows a single field plus the `error` surface. Because you
own the copied file, every threshold, label, and class is yours to change — swap
the composed strength bar, add a "show passphrase" toggle, or wire your own
key-derivation flow.

# Password Strength Bar

Password Strength Bar [#password-strength-bar]

The **Password Strength Bar** renders a themed horizontal bar and label that
visualize how strong a password or passphrase is. It is **presentational only**:
your app computes the strength (`0`–`100`), the label string, and a semantic
color token, then passes them in — pairing with [`deriveEncryptionKey`](https://localmode.dev/docs/core) /
Web Crypto from `@localmode/core` in the surrounding key-derivation flow.

> **No turnkey hook.** This primitive does no strength estimation. There is no
> `@localmode/react` hook behind it — the app supplies the computed `value`,
> `label`, and `color` (typically from length/entropy or a zxcvbn-style
> estimator). The component only renders the state you give it.

**When to use it:** any password-creation, passphrase, or key-derivation form
where you already estimate strength and want a themed meter to surface it.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/security-privacy/password-strength-bar`

Full source: https://localmode.ai/r/ui/security-privacy/password-strength-bar.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/security-privacy/password-strength-bar
```

Dependencies [#dependencies]

* **Data source:** purely presentational — it renders the `value` (0–100), `label`, and `color` you compute (from length/entropy or a zxcvbn-style estimator) and works anywhere; there is no producer hook. Pairs naturally with a `@localmode/core` `deriveEncryptionKey` / Web Crypto key-derivation flow, but that is optional.
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `password-strength-bar.tsx` — the component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**PasswordStrengthBar**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number` | — | **Required.** Strength score, `0`–`100`. **The caller computes this** (length / entropy / a zxcvbn-style estimator) — the bar only renders it. Values outside the range are clamped. Pairs with `@localmode/core` `deriveKey`/crypto in the consuming key-derivation flow. |
| `label` | `string` | — | Human-readable strength label shown beside the bar (e.g. `"Weak"`, `"Good"`, `"Strong"`). The caller decides the wording; the component does not derive it from `value`. |
| `color` | `"success" \| "warning" \| "error"` | `"warning"` | Semantic color token for the fill and label. `error` (red) for weak, `warning` (amber) for medium, `success` (green) for strong. The caller picks the token from its own thresholds. |
| `hideLabel` | `boolean` | `false` | When true, hide the textual label and render the bar only. |

Examples [#examples]

Caller computes strength [#caller-computes-strength]

The app owns the estimator. Map your score onto a `0`–`100` value, a label, and a
semantic color token:

```tsx
import { PasswordStrengthBar, type StrengthColor } from '@/components/password-strength-bar';

function estimate(password: string) {
  const classes =
    (/[a-z]/.test(password) ? 1 : 0) +
    (/[A-Z]/.test(password) ? 1 : 0) +
    (/[0-9]/.test(password) ? 1 : 0) +
    (/[^a-zA-Z0-9]/.test(password) ? 1 : 0);
  const lengthScore = Math.min(password.length, 16) / 16;
  return Math.round(lengthScore * 60 + (classes / 4) * 40);
}

export function PasswordField({ password }: { password: string }) {
  const value = estimate(password);
  const color: StrengthColor = value < 40 ? 'error' : value < 70 ? 'warning' : 'success';
  const label = value < 40 ? 'Weak' : value < 70 ? 'Good' : 'Strong';
  return <PasswordStrengthBar value={value} label={label} color={color} />;
}
```

Pair with key derivation [#pair-with-key-derivation]

Estimate strength before deriving an encryption key with `@localmode/core`:

```tsx
import { deriveEncryptionKey } from '@localmode/core';
import { PasswordStrengthBar } from '@/components/password-strength-bar';

// 1. Surface strength as the user types
<PasswordStrengthBar value={strength} label={label} color={color} />

// 2. On submit, derive the key (Web Crypto, never leaves the device)
const { key } = await deriveEncryptionKey(password, salt);
```

Bar only (no label) [#bar-only-no-label]

```tsx
<PasswordStrengthBar value={72} color="success" hideLabel />
```

Customization [#customization]

The bar is styled entirely with shadcn/ui CSS-variable utilities (`bg-muted` for
the track) so it inherits your theme. The semantic fill/label colors use
Tailwind's `red` / `amber` / `emerald` palettes directly — swap those classes in
the copied `password-strength-bar.tsx` to match your design system, or wire them
to your own tokens.

Because you own the file, you can also change how `color` maps to tokens, or add
more granular labels (`Very weak`, `Fair`, …) — the component never derives the
label from `value`, so your thresholds stay in your code.

# Vault Item Card

Vault Item Card [#vault-item-card]

The **Vault Item Card** renders a single encrypted vault item (a note or a text
document). When **locked**, it shows a masked placeholder body with the
reveal/delete actions disabled — no decrypted content is present in the DOM. When
**unlocked**, it shows the title/timestamp with a reveal/hide toggle over the
caller-supplied decrypted `content` and a delete action, all via callbacks.

> **Backend-agnostic and key-safe.** The card never receives or renders ciphertext
> or key material — the consuming app decrypts and passes plaintext in `content`
> only when `revealed` is true. Recommended LocalMode source: the `items`,
> `readItem`, and `deleteItem` of `useEncryptedVault` from `@localmode/react` — a
> recommendation, never a requirement.

**When to use it:** any encrypted-store UI listing items whose plaintext is
revealed on demand — password managers, secure notes, encrypted document vaults.

Preview [#preview]

Install: `npx shadcn@latest add @localmode/ui/security-privacy/vault-item-card`

Full source: https://localmode.ai/r/ui/security-privacy/vault-item-card.json

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/security-privacy/vault-item-card
```

Dependencies [#dependencies]

* **Data source:** renders the lock state, title/timestamp, and (only when revealed) the decrypted `content` you pass; emits `onReveal`/`onHide`/`onDelete`. Works with any backend. Recommended LocalMode hook: `useEncryptedVault` (optional).
* `lucide-react` — icons
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `vault-item-card.tsx` — the component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**VaultItemCard**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | — | **Required.** Item title (a non-sensitive envelope field — safe to render while locked). |
| `createdAt` | `string` | — | Creation timestamp (preformatted display string, e.g. "2 days ago"). |
| `locked` | `boolean` | — | **Required.** Whether the vault is locked. When `true`, the body is masked, no content is rendered, and the reveal/delete actions are disabled. |
| `revealed` | `boolean` | `false` | Whether the decrypted content is currently revealed. Only meaningful while unlocked. The consuming app toggles this via `onReveal`/`onHide`. |
| `content` | `string` | — | The decrypted plaintext content — supplied by the caller ONLY when revealed. The card never receives ciphertext or key material; the app decrypts and passes plaintext in when the user reveals. |
| `kind` | `"document" \| "note"` | `'note'` | Item kind — drives the icon and the masked-body wording. |
| `onReveal` | `function` | — | Fired when the user requests to reveal (decrypt-on-view) the content. |
| `onHide` | `function` | — | Fired when the user hides the revealed content. |
| `onDelete` | `function` | — | Fired when the user deletes the item. |

Examples [#examples]

Decrypt-on-view from an encrypted vault [#decrypt-on-view-from-an-encrypted-vault]

Pass plaintext only while the item is revealed — the vault decrypts on demand:

```tsx
import { useEncryptedVault } from '@localmode/react';
import { VaultItemCard } from '@/components/vault-item-card';

export function VaultList() {
  const { status, items, deleteItem } = useEncryptedVault<{ title: string; body: string }>({ name: 'notes' });
  const [openId, setOpenId] = useState<string | null>(null);
  return items.map((item) => (
    <VaultItemCard
      key={item.id}
      title={item.data.title}
      locked={status !== 'unlocked'}
      revealed={openId === item.id}
      content={openId === item.id ? item.data.body : undefined}
      onReveal={() => setOpenId(item.id)}
      onHide={() => setOpenId(null)}
      onDelete={() => deleteItem(item.id)}
    />
  ));
}
```

Document variant [#document-variant]

```tsx
<VaultItemCard title="recovery-codes.txt" kind="document" locked={false} content={text} revealed />
```

Customization [#customization]

The masked body, the reveal/hide toggle, and the delete affordance are all styled
with shadcn/ui CSS-variable utilities so they inherit your theme. Because you own
the copied file, you can change the mask rendering, add a copy-to-clipboard
action, or render a richer preview for the document `kind`.

# Blocks

LocalMode UI blocks are composed, installable experiences that wire the copy-owned primitives to real on-device models. Each block runs entirely in the browser, is served live at the /blocks gallery, and installs with the shadcn CLI.

## Chat

### Chat

Chat with AI models running fully in your browser.

- URL: https://localmode.ai/blocks/chat
- Install: npx shadcn@latest add @localmode/ui/blocks/chat

## Knowledge

### Semantic Search

Search your text, PDFs, and scans by meaning.

- URL: https://localmode.ai/blocks/knowledge/semantic-search
- Install: npx shadcn@latest add @localmode/ui/blocks/knowledge/semantic-search

### Document QA

Ask questions and get answers from your documents.

- URL: https://localmode.ai/blocks/knowledge/document-qa
- Install: npx shadcn@latest add @localmode/ui/blocks/knowledge/document-qa

### RAG Chat

Chat with your documents, with cited, grounded answers.

- URL: https://localmode.ai/blocks/knowledge/rag-chat
- Install: npx shadcn@latest add @localmode/ui/blocks/knowledge/rag-chat

### Vector Data Manager

Import, export, and inspect your vector database.

- URL: https://localmode.ai/blocks/knowledge/vector-data-manager
- Install: npx shadcn@latest add @localmode/ui/blocks/knowledge/vector-data-manager

## Vision

### Object Detector

Find and label objects in a photo or webcam frame.

- URL: https://localmode.ai/blocks/vision/object-detector
- Install: npx shadcn@latest add @localmode/ui/blocks/vision/object-detector

### Live Tracker

Track hands, pose, face, and gestures from your webcam.

- URL: https://localmode.ai/blocks/vision/live-tracker
- Install: npx shadcn@latest add @localmode/ui/blocks/vision/live-tracker

## Audio

### Voice Notes

Record audio and turn it into searchable text notes.

- URL: https://localmode.ai/blocks/audio/voice-notes
- Install: npx shadcn@latest add @localmode/ui/blocks/audio/voice-notes

### Live Transcription

Transcribe your microphone live as you speak.

- URL: https://localmode.ai/blocks/audio/live-transcription
- Install: npx shadcn@latest add @localmode/ui/blocks/audio/live-transcription

### Meeting Assistant

Turn a meeting into a summary and action items.

- URL: https://localmode.ai/blocks/audio/meeting-assistant
- Install: npx shadcn@latest add @localmode/ui/blocks/audio/meeting-assistant

### Voice Explorer

Browse and compare 29 natural text-to-speech voices.

- URL: https://localmode.ai/blocks/audio/voice-explorer
- Install: npx shadcn@latest add @localmode/ui/blocks/audio/voice-explorer

### Audiobook Reader

Turn long text into speech that plays as it streams.

- URL: https://localmode.ai/blocks/audio/audiobook-reader
- Install: npx shadcn@latest add @localmode/ui/blocks/audio/audiobook-reader

### Audio Classifier

Identify the sounds in a recording or audio file.

- URL: https://localmode.ai/blocks/audio/audio-classifier
- Install: npx shadcn@latest add @localmode/ui/blocks/audio/audio-classifier

## Text

### Language Detector

Detect the language of a text and compare two.

- URL: https://localmode.ai/blocks/text/language-detector
- Install: npx shadcn@latest add @localmode/ui/blocks/text/language-detector

## Device

### Device Report

See what your device can do for on-device AI.

- URL: https://localmode.ai/blocks/device/device-report
- Install: npx shadcn@latest add @localmode/ui/blocks/device/device-report

### Model Advisor

Get model picks matched to your device and task.

- URL: https://localmode.ai/blocks/device/model-advisor
- Install: npx shadcn@latest add @localmode/ui/blocks/device/model-advisor

### GGUF Explorer

Browse thousands of downloadable AI models.

- URL: https://localmode.ai/blocks/device/gguf-explorer
- Install: npx shadcn@latest add @localmode/ui/blocks/device/gguf-explorer

## Writing Tools

### Write

Rewrite or improve your draft and review the edits.

- URL: https://localmode.ai/blocks/writing-tools/write
- Install: npx shadcn@latest add @localmode/ui/blocks/writing-tools/write

### Translate

Translate text between languages, fully offline.

- URL: https://localmode.ai/blocks/writing-tools/translate
- Install: npx shadcn@latest add @localmode/ui/blocks/writing-tools/translate

### Summarize

Summarize long text at the length you choose.

- URL: https://localmode.ai/blocks/writing-tools/summarize
- Install: npx shadcn@latest add @localmode/ui/blocks/writing-tools/summarize

### Complete

Predict the next word and autocomplete your text.

- URL: https://localmode.ai/blocks/writing-tools/complete
- Install: npx shadcn@latest add @localmode/ui/blocks/writing-tools/complete

## Agents

### Research Agent

Watch an AI agent research a question using tools.

- URL: https://localmode.ai/blocks/agents/research-agent
- Install: npx shadcn@latest add @localmode/ui/blocks/agents/research-agent

### Data Extractor

Pull structured data from text into a table and chart.

- URL: https://localmode.ai/blocks/agents/data-extractor
- Install: npx shadcn@latest add @localmode/ui/blocks/agents/data-extractor

## Text Insights

### Sentiment Analyzer

Score text as positive or negative, one or in bulk.

- URL: https://localmode.ai/blocks/text-insights/sentiment-analyzer
- Install: npx shadcn@latest add @localmode/ui/blocks/text-insights/sentiment-analyzer

### Text Classifier

Sort text into your own labels, no training needed.

- URL: https://localmode.ai/blocks/text-insights/text-classifier
- Install: npx shadcn@latest add @localmode/ui/blocks/text-insights/text-classifier

### Model Evaluator

Measure classifier accuracy on labeled data.

- URL: https://localmode.ai/blocks/text-insights/model-evaluator
- Install: npx shadcn@latest add @localmode/ui/blocks/text-insights/model-evaluator

### Threshold Calibrator

Pick the right similarity cutoff from your data.

- URL: https://localmode.ai/blocks/text-insights/threshold-calibrator
- Install: npx shadcn@latest add @localmode/ui/blocks/text-insights/threshold-calibrator

## Photo

### Smart Gallery

Auto-sort your photos into categories on device.

- URL: https://localmode.ai/blocks/photo/smart-gallery
- Install: npx shadcn@latest add @localmode/ui/blocks/photo/smart-gallery

### Image Search

Search your photos by text or by another image.

- URL: https://localmode.ai/blocks/photo/image-search
- Install: npx shadcn@latest add @localmode/ui/blocks/photo/image-search

### Duplicate Finder

Find and remove near-duplicate photos in your library.

- URL: https://localmode.ai/blocks/photo/duplicate-finder
- Install: npx shadcn@latest add @localmode/ui/blocks/photo/duplicate-finder

### Photo Categorizer

Sort your photos into labels you define.

- URL: https://localmode.ai/blocks/photo/photo-categorizer
- Install: npx shadcn@latest add @localmode/ui/blocks/photo/photo-categorizer

## Image Studio

### Background Remover

Cut out a photo subject to a transparent PNG.

- URL: https://localmode.ai/blocks/image-studio/background-remover
- Install: npx shadcn@latest add @localmode/ui/blocks/image-studio/background-remover

### Image Enhancer

Upscale and sharpen a photo at 2x, 4x, or restore.

- URL: https://localmode.ai/blocks/image-studio/image-enhancer
- Install: npx shadcn@latest add @localmode/ui/blocks/image-studio/image-enhancer

### Image Captioner

Generate alt-text captions for your images.

- URL: https://localmode.ai/blocks/image-studio/image-captioner
- Install: npx shadcn@latest add @localmode/ui/blocks/image-studio/image-captioner

## Privacy

### PII Redactor

Find and mask personal details in text, on device.

- URL: https://localmode.ai/blocks/privacy/pii-redactor
- Install: npx shadcn@latest add @localmode/ui/blocks/privacy/pii-redactor

### Encrypted Vault

A passphrase-locked vault for encrypted notes and files.

- URL: https://localmode.ai/blocks/privacy/encrypted-vault
- Install: npx shadcn@latest add @localmode/ui/blocks/privacy/encrypted-vault