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

package/dist/index.js

@@ -506,8 +506,10 @@ var DEFAULT_UI_STRINGS = {
   newChat: "New chat",
   collapse: "Collapse",
   expand: "Expand",
+  toggleTheme: "Toggle theme",
   conversation: "Conversation",
   thinking: "Assistant is thinking\u2026",
+  thoughts: "Thoughts",
   stopped: "\u23F9 Stopped",
   connectionLost: "Connection lost",
   noResult: "No result returned.",
@@ -519,6 +521,10 @@ var DEFAULT_UI_STRINGS = {
   send: "Send",
   stop: "Stop",
   attachFiles: "Attach files",
+  recordVoice: "Record voice",
+  stopRecording: "Stop recording",
+  transcribing: "Transcribing\u2026",
+  transcriptionFailed: "Transcription failed",
   toolRunning: "running\u2026",
   toolDone: "\u2713 done",
   toolError: "\u26A0 error",
@@ -585,7 +591,8 @@ var AttachmentTray = class {
       status: ATTACHMENT_STATUS.UPLOADING,
       progress: 0,
       ref: null,
-      error: ""
+      error: "",
+      controller: null
     };
     this.#items.push(item);
     const rejection = this.#reject(file);
@@ -623,11 +630,24 @@ var AttachmentTray = class {
     this.#items = this.#items.filter((item) => item.status === ATTACHMENT_STATUS.UPLOADING);
     this.#render();
   }
-  /** Drop every chip (a reset / new-chat). */
+  /** Drop every chip (a reset / new-chat), aborting any in-flight upload. */
   clear() {
+    for (const item of this.#items) {
+      item.controller?.abort();
+    }
     this.#items = [];
     this.#render();
   }
+  /**
+   * Abort every in-flight upload without touching the rendered chips — the
+   * teardown path when the host element is removed mid-upload, so a cancelled
+   * transfer doesn't orphan a server-side file.
+   */
+  dispose() {
+    for (const item of this.#items) {
+      item.controller?.abort();
+    }
+  }
   /** The size/type rejection reason for a file, or `null` when accepted. */
   #reject(file) {
     if (this.#config.maxBytes > 0 && file.size > this.#config.maxBytes) {
@@ -639,25 +659,41 @@ var AttachmentTray = class {
     return null;
   }
   #upload(item) {
+    const rejection = this.#reject(item.file);
+    if (rejection !== null) {
+      item.status = ATTACHMENT_STATUS.ERROR;
+      item.error = rejection;
+      this.#render();
+      this.#config.onChange?.();
+      return;
+    }
     item.status = ATTACHMENT_STATUS.UPLOADING;
     item.progress = 0;
     item.error = "";
+    const controller = new AbortController();
+    item.controller = controller;
     this.#render();
-    this.#config.upload(item.file, (fraction) => {
-      item.progress = fraction;
-      this.#render();
-    }).then((ref) => {
+    this.#config.upload(
+      item.file,
+      (fraction) => {
+        item.progress = fraction;
+        this.#render();
+      },
+      controller.signal
+    ).then((ref) => {
       item.status = ATTACHMENT_STATUS.READY;
       item.ref = ref;
     }).catch((error) => {
       item.status = ATTACHMENT_STATUS.ERROR;
       item.error = error instanceof Error ? error.message : this.#strings.uploadFailed;
     }).finally(() => {
+      item.controller = null;
       this.#render();
       this.#config.onChange?.();
     });
   }
   #remove(item) {
+    item.controller?.abort();
     this.#items = this.#items.filter((other) => other !== item);
     this.#render();
     this.#config.onChange?.();
@@ -3611,7 +3647,7 @@ var STYLES = `
   --ag-ui-radius: 0;
 }
 
-/* Page (PAGE-1): full-bleed background with a centred reading column. Unlike
+/* Page: full-bleed background with a centred reading column. Unlike
    "full" (edge-to-edge, left-aligned messages) the content sits in a column
    capped at --ag-ui-content-max-width. The column is produced by symmetric auto
    padding on the scroll area + composer (no per-row wrapper), so user pills
@@ -3653,7 +3689,7 @@ var STYLES = `
   max-width: 100%;
 }
 
