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

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/transcribe_audio.ts

@@ -0,0 +1,62 @@
+/**
+ * The composer's voice-transcription contract: take a recorded audio `Blob` and
+ * resolve to the transcript text. The built-in handler is {@link transcribeAudio}
+ * (multipart POST to `data-transcribe-url`); a host swaps in its own — e.g. a
+ * browser Web Speech adapter or a direct-to-provider call — via
+ * `AgUiChat.transcribeHandler`, without touching the mic button.
+ */
+export type TranscribeHandler = (audio: Blob) => Promise<string>;
+
+/** Options for {@link transcribeAudio}. */
+export interface TranscribeOptions {
+  /** The transcription endpoint (`data-transcribe-url`). */
+  readonly url: string;
+  /** Extra HTTP headers (CSRF / auth), read fresh per request. */
+  readonly headers?: Record<string, string>;
+}
+
+/**
+ * POST a recorded clip to the transcription endpoint and resolve to its text.
+ *
+ * The clip is sent as multipart under the `audio` field with the element's
+ * `headers`, mirroring {@link uploadAttachment}; the server replies
+ * `{ "text": "<transcript>" }`. A non-2xx response or a network error rejects so
+ * the mic button can surface the failure.
+ */
+export async function transcribeAudio(audio: Blob, options: TranscribeOptions): Promise<string> {
+  const form = new FormData();
+  // A filename hints the server/codec; the extension is cosmetic (the server
+  // reads the blob's content type).
+  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: unknown = await response.json();
+  if (
+    typeof body === "object" &&
+    body !== null &&
+    typeof (body as { text?: unknown }).text === "string"
+  ) {
+    return (body as { text: string }).text;
+  }
+  throw new Error("transcription returned an unreadable response");
+}
+
+/** A human-readable message from a non-2xx transcription response. */
+async function errorMessage(response: Response): Promise<string> {
+  try {
+    const body = (await response.json()) as { error?: unknown };
+    if (typeof body.error === "string") {
+      return body.error;
+    }
+  } catch {
+    // Non-JSON error body — fall through to the status code.
+  }
+  return `transcription failed (${response.status})`;
+}

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/index.ts

@@ -43,6 +43,11 @@ export {
 } from "./core/create_http_agent.js";
 export { defineAgUiChat } from "./core/define_ag_ui_chat.js";
 export { RemoteConversationStore } from "./core/remote_conversation_store.js";
+export {
+  type TranscribeHandler,
+  type TranscribeOptions,
+  transcribeAudio,
+} from "./core/transcribe_audio.js";
 export {
   type UploadHandler,
   type UploadOptions,

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,6 +553,69 @@ export const STYLES = `
   }
 }
 
+/* ── 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 {
+  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: "▾ ";
+}
+
+.thoughts-toggle[aria-expanded="false"]::before {
+  content: "▸ ";
+}
+
+/* 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%;
@@ -583,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;
@@ -631,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"] {
@@ -761,6 +824,49 @@ export const STYLES = `
   display: none;
 }
 
+/* The 🎤 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;

package/src/ui/thoughts_block.ts

@@ -0,0 +1,83 @@
+import { DEFAULT_UI_STRINGS, type UiStrings } from "./ui_strings.js";
+
+/**
+ * A muted, collapsible "thinking" region for a reasoning model's streamed
+ * chain-of-thought.
+ *
+ * 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.
+ * The header toggle lets the reader reopen it.
+ *
+ * Pure DOM (no framework); the host inserts {@link element} and themes it via
+ * the `--ag-ui-*` custom properties or the `thoughts*` `part`s. All visible
+ * chrome text is sourced from {@link UiStrings}.
+ */
+export class ThoughtsBlock {
+  /** The block's root element; insert this at the top of the answer group. */
+  readonly element: HTMLDivElement;
+
+  readonly #label: HTMLSpanElement;
+  readonly #body: HTMLPreElement;
+  readonly #toggle: HTMLButtonElement;
+  readonly #strings: UiStrings;
+  #collapsed = false;
+
+  constructor(strings: UiStrings = DEFAULT_UI_STRINGS) {
+    this.#strings = strings;
+
+    this.element = document.createElement("div");
+    this.element.className = "thoughts";
+    this.element.setAttribute("part", "thoughts");
+    // `data-streaming` lets CSS animate the header (e.g. a pulse) while the
+    // model is still reasoning; dropped on collapse.
+    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: string): void {
+    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(): void {
+    if (this.#collapsed) {
+      return;
+    }
+    this.element.removeAttribute("data-streaming");
+    this.#label.textContent = this.#strings.thoughts;
+    this.#setCollapsed(true);
+  }
+
+  #setCollapsed(collapsed: boolean): void {
+    this.#collapsed = collapsed;
+    this.#body.hidden = collapsed;
+    this.#toggle.setAttribute("aria-expanded", String(!collapsed));
+  }
+}

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];