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

package/src/ui/skills_menu.ts

@@ -1,11 +1,10 @@
 import type { Skill } from "../skills/skill.js";
 
 /**
- * The two skill surfaces over a single catalog: a **chips** row (the
- * `chip: true` subset) and a **`/`-command palette** (all skills, filtered).
- * Both are opt-in. Pure DOM; the host ({@link AgUiChat}) appends
- * {@link chips} + {@link palette}, feeds input via {@link onInput} /
- * {@link onKeydown}, and acts on the {@link onPick} callback.
+ * The two skill surfaces over a single catalog: a chips row (the `chip: true`
+ * subset) and a slash-command palette (all skills, filtered). Both opt-in.
+ * Pure DOM; the host appends {@link chips} and {@link palette}, feeds input via
+ * {@link onInput} / {@link onKeydown}, and acts on {@link onPick}.
  */
 export class SkillsMenu {
   /** Chips row — append above the input. Hidden unless chips are enabled and present. */

package/src/ui/styles.ts

@@ -8,12 +8,11 @@ export const STYLES = `
    only the alias is used by the rules below.
 
    The indirection is what makes ancestor theming work. Declaring the public
-   name on :host would set it *on the host element*, and a value on an element
-   always beats one inherited from an ancestor — so a page that put the tokens
-   on a wrapper would see no effect at all, which is the one thing the API is
-   documented to support. Reading the public name with the default as a var()
-   fallback leaves it undeclared on the element, so an ancestor's value is
-   inherited normally while a value aimed at the element still wins over it.
+   name on :host would set it on the host element, and a value on an element
+   always beats one inherited from an ancestor, so tokens put on a wrapper
+   would have no effect. Reading the public name with the default as a var()
+   fallback leaves it undeclared on the element, so an ancestor's value
+   inherits normally while one aimed at the element still wins.
 
    Two invariants hold this together:
    1. No rule outside this file's :host blocks may reference a public name
@@ -40,11 +39,9 @@ export const STYLES = `
   --_border: var(--ag-ui-border, #e2e2ec);
   --_radius: var(--ag-ui-radius, 12px);
 
-  /* Body text and raised chrome. Both are referenced by the code-block copy
-     button; neither had a default before, so the declarations reading them
-     were dropped and the button fell back to the inherited colour over a
-     transparent box. The defaults below restate exactly that, so this is a
-     rename with no repaint — see the note on .code-copy. */
+  /* Body text and raised chrome, read only by the code-block copy button.
+     The defaults restate what it inherits, so a host that sets neither sees
+     no repaint — see the note on .code-copy. */
   --_text: var(--ag-ui-text, var(--_fg));
   --_surface: var(--ag-ui-surface, transparent);
 
@@ -97,9 +94,9 @@ export const STYLES = `
   --_launcher-inset: var(--ag-ui-launcher-inset, auto 0 0 auto);
 
   /* Motion. One duration and two curves drive every collapse, expand and
-     slide-over, so the whole widget accelerates and settles as one thing.
-     The default curve is a long-tailed ease-out (a fast start that decelerates
-     into place); the pop curve overshoots slightly, for something arriving. */
+     slide-over, so the widget accelerates and settles as one thing. The
+     default curve decelerates into place; the pop curve overshoots slightly,
+     for something arriving. */
   --_motion: var(--ag-ui-motion, 0.28s);
   --_ease: var(--ag-ui-ease, cubic-bezier(0.32, 0.72, 0, 1));
   --_ease-pop: var(--ag-ui-ease-pop, cubic-bezier(0.34, 1.36, 0.64, 1));
@@ -123,7 +120,7 @@ export const STYLES = `
   /* Reading-column width for placement="page" (full-bleed, centred content). */
   --_content-max-width: var(--ag-ui-content-max-width, 820px);
   /* Slim rail the sidebar placement collapses to. Only that placement reads
-     it, but it is declared here so invariant 2 holds for every alias. */
+     it, but it is declared here so every alias has a default in one place. */
   --_rail-width: var(--ag-ui-rail-width, 52px);
 
   position: var(--_position);
@@ -215,11 +212,11 @@ export const STYLES = `
   --_radius: var(--ag-ui-radius, 0);
 }
 
-/* Page: full-bleed background with a centred reading column. Unlike
-   "full" (edge-to-edge, left-aligned messages) the content sits in a column
-   capped at --ag-ui-content-max-width. The column is produced by symmetric auto
-   padding on the scroll area + composer (no per-row wrapper), so user pills
-   still right-align and the assistant well spans the column. */
+/* Page: full-bleed background with a centred reading column capped at
+   --ag-ui-content-max-width, where "full" is edge-to-edge and left-aligned.
+   The column comes from symmetric auto padding on the scroll area and
+   composer rather than a per-row wrapper, so user pills still right-align and
+   the assistant well spans the column. */
 :host([placement="page"]) {
   --_inset: var(--ag-ui-inset, 0);
   --_width: var(--ag-ui-width, 100vw);
@@ -237,9 +234,8 @@ export const STYLES = `
   padding-inline: max(12px, calc((100% - var(--_content-max-width)) / 2));
 }
 
-/* The rows between the message list and the composer (skill chips, the
-   /-command palette, the missing-placeholder hint, the upload tray) line up
-   with the column too — chips are padding-based, the palette/hint/tray are
+/* The rows between the message list and the composer line up with the column
+   too. Chips and tray are padding-based while palette and hint are
    margin-based, so each gets its own inline axis nudged by the same gutter. */
 :host([placement="page"]) .skill-chips,
 :host([placement="page"]) .attachment-tray {
@@ -348,13 +344,12 @@ export const STYLES = `
     visibility var(--_motion) var(--_ease);
 }
 
-/* The launcher grows out of the corner the panel shrank into.
-   It is laid out at rest rather than display:none, which is what lets it
-   animate in *and* out: an element that was not rendered has no before-change
-   style to transition from, and one whose display flips to none cannot
-   transition at all. visibility keeps it unpaintable, untabbable and
-   unclickable in between -- the expanded panel's own controls sit under it and
-   must stay reachable. */
+/* The launcher grows out of the corner the panel shrank into. It stays laid
+   out at rest rather than display:none, which is what lets it animate both in
+   and out: an unrendered element has no before-change style to transition
+   from, and one flipping display to none cannot transition at all. visibility
+   keeps it unpaintable, untabbable and unclickable in between, so the expanded
+   panel's own controls underneath stay reachable. */
 :host([collapsed]) .launcher {
   opacity: 1;
   transform: none;
@@ -515,20 +510,18 @@ export const STYLES = `
 
 /* ── Collapse ───────────────────────────────────────────────────────────────
    Collapsing shrinks the widget to the round floating launcher: the panel
-   scales down toward the launcher's corner and fades out, the launcher pops in
-   from that same point. Both halves are transform and opacity only, so the
-   morph runs on the compositor and never reflows the host page.
-
-   The host box keeps its expanded size. Animating it would animate layout, and
-   a dragged --ag-ui-width would then fight the launcher's own size. Nothing
-   paints there once the panel is gone, so the box only has to stop swallowing
-   clicks: pointer events go to none, and the launcher takes them back.
-
-   Two placements collapse to something else and restore what they need:
-   "sidebar" slides to its rail (below), while "embedded" and "page" keep the
-   original header bar — embedded is laid out by the host page, where a
-   floating circle would escape the layout, and page is a full-screen route
-   with no corner to float in. */
+   scales toward the launcher's corner and fades, the launcher pops in from the
+   same point. Both halves are transform and opacity only, so the morph runs on
+   the compositor and never reflows the host page.
+
+   The host box keeps its expanded size, since animating it would animate
+   layout and a dragged --ag-ui-width would fight the launcher's own size.
+   Nothing paints there once the panel is gone, so the box only has to stop
+   swallowing clicks: pointer events go to none and the launcher takes them.
+
+   Two placements collapse differently: "sidebar" slides to its rail (below),
+   while "embedded" and "page" keep the header bar, having no corner for a
+   floating circle that would escape the host's layout. */
 :host([collapsed]) {
   pointer-events: none;
 }
@@ -539,11 +532,11 @@ export const STYLES = `
   visibility: hidden;
 }
 
-/* visibility is what keeps the panel out of the tab order and the a11y tree at
-   rest without display:none killing the transition. It interpolates so that any
-   progress below 1 still counts as visible: the panel stays on screen for the
-   whole collapse and flips hidden exactly at the end, and on expand it is
-   visible from the first frame. */
+/* visibility keeps the panel out of the tab order and the a11y tree at rest
+   without display:none killing the transition. It interpolates so any progress
+   below 1 still counts as visible: the panel stays on screen for the whole
+   collapse, flips hidden exactly at the end, and on expand is visible from the
+   first frame. */
 .chat {
   transform-origin: bottom right;
   transition:
@@ -570,10 +563,9 @@ export const STYLES = `
   visibility: visible;
 }
 
-/* These two keep the header bar, so the launcher must stay out of the way —
-   an embedded host is position: static, which would otherwise leave an
-   absolutely-positioned circle to escape the layout entirely and land against
-   whatever the page happens to position. */
+/* These two keep the header bar, so the launcher must stay out of the way: an
+   embedded host is position: static, which would let an absolutely-positioned
+   circle escape the layout and land against whatever the page positions. */
 :host([collapsed]:is([placement="embedded"], [placement="page"])) .launcher {
   visibility: hidden;
   opacity: 0;
@@ -613,7 +605,7 @@ export const STYLES = `
    and the pending indicator so a whole answer reads (and can be boxed) as one
    unit. A flex column on the message-list gap, stretched to the list width so
    its children keep their own left/right alignment. data-answer-well opts into
-   the bordered "well"; without it the layout is today's flat stack. */
+   the bordered "well"; without it the turn renders as a flat stack. */
 .answer {
   display: flex;
   flex-direction: column;
@@ -739,13 +731,9 @@ export const STYLES = `
   position: relative;
 }
 
-/* This button is the only reader of --ag-ui-surface and --ag-ui-text, and
-   neither had a default until the alias layer gave them one. Both references
-   used to resolve to nothing, dropping the declaration: the background fell
-   back to the initial transparent, and the hover/copied colour to the
-   inherited body colour. The defaults chosen upstream (transparent, and the
-   body foreground) reproduce that, so the rename repaints nothing. A raised
-   surface behind the button is a separate design question. */
+/* The only reader of --ag-ui-surface and --ag-ui-text. Their defaults are
+   transparent and the body foreground, which is what this button rendered as
+   before either token existed; changing them repaints only this control. */
 .code-copy {
   position: absolute;
   top: 4px;
@@ -791,12 +779,10 @@ export const STYLES = `
   color: var(--_muted);
 }
 
-/* Markdown tables. table/thead/tbody/tr/th/td are all in
-   the sanitizer's ALLOWED_TAGS, so an agent emitting one renders it — and until
-   now rendered it entirely unstyled, overflowing the bubble. A wide table
-   scrolls inside its own box rather than stretching the message: the bubble is
-   width-constrained, so without this the columns either crush or push the
-   layout sideways. */
+/* Markdown tables. table/thead/tbody/tr/th/td are all in the sanitizer's
+   ALLOWED_TAGS, so an agent can emit one. A wide table must scroll inside its
+   own box rather than stretch the message: the bubble is width-constrained, so
+   without this the columns either crush or push the layout sideways. */
 .message--assistant table {
   display: block;
   width: fit-content;
@@ -937,18 +923,28 @@ export const STYLES = `
   color: var(--_tool-fg);
 }
 
+/* Wraps, because the name is the only flexible child and every badge the row
+   gains is taken out of it. An approved call adds a third fixed badge, which in
+   a sidebar-width panel left the name 37px and broke it mid-word. Badges drop to
+   their own row instead. */
 .tool-call-head {
   display: flex;
+  flex-wrap: wrap;
   align-items: center;
   justify-content: space-between;
   gap: 8px;
 }
 
 .tool-call-name {
-  flex: 1;
-  min-width: 0;
+  /* An auto basis, and a min-width floor rather than zero: the name may shrink,
+     but not below something readable, so wrapping moves a badge instead of
+     shredding a word. Breaking anywhere still applies to a name that cannot fit
+     on a line of its own, which is what keeps a long unbroken tool name inside
+     the card. */
+  flex: 1 1 auto;
+  min-width: 6ch;
   font-weight: 600;
-  word-break: break-word;
+  overflow-wrap: anywhere;
 }
 
 /* Leading status icon. Empty in the DOM — the glyph/spinner is drawn
@@ -1053,8 +1049,6 @@ export const STYLES = `
   color: var(--_muted);
 }
 
-/* The record of a human decision on a gated call. An approved call used to
-   look exactly like one that was never gated. */
 .skill-item-token {
   font-family: ui-monospace, "SF Mono", Menlo, monospace;
   font-size: 0.92em;
@@ -1062,6 +1056,8 @@ export const STYLES = `
   margin-right: 6px;
 }
 
+/* The lasting record of a human decision on a gated call — without it an
+   approved call looks exactly like one that was never gated. */
 .tool-call-decision {
   flex: none;
   font-size: 11px;
@@ -1084,10 +1080,8 @@ export const STYLES = `
 }
 
 /* Display modes are pure visibility over one DOM shape, selected from the host
-   attribute rather than a value stamped on the card when it was built. That is
-   what lets a host flip data-tool-display and have every card already on screen
-   re-read it, the way data-answer-well behaves. Baking the structure per mode
-   meant the setting only reached cards created afterwards.
+   attribute rather than a value stamped on the card at build time, so flipping
+   data-tool-display re-styles cards already on screen. See ToolCallCard.
 
    Default (no attribute) is the full mode: arguments always visible, result
    behind the toggle. */
@@ -1184,20 +1178,19 @@ export const STYLES = `
 }
 
 /* Then the measurement corrects it. Which edges are held still belongs to the
-   host's layout rather than to placement -- a floating panel a host right-aligns
-   is anchored bottom-left, not bottom-right -- so the element measures the edges
-   that stay put and stamps them here as "<y>-<x>". Equal specificity to the
-   rules above, so source order is what lets the measured value win.
-
-   These must not be written as [data-resize-anchor~="left"]: the stamped value
-   is one hyphenated token, and ~= matches whitespace-separated words, so such a
-   selector cannot ever match. It did not, which left the grip drawn at the
-   corner that moves while the cursor pointed along the right diagonal.
-
-   Each rule also sets both sides of its axis rather than only the side it
-   moves. One that flipped a single way could not undo a placement guess that
-   had flipped the other, which put the grip on the anchored corner for an
-   embedded panel its host right-aligns. */
+   host's layout, not to placement -- a floating panel a host right-aligns is
+   anchored bottom-left -- so the element measures them and stamps a single
+   hyphenated "<y>-<x>" token here. Equal specificity to the rules above, so
+   source order is what lets the measured value win.
+
+   Two traps, both of which silently draw the grip on the corner that moves:
+
+   Never write these as [data-resize-anchor~="left"]. The stamped value is one
+   hyphenated token and ~= matches whitespace-separated words, so it can never
+   match.
+
+   Each rule must set both sides of its axis, not only the side it moves, or it
+   cannot undo a placement guess that flipped the other way. */
 :host([data-resize-anchor$="-left"]) .resize-handle {
   left: auto;
   right: 0;
@@ -1258,10 +1251,9 @@ export const STYLES = `
 }
 
 /* ── Composer ───────────────────────────────────────────────────────────────
-   One surface owns the border, the background and the focus ring; the field and
-   its tool row sit inside it. The row used to be four siblings stretched to the
-   textarea's height, which gave a paperclip the same visual weight as the field
-   and turned Send into a full-height slab. */
+   One surface owns the border, the background and the focus ring; the field
+   and its tool row sit inside it, rather than being siblings stretched to the
+   textarea's height. */
 .input-row {
   display: flex;
   padding: 12px;
@@ -1509,13 +1501,12 @@ export const STYLES = `
 }
 
 /* A chip carries its own text colour because it carries its own background.
-   The same chip renders in two places with opposite inherited colours: in the
-   composer tray it inherits the panel's, but on a sent user bubble it inherits
-   the user foreground, which is white on the stock light theme. Against the
-   assistant surface underneath that was a 1.13:1 filename — invisible, and only
-   the size stayed legible because it sets its own muted colour. Pair the colour
-   with the background it belongs to, and both placements read the same.
-   Overridden below for an errored chip, which must keep its red. */
+   The same chip renders in two places with opposite inherited colours: the
+   composer tray gives it the panel's, a sent user bubble gives it the user
+   foreground, which is white on the stock light theme and near-invisible
+   against the chip. Pairing the colour with the background it belongs to makes
+   both placements read alike. Overridden below for an errored chip, which
+   keeps its red. */
 .attachment-chip {
   display: inline-flex;
   align-items: center;

package/src/ui/thoughts_block.ts

@@ -4,15 +4,13 @@ import { DEFAULT_UI_STRINGS, type UiStrings } from "./ui_strings.js";
  * A muted, collapsible "thinking" region for a reasoning model's streamed
  * chain-of-thought.
  *
- * Lives at the top of the current answer group (the turn container): it
- * opens expanded while the model reasons — {@link stream} replaces its body with
- * the running reasoning buffer — and {@link collapse} folds it away once the
- * answer's first text token arrives, so the thoughts don't crowd the answer.
- * The header toggle lets the reader reopen it.
+ * Sits at the top of the current answer group. It opens expanded while the
+ * model reasons, {@link stream} replacing its body with the running buffer, and
+ * {@link collapse} folds it away once the answer's first text token arrives.
+ * The header toggle reopens it.
  *
- * Pure DOM (no framework); the host inserts {@link element} and themes it via
- * the `--ag-ui-*` custom properties or the `thoughts*` `part`s. All visible
- * chrome text is sourced from {@link UiStrings}.
+ * Pure DOM. The host inserts {@link element}; all visible chrome text comes
+ * from {@link UiStrings}.
  */
 export class ThoughtsBlock {
   /** The block's root element; insert this at the top of the answer group. */
@@ -30,8 +28,8 @@ export class ThoughtsBlock {
     this.element = document.createElement("div");
     this.element.className = "thoughts";
     this.element.setAttribute("part", "thoughts");
-    // `data-streaming` lets CSS animate the header (e.g. a pulse) while the
-    // model is still reasoning; dropped on collapse.
+    // Lets CSS animate the header while the model is still reasoning; dropped
+    // on collapse.
     this.element.setAttribute("data-streaming", "");
 
     this.#toggle = document.createElement("button");
@@ -63,9 +61,9 @@ export class ThoughtsBlock {
   }
 
   /**
-   * Fold the region away — called when the answer's first text token arrives.
-   * Idempotent (the per-token text handler calls it repeatedly) and flips the
-   * header label from "thinking…" to the settled "Thoughts" affordance.
+   * Fold the region away when the answer's first text token arrives, flipping
+   * the header label to its settled form. Idempotent, since the per-token text
+   * handler calls it repeatedly.
    */
   collapse(): void {
     if (this.#collapsed) {

package/src/ui/thread_drawer.ts

@@ -17,13 +17,14 @@ export interface ThreadDrawerCallbacks {
 /**
  * The chat-history drawer: a slide-over listing the user's threads (title,
  * relative time, preview), with select / new / rename / delete actions and an
- * empty state. Pure DOM in the spirit of {@link SkillsMenu} — the host appends
+ * empty state. Pure DOM, like {@link SkillsMenu}: the host appends
  * {@link element}, toggles it, feeds rows via {@link setThreads}, and acts on
- * the callbacks. The drawer is a *view*: it does not mutate the store; after a
- * callback the host updates the store and calls {@link setThreads} to refresh.
+ * the callbacks.
  *
- * All visible text comes from {@link UiStrings}; {@link setStrings} re-localizes
- * a drawer the host built before its strings resolved.
+ * A view only — it never mutates the store. After a callback the host updates
+ * the store and calls {@link setThreads} to refresh. All visible text comes
+ * from {@link UiStrings}; {@link setStrings} re-localizes a drawer built before
+ * its strings resolved.
  */
 export class ThreadDrawer {
   /** The drawer root (backdrop + panel). Append to the chat shell; hidden until opened. */

package/src/ui/tool_call_card.ts

@@ -41,29 +41,24 @@ function formatPayload(text: string): string {
 /**
  * A live tool-call card for the chat transcript.
  *
- * Construction renders a status icon, the tool name, a `running…` pill, and the
- * card's body: an **arguments** region and a **result** region, each with its own
- * heading and its own `part`. {@link settle} fills in the result and flips the
- * pill. Both payloads are pretty-printed, and the two are never concatenated —
- * the previous compact layout ran `args: {...}` and the result together in one
- * `<pre>`, leaving no way to see where the call ended and the answer began.
+ * Construction renders a status icon, the tool name, a status pill, and a body
+ * of two separately-headed regions — arguments and result — each with its own
+ * `part`. {@link settle} fills in the result and flips the pill. Both payloads
+ * are pretty-printed and never concatenated into one block.
  *
- * **The card renders one DOM shape in every display mode, and CSS decides what
- * shows.** That is what makes `data-tool-display` behave like `data-answer-well`
- * — flip it on the host and every card already on screen re-reads it. Building a
- * different structure per mode meant only cards created *after* the change
- * picked it up, so the setting appeared not to work until the next conversation.
- * Visibility is selected from the host attribute rather than a value copied onto
- * the card at construction, for the same reason.
+ * The card renders one DOM shape in every display mode and lets CSS decide what
+ * shows, selecting visibility from the host attribute rather than a value
+ * copied onto the card at construction. That is what lets `data-tool-display`
+ * be flipped on the host and re-read by every card already on screen; building
+ * a different structure per mode would leave existing cards stale.
  *
- * The leading icon carries no text of its own: its glyph/spinner is drawn by
- * the shadow CSS keyed off the card's `data-status`, so a host themes it via
- * the `--ag-ui-tool-icon-*` custom properties (or the `tool-card-icon` part)
- * without the card reaching into the host stylesheet.
+ * The leading icon carries no text: the shadow CSS draws its glyph or spinner
+ * from the card's `data-status`, so a host themes it through the
+ * `--ag-ui-tool-icon-*` custom properties or the `tool-card-icon` part without
+ * the card reaching into the host stylesheet.
  *
- * Pure DOM (no framework); the host appends {@link element} into its shadow
- * root and themes it via the `--ag-ui-*` custom properties or the exposed
- * `tool-card*` `part`s. All visible text is sourced from {@link UiStrings}.
+ * Pure DOM. The host appends {@link element} into its shadow root; all visible
+ * text comes from {@link UiStrings}.
  */
 export class ToolCallCard {
   /** The card's root element; append this into the message list. */
@@ -97,9 +92,8 @@ export class ToolCallCard {
     head.className = "tool-call-head";
     head.setAttribute("part", "tool-card-head");
 
-    // The leading status icon — a spinner while pending, a check/cross/slash on
-    // settle. Empty in the DOM: the shadow CSS draws it from `data-status`, so
-    // the glyphs stay themeable (`--ag-ui-tool-icon-*`) and the spin is real.
+    // Left empty in the DOM on purpose: the shadow CSS draws the spinner or
+    // settled mark from `data-status`, keeping the glyphs themeable.
     const icon = document.createElement("span");
     icon.className = "tool-call-icon";
     icon.setAttribute("part", "tool-card-icon");
@@ -125,16 +119,15 @@ export class ToolCallCard {
 
     const argsSection = this.#section("args", strings.argumentsLabel);
     argsSection.body.textContent = JSON.stringify(args, null, 2);
-    // A call with no arguments renders an empty object in a box of its own,
-    // which is a frame around nothing. Drop the region instead.
+    // Drop the region rather than frame an empty object.
     argsSection.root.hidden = Object.keys(args).length === 0;
 
     const resultSection = this.#section("result", strings.resultLabel);
     this.#resultSection = resultSection.root;
     this.#resultLabel = resultSection.label;
     this.#resultBody = resultSection.body;
-    // Nothing to show until `settle` supplies it; a pending card would
-    // otherwise expand onto an empty region.
+    // Nothing to show until `settle` supplies it, or a pending card expands
+    // onto an empty region.
     resultSection.root.hidden = true;
 
     this.#toggle = document.createElement("button");
@@ -155,11 +148,8 @@ export class ToolCallCard {
 
   /**
    * Record that a human approved or declined this call, as a line in the card.
-   *
-   * Approval used to leave no trace at all: a declined call became a tool
-   * result saying so, while an approved one simply ran, making the transcript
-   * of a gated call byte-identical to one that was never gated. The prompt is
-   * gone once answered, so this is where the decision lives.
+   * The prompt disappears once answered, so this is the only lasting trace that
+   * the call was gated at all.
    */
   recordDecision(kind: "approved" | "declined"): void {
     this.element.setAttribute("data-decision", kind);

package/src/ui/ui_strings.ts

@@ -5,14 +5,9 @@
  * or its `data-strings` JSON attribute) and the rest fall back to the English
  * defaults.
  *
- * A handful of values are **templates** carrying `{token}` placeholders the call
- * site fills in (e.g. `minutesAgo` → `"{n}m ago"`); the token names are noted on
- * each key. Translators keep the token verbatim.
- *
- * This module is one cohesive unit — the `UiStrings` shape, its `DEFAULT_UI_STRINGS`
- * constant-like backing, and the {@link mergeUiStrings} merge over those defaults —
- * so it bends the one-symbol-per-file rule the way `tool_call_card.ts` (class +
- * its types) and `route_map.ts` (factory + its types) already do.
+ * Some values are templates carrying `{token}` placeholders the call site fills
+ * in; the token names are noted on each key, and a translation must keep them
+ * verbatim.
  */
 export interface UiStrings {
   // ── Header ────────────────────────────────────────────────────────────────
@@ -27,10 +22,9 @@ export interface UiStrings {
   /** Expand affordance (the launcher, and the sidebar rail). */
   expand: string;
   /**
-   * The launcher's label while unread answers are waiting behind it, with
-   * `{count}` replaced by how many. It replaces {@link expand} rather than
-   * appending to it, so a translation can order the two parts as its language
-   * needs.
+   * The launcher's label while unread answers wait behind it. Token: `{count}`.
+   * Replaces {@link expand} rather than appending to it, so a translation can
+   * order the two parts as its language needs.
    */
   expandUnread: string;
   /** Built-in header theme toggle (light ⇄ dark). */

package/src/ui/voice_input.ts

@@ -20,13 +20,13 @@ export interface VoiceInputOptions {
  * `MediaRecorder`, then POSTs the clip through a {@link TranscribeHandler} and
  * hands the transcript back via `onText`.
  *
- * Click to start recording (browser mic permission prompt), click again to stop
- * — the clip is transcribed and dropped into the composer. The button reflects
- * its `idle` / `recording` / `transcribing` state on `data-state` for theming
- * and is exposed as `part="voice-button"`. A capture or transcription failure
- * returns the button to idle and surfaces the message on its tooltip.
+ * Click to start recording, which prompts for mic permission, and again to stop
+ * and transcribe. The button reflects its `idle` / `recording` / `transcribing`
+ * state on `data-state` for theming and is exposed as `part="voice-button"`; a
+ * capture or transcription failure returns it to idle and surfaces the message
+ * on its tooltip.
  *
- * Pure DOM (no framework); the host mounts {@link element} in the input row.
+ * Pure DOM. The host mounts {@link element} in the input row.
  */
 export class VoiceInput {
   /** The mic button; mount this in the composer. */
@@ -102,11 +102,10 @@ export class VoiceInput {
   }
 
   /**
-   * Tear the control down — the teardown path when the host element is removed
-   * mid-recording. Stops any live `MediaRecorder`, releases the mic tracks (so
-   * the browser's recording indicator clears), and suppresses the pending
-   * transcription: a disconnected control must not fire `onText` back into a
-   * detached element.
+   * Tear the control down, for a host element removed mid-recording. Stops any
+   * live `MediaRecorder`, releases the mic tracks so the browser's recording
+   * indicator clears, and suppresses the pending transcription — a
+   * disconnected control must not fire `onText` into a detached element.
    */
   dispose(): void {
     this.#disposed = true;

package/src/version.ts

@@ -1 +1 @@
-export const VERSION: string = "0.23.0";
+export const VERSION: string = "0.24.0";