@artooi/ag-ui-web-component 0.20.1 → 0.22.0

package/src/core/ag_ui_chat.ts

@@ -3,6 +3,10 @@ import {
   ATTACHMENT_EVENT,
   COMPACTION_ACTIVITY_TYPE,
   DEFAULT_ATTACHMENT_MAX_BYTES,
+  ICON_ATTACH,
+  ICON_LAUNCHER,
+  ICON_SEND,
+  ICON_STOP,
   LOAD_CAPABILITY_TOOL,
   MESSAGE_ROLE,
   READ_PAGE_TOOL,
@@ -11,6 +15,7 @@ import {
   TOGGLE_EVENT,
   TOOL_CALL_STATUS,
   TOOL_DISPLAY,
+  UNREAD_EVENT,
   X_CONFIRM_KEY,
   X_SUMMARY_KEY,
 } from "../constants.js";
@@ -75,6 +80,7 @@ import { RemoteConversationStore } from "./remote_conversation_store.js";
 import { RunIndex } from "./run_index.js";
 import { type TranscribeHandler, transcribeAudio } from "./transcribe_audio.js";
 import { type UploadHandler, uploadAttachment } from "./upload_attachment.js";
+import { withCredentials } from "./utils.js";
 
 /** The role a rendered chat message takes. */
 export type MessageRole = (typeof MESSAGE_ROLE)[keyof typeof MESSAGE_ROLE];
@@ -104,6 +110,11 @@ export interface ToggleDetail {
   readonly collapsed: boolean;
 }
 
+/** `detail` shape of the {@link UNREAD_EVENT} CustomEvent. */
+export interface UnreadDetail {
+  readonly unread: number;
+}
+
 /**
  * Attributes read once while connecting, to decide what chrome exists at all.
  *
@@ -133,6 +144,18 @@ const CONNECT_TIME_ATTRIBUTES = [
   "data-icon-url",
 ] as const;
 
+/**
+ * The cookie policies `fetch` accepts. Anything else is a configuration
+ * mistake, and one that would otherwise surface as an unexplained 401 from a
+ * request the browser silently sent anonymously.
+ */
+const CREDENTIALS_MODES: readonly string[] = ["omit", "same-origin", "include"];
+
+/** Whether `value` is one of the three modes `fetch` understands. */
+function isCredentialsMode(value: string): value is RequestCredentials {
+  return CREDENTIALS_MODES.includes(value);
+}
+
 /** Per-tab persistence key for the collapsed state (survives MPA reloads). */
 const COLLAPSED_KEY = "ag-ui-chat:collapsed";
 
@@ -158,9 +181,34 @@ export class AgUiChat extends HTMLElement {
   /** Agent factory; override to inject a custom or fake agent (tests). */
   agentFactory: AgentFactory = createHttpAgent;
 
-  /** Extra HTTP headers for the AG-UI endpoint (e.g. CSRF). */
+  /**
+   * Static extra HTTP headers, sent with **every** request this element makes —
+   * the agent run, the thread index and its messages, the tool and skill
+   * catalogs, the run index, uploads and transcription.
+   *
+   * Right for values fixed for the element's lifetime. A credential that
+   * rotates (a short-lived JWT, a re-issued CSRF token) belongs in
+   * {@link getHeaders} instead: this is read at request time, but only a
+   * re-assignment updates it, so a token captured here is pinned until the host
+   * remembers to assign again.
+   */
   headers: Record<string, string> = {};
 
+  /**
+   * Live header source, consulted immediately before every request — the way to
+   * supply rotating credentials.
+   *
+   * Set it to a function and each request calls it afresh: a token refreshed by
+   * the host between two requests reaches the second one, with nothing to
+   * re-assign and nothing to keep in sync.
+   *
+   * Composes with {@link headers} rather than replacing it: the two are merged
+   * per key with `getHeaders()` winning, so a static `X-Client` and a rotating
+   * `Authorization` can be configured independently and neither silently drops
+   * the other.
+   */
+  getHeaders: (() => Record<string, string>) | null = null;
+
   /**
    * Permit `<img>` in rendered assistant markdown. **Off by default**: a
    * model-controlled image URL is fetched with no user interaction, which
@@ -366,8 +414,12 @@ export class AgUiChat extends HTMLElement {
   readonly #attachSlot: HTMLDivElement;
   /** Optional built-in header theme toggle; shown only with `data-theme-toggle`. */
   readonly #themeToggle: HTMLButtonElement;
-  /** The collapsed-sidebar rail (an expand affordance; shown only for `placement="sidebar"`). */
-  readonly #rail: HTMLButtonElement;
+  /** What the collapsed widget shrinks to: the floating launcher, or the sidebar rail. */
+  readonly #launcher: HTMLButtonElement;
+  /** The launcher's unread badge; hidden at zero, and when the host opts out. */
+  readonly #badge: HTMLSpanElement;
+  // Answers that finished while the widget was collapsed. Expanding clears it.
+  #unread = 0;
   /** Empty-state region at the top of the message list; hidden once anything renders. */
   readonly #emptyWrap: HTMLDivElement;
   /** Upload tray; created on connect only when `data-attachments-url` is set. */
@@ -443,7 +495,8 @@ export class AgUiChat extends HTMLElement {
     this.#attachSlot = document.createElement("div");
     this.#voiceSlot = document.createElement("span");
     this.#themeToggle = document.createElement("button");
-    this.#rail = document.createElement("button");
+    this.#launcher = document.createElement("button");
+    this.#badge = document.createElement("span");
     this.#emptyWrap = document.createElement("div");
     this.#skillsMenu = new SkillsMenu((skill) => this.#applySkill(skill));
     this.#drawer = new ThreadDrawer({
@@ -474,7 +527,11 @@ export class AgUiChat extends HTMLElement {
       return null;
     }
     if (this.#runIndex === null) {
-      this.#runIndex = new RunIndex(url, () => this.headers);
+      this.#runIndex = new RunIndex(
+        url,
+        () => this.#requestHeaders(),
+        () => this.#requestCredentials(),
+      );
     }
     return this.#runIndex;
   }
@@ -504,11 +561,13 @@ export class AgUiChat extends HTMLElement {
       return;
     }
     this.#input.value = "";
+    this.#autoGrow();
     const endpoint = verb === "resume" ? index.resumeUrl(runId) : index.forkUrl(runId);
     const agent = this.agentFactory({
       endpoint,
-      headers: this.headers,
-      getHeaders: () => this.headers,
+      headers: this.#requestHeaders(),
+      getHeaders: () => this.#requestHeaders(),
+      ...this.#credentialsOption(),
       threadId: this.#threadId,
       // The seed the endpoints assume: nothing. The snapshot is the history.
       initialMessages: [],
@@ -533,10 +592,24 @@ export class AgUiChat extends HTMLElement {
 
   /** Attributes the element reacts to after it has been connected. */
   static get observedAttributes(): string[] {
-    return ["title-text", "placement", ...CONNECT_TIME_ATTRIBUTES];
+    return ["title-text", "placement", "credentials", ...CONNECT_TIME_ATTRIBUTES];
   }
 
   attributeChangedCallback(name: string, previous: string | null, value: string | null): void {
+    if (name === "credentials") {
+      // Reported the moment the attribute is written — before connect, and
+      // whether it came from markup or the property setter. An unrecognised
+      // mode is otherwise inert, and the request it was meant to authorise
+      // goes out anonymously with nothing to show for it.
+      if (value !== null && !isCredentialsMode(value)) {
+        console.error(
+          `<ag-ui-chat>: credentials="${value}" is not a fetch credentials mode ` +
+            `(${CREDENTIALS_MODES.join(" / ")}) — it is being ignored, so requests use ` +
+            "the browser default and cross-origin cookies will not be sent.",
+        );
+      }
+      return;
+    }
     if (name === "placement") {
       // A placement owns the axes it fixes, so hand those back before anything
       // else: a size dragged under the previous placement would otherwise sit
@@ -777,6 +850,82 @@ export class AgUiChat extends HTMLElement {
     this.setAttribute("endpoint", value);
   }
 
+  /**
+   * Cookie policy for **every** request this element makes, as `fetch`'s own
+   * `credentials` mode (`"omit"` / `"same-origin"` / `"include"`). Mirrored to
+   * the `credentials` attribute, so markup embeds can set it without script.
+   *
+   * `null` (the default) leaves the browser's default of `same-origin` in
+   * place. That default sends **no cookies at all** when the endpoints live on
+   * a different origin from the page — app.example.com calling
+   * api.example.com is cross-origin — and the request goes out anonymously
+   * rather than failing, so the symptom is a 401 from a server that looks
+   * correctly configured. A cookie-authenticated cross-origin deployment wants
+   * `"include"`, plus `Access-Control-Allow-Credentials: true` and a concrete
+   * (non-wildcard) `Access-Control-Allow-Origin` on the server.
+   *
+   * Read per request, so a late assignment applies to everything after it.
+   * `"omit"` cannot be honoured by the built-in **upload** transport, which is
+   * an `XMLHttpRequest` and only has a two-state cookie switch; every other
+   * endpoint honours all three modes.
+   */
+  get credentials(): RequestCredentials | null {
+    const attr = this.getAttribute("credentials");
+    return attr !== null && isCredentialsMode(attr) ? attr : null;
+  }
+
+  set credentials(value: RequestCredentials | null) {
+    if (value === null) {
+      this.removeAttribute("credentials");
+      return;
+    }
+    // Thrown, not warned: an unrecognised mode is inert at request time, and
+    // the whole failure this option exists to fix is a request that goes out
+    // wrong without saying so. Fail where the mistake was made instead.
+    if (!isCredentialsMode(value)) {
+      throw new TypeError(
+        `<ag-ui-chat>: credentials must be one of ${CREDENTIALS_MODES.map((mode) => `"${mode}"`).join(", ")} ` +
+          `(got ${JSON.stringify(value)}).`,
+      );
+    }
+    this.setAttribute("credentials", value);
+  }
+
+  /**
+   * The headers for the request about to go out: the static {@link headers}
+   * with {@link getHeaders}'s live values overlaid, per key.
+   *
+   * Every request site goes through here, so "how this element authenticates"
+   * is one answer rather than one per endpoint.
+   */
+  #requestHeaders(): Record<string, string> {
+    return { ...this.headers, ...this.getHeaders?.() };
+  }
+
+  /** The configured cookie policy as `fetch` spells it; `undefined` when unset. */
+  #requestCredentials(): RequestCredentials | undefined {
+    return this.credentials ?? undefined;
+  }
+
+  /**
+   * The `credentials` entry for an {@link AgentFactory} call, or nothing at all.
+   *
+   * Spread rather than assigned: `exactOptionalPropertyTypes` rejects an
+   * explicit `credentials: undefined`, and a factory should see the field
+   * absent — not present-and-empty — when no policy is configured. The agent
+   * reads it when it is built (first send, thread switch, continuation), by
+   * which time any host configuration has landed.
+   */
+  #credentialsOption(): { credentials?: RequestCredentials } {
+    const credentials = this.#requestCredentials();
+    return credentials === undefined ? {} : { credentials };
+  }
+
+  /** The `fetch` init for the element's own plain GETs (catalogs). */
+  #fetchInit(): RequestInit | undefined {
+    return withCredentials({ headers: this.#requestHeaders() }, this.#requestCredentials());
+  }
+
   /**
    * How much detail tool-call cards show, from the `data-tool-display`
    * attribute (`minimal` / `inline` / `compact` / `full`). Defaults to `full`.
@@ -831,9 +980,8 @@ export class AgUiChat extends HTMLElement {
     if (this.#readScopedItem(COLLAPSED_KEY) === "1") {
       this.setAttribute("collapsed", "");
     }
-    this.#syncRail();
+    this.#syncLauncher();
     this.#initSkills();
-    void this.#fetchToolCatalog();
     // Namespace the built-in default store too (a host-injected store is used
     // verbatim). Must precede #wireThreadStore, which wraps the current store.
     if (this.#storageNs !== "" && this.conversationStore instanceof SessionStorageStore) {
@@ -843,12 +991,72 @@ export class AgUiChat extends HTMLElement {
     this.#wireAttachments();
     this.#wireVoice();
     this.#threadId = this.conversationStore.threadId();
+    // The catalog requests go out a microtask later, so a host configuring
+    // through a framework ref still has a chance to be heard — see #startup.
+    queueMicrotask(() => this.#startup());
     void this.#rehydrate();
     // Last: everything above reads (and some of it sets) attributes, and none
     // of that should trip the connect-time warning.
     this.#connected = true;
   }
 
+  /**
+   * The catalog requests the element issues on startup: the tool labels
+   * (`data-tools-url`) and the backend skills (`data-skills-url`).
+   *
+   * Deliberately one microtask behind `connectedCallback`. A host that
+   * configures the element through a framework ref necessarily does so *after*
+   * inserting the node — React attaches refs and runs layout effects in the
+   * same commit as the insertion, but strictly afterwards — so a request issued
+   * from `connectedCallback` itself goes out before `headers`,
+   * {@link getHeaders} or {@link credentials} exist, and comes back 401 in a
+   * way that reads as a server fault rather than a mis-timed assignment. A
+   * microtask lands after that commit and still before paint.
+   *
+   * Two things it is **not**. It is not a fix for configuration that arrives
+   * later than the commit (a passive `useEffect`, an awaited token fetch):
+   * configure before insertion (`createElement` → configure → `append`) or call
+   * {@link reload} once configured, because a longer timer would hide that race
+   * rather than close it. And it deliberately excludes the *history* replay,
+   * which stays in `connectedCallback`: the replay renders into the transcript,
+   * so deferring it lets a `sendMessage()` issued in the same task land first
+   * and the replay then duplicate it. The thread history is therefore the one
+   * request that can still go out before a ref is attached — {@link reload}
+   * covers it.
+   */
+  #startup(): void {
+    // An element can be inserted and removed inside one task (a discarded
+    // render, a double-mount); nothing should go out for a node that has
+    // already left the document.
+    if (!this.#connected) {
+      return;
+    }
+    void this.#fetchToolCatalog();
+    void this.#fetchSkills();
+  }
+
+  /**
+   * Re-run everything the element loads on startup — the tool-label catalog,
+   * the backend skill catalog and the thread's history — with the transport
+   * configuration as it stands now.
+   *
+   * This is the answer for a host that can only configure the element after the
+   * fact (a token fetched in a passive effect, an async auth handshake): the
+   * startup requests already went out with whatever was set then, and this says
+   * "try again, properly authenticated" without removing and re-inserting the
+   * node.
+   *
+   * A reload, not a merge — the in-flight run is cancelled and the transcript
+   * is rebuilt from the persisted history, so anything streamed since is
+   * dropped. Call it once, when configuration lands; not between turns.
+   */
+  async reload(): Promise<void> {
+    this.#cancelRun();
+    this.#resetState();
+    this.#setRunning(false);
+    await Promise.all([this.#fetchToolCatalog(), this.#fetchSkills(), 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,
@@ -940,7 +1148,13 @@ export class AgUiChat extends HTMLElement {
     // Forward the tray's abort signal so removing a chip (or tearing the
     // element down) cancels the XHR.
     return (file, onProgress, signal) =>
-      uploadAttachment(file, { url, headers: this.headers, onProgress, signal });
+      uploadAttachment(file, {
+        url,
+        headers: this.#requestHeaders(),
+        ...this.#credentialsOption(),
+        onProgress,
+        signal,
+      });
   }
 
   /**
@@ -969,7 +1183,12 @@ export class AgUiChat extends HTMLElement {
     if (url === null) {
       return null;
     }
-    return (audio) => transcribeAudio(audio, { url, headers: this.headers });
+    return (audio) =>
+      transcribeAudio(audio, {
+        url,
+        headers: this.#requestHeaders(),
+        ...this.#credentialsOption(),
+      });
   }
 
   /** Drop a voice transcript into the composer (appended to any typed text). */
@@ -1050,8 +1269,9 @@ export class AgUiChat extends HTMLElement {
     if (url !== null) {
       this.conversationStore = new RemoteConversationStore(
         url,
-        () => this.headers,
+        () => this.#requestHeaders(),
         this.conversationStore,
+        () => this.#requestCredentials(),
       );
     }
   }
@@ -1063,7 +1283,7 @@ export class AgUiChat extends HTMLElement {
       return;
     }
     try {
-      const response = await fetch(url, { headers: this.headers });
+      const response = await fetch(url, this.#fetchInit());
       this.#toolCatalog = parseToolCatalog(await response.json());
     } catch {
       // Network/parse failure: cards fall back to toolSummaries / raw names.
@@ -1079,13 +1299,16 @@ export class AgUiChat extends HTMLElement {
     this.#recomputeSkills();
   }
 
-  /** Wire the skill surfaces: opt-in flags, embedded catalog, optional fetch. */
+  /**
+   * Wire the skill surfaces: opt-in flags and the embedded catalog. The backend
+   * catalog is fetched from `#startup`, a microtask later, so it carries the
+   * host's transport configuration.
+   */
   #initSkills(): void {
     this.#skillsMenu.enableChips(this.#flag("data-prompt-chips"));
     this.#skillsMenu.enableSlash(this.#flag("data-slash-commands"));
     this.#embedSkills = this.#readEmbeddedSkills();
     this.#recomputeSkills();
-    void this.#fetchSkills();
   }
 
   /** Parse the inline `data-skills` JSON catalog (empty when absent/malformed). */
@@ -1108,7 +1331,7 @@ export class AgUiChat extends HTMLElement {
       return;
     }
     try {
-      const response = await fetch(url, { headers: this.headers });
+      const response = await fetch(url, this.#fetchInit());
       this.#backendSkills = parseSkills(await response.json());
       this.#recomputeSkills();
     } catch {
@@ -1163,12 +1386,14 @@ export class AgUiChat extends HTMLElement {
         .replace("{fields}", missing.join(", "));
       this.#skillHint.hidden = false;
       this.#input.value = text;
+      this.#autoGrow();
       this.#input.focus();
       this.#selectFirstPlaceholder(text);
       return;
     }
     this.#skillHint.hidden = true;
     this.#input.value = text;
+    this.#autoGrow();
     if (skill.sendImmediately === false) {
       this.#input.focus();
       return;
@@ -1213,7 +1438,9 @@ export class AgUiChat extends HTMLElement {
       this.removeAttribute("collapsed");
     }
     sessionStorage.setItem(this.#storageKey(COLLAPSED_KEY), collapsed ? "1" : "0");
-    this.#syncRail();
+    // Expanding is what marks the waiting answers read; collapsing starts a
+    // fresh count. Either way the badge is cleared and the host told.
+    this.#setUnread(0);
     this.dispatchEvent(
       new CustomEvent<ToggleDetail>(TOGGLE_EVENT, {
         detail: { collapsed },
@@ -1223,6 +1450,16 @@ export class AgUiChat extends HTMLElement {
     );
   }
 
+  /**
+   * Answers that finished while the widget was collapsed, and that the user has
+   * therefore not seen. Expanding (or {@link newChat}) clears it. The launcher's
+   * badge renders this; {@link UNREAD_EVENT} announces every change, so a host
+   * chrome can render its own instead.
+   */
+  get unread(): number {
+    return this.#unread;
+  }
+
   /** Flip the collapsed state. Bound to the built-in header toggle. */
   toggleCollapsed(): void {
     this.setCollapsed(!this.collapsed);
@@ -1397,6 +1634,34 @@ export class AgUiChat extends HTMLElement {
     this.#themeToggle.textContent = dark ? "☀️" : "🌙";
   }
 
+  /**
+   * Open the thread-history drawer: the imperative route to the control that
+   * renders as `::part(history-button)`.
+   *
+   * A host that hides `::part(header)` to render its own title bar hides the
+   * history, new-chat and collapse buttons with it — and thread switching then
+   * has no route at all, because those controls live inside the header. Each of
+   * them has a method, so a host chrome can rebuild the set: this one,
+   * {@link openCheckpoints}, {@link newChat}, {@link toggleCollapsed} and
+   * {@link toggleTheme}.
+   */
+  openThreads(): void {
+    void this.#refreshDrawer();
+    this.#drawer.open();
+  }
+
+  /**
+   * Open the checkpoints panel (the `::part(checkpoints-button)` route).
+   *
+   * It lists the runs the `data-runs-url` server reports as continuable;
+   * without that attribute the built-in button is never rendered and this opens
+   * an empty panel.
+   */
+  openCheckpoints(): void {
+    void this.#refreshCheckpoints();
+    this.#checkpoints.open();
+  }
+
   /**
    * Start a fresh conversation: forget the persisted history, drop the
    * in-memory run state, clear the transcript, and mint a new thread id.
@@ -1409,6 +1674,7 @@ export class AgUiChat extends HTMLElement {
     this.#resetState();
     this.#threadId = this.conversationStore.threadId();
     this.#setRunning(false);
+    this.#setUnread(0);
   }
 
   /** Drop the in-memory run + transcript, leaving the thread id untouched. */
@@ -1713,17 +1979,13 @@ export class AgUiChat extends HTMLElement {
     controls.className = "header-controls";
     controls.setAttribute("part", "header-controls");
 
+    // Both controls delegate to the public methods, so a host chrome driving
+    // them imperatively takes exactly the path the built-in button takes.
     const history = this.#headerButton("history", this.#strings.chatHistory, "☰");
-    history.addEventListener("click", () => {
-      void this.#refreshDrawer();
-      this.#drawer.open();
-    });
+    history.addEventListener("click", () => this.openThreads());
 
     const checkpoints = this.#headerButton("checkpoints", this.#strings.checkpoints, "⭯");
-    checkpoints.addEventListener("click", () => {
-      void this.#refreshCheckpoints();
-      this.#checkpoints.open();
-    });
+    checkpoints.addEventListener("click", () => this.openCheckpoints());
 
     const newChat = this.#headerButton("new", this.#strings.newChat, "✚");
     newChat.addEventListener("click", () => this.newChat());
@@ -1776,18 +2038,35 @@ export class AgUiChat extends HTMLElement {
     inputRow.className = "input-row";
     inputRow.setAttribute("part", "composer");
 
+    // One bordered surface holds the field and the tool row under it, so the
+    // icon buttons stop competing with the field for weight.
+    const composer = document.createElement("div");
+    composer.className = "composer";
+    composer.setAttribute("part", "composer-surface");
+
+    const tools = document.createElement("div");
+    tools.className = "composer-tools";
+    tools.setAttribute("part", "composer-tools");
+
     this.#input.className = "input";
     this.#input.setAttribute("part", "input");
     this.#input.setAttribute("aria-label", this.#strings.message);
-    this.#input.rows = 2;
+    this.#input.rows = 1;
     this.#input.placeholder = this.#strings.inputPlaceholder;
     this.#input.addEventListener("keydown", (event) => this.#onKeydown(event));
     this.#input.addEventListener("input", () => this.#onInput());
 
+    // Icon-only, with both glyphs mounted at once and CSS showing the one the
+    // state calls for — swapping a single glyph would leave a host that slotted
+    // its own Send mark holding a stop icon mid-run.
     this.#send.className = "send";
     this.#send.type = "button";
     this.#send.setAttribute("part", "send");
-    this.#send.textContent = this.#strings.send;
+    this.#send.append(
+      this.#glyphSlot("icon-send", "send-send", ICON_SEND),
+      this.#glyphSlot("icon-stop", "send-stop", ICON_STOP),
+    );
+    this.#send.title = this.#strings.send;
     this.#send.setAttribute("aria-label", this.#strings.send);
     this.#send.dataset["state"] = "idle";
     this.#send.addEventListener("click", () => {
@@ -1804,13 +2083,13 @@ export class AgUiChat extends HTMLElement {
     this.#skillHint.setAttribute("part", "skill-hint");
     this.#skillHint.hidden = true;
 
-    // File-upload affordance: a 📎 button (hidden until `data-attachments-url`
-    // is wired) opening a hidden multi-file input. Drag-and-drop covers the
-    // whole shell (wired in #enableDragAndDrop).
+    // File-upload affordance: a paperclip button (hidden until
+    // `data-attachments-url` is wired) opening a hidden multi-file input.
+    // Drag-and-drop covers the whole shell (wired in #enableDragAndDrop).
     this.#attachButton.className = "attach-btn";
     this.#attachButton.type = "button";
     this.#attachButton.setAttribute("part", "attach-button");
-    this.#attachButton.textContent = "📎";
+    this.#attachButton.append(this.#glyphSlot("icon-attach", "attach-glyph", ICON_ATTACH));
     this.#attachButton.title = this.#strings.attachFiles;
     this.#attachButton.setAttribute("aria-label", this.#strings.attachFiles);
     this.#attachButton.hidden = true;
@@ -1831,7 +2110,9 @@ export class AgUiChat extends HTMLElement {
     const footer = document.createElement("slot");
     footer.name = "footer";
 
-    inputRow.append(this.#attachButton, this.#voiceSlot, this.#input, this.#send, this.#fileInput);
+    tools.append(this.#attachButton, this.#voiceSlot, this.#send);
+    composer.append(this.#input, tools);
+    inputRow.append(composer, this.#fileInput);
     // Skill surfaces sit just above the input: palette (opens on `/`), chips,
     // the missing-placeholder hint, and the pending-attachments tray.
     this.#chat.append(
@@ -1847,15 +2128,24 @@ export class AgUiChat extends HTMLElement {
       this.#checkpoints.element,
     );
 
-    // The collapsed-sidebar rail: a slim edge strip (the expand affordance),
-    // sibling of the panel so it survives the panel being hidden. CSS shows it
-    // only for `placement="sidebar"` + `collapsed`.
-    this.#rail.className = "rail";
-    this.#rail.type = "button";
-    this.#rail.setAttribute("part", "launcher");
-    this.#rail.setAttribute("aria-label", this.#strings.expand);
-    this.#rail.append(this.#iconElement("launcher", "launcher-icon", "💬"));
-    this.#rail.addEventListener("click", () => this.setCollapsed(false));
+    // What a collapsed widget shrinks to: a round floating button, or the slim
+    // edge rail under `placement="sidebar"` — one element, shaped by CSS.
+    // A sibling of the panel, so it survives the panel being hidden.
+    this.#launcher.className = "launcher";
+    this.#launcher.type = "button";
+    this.#launcher.setAttribute("part", "launcher");
+    this.#launcher.setAttribute("aria-label", this.#strings.expand);
+    this.#badge.className = "launcher-badge";
+    this.#badge.setAttribute("part", "launcher-badge");
+    // The count is announced through the launcher's own label, so the badge is
+    // decoration to a screen reader rather than a second, context-free number.
+    this.#badge.setAttribute("aria-hidden", "true");
+    this.#badge.hidden = true;
+    this.#launcher.append(
+      this.#iconElement("launcher", "launcher-icon", ICON_LAUNCHER, this.#launcherIconUrl()),
+      this.#badge,
+    );
+    this.#launcher.addEventListener("click", () => this.setCollapsed(false));
 
     this.#chat.append(
       createResizeHandle({
@@ -1873,7 +2163,7 @@ export class AgUiChat extends HTMLElement {
         label: this.#strings.resizePanel,
       }),
     );
-    this.#root.append(style, this.#chat, this.#rail);
+    this.#root.append(style, this.#chat, this.#launcher);
   }
 
   /**
@@ -1902,16 +2192,44 @@ export class AgUiChat extends HTMLElement {
   }
 
   /**
-   * An icon holder wrapping a `<slot>` so a host can project custom markup; with
-   * a `data-icon-url` `<img>` as the slot's fallback, or a glyph when given.
+   * A `<slot>` a host can project its own mark into, falling back to one of the
+   * built-in glyphs. The markup is an author-written constant, never user or
+   * server data, so it is assigned directly rather than sanitised.
+   */
+  #glyphSlot(slotName: string, className: string, markup: string): HTMLSlotElement {
+    const slot = document.createElement("slot");
+    slot.name = slotName;
+    slot.className = className;
+    slot.innerHTML = markup;
+    return slot;
+  }
+
+  /**
+   * The launcher's own image URL. `data-launcher-icon-url` lets the collapsed
+   * button carry a different mark from the header's — a product logo reads at
+   * 22px in a header bar but rarely at 26px in a circle — and falls back to the
+   * header icon so a single `data-icon-url` still feeds both.
+   */
+  #launcherIconUrl(): string | null {
+    return this.getAttribute("data-launcher-icon-url") ?? this.getAttribute("data-icon-url");
+  }
+
+  /**
+   * An icon holder wrapping a `<slot>` so a host can project custom markup;
+   * with an `<img>` as the slot's fallback when an icon URL is configured, or
+   * the given glyph markup when it is not.
    */
-  #iconElement(slotName: string, part: string, fallbackGlyph: string | null): HTMLSpanElement {
+  #iconElement(
+    slotName: string,
+    part: string,
+    fallbackGlyph: string | null,
+    iconUrl: string | null = this.getAttribute("data-icon-url"),
+  ): HTMLSpanElement {
     const holder = document.createElement("span");
     holder.className = "icon-holder";
     holder.setAttribute("part", part);
     const slot = document.createElement("slot");
     slot.name = slotName;
-    const iconUrl = this.getAttribute("data-icon-url");
     if (iconUrl !== null) {
       const img = document.createElement("img");
       img.className = "icon-img";
@@ -1919,15 +2237,71 @@ export class AgUiChat extends HTMLElement {
       img.alt = "";
       slot.append(img);
     } else if (fallbackGlyph !== null) {
-      slot.append(document.createTextNode(fallbackGlyph));
+      slot.innerHTML = fallbackGlyph;
     }
     holder.append(slot);
     return holder;
   }
 
-  /** Reflect the collapsed state on the rail's `aria-expanded`. */
-  #syncRail(): void {
-    this.#rail.setAttribute("aria-expanded", String(!this.collapsed));
+  /**
+   * Reflect the collapsed state and the unread count on the launcher.
+   *
+   * The count is also the launcher's accessible name: a badge that only exists
+   * as a coloured dot says nothing to a screen reader, and "Expand" alone would
+   * be a lie once answers are waiting behind it.
+   */
+  #syncLauncher(): void {
+    this.#launcher.setAttribute("aria-expanded", String(!this.collapsed));
+    const unread = this.#unread;
+    // Past 9 the exact number stops being information and starts being a
+    // layout problem — the badge is a circle, not a field.
+    this.#badge.textContent = unread > 9 ? "9+" : String(unread);
+    this.#badge.hidden = unread === 0 || !this.#badgeEnabled();
+    const label = this.#badge.hidden
+      ? this.#strings.expand
+      : this.#strings.expandUnread.replace("{count}", String(unread));
+    this.#launcher.setAttribute("aria-label", label);
+    this.#launcher.title = label;
+  }
+
+  /**
+   * The unread badge, unlike every other affordance here, is on by default:
+   * a collapsed widget is the one state where an answer can arrive with nothing
+   * on screen to say so. `data-unread-badge="false"` turns it off for a host
+   * that drives its own chrome from the `ag-ui-unread` event.
+   */
+  #badgeEnabled(): boolean {
+    return this.getAttribute("data-unread-badge") !== "false";
+  }
+
+  /**
+   * Set the unread count, repaint the badge, and tell the host.
+   *
+   * The count is kept whether or not the badge renders it, so `unread` stays
+   * truthful for a host chrome and switching the badge on mid-session doesn't
+   * start from a number that was never counted.
+   */
+  #setUnread(count: number): void {
+    this.#unread = count;
+    this.#syncLauncher();
+    this.dispatchEvent(
+      new CustomEvent<UnreadDetail>(UNREAD_EVENT, {
+        detail: { unread: count },
+        bubbles: true,
+        composed: true,
+      }),
+    );
+  }
+
+  /**
+   * Count an answer the user cannot have seen: one that finished while the
+   * widget was collapsed. Expanding is what marks them read.
+   */
+  #noteUnread(): void {
+    if (!this.collapsed) {
+      return;
+    }
+    this.#setUnread(this.#unread + 1);
   }
 
   /** Hide the empty-state region once the message list holds anything else. */
@@ -1939,6 +2313,7 @@ export class AgUiChat extends HTMLElement {
   #onInput(): void {
     this.#skillsMenu.onInput(this.#input.value);
     this.#skillHint.hidden = true;
+    this.#autoGrow();
   }
 
   #onKeydown(event: KeyboardEvent): void {
@@ -1971,15 +2346,34 @@ export class AgUiChat extends HTMLElement {
     this.#client?.cancel();
   }
 
-  /** Swap the composer button between Send (idle) and Stop (running). */
+  /**
+   * Swap the composer button between Send (idle) and Stop (running).
+   *
+   * The glyph is swapped by CSS from `data-state` — both are mounted — so this
+   * only has to move the accessible name, which is the button's whole label now
+   * that it carries no text.
+   */
   #setRunning(running: boolean): void {
     this.#running = running;
     const label = running ? this.#strings.stop : this.#strings.send;
-    this.#send.textContent = label;
+    this.#send.title = label;
     this.#send.setAttribute("aria-label", label);
     this.#send.dataset["state"] = running ? "running" : "idle";
   }
 
+  /**
+   * Size the field to its content: one row when empty, growing with what is
+   * typed until the CSS ceiling takes over and it scrolls.
+   *
+   * Resetting to `auto` first is what makes it shrink again — `scrollHeight`
+   * never reports less than the current height, so measuring without the reset
+   * would ratchet the composer taller and never back down.
+   */
+  #autoGrow(): void {
+    this.#input.style.height = "auto";
+    this.#input.style.height = `${this.#input.scrollHeight}px`;
+  }
+
   async #submit(): Promise<void> {
     // Ignore a submit while a run is in flight — the single choke point for
     // both Enter and the Send button. The button already turns into Stop, but
@@ -1996,6 +2390,7 @@ export class AgUiChat extends HTMLElement {
       return;
     }
     this.#input.value = "";
+    this.#autoGrow();
     // A file still uploading does not ride along — `readyRefs()` returns only
     // settled ones, and `clearReady()` deliberately keeps the rest for a
     // follow-up. Nothing said so, which is the whole defect: attachments are
@@ -2098,11 +2493,12 @@ export class AgUiChat extends HTMLElement {
     if (this.#client === null) {
       const agent = this.agentFactory({
         endpoint: this.endpoint,
-        headers: this.headers,
+        headers: this.#requestHeaders(),
         // Live getter: the client is built once and cached, but a rotated
         // token must still reach every request — the factory's fetch wrapper
         // re-reads this on each call.
-        getHeaders: () => this.headers,
+        getHeaders: () => this.#requestHeaders(),
+        ...this.#credentialsOption(),
         threadId: this.#threadId,
         initialMessages: this.#initialMessages,
         initialState: this.#sharedState,
@@ -2349,6 +2745,7 @@ export class AgUiChat extends HTMLElement {
         }
         attachCopyButtons(bubble, this.#strings);
         this.#streamingBubble = null;
+        this.#noteUnread();
       },
       onToolCall: (call) => {
         this.#hidePending();