@djangocfg/widget-assistant 0.0.0-stage → 0.1.2

package/src/i18n/locales/ru.ts

@@ -0,0 +1,34 @@
+import type { AssistantCopy } from '../types';
+
+export const ru: AssistantCopy = {
+  close: 'Закрыть',
+  resize: 'Изменить ширину ассистента',
+  lockedTitle: 'Войдите, чтобы пообщаться',
+  lockedBody: 'Ассистент подбирает фильмы и помнит разговор. Войдите, чтобы начать.',
+  lockedComposer: 'Войдите, чтобы задать вопрос',
+  signIn: 'Войти',
+  hint: 'Обсудим фильм с ИИ?',
+  statusThinking: 'Думаю…',
+  statusSearching: 'Ищу в каталоге…',
+  statusReading: 'Читаю про фильмы…',
+  statusChoosing: 'Выбираю лучшее…',
+  errAuth: 'Войдите, чтобы спросить ассистента.',
+  errBusy: 'Сначала завершите ответ в другой вкладке.',
+  errInvalid: 'Сообщение слишком длинное. Сократите и повторите.',
+  errRate: 'Слишком много сообщений. Попробуйте через {{seconds}} с.',
+  errUnavailable: 'Ассистент отдыхает. Попробуйте позже.',
+  failed: 'Поиск не удался. Попробуйте ещё раз.',
+  reconnecting: 'Подключаемся снова…',
+  stalled: 'Ответ ещё готовится.',
+  retry: 'Повторить',
+  clear: 'Очистить чат',
+  clearConfirm: 'Удалить этот разговор? Это нельзя отменить.',
+  clearYes: 'Удалить',
+  loadError: 'Не удалось загрузить разговор.',
+  helpLabel: 'Справка',
+  helpDictate: 'Начать или остановить диктовку',
+  helpSend: 'Отправить (при диктовке: остановить и отправить)',
+  helpStop: 'Остановить диктовку, текст остаётся',
+  helpRecall: 'Прошлые вопросы',
+  helpNewline: 'Новая строка',
+};

package/src/i18n/locales/sv.ts

@@ -0,0 +1,34 @@
+import type { AssistantCopy } from '../types';
+
+export const sv: AssistantCopy = {
+  close: 'Stäng',
+  resize: 'Ändra assistentens bredd',
+  lockedTitle: 'Logga in för att chatta',
+  lockedBody: 'Assistenten väljer filmer åt dig och minns samtalet. Logga in för att börja.',
+  lockedComposer: 'Logga in för att fråga',
+  signIn: 'Logga in',
+  hint: 'Ska vi prata film med AI?',
+  statusThinking: 'Funderar…',
+  statusSearching: 'Söker i katalogen…',
+  statusReading: 'Läser om filmerna…',
+  statusChoosing: 'Väljer de bästa…',
+  errAuth: 'Logga in för att fråga assistenten.',
+  errBusy: 'Avsluta först i den andra fliken.',
+  errInvalid: 'Meddelandet är för långt. Korta ner det och försök igen.',
+  errRate: 'För många meddelanden. Försök igen om {{seconds}} s.',
+  errUnavailable: 'Assistenten vilar. Försök igen senare.',
+  failed: 'Sökningen misslyckades. Försök igen.',
+  reconnecting: 'Återansluter…',
+  stalled: 'Svaret är fortfarande på väg.',
+  retry: 'Försök igen',
+  clear: 'Rensa chatten',
+  clearConfirm: 'Ta bort den här konversationen? Det går inte att ångra.',
+  clearYes: 'Ta bort',
+  loadError: 'Konversationen kunde inte laddas.',
+  helpLabel: 'Hjälp',
+  helpDictate: 'Starta eller stoppa diktering',
+  helpSend: 'Skicka (vid diktering: stoppa och skicka)',
+  helpStop: 'Stoppa diktering, behåll texten',
+  helpRecall: 'Tidigare frågor',
+  helpNewline: 'Ny rad',
+};

package/src/i18n/locales/tr.ts