-/* Sidebar (CUST-3): a full-height docked panel that slides open/closed and
+/* Sidebar: a full-height docked panel that slides open/closed and
    collapses to a slim icon rail (not the floating launcher). Docked right by
    default; data-side="left" docks it left. Overlay by default \u2014 set
    --ag-ui-position: static (and place this element in your own layout) for a
@@ -3763,7 +3799,7 @@ var STYLES = `
   white-space: nowrap;
 }
 
-/* Header / launcher icon holder (CUST-2): a slot, with a data-icon-url <img>
+/* Header / launcher icon holder: a slot, with a data-icon-url <img>
    fallback, sized via --ag-ui-icon-size. */
 .icon-holder {
   display: inline-flex;
@@ -3837,7 +3873,7 @@ var STYLES = `
   gap: var(--ag-ui-space);
 }
 
-/* Empty-state region (CUST-1 slot): centred while it's the only thing in the
+/* Empty-state region (slot): centred while it's the only thing in the
    list, hidden as soon as a message, card, or pending indicator renders. */
 .empty {
   margin: auto;
@@ -3849,7 +3885,7 @@ var STYLES = `
   display: none;
 }
 
-/* \u2500\u2500 Answer group / well (WELL-1) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+/* \u2500\u2500 Answer group / well \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
    One .answer per assistant turn wraps the streamed text, its tool cards,
    and the pending indicator so a whole answer reads (and can be boxed) as one
    unit. A flex column on the message-list gap, stretched to the list width so
@@ -4018,6 +4054,69 @@ var STYLES = `
   }
 }
 
+/* \u2500\u2500 Thoughts region \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+   A muted, collapsible chain-of-thought at the top of the answer group: open
+   while the model reasons, folded once the answer text starts. */
+.thoughts {
+  align-self: stretch;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  font-size: 12px;
+  color: var(--ag-ui-muted);
+}
+
+.thoughts-toggle {
+  align-self: flex-start;
+  border: none;
+  padding: 0;
+  background: none;
+  font: inherit;
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--ag-ui-muted);
+  cursor: pointer;
+}
+
+.thoughts-toggle::before {
+  content: "\u25BE ";
+}
+
+.thoughts-toggle[aria-expanded="false"]::before {
+  content: "\u25B8 ";
+}
+
+/* A gentle pulse on the label while reasoning is still streaming. */
+.thoughts[data-streaming] .thoughts-label {
+  animation: ag-ui-thoughts-pulse 1.4s ease-in-out infinite;
+}
+
+@keyframes ag-ui-thoughts-pulse {
+  0%, 100% { opacity: 0.55; }
+  50% { opacity: 1; }
+}
+
+.thoughts-body {
+  margin: 0;
+  padding: 4px 0 4px 10px;
+  border-left: 2px solid var(--ag-ui-border);
+  max-height: 220px;
+  overflow: auto;
+  white-space: pre-wrap;
+  word-break: break-word;
+  font-family: inherit;
+}
+
+.thoughts-body[hidden] {
+  display: none;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .thoughts[data-streaming] .thoughts-label {
+    animation: none;
+  }
+}
+
 .tool-call {
   align-self: flex-start;
   max-width: 80%;
@@ -4048,7 +4147,7 @@ var STYLES = `
   word-break: break-word;
 }
 
-/* Leading status icon (CARD-1). Empty in the DOM \u2014 the glyph/spinner is drawn
+/* Leading status icon. Empty in the DOM \u2014 the glyph/spinner is drawn
    here from the card's data-status, so it stays themeable. */
 .tool-call-icon {
   flex: none;
@@ -4096,7 +4195,7 @@ var STYLES = `
   }
 }
 
