@djangocfg/widget-assistant 0.2.9 → 0.3.7

package/src/sessions/SessionsMenu.tsx

@@ -0,0 +1,82 @@
+'use client';
+
+import { Check, History, Plus } from 'lucide-react';
+
+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';
+import { relativeTime } from '../stream/sessions';
+
+interface Props {
+  session: Pick<Session, 'thread' | 'sessions' | 'busy' | 'startNew' | 'switchTo' | 'refreshSessions'>;
+  /** The language tag for "5 minutes ago". Absent: the assistant's active language. */
+  locale?: string;
+  /** Hide the list and keep only "New chat" (a host with no list endpoint, such as an anonymous one). */
+  newOnly?: boolean;
+}
+
+/**
+ * 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) {
+  const copy = useAssistantCopy(locale);
+  const active = useAssistantLocale(locale);
+  const current = session.thread.kind === 'ready' ? session.thread.session : null;
+  return (
+    <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()}>
+          <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 ? (
+              <p className="px-2 py-1.5 text-xs text-muted-foreground">{copy.sessionsEmpty}</p>
+            ) : (
+              session.sessions.map((item) => (
+                <DropdownMenuItem key={item.id} disabled={session.busy} onSelect={() => void session.switchTo(item.id)} className="items-start gap-2">
+                  <Check className={`mt-0.5 size-4 shrink-0 ${item.id === current ? '' : 'invisible'}`} aria-hidden="true" />
+                  <span className="min-w-0 flex-1">
+                    <span className="block truncate">{item.title || copy.newChat}</span>
+                    <span className="block text-xs text-muted-foreground">{relativeTime(item.last_message_at, active)}</span>
+                  </span>
+                </DropdownMenuItem>
+              ))
+            )}
+          </DropdownMenuContent>
+        </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>

package/src/stream/adapter.ts

@@ -6,6 +6,8 @@ import { ChatHttpError, ChatNetworkError, type ChatTransport } from '../wire/tra
 
 export interface AdapterDeps {
   transport: ChatTransport;
+  /** The session this message goes to: the current one, or a new one created now (the first send of a user who has none). A rejection ends the turn as a failed message. Absent: no session (an anonymous host). */
+  threadFor?: () => Promise<string>;
   /** Scope of this turn, read at send time (the page the user is on). */
   getContext: () => ChatContext | undefined;
   /** Ephemeral progress for the live label above the composer; `null` when the run ends. Never enters the transcript. */
