@djangocfg/widget-assistant 0.0.0-stage → 0.1.1

package/src/shell/panelState.ts

@@ -0,0 +1,74 @@
+import { useEffect, useSyncExternalStore } from 'react';
+import { create } from 'zustand';
+
+/** Where the open flag and the width are remembered. The host decides the keys; reads and writes must never throw. */
+export interface UiStorage {
+  read: (field: 'open' | 'width') => string | null;
+  write: (field: 'open' | 'width', value: string) => void;
+}
+
+export interface UiOptions {
+  storage?: UiStorage;
+  minWidth?: number;
+  maxWidth?: number;
+  defaultWidth?: number;
+  /** Whether the column starts open for a viewer who has never chosen. A choice, once made, is remembered. */
+  defaultOpen?: boolean;
+}
+
+export interface UiState {
+  open: boolean;
+  width: number;
+  setOpen: (open: boolean) => void;
+  setWidth: (width: number) => void;
+  /** Read the remembered state once (`canOpen` decides whether a remembered "open" applies on this screen: a column does, a full-screen sheet must not reopen by itself), once the browser is up (the server render and the first client render both show it closed). */
+  restore: (canOpen?: () => boolean) => void;
+}
+
+/** Open/closed and column width of the assistant, remembered through `storage`. One store per host app. */
+export function createAssistantUi({ storage, minWidth = 320, maxWidth = 560, defaultWidth = 400, defaultOpen = false }: UiOptions = {}) {
+  const clamp = (width: number) => Math.min(maxWidth, Math.max(minWidth, Math.round(width)));
+  const useUi = create<UiState>((set) => ({
+    open: false,
+    width: defaultWidth,
+    setOpen: (open) => {
+      storage?.write('open', open ? '1' : '0');
+      set({ open });
+    },
+    setWidth: (next) => {
+      const width = clamp(next);
+      storage?.write('width', String(width));
+      set({ width });
+    },
+    restore: (canOpen) => {
+      const width = Number(storage?.read('width'));
+      const stored = storage?.read('open');
+      const wanted = stored == null ? defaultOpen : stored === '1';
+      set({ open: wanted && (canOpen ? canOpen() : true), width: Number.isFinite(width) && width > 0 ? clamp(width) : defaultWidth });
+    },
+  }));
+  return {
+    useUi,
+    open: () => useUi.getState().setOpen(true),
+    close: () => useUi.getState().setOpen(false),
+    limits: { minWidth, maxWidth, defaultWidth },
+    /** Mount once in the shell. */
+    useRestore: (canOpen?: () => boolean) => {
+      const restore = useUi((s) => s.restore);
+      useEffect(() => restore(canOpen), []); // eslint-disable-line react-hooks/exhaustive-deps
+    },
+  };
+}
+
+/** A media query as state: `false` on the server and during hydration, so server and first client render agree. */
+export function useMediaQuery(query: string): boolean {
+  return useSyncExternalStore(
+    (onChange) => {
+      const list = window.matchMedia(query);
+      list.addEventListener('change', onChange);
+      return () => list.removeEventListener('change', onChange);
+    },
+    () => window.matchMedia(query).matches,
+    () => false,
+  );
+}

package/src/stream/adapter.ts