-/* Inline display mode (CARD-1): the lightest card \u2014 drop the box chrome so the
+/* Inline display mode: the lightest card \u2014 drop the box chrome so the
    status row reads as one line of the answer; the result toggle still expands
    below it. */
 .tool-call[data-display="inline"] {
@@ -4226,6 +4325,49 @@ var STYLES = `
   display: none;
 }
 
+/* The \u{1F3A4} mic button; shown only once #wireVoice mounts it. */
+.voice-slot {
+  display: contents;
+}
+
+.voice-btn {
+  border: 1px solid var(--ag-ui-border);
+  border-radius: 8px;
+  padding: 0 10px;
+  background: var(--ag-ui-input-bg);
+  color: inherit;
+  font: inherit;
+  cursor: pointer;
+}
+
+.voice-btn:hover {
+  border-color: var(--ag-ui-accent);
+}
+
+.voice-btn:disabled {
+  cursor: default;
+  opacity: 0.6;
+}
+
+/* Recording: a red tint + a gentle pulse so it's clearly "live". */
+.voice-btn[data-state="recording"] {
+  border-color: var(--ag-ui-danger);
+  background: var(--ag-ui-danger);
+  color: #ffffff;
+  animation: ag-ui-voice-pulse 1.2s ease-in-out infinite;
+}
+
+@keyframes ag-ui-voice-pulse {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.6; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .voice-btn[data-state="recording"] {
+    animation: none;
+  }
+}
+
 /* Pending-attachments tray, above the input row; collapses (hidden) when empty. */
 .attachment-slot {
   display: contents;
@@ -4640,8 +4782,67 @@ var STYLES = `
 }
 `;
 
+// src/ui/thoughts_block.ts
+var ThoughtsBlock = class {
+  /** The block's root element; insert this at the top of the answer group. */
+  element;
+  #label;
+  #body;
+  #toggle;
+  #strings;
+  #collapsed = false;
+  constructor(strings = DEFAULT_UI_STRINGS) {
+    this.#strings = strings;
+    this.element = document.createElement("div");
+    this.element.className = "thoughts";
+    this.element.setAttribute("part", "thoughts");
+    this.element.setAttribute("data-streaming", "");
+    this.#toggle = document.createElement("button");
+    this.#toggle.type = "button";
+    this.#toggle.className = "thoughts-toggle";
+    this.#toggle.setAttribute("part", "thoughts-toggle");
+    this.#toggle.setAttribute("aria-expanded", "true");
+    this.#label = document.createElement("span");
+    this.#label.className = "thoughts-label";
+    this.#label.textContent = strings.thinking;
+    this.#toggle.append(this.#label);
+    this.#body = document.createElement("pre");
+    this.#body.className = "thoughts-body";
+    this.#body.setAttribute("part", "thoughts-body");
+    this.#toggle.addEventListener("click", () => {
+      this.#setCollapsed(!this.#collapsed);
+    });
+    this.element.append(this.#toggle, this.#body);
+  }
+  /** Replace the reasoning body with the running buffer (the full text so far). */
+  stream(buffer) {
+    this.#body.textContent = buffer;
+  }
+  /**
+   * Fold the region away — called when the answer's first text token arrives.
+   * Idempotent (the per-token text handler calls it repeatedly) and flips the
+   * header label from "thinking…" to the settled "Thoughts" affordance.
+   */
+  collapse() {
+    if (this.#collapsed) {
+      return;
+    }
+    this.element.removeAttribute("data-streaming");
+    this.#label.textContent = this.#strings.thoughts;
+    this.#setCollapsed(true);
+  }
+  #setCollapsed(collapsed) {
+    this.#collapsed = collapsed;
+    this.#body.hidden = collapsed;
+    this.#toggle.setAttribute("aria-expanded", String(!collapsed));
+  }
+};
+
 // src/ui/relative_time.ts
 function relativeTime(timestamp, now = Date.now(), strings = DEFAULT_UI_STRINGS) {
+  if (!Number.isFinite(timestamp)) {
+    return strings.justNow;
+  }
   const seconds = Math.round((now - timestamp) / 1e3);
   if (seconds < 60) {
     return strings.justNow;
@@ -4673,6 +4874,8 @@ var ThreadDrawer = class {
   #strings;
   #threads = [];
   #activeId = "";
+  /** The element focused before the drawer opened, restored on close. */
+  #lastFocused = null;
   constructor(callbacks, strings = DEFAULT_UI_STRINGS) {
     this.#callbacks = callbacks;
     this.#strings = strings;
@@ -4688,7 +4891,9 @@ var ThreadDrawer = class {
     this.#panel.className = "drawer-panel";
     this.#panel.setAttribute("part", "drawer-panel");
     this.#panel.setAttribute("role", "dialog");
+    this.#panel.setAttribute("aria-modal", "true");
     this.#panel.setAttribute("aria-label", strings.chatHistory);
+    this.#panel.addEventListener("keydown", (event) => this.#onPanelKeydown(event));
     const header = document.createElement("div");
     header.className = "drawer-header";
     header.setAttribute("part", "drawer-header");
@@ -4724,13 +4929,55 @@ var ThreadDrawer = class {
     return !this.element.hidden;
   }
   open() {
+    if (this.isOpen()) {
+      return;
+    }
+    this.#lastFocused = this.#activeElement();
     this.element.hidden = false;
+    this.#newButton.focus();
   }
   close() {
+    if (!this.isOpen()) {
+      return;
+    }
     this.element.hidden = true;
+    this.#lastFocused?.focus();
+    this.#lastFocused = null;
   }
   toggle() {
-    this.element.hidden = !this.element.hidden;
+    if (this.isOpen()) {
+      this.close();
+    } else {
+      this.open();
+    }
+  }
+  /** The currently-focused element within the drawer's root (shadow-aware). */
+  #activeElement() {
+    return this.element.getRootNode().activeElement;
+  }
+  /** Escape-to-close and a Tab focus trap while the dialog is open. */
+  #onPanelKeydown(event) {
+    if (event.key === "Escape") {
+      event.preventDefault();
+      this.close();
+      return;
+    }
+    if (event.key !== "Tab") {
+      return;
+    }
+    const focusables = Array.from(
+      this.#panel.querySelectorAll("button, input, [tabindex]")
+    ).filter((el) => !el.hidden);
+    const first = focusables[0];
+    const last = focusables[focusables.length - 1];
+    const active = this.#activeElement();
+    if (event.shiftKey && active === first) {
+      event.preventDefault();
+      last?.focus();
+    } else if (!event.shiftKey && active === last) {
+      event.preventDefault();
+      first?.focus();
+    }
   }
   /** Render the rows (or the empty state), highlighting the active thread. */
   setThreads(threads, activeId) {
@@ -4797,24 +5044,43 @@ var ThreadDrawer = class {
     row.append(select, actions);
     return row;
   }
-  /** Swap a row for an inline rename input; Enter commits, Escape cancels. */
+  /** Swap a row for an inline rename input; Enter/blur commits, Escape cancels. */
   #startRename(row, meta) {
     const input = document.createElement("input");
     input.type = "text";
     input.className = "drawer-rename-input";
     input.value = meta.title;
+    let done = false;
+    const commit = () => {
+      if (done) {
+        return;
+      }
+      done = true;
+      const value = input.value.trim();
+      if (value === "" || value === meta.title) {
+        this.#renderList();
+      } else {
+        this.#callbacks.onRename(meta.threadId, value);
+      }
+    };
+    const cancel = () => {
+      if (done) {
+        return;
+      }
+      done = true;
+      this.#renderList();
+    };
     input.addEventListener("keydown", (event) => {
       if (event.key === "Enter") {
-        const value = input.value.trim();
-        if (value === "") {
-          this.#renderList();
-        } else {
-          this.#callbacks.onRename(meta.threadId, value);
-        }
+        event.preventDefault();
+        commit();
       } else if (event.key === "Escape") {
-        this.#renderList();
+        event.preventDefault();
+        event.stopPropagation();
+        cancel();
       }
     });
+    input.addEventListener("blur", () => commit());
     row.replaceChildren(input);
     input.focus();
     input.select();
@@ -4910,6 +5176,9 @@ var ToolCallCard = class {
    * `inline`), or the args + result together (`compact`).
    */
   settle(status, text2) {
+    if (this.#settled) {
+      return;
+    }
     this.#settled = true;
     this.element.setAttribute("data-status", status);
     this.#status.textContent = statusLabels(this.#strings)[status];
@@ -4943,6 +5212,134 @@ ${text2}`;
   }
 };
 
