@djangocfg/widget-assistant 0.1.1 → 0.2.1

package/README.md

@@ -29,6 +29,27 @@ It knows nothing about one site (`src/boundary.test.ts` enforces it), so what a
 - **Floating button.** Pops in, shows a message-style hint after a moment (`hint` prop; text defaults to the bundled one), then a ring every so often. No close control; the host decides how often to show it.
 - **Help.** A quiet link under the composer opens the list of keys (`ComposerHelp`).
 
+## The wire (0.2)
+
+One vocabulary, `data: {json with type}\n\n`, decoded only in `wire/frames.ts`:
+
+| Frame | Fields |
+|---|---|
+| `run` | `version`, `thread_id`, `message_id`, `client_id`, `seq` |
+| `status` | `phase`: `thinking` \| `searching` \| `answering` |
+| `text_delta` | `delta` |
+| `ui_payload` | `kind`, `data`: the host draws it through `dataRenderers[kind]`; list the kinds in `payloadKinds` and any other is dropped and reported to `onUnknownPayload` |
+| `done` | `tokens_in`, `tokens_out`, `cost_usd`, `finish_reason`, `replayed?` |
+| `error` | `code` (`unavailable` \| `timeout` \| `failed`), `message`, `retryable` |
+
+An unknown `type` is ignored. `wire/fixtures/events.json` holds one of each frame and is committed on the server side too: drift fails a test on either side. A public chat must not forward `tool_call` / `tool_result`.
+
+`createTransport` takes `streamUrl` (a path, or a function of the send, for a thread id in the path), `buildBody`, `headers`, `streamFetch`, `getToken` (signed in) or `visitorToken` (anonymous, sent as `x-visitor-token`). Omit `api` from `useSession` for an anonymous host: nothing is fetched and the room starts empty. `context` is a plain record the host defines; the package never reads it. `examples/KbAssistant.tsx` is a knowledge-base host with a `citations` payload, the reference the tests mount.
+
 ## Tests
 
 `pnpm --filter @djangocfg/widget-assistant check test`: the wire, stream and boundary tests, and `tsc --noEmit`.
