@artooi/ag-ui-web-component 0.47.0 → 0.49.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,
@@ -13,6 +14,8 @@ import {
   THREAD_EVENT,
   TOGGLE_EVENT,
   TOOL_DISPLAY,
+  TOOL_GROUP_DISPLAY,
+  type ToolGroupDisplayMode,
   UNREAD_EVENT,
 } from "../constants.js";
 import type { Skill } from "../skills/skill.js";
@@ -50,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";
@@ -85,6 +88,7 @@ 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";
@@ -113,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",
@@ -175,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.
  *
@@ -539,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. */
@@ -603,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
@@ -627,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.
@@ -879,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),
@@ -965,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();
@@ -1062,6 +1098,8 @@ export class AgUiChat extends HTMLElement {
     return [
       "title-text",
       "placement",
+      "collapse-to",
+      "anchor",
       "credentials",
       "user-key",
       "user-name",
@@ -1084,7 +1122,15 @@ 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
+    // has no launcher to drag, and keeps its own dragged spot apart from the
+    // corner's, 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.
@@ -1096,9 +1142,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());
@@ -1418,6 +1474,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.
    *
@@ -1493,10 +1575,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
@@ -1556,6 +1660,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();
+    }
   }
 
   /**
@@ -1756,7 +1866,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
@@ -1785,8 +1895,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.
@@ -1832,6 +1947,104 @@ export class AgUiChat extends HTMLElement {
     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.
    *
@@ -1854,10 +2067,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");
   }
 
   /**
@@ -1867,7 +2077,9 @@ export class AgUiChat extends HTMLElement {
    * `movable` folds two separate reasons into the one answer a caller needs:
    * a placement that places itself owns its position, and a panel that fills
    * the screen has nowhere to go. Reporting them apart would make every caller
-   * re-derive the same conjunction.
+   * re-derive the same conjunction. A corner panel docked under
+   * `collapse-to="bar"` or `"none"` is movable on a wide viewport, like the
+   * corner panel it is.
    */
   describeSurface(): ChatSurfaceReport {
     return this.#placement.describeSurface();
@@ -1882,7 +2094,8 @@ export class AgUiChat extends HTMLElement {
    * the corner it opens from is re-picked, and switching placement hands
    * everything back. What it must not do is claim a move it did not make --
    * hence the boolean, and hence {@link describeSurface} existing so a caller
-   * can ask first.
+   * can ask first. A docked panel moves too, within the room above its bar or
+   * anchor, and remembers the spot as a header drag would.
    */
   moveTo(corner: ChatCorner, options: { readonly announce?: boolean } = {}): boolean {
     return this.#placement.moveTo(corner, options);
@@ -1891,6 +2104,9 @@ export class AgUiChat extends HTMLElement {
   /**
    * 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.
+   * Under `collapse-to="bar"` or `"none"` it also returns a panel the user
+   * dragged off its dock to the dock, and forgets the stored spot; a corner
+   * panel keeps a dragged position.
    */
   resetSize(): void {
     this.#placement.resetSize();
@@ -1905,8 +2121,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:
@@ -1914,7 +2131,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();
@@ -2032,9 +2249,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.
@@ -2053,9 +2298,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).
    *
@@ -2082,16 +2348,19 @@ export class AgUiChat extends HTMLElement {
    * for a host that lists conversations in its own chrome.
    *
    * Resolves once the thread has been replayed, when {@link THREAD_EVENT} has
-   * fired. **A run in flight is cancelled**, as the list and {@link newChat} do;
+   * 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.
    */
-  async switchThread(threadId: string): Promise<void> {
+  switchThread(threadId: string): Promise<void> {
     if (!this.#connected) {
-      return;
+      return Promise.resolve();
     }
-    await this.#history.switchThread(threadId);
+    return this.#history.switchThread(threadId);
   }
 
   /**
@@ -2134,6 +2403,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();
@@ -2478,12 +2754,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);
@@ -2491,7 +2795,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);
   }
 
   /**
@@ -2508,9 +2812,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;
   }

package/src/core/events/bar_height_detail.ts

@@ -0,0 +1,5 @@
+/** `detail` shape of the {@link BAR_HEIGHT_EVENT} CustomEvent. */
+export interface BarHeightDetail {
+  /** The bottom bar's height in CSS px; 0 when no bar is drawn. */
+  readonly height: number;
+}

package/src/dom/highlight_overlay.ts

@@ -10,7 +10,8 @@ export interface HighlightOverlayOptions {
   /**
    * Ring colour, and the flat fallback for the gradient. Default:
    * `--ag-ui-highlight-ring-color` on the target, then on the chat, then the
-   * target's `--ag-ui-accent`, then the chat's accent.
+   * target's `--ag-ui-accent`, then the chat's accent, held to 3:1 against the
+   * surface behind the target.
    */
   readonly color?: string;
   /** The chat whose ring colour and accent to use. Default: the latest connected. */