@x12i/ai 1.0.0 → 1.1.0

package/README.md

@@ -1,40 +1,531 @@
 # @x12i/ai
 
-Neutral message shape and store contracts for the Unified UI Kit AI chat set.
+Accessible, provider-agnostic AI chat for React, built on the Unified UI Kit.
 
-> **Status: foundation.** This package ships the typed message parts and the
-> `ThreadStore` contract. The chat components (`ChatThread`, `PromptInput`,
-> `ToolCall`, `ApprovalPrompt`, ...) and the provider adapters are not built yet.
+- A **neutral message shape** with typed parts (`text`, `reasoning`, `tool`, `source`, `file`, `data`). Components never import a provider SDK.
+- A **headless core** (no React, no DOM): the thread reducer, stream events, adapters for AI SDK / OpenAI / Anthropic messages, and Markdown-safety helpers. It is safe in server code.
+- **React components** for a whole chat: `ChatThread`, `PromptInput`, `Conversation`, `Message`, `Markdown`, `Reasoning`, `ToolCall`, `ApprovalPrompt`, `Sources` and citations, `Suggestions`, `MessageActions`, `Attachments`, `ErrorBanner` and more.
+- A **`useThread` hook** that runs any async generator of stream events: deltas, stop, errors, regenerate, edit with branches, and human approval of tool calls.
+- Tokens-only styling, logical CSS properties (RTL works), light/dark/density through the kit's themes, `prefers-reduced-motion` and `forced-colors` support.
 