@@ -17,6 +19,8 @@ export interface AdapterDeps {
   onUnknownPayload?: (kind: string) => void;
   /** The stream ended without a terminal frame: the host reconciles from the server. */
   onInterrupted?: () => void;
+  /** A turn is in flight (true at the send, false when its stream ends): the host holds session switching meanwhile. */
+  onActive?: (active: boolean) => void;
   /** A network-level failure, for the connectivity monitor. */
   onNetworkFailure?: () => void;
   /** One plain sentence per outcome (the catalogue). */
@@ -56,6 +60,7 @@ export function createStreamAdapter(deps: AdapterDeps): ChatAdapter {
           let pending = '';
           let timer: ReturnType<typeof setTimeout> | null = null;
           let terminal = false;
+          deps.onActive?.(true);
 
           const open = (id: string) => {
             messageId = id;
@@ -114,7 +119,8 @@ export function createStreamAdapter(deps: AdapterDeps): ChatAdapter {
           };
 
           try {
-            for await (const frame of deps.transport.open({ text, clientId, context: deps.getContext(), signal })) {
+            const threadId = deps.threadFor ? await deps.threadFor() : undefined;
+            for await (const frame of deps.transport.open({ threadId, text, clientId, context: deps.getContext(), signal })) {
               handle(frame);
               if (terminal) break;
             }
@@ -142,6 +148,7 @@ export function createStreamAdapter(deps: AdapterDeps): ChatAdapter {
           } finally {
             if (timer) clearTimeout(timer);
             deps.onStatus(null);
+            deps.onActive?.(false);
             controller.close();
           }
         },

package/src/stream/sessions.ts

@@ -0,0 +1,58 @@
+import type { StoredConversation, StoredThread } from '../wire/stored';
+import { ThreadNotFoundError } from '../wire/transport';
+
+/** The session endpoints (`/apix/chat/v1/threads`), supplied by the app. `load` throws `ThreadNotFoundError` for a session that is not the viewer's or is gone. */
+export interface ThreadApi {
+  /** The viewer's sessions with messages, newest activity first. */
+  list: (signal: AbortSignal) => Promise<StoredThread[]>;
+  /** A new, empty session (`POST threads`). */
+  create: () => Promise<StoredThread>;
+  /** One session with its last messages. */
+  load: (id: string, signal: AbortSignal) => Promise<StoredConversation>;
+}
+
+/** Where the last used session id is kept (the host picks the key). Reads and writes must never throw. */
+export interface SessionStorage {
+  read: () => string | null;
+  write: (id: string | null) => void;
+}
+
+export const NO_SESSION: StoredConversation = { id: null, messages: [] };
+
+/**
+ * The session to show on page load: the remembered one, else the newest, else none (a session is created on the first send, never on load).
+ * A remembered id that is gone (another account on this browser, a purged session) is forgotten and the newest takes over.
+ */
+export async function restoreSession({ api, storage, signal }: { api: ThreadApi; storage?: SessionStorage; signal: AbortSignal }): Promise<StoredConversation> {
+  const remembered = storage?.read() ?? null;
+  if (remembered) {
+    try {
+      return await api.load(remembered, signal);
+    } catch (error) {
+      if (!(error instanceof ThreadNotFoundError)) throw error;
+      storage?.write(null);
+    }
+  }
+  const [newest] = await api.list(signal);
+  return newest ? api.load(newest.id, signal) : NO_SESSION;
+}
+
+const STEPS: ReadonlyArray<[Intl.RelativeTimeFormatUnit, number]> = [
+  ['year', 31_536_000],
+  ['month', 2_592_000],
+  ['week', 604_800],
+  ['day', 86_400],
+  ['hour', 3_600],
+  ['minute', 60],
+];
+
+/** "5 minutes ago" in the viewer's language; under a minute it is `now` (the unit `numeric: 'auto'` words as "now"). */
+export function relativeTime(iso: string, locale: string, now: number = Date.now()): string {
+  const seconds = Math.round((Date.parse(iso) - now) / 1000);
+  const formatter = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' });
+  const abs = Math.abs(seconds);
+  for (const [unit, size] of STEPS) {
+    if (abs >= size) return formatter.format(Math.round(seconds / size), unit);
+  }
+  return formatter.format(0, 'second');
+}

package/src/stream/useSession.ts

@@ -8,17 +8,12 @@ import { useAssistantCopy } from '../i18n';
 import { sessionCopyFor } from '../i18n/sessionCopy';
 
 import type { ChatContext, Phase } from '../wire/frames';
-import type { StoredConversation } from '../wire/stored';
-import type { ChatHttpError, ChatTransport } from '../wire/transport';
+import type { StoredConversation, StoredThread } from '../wire/stored';
+import { ThreadNotFoundError, type ChatHttpError, type ChatTransport } from '../wire/transport';
 import { createStreamAdapter, type AdapterDeps } from './adapter';
 import { fromStoredThread } from './fromStored';
 import { reconcile } from './reconcile';
-
-/** The conversation endpoints, supplied by the app (signed-in hosts). */
-export interface ThreadApi {
-  load: (signal: AbortSignal) => Promise<StoredConversation>;
-  clear: () => Promise<void>;
-}
+import { NO_SESSION, restoreSession, type SessionStorage, type ThreadApi } from './sessions';
 
 export interface SessionCopy {
   messages: AdapterDeps['messages'];
@@ -30,19 +25,22 @@ export interface SessionCopy {
 
 export interface SessionDeps {
   transport: ChatTransport;
-  /** Absent: an anonymous session. Nothing is fetched, the room starts empty, and a lost stream cannot be reconciled (the notice offers Retry). */
+  /** Absent: an anonymous session. Nothing is fetched or listed, the room starts empty, "new chat" empties it, and a lost stream cannot be reconciled (the notice offers Retry). */
   api?: ThreadApi;
+  /** Remembers the last used session so a reload returns to it. Absent: the newest session is shown. */
+  storage?: SessionStorage;
   getContext: () => ChatContext | undefined;
-  /** Absent: the bundled words for the active language. */
-  copy?: SessionCopy;
   /** The `kind`s the host draws; any other live payload is dropped and reported. */
   payloadKinds?: readonly string[];
   onUnknownPayload?: (kind: string) => void;
+  /** Absent: the bundled words for the active language. */
+  copy?: SessionCopy;
   onRejected?: (error: ChatHttpError) => void;
   onNetworkFailure?: () => void;
 }
 
-export type ThreadState = { kind: 'loading' } | { kind: 'error' } | { kind: 'ready'; id: string; history: ChatMessage[] };
+/** `id` is the transcript's identity (the session plus a revision: a new one reseeds the widget); `session` is the session itself, `null` before the first send. */
+export type ThreadState = { kind: 'loading' } | { kind: 'error' } | { kind: 'ready'; id: string; session: string | null; history: ChatMessage[] };
 
 /** `reconnecting`: the stream was lost and the server is being asked; `stalled`: the answer is still running after the budget (offer Retry). */
 export type SessionNotice = 'reconnecting' | 'stalled';
@@ -53,14 +51,21 @@ export interface Session {
   /** Live progress label while a run streams; null otherwise. */
   statusLabel: string | null;
   notice: SessionNotice | null;
-  /** Load the thread again (after a load error or a stalled run). */
+  /** Load the session again (after a load error or a stalled run). */
   reload: () => void;
-  /** Delete the conversation; the next message starts a new one. */
-  clear: () => Promise<void>;
+  /** The viewer's sessions, newest activity first; `null` until `refreshSessions` has answered once. */
+  sessions: StoredThread[] | null;
+  refreshSessions: () => void;
+  /** A turn is in flight: starting or switching a session waits for it (Stop ends it). */
+  busy: boolean;
+  /** "New chat": a new empty session, shown at once. A no-op while the current one is empty. Resolves `false` when it failed (nothing changed). */
+  startNew: () => Promise<boolean>;
+  /** Show another session. Resolves `false` when it failed (the current one stays). */
+  switchTo: (id: string) => Promise<boolean>;
 }
 
 /**
- * One signed-in conversation: the thread from the server (no client copy), the adapter for new messages, the live status label, and the reconcile
+ * The signed-in assistant's sessions: the shown session from the server (no client copy), the adapter for new messages, the live status label, and the reconcile
  * that runs when a stream is lost. A new `history` identity (`id` carries a revision) reseeds the widget only between runs.
  */
 export function useSession(given: SessionDeps): Session {
@@ -71,27 +76,53 @@ export function useSession(given: SessionDeps): Session {
   const [thread, setThread] = useState<ThreadState>({ kind: 'loading' });
   const [phase, setPhase] = useState<Phase | null>(null);
   const [notice, setNotice] = useState<SessionNotice | null>(null);
+  const [sessions, setSessions] = useState<StoredThread[] | null>(null);
+  const [busy, setBusy] = useState(false);
   const revision = useRef(0);
   const live = useRef<AbortController | null>(null);
+  /** The shown session's id; `null` before the first send. Written with the storage, in one place. */
+  const current = useRef<string | null>(null);
 
-  const seed = useCallback((conversation: StoredConversation) => {
-    revision.current += 1;
-    setThread({ kind: 'ready', id: `${conversation.id ?? 'new'}:${revision.current}`, history: fromStoredThread(conversation.messages, ref.current.copy.failedText) });
+  const remember = useCallback((id: string | null) => {
+    current.current = id;
+    ref.current.storage?.write(id);
   }, []);
 
+  const seed = useCallback(
+    (conversation: StoredConversation) => {
+      revision.current += 1;
+      remember(conversation.id);
+      setThread({
+        kind: 'ready',
+        id: `${conversation.id ?? 'new'}:${revision.current}`,
+        session: conversation.id,
+        history: fromStoredThread(conversation.messages, ref.current.copy.failedText),
+      });
+    },
+    [remember],
+  );
+
   const load = useCallback(() => {
     live.current?.abort();
     const controller = new AbortController();
     live.current = controller;
-    setNotice(null);
-    const api = ref.current.api;
-    if (!api) return seed({ id: null, messages: [] });
     setThread({ kind: 'loading' });
-    api.load(controller.signal).then(
+    setNotice(null);
+    const { api, storage } = ref.current;
+    if (!api) return seed(NO_SESSION);
+    const restore = () => restoreSession({ api, storage, signal: controller.signal });
+    const read = current.current
+      ? api.load(current.current, controller.signal).catch((error: unknown) => {
+          if (!(error instanceof ThreadNotFoundError)) throw error;
+          remember(null); // the shown session is gone: fall back to the newest
+          return restore();
+        })
+      : restore();
+    read.then(
       (conversation) => !controller.signal.aborted && seed(conversation),
       () => !controller.signal.aborted && setThread({ kind: 'error' }),
     );
-  }, [seed]);
+  }, [seed, remember]);
 
   useEffect(() => {
     load();
@@ -102,11 +133,25 @@ export function useSession(given: SessionDeps): Session {
     () =>
       createStreamAdapter({
         transport: deps.transport,
+        // The first send of a viewer with no session creates one; the shown transcript is not reseeded (that would drop the live message).
+        threadFor: ref.current.api
+          ? async () => {
+              if (current.current) return current.current;
+              const created = await ref.current.api!.create();
+              remember(created.id);
+              return created.id;
+            }
+          : undefined,
         getContext: () => ref.current.getContext(),
         onStatus: setPhase,
         payloadKinds: deps.payloadKinds,
         onUnknownPayload: (kind) => ref.current.onUnknownPayload?.(kind),
-        onRejected: (error) => ref.current.onRejected?.(error),
+        onActive: setBusy,
+        onRejected: (error) => {
+          // The session vanished (purged, or another account's): forget it, the next send starts a fresh one.
+          if (error.code === 'not_found') remember(null);
+          ref.current.onRejected?.(error);
+        },
         onNetworkFailure: () => ref.current.onNetworkFailure?.(),
         messages: {
           rejected: (error) => ref.current.copy.messages.rejected(error),
@@ -116,12 +161,12 @@ export function useSession(given: SessionDeps): Session {
           },
         },
         onInterrupted: () => {
-          setNotice('reconnecting');
           const api = ref.current.api;
           if (!api) return setNotice('stalled');
+          setNotice('reconnecting');
           const controller = new AbortController();
           live.current = controller;
-          reconcile({ fetchConversation: api.load, signal: controller.signal }).then(
+          reconcile({ fetchConversation: (signal) => api.load(current.current ?? '', signal), signal: controller.signal }).then(
             (result) => {
               if (controller.signal.aborted) return;
               if (result.outcome === 'timeout') return setNotice('stalled');
@@ -133,14 +178,46 @@ export function useSession(given: SessionDeps): Session {
         },
       }),
     // The transport is one per mounted chat; everything else is read through `ref`.
-    [deps.transport, deps.payloadKinds, seed],
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [deps.transport, deps.payloadKinds, Boolean(deps.api), seed, remember],
   );
 
-  const clear = useCallback(async () => {
-    await ref.current.api?.clear();
-    live.current?.abort();
-    seed({ id: null, messages: [] });
-  }, [seed]);
+  const refreshSessions = useCallback(() => {
+    ref.current.api?.list(new AbortController().signal).then(setSessions, () => undefined);
+  }, []);
+
+  const show = useCallback(
+    async (read: (signal: AbortSignal) => Promise<StoredConversation>): Promise<boolean> => {
+      live.current?.abort();
+      const controller = new AbortController();
+      live.current = controller;
+      try {
+        const conversation = await read(controller.signal);
+        if (controller.signal.aborted) return false;
+        setNotice(null);
+        seed(conversation);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    [seed],
+  );
+
+  const startNew = useCallback(async () => {
+    if ((ref.current.api && current.current === null) || (thread.kind === 'ready' && thread.history.length === 0)) return true; // already a blank page
+    const api = ref.current.api;
+    if (!api) return show(async () => NO_SESSION);
+    return show(async () => {
+      const created = await api.create();
+      return { id: created.id, messages: [] };
+    });
+  }, [show, thread]);
+
+  const switchTo = useCallback(
+    async (id: string) => (id === current.current || !ref.current.api ? true : show((signal) => ref.current.api!.load(id, signal))),
+    [show],
+  );
 
-  return { thread, adapter, statusLabel: phase ? ref.current.copy.status[phase] : null, notice, reload: load, clear };
+  return { thread, adapter, statusLabel: phase ? ref.current.copy.status[phase] : null, notice, reload: load, sessions, refreshSessions, busy, startNew, switchTo };
 }

package/src/wire/stored.ts

@@ -18,7 +18,16 @@ export interface StoredMessage {
   created_at: string;
 }
 
+/** One session with its last messages; `id: null` is the state before the first send (no session exists yet, or the host is anonymous). */
 export interface StoredConversation {
   id: string | null;
   messages: StoredMessage[];
 }
+
+/** A session in the list (`GET threads/`): `title` is the first user message, empty until its first answer finishes. */
+export interface StoredThread {
+  id: string;
+  title: string;
+  last_message_at: string;
+  message_count: number;
+}