@@ -0,0 +1,34 @@
+import type { AssistantCopy } from '../types';
+
+export const tr: AssistantCopy = {
+  close: 'Kapat',
+  resize: 'Asistanın genişliğini değiştir',
+  lockedTitle: 'Sohbet için giriş yapın',
+  lockedBody: 'Asistan sizin için film seçer ve konuşmayı hatırlar. Başlamak için giriş yapın.',
+  lockedComposer: 'Sormak için giriş yapın',
+  signIn: 'Giriş yap',
+  hint: 'Yapay zekayla filmleri konuşalım mı?',
+  statusThinking: 'Düşünüyorum…',
+  statusSearching: 'Katalogda arıyorum…',
+  statusReading: 'Filmleri okuyorum…',
+  statusChoosing: 'En iyilerini seçiyorum…',
+  errAuth: 'Asistana sormak için giriş yapın.',
+  errBusy: 'Önce diğer sekmede bitirin.',
+  errInvalid: 'Mesaj çok uzun. Kısaltıp tekrar deneyin.',
+  errRate: 'Çok fazla mesaj. {{seconds}} sn sonra tekrar deneyin.',
+  errUnavailable: 'Asistan dinleniyor. Daha sonra tekrar deneyin.',
+  failed: 'Arama başarısız oldu. Tekrar deneyin.',
+  reconnecting: 'Yeniden bağlanıyor…',
+  stalled: 'Yanıt hâlâ hazırlanıyor.',
+  retry: 'Tekrar dene',
+  clear: 'Sohbeti temizle',
+  clearConfirm: 'Bu konuşma silinsin mi? Geri alınamaz.',
+  clearYes: 'Sil',
+  loadError: 'Konuşma yüklenemedi.',
+  helpLabel: 'Yardım',
+  helpDictate: 'Dikteyi başlat veya durdur',
+  helpSend: 'Gönder (dikte sırasında: durdur ve gönder)',
+  helpStop: 'Dikteyi durdur, metni koru',
+  helpRecall: 'Önceki sorular',
+  helpNewline: 'Yeni satır',
+};

package/src/i18n/locales/zh.ts

@@ -0,0 +1,34 @@
+import type { AssistantCopy } from '../types';
+
+export const zh: AssistantCopy = {
+  close: '关闭',
+  resize: '调整助手宽度',
+  lockedTitle: '登录后即可聊天',
+  lockedBody: '助手会为你挑选电影并记住对话。登录后开始使用。',
+  lockedComposer: '登录后提问',
+  signIn: '登录',
+  hint: '和 AI 聊聊电影？',
+  statusThinking: '思考中…',
+  statusSearching: '正在搜索片库…',
+  statusReading: '正在查阅影片资料…',
+  statusChoosing: '正在挑选最佳影片…',
+  errAuth: '请登录后向助手提问。',
+  errBusy: '请先在另一个标签页完成。',
+  errInvalid: '消息太长，请缩短后重试。',
+  errRate: '消息过多，请 {{seconds}} 秒后重试。',
+  errUnavailable: '助手正在休息，请稍后再试。',
+  failed: '搜索失败，请重试。',
+  reconnecting: '正在重新连接…',
+  stalled: '仍在生成回答。',
+  retry: '重试',
+  clear: '清空对话',
+  clearConfirm: '删除此对话？此操作无法撤销。',
+  clearYes: '删除',
+  loadError: '无法加载对话。',
+  helpLabel: '帮助',
+  helpDictate: '开始或停止听写',
+  helpSend: '发送（听写时：停止并发送）',
+  helpStop: '停止听写并保留文字',
+  helpRecall: '之前的问题',
+  helpNewline: '换行',
+};

package/src/i18n/sessionCopy.ts

@@ -0,0 +1,30 @@
+import type { ChatHttpError } from '../wire/transport';
+import type { SessionCopy } from '../stream/useSession';
+import type { AssistantCopy } from './types';
+
+/** The one plain sentence per refusal (see the chat contract, "Auth and errors"). */
+function rejectedText(copy: AssistantCopy, error: ChatHttpError): string {
+  switch (error.code) {
+    case 'unauthorized':
+      return copy.errAuth;
+    case 'busy':
+      return copy.errBusy;
+    case 'invalid':
+      return copy.errInvalid;
+    case 'rate_limited':
+      return copy.errRate.replace('{{seconds}}', String(error.retryAfter ?? 30));
+    case 'unavailable':
+      return copy.errUnavailable;
+    default:
+      return copy.failed;
+  }
+}
+
+/** What a session says (refusals, progress labels, a failed turn) in the dictionary's language. */
+export function sessionCopyFor(copy: AssistantCopy): SessionCopy {
+  return {
+    messages: { rejected: (error) => rejectedText(copy, error), streamError: () => copy.failed, failed: copy.failed },
+    status: { thinking: copy.statusThinking, searching: copy.statusSearching, reading: copy.statusReading, choosing: copy.statusChoosing },
+    failedText: copy.failed,
+  };
+}

