@djangocfg/widget-assistant 0.3.9 → 0.3.11

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.9",
+  "version": "0.3.11",
   "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.25",
+    "@djangocfg/widget-chat": "^0.1.27",
     "zustand": "^5.0.16"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.624",
-    "@djangocfg/ui-core": "^2.1.624",
+    "@djangocfg/i18n": "^2.1.626",
+    "@djangocfg/ui-core": "^2.1.626",
     "lucide-react": "^1.68.0",
     "react": "^19.0.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.624",
-    "@djangocfg/typescript-config": "^2.1.624",
-    "@djangocfg/ui-core": "^2.1.624",
+    "@djangocfg/i18n": "^2.1.626",
+    "@djangocfg/typescript-config": "^2.1.626",
+    "@djangocfg/ui-core": "^2.1.626",
     "@storybook/react-vite": "^10.6.5",
     "@types/node": "^25.9.5",
     "@types/react": "19.3.0",

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':