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

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

@@ -168,6 +168,20 @@ export const STYLES = `
   padding-inline: max(12px, calc((100% - var(--ag-ui-content-max-width)) / 2));
 }
 
+/* The rows between the message list and the composer (skill chips, the
+   /-command palette, the missing-placeholder hint, the upload tray) line up
+   with the column too — chips are padding-based, the palette/hint/tray are
+   margin-based, so each gets its own inline axis nudged by the same gutter. */
+:host([placement="page"]) .skill-chips,
+:host([placement="page"]) .attachment-tray {
+  padding-inline: max(12px, calc((100% - var(--ag-ui-content-max-width)) / 2));
+}
+
+:host([placement="page"]) .skill-palette,
+:host([placement="page"]) .skill-hint {
+  margin-inline: max(12px, calc((100% - var(--ag-ui-content-max-width)) / 2));
+}
+
 /* In the reading column the assistant well uses the full width; the user
    message stays a right-aligned pill (its default align-self + max-width). */
 :host([placement="page"]) .message--assistant {
@@ -539,6 +553,69 @@ export const STYLES = `
   }
 }
 
+/* ── Thoughts region (THINK-1) ────────────────────────────────────────────
+   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%;
@@ -747,6 +824,49 @@ export const STYLES = `
   display: none;
 }
 
+/* The 🎤 mic button (VOICE-1); 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 (THINK-1).
+ *
+ * Lives at the top of the current answer group (the WELL-1 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/ui_strings.ts

@@ -26,12 +26,17 @@ export interface UiStrings {
   collapse: string;
   /** Expand affordance (the sidebar rail toggle). */
   expand: string;
+  /** Built-in header theme toggle (light ⇄ dark). */
+  toggleTheme: string;
 
   // ── Messages region ─────────────────────────────────────────────────────────
   /** `aria-label` of the scrolling message log. */
   conversation: string;
-  /** `aria-label` of the "thinking" pending indicator. */
+  /** `aria-label` of the "thinking" pending indicator, and the thoughts region's
+   * header while the model is still reasoning. */
   thinking: string;
+  /** The thoughts region's header once reasoning has streamed (collapsed label). */
+  thoughts: string;
   /** The muted note after a cancelled run. */
   stopped: string;
   /** Error shown when the stream drops without a terminal AG-UI event. */
@@ -56,6 +61,14 @@ export interface UiStrings {
   stop: string;
   /** Attach-files button. */
   attachFiles: string;
+  /** Mic button while idle (start recording). */
+  recordVoice: string;
+  /** Mic button while recording (stop + transcribe). */
+  stopRecording: string;
+  /** Mic button while the clip is being transcribed. */
+  transcribing: string;
+  /** Mic button fallback message when transcription fails. */
+  transcriptionFailed: string;
 
   // ── Tool-call card ──────────────────────────────────────────────────────────
   /** Status pill while the call runs. */
@@ -137,9 +150,11 @@ export const DEFAULT_UI_STRINGS: UiStrings = {
   newChat: "New chat",
   collapse: "Collapse",
   expand: "Expand",
+  toggleTheme: "Toggle theme",
 
   conversation: "Conversation",
   thinking: "Assistant is thinking…",
+  thoughts: "Thoughts",
   stopped: "⏹ Stopped",
   connectionLost: "Connection lost",
   noResult: "No result returned.",
@@ -152,6 +167,10 @@ export const DEFAULT_UI_STRINGS: UiStrings = {
   send: "Send",
   stop: "Stop",
   attachFiles: "Attach files",
+  recordVoice: "Record voice",
+  stopRecording: "Stop recording",
+  transcribing: "Transcribing…",
+  transcriptionFailed: "Transcription failed",
 
   toolRunning: "running…",
   toolDone: "✓ done",

package/src/ui/voice_input.ts

@@ -0,0 +1,149 @@
+import type { TranscribeHandler } from "../core/transcribe_audio.js";
+import { DEFAULT_UI_STRINGS, type UiStrings } from "./ui_strings.js";
+
+/** Lifecycle of the mic button, reflected on its `data-state` for CSS. */
+type VoiceState = "idle" | "recording" | "transcribing";
+
+/** Construction options for {@link VoiceInput}. */
+export interface VoiceInputOptions {
+  /** Turns a recorded clip into text (the built-in or a custom transport). */
+  readonly transcribe: TranscribeHandler;
+  /** Called with the transcript when a recording transcribes successfully. */
+  readonly onText: (text: string) => void;
+  /** UI string table (labels/tooltips). */
+  readonly strings?: UiStrings;
+}
+
+/**
+ * The composer's voice-input control (VOICE-1): a mic button that records via
+ * `MediaRecorder`, then POSTs the clip through a {@link TranscribeHandler} and
+ * hands the transcript back via `onText`.
+ *
+ * Click to start recording (browser mic permission prompt), click again to stop
+ * — the clip is transcribed and dropped into the composer. The button reflects
+ * its `idle` / `recording` / `transcribing` state on `data-state` for theming
+ * and is exposed as `part="voice-button"`. A capture or transcription failure
+ * returns the button to idle and surfaces the message on its tooltip.
+ *
+ * Pure DOM (no framework); the host mounts {@link element} in the input row.
+ */
+export class VoiceInput {
+  /** The mic button; mount this in the composer. */
+  readonly element: HTMLButtonElement;
+
+  readonly #transcribe: TranscribeHandler;
+  readonly #onText: (text: string) => void;
+  readonly #strings: UiStrings;
+  #state: VoiceState = "idle";
+  #recorder: MediaRecorder | null = null;
+  #stream: MediaStream | null = null;
+  #chunks: Blob[] = [];
+
+  constructor(options: VoiceInputOptions) {
+    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 = "🎤";
+    this.#setState("idle");
+    this.element.addEventListener("click", () => {
+      void this.toggle();
+    });
+  }
+
+  /** Start recording when idle, stop (and transcribe) when recording. */
+  async toggle(): Promise<void> {
+    if (this.#state === "recording") {
+      this.#stop();
+      return;
+    }
+    if (this.#state === "transcribing") {
+      return;
+    }
+    await this.#start();
+  }
+
+  async #start(): Promise<void> {
+    let stream: MediaStream;
+    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(): void {
+    // ``stop`` flushes a final ``dataavailable`` then fires ``stop`` → #finish.
+    this.#recorder?.stop();
+  }
+
+  async #finish(mimeType: string): Promise<void> {
+    this.#releaseStream();
+    this.#setState("transcribing");
+    const audio = new Blob(this.#chunks, { type: mimeType || "audio/webm" });
+    try {
+      const text = await this.#transcribe(audio);
+      this.#setState("idle");
+      if (text !== "") {
+        this.#onText(text);
+      }
+    } 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(): void {
+    for (const track of this.#stream?.getTracks() ?? []) {
+      track.stop();
+    }
+    this.#stream = null;
+  }
+
+  #fail(message: string): void {
+    this.#releaseStream();
+    this.#recorder = null;
+    this.#setState("idle");
+    this.element.title = message;
+  }
+
+  #setState(state: VoiceState): void {
+    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"));
+    // The control is inert while a clip transcribes (no second recording yet).
+    this.element.disabled = state === "transcribing";
+  }
+
+  #labelFor(state: VoiceState): string {
+    if (state === "recording") {
+      return this.#strings.stopRecording;
+    }
+    if (state === "transcribing") {
+      return this.#strings.transcribing;
+    }
+    return this.#strings.recordVoice;
+  }
+}

package/src/version.ts

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