package/src/i18n/types.ts

@@ -0,0 +1,42 @@
+/** Every string the assistant draws itself, in one language. The dictionaries are bundled (`locales/`), so a host passes a language and nothing else. `{{name}}` marks a value to fill. */
+export interface AssistantCopy {
+  /** Panel and sheet. */
+  close: string;
+  resize: string;
+  /** A viewer who cannot write yet. */
+  lockedTitle: string;
+  lockedBody: string;
+  lockedComposer: string;
+  signIn: string;
+  /** The floating button's teaser. */
+  hint: string;
+  /** What the assistant is doing while an answer streams. */
+  statusThinking: string;
+  statusSearching: string;
+  statusReading: string;
+  statusChoosing: string;
+  /** One plain sentence per refusal or failure. */
+  errAuth: string;
+  errBusy: string;
+  errInvalid: string;
+  /** `{{seconds}}`: how long to wait. */
+  errRate: string;
+  errUnavailable: string;
+  failed: string;
+  /** The line above the composer when the connection drops or an answer stalls, and its action. */
+  reconnecting: string;
+  stalled: string;
+  retry: string;
+  /** Deleting the conversation. */
+  clear: string;
+  clearConfirm: string;
+  clearYes: string;
+  loadError: string;
+  /** The "Help" link under the composer and its list of keys. */
+  helpLabel: string;
+  helpDictate: string;
+  helpSend: string;
+  helpStop: string;
+  helpRecall: string;
+  helpNewline: string;
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+export { AssistantChat, type DataPartRenderer } from './AssistantChat';
+export { scriptedTransport, type ScriptStep } from './stream/scriptedTransport';
+export { useAssistantCopy, ASSISTANT_DICTIONARIES, type AssistantCopy } from './i18n';
+export { ChatDock } from './shell/ChatDock';
+export { AssistantFrame, type FrameLabels } from './shell/AssistantFrame';
+export { AssistantFab, type FabHint } from './shell/AssistantFab';
+export { AssistantLocked } from './shell/AssistantLocked';
+export { createAssistantUi, useMediaQuery, type UiOptions, type UiState, type UiStorage } from './shell/panelState';
+export { AssistantHostProvider, AssistantPortal, AssistantSlot } from './Host';
+export { useSession, type Session, type SessionCopy, type SessionDeps, type SessionNotice, type ThreadApi, type ThreadState } from './stream/useSession';
+export { createStreamAdapter, type AdapterDeps } from './stream/adapter';
+export { reconcile, type Reconciled } from './stream/reconcile';
+export { fromStored, fromStoredThread } from './stream/fromStored';
+export { createTransport, ChatHttpError, ChatNetworkError, type ChatTransport, type RejectCode, type SendInput, type TransportConfig } from './wire/transport';
+export { StreamLostError } from './wire/parseSSE';
+export type { ChatContext, Frame, Phase, StreamErrorCode } from './wire/frames';
+export type { StoredConversation, StoredMessage, StoredStatus, StoredWidget } from './wire/stored';

package/src/messages/MessageFooter.tsx

@@ -0,0 +1,25 @@
+'use client';
+
+import { Check, Copy } from 'lucide-react';
+
+import { MessageActions, useChatCopy, 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.) */
+export function MessageFooter({ message }: { message: ChatMessage }) {
+  const copy = useChatCopy().message;
+  const action = useCopyAction(message, {
+    label: copy.copy,
+    copiedLabel: copy.copied,
+    icon: <Copy className="size-3.5" aria-hidden="true" />,
+    copiedIcon: <Check className="size-3.5" aria-hidden="true" />,
+    write: async (text) => {
+      try {
+        await navigator.clipboard.writeText(text);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+  });
+  return <MessageActions message={message} actions={action ? [action] : []} />;
+}

package/src/messages/NoticeLine.tsx

@@ -0,0 +1,32 @@
+'use client';
+
+import { Button } from '@djangocfg/ui-core/components';
+
+import { useAssistantCopy } from '../i18n';
+import type { SessionNotice } from '../stream/useSession';
+
+interface Props {
+  notice: SessionNotice;
+  onRetry?: () => void;
+}
+
+/** The plain line above the composer when the connection dropped (`reconnecting`) or an answer is still running past its budget (`stalled`, with Retry). */
+export function NoticeLine({ notice, onRetry }: Props) {
+  const copy = useAssistantCopy();
+  return (
+    <div role="status" className="px-4 pb-2 text-xs text-muted-foreground">
+      {notice === 'reconnecting' ? (
+        copy.reconnecting
+      ) : (
+        <span className="inline-flex items-center gap-2">
+          {copy.stalled}
+          {onRetry ? (
+            <Button size="sm" variant="outline" onClick={onRetry}>
+              {copy.retry}
+            </Button>
+          ) : null}
+        </span>
+      )}
+    </div>
+  );
+}

package/src/shell/AssistantFab.tsx

@@ -0,0 +1,112 @@
+'use client';
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import { MessageSquare } from 'lucide-react';
+
+import { useAssistantCopy } from '../i18n';
+
+/** A short line that grows out of the button now and then, so people know what it is for (a live-chat teaser). It has no close control: it leaves by itself, and pressing it opens the chat. The host passes its own, translated, text. */
+export interface FabHint {
+  /** Absent: the bundled teaser for the active language. */
+  text?: string;
+  /** Wait after the button appears before the first showing. Default 2500. */
+  delayMs?: number;
+  /** How long one showing stays. Default 12000. */
+  visibleMs?: number;
+  /** Quiet rings around the button after the bubble has gone, one per interval. Default: every 25 s, three times. */
+  reminders?: { everyMs: number; count: number };
+  /** Classes for the bubble's colours (the package draws it with the popover tokens). */
+  className?: string;
+  /** The bubble appeared (the host may remember that it was shown). */
+  onShown?: () => void;
+}
+
+interface Props {
+  /** Accessible name; the button is icon-only. */
+  label: string;
+  onClick: () => void;
+  hint?: FabHint;
+}
+
+const DEFAULT_REMINDERS = { everyMs: 25_000, count: 3 };
+
+/**
+ * The floating assistant button for screens without room for the column: bottom right, clear of the safe area. The host decides when it shows.
+ * It pops in on load; with a `hint` a bubble follows after a moment, and ring pulses remind of the button later. Pressing the bubble opens the chat.
+ */
+export function AssistantFab({ label, onClick, hint }: Props) {
+  const copy = useAssistantCopy();
+  const [bubble, setBubble] = useState<'off' | 'in' | 'leaving'>('off');
+  const [ring, setRing] = useState(0);
+  const dismissed = useRef(false);
+  const hintRef = useRef(hint);
+  hintRef.current = hint;
+  const hasHint = hint !== undefined;
+  const delayMs = hint?.delayMs ?? 2500;
+  const visibleMs = hint?.visibleMs ?? 12_000;
+  const reminders = hint?.reminders ?? DEFAULT_REMINDERS;
+
+  const leave = useCallback(() => {
+    setBubble((current) => (current === 'in' ? 'leaving' : current));
+    window.setTimeout(() => setBubble('off'), 250);
+  }, []);
+
+  // The showing: after the delay, for a while, then away; reminders follow unless the bubble was closed or the button was pressed.
+  useEffect(() => {
+    if (!hasHint) return;
+    const timers: number[] = [];
+    timers.push(
+      window.setTimeout(() => {
+        if (dismissed.current) return;
+        setBubble('in');
+        hintRef.current?.onShown?.();
+        timers.push(window.setTimeout(leave, visibleMs));
+        for (let i = 1; i <= reminders.count; i += 1) {
+          timers.push(
+            window.setTimeout(() => {
+              if (!dismissed.current) setRing((n) => n + 1);
+            }, visibleMs + i * reminders.everyMs),
+          );
+        }
+      }, delayMs),
+    );
+    return () => timers.forEach((id) => window.clearTimeout(id));
+  }, [hasHint, delayMs, visibleMs, reminders.count, reminders.everyMs, leave]);
+
+  const press = () => {
+    dismissed.current = true;
+    onClick();
+  };
+
+  return (
+    <div
+      style={{ right: 'max(1rem, env(safe-area-inset-right))', bottom: 'max(1rem, env(safe-area-inset-bottom))' }}
+      className="pointer-events-none fixed z-40 flex flex-col items-end gap-2"
+    >
+      {hint && bubble !== 'off' ? (
+        // Like a message bubble: one soft shape whose corner points at the button, text balanced on its lines, nothing to close.
+        <button
+          type="button"
+          role="status"
+          onClick={press}
+          data-leaving={bubble === 'leaving' || undefined}
+          className={`assistant-fab-hint pointer-events-auto -mb-1 max-w-[min(16rem,calc(100vw-2rem))] rounded-[1.25rem] rounded-br-[0.4rem] px-4 py-2.5 text-start text-[0.9375rem] font-medium leading-snug tracking-[-0.01em] text-balance shadow-lg outline-none focus-visible:ring-2 focus-visible:ring-ring ${hint.className ?? 'bg-popover text-popover-foreground'}`}
+        >
+          {hint.text ?? copy.hint}
+        </button>
+      ) : null}
+      <span className="relative inline-flex">
+        {ring > 0 ? <span key={ring} aria-hidden="true" className="assistant-fab-ring absolute inset-0 rounded-full bg-primary" /> : null}
+        <button
+          type="button"
+          aria-label={label}
+          onClick={press}
+          className="assistant-fab pointer-events-auto relative inline-flex size-14 items-center justify-center rounded-full bg-primary text-primary-foreground shadow-lg outline-none transition-transform hover:scale-105 focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 active:scale-95"
+        >
+          <MessageSquare className="size-6" aria-hidden="true" />
+        </button>
+      </span>
+    </div>
+  );
+}

package/src/shell/AssistantFrame.tsx

@@ -0,0 +1,103 @@
+'use client';
+
+import { useCallback, type CSSProperties, type KeyboardEvent, type PointerEvent, type ReactNode } from 'react';
+
+import { X } from 'lucide-react';
+
+import { Button } from '@djangocfg/ui-core/components';
+
+import { AssistantSlot } from '../Host';
+import { useAssistantCopy } from '../i18n';
+
+export interface FrameLabels {
+  /** Name of the column and its heading (the host's brand). */
+  title: string;
+  /** Absent: the bundled words for the active language. */
+  close?: string;
+  /** Name of the width handle. */
+  resize?: string;
+}
+
+interface Props {
+  /** The column is on screen. The host decides (open, wide enough, allowed); when false the page takes the whole width. */
+  docked: boolean;
+  width: number;
+  minWidth: number;
+  maxWidth: number;
+  defaultWidth: number;
+  onWidthChange: (width: number) => void;
+  onClose: () => void;
+  labels: FrameLabels;
+  /** What the column shows instead of the chat (the locked view, a notice). Absent: the chat itself. */
+  content?: ReactNode;
+  /** The page. */
+  children: ReactNode;
+}
+
+/**
+ * The page with the assistant column beside it. While `docked`, the page narrows and the column stands at the right edge, full height. Its width is published as the CSS
+ * variable `--assistant-w` (`0px` when closed) so fixed elements of the host keep clear of it. Page scroll stays the window's: the column is `sticky`, not a scroll container.
+ */
+export function AssistantFrame({ docked, width, minWidth, maxWidth, defaultWidth, onWidthChange, onClose, labels, content, children }: Props) {
+  const style = { '--assistant-w': docked ? `${width}px` : '0px' } as CSSProperties;
+  return (
+    <div className="flex" style={style}>
+      <div className="min-w-0 flex-1">{children}</div>
+      {docked ? <Column {...{ width, minWidth, maxWidth, defaultWidth, onWidthChange, onClose, labels, content }} /> : null}
+    </div>
+  );
+}
+
+function Column({ width, minWidth, maxWidth, defaultWidth, onWidthChange, onClose, labels, content }: Omit<Props, 'docked' | 'children'>) {
+  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(
+    (event: PointerEvent<HTMLDivElement>) => {
+      event.preventDefault();
+      const handle = event.currentTarget;
+      handle.setPointerCapture(event.pointerId);
+      const move = (e: globalThis.PointerEvent) => onWidthChange(window.innerWidth - e.clientX);
+      const stop = () => {
+        handle.removeEventListener('pointermove', move);
+        handle.removeEventListener('pointerup', stop);
+        handle.removeEventListener('pointercancel', stop);
+      };
+      handle.addEventListener('pointermove', move);
+      handle.addEventListener('pointerup', stop);
+      handle.addEventListener('pointercancel', stop);
+    },
+    [onWidthChange],
+  );
+  const key = (event: KeyboardEvent<HTMLDivElement>) => {
+    if (event.key === 'ArrowLeft') onWidthChange(width + 24);
+    else if (event.key === 'ArrowRight') onWidthChange(width - 24);
+    else if (event.key === 'Home') onWidthChange(defaultWidth);
+    else return;
+    event.preventDefault();
+  };
+
+  return (
+    <aside aria-label={labels.title} style={{ width }} className="sticky top-0 flex h-dvh shrink-0 flex-col self-start border-l bg-background">
+      <div
+        role="separator"
+        aria-orientation="vertical"
+        aria-label={labels.resize ?? copy.resize}
+        aria-valuemin={minWidth}
+        aria-valuemax={maxWidth}
+        aria-valuenow={width}
+        tabIndex={0}
+        onPointerDown={drag}
+        onKeyDown={key}
+        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>
+      {content ? <div className="flex min-h-0 flex-1 flex-col">{content}</div> : <AssistantSlot className="min-h-0 flex-1" />}
+    </aside>
+  );
+}

package/src/shell/AssistantLocked.tsx

@@ -0,0 +1,44 @@
+'use client';
+
+import type { ReactNode } from 'react';
+
+import { Lock } from 'lucide-react';
+
+import { useAssistantCopy } from '../i18n';
+
+interface Props {
+  /** Absent: the bundled "sign in to chat" words for the active language. */
+  title?: string;
+  body?: string;
+  /** The way out ("Sign in"); absent when there is none (the assistant is switched off). */
+  action?: ReactNode;
+  /** Text of the inert composer under the message, so the column still reads as a chat. */
+  composerLabel?: string;
+  /** Replaces the lock. */
+  icon?: ReactNode;
+}
+
+/**
+ * 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) {
+  const copy = useAssistantCopy();
+  return (
+    <div className="flex min-h-0 flex-1 flex-col">
+      <div className="flex min-h-0 flex-1 flex-col items-center justify-center gap-4 px-8 py-12 text-center">
+        <span className="grid size-16 place-items-center rounded-full bg-muted text-muted-foreground ring-1 ring-border">{icon ?? <Lock className="size-7" aria-hidden="true" />}</span>
+        <div className="space-y-2">
+          <p className="font-display text-lg font-semibold">{title ?? copy.lockedTitle}</p>
+          <p className="mx-auto max-w-[32ch] text-sm leading-relaxed text-muted-foreground">{body ?? copy.lockedBody}</p>
+        </div>
+        {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>
+      </div>
+    </div>
+  );
+}

package/src/shell/ChatDock.tsx

@@ -0,0 +1,62 @@
+'use client';
+
+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 { useIsMobile } from '@djangocfg/ui-core/hooks';
+
+import { useAssistantCopy } from '../i18n';
+
+interface Props {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  /** The chat, or the slot that shows it. */
+  children: ReactNode;
+  title: string;
+  /** What the thread is about ("The Quiet Harbour"), shown under the title; absent outside a title or browse scope. */
+  contextLine?: string;
+  /** Accessible name of the close button on phones. Absent: the bundled word. */
+  closeLabel?: string;
+}
+
+/** 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();
+  const isMobile = useIsMobile();
+
+  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>
+    );
+  }
+
+  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>
+        <SidePanel.Body>{chat}</SidePanel.Body>
+      </SidePanel.Content>
+    </SidePanel>
+  );
+}