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

package/src/core/chat_registry.ts

@@ -0,0 +1,53 @@
+/**
+ * The `<ag-ui-chat>` elements connected to this document, oldest first.
+ *
+ * The highlight ring is drawn in the host's page, outside every chat, so a
+ * token set on a chat never reaches it through the cascade. A free `flash()`
+ * still has to answer "which widget is this ring speaking for", and that is a
+ * question about the live elements rather than about any one of them.
+ *
+ * Module-level on purpose, and the second piece of shared mutable state the
+ * repository's `CLAUDE.md` records, beside the claimed storage namespaces. See
+ * the conditions it states, and how this one meets them, before adding a
+ * third.
+ */
+const CONNECTED_CHATS = new Set<HTMLElement>();
+
+/**
+ * One chat's place in the document's list of connected chats.
+ *
+ * Owned one-to-one by an `<ag-ui-chat>`, which joins on connect and leaves on
+ * disconnect, so the list holds exactly the elements that are in a document
+ * now. Typed as `HTMLElement` rather than the element's class, because the DOM
+ * driver reads it and must not import the element.
+ */
+export class ChatRegistration {
+  readonly #chat: HTMLElement;
+
+  constructor(chat: HTMLElement) {
+    this.#chat = chat;
+  }
+
+  /**
+   * Join, as the most recently connected chat. An element moved in the DOM
+   * left on disconnect before it reconnected, so it rejoins at the end and no
+   * entry needs removing first.
+   */
+  join(): void {
+    CONNECTED_CHATS.add(this.#chat);
+  }
+
+  /** Leave. The previous chat, if one is still connected, becomes the latest. */
+  leave(): void {
+    CONNECTED_CHATS.delete(this.#chat);
+  }
+
+  /** The most recently connected chat still in the document, or `null`. */
+  static latest(): HTMLElement | null {
+    let latest: HTMLElement | null = null;
+    for (const chat of CONNECTED_CHATS) {
+      latest = chat;
+    }
+    return latest;
+  }
+}

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/core/events/run_finished_detail.ts

@@ -2,6 +2,12 @@ import type { ToolRun } from "./tool_run.js";
 
 /** `detail` shape of the {@link RUN_FINISHED_EVENT} CustomEvent. */
 export interface RunFinishedDetail {
+  /**
+   * The thread the run belonged to, fixed when its client was built. Not always
+   * the thread on screen: a run stopped by a new chat or a thread switch still
+   * reports once its request closes, and by then another thread is.
+   */
+  readonly threadId: string;
   /** In settle order. Empty when the interaction called no tools. */
   readonly tools: readonly ToolRun[];
   /**

package/src/core/events/thread_detail.ts

@@ -0,0 +1,26 @@
+/** `detail` shape of the {@link THREAD_EVENT} CustomEvent. */
+export interface ThreadDetail {
+  /** The thread now on screen. */
+  readonly threadId: string;
+  /**
+   * The thread on screen before the change: the one the previous event
+   * reported, and `null` before the first, as at the restore when the element
+   * first connects. Equal to `threadId` when the same thread was restored
+   * again (`reload()`, the element connecting again).
+   */
+  readonly previousThreadId: string | null;
+  /**
+   * What changed it:
+   *
+   * - `new`: `newChat()` or the built-in New chat button.
+   * - `switch`: `switchThread()` or a row picked in the conversation list.
+   * - `delete`: the active thread was deleted, and a fresh one took its place.
+   * - `restore`: the stored thread was replayed, on connect or by `reload()`.
+   * - `rescope`: a `user-key` change handed the element to another principal,
+   *   live or while it was out of the document.
+   *
+   * A closed set today; a host should ignore a reason it does not know, so a
+   * later one can be added without breaking it.
+   */
+  readonly reason: "new" | "switch" | "delete" | "restore" | "rescope";
+}

package/src/core/run_handlers.ts

@@ -176,8 +176,13 @@ export class RunHandlers {
    * A handler table for one AG-UI client. Every table built for the current
    * conversation draws into the same transcript and shares its bookkeeping, so
    * a continuation run reports into the interaction the user is looking at.
+   *
+   * `threadId` is the thread the client was built for, named on the
+   * run-finished detail. Taken here rather than read when the run settles,
+   * because a stopped run settles after the reset that stopped it, when the
+   * thread on screen is already the next one.
    */
-  forClient(): AgUiClientHandlers {
+  forClient(threadId: string): AgUiClientHandlers {
     const ledger = this.#ledger;
     const attached = (): boolean => ledger === this.#ledger;
     const { onSettled, ...drawing } = this.#tableFor(ledger);
@@ -190,7 +195,7 @@ export class RunHandlers {
         // Last, so a listener that refetches sees a transcript that has already
         // stopped changing -- and outside the check, because what a run did is
         // true whichever conversation is on screen when it ends.
-        this.#dispatchRunFinished(ledger);
+        this.#dispatchRunFinished(ledger, threadId);
       },
     };
   }
@@ -444,7 +449,7 @@ export class RunHandlers {
    * server is a fact about the run, and a name can appear on both sides across a
    * conversation.
    */
-  #dispatchRunFinished(ledger: RunLedger): void {
+  #dispatchRunFinished(ledger: RunLedger, threadId: string): void {
     const tools: ToolRun[] = ledger.tools.map(({ id, name }) => ({
       name,
       side: ledger.serverSettled.has(id) ? "server" : "client",
@@ -455,7 +460,7 @@ export class RunHandlers {
     ledger.invalidated.clear();
     this.#host.element.dispatchEvent(
       new CustomEvent<RunFinishedDetail>(RUN_FINISHED_EVENT, {
-        detail: { tools, invalidated },
+        detail: { threadId, tools, invalidated },
         bubbles: true,
         composed: true,
       }),

package/src/dom/animations.ts

@@ -8,17 +8,7 @@
 
 import { showHighlightOverlay } from "./highlight_overlay.js";
 import { setNativeChecked, setNativeValue } from "./native_setter.js";
-
-/** Ring colour when the host page has not themed `--ag-ui-accent`. */
-const ACCENT = "#4f46e5";
-
-/**
- * Fallback for the box-shadow rings, which read as a soft halo rather than a
- * line and so carry their own alpha.
- */
-const ACCENT_HALO = "rgba(79, 70, 229, 0.4)";
-
-const ACCENT_PROPERTY = "--ag-ui-accent";
+import { ringColor } from "./ring_color.js";
 
 function delay(ms: number): Promise<void> {
   return new Promise<void>((resolve) => {
@@ -48,19 +38,23 @@ function motionDelay(ms: number): Promise<void> {
 }
 
 /**
- * Resolve the accent colour from the target's own computed style.
+ * Which `<ag-ui-chat>` a ring speaks for, so it is drawn in that chat's colour.
  *
- * `--ag-ui-accent` inherits, so reading it off the element about to be touched
- * picks up whatever the host's cascade produced there, and a themed page is
- * flashed in its own colour rather than this package's indigo.
+ * The ring is drawn in the host's page, which a token set on the chat never
+ * reaches, so the chat is read directly. Unset, it is the most recently
+ * connected chat; a page with two widgets names the one acting.
  */
-function accentColor(el: HTMLElement, fallback: string): string {
-  const themed = window.getComputedStyle(el).getPropertyValue(ACCENT_PROPERTY).trim();
-  return themed === "" ? fallback : themed;
+export interface RingOwnerOptions {
+  /** The chat whose ring colour and accent to use. Default: the latest connected. */
+  chat?: HTMLElement;
 }
 
-function ringShadow(el: HTMLElement): string {
-  return `0 0 0 3px ${accentColor(el, ACCENT_HALO)}`;
+/**
+ * The soft halo the press and toggle rings draw: the ring colour at 40%.
+ * Mixed rather than given its own alpha, so it follows whichever colour won.
+ */
+function ringShadow(el: HTMLElement, chat: HTMLElement | undefined): string {
+  return `0 0 0 3px color-mix(in srgb, ${ringColor(el, chat)} 40%, transparent)`;
 }
 
 /** An element whose `value` can be typed into. */
@@ -93,7 +87,7 @@ export async function typeInto(
   el.dispatchEvent(new Event("change", { bubbles: true }));
 }
 
-export interface HighlightClickOptions {
+export interface HighlightClickOptions extends RingOwnerOptions {
   /** Milliseconds to hold the highlight before clicking. Default 280. */
   highlightMs?: number;
 }
@@ -106,7 +100,7 @@ export async function highlightThenClick(
   const highlightMs = options.highlightMs ?? 280;
   const previousOutline = el.style.outline;
   const previousOffset = el.style.outlineOffset;
-  el.style.outline = `2px solid ${accentColor(el, ACCENT)}`;
+  el.style.outline = `2px solid ${ringColor(el, options.chat)}`;
   el.style.outlineOffset = "2px";
   await delay(highlightMs);
   el.style.outline = previousOutline;
@@ -176,10 +170,14 @@ const FLASH_MS = 1200;
 /** Share of {@link FLASH_MS} spent fading out rather than holding. */
 const FLASH_FADE_RATIO = 1 / 3;
 
-export interface FlashOptions {
+export interface FlashOptions extends RingOwnerOptions {
   /** Total milliseconds the ring is on screen, hold plus fade. Default 1200. */
   flashMs?: number;
-  /** Ring colour. Defaults to the target's `--ag-ui-accent`, else the package accent. */
+  /**
+   * Ring colour. Defaults to `--ag-ui-highlight-ring-color` (on the target,
+   * then on the chat), then the target's `--ag-ui-accent`, then the chat's
+   * accent.
+   */
   color?: string;
   /**
    * Dim everything except the target.
@@ -226,6 +224,7 @@ async function flashRing(
       gradient: options.gradient === true,
       ...(options.color === undefined ? {} : { color: options.color }),
       ...(options.ringPadding === undefined ? {} : { padding: options.ringPadding }),
+      ...(options.chat === undefined ? {} : { chat: options.chat }),
     });
     await delay(flashMs);
     dismiss();
@@ -234,7 +233,7 @@ async function flashRing(
   const previousOutline = el.style.outline;
   const previousOffset = el.style.outlineOffset;
   const previousTransition = el.style.transition;
-  const color = options.color ?? accentColor(el, ACCENT);
+  const color = options.color ?? ringColor(el, options.chat);
   // outline, not box-shadow: a shadow paints outside the border box, so any
   // overflow:hidden ancestor sharing the target's box (a card, a table cell)
   // clips the whole ring away while the helper still reports success.
@@ -273,7 +272,7 @@ export function focusWithFlash(el: HTMLElement, options: FlashOptions = {}): Pro
   return flashRing(el, options, true);
 }
 
-export interface PressOptions {
+export interface PressOptions extends RingOwnerOptions {
   /** Milliseconds to hold the pressed state before clicking. Default 140. */
   pressMs?: number;
 }
@@ -290,7 +289,7 @@ export async function pressThenClick(el: HTMLElement, options: PressOptions = {}
   const previousShadow = el.style.boxShadow;
   el.style.transition = "transform 80ms ease";
   el.style.transform = "scale(0.96)";
-  el.style.boxShadow = ringShadow(el);
+  el.style.boxShadow = ringShadow(el, options.chat);
   await motionDelay(pressMs);
   el.style.transform = previousTransform;
   el.style.transition = previousTransition;
@@ -298,7 +297,7 @@ export async function pressThenClick(el: HTMLElement, options: PressOptions = {}
   el.click();
 }
 
-export interface SelectOptions {
+export interface SelectOptions extends RingOwnerOptions {
   /** Milliseconds to hold the highlight before committing. Default 220. */
   highlightMs?: number;
 }
@@ -330,7 +329,7 @@ export async function selectOption(
   const highlightMs = options.highlightMs ?? 220;
   const previousOutline = el.style.outline;
   const previousOffset = el.style.outlineOffset;
-  el.style.outline = `2px solid ${accentColor(el, ACCENT)}`;
+  el.style.outline = `2px solid ${ringColor(el, options.chat)}`;
   el.style.outlineOffset = "2px";
   await motionDelay(highlightMs);
   setNativeValue(el, option.value);
@@ -340,7 +339,7 @@ export async function selectOption(
   el.style.outlineOffset = previousOffset;
 }
 
-export interface ToggleOptions {
+export interface ToggleOptions extends RingOwnerOptions {
   /** Milliseconds to hold the flash. Default 200. */
   flashMs?: number;
 }
@@ -356,7 +355,7 @@ export async function toggleControl(
 ): Promise<void> {
   const flashMs = options.flashMs ?? 200;
   const previousShadow = el.style.boxShadow;
-  el.style.boxShadow = ringShadow(el);
+  el.style.boxShadow = ringShadow(el, options.chat);
   await motionDelay(flashMs);
   setNativeChecked(el, checked);
   el.dispatchEvent(new Event("input", { bubbles: true }));

package/src/dom/highlight_overlay.ts

@@ -1,7 +1,5 @@
 import { HIGHLIGHT_OVERLAY_Z_INDEX } from "../constants.js";
-
-/** The package accent, used when the host has themed nothing. */
-const ACCENT = "#4f46e5";
+import { ringColor } from "./ring_color.js";
 
 /** How the overlay is drawn around the element being pointed at. */
 export interface HighlightOverlayOptions {
@@ -9,8 +7,15 @@ export interface HighlightOverlayOptions {
   readonly scrim?: boolean;
   /** Draw the ring as a moving gradient rather than a flat colour. Default false. */
   readonly gradient?: boolean;
-  /** Ring colour, and the flat fallback for the gradient. */
+  /**
+   * 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, 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. */
+  readonly chat?: HTMLElement;
   /** Gap between the target's box and the ring. Default 4. */
   readonly padding?: number;
   /** Corner radius of the cut-out and the ring. Default: the target's own. */
@@ -205,7 +210,7 @@ function safeColor(value: string | undefined): string | null {
  * the padding box, leaving the frame.
  */
 function ringPaint(target: HTMLElement, options: HighlightOverlayOptions): string {
-  const color = safeColor(options.color) ?? tokenOn(target, "--ag-ui-accent", ACCENT);
+  const color = safeColor(options.color) ?? ringColor(target, options.chat);
   if (options.gradient !== true) {
     return `border-color: ${color}`;
   }

package/src/dom/ring_color.ts

@@ -0,0 +1,222 @@
+import { ChatRegistration } from "../core/chat_registry.js";
+
+/** The public ring token, read from the target and then from the chat. */
+const RING_TOKEN = "--ag-ui-highlight-ring-color";
+
+/** The accent a host themes its page with, read from the target. */
+const ACCENT_TOKEN = "--ag-ui-accent";
+
+/**
+ * The accent the chat actually resolved, its theme's default included. Read
+ * through the private alias because the public token is unset on a page that
+ * themed nothing, which is exactly the page this exists for.
+ */
+const CHAT_ACCENT = "--_accent";
+
+/** The package indigo, for a page with no chat and no theming at all. */
+const PACKAGE_ACCENT = "#4f46e5";
+
+/**
+ * The colour a highlight ring is drawn in when the caller passed none.
+ *
+ * In order: `--ag-ui-highlight-ring-color` on the target, the same token on
+ * the chat, the target's `--ag-ui-accent`, the chat's resolved accent, the
+ * package indigo. The target's accent stays above the chat's own default so a
+ * host that themes `--ag-ui-accent` on its page keeps the rings it has; the
+ * ring token sits above both so a host can keep the ring apart from the accent.
+ *
+ * Only the chat's own accent is adjusted, because it follows the widget's
+ * scheme rather than the page's: a dark widget's near-white accent on a light
+ * page all but disappears. It is held to 3:1 against the surface behind the
+ * target (see {@link surfaceBehind}): the accent as resolved if it holds, else
+ * the other half of the chat's light-dark pair, else the accent stepped toward
+ * black or white. Every value above it is a choice someone made, and is drawn
+ * as given.
+ *
+ * `chat` defaults to the most recently connected `<ag-ui-chat>`, the common
+ * page with one widget. A page with two passes the one the ring speaks for.
+ */
+export function ringColor(target: HTMLElement, chat?: HTMLElement): string {
+  const onTarget = readToken(target, RING_TOKEN);
+  if (onTarget !== "") {
+    return onTarget;
+  }
+  const owner = chat ?? ChatRegistration.latest();
+  const onChat = owner === null ? "" : resolveOn(owner, RING_TOKEN);
+  if (onChat !== "") {
+    return onChat;
+  }
+  const accent = readToken(target, ACCENT_TOKEN);
+  if (accent !== "") {
+    return accent;
+  }
+  if (owner === null) {
+    return PACKAGE_ACCENT;
+  }
+  const chatAccent = resolveOn(owner, CHAT_ACCENT);
+  return chatAccent === "" ? PACKAGE_ACCENT : legible(owner, chatAccent, target);
+}
+
+/** The contrast a ring needs against what it is drawn on (WCAG 2.4.13). */
+const RING_CONTRAST = 3;
+
+/** How far each step moves a failing accent toward black or white. */
+const STEP = 0.1;
+
+type Rgba = readonly [number, number, number, number];
+
+/**
+ * `accent`, or the nearest variant of it that holds {@link RING_CONTRAST}
+ * against the surface behind `target`.
+ *
+ * Colours are compared as sRGB bytes painted onto a one-pixel canvas, the one
+ * reading that turns a resolved color-mix() or oklch() into numbers. Where
+ * there is no 2d context to paint on, nothing can be measured, and the accent
+ * is drawn as it was.
+ */
+function legible(chat: HTMLElement, accent: string, target: HTMLElement): string {
+  const paint = document.createElement("canvas").getContext("2d", { willReadFrequently: true });
+  if (paint === null) {
+    return accent;
+  }
+  const bytes = (color: string): Rgba => {
+    paint.clearRect(0, 0, 1, 1);
+    paint.fillStyle = "rgb(0 0 0 / 0)";
+    paint.fillStyle = color;
+    paint.fillRect(0, 0, 1, 1);
+    const [r = 0, g = 0, b = 0, a = 0] = paint.getImageData(0, 0, 1, 1).data;
+    return [r, g, b, a / 255];
+  };
+  const surface = surfaceBehind(target, bytes);
+  const holds = (color: Rgba): boolean => contrast(over(color, surface), surface) >= RING_CONTRAST;
+  const own = [accent, resolveOn(chat, CHAT_ACCENT, "light"), resolveOn(chat, CHAT_ACCENT, "dark")];
+  const fit = own.find((candidate) => holds(bytes(candidate)));
+  if (fit !== undefined) {
+    return fit;
+  }
+  // Black or white, whichever the surface sets off better, holds at least
+  // 4.5:1 against any surface, so the walk always ends by the last step.
+  const from = over(bytes(accent), surface);
+  const black: Rgba = [0, 0, 0, 1];
+  const white: Rgba = [255, 255, 255, 1];
+  const toward = contrast(black, surface) > contrast(white, surface) ? black : white;
+  let step = 1;
+  while (!holds(mix(from, toward, step * STEP))) {
+    step += 1;
+  }
+  const [r, g, b] = mix(from, toward, step * STEP);
+  return `rgb(${r}, ${g}, ${b})`;
+}
+
+/**
+ * The colour of the surface a ring around `target` is drawn on, as opaque
+ * sRGB bytes.
+ *
+ * The ring sits outside the target's border box (the flash outline is offset
+ * from it, the overlay leaves a gap), so the target's own fill is not under
+ * it: a white field on a dark page is ringed on the dark page. The surface is
+ * every background from the target's parent up, composited until one is
+ * opaque, over the page canvas, which follows the root's colour scheme. A
+ * background image is not read; its colour beneath is.
+ */
+function surfaceBehind(target: HTMLElement, bytes: (color: string) => Rgba): Rgba {
+  const layers: Rgba[] = [];
+  for (let el = parentOf(target); el !== null; el = parentOf(el)) {
+    const layer = bytes(window.getComputedStyle(el).backgroundColor);
+    layers.push(layer);
+    if (layer[3] === 1) {
+      break;
+    }
+  }
+  const probe = document.createElement("span");
+  probe.hidden = true;
+  probe.style.color = "Canvas";
+  document.documentElement.appendChild(probe);
+  let surface = bytes(window.getComputedStyle(probe).color);
+  probe.remove();
+  for (const layer of layers.reverse()) {
+    surface = over(layer, surface);
+  }
+  return surface;
+}
+
+/** The element above `el`, crossing out of a shadow root to its host. */
+function parentOf(el: Element): Element | null {
+  if (el.parentElement !== null) {
+    return el.parentElement;
+  }
+  const root = el.getRootNode();
+  return root instanceof ShadowRoot ? root.host : null;
+}
+
+/** `top` painted over the opaque `under`. */
+function over(top: Rgba, under: Rgba): Rgba {
+  return mix(under, top, top[3]);
+}
+
+/** `from` moved `share` of the way to `to`, as opaque bytes. */
+function mix(from: Rgba, to: Rgba, share: number): Rgba {
+  const channel = (index: 0 | 1 | 2): number =>
+    Math.round(from[index] + (to[index] - from[index]) * share);
+  return [channel(0), channel(1), channel(2), 1];
+}
+
+/** WCAG relative luminance of opaque sRGB bytes. */
+function luminance([r, g, b]: Rgba): number {
+  const linear = (channel: number): number => {
+    const c = channel / 255;
+    return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * linear(r) + 0.7152 * linear(g) + 0.0722 * linear(b);
+}
+
+/** WCAG contrast ratio between two opaque colours. */
+function contrast(a: Rgba, b: Rgba): number {
+  const [la, lb] = [luminance(a), luminance(b)];
+  return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+}
+
+function readToken(el: HTMLElement, name: string): string {
+  return window.getComputedStyle(el).getPropertyValue(name).trim();
+}
+
+/**
+ * The custom property `name` on `chat`, as the colour it computes to there, or
+ * `""` when it is unset or not a colour.
+ *
+ * Resolved inside the chat rather than handed to the target, because the
+ * chat's colours are `light-dark()` pairs and a custom property keeps them
+ * unresolved: written onto an element in the page, the pair would pick its
+ * half by the page's colour scheme, so a dark widget on a light page would ring
+ * in its light-mode accent. A probe inside the shadow tree inherits the chat's
+ * scheme, and its computed `color` is the resolved value.
+ *
+ * An element with no open shadow root (a host passing something other than a
+ * chat) is read as it is, unresolved; that is the best it offers. `scheme`
+ * forces one half of the pair, which is how a ring finds the chat's other
+ * accent when its own scheme's is too faint against the page.
+ */
+function resolveOn(chat: HTMLElement, name: string, scheme?: "light" | "dark"): string {
+  const value = readToken(chat, name);
+  const root = chat.shadowRoot;
+  if (value === "" || root === null) {
+    return value;
+  }
+  const probe = document.createElement("span");
+  probe.hidden = true;
+  // A scheme named here picks that half of a light-dark() pair instead of
+  // the one the chat's own scheme picks.
+  if (scheme !== undefined) {
+    probe.style.colorScheme = scheme;
+  }
+  probe.style.color = value;
+  // An unparseable value leaves the declaration empty, and the probe would
+  // then report the colour it inherits instead of saying it has none.
+  if (probe.style.color === "") {
+    return "";
+  }
+  root.appendChild(probe);
+  const resolved = window.getComputedStyle(probe).color;
+  probe.remove();
+  return resolved;
+}

package/src/index.ts

@@ -2,6 +2,7 @@
 
 export {
   ATTACHMENT_EVENT,
+  BAR_HEIGHT_EVENT,
   CHART_ACTIVITY_TYPE,
   COMPACTION_ACTIVITY_TYPE,
   CUSTOM_AGENT_EVENT,
@@ -17,10 +18,13 @@ export {
   STATE_EVENT,
   SUBMIT_EVENT,
   SUGGESTIONS_ACTIVITY_TYPE,
+  THREAD_EVENT,
   TOGGLE_EVENT,
   TOOL_CALL_STATUS,
   TOOL_DISPLAY,
+  TOOL_GROUP_DISPLAY,
   TOOL_OUTCOME,
+  type ToolGroupDisplayMode,
   UNREAD_EVENT,
   X_CONFIRM_KEY,
   X_DESTRUCTIVE_KEY,
@@ -57,12 +61,14 @@ export {
 } from "./core/create_http_agent.js";
 export { defineAgUiChat } from "./core/define_ag_ui_chat.js";
 export type { AttachmentsDetail } from "./core/events/attachments_detail.js";
+export type { BarHeightDetail } from "./core/events/bar_height_detail.js";
 export type { CustomAgentDetail } from "./core/events/custom_agent_detail.js";
 export type { FeedbackDetail } from "./core/events/feedback_detail.js";
 export type { InvalidateDetail } from "./core/events/invalidate_detail.js";
 export type { RunFinishedDetail } from "./core/events/run_finished_detail.js";
 export type { StateDetail } from "./core/events/state_detail.js";
 export type { SubmitDetail } from "./core/events/submit_detail.js";
+export type { ThreadDetail } from "./core/events/thread_detail.js";
 export type { ToggleDetail } from "./core/events/toggle_detail.js";
 export type { ToolRun } from "./core/events/tool_run.js";
 export type { UnreadDetail } from "./core/events/unread_detail.js";
@@ -89,6 +95,7 @@ export {
   type PressOptions,
   prefersReducedMotion,
   pressThenClick,
+  type RingOwnerOptions,
   type ScrollOptions,
   type SelectOptions,
   scrollIntoCenterView,

package/src/tools/chat_surface_tools.ts

@@ -1,4 +1,5 @@
 import { X_SUMMARY_KEY } from "../constants.js";
+import type { CollapseTarget } from "../ui/placement/surface_for.js";
 import type { ClientTool } from "./client_tool_registry.js";
 
 /** Every corner the panel can be sent to, in the order the schema states them. */
@@ -11,7 +12,13 @@ export type ChatCorner = (typeof CHAT_CORNERS)[number];
 export interface ChatSurfaceReport {
   /** The placement in force, or `null` when the host set none. */
   readonly placement: string | null;
-  /** Whether the panel is currently at its launcher. */
+  /**
+   * What the panel collapses to: `launcher`, `rail`, `header`, `bar` (the
+   * bottom bar it rises from), `none` (hidden, brought back by the host's own
+   * control), or `null` when it cannot collapse.
+   */
+  readonly collapseTo: CollapseTarget;
+  /** Whether the panel is currently collapsed. */
   readonly collapsed: boolean;
   /** Whether this placement has a collapsed state at all. */
   readonly collapsible: boolean;
@@ -154,9 +161,11 @@ export function createChatSurfaceTools(surface: ChatSurface): ClientTool[] {
             moved: false,
             reason: report.fullBleed
               ? "the panel fills the screen, so there is nowhere to move it to"
-              : report.draggable === false
-                ? "this page has turned off moving the panel"
-                : `the "${report.placement ?? ""}" placement owns the panel's position`,
+              : report.collapseTo === "bar" || report.collapseTo === "none"
+                ? "the panel is docked: it rises from the page's bottom bar and stays there"
+                : report.draggable === false
+                  ? "this page has turned off moving the panel"
+                  : `the "${report.placement ?? ""}" placement owns the panel's position`,
             suggestion: report.collapsible ? "minimise_chat" : null,
           };
         }
@@ -166,9 +175,10 @@ export function createChatSurfaceTools(surface: ChatSurface): ClientTool[] {
     {
       name: "minimise_chat",
       description:
-        "Collapse your own panel to its launcher, so the user can see the whole page. " +
-        "The launcher stays visible and reopens it. Answers `minimised: false` when the " +
-        "placement has no collapsed state, which is the case for a full-page chat.",
+        "Collapse your own panel, so the user can see the whole page. The user reopens " +
+        "it from where it collapsed to (a launcher, a rail, a bottom bar or the page's " +
+        "own control). Answers `minimised: false` when the placement has no collapsed " +
+        "state, which is the case for a full-page chat.",
       parameters: {
         type: "object",
         properties: {},
@@ -180,7 +190,7 @@ export function createChatSurfaceTools(surface: ChatSurface): ClientTool[] {
         if (!report.collapsible) {
           return {
             minimised: false,
-            reason: "this placement has no collapsed state, so there is no launcher to return to",
+            reason: "this placement has no collapsed state, so there is nothing to minimise to",
           };
         }
         surface.setCollapsed(true, { announce: true });