@talk2view/sdk 0.14.0 → 0.16.0

package/README.md

@@ -8,12 +8,51 @@ Add AI-powered natural language control to any application. Talk2View's SDK hand
 npm install @talk2view/sdk
 ```
 
+## Chat UI
+
+Three lines to a working chat. `@talk2view/sdk/chat` is the branded Talk2View
+chat, packaged: your app needs no Tailwind, no PostCSS, no shadcn and no copied
+component files.
+
+```tsx
+import { Talk2ViewChat } from '@talk2view/sdk/chat';
+import '@talk2view/sdk/chat.css';
+
+<Talk2ViewChat partnerKey="pk_live_…" tools={tools} welcome={{ suggestions: ['What can you do?'] }} />
+```
+
+That is the full pane: sign-in, streaming replies, attachments, dictation,
+Settings, earlier conversations and tool approvals. Give it a parent with a
+height — it fills its box.
+
+For a floating chat instead — a mark in the corner of the page, a popover on a
+desktop, a full-screen sheet on a phone:
+
+```tsx
+import { Talk2ViewChatLauncher } from '@talk2view/sdk/chat';
+import '@talk2view/sdk/chat.css';
+
+<Talk2ViewChatLauncher partnerKey="pk_live_…" tools={tools} label="Ask Talk2View" />
+```
+
+Theming is the custom properties on `.t2v-chat` (`--radius`, `--primary`, the
+rest); dark mode is `className="dark"`. The chat fetches nothing at runtime — no
+fonts, no CDN — and uses your page's font unless you pass `fontFamily`.
+
+**It is large: 361.8 KB gzip, excluding React.** A consumer who never imports
+`/chat` pays none of it.
+
+Everything else — the full prop table, theming tokens, the launcher in a hostile
+page, CSP, Next.js — is in **[`docs/chat.md`](docs/chat.md)**. A runnable
+example with no Tailwind in the host is in
+[`examples/react-chat`](examples/react-chat).
+
 ## Quick Start
 
 ### React (recommended)
 
 ```tsx
