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

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) {

package/src/core/remote_conversation_store.ts

@@ -96,7 +96,13 @@ export class RemoteConversationStore implements ClientConversationStore {
     if (response === null || !response.ok) {
       return this.#local.loadMessages(threadId);
     }
-    const body = (await response.json()) as { messages?: readonly Message[] };
+    // A 200 whose body isn't the expected JSON (a proxy's HTML error page, a
+    // truncated stream) must not throw an unhandled rejection that the caller's
+    // `void #rehydrate()` swallows — fall back to the local cache instead.
+    const body = await this.#readJson<{ messages?: readonly Message[] }>(response);
+    if (body === null) {
+      return this.#local.loadMessages(threadId);
+    }
     return body.messages ?? null;
   }
 
@@ -105,15 +111,30 @@ export class RemoteConversationStore implements ClientConversationStore {
     if (response === null || !response.ok) {
       return null;
     }
-    const body = (await response.json()) as { threads?: readonly ServerThreadRow[] };
+    const body = await this.#readJson<{ threads?: readonly ServerThreadRow[] }>(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<T>(response: Response): Promise<T | null> {
+    try {
+      return (await response.json()) as T;
+    } catch {
+      return null;
+    }
+  }
+
   #toMeta(row: ServerThreadRow): ThreadMeta {
     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,
     };
   }

package/src/core/upload_attachment.ts

@@ -7,10 +7,17 @@ import type { AttachmentRef } from "./attachment.js";
  * `tus-js-client` or direct-to-S3 adapter — via `AgUiChat.uploadHandler`,
  * **without** touching the tray, the chips, or the AG-UI wire (refs are
  * transport-agnostic).
+ *
+ * The optional third `signal` argument lets the tray abort an in-flight upload
+ * when its chip is removed (or the element is torn down), so a cancelled upload
+ * doesn't orphan a server-side file. It is non-breaking: existing two-argument
+ * handlers keep working (the extra argument is simply ignored), and a custom
+ * handler that honours it should abort its own transport when the signal fires.
  */
 export type UploadHandler = (
   file: File,
   onProgress: (fraction: number) => void,
+  signal?: AbortSignal,
 ) => Promise<AttachmentRef>;
 
 /** Options for {@link uploadAttachment}. */
@@ -22,7 +29,7 @@ export interface UploadOptions {
   /** Progress callback, `0..1`, fired as the body uploads. */
   readonly onProgress?: (fraction: number) => void;
   /** Abort signal to cancel the in-flight upload. */
-  readonly signal?: AbortSignal;
+  readonly signal?: AbortSignal | undefined;
 }
 
 /**

package/src/ui/attachment_tray.ts

@@ -30,6 +30,8 @@ interface TrayItem {
   progress: number;
   ref: AttachmentRef | null;
   error: string;
+  /** Aborts the in-flight upload when the chip is removed / the tray cleared. */
+  controller: AbortController | null;
 }
 
 /**
@@ -68,6 +70,7 @@ export class AttachmentTray {
       progress: 0,
       ref: null,
       error: "",
+      controller: null,
     };
     this.#items.push(item);
     const rejection = this.#reject(file);
@@ -110,12 +113,26 @@ export class AttachmentTray {
     this.#render();
   }
 
-  /** Drop every chip (a reset / new-chat). */
+  /** Drop every chip (a reset / new-chat), aborting any in-flight upload. */
   clear(): void {
+    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(): void {
+    for (const item of this.#items) {
+      item.controller?.abort();
+    }
+  }
+
   /** The size/type rejection reason for a file, or `null` when accepted. */
   #reject(file: File): string | null {
     if (this.#config.maxBytes > 0 && file.size > this.#config.maxBytes) {
@@ -128,15 +145,32 @@ export class AttachmentTray {
   }
 
   #upload(item: TrayItem): void {
+    // Re-apply the client guard on every attempt, not just the first `add` — an
+    // ERROR chip always renders retry, so without this a size/type-rejected file
+    // would upload in full on ↻.
+    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();
-      })
+      .upload(
+        item.file,
+        (fraction) => {
+          item.progress = fraction;
+          this.#render();
+        },
+        controller.signal,
+      )
       .then((ref) => {
         item.status = ATTACHMENT_STATUS.READY;
         item.ref = ref;
@@ -146,12 +180,15 @@ export class AttachmentTray {
         item.error = error instanceof Error ? error.message : this.#strings.uploadFailed;
       })
       .finally(() => {
+        item.controller = null;
         this.#render();
         this.#config.onChange?.();
       });
   }
 
   #remove(item: TrayItem): void {
