@djangocfg/ui-tools 2.1.459 → 2.1.460

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-tools",
-  "version": "2.1.459",
+  "version": "2.1.460",
   "description": "Heavy React tools with lazy loading - for Electron, Vite, CRA, Next.js apps",
   "keywords": [
     "ui-tools",
@@ -334,8 +334,8 @@
     "test:watch": "vitest"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.459",
-    "@djangocfg/ui-core": "^2.1.459",
+    "@djangocfg/i18n": "^2.1.460",
+    "@djangocfg/ui-core": "^2.1.460",
     "consola": "^3.4.2",
     "lodash-es": "^4.18.1",
     "lucide-react": "^0.545.0",
@@ -418,9 +418,9 @@
     "@maplibre/maplibre-gl-geocoder": "^1.7.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.459",
-    "@djangocfg/typescript-config": "^2.1.459",
-    "@djangocfg/ui-core": "^2.1.459",
+    "@djangocfg/i18n": "^2.1.460",
+    "@djangocfg/typescript-config": "^2.1.460",
+    "@djangocfg/ui-core": "^2.1.460",
     "@types/lodash-es": "^4.17.12",
     "@types/mapbox__mapbox-gl-draw": "^1.4.8",
     "@types/node": "^25.2.3",

package/src/tools/chat/composer/Composer.tsx

@@ -425,15 +425,18 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
     [ref],
   );
 