@@ -0,0 +1,144 @@
+import type { ChatAdapter, StreamChunk } from '@djangocfg/widget-chat';
+
+import type { ChatContext, Frame, Phase, StreamErrorCode } from '../wire/frames.ts';
+import { StreamLostError } from '../wire/parseSSE.ts';
+import { ChatHttpError, ChatNetworkError, type ChatTransport } from '../wire/transport.ts';
+
+export interface AdapterDeps {
+  transport: ChatTransport;
+  /** Scope of this turn, read at send time (the page the user is on). */
+  getContext: () => ChatContext | undefined;
+  /** Ephemeral progress for the live label above the composer; `null` when the run ends. Never enters the transcript. */
+  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 stream ended without a terminal frame: the host reconciles from the server. */
+  onInterrupted?: () => void;
+  /** A network-level failure, for the connectivity monitor. */
+  onNetworkFailure?: () => void;
+  /** One plain sentence per outcome (the catalogue). */
+  messages: {
+    rejected: (error: ChatHttpError) => string;
+    streamError: (code: StreamErrorCode, serverMessage: string) => string;
+    failed: string;
+  };
+  newId?: () => string;
+  /** Token coalescing window; `0` forwards every delta at once (tests). About 30 fps by default. */
+  coalesceMs?: number;
+}
+
+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
+ * 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.
+ */
+export function createStreamAdapter(deps: AdapterDeps): ChatAdapter {
+  const newId = deps.newId ?? defaultId;
+  const coalesceMs = deps.coalesceMs ?? 33;
+  /** The last attempt that never reached `run`: resending the same text reuses its `client_id` (nothing ran, so the resend is idempotent). */
+  let unsent: { text: string; clientId: string } | null = null;
+
+  return {
+    async sendMessage({ text, signal }) {
+      const clientId = unsent?.text === text ? unsent.clientId : newId();
+      unsent = { text, clientId };
+
+      return new ReadableStream<StreamChunk>({
+        async start(controller) {
+          let messageId = '';
+          let textPart: string | null = null;
+          let parts = 0;
+          let pending = '';
+          let timer: ReturnType<typeof setTimeout> | null = null;
+          let terminal = false;
+
+          const open = (id: string) => {
+            messageId = id;
+            controller.enqueue({ type: 'message-start', messageId: id, createdAt: Date.now() });
+          };
+          const flush = () => {
+            if (timer) clearTimeout(timer);
+            timer = null;
+            if (pending && textPart) controller.enqueue({ type: 'text-delta', partId: textPart, delta: pending });
+            pending = '';
+          };
+          const fail = (message: string) => {
+            flush();
+            if (!messageId) open(`local-${clientId}`);
+            controller.enqueue({ type: 'error', message });
+            terminal = true;
+          };
+          const handle = (frame: Frame) => {
+            switch (frame.type) {
+              case 'run':
+                unsent = null;
+                open(frame.assistant_message_id);
+                break;
+              case 'status':
+                deps.onStatus(frame.phase);
+                break;
+              case 'text_delta':
+                if (!messageId) break;
+                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);
+                break;
+              case 'ui_payload':
+                if (!messageId) break;
+                flush();
+                textPart = null;
+                controller.enqueue({ type: 'data', part: { type: 'data', id: `${messageId}:w${parts++}`, kind: frame.kind, data: frame.data } });
+                break;
+              case 'done':
+                flush();
+                controller.enqueue({ type: 'finish' });
+                terminal = true;
+                break;
+              case 'error':
+                fail(deps.messages.streamError(frame.code, frame.message));
+                break;
+            }
+          };
+
+          try {
+            for await (const frame of deps.transport.open({ text, clientId, context: deps.getContext(), signal })) {
+              handle(frame);
+              if (terminal) break;
+            }
+            if (!terminal) {
+              flush();
+              if (!signal.aborted) {
+                controller.enqueue({ type: 'interrupted' });
+                deps.onInterrupted?.();
+              }
+            }
+          } catch (error) {
+            if (error instanceof ChatHttpError) {
+              deps.onRejected?.(error);
+              fail(deps.messages.rejected(error));
+            } else if (error instanceof ChatNetworkError) {
+              deps.onNetworkFailure?.();
+              fail(deps.messages.failed);
+            } else if (error instanceof StreamLostError) {
+              flush();
+              controller.enqueue({ type: 'interrupted' });
+              deps.onInterrupted?.();
+            } else {
+              fail(deps.messages.failed);
+            }
+          } finally {
+            if (timer) clearTimeout(timer);
+            deps.onStatus(null);
+            controller.close();
+          }
+        },
+      });
+    },
+  };
+}

package/src/stream/fromStored.ts

@@ -0,0 +1,23 @@
+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).
+ */
+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 } });
+  });
+  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 };
+}
+
+export const fromStoredThread = (messages: readonly StoredMessage[], failedText: string): ChatMessage[] => messages.map((m) => fromStored(m, failedText));

package/src/stream/reconcile.ts