+    // Abort an in-flight upload so removing its chip doesn't orphan the file.
+    item.controller?.abort();
     this.#items = this.#items.filter((other) => other !== item);
     this.#render();
     this.#config.onChange?.();

package/src/ui/relative_time.ts

@@ -6,15 +6,20 @@ import { DEFAULT_UI_STRINGS, type UiStrings } from "./ui_strings.js";
  *
  * `now` is injectable so callers (and tests) can pin the reference point; it
  * defaults to the current time. A timestamp in the future (clock skew) reads as
- * `"just now"`. The unit words come from {@link UiStrings} (the `{n}` token is
- * filled in here) so a localized host translates them; the bucketing stays
- * integer-rounded and locale-neutral.
+ * `"just now"`. A non-finite timestamp — an unparseable or missing `updated_at`
+ * that arrived as `NaN` — has no meaningful age, so it falls back to `justNow`
+ * rather than rendering `"NaNw ago"` or `"~2950w ago"`. The unit words come from
+ * {@link UiStrings} (the `{n}` token is filled in here) so a localized host
+ * translates them; the bucketing stays integer-rounded and locale-neutral.
  */
 export function relativeTime(
   timestamp: number,
   now: number = Date.now(),
   strings: UiStrings = DEFAULT_UI_STRINGS,
 ): string {
+  if (!Number.isFinite(timestamp)) {
+    return strings.justNow;
+  }
   const seconds = Math.round((now - timestamp) / 1000);
   if (seconds < 60) {
     return strings.justNow;

package/src/ui/styles.ts

@@ -146,7 +146,7 @@ export const 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
@@ -188,7 +188,7 @@ export const 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 — set
    --ag-ui-position: static (and place this element in your own layout) for a
@@ -298,7 +298,7 @@ export const 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;
@@ -372,7 +372,7 @@ export const 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;
@@ -384,7 +384,7 @@ export const STYLES = `
   display: none;
 }
 
-/* ── Answer group / well (WELL-1) ─────────────────────────────────────────
+/* ── Answer group / well ─────────────────────────────────────────
    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
@@ -553,7 +553,7 @@ export const STYLES = `
   }
 }
 
-/* ── Thoughts region (THINK-1) ────────────────────────────────────────────
+/* ── Thoughts region ────────────────────────────────────────────
    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 {
@@ -646,7 +646,7 @@ export const STYLES = `
   word-break: break-word;
 }
 
-/* Leading status icon (CARD-1). Empty in the DOM — the glyph/spinner is drawn
+/* Leading status icon. Empty in the DOM — the glyph/spinner is drawn
    here from the card's data-status, so it stays themeable. */
 .tool-call-icon {
   flex: none;
@@ -694,7 +694,7 @@ export const STYLES = `
   }
 }
 
-/* Inline display mode (CARD-1): the lightest card — drop the box chrome so the
+/* Inline display mode: the lightest card — 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"] {
@@ -824,7 +824,7 @@ export const STYLES = `
   display: none;
 }
 
-/* The 🎤 mic button (VOICE-1); shown only once #wireVoice mounts it. */
+/* The 🎤 mic button; shown only once #wireVoice mounts it. */
 .voice-slot {
   display: contents;
 }

package/src/ui/thoughts_block.ts

