@artooi/ag-ui-web-component 0.46.0 → 0.48.0

package/src/core/ag_ui_chat.ts

@@ -1,6 +1,7 @@
 import type { Context, Tool } from "@ag-ui/core";
 import {
   ATTACHMENT_EVENT,
+  BAR_HEIGHT_EVENT,
   CHART_ACTIVITY_TYPE,
   COMPACTION_ACTIVITY_TYPE,
   CUSTOM_AGENT_EVENT,
@@ -10,8 +11,11 @@ import {
   STATE_EVENT,
   SUBMIT_EVENT,
   SUGGESTIONS_ACTIVITY_TYPE,
+  THREAD_EVENT,
   TOGGLE_EVENT,
   TOOL_DISPLAY,
+  TOOL_GROUP_DISPLAY,
+  type ToolGroupDisplayMode,
   UNREAD_EVENT,
 } from "../constants.js";
 import type { Skill } from "../skills/skill.js";
@@ -49,7 +53,7 @@ import { PendingDecision } from "../ui/interrupts/pending_decision.js";
 // biome-ignore lint/style/useImportType: the emitted declaration file copies this form
 import { type QuestionRenderer } from "../ui/interrupts/question_card.js";
 import { PanelPlacement } from "../ui/placement/panel_placement.js";
-import { surfaceFor } from "../ui/placement/surface_for.js";
+import { type Surface, surfaceFor } from "../ui/placement/surface_for.js";
 import { RunAnnouncer } from "../ui/progress/run_announcer.js";
 import { renderRunNotice } from "../ui/progress/run_notice.js";
 import { SubAgentProgress } from "../ui/progress/subagent_progress.js";
@@ -75,6 +79,7 @@ import type { ActivityRenderer } from "./activity_renderer.js";
 import { AgUiClient } from "./agui_client.js";
 // biome-ignore lint/style/useImportType: the emitted declaration file copies this form
 import { type AttachmentRef } from "./attachment.js";
+import { ChatRegistration } from "./chat_registry.js";
 import type { ClientSeed } from "./client_seed.js";
 import {
   type ClientConversationStore,
@@ -83,8 +88,10 @@ import {
   writeStoredItem,
 } from "./conversation_store.js";
 import { type AgentFactory, createHttpAgent } from "./create_http_agent.js";
+import type { BarHeightDetail } from "./events/bar_height_detail.js";
 import type { StateDetail } from "./events/state_detail.js";
 import type { SubmitDetail } from "./events/submit_detail.js";
+import type { ThreadDetail } from "./events/thread_detail.js";
 import type { ToggleDetail } from "./events/toggle_detail.js";
 import type { UnreadDetail } from "./events/unread_detail.js";
 import type { MessageRole } from "./message_role.js";
@@ -110,7 +117,7 @@ import { warnOnCrossOriginCredentials, withCredentials } from "./utils.js";
  * Excludes the attributes that are re-read per use, where a late change works
  * and a warning would be wrong: `data-runs-url`, `data-page-actions`,
  * `data-text-animation`, `data-tool-display`, `endpoint`, and the CSS-reactive
- * `theme` / `collapsed`.
+ * `theme` / `collapsed` / `data-tool-group-display`.
  */
 const CONNECT_TIME_ATTRIBUTES = [
   "data-attachments-url",
@@ -172,6 +179,20 @@ function withScheme(theme: string, scheme: string): string {
   return [...names, scheme].join(" ");
 }
 
+/**
+ * The element a selector names, in the given root first and then the
+ * document; null for no match, and for a selector that does not parse, which
+ * is the same mistake from the host's side.
+ */
+function findAnchor(root: Node, selector: string): Element | null {
+  try {
+    const scope = root instanceof ShadowRoot ? root : document;
+    return scope.querySelector(selector) ?? document.querySelector(selector);
+  } catch {
+    return null;
+  }
+}
+
 /**
  * `<ag-ui-chat>` — a framework-free chat sidebar Web Component over AG-UI.
  *
@@ -536,8 +557,21 @@ export class AgUiChat extends HTMLElement {
   readonly #launcher: HTMLButtonElement;
   /** The launcher's unread badge; hidden at zero, and when the host opts out. */
   readonly #badge: HTMLSpanElement;
-  /** The rail's vertical caption. Rendered only by the sidebar's edge rail. */
+  /** The rail's vertical caption. Rendered only by the sidebar's edge rail and the bottom bar. */
   readonly #railLabel: HTMLSpanElement = document.createElement("span");
+  /**
+   * The bottom bar under collapse-to="bar": the launcher drawn as a strip, and
+   * the history button beside it. Outside the bar it draws no box of its own.
+   */
+  readonly #dockBar: HTMLDivElement = document.createElement("div");
+  /** The bottom bar's history button, which opens the drawer as a popover. */
+  readonly #barHistory: HTMLButtonElement = document.createElement("button");
+  /** The bar height last reported, so the event fires on a change only. */
+  #barHeight = 0;
+  /** The element the panel rises from under collapse-to="none", set as a property. */
+  #anchor: Element | null = null;
+  /** Whether a missing anchor has been reported; once per anchor given. */
+  #anchorWarned = false;
   // 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. */
@@ -600,6 +634,7 @@ export class AgUiChat extends HTMLElement {
    */
   readonly #onViewportResize = (): void => {
     this.#placement.publishVisualViewport();
+    this.#syncDock();
     // Not while a gesture owns the position. Restoring re-applies the *stored*
     // position, and mid-drag that value is the one from before the drag began
     // -- so it puts the widget back where it was, the next pointer move puts it
@@ -624,6 +659,8 @@ export class AgUiChat extends HTMLElement {
   readonly #voice: ComposerVoice;
   /** Whether the element is currently in the DOM; gates the connect-time warning. */
   #connected = false;
+  /** A {@link newChat} asked for before the element connected, to start at connect. */
+  #newChatOnConnect = false;
   /**
    * Aborted when the element leaves the document, and replaced when it comes
    * back.
@@ -750,6 +787,11 @@ export class AgUiChat extends HTMLElement {
    * then a host's {@link sendMessage} waits for it rather than refusing.
    */
   #restoreHold: { readonly hold: object; readonly restored: Promise<void> } | null = null;
+  /**
+   * The thread the latest {@link THREAD_EVENT} reported, which the next one
+   * names as the thread it replaced; `null` before the first.
+   */
+  #shownThread: string | null = null;
   /** The decision a run is suspended on, which a Stop abandons. */
   readonly #decision = new PendingDecision();
   /**
@@ -781,6 +823,8 @@ export class AgUiChat extends HTMLElement {
     allowImages: () => this.allowImages,
     follow: () => this.#transcript.follow(),
   });
+  // This chat's place among the connected ones, which a free highlight ring reads.
+  readonly #chatRegistration = new ChatRegistration(this);
   /**
    * Which storage keys are this element's: the namespace it claims, the keys
    * its layout preferences live under, and the built-in store scoped to them.
@@ -869,7 +913,7 @@ export class AgUiChat extends HTMLElement {
       root: this.#root,
       connected: () => this.#connected,
       collapsed: () => this.collapsed,
-      collapsible: () => surfaceFor(this.getAttribute("placement")).collapseTo !== null,
+      collapsible: () => this.#surface().collapseTo !== null,
       strings: () => this.#strings,
       readPreference: (base) => this.#storage.readPreference(base),
       writePreference: (base, value) => this.#storage.writePreference(base, value),
@@ -955,7 +999,9 @@ export class AgUiChat extends HTMLElement {
     });
     this.#drawer = new ThreadDrawer({
       onSelect: (threadId) => {
-        void this.#history.switchThread(threadId);
+        // switchThread rejects when the store cannot load the thread, and keeps
+        // the old one on screen; a pick has nobody to tell, so it ends here.
+        this.#history.switchThread(threadId).catch(() => undefined);
       },
       onNew: () => {
         this.newChat();
@@ -1043,6 +1089,7 @@ export class AgUiChat extends HTMLElement {
       cancelRun: () => this.#cancelRun(),
       resetState: () => this.#resetState(),
       setRunning: (running) => this.#setRunning(running),
+      threadChanged: (threadId, reason) => this.#dispatchThread(threadId, reason),
     });
   }
 
@@ -1051,6 +1098,8 @@ export class AgUiChat extends HTMLElement {
     return [
       "title-text",
       "placement",
+      "collapse-to",
+      "anchor",
       "credentials",
       "user-key",
       "user-name",
@@ -1073,7 +1122,14 @@ export class AgUiChat extends HTMLElement {
       }
       return;
     }
-    if (name === "placement") {
+    if (name === "anchor") {
+      this.#anchorWarned = false;
+      this.#syncDock();
+      return;
+    }
+    // collapse-to changes the surface the way placement does -- a docked panel
+    // cannot be moved, so the same handover applies -- and is live the same way.
+    if (name === "placement" || name === "collapse-to") {
       // A placement owns the axes it fixes, so hand those back before anything
       // else: a size dragged under the previous placement would otherwise sit
       // inline and outrank the new one.
@@ -1085,9 +1141,19 @@ export class AgUiChat extends HTMLElement {
       // not just stop offering it: the control is gone from the header the
       // moment the attribute changes, so a panel collapsed under the previous
       // placement would have no way back.
-      if (surfaceFor(this.getAttribute("placement")).collapseTo === null && this.collapsed) {
+      if (this.#surface().collapseTo === null && this.collapsed) {
         this.setCollapsed(false);
       }
+      this.#stampCollapseTarget();
+      if (name === "collapse-to") {
+        // The strip's label and the popover's home both depend on the target,
+        // and neither is re-derived by the dock sync.
+        this.#syncLauncher();
+        if (this.#surface().collapseTo !== "bar") {
+          this.#homeDrawer();
+        }
+      }
+      this.#syncDock();
       // Placement also moves the panel, so the edges its layout holds still
       // change with it. Deferred a frame so the new rules have applied.
       requestAnimationFrame(() => this.#placement.syncResizeAnchor());
@@ -1407,6 +1473,32 @@ export class AgUiChat extends HTMLElement {
     this.setAttribute("data-tool-display", value);
   }
 
+  /**
+   * How an opened step group draws its calls, from the
+   * `data-tool-group-display` attribute (`full` / `compact` / `minimal` /
+   * `inline`). Defaults to `full`, for an absent attribute and for a value the
+   * element does not know, which is what a group drew before the attribute.
+   *
+   * Read only while `toolDisplay` is `grouped`: under a card mode the groups
+   * are flattened into that mode's cards. Applied by the shadow CSS from the
+   * attribute itself, so changing it restyles groups already on screen.
+   */
+  get toolGroupDisplay(): ToolGroupDisplayMode {
+    const attr = this.getAttribute("data-tool-group-display");
+    if (
+      attr === TOOL_GROUP_DISPLAY.INLINE ||
+      attr === TOOL_GROUP_DISPLAY.MINIMAL ||
+      attr === TOOL_GROUP_DISPLAY.COMPACT
+    ) {
+      return attr;
+    }
+    return TOOL_GROUP_DISPLAY.FULL;
+  }
+
+  set toolGroupDisplay(value: ToolGroupDisplayMode) {
+    this.setAttribute("data-tool-group-display", value);
+  }
+
   /**
    * The host's own constructed stylesheets, adopted after the built-in one.
    *
@@ -1448,6 +1540,7 @@ export class AgUiChat extends HTMLElement {
     // this instance doesn't share collapsed/theme/thread state with another on
     // the same origin.
     this.#storage.claim();
+    this.#chatRegistration.join();
     // Restore a dragged size before the panel paints, so it does not snap from
     // the placement default to the user's width on the first frame.
     this.#placement.restoreSize();
@@ -1481,10 +1574,32 @@ export class AgUiChat extends HTMLElement {
     // namespaced per instance but not per placement, so a tab that collapsed a
     // floating panel and later loaded the same instance as a page would restore
     // a state that placement has no way out of.
-    if (surfaceFor(this.getAttribute("placement")).collapseTo !== null && this.#startsCollapsed()) {
+    if (this.#surface().collapseTo !== null && this.#startsCollapsed()) {
       this.setAttribute("collapsed", "");
     }
     this.#syncLauncher();
+    this.#stampCollapseTarget();
+    // The bar's height follows its content (the font, a long title), so it is
+    // measured rather than known; the observer reports a change of size, and
+    // the strip going from drawn to not drawn is one.
+    const dockObserver = new ResizeObserver(() => this.#syncDock());
+    dockObserver.observe(this.#dockBar);
+    this.#connection.signal.addEventListener("abort", () => dockObserver.disconnect());
+    this.#syncDock();
+    // Under collapse-to="none" the host draws the collapsed state itself, so
+    // it has to learn the state the element mounted in -- restored from
+    // storage or the placement's default -- without waiting for a change.
+    // Dispatched directly rather than through setCollapsed, which would write
+    // storage and clear the unread count for a state nobody changed.
+    if (this.#surface().collapseTo === "none") {
+      this.dispatchEvent(
+        new CustomEvent<ToggleDetail>(TOGGLE_EVENT, {
+          detail: { collapsed: this.collapsed },
+          bubbles: true,
+          composed: true,
+        }),
+      );
+    }
     this.#skills.init();
     // A `user-key` that changed while the element was out of the document gets
     // the handover a live change gets, here, because this is the first moment
@@ -1530,7 +1645,10 @@ export class AgUiChat extends HTMLElement {
     // 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.#history.rehydrate();
+    // A key changed while the element was away handed it over all the same,
+    // and the restore is the arriving principal's: reported as the live change
+    // is. An adoption is not a handover, and restores the same conversation.
+    void this.#history.rehydrate(changed && held !== "" ? "rescope" : "restore");
     if (changed) {
       // The last of what a live change does: a drawer left open across the
       // move still lists the threads of the principal who left, titles and
@@ -1541,6 +1659,12 @@ export class AgUiChat extends HTMLElement {
     // Last: everything above reads (and some of it sets) attributes, and none
     // of that should trip the connect-time warning.
     this.#connected = true;
+    if (this.#newChatOnConnect) {
+      this.#newChatOnConnect = false;
+      // After the restore above has started: starting the chat stops it, so
+      // the one event is the new chat's and the conversation left stays kept.
+      this.newChat();
+    }
   }
 
   /**
@@ -1594,7 +1718,7 @@ export class AgUiChat extends HTMLElement {
     await Promise.all([
       this.#tools.fetchCatalog(),
       this.#skills.fetch(),
-      this.#history.rehydrate(),
+      this.#history.rehydrate("restore"),
     ]);
   }
 
@@ -1611,6 +1735,7 @@ export class AgUiChat extends HTMLElement {
     window.visualViewport?.removeEventListener("resize", this.#onViewportResize);
     window.visualViewport?.removeEventListener("scroll", this.#onViewportResize);
     this.#storage.release();
+    this.#chatRegistration.leave();
     this.#cancelRun();
     this.#excerpts.detachPageOffer();
     this.#attachments.tray?.dispose();
@@ -1740,7 +1865,7 @@ export class AgUiChat extends HTMLElement {
    * its own chrome.
    */
   setCollapsed(collapsed: boolean, options: { readonly announce?: boolean } = {}): void {
-    if (collapsed && surfaceFor(this.getAttribute("placement")).collapseTo === null) {
+    if (collapsed && this.#surface().collapseTo === null) {
       return;
     }
     // Announced before the state changes, so the notice is written into a
@@ -1769,8 +1894,13 @@ export class AgUiChat extends HTMLElement {
     if (collapsed) {
       this.setAttribute("collapsed", "");
     } else {
+      // The history popover belongs to the bar only while the panel is away.
+      // Opening the panel closes it and takes the drawer back, so the panel
+      // lands on the conversation rather than on a list over it.
+      this.#homeDrawer();
       this.removeAttribute("collapsed");
     }
+    this.#syncDock();
     writeStoredItem(this.#storage.key(COLLAPSED_KEY), collapsed ? "1" : "0");
     // Expanding is what marks the waiting answers read; collapsing starts a
     // fresh count. Either way the badge is cleared and the host told.
@@ -1794,6 +1924,126 @@ export class AgUiChat extends HTMLElement {
     return this.#unread;
   }
 
+  /**
+   * The thread on screen; `null` before the element first connects.
+   *
+   * Only reads. `conversationStore.threadId()` mints and stores a thread when
+   * the store points at none, so a host asking which conversation is showing
+   * could start one; this never does. {@link THREAD_EVENT} says when it changes.
+   */
+  get threadId(): string | null {
+    const threadId = this.#history.threadId;
+    return threadId === "" ? null : threadId;
+  }
+
+  /**
+   * Whether an interaction is in flight: the composer's own state, the one that
+   * shows Stop. It spans every tool round, a retry and a checkpoint
+   * continuation as well as a send, which {@link SUBMIT_EVENT} alone does not.
+   * Reflected as `data-running` on the element, for a host's CSS.
+   */
+  get running(): boolean {
+    return this.#running;
+  }
+
+  /**
+   * The height of the bottom bar in CSS px, and 0 when none is drawn: under
+   * any collapse-to but "bar", and on a phone while the panel is open, where
+   * the panel is the screen. The bar is fixed over the page, so a host pads
+   * its own page by this much; {@link BAR_HEIGHT_EVENT} says when it changes.
+   */
+  get barHeight(): number {
+    return this.#barHeight;
+  }
+
+  /**
+   * The element the panel rises from under collapse-to="none", right-aligned
+   * to it: typically the host's own button in its own bar. Takes precedence
+   * over the anchor attribute, which names one by selector. One that resolves
+   * to nothing leaves the panel in its placement's own corner, with a console
+   * warning.
+   */
+  get anchor(): Element | null {
+    return this.#anchor;
+  }
+
+  set anchor(value: Element | null) {
+    this.#anchor = value;
+    this.#anchorWarned = false;
+    this.#syncDock();
+  }
+
+  /** The surface the live placement and collapse-to attributes describe. */
+  #surface(): Surface {
+    return surfaceFor(this.getAttribute("placement"), this.getAttribute("collapse-to"));
+  }
+
+  /**
+   * Stamp what the panel collapses to as data-collapsed-to, which is what the
+   * stylesheet draws the bar and the hidden state from. Resolved here rather
+   * than in CSS, because "bar" over a sidebar is its rail and "none" over a
+   * page is no collapse at all, and the stylesheet would have to restate that
+   * table.
+   */
+  #stampCollapseTarget(): void {
+    const target = this.#surface().collapseTo;
+    if (target === null) {
+      this.removeAttribute("data-collapsed-to");
+    } else {
+      this.setAttribute("data-collapsed-to", target);
+    }
+  }
+
+  /** Re-measure the bar or the anchor, and tell the host when the bar's height changed. */
+  #syncDock(): void {
+    // isConnected rather than the connected flag, which connectedCallback
+    // sets only at its end, after the first measurement here.
+    if (!this.isConnected) {
+      return;
+    }
+    const height = this.#placement.syncDock(this.#dockBar, this.#resolveAnchor());
+    if (height === this.#barHeight) {
+      return;
+    }
+    this.#barHeight = height;
+    this.dispatchEvent(
+      new CustomEvent<BarHeightDetail>(BAR_HEIGHT_EVENT, {
+        detail: { height },
+        bubbles: true,
+        composed: true,
+      }),
+    );
+  }
+
+  /**
+   * The anchor in force under collapse-to="none": the property, else the
+   * attribute's selector, looked up in the root this element lives in and
+   * then the document, so a chat inside a framework's shadow root can name a
+   * button beside it. Null under any other collapse-to, with nothing given,
+   * or when what was given is not in the document -- reported once per anchor.
+   */
+  #resolveAnchor(): Element | null {
+    if (this.#surface().collapseTo !== "none") {
+      return null;
+    }
+    const selector = this.getAttribute("anchor") ?? "";
+    if (this.#anchor === null && selector === "") {
+      return null;
+    }
+    const found = this.#anchor ?? findAnchor(this.getRootNode(), selector);
+    if (found?.isConnected === true) {
+      return found;
+    }
+    if (!this.#anchorWarned) {
+      this.#anchorWarned = true;
+      console.warn(
+        `<ag-ui-chat>: the anchor ${this.#anchor === null ? `"${selector}"` : "element"} ` +
+          "is not in the document, so the panel opens from its placement's own corner.",
+      );
+    }
+    return null;
+  }
+
   /**
    * Whether to mount collapsed.
    *
@@ -1816,10 +2066,7 @@ export class AgUiChat extends HTMLElement {
     if (stored !== null) {
       return stored === "1";
     }
-    return (
-      surfaceFor(this.getAttribute("placement")).startsCollapsed &&
-      !this.hasAttribute("data-start-open")
-    );
+    return this.#surface().startsCollapsed && !this.hasAttribute("data-start-open");
   }
 
   /**
@@ -1850,6 +2097,14 @@ export class AgUiChat extends HTMLElement {
     return this.#placement.moveTo(corner, options);
   }
 
+  /**
+   * Drop a size the user dragged, and its stored copy, so the placement's
+   * default and the host's `--ag-ui-width` / `--ag-ui-height` apply again.
+   */
+  resetSize(): void {
+    this.#placement.resetSize();
+  }
+
   /** Flip the collapsed state. Bound to the built-in header toggle. */
   toggleCollapsed(): void {
     this.setCollapsed(!this.collapsed);
@@ -1859,8 +2114,9 @@ export class AgUiChat extends HTMLElement {
    * Flip the scheme word of the `theme` attribute between `light` and `dark`
    * and persist the choice per tab. Bound to the optional built-in header theme
    * toggle (`data-theme-toggle`). The theme name and any host words are kept:
-   * `soft` becomes `soft dark`, and `soft dark` becomes `soft light`. Any
-   * scheme but `dark` (including `auto`) flips to `dark` first.
+   * `soft` becomes `soft dark`, and `soft dark` becomes `soft light`. With no
+   * scheme word (`auto`, or a host rule setting `color-scheme` on the element),
+   * it flips away from the scheme the panel is drawn in.
    */
   toggleTheme(): void {
     // Only the scheme word flips, so a named theme survives the toggle:
@@ -1868,7 +2124,7 @@ export class AgUiChat extends HTMLElement {
     // only the scheme word is saved: the name is the host's, and a name saved
     // on one page would replace another page's theme on restore.
     const theme = this.getAttribute("theme") ?? "";
-    const scheme = theme.split(/\s+/).includes("dark") ? "light" : "dark";
+    const scheme = this.#drawnScheme() === "dark" ? "light" : "dark";
     this.setAttribute("theme", withScheme(theme, scheme));
     this.#storage.writePreference(THEME_KEY, scheme);
     this.#syncThemeGlyph();
@@ -1960,7 +2216,7 @@ export class AgUiChat extends HTMLElement {
     this.#voice.dispose();
     this.#voice.wire();
     this.#history.adoptActiveThread();
-    void this.#history.rehydrate();
+    void this.#history.rehydrate("rescope");
     void this.#history.refreshDrawer();
   }
 
@@ -1986,9 +2242,37 @@ export class AgUiChat extends HTMLElement {
     this.#wireThreadStore();
   }
 
+  /**
+   * The scheme the panel is drawn in, which the toggle flips and its glyph
+   * offers the way out of. A scheme word decides it, since the scheme rules
+   * hold against a host's. Without one the panel follows whatever sets its
+   * color-scheme: a host rule on the element, auto's "light dark", or the
+   * light default. Both schemes allowed means the system picks. Read before
+   * the shadow styles apply too (the glyph is drawn first), when the computed
+   * value carries only a host rule, so auto is answered from its word.
+   */
+  #drawnScheme(): "light" | "dark" {
+    const words = (this.getAttribute("theme") ?? "").split(/\s+/);
+    if (words.includes("dark")) {
+      return "dark";
+    }
+    if (words.includes("light")) {
+      return "light";
+    }
+    const declared = getComputedStyle(this).colorScheme.split(/\s+/);
+    const dark = declared.includes("dark");
+    if (dark !== declared.includes("light")) {
+      return dark ? "dark" : "light";
+    }
+    if (dark || words.includes("auto")) {
+      return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+    }
+    return "light";
+  }
+
   /** Reflect the current theme on the toggle: show the destination's glyph. */
   #syncThemeGlyph(): void {
-    const dark = (this.getAttribute("theme") ?? "").split(/\s+/).includes("dark");
+    const dark = this.#drawnScheme() === "dark";
     // Replaced wholesale rather than toggling a class: the two marks are
     // different paths, not one path in two states, and the slot has to keep
     // working so a host can still supply its own.
@@ -2007,9 +2291,30 @@ export class AgUiChat extends HTMLElement {
    * {@link toggleCollapsed} and {@link toggleTheme}.
    */
   openThreads(): void {
+    // Collapsed into the bar, the list opens as a popover over the bar rather
+    // than expanding the panel: the same drawer, moved beside the bar, since
+    // nothing inside the hidden panel can be drawn.
+    if (this.collapsed && this.#surface().collapseTo === "bar") {
+      this.#dockBar.append(this.#drawer.element);
+    } else {
+      this.#homeDrawer();
+    }
     this.#history.openThreads();
   }
 
+  /**
+   * Put the drawer back in the panel, where every surface but the bar's
+   * popover draws it. A popover still open is closed first: the list was
+   * opened over the bar, and carried into the panel it would cover the
+   * conversation the user asked to see.
+   */
+  #homeDrawer(): void {
+    if (this.#drawer.element.parentNode === this.#dockBar) {
+      this.#drawer.close();
+      this.#chat.insertBefore(this.#drawer.element, this.#checkpoints.element);
+    }
+  }
+
   /**
    * Open the checkpoints panel (the `::part(checkpoints-button)` route).
    *
@@ -2031,6 +2336,39 @@ export class AgUiChat extends HTMLElement {
     this.#checkpoints.close();
   }
 
+  /**
+   * Put a stored thread on screen, as picking it in the conversation list does,
+   * for a host that lists conversations in its own chrome.
+   *
+   * Resolves once the thread has been replayed, when {@link THREAD_EVENT} has
+   * fired; a second call for the thread already loading settles with that load.
+   * If the store rejects the load, the element stays on the thread it was on,
+   * fires nothing, and the promise rejects with the store's error.
+   * **A run in flight is cancelled**, as the list and {@link newChat} do;
+   * a host that would rather wait reads {@link running} first. The thread
+   * already on screen is left alone, and so is everything before the element
+   * connects, since until then it has no store to read the thread from.
+   */
+  switchThread(threadId: string): Promise<void> {
+    if (!this.#connected) {
+      return Promise.resolve();
+    }
+    return this.#history.switchThread(threadId);
+  }
+
+  /**
+   * Delete a stored thread, as the conversation list's delete does. Deleting the
+   * thread on screen cancels its run and puts a fresh thread in its place, and
+   * {@link THREAD_EVENT} reports it; deleting another leaves the screen alone.
+   * Does nothing before the element connects.
+   */
+  deleteThread(threadId: string): void {
+    if (!this.#connected) {
+      return;
+    }
+    this.#history.deleteThread(threadId);
+  }
+
   /**
    * Open the checkpoints panel, or close it if it is already open — what the
    * built-in ⭯ button does, because a control that opens a panel is read as the
@@ -2058,6 +2396,13 @@ export class AgUiChat extends HTMLElement {
    * one. The page is not scrolled to bring the composer into view.
    */
   newChat(): void {
+    // Before the element connects it has no store scoped to its namespace and
+    // no thread to leave, and minting one would write to the unscoped store and
+    // fire an event for a thread it does not yet show. Connecting starts it.
+    if (!this.#connected) {
+      this.#newChatOnConnect = true;
+      return;
+    }
     // Stop any in-flight run first — discarding the client mid-run would
     // leave the old agent streaming into a cleared transcript.
     this.#cancelRun();
@@ -2066,6 +2411,7 @@ export class AgUiChat extends HTMLElement {
     this.#history.startThread();
     this.#setRunning(false);
     this.#setUnread(0);
+    this.#dispatchThread(this.#history.threadId, "new");
     // Whichever control started it: the header's, the history list's (which
     // hands focus back to its opener as it closes, before this runs), or a
     // host's own. A keyboard user otherwise had to find their way back to the
@@ -2340,6 +2686,12 @@ export class AgUiChat extends HTMLElement {
       onFilesPicked: () => this.#attachments.onFilesPicked(),
     });
 
+    // Host content against the input, after everything of the turn being
+    // written. A bare slot, whose own box is none, so an empty one takes no
+    // space and the greeting layout carries a filled one with the composer.
+    const aboveComposer = document.createElement("slot");
+    aboveComposer.name = "above-composer";
+
     // A coarse footer slot below the composer.
     const footer = document.createElement("slot");
     footer.name = "footer";
@@ -2351,7 +2703,8 @@ export class AgUiChat extends HTMLElement {
 
     // Composer surfaces sit just above the input: the skills palette (opens on
     // `/`), the chips, the hint saying what the composer still needs, the
-    // queued messages and the pending-attachments tray.
+    // queued messages and the pending-attachments tray, then the host's own
+    // content directly over the input.
     this.#chat.replaceChildren(
       header,
       this.#messagesWrap,
@@ -2360,6 +2713,7 @@ export class AgUiChat extends HTMLElement {
       this.#composerHint,
       this.#queuedRow,
       this.#attachSlot,
+      aboveComposer,
       inputRow,
       footer,
       this.#drawer.element,
@@ -2393,12 +2747,40 @@ export class AgUiChat extends HTMLElement {
       launcher: this.#launcher,
       badge: this.#badge,
       railLabel: this.#railLabel,
+      bar: this.#dockBar,
+      barHistory: this.#barHistory,
       titleText,
       iconUrl: readLauncherIconUrl(this),
       strings: this.#strings,
       signal,
-      onOpen: () => this.setCollapsed(false),
+      // The bar stays on screen with the panel open, as the way to minimise
+      // it, so its strip toggles; everywhere else the launcher is only drawn
+      // while collapsed and only ever opens.
+      onOpen: () => this.setCollapsed(this.#surface().collapseTo === "bar" && !this.collapsed),
+      // The bar's history button toggles: the popover has no backdrop, and a
+      // press on the bar is not a press outside it, so this is how the button
+      // that opened the list closes it again. openThreads() stays open-only.
+      onHistory: () => {
+        if (this.#drawer.isOpen()) {
+          this.#drawer.close();
+        } else {
+          this.openThreads();
+        }
+      },
     });
+    // The popover has no backdrop to catch a click away, so a press outside
+    // the bar closes it, as Escape already does.
+    document.addEventListener(
+      "pointerdown",
+      (event) => {
+        if (this.#drawer.element.parentNode === this.#dockBar && this.#drawer.isOpen()) {
+          if (!event.composedPath().includes(this.#dockBar)) {
+            this.#drawer.close();
+          }
+        }
+      },
+      { signal },
+    );
     this.#placement.enableLauncherDrag(signal);
 
     this.#placement.mountResizeGrips(this.#chat);
@@ -2406,7 +2788,7 @@ export class AgUiChat extends HTMLElement {
     const probe = this.#placement.probe;
     probe.className = "viewport-probe";
     probe.setAttribute("aria-hidden", "true");
-    this.#root.replaceChildren(probe, this.#announcer.region, this.#chat, this.#launcher);
+    this.#root.replaceChildren(probe, this.#announcer.region, this.#chat, this.#dockBar);
   }
 
   /**
@@ -2423,9 +2805,12 @@ export class AgUiChat extends HTMLElement {
     // layout problem — the badge is a circle, not a field.
     this.#badge.textContent = unread > 9 ? "9+" : String(unread);
     this.#badge.hidden = unread === 0 || !isUnreadBadgeEnabled(this);
-    const label = this.#badge.hidden
-      ? this.#strings.expand
-      : fillUiString(this.#strings.expandUnread, { count: unread });
+    const label =
+      !this.collapsed && this.#surface().collapseTo === "bar"
+        ? this.#strings.collapse
+        : this.#badge.hidden
+          ? this.#strings.expand
+          : fillUiString(this.#strings.expandUnread, { count: unread });
     this.#launcher.setAttribute("aria-label", label);
     this.#launcher.title = label;
   }
@@ -2594,6 +2979,22 @@ export class AgUiChat extends HTMLElement {
     this.#history.stopContinuation();
   }
 
+  /**
+   * Say the conversation on screen changed: {@link THREAD_EVENT}.
+   *
+   * The thread it replaced is the one last reported, rather than the one the
+   * element last pointed at: a switch superseded before it replayed never drew
+   * its thread, so naming it as the previous one left a host's own list
+   * marking a thread that was never shown and still marking the one that was.
+   */
+  #dispatchThread(threadId: string, reason: ThreadDetail["reason"]): void {
+    const detail: ThreadDetail = { threadId, previousThreadId: this.#shownThread, reason };
+    this.#shownThread = threadId;
+    this.dispatchEvent(
+      new CustomEvent<ThreadDetail>(THREAD_EVENT, { detail, bubbles: true, composed: true }),
+    );
+  }
+
   /**
    * Swap the composer button between Send (idle) and Stop (running).
    *
@@ -2615,6 +3016,8 @@ export class AgUiChat extends HTMLElement {
     this.#send.title = label;
     this.#send.setAttribute("aria-label", label);
     this.#send.dataset["state"] = running ? "running" : "idle";
+    // For a host's CSS, as `data-empty` is: the same state, on the element.
+    this.toggleAttribute("data-running", running);
     if (settled) {
       this.#flushQueued();
     }
@@ -3006,7 +3409,7 @@ export class AgUiChat extends HTMLElement {
     });
     return new AgUiClient({
       agent,
-      handlers: this.#runHandlers.forClient(),
+      handlers: this.#runHandlers.forClient(threadId),
       getTools: () => this.#tools.advertise(),
       getContext: () => this.#dispatch.buildContext(),
       executeTool: (call) => this.#dispatch.execute(call),