@@ -0,0 +1,45 @@
+import type { StoredConversation, StoredMessage } from '../wire/stored.ts';
+
+/** What the server says about the run the client lost track of. */
+export type Reconciled =
+  | { outcome: 'done' | 'error' | 'cancelled'; conversation: StoredConversation }
+  /** The server never stored an answer: nothing ran, a resend with the same `client_id` is safe. */
+  | { outcome: 'lost'; conversation: StoredConversation }
+  /** Still running after the budget: offer Retry, keep looking on the next load. */
+  | { outcome: 'timeout'; conversation: StoredConversation };
+
+export interface ReconcileDeps {
+  fetchConversation: (signal: AbortSignal) => Promise<StoredConversation>;
+  signal: AbortSignal;
+  sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+  now?: () => number;
+  pollMs?: number;
+  budgetMs?: number;
+}
+
+const wait = (ms: number, signal: AbortSignal) =>
+  new Promise<void>((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    signal.addEventListener('abort', () => {
+      clearTimeout(timer);
+      resolve();
+    }, { once: true });
+  });
+
+const lastAssistant = (messages: StoredMessage[]): StoredMessage | undefined => [...messages].reverse().find((m) => m.role === 'assistant');
+
+/**
+ * Refetch the thread and trust the last assistant message (CONTRACT.md "Abort, loss and reconcile"): `done`, `error` and `cancelled` are final;
+ * `running` is polled every 2 s for about 60 s. No replay, no resume: the stored message is the truth. A fetch failure throws; the caller shows Retry.
+ */
+export async function reconcile({ fetchConversation, signal, sleep = wait, now = Date.now, pollMs = 2000, budgetMs = 60_000 }: ReconcileDeps): Promise<Reconciled> {
+  const deadline = now() + budgetMs;
+  for (;;) {
+    const conversation = await fetchConversation(signal);
+    const last = lastAssistant(conversation.messages);
+    if (!last) return { outcome: 'lost', conversation };
+    if (last.status !== 'running') return { outcome: last.status, conversation };
+    if (now() + pollMs > deadline || signal.aborted) return { outcome: 'timeout', conversation };
+    await sleep(pollMs, signal);
+  }
+}

package/src/stream/scriptedTransport.ts

@@ -0,0 +1,28 @@
+import type { Frame } from '../wire/frames.ts';
+import type { ChatTransport } from '../wire/transport.ts';
+
+/** One step of a scripted run: a frame after a pause, or an error thrown as a real transport would (refusal, network, lost stream). */
+export type ScriptStep = { frame: Frame; after?: number } | { throw: Error; after?: number };
+
+const pause = (ms: number, signal: AbortSignal) =>
+  new Promise<void>((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    signal.addEventListener('abort', () => {
+      clearTimeout(timer);
+      resolve();
+    }, { once: true });
+  });
+
+/** A transport that replays a script: stories and tests drive the real adapter and session with it, so every state is the production code path. */
+export function scriptedTransport(steps: ScriptStep[] | ((text: string) => ScriptStep[])): ChatTransport {
+  return {
+    async *open({ text, signal }) {
+      for (const step of typeof steps === 'function' ? steps(text) : steps) {
+        await pause(step.after ?? 40, signal);
+        if (signal.aborted) return;
+        if ('throw' in step) throw step.throw;
+        yield step.frame;
+      }
+    },
+  };
+}

package/src/stream/useSession.ts