-Components read a neutral message with typed parts (`text`, `reasoning`, `tool`,
-`source`, `file`, `data`), so they never import a provider SDK. Adapters convert
-provider formats, such as Vercel AI SDK message parts, into this shape.
+> This package has no AI SDK dependency. You bring the model; you give the hook an async generator that yields `StreamEvent` objects.
+
+## Install
+
+```sh
+pnpm add @x12i/ai @x12i/ui @x12i/themes react react-dom
+```
+
+`@x12i/ui` and `react` are peer dependencies. `react-markdown` and `remark-gfm` come with the package.
+
+Load the stylesheets once, after the theme:
+
+```css
+@import "@x12i/themes/themes.css";
+@import "@x12i/ui/styles.css";
+@import "@x12i/ai/styles.css";
+```
+
+Wrap your app in the kit's `ThemeProvider` (and optionally `DensityProvider`) from `@x12i/ui`.
+
+## Two entry points
+
+| Import | Contains | Runs where |
+| --- | --- | --- |
+| `@x12i/ai` | Types, `threadReducer`, stream events, adapters, helpers, Markdown URL safety | Anywhere: server, worker, tests. No React, no DOM. |
+| `@x12i/ai/react` | `useThread` and all components | Browser (or a Next.js client boundary). |
+| `@x12i/ai/styles.css` | One stylesheet for every component | Import once. |
+
+`dist/react.js` starts with `"use client"`, so importing it from a React Server Component file works in a framework that honours the directive: the components render as client components. Server components can still import `@x12i/ai` (for example to run an adapter or call `threadReducer`).
+
+### Server rendering
+
+Every component renders on the server without touching `window` or `document`. The only things that differ between server and client are time-dependent: with `showTimestamps`, a message time is formatted with `Intl` in the viewer's time zone, so the server and the browser can disagree. The `<time>` element has `suppressHydrationWarning`; leave `showTimestamps` off, or pass `formatTimestamp` to `Message` if you need stable output.
+
+## Quick start
+
+`useThread` keeps the conversation, runs your provider, and hands `ChatThread` everything it needs through `chatProps`.
+
+```tsx
+import "@x12i/ai/styles.css";
+import { ChatThread, useThread } from "@x12i/ai/react";
+
+export function Chat() {
+  const thread = useThread({
+    // Return (or be) an async generator of stream events.
+    onSend: async ({ messages, signal }) => {
+      const response = await fetch("/api/chat", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ messages }),
+        signal, // aborted when the user presses Stop
+      });
+      if (!response.ok) throw Object.assign(new Error(response.statusText), { status: response.status });
+      return readEvents(response); // see "Writing a provider adapter"
+    },
+  });
+
+  return (
+    <div style={{ blockSize: "40rem" }}>
+      <ChatThread {...thread.chatProps} suggestions={["What can you do?"]} />
+    </div>
+  );
+}
+```
+
+`ChatThread` fills its parent's height (`block-size: 100%`), so give the parent a height. The message list scrolls inside it, and the prompt stays at the bottom.
+
+### Ready-to-paste example with a fake streaming provider
+
+This runs with no backend. It streams reasoning, a tool call, Markdown (a table, a list, code and a Hebrew sentence), then sources with `[1]` citations. Type or pick "Send the summary by mail" to see an approval request; type anything with "fail" or "error" to see the error banner.
+
+```tsx
+import "@x12i/ai/styles.css";
+import type { StreamEvent } from "@x12i/ai";
+import { ChatThread, useThread, type ThreadRequest, type ToolDecisionRequest } from "@x12i/ai/react";
+
+const wait = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+/** Streams text in small pieces, the way a model streams tokens. */
+async function* typeOut(text: string, delay: number): AsyncGenerator<StreamEvent> {
+  for (let index = 0; index < text.length; index += 6) {
+    yield { type: "text-delta", delta: text.slice(index, index + 6) };
+    await wait(delay);
+  }
+}
+
+const REPLY = [
+  "## Quarter summary\n\n",
+  "Revenue grew **12%** [1] while costs stayed flat [2].\n\n",
+  "| Region | Revenue | Change |\n| --- | ---: | ---: |\n| North | 120 | +14% |\n| South | 95 | +9% |\n\n",
+  "Next steps:\n\n- Review the regional gaps\n- Share the summary with finance\n\n",
+  "```ts\nconst total = north + south; // 215\n```\n\n",
+  "שלום! זה סיכום קצר בעברית: ההכנסות עלו בכל האזורים.",
+].join("");
+
+async function* fakeProvider({ text }: ThreadRequest): AsyncGenerator<StreamEvent> {
+  yield { type: "start" };
+
+  yield { type: "reasoning-delta", delta: "The user wants a summary. " };
+  await wait(150);
+  yield { type: "reasoning-delta", delta: "I will check the sources first." };
+  yield { type: "reasoning-end" };
+
+  if (/fail|error/i.test(text)) {
+    await wait(200);
+    yield { type: "error", error: { message: "The fake provider was asked to fail.", kind: "network" } };
+    return;
+  }
+
+  if (/\b(mail|send)/i.test(text)) {
+    yield* typeOut("I can send that summary. I need your approval first.", 20);
+    yield {
+      type: "tool-call",
+      callId: "send-1",
+      name: "send_email",
+      input: { to: "dana@example.com", subject: "Quarter summary" },
+      requiresApproval: true,
+      approvalPrompt: "Send the summary to dana@example.com?",
+    };
+    // The stream ends here. The thread waits for the person to decide.
+    yield { type: "finish", finishReason: "tool-calls" };
+    return;
+  }
+
+  yield { type: "tool-call", callId: "lookup-1", name: "query_sales", input: { quarter: "Q3" } };
+  await wait(400);
+  yield { type: "tool-result", callId: "lookup-1", output: { rows: 2 }, durationMs: 400 };
+
+  yield* typeOut(REPLY, 15);
+  yield { type: "source", id: "s1", title: "Q3 revenue report", url: "https://example.com/q3", snippet: "Revenue by region." };
+  yield { type: "source", id: "s2", title: "Cost memo", url: "https://example.com/costs" };
+  yield { type: "finish", finishReason: "stop", usage: { inputTokens: 42, outputTokens: 180 } };
+}
+
+/** Called after Approve or Deny. What it streams is written into the same reply. */
+async function* afterDecision({ decision, reason }: ToolDecisionRequest): AsyncGenerator<StreamEvent> {
+  if (decision === "approve") {
+    yield { type: "tool-result", callId: "send-1", output: { delivered: true }, durationMs: 300 };
+    yield* typeOut(" Done: the summary was sent.", 20);
+  } else {
+    yield* typeOut(` Understood, I will not send it${reason ? ` (${reason})` : ""}.`, 20);
+  }
+  yield { type: "finish" };
+}
+
+export function FakeChat() {
+  const thread = useThread({ onSend: fakeProvider, onToolDecision: afterDecision });
+
+  return (
+    <div style={{ blockSize: "min(40rem, 85vh)" }}>
+      <ChatThread
+        {...thread.chatProps}
+        suggestions={["Summarize the quarter", "Send the summary by mail", "Simulate a failure"]}
+        followUps={["Compare to last year"]}
+        onFeedback={() => {}}
+      />
+    </div>
+  );
+}
+```
+
+The same file is kept in `test/fake-chat.example.tsx` and exercised by the test suite, so it stays correct.
+
+## Writing a provider adapter
+
+A provider adapter is an async generator that yields `StreamEvent`s. The UI only ever sees those events. A minimal adapter for a server that streams newline-delimited JSON events:
+
+```ts
+import type { StreamEvent } from "@x12i/ai";
+
+export async function* readEvents(response: Response): AsyncGenerator<StreamEvent> {
+  if (!response.body) return;
+  const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
+  let buffer = "";
+  for (;;) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    buffer += value;
+    let newline = buffer.indexOf("\n");
+    while (newline >= 0) {
+      const line = buffer.slice(0, newline).trim();
+      buffer = buffer.slice(newline + 1);
+      if (line !== "") yield JSON.parse(line) as StreamEvent;
+      newline = buffer.indexOf("\n");
+    }
+  }
+}
+```
+
+If your stream already uses another protocol, map each chunk to one or more events (`text-delta`, `tool-call`, ...) in the same way. Unknown event types are ignored, so you can pass extra events through.
+
+Errors you throw (or the stream throws) become `status: "error"` with a typed `kind` (`network`, `rate-limit`, `moderation`, `auth`, `unknown`), worked out from `status` / `statusCode`, `code`, and the message. `toThreadError` is exported if you want the same mapping elsewhere.
+
+## `useThread`
+
+```ts
+const thread = useThread({
+  initialMessages,            // read once, for example loaded from your store
+  onSend,                     // (request) => AsyncIterable<StreamEvent> | void
+  onRegenerate,               // optional; defaults to onSend with trigger "regenerate"
+  onToolDecision,             // (request) => AsyncIterable<StreamEvent> | void, after Approve or Deny
+  onStop, onFinish, onError,  // notifications
+  batch: true,                // one render per animation frame; false renders every event (tests)
+  generateId, now,            // for tests
+});
+```
+
+| Result | Meaning |
+| --- | --- |
+| `messages`, `status`, `error`, `state` | The thread. `status` is `idle`, `submitted`, `streaming` or `error`. `state` also holds the branches. |
+| `send(text, attachments?)` | Adds a user message and asks `onSend` for the reply. Ignored while a reply runs, and when there is neither text nor an attachment. |
+| `stop()` | Aborts the `signal` your handler received, ends the stream, and keeps the text written so far (`message.status === "stopped"`). Tool calls still running are marked `failed` with `errorCode: "aborted"`. |
+| `regenerate()` | Drops the last reply and asks again (also the retry after an error). |
+| `approve(callId, reason?)`, `deny(callId, reason?)`, `decide(...)` | Decides a tool call that needs approval. |
+| `edit(messageId, text, { mode })` | Edits a user message and asks again. `"truncate"` (default) drops what followed; `"branch"` keeps the old version reachable. |
+| `switchBranch(parentId, index)`, `dismissError()`, `clear()`, `setMessages(list)` | State controls. |
+| `dispatch(action)`, `applyEvent(event)` | Escape hatches: apply a reducer action, or one stream event (for example from a WebSocket). |
+| `chatProps` | Spread into `ChatThread`. Stable between unrelated renders. |
+
+The request object your handlers receive:
 
 ```ts
