@djangocfg/ui-tools 2.1.368 → 2.1.371

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-tools",
-  "version": "2.1.368",
+  "version": "2.1.371",
   "description": "Heavy React tools with lazy loading - for Electron, Vite, CRA, Next.js apps",
   "keywords": [
     "ui-tools",
@@ -156,8 +156,8 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.368",
-    "@djangocfg/ui-core": "^2.1.368",
+    "@djangocfg/i18n": "^2.1.371",
+    "@djangocfg/ui-core": "^2.1.371",
     "consola": "^3.4.2",
     "lodash-es": "^4.18.1",
     "lucide-react": "^0.545.0",
@@ -193,6 +193,7 @@
     "react-lottie-player": "^2.1.0",
     "react-map-gl": "^8.1.0",
     "react-markdown": "10.1.0",
+    "react-virtuoso": "^4.18.7",
     "react-zoom-pan-pinch": "^3.7.0",
     "rehype-external-links": "^3.0.0",
     "rehype-raw": "^7.0.0",
@@ -210,10 +211,10 @@
     "material-file-icons": "^2.4.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.368",
+    "@djangocfg/i18n": "^2.1.371",
     "@djangocfg/playground": "workspace:*",
-    "@djangocfg/typescript-config": "^2.1.368",
-    "@djangocfg/ui-core": "^2.1.368",
+    "@djangocfg/typescript-config": "^2.1.371",
+    "@djangocfg/ui-core": "^2.1.371",
     "@types/lodash-es": "^4.17.12",
     "@types/mapbox__mapbox-gl-draw": "^1.4.8",
     "@types/node": "^24.7.2",

package/src/tools/Chat/README.md

@@ -513,7 +513,28 @@ LazyChat
 - **Token coalescing.** `createTokenBuffer` aggregates stream chunks within ~16ms before dispatching → ≤1 render per frame.
 - **Plain text during stream.** `MessageBubble` skips ReactMarkdown until the message finishes, then re-renders once with full markdown.
 - **Memoized bubbles.** Memo key `(id, content, isStreaming, version, toolActivity, toolCalls, sources, attachments)` — references only.
-- **Virtualization is opt-in.** `@tanstack/react-virtual` stays a host-side decision via `MessageList renderItem` slot.
+- **Virtualization is on by default.** As of plan64, `<MessageList>` is built on [`react-virtuoso`](https://virtuoso.dev/). Sticky-bottom + auto-follow on streaming come from `followOutput`, top-of-list pagination from `startReached`, scroll-anchor preservation on prepend from `firstItemIndex`. No host-side virtualizer needed. Set `noVirtualize` on `<MessageList>` to opt out (stories / DevTools tracing).
+
+### Scroll API
+
+`<MessageList>` exposes an imperative handle:
+
+```tsx
+const listRef = useRef<MessageListHandle>(null);
+
+<MessageList
+  ref={listRef}
+  onAtBottomChange={setIsAtBottom}     // drives "Jump to latest" pill
+  onStartReached={() => void loadMore()} // top-of-list pagination
+/>;
+
+listRef.current?.scrollToBottom(true);  // smooth jump
+listRef.current?.scrollToIndex(42);     // jump to a specific bubble
+```
+
+The legacy `useChatScroll` hook is kept for hosts that render their
+own (non-virtualized) scroll container, but is `@deprecated` for use
+with `<MessageList>` — the component owns sticky-bottom internally.
 
 ## Design docs
 

package/src/tools/Chat/components/ChatRoot.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { type ReactNode, useRef } from 'react';
+import { type ReactNode, useRef, useState } from 'react';
 
 import { cn } from '@djangocfg/ui-core/lib';
 
@@ -8,14 +8,12 @@ import type { ChatAttachment, ChatConfig, ChatMessage, ChatTransport } from '../
 import type { ChatAudioConfig } from '../core/audio/types';
 import { ChatProvider, useChatContext, type ChatContextValue } from '../context';
 import { useChatComposer, type UseChatComposerReturn } from '../hooks/useChatComposer';
-import { useChatScroll } from '../hooks/useChatScroll';
-import { useChatHistory } from '../hooks/useChatHistory';
 import { Composer, type ComposerSize } from './Composer';
 import { EmptyState } from './EmptyState';
 import { ErrorBanner } from './ErrorBanner';
 import { JumpToLatest } from './JumpToLatest';
 import { MessageBubble } from './MessageBubble';
-import { MessageList } from './MessageList';
+import { MessageList, type MessageListHandle } from './MessageList';
 import type { AttachmentRendererMap } from './Attachments';
 import type { ToolCallsProps } from './ToolCalls';
 
@@ -115,24 +113,14 @@ function ChatRootShell({ className, listClassName, slots }: ChatRootShellProps)
     onSubmit: (content, attachments) => chat.sendMessage(content, attachments),
     disabled: chat.isStreaming,
   });
