@djangocfg/widget-assistant 0.3.2 → 0.3.8

package/README.md

@@ -7,6 +7,10 @@ It knows nothing about one site (`src/boundary.test.ts` enforces it), so what a
 <AssistantChat adapter={adapter} suggestions={suggestions} dataRenderers={renderers} />
 ```
 
+## Docs
+
+Longer pages live in [`@docs/`](./@docs/README.md) (repository only, not in the npm package): architecture, the wire contract, the Python server half, connecting a new project, customization, troubleshooting. The server half is not in django-cfg's config: each product writes its own on the agent plane (`@docs/server.md`).
+
 ## Folders (one job each)
 
 | Folder | Job |
@@ -58,6 +62,20 @@ A session is one thread on the server. `useSession({ transport, api, storage, ge
 *   There is no delete and no `clear()`: "clear" is "new chat". Retention is the server's job.
 *   Without `api` (anonymous host) nothing is listed; `startNew()` just empties the room.
 
+## Voice (0.3.3)
+
+The microphone menu always offers a dictation language: a visitor may speak any language, whatever the host UI says. With no `speech` prop the assistant uses `useSpeechLanguage` from `@djangocfg/widget-chat/store` (the last pick, kept on this device; else the page language if the browser also lists it; else the browser's; else English). A host `speech={{ value, onChange }}` still overrides it.
+
+Message sounds (sent, answer starts, answer done, error) come from `widget-chat` and are on by default; `messageSounds={false}` silences them, `messageSounds={{ volume, urls }}` tunes them.
+
+Dictation start/stop tones are bundled (Web Audio, no files). `sounds={false}` silences them; `sounds={{ play(kind) }}` replaces them.
+
+## Asking from outside, the dock and the locked room
+
+*   `askAssistant(text)` puts a prompt typed elsewhere on the page (a hero search, a "discuss this" button) into the composer and sends it once the composer is mounted and sending is allowed. One slot: asking twice before the composer exists keeps the last.
+*   `AssistantFrame` and `ChatDock` take `actions` (header controls such as `SessionsMenu`): they sit next to Close in the one panel header (`ChatPanelHeader` from `widget-chat`, drawn identically by the wide column, the tablet side panel and the phone sheet), set apart by a thin divider; each button has a ui-core tooltip. `ChatDock` is a side panel on tablets, the base package's `ChatSheet` on phones. The keys list (`ComposerHelp`) is hidden on touch devices.
+*   `AssistantLocked` takes `onComposerClick`: the inert composer becomes a button for the way out (sign in).
+
 ## Tests
 
 `pnpm --filter @djangocfg/widget-assistant check test`: the wire, stream and boundary tests, and `tsc --noEmit`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/widget-assistant",
-  "version": "0.3.2",
+  "version": "0.3.8",
   "description": "A site assistant on top of @djangocfg/widget-chat: the SSE wire and session layer, a persistent host, docked column, floating button and sheet, dictation, Help and 17 built-in locales",
   "keywords": [
     "chat",
@@ -44,19 +44,19 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@djangocfg/widget-chat": "^0.1.19",
+    "@djangocfg/widget-chat": "^0.1.24",
     "zustand": "^5.0.16"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.621",
-    "@djangocfg/ui-core": "^2.1.621",
+    "@djangocfg/i18n": "^2.1.623",
+    "@djangocfg/ui-core": "^2.1.623",
     "lucide-react": "^1.68.0",
     "react": "^19.0.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.621",
-    "@djangocfg/typescript-config": "^2.1.621",
-    "@djangocfg/ui-core": "^2.1.621",
+    "@djangocfg/i18n": "^2.1.623",
+    "@djangocfg/typescript-config": "^2.1.623",
+    "@djangocfg/ui-core": "^2.1.623",
     "@storybook/react-vite": "^10.6.5",
     "@types/node": "^25.9.5",
     "@types/react": "19.3.0",

package/src/AssistantChat.tsx

@@ -2,6 +2,8 @@
 
 import { useMemo, useRef, type ReactNode } from 'react';
 
+import type { ChatSoundsCapability, VoiceSoundsCapability } from '@djangocfg/widget-chat/core';
+import { useSpeechLanguage } from '@djangocfg/widget-chat/store';
 import {
   Chat,
   ChatTranscript,
@@ -14,6 +16,8 @@ import {
 import { Response } from '@djangocfg/widget-chat/content';
 
 import type { SessionNotice } from './stream/useSession';
+import { useAssistantLocale } from './i18n';
+import { bundledEarcons } from './composer/earcons';
 import { createWholeTranscriptSpeech } from './composer/wholeTranscript';
 import { AssistantComposer } from './composer/AssistantComposer';
 import { ComposerHelp } from './composer/ComposerHelp';
@@ -39,8 +43,12 @@ interface Props {
   draftRoom?: string;
   /** The host's drawing of structured parts, by `kind` (for example `citations`). Unknown kinds fall through to the widget. */
   dataRenderers?: Readonly<Record<string, DataPartRenderer>>;
-  /** Dictation language and its picker (the microphone menu). Absent: the browser's default engine with the widget's default language. */
+  /** Dictation language and its picker (the microphone menu). Absent: the assistant's own picker (the viewer's last pick, else the page and browser language), always shown. */
   speech?: SpeechLanguage;
+  /** The dictation start/stop tones. Absent: the bundled ones (Web Audio, no files). `false`: silent. */
+  sounds?: VoiceSoundsCapability | false;
+  /** The message sounds (sent, answer starts, answer done, error). Absent: the widget's bundled ones, on. `false`: silent. */
+  messageSounds?: ChatSoundsCapability | false;
   /** A plain line above the composer: reconnecting, or a stalled run with its Retry (`onRetry`). */
   notice?: SessionNotice | null;
   onRetry?: () => void;
@@ -59,7 +67,7 @@ const NO_RENDERERS: Readonly<Record<string, DataPartRenderer>> = {};
  * recall of sent prompts with the arrow keys, an unsent draft that survives a reload). The widget's packaged layout shows only a bare composer, so the layout
  * is composed here from its own primitives: every behaviour is the widget's, nothing is re-implemented.
  */
-export function AssistantChat({ adapter, suggestions, conversation = EMPTY_ROOM, draftRoom, dataRenderers = NO_RENDERERS, speech, notice, onRetry, focusWhen, refocus, className }: Props) {
+export function AssistantChat({ adapter, suggestions, conversation = EMPTY_ROOM, draftRoom, dataRenderers = NO_RENDERERS, speech: given, sounds, messageSounds, notice, onRetry, focusWhen, refocus, className }: Props) {
   const renderers = useMemo(
     () => ({
       text: ({ part }: PartRenderProps) => (part.type === 'text' ? <Response>{part.text}</Response> : null),
@@ -74,13 +82,15 @@ export function AssistantChat({ adapter, suggestions, conversation = EMPTY_ROOM,
     }),
     [dataRenderers],
   );
+  const own = useSpeechLanguage({ uiLocale: useAssistantLocale() });
+  const speech = given ?? { value: own.language, onChange: own.setLanguage };
   // The language is read at each start, through a ref: the capability must not be rebuilt when the picker changes.
   const language = useRef(speech?.value);
   language.current = speech?.value;
   const voice = useMemo(() => createWholeTranscriptSpeech(() => language.current ?? (typeof navigator === 'undefined' ? 'en-US' : navigator.language)), []);
   const capabilities = useMemo<ChatCapabilities>(
-    () => ({ suggestions: { items: suggestions.map((prompt, index) => ({ id: `s${index}`, title: prompt, prompt })) }, ...(voice ? { voice } : {}) }),
-    [suggestions, voice],
+    () => ({ suggestions: { items: suggestions.map((prompt, index) => ({ id: `s${index}`, title: prompt, prompt })) }, ...(voice ? { voice } : {}), ...(sounds === false ? {} : { voiceSounds: sounds ?? bundledEarcons }), ...(messageSounds === undefined ? {} : { sounds: messageSounds }) }),
+    [suggestions, voice, sounds, messageSounds],
   );
   const slots = useMemo(
     () => ({

package/src/composer/ComposerBehaviour.tsx

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

package/src/composer/ComposerHelp.tsx

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

package/src/composer/earcons.ts

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

package/src/composer/handoff.ts

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

package/src/index.ts

@@ -1,6 +1,7 @@
 export { AssistantChat, type DataPartRenderer } from './AssistantChat';
 export { scriptedTransport, type ScriptStep } from './stream/scriptedTransport';
 export { useAssistantCopy, useAssistantLocale, ASSISTANT_DICTIONARIES, type AssistantCopy } from './i18n';
+export { askAssistant } from './composer/handoff';
 export { ChatDock } from './shell/ChatDock';
 export { AssistantFrame, type FrameLabels } from './shell/AssistantFrame';
 export { AssistantFab, type FabHint } from './shell/AssistantFab';

package/src/sessions/SessionsMenu.tsx

@@ -2,7 +2,18 @@
 
 import { Check, History, Plus } from 'lucide-react';
 
-import { Button, DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuLabel, DropdownMenuTrigger } from '@djangocfg/ui-core/components';
+import {
+  Button,
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuTrigger,
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from '@djangocfg/ui-core/components';
 
 import { useAssistantCopy, useAssistantLocale } from '../i18n';
 import type { Session } from '../stream/useSession';
@@ -17,7 +28,7 @@ interface Props {
 }
 
 /**
- * The chat's header controls: "New chat" (a new session; the old ones stay) and the list of earlier sessions, newest first, to switch back.
+ * The chat's header controls (put them in the frame's or the dock's `actions`, next to Close; each has a tooltip): "New chat" (a new session; the old ones stay) and the list of earlier sessions, newest first, to switch back.
  * Both wait while an answer streams: Stop ends it first. Words come from the assistant's own dictionaries.
  */
 export function SessionsMenu({ session, locale, newOnly = false }: Props) {
@@ -25,17 +36,28 @@ export function SessionsMenu({ session, locale, newOnly = false }: Props) {
   const active = useAssistantLocale(locale);
   const current = session.thread.kind === 'ready' ? session.thread.session : null;
   return (
-    <div className="flex items-center" data-testid="sessions-menu">
-      <Button variant="ghost" size="icon" aria-label={copy.newChat} title={copy.newChat} disabled={session.busy} onClick={() => void session.startNew()}>
-        <Plus className="size-5" aria-hidden="true" />
-      </Button>
+    <TooltipProvider delayDuration={300}>
+    <div className="flex items-center gap-1" data-testid="sessions-menu">
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <Button variant="ghost" size="icon" aria-label={copy.newChat} disabled={session.busy} onClick={() => void session.startNew()}>
+            <Plus className="size-4" aria-hidden="true" />
+          </Button>
+        </TooltipTrigger>
+        <TooltipContent>{copy.newChat}</TooltipContent>
+      </Tooltip>
       {newOnly ? null : (
         <DropdownMenu onOpenChange={(open) => open && session.refreshSessions()}>
-          <DropdownMenuTrigger asChild>
-            <Button variant="ghost" size="icon" aria-label={copy.sessions} title={copy.sessions}>
-              <History className="size-5" aria-hidden="true" />
-            </Button>
-          </DropdownMenuTrigger>
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <DropdownMenuTrigger asChild>
+                <Button variant="ghost" size="icon" aria-label={copy.sessions}>
+                  <History className="size-4" aria-hidden="true" />
+                </Button>
+              </DropdownMenuTrigger>
+            </TooltipTrigger>
+            <TooltipContent>{copy.sessions}</TooltipContent>
+          </Tooltip>
           <DropdownMenuContent align="end" sideOffset={4} className="max-h-96 w-72 overflow-y-auto">
             <DropdownMenuLabel>{copy.sessions}</DropdownMenuLabel>
             {session.sessions === null ? null : session.sessions.length === 0 ? (
@@ -55,5 +77,6 @@ export function SessionsMenu({ session, locale, newOnly = false }: Props) {
         </DropdownMenu>
       )}
     </div>
+    </TooltipProvider>
   );
 }

package/src/shell/AssistantFrame.tsx

@@ -2,9 +2,7 @@
 
 import { useCallback, useEffect, useRef, useState, type CSSProperties, type KeyboardEvent, type PointerEvent, type ReactNode } from 'react';
 
-import { X } from 'lucide-react';
-
-import { Button } from '@djangocfg/ui-core/components';
+import { ChatPanelHeader, PANEL_TITLE_CLASS, PanelCloseButton } from '@djangocfg/widget-chat';
 
 import { AssistantSlot } from '../Host';
 import { useAssistantCopy } from '../i18n';
@@ -28,6 +26,8 @@ interface Props {
   onWidthChange: (width: number) => void;
   onClose: () => void;
   labels: FrameLabels;
+  /** Header controls beside the close button (for example `SessionsMenu`): one header, a thin divider keeps them apart from Close. */
+  actions?: ReactNode;
   /** What the column shows instead of the chat (the locked view, a notice). Absent: the chat itself. */
   content?: ReactNode;
   /** The page. */
@@ -47,7 +47,7 @@ const RESTORE_GRACE_MS = 800;
  * reflows), with a short fade. `--assistant-w` is a registered length (`layout.css`), so fixed host elements follow the same curve. The column stays mounted until the
  * close finishes. Resizing by hand and the first paint after a page load are not animated.
  */
-export function AssistantFrame({ docked, width, minWidth, maxWidth, defaultWidth, onWidthChange, onClose, labels, content, children }: Props) {
+export function AssistantFrame({ docked, width, minWidth, maxWidth, defaultWidth, onWidthChange, onClose, labels, content, actions, children }: Props) {
   const born = useRef(0);
   const [mounted, setMounted] = useState(false);
   const [shown, setShown] = useState(false);
@@ -90,12 +90,12 @@ export function AssistantFrame({ docked, width, minWidth, maxWidth, defaultWidth
   return (
     <div className="assistant-frame flex" data-moving={moving ? 'true' : 'false'} style={style}>
       <div className="min-w-0 flex-1">{children}</div>
-      {mounted ? <Column {...{ width, shown, minWidth, maxWidth, defaultWidth, onWidthChange, onClose, labels, content }} /> : null}
+      {mounted ? <Column {...{ width, shown, minWidth, maxWidth, defaultWidth, onWidthChange, onClose, labels, content, actions }} /> : null}
     </div>
   );
 }
 
-function Column({ width, shown, minWidth, maxWidth, defaultWidth, onWidthChange, onClose, labels, content }: Omit<Props, 'docked' | 'children'> & { shown: boolean }) {
+function Column({ width, shown, minWidth, maxWidth, defaultWidth, onWidthChange, onClose, labels, content, actions }: Omit<Props, 'docked' | 'children'> & { shown: boolean }) {
   const copy = useAssistantCopy();
   // The handle sits on the column's left edge: the pointer's distance from the window's right edge is the new width.
   const drag = useCallback(
@@ -140,12 +140,11 @@ function Column({ width, shown, minWidth, maxWidth, defaultWidth, onWidthChange,
         onDoubleClick={() => onWidthChange(defaultWidth)}
         className="absolute inset-y-0 -left-1 z-10 w-2 cursor-col-resize touch-none outline-none transition-colors hover:bg-primary/30 focus-visible:bg-primary/40"
       />
-      <header className="flex shrink-0 items-center justify-between border-b px-4 py-2.5">
-        <h2 className="font-display text-sm font-semibold uppercase tracking-wide text-muted-foreground">{labels.title}</h2>
-        <Button variant="ghost" size="icon" aria-label={labels.close ?? copy.close} onClick={onClose}>
-          <X className="size-4" aria-hidden="true" />
-        </Button>
-      </header>
+      <ChatPanelHeader
+        heading={<h2 className={PANEL_TITLE_CLASS}>{labels.title}</h2>}
+        actions={actions}
+        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" />}
     </aside>
     </div>

package/src/shell/AssistantLocked.tsx

@@ -16,13 +16,15 @@ interface Props {
   composerLabel?: string;
   /** Replaces the lock. */
   icon?: ReactNode;
+  /** Makes the composer a button for the way out (sign in): touching the field is the same ask as the action. */
+  onComposerClick?: () => void;
 }
 
 /**
  * The chat as it looks when the viewer cannot write: a centred icon, one short reason, the action, and a composer that is visibly switched off.
  * The root is a flex item (`flex-1`), not `h-full`: percentage heights do not resolve inside a flex column, and the message collapsed against the header.
  */
-export function AssistantLocked({ title, body, action, composerLabel, icon }: Props) {
+export function AssistantLocked({ title, body, action, composerLabel, icon, onComposerClick }: Props) {
   const copy = useAssistantCopy();
   return (
     <div className="flex min-h-0 flex-1 flex-col">
@@ -35,9 +37,15 @@ export function AssistantLocked({ title, body, action, composerLabel, icon }: Pr
         {action ? <div className="mt-2">{action}</div> : null}
       </div>
       <div className="px-4 pt-2 pb-[max(1rem,env(safe-area-inset-bottom))]">
-        <div aria-disabled="true" className="flex select-none items-center rounded-2xl border bg-muted/40 px-4 py-3.5 text-sm text-muted-foreground opacity-70">
-          {composerLabel ?? copy.lockedComposer}
-        </div>
+        {onComposerClick ? (
+          <button type="button" onClick={onComposerClick} className="flex w-full items-center rounded-2xl border bg-muted/40 px-4 py-3.5 text-start text-sm text-muted-foreground">
+            {composerLabel ?? copy.lockedComposer}
+          </button>
+        ) : (
+          <div aria-disabled="true" className="flex select-none items-center rounded-2xl border bg-muted/40 px-4 py-3.5 text-sm text-muted-foreground opacity-70">
+            {composerLabel ?? copy.lockedComposer}
+          </div>
+        )}
       </div>
     </div>
   );

package/src/shell/ChatDock.tsx

@@ -2,10 +2,9 @@
 
 import type { ReactNode } from 'react';
 
-import { X } from 'lucide-react';
-
-import { Button, Drawer, DrawerClose, DrawerContent, DrawerDescription, DrawerHeader, DrawerTitle, SidePanel } from '@djangocfg/ui-core/components';
+import { SidePanel } from '@djangocfg/ui-core/components';
 import { useIsMobile } from '@djangocfg/ui-core/hooks';
+import { ChatPanelHeader, ChatSheet, PANEL_TITLE_CLASS, PanelCloseButton } from '@djangocfg/widget-chat';
 
 import { useAssistantCopy } from '../i18n';
 
@@ -19,42 +18,32 @@ interface Props {
   contextLine?: string;
   /** Accessible name of the close button on phones. Absent: the bundled word. */
   closeLabel?: string;
+  /** Header controls before the close button (for example `SessionsMenu`). */
+  actions?: ReactNode;
 }
 
-/** The chat when the page has no room for a column: a non-modal side panel on tablets (the page stays usable), a full-screen sheet on phones. */
-export function ChatDock({ open, onOpenChange, children: chat, title, contextLine, closeLabel }: Props) {
-  const copy = useAssistantCopy();
+/** The chat when the page has no room for a column: a non-modal side panel on tablets (the page stays usable), the package's full-screen `ChatSheet` on phones (it owns the keyboard, layer and pinning problems). */
+export function ChatDock({ open, onOpenChange, children: chat, title, contextLine, closeLabel, actions }: Props) {
   const isMobile = useIsMobile();
+  const copy = useAssistantCopy();
 
   if (isMobile) {
     return (
-      <Drawer open={open} onOpenChange={onOpenChange} direction="bottom">
-        <DrawerContent height="100dvh" className="max-h-[100dvh] rounded-t-none">
-          <DrawerHeader className="flex flex-row items-center justify-between border-b py-2 text-left">
-            <div>
-              <DrawerTitle>{title}</DrawerTitle>
-              {contextLine ? <DrawerDescription>{contextLine}</DrawerDescription> : null}
-            </div>
-            <DrawerClose asChild>
-              <Button variant="ghost" size="icon" aria-label={closeLabel ?? copy.close}><X className="size-5" aria-hidden="true" /></Button>
-            </DrawerClose>
-          </DrawerHeader>
-          {/* The drawer wraps its children in a scroller that is as tall as its content (it only stretches with snap points), so `flex-1` cannot fill the sheet:
-              the body gets the screen height minus the handle, the header and the bottom padding. */}
-          <div className="flex flex-col" style={{ height: 'calc(100dvh - 7.5rem)' }}>{chat}</div>
-        </DrawerContent>
-      </Drawer>
+      <ChatSheet open={open} onOpenChange={onOpenChange} title={title} description={contextLine} closeLabel={closeLabel ?? copy.close} actions={actions}>
+        {chat}
+      </ChatSheet>
     );
   }
 
   return (
     <SidePanel open={open} onOpenChange={onOpenChange}>
       <SidePanel.Content width="min(440px, 90vw)">
-        <SidePanel.Header>
-          <SidePanel.Title>{title}</SidePanel.Title>
-          {contextLine ? <SidePanel.Description>{contextLine}</SidePanel.Description> : null}
-          <SidePanel.Close />
-        </SidePanel.Header>
+        <ChatPanelHeader
+          heading={<SidePanel.Title className={PANEL_TITLE_CLASS}>{title}</SidePanel.Title>}
+          description={contextLine ? <SidePanel.Description>{contextLine}</SidePanel.Description> : undefined}
+          actions={actions}
+          close={<PanelCloseButton label={closeLabel ?? copy.close} onClick={() => onOpenChange(false)} />}
+        />
         <SidePanel.Body>{chat}</SidePanel.Body>
       </SidePanel.Content>
     </SidePanel>