juneau 0.3.4 → 0.4.0

package/README.md

@@ -1,789 +1,834 @@
-# Juneau
-
-React component library for building AI chat interfaces. Streaming-first, adapter-based, fully themeable.
-
-```tsx
-import { JuneauProvider, AiChatProvider, AiSidebar, createSseAdapter } from 'juneau';
-import 'juneau/dist/style.css';
-
-const adapter = createSseAdapter('/api/chat');
-
-<JuneauProvider>
-  <AiChatProvider adapter={adapter}>
-    <App />
-    <AiSidebar />
-  </AiChatProvider>
-</JuneauProvider>
-```
-
----
-
-## Install
-
-```bash
-npm install juneau
-```
-
-**Peer dependencies:** `react ^18 || ^19`, `react-dom ^18 || ^19`
-
----
-
-## Core concept — the adapter
-
-Juneau never calls any AI API directly. **You own the network layer.** Juneau provides the UI, state, and streaming machinery — you provide an adapter that connects it to your backend.
-
-An adapter is just one method:
-
-```ts
-interface AiBackendAdapter {
-  sendMessage(input: AiAdapterInput): AsyncIterable<AiStreamEvent>;
-}
-```
-
-It receives the conversation history and streams back typed events:
-
-```ts
-type AiStreamEvent =
-  | { type: 'text';  text: string }       // streamed text chunk — append to current bubble
-  | { type: 'part';  part: AiMessagePart } // rich UI block (table, proposal, activity, error)
-  | { type: 'done' }                       // stream finished cleanly
-  | { type: 'error'; message: string }     // stream failed
-```
-
-This means your API keys stay on your backend, you control auth, rate limiting, model selection — Juneau just renders whatever comes back.
-
----
-
-## Built-in adapters
-
-Juneau ships two factory functions so you don't have to write boilerplate streaming code.
-
-### `createSseAdapter(url, options?)` — recommended
-
-For backends that stream **Server-Sent Events (SSE)** — the format used by OpenAI, Anthropic, and most AI API proxies.
-
-The default parser understands OpenAI's streaming format out of the box (`choices[0].delta.content`).
-
-```ts
-import { createSseAdapter } from 'juneau';
-
-// OpenAI-compatible backend — zero config needed:
-const adapter = createSseAdapter('/api/chat');
-
-// With dynamic auth header:
-const adapter = createSseAdapter('/api/chat', {
-  getHeaders: async () => ({
-    Authorization: `Bearer ${await getSessionToken()}`,
-  }),
-});
-
-// Custom request body:
-const adapter = createSseAdapter('/api/chat', {
-  getBody: ({ messages, context }) => ({
-    messages,
-    model: 'gpt-4o',
-    stream: true,
-    temperature: 0.7,
-  }),
-});
-
-// Custom SSE event schema (backend streams { text: "..." } instead of OpenAI format):
-const adapter = createSseAdapter('/api/chat', {
-  parseEvent: (data) => {
-    try {
-      const json = JSON.parse(data);
-      return json.text ? [{ type: 'text', text: json.text }] : [];
-    } catch {
-      return [];
-    }
-  },
-});
-```
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `method` | `string` | `'POST'` | HTTP method |
-| `headers` | `Record<string, string>` | `{}` | Static headers, merged with Content-Type |
-| `getHeaders` | `(input) => Record<string, string>` | — | Dynamic headers, called per request. Merged on top of `headers`. |
-| `getBody` | `(input) => unknown` | `{ messages, context }` | Override request body |
-| `parseEvent` | `(data: string) => AiStreamEvent[]` | OpenAI parser | Parse each `data: ...` SSE line into events |
-
----
-
-### `createFetchStreamAdapter(url, options?)` — for non-SSE backends
-
-For backends that stream **newline-delimited JSON (NDJSON)** or plain text — raw chunked HTTP without SSE formatting.
-
-The default parser expects `{ "text": "..." }` or `{ "done": true }` JSON lines.
-
-```ts
-import { createFetchStreamAdapter } from 'juneau';
-
-// NDJSON backend (streams { text: "..." } lines):
-const adapter = createFetchStreamAdapter('/api/chat');
-
-// Plain text — treat every chunk as raw text:
-const adapter = createFetchStreamAdapter('/api/chat', {
-  parseChunk: (chunk) => chunk ? [{ type: 'text', text: chunk }] : [],
-});
-
-// Custom JSON lines schema:
-const adapter = createFetchStreamAdapter('/api/chat', {
-  parseChunk: (chunk) => {
-    try {
-      const json = JSON.parse(chunk);
-      if (json.error)  return [{ type: 'error', message: json.error }];
-      if (json.done)   return [{ type: 'done' }];
-      if (json.delta)  return [{ type: 'text', text: json.delta }];
-      return [];
-    } catch { return []; }
-  },
-});
-```
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `method` | `string` | `'POST'` | HTTP method |
-| `headers` | `Record<string, string>` | `{}` | Static headers |
-| `getHeaders` | `(input) => Record<string, string>` | — | Dynamic headers, called per request |
-| `getBody` | `(input) => unknown` | `{ messages, context }` | Override request body |
-| `parseChunk` | `(chunk: string) => AiStreamEvent[]` | NDJSON parser | Parse each newline-delimited chunk into events |
-
----
-
-### Writing your own adapter
-
-If neither factory fits, implementing the interface directly takes about 10 lines:
-
-```ts
-import type { AiBackendAdapter } from 'juneau';
-
-export const myAdapter: AiBackendAdapter = {
-  async *sendMessage({ messages, context }) {
-    const res = await fetch('/api/chat', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ messages }),
-    });
-
-    const reader = res.body!.getReader();
-    const decoder = new TextDecoder();
-
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      yield { type: 'text', text: decoder.decode(value) };
-    }
-
-    yield { type: 'done' };
-  },
-};
-```
-
----
-
-### Backend utilities — `juneau/server`
-
-If your backend uses ai-sdk, Juneau ships server-side helpers that eliminate the boilerplate of history mapping, activity streaming, and tool failure recovery. Import from the `/server` subpath — zod stays out of the browser bundle.
-
-```ts
-import { toSdkMessages, createSkillSet, withToolRecovery } from 'juneau/server';
-```
-
-**Full integration in ~15 lines:**
-
-```ts
-import { toSdkMessages, createSkillSet, withToolRecovery } from 'juneau/server';
-import { streamText } from 'ai';
-import { z } from 'zod';
-
-const skillSet = createSkillSet({
-  search: {
-    description: 'Search for records.',
-    input: z.object({ query: z.string() }),
-    labels: {
-      running: { en: 'Searching…',    cs: 'Vyhledávám…' },
-      done:    { en: 'Results found', cs: 'Nalezeno' },
-    },
-    execute: async ({ query }) => db.search(query),
-  },
-}, { language: context.language });
-
-for await (const chunk of withToolRecovery({
-  phase1: () => streamText({ model, system, messages: toSdkMessages(input.messages), tools: skillSet.tools, maxSteps: 1 }),
-  phase2: (ctx) => streamText({ model, system, messages: [...toSdkMessages(input.messages), { role: 'assistant', content: ctx }] }),
-  skillSet,
-})) {
-  res.write(chunk);
-}
-```
-
-#### `toSdkMessages(messages)`
-
-Converts `AiMessage[]` to `CoreMessage[]` for ai-sdk. Extracts text from parts, fixes conversation alternation (no two consecutive user turns), filters empty turns.
-
-#### `createSkillSet(skills, options?)`
-
-Wraps skill definitions into ai-sdk `tools` with a built-in activity buffer. Each tool call automatically emits `running` / `done` / `failed` Juneau wire SSE strings — no manual activity handling needed.
-
-`SkillSet` members: `tools`, `drainActivities()`, `hadFailure`, `failureContext`.
-
-`SkillSetOptions`: `language?` — selects label variant (`'en'` default). `debug?` — emit `console.debug` logs per skill execution (default: `false`).
-
-#### `streamToWire(fullStream, skillSet?, options?)`
-
-Converts ai-sdk `fullStream` to Juneau wire SSE strings. Handles all ai-sdk v7 text chunk types (`text-delta` and `text`), drains activity buffer at the right moment, emits `done` at the end. Pass `{ debug: true }` to log every chunk received from ai-sdk.
-
-#### `withToolRecovery(options)`
-
-Multi-phase pattern for Gemini-style tool calls. Phase 1 streams with tools. Phase 2 triggers only when a tool failed **and** no text was produced — it calls the model without tools and injects the failure context to force a text response. Phase 3 (optional) handles the silent-success case — Gemini 2.5 Flash often treats a successful tool call as its complete response and never writes text. When the tool succeeded but no text was produced, `phase3` receives the full phase 1 message history (resolved from the ai-sdk result's `messages` promise — includes tool-call and tool-result turns, which Gemini requires to accept the history) so a second model call without tools can summarise the result. Errors thrown by phase 2/3 are emitted as wire `error` events instead of a silent `done`. Pass `debug: true` to log phase decisions, the resolved phase 3 history, and the `textProduced` / `hadFailure` state at each decision point.
-
-```ts
-yield* withToolRecovery({
-  phase1: () => streamText({ model, system, messages, tools: skillSet.tools, maxSteps: 2 }),
-  phase2: (ctx) => streamText({ model, system, messages: [...messages, { role: 'assistant', content: ctx }] }),
-  phase3: (fullMessages) => streamText({ model, system, messages: fullMessages }), // no tools — forced text
-  skillSet,
-});
-```
-
----
-
-### Juneau wire protocol — for Juneau-compatible backends
-
-If your backend is built specifically for Juneau (e.g. Tappeer), stream newline-delimited JSON where each line is one of these shapes. Both `createSseAdapter` and `createFetchStreamAdapter` parse this automatically — no custom `parseEvent` or `parseChunk` needed.
-
-```ts
-// Text chunk — appended to the current assistant bubble
-{ "type": "text", "text": "Here is what I found:" }
-
-// Activity — shows AI progress (skill selection, tool calls, etc.)
-// Send the same `id` with a new status to update in-place
-{ "type": "activity", "id": "skill-select", "title": "Selecting skill", "description": "Finding the best skill for this request.", "status": "running" }
-{ "type": "activity", "id": "skill-select", "title": "Skill selected", "description": "Using Document Search.", "status": "done" }
-{ "type": "activity", "id": "doc-search",   "title": "Searching document", "status": "running" }
-{ "type": "activity", "id": "doc-search",   "title": "Document found", "description": "INV-2024-0894", "status": "done" }
-
-// Rich block — table or proposal
-{ "type": "part", "part": { "type": "table", "columns": ["Name", "Amount"], "rows": [...] } }
-{ "type": "part", "part": { "type": "proposal", "proposal": { "id": "...", "title": "..." } } }
-
-// Stream finished cleanly
-{ "type": "done" }
-
-// Stream error — ends the stream
-{ "type": "error", "message": "Something went wrong." }
-```
-
-**Activity `status` values:** `running` | `done` | `failed`
-
-**Activity `id` behaviour:**
-- With `id` — a later event with the same `id` updates the existing row in-place (running → done)
-- Without `id` — each activity appends as a new timeline row
-
-**Activity `metadata`** is an optional opaque object — not rendered by Juneau, available for logging or custom renderers. Use it for internal data (tool name, duration, skill ID) that should not be shown to the user.
-
-`createSseAdapter` also retains OpenAI-format fallback parsing (`choices[0].delta.content`) so it works with both Juneau-compatible backends and standard OpenAI proxies.
-
----
-
-### `mockAdapter` — for development
-
-Shipped for local development. No backend needed — responds to keywords in the message:
-
-| Say... | Gets you... |
-|---|---|
-| `"show"`, `"list"`, `"data"`, `"table"` | A rendered data table |
-| `"suggest"`, `"recommend"`, `"proposal"` | A proposal card with confirm/cancel |
-| `"activity"`, `"progress"`, `"document"` | An activity timeline with running/done states |
-| `"help"`, `"what can you do"` | Capability overview |
-| `"error"`, `"fail"` | Simulated error response |
-| anything else | Explains the available triggers |
-
-```ts
-import { mockAdapter } from 'juneau';
-// Pass to AiChatProvider — see below
-```
-
----
-
-## Providers
-
-### `<JuneauProvider>`
-
-Wrap your app once. Provides theme tokens and UI labels to all Juneau components below it.
-
-```tsx
-import { JuneauProvider, juneauCs } from 'juneau';
-
-<JuneauProvider
-  theme={{ colorPrimary: '#0f766e', colorAccent: '#14b8a6' }}
-  labels={juneauCs}
->
-  {children}
-</JuneauProvider>
-```
-
-| Prop | Type | Description |
-|---|---|---|
-| `theme` | `JuneauTheme` | Override design tokens. Only specified keys are applied. |
-| `labels` | `Partial<JuneauLabels>` | Override UI strings. Omitted keys fall back to English. |
-| `className` | `string` | Added to the root `<div>`. |
-| `style` | `CSSProperties` | Inline styles on the root `<div>`. |
-
----
-
-### `<AiChatProvider>`
-
-Holds the shared conversation state. Wrap your app (or layout) once — any page can then render `<AiSidebar />` without losing conversation history on navigation.
-
-```tsx
-import { AiChatProvider } from 'juneau';
-
-<AiChatProvider
-  adapter={myAdapter}
-  onProposalConfirm={(id, payload) => handleAction(id, payload)}
-  onProposalCancel={(id) => handleDismiss(id)}
->
-  <App />
-</AiChatProvider>
-```
-
-| Prop | Type | Description |
-|---|---|---|
-| `adapter` | `AiBackendAdapter` | **Required.** Your adapter. |
-| `context` | `Record<string, unknown>` | Initial context forwarded to every adapter call. Update per-page via `setContext()`. |
-| `onProposalConfirm` | `(id, payload) => void` | Called when user confirms a proposal card. |
-| `onProposalCancel` | `(id) => void` | Called when user cancels a proposal card. |
-
-**Updating context per page:**
-
-Use `setContext()` from `useAiChatContext()` to tell the AI where the user is on each page. The context is forwarded opaquely to every `adapter.sendMessage` call as `input.context`.
-
-```tsx
-import { useAiChatContext } from 'juneau';
-
-function InvoicesPage() {
-  const { setContext } = useAiChatContext();
-
-  useEffect(() => {
-    setContext({
-      page: 'invoices',
-      availableTools: ['search', 'export'],
-      userRole: 'admin',
-    });
-  }, []);
-
-  return <main>...</main>;
-}
-```
-
----
-
-## Components
-
-### `<AiSidebar>`
-
-Fixed-position chat panel. Reads all state from the nearest `<AiChatProvider>` — renders wherever you place it, conversation persists across navigation.
-
-The sidebar anchors to the bottom-right of the viewport and opens at 60% screen height by default. Users can minimize it to a compact header bar.
-
-```tsx
-<AiSidebar
-  title="AI Assistant"
-  height="70vh"
-/>
-```
-
-| Prop | Type | Description |
-|---|---|---|
-| `title` | `string` | Overrides the `sidebarTitle` label for this instance. |
-| `icon` | `ReactNode` | Override the header + avatar icon. Defaults to a wand icon. |
-| `actions` | `AiInputAction[]` | Toolbar buttons left of send. Pass `[]` to hide entirely. |
-| `sendIcon` | `ReactNode` | Override the send button icon. |
-| `height` | `string` | Height when open. Any CSS value. Defaults to `'60vh'`. |
-| `className` | `string` | Added to the `<aside>` element. |
-| `style` | `CSSProperties` | Inline styles on the `<aside>`. |
-
----
-
-### `<AiChat>`
-
-Headless chat body — message list + input bar + error banner, no surrounding chrome. Use this when you want to embed chat inside your own layout (dashboard panel, modal, full-page view).
-
-The parent is responsible for calling `useAiChat` and passing results down as props.
-
-```tsx
-import { useAiChat, AiChat } from 'juneau';
-
-function MyPage() {
-  const chat = useAiChat({ adapter });
-
-  return (
-    <div className="my-layout">
-      <MySidebar />
-      <AiChat
-        messages={chat.messages}
-        input={chat.input}
-        isLoading={chat.isLoading}
-        error={chat.error}
-        onInputChange={chat.setInput}
-        onSend={chat.sendMessage}
-        onStop={chat.stop}
-        onProposalConfirm={chat.confirmProposal}
-        onProposalCancel={chat.cancelProposal}
-      />
-    </div>
-  );
-}
-```
-
-| Prop | Type | Description |
-|---|---|---|
-| `messages` | `AiMessage[]` | Conversation history. |
-| `input` | `string` | Current textarea value. |
-| `isLoading` | `boolean` | Whether a stream is in progress. |
-| `error` | `string \| null` | Last error message, or `null`. |
-| `onInputChange` | `(value: string) => void` | Input change handler. |
-| `onSend` | `() => void` | Send the current input. |
-| `onStop` | `() => void` | Abort the in-flight stream. Renders a stop button while loading. |
-| `onProposalConfirm` | `(id, payload) => void` | Proposal confirmed. |
-| `onProposalCancel` | `(id) => void` | Proposal cancelled. |
-| `assistantIcon` | `ReactNode` | Override the assistant avatar in all bubbles. |
-| `actions` | `AiInputAction[]` | Toolbar buttons. |
-| `sendIcon` | `ReactNode` | Override send button icon. |
-| `placeholder` | `string` | Input placeholder text. |
-
----
-
-## `useAiChat` hook
-
-For full control over layout and behaviour. Returns everything needed to build a custom chat UI.
-
-```ts
-const {
-  messages,            // AiMessage[] — full conversation history
-  input,               // string — current textarea value
-  setInput,            // (value: string) => void
-  sendMessage,         // () => Promise<void> — sends current input as user message
-  sendMessageWithText, // (text: string) => Promise<void> — send programmatically, no input state change
-  sendGreeting,        // (contextHint: string) => Promise<void> — assistant speaks first, no user bubble shown
-  stop,                // () => void — abort in-flight stream, keep existing messages
-  isLoading,           // boolean — true while streaming
-  isConnecting,        // boolean — true from send until first token arrives
-  error,               // string | null — last error, cleared on next send
-  reset,               // () => void — clear all messages and abort any stream
-  confirmProposal,     // (id: string, payload: unknown) => void
-  cancelProposal,      // (id: string) => void
-} = useAiChat({
-  adapter,             // required
-  context,             // optional — forwarded to every adapter.sendMessage call
-  onProposalConfirm,   // optional — called by confirmProposal
-  onProposalCancel,    // optional — called by cancelProposal
-});
-```
-
-## `useAiChatContext` hook
-
-Reads the shared state from `<AiChatProvider>`. Includes everything from `useAiChat` plus `setContext()`.
-
-```ts
-const {
-  // all useAiChat fields +
-  setContext,  // (ctx: Record<string, unknown>) => void — update context forwarded to adapter
-} = useAiChatContext();
-```
-
-Throws a descriptive error if called outside `<AiChatProvider>`.
-
----
-
-### Useful patterns
-
-**Proactive greeting on mount (`sendGreeting`):**
-
-`sendGreeting(hint)` sends the hint as a `system` role message to the adapter and streams the response as an assistant-only message — no user bubble is added to the conversation. Perfect for page-load summaries where the AI speaks first.
-
-```ts
-const { sendGreeting } = useAiChatContext();
-
-useEffect(() => {
-  sendGreeting(
-    'The user is viewing the Invoices page. ' +
-    'Briefly introduce what you can help with on this page.'
-  );
-}, []);
-```
-
-**Trigger from outside the chat (e.g. clicking a data row):**
-```ts
-const { sendMessageWithText } = useAiChatContext();
-sendMessageWithText(`Summarise order #${order.id} for me`);
-```
-
-**Pass page context to every request:**
-```tsx
-const { setContext } = useAiChatContext();
-
-useEffect(() => {
-  setContext({ pageId: 'invoices', entityId: invoice.id, userRole: 'admin' });
-}, [invoice.id]);
-```
-
-The `context` object lands in `input.context` inside every `adapter.sendMessage` call — use it to inject page-level data without polluting the message history.
-
-**Reading message text in your adapter:**
-
-Don't dig into `parts` manually — use the exported `getMessageText` helper:
-
-```ts
-import { getMessageText } from 'juneau';
-
-async *sendMessage({ messages }) {
-  const lastUser = [...messages].reverse().find(m => m.role === 'user');
-  const text = lastUser ? getMessageText(lastUser) : '';
-  // → plain string, all text parts concatenated
-}
-```
-
-**Auth — bearer token from React context:**
-```ts
-const adapter = createSseAdapter('/api/chat', {
-  getHeaders: async () => ({
-    Authorization: `Bearer ${await getAccessToken()}`,
-  }),
-});
-```
-
-**Auth — session cookie (no extra config needed):**
-
-Cookies are sent automatically by `fetch` to same-origin URLs. Just use `createSseAdapter('/api/chat')` with no headers — the browser attaches the session cookie for you.
-
-For cross-origin backends, add `credentials: 'include'` by writing a custom adapter:
-
-```ts
-const adapter: AiBackendAdapter = {
-  async *sendMessage({ messages }) {
-    const res = await fetch('https://api.example.com/chat', {
-      method: 'POST',
-      credentials: 'include',   // sends cookies cross-origin
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ messages }),
-    });
-    // …stream response
-  },
-};
-```
-
-**Stop button feedback:**
-
-When `onStop` is provided, the send button becomes a stop button while streaming. After the user hits stop, `isLoading` goes false immediately and the existing partial response stays visible in the conversation — there's no error state, the stream just ends cleanly where it was cut.
-
----
-
-## Message parts
-
-Assistant messages are composed of typed **parts**. Text is streamed chunk by chunk; rich UI blocks are emitted as complete `part` events.
-
-| Part type | Emitted as | Rendered by |
-|---|---|---|
-| `text` | `{ type: 'text', text: string }` stream events, accumulated | Markdown via `react-markdown` — safe against XSS |
-| `table` | `{ type: 'part', part: { type: 'table', ... } }` | `AiTablePart` |
-| `proposal` | `{ type: 'part', part: { type: 'proposal', ... } }` | `AiProposalCard` |
-| `activity` | `{ type: 'part', part: { type: 'activity', ... } }` | `AiActivityPart` |
-| `error` | `{ type: 'error', message: string }` or `{ type: 'part', part: { type: 'error', ... } }` | Inline error in bubble |
-
-**Emitting an activity from your adapter:**
-
-Activity parts show the user what the AI is doing while it works — skill selection, document search, tool calls, etc. They have three states: `running`, `done`, `failed`.
-
-```ts
-// Show a running activity
-yield {
-  type: 'part',
-  part: {
-    type: 'activity',
-    id: 'doc-search',           // optional stable ID — enables in-place update
-    title: 'Searching document',
-    description: 'Looking up document by ID.',
-    status: 'running',
-  },
-};
-
-// Later: update the same activity in-place (same id)
-yield {
-  type: 'part',
-  part: {
-    type: 'activity',
-    id: 'doc-search',
-    title: 'Document found',
-    description: 'Found document INV-2024-0894.',
-    status: 'done',
-  },
-};
-```
-
-If `id` is provided, a later activity part with the same `id` updates the previous one in-place instead of appending a new row. Without `id`, activity parts append as a timeline.
-
-**Emitting a proposal from your adapter:**
-```ts
-yield {
-  type: 'part',
-  part: {
-    type: 'proposal',
-    proposal: {
-      id: 'confirm-delete',           // passed back to onProposalConfirm
-      title: 'Delete this item?',
-      description: 'This cannot be undone.',
-      confirmLabel: 'Delete',         // optional, falls back to labels.proposalConfirm
-      cancelLabel: 'Keep',            // optional, falls back to labels.proposalCancel
-      payload: { itemId: 42 },        // anything — you get it back in onProposalConfirm
-    },
-  },
-};
-```
-
-**Emitting a table:**
-```ts
-yield {
-  type: 'part',
-  part: {
-    type: 'table',
-    columns: ['Name', 'Amount', 'Status'],
-    rows: [
-      { Name: 'Item A', Amount: '$1,200', Status: 'Paid' },
-      { Name: 'Item B', Amount: '$840',   Status: 'Pending' },
-    ],
-  },
-};
-```
-
----
-
-## Theming
-
-All visual values are CSS custom properties prefixed `--juneau-`. Override them via `JuneauProvider`:
-
-```tsx
-<JuneauProvider theme={{
-  colorPrimary:  '#1d4ed8',
-  colorAccent:   '#7c3aed',
-  radiusLg:      '16px',
-  fontFamily:    '"Inter", sans-serif',
-}}>
-```
-
-Only keys you specify are overridden — everything else keeps its default. Overrides are scoped to the provider's subtree so multiple providers with different themes can coexist.
-
-### Full theme reference
-
-| Key | CSS variable | Default | Usage |
-|---|---|---|---|
-| `colorPrimary` | `--juneau-color-primary` | `#000000` | Send button, user bubble |
-| `colorPrimaryDark` | `--juneau-color-primary-dark` | `#252528` | Primary hover state |
-| `colorPrimaryLight` | `--juneau-color-primary-light` | `#ECECEC` | Primary tinted backgrounds |
-| `colorAccent` | `--juneau-color-accent` | `#FF49A4` | Header bg, proposal confirm, avatar |
-| `colorAccentDark` | `--juneau-color-accent-dark` | `#FF6BB3` | Accent hover |
-| `colorAccentLight` | `--juneau-color-accent-light` | `#FFF0F7` | Proposal card background |
-| `colorSurface` | `--juneau-color-surface` | `#FFFFFF` | Cards, sidebar, input background |
-| `colorSurfaceRaised` | `--juneau-color-surface-raised` | `#F4F4F6` | Page background, table headers |
-| `colorSurfaceHover` | `--juneau-color-surface-hover` | `#ECECEC` | Row hover |
-| `colorBorder` | `--juneau-color-border` | `#E8E8EC` | Default borders |
-| `colorTextPrimary` | `--juneau-color-text-primary` | `#000000` | Main body text |
-| `colorTextSecondary` | `--juneau-color-text-secondary` | `#474747` | Supporting text |
-| `colorTextMuted` | `--juneau-color-text-muted` | `#474747` | Labels, hints |
-| `colorTextFaint` | `--juneau-color-text-faint` | `#9090A0` | Empty states |
-| `colorTextInverse` | `--juneau-color-text-inverse` | `#FFFFFF` | Text on dark backgrounds |
-| `colorAssistantAvatar` | `--juneau-color-assistant-avatar` | `#FF49A4` | Assistant avatar circle |
-| `radiusSm` | `--juneau-radius-sm` | `6px` | Buttons, small elements |
-| `radiusMd` | `--juneau-radius-md` | `8px` | Inputs, cards |
-| `radiusLg` | `--juneau-radius-lg` | `12px` | Panels, large cards |
-| `fontFamily` | `--juneau-font-family` | system-ui | Font used across all components |
-
----
-
-## i18n / Labels
-
-All UI strings are overridable. Built-in locales: `juneauEn` (default) and `juneauCs`.
-
-```tsx
-import { juneauCs } from 'juneau';
-<JuneauProvider labels={juneauCs}>...</JuneauProvider>
-```
-
-Pass any `Partial<JuneauLabels>` — omitted keys fall back to English:
-
-```tsx
-<JuneauProvider labels={{ sidebarTitle: 'Ask AI', sendMessage: 'Send' }}>
-```
-
-### Full label reference
-
-| Key | Default (EN) | Used in |
-|---|---|---|
-| `sidebarTitle` | `AI Assistant` | `AiChatHeader` title |
-| `minimizeSidebar` | `Minimize` | `AiChatHeader` minimize button |
-| `expandSidebar` | `Expand` | `AiChatHeader` expand button (when minimized) |
-| `inputPlaceholder` | `Ask a question… (Enter to send)` | `AiInput` textarea |
-| `sendMessage` | `Send message` | `AiInput` send button |
-| `stopMessage` | `Stop` | `AiInput` stop button (while streaming) |
-| `emptyStateText` | `How can I help you today?` | `AiMessageList` empty state |
-| `emptyStateHint` | `Try: "Show me the data" or "Can you suggest something?"` | `AiMessageList` empty state hint |
-| `proposalConfirm` | `Confirm` | `AiProposalCard` fallback confirm label |
-| `proposalCancel` | `Cancel` | `AiProposalCard` fallback cancel label |
-| `errorDismiss` | `Dismiss` | `AiError` dismiss button |
-| `actionAddFile` | `Add file` | `AiInput` toolbar |
-| `actionQuickActions` | `Quick actions` | `AiInput` toolbar |
-| `actionNew` | `New` | `AiInput` toolbar |
-| `actionHistory` | `History` | `AiInput` toolbar |
-| `actionRules` | `Rules` | `AiInput` toolbar |
-
----
-
-## Custom toolbar actions
-
-The toolbar buttons left of the send button are fully configurable:
-
-```tsx
-<AiSidebar
-  actions={[
-    {
-      icon: <MyAttachIcon />,
-      label: 'Attach file',
-      onClick: () => openFilePicker(),
-    },
-    {
-      icon: <MyTemplatesIcon />,
-      label: 'Templates',
-      onClick: () => openTemplateMenu(),
-    },
-  ]}
-/>
-
-// Hide the toolbar entirely:
-<AiSidebar actions={[]} />
-```
-
-Each action: `{ icon: ReactNode, label: string, onClick?: () => void }`
-
----
-
-## Security
-
-- **No API keys in the library** — all AI calls happen in your adapter, which calls your backend. Juneau never sees credentials.
-- **XSS-safe markdown** — text parts are rendered via `react-markdown`, which never uses `dangerouslySetInnerHTML`. Malicious model output cannot inject scripts.
-- **No data storage** — Juneau holds conversation state in React memory only. Nothing is persisted or sent anywhere by the library itself.
-
----
-
-## License
-
-MIT
-
----
-
-## Icon attribution
-
-Icons used internally by Juneau are from [Font Awesome Free](https://fontawesome.com) (v6), licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). SVG paths are inlined directly — no runtime dependency on the Font Awesome package.
-
-Icons used: `crow`, `paper-plane`, `paperclip`, `bolt`, `plus`, `clock-rotate-left`, `scroll`, `arrow-rotate-left`, `window-minimize`, `window-restore`.
+# Juneau
+
+React component library for building AI chat interfaces. Streaming-first, adapter-based, fully themeable.
+
+```tsx
+import { JuneauProvider, AiChatProvider, AiSidebar, createSseAdapter } from 'juneau';
+import 'juneau/dist/style.css';
+
+const adapter = createSseAdapter('/api/chat');
+
+<JuneauProvider>
+  <AiChatProvider adapter={adapter}>
+    <App />
+    <AiSidebar />
+  </AiChatProvider>
+</JuneauProvider>
+```
+
+---
+
+## Install
+
+```bash
+npm install juneau
+```
+
+**Peer dependencies:** `react ^18 || ^19`, `react-dom ^18 || ^19`
+
+---
+
+## Core concept — the adapter
+
+Juneau never calls any AI API directly. **You own the network layer.** Juneau provides the UI, state, and streaming machinery — you provide an adapter that connects it to your backend.
+
+An adapter is just one method:
+
+```ts
+interface AiBackendAdapter {
+  sendMessage(input: AiAdapterInput): AsyncIterable<AiStreamEvent>;
+}
+```
+
+It receives the conversation history and streams back typed events:
+
+```ts
+type AiStreamEvent =
+  | { type: 'text';  text: string }       // streamed text chunk — append to current bubble
+  | { type: 'part';  part: AiMessagePart } // rich UI block (table, proposal, activity, error)
+  | { type: 'done' }                       // stream finished cleanly
+  | { type: 'error'; message: string }     // stream failed
+```
+
+This means your API keys stay on your backend, you control auth, rate limiting, model selection — Juneau just renders whatever comes back.
+
+---
+
+## Built-in adapters
+
+Juneau ships two factory functions so you don't have to write boilerplate streaming code.
+
+### `createSseAdapter(url, options?)` — recommended
+
+For backends that stream **Server-Sent Events (SSE)** — the format used by OpenAI, Anthropic, and most AI API proxies.
+
+The default parser understands OpenAI's streaming format out of the box (`choices[0].delta.content`).
+
+```ts
+import { createSseAdapter } from 'juneau';
+
+// OpenAI-compatible backend — zero config needed:
+const adapter = createSseAdapter('/api/chat');
+
+// With dynamic auth header:
+const adapter = createSseAdapter('/api/chat', {
+  getHeaders: async () => ({
+    Authorization: `Bearer ${await getSessionToken()}`,
+  }),
+});
+
+// Custom request body:
+const adapter = createSseAdapter('/api/chat', {
+  getBody: ({ messages, context }) => ({
+    messages,
+    model: 'gpt-4o',
+    stream: true,
+    temperature: 0.7,
+  }),
+});
+
+// Custom SSE event schema (backend streams { text: "..." } instead of OpenAI format):
+const adapter = createSseAdapter('/api/chat', {
+  parseEvent: (data) => {
+    try {
+      const json = JSON.parse(data);
+      return json.text ? [{ type: 'text', text: json.text }] : [];
+    } catch {
+      return [];
+    }
+  },
+});
+```
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `method` | `string` | `'POST'` | HTTP method |
+| `headers` | `Record<string, string>` | `{}` | Static headers, merged with Content-Type |
+| `getHeaders` | `(input) => Record<string, string>` | — | Dynamic headers, called per request. Merged on top of `headers`. |
+| `getBody` | `(input) => unknown` | `{ messages, context }` | Override request body |
+| `parseEvent` | `(data: string) => AiStreamEvent[]` | OpenAI parser | Parse each `data: ...` SSE line into events |
+
+---
+
+### `createFetchStreamAdapter(url, options?)` — for non-SSE backends
+
+For backends that stream **newline-delimited JSON (NDJSON)** or plain text — raw chunked HTTP without SSE formatting.
+
+The default parser expects `{ "text": "..." }` or `{ "done": true }` JSON lines.
+
+```ts
+import { createFetchStreamAdapter } from 'juneau';
+
+// NDJSON backend (streams { text: "..." } lines):
+const adapter = createFetchStreamAdapter('/api/chat');
+
+// Plain text — treat every chunk as raw text:
+const adapter = createFetchStreamAdapter('/api/chat', {
+  parseChunk: (chunk) => chunk ? [{ type: 'text', text: chunk }] : [],
+});
+
+// Custom JSON lines schema:
+const adapter = createFetchStreamAdapter('/api/chat', {
+  parseChunk: (chunk) => {
+    try {
+      const json = JSON.parse(chunk);
+      if (json.error)  return [{ type: 'error', message: json.error }];
+      if (json.done)   return [{ type: 'done' }];
+      if (json.delta)  return [{ type: 'text', text: json.delta }];
+      return [];
+    } catch { return []; }
+  },
+});
+```
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `method` | `string` | `'POST'` | HTTP method |
+| `headers` | `Record<string, string>` | `{}` | Static headers |
+| `getHeaders` | `(input) => Record<string, string>` | — | Dynamic headers, called per request |
+| `getBody` | `(input) => unknown` | `{ messages, context }` | Override request body |
+| `parseChunk` | `(chunk: string) => AiStreamEvent[]` | NDJSON parser | Parse each newline-delimited chunk into events |
+
+---
+
+### Writing your own adapter
+
+If neither factory fits, implementing the interface directly takes about 10 lines:
+
+```ts
+import type { AiBackendAdapter } from 'juneau';
+
+export const myAdapter: AiBackendAdapter = {
+  async *sendMessage({ messages, context }) {
+    const res = await fetch('/api/chat', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ messages }),
+    });
+
+    const reader = res.body!.getReader();
+    const decoder = new TextDecoder();
+
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      yield { type: 'text', text: decoder.decode(value) };
+    }
+
+    yield { type: 'done' };
+  },
+};
+```
+
+---
+
+### Backend utilities — `juneau/server`
+
+If your backend uses ai-sdk, Juneau ships server-side helpers that eliminate the boilerplate of history mapping, activity streaming, and tool failure recovery. Import from the `/server` subpath — zod stays out of the browser bundle.
+
+```ts
+import { toSdkMessages, createSkillSet, withToolRecovery } from 'juneau/server';
+```
+
+**Full integration in ~15 lines:**
+
+```ts
+import { toSdkMessages, createSkillSet, withToolRecovery } from 'juneau/server';
+import { streamText } from 'ai';
+import { z } from 'zod';
+
+const skillSet = createSkillSet({
+  search: {
+    description: 'Search for records.',
+    input: z.object({ query: z.string() }),
+    labels: {
+      running: { en: 'Searching…',    cs: 'Vyhledávám…' },
+      done:    { en: 'Results found', cs: 'Nalezeno' },
+    },
+    execute: async ({ query }) => db.search(query),
+  },
+}, { language: context.language });
+
+for await (const chunk of withToolRecovery({
+  phase1: () => streamText({ model, system, messages: toSdkMessages(input.messages), tools: skillSet.tools, maxSteps: 1 }),
+  phase2: (ctx) => streamText({ model, system, messages: [...toSdkMessages(input.messages), { role: 'assistant', content: ctx }] }),
+  skillSet,
+})) {
+  res.write(chunk);
+}
+```
+
+#### `toSdkMessages(messages)`
+
+Converts `AiMessage[]` to `CoreMessage[]` for ai-sdk. Extracts text from parts, fixes conversation alternation (no two consecutive user turns), filters empty turns.
+
+#### `createSkillSet(skills, options?)`
+
+Wraps skill definitions into ai-sdk `tools` with a built-in activity buffer. Each tool call automatically emits `running` / `done` / `failed` Juneau wire SSE strings — no manual activity handling needed.
+
+`execute` receives a `SkillExecuteContext` as its second argument with an `emit(part)` callback — push custom part wire events into the stream alongside the activities, e.g. an invoice card widget the frontend renders via `renderPart`:
+
+```ts
+execute: async ({ query }, { emit }) => {
+  const inv = await db.findInvoice(query);
+  emit({ type: 'invoice-card', invoiceNumber: inv.number, amount: inv.total });
+  return { found: 1, invoice: inv }; // returned to the model as the tool result
+},
+```
+
+Emitted parts share the activity buffer and are drained by `streamToWire` at the same points — they appear in the stream in emit order, before the model's text response.
+
+`SkillSet` members: `tools`, `drainActivities()`, `hadFailure`, `failureContext`.
+
+`SkillSetOptions`: `language?` — selects label variant (`'en'` default). `debug?` — emit `console.debug` logs per skill execution (default: `false`).
+
+#### `streamToWire(fullStream, skillSet?, options?)`
+
+Converts ai-sdk `fullStream` to Juneau wire SSE strings. Handles all ai-sdk v7 text chunk types (`text-delta` and `text`), drains activity buffer at the right moment, emits `done` at the end. Pass `{ debug: true }` to log every chunk received from ai-sdk.
+
+#### `withToolRecovery(options)`
+
+Multi-phase pattern for Gemini-style tool calls. Phase 1 streams with tools. Phase 2 triggers only when a tool failed **and** no text was produced — it calls the model without tools and injects the failure context to force a text response. Phase 3 (optional) handles the silent-success case — Gemini 2.5 Flash often treats a successful tool call as its complete response and never writes text. When the tool succeeded but no text was produced, `phase3` receives the full phase 1 message history (resolved from the ai-sdk result's `messages` promise — includes tool-call and tool-result turns, which Gemini requires to accept the history) so a second model call without tools can summarise the result. Errors thrown by phase 2/3 are emitted as wire `error` events instead of a silent `done`. Pass `debug: true` to log phase decisions, the resolved phase 3 history, and the `textProduced` / `hadFailure` state at each decision point.
+
+```ts
+yield* withToolRecovery({
+  phase1: () => streamText({ model, system, messages, tools: skillSet.tools, maxSteps: 2 }),
+  phase2: (ctx) => streamText({ model, system, messages: [...messages, { role: 'assistant', content: ctx }] }),
+  phase3: (fullMessages) => streamText({ model, system, messages: fullMessages }), // no tools — forced text
+  skillSet,
+});
+```
+
+---
+
+### Juneau wire protocol — for Juneau-compatible backends
+
+If your backend is built specifically for Juneau (e.g. Tappeer), stream newline-delimited JSON where each line is one of these shapes. Both `createSseAdapter` and `createFetchStreamAdapter` parse this automatically — no custom `parseEvent` or `parseChunk` needed.
+
+```ts
+// Text chunk — appended to the current assistant bubble
+{ "type": "text", "text": "Here is what I found:" }
+
+// Activity — shows AI progress (skill selection, tool calls, etc.)
+// Send the same `id` with a new status to update in-place
+{ "type": "activity", "id": "skill-select", "title": "Selecting skill", "description": "Finding the best skill for this request.", "status": "running" }
+{ "type": "activity", "id": "skill-select", "title": "Skill selected", "description": "Using Document Search.", "status": "done" }
+{ "type": "activity", "id": "doc-search",   "title": "Searching document", "status": "running" }
+{ "type": "activity", "id": "doc-search",   "title": "Document found", "description": "INV-2024-0894", "status": "done" }
+
+// Rich block — table or proposal
+{ "type": "part", "part": { "type": "table", "columns": ["Name", "Amount"], "rows": [...] } }
+{ "type": "part", "part": { "type": "proposal", "proposal": { "id": "...", "title": "..." } } }
+
+// Stream finished cleanly
+{ "type": "done" }
+
+// Stream error — ends the stream
+{ "type": "error", "message": "Something went wrong." }
+```
+
+**Activity `status` values:** `running` | `done` | `failed`
+
+**Activity `id` behaviour:**
+- With `id` — a later event with the same `id` updates the existing row in-place (running → done)
+- Without `id` — each activity appends as a new timeline row
+
+**Activity `metadata`** is an optional opaque object — not rendered by Juneau, available for logging or custom renderers. Use it for internal data (tool name, duration, skill ID) that should not be shown to the user.
+
+`createSseAdapter` also retains OpenAI-format fallback parsing (`choices[0].delta.content`) so it works with both Juneau-compatible backends and standard OpenAI proxies.
+
+---
+
+### `mockAdapter` — for development
+
+Shipped for local development. No backend needed — responds to keywords in the message:
+
+| Say... | Gets you... |
+|---|---|
+| `"show"`, `"list"`, `"data"`, `"table"` | A rendered data table |
+| `"suggest"`, `"recommend"`, `"proposal"` | A proposal card with confirm/cancel |
+| `"activity"`, `"progress"`, `"document"` | An activity timeline with running/done states |
+| `"help"`, `"what can you do"` | Capability overview |
+| `"error"`, `"fail"` | Simulated error response |
+| anything else | Explains the available triggers |
+
+```ts
+import { mockAdapter } from 'juneau';
+// Pass to AiChatProvider — see below
+```
+
+---
+
+## Providers
+
+### `<JuneauProvider>`
+
+Wrap your app once. Provides theme tokens and UI labels to all Juneau components below it.
+
+```tsx
+import { JuneauProvider, juneauCs } from 'juneau';
+
+<JuneauProvider
+  theme={{ colorPrimary: '#0f766e', colorAccent: '#14b8a6' }}
+  labels={juneauCs}
+>
+  {children}
+</JuneauProvider>
+```
+
+| Prop | Type | Description |
+|---|---|---|
+| `theme` | `JuneauTheme` | Override design tokens. Only specified keys are applied. |
+| `labels` | `Partial<JuneauLabels>` | Override UI strings. Omitted keys fall back to English. |
+| `className` | `string` | Added to the root `<div>`. |
+| `style` | `CSSProperties` | Inline styles on the root `<div>`. |
+
+---
+
+### `<AiChatProvider>`
+
+Holds the shared conversation state. Wrap your app (or layout) once — any page can then render `<AiSidebar />` without losing conversation history on navigation.
+
+```tsx
+import { AiChatProvider } from 'juneau';
+
+<AiChatProvider
+  adapter={myAdapter}
+  onProposalConfirm={(id, payload) => handleAction(id, payload)}
+  onProposalCancel={(id) => handleDismiss(id)}
+>
+  <App />
+</AiChatProvider>
+```
+
+| Prop | Type | Description |
+|---|---|---|
+| `adapter` | `AiBackendAdapter` | **Required.** Your adapter. |
+| `context` | `Record<string, unknown>` | Initial context forwarded to every adapter call. Update per-page via `setContext()`. |
+| `onProposalConfirm` | `(id, payload) => void` | Called when user confirms a proposal card. |
+| `onProposalCancel` | `(id) => void` | Called when user cancels a proposal card. |
+
+**Updating context per page:**
+
+Use `setContext()` from `useAiChatContext()` to tell the AI where the user is on each page. The context is forwarded opaquely to every `adapter.sendMessage` call as `input.context`.
+
+```tsx
+import { useAiChatContext } from 'juneau';
+
+function InvoicesPage() {
+  const { setContext } = useAiChatContext();
+
+  useEffect(() => {
+    setContext({
+      page: 'invoices',
+      availableTools: ['search', 'export'],
+      userRole: 'admin',
+    });
+  }, []);
+
+  return <main>...</main>;
+}
+```
+
+---
+
+## Components
+
+### `<AiSidebar>`
+
+Fixed-position chat panel. Reads all state from the nearest `<AiChatProvider>` — renders wherever you place it, conversation persists across navigation.
+
+The sidebar anchors to the bottom-right of the viewport and opens at 60% screen height by default. Users can minimize it to a compact header bar.
+
+```tsx
+<AiSidebar
+  title="AI Assistant"
+  height="70vh"
+/>
+```
+
+| Prop | Type | Description |
+|---|---|---|
+| `title` | `string` | Overrides the `sidebarTitle` label for this instance. |
+| `icon` | `ReactNode` | Override the header + avatar icon. Defaults to a wand icon. |
+| `actions` | `AiInputAction[]` | Toolbar buttons left of send. Pass `[]` to hide entirely. |
+| `sendIcon` | `ReactNode` | Override the send button icon. |
+| `height` | `string` | Height when open. Any CSS value. Defaults to `'60vh'`. |
+| `className` | `string` | Added to the `<aside>` element. |
+| `style` | `CSSProperties` | Inline styles on the `<aside>`. |
+
+---
+
+### `<AiChat>`
+
+Headless chat body — message list + input bar + error banner, no surrounding chrome. Use this when you want to embed chat inside your own layout (dashboard panel, modal, full-page view).
+
+The parent is responsible for calling `useAiChat` and passing results down as props.
+
+```tsx
+import { useAiChat, AiChat } from 'juneau';
+
+function MyPage() {
+  const chat = useAiChat({ adapter });
+
+  return (
+    <div className="my-layout">
+      <MySidebar />
+      <AiChat
+        messages={chat.messages}
+        input={chat.input}
+        isLoading={chat.isLoading}
+        error={chat.error}
+        onInputChange={chat.setInput}
+        onSend={chat.sendMessage}
+        onStop={chat.stop}
+        onProposalConfirm={chat.confirmProposal}
+        onProposalCancel={chat.cancelProposal}
+      />
+    </div>
+  );
+}
+```
+
+| Prop | Type | Description |
+|---|---|---|
+| `messages` | `AiMessage[]` | Conversation history. |
+| `input` | `string` | Current textarea value. |
+| `isLoading` | `boolean` | Whether a stream is in progress. |
+| `error` | `string \| null` | Last error message, or `null`. |
+| `onInputChange` | `(value: string) => void` | Input change handler. |
+| `onSend` | `() => void` | Send the current input. |
+| `onStop` | `() => void` | Abort the in-flight stream. Renders a stop button while loading. |
+| `onProposalConfirm` | `(id, payload) => void` | Proposal confirmed. |
+| `onProposalCancel` | `(id) => void` | Proposal cancelled. |
+| `assistantIcon` | `ReactNode` | Override the assistant avatar in all bubbles. |
+| `actions` | `AiInputAction[]` | Toolbar buttons. |
+| `sendIcon` | `ReactNode` | Override send button icon. |
+| `placeholder` | `string` | Input placeholder text. |
+| `renderPart` | `RenderPartFn` | Custom part renderer — see below. |
+
+---
+
+## Custom part rendering — `renderPart`
+
+Both `AiSidebar` and `AiChat` accept a `renderPart` prop — an escape hatch for rendering consumer-defined part types (or overriding built-in ones):
+
+```ts
+type RenderPartFn = (part: AiMessagePart) => ReactNode | null | undefined;
+```
+
+It is called **before** the built-in renderers for every message part. Return a ReactNode to render it; return `null`/`undefined` to fall through to the built-ins (`text`, `table`, `proposal`, `activity`, `error`).
+
+The backend can stream any custom part through the standard wire protocol:
+
+```json
+{ "type": "part", "part": { "type": "invoice-card", "invoiceNumber": "23251", "amount": "1200.00" } }
+```
+
+`AiCustomPart` (`{ type: string; [key: string]: unknown }`) is part of the `AiMessagePart` union, so TypeScript accepts custom shapes on both ends. Juneau applies **no validation or narrowing** to custom parts — the consumer owns all type assertions:
+
+```tsx
+// Define your part type wherever you like — Juneau doesn't need to know about it
+type InvoiceCardPart = { type: 'invoice-card'; invoiceNumber: string; amount: string };
+
+<AiSidebar renderPart={part => {
+  if (part.type === 'invoice-card') return <InvoiceCard part={part as InvoiceCardPart} />;
+  return null; // everything else falls through to the built-ins
+}} />
+```
+
+Unhandled custom part types show a dashed warning outline in development (so they're never a silent mystery) and render nothing in production.
+
+---
+
+## `useAiChat` hook
+
+For full control over layout and behaviour. Returns everything needed to build a custom chat UI.
+
+```ts
+const {
+  messages,            // AiMessage[] — full conversation history
+  input,               // string — current textarea value
+  setInput,            // (value: string) => void
+  sendMessage,         // () => Promise<void> — sends current input as user message
+  sendMessageWithText, // (text: string) => Promise<void> — send programmatically, no input state change
+  sendGreeting,        // (contextHint: string) => Promise<void> — assistant speaks first, no user bubble shown
+  stop,                // () => void — abort in-flight stream, keep existing messages
+  isLoading,           // boolean — true while streaming
+  isConnecting,        // boolean — true from send until first token arrives
+  error,               // string | null — last error, cleared on next send
+  reset,               // () => void — clear all messages and abort any stream
+  confirmProposal,     // (id: string, payload: unknown) => void
+  cancelProposal,      // (id: string) => void
+} = useAiChat({
+  adapter,             // required
+  context,             // optional — forwarded to every adapter.sendMessage call
+  onProposalConfirm,   // optional — called by confirmProposal
+  onProposalCancel,    // optional — called by cancelProposal
+});
+```
+
+## `useAiChatContext` hook
+
+Reads the shared state from `<AiChatProvider>`. Includes everything from `useAiChat` plus `setContext()`.
+
+```ts
+const {
+  // all useAiChat fields +
+  setContext,  // (ctx: Record<string, unknown>) => void — update context forwarded to adapter
+} = useAiChatContext();
+```
+
+Throws a descriptive error if called outside `<AiChatProvider>`.
+
+---
+
+### Useful patterns
+
+**Proactive greeting on mount (`sendGreeting`):**
+
+`sendGreeting(hint)` sends the hint as a `system` role message to the adapter and streams the response as an assistant-only message — no user bubble is added to the conversation. Perfect for page-load summaries where the AI speaks first.
+
+```ts
+const { sendGreeting } = useAiChatContext();
+
+useEffect(() => {
+  sendGreeting(
+    'The user is viewing the Invoices page. ' +
+    'Briefly introduce what you can help with on this page.'
+  );
+}, []);
+```
+
+**Trigger from outside the chat (e.g. clicking a data row):**
+```ts
+const { sendMessageWithText } = useAiChatContext();
+sendMessageWithText(`Summarise order #${order.id} for me`);
+```
+
+**Pass page context to every request:**
+```tsx
+const { setContext } = useAiChatContext();
+
+useEffect(() => {
+  setContext({ pageId: 'invoices', entityId: invoice.id, userRole: 'admin' });
+}, [invoice.id]);
+```
+
+The `context` object lands in `input.context` inside every `adapter.sendMessage` call — use it to inject page-level data without polluting the message history.
+
+**Reading message text in your adapter:**
+
+Don't dig into `parts` manually — use the exported `getMessageText` helper:
+
+```ts
+import { getMessageText } from 'juneau';
+
+async *sendMessage({ messages }) {
+  const lastUser = [...messages].reverse().find(m => m.role === 'user');
+  const text = lastUser ? getMessageText(lastUser) : '';
+  // → plain string, all text parts concatenated
+}
+```
+
+**Auth — bearer token from React context:**
+```ts
+const adapter = createSseAdapter('/api/chat', {
+  getHeaders: async () => ({
+    Authorization: `Bearer ${await getAccessToken()}`,
+  }),
+});
+```
+
+**Auth — session cookie (no extra config needed):**
+
+Cookies are sent automatically by `fetch` to same-origin URLs. Just use `createSseAdapter('/api/chat')` with no headers — the browser attaches the session cookie for you.
+
+For cross-origin backends, add `credentials: 'include'` by writing a custom adapter:
+
+```ts
+const adapter: AiBackendAdapter = {
+  async *sendMessage({ messages }) {
+    const res = await fetch('https://api.example.com/chat', {
+      method: 'POST',
+      credentials: 'include',   // sends cookies cross-origin
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ messages }),
+    });
+    // …stream response
+  },
+};
+```
+
+**Stop button feedback:**
+
+When `onStop` is provided, the send button becomes a stop button while streaming. After the user hits stop, `isLoading` goes false immediately and the existing partial response stays visible in the conversation — there's no error state, the stream just ends cleanly where it was cut.
+
+---
+
+## Message parts
+
+Assistant messages are composed of typed **parts**. Text is streamed chunk by chunk; rich UI blocks are emitted as complete `part` events.
+
+| Part type | Emitted as | Rendered by |
+|---|---|---|
+| `text` | `{ type: 'text', text: string }` stream events, accumulated | Markdown via `react-markdown` — safe against XSS |
+| `table` | `{ type: 'part', part: { type: 'table', ... } }` | `AiTablePart` |
+| `proposal` | `{ type: 'part', part: { type: 'proposal', ... } }` | `AiProposalCard` |
+| `activity` | `{ type: 'part', part: { type: 'activity', ... } }` | `AiActivityPart` |
+| `error` | `{ type: 'error', message: string }` or `{ type: 'part', part: { type: 'error', ... } }` | Inline error in bubble |
+
+**Emitting an activity from your adapter:**
+
+Activity parts show the user what the AI is doing while it works — skill selection, document search, tool calls, etc. They have three states: `running`, `done`, `failed`.
+
+```ts
+// Show a running activity
+yield {
+  type: 'part',
+  part: {
+    type: 'activity',
+    id: 'doc-search',           // optional stable ID — enables in-place update
+    title: 'Searching document',
+    description: 'Looking up document by ID.',
+    status: 'running',
+  },
+};
+
+// Later: update the same activity in-place (same id)
+yield {
+  type: 'part',
+  part: {
+    type: 'activity',
+    id: 'doc-search',
+    title: 'Document found',
+    description: 'Found document INV-2024-0894.',
+    status: 'done',
+  },
+};
+```
+
+If `id` is provided, a later activity part with the same `id` updates the previous one in-place instead of appending a new row. Without `id`, activity parts append as a timeline.
+
+**Emitting a proposal from your adapter:**
+```ts
+yield {
+  type: 'part',
+  part: {
+    type: 'proposal',
+    proposal: {
+      id: 'confirm-delete',           // passed back to onProposalConfirm
+      title: 'Delete this item?',
+      description: 'This cannot be undone.',
+      confirmLabel: 'Delete',         // optional, falls back to labels.proposalConfirm
+      cancelLabel: 'Keep',            // optional, falls back to labels.proposalCancel
+      payload: { itemId: 42 },        // anything — you get it back in onProposalConfirm
+    },
+  },
+};
+```
+
+**Emitting a table:**
+```ts
+yield {
+  type: 'part',
+  part: {
+    type: 'table',
+    columns: ['Name', 'Amount', 'Status'],
+    rows: [
+      { Name: 'Item A', Amount: '$1,200', Status: 'Paid' },
+      { Name: 'Item B', Amount: '$840',   Status: 'Pending' },
+    ],
+  },
+};
+```
+
+---
+
+## Theming
+
+All visual values are CSS custom properties prefixed `--juneau-`. Override them via `JuneauProvider`:
+
+```tsx
+<JuneauProvider theme={{
+  colorPrimary:  '#1d4ed8',
+  colorAccent:   '#7c3aed',
+  radiusLg:      '16px',
+  fontFamily:    '"Inter", sans-serif',
+}}>
+```
+
+Only keys you specify are overridden — everything else keeps its default. Overrides are scoped to the provider's subtree so multiple providers with different themes can coexist.
+
+### Full theme reference
+
+| Key | CSS variable | Default | Usage |
+|---|---|---|---|
+| `colorPrimary` | `--juneau-color-primary` | `#000000` | Send button, user bubble |
+| `colorPrimaryDark` | `--juneau-color-primary-dark` | `#252528` | Primary hover state |
+| `colorPrimaryLight` | `--juneau-color-primary-light` | `#ECECEC` | Primary tinted backgrounds |
+| `colorAccent` | `--juneau-color-accent` | `#FF49A4` | Header bg, proposal confirm, avatar |
+| `colorAccentDark` | `--juneau-color-accent-dark` | `#FF6BB3` | Accent hover |
+| `colorAccentLight` | `--juneau-color-accent-light` | `#FFF0F7` | Proposal card background |
+| `colorSurface` | `--juneau-color-surface` | `#FFFFFF` | Cards, sidebar, input background |
+| `colorSurfaceRaised` | `--juneau-color-surface-raised` | `#F4F4F6` | Page background, table headers |
+| `colorSurfaceHover` | `--juneau-color-surface-hover` | `#ECECEC` | Row hover |
+| `colorBorder` | `--juneau-color-border` | `#E8E8EC` | Default borders |
+| `colorTextPrimary` | `--juneau-color-text-primary` | `#000000` | Main body text |
+| `colorTextSecondary` | `--juneau-color-text-secondary` | `#474747` | Supporting text |
+| `colorTextMuted` | `--juneau-color-text-muted` | `#474747` | Labels, hints |
+| `colorTextFaint` | `--juneau-color-text-faint` | `#9090A0` | Empty states |
+| `colorTextInverse` | `--juneau-color-text-inverse` | `#FFFFFF` | Text on dark backgrounds |
+| `colorAssistantAvatar` | `--juneau-color-assistant-avatar` | `#FF49A4` | Assistant avatar circle |
+| `radiusSm` | `--juneau-radius-sm` | `6px` | Buttons, small elements |
+| `radiusMd` | `--juneau-radius-md` | `8px` | Inputs, cards |
+| `radiusLg` | `--juneau-radius-lg` | `12px` | Panels, large cards |
+| `fontFamily` | `--juneau-font-family` | system-ui | Font used across all components |
+
+---
+
+## i18n / Labels
+
+All UI strings are overridable. Built-in locales: `juneauEn` (default) and `juneauCs`.
+
+```tsx
+import { juneauCs } from 'juneau';
+<JuneauProvider labels={juneauCs}>...</JuneauProvider>
+```
+
+Pass any `Partial<JuneauLabels>` — omitted keys fall back to English:
+
+```tsx
+<JuneauProvider labels={{ sidebarTitle: 'Ask AI', sendMessage: 'Send' }}>
+```
+
+### Full label reference
+
+| Key | Default (EN) | Used in |
+|---|---|---|
+| `sidebarTitle` | `AI Assistant` | `AiChatHeader` title |
+| `minimizeSidebar` | `Minimize` | `AiChatHeader` minimize button |
+| `expandSidebar` | `Expand` | `AiChatHeader` expand button (when minimized) |
+| `inputPlaceholder` | `Ask a question… (Enter to send)` | `AiInput` textarea |
+| `sendMessage` | `Send message` | `AiInput` send button |
+| `stopMessage` | `Stop` | `AiInput` stop button (while streaming) |
+| `emptyStateText` | `How can I help you today?` | `AiMessageList` empty state |
+| `emptyStateHint` | `Try: "Show me the data" or "Can you suggest something?"` | `AiMessageList` empty state hint |
+| `proposalConfirm` | `Confirm` | `AiProposalCard` fallback confirm label |
+| `proposalCancel` | `Cancel` | `AiProposalCard` fallback cancel label |
+| `errorDismiss` | `Dismiss` | `AiError` dismiss button |
+| `actionAddFile` | `Add file` | `AiInput` toolbar |
+| `actionQuickActions` | `Quick actions` | `AiInput` toolbar |
+| `actionNew` | `New` | `AiInput` toolbar |
+| `actionHistory` | `History` | `AiInput` toolbar |
+| `actionRules` | `Rules` | `AiInput` toolbar |
+
+---
+
+## Custom toolbar actions
+
+The toolbar buttons left of the send button are fully configurable:
+
+```tsx
+<AiSidebar
+  actions={[
+    {
+      icon: <MyAttachIcon />,
+      label: 'Attach file',
+      onClick: () => openFilePicker(),
+    },
+    {
+      icon: <MyTemplatesIcon />,
+      label: 'Templates',
+      onClick: () => openTemplateMenu(),
+    },
+  ]}
+/>
+
+// Hide the toolbar entirely:
+<AiSidebar actions={[]} />
+```
+
+Each action: `{ icon: ReactNode, label: string, onClick?: () => void }`
+
+---
+
+## Security
+
+- **No API keys in the library** — all AI calls happen in your adapter, which calls your backend. Juneau never sees credentials.
+- **XSS-safe markdown** — text parts are rendered via `react-markdown`, which never uses `dangerouslySetInnerHTML`. Malicious model output cannot inject scripts.
+- **No data storage** — Juneau holds conversation state in React memory only. Nothing is persisted or sent anywhere by the library itself.
+
+---
+
+## License
+
+MIT
+
+---
+
+## Icon attribution
+
+Icons used internally by Juneau are from [Font Awesome Free](https://fontawesome.com) (v6), licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). SVG paths are inlined directly — no runtime dependency on the Font Awesome package.
+
+Icons used: `crow`, `paper-plane`, `paperclip`, `bolt`, `plus`, `clock-rotate-left`, `scroll`, `arrow-rotate-left`, `window-minimize`, `window-restore`.