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

package/src/core/upload_attachment.ts

@@ -3,16 +3,13 @@ import type { AttachmentRef } from "./attachment.js";
 /**
  * The composer's upload contract: take a `File`, report `0..1` progress, and
  * resolve to a durable {@link AttachmentRef}. The built-in handler is
- * {@link uploadAttachment} (multipart POST); a host swaps in its own — e.g. a
- * `tus-js-client` or direct-to-S3 adapter — via `AgUiChat.uploadHandler`,
- * **without** touching the tray, the chips, or the AG-UI wire (refs are
- * transport-agnostic).
+ * {@link uploadAttachment}; a host swaps in its own (a `tus-js-client` or
+ * direct-to-S3 adapter) via `AgUiChat.uploadHandler` without touching the tray,
+ * the chips, or the AG-UI wire, refs being transport-agnostic.
  *
- * The optional third `signal` argument lets the tray abort an in-flight upload
- * when its chip is removed (or the element is torn down), so a cancelled upload
- * doesn't orphan a server-side file. It is non-breaking: existing two-argument
- * handlers keep working (the extra argument is simply ignored), and a custom
- * handler that honours it should abort its own transport when the signal fires.
+ * The optional `signal` fires when the tray removes a chip or the element is
+ * torn down; a handler that honours it should abort its own transport, so a
+ * cancelled upload doesn't orphan a server-side file.
  */
 export type UploadHandler = (
   file: File,
@@ -28,11 +25,11 @@ export interface UploadOptions {
   readonly headers?: Record<string, string>;
   /**
    * Cookie policy, spelled as `fetch`'s `credentials` mode for consistency with
-   * the component's other endpoints — but carried by `XMLHttpRequest`, which
-   * only has the two-state `withCredentials`. `"include"` sets it; every other
-   * value leaves it off, which matches `"same-origin"`. `"omit"` therefore
-   * **cannot** be honoured for a same-origin upload (XHR always sends cookies
-   * there); use a custom {@link UploadHandler} if that matters.
+   * the other endpoints, but carried by `XMLHttpRequest`'s two-state
+   * `withCredentials`: `"include"` sets it and every other value leaves it off,
+   * matching `"same-origin"`. `"omit"` therefore cannot be honoured for a
+   * same-origin upload, XHR always sending cookies there; use a custom
+   * {@link UploadHandler} if that matters.
    */
   readonly credentials?: RequestCredentials;
   /** Progress callback, `0..1`, fired as the body uploads. */
@@ -45,10 +42,10 @@ export interface UploadOptions {
  * Upload one file to the attachments endpoint and resolve to its durable
  * {@link AttachmentRef}.
  *
- * Uses `XMLHttpRequest` (not `fetch`) for real upload-progress events: the file
- * is sent as multipart under the `file` field, with the element's `headers` so
- * CSRF / auth ride along exactly like the skills/tools fetches. A non-2xx
- * response or a network/abort error rejects, so the tray can show an error chip.
+ * Uses `XMLHttpRequest` rather than `fetch` for real upload-progress events.
+ * The file goes as multipart under the `file` field with the element's
+ * `headers`, so CSRF / auth ride along; a non-2xx response or a network/abort
+ * error rejects, letting the tray show an error chip.
  */
 export function uploadAttachment(file: File, options: UploadOptions): Promise<AttachmentRef> {
   return new Promise<AttachmentRef>((resolve, reject) => {
@@ -57,9 +54,9 @@ export function uploadAttachment(file: File, options: UploadOptions): Promise<At
 
     const xhr = new XMLHttpRequest();
     xhr.open("POST", options.url);
-    // Cross-origin cookies ride only when asked for, exactly as with the fetch
-    // sites; without this an upload to another subdomain is anonymous and 401s
-    // while the run itself succeeds.
+    // Cross-origin cookies ride only when asked for, as at the fetch sites.
+    // Without this an upload to another subdomain goes anonymous and 401s while
+    // the run itself succeeds.
     xhr.withCredentials = options.credentials === "include";
     for (const [key, value] of Object.entries(options.headers ?? {})) {
       xhr.setRequestHeader(key, value);

package/src/core/utils.ts

@@ -2,13 +2,11 @@
 
 /**
  * Overlay a `credentials` mode onto a fetch `init`, or hand the `init` back
- * untouched when the caller has none configured.
+ * untouched when none is configured.
  *
- * Absent and `undefined` are not the same thing here. `exactOptionalPropertyTypes`
- * rejects an explicit `credentials: undefined`, and writing one anyway would
- * state a mode where the point is to leave the browser's own default in place.
- * Every fetch this component makes has to make that choice, so it is made in one
- * place rather than repeated (and eventually forgotten) at each call site.
+ * Absent and `undefined` differ: `exactOptionalPropertyTypes` rejects an
+ * explicit `credentials: undefined`, and writing one anyway would state a mode
+ * where the point is to leave the browser's own default in place.
  */
 export function withCredentials(
   init: RequestInit | undefined,

package/src/dom/animations.ts

@@ -28,12 +28,11 @@ function delay(ms: number): Promise<void> {
 /**
  * Whether the user has asked the OS/browser to minimise motion.
  *
- * Honoured by every primitive that *moves* something: the action animations
- * skip their hold delays, `scrollIntoCenterView` jumps instead of gliding, and
- * the focus flash drops its fade while still holding the ring long enough to be
- * seen — reduced motion asks for no animation, not for no feedback. The
- * character-typing and highlight primitives predate this and keep their
- * explicit-duration contract.
+ * Honoured by every primitive that moves something: hold delays are skipped,
+ * `scrollIntoCenterView` jumps instead of gliding, and the flash drops its fade
+ * but still holds the ring long enough to be seen — reduced motion asks for no
+ * animation, not for no feedback. `typeInto` and `highlightThenClick` keep
+ * their explicit-duration contract instead.
  */
 export function prefersReducedMotion(): boolean {
   return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
@@ -48,11 +47,11 @@ function motionDelay(ms: number): Promise<void> {
 }
 
 /**
- * Resolve the accent colour from the **target's** computed style.
+ * Resolve the accent colour from the target's own computed style.
  *
- * `--ag-ui-accent` inherits, so reading it off the element the agent is about
- * to touch picks up whatever the host's cascade produced there — a themed page
- * gets flashed in its own colour instead of this package's indigo.
+ * `--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.
  */
 function accentColor(el: HTMLElement, fallback: string): string {
   const themed = window.getComputedStyle(el).getPropertyValue(ACCENT_PROPERTY).trim();
@@ -72,8 +71,8 @@ export interface TypeOptions {
 }
 
 /**
- * Clear ``el`` and type ``value`` one character at a time, firing ``input``
- * events as a real user would, then a final ``change`` event.
+ * Clear `el` and type `value` one character at a time, firing an `input` event
+ * per character as a real user would, then a final `change`.
  */
 export async function typeInto(
   el: TextLikeElement,
@@ -98,7 +97,7 @@ export interface HighlightClickOptions {
   highlightMs?: number;
 }
 
-/** Outline ``el``, pause so the user sees it, then click and restore. */
+/** Outline `el`, pause so the user sees it, then click and restore. */
 export async function highlightThenClick(
   el: HTMLElement,
   options: HighlightClickOptions = {},
@@ -128,12 +127,11 @@ const SCROLL_SETTLE_MS = 600;
 const SCROLL_START_MS = 100;
 
 /**
- * Scroll ``el`` to the vertical centre of the viewport.
+ * Scroll `el` to the vertical centre of the viewport.
  *
- * The returned promise resolves once the scroll has settled, so a caller can
- * hold its animation until the element has stopped moving — a ring drawn
- * mid-glide lands somewhere the user is not looking yet. Awaiting is optional;
- * the scroll itself is requested synchronously.
+ * Resolves once the scroll settles, so a caller can hold its animation until
+ * the element stops moving — a ring drawn mid-glide lands where the user is not
+ * looking yet. Awaiting is optional; the scroll is requested synchronously.
  */
 export function scrollIntoCenterView(el: HTMLElement, options: ScrollOptions = {}): Promise<void> {
   const reduced = prefersReducedMotion();
@@ -161,12 +159,10 @@ export function scrollIntoCenterView(el: HTMLElement, options: ScrollOptions = {
     // Neither event bubbles, and both fire on whichever ancestor actually
     // scrolled, so listen on the document in the capture phase.
     //
-    // Two timeouts, because two things can go wrong. An element already in
-    // view never scrolls and so never fires scrollend — waiting the full
-    // budget for it would add dead time to every action, hence the short
-    // did-anything-move probe. Once something is moving, the longer budget
-    // covers browsers that do not implement scrollend at all (Safari gained it
-    // only recently).
+    // Two timeouts, for two failure modes: an element already in view never
+    // scrolls and so never fires scrollend (the short did-anything-move probe),
+    // and once something is moving the longer budget covers browsers without
+    // scrollend at all.
     timer = setTimeout(settle, SCROLL_START_MS);
     document.addEventListener("scroll", started, true);
     document.addEventListener("scrollend", settle, true);
@@ -180,10 +176,7 @@ const FLASH_MS = 1200;
 const FLASH_FADE_RATIO = 1 / 3;
 
 export interface FlashOptions {
-  /**
-   * Total milliseconds the ring is on screen, hold plus fade. Default 1200 —
-   * long enough for someone who does not yet know where to look to find it.
-   */
+  /** 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. */
   color?: string;
@@ -220,8 +213,8 @@ async function flashRing(
   const fadeMs = prefersReducedMotion() ? 0 : Math.round(flashMs * FLASH_FADE_RATIO);
   await delay(flashMs - fadeMs);
   if (fadeMs > 0) {
-    // Setting the transition and the new colour in the same task is fine: the
-    // browser starts transitions from the after-change style.
+    // Transition and new colour in the same task is fine: the browser starts
+    // transitions from the after-change style.
     el.style.transition = `outline-color ${fadeMs}ms ease-out`;
     el.style.outline = "3px solid transparent";
     await delay(fadeMs);
@@ -232,9 +225,9 @@ async function flashRing(
 }
 
 /**
- * Flash a ring around ``el`` without touching focus.
+ * Flash a ring around `el` without touching focus.
  *
- * Prefer this over {@link focusWithFlash} when the point is to *show* the user
+ * Prefer this over {@link focusWithFlash} when the point is to show the user
  * something: moving focus steals it from the composer, can fire blur validation
  * on whatever they were mid-edit in, and can close an open menu.
  */
@@ -243,11 +236,8 @@ export function flash(el: HTMLElement, options: FlashOptions = {}): Promise<void
 }
 
 /**
- * Focus ``el`` and flash a ring around it.
- *
- * Focus moves unless ``options.focus`` says otherwise — that is the documented
- * behaviour of this name. Use {@link flash} for a highlight that leaves focus
- * where the user put it.
+ * Focus `el` and flash a ring around it. Focus moves unless `options.focus`
+ * says otherwise; use {@link flash} to leave focus where the user put it.
  */
 export function focusWithFlash(el: HTMLElement, options: FlashOptions = {}): Promise<void> {
   return flashRing(el, options, true);
@@ -259,9 +249,9 @@ export interface PressOptions {
 }
 
 /**
- * Show a brief "pressed" affordance on a button/control — a slight scale-down
- * plus accent ring — then click it and restore. Reads as an actual press, not
- * just an outline (cf. {@link highlightThenClick}).
+ * Show a brief pressed affordance on a control — a slight scale-down plus
+ * accent ring — then click it and restore. Reads as a press rather than the
+ * plain outline {@link highlightThenClick} draws.
  */
 export async function pressThenClick(el: HTMLElement, options: PressOptions = {}): Promise<void> {
   const pressMs = options.pressMs ?? 140;
@@ -283,7 +273,7 @@ export interface SelectOptions {
   highlightMs?: number;
 }
 
-/** Find an option in ``el`` whose value or visible text equals ``value``. */
+/** Find an option in `el` whose value or visible text equals `value`. */
 function findOption(el: HTMLSelectElement, value: string): HTMLOptionElement | null {
   for (const option of Array.from(el.options)) {
     if (option.value === value || option.text === value) {
@@ -295,7 +285,7 @@ function findOption(el: HTMLSelectElement, value: string): HTMLOptionElement | n
 
 /**
  * Outline a `<select>`, pause so the user sees the pick, then set it to the
- * option matching ``value`` (by value or visible text) and fire `input` +
+ * option matching `value` (by value or visible text) and fire `input` +
  * `change`. Throws when no option matches.
  */
 export async function selectOption(
@@ -326,7 +316,7 @@ export interface ToggleOptions {
 }
 
 /**
- * Flash a ring around a checkbox/radio, set its ``checked`` state, and fire
+ * Flash a ring around a checkbox/radio, set its `checked` state, and fire
  * `input` + `change` so frameworks observe the flip.
  */
 export async function toggleControl(

package/src/dom/dom_driver.ts

@@ -25,16 +25,16 @@ import { setNativeChecked, setNativeValue } from "./native_setter.js";
  */
 
 /**
- * A field has to hold focus to be typed into, so ``focus`` is not on offer
- * here — everything else the flash takes is.
+ * Every flash option except `focus`, which is not on offer: a field has to hold
+ * focus to be typed into.
  */
 export interface FillFieldOptions extends TypeOptions, Omit<FlashOptions, "focus"> {}
 
 /**
- * Scroll to, focus (with a flash), and type ``value`` into a text field.
+ * Scroll to, focus (with a flash), and type `value` into a text field.
  *
- * The scroll is awaited: typing into an element that is still gliding past
- * shows the user nothing.
+ * The scroll is awaited — typing into an element still gliding past shows the
+ * user nothing.
  */
 export async function fillField(
   el: TextLikeElement,
@@ -82,8 +82,8 @@ export async function toggleCheckbox(
 }
 
 /**
- * Set a `<select>` or checkbox value without typing animation, dispatching the
- * ``input`` and ``change`` events frameworks listen for.
+ * Set a `<select>` or checkbox value without animation, dispatching the `input`
+ * and `change` events frameworks listen for.
  */
 export function setControlValue(
   el: HTMLInputElement | HTMLSelectElement,

package/src/dom/native_setter.ts

@@ -1,18 +1,17 @@
-// Set a control's `value` / `checked` through the **native prototype setter**,
-// so framework value-tracking sees the change. React (and Vue/Svelte) replace
-// the element's `value`/`checked` setter with a tracked one; assigning
-// `el.value = x` directly hits that override and the subsequent `input` event
-// carries no change, so the field looks filled but the framework's state stays
-// empty. Calling the original prototype setter, then dispatching `input`, makes
-// `fillField` / `typeInto` / `setControlValue` work on framework-controlled
-// inputs out of the box.
+// Set a control's `value` / `checked` through the native prototype setter, so
+// framework value-tracking sees the change. React (and Vue/Svelte) replace the
+// element's own setter with a tracked one, so `el.value = x` hits that override
+// and the following `input` event carries no change: the field looks filled
+// while the framework's state stays empty. Calling the original prototype
+// setter and then dispatching `input` avoids that.
 
 type ValueSetter = (this: HTMLElement, value: string) => void;
 type CheckedSetter = (this: HTMLElement, checked: boolean) => void;
 
-/** The original prototype setter for ``prop`` on ``proto``. */
+/** The original prototype setter for `prop` on `proto`. */
 function prototypeSetter(proto: object, prop: string): (this: HTMLElement, value: never) => void {
-  // Captured once at module load; DOM environments always define these.
+  // Captured once at module load; DOM environments always define these, which
+  // is what makes the descriptor cast safe.
   const setter = (Object.getOwnPropertyDescriptor(proto, prop) as PropertyDescriptor).set;
   return setter as unknown as (this: HTMLElement, value: never) => void;
 }
@@ -22,7 +21,7 @@ const setTextareaValue = prototypeSetter(HTMLTextAreaElement.prototype, "value")
 const setSelectValue = prototypeSetter(HTMLSelectElement.prototype, "value") as ValueSetter;
 const setInputChecked = prototypeSetter(HTMLInputElement.prototype, "checked") as CheckedSetter;
 
-/** Set ``el.value`` via the element's native prototype setter. */
+/** Set `el.value` via the element's native prototype setter. */
 export function setNativeValue(
   el: HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement,
   value: string,
@@ -36,7 +35,7 @@ export function setNativeValue(
   }
 }
 
-/** Set ``el.checked`` via the native prototype setter. */
+/** Set `el.checked` via the native prototype setter. */
 export function setNativeChecked(el: HTMLInputElement, checked: boolean): void {
   setInputChecked.call(el, checked);
 }

package/src/skills/fill_template.ts

@@ -9,12 +9,11 @@ export interface TemplateResult {
 const PLACEHOLDER_RE = /\{([a-zA-Z_][a-zA-Z0-9_]*)\}/g;
 
 /**
- * Substitute `{name}` placeholders in ``template`` from ``values``.
+ * Substitute `{name}` placeholders in `template` from `values`.
  *
- * A placeholder whose value is missing, ``null``, or an empty string is left
- * verbatim and reported in ``missing`` — the caller blocks send and tells the
- * user what's needed (e.g. "select rows first") rather than sending a
- * half-filled prompt.
+ * A placeholder whose value is missing, `null`, or an empty string is left
+ * verbatim and reported in `missing`, so the caller can block the send rather
+ * than dispatch a half-filled prompt.
  */
 export function fillTemplate(template: string, values: Record<string, unknown>): TemplateResult {
   const missing: string[] = [];

package/src/skills/parse_skills.ts

@@ -1,11 +1,10 @@
 import type { Skill } from "./skill.js";
 
 /**
- * Whether ``value`` has the required string fields of a {@link Skill}.
+ * Whether `value` has the required string fields of a {@link Skill}.
  *
- * `prompt` is optional and must stay so: a server-resolved skill deliberately
- * omits it, and requiring it here would silently drop exactly the skills whose
- * wording was kept off the client.
+ * `prompt` must stay optional: a server-resolved skill omits it, and requiring
+ * it would silently drop exactly the skills kept off the client.
  */
 function isSkill(value: unknown): value is Skill {
   if (typeof value !== "object" || value === null) {

package/src/skills/skill.ts

@@ -15,17 +15,16 @@ export interface Skill {
    * The prompt to send. May contain `{placeholder}`s filled from the host's
    * skill context before send; an unfilled placeholder blocks send.
    *
-   * **Omit it to keep the prompt on the server.** The skill then sends the bare
-   * `/name` token and the agent resolves what it means, so the wording never
-   * reaches the browser — worth preferring for anything internal, since a
-   * fetched catalog is a plain GET and an embedded one sits in the page source.
+   * Omit it to keep the prompt server-side: the skill then sends the bare
+   * `/name` token for the agent to resolve, and the wording never reaches the
+   * browser. Prefer that for anything internal — a fetched catalog is a plain
+   * GET and an embedded one sits in the page source.
    */
   readonly prompt?: string;
   /**
-   * Set `false` to pre-fill the composer instead of sending on pick. Only
-   * meaningful for a skill that carries its own `prompt`; a server-resolved one
-   * always sends. Defaults to sending — a chip that needs a second click to do
-   * anything is a two-step shortcut.
+   * Set `false` to pre-fill the composer instead of sending on pick. Defaults
+   * to sending, and is only meaningful for a skill carrying its own `prompt`;
+   * a server-resolved one always sends.
    */
   readonly sendImmediately?: boolean;
   /** Also surface this skill as a chip (default false; the palette shows all). */

package/src/tools/client_tool_registry.ts

@@ -27,8 +27,8 @@ export class ClientToolRegistry {
   /**
    * Register a tool, replacing any existing one with the same name.
    *
-   * Idempotent on the name so re-fired host refs / React StrictMode's
-   * double-invoke don't throw — re-registering is a replace, not an error.
+   * Idempotent on the name so a re-fired host ref or React StrictMode's
+   * double-invoke replaces rather than throws.
    */
   register(tool: ClientTool): void {
     this.#tools.set(tool.name, tool);

package/src/tools/page_action_tools.ts

@@ -4,10 +4,8 @@ import type { ClientTool } from "./client_tool_registry.js";
 
 /**
  * Resolve a page-action target string to a host-page element, or `null` when it
- * matches nothing. The default (`document.querySelector`) treats the string as a
- * CSS selector; a host with a page map overrides it to map its own element ids,
- * the same way host packages wrap the DOM-driver primitives with environment-
- * aware lookups.
+ * matches nothing. The default treats the string as a CSS selector; a host with
+ * a page map overrides it to map its own element ids.
  */
 export type ResolvePageTarget = (target: string) => HTMLElement | null;
 
@@ -24,13 +22,12 @@ export const PAGE_ACTIONS = {
  * - `scroll_to` — scroll a target (`top` / `bottom` / a resolver target) into
  *   view. Benign; no confirmation.
  * - `drag_and_drop` — drag one element onto another, firing the standard HTML5
- *   drag sequence so the host page's own drop handler reacts. Not stamped
- *   destructive: a drag rearranges transient state and the durable change
- *   happens at the page's explicit commit. A host whose page persists *on drop*
- *   gates it with the element's `confirmPredicate`.
+ *   drag sequence so the host page's own drop handler reacts. Deliberately not
+ *   stamped destructive: a drag rearranges transient state, and the durable
+ *   change happens at the page's explicit commit. A host whose page persists on
+ *   drop must gate it with the element's `confirmPredicate`.
  *
- * Both report a clean, model-readable error when a target resolves to nothing,
- * rather than throwing an opaque crash.
+ * Both report a model-readable error when a target resolves to nothing.
  */
 export function createPageActionTools(
   enabled: ReadonlySet<string>,
@@ -106,11 +103,11 @@ function dragTool(resolveTarget: ResolvePageTarget): ClientTool {
 }
 
 /**
- * Fire the standard HTML5 drag sequence — `dragstart` on the source, then
- * `dragenter` / `dragover` / `drop` on the target, then `dragend` on the source —
- * sharing one {@link DataTransfer}. Dispatched as typed, bubbling events (the
- * `dataTransfer` is attached explicitly so a drop handler reads it in every
- * environment).
+ * Fire the standard HTML5 drag sequence in the order a page's own handlers
+ * expect — `dragstart` on the source, `dragenter` / `dragover` / `drop` on the
+ * target, `dragend` on the source — all sharing one {@link DataTransfer}, which
+ * is attached to each event explicitly so a drop handler reads it in every
+ * environment.
  */
 function dispatchDragSequence(from: HTMLElement, to: HTMLElement): void {
   const dataTransfer = new DataTransfer();

package/src/tools/page_state.ts

@@ -7,11 +7,9 @@ import type { ClientTool } from "./client_tool_registry.js";
  * Ergonomic sugar over `registerTool` for SPA state (Redux/Zustand/signals):
  * generates a read tool and, when `write` is given, a destructive set tool.
  *
- * This is **not** AG-UI shared state. `STATE_SNAPSHOT` / `STATE_DELTA` are
- * protocol events carrying state between agent and client; this is a pair of
- * ordinary client tools the agent calls like any other. The two are unrelated,
- * which is why this no longer carries the word "hook" — the old name read as
- * protocol state sync, which this component does not implement.
+ * Not AG-UI shared state. `STATE_SNAPSHOT` / `STATE_DELTA` are protocol events
+ * carrying state between agent and client; these are ordinary client tools the
+ * agent calls like any other.
  */
 export interface PageState {
   /** Base name; tools become `read_<name>` and `set_<name>`. */
@@ -59,9 +57,8 @@ export function createPageStateTools(binding: PageState): ClientTool[] {
 }
 
 /**
- * @deprecated Renamed to {@link PageState}. The old name read as AG-UI
- * shared-state sync (`STATE_SNAPSHOT` / `STATE_DELTA`), which this component
- * does not implement. Will be removed in a future major.
+ * @deprecated Renamed to {@link PageState} — the old name read as AG-UI
+ * shared-state sync. Will be removed in a future major.
  */
 export type StateHook = PageState;
 

package/src/tools/route_map.ts

@@ -7,9 +7,8 @@ export interface Route {
   readonly id: string;
   /**
    * The URL path to navigate to. May contain `:name` placeholders for dynamic
-   * segments (e.g. `/admin/shop/book/:pk/change/`); the agent fills them via
-   * the `navigate_to_route` `params` argument. Real apps are mostly
-   * parameterised — few pages have a truly static path.
+   * segments (e.g. `/admin/shop/book/:pk/change/`), which the agent fills via
+   * `navigate_to_route`'s `params` argument.
    */
   readonly path: string;
   /** Human label shown to the agent. */
@@ -33,20 +32,19 @@ const PATH_PARAM_RE = /:([A-Za-z_][A-Za-z0-9_]*)/g;
 
 /** The `:name` path-parameter names declared in a path template, in order. */
 function pathParamNames(path: string): string[] {
-  // Slicing the ":" off the whole match rather than reading the capture group:
-  // the group is mandatory, so under `noUncheckedIndexedAccess` indexing it
-  // forces an `undefined` guard on a case the regex cannot produce — an
-  // unreachable branch no test can ever cover.
+  // Slice the ":" off the whole match rather than read the capture group: under
+  // `noUncheckedIndexedAccess`, indexing the group forces an `undefined` guard
+  // on a case the regex cannot produce, which no test can cover.
   return [...path.matchAll(PATH_PARAM_RE)].map((match) => match[0].slice(1));
 }
 
 /**
- * Substitute `:name` placeholders in ``path`` from ``params``.
+ * Substitute `:name` placeholders in `path` from `params`.
  *
- * Returns the concrete path plus the params *not* consumed by a placeholder, so
- * the caller can append those as a query string. Throws (referencing
- * ``routeId``) when a declared path param is missing or empty — a half-filled
- * path must never be navigated to.
+ * Returns the concrete path plus the params no placeholder consumed, for the
+ * caller to append as a query string. Throws (naming `routeId`) when a declared
+ * path param is missing or empty — a half-filled path must never be navigated
+ * to.
  */
 function fillPath(
   routeId: string,
@@ -79,13 +77,11 @@ function withQuery(path: string, params: Record<string, unknown>): string {
  * The built-in `route.*` tools, bound to live getters so a host can set
  * `routeMap` / `navigate` before or after mount.
  *
- * `list_routes` is read-only and advertises each route's dynamic
- * `pathParams` so the model knows what to supply. `navigate_to_route` is marked
- * `x-navigates` so an MPA reload checkpoints + resumes; it substitutes path
- * params into the template and appends any remaining params as a query string.
- * When the host supplies a `navigate(path)` callback (an SPA), the element
- * routes client-side instead and the run loop simply continues — see
- * `AgUiChat`'s execute path.
+ * `list_routes` is read-only and advertises each route's `pathParams` so the
+ * model knows what to supply. `navigate_to_route` fills those params, appends
+ * the rest as a query string, and is stamped `x-navigates` so an MPA reload
+ * checkpoints and resumes; with a host `navigate(path)` callback (an SPA) it
+ * routes client-side and the run loop continues instead.
  */
 export function createRouteTools(
   getRouteMap: () => RouteMap,

package/src/ui/approval_card.ts

@@ -25,9 +25,8 @@ function actionButton(modifier: string, label: string): HTMLButtonElement {
 /** Options for {@link requestApproval}. */
 export interface ApprovalOptions {
   /**
-   * Aborting this signal resolves the card as **denied** (buttons disabled,
-   * `data-resolved="denied"`) — the hook a Stop control uses to dismiss a
-   * pending approval when the user cancels the whole run.
+   * Aborting this signal resolves the card as denied, with buttons disabled and
+   * `data-resolved="denied"` — how a Stop control dismisses a pending approval.
    */
   signal?: AbortSignal;
   /** Localized strings; defaults to the English {@link DEFAULT_UI_STRINGS}. */
@@ -36,13 +35,11 @@ export interface ApprovalOptions {
 
 /**
  * A fully custom renderer for a server-side-tool approval, set via
- * `AgUiChat.approvalRenderer`. Receives the {@link ApprovalRequest} (the
- * interrupt's message + tool name) and an `AbortSignal` that fires when the run
- * is stopped, and resolves `true` to approve or `false` to deny. When provided
- * it **replaces** the built-in {@link requestApproval} card entirely — the host
- * owns the DOM, so it can render a native modal, a framework component, or
- * anything else. See the `strings` / `::part()` seams for styling the built-in
- * card instead of replacing it.
+ * `AgUiChat.approvalRenderer`. Receives the {@link ApprovalRequest} and an
+ * `AbortSignal` that fires when the run is stopped, and resolves `true` to
+ * approve or `false` to deny. Replaces the built-in {@link requestApproval}
+ * card entirely, the host owning the DOM; to restyle the built-in card instead,
+ * use the `strings` and `::part()` seams.
  */
 export type ApprovalRenderer = (
   request: ApprovalRequest,
@@ -50,17 +47,15 @@ export type ApprovalRenderer = (
 ) => Promise<boolean>;
 
 /**
- * Append an inline **approval** card to ``host`` and resolve when the user
- * decides whether a gated *server-side* tool may run.
+ * Append an inline approval card to `host` and resolve `true` to run a gated
+ * server-side tool or `false` to deny it.
  *
- * The server-side approval gate is distinct from the client-tool confirmation
- * card ({@link requestConfirmation}): a destructive server tool defers instead
- * of executing, and the run finishes on an AG-UI *interrupt* the client answers
- * with `resume[]`. This card is the browser half of that loop — it reads
- * naturally after the tool-call card whose execution it gates, and resolves
- * ``true`` to approve (run the tool) or ``false`` to deny. The card stays in the
- * transcript as a resolved record (buttons disabled, `data-resolved` set)
- * rather than vanishing.
+ * Distinct from the client-tool confirmation card
+ * ({@link requestConfirmation}): a gated server tool defers instead of
+ * executing, so the run finishes on an AG-UI interrupt the client answers with
+ * `resume[]`, and this is the browser half of that loop. Unlike the
+ * confirmation card, this one stays in the transcript as a resolved record,
+ * buttons disabled and `data-resolved` set.
  */
 export function requestApproval(
   host: Node & ParentNode,