@artooi/ag-ui-web-component 0.8.1 → 0.10.0

package/src/core/ag_ui_chat.ts

@@ -28,9 +28,11 @@ import { renderMarkdown } from "../ui/render_markdown.js";
 import { wrapWords } from "../ui/reveal_words.js";
 import { SkillsMenu } from "../ui/skills_menu.js";
 import { STYLES } from "../ui/styles.js";
+import { ThoughtsBlock } from "../ui/thoughts_block.js";
 import { ThreadDrawer } from "../ui/thread_drawer.js";
 import { ToolCallCard, type ToolDisplayMode } from "../ui/tool_call_card.js";
 import { DEFAULT_UI_STRINGS, mergeUiStrings, type UiStrings } from "../ui/ui_strings.js";
+import { VoiceInput } from "../ui/voice_input.js";
 import {
   AgUiClient,
   type AgUiClientHandlers,
@@ -45,6 +47,7 @@ import {
 } from "./conversation_store.js";
 import { type AgentFactory, createHttpAgent } from "./create_http_agent.js";
 import { RemoteConversationStore } from "./remote_conversation_store.js";
+import { type TranscribeHandler, transcribeAudio } from "./transcribe_audio.js";
 import { type UploadHandler, uploadAttachment } from "./upload_attachment.js";
 
 /** The role a rendered chat message takes. */
@@ -65,6 +68,9 @@ export interface ToggleDetail {
 /** Per-tab persistence key for the collapsed state (survives MPA reloads). */
 const COLLAPSED_KEY = "ag-ui-chat:collapsed";
 
+/** Per-tab persistence key for the built-in theme toggle. */
+const THEME_KEY = "ag-ui-chat:theme";
+
 /**
  * `<ag-ui-chat>` — a framework-free chat sidebar Web Component over AG-UI.
  *
@@ -169,6 +175,16 @@ export class AgUiChat extends HTMLElement {
    */
   uploadHandler: UploadHandler | null = null;
 
+  /**
+   * How recorded voice clips are transcribed. `null` (default) POSTs the clip
+   * to `data-transcribe-url` (django-ag-ui's `TranscribeView`). Set a custom
+   * {@link TranscribeHandler} — `(audio: Blob) => Promise<string>` — to swap the
+   * transport (a different STT endpoint, a browser Web Speech adapter) without
+   * touching the mic button. When set, the 🎤 affordance appears even with no
+   * `data-transcribe-url`.
+   */
+  transcribeHandler: TranscribeHandler | null = null;
+
   /**
    * Builds the tool result a navigating tool resumes with after the page
    * reloads. Defaults to the landed URL; a host (e.g. the admin package) can
@@ -243,12 +259,18 @@ export class AgUiChat extends HTMLElement {
   readonly #attachButton: HTMLButtonElement;
   readonly #fileInput: HTMLInputElement;
   readonly #attachSlot: HTMLDivElement;
+  /** Optional built-in header theme toggle; shown only with `data-theme-toggle`. */
+  readonly #themeToggle: HTMLButtonElement;
   /** The collapsed-sidebar rail (an expand affordance; shown only for `placement="sidebar"`). */
   readonly #rail: HTMLButtonElement;
   /** Empty-state region at the top of the message list; hidden once anything renders. */
   readonly #emptyWrap: HTMLDivElement;
   /** Upload tray; created on connect only when `data-attachments-url` is set. */
   #attachTray: AttachmentTray | null = null;
+  /** Mic button mount point (input row); the control mounts on connect when enabled. */
+  readonly #voiceSlot: HTMLSpanElement;
+  /** Voice-input control; created on connect when transcription is available. */
+  #voice: VoiceInput | null = null;
   /** Refs attached to the message currently being sent (the context manifest). */
   #runAttachments: readonly AttachmentRef[] = [];
 
@@ -266,14 +288,25 @@ export class AgUiChat extends HTMLElement {
   // it; ≤1 ⇒ it arrived at once and the word reveal is appropriate.
   #streamDeltas = 0;
   #pending: HTMLDivElement | null = null;
-  // The current assistant turn's grouping container (WELL-1). One `.answer`
+  // The current assistant turn's grouping container. One `.answer`
   // wraps everything a single answer produces — streamed text, tool cards, the
   // pending indicator — so it can be boxed as one "well" by CSS. Opened on the
   // turn's first run start, closed at settle, so it spans the whole multi-round
   // frontend-tool loop (which is several AG-UI runs), not one run. `null`
   // between turns; user bubbles never enter it.
   #currentGroup: HTMLDivElement | null = null;
+  // The current turn's streamed-reasoning region, shown at the top of
+  // the answer group while a reasoning model thinks and collapsed once the
+  // answer's first text token arrives. `null` outside a reasoning turn.
+  #thoughts: ThoughtsBlock | null = null;
   #threadId = "";
+  // Per-instance suffix for the origin-scoped storage keys (collapsed / theme /
+  // active thread), so two instances on one origin don't clobber each other.
+  // Empty ⇒ the pre-namespacing global keys (back-compat). Resolved on connect.
+  #storageNs = "";
+  // Bumped on every #rehydrate; a replay whose generation is stale (a newer
+  // thread switch started while it awaited a slow store) drops its result.
+  #rehydrateGeneration = 0;
   #initialMessages: readonly Message[] = [];
   // Skill catalog by source; merged backend → embed → client (later wins).
   #backendSkills: readonly Skill[] = [];
@@ -292,6 +325,8 @@ export class AgUiChat extends HTMLElement {
     this.#attachButton = document.createElement("button");
     this.#fileInput = document.createElement("input");
     this.#attachSlot = document.createElement("div");
+    this.#voiceSlot = document.createElement("span");
+    this.#themeToggle = document.createElement("button");
     this.#rail = document.createElement("button");
     this.#emptyWrap = document.createElement("div");
     this.#skillsMenu = new SkillsMenu((skill) => this.#applySkill(skill));
@@ -442,23 +477,55 @@ export class AgUiChat extends HTMLElement {
   }
 
   connectedCallback(): void {
+    // Resolve the per-instance storage namespace (id, else endpoint) before any
+    // key read/write, so this instance doesn't share collapsed/theme/thread
+    // state with another on the same origin.
+    this.#storageNs = this.id !== "" ? this.id : this.endpoint;
     // Resolve the string table before rendering any chrome (defaults are the
     // floor; `data-strings` then the `strings` property layer over them).
     this.#strings = mergeUiStrings({ ...this.#readStringOverrides(), ...this.strings });
+    // Restore a theme the built-in toggle persisted last visit (opt-in only, so
+    // it never overrides a host that drives `theme` itself).
+    if (this.getAttribute("data-theme-toggle") !== null) {
+      const saved = this.#readScopedItem(THEME_KEY);
+      if (saved !== null) {
+        this.setAttribute("theme", saved);
+      }
+    }
     this.#render();
     this.#drawer.setStrings(this.#strings);
-    if (sessionStorage.getItem(COLLAPSED_KEY) === "1") {
+    if (this.#readScopedItem(COLLAPSED_KEY) === "1") {
       this.setAttribute("collapsed", "");
     }
     this.#syncRail();
     this.#initSkills();
     void this.#fetchToolCatalog();
+    // Namespace the built-in default store too (a host-injected store is used
+    // verbatim). Must precede #wireThreadStore, which wraps the current store.
+    if (this.#storageNs !== "" && this.conversationStore instanceof SessionStorageStore) {
+      this.conversationStore = new SessionStorageStore(this.#storageNs);
+    }
     this.#wireThreadStore();
     this.#wireAttachments();
+    this.#wireVoice();
     this.#threadId = this.conversationStore.threadId();
     void this.#rehydrate();
   }
 
+  /**
+   * Tear down live resources when the element leaves the DOM (a removed node, a
+   * client-side route swap): cancel the in-flight run so its SSE stream closes,
+   * abort any in-flight uploads so they don't orphan server-side files, and
+   * release the mic so the browser's recording indicator clears. Without this a
+   * removed `<ag-ui-chat>` leaks a streaming request, uploads, and a live
+   * `MediaRecorder`.
+   */
+  disconnectedCallback(): void {
+    this.#cancelRun();
+    this.#attachTray?.dispose();
+    this.#voice?.dispose();
+  }
+
   /** Parse the inline `data-strings` JSON overrides (empty when absent/malformed). */
   #readStringOverrides(): Partial<UiStrings> {
     const raw = this.getAttribute("data-strings");
@@ -507,7 +574,47 @@ export class AgUiChat extends HTMLElement {
     if (url === null) {
       return null;
     }
-    return (file, onProgress) => uploadAttachment(file, { url, headers: this.headers, onProgress });
+    // Forward the tray's abort signal so removing a chip (or tearing the
+    // element down) cancels the XHR.
+    return (file, onProgress, signal) =>
+      uploadAttachment(file, { url, headers: this.headers, onProgress, signal });
+  }
+
+  /**
+   * Reveal the composer's 🎤 mic button when transcription is possible — either
+   * a custom {@link transcribeHandler} is set or `data-transcribe-url` provides
+   * the built-in POST endpoint. The control records via `MediaRecorder` and
+   * drops the transcript into the composer; with neither configured the mic
+   * stays hidden and the chat is text-only.
+   */
+  #wireVoice(): void {
+    const url = this.getAttribute("data-transcribe-url");
+    const transcribe = this.transcribeHandler ?? this.#defaultTranscribeHandler(url);
+    if (transcribe === null) {
+      return;
+    }
+    this.#voice = new VoiceInput({
+      transcribe,
+      onText: (text) => this.#insertVoiceText(text),
+      strings: this.#strings,
+    });
+    this.#voiceSlot.appendChild(this.#voice.element);
+  }
+
+  /** The built-in transcription handler for `data-transcribe-url`, or `null`. */
+  #defaultTranscribeHandler(url: string | null): TranscribeHandler | null {
+    if (url === null) {
+      return null;
+    }
+    return (audio) => transcribeAudio(audio, { url, headers: this.headers });
+  }
+
+  /** Drop a voice transcript into the composer (appended to any typed text). */
+  #insertVoiceText(text: string): void {
+    const current = this.#input.value.trim();
+    this.#input.value = current === "" ? text : `${current} ${text}`;
+    this.#onInput();
+    this.#input.focus();
   }
 
   /** The client-side upload size cap from `data-attachment-max-bytes`. */
@@ -696,7 +803,7 @@ export class AgUiChat extends HTMLElement {
     } else {
       this.removeAttribute("collapsed");
     }
-    sessionStorage.setItem(COLLAPSED_KEY, collapsed ? "1" : "0");
+    sessionStorage.setItem(this.#storageKey(COLLAPSED_KEY), collapsed ? "1" : "0");
     this.#syncRail();
     this.dispatchEvent(
       new CustomEvent<ToggleDetail>(TOGGLE_EVENT, {
@@ -712,6 +819,43 @@ export class AgUiChat extends HTMLElement {
     this.setCollapsed(!this.collapsed);
   }
 
+  /**
+   * Flip the `theme` attribute between `light` and `dark` and persist the choice
+   * per tab. Bound to the optional built-in header theme toggle
+   * (`data-theme-toggle`); any non-dark theme (incl. `auto` / `code`) flips to
+   * `dark` first.
+   */
+  toggleTheme(): void {
+    const next = this.getAttribute("theme") === "dark" ? "light" : "dark";
+    this.setAttribute("theme", next);
+    sessionStorage.setItem(this.#storageKey(THEME_KEY), next);
+    this.#syncThemeGlyph();
+  }
+
+  /** This instance's namespaced form of an origin-scoped storage key. */
+  #storageKey(base: string): string {
+    return this.#storageNs === "" ? base : `${base}:${this.#storageNs}`;
+  }
+
+  /**
+   * Read a namespaced origin-scoped value, falling back once to the legacy
+   * pre-namespacing global key (left in place) so an existing collapsed/theme
+   * preference survives the upgrade.
+   */
+  #readScopedItem(base: string): string | null {
+    const scoped = sessionStorage.getItem(this.#storageKey(base));
+    if (scoped !== null || this.#storageNs === "") {
+      return scoped;
+    }
+    return sessionStorage.getItem(base);
+  }
+
+  /** Reflect the current theme on the toggle: show the destination's glyph. */
+  #syncThemeGlyph(): void {
+    const dark = this.getAttribute("theme") === "dark";
+    this.#themeToggle.textContent = dark ? "☀️" : "🌙";
+  }
+
   /**
    * Start a fresh conversation: forget the persisted history, drop the
    * in-memory run state, clear the transcript, and mint a new thread id.
@@ -731,6 +875,7 @@ export class AgUiChat extends HTMLElement {
     this.#client = null;
     this.#streamingBubble = null;
     this.#currentGroup = null;
+    this.#thoughts = null;
     this.#hidePending();
     this.#toolCards.clear();
     this.#serverSettled.clear();
@@ -781,7 +926,16 @@ export class AgUiChat extends HTMLElement {
    * result from the page we landed on.
    */
   async #rehydrate(): Promise<void> {
+    // Guard against a thread-switch race: with a slow remote store, picking
+    // thread B then C would interleave both replays into one transcript. Each
+    // rehydrate claims a generation before awaiting and bails if a newer one
+    // started meanwhile (its `#resetState` already cleared the transcript).
+    this.#rehydrateGeneration += 1;
+    const generation = this.#rehydrateGeneration;
     const messages = await this.conversationStore.loadMessages(this.#threadId);
+    if (generation !== this.#rehydrateGeneration) {
+      return;
+    }
     if (messages !== null) {
       this.#initialMessages = messages;
       for (const message of messages) {
@@ -879,7 +1033,7 @@ export class AgUiChat extends HTMLElement {
    * stays literal text (no need to parse what the user typed, and it avoids
    * rendering user-authored markup).
    *
-   * Assistant bubbles land in the current answer group (WELL-1), opening one if
+   * Assistant bubbles land in the current answer group, opening one if
    * needed; a user bubble closes the prior group and sits directly in the list
    * (the well wraps the *assistant* turn, the user message precedes it).
    */
@@ -965,7 +1119,20 @@ export class AgUiChat extends HTMLElement {
     const collapse = this.#headerButton("collapse", this.#strings.collapse, "—");
     collapse.addEventListener("click", () => this.toggleCollapsed());
 
-    controls.append(history, newChat, collapse);
+    controls.append(history, newChat);
+    // Optional built-in theme toggle: off unless the host opts in, so
+    // it never competes with a host-supplied switch in `slot="header-actions"`.
+    if (this.getAttribute("data-theme-toggle") !== null) {
+      this.#themeToggle.type = "button";
+      this.#themeToggle.className = "header-btn header-btn--theme";
+      this.#themeToggle.setAttribute("part", "header-button theme-toggle");
+      this.#themeToggle.title = this.#strings.toggleTheme;
+      this.#themeToggle.setAttribute("aria-label", this.#strings.toggleTheme);
+      this.#themeToggle.addEventListener("click", () => this.toggleTheme());
+      this.#syncThemeGlyph();
+      controls.append(this.#themeToggle);
+    }
+    controls.append(collapse);
     header.append(title, headerActions, controls);
 
     this.#messages.className = "messages";
@@ -1035,11 +1202,14 @@ export class AgUiChat extends HTMLElement {
 
     this.#attachSlot.className = "attachment-slot";
 
+    // Mic button mount point (kept empty until #wireVoice mounts the control).
+    this.#voiceSlot.className = "voice-slot";
+
     // A coarse footer slot below the composer.
     const footer = document.createElement("slot");
     footer.name = "footer";
 
-    inputRow.append(this.#attachButton, this.#input, this.#send, this.#fileInput);
+    inputRow.append(this.#attachButton, this.#voiceSlot, this.#input, this.#send, this.#fileInput);
     // Skill surfaces sit just above the input: palette (opens on `/`), chips,
     // the missing-placeholder hint, and the pending-attachments tray.
     this.#chat.append(
@@ -1159,6 +1329,14 @@ export class AgUiChat extends HTMLElement {
   }
 
   async #submit(): Promise<void> {
+    // Ignore a submit while a run is in flight — the single choke point for
+    // both Enter and the Send button. The button already turns into Stop, but
+    // Enter has no such guard; without this it would start a second concurrent
+    // SSE run that orphans the first (unabortable) and lets the second run's
+    // settle sweep corrupt the first's still-pending tool cards.
+    if (this.#running) {
+      return;
+    }
     const content = this.#input.value.trim();
     const attachments = this.#attachTray?.readyRefs() ?? [];
     // Allow an attachments-only message (no typed text), but nothing empty.
@@ -1310,8 +1488,23 @@ export class AgUiChat extends HTMLElement {
         this.#ensureGroup();
         this.#showPending();
       },
+      onReasoningStart: () => {
+        // The model is thinking: swap the pending dots for a live thoughts
+        // region at the top of the turn's answer group.
+        this.#hidePending();
+        this.#showThoughts();
+      },
+      onReasoningDelta: (buffer) => {
+        this.#showThoughts().stream(buffer);
+      },
+      onReasoningEnd: () => {
+        // Leave the region expanded until the answer text starts — it collapses
+        // on the first text delta (onTextDelta).
+      },
       onTextDelta: (buffer) => {
         this.#hidePending();
+        // The answer has begun — fold the thoughts away so they don't crowd it.
+        this.#thoughts?.collapse();
         this.#streamInto(buffer);
         this.#streamDeltas += 1;
       },
@@ -1380,6 +1573,7 @@ export class AgUiChat extends HTMLElement {
           this.#updateEmptyState();
         }
         this.#currentGroup = null;
+        this.#thoughts = null;
       },
     };
   }
@@ -1427,6 +1621,22 @@ export class AgUiChat extends HTMLElement {
     this.#pending = null;
   }
 
+  /**
+   * The current turn's thoughts region, creating it (at the top of the answer
+   * group, above any streamed text or tool cards) on first sight. Idempotent
+   * across a turn's reasoning tokens.
+   */
+  #showThoughts(): ThoughtsBlock {
+    if (this.#thoughts === null) {
+      this.#thoughts = new ThoughtsBlock(this.#strings);
+      const group = this.#ensureGroup();
+      group.insertBefore(this.#thoughts.element, group.firstChild);
+      this.#updateEmptyState();
+      this.#messages.scrollTop = this.#messages.scrollHeight;
+    }
+    return this.#thoughts;
+  }
+
   #streamInto(buffer: string): HTMLDivElement {
     if (this.#streamingBubble === null) {
       this.#streamingBubble = this.appendMessage(MESSAGE_ROLE.ASSISTANT, "");

package/src/core/agui_client.ts

@@ -52,6 +52,12 @@ export interface AgUiClientHandlers {
    * their result itself — so this is the channel for server-executed output.
    */
   onToolResult(toolCallId: string, content: string): void;
+  /** Fired when a reasoning model starts emitting its chain-of-thought. */
+  onReasoningStart(): void;
+  /** Fired on every reasoning token; ``buffer`` is the full reasoning text so far. */
+  onReasoningDelta(buffer: string): void;
+  /** Fired when the reasoning block ends (before the answer text streams). */
+  onReasoningEnd(): void;
   onRunEnd(): void;
   onError(message: string): void;
   /**
@@ -242,7 +248,7 @@ export class AgUiClient {
         return;
       }
       const pending: AgUiToolCall[] = [];
-      const runState = { terminal: false };
+      const runState = { terminal: false, errored: false };
       await this.#agent.runAgent(
         { tools: this.#getTools(), context: this.#getContext() },
         this.#buildSubscriber(pending, runState),
@@ -259,6 +265,13 @@ export class AgUiClient {
       if (!runState.terminal) {
         throw new ConnectionLostError(this.#connectionLostMessage);
       }
+      // RUN_ERROR is terminal: the agent already reported the failure via
+      // onError. Don't execute the tool calls collected before it or start
+      // another round — that would run into a broken context and surface a
+      // confusing second error. Any pending tool card is swept at onSettled.
+      if (runState.errored) {
+        return;
+      }
       if (this.#executeTool === null || pending.length === 0) {
         return;
       }
@@ -288,7 +301,10 @@ export class AgUiClient {
     }
   }
 
-  #buildSubscriber(pending: AgUiToolCall[], runState: { terminal: boolean }): AgentSubscriber {
+  #buildSubscriber(
+    pending: AgUiToolCall[],
+    runState: { terminal: boolean; errored: boolean },
+  ): AgentSubscriber {
     const h = this.#handlers;
     return {
       onRunInitialized() {
@@ -312,8 +328,21 @@ export class AgUiClient {
       onToolCallResultEvent({ event }) {
         h.onToolResult(event.toolCallId, event.content);
       },
+      // Reasoning. `@ag-ui/client` already maps the deprecated
+      // THINKING_* events onto these REASONING_* callbacks, so handling the
+      // reasoning family alone covers both protocol versions.
+      onReasoningStartEvent() {
+        h.onReasoningStart();
+      },
+      onReasoningMessageContentEvent({ reasoningMessageBuffer }) {
+        h.onReasoningDelta(reasoningMessageBuffer);
+      },
+      onReasoningEndEvent() {
+        h.onReasoningEnd();
+      },
       onRunErrorEvent({ event }) {
         runState.terminal = true;
+        runState.errored = true;
         h.onError(event.message);
       },
       onRunFinalized() {

package/src/core/attachment.ts

@@ -32,8 +32,28 @@ export interface AttachmentRef {
  * restored conversation re-renders its attachment chips. The server's strict
  * `RunAgentInput` validation ignores the unknown field — the model learns the
  * ids from the run context manifest instead.
+ *
+ * The persisted array is untrusted (it can be hand-edited, truncated, or
+ * corrupted in storage), so every entry is validated and malformed ones are
+ * dropped — a `null` or shapeless entry would otherwise throw in `iconFor` and
+ * abort the whole history replay.
  */
 export function messageAttachments(message: Message): readonly AttachmentRef[] {
   const refs = (message as { attachments?: unknown }).attachments;
-  return Array.isArray(refs) ? (refs as readonly AttachmentRef[]) : [];
+  return Array.isArray(refs) ? refs.filter(isAttachmentRef) : [];
+}
+
+/** Whether an unknown value is a structurally valid {@link AttachmentRef}. */
+function isAttachmentRef(value: unknown): value is AttachmentRef {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const ref = value as Record<string, unknown>;
+  return (
+    typeof ref["id"] === "string" &&
+    typeof ref["name"] === "string" &&
+    typeof ref["mime"] === "string" &&
+    typeof ref["size"] === "number" &&
+    (ref["url"] === undefined || typeof ref["url"] === "string")
+  );
 }

package/src/core/conversation_store.ts

@@ -64,10 +64,11 @@ export interface ClientConversationStore {
   renameThread(threadId: string, title: string): void;
 }
 
-const THREAD_KEY = "ag-ui-chat:thread";
-const THREADS_KEY = "ag-ui-chat:threads";
-const MESSAGES_PREFIX = "ag-ui-chat:messages:";
-const CHECKPOINT_PREFIX = "ag-ui-chat:checkpoint:";
+const KEY_ROOT = "ag-ui-chat";
+const THREAD_SUFFIX = "thread";
+const THREADS_SUFFIX = "threads";
+const MESSAGES_SUFFIX = "messages:";
+const CHECKPOINT_SUFFIX = "checkpoint:";
 
 const TITLE_LIMIT = 60;
 const PREVIEW_LIMIT = 100;
@@ -90,33 +91,50 @@ interface StoredThread {
  * Tracks multiple threads per tab: the active id lives under one key, the
  * message history / checkpoint are namespaced by id, and a small index feeds
  * the drawer so it works with no server.
+ *
+ * An optional `namespace` scopes every key to one element (its `id`, else its
+ * endpoint), so two `<ag-ui-chat>` instances — or two apps — on the same origin
+ * keep separate active-thread pointers and drawer indexes instead of clobbering
+ * each other. Constructing with a namespace migrates any pre-namespacing
+ * (`ag-ui-chat:*`) keys into it once, so an existing conversation survives the
+ * upgrade; the default empty namespace keeps the legacy origin-global keys.
  */
 export class SessionStorageStore implements ClientConversationStore {
+  readonly #root: string;
+
+  constructor(namespace = "") {
+    this.#root = namespace === "" ? KEY_ROOT : `${KEY_ROOT}@${namespace}`;
+    if (namespace !== "") {
+      this.#migrateLegacyKeys();
+    }
+  }
+
   threadId(): string {
-    const existing = sessionStorage.getItem(THREAD_KEY);
+    const key = this.#key(THREAD_SUFFIX);
+    const existing = sessionStorage.getItem(key);
     if (existing !== null) {
       return existing;
     }
     const id = randomUUID();
-    sessionStorage.setItem(THREAD_KEY, id);
+    sessionStorage.setItem(key, id);
     return id;
   }
 
   loadMessages(threadId: string): Promise<readonly Message[] | null> {
-    return Promise.resolve(this.#readJson<Message[]>(MESSAGES_PREFIX + threadId));
+    return Promise.resolve(this.#readJson<Message[]>(this.#key(MESSAGES_SUFFIX + threadId)));
   }
 
   saveMessages(threadId: string, messages: readonly Message[]): void {
-    sessionStorage.setItem(MESSAGES_PREFIX + threadId, JSON.stringify(messages));
+    sessionStorage.setItem(this.#key(MESSAGES_SUFFIX + threadId), JSON.stringify(messages));
     this.#touchThread(threadId, messages);
   }
 
   loadCheckpoint(threadId: string): NavigationCheckpoint | null {
-    return this.#readJson<NavigationCheckpoint>(CHECKPOINT_PREFIX + threadId);
+    return this.#readJson<NavigationCheckpoint>(this.#key(CHECKPOINT_SUFFIX + threadId));
   }
 
   saveCheckpoint(threadId: string, checkpoint: NavigationCheckpoint | null): void {
-    const key = CHECKPOINT_PREFIX + threadId;
+    const key = this.#key(CHECKPOINT_SUFFIX + threadId);
     if (checkpoint === null) {
       sessionStorage.removeItem(key);
       return;
@@ -125,14 +143,14 @@ export class SessionStorageStore implements ClientConversationStore {
   }
 
   clear(threadId: string): void {
-    sessionStorage.removeItem(MESSAGES_PREFIX + threadId);
-    sessionStorage.removeItem(CHECKPOINT_PREFIX + threadId);
+    sessionStorage.removeItem(this.#key(MESSAGES_SUFFIX + threadId));
+    sessionStorage.removeItem(this.#key(CHECKPOINT_SUFFIX + threadId));
     this.#writeThreads(this.#readThreads().filter((thread) => thread.threadId !== threadId));
     // Only drop the active pointer when the active thread itself is cleared, so
     // the next `threadId()` mints a fresh one. Deleting another thread from the
     // drawer must not disturb the conversation on screen.
-    if (sessionStorage.getItem(THREAD_KEY) === threadId) {
-      sessionStorage.removeItem(THREAD_KEY);
+    if (sessionStorage.getItem(this.#key(THREAD_SUFFIX)) === threadId) {
+      sessionStorage.removeItem(this.#key(THREAD_SUFFIX));
     }
   }
 
@@ -144,7 +162,7 @@ export class SessionStorageStore implements ClientConversationStore {
   }
 
   setActiveThread(threadId: string): void {
-    sessionStorage.setItem(THREAD_KEY, threadId);
+    sessionStorage.setItem(this.#key(THREAD_SUFFIX), threadId);
   }
 
   renameThread(threadId: string, title: string): void {
@@ -183,15 +201,53 @@ export class SessionStorageStore implements ClientConversationStore {
   }
 
   #readThreads(): StoredThread[] {
-    return this.#readJson<StoredThread[]>(THREADS_KEY) ?? [];
+    return this.#readJson<StoredThread[]>(this.#key(THREADS_SUFFIX)) ?? [];
   }
 
   #writeThreads(threads: readonly StoredThread[]): void {
+    const key = this.#key(THREADS_SUFFIX);
     if (threads.length === 0) {
-      sessionStorage.removeItem(THREADS_KEY);
+      sessionStorage.removeItem(key);
       return;
     }
-    sessionStorage.setItem(THREADS_KEY, JSON.stringify(threads));
+    sessionStorage.setItem(key, JSON.stringify(threads));
+  }
+
+  /** This store's fully-qualified key for a suffix (namespaced when set). */
+  #key(suffix: string): string {
+    return `${this.#root}:${suffix}`;
+  }
+
+  /**
+   * One-time move of pre-namespacing (`ag-ui-chat:*`) keys into this instance's
+   * namespace, so an existing conversation isn't orphaned by the upgrade. Only
+   * this store's own keys move (thread pointer, drawer index, per-thread
+   * messages/checkpoints) — the element's `collapsed`/`theme` keys are left
+   * alone. The first namespaced instance to mount adopts the legacy data; a
+   * second namespace finds it gone and starts fresh.
+   */
+  #migrateLegacyKeys(): void {
+    const legacyRoot = `${KEY_ROOT}:`;
+    const moves: Array<readonly [string, string]> = [];
+    for (let i = 0; i < sessionStorage.length; i += 1) {
+      const key = sessionStorage.key(i);
+      if (key === null || !key.startsWith(legacyRoot)) {
+        continue;
+      }
+      const suffix = key.slice(legacyRoot.length);
+      if (isOwnedSuffix(suffix)) {
+        moves.push([key, this.#key(suffix)]);
+      }
+    }
+    // Collected first, mutated second — writing while iterating by index skips
+    // entries as the key list shifts.
+    for (const [from, to] of moves) {
+      const value = sessionStorage.getItem(from);
+      if (value !== null && sessionStorage.getItem(to) === null) {
+        sessionStorage.setItem(to, value);
+      }
+      sessionStorage.removeItem(from);
+    }
   }
 
   /** Parse a stored JSON value, returning `null` when absent or corrupt. */
@@ -208,6 +264,16 @@ export class SessionStorageStore implements ClientConversationStore {
   }
 }
 
+/** Whether a legacy key suffix belongs to the store (vs the element's own keys). */
+function isOwnedSuffix(suffix: string): boolean {
+  return (
+    suffix === THREAD_SUFFIX ||
+    suffix === THREADS_SUFFIX ||
+    suffix.startsWith(MESSAGES_SUFFIX) ||
+    suffix.startsWith(CHECKPOINT_SUFFIX)
+  );
+}
+
 /** The thread title: the first user message, collapsed + truncated. */
 function deriveTitle(messages: readonly Message[]): string {
   for (const message of messages) {