-import { messageText, type Message } from "@x12i/ai";
+interface ThreadRequest {
+  trigger: "send" | "regenerate" | "edit";
+  message: Message | undefined;    // the user message being answered
+  text: string;                    // its text
+  attachments: FilePart[];
+  messages: readonly Message[];    // a snapshot of the whole thread
+  signal: AbortSignal;             // aborted by stop(); pass it to fetch
+}
+
+interface ToolDecisionRequest {
+  callId: string; toolName: string;
+  decision: "approve" | "deny";
+  reason: string | undefined;
+  pending: number;                 // calls still waiting for a decision after this one
+  messages: readonly Message[];
+  signal: AbortSignal;
+}
+```
+
+Behavior worth knowing:
+
+- Events are applied to the state as they arrive and rendered once per animation frame, so a fast stream does not render once per token.
+- If the stream ends without a `finish` event, the message is finished for you.
+- A stop that races a late event is safe: events after `stop()` are ignored.
+- **Approval is never automatic.** A tool call that needs approval stays in `needs-approval` until `approve` or `deny` is called. Decisions run one after another. `pending` is counted when the decision is made, so with two calls waiting you get `1` and then `0`; resume the model only when it is `0`. What `onToolDecision` returns is written into the same assistant message. If the original stream is still open (waiting for the decision), it is left running instead of being aborted.
+
+## Components
+
+All components take `ref`, `className`, and the props of their root element, and a `messages` prop to override their words (see [Internationalization](#internationalization)).
+
+### High level
+
+| Component | Purpose | Key props |
+| --- | --- | --- |
+| `ChatThread` | The whole chat: message list, prompt, errors, suggestions, live announcements. Owns no conversation state. | `messages`, `status`, `error`, `onSend`, `onStop`, `onRegenerate`, `onToolDecision`, `onEdit`, `branches`, `onSwitchBranch`, `onFeedback`, `suggestions`, `followUps`, `renderPart`, `emptyState`, `header`, `disclaimer`, `avatars`, `names`, `showTimestamps`, `showUsage`, `images`, `announce`, `disabled`, `promptProps`, `locale`, `strings`, `conversationRef` |
+| `useThread` | State for `ChatThread` (see above). | |
+
+### Building blocks
 
-const message: Message = {
-  id: "m1",
-  role: "assistant",
-  parts: [{ type: "text", text: "Hello" }],
+| Component | Purpose | Key props |
+| --- | --- | --- |
+| `Conversation` | The scrolling `role="log"`. Follows new content, lets go when you scroll up, shows "Jump to latest". | `stickThreshold`, `onAtBottomChange`, `label`, `handleRef` |
+| `useStickToBottom` | The hook behind it, for your own scroller. | `threshold`, `onAtBottomChange` |
+| `Message` (`ChatMessage`) | One message and its parts. | `message`, `streaming`, `avatar`, `name`, `showTimestamp`, `showUsage`, `renderPart`, `onToolDecision`, `onRetry`, `editing`, `onEditSubmit`, `onEditCancel`, `actions`, `images` |
+| `MessageActions` | Copy, regenerate, edit, thumbs, version navigation. | `text`, `onCopied`, `onRegenerate`, `onEdit`, `feedback`, `onFeedback`, `branch` (`{ index, count, onSelect }`), `disabled`, `children` (extra buttons) |
+| `Markdown` | Safe GFM rendering. | `children`, `streaming`, `headingOffset`, `images`, `allowDataImages`, `transformImageUrl`, `citations`, `sources`, `onLinkClick`, `onCopyCode` |
+| `CodeBlock` | Plain code with a language label and copy button. Always left-to-right. | `code`, `language`, `onCopied` |
+| `Reasoning` | Collapsible reasoning. Open while streaming, folds when done ("Thought for 4s"). | `text`, `streaming`, `durationMs`, `open` / `defaultOpen` / `onOpenChange` |
+| `ToolCall` | Name, state badge, duration, JSON input/output. | `part`, `onDecision`, `renderInput`, `renderOutput` |
+| `ApprovalPrompt` | Allow or refuse an action. Non-modal. | `toolName`, `input`, `prompt`, `onApprove`, `onDeny`, `autoFocus`, `returnFocusTo`, `allowReason`, `renderInput` |
+| `Sources`, `SourceCard`, `Citation`, `SourcesProvider` | The collapsible source list, one source, an inline `[n]` chip, and the provider that connects chips to the list. | `Sources`: `sources`, `open` / `defaultOpen` / `onOpenChange`. `Citation`: `index`, `source`. `SourcesProvider`: `sources`. |
+| `Attachments` | Files of a message: image thumbnails and download chips. | `files` |
+| `PromptInput` | The composer. | `onSubmit`, `value` / `defaultValue` / `onValueChange`, `status`, `onStop`, `disabled`, `maxLength`, `minRows`, `maxRows`, `submitOnEnter`, `stopOnEscape`, `attachments`, `onRemoveAttachment`, `onFiles`, `allowFiles`, `accept`, `maxFiles`, `slashCommands`, `onCommandSelect`, `footer`, `textareaRef` |
+| `Suggestions` | A row of starter or follow-up prompts. | `suggestions`, `onSelect`, `disabled` |
+| `StreamingIndicator` | Three dots (still under reduced motion). | `label` |
+| `ErrorBanner` | Explains a failure by kind, with retry. | `error`, `onRetry`, `onDismiss`, `onEdit`, `showDetail` |
+| `EmptyThread` | Title, line of help, starter suggestions as children. | `title`, `description`, `icon` |
+| `AiMessagesProvider`, `useAiMessages`, `defaultMessages`, `mergeMessages` | Words. | |
+
+Internal controls (the copy button, JSON viewer, disclosure) are private, built from native elements and the kit's `Button`, `IconButton`, `Badge`, `Stack`, `Inline`, `Divider`, `Spinner`, `VisuallyHidden`.
+
+### Custom part renderers
+
+`ChatThread` and `Message` take `renderPart` to change how any part draws. Return `undefined` to use the built-in view, `null` to show nothing, or any node. `data:<kind>` targets one kind of data part and beats `data`. The context carries a `defaultRender()` so you can wrap the default.
+
+```tsx
+import { ChatThread, type PartRenderers } from "@x12i/ai/react";
+
+// Define it outside the component (or memoize it) so message rows are not re-rendered.
+const renderPart: PartRenderers = {
+  "data:chart": (part) => <BarChart aria-label="Revenue by region" values={(part.data as { values: number[] }).values} />,
+  tool: (part, { defaultRender }) =>
+    part.name === "query_sales" ? <SalesTable output={part.output} /> : defaultRender(),
+  reasoning: () => null, // hide reasoning entirely
 };
 