-  const containerRef = useRef<HTMLDivElement | null>(null);
-  const bottomRef = useRef<HTMLDivElement | null>(null);
-  const topRef = useRef<HTMLDivElement | null>(null);
-
-  const scroll = useChatScroll({
-    containerRef,
-    bottomRef,
-    isStreaming: chat.isStreaming,
-    messagesCount: chat.messages.length,
-  });
-
-  useChatHistory({
-    containerRef,
-    topSentinelRef: topRef,
-    hasMore: chat.hasMore,
-    isLoadingMore: chat.isLoadingMore,
-    loadMore: chat.loadMore,
-  });
+  // MessageList (virtuoso) owns the scroll viewport. We talk to it
+  // via the imperative handle (scrollToBottom on JumpToLatest click)
+  // and via the `onAtBottomChange` callback (drives the pill).
+  const listRef = useRef<MessageListHandle | null>(null);
+  const [isAtBottom, setIsAtBottom] = useState(true);
+  const handleStartReached = chat.hasMore && !chat.isLoadingMore
+    ? () => void chat.loadMore()
+    : undefined;
 
   const greeting = chat.config.greeting ?? 'How can I help?';
   const description = chat.config.description;
@@ -180,19 +168,18 @@ function ChatRootShell({ className, listClassName, slots }: ChatRootShellProps)
           onRetry={chat.error ? () => void chat.regenerate() : undefined}
         />
         <MessageList
-          ref={containerRef}
-          topSentinelRef={topRef}
-          bottomRef={bottomRef}
+          ref={listRef}
           renderItem={renderItem}
           renderEmpty={() => <>{emptyNode}</>}
           className={listClassName}
+          onStartReached={handleStartReached}
+          onAtBottomChange={setIsAtBottom}
         />
         <div className="pointer-events-none absolute inset-x-0 bottom-2 flex justify-center">
           {slots.jumpToLatest ?? (
             <JumpToLatest
-              visible={!scroll.isAtBottom}
-              unreadCount={scroll.unreadCount}
-              onClick={() => scroll.scrollToBottom(true)}
+              visible={!isAtBottom}
+              onClick={() => listRef.current?.scrollToBottom(true)}
             />
           )}
         </div>

package/src/tools/Chat/components/MessageBubble.tsx