-  // Send, then return focus to the composer. Clicking the Send button
-  // moves focus to that button; after the message goes the caret should
-  // be back in the input so the user can keep typing without reaching for
-  // the mouse (the same UX the stream-end refocus gives on Enter-send —
-  // this covers the button-click and instant/non-streaming paths too).
-  // Resolve the live handle from the registry so it works for both the
-  // built-in <textarea> and the custom TipTap composer. No-op while the
-  // gate is closed (gatedComposer.submit swallows it).
+  // Send, and make sure the caret is in the input. The button itself never
+  // takes focus (ComposerButton preventDefaults mousedown), and the textarea
+  // stays EDITABLE during the stream (type-ahead by design) — so the caret
+  // goes back IMMEDIATELY at send, not after the reply lands. The immediate
+  // call covers the case where focus was somewhere else entirely at click
+  // time; the `.finally` refocus stays as the tail net for the buffered /
+  // error paths (submit resolves at stream end — same edge the provider's
+  // stream-end refocus covers). Resolve the live handle from the registry so
+  // it works for both the built-in <textarea> and the custom TipTap composer.
+  // No-op while the gate is closed (gatedComposer.submit swallows it).
   const handleSend = useCallback(() => {
+    getActiveComposer()?.focus?.();
     void Promise.resolve(gatedComposer.submit()).finally(() => {
       requestAnimationFrame(() => getActiveComposer()?.focus?.());
     });

package/src/tools/chat/composer/ComposerButton.tsx

@@ -41,6 +41,13 @@ export function ComposerButton({ action, size }: ComposerButtonProps) {
     <button
       type="button"
       onClick={action.onClick}
+      // Action-bar buttons never TAKE focus on click (the editor-toolbar
+      // convention): clicking Send/Stop/attach keeps the caret in the
+      // composer, so nothing has to "give focus back" afterwards — the
+      // deterministic half of the send-refocus UX (the stream-end refocus
+      // remains the safety net for focus lost elsewhere). Keyboard focus
+      // (Tab) is untouched — this suppresses only the mousedown default.
+      onMouseDown={(e) => e.preventDefault()}
       disabled={action.disabled}
       aria-label={action.label}
       title={action.label}

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

@@ -62,6 +62,14 @@ const Ctx = createContext<ChatContextValue | null>(null);
 export interface ChatProviderProps {
   transport: ChatTransport;
   config?: ChatConfig;
+  /**
+   * The session to resume on mount. Changing it AFTER mount performs an
+   * in-place session switch (atomic `SESSION_SWITCH` + background history
+   * revalidate) — the modern alternative to remounting the whole tree via
+   * `key={sessionId}`. Pair with a fresh `initialMessages` for the new room
+   * to make the swap paint instantly from the host's cache. The legacy
+   * remount pattern remains fully supported.
+   */
   initialSessionId?: string;
   /**
    * Warm transcript rendered instantly on mount while the resume-path
@@ -226,6 +234,17 @@ export function ChatProvider({
   // chat appears. Pairs with the stream-end focus above.
   useAutoFocusOnMount({ enabled: autoFocusOnMount });
 
+  // An IN-PLACE session switch (initialSessionId change, no remount) deserves
+  // the same treatment: land the caret in the composer when the room changes,
+  // exactly like the legacy remount did via the mount focus above.
+  const prevSessionRef = useRef(chat.sessionId);
+  useEffect(() => {
+    if (prevSessionRef.current === chat.sessionId) return;
+    prevSessionRef.current = chat.sessionId;
+    if (!autoFocusOnMount) return;
+    getActiveComposer()?.focus();
+  }, [chat.sessionId, autoFocusOnMount]);
+
   const value = useMemo<ChatContextValue>(
     () => ({
       ...chat,

package/src/tools/chat/context/__tests__/ChatProvider.streamEndFocus.test.tsx

@@ -0,0 +1,188 @@
+// @vitest-environment jsdom
+//
+// Stream-end + send refocus contract (ChatProvider + composer registry).
+//
+// The full UX has three layers (see Composer.tsx handleSend / ComposerButton):
+//   1. buttons never TAKE focus (mousedown preventDefault) — nothing to give back;
+//   2. handleSend focuses the registered composer immediately at click;
+//   3. ChatProvider's `useStreamEndFocus` refocuses on the streaming → idle edge.
+// This file locks layer 3 — the engine-side edge — plus the focus-on-switch
+// effect, through the SAME registry instance ChatProvider reads
+// (`@djangocfg/ui-tools/composer-registry` — importing the registry by any
+// other path would create a second module instance and test nothing).
+import { act, createElement, useEffect } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+(globalThis as Record<string, unknown>).IS_REACT_ACT_ENVIRONMENT = true;
+
+// jsdom has no matchMedia; ChatProvider's useChatLayout reads it via
+// ui-core's useMediaQuery. A minimal always-false stub is enough.
+if (!window.matchMedia) {
+  window.matchMedia = ((query: string) => ({
+    matches: false,
+    media: query,
+    onchange: null,
+    addEventListener: () => undefined,
+    removeEventListener: () => undefined,
+    addListener: () => undefined,
+    removeListener: () => undefined,
+    dispatchEvent: () => false,
+  })) as typeof window.matchMedia;
+}
+
+import { registerComposer } from '@djangocfg/ui-tools/composer-registry';
+import { ChatProvider, useChatContext } from '../ChatProvider';
+import type { ChatMessage } from '../../types';
+import type { ChatTransport } from '../../types/transport';
+import type { HistoryPage, SessionInfo } from '../../types/session';
+
+function msg(id: string, content: string, role: ChatMessage['role'] = 'user'): ChatMessage {
+  return { id, role, content, createdAt: 1 };
+}
+
+/** Transport whose stream stays open until the test releases it. */
+function gatedStreamTransport(): { transport: ChatTransport; endStream: () => void } {
+  let release!: () => void;
+  const gate = new Promise<void>((r) => {
+    release = r;
+  });
+  const transport: ChatTransport = {
+    async createSession(): Promise<SessionInfo> {
+      return { sessionId: 's1' };
+    },
+    async loadHistory(): Promise<HistoryPage> {
+      return { messages: [], hasMore: false, nextCursor: null };
+    },
+    async *stream() {
+      yield { type: 'chunk' as const, delta: 'hello ' };
+      await gate;
+      yield { type: 'chunk' as const, delta: 'world' };
+    },
+    async send(): Promise<ChatMessage> {
+      return msg('a', 'a', 'assistant');
+    },
+    async closeSession() {
+      /* unused */
+    },
+  };
+  return { transport, endStream: release };
+}
+
+async function frame(): Promise<void> {
+  await new Promise<void>((r) => requestAnimationFrame(() => r()));
+}
+
+describe('ChatProvider — refocus edges', () => {
+  let roots: Root[] = [];
+  beforeEach(() => {
+    roots = [];
+  });
+  afterEach(() => {
+    act(() => roots.forEach((r) => r.unmount()));
+    registerComposer(null);
+  });
+
+  it('focuses the registered composer on the streaming → idle edge', async () => {
+    const focus = vi.fn();
+    registerComposer({ focus });
+
+    const { transport, endStream } = gatedStreamTransport();
+    let send!: (text: string) => Promise<void>;
+    const Grab = () => {
+      const chat = useChatContext();
+      send = chat.sendMessage;
+      return null;
+    };
+    const root = createRoot(document.createElement('div'));
+    roots.push(root);
+    await act(async () => {
+      root.render(
+        createElement(
+          ChatProvider,
+          { transport, initialSessionId: 's1' },
+          createElement(Grab),
+        ),
+      );
+    });
+
+    let turn!: Promise<void>;
+    act(() => {
+      turn = send('hi');
+    });
+    await act(async () => {
+      await Promise.resolve();
+    });
+    focus.mockClear(); // ignore any mount-path focus — this test is the EDGE
+
+    await act(async () => {
+      endStream();
+      await turn;
+    });
+    await act(frame); // the stream-end refocus fires on the next frame
+
+    expect(focus).toHaveBeenCalled();
+  });
+
+  it('autoFocusOnStreamEnd={false} leaves focus alone', async () => {
+    const focus = vi.fn();
+    registerComposer({ focus });
+
+    const { transport, endStream } = gatedStreamTransport();
+    let send!: (text: string) => Promise<void>;
+    const Grab = () => {
+      const chat = useChatContext();
+      send = chat.sendMessage;
+      return null;
+    };
+    const root = createRoot(document.createElement('div'));
+    roots.push(root);
+    await act(async () => {
+      root.render(
+        createElement(
+          ChatProvider,
+          { transport, initialSessionId: 's1', autoFocusOnStreamEnd: false, autoFocusOnMount: false },
+          createElement(Grab),
+        ),
+      );
+    });
+
+    let turn!: Promise<void>;
+    act(() => {
+      turn = send('hi');
+    });
+    focus.mockClear();
+    await act(async () => {
+      endStream();
+      await turn;
+    });
+    await act(frame);
+
+    expect(focus).not.toHaveBeenCalled();
+  });
+
+  it('focuses the composer after an in-place session switch', async () => {
+    const focus = vi.fn();
+    registerComposer({ focus });
+
+    const { transport } = gatedStreamTransport();
+    const Host = ({ sid }: { sid: string }) =>
+      createElement(ChatProvider, { transport, initialSessionId: sid });
+    const root = createRoot(document.createElement('div'));
+    roots.push(root);
+    await act(async () => {
+      root.render(createElement(Host, { sid: 'room-a' }));
+    });
+    focus.mockClear();
+
+    await act(async () => {
+      root.render(createElement(Host, { sid: 'room-b' }));
+    });
+    await act(frame);
+
+    expect(focus).toHaveBeenCalled();
+  });
+});
+
+// Silence unused-import lint for useEffect (kept for parity with sibling tests).
+void useEffect;

package/src/tools/chat/core/__tests__/reducer.sessionSwitch.test.ts

@@ -0,0 +1,151 @@
+// SESSION_SWITCH + the HISTORY_LOAD_DONE stale-page guard
+// (chat-remount-flicker F2) — the pure state-machine half of the in-place
+// session switch. The hook-level integration lives in
+// hooks/__tests__/useChat.sessionSwitch.test.tsx.
+import { describe, expect, it } from 'vitest';
+
+import { initialState, reducer, type ChatState } from '../reducer';
+import type { ChatMessage } from '../../types';
+
+function msg(id: string, content: string, role: ChatMessage['role'] = 'user'): ChatMessage {
+  return { id, role, content, createdAt: 1 };
+}
+
+/** A lived-in room-A state: transcript, stream flag, error banner, cursor. */
+function roomA(): ChatState {
+  return {
+    ...initialState,
+    sessionId: 'room-a',
+    messages: [msg('a1', 'hello'), msg('a2', 'world', 'assistant')],
+    historyLoaded: true,
+    isStreaming: true,
+    hasMore: false,
+    oldestCursor: 'cur-a',
+    error: 'boom',
+    errorTurnId: 'a2',
+  };
+}
+
+describe('reducer — SESSION_SWITCH', () => {
+  it('seeded switch swaps id + transcript atomically (no loading state)', () => {
+    const next = reducer(roomA(), {
+      type: 'SESSION_SWITCH',
+      sessionId: 'room-b',
+      messages: [msg('b1', 'cached b')],
+    });
+    expect(next.sessionId).toBe('room-b');
+    expect(next.messages.map((m) => m.id)).toEqual(['b1']);
+    expect(next.historyLoaded).toBe(true);
+    expect(next.isLoading).toBe(false);
+  });
+
+  it('unseeded switch enters the loading state with an empty feed', () => {
+    const next = reducer(roomA(), { type: 'SESSION_SWITCH', sessionId: 'room-b' });
+    expect(next.sessionId).toBe('room-b');
+    expect(next.messages).toEqual([]);
+    expect(next.historyLoaded).toBe(false);
+    expect(next.isLoading).toBe(true);
+  });
+
+  it('resets the OLD room\'s stream / error / paging state wholesale', () => {
+    const next = reducer(roomA(), {
+      type: 'SESSION_SWITCH',
+      sessionId: 'room-b',
+      messages: [msg('b1', 'cached b')],
+    });
+    expect(next.isStreaming).toBe(false);
+    expect(next.error).toBeNull();
+    expect(next.errorTurnId).toBeNull();
+    expect(next.hasMore).toBe(true);
+    expect(next.oldestCursor).toBeNull();
+  });
+});
+
+describe('reducer — HISTORY_LOAD_DONE stale-page guard', () => {
+  it('drops a page tagged for a session the state already left', () => {
+    const state = reducer(roomA(), {
+      type: 'SESSION_SWITCH',
+      sessionId: 'room-b',
+      messages: [msg('b1', 'cached b')],
+    });
+    const after = reducer(state, {
+      type: 'HISTORY_LOAD_DONE',
+      sessionId: 'room-a', // slow read for the abandoned room
+      messages: [msg('a9', 'stale a page')],
+      hasMore: false,
+      cursor: null,
+    });
+    expect(after).toBe(state); // identical reference — nothing committed
+  });
+
+  it('commits a page tagged for the CURRENT session', () => {
+    const state = reducer(roomA(), { type: 'SESSION_SWITCH', sessionId: 'room-b' });
+    const after = reducer(state, {
+      type: 'HISTORY_LOAD_DONE',
+      sessionId: 'room-b',
+      messages: [msg('b1', 'fresh b page')],
+      hasMore: false,
+      cursor: null,
+    });
+    expect(after.messages.map((m) => m.id)).toEqual(['b1']);
+    expect(after.historyLoaded).toBe(true);
+    expect(after.isLoading).toBe(false);
+  });
+
+  it('commits an UNTAGGED page unconditionally (legacy dispatch sites)', () => {
+    const after = reducer(roomA(), {
+      type: 'HISTORY_LOAD_DONE',
+      messages: [msg('a3', 'server page')],
+      hasMore: true,
+      cursor: 'cur-2',
+    });
+    expect(after.messages.map((m) => m.id)).toEqual(['a3']);
+    expect(after.hasMore).toBe(true);
+    expect(after.oldestCursor).toBe('cur-2');
+  });
+});
+
+describe('reducer — MESSAGE_INJECT { afterId } (transcript-order splice)', () => {
+  it('inserts right after the anchor message', () => {
+    const state: ChatState = {
+      ...initialState,
+      sessionId: 's',
+      messages: [msg('srv-1', 'old'), msg('u-1', 'my new question')],
+    };
+    const next = reducer(state, {
+      type: 'MESSAGE_INJECT',
+      message: msg('srv-2', 'scheduled reminder', 'assistant'),
+      position: { afterId: 'srv-1' },
+    });
+    expect(next.messages.map((m) => m.id)).toEqual(['srv-1', 'srv-2', 'u-1']);
+  });
+
+  it('falls back to append when the anchor is not rendered', () => {
+    const state: ChatState = {
+      ...initialState,
+      sessionId: 's',
+      messages: [msg('u-1', 'hello')],
+    };
+    const next = reducer(state, {
+      type: 'MESSAGE_INJECT',
+      message: msg('srv-9', 'late row', 'assistant'),
+      position: { afterId: 'gone' },
+    });
+    expect(next.messages.map((m) => m.id)).toEqual(['u-1', 'srv-9']);
+  });
+
+  it('still dedupes by id regardless of position', () => {
+    const state: ChatState = {
+      ...initialState,
+      sessionId: 's',
+      messages: [msg('srv-1', 'old')],
+    };
+    const next = reducer(state, {
+      type: 'MESSAGE_INJECT',
+      message: msg('srv-1', 'old (edited)'),
+      position: { afterId: 'srv-1' },
+    });
+    expect(next.messages).toHaveLength(1);
+    expect(next.messages[0].content).toBe('old (edited)');
+  });
+});

package/src/tools/chat/core/index.ts

@@ -1,4 +1,10 @@
-export { reducer, initialState, type ChatState, type ChatAction } from './reducer';
+export {
+  reducer,
+  initialState,
+  type ChatState,
+  type ChatAction,
+  type MessageInjectPosition,
+} from './reducer';
 export { createId } from './ids';
 export { createTokenBuffer, type TokenBuffer } from './markdown';
 export { resolvePersona, deriveInitials } from './persona';

package/src/tools/chat/core/reducer.ts

@@ -43,6 +43,15 @@ export interface ChatState {
   errorTurnId: string | null;
 }
 
+/**
+ * Where an injected message lands: `append`/`prepend`, or `{ afterId }` —
+ * insert right after the message with that id (falls back to append when the
+ * anchor isn't rendered). The anchored form lets a history reconcile place
+ * server rows in TRANSCRIPT order instead of tacking them onto the end after
+ * the client's own newer live turn (the "scheduled message appears last" bug).
+ */
+export type MessageInjectPosition = 'append' | 'prepend' | { afterId: string };
+
 export const initialState: ChatState = {
   sessionId: null,
   messages: [],
@@ -70,6 +79,22 @@ export type ChatAction =
       messages: ChatMessage[];
       hasMore: boolean;
       cursor: string | null;
+      /**
+       * The session this page belongs to. When present and different from
+       * `state.sessionId`, the commit is DROPPED — a slow history read for a
+       * session the user already switched away from must not clobber the
+       * current transcript. Omitted by legacy dispatch sites (applies
+       * unconditionally, as before).
+       */
+      sessionId?: string;
+    }
+  | {
+      type: 'SESSION_SWITCH';
+      sessionId: string;
+      /** Warm transcript for the NEW session (host cache). When present the
+       *  feed swaps atomically (`historyLoaded` true, no spinner); when
+       *  absent the feed enters the loading state until HISTORY_LOAD_DONE. */
+      messages?: ChatMessage[];
     }
   | { type: 'HISTORY_MORE_START' }
   | {
@@ -107,7 +132,7 @@ export type ChatAction =
   | { type: 'STREAM_RESUME_EXISTING' }
   | { type: 'MESSAGE_EDIT'; id: string; content: string }
   | { type: 'MESSAGE_DELETE'; id: string }
-  | { type: 'MESSAGE_INJECT'; message: ChatMessage; position?: 'append' | 'prepend' }
+  | { type: 'MESSAGE_INJECT'; message: ChatMessage; position?: MessageInjectPosition }
   | { type: 'MESSAGE_PATCH'; id: string; patch: Partial<ChatMessage> }
   | { type: 'MESSAGES_CLEAR' }
   | { type: 'ERROR_SET'; error: string | null }
@@ -119,6 +144,23 @@ export type ChatAction =
       status?: ChatAttachment['status'];
     };
 
+/**
+ * Where a MESSAGE_INJECT lands: `'prepend'` → 0, `{ afterId }` → right after
+ * the anchor (append when the anchor isn't rendered — deleted or never
+ * loaded), `'append'`/absent → the end.
+ */
+function insertIndexFor(
+  position: MessageInjectPosition | undefined,
+  messages: ChatMessage[],
+): number {
+  if (position === 'prepend') return 0;
+  if (typeof position === 'object') {
+    const idx = messages.findIndex((m) => m.id === position.afterId);
+    return idx === -1 ? messages.length : idx + 1;
+  }
+  return messages.length;
+}
+
 function updateLastStreaming(
   messages: ChatMessage[],
   patch: (m: ChatMessage) => ChatMessage,
@@ -171,6 +213,10 @@ export function reducer(state: ChatState, action: ChatAction): ChatState {
       return { ...state, isLoading: true, error: null };
 
     case 'HISTORY_LOAD_DONE':
+      // Stale-page guard: a read that raced a session switch commits nothing.
+      if (action.sessionId !== undefined && action.sessionId !== state.sessionId) {
+        return state;
+      }
       return {
         ...state,
         isLoading: false,
@@ -180,6 +226,20 @@ export function reducer(state: ChatState, action: ChatAction): ChatState {
         oldestCursor: action.cursor,
       };
 
+    case 'SESSION_SWITCH':
+      // Atomic transition to another session — the in-place alternative to the
+      // legacy `key={sessionId}` full remount. One dispatch swaps identity and
+      // transcript together, so the feed never renders a half-state (old
+      // messages under a new id, or a blank frame between "clear" and "set").
+      // Stream/tool state belongs to the OLD session and resets wholesale.
+      return {
+        ...initialState,
+        sessionId: action.sessionId,
+        messages: action.messages ?? [],
+        historyLoaded: action.messages !== undefined,
+        isLoading: action.messages === undefined,
+      };
+
     case 'HISTORY_MORE_START':
       return { ...state, isLoadingMore: true };
 
@@ -411,10 +471,13 @@ export function reducer(state: ChatState, action: ChatAction): ChatState {
         };
         return { ...state, messages };
       }
-      const next =
-        action.position === 'prepend'
-          ? [action.message, ...state.messages]
-          : [...state.messages, action.message];
+      // ONE insert path for every position: resolve the index, splice.
+      const at = insertIndexFor(action.position, state.messages);
+      const next = [
+        ...state.messages.slice(0, at),
+        action.message,
+        ...state.messages.slice(at),
+      ];
       return { ...state, messages: next };
     }
 

package/src/tools/chat/hooks/__tests__/useChat.newSession.test.tsx

@@ -0,0 +1,123 @@
+// @vitest-environment jsdom
+//
+// newSession() atomicity (chat-remount-flicker F2).
+//
+// The legacy sequence was MESSAGES_CLEAR → await createSession → SESSION_SET:
+// the feed rendered EMPTY for the whole round-trip, and stayed empty forever
+// when createSession failed. The contract now:
+//   1. The previous conversation stays readable until the new session lands.
+//   2. SESSION_SET swaps id + transcript in one commit.
+//   3. On failure the old transcript survives alongside the error banner.
+import { act, createElement } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+(globalThis as Record<string, unknown>).IS_REACT_ACT_ENVIRONMENT = true;
+
+import { useChat, type UseChatReturn } from '../useChat';
+import type { ChatMessage } from '../../types';
+import type { ChatTransport } from '../../types/transport';
+import type { HistoryPage, SessionInfo } from '../../types/session';
+
+function msg(id: string, content: string, role: ChatMessage['role'] = 'user'): ChatMessage {
+  return { id, role, content, createdAt: 1 };
+}
+
+function makeTransport(opts: {
+  createGate?: Promise<void>;
+  failCreate?: boolean;
+}): ChatTransport {
+  return {
+    async createSession(): Promise<SessionInfo> {
+      if (opts.createGate) await opts.createGate;
+      if (opts.failCreate) throw new Error('relay unreachable');
+      return { sessionId: 'fresh-room', messages: [] };
+    },
+    async loadHistory(): Promise<HistoryPage> {
+      return {
+        messages: [msg('h1', 'old history')],
+        hasMore: false,
+        nextCursor: null,
+      };
+    },
+    async *stream() {
+      /* unused */
+    },
+    async send(): Promise<ChatMessage> {
+      return msg('x', 'x', 'assistant');
+    },
+    async closeSession() {
+      /* unused */
+    },
+  };
+}
+
+function mountChat(roots: Root[], transport: ChatTransport): () => UseChatReturn {
+  let latest!: UseChatReturn;
+  const root = createRoot(document.createElement('div'));
+  roots.push(root);
+  act(() => {
+    root.render(
+      createElement(function W() {
+        latest = useChat({ transport, initialSessionId: 'room-old' });
+        return null;
+      }),
+    );
+  });
+  return () => latest;
+}
+
+describe('useChat — newSession atomicity', () => {
+  let roots: Root[] = [];
+  beforeEach(() => {
+    roots = [];
+  });
+  afterEach(() => {
+    act(() => roots.forEach((r) => r.unmount()));
+  });
+
+  it('keeps the old transcript readable while createSession is in flight', async () => {
+    let release!: () => void;
+    const gate = new Promise<void>((r) => {
+      release = r;
+    });
+    const chat = mountChat(roots, makeTransport({ createGate: gate }));
+    await act(async () => {
+      await Promise.resolve();
+    });
+    expect(chat().messages.map((m) => m.content)).toEqual(['old history']);
+
+    let done!: Promise<void>;
+    act(() => {
+      done = chat().newSession();
+    });
+    await act(async () => {
+      await Promise.resolve();
+    });
+    // Round-trip in flight — the old conversation is STILL on screen.
+    expect(chat().messages.map((m) => m.content)).toEqual(['old history']);
+
+    await act(async () => {
+      release();
+      await done;
+    });
+    // Atomic swap: new id, new (empty) transcript, load settled.
+    expect(chat().sessionId).toBe('fresh-room');
+    expect(chat().messages).toEqual([]);
+    expect(chat().historyLoaded).toBe(true);
+  });
+
+  it('a failed createSession keeps the old transcript and raises the banner', async () => {
+    const chat = mountChat(roots, makeTransport({ failCreate: true }));
+    await act(async () => {
+      await Promise.resolve();
+    });
+
+    await act(async () => {
+      await chat().newSession();
+    });
+    expect(chat().messages.map((m) => m.content)).toEqual(['old history']);
+    expect(chat().sessionId).toBe('room-old');
+    expect(chat().error).toBe('relay unreachable');
+  });
+});

package/src/tools/chat/hooks/__tests__/useChat.sessionSwitch.test.tsx

@@ -0,0 +1,275 @@
+// @vitest-environment jsdom
+//
+// In-place session switch (chat-remount-flicker F2).
+//
+// Contract under test (see the switch effect in useChat):
+//   1. Changing `initialSessionId` after mount dispatches one atomic
+//      SESSION_SWITCH — id + transcript swap together; with a warm
+//      `initialMessages` seed the feed never renders empty.
+//   2. The background history read commits only for the session the user is
+//      still on — a slow page for an abandoned session is dropped
+//      (sessionId-guarded HISTORY_LOAD_DONE).
+//   3. `sendMessage` racing a switch waits for the new session's page, so the
+//      optimistic bubble can't be replaced by the arriving history.
+import { act, createElement, useState } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+(globalThis as Record<string, unknown>).IS_REACT_ACT_ENVIRONMENT = true;
+
+import { useChat, type UseChatReturn } from '../useChat';
+import type { ChatMessage } from '../../types';
+import type { ChatTransport } from '../../types/transport';
+import type { HistoryPage, SessionInfo } from '../../types/session';
+
+function msg(id: string, content: string, role: ChatMessage['role'] = 'user'): ChatMessage {
+  return { id, role, content, createdAt: 1 };
+}
+
+/** Transport whose per-session history resolves when the test releases it. */
+function gatedTransport(pages: Record<string, HistoryPage>): {
+  transport: ChatTransport;
+  release: (sessionId: string) => void;
+} {
+  const gates = new Map<string, { promise: Promise<void>; release: () => void }>();
+  const gateFor = (sessionId: string) => {
+    let g = gates.get(sessionId);
+    if (!g) {
+      let release!: () => void;
+      const promise = new Promise<void>((r) => {
+        release = r;
+      });
+      g = { promise, release };
+      gates.set(sessionId, g);
+    }
+    return g;
+  };
+  const transport: ChatTransport = {
+    async createSession(): Promise<SessionInfo> {
+      return { sessionId: 'created' };
+    },
+    async loadHistory(sessionId: string): Promise<HistoryPage> {
+      await gateFor(sessionId).promise;
+      return pages[sessionId] ?? { messages: [], hasMore: false, nextCursor: null };
+    },
+    async *stream() {
+      /* replies are irrelevant here */
+    },
+    async send(): Promise<ChatMessage> {
+      return msg('x', 'x', 'assistant');
+    },
+    async closeSession() {
+      /* unused */
+    },
+  };
+  return { transport, release: (id) => gateFor(id).release() };
+}
+
+interface Harness {
+  chat: () => UseChatReturn;
+  setSession: (id: string, seed?: readonly ChatMessage[]) => void;
+}
+
+function mount(
+  roots: Root[],
+  transport: ChatTransport,
+  initial: { id: string; seed?: readonly ChatMessage[] },
+): Harness {
+  let latest!: UseChatReturn;
+  let set!: (v: { id: string; seed?: readonly ChatMessage[] }) => void;
+  const root = createRoot(document.createElement('div'));
+  roots.push(root);
+  act(() => {
+    root.render(
+      createElement(function W() {
+        const [session, setSession] = useState(initial);
+        set = setSession;
+        latest = useChat({
+          transport,
+          initialSessionId: session.id,
+          initialMessages: session.seed,
+        });
+        return null;
+      }),
+    );
+  });
+  return {
+    chat: () => latest,
+    setSession: (id, seed) => act(() => set({ id, seed })),
+  };
+}
+
+describe('useChat — in-place session switch', () => {
+  let roots: Root[] = [];
+  beforeEach(() => {
+    roots = [];
+  });
+  afterEach(() => {
+    act(() => roots.forEach((r) => r.unmount()));
+  });
+
+  it('switches atomically with a warm seed — never renders an empty frame', async () => {
+    const { transport, release } = gatedTransport({
+      'room-a': { messages: [msg('a1', 'A history')], hasMore: false, nextCursor: null },
+      'room-b': { messages: [msg('b1', 'B history')], hasMore: false, nextCursor: null },
+    });
+    const h = mount(roots, transport, {
+      id: 'room-a',
+      seed: [msg('a1', 'A history')],
+    });
+    expect(h.chat().messages.map((m) => m.content)).toEqual(['A history']);
+
+    h.setSession('room-b', [msg('b1', 'B cached')]);
+    // Seeded swap: new id + cached transcript in the same commit.
+    expect(h.chat().sessionId).toBe('room-b');
+    expect(h.chat().historyLoaded).toBe(true);
+    expect(h.chat().messages.map((m) => m.content)).toEqual(['B cached']);
+
+    // Server page replaces the seed once it lands.
+    await act(async () => {
+      release('room-b');
+      await Promise.resolve();
+    });
+    expect(h.chat().messages.map((m) => m.content)).toEqual(['B history']);
+  });
+
+  it('switches without a seed into the loading state, then commits the page', async () => {
+    const { transport, release } = gatedTransport({
+      'room-a': { messages: [], hasMore: false, nextCursor: null },
+      'room-b': { messages: [msg('b1', 'B history')], hasMore: false, nextCursor: null },
+    });
+    const h = mount(roots, transport, { id: 'room-a', seed: [msg('a1', 'A seed')] });
+
+    h.setSession('room-b');
+    expect(h.chat().sessionId).toBe('room-b');
+    expect(h.chat().historyLoaded).toBe(false);
+    expect(h.chat().isLoading).toBe(true);
+
+    await act(async () => {
+      release('room-b');
+      await Promise.resolve();
+    });
+    expect(h.chat().historyLoaded).toBe(true);
+    expect(h.chat().messages.map((m) => m.content)).toEqual(['B history']);
+  });
+
+  it('drops a slow page for a session the user already left (A→B→A)', async () => {
+    const { transport, release } = gatedTransport({
+      'room-a': { messages: [msg('a1', 'A history')], hasMore: false, nextCursor: null },
+      'room-b': { messages: [msg('b1', 'B history')], hasMore: false, nextCursor: null },
+    });
+    const h = mount(roots, transport, { id: 'room-a', seed: [msg('a1', 'A seed')] });
+
+    h.setSession('room-b'); // B's read is gated — still in flight
+    h.setSession('room-a', [msg('a1', 'A cached')]); // back before B landed
+    expect(h.chat().sessionId).toBe('room-a');
+
+    // B's page finally arrives — it must NOT clobber room-a's transcript.
+    await act(async () => {
+      release('room-b');
+      await Promise.resolve();
+    });
+    expect(h.chat().sessionId).toBe('room-a');
+    expect(h.chat().messages.map((m) => m.content)).toEqual(['A cached']);
+
+    await act(async () => {
+      release('room-a');
+      await Promise.resolve();
+    });
+    expect(h.chat().messages.map((m) => m.content)).toEqual(['A history']);
+  });
+
+  it('switching mid-stream aborts the old turn and leaves the new room clean', async () => {
+    // A stream that emits one chunk, then hangs until aborted.
+    let started!: () => void;
+    const streamStarted = new Promise<void>((r) => {
+      started = r;
+    });
+    const transport: ChatTransport = {
+      async createSession(): Promise<SessionInfo> {
+        return { sessionId: 'created' };
+      },
+      async loadHistory(sessionId: string): Promise<HistoryPage> {
+        return sessionId === 'room-b'
+          ? { messages: [msg('b1', 'B history')], hasMore: false, nextCursor: null }
+          : { messages: [], hasMore: false, nextCursor: null };
+      },
+      async *stream(_s: string, _c: string, opts: { signal?: AbortSignal }) {
+        yield { type: 'chunk' as const, delta: 'partial…' };
+        started();
+        // Hang until the switch aborts us.
+        await new Promise<void>((resolve) => {
+          opts.signal?.addEventListener('abort', () => resolve(), { once: true });
+        });
+        if (opts.signal?.aborted) return;
+      },
+      async send(): Promise<ChatMessage> {
+        return msg('x', 'x', 'assistant');
+      },
+      async closeSession() {
+        /* unused */
+      },
+    };
+
+    const h = mount(roots, transport, { id: 'room-a', seed: [msg('a1', 'A seed')] });
+    await act(async () => {
+      await Promise.resolve();
+    });
+
+    let send!: Promise<void>;
+    act(() => {
+      send = h.chat().sendMessage('trigger');
+    });
+    await act(async () => {
+      await streamStarted;
+    });
+    expect(h.chat().isStreaming).toBe(true);
+
+    // Switch away while the assistant is mid-stream.
+    h.setSession('room-b', [msg('b1', 'B cached')]);
+    await act(async () => {
+      await send;
+      await Promise.resolve();
+    });
+
+    const c = h.chat();
+    expect(c.sessionId).toBe('room-b');
+    expect(c.isStreaming).toBe(false);
+    // Nothing from room-a's aborted turn bleeds into room-b's feed.
+    expect(c.messages.some((m) => m.content.includes('partial'))).toBe(false);
+    expect(c.messages.some((m) => m.content === 'trigger')).toBe(false);
+  });
+
+  it('a send racing the switch waits for the page — the optimistic bubble survives', async () => {
+    const { transport, release } = gatedTransport({
+      'room-a': { messages: [], hasMore: false, nextCursor: null },
+      'room-b': { messages: [msg('b1', 'B history')], hasMore: false, nextCursor: null },
+    });
+    const h = mount(roots, transport, { id: 'room-a', seed: [msg('a1', 'A seed')] });
+
+    h.setSession('room-b');
+    // Send while the switch's history read is still gated.
+    let sendDone = false;
+    let send!: Promise<void>;
+    act(() => {
+      send = h.chat().sendMessage('hi from the race').then(() => {
+        sendDone = true;
+      });
+    });
+    await act(async () => {
+      await Promise.resolve();
+    });
+    // Blocked on the switch — no optimistic bubble yet, nothing to clobber.
+    expect(sendDone).toBe(false);
+    expect(h.chat().messages.some((m) => m.content === 'hi from the race')).toBe(false);
+
+    await act(async () => {
+      release('room-b');
+      await send;
+    });
+    const contents = h.chat().messages.map((m) => m.content);
+    // History first, then the user's message — nothing lost.
+    expect(contents[0]).toBe('B history');
+    expect(contents).toContain('hi from the race');
+  });
+});

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

@@ -16,6 +16,7 @@ import {
   initialState,
   reducer,
   type ChatAction,
+  type MessageInjectPosition,
 } from '../core/reducer';
 import { createId } from '../core/ids';
 import { getChatLogger } from '../core/logger';
@@ -95,9 +96,11 @@ export interface UseChatReturn extends ChatState {
   /**
    * Inject a complete message from outside (push notification, admin
    * takeover, system notice). De-duped by id. Position defaults to
-   * `append` — pass `prepend` for retroactive inserts.
+   * `append`; pass `prepend` for retroactive inserts or `{ afterId }` to
+   * splice into transcript order (e.g. a history reconcile placing server
+   * rows before the client's own newer live turn).
    */
-  injectMessage: (message: ChatMessage, position?: 'append' | 'prepend') => void;
+  injectMessage: (message: ChatMessage, position?: MessageInjectPosition) => void;
   /**
    * Patch fields of an existing message in place (e.g. live-edit the
    * admin's last reply, mark a message as resolved). No-op if the id
@@ -118,7 +121,15 @@ export function useChat(config: UseChatConfig): UseChatReturn {
   // bootstrap finished without producing one — e.g. autoCreateSession=false).
   // Action methods (sendMessage, regenerate, …) await this so users who type
   // before the first network round-trip resolves don't hit "No active session".
+  // An in-place session SWITCH re-points this at the switch promise so the
+  // same await gate covers both transitions.
   const bootstrapRef = useRef<Promise<string | null> | null>(null);
+  // In-place session-switch machinery (see the switch effect below). `seq`
+  // invalidates a superseded switch; `switching` keeps `awaitSession` blocking
+  // until the new session's history page has committed.
+  const sessionPropRef = useRef(config.initialSessionId);
+  const switchSeqRef = useRef(0);
+  const switchingRef = useRef(false);
 
   const { transport, autoCreateSession = true, streaming = true, pageSize = LIMITS.pageSize } =
     config;
@@ -263,10 +274,78 @@ export function useChat(config: UseChatConfig): UseChatReturn {
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
+  // Session SWITCH as a state transition (no remount needed). The mount
+  // bootstrap above reads `initialSessionId` once; historically a later change
+  // was ignored and hosts remounted the whole tree via `key={sessionId}` —
+  // a contract that turns ANY key-feeding state churn into a full feed wipe.
+  // A post-mount change of `initialSessionId` now switches IN PLACE: one
+  // atomic SESSION_SWITCH (seeded from the CURRENT `initialMessages` when the
+  // host holds a warm cache for the new room), then a background history read
+  // whose commit is sessionId-guarded in the reducer, so a read that raced a
+  // further switch clobbers nothing. The legacy remount pattern keeps working
+  // unchanged — a remounted engine never observes a prop change.
+  useEffect(() => {
+    const next = config.initialSessionId;
+    if (next === sessionPropRef.current) return;
+    sessionPropRef.current = next;
+    // A cleared prop hands session lifecycle back to the host (create path) —
+    // keep the current transcript rather than tearing it down.
+    if (!next || next === stateRef.current.sessionId) return;
+
+    const seq = ++switchSeqRef.current;
+    switchingRef.current = true;
+    abortRef.current?.abort();
+    const seed =
+      config.initialMessages !== undefined && config.initialMessages.length > 0
+        ? [...config.initialMessages]
+        : undefined;
+    dispatch({ type: 'SESSION_SWITCH', sessionId: next, messages: seed });
+    log.lifecycle.info('sessionSwitch', { to: next, seeded: seed !== undefined });
+
+    const run = async (): Promise<string | null> => {
+      try {
+        const page = await transport.loadHistory(next, null, pageSize);
+        dispatch({
+          type: 'HISTORY_LOAD_DONE',
+          sessionId: next,
+          messages: page.messages,
+          hasMore: page.hasMore,
+          cursor: page.nextCursor,
+        });
+        log.lifecycle.success('sessionSwitch loaded', {
+          sessionId: next,
+          messages: page.messages.length,
+        });
+        return next;
+      } catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        // A superseded switch reports nothing — the newer one owns the UI.
+        if (switchSeqRef.current === seq) {
+          lastErrorRef.current = e;
+          dispatch({ type: 'ERROR_SET', error: e.message });
+          config.onError?.(e);
+          log.error.error('sessionSwitch failed', { sessionId: next, message: e.message });
+        }
+        return next;
+      } finally {
+        if (switchSeqRef.current === seq) switchingRef.current = false;
+      }
+    };
+    bootstrapRef.current = run();
+    // Only the id is the trigger; seed/transport/pageSize are read as-of the
+    // switch moment on purpose.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [config.initialSessionId]);
+
   /** Wait for the initial session bootstrap to settle, then return whatever
-   * sessionId is now in state. Safe to call multiple times. */
+   * sessionId is now in state. Safe to call multiple times. During an
+   * in-place session switch the id is already in state while the transcript
+   * is still loading — block until the page committed, so a racing send's
+   * optimistic bubble can't be replaced by the arriving history. */
   const awaitSession = useCallback(async (): Promise<string | null> => {
-    if (stateRef.current.sessionId) return stateRef.current.sessionId;
+    if (!switchingRef.current && stateRef.current.sessionId) {
+      return stateRef.current.sessionId;
+    }
     if (bootstrapRef.current) {
       const id = await bootstrapRef.current;
       if (id) return id;
@@ -653,7 +732,7 @@ export function useChat(config: UseChatConfig): UseChatReturn {
   }, []);
 
   const injectMessage = useCallback(
-    (message: ChatMessage, position?: 'append' | 'prepend') => {
+    (message: ChatMessage, position?: MessageInjectPosition) => {
       dispatch({ type: 'MESSAGE_INJECT', message, position });
     },
     [],
@@ -707,7 +786,10 @@ export function useChat(config: UseChatConfig): UseChatReturn {
         /* ignore */
       }
     }
-    dispatch({ type: 'MESSAGES_CLEAR' });
+    // NO eager MESSAGES_CLEAR here: the old clear→await→set sequence blanked
+    // the feed for the whole createSession round-trip (and left it blank
+    // forever on failure). SESSION_SET below swaps id + transcript atomically;
+    // until it lands the previous conversation stays readable.
     try {
       const info = await transport.createSession({ metadata: config.metadata });
       dispatch({

package/src/tools/chat/public.ts

@@ -85,6 +85,7 @@ export {
   deriveInitials,
   type ChatState,
   type ChatAction,
+  type MessageInjectPosition,
   type TokenBuffer,
 } from './core';