@djangocfg/widget-assistant 0.3.10 → 0.3.12

package/README.md

@@ -42,6 +42,8 @@ One vocabulary, `data: {json with type}\n\n`, decoded only in `wire/frames.ts`:
 | `run` | `version`, `thread_id`, `message_id`, `client_id`, `seq` |
 | `status` | `phase`: `thinking` \| `searching` \| `answering` |
 | `text_delta` | `delta` |
+| `reasoning_delta` | `delta` (optional layer: the model's thinking, drawn by the widget's own Reasoning block) |
+| `reasoning_end` | `elapsed_ms?`, `tokens?` (optional: seals the thought; otherwise the next text, payload or `done` does) |
 | `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` |
@@ -64,7 +66,7 @@ A session is one thread on the server. `useSession({ transport, api, storage, ge
 
 ## 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.
+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 owns it through `useSpeechLanguage` from `@djangocfg/widget-chat/store` (the last pick, kept on this device under `cfg.chat.speech_language`, storage errors swallowed; else the page language if the browser also lists it; else the browser's; else English) and feeds `createWholeTranscriptSpeech`. A host `speech={{ value, onChange }}` still overrides it (controlled mode). The picker lists the base widget's Web Speech catalogue (61 languages, with dialects, searchable), which covers all 17 bundled locales (`zh` is Mandarin, `no` is Bokmål); it has no free "other BCP-47" field. Touch devices hide the picker and the microphone (they have their own keyboard dictation). A host that shows no picker runs an older release: upgrade to 0.3.3 or later.
 
 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/widget-assistant",
-  "version": "0.3.10",
+  "version": "0.3.12",
   "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.26",
+    "@djangocfg/widget-chat": "^0.1.28",
     "zustand": "^5.0.16"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.625",
-    "@djangocfg/ui-core": "^2.1.625",
+    "@djangocfg/i18n": "^2.1.627",
+    "@djangocfg/ui-core": "^2.1.627",
     "lucide-react": "^1.68.0",
     "react": "^19.0.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.625",
-    "@djangocfg/typescript-config": "^2.1.625",
-    "@djangocfg/ui-core": "^2.1.625",
+    "@djangocfg/i18n": "^2.1.627",
+    "@djangocfg/typescript-config": "^2.1.627",
+    "@djangocfg/ui-core": "^2.1.627",
     "@storybook/react-vite": "^10.6.5",
     "@types/node": "^25.9.5",
     "@types/react": "19.3.0",

package/src/index.ts

@@ -11,6 +11,20 @@ export { AssistantHostProvider, AssistantPortal, AssistantSlot, AssistantHeaderA
 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 { createSessionStorage, useRememberedSession } from './sessions/storage';
+export {
+  createChatTransport,
+  storedMessageOf,
+  storedThreadOf,
+  type ChatCallResult,
+  type ChatConnection,
+  type ChatMessageShape,
+  type ChatThreadCalls,
+  type ChatThreadDetailShape,
+  type ChatThreadListItemShape,
+  type ChatThreadShape,
+  type ChatTransportConfig,
+} from './sessions/kit';
 export { createStreamAdapter, type AdapterDeps } from './stream/adapter';
 export { reconcile, type Reconciled } from './stream/reconcile';
 export { fromStored, fromStoredThread } from './stream/fromStored';

package/src/sessions/kit.ts

@@ -0,0 +1,119 @@
+import type { StoredConversation, StoredMessage, StoredStatus, StoredThread } from '../wire/stored';
+import { createTransport, ThreadNotFoundError, type ChatTransport, type SendInput, type TransportConfig } from '../wire/transport';
+import type { ThreadApi } from '../stream/sessions';
+
+/**
+ * The chat API kit's thread shapes (django-cfg `django_llm.agent.chat.api`), as the generated client names them (`ChatThread`, `ChatThreadListItem`,
+ * `ChatThreadDetail`, `ChatMessage`). Structural and read-only: a generated type is assignable (its enums are string enums), and a field the contract
+ * changes shows up at the host's call site as a type error. Only the fields the widget reads are listed.
+ */
+export interface ChatMessageShape {
+  id: string;
+  seq: number;
+  role: string;
+  text: string;
+  status: string;
+  /** `''` when there is none. */
+  error_code: string | null;
+  parts: ReadonlyArray<{ kind: string; data?: unknown }>;
+  created_at: string;
+}
+export interface ChatThreadShape {
+  id: string;
+  title: string;
+  updated_at: string;
+}
+export interface ChatThreadListItemShape extends ChatThreadShape {
+  message_count: number;
+  last_message_at: string | null;
+}
+export interface ChatThreadDetailShape extends ChatThreadShape {
+  messages: readonly ChatMessageShape[];
+}
+
+/** What a generated hey-api call resolves to (`{data, error, response}`); `response.status` carries a 404. */
+export interface ChatCallResult<T> {
+  data?: T;
+  error?: unknown;
+  response?: { status: number };
+}
+
+/** The three plain calls of the kit's thread routes, as the host maps them from its generated client (`Chat.chatThreadsList`, ...). The stream is not among them: no schema describes it. */
+export interface ChatThreadCalls {
+  list: (options: { signal?: AbortSignal }) => Promise<ChatCallResult<readonly ChatThreadListItemShape[]>>;
+  create: (options: { body?: { kind?: string } }) => Promise<ChatCallResult<ChatThreadShape>>;
+  retrieve: (options: { path: { thread_id: string }; signal?: AbortSignal }) => Promise<ChatCallResult<ChatThreadDetailShape>>;
+}
+
+const STATUSES: readonly StoredStatus[] = ['done', 'running', 'error', 'cancelled'];
+
+/** The kit's message as the widget's stored message. An unknown status reads as `error` (never a spinner without a stream). */
+export function storedMessageOf(message: ChatMessageShape): StoredMessage {
+  return {
+    id: message.id,
+    seq: message.seq,
+    role: message.role === 'user' ? 'user' : 'assistant',
+    text: message.text,
+    parts: message.parts.map((part) => ({ kind: part.kind, data: part.data })),
+    status: (STATUSES as readonly string[]).includes(message.status) ? (message.status as StoredStatus) : 'error',
+    error_code: message.error_code ? message.error_code : null,
+    created_at: message.created_at,
+  };
+}
+
+/** A listed row, or a freshly created thread (`POST` answers without the counters). */
+export function storedThreadOf(row: ChatThreadShape & Partial<Pick<ChatThreadListItemShape, 'message_count' | 'last_message_at'>>): StoredThread {
+  return { id: row.id, title: row.title, last_message_at: row.last_message_at ?? row.updated_at, message_count: row.message_count ?? 0 };
+}
+
+export interface ChatTransportConfig
+  extends Pick<TransportConfig, 'getToken' | 'headers' | 'idleMs' | 'streamFetch'> {
+  /** The thread calls of the generated client. */
+  client: ChatThreadCalls;
+  /** API origin, no trailing slash (the stream is called directly, never through a rewrite). */
+  baseUrl: string;
+  /** Where the kit is mounted, e.g. `/apix/assistant` (no trailing slash). The stream goes to `<mount>/threads/<id>/messages/`. */
+  mount: string;
+  /** `false` when the kit was mounted with `trailing_slash=False`. Default `true`. */
+  trailingSlash?: boolean;
+  /** The chat kind "New chat" asks for; omit where the server named a default kind. */
+  kind?: string;
+}
+
+export interface ChatConnection {
+  /** Hand to `useSession({ transport })`. */
+  transport: ChatTransport;
+  /** Hand to `useSession({ api })`. */
+  api: ThreadApi;
+}
+
+/**
+ * Everything a host connects to the kit, from the generated client's three thread calls: the SSE transport (`POST <mount>/threads/<id>/messages`, the frames of
+ * `wire-contract.md`) and the `ThreadApi` for list / new chat / load (a 404 is `ThreadNotFoundError`, an error body or an absent one is a plain `Error`).
+ * The host adds renderers, words, auth (`getToken` / `streamFetch`) and the mount point; nothing else.
+ */
+export function createChatTransport(config: ChatTransportConfig): ChatConnection {
+  const { client, baseUrl, mount, kind, trailingSlash = true } = config;
+  const tail = trailingSlash ? '/' : '';
+  const streamUrl = ({ threadId }: SendInput) => `${mount}/threads/${encodeURIComponent(threadId ?? '')}/messages${tail}`;
+  const transport = createTransport({ baseUrl, streamUrl, getToken: config.getToken, headers: config.headers, idleMs: config.idleMs, streamFetch: config.streamFetch });
+  const api: ThreadApi = {
+    async list(signal) {
+      const res = await client.list({ signal });
+      if (res.error || !res.data) throw new Error('chat threads');
+      return res.data.map(storedThreadOf);
+    },
+    async create() {
+      const res = await client.create(kind ? { body: { kind } } : {});
+      if (res.error || !res.data) throw new Error('chat create');
+      return storedThreadOf(res.data);
+    },
+    async load(id, signal): Promise<StoredConversation> {
+      const res = await client.retrieve({ path: { thread_id: id }, signal });
+      if (res.response?.status === 404) throw new ThreadNotFoundError();
+      if (res.error || !res.data) throw new Error('chat thread');
+      return { id: res.data.id, messages: res.data.messages.map(storedMessageOf) };
+    },
+  };
+  return { transport, api };
+}

package/src/sessions/storage.ts

@@ -0,0 +1,32 @@
+'use client';
+
+import { useMemo } from 'react';
+
+import type { SessionStorage } from '../stream/sessions';
+
+/** The last used session id in a Storage (default `localStorage`). Never throws: remembering is a convenience (private mode, a full quota, SSR). */
+export function createSessionStorage(key: string, backing?: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>): SessionStorage {
+  const store = () => backing ?? (typeof localStorage === 'undefined' ? null : localStorage);
+  return {
+    read: () => {
+      try {
+        return store()?.getItem(key) ?? null;
+      } catch {
+        return null;
+      }
+    },
+    write: (id) => {
+      try {
+        if (id) store()?.setItem(key, id);
+        else store()?.removeItem(key);
+      } catch {
+        // see above
+      }
+    },
+  };
+}
+
+/** A stable `SessionStorage` for `useSession({ storage })`: the key should be namespaced to the app (and to the account if accounts share a browser). */
+export function useRememberedSession(key: string): SessionStorage {
+  return useMemo(() => createSessionStorage(key), [key]);
+}

package/src/stream/adapter.ts

@@ -37,7 +37,7 @@ export interface AdapterDeps {
 const defaultId = () => globalThis.crypto.randomUUID();
 
 /**
- * The wire to the widget. Maps one run's frames to chunks (`run` opens the assistant message, `text_delta` grows its text, `ui_payload` adds a card part after the text
+ * The wire to the widget. Maps one run's frames to chunks (`run` opens the assistant message, `text_delta` grows its text, the optional `reasoning_delta` / `reasoning_end` frames drive the widget's own Reasoning part, `ui_payload` adds a card part after the text
  * it follows, `done` finishes, `error` fails keeping the partial text); a stream that ends without a terminal frame is `interrupted`, and the host reconciles from the server.
  * Everything a run needs travels inside its own ordered chunk stream: no shared buffer between runs.
  */
@@ -56,8 +56,12 @@ export function createStreamAdapter(deps: AdapterDeps): ChatAdapter {
         async start(controller) {
           let messageId = '';
           let textPart: string | null = null;
+          /** The open reasoning part (optional `reasoning_delta` frames); sealed by `reasoning_end` or by the next part. */
+          let thoughtPart: string | null = null;
           let parts = 0;
           let pending = '';
+          /** The part `pending` belongs to, with the chunk that carries it. */
+          let pendingKind: 'text-delta' | 'reasoning-delta' = 'text-delta';
           let timer: ReturnType<typeof setTimeout> | null = null;
           let terminal = false;
           deps.onActive?.(true);
@@ -69,10 +73,25 @@ export function createStreamAdapter(deps: AdapterDeps): ChatAdapter {
           const flush = () => {
             if (timer) clearTimeout(timer);
             timer = null;
-            if (pending && textPart) controller.enqueue({ type: 'text-delta', partId: textPart, delta: pending });
+            const target = pendingKind === 'text-delta' ? textPart : thoughtPart;
+            if (pending && target) controller.enqueue({ type: pendingKind, partId: target, delta: pending });
             pending = '';
           };
+          const queue = (kind: 'text-delta' | 'reasoning-delta', delta: string) => {
+            if (pending && pendingKind !== kind) flush();
+            pendingKind = kind;
+            pending += delta;
+            if (coalesceMs === 0) flush();
+            else timer ??= setTimeout(flush, coalesceMs);
+          };
+          const endThought = (elapsedMs?: number, tokens?: number) => {
+            if (!thoughtPart) return;
+            flush();
+            controller.enqueue({ type: 'reasoning-end', partId: thoughtPart, ...(elapsedMs === undefined ? {} : { elapsedMs }), ...(tokens === undefined ? {} : { tokens }) });
+            thoughtPart = null;
+          };
           const fail = (message: string) => {
+            endThought();
             flush();
             if (!messageId) open(`local-${clientId}`);
             controller.enqueue({ type: 'error', message });
@@ -89,13 +108,25 @@ export function createStreamAdapter(deps: AdapterDeps): ChatAdapter {
                 break;
               case 'text_delta':
                 if (!messageId) break;
+                endThought();
                 if (!textPart) {
                   textPart = `${messageId}:t${parts++}`;
                   controller.enqueue({ type: 'text-start', partId: textPart });
                 }
-                pending += frame.delta;
-                if (coalesceMs === 0) flush();
-                else timer ??= setTimeout(flush, coalesceMs);
+                queue('text-delta', frame.delta);
+                break;
+              case 'reasoning_delta':
+                if (!messageId) break;
+                if (!thoughtPart) {
+                  flush();
+                  textPart = null;
+                  thoughtPart = `${messageId}:r${parts++}`;
+                  controller.enqueue({ type: 'reasoning-start', partId: thoughtPart });
+                }
+                queue('reasoning-delta', frame.delta);
+                break;
+              case 'reasoning_end':
+                endThought(frame.elapsed_ms ?? undefined, frame.tokens ?? undefined);
                 break;
               case 'ui_payload':
                 if (!messageId) break;
@@ -103,11 +134,13 @@ export function createStreamAdapter(deps: AdapterDeps): ChatAdapter {
                   deps.onUnknownPayload?.(frame.kind);
                   break;
                 }
+                endThought();
                 flush();
                 textPart = null;
                 controller.enqueue({ type: 'data', part: { type: 'data', id: `${messageId}:w${parts++}`, kind: frame.kind, data: frame.data } });
                 break;
               case 'done':
+                endThought();
                 flush();
                 controller.enqueue({ type: 'finish' });
                 terminal = true;
@@ -125,6 +158,7 @@ export function createStreamAdapter(deps: AdapterDeps): ChatAdapter {
               if (terminal) break;
             }
             if (!terminal) {
+              endThought();
               flush();
               if (!signal.aborted) {
                 controller.enqueue({ type: 'interrupted' });
@@ -139,6 +173,7 @@ export function createStreamAdapter(deps: AdapterDeps): ChatAdapter {
               deps.onNetworkFailure?.();
               fail(deps.messages.failed);
             } else if (error instanceof StreamLostError) {
+              endThought();
               flush();
               controller.enqueue({ type: 'interrupted' });
               deps.onInterrupted?.();

package/src/wire/fixtures/events.json

@@ -5,6 +5,8 @@
     { "type": "status", "phase": "thinking" },
     { "type": "status", "phase": "searching" },
     { "type": "status", "phase": "answering" },
+    { "type": "reasoning_delta", "delta": "Checking the refund policy. " },
+    { "type": "reasoning_end", "elapsed_ms": 1200, "tokens": 42 },
     { "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" },

package/src/wire/frames.ts

@@ -1,6 +1,7 @@
 /**
  * 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.
+ * `reasoning_delta` / `reasoning_end` are an optional layer: a host that never emits them is unaffected.
  * An unknown `type` is ignored and a malformed frame is dropped: the contract is forward compatible.
  */
 
@@ -14,6 +15,8 @@ export type Frame =
   | { 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: 'reasoning_delta'; delta: string }
+  | { type: 'reasoning_end'; elapsed_ms: number | null; tokens: number | null }
   | { 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 };
@@ -37,6 +40,10 @@ export function decodeFrame(raw: unknown): Frame | null {
       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 'reasoning_delta':
+      return str(raw.delta) ? { type: 'reasoning_delta', delta: raw.delta } : null;
+    case 'reasoning_end':
+      return { type: 'reasoning_end', elapsed_ms: num(raw.elapsed_ms), tokens: num(raw.tokens) };
     case 'ui_payload':
       return str(raw.kind) && raw.kind !== '' && 'data' in raw ? { type: 'ui_payload', kind: raw.kind, data: raw.data } : null;
     case 'done':