@@ -0,0 +1,136 @@
+'use client';
+
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import type { ChatAdapter, ChatMessage } from '@djangocfg/widget-chat';
+
+import { useAssistantCopy } from '../i18n';
+import { sessionCopyFor } from '../i18n/sessionCopy';
+
+import type { ChatContext, Phase } from '../wire/frames.ts';
+import type { StoredConversation } from '../wire/stored.ts';
+import type { ChatHttpError, ChatTransport } from '../wire/transport.ts';
+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. */
+export interface ThreadApi {
+  load: (signal: AbortSignal) => Promise<StoredConversation>;
+  clear: () => Promise<void>;
+}
+
+export interface SessionCopy {
+  messages: AdapterDeps['messages'];
+  /** Live label per phase ("Searching the catalog..."). */
+  status: Record<Phase, string>;
+  /** Shown on a message that ended in an error when the thread is reloaded. */
+  failedText: string;
+}
+
+export interface SessionDeps {
+  transport: ChatTransport;
+  api: ThreadApi;
+  getContext: () => ChatContext | undefined;
+  /** Absent: the bundled words for the active language. */
+  copy?: SessionCopy;
+  onRejected?: (error: ChatHttpError) => void;
+  onNetworkFailure?: () => void;
+}
+
+export type ThreadState = { kind: 'loading' } | { kind: 'error' } | { kind: 'ready'; id: string; history: ChatMessage[] };
+
+/** `reconnecting`: the stream was lost and the server is being asked; `stalled`: the answer is still running after the budget (offer Retry). */
+export type SessionNotice = 'reconnecting' | 'stalled';
+
+export interface Session {
+  thread: ThreadState;
+  adapter: ChatAdapter;
+  /** Live progress label while a run streams; null otherwise. */
+  statusLabel: string | null;
+  notice: SessionNotice | null;
+  /** Load the thread again (after a load error or a stalled run). */
+  reload: () => void;
+  /** Delete the conversation; the next message starts a new one. */
+  clear: () => Promise<void>;
+}
+
+/**
+ * One signed-in conversation: the thread from the server (no client copy), the adapter for new messages, the live status label, and the reconcile
+ * that runs when a stream is lost. A new `history` identity (`id` carries a revision) reseeds the widget only between runs.
+ */
+export function useSession(given: SessionDeps): Session {
+  const bundled = useAssistantCopy();
+  const deps = { ...given, copy: given.copy ?? sessionCopyFor(bundled) };
+  const ref = useRef(deps);
+  ref.current = deps;
+  const [thread, setThread] = useState<ThreadState>({ kind: 'loading' });
+  const [phase, setPhase] = useState<Phase | null>(null);
+  const [notice, setNotice] = useState<SessionNotice | null>(null);
+  const revision = useRef(0);
+  const live = useRef<AbortController | null>(null);
+
+  const seed = useCallback((conversation: StoredConversation) => {
+    revision.current += 1;
+    setThread({ kind: 'ready', id: `${conversation.id ?? 'new'}:${revision.current}`, history: fromStoredThread(conversation.messages, ref.current.copy.failedText) });
+  }, []);
+
+  const load = useCallback(() => {
+    live.current?.abort();
+    const controller = new AbortController();
+    live.current = controller;
+    setThread({ kind: 'loading' });
+    setNotice(null);
+    ref.current.api.load(controller.signal).then(
+      (conversation) => !controller.signal.aborted && seed(conversation),
+      () => !controller.signal.aborted && setThread({ kind: 'error' }),
+    );
+  }, [seed]);
+
+  useEffect(() => {
+    load();
+    return () => live.current?.abort();
+  }, [load]);
+
+  const adapter = useMemo(
+    () =>
+      createStreamAdapter({
+        transport: deps.transport,
+        getContext: () => ref.current.getContext(),
+        onStatus: setPhase,
+        onRejected: (error) => ref.current.onRejected?.(error),
+        onNetworkFailure: () => ref.current.onNetworkFailure?.(),
+        messages: {
+          rejected: (error) => ref.current.copy.messages.rejected(error),
+          streamError: (code, message) => ref.current.copy.messages.streamError(code, message),
+          get failed() {
+            return ref.current.copy.messages.failed;
+          },
+        },
+        onInterrupted: () => {
+          setNotice('reconnecting');
+          const controller = new AbortController();
+          live.current = controller;
+          reconcile({ fetchConversation: ref.current.api.load, signal: controller.signal }).then(
+            (result) => {
+              if (controller.signal.aborted) return;
+              if (result.outcome === 'timeout') return setNotice('stalled');
+              setNotice(null);
+              seed(result.conversation);
+            },
+            () => !controller.signal.aborted && setNotice('stalled'),
+          );
+        },
+      }),
+    // The transport is one per mounted chat; everything else is read through `ref`.
+    [deps.transport, seed],
+  );
+
+  const clear = useCallback(async () => {
+    await ref.current.api.clear();
+    live.current?.abort();
+    seed({ id: null, messages: [] });
+  }, [seed]);
+
+  return { thread, adapter, statusLabel: phase ? ref.current.copy.status[phase] : null, notice, reload: load, clear };
+}

package/src/styles/composer.css

@@ -0,0 +1,14 @@
+/* A larger composer than the widget default, through the widget's own tokens, so the field reads as the main control of the dock. */
+.assistant-chat {
+  --chat-composer-inset-y: 0.625rem;
+  --chat-composer-inset-x: 1rem;
+  --chat-composer-control-h: 2.5rem;
+}
+
+/* Field text and controls share one centre line: the box aligns items to the end by default, which sat the text a few pixels low. */
+.assistant-chat .composer-box {
+  align-items: center;
+}
+.assistant-chat .composer-box textarea {
+  padding-block: 0.25rem;
+}