+
+## Migrating from 0.1 (a host that spoke the film frames)
+
+0.2 breaks the wire. In the host's server: `run` carries `thread_id` and `message_id` (not `run_id`, `user_message_id`, `assistant_message_id`); `status.phase` is `thinking|searching|answering` (`reading` and `choosing` are gone); `done` carries no message id; a card payload is `ui_payload {kind: 'film_cards', data}` as before, but the package no longer validates it, so register it: `dataRenderers={{ film_cards: … }}` and `payloadKinds={['film_cards']}`. A stored message has `parts: [{kind, data}]` in place of `widgets: [{kind, ids, caption}]`. `ChatContext` is a plain record (the old `title` and `browse` kinds are the host's to define). `createTransport` still opens `/apix/chat/v1/stream` when no `streamUrl` is given; that default goes in 0.3. The dictionaries lose `statusReading` and `statusChoosing` and gain `statusAnswering`; the bundled `lockedBody` and `hint` no longer talk about films.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/widget-assistant",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "A site assistant on top of @djangocfg/widget-chat: the SSE wire and session layer, a persistent host, docked column, floating button and sheet, dictation, Help and 17 built-in locales",
   "keywords": [
     "chat",
@@ -44,19 +44,19 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@djangocfg/widget-chat": "^0.1.14",
+    "@djangocfg/widget-chat": "^0.1.16",
     "zustand": "^5.0.14"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.585",
-    "@djangocfg/ui-core": "^2.1.585",
+    "@djangocfg/i18n": "^2.1.610",
+    "@djangocfg/ui-core": "^2.1.610",
     "lucide-react": "^0.545.0",
     "react": "^19.0.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.585",
-    "@djangocfg/typescript-config": "^2.1.585",
-    "@djangocfg/ui-core": "^2.1.585",
+    "@djangocfg/i18n": "^2.1.610",
+    "@djangocfg/typescript-config": "^2.1.610",
+    "@djangocfg/ui-core": "^2.1.610",
     "@storybook/react-vite": "^10.5.0",
     "@types/node": "^25.9.5",
     "@types/react": "19.2.15",

package/src/AssistantChat.tsx

@@ -35,7 +35,7 @@ interface Props {
   suggestions: string[];
   /** The room on screen: `id` changes when the thread is reloaded (reconcile, clear), which reseeds the transcript. */
   conversation?: { id?: string; history: readonly ChatMessage[] };
-  /** The host's drawing of structured parts, by `kind` (for example `film_cards`). Unknown kinds fall through to the widget. */
+  /** The host's drawing of structured parts, by `kind` (for example `citations`). Unknown kinds fall through to the widget. */
   dataRenderers?: Readonly<Record<string, DataPartRenderer>>;
   /** Dictation language and its picker (the microphone menu). Absent: the browser's default engine with the widget's default language. */
   speech?: SpeechLanguage;

package/src/examples/KbAssistant.tsx

@@ -0,0 +1,35 @@
+import type { ReactNode } from 'react';
+
+import type { DataPartRenderer } from '../AssistantChat';
+
+/**
+ * A plain knowledge-base host, not a film site: the answer carries a `citations` payload and the host draws it as a numbered list. It is the reference the
+ * tests mount, and the shape a new product copies: the payload kinds it draws, and a renderer per kind.
+ */
+export interface Citation {
+  n: number;
+  title: string;
+  heading_path?: string[];
+  url?: string;
+}
+
+const isCitations = (data: unknown): data is { items: Citation[] } =>
+  typeof data === 'object' && data !== null && Array.isArray((data as { items?: unknown }).items);
+
+export const citationsRenderer: DataPartRenderer = (data): ReactNode | undefined => {
+  if (!isCitations(data) || data.items.length === 0) return undefined;
+  return (
+    <ol className="mt-2 space-y-1 text-sm text-muted-foreground">
+      {data.items.map((item) => (
+        <li key={item.n}>
+          [{item.n}] {item.url ? <a href={item.url}>{item.title}</a> : item.title}
+          {item.heading_path && item.heading_path.length > 1 ? ` — ${item.heading_path.slice(1).join(' › ')}` : ''}
+        </li>
+      ))}
+    </ol>
+  );
+};
+
+/** What the host draws, by `kind`. Pass it as `dataRenderers`, and its keys as `payloadKinds`. */
+export const KB_RENDERERS: Readonly<Record<string, DataPartRenderer>> = { citations: citationsRenderer };
+export const KB_PAYLOAD_KINDS: readonly string[] = Object.keys(KB_RENDERERS);

package/src/i18n/index.ts

@@ -1,6 +1,4 @@
-import { useMemo } from 'react';
-
-import { useLocaleOptional } from '@djangocfg/i18n';
+import { createCopy, type Locale } from '@djangocfg/i18n/copy';
 
 import { ar } from './locales/ar';
 import { da } from './locales/da';
@@ -23,14 +21,16 @@ import type { AssistantCopy } from './types';
 
 export type { AssistantCopy } from './types';
 
-/** Every bundled dictionary, keyed by the language code the app reports; the same seventeen languages as the framework widget. */
-export const ASSISTANT_DICTIONARIES: Readonly<Record<string, AssistantCopy>> = { ar, da, de, en, es, fr, it, ja, ko, nl, no, pl, 'pt-BR': ptBR, ru, sv, tr, zh };
+/** Every bundled dictionary, typed complete over the shared `Locale` union. */
+export const ASSISTANT_DICTIONARIES: Readonly<Record<Locale, AssistantCopy>> = {
+  en, ru, ko, ja, de, fr, zh, it, es, nl, ar, tr, pl, sv, no, da,
+  'pt-BR': ptBR,
+};
+
+const kit = createCopy(ASSISTANT_DICTIONARIES);
 
 /**
- * The assistant's own words for the active language (English for one not yet translated). The host passes no strings: the language comes from the framework's
- * locale provider, the one the widget's built-in composer copy already follows. With no provider (a story, a test) it is English.
+ * The assistant's own words for the active language: the `locale` prop, else the
+ * `@djangocfg/i18n` provider, else English. The host passes no strings.
  */
-export function useAssistantCopy(): AssistantCopy {
-  const locale = useLocaleOptional();
-  return useMemo(() => (locale ? ASSISTANT_DICTIONARIES[locale] ?? en : en), [locale]);
-}
+export const useAssistantCopy = kit.useCopy;

package/src/i18n/locales/ar.ts

@@ -4,14 +4,13 @@ export const ar: AssistantCopy = {
   close: 'إغلاق',
   resize: 'تغيير عرض المساعد',
   lockedTitle: 'سجّل الدخول للدردشة',
-  lockedBody: 'يختار المساعد الأفلام لك ويتذكر المحادثة. سجّل الدخول للبدء.',
+  lockedBody: 'يجيب المساعد من مستنداتك ويتذكر المحادثة. سجّل الدخول للبدء.',
   lockedComposer: 'سجّل الدخول لتسأل',
   signIn: 'تسجيل الدخول',
-  hint: 'نتحدث عن الأفلام مع الذكاء الاصطناعي؟',
+  hint: 'اسأل المساعد؟',
   statusThinking: 'أفكر…',
-  statusSearching: 'أبحث في الكتالوج…',
-  statusReading: 'أقرأ عن الأفلام…',
-  statusChoosing: 'أختار الأفضل…',
+  statusSearching: 'أبحث…',
+  statusAnswering: 'أكتب الإجابة…',
   errAuth: 'سجّل الدخول لتسأل المساعد.',
   errBusy: 'أنهِ أولاً في التبويب الآخر.',
   errInvalid: 'الرسالة طويلة جدًا. اختصرها وأعد المحاولة.',

package/src/i18n/locales/da.ts

@@ -4,14 +4,13 @@ export const da: AssistantCopy = {
   close: 'Luk',
   resize: 'Skift assistentens bredde',
   lockedTitle: 'Log ind for at chatte',
-  lockedBody: 'Assistenten vælger film til dig og husker samtalen. Log ind for at komme i gang.',
+  lockedBody: 'Assistenten svarer ud fra dine dokumenter og husker samtalen. Log ind for at starte.',
   lockedComposer: 'Log ind for at spørge',
   signIn: 'Log ind',
-  hint: 'Skal vi snakke film med AI?',
+  hint: 'Spørg assistenten?',
   statusThinking: 'Tænker…',
-  statusSearching: 'Søger i kataloget…',
-  statusReading: 'Læser om filmene…',
-  statusChoosing: 'Vælger de bedste…',
+  statusSearching: 'Søger…',
+  statusAnswering: 'Skriver svaret…',
   errAuth: 'Log ind for at spørge assistenten.',
   errBusy: 'Afslut først i den anden fane.',
   errInvalid: 'Beskeden er for lang. Forkort den og prøv igen.',

package/src/i18n/locales/de.ts

@@ -4,14 +4,13 @@ export const de: AssistantCopy = {
   close: 'Schließen',
   resize: 'Breite des Assistenten ändern',
   lockedTitle: 'Anmelden, um zu chatten',
-  lockedBody: 'Der Assistent wählt Filme für dich aus und merkt sich das Gespräch. Melde dich an, um zu starten.',
+  lockedBody: 'Der Assistent antwortet aus deinen Dokumenten und merkt sich das Gespräch. Melde dich an, um zu starten.',
   lockedComposer: 'Anmelden, um zu fragen',
   signIn: 'Anmelden',
-  hint: 'Über Filme mit KI sprechen?',
+  hint: 'Den Assistenten fragen?',
   statusThinking: 'Ich denke nach…',
-  statusSearching: 'Durchsuche den Katalog…',
-  statusReading: 'Lese über die Filme…',
-  statusChoosing: 'Wähle die besten aus…',
+  statusSearching: 'Suche…',
+  statusAnswering: 'Schreibe die Antwort…',
   errAuth: 'Melde dich an, um den Assistenten zu fragen.',
   errBusy: 'Beende zuerst die Antwort im anderen Tab.',
   errInvalid: 'Die Nachricht ist zu lang. Kürze sie und versuche es erneut.',

package/src/i18n/locales/en.ts

@@ -4,14 +4,13 @@ export const en: AssistantCopy = {
   close: 'Close',
   resize: 'Resize the assistant',
   lockedTitle: 'Sign in to chat',
-  lockedBody: 'The assistant picks films for you and remembers the conversation. Sign in to start.',
+  lockedBody: 'The assistant answers from your documents and remembers the conversation. Sign in to start.',
   lockedComposer: 'Sign in to ask anything',
   signIn: 'Sign in',
-  hint: 'Talk films with AI?',
+  hint: 'Ask the assistant?',
   statusThinking: 'Thinking…',
-  statusSearching: 'Searching the catalog…',
-  statusReading: 'Reading about the films…',
-  statusChoosing: 'Choosing the best ones…',
+  statusSearching: 'Searching…',
+  statusAnswering: 'Writing the answer…',
   errAuth: 'Sign in to ask the assistant.',
   errBusy: 'Finish in the other tab first.',
   errInvalid: 'That message is too long. Shorten it and try again.',

package/src/i18n/locales/es.ts

@@ -4,14 +4,13 @@ export const es: AssistantCopy = {
   close: 'Cerrar',
   resize: 'Cambiar el ancho del asistente',
   lockedTitle: 'Inicia sesión para chatear',
-  lockedBody: 'El asistente elige películas para ti y recuerda la conversación. Inicia sesión para empezar.',
+  lockedBody: 'El asistente responde con tus documentos y recuerda la conversación. Inicia sesión para empezar.',
   lockedComposer: 'Inicia sesión para preguntar',
   signIn: 'Iniciar sesión',
-  hint: '¿Hablamos de películas con la IA?',
+  hint: '¿Preguntar al asistente?',
   statusThinking: 'Pensando…',
-  statusSearching: 'Buscando en el catálogo…',
-  statusReading: 'Leyendo sobre las películas…',
-  statusChoosing: 'Eligiendo las mejores…',
+  statusSearching: 'Buscando…',
+  statusAnswering: 'Escribiendo la respuesta…',
   errAuth: 'Inicia sesión para preguntar al asistente.',
   errBusy: 'Termina primero en la otra pestaña.',
   errInvalid: 'El mensaje es demasiado largo. Acórtalo e inténtalo de nuevo.',

package/src/i18n/locales/fr.ts

@@ -4,14 +4,13 @@ export const fr: AssistantCopy = {
   close: 'Fermer',
   resize: 'Redimensionner l’assistant',
   lockedTitle: 'Connectez-vous pour discuter',
-  lockedBody: 'L’assistant choisit des films pour vous et se souvient de la conversation. Connectez-vous pour commencer.',
+  lockedBody: 'L’assistant répond à partir de vos documents et se souvient de la conversation. Connectez-vous pour commencer.',
   lockedComposer: 'Connectez-vous pour demander',
   signIn: 'Se connecter',
-  hint: 'On parle films avec l’IA ?',
+  hint: 'Demander à l’assistant ?',
   statusThinking: 'Je réfléchis…',
-  statusSearching: 'Recherche dans le catalogue…',
-  statusReading: 'Lecture sur les films…',
-  statusChoosing: 'Je choisis les meilleurs…',
+  statusSearching: 'Recherche…',
+  statusAnswering: 'Rédaction de la réponse…',
   errAuth: 'Connectez-vous pour interroger l\'assistant.',
   errBusy: 'Terminez d\'abord dans l\'autre onglet.',
   errInvalid: 'Ce message est trop long. Raccourcissez-le et réessayez.',

package/src/i18n/locales/it.ts

@@ -4,14 +4,13 @@ export const it: AssistantCopy = {
   close: 'Chiudi',
   resize: 'Ridimensiona l’assistente',
   lockedTitle: 'Accedi per chattare',
-  lockedBody: 'L’assistente sceglie i film per te e ricorda la conversazione. Accedi per iniziare.',
+  lockedBody: 'L’assistente risponde dai tuoi documenti e ricorda la conversazione. Accedi per iniziare.',
   lockedComposer: 'Accedi per chiedere',
   signIn: 'Accedi',
-  hint: 'Parliamo di film con l’IA?',
+  hint: 'Chiedere all’assistente?',
   statusThinking: 'Sto pensando…',
-  statusSearching: 'Cerco nel catalogo…',
-  statusReading: 'Leggo i film…',
-  statusChoosing: 'Scelgo i migliori…',
+  statusSearching: 'Cerco…',
+  statusAnswering: 'Scrivo la risposta…',
   errAuth: 'Accedi per chiedere all\'assistente.',
   errBusy: 'Prima termina nell\'altra scheda.',
   errInvalid: 'Il messaggio è troppo lungo. Accorcialo e riprova.',

package/src/i18n/locales/ja.ts

@@ -4,14 +4,13 @@ export const ja: AssistantCopy = {
   close: '閉じる',
   resize: 'アシスタントの幅を変更',
   lockedTitle: 'チャットするにはサインイン',
-  lockedBody: 'アシスタントがあなたに合う映画を選び、会話を覚えています。サインインして始めましょう。',
+  lockedBody: 'アシスタントはあなたの資料から答え、会話を覚えています。ログインして始めましょう。',
   lockedComposer: '質問するにはサインイン',
   signIn: 'サインイン',
-  hint: 'AIと映画の話をしませんか？',
+  hint: 'アシスタントに聞いてみる？',
   statusThinking: '考え中…',
-  statusSearching: 'カタログを検索中…',
-  statusReading: '作品について調べ中…',
-  statusChoosing: 'おすすめを選んでいます…',
+  statusSearching: '検索中…',
+  statusAnswering: '回答を作成中…',
   errAuth: 'アシスタントに聞くにはログインしてください。',
   errBusy: '先に別のタブでの回答をお待ちください。',
   errInvalid: 'メッセージが長すぎます。短くして再試行してください。',

package/src/i18n/locales/ko.ts

@@ -4,14 +4,13 @@ export const ko: AssistantCopy = {
   close: '닫기',
   resize: '어시스턴트 너비 조절',
   lockedTitle: '채팅하려면 로그인하세요',
-  lockedBody: '어시스턴트가 영화를 골라 주고 대화를 기억합니다. 시작하려면 로그인하세요.',
+  lockedBody: '어시스턴트가 문서를 바탕으로 답하고 대화를 기억합니다. 로그인하여 시작하세요.',
   lockedComposer: '질문하려면 로그인하세요',
   signIn: '로그인',
-  hint: 'AI와 영화 이야기 나눠볼까요?',
+  hint: '어시스턴트에게 물어볼까요?',
   statusThinking: '생각 중…',
-  statusSearching: '카탈로그에서 찾는 중…',
-  statusReading: '영화 정보를 읽는 중…',
-  statusChoosing: '가장 좋은 작품을 고르는 중…',
+  statusSearching: '검색 중…',
+  statusAnswering: '답변 작성 중…',
   errAuth: '어시스턴트에게 물으려면 로그인하세요.',
   errBusy: '다른 탭에서 먼저 끝내 주세요.',
   errInvalid: '메시지가 너무 깁니다. 줄여서 다시 시도하세요.',

package/src/i18n/locales/nl.ts

@@ -4,14 +4,13 @@ export const nl: AssistantCopy = {
   close: 'Sluiten',
   resize: 'Breedte van de assistent aanpassen',
   lockedTitle: 'Log in om te chatten',
-  lockedBody: 'De assistent kiest films voor je en onthoudt het gesprek. Log in om te beginnen.',
+  lockedBody: 'De assistent antwoordt op basis van je documenten en onthoudt het gesprek. Log in om te beginnen.',
   lockedComposer: 'Log in om te vragen',
   signIn: 'Inloggen',
-  hint: 'Praten over films met AI?',
+  hint: 'De assistent iets vragen?',
   statusThinking: 'Even nadenken…',
-  statusSearching: 'Zoeken in de catalogus…',
-  statusReading: 'Lezen over de films…',
-  statusChoosing: 'De beste kiezen…',
+  statusSearching: 'Zoeken…',
+  statusAnswering: 'Antwoord schrijven…',
   errAuth: 'Log in om de assistent te vragen.',
   errBusy: 'Rond eerst af in het andere tabblad.',
   errInvalid: 'Dat bericht is te lang. Maak het korter en probeer opnieuw.',

package/src/i18n/locales/no.ts

@@ -4,14 +4,13 @@ export const no: AssistantCopy = {
   close: 'Lukk',
   resize: 'Endre bredden på assistenten',
   lockedTitle: 'Logg inn for å chatte',
-  lockedBody: 'Assistenten velger filmer for deg og husker samtalen. Logg inn for å komme i gang.',
+  lockedBody: 'Assistenten svarer ut fra dokumentene dine og husker samtalen. Logg inn for å starte.',
   lockedComposer: 'Logg inn for å spørre',
   signIn: 'Logg inn',
-  hint: 'Skal vi snakke film med AI?',
+  hint: 'Spørre assistenten?',
   statusThinking: 'Tenker…',
-  statusSearching: 'Søker i katalogen…',
-  statusReading: 'Leser om filmene…',
-  statusChoosing: 'Velger de beste…',
+  statusSearching: 'Søker…',
+  statusAnswering: 'Skriver svaret…',
   errAuth: 'Logg inn for å spørre assistenten.',
   errBusy: 'Fullfør først i den andre fanen.',
   errInvalid: 'Meldingen er for lang. Kort den ned og prøv igjen.',

package/src/i18n/locales/pl.ts

@@ -4,14 +4,13 @@ export const pl: AssistantCopy = {
   close: 'Zamknij',
   resize: 'Zmień szerokość asystenta',
   lockedTitle: 'Zaloguj się, aby czatować',
-  lockedBody: 'Asystent wybiera filmy dla Ciebie i pamięta rozmowę. Zaloguj się, aby zacząć.',
+  lockedBody: 'Asystent odpowiada na podstawie Twoich dokumentów i pamięta rozmowę. Zaloguj się, aby zacząć.',
   lockedComposer: 'Zaloguj się, aby zapytać',
   signIn: 'Zaloguj się',
-  hint: 'Pogadamy o filmach z AI?',
+  hint: 'Zapytać asystenta?',
   statusThinking: 'Myślę…',
-  statusSearching: 'Przeszukuję katalog…',
-  statusReading: 'Czytam o filmach…',
-  statusChoosing: 'Wybieram najlepsze…',
+  statusSearching: 'Szukam…',
+  statusAnswering: 'Piszę odpowiedź…',
   errAuth: 'Zaloguj się, aby zapytać asystenta.',
   errBusy: 'Najpierw dokończ w drugiej karcie.',
   errInvalid: 'Wiadomość jest za długa. Skróć ją i spróbuj ponownie.',

package/src/i18n/locales/pt-BR.ts

@@ -4,14 +4,13 @@ export const ptBR: AssistantCopy = {
   close: 'Fechar',
   resize: 'Redimensionar o assistente',
   lockedTitle: 'Entre para conversar',
-  lockedBody: 'O assistente escolhe filmes para você e lembra da conversa. Entre para começar.',
+  lockedBody: 'O assistente responde com base nos seus documentos e lembra da conversa. Entre para começar.',
   lockedComposer: 'Entre para perguntar',
   signIn: 'Entrar',
-  hint: 'Vamos falar de filmes com a IA?',
+  hint: 'Perguntar ao assistente?',
   statusThinking: 'Pensando…',
-  statusSearching: 'Buscando no catálogo…',
-  statusReading: 'Lendo sobre os filmes…',
-  statusChoosing: 'Escolhendo os melhores…',
+  statusSearching: 'Buscando…',
+  statusAnswering: 'Escrevendo a resposta…',
   errAuth: 'Entre para perguntar ao assistente.',
   errBusy: 'Termine primeiro na outra aba.',
   errInvalid: 'A mensagem é longa demais. Encurte e tente de novo.',

package/src/i18n/locales/ru.ts

@@ -4,14 +4,13 @@ export const ru: AssistantCopy = {
   close: 'Закрыть',
   resize: 'Изменить ширину ассистента',
   lockedTitle: 'Войдите, чтобы пообщаться',
-  lockedBody: 'Ассистент подбирает фильмы и помнит разговор. Войдите, чтобы начать.',
+  lockedBody: 'Ассистент отвечает по вашим документам и помнит разговор. Войдите, чтобы начать.',
   lockedComposer: 'Войдите, чтобы задать вопрос',
   signIn: 'Войти',
-  hint: 'Обсудим фильм с ИИ?',
+  hint: 'Спросить ассистента?',
   statusThinking: 'Думаю…',
-  statusSearching: 'Ищу в каталоге…',
-  statusReading: 'Читаю про фильмы…',
-  statusChoosing: 'Выбираю лучшее…',
+  statusSearching: 'Ищу…',
+  statusAnswering: 'Пишу ответ…',
   errAuth: 'Войдите, чтобы спросить ассистента.',
   errBusy: 'Сначала завершите ответ в другой вкладке.',
   errInvalid: 'Сообщение слишком длинное. Сократите и повторите.',

package/src/i18n/locales/sv.ts

@@ -4,14 +4,13 @@ export const sv: AssistantCopy = {
   close: 'Stäng',
   resize: 'Ändra assistentens bredd',
   lockedTitle: 'Logga in för att chatta',
-  lockedBody: 'Assistenten väljer filmer åt dig och minns samtalet. Logga in för att börja.',
+  lockedBody: 'Assistenten svarar utifrån dina dokument och minns samtalet. Logga in för att börja.',
   lockedComposer: 'Logga in för att fråga',
   signIn: 'Logga in',
-  hint: 'Ska vi prata film med AI?',
+  hint: 'Fråga assistenten?',
   statusThinking: 'Funderar…',
-  statusSearching: 'Söker i katalogen…',
-  statusReading: 'Läser om filmerna…',
-  statusChoosing: 'Väljer de bästa…',
+  statusSearching: 'Söker…',
+  statusAnswering: 'Skriver svaret…',
   errAuth: 'Logga in för att fråga assistenten.',
   errBusy: 'Avsluta först i den andra fliken.',
   errInvalid: 'Meddelandet är för långt. Korta ner det och försök igen.',

package/src/i18n/locales/tr.ts

@@ -4,14 +4,13 @@ export const tr: AssistantCopy = {
   close: 'Kapat',
   resize: 'Asistanın genişliğini değiştir',
   lockedTitle: 'Sohbet için giriş yapın',
-  lockedBody: 'Asistan sizin için film seçer ve konuşmayı hatırlar. Başlamak için giriş yapın.',
+  lockedBody: 'Asistan belgelerinizden yanıt verir ve konuşmayı hatırlar. Başlamak için giriş yapın.',
   lockedComposer: 'Sormak için giriş yapın',
   signIn: 'Giriş yap',
-  hint: 'Yapay zekayla filmleri konuşalım mı?',
+  hint: 'Asistana soralım mı?',
   statusThinking: 'Düşünüyorum…',
-  statusSearching: 'Katalogda arıyorum…',
-  statusReading: 'Filmleri okuyorum…',
-  statusChoosing: 'En iyilerini seçiyorum…',
+  statusSearching: 'Arıyorum…',
+  statusAnswering: 'Yanıtı yazıyorum…',
   errAuth: 'Asistana sormak için giriş yapın.',
   errBusy: 'Önce diğer sekmede bitirin.',
   errInvalid: 'Mesaj çok uzun. Kısaltıp tekrar deneyin.',

package/src/i18n/locales/zh.ts

@@ -4,14 +4,13 @@ export const zh: AssistantCopy = {
   close: '关闭',
   resize: '调整助手宽度',
   lockedTitle: '登录后即可聊天',
-  lockedBody: '助手会为你挑选电影并记住对话。登录后开始使用。',
+  lockedBody: '助手会根据你的文档回答，并记住对话。登录后开始。',
   lockedComposer: '登录后提问',
   signIn: '登录',
-  hint: '和 AI 聊聊电影？',
+  hint: '问问助手？',
   statusThinking: '思考中…',
-  statusSearching: '正在搜索片库…',
-  statusReading: '正在查阅影片资料…',
-  statusChoosing: '正在挑选最佳影片…',
+  statusSearching: '正在搜索…',
+  statusAnswering: '正在撰写回答…',
   errAuth: '请登录后向助手提问。',
   errBusy: '请先在另一个标签页完成。',
   errInvalid: '消息太长，请缩短后重试。',

package/src/i18n/sessionCopy.ts

@@ -24,7 +24,7 @@ function rejectedText(copy: AssistantCopy, error: ChatHttpError): string {
 export function sessionCopyFor(copy: AssistantCopy): SessionCopy {
   return {
     messages: { rejected: (error) => rejectedText(copy, error), streamError: () => copy.failed, failed: copy.failed },
-    status: { thinking: copy.statusThinking, searching: copy.statusSearching, reading: copy.statusReading, choosing: copy.statusChoosing },
+    status: { thinking: copy.statusThinking, searching: copy.statusSearching, answering: copy.statusAnswering },
     failedText: copy.failed,
   };
 }

package/src/i18n/types.ts

@@ -13,8 +13,7 @@ export interface AssistantCopy {
   /** What the assistant is doing while an answer streams. */
   statusThinking: string;
   statusSearching: string;
-  statusReading: string;
-  statusChoosing: string;
+  statusAnswering: string;
   /** One plain sentence per refusal or failure. */
   errAuth: string;
   errBusy: string;

package/src/index.ts

@@ -13,5 +13,7 @@ export { reconcile, type Reconciled } from './stream/reconcile';
 export { fromStored, fromStoredThread } from './stream/fromStored';
 export { createTransport, ChatHttpError, ChatNetworkError, type ChatTransport, type RejectCode, type SendInput, type TransportConfig } from './wire/transport';
 export { StreamLostError } from './wire/parseSSE';
+export { decodeFrame, WIRE_VERSION } from './wire/frames';
 export type { ChatContext, Frame, Phase, StreamErrorCode } from './wire/frames';
-export type { StoredConversation, StoredMessage, StoredStatus, StoredWidget } from './wire/stored';
+export type { StoredConversation, StoredMessage, StoredPart, StoredStatus } from './wire/stored';
+export { citationsRenderer, KB_RENDERERS, KB_PAYLOAD_KINDS, type Citation } from './examples/KbAssistant';

package/src/stream/adapter.ts

@@ -12,6 +12,9 @@ export interface AdapterDeps {
   onStatus: (phase: Phase | null) => void;
   /** A refusal before any frame (401, 409, 422, 429, 503): the host reacts (invitation, countdown, hide the entry point). */
   onRejected?: (error: ChatHttpError) => void;
+  /** The `kind`s the host draws. A live `ui_payload` of another kind is dropped and reported to `onUnknownPayload`. Absent: every kind is forwarded. */
+  payloadKinds?: readonly string[];
+  onUnknownPayload?: (kind: string) => void;
   /** The stream ended without a terminal frame: the host reconciles from the server. */
   onInterrupted?: () => void;
   /** A network-level failure, for the connectivity monitor. */
@@ -74,7 +77,7 @@ export function createStreamAdapter(deps: AdapterDeps): ChatAdapter {
             switch (frame.type) {
               case 'run':
                 unsent = null;
-                open(frame.assistant_message_id);
+                open(frame.message_id);
                 break;
               case 'status':
                 deps.onStatus(frame.phase);
@@ -91,6 +94,10 @@ export function createStreamAdapter(deps: AdapterDeps): ChatAdapter {
                 break;
               case 'ui_payload':
                 if (!messageId) break;
+                if (deps.payloadKinds && !deps.payloadKinds.includes(frame.kind)) {
+                  deps.onUnknownPayload?.(frame.kind);
+                  break;
+                }
                 flush();
                 textPart = null;
                 controller.enqueue({ type: 'data', part: { type: 'data', id: `${messageId}:w${parts++}`, kind: frame.kind, data: frame.data } });

package/src/stream/fromStored.ts

@@ -2,19 +2,15 @@ import type { ChatMessage, MessagePart } from '@djangocfg/widget-chat';
 
 import type { StoredMessage } from '../wire/stored.ts';
 
-/** The card widget kind (the one the host renders); stored widgets of another kind are skipped, as live ones are. */
-const FILM_CARDS = 'film_cards';
-
 /**
  * A stored message as a widget message. A `running` or `cancelled` one reads as interrupted: the thread never shows a spinner without a stream behind it
- * (a running message is resolved by `reconcile`, which reseeds the thread when the server finishes it).
+ * (a running message is resolved by `reconcile`, which reseeds the thread when the server finishes it). Parts are kept whatever their `kind`: the host's
+ * renderers draw the kinds they know, as for a live answer.
  */
 export function fromStored(message: StoredMessage, failedText: string): ChatMessage {
   const parts: MessagePart[] = [];
   if (message.text) parts.push({ id: `${message.id}:t`, type: 'text', text: message.text });
-  message.widgets.forEach((widget, index) => {
-    if (widget.kind === FILM_CARDS && widget.ids.length > 0) parts.push({ id: `${message.id}:w${index}`, type: 'data', kind: FILM_CARDS, data: { ids: widget.ids, caption: widget.caption } });
-  });
+  message.parts.forEach((part, index) => parts.push({ id: `${message.id}:w${index}`, type: 'data', kind: part.kind, data: part.data }));
   const status: ChatMessage['status'] =
     message.status === 'done' ? { state: 'complete' } : message.status === 'error' ? { state: 'failed', message: failedText } : { state: 'interrupted' };
   return { id: message.id, role: message.role, parts, status, createdAt: Date.parse(message.created_at) || 0 };

package/src/stream/useSession.ts

@@ -14,7 +14,7 @@ import { createStreamAdapter, type AdapterDeps } from './adapter.ts';
 import { fromStoredThread } from './fromStored.ts';
 import { reconcile } from './reconcile.ts';
 
-/** The conversation endpoints (`GET`/`DELETE /apix/chat/v1/conversation`), supplied by the app. */
+/** The conversation endpoints, supplied by the app (signed-in hosts). */
 export interface ThreadApi {
   load: (signal: AbortSignal) => Promise<StoredConversation>;
   clear: () => Promise<void>;
@@ -30,10 +30,14 @@ export interface SessionCopy {
 
 export interface SessionDeps {
   transport: ChatTransport;
-  api: ThreadApi;
+  /** Absent: an anonymous session. Nothing is fetched, the room starts empty, and a lost stream cannot be reconciled (the notice offers Retry). */
+  api?: ThreadApi;
   getContext: () => ChatContext | undefined;
   /** Absent: the bundled words for the active language. */
   copy?: SessionCopy;
+  /** The `kind`s the host draws; any other live payload is dropped and reported. */
+  payloadKinds?: readonly string[];
+  onUnknownPayload?: (kind: string) => void;
   onRejected?: (error: ChatHttpError) => void;
   onNetworkFailure?: () => void;
 }
@@ -79,9 +83,11 @@ export function useSession(given: SessionDeps): Session {
     live.current?.abort();
     const controller = new AbortController();
     live.current = controller;
-    setThread({ kind: 'loading' });
     setNotice(null);
-    ref.current.api.load(controller.signal).then(
+    const api = ref.current.api;
+    if (!api) return seed({ id: null, messages: [] });
+    setThread({ kind: 'loading' });
+    api.load(controller.signal).then(
       (conversation) => !controller.signal.aborted && seed(conversation),
       () => !controller.signal.aborted && setThread({ kind: 'error' }),
     );
@@ -98,6 +104,8 @@ export function useSession(given: SessionDeps): Session {
         transport: deps.transport,
         getContext: () => ref.current.getContext(),
         onStatus: setPhase,
+        payloadKinds: deps.payloadKinds,
+        onUnknownPayload: (kind) => ref.current.onUnknownPayload?.(kind),
         onRejected: (error) => ref.current.onRejected?.(error),
         onNetworkFailure: () => ref.current.onNetworkFailure?.(),
         messages: {
@@ -109,9 +117,11 @@ export function useSession(given: SessionDeps): Session {
         },
         onInterrupted: () => {
           setNotice('reconnecting');
+          const api = ref.current.api;
+          if (!api) return setNotice('stalled');
           const controller = new AbortController();
           live.current = controller;
-          reconcile({ fetchConversation: ref.current.api.load, signal: controller.signal }).then(
+          reconcile({ fetchConversation: api.load, signal: controller.signal }).then(
             (result) => {
               if (controller.signal.aborted) return;
               if (result.outcome === 'timeout') return setNotice('stalled');
@@ -123,11 +133,11 @@ export function useSession(given: SessionDeps): Session {
         },
       }),
     // The transport is one per mounted chat; everything else is read through `ref`.
-    [deps.transport, seed],
+    [deps.transport, deps.payloadKinds, seed],
   );
 
   const clear = useCallback(async () => {
-    await ref.current.api.clear();
+    await ref.current.api?.clear();
     live.current?.abort();
     seed({ id: null, messages: [] });
   }, [seed]);

package/src/wire/fixtures/events.json

@@ -0,0 +1,18 @@
+{
+  "_note": "One of each frame the server speaks. The Python side (django_cfg agent bus events) commits the same file in its own tests; a drift fails a test on either side.",
+  "frames": [
+    { "type": "run", "version": 1, "thread_id": "5f0c8a52-7f0e-4c43-9a43-0e3b5a0d2f11", "message_id": "9b1e2c7a-4a0f-4d52-8d0d-3f1f6c9a7e22", "client_id": "c0a8e1d2-8f2e-4b7e-a1c4-6f5d8c1b2a33", "seq": 2 },
+    { "type": "status", "phase": "thinking" },
+    { "type": "status", "phase": "searching" },
+    { "type": "status", "phase": "answering" },
+    { "type": "text_delta", "delta": "Within 14 days " },
+    { "type": "ui_payload", "kind": "citations", "data": { "items": [{ "n": 1, "title": "Refund policy", "heading_path": ["Refund policy", "Eligibility"], "url": "" }] } },
+    { "type": "done", "tokens_in": 812, "tokens_out": 64, "cost_usd": 0.000412, "finish_reason": "stop" },
+    { "type": "done", "tokens_in": 0, "tokens_out": 0, "cost_usd": 0, "finish_reason": "stop", "replayed": true },
+    { "type": "error", "code": "timeout", "message": "That took too long. Try again.", "retryable": true }
+  ],
+  "ignored": [
+    { "type": "tool_call", "tool": "kb_search", "args": {} },
+    { "type": "future_frame", "x": 1 }
+  ]
+}

package/src/wire/frames.ts

@@ -1,53 +1,64 @@
-/** The assistant SSE stream (frames: text deltas, tool and status events, structured parts, errors). The only file that knows the frame shapes. */
+/**
+ * The assistant SSE vocabulary, one version of it: `run`, `status`, `text_delta`, `ui_payload`, `done`, `error`, each as `data: {json with type}\n\n`.
+ * The only file that knows the frame shapes. A host's structured parts travel as `ui_payload` `{kind, data}` and are drawn by the host's renderer for that kind.
+ * An unknown `type` is ignored and a malformed frame is dropped: the contract is forward compatible.
+ */
 
-export type Phase = 'thinking' | 'searching' | 'reading' | 'choosing';
+export type Phase = 'thinking' | 'searching' | 'answering';
 export type StreamErrorCode = 'unavailable' | 'timeout' | 'failed';
 
+/** The version `run` carries; a decoder that does not know a version still reads the fields it knows. */
+export const WIRE_VERSION = 1;
+
 export type Frame =
-  | { type: 'run'; run_id: string; user_message_id: string; assistant_message_id: string }
+  | { type: 'run'; version: number; thread_id: string; message_id: string; client_id: string | null; seq: number | null }
   | { type: 'status'; phase: Phase }
   | { type: 'text_delta'; delta: string }
-  | { type: 'ui_payload'; kind: 'film_cards'; data: { ids: string[]; caption: string | null } }
-  | { type: 'done'; assistant_message_id: string }
-  | { type: 'error'; code: StreamErrorCode; message: string };
+  | { type: 'ui_payload'; kind: string; data: unknown }
+  | { type: 'done'; finish_reason: string | null; tokens_in: number | null; tokens_out: number | null; cost_usd: number | null; replayed: boolean }
+  | { type: 'error'; code: StreamErrorCode; message: string; retryable: boolean };
 
-const PHASES: readonly string[] = ['thinking', 'searching', 'reading', 'choosing'];
+const PHASES: readonly string[] = ['thinking', 'searching', 'answering'];
 const ERROR_CODES: readonly string[] = ['unavailable', 'timeout', 'failed'];
 
 const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === 'object' && value !== null && !Array.isArray(value);
 const str = (value: unknown): value is string => typeof value === 'string';
+const num = (value: unknown): number | null => (typeof value === 'number' && Number.isFinite(value) ? value : null);
 
-/** A known, well-formed frame, or null: an unknown `type` or widget `kind` is ignored (the contract is forward compatible), a malformed one is dropped. */
+/** A known, well-formed frame, or null. */
 export function decodeFrame(raw: unknown): Frame | null {
   if (!isRecord(raw)) return null;
   switch (raw.type) {
     case 'run':
-      return str(raw.run_id) && str(raw.user_message_id) && str(raw.assistant_message_id)
-        ? { type: 'run', run_id: raw.run_id, user_message_id: raw.user_message_id, assistant_message_id: raw.assistant_message_id }
+      return str(raw.thread_id) && str(raw.message_id)
+        ? { type: 'run', version: num(raw.version) ?? WIRE_VERSION, thread_id: raw.thread_id, message_id: raw.message_id, client_id: str(raw.client_id) ? raw.client_id : null, seq: num(raw.seq) }
         : null;
     case 'status':
       return str(raw.phase) && PHASES.includes(raw.phase) ? { type: 'status', phase: raw.phase as Phase } : null;
     case 'text_delta':
       return str(raw.delta) ? { type: 'text_delta', delta: raw.delta } : null;
-    case 'ui_payload': {
-      if (raw.kind !== 'film_cards' || !isRecord(raw.data) || !Array.isArray(raw.data.ids)) return null;
-      const ids = raw.data.ids.filter(str);
-      if (ids.length === 0) return null;
-      return { type: 'ui_payload', kind: 'film_cards', data: { ids, caption: str(raw.data.caption) ? raw.data.caption : null } };
-    }
+    case 'ui_payload':
+      return str(raw.kind) && raw.kind !== '' && 'data' in raw ? { type: 'ui_payload', kind: raw.kind, data: raw.data } : null;
     case 'done':
-      return str(raw.assistant_message_id) ? { type: 'done', assistant_message_id: raw.assistant_message_id } : null;
+      return {
+        type: 'done',
+        finish_reason: str(raw.finish_reason) ? raw.finish_reason : null,
+        tokens_in: num(raw.tokens_in),
+        tokens_out: num(raw.tokens_out),
+        cost_usd: num(raw.cost_usd),
+        replayed: raw.replayed === true,
+      };
     case 'error':
-      return str(raw.code) && ERROR_CODES.includes(raw.code) && str(raw.message) ? { type: 'error', code: raw.code as StreamErrorCode, message: raw.message } : null;
+      return str(raw.code) && ERROR_CODES.includes(raw.code) && str(raw.message)
+        ? { type: 'error', code: raw.code as StreamErrorCode, message: raw.message, retryable: raw.retryable !== false }
+        : null;
     default:
       return null;
   }
 }
 
-/** Turn context of the next message (applies to that turn only). */
-export type ChatContext =
-  | { kind: 'title'; imdb_id: string }
-  | { kind: 'browse'; query: string | null; filters: Record<string, unknown> | null };
+/** What the host says about the next turn (applies to that turn only): the page on screen, a selection, anything its server reads. The package never looks inside. */
+export type ChatContext = Record<string, unknown>;
 
 /** The idle limit above the server's 15 s ping; a silent stream past it is treated as lost. */
 export const IDLE_MS = 45_000;

package/src/wire/stored.ts

@@ -1,10 +1,10 @@
-/** A stored message as `GET /apix/chat/v1/conversation` returns it (CONTRACT.md `Message`). Replace with the generated type once `make gen-ts` carries group `chat`. */
+/** A stored message as the host's history endpoint returns it. The shape is the host's server's; this is the part the widget reads. */
 export type StoredStatus = 'done' | 'running' | 'error' | 'cancelled';
 
-export interface StoredWidget {
+/** A structured part the answer carried, by the same `kind` a live `ui_payload` has. */
+export interface StoredPart {
   kind: string;
-  ids: string[];
-  caption: string | null;
+  data: unknown;
 }
 
 export interface StoredMessage {
@@ -12,7 +12,7 @@ export interface StoredMessage {
   seq: number;
   role: 'user' | 'assistant';
   text: string;
-  widgets: StoredWidget[];
+  parts: StoredPart[];
   status: StoredStatus;
   error_code: string | null;
   created_at: string;

package/src/wire/transport.ts

@@ -39,38 +39,63 @@ export interface ChatTransport {
 }
 
 export interface TransportConfig {
-  /** API origin, no trailing slash. The stream is called directly, never through a Next rewrite. */
+  /** API origin, no trailing slash; prefixes a relative `streamUrl`. The stream is called directly, never through a Next rewrite. */
   baseUrl: string;
-  /** The bearer token, read per request; the header only, never the query string. */
-  getToken: () => string | null | undefined;
+  /** Where one run is opened: a path or URL, or a function read per request (a thread id in the path). Absent: the legacy `/apix/chat/v1/stream` (deprecated, removed in 0.3). */
+  streamUrl?: string | ((input: SendInput) => string);
+  /** The request body. Absent: `{text, client_id, context?}`. */
+  buildBody?: (input: SendInput) => unknown;
+  /** The bearer token, read per request; the header only, never the query string. Signed-in hosts. */
+  getToken?: () => string | null | undefined;
+  /** Anonymous hosts: an opaque token the host stores, sent as `x-visitor-token`. No cookie is assumed, no history is fetched. */
+  visitorToken?: () => string | null | undefined;
+  /** More headers per request (a CSRF token). */
+  headers?: () => Record<string, string>;
   idleMs?: number;
+  /** Replaces `fetch` for the stream: add auth, a CSRF token, credentials. */
+  streamFetch?: typeof fetch;
+  /** @deprecated Use `streamFetch`. */
   fetch?: typeof fetch;
 }
 
 const CODES: readonly string[] = ['unauthorized', 'busy', 'invalid', 'rate_limited', 'unavailable'];
+/** A server may name a bad request its own way; these read as `invalid`. */
+const INVALID: readonly string[] = ['validation_error'];
 
 function rejectCode(status: number, body: unknown): RejectCode {
   const code = typeof body === 'object' && body !== null ? (body as { code?: unknown }).code : undefined;
   if (typeof code === 'string' && CODES.includes(code)) return code as RejectCode;
+  if (typeof code === 'string' && INVALID.includes(code)) return 'invalid';
   if (status === 401) return 'unauthorized';
   if (status === 409) return 'busy';
-  if (status === 422) return 'invalid';
+  if (status === 400 || status === 422) return 'invalid';
   if (status === 429) return 'rate_limited';
   if (status === 503) return 'unavailable';
   return 'failed';
 }
 
+const LEGACY_STREAM = '/apix/chat/v1/stream';
+
 export function createTransport(config: TransportConfig): ChatTransport {
-  const call = config.fetch ?? fetch;
+  const call = config.streamFetch ?? config.fetch ?? fetch;
   return {
-    async *open({ text, clientId, context, signal }) {
-      const token = config.getToken();
+    async *open(input) {
+      const { text, clientId, context, signal } = input;
+      const token = config.getToken?.();
+      const visitor = config.visitorToken?.();
+      const target = typeof config.streamUrl === 'function' ? config.streamUrl(input) : (config.streamUrl ?? LEGACY_STREAM);
+      const url = /^https?:\/\//.test(target) ? target : `${config.baseUrl}${target}`;
       let response: Response;
       try {
-        response = await call(`${config.baseUrl}/apix/chat/v1/stream`, {
+        response = await call(url, {
           method: 'POST',
-          headers: { 'content-type': 'application/json', ...(token ? { authorization: `Bearer ${token}` } : {}) },
-          body: JSON.stringify({ text, client_id: clientId, ...(context ? { context } : {}) }),
+          headers: {
+            'content-type': 'application/json',
+            ...(token ? { authorization: `Bearer ${token}` } : {}),
+            ...(visitor ? { 'x-visitor-token': visitor } : {}),
+            ...config.headers?.(),
+          },
+          body: JSON.stringify(config.buildBody ? config.buildBody(input) : { text, client_id: clientId, ...(context ? { context } : {}) }),
           signal,
         });
       } catch {