@djangocfg/widget-assistant 0.2.9 → 0.3.7

package/README.md

@@ -46,10 +46,40 @@ An unknown `type` is ignored. `wire/fixtures/events.json` holds one of each fram
 
 `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.
 
+## Sessions (0.3)
+
+A session is one thread on the server. `useSession({ transport, api, storage, getContext })` shows one at a time and gives the host `startNew()`, `switchTo(id)`, `sessions` / `refreshSessions()` and `busy` (a turn is streaming: starting or switching waits, Stop ends it).
+
+*   `api: ThreadApi` is three calls the host maps to its endpoints: `list(signal)` (newest activity first), `create()` (`POST threads/`, always a new row) and `load(id, signal)` (throws `ThreadNotFoundError` on a 404: a stranger's or purged session).
+*   On load the remembered session (`storage: { read, write }`, the host picks the key; reads and writes must not throw) is shown, else the newest, else a blank page. **A session is created on the first send, never on load**; the transcript is not reseeded then, so the live message survives.
+*   `createTransport({ streamUrl: ({ threadId }) => … })` posts to the session in the path; `SendInput.threadId` is what `threadFor` returned.
+*   `<SessionsMenu session={session} />` is the header control: "New chat" and the list of earlier chats (title, "5 minutes ago", a check on the current one). Words come from the bundled dictionaries (`newChat`, `sessions`, `sessionsEmpty`).
+*   `<AssistantChat draftRoom={session.thread.session ?? 'new'} />` keeps each session's unsent draft under its own id.
+*   There is no delete and no `clear()`: "clear" is "new chat". Retention is the server's job.
+*   Without `api` (anonymous host) nothing is listed; `startNew()` just empties the room.
+
+## Voice (0.3.3)
+
+The microphone menu always offers a dictation language: a visitor may speak any language, whatever the host UI says. With no `speech` prop the assistant uses `useSpeechLanguage` from `@djangocfg/widget-chat/store` (the last pick, kept on this device; else the page language if the browser also lists it; else the browser's; else English). A host `speech={{ value, onChange }}` still overrides it.
+
+Message sounds (sent, answer starts, answer done, error) come from `widget-chat` and are on by default; `messageSounds={false}` silences them, `messageSounds={{ volume, urls }}` tunes them.
+
+Dictation start/stop tones are bundled (Web Audio, no files). `sounds={false}` silences them; `sounds={{ play(kind) }}` replaces them.
+
+## Asking from outside, the dock and the locked room
+
+*   `askAssistant(text)` puts a prompt typed elsewhere on the page (a hero search, a "discuss this" button) into the composer and sends it once the composer is mounted and sending is allowed. One slot: asking twice before the composer exists keeps the last.
+*   `AssistantFrame` and `ChatDock` take `actions` (header controls such as `SessionsMenu`): they sit next to Close in the one panel header (`ChatPanelHeader` from `widget-chat`, drawn identically by the wide column, the tablet side panel and the phone sheet), set apart by a thin divider; each button has a ui-core tooltip. `ChatDock` is a side panel on tablets, the base package's `ChatSheet` on phones. The keys list (`ComposerHelp`) is hidden on touch devices.
+*   `AssistantLocked` takes `onComposerClick`: the inert composer becomes a button for the way out (sign in).
+
 ## 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.
+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 stays for anonymous hosts only; a signed-in host with sessions sets `streamUrl`. The dictionaries lose `statusReading` and `statusChoosing` and gain `statusAnswering`; the bundled `lockedBody` and `hint` no longer talk about films.
+
+## Migrating from 0.2 (one thread, `clear()`)
+
+0.3 replaces the single-thread `ThreadApi { load, clear }` with `ThreadApi { list, create, load(id, signal) }` (`useSession` takes an optional `storage`), removes `Session.clear` (use `startNew`), swaps the dictionary keys `clear`, `clearConfirm`, `clearYes` for `newChat`, `sessions`, `sessionsEmpty`, and adds `ThreadNotFoundError`, the `not_found` reject code, `SendInput.threadId`, `AdapterDeps.threadFor` / `onActive`, `AssistantChat.draftRoom`, `SessionsMenu`, `useAssistantLocale` and `relativeTime`. A host that kept a hand-written sessions bar can delete it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/widget-assistant",
-  "version": "0.2.9",
+  "version": "0.3.7",
   "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.19",
+    "@djangocfg/widget-chat": "^0.1.23",
     "zustand": "^5.0.16"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.619",
-    "@djangocfg/ui-core": "^2.1.619",
+    "@djangocfg/i18n": "^2.1.622",
+    "@djangocfg/ui-core": "^2.1.622",
     "lucide-react": "^1.68.0",
     "react": "^19.0.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.619",
-    "@djangocfg/typescript-config": "^2.1.619",
-    "@djangocfg/ui-core": "^2.1.619",
+    "@djangocfg/i18n": "^2.1.622",
+    "@djangocfg/typescript-config": "^2.1.622",
+    "@djangocfg/ui-core": "^2.1.622",
     "@storybook/react-vite": "^10.6.5",
     "@types/node": "^25.9.5",
     "@types/react": "19.3.0",

package/src/AssistantChat.tsx

@@ -2,6 +2,8 @@
 
 import { useMemo, useRef, type ReactNode } from 'react';
 
+import type { ChatSoundsCapability, VoiceSoundsCapability } from '@djangocfg/widget-chat/core';
+import { useSpeechLanguage } from '@djangocfg/widget-chat/store';
 import {
   Chat,
   ChatTranscript,
@@ -14,6 +16,8 @@ import {
 import { Response } from '@djangocfg/widget-chat/content';
 
 import type { SessionNotice } from './stream/useSession';
+import { useAssistantLocale } from './i18n';
+import { bundledEarcons } from './composer/earcons';
 import { createWholeTranscriptSpeech } from './composer/wholeTranscript';
 import { AssistantComposer } from './composer/AssistantComposer';
 import { ComposerHelp } from './composer/ComposerHelp';
@@ -33,12 +37,18 @@ interface Props {
   adapter: ChatAdapter;
   /** Example prompts shown in an empty chat. */
   suggestions: string[];
-  /** The room on screen: `id` changes when the thread is reloaded (reconcile, clear), which reseeds the transcript. */
+  /** The room on screen: `id` changes when the thread is reloaded (reconcile, a new or another session), which reseeds the transcript. */
   conversation?: { id?: string; history: readonly ChatMessage[] };
+  /** What the unsent draft is kept under: the session's own id, so each session keeps its draft across reseeds. Absent: the conversation `id`. */
+  draftRoom?: string;
   /** 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. */
+  /** Dictation language and its picker (the microphone menu). Absent: the assistant's own picker (the viewer's last pick, else the page and browser language), always shown. */
   speech?: SpeechLanguage;
+  /** The dictation start/stop tones. Absent: the bundled ones (Web Audio, no files). `false`: silent. */
+  sounds?: VoiceSoundsCapability | false;
+  /** The message sounds (sent, answer starts, answer done, error). Absent: the widget's bundled ones, on. `false`: silent. */
+  messageSounds?: ChatSoundsCapability | false;
   /** A plain line above the composer: reconnecting, or a stalled run with its Retry (`onRetry`). */
   notice?: SessionNotice | null;
   onRetry?: () => void;
@@ -57,7 +67,7 @@ const NO_RENDERERS: Readonly<Record<string, DataPartRenderer>> = {};
  * recall of sent prompts with the arrow keys, an unsent draft that survives a reload). The widget's packaged layout shows only a bare composer, so the layout
  * is composed here from its own primitives: every behaviour is the widget's, nothing is re-implemented.
  */
-export function AssistantChat({ adapter, suggestions, conversation = EMPTY_ROOM, dataRenderers = NO_RENDERERS, speech, notice, onRetry, focusWhen, refocus, className }: Props) {
+export function AssistantChat({ adapter, suggestions, conversation = EMPTY_ROOM, draftRoom, dataRenderers = NO_RENDERERS, speech: given, sounds, messageSounds, notice, onRetry, focusWhen, refocus, className }: Props) {
   const renderers = useMemo(
     () => ({
       text: ({ part }: PartRenderProps) => (part.type === 'text' ? <Response>{part.text}</Response> : null),
@@ -72,13 +82,15 @@ export function AssistantChat({ adapter, suggestions, conversation = EMPTY_ROOM,
     }),
     [dataRenderers],
   );
+  const own = useSpeechLanguage({ uiLocale: useAssistantLocale() });
+  const speech = given ?? { value: own.language, onChange: own.setLanguage };
   // The language is read at each start, through a ref: the capability must not be rebuilt when the picker changes.
   const language = useRef(speech?.value);
   language.current = speech?.value;
   const voice = useMemo(() => createWholeTranscriptSpeech(() => language.current ?? (typeof navigator === 'undefined' ? 'en-US' : navigator.language)), []);
   const capabilities = useMemo<ChatCapabilities>(
-    () => ({ suggestions: { items: suggestions.map((prompt, index) => ({ id: `s${index}`, title: prompt, prompt })) }, ...(voice ? { voice } : {}) }),
-    [suggestions, voice],
+    () => ({ suggestions: { items: suggestions.map((prompt, index) => ({ id: `s${index}`, title: prompt, prompt })) }, ...(voice ? { voice } : {}), ...(sounds === false ? {} : { voiceSounds: sounds ?? bundledEarcons }), ...(messageSounds === undefined ? {} : { sounds: messageSounds }) }),
+    [suggestions, voice, sounds, messageSounds],
   );
   const slots = useMemo(
     () => ({
@@ -106,7 +118,7 @@ export function AssistantChat({ adapter, suggestions, conversation = EMPTY_ROOM,
         children: (
           <>
             <ChatTranscript footer={(message) => <MessageFooter message={message} />} />
-            <AssistantComposer speech={speech} draftRoom={conversation.id ?? 'assistant'} focusWhen={focusWhen} refocus={refocus} />
+            <AssistantComposer speech={speech} draftRoom={draftRoom ?? conversation.id ?? 'assistant'} focusWhen={focusWhen} refocus={refocus} />
           </>
         ),
       }}

package/src/composer/ComposerBehaviour.tsx

@@ -6,6 +6,7 @@ import { useHotkey } from '@djangocfg/ui-core/hooks';
 import { useComposer } from '@djangocfg/widget-chat';
 
 import { useCaretFocus } from './useCaretFocus';
+import { clearPendingPrompt, usePendingPrompt } from './handoff';
 import { useComposerNodes } from './useComposerNodes';
 import { DICTATION_TOGGLE } from './keys';
 import { useFocusArea } from './useFocusArea';
@@ -33,6 +34,22 @@ export function ComposerBehaviour({ focusWhen = false, refocus = false }: Props)
   const latest = useRef(composer);
   latest.current = composer;
 
+  // A prompt asked from outside the assistant (`askAssistant`): into the draft, then sent once the draft holds it and sending is allowed.
+  const pendingPrompt = usePendingPrompt();
+  const draftText = composer.draft.text;
+  const canSend = composer.canSend;
+  useEffect(() => {
+    if (!pendingPrompt) return;
+    if (draftText !== pendingPrompt) {
+      latest.current.setText(pendingPrompt);
+      return;
+    }
+    if (canSend) {
+      clearPendingPrompt();
+      latest.current.send();
+    }
+  }, [pendingPrompt, draftText, canSend]);
+
   const recording = useRecording(nodes);
   useHeightFloor(nodes, recording);
   useFocusArea(nodes, marker, refocus);

package/src/composer/ComposerHelp.tsx

@@ -1,7 +1,7 @@
 'use client';
 
 import { Kbd, Popover, PopoverContent, PopoverTrigger } from '@djangocfg/ui-core/components';
-import { formatHotkey } from '@djangocfg/ui-core/hooks';
+import { formatHotkey, useIsTouch } from '@djangocfg/ui-core/hooks';
 
 import { useAssistantCopy } from '../i18n';
 import { DICTATION_TOGGLE } from './keys';
@@ -22,6 +22,9 @@ function useRows() {
 export function ComposerHelp() {
   const copy = useAssistantCopy();
   const rows = useRows();
+  const touch = useIsTouch();
+  // The keys are a desktop keyboard's: a phone has none of them.
+  if (touch) return null;
   return (
     <div className="px-4 pb-1 text-end">
       <Popover>

package/src/composer/earcons.ts

@@ -0,0 +1,49 @@
+import type { VoiceSoundsCapability } from '@djangocfg/widget-chat/core';
+
+/**
+ * The dictation tones, made with the Web Audio API: a rising pair when the microphone opens, a falling pair when it closes. No audio files ship and none
+ * are fetched. A tone is quiet and short; a browser that has no `AudioContext`, or has not been unlocked by a gesture, plays nothing (the dictation starts from a click, so it is unlocked).
+ */
+const TONES: Readonly<Record<'start' | 'stop', readonly [number, number]>> = {
+  start: [660, 880],
+  stop: [880, 560],
+};
+
+const STEP = 0.07;
+const GAIN = 0.06;
+
+let context: AudioContext | null | undefined;
+
+function audio(): AudioContext | null {
+  if (context !== undefined) return context;
+  const Ctor = typeof window === 'undefined' ? undefined : (window.AudioContext ?? (window as unknown as { webkitAudioContext?: typeof AudioContext }).webkitAudioContext);
+  context = Ctor ? new Ctor() : null;
+  return context;
+}
+
+/** The bundled tones. Never throws: the session runs this on the path that opens the microphone. */
+export const bundledEarcons: VoiceSoundsCapability = {
+  play: (kind) => {
+    try {
+      const ctx = audio();
+      if (!ctx) return;
+      if (ctx.state === 'suspended') void ctx.resume();
+      const [first, second] = TONES[kind];
+      const now = ctx.currentTime;
+      [first, second].forEach((frequency, index) => {
+        const osc = ctx.createOscillator();
+        const gain = ctx.createGain();
+        const at = now + index * STEP;
+        osc.frequency.value = frequency;
+        gain.gain.setValueAtTime(0, at);
+        gain.gain.linearRampToValueAtTime(GAIN, at + 0.01);
+        gain.gain.linearRampToValueAtTime(0, at + STEP);
+        osc.connect(gain).connect(ctx.destination);
+        osc.start(at);
+        osc.stop(at + STEP + 0.02);
+      });
+    } catch {
+      // A tone is a convenience.
+    }
+  },
+};

package/src/composer/handoff.ts

@@ -0,0 +1,26 @@
+import { useSyncExternalStore } from 'react';
+
+/**
+ * A prompt typed outside the assistant (the header's AI mode) waiting for the composer. The composer, once mounted, puts it in the draft and
+ * sends it, then clears it. One slot: asking twice before the composer exists keeps the last.
+ */
+let pending: string | null = null;
+const listeners = new Set<() => void>();
+const emit = () => listeners.forEach((listener) => listener());
+
+export function askAssistant(text: string): void {
+  pending = text.trim() || null;
+  emit();
+}
+
+export function clearPendingPrompt(): void {
+  pending = null;
+  emit();
+}
+
+const subscribe = (listener: () => void) => {
+  listeners.add(listener);
+  return () => void listeners.delete(listener);
+};
+
+export const usePendingPrompt = (): string | null => useSyncExternalStore(subscribe, () => pending, () => null);

package/src/i18n/index.ts

@@ -34,3 +34,6 @@ const kit = createCopy(ASSISTANT_DICTIONARIES);
  * `@djangocfg/i18n` provider, else English. The host passes no strings.
  */
 export const useAssistantCopy = kit.useCopy;
+
+/** The bundled locale the assistant resolved to (feed it to `Intl`). */
+export const useAssistantLocale = kit.useLocale;

package/src/i18n/locales/ar.ts

@@ -20,9 +20,9 @@ export const ar: AssistantCopy = {
   reconnecting: 'إعادة الاتصال…',
   stalled: 'ما زالت الإجابة قيد الإعداد.',
   retry: 'إعادة المحاولة',
-  clear: 'مسح المحادثة',
-  clearConfirm: 'حذف هذه المحادثة؟ لا يمكن التراجع.',
-  clearYes: 'حذف',
+  newChat: 'محادثة جديدة',
+  sessions: 'المحادثات السابقة',
+  sessionsEmpty: 'لا توجد محادثات سابقة بعد',
   loadError: 'تعذّر تحميل المحادثة.',
   helpLabel: 'مساعدة',
   helpDictate: 'بدء الإملاء أو إيقافه',

package/src/i18n/locales/da.ts

@@ -20,9 +20,9 @@ export const da: AssistantCopy = {
   reconnecting: 'Forbinder igen…',
   stalled: 'Svaret er stadig undervejs.',
   retry: 'Prøv igen',
-  clear: 'Ryd chatten',
-  clearConfirm: 'Slet denne samtale? Det kan ikke fortrydes.',
-  clearYes: 'Slet',
+  newChat: 'Ny chat',
+  sessions: 'Tidligere chats',
+  sessionsEmpty: 'Ingen tidligere chats endnu',
   loadError: 'Samtalen kunne ikke indlæses.',
   helpLabel: 'Hjælp',
   helpDictate: 'Start eller stop diktering',

package/src/i18n/locales/de.ts

@@ -20,9 +20,9 @@ export const de: AssistantCopy = {
   reconnecting: 'Verbinde neu…',
   stalled: 'Die Antwort wird noch erstellt.',
   retry: 'Erneut versuchen',
-  clear: 'Chat leeren',
-  clearConfirm: 'Diese Unterhaltung löschen? Das lässt sich nicht rückgängig machen.',
-  clearYes: 'Löschen',
+  newChat: 'Neuer Chat',
+  sessions: 'Frühere Chats',
+  sessionsEmpty: 'Noch keine früheren Chats',
   loadError: 'Die Unterhaltung konnte nicht geladen werden.',
   helpLabel: 'Hilfe',
   helpDictate: 'Diktat starten oder beenden',

package/src/i18n/locales/en.ts

@@ -20,9 +20,9 @@ export const en: AssistantCopy = {
   reconnecting: 'Reconnecting…',
   stalled: 'Still working on the answer.',
   retry: 'Retry',
-  clear: 'Clear chat',
-  clearConfirm: 'Delete this conversation? This cannot be undone.',
-  clearYes: 'Delete',
+  newChat: 'New chat',
+  sessions: 'Earlier chats',
+  sessionsEmpty: 'No earlier chats yet',
   loadError: 'Could not load the conversation.',
   helpLabel: 'Help',
   helpDictate: 'Start or stop dictation',

package/src/i18n/locales/es.ts

@@ -20,9 +20,9 @@ export const es: AssistantCopy = {
   reconnecting: 'Reconectando…',
   stalled: 'La respuesta sigue en curso.',
   retry: 'Reintentar',
-  clear: 'Borrar chat',
-  clearConfirm: '¿Eliminar esta conversación? No se puede deshacer.',
-  clearYes: 'Eliminar',
+  newChat: 'Nuevo chat',
+  sessions: 'Chats anteriores',
+  sessionsEmpty: 'Aún no hay chats anteriores',
   loadError: 'No se pudo cargar la conversación.',
   helpLabel: 'Ayuda',
   helpDictate: 'Iniciar o detener el dictado',

package/src/i18n/locales/fr.ts

@@ -20,9 +20,9 @@ export const fr: AssistantCopy = {
   reconnecting: 'Reconnexion…',
   stalled: 'La réponse est encore en cours.',
   retry: 'Réessayer',
-  clear: 'Effacer le chat',
-  clearConfirm: 'Supprimer cette conversation ? Cette action est irréversible.',
-  clearYes: 'Supprimer',
+  newChat: 'Nouvelle discussion',
+  sessions: 'Discussions précédentes',
+  sessionsEmpty: 'Aucune discussion précédente',
   loadError: 'Impossible de charger la conversation.',
   helpLabel: 'Aide',
   helpDictate: 'Démarrer ou arrêter la dictée',

package/src/i18n/locales/it.ts

@@ -20,9 +20,9 @@ export const it: AssistantCopy = {
   reconnecting: 'Riconnessione…',
   stalled: 'La risposta è ancora in corso.',
   retry: 'Riprova',
-  clear: 'Cancella chat',
-  clearConfirm: 'Eliminare questa conversazione? Non si può annullare.',
-  clearYes: 'Elimina',
+  newChat: 'Nuova chat',
+  sessions: 'Chat precedenti',
+  sessionsEmpty: 'Ancora nessuna chat precedente',
   loadError: 'Impossibile caricare la conversazione.',
   helpLabel: 'Aiuto',
   helpDictate: 'Avvia o ferma la dettatura',

package/src/i18n/locales/ja.ts

@@ -20,9 +20,9 @@ export const ja: AssistantCopy = {
   reconnecting: '再接続中…',
   stalled: 'まだ回答を作成中です。',
   retry: '再試行',
-  clear: 'チャットを消去',
-  clearConfirm: 'この会話を削除しますか？元に戻せません。',
-  clearYes: '削除',
+  newChat: '新しいチャット',
+  sessions: '過去のチャット',
+  sessionsEmpty: '過去のチャットはまだありません',
   loadError: '会話を読み込めませんでした。',
   helpLabel: 'ヘルプ',
   helpDictate: '音声入力の開始/停止',

package/src/i18n/locales/ko.ts

@@ -20,9 +20,9 @@ export const ko: AssistantCopy = {
   reconnecting: '다시 연결하는 중…',
   stalled: '아직 답변을 준비 중입니다.',
   retry: '다시 시도',
-  clear: '대화 지우기',
-  clearConfirm: '이 대화를 삭제할까요? 되돌릴 수 없습니다.',
-  clearYes: '삭제',
+  newChat: '새 채팅',
+  sessions: '이전 채팅',
+  sessionsEmpty: '이전 채팅이 아직 없습니다',
   loadError: '대화를 불러오지 못했습니다.',
   helpLabel: '도움말',
   helpDictate: '음성 입력 시작/중지',

package/src/i18n/locales/nl.ts

@@ -20,9 +20,9 @@ export const nl: AssistantCopy = {
   reconnecting: 'Opnieuw verbinden…',
   stalled: 'Het antwoord wordt nog gemaakt.',
   retry: 'Opnieuw proberen',
-  clear: 'Chat wissen',
-  clearConfirm: 'Dit gesprek verwijderen? Dit kan niet ongedaan worden gemaakt.',
-  clearYes: 'Verwijderen',
+  newChat: 'Nieuwe chat',
+  sessions: 'Eerdere chats',
+  sessionsEmpty: 'Nog geen eerdere chats',
   loadError: 'Het gesprek kon niet worden geladen.',
   helpLabel: 'Help',
   helpDictate: 'Dicteren starten of stoppen',

package/src/i18n/locales/no.ts

@@ -20,9 +20,9 @@ export const no: AssistantCopy = {
   reconnecting: 'Kobler til igjen…',
   stalled: 'Svaret lages fortsatt.',
   retry: 'Prøv igjen',
-  clear: 'Tøm chatten',
-  clearConfirm: 'Slette denne samtalen? Det kan ikke angres.',
-  clearYes: 'Slett',
+  newChat: 'Ny chat',
+  sessions: 'Tidligere chatter',
+  sessionsEmpty: 'Ingen tidligere chatter ennå',
   loadError: 'Samtalen kunne ikke lastes.',
   helpLabel: 'Hjelp',
   helpDictate: 'Start eller stopp diktering',

package/src/i18n/locales/pl.ts

@@ -20,9 +20,9 @@ export const pl: AssistantCopy = {
   reconnecting: 'Łączę ponownie…',
   stalled: 'Odpowiedź wciąż powstaje.',
   retry: 'Spróbuj ponownie',
-  clear: 'Wyczyść czat',
-  clearConfirm: 'Usunąć tę rozmowę? Nie można tego cofnąć.',
-  clearYes: 'Usuń',
+  newChat: 'Nowy czat',
+  sessions: 'Wcześniejsze czaty',
+  sessionsEmpty: 'Brak wcześniejszych czatów',
   loadError: 'Nie udało się wczytać rozmowy.',
   helpLabel: 'Pomoc',
   helpDictate: 'Włącz lub zatrzymaj dyktowanie',

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

@@ -20,9 +20,9 @@ export const ptBR: AssistantCopy = {
   reconnecting: 'Reconectando…',
   stalled: 'A resposta ainda está sendo preparada.',
   retry: 'Tentar de novo',
-  clear: 'Limpar conversa',
-  clearConfirm: 'Excluir esta conversa? Não dá para desfazer.',
-  clearYes: 'Excluir',
+  newChat: 'Novo chat',
+  sessions: 'Chats anteriores',
+  sessionsEmpty: 'Ainda não há chats anteriores',
   loadError: 'Não foi possível carregar a conversa.',
   helpLabel: 'Ajuda',
   helpDictate: 'Iniciar ou parar o ditado',

package/src/i18n/locales/ru.ts

@@ -20,9 +20,9 @@ export const ru: AssistantCopy = {
   reconnecting: 'Подключаемся снова…',
   stalled: 'Ответ ещё готовится.',
   retry: 'Повторить',
-  clear: 'Очистить чат',
-  clearConfirm: 'Удалить этот разговор? Это нельзя отменить.',
-  clearYes: 'Удалить',
+  newChat: 'Новый чат',
+  sessions: 'Прошлые чаты',
+  sessionsEmpty: 'Прошлых чатов пока нет',
   loadError: 'Не удалось загрузить разговор.',
   helpLabel: 'Справка',
   helpDictate: 'Начать или остановить диктовку',

package/src/i18n/locales/sv.ts

@@ -20,9 +20,9 @@ export const sv: AssistantCopy = {
   reconnecting: 'Återansluter…',
   stalled: 'Svaret är fortfarande på väg.',
   retry: 'Försök igen',
-  clear: 'Rensa chatten',
-  clearConfirm: 'Ta bort den här konversationen? Det går inte att ångra.',
-  clearYes: 'Ta bort',
+  newChat: 'Ny chatt',
+  sessions: 'Tidigare chattar',
+  sessionsEmpty: 'Inga tidigare chattar ännu',
   loadError: 'Konversationen kunde inte laddas.',
   helpLabel: 'Hjälp',
   helpDictate: 'Starta eller stoppa diktering',

package/src/i18n/locales/tr.ts

@@ -20,9 +20,9 @@ export const tr: AssistantCopy = {
   reconnecting: 'Yeniden bağlanıyor…',
   stalled: 'Yanıt hâlâ hazırlanıyor.',
   retry: 'Tekrar dene',
-  clear: 'Sohbeti temizle',
-  clearConfirm: 'Bu konuşma silinsin mi? Geri alınamaz.',
-  clearYes: 'Sil',
+  newChat: 'Yeni sohbet',
+  sessions: 'Önceki sohbetler',
+  sessionsEmpty: 'Henüz önceki sohbet yok',
   loadError: 'Konuşma yüklenemedi.',
   helpLabel: 'Yardım',
   helpDictate: 'Dikteyi başlat veya durdur',

package/src/i18n/locales/zh.ts

@@ -20,9 +20,9 @@ export const zh: AssistantCopy = {
   reconnecting: '正在重新连接…',
   stalled: '仍在生成回答。',
   retry: '重试',
-  clear: '清空对话',
-  clearConfirm: '删除此对话？此操作无法撤销。',
-  clearYes: '删除',
+  newChat: '新对话',
+  sessions: '以前的对话',
+  sessionsEmpty: '还没有以前的对话',
   loadError: '无法加载对话。',
   helpLabel: '帮助',
   helpDictate: '开始或停止听写',

package/src/i18n/types.ts

@@ -26,10 +26,10 @@ export interface AssistantCopy {
   reconnecting: string;
   stalled: string;
   retry: string;
-  /** Deleting the conversation. */
-  clear: string;
-  clearConfirm: string;
-  clearYes: string;
+  /** Sessions: start a new chat, the list of earlier ones, and its empty line. */
+  newChat: string;
+  sessions: string;
+  sessionsEmpty: string;
   loadError: string;
   /** The "Help" link under the composer and its list of keys. */
   helpLabel: string;

package/src/index.ts

@@ -1,19 +1,22 @@
 export { AssistantChat, type DataPartRenderer } from './AssistantChat';
 export { scriptedTransport, type ScriptStep } from './stream/scriptedTransport';
-export { useAssistantCopy, ASSISTANT_DICTIONARIES, type AssistantCopy } from './i18n';
+export { useAssistantCopy, useAssistantLocale, ASSISTANT_DICTIONARIES, type AssistantCopy } from './i18n';
+export { askAssistant } from './composer/handoff';
 export { ChatDock } from './shell/ChatDock';
 export { AssistantFrame, type FrameLabels } from './shell/AssistantFrame';
 export { AssistantFab, type FabHint } from './shell/AssistantFab';
 export { AssistantLocked } from './shell/AssistantLocked';
 export { createAssistantUi, useMediaQuery, type UiOptions, type UiState, type UiStorage } from './shell/panelState';
 export { AssistantHostProvider, AssistantPortal, AssistantSlot } from './Host';
-export { useSession, type Session, type SessionCopy, type SessionDeps, type SessionNotice, type ThreadApi, type ThreadState } from './stream/useSession';
+export { useSession, type Session, type SessionCopy, type SessionDeps, type SessionNotice, type ThreadState } from './stream/useSession';
+export { relativeTime, restoreSession, type SessionStorage, type ThreadApi } from './stream/sessions';
+export { SessionsMenu } from './sessions/SessionsMenu';
 export { createStreamAdapter, type AdapterDeps } from './stream/adapter';
 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 { createTransport, ChatHttpError, ChatNetworkError, ThreadNotFoundError, 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, StoredPart, StoredStatus } from './wire/stored';
+export type { StoredConversation, StoredMessage, StoredPart, StoredStatus, StoredThread } from './wire/stored';
 export { citationsRenderer, KB_RENDERERS, KB_PAYLOAD_KINDS, type Citation } from './examples/KbAssistant';