@artooi/ag-ui-web-component 0.23.0 → 0.24.0

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,

package/src/ui/attach_copy_buttons.ts

@@ -6,17 +6,11 @@ const CONFIRM_MS = 1500;
 /**
  * Give every fenced code block in `root` a copy button.
  *
- * An agent that answers with code is answering with something the reader means
- * to *use*, and selecting it by hand out of a scrolling transcript — inside a
- * shadow root, in a narrow sidebar — is the one interaction the chat surface
- * made harder than the page around it.
+ * Call only on finished bubbles: the streaming bubble reassigns its `innerHTML`
+ * on every delta, so a button attached mid-stream is discarded and rebuilt for
+ * each one.
  *
- * Applied to **finished** bubbles only. The streaming bubble reassigns its
- * `innerHTML` on every delta, so a button attached mid-stream would be
- * discarded and rebuilt for each one; waiting until the turn ends costs
- * nothing and does that work once.
- *
- * Idempotent: a bubble already processed is skipped, so a re-render or a second
+ * Idempotent — a bubble already processed is skipped, so a re-render or a second
  * call cannot stack buttons.
  */
 export function attachCopyButtons(root: ParentNode, strings: UiStrings): void {
@@ -43,9 +37,8 @@ function button(code: Element, strings: UiStrings): HTMLButtonElement {
   copy.setAttribute("aria-label", strings.copyCode);
   copy.addEventListener("click", () => {
     void writeText(text).then((ok) => {
-      // Say which of the two happened. A button that always claims success is
-      // worse than no button: the reader pastes stale clipboard content and
-      // finds out somewhere else entirely.
+      // Report the real outcome: a button that always claims success leaves the
+      // reader pasting stale clipboard content.
       confirm(copy, ok ? strings.copied : strings.copyFailed, strings);
     });
   });
@@ -53,11 +46,9 @@ function button(code: Element, strings: UiStrings): HTMLButtonElement {
 }
 
 /**
- * Copy `text`, reporting whether it landed.
- *
- * The Clipboard API needs a secure context and a user gesture, and is simply
- * absent in some embeddings, so its absence is an ordinary outcome rather than
- * an error worth throwing at the host page.
+ * Copy `text`, reporting whether it landed. The Clipboard API needs a secure
+ * context and a user gesture and is absent in some embeddings, so failure is an
+ * ordinary outcome rather than an error to throw at the host page.
  */
 async function writeText(text: string): Promise<boolean> {
   const clipboard = navigator.clipboard;

package/src/ui/attachment_chips.ts

@@ -2,10 +2,10 @@ import { ICON_FILE, ICON_FILE_IMAGE, ICON_FILE_PDF, ICON_FILE_TEXT } from "../co
 import type { AttachmentRef } from "../core/attachment.js";
 
 /**
- * Render the read-only attachment chips shown on a sent user message bubble
- * (and on restored history) — one chip per ref with a type icon, the filename,
- * and a human size. Static by design: no progress, no remove (that lives in the
- * composer tray); a restored bubble re-renders these with no animation.
+ * Render the read-only attachment chips on a sent user message bubble and on
+ * restored history — one chip per ref with a type icon, filename, and human
+ * size. Static: no progress and no remove, both of which live in the composer
+ * tray.
  */
 export function renderAttachmentChips(refs: readonly AttachmentRef[]): HTMLDivElement {
   const list = document.createElement("div");
@@ -45,12 +45,9 @@ function renderChip(ref: AttachmentRef): HTMLDivElement {
 
 /**
  * A coarse type mark for a chip — image, PDF, text document, or generic file —
- * as the inline SVG markup of one of the built-in glyphs.
- *
- * Returns markup rather than a character because chips sit beside the
- * composer's SVG send, attach and mic buttons: emoji render at a different
- * optical weight, vary by platform, and take neither the glyph size nor
- * `currentColor`, so the two never matched.
+ * as inline SVG markup rather than a character, so it matches the composer's
+ * SVG buttons in weight and takes the glyph size and `currentColor`, which
+ * emoji do not.
  *
  * The MIME string only selects among author-written constants and is never
  * interpolated into one, so the result is safe to assign as markup.

package/src/ui/attachment_tray.ts

@@ -36,13 +36,13 @@ interface TrayItem {
 
 /**
  * The composer's pending-attachments tray: a chip per picked file with a
- * progress bar while it uploads, settling to a ready chip (holding the durable
- * ref) or an error chip (with retry). A *stateful view* in the spirit of
- * {@link ThreadDrawer} — the host appends {@link element}, calls {@link add} on
- * pick/drop, reads {@link readyRefs} when the user sends, and clears it.
+ * progress bar while it uploads, settling to a ready chip holding the durable
+ * ref or an error chip with retry. A stateful view like {@link ThreadDrawer}:
+ * the host appends {@link element}, calls {@link add} on pick or drop, reads
+ * {@link readyRefs} on send, and clears it.
  *
- * Client-side size/type guards reject a bad file into an error chip without
- * uploading — instant feedback, but the server is the authority.
+ * Client-side size and type guards reject a bad file into an error chip without
+ * uploading, for instant feedback, but the server stays the authority.
  */
 export class AttachmentTray {
   /** The tray root; append above the input row. Hidden while empty. */

package/src/ui/checkpoint_menu.ts

@@ -8,16 +8,15 @@ export type CheckpointVerb = "resume" | "fork";
 /**
  * The checkpoint panel: continuable runs, each offering **resume** or **fork**.
  *
- * A separate surface from the thread drawer on purpose — they are different
- * axes. A thread is a conversation you switch *to*; a checkpoint is a run you
- * continue *from*, and one thread can hold many. Folding them into one list
- * would make "resume" look like "open", which it isn't: resuming starts a new
+ * Deliberately separate from the thread drawer: a thread is a conversation you
+ * switch to, a checkpoint is a run you continue from, and one thread holds
+ * many. One list would make "resume" read as "open", when resuming starts a new
  * run seeded from a snapshot.
  *
- * Only rows the server marked `continuable` are worth offering, so the host
- * feeds those; a run with no snapshot would resume from nothing. Pure DOM in
- * the spirit of {@link SkillsMenu} — the host appends {@link element}, toggles
- * it, feeds rows via {@link setRuns}, and acts on {@link onPick}.
+ * The host feeds only rows the server marked `continuable`, a run without a
+ * snapshot having nothing to resume from. Pure DOM, like {@link SkillsMenu}:
+ * append {@link element}, toggle it, feed {@link setRuns}, act on
+ * {@link onPick}.
  */
 export class CheckpointMenu {
   /** The panel root. Append to the chat shell; hidden until opened. */

package/src/ui/confirmation_card.ts

@@ -24,9 +24,9 @@ function actionButton(modifier: string, label: string): HTMLButtonElement {
 /** Options for {@link requestConfirmation}. */
 export interface ConfirmationOptions {
   /**
-   * Aborting this signal resolves the card as declined (buttons disabled,
-   * `data-resolved="declined"`) — the hook a Stop control uses to dismiss a
-   * pending confirmation when the user cancels the whole run.
+   * Aborting this signal resolves the card as declined, with buttons disabled
+   * and `data-resolved="declined"` — how a Stop control dismisses a pending
+   * confirmation.
    */
   signal?: AbortSignal;
   /** Localized strings; defaults to the English {@link DEFAULT_UI_STRINGS}. */
@@ -34,20 +34,15 @@ export interface ConfirmationOptions {
 }
 
 /**
- * Append an inline confirmation card to ``host`` (the chat message list) and
- * resolve when the user decides.
+ * Append an inline confirmation card to `host` (the chat message list) and
+ * resolve `true` on confirm, `false` on cancel.
  *
- * Unlike a modal overlay, the card lives in the transcript right where the
- * action is — it reads naturally after the assistant's explanation and never
- * steals focus from the page. Resolves ``true`` on confirm, ``false`` on
- * cancel.
+ * The card lives in the transcript rather than in a modal overlay, so it reads
+ * after the assistant's explanation and never steals focus from the page.
  *
- * **Answering it removes it.** A prompt and a record are two different objects:
- * the prompt owns the user's attention until it is answered, and the record of
- * what was decided belongs in the transcript, in order, scrolling with
- * everything else. The tool card this gates is that record — it settles to
- * `done` or `declined` and carries the decision. Leaving the spent form in
- * place made an answered question read as outstanding.
+ * Answering it removes it: the record of the decision belongs to the tool card
+ * this gates, which settles to `done` or `declined` and carries it. A spent
+ * form left in place reads as still outstanding.
  */
 export function requestConfirmation(
   host: Node & ParentNode,

package/src/ui/question_card.ts

@@ -19,9 +19,8 @@ export interface QuestionRequest {
 /** Options for {@link requestQuestion}. */
 export interface QuestionOptions {
   /**
-   * Aborting this signal resolves the card with an empty answer (fields
-   * disabled) — the hook a Stop control uses to dismiss an open question when
-   * the user cancels the whole run.
+   * Aborting this signal resolves the card with an empty answer and disabled
+   * fields — how a Stop control dismisses an open question.
    */
   signal?: AbortSignal;
   /** Localized strings; defaults to the English {@link DEFAULT_UI_STRINGS}. */
@@ -32,11 +31,9 @@ export interface QuestionOptions {
  * A fully custom renderer for the `ask_user` question, set via
  * `AgUiChat.askUserRenderer`. Receives the parsed {@link QuestionRequest} and an
  * `AbortSignal` that fires when the run is stopped, and resolves with the user's
- * answer (an empty string signals "no answer", e.g. on abort). When provided it
- * **replaces** the built-in {@link requestQuestion} 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.
+ * answer; an empty string means no answer. Replaces the built-in
+ * {@link requestQuestion} card entirely — see {@link ApprovalRenderer} for the
+ * same seam on approvals.
  */
 export type QuestionRenderer = (
   request: QuestionRequest,
@@ -54,14 +51,14 @@ function answerInput(placeholder: string): HTMLInputElement {
 }
 
 /**
- * Append an inline **question** card to ``host`` and resolve with the user's
- * answer — the browser half of the built-in `ask_user` frontend tool.
+ * Append an inline question card to `host` and resolve with the user's answer —
+ * the browser half of the built-in `ask_user` frontend tool.
  *
- * Unlike the confirmation/approval cards (which resolve a yes/no), this collects
- * a typed answer: a radio pick from ``options``, or free text (when
- * ``allowCustom`` or no ``options`` are given). The card stays in the transcript
- * as a resolved record (controls disabled, `data-resolved` set) rather than
- * vanishing. A Stop while it is open resolves it with an empty string.
+ * Collects a typed answer rather than the yes/no the confirmation and approval
+ * cards return: a radio pick from `options`, or free text when `allowCustom` is
+ * set or no `options` are given. Stays in the transcript as a resolved record,
+ * controls disabled and `data-resolved` set; a Stop while it is open resolves
+ * it with an empty string.
  */
 export function requestQuestion(
   host: Node & ParentNode,

package/src/ui/relative_time.ts

@@ -4,13 +4,11 @@ import { DEFAULT_UI_STRINGS, type UiStrings } from "./ui_strings.js";
  * A compact relative timestamp for a thread row — e.g. `"just now"`, `"5m ago"`,
  * `"3h ago"`, `"2d ago"`, `"4w ago"`.
  *
- * `now` is injectable so callers (and tests) can pin the reference point; it
- * defaults to the current time. A timestamp in the future (clock skew) reads as
- * `"just now"`. A non-finite timestamp — an unparseable or missing `updated_at`
- * that arrived as `NaN` — has no meaningful age, so it falls back to `justNow`
- * rather than rendering `"NaNw ago"` or `"~2950w ago"`. The unit words come from
- * {@link UiStrings} (the `{n}` token is filled in here) so a localized host
- * translates them; the bucketing stays integer-rounded and locale-neutral.
+ * `now` is injectable so callers and tests can pin the reference point. A
+ * future timestamp (clock skew) and a non-finite one (an unparseable or missing
+ * `updated_at`, arriving as `NaN`) both read as `justNow`, rather than
+ * rendering a nonsense age. Unit words come from {@link UiStrings} with `{n}`
+ * filled in here; the bucketing stays integer-rounded and locale-neutral.
  */
 export function relativeTime(
   timestamp: number,

package/src/ui/render_markdown.ts

@@ -1,52 +1,26 @@
-// DOMPurify is exercised in a **real browser** by the `chromium` project in
-// vitest.config.ts, not by the happy-dom suite. That is deliberate: 3.4.8+ do
-// not sanitise under happy-dom at all — `<script>` and `<img>` pass straight
-// through — so a happy-dom-only suite can go green while this module ships no
-// sanitisation whatsoever.
-//
-// **Root cause, upstream, and both are refusing to move.** DOMPurify 3.4.8
-// changed one line, reading the tag name through
-// `lookupGetter(Node.prototype, "nodeName")` instead of `currentNode.nodeName`
-// (cure53/DOMPurify 3.4.7...3.4.8). happy-dom defines an *own* `nodeName`
-// getter on **both** `Node.prototype` (returning `""`) and `Element.prototype`,
-// so grabbing the base one defeats the dispatch and every element resolves to
-// `tagName === ""`. Not in ALLOWED_TAGS, so the wrapper is stripped and its
-// children are re-inserted as clones the NodeIterator never revisits — which is
-// why nested payloads come back *entirely* unsanitised. Real browsers and jsdom
-// define `nodeName` only on `Node.prototype` and are unaffected.
-//
-//   happy-dom bug:      capricorn86/happy-dom#2182 (open)
-//   working fix:        capricorn86/happy-dom#2183 (closed, never merged)
-//   DOMPurify's answer: cure53/DOMPurify#1457, #1496 (closed, wontfix —
-//                       "happy-dom is not supported")
-//
-// ⚠ DOMPurify's README names happy-dom as **not safe**: combining them "will
-// likely lead to XSS". jsdom is the only non-browser DOM it supports. So the
-// old exact pin at 3.4.7 was never the safety it looked like — cure53 notes it
-// "doesn't really work, it just appears so". Running these assertions in
-// Chromium is the fix; the pin was a placebo.
-//
-// ⚠ If you ever move these assertions back under happy-dom to make them faster,
-// you remove the only check that this module does anything at all.
+// This module's sanitisation is verified only by the `chromium` project in
+// vitest.config.ts, and must stay there. DOMPurify 3.4.8+ silently sanitises
+// nothing under happy-dom (every element resolves to an empty tag name), so a
+// happy-dom-only suite goes green while this module strips nothing at all.
+// Moving those assertions back under happy-dom for speed removes the only check
+// that this module does anything. CLAUDE.md records the upstream root cause.
 import DOMPurify from "dompurify";
 import { Marked } from "marked";
 
-// Local parser instance so configuration never leaks into the shared `marked`
-// singleton (a host app's deduped copy keeps its own options). GitHub-flavoured
-// markdown with single-newline line breaks (chat-like). Constructed once at
-// module scope — configured here and never mutated afterwards; per-call
-// construction would re-pay setup on every streaming re-render.
+// A local parser instance, so configuration never leaks into the shared
+// `marked` singleton a host app's deduped copy would share. Built once at module
+// scope and never mutated; per-call construction would re-pay setup on every
+// streaming re-render.
 const parser = new Marked({ gfm: true, breaks: true });
 
-// Conservative allowlist for assistant chat content: inline emphasis, code,
-// lists, quotes, headings, links, and tables. Deliberately excludes `iframe`,
-// `style`, and any scripting — rendering untrusted model/tool output as HTML
-// is an XSS surface, so the sanitiser is the load-bearing safety net.
+// Conservative allowlist for assistant chat content. Rendering untrusted
+// model/tool output as HTML is an XSS surface and this sanitiser is the only
+// thing standing in front of it, so `iframe`, `style` and all scripting stay
+// out.
 //
-// `img` is excluded by default: a model-controlled `<img src="https://...">`
-// is fetched by the browser with **no user interaction**, which turns any
-// prompt-injected page data into a zero-click exfiltration channel. Hosts
-// that trust their content can opt back in via `allowImages`.
+// `img` is excluded by default: a model-controlled image URL is fetched with no
+// user interaction, turning prompt-injected page data into a zero-click
+// exfiltration channel. Hosts that trust their content opt in via `allowImages`.
 const ALLOWED_TAGS = [
   "a",
   "p",
@@ -89,9 +63,9 @@ const ALLOWED_ATTR_WITH_IMAGES = [...ALLOWED_ATTR, "src", "alt", "width", "heigh
 /** Options for {@link renderMarkdown}. */
 export interface RenderMarkdownOptions {
   /**
-   * Permit `<img>` tags (and their `src`/`alt`/`width`/`height` attributes)
-   * in the sanitised output. **Off by default** — see the allowlist note on
-   * the exfiltration risk. Only enable for trusted content sources.
+   * Permit `<img>` tags (and their `src`/`alt`/`width`/`height` attributes) in
+   * the sanitised output. Off by default; see the exfiltration note on the
+   * allowlist above. Only enable for trusted content sources.
    */
   readonly allowImages?: boolean;
 }
@@ -99,13 +73,13 @@ export interface RenderMarkdownOptions {
 /**
  * Render markdown (and any embedded raw HTML) to a sanitised HTML string.
  *
- * Both markdown syntax and literal HTML flow through one path: `marked` emits
- * HTML, then DOMPurify strips everything outside {@link ALLOWED_TAGS} /
- * {@link ALLOWED_ATTR} (scripts, event handlers, `javascript:` URLs, etc.).
- * Links are hardened with `target="_blank"` + `rel="noopener noreferrer"`.
+ * Markdown syntax and literal HTML share one path: `marked` emits HTML, then
+ * DOMPurify strips everything outside {@link ALLOWED_TAGS} /
+ * {@link ALLOWED_ATTR} — scripts, event handlers, `javascript:` URLs. Links are
+ * hardened with `target="_blank"` and `rel="noopener noreferrer"`.
  *
  * The result is trimmed so a single-paragraph message round-trips to clean
- * `textContent` (no trailing newline from the wrapping `<p>`).
+ * `textContent`, without the wrapping paragraph's trailing newline.
  */
 export function renderMarkdown(text: string, options?: RenderMarkdownOptions): string {
   const allowImages = options?.allowImages === true;

package/src/ui/resize_handle.ts

@@ -7,10 +7,8 @@ export interface ResizeAnchor {
 }
 
 /**
- * What the current placement allows: both axes, width only, or nothing.
- *
- * Which *corner* the grip sits on is not part of this — that follows the host's
- * layout, which the component measures rather than assumes.
+ * What the current placement allows: both axes, width only, or nothing. Which
+ * corner the grip sits on is separate, and is measured rather than assumed.
  */
 export type ResizeAxis = "none" | "width" | "both";
 
@@ -31,22 +29,16 @@ export interface PanelRect {
 /** What the handle needs from its host to do its job. */
 export interface ResizeOptions {
   /**
-   * Which axes the current placement allows, read **per interaction**.
-   *
-   * A getter rather than a value because `placement` is a live attribute: read
-   * once at construction, a handle built while floating kept its axes after the
-   * host switched to a docked or full-bleed layout.
+   * Which axes the current placement allows, read per interaction. A getter
+   * because `placement` is a live attribute, and a value read at construction
+   * would survive the host switching to a docked or full-bleed layout.
    */
   readonly axis: () => ResizeAxis;
   /**
-   * Which edges the layout is holding still, measured at the moment of the
-   * drag.
-   *
-   * **Measured, not derived from `placement`.** A floating panel is pinned
-   * bottom-right and an embedded one goes wherever the host's own CSS puts it —
-   * the demo playground drops it in a right-aligned flex slot, so "embedded"
-   * alone says nothing. Guessing produced a panel that shrank when dragged
-   * outward and travelled by its opposite corner.
+   * Which edges the layout is holding still, measured at the moment of the drag
+   * rather than derived from `placement`: a floating panel is pinned
+   * bottom-right, while an embedded one goes wherever the host's CSS puts it,
+   * so `placement` alone cannot answer the question.
    */
   readonly anchor: () => ResizeAnchor;
   /** The panel's current bounding box. */
@@ -66,25 +58,20 @@ const MIN_HEIGHT = 240;
 /**
  * A drag handle that resizes the chat panel.
  *
- * The size was previously fixed by whatever the host set `--ag-ui-width` /
- * `--ag-ui-height` to: themeable by the page, immovable by the person reading a
- * long answer in a 380px column.
- *
- * **The new size is measured from the edge that is not moving, never from a
- * delta**, and which edge that is is **measured rather than assumed**. A
- * floating panel is pinned bottom-right; an embedded one goes wherever the
- * host's CSS puts it, so `placement` does not answer the question. Getting it
- * wrong is very visible: the panel shrinks when dragged outward and travels by
- * its opposite corner.
+ * Two rules keep it correct, and both are easy to break invisibly:
  *
- * **It writes the custom properties rather than inline `width` / `height`.**
- * The placement rules set those same properties, so an inline dimension would
- * fight them — a sidebar would keep a dragged width after switching to
- * fullscreen. Writing the property means placement still has the final say.
+ * - The new size is measured from the edge that is *not* moving, never from a
+ *   delta, and that edge is measured rather than assumed. Getting it wrong is
+ *   very visible: the panel shrinks when dragged outward and travels by its
+ *   opposite corner.
+ * - It writes the `--ag-ui-width` / `--ag-ui-height` custom properties, not
+ *   inline `width` / `height`. The placement rules set those same properties,
+ *   so an inline dimension would outrank and fight them — a sidebar would keep
+ *   its dragged width after switching to fullscreen. Writing the property
+ *   leaves placement the final say.
  *
- * The axes are read per interaction, so switching `placement` at runtime takes
- * effect immediately rather than leaving whichever ones the element happened to
- * mount with.
+ * Axes and anchor are both read per interaction, so a runtime `placement`
+ * change takes effect at once.
  */
 export function createResizeHandle(options: ResizeOptions): HTMLDivElement {
   const handle = document.createElement("div");
@@ -116,7 +103,7 @@ export function createResizeHandle(options: ResizeOptions): HTMLDivElement {
     if (axis === "none") {
       return;
     }
-    // Captured once: the fixed edges cannot move during the drag, and reading
+    // Captured once: the pinned edges cannot move during the drag, and reading
     // them live would chase the panel as it resizes.
     const anchor = options.anchor();
     const rect = options.rect();
@@ -140,7 +127,7 @@ export function createResizeHandle(options: ResizeOptions): HTMLDivElement {
     event.preventDefault();
   });
 
-  // Keyboard parity. A pointer-only resize is unreachable without a mouse, and
+  // Keyboard parity: a pointer-only resize is unreachable without a mouse, and
   // this control has no equivalent elsewhere in the UI.
   handle.addEventListener("keydown", (event: KeyboardEvent) => {
     const axis = options.axis();
@@ -150,8 +137,8 @@ export function createResizeHandle(options: ResizeOptions): HTMLDivElement {
     const anchor = options.anchor();
     const rect = options.rect();
     const step = event.shiftKey ? 64 : 16;
-    // An arrow moves the grip, and whether that grows or shrinks depends on
-    // which side the grip is on — the same asymmetry the pointer path handles.
+    // An arrow moves the grip, so whether it grows or shrinks depends on which
+    // side the grip is on — the asymmetry the pointer path also handles.
     const outward = anchor.x === "right" ? -1 : 1;
     const width = rect.right - rect.left;
     const height = rect.bottom - rect.top;

package/src/ui/run_notice.ts

@@ -1,28 +1,25 @@
 /**
- * A muted one-line notice about something the *run* did, rendered inline in the
- * transcript between turns.
+ * A muted one-line notice about something the run did (history condensed, a
+ * skill loaded), rendered inline between turns.
  *
- * Distinct from a tool card (which reports work the agent asked for and is
- * settleable) and from an error (which is a failure). A notice is ambient: the
- * agent condensed earlier turns, or loaded a skill. It never settles, never
- * takes an action, and carries no controls — so it stays visually quiet and out
- * of the way of the conversation it annotates.
+ * Distinct from a tool card, which reports work the agent asked for and
+ * settles, and from an error, which is a failure. A notice never settles, takes
+ * no action, and carries no controls.
  */
 export function renderRunNotice(icon: string, text: string, kind: string): HTMLDivElement {
   const notice = document.createElement("div");
   notice.className = `run-notice run-notice--${kind}`;
   notice.setAttribute("part", `run-notice run-notice-${kind}`);
-  // A status role, not an alert: this is informational and must not interrupt a
-  // screen reader mid-sentence. Polite announcements land after the current
-  // utterance, which is right for an annotation about turns already spoken.
+  // status, not alert: informational, so it must not interrupt a screen reader
+  // mid-sentence. Polite announcements land after the current utterance.
   notice.setAttribute("role", "status");
 
   const glyph = document.createElement("span");
   glyph.className = "run-notice-icon";
   glyph.setAttribute("part", "run-notice-icon");
   glyph.textContent = icon;
-  // Decorative: the adjacent text already says what happened, and a screen
-  // reader announcing the emoji's name would just add noise.
+  // Decorative: the adjacent text already says what happened, so announcing the
+  // glyph's name would only add noise.
   glyph.setAttribute("aria-hidden", "true");
 
   const label = document.createElement("span");