package/src/styles/fab.css

@@ -0,0 +1,53 @@
+/* The floating button's motion: it pops in on load, its hint bubble grows out of the button, and a ring now and then reminds of it. All of it only for people who allow motion. */
+@media (prefers-reduced-motion: no-preference) {
+  .assistant-fab {
+    animation: assistant-fab-pop 0.6s cubic-bezier(0.34, 1.56, 0.64, 1) both;
+  }
+  .assistant-fab-hint {
+    transform-origin: bottom right;
+    animation: assistant-fab-hint-in 0.45s cubic-bezier(0.34, 1.56, 0.64, 1) both;
+  }
+  .assistant-fab-hint[data-leaving] {
+    animation: assistant-fab-hint-out 0.25s ease-in both;
+  }
+  .assistant-fab-ring {
+    animation: assistant-fab-ring 1.8s ease-out 2 both;
+  }
+}
+
+@keyframes assistant-fab-pop {
+  from {
+    opacity: 0;
+    transform: translateY(1.5rem) scale(0.4);
+  }
+  to {
+    opacity: 1;
+    transform: none;
+  }
+}
+@keyframes assistant-fab-hint-in {
+  from {
+    opacity: 0;
+    transform: translateY(0.5rem) scale(0.6);
+  }
+  to {
+    opacity: 1;
+    transform: none;
+  }
+}
+@keyframes assistant-fab-hint-out {
+  to {
+    opacity: 0;
+    transform: translateY(0.25rem) scale(0.9);
+  }
+}
+@keyframes assistant-fab-ring {
+  from {
+    opacity: 0.55;
+    transform: scale(1);
+  }
+  to {
+    opacity: 0;
+    transform: scale(1.9);
+  }
+}

package/src/styles/index.css

@@ -0,0 +1,6 @@
+/* Chat styles: the widget stylesheet and sources, then our layout and composer rules. */
+@import "./widget.css";
+@import "./layout.css";
+@import "./composer.css";
+@import "./fab.css";
+@source "../**/*.{ts,tsx}";

package/src/styles/layout.css

@@ -0,0 +1,15 @@
+/*
+ * The widget's root is a plain block: the host supplies the column layout (`AssistantChat` adds `.assistant-chat`).
+ * The widget reserves its inset on the right only (room for a scrollbar) and leaves the left to the host, so one token is mirrored
+ * on the left, plus a bottom margin for the composer.
+ */
+.assistant-chat {
+  --chat-edge-r: 0.75rem;
+  padding-inline-start: 0.75rem;
+  padding-block-end: 0.75rem;
+}
+
+/* The transcript takes the free height and scrolls, so the composer sits at the bottom of the dock. */
+.assistant-chat > .chat-surface {
+  flex: 1 1 0;
+}

package/src/styles/widget.css

@@ -0,0 +1,7 @@
+/* The widget's own stylesheet carries the visual rules (composer, transcript, markdown); it must join the Tailwind pipeline by @import, not by a JS import in a component. */
+@import "@djangocfg/widget-chat/styles";
+
+/* Tailwind must see the widgets' classes: without these sources it purges them silently (the root node_modules holds them; the package has none of its own). */
+@source "../../../../node_modules/@djangocfg/widget-chat/src/**/*.{ts,tsx}";
+@source "../../../../node_modules/@djangocfg/widget-kit/src/**/*.{ts,tsx}";
+@source "../../../../node_modules/@djangocfg/widget-media/src/**/*.{ts,tsx}";

package/src/wire/frames.ts

@@ -0,0 +1,53 @@
+/** The assistant SSE stream (frames: text deltas, tool and status events, structured parts, errors). The only file that knows the frame shapes. */
+
+export type Phase = 'thinking' | 'searching' | 'reading' | 'choosing';
+export type StreamErrorCode = 'unavailable' | 'timeout' | 'failed';
+
+export type Frame =
+  | { type: 'run'; run_id: string; user_message_id: string; assistant_message_id: string }
+  | { 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 };
+
+const PHASES: readonly string[] = ['thinking', 'searching', 'reading', 'choosing'];
+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';
+
+/** 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. */
+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 }
+        : 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 'done':
+      return str(raw.assistant_message_id) ? { type: 'done', assistant_message_id: raw.assistant_message_id } : null;
+    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;
+    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 };
+
+/** 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;