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

package/dist/ui/ui_strings.d.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 {
     /** Default header title (the `title-text` attribute overrides per element). */
@@ -26,10 +21,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/dist/ui/ui_strings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ui_strings.d.ts","sourceRoot":"","sources":["../../src/ui/ui_strings.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ui_strings.d.ts","sourceRoot":"","sources":["../../src/ui/ui_strings.ts"],"names":[],"mappings":"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"}

package/dist/ui/voice_input.d.ts

@@ -14,13 +14,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 declare class VoiceInput {
     #private;
@@ -30,11 +30,10 @@ export declare class VoiceInput {
     /** Start recording when idle, stop (and transcribe) when recording. */
     toggle(): Promise<void>;
     /**
-     * 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;
 }

package/dist/ui/voice_input.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"voice_input.d.ts","sourceRoot":"","sources":["../../src/ui/voice_input.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAKrE,mDAAmD;AACnD,MAAM,WAAW,iBAAiB;IAChC,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,EAAE,iBAAiB,CAAC;IACvC,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,yCAAyC;IACzC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC;CAC9B;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,UAAU;;IACrB,kDAAkD;IAClD,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;IAWpC,YAAY,OAAO,EAAE,iBAAiB,EAmBrC;IAED,uEAAuE;IACjE,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAS5B;IA6BD;;;;;;OAMG;IACH,OAAO,IAAI,IAAI,CAOd;CAyDF"}
+{"version":3,"file":"voice_input.d.ts","sourceRoot":"","sources":["../../src/ui/voice_input.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAKrE,mDAAmD;AACnD,MAAM,WAAW,iBAAiB;IAChC,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,EAAE,iBAAiB,CAAC;IACvC,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,yCAAyC;IACzC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC;CAC9B;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,UAAU;;IACrB,kDAAkD;IAClD,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;IAWpC,YAAY,OAAO,EAAE,iBAAiB,EAmBrC;IAED,uEAAuE;IACjE,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAS5B;IA6BD;;;;;OAKG;IACH,OAAO,IAAI,IAAI,CAOd;CAyDF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@artooi/ag-ui-web-component",
-  "version": "0.22.0",
+  "version": "0.23.1",
   "description": "Framework-free <ag-ui-chat> Web Component over the AG-UI protocol. Drop-in chat sidebar with a pluggable client-side tool registry, DOM driver primitives, animations, and destructive-action confirmation modal.",
   "type": "module",
   "main": "./dist/index.js",

package/src/constants.ts

@@ -1,55 +1,40 @@
-// The package's single home for enums and constant-like values. Per
-// CLAUDE.md this is the only file allowed to export multiple symbols.
+// The package's single home for enums and constant-like values, and per
+// CLAUDE.md the only file allowed to export multiple symbols.
 
 /** The Custom Element tag name registered by {@link defineAgUiChat}. */
 export const ELEMENT_TAG = "ag-ui-chat";
 
-/**
- * Event dispatched by `<ag-ui-chat>` when the user submits a message.
- * `detail` carries `{ content: string }`. Later phases wire this to the
- * AG-UI client; for now it is the public seam for host integration.
- */
+/** User submitted a message. `detail` is {@link SubmitDetail}. */
 export const SUBMIT_EVENT = "ag-ui-submit";
 
 /**
- * Event dispatched by `<ag-ui-chat>` when its collapsed state changes (via the
- * built-in toggle or {@link setCollapsed}). `detail` carries
- * `{ collapsed: boolean }`. A host can listen to drive its own chrome, or hide
- * the built-in toggle and drive the `collapsed` attribute itself.
+ * Collapsed state changed, via the built-in toggle or `setCollapsed`.
+ * `detail` is {@link ToggleDetail}.
  */
 export const TOGGLE_EVENT = "ag-ui-toggle";
 
 /**
- * Event dispatched by `<ag-ui-chat>` when the number of answers that arrived
- * while it was collapsed changes — one more finished, or expanding cleared them
- * all. `detail` carries `{ unread: number }`.
- *
- * The built-in badge on the launcher renders exactly this. A host driving its
- * own chrome can turn the badge off with `data-unread-badge="false"` and listen
- * here instead.
+ * The count of answers that arrived while collapsed changed. `detail` is
+ * {@link UnreadDetail}. The built-in launcher badge renders exactly this; a
+ * host driving its own chrome sets `data-unread-badge="false"` and listens.
  */
 export const UNREAD_EVENT = "ag-ui-unread";
 
 /**
- * Event dispatched by `<ag-ui-chat>` when AG-UI **shared state** changes — the
- * server streamed a `STATE_SNAPSHOT` / `STATE_DELTA`, or the host assigned
- * {@link AgUiChat.sharedState}. `detail` carries `{ state }`.
+ * AG-UI shared state changed — a streamed `STATE_SNAPSHOT` / `STATE_DELTA`, or
+ * a host assignment to `sharedState`. `detail` is {@link StateDetail}.
  *
- * This is the protocol's own state channel, distinct from `registerPageState`,
- * which exposes host state to the agent as ordinary *tools*.
+ * The protocol's own state channel, distinct from `registerPageState`, which
+ * exposes host state to the agent as ordinary tools.
  */
 export const STATE_EVENT = "ag-ui-state";
 
 /**
- * Event dispatched by `<ag-ui-chat>` whenever the attachment tray changes — a
- * file queued, an upload finishing or failing, a chip removed, the tray
- * cleared after a send. `detail` carries `{ attachments, pending }`:
- * the durable refs of everything that has finished uploading, and how many are
- * still in flight.
- *
- * This is the seam for a host that drives its own composer: without it the tray
- * only ever spoke to the built-in Send button, so a custom send had no way to
- * know whether a file was ready or still uploading.
+ * The attachment tray changed — a file queued, an upload finishing or failing,
+ * a chip removed, the tray cleared after a send. `detail` is
+ * {@link AttachmentsDetail}, carrying the refs that finished uploading and how
+ * many are still in flight. A host driving its own composer uses this to know
+ * whether a send would leave files behind.
  */
 export const ATTACHMENT_EVENT = "ag-ui-attachments";
 
@@ -60,43 +45,35 @@ export const MESSAGE_ROLE = {
 } as const;
 
 /**
- * JSON-Schema extension key marking a tool as destructive. Mirrors the
- * `django-ag-ui` server side. When a tool's `parameters` carries
- * `{ "x-destructive": true }`, the element gates its execution behind the
- * confirmation modal (unless `autoConfirm` is set).
+ * Schema-root key marking a tool destructive: the element gates its execution
+ * behind the confirmation card unless `autoConfirm` is set. All four `x-*` keys
+ * below mirror the `django-ag-ui` server side.
  */
 export const X_DESTRUCTIVE_KEY = "x-destructive";
 
 /**
- * JSON-Schema extension key carrying a human-readable confirmation prompt for a
- * destructive tool (e.g. `"Activate this project?"`). Mirrors the `django-ag-ui`
- * server side. When present, the inline confirmation card shows this instead of
- * the generic `Run "<tool>"?`.
+ * Schema-root key holding a confirmation prompt (e.g. `"Activate this
+ * project?"`), shown instead of the generic `Run "<tool>"?`.
  */
 export const X_CONFIRM_KEY = "x-confirm";
 
 /**
- * JSON-Schema extension key carrying a short human-readable label for a tool
- * (e.g. `"Query orders"` for `query_model`). Mirrors the `django-ag-ui` server
- * side; the tool-call card shows it instead of the raw tool name when present.
+ * Schema-root key holding a short label for a tool (e.g. `"Query orders"` for
+ * `query_model`), shown on the card instead of the raw tool name.
  */
 export const X_SUMMARY_KEY = "x-summary";
 
 /**
- * JSON-Schema extension key marking a tool as navigating — its handler triggers
- * a full page reload (an MPA navigation). When a tool's `parameters` carries
- * `{ "x-navigates": true }`, the element checkpoints the call before the reload
- * and resumes the run loop once the next page mounts. Mirrors `x-destructive`.
+ * Schema-root key marking a tool as navigating — its handler triggers a full
+ * page reload. The element checkpoints the call before the reload and resumes
+ * the run loop once the next page mounts.
  */
 export const X_NAVIGATES_KEY = "x-navigates";
 
 /**
- * Name of the built-in tool that re-reads the current page.
- *
- * Registered only when a page-map provider is set. Named here because it is
- * also the documented recovery from a stale page, so the stale-page guard has
- * to exempt it — refusing the very call that would refresh the agent's view
- * would be a deadlock.
+ * The built-in tool that re-reads the current page, registered only when a
+ * page-map provider is set. Named here because the stale-page guard must exempt
+ * it: refusing the one call that would refresh the agent's view deadlocks.
  */
 export const READ_PAGE_TOOL = "read_page";
 
@@ -127,23 +104,20 @@ export const ATTACHMENT_STATUS = {
 
 /**
  * Default client-side upload size cap (10 MiB), matching django-ag-ui's
- * `ATTACHMENT_MAX_BYTES` default. Overridable per element via
- * `data-attachment-max-bytes`; the server stays authoritative.
+ * `ATTACHMENT_MAX_BYTES`. Overridable via `data-attachment-max-bytes`; the
+ * server stays authoritative.
  */
 export const DEFAULT_ATTACHMENT_MAX_BYTES = 10 * 1024 * 1024;
 
 /**
- * How much detail a tool-call card shows. Set via the `data-tool-display`
- * attribute on `<ag-ui-chat>`; defaults to `full` (back-compatible).
+ * How much detail a tool-call card shows. Set via `data-tool-display`; the
+ * default is `full`.
  *
- * - `inline` — the lightest mode: a single status row (icon + summary) with no
- *   surrounding card chrome, the result tucked behind its own toggle. Reads as
- *   one line of the answer rather than a boxed card — pairs with the answer
- *   well (page mode).
- * - `minimal` — just the tool name + status pill. No args, no result body.
- * - `compact` — name + status, with args *and* result tucked behind a single
- *   collapsed "Details" toggle. The light default for dense UIs.
- * - `full` — args shown inline, result behind its own toggle (the original).
+ * - `inline` — one status row (icon + summary), no card chrome, result behind
+ *   its own toggle. Reads as a line of the answer rather than a boxed card.
+ * - `minimal` — tool name + status pill only. No args, no result body.
+ * - `compact` — name + status, args and result behind one "Details" toggle.
+ * - `full` — args inline, result behind its own toggle.
  */
 export const TOOL_DISPLAY = {
   INLINE: "inline",
@@ -153,32 +127,32 @@ export const TOOL_DISPLAY = {
 } as const;
 
 /**
- * `activityType` of the AG-UI `ACTIVITY_SNAPSHOT` event `django-ag-ui` emits
- * when a compaction capability trimmed the message history. Its `content`
- * carries `{ removed, before, after }`.
+ * `activityType` of the `ACTIVITY_SNAPSHOT` event django-ag-ui emits when a
+ * compaction capability trimmed the history. `content` carries
+ * `{ removed, before, after }`.
  */
 export const COMPACTION_ACTIVITY_TYPE = "compaction";
 
 /**
- * Pydantic-AI's built-in tool the model calls to load a *deferred* capability,
- * with `{ id }` naming it. Agent skills are deferred capabilities whose id is
- * the skill name, so a call to this tool is how "the agent picked skill X"
- * reaches the client — there is no separate event for it.
+ * Pydantic-AI's built-in tool for loading a deferred capability, with `{ id }`
+ * naming it. Agent skills are deferred capabilities keyed by skill name, so a
+ * call to this tool is the only signal that the agent picked a skill.
  *
- * Not to be confused with the host-provided {@link Skill} catalog, which is a
- * *human* affordance (a prompt the user launches from the `/`-palette).
+ * Distinct from the host-provided {@link Skill} catalog, which is a human
+ * affordance launched from the slash palette.
  */
 export const LOAD_CAPABILITY_TOOL = "load_capability";
 
 /**
  * The chrome's glyphs, as inline SVG markup.
  *
- * Static, author-written markup assigned to a `<slot>`'s fallback content, so
- * it never passes through the sanitiser — nothing here is user or server data.
- * Each icon is a 24x24 viewBox carrying the shared `glyph` class, which
- * `STYLES` sizes and paints from `currentColor`; `glyph--solid` fills instead
- * of stroking. A host that wants its own mark projects a matching
- * `slot="icon-…"` child rather than editing these.
+ * Static author-written markup assigned as a `<slot>`'s fallback content, so it
+ * never passes through the sanitiser — nothing here is user or server data, and
+ * nothing user-supplied may be interpolated into it. Each icon is a 24x24
+ * viewBox carrying the shared `glyph` class, which `STYLES` sizes and paints
+ * from `currentColor`; `glyph--solid` fills instead of stroking. A host wanting
+ * its own mark projects a matching `slot="icon-…"` child instead of editing
+ * these.
  */
 export const ICON_SEND = `<svg class="glyph" viewBox="0 0 24 24" aria-hidden="true"><path d="M12 19.5V5m-6.5 6.5L12 5l6.5 6.5"/></svg>`;
 
@@ -193,3 +167,20 @@ export const ICON_VOICE = `<svg class="glyph" viewBox="0 0 24 24" aria-hidden="t
 
 /** The default launcher mark (a speech bubble), shown when the host slots none. */
 export const ICON_LAUNCHER = `<svg class="glyph" viewBox="0 0 24 24" aria-hidden="true"><path d="M4 5.5A2.5 2.5 0 0 1 6.5 3h11A2.5 2.5 0 0 1 20 5.5v8a2.5 2.5 0 0 1-2.5 2.5H9l-5 4z"/></svg>`;
+
+/**
+ * The generic attachment-chip mark, for a file family with nothing more
+ * specific to say. The chip marks share the contract of the chrome glyphs
+ * above; `iconFor` selects one by MIME family, never interpolating the MIME
+ * string into the markup.
+ */
+export const ICON_FILE = `<svg class="glyph" viewBox="0 0 24 24" aria-hidden="true"><path d="M14 3H7a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V8z"/><path d="M14 3v5h5"/></svg>`;
+
+/** An image attachment: a framed picture with a horizon and a sun. */
+export const ICON_FILE_IMAGE = `<svg class="glyph" viewBox="0 0 24 24" aria-hidden="true"><rect x="3.5" y="4.5" width="17" height="15" rx="2.5"/><circle cx="9" cy="10" r="1.5"/><path d="M4.5 17.5 9 13.5l3.5 3 3-2.5 4.5 4"/></svg>`;
+
+/** A PDF: the generic page, banded to read as a labelled document. */
+export const ICON_FILE_PDF = `<svg class="glyph" viewBox="0 0 24 24" aria-hidden="true"><path d="M14 3H7a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V8z"/><path d="M14 3v5h5"/><rect class="glyph--solid" x="7.5" y="13.5" width="9" height="4.5" rx="1"/></svg>`;
+
+/** A text document: the generic page, ruled. */
+export const ICON_FILE_TEXT = `<svg class="glyph" viewBox="0 0 24 24" aria-hidden="true"><path d="M14 3H7a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V8z"/><path d="M14 3v5h5"/><path d="M8.5 13.5h7M8.5 17h4.5"/></svg>`;