+// src/ui/voice_input.ts
+var VoiceInput = class {
+  /** The mic button; mount this in the composer. */
+  element;
+  #transcribe;
+  #onText;
+  #strings;
+  #state = "idle";
+  #recorder = null;
+  #stream = null;
+  #chunks = [];
+  #disposed = false;
+  constructor(options) {
+    this.#transcribe = options.transcribe;
+    this.#onText = options.onText;
+    this.#strings = options.strings ?? DEFAULT_UI_STRINGS;
+    this.element = document.createElement("button");
+    this.element.type = "button";
+    this.element.className = "voice-btn";
+    this.element.setAttribute("part", "voice-button");
+    this.element.textContent = "\u{1F3A4}";
+    this.#setState("idle");
+    this.element.addEventListener("click", () => {
+      void this.toggle();
+    });
+  }
+  /** Start recording when idle, stop (and transcribe) when recording. */
+  async toggle() {
+    if (this.#state === "recording") {
+      this.#stop();
+      return;
+    }
+    if (this.#state === "transcribing") {
+      return;
+    }
+    await this.#start();
+  }
+  async #start() {
+    let stream;
+    try {
+      stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+    } catch {
+      this.#fail(this.#strings.transcriptionFailed);
+      return;
+    }
+    this.#stream = stream;
+    this.#chunks = [];
+    const recorder = new MediaRecorder(stream);
+    recorder.addEventListener("dataavailable", (event) => {
+      this.#chunks.push(event.data);
+    });
+    recorder.addEventListener("stop", () => {
+      void this.#finish(recorder.mimeType);
+    });
+    this.#recorder = recorder;
+    recorder.start();
+    this.#setState("recording");
+  }
+  #stop() {
+    this.#recorder?.stop();
+  }
+  /**
+   * Tear the control down — the teardown path when the host element is removed
+   * mid-recording. Stops any live `MediaRecorder`, releases the mic tracks (so
+   * the browser's recording indicator clears), and suppresses the pending
+   * transcription: a disconnected control must not fire `onText` back into a
+   * detached element.
+   */
+  dispose() {
+    this.#disposed = true;
+    if (this.#recorder !== null && this.#recorder.state !== "inactive") {
+      this.#recorder.stop();
+    }
+    this.#recorder = null;
+    this.#releaseStream();
+  }
+  async #finish(mimeType) {
+    if (this.#disposed) {
+      return;
+    }
+    this.#releaseStream();
+    this.#setState("transcribing");
+    const audio = new Blob(this.#chunks, { type: mimeType || "audio/webm" });
+    try {
+      const text2 = await this.#transcribe(audio);
+      this.#setState("idle");
+      if (text2 !== "") {
+        this.#onText(text2);
+      }
+    } catch (error) {
+      this.#fail(error instanceof Error ? error.message : this.#strings.transcriptionFailed);
+    } finally {
+      this.#recorder = null;
+    }
+  }
+  /** Stop the mic tracks so the browser's recording indicator clears. */
+  #releaseStream() {
+    for (const track of this.#stream?.getTracks() ?? []) {
+      track.stop();
+    }
+    this.#stream = null;
+  }
+  #fail(message) {
+    this.#releaseStream();
+    this.#recorder = null;
+    this.#setState("idle");
+    this.element.title = message;
+  }
+  #setState(state) {
+    this.#state = state;
+    this.element.dataset["state"] = state;
+    const label = this.#labelFor(state);
+    this.element.title = label;
+    this.element.setAttribute("aria-label", label);
+    this.element.setAttribute("aria-pressed", String(state === "recording"));
+    this.element.disabled = state === "transcribing";
+  }
+  #labelFor(state) {
+    if (state === "recording") {
+      return this.#strings.stopRecording;
+    }
+    if (state === "transcribing") {
+      return this.#strings.transcribing;
+    }
+    return this.#strings.recordVoice;
+  }
+};
+
 // src/core/agui_client.ts
 import { randomUUID as randomUUID2 } from "@ag-ui/client";
 var ConnectionLostError = class extends Error {
@@ -5052,7 +5449,7 @@ var AgUiClient = class {
         return;
       }
       const pending = [];
-      const runState = { terminal: false };
+      const runState = { terminal: false, errored: false };
       await this.#agent.runAgent(
         { tools: this.#getTools(), context: this.#getContext() },
         this.#buildSubscriber(pending, runState)
@@ -5064,6 +5461,9 @@ var AgUiClient = class {
       if (!runState.terminal) {
         throw new ConnectionLostError(this.#connectionLostMessage);
       }
+      if (runState.errored) {
+        return;
+      }
       if (this.#executeTool === null || pending.length === 0) {
         return;
       }
@@ -5114,8 +5514,21 @@ var AgUiClient = class {
       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() {
@@ -5132,40 +5545,56 @@ function isAbortError(error) {
 // src/core/attachment.ts
 function messageAttachments(message) {
   const refs = message.attachments;
-  return Array.isArray(refs) ? refs : [];
+  return Array.isArray(refs) ? refs.filter(isAttachmentRef) : [];
+}
+function isAttachmentRef(value) {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const ref = value;
+  return typeof ref["id"] === "string" && typeof ref["name"] === "string" && typeof ref["mime"] === "string" && typeof ref["size"] === "number" && (ref["url"] === void 0 || typeof ref["url"] === "string");
 }
 
 // src/core/conversation_store.ts
 import { randomUUID as randomUUID3 } from "@ag-ui/client";
-var THREAD_KEY = "ag-ui-chat:thread";
-var THREADS_KEY = "ag-ui-chat:threads";
-var MESSAGES_PREFIX = "ag-ui-chat:messages:";
-var CHECKPOINT_PREFIX = "ag-ui-chat:checkpoint:";
+var KEY_ROOT = "ag-ui-chat";
+var THREAD_SUFFIX = "thread";
+var THREADS_SUFFIX = "threads";
+var MESSAGES_SUFFIX = "messages:";
+var CHECKPOINT_SUFFIX = "checkpoint:";
 var TITLE_LIMIT = 60;
 var PREVIEW_LIMIT = 100;
 var DEFAULT_TITLE = "New conversation";
 var SessionStorageStore = class {
+  #root;
+  constructor(namespace = "") {
+    this.#root = namespace === "" ? KEY_ROOT : `${KEY_ROOT}@${namespace}`;
+    if (namespace !== "") {
+      this.#migrateLegacyKeys();
+    }
+  }
   threadId() {
-    const existing = sessionStorage.getItem(THREAD_KEY);
+    const key = this.#key(THREAD_SUFFIX);
+    const existing = sessionStorage.getItem(key);
     if (existing !== null) {
       return existing;
     }
     const id = randomUUID3();
-    sessionStorage.setItem(THREAD_KEY, id);
+    sessionStorage.setItem(key, id);
     return id;
   }
   loadMessages(threadId) {
-    return Promise.resolve(this.#readJson(MESSAGES_PREFIX + threadId));
+    return Promise.resolve(this.#readJson(this.#key(MESSAGES_SUFFIX + threadId)));
   }
   saveMessages(threadId, messages) {
-    sessionStorage.setItem(MESSAGES_PREFIX + threadId, JSON.stringify(messages));
+    sessionStorage.setItem(this.#key(MESSAGES_SUFFIX + threadId), JSON.stringify(messages));
     this.#touchThread(threadId, messages);
   }
   loadCheckpoint(threadId) {
-    return this.#readJson(CHECKPOINT_PREFIX + threadId);
+    return this.#readJson(this.#key(CHECKPOINT_SUFFIX + threadId));
   }
   saveCheckpoint(threadId, checkpoint) {
-    const key = CHECKPOINT_PREFIX + threadId;
+    const key = this.#key(CHECKPOINT_SUFFIX + threadId);
     if (checkpoint === null) {
       sessionStorage.removeItem(key);
       return;
@@ -5173,11 +5602,11 @@ var SessionStorageStore = class {
     sessionStorage.setItem(key, JSON.stringify(checkpoint));
   }
   clear(threadId) {
-    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));
-    if (sessionStorage.getItem(THREAD_KEY) === threadId) {
-      sessionStorage.removeItem(THREAD_KEY);
+    if (sessionStorage.getItem(this.#key(THREAD_SUFFIX)) === threadId) {
+      sessionStorage.removeItem(this.#key(THREAD_SUFFIX));
     }
   }
   listThreads() {
@@ -5185,7 +5614,7 @@ var SessionStorageStore = class {
     return Promise.resolve(metas);
   }
   setActiveThread(threadId) {
-    sessionStorage.setItem(THREAD_KEY, threadId);
+    sessionStorage.setItem(this.#key(THREAD_SUFFIX), threadId);
   }
   renameThread(threadId, title) {
     const threads = this.#readThreads();
@@ -5221,14 +5650,48 @@ var SessionStorageStore = class {
     this.#writeThreads(threads);
   }
   #readThreads() {
-    return this.#readJson(THREADS_KEY) ?? [];
+    return this.#readJson(this.#key(THREADS_SUFFIX)) ?? [];
   }
   #writeThreads(threads) {
+    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) {
+    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() {
+    const legacyRoot = `${KEY_ROOT}:`;
+    const moves = [];
+    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)]);
+      }
+    }
+    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. */
   #readJson(key) {
@@ -5243,6 +5706,9 @@ var SessionStorageStore = class {
     }
   }
 };
+function isOwnedSuffix(suffix) {
+  return suffix === THREAD_SUFFIX || suffix === THREADS_SUFFIX || suffix.startsWith(MESSAGES_SUFFIX) || suffix.startsWith(CHECKPOINT_SUFFIX);
+}
 function deriveTitle(messages) {
   for (const message of messages) {
     if (message.role === "user") {
@@ -5349,7 +5815,10 @@ var RemoteConversationStore = class {
     if (response === null || !response.ok) {
       return this.#local.loadMessages(threadId);
     }
-    const body = await response.json();
+    const body = await this.#readJson(response);
+    if (body === null) {
+      return this.#local.loadMessages(threadId);
+    }
     return body.messages ?? null;
   }
   async #fetchThreads() {
@@ -5357,14 +5826,28 @@ var RemoteConversationStore = class {
     if (response === null || !response.ok) {
       return null;
     }
-    const body = await response.json();
+    const body = await this.#readJson(response);
+    if (body === null) {
+      return null;
+    }
     return body.threads ?? [];
   }
+  /** Parse a `Response` body as JSON, or `null` when it isn't valid JSON. */
+  async #readJson(response) {
+    try {
+      return await response.json();
+    } catch {
+      return null;
+    }
+  }
   #toMeta(row) {
     return {
       threadId: row.thread_id,
       title: this.#renamed.get(row.thread_id) ?? row.title,
-      updatedAt: row.updated_at === null ? 0 : Date.parse(row.updated_at),
+      // `null` or an unparseable date both become `NaN` (Date.parse's own
+      // signal), which `relativeTime` renders as a neutral label rather than
+      // "~2950w ago" (epoch 0) or "NaNw ago".
+      updatedAt: row.updated_at === null ? Number.NaN : Date.parse(row.updated_at),
       preview: row.preview
     };
   }
@@ -5390,6 +5873,35 @@ var RemoteConversationStore = class {
   }
 };
 
+// src/core/transcribe_audio.ts
+async function transcribeAudio(audio, options) {
+  const form = new FormData();
+  form.append("audio", audio, "recording.webm");
+  const response = await fetch(options.url, {
+    method: "POST",
+    headers: { ...options.headers ?? {} },
+    body: form
+  });
+  if (!response.ok) {
+    throw new Error(await errorMessage(response));
+  }
+  const body = await response.json();
+  if (typeof body === "object" && body !== null && typeof body.text === "string") {
+    return body.text;
+  }
+  throw new Error("transcription returned an unreadable response");
+}
+async function errorMessage(response) {
+  try {
+    const body = await response.json();
+    if (typeof body.error === "string") {
+      return body.error;
+    }
+  } catch {
+  }
+  return `transcription failed (${response.status})`;
+}
+
 // src/core/upload_attachment.ts
 function uploadAttachment(file, options) {
   return new Promise((resolve, reject) => {
@@ -5416,7 +5928,7 @@ function uploadAttachment(file, options) {
           reject(new Error("upload returned an unreadable response"));
         }
       } else {
-        reject(new Error(errorMessage(xhr)));
+        reject(new Error(errorMessage2(xhr)));
       }
     });
     xhr.addEventListener("error", () => reject(new Error("upload failed")));
@@ -5443,7 +5955,7 @@ function parseRef(body) {
   }
   return typeof url === "string" ? { id, name, mime, size, url } : { id, name, mime, size };
 }
-function errorMessage(xhr) {
+function errorMessage2(xhr) {
   try {
     const body = JSON.parse(xhr.responseText);
     if (typeof body.error === "string") {
@@ -5456,6 +5968,7 @@ function errorMessage(xhr) {
 
 // src/core/ag_ui_chat.ts
 var COLLAPSED_KEY = "ag-ui-chat:collapsed";
+var THEME_KEY = "ag-ui-chat:theme";
 var AgUiChat = class extends HTMLElement {
   /** Agent factory; override to inject a custom or fake agent (tests). */
   agentFactory = createHttpAgent;
@@ -5533,6 +6046,15 @@ var AgUiChat = class extends HTMLElement {
    * with no `data-attachments-url`; the handler owns its own endpoint + headers.
    */
   uploadHandler = 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 = 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
@@ -5601,12 +6123,18 @@ var AgUiChat = class extends HTMLElement {
   #attachButton;
   #fileInput;
   #attachSlot;
+  /** Optional built-in header theme toggle; shown only with `data-theme-toggle`. */
+  #themeToggle;
   /** The collapsed-sidebar rail (an expand affordance; shown only for `placement="sidebar"`). */
   #rail;
   /** Empty-state region at the top of the message list; hidden once anything renders. */
   #emptyWrap;
   /** Upload tray; created on connect only when `data-attachments-url` is set. */
   #attachTray = null;
+  /** Mic button mount point (input row); the control mounts on connect when enabled. */
+  #voiceSlot;
+  /** Voice-input control; created on connect when transcription is available. */
+  #voice = null;
   /** Refs attached to the message currently being sent (the context manifest). */
   #runAttachments = [];
   #client = null;
@@ -5623,14 +6151,25 @@ var AgUiChat = class extends HTMLElement {
   // it; ≤1 ⇒ it arrived at once and the word reveal is appropriate.
   #streamDeltas = 0;
   #pending = 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 = 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 = 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 = [];
   // Skill catalog by source; merged backend → embed → client (later wins).
   #backendSkills = [];
@@ -5648,6 +6187,8 @@ var AgUiChat = class 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));
@@ -5772,20 +6313,44 @@ var AgUiChat = class extends HTMLElement {
     this.setAttribute("data-tool-display", value);
   }
   connectedCallback() {
+    this.#storageNs = this.id !== "" ? this.id : this.endpoint;
     this.#strings = mergeUiStrings({ ...this.#readStringOverrides(), ...this.strings });
+    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();
+    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() {
+    this.#cancelRun();
+    this.#attachTray?.dispose();
+    this.#voice?.dispose();
+  }
   /** Parse the inline `data-strings` JSON overrides (empty when absent/malformed). */
   #readStringOverrides() {
     const raw = this.getAttribute("data-strings");
@@ -5831,7 +6396,41 @@ var AgUiChat = class extends HTMLElement {
     if (url === null) {
       return null;
     }
-    return (file, onProgress) => uploadAttachment(file, { url, headers: this.headers, onProgress });
+    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() {
+    const url = this.getAttribute("data-transcribe-url");
+    const transcribe = this.transcribeHandler ?? this.#defaultTranscribeHandler(url);
+    if (transcribe === null) {
+      return;
+    }
+    this.#voice = new VoiceInput({
+      transcribe,
+      onText: (text2) => this.#insertVoiceText(text2),
+      strings: this.#strings
+    });
+    this.#voiceSlot.appendChild(this.#voice.element);
+  }
+  /** The built-in transcription handler for `data-transcribe-url`, or `null`. */
+  #defaultTranscribeHandler(url) {
+    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(text2) {
+    const current = this.#input.value.trim();
+    this.#input.value = current === "" ? text2 : `${current} ${text2}`;
+    this.#onInput();
+    this.#input.focus();
   }
   /** The client-side upload size cap from `data-attachment-max-bytes`. */
   #attachmentMaxBytes() {
@@ -6001,7 +6600,7 @@ Use the read_attachment tool with an id to read a file's contents.`
     } 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(TOGGLE_EVENT, {
@@ -6015,6 +6614,39 @@ Use the read_attachment tool with an id to read a file's contents.`
   toggleCollapsed() {
     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() {
+    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) {
+    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) {
+    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() {
+    const dark = this.getAttribute("theme") === "dark";
+    this.#themeToggle.textContent = dark ? "\u2600\uFE0F" : "\u{1F319}";
+  }
   /**
    * Start a fresh conversation: forget the persisted history, drop the
    * in-memory run state, clear the transcript, and mint a new thread id.
@@ -6031,6 +6663,7 @@ Use the read_attachment tool with an id to read a file's contents.`
     this.#client = null;
     this.#streamingBubble = null;
     this.#currentGroup = null;
+    this.#thoughts = null;
     this.#hidePending();
     this.#toolCards.clear();
     this.#serverSettled.clear();
@@ -6076,7 +6709,12 @@ Use the read_attachment tool with an id to read a file's contents.`
    * result from the page we landed on.
    */
   async #rehydrate() {
+    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) {
@@ -6163,7 +6801,7 @@ Use the read_attachment tool with an id to read a file's contents.`
    * 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).
    */
@@ -6230,7 +6868,18 @@ Use the read_attachment tool with an id to read a file's contents.`
     newChat.addEventListener("click", () => this.newChat());
     const collapse = this.#headerButton("collapse", this.#strings.collapse, "\u2014");
     collapse.addEventListener("click", () => this.toggleCollapsed());
-    controls.append(history, newChat, collapse);
+    controls.append(history, newChat);
+    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";
     this.#messages.setAttribute("part", "messages");
@@ -6282,9 +6931,10 @@ Use the read_attachment tool with an id to read a file's contents.`
     this.#fileInput.hidden = true;
     this.#fileInput.addEventListener("change", () => this.#onFilesPicked());
     this.#attachSlot.className = "attachment-slot";
+    this.#voiceSlot.className = "voice-slot";
     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);
     this.#chat.append(
       header,
       this.#messages,
@@ -6385,6 +7035,9 @@ Use the read_attachment tool with an id to read a file's contents.`
     this.#send.dataset["state"] = running ? "running" : "idle";
   }
   async #submit() {
+    if (this.#running) {
+      return;
+    }
     const content = this.#input.value.trim();
     const attachments = this.#attachTray?.readyRefs() ?? [];
     if (content === "" && attachments.length === 0) {
@@ -6509,8 +7162,18 @@ Use the read_attachment tool with an id to read a file's contents.`
         this.#ensureGroup();
         this.#showPending();
       },
+      onReasoningStart: () => {
+        this.#hidePending();
+        this.#showThoughts();
+      },
+      onReasoningDelta: (buffer) => {
+        this.#showThoughts().stream(buffer);
+      },
+      onReasoningEnd: () => {
+      },
       onTextDelta: (buffer) => {
         this.#hidePending();
+        this.#thoughts?.collapse();
         this.#streamInto(buffer);
         this.#streamDeltas += 1;
       },
@@ -6562,6 +7225,7 @@ Use the read_attachment tool with an id to read a file's contents.`
           this.#updateEmptyState();
         }
         this.#currentGroup = null;
+        this.#thoughts = null;
       }
     };
   }
@@ -6605,6 +7269,21 @@ Use the read_attachment tool with an id to read a file's contents.`
     this.#pending?.remove();
     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() {
+    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) {
     if (this.#streamingBubble === null) {
       this.#streamingBubble = this.appendMessage(MESSAGE_ROLE.ASSISTANT, "");
@@ -6676,7 +7355,7 @@ function setControlValue(el, value) {
 }
 
 // src/version.ts
-var VERSION = "0.8.1";
+var VERSION = "0.10.0";
 export {
   AgUiChat,
   AgUiClient,
@@ -6728,6 +7407,7 @@ export {
   setNativeValue,
   toggleCheckbox,
   toggleControl,
+  transcribeAudio,
   typeInto,
   uploadAttachment
 };