-import { T2VProvider, ChatPanel } from '@talk2view/sdk/react';
+import { Talk2View, ChatPanel } from '@talk2view/sdk/ui';
 import type { ClientTool } from '@talk2view/sdk';
 
 const tools: ClientTool[] = [
@@ -36,17 +75,26 @@ const tools: ClientTool[] = [
 
 function App() {
   return (
-    <T2VProvider partnerKey="pk_live_..." baseUrl="https://api.talk2view.com">
-      <ChatPanel tools={tools} systemPrompt="You control a canvas." />
-    </T2VProvider>
+    <Talk2View partnerKey="pk_live_..." tools={tools} systemPrompt="You control a canvas.">
+      <ChatPanel />
+    </Talk2View>
   );
 }
 ```
 
-That's it. The `ChatPanel` handles login, tool registration, streaming chat, and tool execution automatically.
+That's it. `<Talk2View>` registers your tools and holds the chat state; `<ChatPanel>` is the UI — sign-in, streaming replies, tool calls and approvals. Both come from `@talk2view/sdk/ui`, and `<ChatPanel>` must be inside `<Talk2View>`.
+
+> `/ui` is the previous chat panel, and is still supported. It is far smaller
+> than the packaged chat (39.9 KB gzip against 361.8) and has no assistant-ui in
+> it. New integrations that want the current Talk2View chat should use
+> [`@talk2view/sdk/chat`](#chat-ui) above.
+
+A logged-out visitor gets an anonymous demo session automatically, so there is nothing to wire up before the first reply. Pass `allowAnonymous={false}` to `<ChatPanel>` to ask people to sign in first.
 
 ### Vanilla JavaScript
 
+The package root exports a `Talk2View` **class** — the framework-agnostic client. It shares a name with the `<Talk2View>` provider component from `/ui` above; if you need both in one file, alias one of them.
+
 ```typescript
 import { Talk2View } from '@talk2view/sdk';
 
@@ -69,9 +117,10 @@ await t2v.tools.register([
 ]);
 
 // 3. Chat — tool calls are handled automatically
+let reply = '';
 for await (const event of t2v.chat('What time is it?')) {
-  if (event.type === 'text') process.stdout.write(event.content);
-  if (event.type === 'done') console.log('\n');
+  if (event.type === 'text') reply += event.content;
+  if (event.type === 'done') console.log(reply);
 }
 ```
 
@@ -124,49 +173,79 @@ Tools with `return_direct: true` skip the AI's post-processing step. The tool re
 
 ## React API
 
-### `<T2VProvider>`
+There are four React entry points, and they do different jobs:
 
-Context provider that initializes the Talk2View client. Wrap your app (or the section that uses Talk2View) with this.
+- **`@talk2view/sdk/chat`** — the branded Talk2View chat, packaged: `<Talk2ViewChat>` and `<Talk2ViewChatLauncher>`, one stylesheet, nothing to configure. Start here. See [Chat UI](#chat-ui) above and [`docs/chat.md`](docs/chat.md).
+- **`@talk2view/sdk/ui`** — the previous chat panel, still supported: `<Talk2View>`, `<ChatPanel>`, `<ChatWidget>` and the components they are built from. 39.9 KB gzip against the packaged chat's 361.8, and no assistant-ui.
+- **`@talk2view/sdk/react`** — headless: `<T2VProvider>` and hooks, for building your own UI.
+- **`@talk2view/sdk/assistant-ui`** — a runtime for [assistant-ui](https://www.assistant-ui.com): render the stock `<Thread />` on Talk2View. See [assistant-ui](#assistant-ui) below.
+
+### `<Talk2View>` (from `/ui`)
+
+The root provider for the UI components. It creates the client, registers your tools, injects the theme, and holds the chat state every `/ui` component reads.
 
 ```tsx
-<T2VProvider
-  partnerKey="pk_live_..."   // Required
-  baseUrl="https://api.talk2view.com"  // Optional, defaults to localhost:8100
-  model="gpt-4.1-mini"      // Optional, uses server default
+<Talk2View
+  partnerKey="pk_live_..."          // Required
+  tools={myTools}                    // Optional — ClientTool[] (with execute) or schemas
+  systemPrompt="You are..."          // Optional — sent with every message
+  baseUrl="https://engine.talk2view.com"  // Optional, this is the default
+  model="gpt-4.1-mini"               // Optional, falls back to your partner default
+  theme={{ accent: '#26C8B8' }}      // Optional
+  debug={false}                      // Optional — log to the browser console
 >
   {children}
-</T2VProvider>
+</Talk2View>
 ```
 
-### `<ChatPanel>`
+### `<ChatPanel>` (from `/ui`)
 
-Self-contained chat UI with built-in login, tool registration, message list, and input. Drop this in and it works.
+The full chat surface: header, message list, composer, sign-in, tool approvals. It takes its client and state from `<Talk2View>`, so it must be rendered inside one — on its own it throws `useTalk2View must be used within <Talk2View>`. Note that `tools` and `systemPrompt` belong on `<Talk2View>`, not here.
 
 ```tsx
 <ChatPanel
-  tools={myTools}            // ClientTool[] — tools with execute handlers
-  systemPrompt="You are..."  // Optional system prompt
-  signupUrl="https://..."    // Optional, link shown on login form
-  className="my-chat"        // Optional CSS class
-  style={{ height: '100%' }} // Optional inline styles
+  welcome={{ heading: 'Ask about this document', suggestions: ['Summarise it'] }}
+  allowAnonymous={true}          // Default. false = require sign-in before chatting
+  signupUrl="https://..."        // Link shown on the sign-in form
+  resetPasswordUrl="https://..." // Adds a "Forgot password?" link
+  resetPasswordTarget="_blank"   // Default. '_self' opens in your own app
+  describeToolActivity={(name, args) => (name === 'set_color' ? 'Recolouring' : null)}
+  isToolDestructive={(name) => name.startsWith('delete_')}
+  groupAssistantMessages={false}
 />
 ```
 
-If the user isn't logged in, `ChatPanel` shows a login form automatically. After login, it registers the provided tools and enables the chat input.
+By default a logged-out visitor is signed into an anonymous demo session rather than being shown a login form. The sign-in form appears when `allowAnonymous` is `false`, when your partner account has anonymous access switched off or its daily cap is spent, or when the demo budget for that visitor runs out.
 
-### `<LoginModal>`
+### `<LoginForm>` (from `/ui`)
 
-Standalone login form. Use this if you want to control placement separately from the chat UI.
+The sign-in form on its own, if you want to place it yourself. It renders unconditionally — you decide when to show it (check `isAuthenticated` from `useTalk2View()`, the `/ui` hook).
 
 ```tsx
-<LoginModal
-  signupUrl="https://talk2view.com/auth?signup"  // Optional
-  onSuccess={() => console.log('Logged in!')}     // Optional callback
-  className="my-login"                             // Optional CSS class
+<LoginForm
+  heading="Sign in"
+  subheading="to keep your chat history"
+  defaultMode="login"            // or 'signup'
+  signupUrl="https://talk2view.com/auth?signup"
+  resetPasswordUrl="https://..."
+  termsUrl="https://..."
+  privacyUrl="https://..."
 />
 ```
 
-Returns `null` if the user is already authenticated.
+### `<T2VProvider>` (from `/react`)
+
+The headless provider. Use it when you are building your own UI on the hooks below; `<Talk2View>` already includes it, so you never need both.
+
+```tsx
+<T2VProvider
+  partnerKey="pk_live_..."   // Required
+  baseUrl="https://engine.talk2view.com"  // Optional, this is the default
+  model="gpt-4.1-mini"      // Optional, uses your partner default
+>
+  {children}
+</T2VProvider>
+```
 
 ### `useT2V()`
 
@@ -187,30 +266,45 @@ const {
   isLoading,         // boolean
   error,             // string | null
   login,             // (email: string, password: string) => Promise<void>
-  signup,            // (email: string, password: string) => Promise<void>
+  signup,            // (email, password) => Promise<{ user, confirmationRequired }>
   logout,            // () => Promise<void>
   clearError,        // () => void
+  signInWithGoogle,  // () => Promise<void> — opens the Google sign-in popup
+  signInWithApple,   // () => Promise<void> — opens the Apple sign-in popup
+  oauthLoading,      // boolean — true while either popup is open
+  oauthProvider,     // 'google' | 'apple' | null — which one
+  oauthProviders,    // ('google' | 'apple')[] | null — popup sign-ins available on this website; null while loading
 } = useT2VAuth();
 ```
 
+`signup()` resolves to a `SignupOutcome`: `{ user: User | null; confirmationRequired: boolean }`. When your project has email confirmation switched on, `confirmationRequired` is `true` and `user` is `null` until the person clicks the link in their inbox.
+
+Google and Apple sign-in open a popup and work on any `https://` website, with nothing to configure — your users have Talk2View accounts, and the sign-in form is the same in every app. Your publishable key is public, though, so on a website you have **not** registered your users first see a Talk2View screen naming the site that is asking, and press Continue. Add your site under **Settings → Allowed websites** in the dashboard (the exact `https://` address, nothing after the domain) and that screen goes away; the SDK logs one line to the console when it applies. If your account is set to allow only registered websites, `<LoginForm>` hides the two buttons elsewhere. Popup sign-in never runs on `localhost`; use email and password while developing.
+
 ### `useT2VChat()`
 
 Chat state and message sending.
 
 ```tsx
 const {
-  messages,          // DisplayMessage[]
-  isLoading,         // boolean — true while streaming
-  error,             // string | null
-  threadId,          // string | null
-  agentStatus,       // { type: string; message: string } | null — real-time agent status
-  todos,             // string — agent's current todo/plan text
-  sendMessage,       // (content: string) => Promise<void>
-  clearMessages,     // () => void
-  clearError,        // () => void
+  messages,            // DisplayMessage[]
+  isLoading,           // boolean — true while streaming
+  error,               // string | null
+  threadId,            // string | null
+  agentStatus,         // { status: string; message: string } | null
+  pendingApproval,     // PendingApproval | null — a tool call awaiting a decision
+  alwaysAllowedTools,  // ReadonlySet<string> — approved for the rest of the session
+  sendMessage,         // (content, { attachments? }) => Promise<void>
+  approveToolCall,     // (decision: HumanDecision) => Promise<void>
+  retryLastMessage,    // () => Promise<void> — only meaningful while error is set
+  stop,                // () => void — ends the reply, keeps the text so far
+  clearMessages,       // () => void
+  clearError,          // () => void
 } = useT2VChat({ systemPrompt: 'You are a helpful assistant.' });
 ```
 
+When a tool is registered with `permission: true`, the agent pauses and `pendingApproval` fills in. Show it, then call `approveToolCall({ action: 'once' | 'always' | 'deny' })` — `'always'` adds the tool to `alwaysAllowedTools` for the rest of the session. `<ChatPanel>` already does all of this; you only need it when building your own UI.
+
 `DisplayMessage` shape:
 ```typescript
 {
@@ -218,7 +312,10 @@ const {
   role: 'user' | 'assistant'
   content: string
   timestamp: Date
-  isStreaming?: boolean  // true while the assistant is still generating
+  isStreaming?: boolean   // true while the assistant is still generating
+  attachments?: Attachment[]  // files sent with a user message
+  plan?: string           // markdown checklist from the agent's planning tool
+  steps?: ToolStep[]      // completed tool calls, rendered as inline steps
 }
 ```
 
@@ -236,6 +333,86 @@ const {
 
 ---
 
+## assistant-ui
+
+assistant-ui already has a seam other backends plug into at the runtime level — `@assistant-ui/react-ai-sdk` for the Vercel AI SDK is the well-known example. `useTalk2ViewRuntime` is Talk2View's equivalent: it hands assistant-ui an `AssistantRuntime`, built on `useExternalStoreRuntime`, so the stock `<Thread />` (or the primitives) render Talk2View's messages, client tools, approvals and streaming — with no Talk2View-specific component in the tree.
+
+This is a separate entry point from `/ui` and `/react`: `@assistant-ui/react` is an optional peer dependency, loaded only when you import `@talk2view/sdk/assistant-ui`. It never affects the root, `/react` or `/ui` bundles.
+
+### Install
+
+```bash
+npm install @assistant-ui/react
+npx shadcn@latest init --yes --defaults
+npx shadcn@latest add @assistant-ui/thread --yes
+```
+
+The `shadcn` commands generate the Thread's source into your own `src/components/` — they're your files, not a Talk2View package, so you can restyle or extend them freely. See `examples/react-assistant-ui` for a full app built this way, including the exact generated output.
+
+One known wrinkle in the registry output at the time of writing: `tooltip-icon-button.tsx` passes `delayDuration={0}` to a `TooltipProvider` whose prop is `delay`. It is inert at runtime, but it fails `tsc`, so if your build type-checks (most Vite templates run `tsc -b && vite build`) change it to `delay={0}` — the example does.
+
+### `useTalk2ViewRuntime`
+
+```tsx
+import { AssistantRuntimeProvider } from '@assistant-ui/react';
+import { useTalk2ViewRuntime } from '@talk2view/sdk/assistant-ui';
+
+function Chat() {
+  const runtime = useTalk2ViewRuntime({ partnerKey: 'pk_live_...', tools });
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <Thread />
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+`useTalk2ViewRuntime(options)` takes the same connection options as `<T2VProvider>` (`partnerKey`, `baseUrl`, `model`, `debug`, `anonymousAutoStart`) plus `tools` and `systemPrompt`, and creates its own `Talk2View` client — a new one only when `partnerKey`, `baseUrl`, `debug` or `anonymousAutoStart` changes (`requestTimeout` is read once, at creation). `model` is sent with each message rather than baked into the client, so an end-user can switch models from a settings screen without losing the chat. `tools` are registered with the engine when their schemas change, compared by value, so an inline array is fine.
+
+### `useTalk2ViewRuntimeForClient`
+
+For an app that already has a `Talk2View` client — for example from `<T2VProvider>`, so auth and chat state stay shared with the rest of the app — pass it in instead of creating a second one:
+
+```tsx
+import { AssistantRuntimeProvider } from '@assistant-ui/react';
+import { useT2V } from '@talk2view/sdk/react';
+import { useTalk2ViewRuntimeForClient } from '@talk2view/sdk/assistant-ui';
+
+function Chat() {
+  const { t2v } = useT2V(); // from <T2VProvider>
+  const runtime = useTalk2ViewRuntimeForClient(t2v, { tools });
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <Thread />
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+### What maps to what
+
+| assistant-ui | Talk2View SDK |
+| --- | --- |
+| Streaming replies | `DisplayMessage`s from `t2v.messages`, converted per-message by `toThreadMessage()` |
+| Client tools | `tools` registers schemas via `t2v.tools.register()` and handlers via `t2v.tools.handle()` — same as `<Talk2View tools>` |
+| Tool approvals | A `PendingApproval` becomes assistant-ui's own approval card (`allow-once` / `allow-always` / `reject-once`, plus a free-form reason); the decision is sent through `t2v.approveToolCall()` |
+| Attachments | assistant-ui's `AttachmentAdapter` uploads through `t2v.uploadAttachment()` |
+| Stop | assistant-ui's cancel action calls `t2v.stop()` — or, while a tool call is waiting for a decision, denies it with the reason "Cancelled by the user" |
+| Retry | assistant-ui's reload action on the **latest turn** — its reply, or the error card when it failed — calls `t2v.retryLastMessage()`; on an older reply it does nothing, because the SDK can only regenerate the last turn |
+
+Four things do not map, on purpose:
+
+- **Editing tool arguments before approval.** The SDK supports it (`HumanDecision.updatedInput`, used by `<ApprovalCard>` in `/ui`), but the stock assistant-ui approval card has no edit-and-resubmit affordance to drive it from — it can only approve, deny, or attach a free-form reason.
+- **Sign-in UI.** `useTalk2ViewRuntime` only creates a client and a runtime; there is no `<LoginForm>` equivalent. A logged-out visitor gets an anonymous demo session automatically (same default as `<ChatPanel>`), and building your own sign-in UI, or gating the app before it mounts, is on the partner.
+- **The agent's plan.** The planning checklist `<ChatPanel>` shows arrives as a `data` part named `plan` (`{ markdown }`). The stock Thread has no renderer for it, so it is silently not shown; register one to see it: `<MessagePrimitive.Parts components={{ data: { by_name: { plan: PlanView } } }} />`.
+- **Editing and deleting sent messages.** The runtime supplies no `onEdit`/`onDelete`, so the stock Thread's pencil on user messages stays disabled. Remove it from your copy of the Thread if you'd rather not show it.
+
+### Bundle size
+
+`<Thread />` and its dependencies are the partner's own assistant-ui bundle, sized however assistant-ui and its registry components size it; `@talk2view/sdk/assistant-ui` itself adds about 1.9 KB gzipped on top (`dist/assistant-ui/{index,convert}.js`, bundled and minified with esbuild, `react`, `react-dom`, `@assistant-ui/react` and the SDK's own `Talk2View` client marked external since a partner already has them).
+
+---
+
 ## Core API (framework-agnostic)
 
 ### `Talk2View`
@@ -245,7 +422,7 @@ Main entry point. Use this directly for vanilla JS or non-React frameworks.
 ```typescript
 const t2v = new Talk2View({
   partnerKey: 'pk_live_...',          // Required
-  baseUrl: 'https://api.talk2view.com', // Optional
+  baseUrl: 'https://engine.talk2view.com', // Optional, this is the default
   model: 'gpt-4.1-mini',             // Optional
 });
 ```
@@ -254,7 +431,7 @@ const t2v = new Talk2View({
 
 ```typescript
 await t2v.auth.login(email, password)    // Returns User
-await t2v.auth.signup(email, password)   // Returns User
+await t2v.auth.signup(email, password)   // Returns { user, confirmationRequired }
 await t2v.auth.logout()
 t2v.auth.getUser()                       // Returns User | null
 t2v.auth.isAuthenticated()               // Returns boolean
@@ -358,6 +535,24 @@ for await (const event of t2v.chat('Zoom in please')) {
 }
 ```
 
+#### `t2v.warmUp()`
+
+A new end-user's first AI call is slower than the rest: the engine sets up their
+account with the model proxy on first use, which takes a few seconds. Call
+`warmUp()` at the first sign they are going to use the chat — their first
+keystroke, a tap on the mic — and that setup happens while they are still typing.
+
+```ts
+input.addEventListener('input', () => t2v.warmUp(), { once: true });
+```
+
+It is safe to call repeatedly (one request per signed-in end-user), never
+throws, and is a no-op against an engine that predates it. Don't call it when
+the chat merely opens: for a logged-out visitor it starts an anonymous session,
+which counts toward your daily anonymous cap.
+
+`<ChatWidget>`, `<ChatPanel>` and the assistant-ui runtime already do this.
+
 #### `t2v.clearSession()`
 
 Reset the current session. Clears the thread ID so the next `chat()` call starts a fresh conversation.
@@ -379,8 +574,15 @@ const audioModels = await t2v.listAudioModels(); // Speech-to-text models
 
 Transcribe an audio file using the server's speech-to-text service:
 
+Takes a `FormData`, with the fields the engine's `/v1/audio/transcriptions` endpoint accepts (`file`, `model`, and optionally `language`, `translate_to`, `translation_guidance`):
+
 ```typescript
-const result = await t2v.transcribe(audioBlob, 'whisper-1', 'en');
+const form = new FormData();
+form.append('file', audioBlob, 'recording.webm');
+form.append('model', 'faster-whisper-large-turbo-gcp'); // one of listAudioModels()
+form.append('language', 'en');        // optional
+
+const result = await t2v.transcribe(form);
 console.log(result.text);
 ```
 
@@ -492,7 +694,7 @@ Use `enum` to restrict string values:
 The `execute` function receives the AI's arguments as a `Record<string, unknown>` and must return a `Promise<string>`. The returned string is sent back to the AI as the tool's result.
 
 - Return `JSON.stringify(...)` for structured results
-- Throw an error or return an error string if the tool fails — the SDK catches errors and sends them back to the AI as `{ result: "Error: ...", is_error: true }`
+- Throw an error or return an error string if the tool fails — the SDK catches it and sends the message back to the AI as `{ result: '{"error":"..."}', is_error: true }`, so the agent can explain or try something else
 
 ---
 
@@ -523,22 +725,62 @@ To mitigate this:
 
 ---
 
+## Rendering model replies
+
+Treat every model reply as untrusted. Prompt injection through web search, documents, email or tool results can make the model write anything. `<ChatPanel>` renders replies as markdown only, and never loads remote content on its own:
+
+- **Raw HTML** in a reply is shown as text, apart from a bare `<br>`, which is kept so a GFM table cell can break a line (a cell can't hold a literal newline).
+- **Images** become links (`Image: <alt> (<host>)`) that the end-user can choose to open.
+- **Links** open in a new tab with `noopener noreferrer`, and only `http(s)` and `mailto` link destinations are kept.
+
+If you build your own chat UI, render replies the same way:
+
+```tsx
+import { renderSafeMarkdown } from '@talk2view/sdk/ui';
+
+<div dangerouslySetInnerHTML={{ __html: renderSafeMarkdown(reply) }} />
+```
+
+Never pass model output to `innerHTML` or a markdown library's raw HTML output without it.
+
+Call it in the browser (client components): without a DOM it returns the reply as escaped plain text.
+
+## Chat sessions and deploys
+
+A chat session lives in the engine's memory, so a Talk2View deploy, a restart, or eviction under load can end it. The SDK handles most of that for you:
+
+- **Sending a message:** if the session is gone before the reply has started, the SDK opens a new one, re-registers your tools and resends the turn with the conversation so far — nothing from that turn is lost. It emits `sessionRecovered` with the new session id, which you can log.
+- **Answering an approval:** the SDK can't safely resend the tool result, because your handler has already run. It emits one `error` event with `errorType: 'session_lost'` and clears the pending approval, so the end-user can send their message again.
+- **Mid-reply or mid-tool-resume:** if the chat session is lost after the reply has started, or while a tool result is being sent back, the SDK reports `session_lost` and doesn't resend, because the tool handler may already have run.
+
+```ts
+t2v.on('sessionRecovered', (sessionId) => console.info('reconnected', sessionId));
+```
+
+This is why `sendMessage()` and `chat()` take the conversation history: the engine works out which messages are new, so a fresh session continues where the old one stopped.
+
 ## Error Handling
 
 The SDK throws typed errors:
 
-| Error Class | When |
-|-------------|------|
-| `AuthenticationError` | Invalid credentials, expired token |
-| `PartnerKeyError` | Invalid or inactive partner API key |
-| `SessionError` | Session not found or creation failed |
-| `NetworkError` | Network failure, server unreachable |
-| `T2VError` | Base class for all SDK errors |
+| Error Class | When | `err.type` |
+|-------------|------|------------|
+| `AuthenticationError` | Bad credentials, expired or rejected token | `authentication_error` |
+| `PartnerKeyError` | Unknown or inactive partner key | `partner_key_error` |
+| `NetworkError` | Network failure, server unreachable, request timed out | `network_error` |
+| `T2VError` | Base class — and what everything else arrives as | the engine's own type |
+| `SessionError` | Reserved — see below | `session_not_found` |
+
+Every error carries the engine's machine-readable `type`, so `err.type` is the precise test; the classes above are a convenience for the common cases. Types worth knowing that arrive as a plain `T2VError`: `origin_not_allowed` (403 — the request's Origin isn't on your key's allow-list), `not_found` (404), and `rate_limit_exceeded` (429).
 
-All errors extend `T2VError`, which exposes `message`, `type`, `statusCode`, and `code`:
+Some failures never reach a `catch` at all, because they arrive inside the chat stream rather than as a rejected request: a spent anonymous demo budget comes through as an `error` event with `errorType: 'budget_exceeded'`, which the SDK turns into a `demoLimitReached` event rather than an error state. Listen for that instead of trying to catch it.
+
+**On lost chat sessions:** `SessionError` is reserved for a dedicated engine type that isn't in use yet — today a chat session that no longer exists comes back as a `T2VError` with `type: 'not_found'` and `statusCode: 404`. You shouldn't need to catch it: the SDK recovers the session itself where that is safe, and otherwise reports an `error` event with `errorType: 'session_lost'`. See [Chat sessions and deploys](#chat-sessions-and-deploys).
+
+All errors extend `T2VError`, which exposes `message`, `type`, `statusCode`, `code`, and `detail` (the server's raw diagnostic text, kept out of `message` so it never reaches an end-user by accident):
 
 ```typescript
-import { T2VError, AuthenticationError, NetworkError, SessionError } from '@talk2view/sdk';
+import { T2VError, AuthenticationError, NetworkError, PartnerKeyError } from '@talk2view/sdk';
 
 try {
   await t2v.auth.login(email, password);
@@ -547,8 +789,8 @@ try {
     console.log('Bad credentials');
   } else if (err instanceof NetworkError) {
     console.log('Server unreachable');
-  } else if (err instanceof SessionError) {
-    console.log('Session issue:', err.message);
+  } else if (err instanceof PartnerKeyError) {
+    console.log('Check your partner key:', err.message);
   } else if (err instanceof T2VError) {
     // Access the error code for programmatic handling
     console.log(`Error [${err.code}]: ${err.message} (HTTP ${err.statusCode})`);
@@ -575,18 +817,25 @@ const { error: chatError } = useT2VChat({ systemPrompt: '...' });
 | Property | Type | Required | Default | Description |
 |----------|------|----------|---------|-------------|
 | `partnerKey` | `string` | Yes | — | Your partner API key |
-| `baseUrl` | `string` | No | `'http://localhost:8100'` | Talk2View API server URL |
+| `baseUrl` | `string` | No | `'https://engine.talk2view.com'` | Talk2View engine URL |
 | `model` | `string` | No | Server default | LLM model to use |
 | `requestTimeout` | `number` | No | `30000` | HTTP request timeout in ms. Does not apply to SSE streams after connection. |
+| `anonymousAutoStart` | `boolean` | No | `true` | Start an anonymous demo session on the first `chat()` when nobody is signed in. Set `false` to require sign-in. |
+| `debug` | `boolean` | No | `false` | Log streaming events, tool calls, history and state changes to the console. |
 
 ---
 
 ## System Prompts
 
-System prompts set the AI's behavior and context for your application. Pass them to `ChatPanel` or `useT2VChat`:
+System prompts set the AI's behavior and context for your application. Pass one to `<Talk2View>` (the UI components) or to `useT2VChat` (the hooks):
 
 ```tsx
-<ChatPanel systemPrompt="You are a medical imaging assistant. Use the provided tools to control the DICOM viewer." />
+<Talk2View
+  partnerKey="pk_live_..."
+  systemPrompt="You are a medical imaging assistant. Use the provided tools to control the DICOM viewer."
+>
+  <ChatPanel />
+</Talk2View>
 ```
 
 Best practices:
@@ -603,7 +852,7 @@ Here's a complete example integrating Talk2View into a hypothetical drawing app:
 
 ```tsx
 import React, { useRef, useMemo } from 'react';
-import { T2VProvider, ChatPanel } from '@talk2view/sdk/react';
+import { Talk2View, ChatPanel } from '@talk2view/sdk/ui';
 import type { ClientTool } from '@talk2view/sdk';
 import { Canvas } from './Canvas';
 
@@ -656,16 +905,18 @@ function App() {
   ], []);
 
   return (
-    <T2VProvider partnerKey="pk_live_..." baseUrl="https://api.talk2view.com">
+    <Talk2View
+      partnerKey="pk_live_..."
+      tools={tools}
+      systemPrompt="You control a drawing canvas. Use the tools to draw shapes and manage the canvas."
+    >
       <div style={{ display: 'flex', height: '100vh' }}>
         <Canvas ref={canvasRef} style={{ flex: 1 }} />
-        <ChatPanel
-          tools={tools}
-          systemPrompt="You control a drawing canvas. Use the tools to draw shapes and manage the canvas."
-          style={{ width: 360 }}
-        />
+        <div style={{ width: 360 }}>
+          <ChatPanel welcome={{ heading: 'What should I draw?' }} />
+        </div>
       </div>
-    </T2VProvider>
+    </Talk2View>
   );
 }
 ```
@@ -694,16 +945,32 @@ import type {
   RegisterSkillsResponse,
 } from '@talk2view/sdk';
 
-// React types
+// Headless React types
 import type {
   T2VProviderProps,
   UseT2VAuthResult,
   UseT2VChatResult,
   UseT2VToolsResult,
+  UsePartnerConfigResult,
+  UseUserPreferencesResult,
   DisplayMessage,
-  ChatPanelProps,
-  LoginModalProps,
+  ToolStep,
+  PendingApproval,
 } from '@talk2view/sdk/react';
+
+// UI component types
+import type {
+  Talk2ViewProps,
+  ChatPanelProps,
+  ChatWidgetProps,
+} from '@talk2view/sdk/ui';
+
+// assistant-ui runtime
+import { useTalk2ViewRuntime, useTalk2ViewRuntimeForClient } from '@talk2view/sdk/assistant-ui';
+import type {
+  UseTalk2ViewRuntimeOptions, // useTalk2ViewRuntime(options)
+  Talk2ViewRuntimeOptions,    // useTalk2ViewRuntimeForClient(t2v, options)
+} from '@talk2view/sdk/assistant-ui';
 ```
 
 ## Publishing

package/dist/assistant-ui/convert.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Pure mapping from the SDK's chat state onto assistant-ui's message shape.
+ *
+ * assistant-ui renders `ThreadMessageLike`; the SDK keeps `DisplayMessage`.
+ * Everything here is a function of (message, surrounding state) so it can be
+ * unit-tested without React or a runtime.
+ */
+import type { ThreadMessageLike } from '@assistant-ui/react';
+import type { DisplayMessage, HumanDecision, PendingApproval } from '../types.js';
+/** What a message needs to know about the thread around it. */
+export interface ConvertContext {
+    /** True for the newest message — the only one that can be streaming or waiting on a decision. */
+    isLast: boolean;
+    /** A tool call waiting for the end-user; rendered as an approval gate on the last assistant message. */
+    pendingApproval: PendingApproval | null;
+    /** The SDK's error state; shown on the last assistant message. */
+    error: string | null;
+}
+type ThreadPart = Extract<ThreadMessageLike['content'], readonly unknown[]>[number];
+/** Option ids the stock assistant-ui approval card sends back; we map them onto `HumanDecision`. */
+export declare const APPROVAL_OPTION_IDS: {
+    readonly once: "allow-once";
+    readonly always: "allow-always";
+    readonly deny: "reject-once";
+};
+/** Stable id for a completed step: steps carry no id of their own. */
+export declare function stepToolCallId(messageId: string, index: number): string;
+/** The approval gate assistant-ui draws for a tool call that needs a decision. */
+export declare function approvalPart(approval: PendingApproval): ThreadPart;
+/** Convert one SDK message for assistant-ui. */
+export declare function toThreadMessage(msg: DisplayMessage, ctx: ConvertContext): ThreadMessageLike;
+/** Turn the stock approval card's answer into the SDK's `HumanDecision`. */
+export declare function toHumanDecision(response: {
+    approved: boolean;
+    optionId?: string;
+    text?: string;
+    reason?: string;
+}): HumanDecision;
+export {};
+//# sourceMappingURL=convert.d.ts.map

package/dist/assistant-ui/convert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convert.d.ts","sourceRoot":"","sources":["../../src/assistant-ui/convert.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAuB,MAAM,qBAAqB,CAAC;AAClF,OAAO,KAAK,EAAc,cAAc,EAAE,aAAa,EAAE,eAAe,EAAY,MAAM,aAAa,CAAC;AAExG,+DAA+D;AAC/D,MAAM,WAAW,cAAc;IAC7B,iGAAiG;IACjG,MAAM,EAAE,OAAO,CAAC;IAChB,wGAAwG;IACxG,eAAe,EAAE,eAAe,GAAG,IAAI,CAAC;IACxC,kEAAkE;IAClE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAGD,KAAK,UAAU,GAAG,OAAO,CAAC,iBAAiB,CAAC,SAAS,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpF,oGAAoG;AACpG,eAAO,MAAM,mBAAmB;;;;CAItB,CAAC;AAQX,sEAAsE;AACtE,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEvE;AAgBD,kFAAkF;AAClF,wBAAgB,YAAY,CAAC,QAAQ,EAAE,eAAe,GAAG,UAAU,CAelE;AAkCD,gDAAgD;AAChD,wBAAgB,eAAe,CAAC,GAAG,EAAE,cAAc,EAAE,GAAG,EAAE,cAAc,GAAG,iBAAiB,CA0B3F;AAED,4EAA4E;AAC5E,wBAAgB,eAAe,CAAC,QAAQ,EAAE;IACxC,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,aAAa,CAShB"}