@@ -57,6 +57,27 @@ export interface MessageBubbleProps {
   onRegenerate?: () => void;
   onEdit?: () => void;
   onDelete?: () => void;
+  /**
+   * Extra content rendered alongside the default copy/regenerate/edit/
+   * delete actions (after them, on the same row). Hosts pass app-
+   * specific affordances here — e.g. "Send to plan", "Add note",
+   * "Open in inspector" — without having to fork `<MessageActions>`.
+   * Receives the message so renderers can branch by id / role / etc.
+   * Plan64.
+   */
+  messageActionsExtra?: (m: ChatMessage) => ReactNode;
+  /**
+   * Override the default streaming indicator (the dots / pulse + tool
+   * activity label). Receives the message so the host can read
+   * `toolActivity`, the running tool call name, etc., and render a
+   * richer affordance ("Running cmd_execute on vps-audi…"). Plan64.
+   *
+   * Renders in two slots: as the in-bubble pre-token affordance, and
+   * as the inline label above the bubble when `toolActivity` is set.
+   * The render-prop is called for both — branch on `m.content` if
+   * you need different behaviour per slot.
+   */
+  streamingIndicator?: (m: ChatMessage) => ReactNode;
 }
 
 const MessageBubbleInner = ({
@@ -83,6 +104,8 @@ const MessageBubbleInner = ({
   onRegenerate,
   onEdit,
   onDelete,
+  messageActionsExtra,
+  streamingIndicator,
 }: MessageBubbleProps) => {
   const isUser = isUserProp ?? message.role === 'user';
   const isStreaming = !!message.isStreaming;
@@ -160,7 +183,9 @@ const MessageBubbleInner = ({
         >
           {isStreaming && message.toolActivity ? (
             <div className="mb-1.5">
-              <StreamingIndicator label={message.toolActivity} />
+              {streamingIndicator
+                ? streamingIndicator(message)
+                : <StreamingIndicator label={message.toolActivity} />}
             </div>
           ) : null}
 
@@ -172,7 +197,7 @@ const MessageBubbleInner = ({
               plainText={isStreaming}
             />
           ) : (
-            <StreamingIndicator />
+            streamingIndicator ? streamingIndicator(message) : <StreamingIndicator />
           )}
         </div>
 
@@ -189,13 +214,16 @@ const MessageBubbleInner = ({
           : null}
 
         {showActions && !isStreaming ? (
-          <MessageActions
-            role={message.role}
-            onCopy={onCopy}
-            onRegenerate={onRegenerate}
-            onEdit={onEdit}
-            onDelete={onDelete}
-          />
+          <div className="flex items-center gap-0.5">
+            <MessageActions
+              role={message.role}
+              onCopy={onCopy}
+              onRegenerate={onRegenerate}
+              onEdit={onEdit}
+              onDelete={onDelete}
+            />
+            {messageActionsExtra ? messageActionsExtra(message) : null}
+          </div>
         ) : null}
 
         {showTimestamp ? (

package/src/tools/Chat/components/MessageList.tsx

@@ -1,9 +1,20 @@
 'use client';
 
-import { type RefObject, type ReactNode, forwardRef, useCallback } from 'react';
+import {
+  type ReactNode,
+  type RefObject,
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+} from 'react';
+import { Virtuoso, type VirtuosoHandle } from 'react-virtuoso';
 
 import { cn } from '@djangocfg/ui-core/lib';
 import { Spinner } from '@djangocfg/ui-core/components';
+import { useCopy } from '@djangocfg/ui-core/hooks';
 
 import type { ChatMessage } from '../types';
 import { useChatContextOptional } from '../context';
@@ -14,69 +25,234 @@ export interface MessageListProps {
   renderItem?: (m: ChatMessage, i: number) => ReactNode;
   renderEmpty?: () => ReactNode;
   isLoadingMore?: boolean;
+  /**
+   * Fires when the user scrolls within `topThresholdPx` of the top of
+   * the list — wire to your `loadMore()` here. Replaces the previous
+   * `topSentinelRef` API. The callback is gated by Virtuoso, so it
+   * won't fire repeatedly while a load is in flight (Virtuoso pauses
+   * `startReached` until `data` length grows).
+   */
+  onStartReached?: () => void;
+  /**
+   * @deprecated Kept as a no-op for backwards compatibility — wire
+   * `onStartReached` instead. Virtuoso owns the scroll viewport now,
+   * external sentinels never see scroll events.
+   */
   topSentinelRef?: RefObject<HTMLDivElement | null>;
+  /**
+   * @deprecated Kept as a no-op for backwards compatibility — Virtuoso
+   * exposes `scrollToIndex` via the imperative handle instead. See
+   * `useChatScroll` for the chat-friendly wrapper.
+   */
   bottomRef?: RefObject<HTMLDivElement | null>;
   className?: string;
   itemClassName?: string;
+  /**
+   * Skip virtualization and render through plain `.map()`. Use for
+   * stories / debugging where DevTools needs to see every node, or
+   * when `messages` is guaranteed-tiny. Default: `false` — virtualize
+   * always. Plan64.
+   */
+  noVirtualize?: boolean;
+  /**
+   * Initial item height estimate fed to Virtuoso's first-paint pass.
+   * The library re-measures every item after mount; this just tightens
+   * the initial scrollbar before measurements land. Default `120`.
+   */
+  defaultItemHeight?: number;
+  /**
+   * Fires when the viewport sticky state changes — `true` when the
+   * user is pinned to the bottom (streaming token deltas keep them
+   * there), `false` once they scroll up. Wire to your "Jump to
+   * latest" affordance via the inverse: render the pill when
+   * `!isAtBottom`. Plan64.
+   */
+  onAtBottomChange?: (isAtBottom: boolean) => void;
 }
 
-export const MessageList = forwardRef<HTMLDivElement, MessageListProps>(function MessageList(
+export interface MessageListHandle {
+  scrollToBottom: (smooth?: boolean) => void;
+  scrollToIndex: (index: number, smooth?: boolean) => void;
+}
+
+export const MessageList = forwardRef<MessageListHandle, MessageListProps>(function MessageList(
   {
     messages: messagesProp,
     renderItem,
     renderEmpty,
     isLoadingMore: isLoadingMoreProp,
-    topSentinelRef,
-    bottomRef,
+    onStartReached,
     className,
     itemClassName,
+    noVirtualize = false,
+    defaultItemHeight = 120,
+    onAtBottomChange,
   },
   ref,
 ) {
   const ctx = useChatContextOptional();
   const messages = messagesProp ?? ctx?.messages ?? [];
   const isLoadingMore = isLoadingMoreProp ?? ctx?.isLoadingMore ?? false;
+  const { copyToClipboard } = useCopy();
+
+  const virtuosoRef = useRef<VirtuosoHandle | null>(null);
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      scrollToBottom: (smooth = false) => {
+        virtuosoRef.current?.scrollToIndex({
+          index: 'LAST',
+          behavior: smooth ? 'smooth' : 'auto',
+          align: 'end',
+        });
+      },
+      scrollToIndex: (index, smooth = false) => {
+        virtuosoRef.current?.scrollToIndex({
+          index,
+          behavior: smooth ? 'smooth' : 'auto',
+        });
+      },
+    }),
+    [],
+  );
 
   const defaultRenderItem = useCallback(
     (m: ChatMessage) => (
-      <div className={itemClassName} key={m.id}>
+      <div className={itemClassName}>
         <MessageBubble
           message={m}
-          onCopy={() => copy(m.content)}
+          onCopy={() => void copyToClipboard(m.content)}
           onRegenerate={ctx ? () => void ctx.regenerate(m.id) : undefined}
           onDelete={ctx ? () => ctx.deleteMessage(m.id) : undefined}
         />
       </div>
     ),
-    [itemClassName, ctx],
+    [itemClassName, ctx, copyToClipboard],
   );
 
   const itemRenderer = renderItem ?? defaultRenderItem;
+  // Virtuoso may invoke `computeItemKey` for an index briefly out of
+  // sync with `data` during fast state churn (streaming chunks +
+  // Strict Mode double-mount). `m` arrives undefined in that window.
+  // Falling back to the index keeps the lookup stable instead of
+  // crashing with `undefined.id` — the next pass with the real item
+  // re-keys it correctly. See react-virtuoso issue #532 / #1045.
+  const computeItemKey = useCallback(
+    (index: number, m: ChatMessage | undefined) => m?.id ?? index,
+    [],
+  );
+
+  // Wrap user-supplied onStartReached so we don't double-fire while a
+  // load is already in flight. Virtuoso pauses startReached until
+  // `data` grows, but our consumers pass `onStartReached={loadMore}`
+  // directly — `loadMore` sets `isLoadingMore=true` synchronously, so
+  // we can suppress further calls until that flag drops back to false.
+  const startReachedHandler = useMemo(() => {
+    if (!onStartReached) return undefined;
+    let inFlight = false;
+    return () => {
+      if (inFlight || isLoadingMore) return;
+      inFlight = true;
+      try {
+        onStartReached();
+      } finally {
+        // Release on the next tick — Virtuoso re-fires startReached
+        // only after data length changes, so the inFlight guard is
+        // belt+suspenders against same-frame double calls.
+        queueMicrotask(() => {
+          inFlight = false;
+        });
+      }
+    };
+  }, [onStartReached, isLoadingMore]);
+
+  // Empty path — render renderEmpty instead of the virtualizer to avoid
+  // a blank Virtuoso frame and the cost of mounting it for nothing.
+  if (messages.length === 0) {
+    return (
+      <div
+        role="log"
+        aria-live="polite"
+        aria-atomic="false"
+        className={cn('flex-1 overflow-y-auto', className)}
+      >
+        {renderEmpty?.() ?? null}
+      </div>
+    );
+  }
+
+  if (noVirtualize) {
+    return (
+      <div
+        role="log"
+        aria-live="polite"
+        aria-atomic="false"
+        className={cn('flex-1 overflow-y-auto', className)}
+      >
+        {isLoadingMore ? (
+          <div className="flex justify-center py-2">
+            <Spinner className="size-4 text-muted-foreground" />
+          </div>
+        ) : null}
+        {messages.map((m, i) => (
+          <div key={m.id ?? i}>{itemRenderer(m, i)}</div>
+        ))}
+      </div>
+    );
+  }
 
   return (
-    <div
-      ref={ref}
+    <Virtuoso
+      ref={virtuosoRef}
       role="log"
       aria-live="polite"
       aria-atomic="false"
-      className={cn('flex-1 overflow-y-auto', className)}
-    >
-      <div ref={topSentinelRef} aria-hidden />
-      {isLoadingMore ? (
-        <div className="flex justify-center py-2">
-          <Spinner className="size-4 text-muted-foreground" />
-        </div>
-      ) : null}
-      {messages.length === 0
-        ? renderEmpty?.() ?? null
-        : messages.map((m, i) => itemRenderer(m, i))}
-      <div ref={bottomRef} aria-hidden />
-    </div>
+      className={cn('flex-1', className)}
+      data={messages}
+      computeItemKey={computeItemKey}
+      itemContent={(index, m) => (m ? itemRenderer(m, index) : null)}
+      defaultItemHeight={defaultItemHeight}
+      // Sticky-bottom: keep the viewport anchored to the latest message
+      // unless the user scrolled up. `'smooth'` while streaming would
+      // jank; Virtuoso defaults to `'auto'` which is what we want.
+      followOutput={(isAtBottom) => (isAtBottom ? 'auto' : false)}
+      atBottomStateChange={onAtBottomChange}
+      // Pad the list so a short conversation still hugs the bottom of
+      // the viewport (Telegram / iMessage feel) instead of stacking at
+      // the top.
+      alignToBottom
+      // Top-of-list pagination — fire when the topmost item enters the
+      // viewport. Virtuoso pauses this until `data` grows, so loadMore
+      // implementations don't need their own debounce.
+      startReached={startReachedHandler}
+      // Spinner while older history is loading. Rendering it as the
+      // Header keeps it inside the virtualized scroll, so it doesn't
+      // shift the viewport when it appears/disappears.
+      //
+      // Always pass an object — virtuoso indexes `components[name]`
+      // internally without a null-guard, so passing `undefined` here
+      // crashes with `d[l]` on any render where the empty-defaults
+      // path runs (regression: ui-tools 2.1.369 first ship).
+      components={
+        isLoadingMore
+          ? {
+              Header: () => (
+                <div className="flex justify-center py-2">
+                  <Spinner className="size-4 text-muted-foreground" />
+                </div>
+              ),
+            }
+          : EMPTY_COMPONENTS
+      }
+      // Item height is dynamic; Virtuoso re-measures on resize. We
+      // bias the initial overscan a bit so streaming-token re-layout
+      // doesn't leave gaps before the next measurement lands.
+      increaseViewportBy={{ top: 200, bottom: 400 }}
+    />
   );
 });
 
-function copy(text: string) {
-  if (typeof navigator !== 'undefined' && navigator.clipboard) {
-    void navigator.clipboard.writeText(text);
-  }
-}
+// Stable empty-components reference — passed when `isLoadingMore` is
+// false so virtuoso's `components[name]` lookups never see undefined.
+const EMPTY_COMPONENTS = {} as const;

package/src/tools/Chat/components/index.ts

@@ -1,7 +1,11 @@
 'use client';
 
 export { ChatRoot, type ChatRootProps } from './ChatRoot';
-export { MessageList, type MessageListProps } from './MessageList';
+export {
+  MessageList,
+  type MessageListProps,
+  type MessageListHandle,
+} from './MessageList';
 export { MessageBubble, type MessageBubbleProps } from './MessageBubble';
 export { MessageActions, type MessageActionsProps } from './MessageActions';
 export { Composer, type ComposerProps } from './Composer';

package/src/tools/Chat/context/ChatProvider.tsx

@@ -40,6 +40,12 @@ export interface ChatProviderProps {
   audio?: ChatAudioConfig;
   /** Enable verbose dev logging via consola. Defaults to `isDev`. */
   debug?: boolean;
+  /**
+   * Rewrite outgoing message content before it hits the transport.
+   * History bubble keeps the original; useful for stripping rich-
+   * display chips so the LLM sees plain text. See `useChat`.
+   */
+  onBeforeSend?: (content: string) => string | Promise<string>;
   children?: ReactNode;
 }
 
@@ -51,6 +57,7 @@ export function ChatProvider({
   streaming,
   audio,
   debug,
+  onBeforeSend,
   children,
 }: ChatProviderProps) {
   const audioApi = useChatAudio(audio ?? {});
@@ -80,6 +87,7 @@ export function ChatProvider({
     onMessageEnd,
     onStreamStart,
     onError,
+    onBeforeSend,
   });
   const layout = useChatLayout({ defaultMode: 'embedded' });
 

package/src/tools/Chat/hooks/useChat.ts

@@ -37,6 +37,16 @@ export interface UseChatConfig {
   metadata?: Record<string, unknown>;
   /** Stamped on outgoing user messages as `message.sender`. */
   userPersona?: ChatPersona;
+  /**
+   * Rewrite the outgoing message content right before it hits the
+   * transport — runs after the user bubble is added (so history shows
+   * the original) but before `transport.stream/send`. Sync or async.
+   * Return the original to opt out for that call.
+   *
+   * Use case: strip rich-display chips (e.g. mention links) so the LLM
+   * sees plain text, while the bubble keeps the chip rendering. Plan64.
+   */
+  onBeforeSend?: (content: string) => string | Promise<string>;
   /**
    * Enable verbose dev-mode logging (consola, namespace `chat:*`).
    * Defaults to `isDev` from `@djangocfg/ui-core/lib`. Pass `false` to silence
@@ -439,13 +449,24 @@ export function useChat(config: UseChatConfig): UseChatReturn {
       dispatch({ type: 'MESSAGE_USER_ADD', message: userMsg });
       config.onMessageSent?.(userMsg);
 
+      // History bubble shows the original; transport sees the rewrite.
+      // Use case: strip rich-display chips so the LLM sees plain text.
+      let outbound = content;
+      if (config.onBeforeSend) {
+        try {
+          outbound = await config.onBeforeSend(content);
+        } catch (err) {
+          log.error.error('onBeforeSend threw — falling back to original content', err);
+        }
+      }
+
       if (streaming) {
-        await consumeStream(sessionId, content, attachments);
+        await consumeStream(sessionId, outbound, attachments);
       } else {
-        await consumeBuffered(sessionId, content, attachments);
+        await consumeBuffered(sessionId, outbound, attachments);
       }
     },
-    [streaming, consumeStream, consumeBuffered, config, awaitSession],
+    [streaming, consumeStream, consumeBuffered, config, awaitSession, log],
   );
 
   const cancelStream = useCallback(() => {

package/src/tools/Chat/hooks/useChatComposer.ts

@@ -24,6 +24,16 @@ export interface UseChatComposerOptions {
   submitOn?: 'enter' | 'cmd+enter';
   history?: { enabled?: boolean; size?: number };
   onPasteFiles?: (files: File[]) => void;
+  /**
+   * Persist the current draft to `sessionStorage` under this key. The
+   * draft is loaded once on mount (overrides `initialValue` if non-
+   * empty) and rewritten on every value change. Cleared on `reset()`.
+   *
+   * Pass a per-conversation id to keep separate drafts per chat. Pass
+   * `undefined` (default) to disable persistence — composer behaves
+   * exactly as before. Plan64.
+   */
+  persistKey?: string;
 }
 
 export interface UseChatComposerReturn {
@@ -62,9 +72,37 @@ export function useChatComposer(options: UseChatComposerOptions): UseChatCompose
     submitOn = 'enter',
     history = { enabled: true, size: LIMITS.composerHistorySize },
     onPasteFiles,
+    persistKey,
   } = options;
 
-  const [value, setValueState] = useState(initialValue);
+  // Hydrate draft from sessionStorage on mount when a key is provided.
+  // We read once, lazily — switching `persistKey` mid-life (e.g.
+  // session change) requires a parent remount via React `key`, same
+  // pattern as `<MessageList>`. Avoids accidental cross-session
+  // bleed-through when the parent forgets to remount.
+  const initialFromStorage = (() => {
+    if (!persistKey || typeof window === 'undefined') return initialValue;
+    try {
+      const stored = window.sessionStorage.getItem(`chat:draft:${persistKey}`);
+      return stored && stored.length > 0 ? stored : initialValue;
+    } catch {
+      return initialValue;
+    }
+  })();
+  const [value, setValueState] = useState(initialFromStorage);
+
+  // Persist on every value change. Throwaway swallow keeps quota /
+  // private-mode failures from breaking the composer.
+  useEffect(() => {
+    if (!persistKey || typeof window === 'undefined') return;
+    try {
+      const k = `chat:draft:${persistKey}`;
+      if (value.length > 0) window.sessionStorage.setItem(k, value);
+      else window.sessionStorage.removeItem(k);
+    } catch {
+      /* noop — quota / disabled storage is non-fatal */
+    }
+  }, [value, persistKey]);
   const [attachments, setAttachments] = useState<ChatAttachment[]>([]);
   const [isSubmitting, setIsSubmitting] = useState(false);
   const textareaRef = useRef<HTMLTextAreaElement | null>(null);