@artooi/ag-ui-web-component 0.45.0 → 0.47.0

package/src/core/ag_ui_chat.ts

@@ -10,6 +10,7 @@ import {
   STATE_EVENT,
   SUBMIT_EVENT,
   SUGGESTIONS_ACTIVITY_TYPE,
+  THREAD_EVENT,
   TOGGLE_EVENT,
   TOOL_DISPLAY,
   UNREAD_EVENT,
@@ -75,6 +76,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,
@@ -85,6 +87,7 @@ import {
 import { type AgentFactory, createHttpAgent } from "./create_http_agent.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";
@@ -750,6 +753,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();
   /**
@@ -767,6 +775,7 @@ export class AgUiChat extends HTMLElement {
     askUser: () => this.askUser,
     askUserRenderer: () => this.askUserRenderer,
     decision: this.#decision,
+    setAsking: (callId, asking) => this.#transcript.setAsking(callId, asking),
     ensureGroup: () => this.#transcript.ensureGroup(),
     strings: () => this.#strings,
     hidePending: () => this.#transcript.hidePending(),
@@ -780,6 +789,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.
@@ -820,6 +831,7 @@ export class AgUiChat extends HTMLElement {
       resolveTool: (name) => this.#tools.resolve(name),
       toolSummaries: () => this.toolSummaries,
       serverSummary: (name) => this.#tools.summary(name),
+      toolDisplay: () => this.toolDisplay,
       // A thunk over the live property, not the property itself: the card keeps
       // this for the life of the call, and the result region is filled when the
       // tool settles -- which can be long after a host set the hook.
@@ -1041,6 +1053,7 @@ export class AgUiChat extends HTMLElement {
       cancelRun: () => this.#cancelRun(),
       resetState: () => this.#resetState(),
       setRunning: (running) => this.#setRunning(running),
+      threadChanged: (threadId, reason) => this.#dispatchThread(threadId, reason),
     });
   }
 
@@ -1377,22 +1390,28 @@ export class AgUiChat extends HTMLElement {
 
   /**
    * How much detail tool-call cards show, from the `data-tool-display`
-   * attribute (`minimal` / `inline` / `compact` / `full`). Defaults to `full`.
+   * attribute (`grouped` / `minimal` / `inline` / `compact` / `full`).
+   * Defaults to `grouped`, for an absent attribute and for a value the
+   * element does not know; `full` is the per-call card default before
+   * `grouped` existed.
    *
-   * Applied by the shadow CSS from the attribute itself, so changing it
-   * restyles every card already in the transcript rather than only the ones
-   * built afterwards.
+   * The four card modes are applied by the shadow CSS from the attribute
+   * itself, so changing between them restyles every card already in the
+   * transcript. Whether calls fold into a step group is decided as each card
+   * is built: switching to `grouped` folds only the calls drawn afterwards,
+   * and switching away flattens the existing groups, again by CSS.
    */
   get toolDisplay(): ToolDisplayMode {
     const attr = this.getAttribute("data-tool-display");
     if (
       attr === TOOL_DISPLAY.INLINE ||
       attr === TOOL_DISPLAY.MINIMAL ||
-      attr === TOOL_DISPLAY.COMPACT
+      attr === TOOL_DISPLAY.COMPACT ||
+      attr === TOOL_DISPLAY.FULL
     ) {
       return attr;
     }
-    return TOOL_DISPLAY.FULL;
+    return TOOL_DISPLAY.GROUPED;
   }
 
   set toolDisplay(value: ToolDisplayMode) {
@@ -1440,6 +1459,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();
@@ -1522,7 +1542,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
@@ -1586,7 +1609,7 @@ export class AgUiChat extends HTMLElement {
     await Promise.all([
       this.#tools.fetchCatalog(),
       this.#skills.fetch(),
-      this.#history.rehydrate(),
+      this.#history.rehydrate("restore"),
     ]);
   }
 
@@ -1603,6 +1626,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();
@@ -1786,6 +1810,28 @@ 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;
+  }
+
   /**
    * Whether to mount collapsed.
    *
@@ -1842,6 +1888,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);
@@ -1952,7 +2006,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();
   }
 
@@ -2023,6 +2077,36 @@ 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 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> {
+    if (!this.#connected) {
+      return;
+    }
+    await 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 +2142,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
@@ -2332,6 +2417,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";
@@ -2343,7 +2434,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,
@@ -2352,6 +2444,7 @@ export class AgUiChat extends HTMLElement {
       this.#composerHint,
       this.#queuedRow,
       this.#attachSlot,
+      aboveComposer,
       inputRow,
       footer,
       this.#drawer.element,
@@ -2586,6 +2679,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).
    *
@@ -2607,6 +2716,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();
     }
@@ -2998,7 +3109,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),

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/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,14 @@ 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.
+   */
   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 +209,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}`;
   }