@@ -2,9 +2,9 @@ import { DEFAULT_UI_STRINGS, type UiStrings } from "./ui_strings.js";
 
 /**
  * A muted, collapsible "thinking" region for a reasoning model's streamed
- * chain-of-thought (THINK-1).
+ * chain-of-thought.
  *
- * Lives at the top of the current answer group (the WELL-1 turn container): it
+ * Lives at the top of the current answer group (the turn container): it
  * opens expanded while the model reasons — {@link stream} replaces its body with
  * the running reasoning buffer — and {@link collapse} folds it away once the
  * answer's first text token arrives, so the thoughts don't crowd the answer.

package/src/ui/thread_drawer.ts

@@ -37,6 +37,8 @@ export class ThreadDrawer {
   #strings: UiStrings;
   #threads: readonly ThreadMeta[] = [];
   #activeId = "";
+  /** The element focused before the drawer opened, restored on close. */
+  #lastFocused: HTMLElement | null = null;
 
   constructor(callbacks: ThreadDrawerCallbacks, strings: UiStrings = DEFAULT_UI_STRINGS) {
     this.#callbacks = callbacks;
@@ -56,7 +58,10 @@ export class ThreadDrawer {
     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);
+    // Escape closes the drawer; Tab is trapped within the panel while it's open.
+    this.#panel.addEventListener("keydown", (event) => this.#onPanelKeydown(event));
 
     const header = document.createElement("div");
     header.className = "drawer-header";
@@ -98,15 +103,61 @@ export class ThreadDrawer {
   }
 
   open(): void {
+    if (this.isOpen()) {
+      return;
+    }
+    // Remember what had focus so it's restored on close, then move focus into
+    // the panel (its first control) so keyboard users land inside the dialog.
+    this.#lastFocused = this.#activeElement() as HTMLElement | null;
     this.element.hidden = false;
+    this.#newButton.focus();
   }
 
   close(): void {
+    if (!this.isOpen()) {
+      return;
+    }
     this.element.hidden = true;
+    this.#lastFocused?.focus();
+    this.#lastFocused = null;
   }
 
   toggle(): void {
-    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(): Element | null {
+    return (this.element.getRootNode() as Document | ShadowRoot).activeElement;
+  }
+
+  /** Escape-to-close and a Tab focus trap while the dialog is open. */
+  #onPanelKeydown(event: KeyboardEvent): void {
+    if (event.key === "Escape") {
+      event.preventDefault();
+      this.close();
+      return;
+    }
+    if (event.key !== "Tab") {
+      return;
+    }
+    const focusables = Array.from(
+      this.#panel.querySelectorAll<HTMLElement>("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. */
@@ -182,24 +233,47 @@ export class ThreadDrawer {
     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: HTMLDivElement, meta: ThreadMeta): void {
     const input = document.createElement("input");
     input.type = "text";
     input.className = "drawer-rename-input";
     input.value = meta.title;
+    // One-shot: Enter, Escape, and blur can all fire for a single edit (Enter
+    // commits and re-renders, which blurs the detached input); the flag makes
+    // the later events no-ops so a rename isn't submitted twice.
+    let done = false;
+    const commit = (): void => {
+      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 = (): void => {
+      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();
+        // Stop the panel's Escape handler from also closing the drawer.
+        event.preventDefault();
+        event.stopPropagation();
+        cancel();
       }
     });
+    input.addEventListener("blur", () => commit());
     row.replaceChildren(input);
     input.focus();
     input.select();

package/src/ui/tool_call_card.ts

@@ -126,6 +126,12 @@ export class ToolCallCard {
    * `inline`), or the args + result together (`compact`).
    */
   settle(status: SettledStatus, text: string): void {
+    // Idempotent: a duplicate `TOOL_CALL_RESULT`, or a replayed tool message
+    // for an already-settled card, must not append a second toggle+body. The
+    // first settle wins; later calls are ignored.
+    if (this.#settled) {
+      return;
+    }
     this.#settled = true;
     this.element.setAttribute("data-status", status);
     this.#status.textContent = statusLabels(this.#strings)[status];

package/src/ui/voice_input.ts

@@ -15,7 +15,7 @@ export interface VoiceInputOptions {
 }
 
 /**
- * The composer's voice-input control (VOICE-1): a mic button that records via
+ * The composer's voice-input control: a mic button that records via
  * `MediaRecorder`, then POSTs the clip through a {@link TranscribeHandler} and
  * hands the transcript back via `onText`.
  *
@@ -38,6 +38,7 @@ export class VoiceInput {
   #recorder: MediaRecorder | null = null;
   #stream: MediaStream | null = null;
   #chunks: Blob[] = [];
+  #disposed = false;
 
   constructor(options: VoiceInputOptions) {
     this.#transcribe = options.transcribe;
@@ -94,7 +95,26 @@ export class VoiceInput {
     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(): void {
+    this.#disposed = true;
+    if (this.#recorder !== null && this.#recorder.state !== "inactive") {
+      this.#recorder.stop();
+    }
+    this.#recorder = null;
+    this.#releaseStream();
+  }
+
   async #finish(mimeType: string): Promise<void> {
+    if (this.#disposed) {
+      return;
+    }
     this.#releaseStream();
     this.#setState("transcribing");
     const audio = new Blob(this.#chunks, { type: mimeType || "audio/webm" });

package/src/version.ts

@@ -1 +1 @@
-export const VERSION: string = "0.9.0";
+export const VERSION: string = "0.10.0";