-messageText(message); // "Hello"
+<ChatThread {...thread.chatProps} renderPart={renderPart} />;
+```
+
+Keys: `text`, `reasoning`, `tool`, `sources` (all source parts at once), `files` (all file parts at once), `data`, `data:<kind>`.
+
+A model sends a chart as a data part: `{ type: "data", kind: "chart", data: { values: [3, 1, 4] } }`, or as the stream event `{ type: "data", kind: "chart", data: {...} }`. Data parts with no renderer show as copyable JSON.
+
+## Adapters
+
+Pure functions from provider message arrays to the neutral `Message[]`. They do not import any SDK; they read documented shapes.
+
+```ts
+import { fromAiSdkMessages, fromOpenAIChatMessages, fromAnthropicMessages } from "@x12i/ai";
+
+const fromAiSdk = fromAiSdkMessages(uiMessages);               // Vercel AI SDK UIMessage (v4 and v5 shapes)
+const fromOpenAI = fromOpenAIChatMessages(chatMessages);       // chat.completions messages, tool calls matched to tool results
+const fromAnthropic = fromAnthropicMessages(messages, { system: "You are helpful." });
+```
+
+They map text, reasoning (`reasoning_content`, thinking blocks), tool calls and results (with states), sources, files and usage, skip roles that have no UI (a bare `tool` message is merged into its call), and make ids for messages that have none (`idPrefix` option). `normalizeUsage` and `normalizeFinishReason` are exported for your own adapters.
+
+## Message and part schema
+
+Plain JSON, so a thread can be stored, sent over the wire or restored.
+
+```ts
+interface Message {
+  id: string;
+  role: "user" | "assistant" | "system" | "tool";
+  parts: MessagePart[];
+  status?: "streaming" | "complete" | "error" | "stopped";
+  createdAt?: string;                  // ISO 8601
+  parentId?: string;
+  metadata?: Record<string, unknown>;  // metadata.edited === true shows an "Edited" mark
+  usage?: Usage;                       // inputTokens, outputTokens, totalTokens, reasoningTokens, cachedInputTokens
+  finishReason?: "stop" | "length" | "tool-calls" | "content-filter" | "error" | "other";
+  error?: ThreadError;                 // { message, kind?, code?, retryable? }
+}
+
+type MessagePart =
+  | { type: "text"; text: string }
+  | { type: "reasoning"; text: string; durationMs?: number; startedAt?: number }
+  | { type: "tool"; id: string; name: string; state: ToolState; input?: unknown; output?: unknown;
+      error?: string; errorCode?: string; durationMs?: number; startedAt?: number;
+      approval?: { prompt?: string; reason?: string } }
+  | { type: "source"; id: string; title: string; url: string; snippet?: string }
+  | { type: "file"; id?: string; name: string; mediaType: string; url: string; size?: number }
+  | { type: "data"; kind: string; data: unknown };
+
+type ToolState = "queued" | "running" | "needs-approval" | "approved" | "denied" | "succeeded" | "failed";
+```
+
+Assistant text is rendered as Markdown; user and system text is rendered as plain text. Source parts are shown together under the message, numbered in order; `[1]` in the text links to the first source. A `failed` tool with `errorCode: "aborted"` is shown as "Stopped before it finished", not as an error.
+
+## Stream event reference
+
+The one shape every provider is adapted to. `messageId` on any event is optional.
+
+| Event | Fields | Effect |
+| --- | --- | --- |
+| `start` | `messageId?`, `createdAt?`, `metadata?` | Begins the assistant message. Optional: content that arrives first starts it. |
+| `text-delta` | `delta` | Appends to the text part. |
+| `reasoning-delta` | `delta` | Appends to the reasoning part. |
+| `reasoning-end` | `durationMs?` | Ends the reasoning block. Optional: the first text, tool call or finish ends it. |
+| `tool-call` | `callId`, `name`, `input?`, `requiresApproval?`, `approvalPrompt?`, `state?` | Adds a tool part: `running`, or `needs-approval` when `requiresApproval`. |
+| `tool-update` | `callId`, `state?`, `name?`, `input?`, `output?`, `error?`, `approval?` | Patches a tool part (for example streaming input). |
+| `tool-result` | `callId`, `output?`, `error?`, `durationMs?`, `name?` | `succeeded`, or `failed` when `error` is set. |
+| `source` | `id`, `title`, `url`, `snippet?` | Adds a source. |
+| `file` | `id?`, `name`, `mediaType`, `url`, `size?` | Adds a file. |
+| `data` | `kind`, `data` | Adds a data part. |
+| `finish` | `usage?`, `finishReason?` | Completes the message and returns to `idle`. |
+| `error` | `error` (string or `ThreadError`) | Marks the message and the thread as failed. |
+| `abort` | | The user stopped the response. Content so far is kept. |
+
+Headless helpers: `applyStreamEvent(state, event)`, `applyStreamEvents(state, events)`, `streamEventToAction`, `isTerminalStreamEvent`, `createAbortableStream(source, signal)` (stops quietly when the signal aborts and lets the source clean up), `errorEvent(error)`.
+
+### The reducer
+
+`threadReducer(state, action)` is pure and immutable. State: `{ messages, status, error, activeMessageId, branches }`. Actions include `add-user-message`, `begin-assistant-message`, `append-text`, `append-reasoning`, `end-reasoning`, `start-tool-call`, `update-tool-call`, `finish-tool-call`, `tool-decision`, `add-source`, `add-part`, `attach-files`, `finish`, `error`, `abort`, `regenerate`, `edit-message`, `switch-branch`, `dismiss-error`, `clear`, `set-messages`, `add-message`, and `batch`. Use it without React for server-side thread handling or tests:
+
+```ts
+import { applyStreamEvents, createThreadState, messageText } from "@x12i/ai";
+
+const state = applyStreamEvents(createThreadState(), [
+  { type: "start", messageId: "a1" },
+  { type: "text-delta", delta: "Hello" },
+  { type: "finish" },
+]);
+messageText(state.messages[0]!); // "Hello"
+```
+
+## Keyboard map
+
+| Where | Key | Does |
+| --- | --- | --- |
+| Prompt | `Enter` | Sends (not during IME composition). |
+| Prompt | `Shift+Enter` | New line. |
+| Prompt (`submitOnEnter={false}`) | `Ctrl/Cmd+Enter` | Sends; `Enter` adds a line. |
+| Prompt, while a reply runs | `Escape` | Stops the reply (`stopOnEscape`, default on). |
+| Prompt, slash command list open | `ArrowDown` / `ArrowUp` | Move through commands (wraps). |
+| Prompt, slash command list open | `Enter` or `Tab` | Insert the command. |
+| Prompt, slash command list open | `Escape` | Close the list. |
+| Send / Stop button | `Enter`, `Space` | One button: its name says "Send message" or "Stop generating". |
+| Conversation | `Tab` | Focuses the log so the arrow keys, `PageUp`, `PageDown`, `Home`, `End` scroll it. Scrolling up stops auto-follow; "Jump to latest" resumes it. |
+| Reasoning, tool call, sources, "Show more" | `Enter`, `Space` | Open or close (disclosure button with `aria-expanded`). |
+| Citation `[1]` | `Enter` | Opens the source list and moves focus to that source. |
+| Approval prompt | (appears) | Focus moves to the prompt itself, never to a button (so `Enter` cannot approve by accident). `Tab` reaches the reason field, Approve, then Deny. After a decision, focus returns to where it was, else to the prompt box. |
+| Message editor | `Ctrl/Cmd+Enter` / `Escape` | Save and resend / cancel. Focus goes back to what had it before editing began. |
+| Message actions | `Tab` | Each action is a button in the tab order. No roving focus, no trap. |
+| Code block, table | `Tab` | The scroll region is focusable only when its content overflows. |
+
+## Accessibility notes
+
+- **No focus traps, no modals.** The approval prompt is a non-modal `role="group"` with a label and description. Nothing steals focus, with one exception: an approval prompt takes focus once when it appears, so a keyboard or screen-reader user notices it. It skips this when focus is somewhere else on the page outside the chat (`autoFocus={false}` turns it off), and it never focuses a button. If you are typing in the prompt box at that moment, focus does move (see Limitations).
+- **Live regions are quiet on purpose.** The message list is a `role="log"` with `aria-live="polite"` and `aria-relevant="additions"`. A streaming message is `aria-busy` and its content is `aria-live="off"`, so a screen reader is not read every token. A separate visually hidden `role="status"` in `ChatThread` speaks a reply **once, when it finishes** ("Assistant replied: ...", the plain-text reading of the Markdown, at most 600 characters). It also speaks a stop and a new approval request. `announce="sentences"` speaks each finished sentence while it streams; `announce="off"` speaks nothing (the log still holds everything). History that was already on screen is never spoken. Errors are spoken by the banner's `role="alert"`.
+- **State is in words.** Tool states are badges with text ("Running", "Needs approval", "Done"), never colour alone. Buttons say what they do now ("Send message" / "Stop generating"); thumbs and the like are `aria-pressed` toggles.
+- **Names.** Each message is an `article` named "Message from Assistant"; assistant messages carry an "AI-generated" label for assistive technology. Code blocks are named "Code, ts". External links say "(opens in a new tab)".
+- **Focus rings** come from the kit's focus tokens. Forced-colors mode keeps borders and focus indicators. `prefers-reduced-motion` stops the streaming dots' pulse and makes "Jump to latest" instant.
+- **Tested with axe** (zero violations) on a full `ChatThread` in idle, streaming, waiting, tool-running, approval, error, editing and right-to-left states, and on the playground example. axe in jsdom cannot check colour contrast; contrast comes from the themes.
+
+## Styling and theming
+
+Everything is styled with the kit's `--kit-*` tokens, so a theme change (light, dark, high-contrast, density) restyles the chat. The stylesheet has no hard-coded colours, sizes or physical (`left`/`right`) properties, and **every selector is wrapped in `:where()`**, so any rule of yours wins regardless of order.
+
+Hooks are `data-kit` values plus state attributes:
+
+| Hook (`data-kit="…"`) | State attributes |
+| --- | --- |
+| `ai-chat-thread` | `data-status` (`idle`, `submitted`, `streaming`, `error`) |
+| `ai-conversation`, `ai-conversation-scroller`, `ai-conversation-content`, `ai-message-list`, `ai-jump-to-latest`, `ai-pending` | |
+| `ai-message` (`-main`, `-header`, `-author`, `-label`, `-time`, `-edited`, `-content`, `-avatar`, `-usage`, `-editor`) | `data-role`, `data-status`, `data-streaming` |
+| `ai-message-part` | `data-part` (`text`, `reasoning`, `tool`, `data`, `files`) |
+| `ai-message-status` | `data-status="stopped"` |
+| `ai-markdown` | `data-streaming` |
+| `ai-markdown-link`, `ai-markdown-image` (only when blocked) | `data-blocked` |
+| `ai-markdown-table`, `ai-code-block` (`-header`, `-language`), `ai-json-view` | |
+| `ai-reasoning` | `data-state` (`open` / `closed`), `data-streaming` |
+| `ai-tool-call` | `data-state` (the tool's state: `running`, `needs-approval`, …), `data-open` |
+| `ai-sources`, `ai-source`, `ai-citation` | `data-state` (`ai-sources`: `open` / `closed`); `data-inert` on `ai-citation` and `ai-source-link` when there is no safe link |
+| `ai-approval-prompt` (`-title`, `-description`, `-action`, `-reason`, `-buttons`) | |
+| `ai-prompt-input` (`-row`, `-textarea`, `-footer`, `-counter`, `-commands`, `-drop`) | `data-busy`, `data-disabled`, `data-dragging` |
+| `ai-prompt-attachment` | `data-status` (`ready`, `uploading`, `error`) |
+| `ai-attachments`, `ai-attachment` | `data-kind` (`image`, `file`) on `ai-attachment` |
+| `ai-error-banner` | `data-kind` (`network`, `rate-limit`, `moderation`, `auth`, `unknown`) |
+| `ai-copy` | `data-state` (copy button feedback) |
+| `ai-chat-composer`, `ai-disclaimer`, `ai-message-actions`, `ai-branch-nav`, `ai-suggestions`, `ai-streaming-indicator`, `ai-empty-thread` | |
+
+Reading width: the message column and the prompt are capped at a width of about 14 × the 56 size token. To change it, override `max-inline-size` on `[data-kit="ai-conversation-content"]` and `[data-kit="ai-chat-composer"]`. The prompt's auto-grow uses internal `--_ai-*` properties; set `minRows` and `maxRows` instead of touching them.
+
+For right-to-left pages set `dir="rtl"` on any ancestor: bubbles align to the inline start and end, arrows and branch icons mirror, message text and the prompt use `dir="auto"` so a Hebrew message in an English page (and the reverse) aligns itself, and code blocks, tool names and JSON are always left-to-right.
+
+## Internationalization
+
+No English is hard-coded in the components. Every string comes from a catalog, `defaultMessages` (English), which you can override in three places, from broadest to narrowest:
+
+```tsx
+import { AiMessagesProvider, ChatThread, defaultMessages, mergeMessages } from "@x12i/ai/react";
+
+// 1. Everything under a provider
+<AiMessagesProvider messages={{ send: "Enviar", stop: "Detener" }}>...</AiMessagesProvider>;
+
+// 2. One ChatThread (named `strings`, because `messages` is the list)
+<ChatThread {...thread.chatProps} strings={{ promptLabel: "Mensaje", roles: { user: "Tú", assistant: "Asistente" } }} />;
+
+// 3. One component
+<PromptInput messages={{ send: "Enviar" }} onSubmit={...} />;
 ```
 
+Nested records merge key by key, so you can translate one tool state (`toolStates: { running: "En curso" }`) or one error title (`errorKinds: { network: { title: "Sin conexión" } }`). Strings that include a value are functions, such as `thoughtFor: (duration) => ...`, `characterCount: (count, max) => ...`, `messageFrom: (role) => ...`, so word order can change. Durations and byte sizes use `Intl` with the `locale` prop. See `AiMessages` for the full list.
+
+## Security notes
+
+- **Model output is untrusted.** `Markdown` skips raw HTML completely (no `<script>`, `<img onerror>`, `<iframe>`, no escaped echo). It never uses `dangerouslySetInnerHTML`.
+- **Link allow-list.** Only `http:`, `https:`, `mailto:`, `tel:`, relative paths and `#fragments` become links. `javascript:`, `data:`, `vbscript:`, `file:` and anything else (including obfuscated forms such as mixed case or leading whitespace) render as plain text. External links open with `target="_blank" rel="noopener noreferrer"` and say so to assistive technology.
+- **Images do not auto-load by default.** A remote image in a reply can leak the viewer's IP and reading time to a third party, so the default `images="link"` shows a link. `images="inline"` renders `http(s)` images with `referrerpolicy="no-referrer"` and lazy loading; `"none"` shows only alt text. SVG is never shown inline. `data:` images are blocked unless `allowDataImages` is set, and then only raster formats. `transformImageUrl` lets you route images through your own proxy; its result is checked again.
+- **Footnote ids are scoped** per message, so two replies (or a reply that writes `id`-like text) cannot collide with or hijack each other's anchors.
+- **Approvals are explicit.** The approval prompt shows the exact tool and arguments, never decides on its own, never focuses a button, and `useThread` never resolves a `needs-approval` call without a call to `approve` or `deny`.
+- **Tool input and output are shown as text** (folded after 4,000 characters). Circular structures, `BigInt` and functions are handled without throwing.
+- **No telemetry, no favicon fetches, no network access** from the package. Listing sources never makes a request to the source's site.
+- What `renderPart` returns is your code; sanitize what you draw.
+
+## Design decisions
+
+- **One neutral shape.** Components read typed parts; adapters and stream events translate. The existing message types are only extended (every addition is optional), because `@x12i/flowix-ui` and `@x12i/records` build on them.
+- **Headless first.** The reducer and the stream layer are plain TypeScript, so the same thread logic runs on a server, in a worker or in a test, and the React layer is a thin view.
+- **Streaming never re-parses finished text.** `Markdown` splits text into top-level blocks and memoizes finished ones; only the last block re-parses as tokens arrive. Text with footnotes is rendered as one block because footnotes depend on definitions elsewhere.
+- **Reading comes before reacting.** Auto-follow stops the instant you scroll up and you get a "Jump to latest" button instead of being dragged down.
+- **No syntax highlighting.** A highlighter is a large dependency with a licensing and bundle cost; code blocks are plain, with a language label and a copy button. Pass your own through `renderPart` or wrap `CodeBlock`.
+- **Private controls.** Controls the kit's `@x12i/ui` does not have (copy button, disclosure, JSON viewer, textarea) are small internals built from native elements rather than new public API.
+- **Edit and regenerate.** Regenerate replaces the last reply. Editing a user message replaces it and drops what followed (`truncate`), or keeps the old version as a branch you can step through with `Previous version` / `Next version`.
+
+## Limitations
+
+Honest list of what is not here, or not verified:
+
+- **No virtualization.** Every message renders. It is comfortable to a few hundred messages; for very long threads, window the list yourself and render rows with `Message`.
+- **No ResponseStream animation, artifact panel, `@mentions`, model picker, voice input or text-to-speech, no Mermaid, no math, no syntax highlighting.** Math and diagrams can be added through `renderPart` for a `data` part.
+- **Images in replies are links by default** (see Security notes).
+- **Approvals have no timeout and no "remember my choice".** A call waits until a person decides.
+- **An approval prompt can pull focus out of the prompt box** while the person is typing, because the chat is where it appears. Pass `autoFocus={false}` to `ApprovalPrompt` (when you render it yourself) if that is wrong for your product; the live announcement still tells screen-reader users.
+- **Citation links go one way:** from `[n]` to the source. There is no link back from the source to the citation.
+- **Footnotes make a message one parse block**, so very long replies with footnotes re-parse in full while streaming.
+- **Half-written Markdown** (a table whose separator row has not arrived yet) shows as plain text until it is complete; an unclosed code fence shows as code to the end of the text.
+- **One run per `useThread`.** A new `send` is ignored while a reply runs; use `stop()` first.
+- **Verified with jsdom, Testing Library and axe**, not yet with real screen readers (NVDA, VoiceOver, TalkBack) or in real browsers across devices. Scrolling and auto-grow are tested against stubbed layout metrics.
+- **Contrast** is delegated to the themes and not measured here.
+- With `showTimestamps`, server and client may format the time differently (see Server rendering).
+
 ## Contracts
 
