@djangocfg/widget-assistant 0.3.13 → 0.3.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/widget-assistant",
-  "version": "0.3.13",
+  "version": "0.3.15",
   "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.29",
+    "@djangocfg/widget-chat": "^0.1.31",
     "zustand": "^5.0.16"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.628",
-    "@djangocfg/ui-core": "^2.1.628",
+    "@djangocfg/i18n": "^2.1.635",
+    "@djangocfg/ui-core": "^2.1.635",
     "lucide-react": "^1.68.0",
     "react": "^19.0.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.628",
-    "@djangocfg/typescript-config": "^2.1.628",
-    "@djangocfg/ui-core": "^2.1.628",
+    "@djangocfg/i18n": "^2.1.635",
+    "@djangocfg/typescript-config": "^2.1.635",
+    "@djangocfg/ui-core": "^2.1.635",
     "@storybook/react-vite": "^10.6.5",
     "@types/node": "^25.9.5",
     "@types/react": "19.3.0",

package/src/AssistantChat.tsx

@@ -20,7 +20,6 @@ import { useAssistantLocale } from './i18n';
 import { bundledEarcons } from './composer/earcons';
 import { createWholeTranscriptSpeech } from './composer/wholeTranscript';
 import { AssistantComposer } from './composer/AssistantComposer';
-import { ComposerHelp } from './composer/ComposerHelp';
 import { MessageFooter } from './messages/MessageFooter';
 import { NoticeLine } from './messages/NoticeLine';
 
@@ -36,7 +35,10 @@ export interface SpeechLanguage {
 interface Props {
   adapter: ChatAdapter;
   /** Example prompts shown in an empty chat. */
-  suggestions: string[];
+  /** The starter rows: a prompt, or `{ prompt, icon }` with an icon key (`SUGGESTION_ICON_KEYS`). */
+  suggestions: (string | { prompt: string; icon?: string })[];
+  /** What the empty room shows above the starter rows: `<AssistantGreeting title="…" mark={…} />`, or any node. Absent: the widget's plain empty line. */
+  greeting?: ReactNode;
   /** 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`. */
@@ -67,7 +69,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, draftRoom, dataRenderers = NO_RENDERERS, speech: given, sounds, messageSounds, notice, onRetry, focusWhen, refocus, className }: Props) {
+export function AssistantChat({ adapter, suggestions, greeting, 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),
@@ -89,7 +91,7 @@ export function AssistantChat({ adapter, suggestions, conversation = EMPTY_ROOM,
   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 } : {}), ...(sounds === false ? {} : { voiceSounds: sounds ?? bundledEarcons }), ...(messageSounds === undefined ? {} : { sounds: messageSounds }) }),
