AI Chat Interface

Demo & usage

More examples

When to use

• Adding a conversational AI surface: assistant, support bot, copilot panel.
• You want streaming indicators, tool-call chips and markdown/code rendering ready-made.
• Pick the variant that fits placement — floating for apps, embedded for a page section.

Async states

• loading
• error
• retry
• offline

Outputs

Wire it to your API

This component is headless about transport: it renders what you give it and reports what the user asks for. Nothing below requires @styloviz/data — drive it from whatever you already use.

• This component does not emit a query, so it renders what you give it. Fetch on your own trigger and bind `messages`, `loading` and `error`.
• `connection` reports the state of your `EventSource` or WebSocket. The component cannot infer it: a list that stops growing looks identical whether the feed is quiet or the socket died.
• Normalize failures with `toSvDataError()` from `@styloviz/core`. It derives `retryable` from the status, so a 404 does not get a "Try again" button that can only fail again.

Full walkthrough: Connecting to a backend.

Customization & theming

• Every content set is an input and every one defaults to empty — `messages` (two-way), `models`, `selectedModel` (two-way, nullable), `suggestedPrompts`, `sessions` and `activeSessionId` (two-way, nullable). The component ships no sample data; import `DEMO_MODELS` / `DEMO_PROMPTS` / `DEMO_SESSIONS` for a demo.
• Stream a real reply with `beginAssistantMessage()` → `appendToken()` → `completeAssistantMessage()` / `failAssistantMessage()`. A failed stream keeps whatever text arrived and offers a resend. Acknowledge a delivered user message with `acknowledgeMessage()`, or reveal its resend control with `failMessage()`.
• While a reply is streaming the send button becomes a stop control, which emits `stopRequest` — abort your request there.
• Set `demoMode` to fake replies with no backend; it used to be on by default under the name `simulate`.
• Use `loading` / `error` / `retry` for fetching the transcript or the session list; `busy` for your own in-flight state.
• Four layouts, set with `variant`: `copilot` (docked side panel), `fullscreen`, `inline` (embedded in a page) and `bubble` (floating launcher).
• Streaming indicators; assistant messages render `toolCalls` (running/success/error cards with args + result) and `attachments` (file chips).
• Markdown + code-block rendering with copy.
• Every variant exposes working per-message copy, like and dislike actions (like/dislike are mutually exclusive) via a shared action row. Copy confirms only once the clipboard write resolves — the clipboard is unavailable over plain HTTP and can reject — and emits `copyFailed` with the message id when it does not, so a host can offer the text another way.
• Emits `messageSent` (the sent text) and `modelChange` so a host can wire it to a real backend.
• Responsive: in the fullscreen layout the session sidebar is hidden on phones (chat takes the full width) and returns from `md` up.
• One privacy policy for the whole pack (`X-2`): `provideSvAiPrivacy({ patterns, reveal, copy, telemetry })` in `@styloviz/core` configures masking once instead of eight times. Message content is masked at RENDER — your `messages` are never edited — and `copy: false` hides the copy control AND refuses `copyMessage()`, because a hidden button is a styling decision and the method is public API. With no policy provided nothing is masked and copy works exactly as before.
• A scale ceiling on the transcript: `[maxMessages]` (300) is how many messages the thread renders at once, and the window keeps the NEWEST — a conversation cut at its first hundred messages would hide the part the user is having right now. What is missing is disclosed at the top of the thread, where it was, and `messages` itself stays complete: the ceiling is a rendering decision, not an edit to your data. Set `0` if you virtualize the thread yourself.
• Attachment limits are a policy the kit owns and the host enforces: `svCheckAttachments(list, { maxCount, maxBytes, accept })` returns what is accepted and what is refused, each refusal carrying a reason in `ChatAttachment.rejected`. The count limit **refuses the overflow rather than truncating it**, and a refused attachment stays in the transcript, struck through with its reason — one that disappears is indistinguishable from one that uploaded, and the user sends 'here’s the recording' to a model that never saw it.
• An unknown size or MIME type is accepted rather than refused: the host may not have either until the upload finishes, and a limit that rejects everything is indistinguishable from a broken picker. A non-positive `maxCount` or `maxBytes` falls back to the default (10 files, 25 MB) rather than meaning 'nothing allowed'.
• Attachments render on **user** messages as well as assistant ones. They used to render only under an assistant message, so a file the user attached — and any refusal of it — was invisible on the message that carried it.
• When the clipboard refuses — plain HTTP, a denied permission, an unfocused document — the component **selects the message text** and says which keys to press, naming ⌘C or Ctrl+C for the platform the reader is actually on. Telling somebody 'copying failed' leaves them to select three paragraphs by hand, which is the moment they give up and retype it.
• Streaming is a **separate package**: `@styloviz-pro/ai-chat-transport`. Nothing in this component imports it, and that is the point — a transport baked into the UI is a UI that has picked your backend for you, and a provider renaming a field would ship as a new version of the chat. It carries `svSseReader` (SSE framing that survives a chunk boundary, which is the bug that makes a hand-rolled loop drop one token in a few hundred), `svFrameGate` (duplicate, late and missing WebSocket frames), `svDecodePart` (an AI-SDK-style part decoder that tells an incremental delta from a cumulative snapshot — confuse them and the reply either repeats itself or loses all but its last token), and `svStreamStart` / `svApplyParts` / `svStreamEnd` / `svToChatMessage` to reduce the lot into one of these messages.
• A stream that stops arriving without a terminal event is `interrupted`, not `complete`, and `svToChatMessage` renders it as an `error` message so the reader gets the reason and a resend control beside the half answer. Flipping it to complete — tempting, because there IS text to show — tells them the half answer is the whole answer, which is the one lie in a chat UI they will act on.
• A part of a kind the decoder does not model is counted, not dropped: `svStreamNotice` then says that something which arrived is not shown. Providers add part types constantly, and ignoring the unknown ones produces a transcript missing content that looks whole.
• The AI SDK is decoded in both of its wire formats: the **v5 UI message stream** (text, reasoning, tool input/output, sources, errors; `start` / `start-step` / `text-start` lifecycle markers are understood rather than counted as unknown; `finish-step` separates the steps of a tool → answer run with a paragraph break and only `finish` ends the reply; `abort` ends it as interrupted) and the **v4 data stream protocol** (`0:` text, `9:` / `a:` tool call and result, `e:` / `d:` step and finish, `3:` error), which arrives as a plain line-per-part body and is read with `svDataStreamReader`. **OpenAI Responses** function calls are assembled from `output_item.added` and `function_call_arguments.delta` addressed by `output_index`.
• The transport also decodes the two provider formats most hosts actually hold: **Anthropic Messages streaming** (`content_block_delta` text and thinking deltas, `tool_use` arguments assembled from `input_json_delta` fragments addressed by `index`, `message_delta` stop reasons, `ping` ignored) and **OpenAI Chat Completions** (`chat.completion.chunk` — `choices[].delta.content`, index-addressed `tool_calls`, `finish_reason`, and the usage chunk that arrives after the finish). `svFinishReason` maps both vocabularies onto one, so an Anthropic reply cut off at `max_tokens` reads as truncated rather than finished. Use `svDecodeParts` — one Chat Completions chunk can carry several parts, and `svDecodePart` returns such a chunk as `unknown` rather than keeping only the first.
• Auto-scroll follows the conversation only while the reader is at the bottom (within `stickToBottomThreshold`, default 48px) or has just sent a message. Scrolled up to re-read an answer, their position is kept while tokens stream in, and a **Jump to latest** control — with a count of new messages — appears instead of the view being pulled out from under them.

Best practices

• Do: Leave `[maxMessages]` on unless you virtualize the thread yourself. An agent conversation with tool calls woven in reaches four figures inside an afternoon, and a thread that renders all of them slows down until the user reloads — which on a chat is how a support transcript gets lost.
• Do: Use the `variant` that matches placement; wire it to your own message store.
• Do: Stream responses into a live region so screen readers announce updates (handled).
• Tip: Treat the component as a styled shell — connect it to your model/transport layer.
• Do: Acknowledge each user message once the server has it. Until you do it shows "Sending…", which is what makes a dropped message visible instead of silent.
• Don't: Do not ship `demoMode` enabled. It fabricates assistant replies, so the chat answers itself alongside your real backend.

Accessibility

• Message log uses a live region for streaming; user text is bound safely and all assistant HTML — including tool-call and attachment markup — is escaped.
• Model picker exposes aria-haspopup/aria-expanded; feedback buttons report aria-pressed.
• Input and actions are labelled and keyboard reachable.
• The Jump to latest control is a real button outside the message live region, so Tab reaches it and it is not announced as a message; activating it moves focus to the transcript rather than dropping it to the page.