-- `MessageAdapter<Input>`: converts a provider message into a `Message`.
-- `ThreadStore`: the thread component is stateless, so storage and history belong
-  to the app. `@x12i/flowix-ui` has one that keeps each thread as a Flowix fact
-  (`createFlowixThreadStore`), so a conversation survives a reload and every save
-  stays in Flowix's revision history.
-- `DataPart`: structured data a component can render. Tool input and output, and
-  any JSON you attach, can be painted with `@x12i/records`' `RecordView`, which
-  lays out undescribed JSON from its shape.
+- `MessageAdapter<Input>`, `MessagesAdapter<Input>`: convert provider messages into `Message`.
+- `ThreadStore`: the thread component is stateless, so storage and history belong to the app. `@x12i/flowix-ui` has one that keeps each thread as a Flowix fact (`createFlowixThreadStore`), so a conversation survives a reload and every save stays in Flowix's revision history. Load with `initialMessages` or `setMessages`.
+- `DataPart`: structured data a component can render. Tool output, or any JSON you attach as a data part, can be drawn with a component from another package (for example `@x12i/records`' `RecordView`) through `renderPart` (`tool` or `data:<kind>`). This package does not import it.
+
+## Headless exports (`@x12i/ai`)
+
+Types: `Message`, `MessagePart`, `TextPart`, `ReasoningPart`, `ToolPart`, `ToolState`, `ToolApproval`, `SourcePart`, `FilePart`, `DataPart`, `MessageRole`, `MessageStatus`, `Usage`, `FinishReason`, `ErrorKind`, `ThreadError`, `Thread`, `ThreadStore`, `MessageAdapter`, `MessagesAdapter`, `ThreadState`, `ThreadAction`, `ThreadStatus`, `BranchInfo`, `BranchPoint`, `StreamEvent` and each event type.
+
+Functions: `threadReducer`, `createThreadState`, `getBranchInfo`, `getBranchInfoMap`, `isBusy`, `isTerminalToolState`, `lastUserMessage`; `applyStreamEvent`, `applyStreamEvents`, `streamEventToAction`, `isTerminalStreamEvent`, `createAbortableStream`, `errorEvent`; `fromAiSdkMessages`, `fromOpenAIChatMessages`, `fromAnthropicMessages`, `normalizeUsage`, `normalizeFinishReason`; `messageText`, `messageReasoning`, `messageToolCalls`, `messageSources`, `messageFiles`, `messageData`, `pendingApprovals`, `threadPendingApprovals`, `findToolCall`, `isStreaming`, `lastMessageWithRole`; `toThreadError`, `isAbortError`; `parseCitations`, `citedNumbers`; `formatBytes`, `formatDuration`, `formatTokenCount`, `formatUsage`, `mergeUsage`, `totalTokens`, `markdownToPlainText`, `splitCompletedSentences`; `sanitizeUrl`, `sanitizeImageUrl`, `isSafeUrl`, `isExternalUrl`, `getUrlHostname`, `splitMarkdownBlocks`, `SAFE_LINK_PROTOCOLS`, `SAFE_IMAGE_PROTOCOLS`.
 
 ## References
 
-The kit adopts structure and naming from Vercel AI Elements (Apache-2.0),
-assistant-ui (MIT) and prompt-kit (MIT), restyled through tokens, and does not
-depend on any of them at runtime.
+The kit adopts structure and naming from Vercel AI Elements (Apache-2.0), assistant-ui (MIT) and prompt-kit (MIT), restyled through tokens, and does not depend on any of them at runtime.