+    () => ({ suggestions: { items: suggestions.map((row, index) => { const item = typeof row === 'string' ? { prompt: row } : row; return { id: `s${index}`, title: item.prompt, prompt: item.prompt, ...('icon' in item && item.icon ? { icon: item.icon } : {}) }; }) }, ...(voice ? { voice } : {}), ...(sounds === false ? {} : { voiceSounds: sounds ?? bundledEarcons }), ...(messageSounds === undefined ? {} : { sounds: messageSounds }) }),
     [suggestions, voice, sounds, messageSounds],
   );
   const slots = useMemo(
@@ -99,7 +101,6 @@ export function AssistantChat({ adapter, suggestions, conversation = EMPTY_ROOM,
       footer: (
         <>
           {notice ? <NoticeLine notice={notice} onRetry={onRetry} /> : null}
-          <ComposerHelp />
         </>
       ),
     }),
@@ -117,7 +118,7 @@ export function AssistantChat({ adapter, suggestions, conversation = EMPTY_ROOM,
         kind: 'custom',
         children: (
           <>
-            <ChatTranscript footer={(message) => <MessageFooter message={message} />} />
+            <ChatTranscript {...(greeting === undefined ? {} : { empty: greeting })} footer={(message) => <MessageFooter message={message} />} />
             <AssistantComposer speech={speech} draftRoom={draftRoom ?? conversation.id ?? 'assistant'} focusWhen={focusWhen} refocus={refocus} />
           </>
         ),

package/src/composer/AssistantComposer.tsx

@@ -3,6 +3,7 @@
 import { ChatComposer } from '@djangocfg/widget-chat';
 
 import { ComposerBehaviour } from './ComposerBehaviour';
+import { suggestionIcon } from './suggestionIcons';
 import { useSentPrompts } from './useSentPrompts';
 
 interface Props {
@@ -15,5 +16,5 @@ interface Props {
 /** The widget's composer with its recall fed from the live transcript and our behaviour mounted inside. Must sit inside the chat. */
 export function AssistantComposer({ speech, draftRoom, focusWhen, refocus }: Props) {
   const history = useSentPrompts();
-  return <ChatComposer history={history} speechLanguage={speech} draftRoom={draftRoom} toolbarEnd={<ComposerBehaviour focusWhen={focusWhen} refocus={refocus} />} />;
+  return <ChatComposer history={history} speechLanguage={speech} draftRoom={draftRoom} stacked suggestionIcon={suggestionIcon} toolbarEnd={<ComposerBehaviour focusWhen={focusWhen} refocus={refocus} />} />;
 }

package/src/composer/ComposerBehaviour.tsx

@@ -3,7 +3,7 @@
 import { useCallback, useEffect, useRef } from 'react';
 
 import { useHotkey } from '@djangocfg/ui-core/hooks';
-import { useComposer } from '@djangocfg/widget-chat';
+import { useComposer, useTurn } from '@djangocfg/widget-chat';
 
 import { useCaretFocus } from './useCaretFocus';
 import { clearPendingPrompt, usePendingPrompt } from './handoff';
@@ -53,7 +53,8 @@ export function ComposerBehaviour({ focusWhen = false, refocus = false }: Props)
   const recording = useRecording(nodes);
   useHeightFloor(nodes, recording);
   useFocusArea(nodes, marker, refocus);
-  useCaretFocus(nodes, { focusWhen, refocus, recording, onSend: composer.onSend });
+  const { isStreaming } = useTurn();
+  useCaretFocus(nodes, { focusWhen, refocus, recording, streaming: isStreaming, onSend: composer.onSend });
 
   // Waits for the words still being recognised, then commits them into the draft; sending reads the draft after that.
   const stop = useGracefulStop(nodes, recording, useCallback(() => latest.current.draft.text, []));

package/src/composer/suggestionIcons.tsx

@@ -0,0 +1,22 @@
+import { BarChart3, FileText, Filter, ListChecks, PenLine, Search, Sparkles, Wand2 } from 'lucide-react';
+import type { ReactNode } from 'react';
+
+/** The starter rows' glyphs, by key. A row names one with `{ prompt, icon: 'search' }`; an unknown key draws none. */
+const ICONS = {
+  sparkles: Sparkles,
+  search: Search,
+  summarize: FileText,
+  write: PenLine,
+  tidy: ListChecks,
+  chart: BarChart3,
+  filter: Filter,
+  agent: Wand2,
+} as const;
+
+export type SuggestionIconKey = keyof typeof ICONS;
+export const SUGGESTION_ICON_KEYS = Object.keys(ICONS) as SuggestionIconKey[];
+
+export function suggestionIcon(key: string): ReactNode {
+  const Icon = (ICONS as Record<string, (typeof ICONS)[SuggestionIconKey]>)[key];
+  return Icon ? <Icon className="size-4 shrink-0 text-muted-foreground" aria-hidden /> : null;
+}

package/src/composer/useCaretFocus.ts

@@ -8,22 +8,50 @@ interface Options {
   /** A keyboard device: after a send the caret returns to the field, or to the microphone when the send ended a dictation (so Enter starts the next one). */
   refocus: boolean;
   recording: boolean;
+  /** A reply is streaming. When it ends (keyboard devices) the caret returns to the field, so the next question can be typed at once. */
+  streaming?: boolean;
   /** The draft's send listener registry. */
   onSend: (listener: () => void) => () => void;
 }
 
 /** Where the caret is after the panel opens and after a send. Both are for keyboards only: on a phone either would raise the keyboard over the answer. */
-export function useCaretFocus({ mic, field }: ComposerNodes, { focusWhen, refocus, recording, onSend }: Options): void {
+export function useCaretFocus({ mic, field }: ComposerNodes, { focusWhen, refocus, recording, streaming = false, onSend }: Options): void {
   const wasOn = useRef(focusWhen);
   useEffect(() => {
+    let frame = 0;
     if (focusWhen && !wasOn.current) {
-      const node = field();
-      node?.focus();
-      node?.setSelectionRange(node.value.length, node.value.length);
+      // The column mounts a render AFTER the flag flips and the chat is still parked in a hidden element until then: focusing now is a silent no-op.
+      // Retry per frame until the field is laid out (it is on screen), for at most ~1 s.
+      let tries = 0;
+      const attempt = () => {
+        const node = field();
+        if (node && node.getClientRects().length > 0) {
+          node.focus({ preventScroll: true });
+          node.setSelectionRange(node.value.length, node.value.length);
+        } else if (++tries < 60) {
+          frame = requestAnimationFrame(attempt);
+        }
+      };
+      attempt();
     }
     wasOn.current = focusWhen;
+    return () => cancelAnimationFrame(frame);
   }, [focusWhen, field]);
 
+  // The reply finished streaming: the caret goes back to the field. The send's own refocus is too early (the answer has not started yet),
+  // and the focus may have wandered off meanwhile (the stop button, a link inside the answer).
+  const wasStreaming = useRef(streaming);
+  useEffect(() => {
+    const ended = wasStreaming.current && !streaming;
+    wasStreaming.current = streaming;
+    if (!ended || !refocus) return;
+    const id = window.setTimeout(() => {
+      const node = field();
+      if (node && !typingElsewhere(node) && node.getClientRects().length > 0) node.focus({ preventScroll: true });
+    }, 0);
+    return () => window.clearTimeout(id);
+  }, [streaming, refocus, field]);
+
   // Read through a ref because the send listener runs before the widget ends the dictation.
   const dictating = useRef(false);
   useEffect(() => {
@@ -47,3 +75,10 @@ export function useCaretFocus({ mic, field }: ComposerNodes, { focusWhen, refocu
     });
   }, [refocus, onSend, mic, field]);
 }
+
+/** True when the user parked the caret in some other text field; the end of a reply must not pull it away from there. */
+function typingElsewhere(field: HTMLTextAreaElement | null): boolean {
+  const active = document.activeElement;
+  if (!(active instanceof HTMLElement) || active === field) return false;
+  return active.isContentEditable || active instanceof HTMLInputElement || active instanceof HTMLTextAreaElement;
+}

package/src/examples/demo/DemoAssistant.tsx

@@ -0,0 +1,47 @@
+'use client';
+
+import { useMemo } from 'react';
+
+import { AssistantChat } from '../../AssistantChat';
+import { scriptedTransport } from '../../stream/scriptedTransport';
+import type { ThreadApi } from '../../stream/sessions';
+import { useSession, type SessionCopy } from '../../stream/useSession';
+import { DEMO_THREAD, demoScript } from './thread';
+import { DEMO_RENDERERS } from './widgets';
+
+const COPY: SessionCopy = {
+  messages: { rejected: () => 'The demo cannot send this.', streamError: () => 'Something went wrong.', failed: 'Something went wrong.' },
+  status: { thinking: 'Thinking…', searching: 'Searching…', answering: 'Writing the answer…' },
+  failedText: 'Something went wrong.',
+};
+
+export const DEMO_SUGGESTIONS = ['Give me a quick overview', 'Show the tasks as a table', 'What is blocked?'];
+
+/**
+ * Demo mode: the assistant with no server. The long transcript is restored as stored history, every new message is answered by a script through the
+ * real adapter and session (status, reasoning, streamed text, widgets), and the widgets are the production slot mechanism. It is for stories,
+ * screenshots and for a product to see what an answer can hold before it writes its own renderers.
+ */
+export function DemoAssistant({ empty = false, className }: { empty?: boolean; className?: string }) {
+  const transport = useMemo(() => scriptedTransport(demoScript), []);
+  const api = useMemo<ThreadApi>(() => {
+    const thread = empty ? { id: 'demo', messages: [] } : DEMO_THREAD;
+    return {
+      list: async () => [{ id: 'demo', title: 'Weekly overview', last_message_at: '2026-11-06T09:00:00Z', message_count: thread.messages.length }],
+      create: async () => ({ id: 'demo', title: '', last_message_at: '2026-11-06T09:00:00Z', message_count: 0 }),
+      load: async () => thread,
+    };
+  }, [empty]);
+  const session = useSession({ transport, api, getContext: () => undefined, copy: COPY });
+  if (session.thread.kind !== 'ready') return null;
+  return (
+    <AssistantChat
+      adapter={session.adapter}
+      dataRenderers={DEMO_RENDERERS}
+      suggestions={DEMO_SUGGESTIONS}
+      conversation={{ id: session.thread.id, history: session.thread.history }}
+      draftRoom="demo"
+      className={className}
+    />
+  );
+}

package/src/examples/demo/thread.ts

@@ -0,0 +1,68 @@
+import type { StoredConversation, StoredMessage, StoredPart } from '../../wire/stored';
+import type { ScriptStep } from '../../stream/scriptedTransport';
+
+/**
+ * The demo transcript: one long read that shows every kind of message an answer can hold, in the order a real working session produces them.
+ * Abstract on purpose: no real people, no real data.
+ */
+
+let n = 0;
+const at = (minutes: number) => new Date(Date.UTC(2026, 10, 6, 9, 0) + minutes * 60_000).toISOString();
+const message = (role: 'user' | 'assistant', text: string, parts: StoredPart[] = []): StoredMessage => {
+  n += 1;
+  return { id: `demo-${n}`, seq: n, role, text, parts, status: 'done', error_code: null, created_at: at(n * 2) };
+};
+const user = (text: string) => message('user', text);
+const bot = message.bind(null, 'assistant');
+
+export const DEMO_THREAD: StoredConversation = {
+  id: 'demo',
+  messages: [
+    user('Give me a quick overview of the project and what changed this week.'),
+    bot(
+      '## Weekly overview\n\nThe project is **on track**. Three things moved this week:\n\n1. The onboarding flow was shortened from five steps to three.\n2. Search now answers in under 200 ms.\n3. Two blocked tasks were unblocked.\n\n> Nothing here needs a decision from you yet.',
+      [{ kind: 'metrics', data: { items: [{ label: 'Tasks done', value: '24', delta: '+6 this week' }, { label: 'Open issues', value: '9', delta: '−3' }, { label: 'Response time', value: '184 ms', delta: '−41 ms' }], progress: { label: 'Milestone 3', value: 72 } } }],
+    ),
+    user('Show me the tasks as a table.'),
+    bot('Here are the open items, sorted by priority.', [
+      { kind: 'table', data: { columns: ['Task', 'Owner', 'Status', 'Due'], rows: [
+        { cells: ['Shorten the onboarding', 'Team A', 'Done', 'Nov 3'], tag: { column: 2, tone: 'green' } },
+        { cells: ['Search latency budget', 'Team B', 'In review', 'Nov 8'], tag: { column: 2, tone: 'blue' } },
+        { cells: ['Migrate the old exports', 'Team C', 'Blocked', 'Nov 12'], tag: { column: 2, tone: 'red' } },
+        { cells: ['Write the release notes', 'Team A', 'Not started', 'Nov 14'], tag: { column: 2, tone: 'gray' } },
+      ] } },
+    ]),
+    user('Why is the export migration blocked?'),
+    bot(
+      'It waits on a schema decision. The old exports store dates as text, the new ones as timestamps. A short script handles both:\n\n```ts\nconst toTimestamp = (value: string | number) =>\n  typeof value === \'number\' ? value : Date.parse(value);\n```\n\nIf you agree with timestamps, I can prepare the change for review.',
+      [{ kind: 'choices', data: { prompt: 'What should I do?', options: ['Prepare the change', 'Show me the old schema', 'Not now'] } }],
+    ),
+    user('Prepare the change.'),
+    bot('Done. Review the proposal below; nothing is applied until you press Apply.', [
+      { kind: 'steps', data: { title: 'What I did', steps: [{ label: 'Read the old export schema', state: 'done' }, { label: 'Wrote the conversion', state: 'done' }, { label: 'Checked 1 200 sample rows', state: 'done' }, { label: 'Wait for your approval', state: 'running' }] } },
+      { kind: 'approval', data: { summary: 'Store export dates as timestamps', changes: [{ path: 'export.created_at', from: 'text', to: 'timestamp' }, { path: 'export.updated_at', from: 'text', to: 'timestamp' }, { path: 'export.version', to: '2' }] } },
+    ]),
+    user('Is there anything to watch while I wait?'),
+    bot('Two recordings explain the new flow, and the summary is attached as a file.', [
+      { kind: 'media', data: { items: [{ id: 'v1', title: 'The three-step onboarding', meta: 'Walkthrough · 2026', duration: '4:12', hue: 210 }, { id: 'v2', title: 'How search ranks results', meta: 'Explainer · 2026', duration: '7:40', hue: 150 }] } },
+      { kind: 'files', data: { files: [{ name: 'weekly-summary.pdf', size: '184 KB' }, { name: 'export-schema.json', size: '12 KB' }] } },
+    ]),
+  ],
+};
+
+const words = (text: string): ScriptStep[] => text.split(/(?<=\s)/).map((delta) => ({ frame: { type: 'text_delta', delta }, after: 35 }));
+const payload = (kind: string, data: unknown): ScriptStep => ({ frame: { type: 'ui_payload', kind, data }, after: 250 });
+
+/** Any new message streams a reply that uses the live path: status, reasoning, text, then two widgets. */
+export const demoScript = (): ScriptStep[] => [
+  { frame: { type: 'run', version: 1, thread_id: 'demo', message_id: `live-${Date.now()}`, client_id: null, seq: null } },
+  { frame: { type: 'status', phase: 'thinking' }, after: 300 },
+  { frame: { type: 'reasoning_delta', delta: 'Checking the open tasks and the latest changes. ' }, after: 200 },
+  { frame: { type: 'reasoning_delta', delta: 'The export migration is the only blocker.' }, after: 200 },
+  { frame: { type: 'reasoning_end', elapsed_ms: 1400, tokens: 38 }, after: 200 },
+  { frame: { type: 'status', phase: 'answering' }, after: 200 },
+  ...words('Here is where things stand right now. The export migration is still the only blocker, and everything else is moving.\n\n- Review is open for the search budget\n- Release notes are not started\n\n'),
+  payload('steps', { title: 'Progress', steps: [{ label: 'Onboarding', state: 'done' }, { label: 'Search budget', state: 'running' }, { label: 'Release notes', state: 'todo' }] }),
+  payload('choices', { options: ['Show the blocker', 'Summarize again'] }),
+  { frame: { type: 'done', finish_reason: 'stop', tokens_in: null, tokens_out: null, cost_usd: null, replayed: false } },
+];

package/src/examples/demo/widgets.tsx

@@ -0,0 +1,190 @@
+'use client';
+
+import { Check, CircleDashed, FileText, Loader2, Play, X } from 'lucide-react';
+import { useState, type ReactNode } from 'react';
+
+import { Badge, Button, Progress, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '@djangocfg/ui-core/components';
+
+import type { DataPartRenderer } from '../../AssistantChat';
+import { askAssistant } from '../../composer/handoff';
+
+/**
+ * The widgets of the demo transcript, one per kind of structured part an answer can carry. They are the pattern a product copies: a payload shape,
+ * a guard that returns `undefined` for a malformed one (the widget then draws its own fallback), and a card made of ready ui-core parts.
+ * Every card is a block of the same width and rhythm, so a long answer reads as one column.
+ */
+
+const CARD = 'my-2 rounded-lg border bg-card p-3 text-sm';
+const isObject = (value: unknown): value is Record<string, unknown> => typeof value === 'object' && value !== null;
+
+/* Approval: the `json_patch` / docman pattern. Nothing happens by rendering; Apply is a click. */
+export interface ApprovalData { summary: string; changes: { path: string; from?: string; to: string }[] }
+
+function Approval({ data }: { data: ApprovalData }) {
+  const [state, setState] = useState<'open' | 'applied' | 'dismissed'>('open');
+  return (
+    <div className={CARD}>
+      <p className="font-medium">{data.summary}</p>
+      <ul className="mt-2 space-y-1 text-xs">
+        {data.changes.map((change) => (
+          <li key={change.path} className="flex items-baseline gap-2">
+            <code className="text-muted-foreground">{change.path}</code>
+            {change.from ? <span className="text-muted-foreground line-through">{change.from}</span> : null}
+            {change.from ? <span className="text-muted-foreground">→</span> : null}
+            <span>{change.to}</span>
+          </li>
+        ))}
+      </ul>
+      <div className="mt-3 flex items-center gap-2">
+        {state === 'open' ? (
+          <>
+            <Button size="sm" onClick={() => setState('applied')}><Check /> Apply</Button>
+            <Button size="sm" variant="ghost" onClick={() => setState('dismissed')}>Dismiss</Button>
+          </>
+        ) : (
+          <span className="inline-flex items-center gap-1 text-xs text-muted-foreground">
+            {state === 'applied' ? <Check className="size-3.5" /> : <X className="size-3.5" />}
+            {state === 'applied' ? 'Applied' : 'Dismissed'}
+          </span>
+        )}
+      </div>
+    </div>
+  );
+}
+
+/* Media: the gptkino pattern, a poster row that opens the item. Fixed height, so hydrating it never moves the transcript. */
+export interface MediaData { items: { id: string; title: string; meta: string; duration: string; hue: number }[] }
+
+function Media({ data }: { data: MediaData }) {
+  return (
+    <div className="my-2 space-y-2">
+      {data.items.map((item) => (
+        <a key={item.id} href="#" onClick={(event) => event.preventDefault()} className="flex h-[62px] items-center gap-3 rounded-lg border bg-card p-1.5 no-underline outline-none hover:bg-accent focus-visible:ring-2 focus-visible:ring-ring">
+          <span className="relative flex h-full w-24 shrink-0 items-center justify-center overflow-hidden rounded-md text-white" style={{ background: `linear-gradient(135deg, hsl(${item.hue} 45% 38%), hsl(${(item.hue + 40) % 360} 40% 22%))` }}>
+            <Play className="size-4 fill-current" />
+            <span className="absolute bottom-0.5 right-1 text-[10px] tabular-nums">{item.duration}</span>
+          </span>
+          <span className="min-w-0">
+            <span className="block truncate text-sm font-medium text-foreground">{item.title}</span>
+            <span className="block truncate text-xs text-muted-foreground">{item.meta}</span>
+          </span>
+        </a>
+      ))}
+    </div>
+  );
+}
+
+/* Steps: what the assistant did or is doing. */
+export interface StepsData { title?: string; steps: { label: string; state: 'done' | 'running' | 'todo' }[] }
+
+function Steps({ data }: { data: StepsData }) {
+  return (
+    <div className={CARD}>
+      {data.title ? <p className="mb-2 font-medium">{data.title}</p> : null}
+      <ul className="space-y-1.5">
+        {data.steps.map((step) => (
+          <li key={step.label} className="flex items-center gap-2">
+            {step.state === 'done' ? <Check className="size-4 text-green-600" /> : step.state === 'running' ? <Loader2 className="size-4 animate-spin text-muted-foreground" /> : <CircleDashed className="size-4 text-muted-foreground" />}
+            <span className={step.state === 'todo' ? 'text-muted-foreground' : undefined}>{step.label}</span>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+
+/* Metrics: a few figures and one progress bar. */
+export interface MetricsData { items: { label: string; value: string; delta?: string }[]; progress?: { label: string; value: number } }
+
+function Metrics({ data }: { data: MetricsData }) {
+  return (
+    <div className={CARD}>
+      <div className="grid grid-cols-3 gap-3">
+        {data.items.map((item) => (
+          <div key={item.label}>
+            <p className="text-xs text-muted-foreground">{item.label}</p>
+            <p className="text-lg font-semibold tabular-nums">{item.value}</p>
+            {item.delta ? <p className="text-xs text-muted-foreground">{item.delta}</p> : null}
+          </div>
+        ))}
+      </div>
+      {data.progress ? (
+        <div className="mt-3 space-y-1">
+          <p className="flex justify-between text-xs text-muted-foreground"><span>{data.progress.label}</span><span className="tabular-nums">{data.progress.value}%</span></p>
+          <Progress value={data.progress.value} />
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+/* Table: rows with tag cells, the Notion database look. */
+export interface TableData { columns: string[]; rows: { cells: string[]; tag?: { column: number; tone: 'gray' | 'blue' | 'green' | 'yellow' | 'red' | 'purple' } }[] }
+
+function DataTable({ data }: { data: TableData }) {
+  return (
+    <div className="my-2 overflow-hidden rounded-lg border">
+      <Table frame={false} grid className="w-full">
+        <TableHeader>
+          <TableRow>{data.columns.map((column) => <TableHead key={column}>{column}</TableHead>)}</TableRow>
+        </TableHeader>
+        <TableBody>
+          {data.rows.map((row) => (
+            <TableRow key={row.cells.join('|')}>
+              {row.cells.map((cell, index) => (
+                <TableCell key={`${index}-${cell}`}>{row.tag?.column === index ? <Badge variant={row.tag.tone}>{cell}</Badge> : cell}</TableCell>
+              ))}
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+    </div>
+  );
+}
+
+/* Files: attachments the answer produced. */
+export interface FilesData { files: { name: string; size: string }[] }
+
+function Files({ data }: { data: FilesData }) {
+  return (
+    <div className="my-2 flex flex-wrap gap-2">
+      {data.files.map((file) => (
+        <span key={file.name} className="inline-flex items-center gap-2 rounded-lg border bg-card px-2.5 py-1.5 text-xs">
+          <FileText className="size-4 text-muted-foreground" />
+          <span className="font-medium">{file.name}</span>
+          <span className="text-muted-foreground">{file.size}</span>
+        </span>
+      ))}
+    </div>
+  );
+}
+
+/* Choices: quick replies. A click sends the label as the next message. */
+export interface ChoicesData { prompt?: string; options: string[] }
+
+function Choices({ data }: { data: ChoicesData }) {
+  return (
+    <div className="my-2 space-y-1.5">
+      {data.prompt ? <p className="text-xs text-muted-foreground">{data.prompt}</p> : null}
+      <div className="flex flex-wrap gap-2">
+        {data.options.map((option) => (
+          <Button key={option} size="sm" variant="outline" onClick={() => askAssistant(option)}>{option}</Button>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+const guard = <T,>(check: (data: Record<string, unknown>) => boolean, draw: (data: T) => ReactNode): DataPartRenderer => (data) => (isObject(data) && check(data) ? draw(data as T) : undefined);
+
+/** What the demo draws, by `kind`. Pass it as `dataRenderers`. */
+export const DEMO_RENDERERS: Readonly<Record<string, DataPartRenderer>> = {
+  approval: guard<ApprovalData>((d) => typeof d.summary === 'string' && Array.isArray(d.changes), (d) => <Approval data={d} />),
+  media: guard<MediaData>((d) => Array.isArray(d.items), (d) => <Media data={d} />),
+  steps: guard<StepsData>((d) => Array.isArray(d.steps), (d) => <Steps data={d} />),
+  metrics: guard<MetricsData>((d) => Array.isArray(d.items), (d) => <Metrics data={d} />),
+  table: guard<TableData>((d) => Array.isArray(d.columns) && Array.isArray(d.rows), (d) => <DataTable data={d} />),
+  files: guard<FilesData>((d) => Array.isArray(d.files), (d) => <Files data={d} />),
+  choices: guard<ChoicesData>((d) => Array.isArray(d.options), (d) => <Choices data={d} />),
+};
+export const DEMO_PAYLOAD_KINDS: readonly string[] = Object.keys(DEMO_RENDERERS);

package/src/index.ts

@@ -5,6 +5,7 @@ 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 { AssistantGreeting, type AssistantGreetingProps } from './shell/AssistantGreeting';
 export { AssistantLocked } from './shell/AssistantLocked';
 export { createAssistantUi, useMediaQuery, type UiOptions, type UiState, type UiStorage } from './shell/panelState';
 export { AssistantHostProvider, AssistantPortal, AssistantSlot, AssistantHeaderActions } from './Host';
@@ -34,3 +35,8 @@ export { decodeFrame, WIRE_VERSION } from './wire/frames';
 export type { ChatContext, Frame, Phase, StreamErrorCode } from './wire/frames';
 export type { StoredConversation, StoredMessage, StoredPart, StoredStatus, StoredThread } from './wire/stored';
 export { citationsRenderer, KB_RENDERERS, KB_PAYLOAD_KINDS, type Citation } from './examples/KbAssistant';
+export { DemoAssistant, DEMO_SUGGESTIONS } from './examples/demo/DemoAssistant';
+export { DEMO_RENDERERS, DEMO_PAYLOAD_KINDS } from './examples/demo/widgets';
+export { DEMO_THREAD, demoScript } from './examples/demo/thread';
+export { SUGGESTION_ICON_KEYS, suggestionIcon, type SuggestionIconKey } from './composer/suggestionIcons';
+export { AssistantMenu, type AssistantMenuItem, type AssistantMenuProps } from './menu/AssistantMenu';

package/src/menu/AssistantMenu.tsx

@@ -0,0 +1,90 @@
+'use client';
+
+import { Check, MoreHorizontal } from 'lucide-react';
+import type { ComponentType, ReactNode } from 'react';
+
+import {
+  Button,
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from '@djangocfg/ui-core/components';
+
+export interface AssistantMenuItem {
+  id: string;
+  label: string;
+  icon?: ComponentType<{ className?: string }>;
+  onSelect: () => void;
+  /** A destructive row (Delete): drawn in the destructive colour. */
+  danger?: boolean;
+  /** A choice among siblings (a view mode): the current one shows a check at the end. */
+  checked?: boolean;
+  disabled?: boolean;
+}
+
+export interface AssistantMenuProps {
+  /** Groups of rows; a hairline separates the groups. */
+  sections: AssistantMenuItem[][];
+  /** The quiet last line ("Last updated just now"). */
+  footer?: ReactNode;
+  /** Name of the trigger (tooltip and accessible name). */
+  label: string;
+}
+
+/**
+ * The conversation's "..." menu, for the frame's or the dock's `actions` slot: a round ghost trigger and a panel of icon rows in groups, the way Notion
+ * lays out a chat's actions (link, pin, rename, archive, delete, then where the chat lives). The host supplies the rows and what each does; the
+ * widget owns only the look, so one menu serves a column, a dock or a full page. Rows follow the menu tokens (`--menu-*`).
+ */
+export function AssistantMenu({ sections, footer, label }: AssistantMenuProps) {
+  return (
+    <TooltipProvider delayDuration={300}>
+      <DropdownMenu>
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <DropdownMenuTrigger asChild>
+              <Button variant="ghost" size="icon" aria-label={label} className="rounded-full" data-testid="assistant-menu">
+                <MoreHorizontal className="size-4" aria-hidden="true" />
+              </Button>
+            </DropdownMenuTrigger>
+          </TooltipTrigger>
+          <TooltipContent>{label}</TooltipContent>
+        </Tooltip>
+        <DropdownMenuContent align="end" sideOffset={4} className="w-56">
+          {sections.map((items, index) => (
+            <div key={items.map((item) => item.id).join('|')}>
+              {index > 0 ? <DropdownMenuSeparator /> : null}
+              {items.map((item) => {
+                const Icon = item.icon;
+                return (
+                  <DropdownMenuItem
+                    key={item.id}
+                    disabled={item.disabled}
+                    onSelect={item.onSelect}
+                    className={`gap-2.5 ${item.danger ? 'text-destructive focus:text-destructive' : ''}`}
+                  >
+                    {Icon ? <Icon className="size-4 shrink-0" /> : null}
+                    <span className="flex-1">{item.label}</span>
+                    {item.checked ? <Check className="size-4 shrink-0" aria-hidden="true" /> : null}
+                  </DropdownMenuItem>
+                );
+              })}
+            </div>
+          ))}
+          {footer ? (
+            <>
+              <DropdownMenuSeparator />
+              <p className="px-2 py-1.5 text-xs text-muted-foreground">{footer}</p>
+            </>
+          ) : null}
+        </DropdownMenuContent>
+      </DropdownMenu>
+    </TooltipProvider>
+  );
+}

package/src/messages/MessageFooter.tsx

@@ -2,11 +2,14 @@
 
 import { Check, Copy } from 'lucide-react';
 
-import { MessageActions, useChatCopy, useCopyAction, type ChatMessage } from '@djangocfg/widget-chat';
+import { MessageActions, MessageTime, useChatCopy, useMessageIds, useCopyAction, type ChatMessage } from '@djangocfg/widget-chat';
 
-/** The row under each message: copy. (Retry and the rest are the host's inventory, added here when the backend can honour them.) */
+/** The row under each message: copy, and the time it was sent (shown with the actions). (Retry and the rest are the host's inventory, added here when the backend can honour them.) */
 export function MessageFooter({ message }: { message: ChatMessage }) {
   const copy = useChatCopy().message;
+  // Only the newest message keeps its actions in view; every other row shows them on hover or focus, so the transcript stays quiet.
+  const ids = useMessageIds();
+  const last = ids[ids.length - 1] === message.id;
   const action = useCopyAction(message, {
     label: copy.copy,
     copiedLabel: copy.copied,
@@ -21,5 +24,10 @@ export function MessageFooter({ message }: { message: ChatMessage }) {
       }
     },
   });
-  return <MessageActions message={message} actions={action ? [action] : []} />;
+  return (
+    <div className={`flex items-center gap-2 ${message.role === 'user' ? 'justify-end' : 'justify-start'}`}>
+      <MessageActions message={message} actions={action ? [action] : []} className={last ? 'opacity-100' : 'opacity-0'} />
+      <MessageTime message={message} className={last ? 'opacity-100' : undefined} />
+    </div>
+  );
 }

package/src/shell/AssistantFrame.tsx

@@ -6,6 +6,7 @@ import { ChatPanelHeader, PANEL_TITLE_CLASS, PanelCloseButton } from '@djangocfg
 
 import { AssistantSlot, useHeaderActions } from '../Host';
 import { useAssistantCopy } from '../i18n';
+import { AssistantHelp } from './AssistantHelp';
 
 export interface FrameLabels {
   /** Name of the column and its heading (the host's brand). */
@@ -125,9 +126,9 @@ function Column({ width, shown, minWidth, maxWidth, defaultWidth, onWidthChange,
   };
 
   return (
-    // The clip: as wide as the page has given so far, the column inside keeps its full width and is anchored right, so it slides in instead of squeezing.
-    <div className="assistant-clip sticky top-0 flex h-dvh shrink-0 justify-end self-start overflow-hidden" data-shown={shown ? 'true' : 'false'}>
-    <aside aria-label={labels.title} style={{ width }} className="assistant-column relative flex h-full shrink-0 flex-col border-l bg-background">
+    // The clip: as wide as the page has given so far, and it owns the divider, so the hairline is there from the first frame and travels with the leading edge (a border on the column would be clipped away until the very end). the column inside keeps its full width and is anchored right, so it slides in instead of squeezing.
+    <div className="assistant-clip sticky top-0 box-border flex h-dvh shrink-0 justify-end self-start overflow-hidden border-l" data-shown={shown ? 'true' : 'false'}>
+    <aside aria-label={labels.title} style={{ width }} className="assistant-column relative flex h-full shrink-0 flex-col bg-background">
       <div
         role="separator"
         aria-orientation="vertical"
@@ -143,7 +144,7 @@ function Column({ width, shown, minWidth, maxWidth, defaultWidth, onWidthChange,
       />
       <ChatPanelHeader
         heading={<h2 className={PANEL_TITLE_CLASS}>{labels.title}</h2>}
-        actions={actions ?? published}
+        actions={<><AssistantHelp />{actions ?? published}</>}
         close={<PanelCloseButton label={labels.close ?? copy.close} onClick={onClose} />}
       />
       {content ? <div className="flex min-h-0 flex-1 flex-col">{content}</div> : <AssistantSlot className="min-h-0 flex-1" />}

package/src/shell/AssistantGreeting.tsx

@@ -0,0 +1,21 @@
+import type { ReactNode } from 'react';
+
+export interface AssistantGreetingProps {
+  /** The line over the starter rows ("How can I help you today?"). */
+  title: ReactNode;
+  /** A round mark above it: an avatar, a logo, an icon. Absent: none. */
+  mark?: ReactNode;
+}
+
+/**
+ * The empty room's greeting, shown in the transcript until the first message: a round mark and one line, left-aligned to
+ * sit over the starter rows, near the composer where the eye already is (the Notion AI arrangement).
+ */
+export function AssistantGreeting({ title, mark }: AssistantGreetingProps) {
+  return (
+    <div className="flex h-full min-h-0 flex-col justify-end px-3 pb-2">
+      {mark ? <div className="mb-3 flex size-12 items-center justify-center overflow-hidden rounded-full bg-muted text-foreground">{mark}</div> : null}
+      <h3 className="text-[length:var(--greeting-font-size,1.0625rem)] font-semibold leading-tight text-foreground">{title}</h3>
+    </div>
+  );
+}

package/src/shell/AssistantHelp.tsx

@@ -0,0 +1,49 @@
+'use client';
+
+import { CircleHelp } from 'lucide-react';
+
+import { Button, Kbd, Popover, PopoverContent, PopoverTrigger } from '@djangocfg/ui-core/components';
+import { formatHotkey, useIsTouch } from '@djangocfg/ui-core/hooks';
+
+import { useAssistantCopy } from '../i18n';
+import { DICTATION_TOGGLE } from '../composer/keys';
+
+/** The keys the composer answers to, in the order a person needs them. `combo` is a hotkey string, drawn for the viewer's system (⌘ on Apple, Ctrl elsewhere). */
+function useRows() {
+  const copy = useAssistantCopy();
+  return [
+    { combo: DICTATION_TOGGLE, text: copy.helpDictate },
+    { combo: 'enter', text: copy.helpSend },
+    { combo: 'escape', text: copy.helpStop },
+    { combo: 'arrowup', text: copy.helpRecall },
+    { combo: 'shift+enter', text: copy.helpNewline },
+  ];
+}
+
+/** A round "?" in the assistant's header, before its other actions; pressing it opens the short list of keys the composer answers to. */
+export function AssistantHelp() {
+  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 (
+    <Popover>
+      <PopoverTrigger asChild>
+        <Button variant="ghost" size="icon" className="rounded-full" aria-label={copy.helpLabel} title={copy.helpLabel}>
+          <CircleHelp className="size-4" aria-hidden />
+        </Button>
+      </PopoverTrigger>
+      <PopoverContent side="bottom" align="end" className="w-72 p-3">
+        <ul className="space-y-2">
+          {rows.map(({ combo, text }) => (
+            <li key={combo} className="flex items-start justify-between gap-3 text-sm">
+              <span className="text-muted-foreground">{text}</span>
+              <Kbd className="shrink-0">{formatHotkey(combo)}</Kbd>
+            </li>
+          ))}
+        </ul>
+      </PopoverContent>
+    </Popover>
+  );
+}

package/src/shell/ChatDock.tsx

@@ -7,6 +7,7 @@ import { useIsMobile } from '@djangocfg/ui-core/hooks';
 import { ChatPanelHeader, ChatSheet, PANEL_TITLE_CLASS, PanelCloseButton } from '@djangocfg/widget-chat';
 
 import { useHeaderActions } from '../Host';
+import { AssistantHelp } from './AssistantHelp';
 import { useAssistantCopy } from '../i18n';
 
 interface Props {
@@ -44,7 +45,7 @@ export function ChatDock({ open, onOpenChange, children: chat, title, contextLin
         <ChatPanelHeader
           heading={<SidePanel.Title className={PANEL_TITLE_CLASS}>{title}</SidePanel.Title>}
           description={contextLine ? <SidePanel.Description>{contextLine}</SidePanel.Description> : undefined}
-          actions={shown}
+          actions={<><AssistantHelp />{shown}</>}
           close={<PanelCloseButton label={closeLabel ?? copy.close} onClick={() => onOpenChange(false)} />}
         />
         <SidePanel.Body>{chat}</SidePanel.Body>

package/src/styles/layout.css

@@ -36,25 +36,29 @@
 
 .assistant-clip {
   width: var(--assistant-w);
+}
+
+/* Only the content fades. The clip's own divider must be visible from the first frame of opening and until the last of closing. */
+.assistant-clip .assistant-column {
   opacity: 0;
 }
 
-.assistant-clip[data-shown="true"] {
+.assistant-clip[data-shown="true"] .assistant-column {
   opacity: 1;
 }
 
-.assistant-frame[data-moving="true"] .assistant-clip {
+.assistant-frame[data-moving="true"] .assistant-column {
   transition: opacity calc(var(--assistant-ms) * 0.7) ease-out;
 }
 
 /* Closing: the fade finishes early so the column does not look like it is dragged off. */
-.assistant-frame[data-moving="true"] .assistant-clip[data-shown="false"] {
+.assistant-frame[data-moving="true"] .assistant-clip[data-shown="false"] .assistant-column {
   transition-duration: calc(var(--assistant-ms) * 0.45);
 }
 
 @media (prefers-reduced-motion: reduce) {
   .assistant-frame[data-moving="true"],
-  .assistant-frame[data-moving="true"] .assistant-clip {
+  .assistant-frame[data-moving="true"] .assistant-column {
     transition: none;
   }
 }

package/src/composer/ComposerHelp.tsx

@@ -1,49 +0,0 @@
-'use client';
-
-import { Kbd, Popover, PopoverContent, PopoverTrigger } from '@djangocfg/ui-core/components';
-import { formatHotkey, useIsTouch } from '@djangocfg/ui-core/hooks';
-
-import { useAssistantCopy } from '../i18n';
-import { DICTATION_TOGGLE } from './keys';
-
-/** The keys the composer answers to, in the order a person needs them. `combo` is a hotkey string, drawn for the viewer's system (⌘ on Apple, Ctrl elsewhere). */
-function useRows() {
-  const copy = useAssistantCopy();
-  return [
-    { combo: DICTATION_TOGGLE, text: copy.helpDictate },
-    { combo: 'enter', text: copy.helpSend },
-    { combo: 'escape', text: copy.helpStop },
-    { combo: 'arrowup', text: copy.helpRecall },
-    { combo: 'shift+enter', text: copy.helpNewline },
-  ];
-}
-
-/** A quiet "Help" under the composer; pressing it opens the short list of keys. */
-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>
-        <PopoverTrigger asChild>
-          <button type="button" className="rounded px-1 text-xs text-muted-foreground underline-offset-2 outline-none hover:text-foreground hover:underline focus-visible:ring-2 focus-visible:ring-ring">
-            {copy.helpLabel}
-          </button>
-        </PopoverTrigger>
-        <PopoverContent side="top" align="end" className="w-72 p-3">
-          <ul className="space-y-2">
-            {rows.map(({ combo, text }) => (
-              <li key={combo} className="flex items-start justify-between gap-3 text-sm">
-                <span className="text-muted-foreground">{text}</span>
-                <Kbd className="shrink-0">{formatHotkey(combo)}</Kbd>
-              </li>
-            ))}
-          </ul>
-        </PopoverContent>
-      </Popover>
-    </div>
-  );
-}