@artooi/ag-ui-web-component 0.1.0 → 0.2.0

package/src/{agui_client.ts → core/agui_client.ts}

@@ -1,6 +1,6 @@
 import { type AbstractAgent, type AgentSubscriber, randomUUID } from "@ag-ui/client";
 import type { Context, Message, Tool } from "@ag-ui/core";
-import { MAX_TOOL_ROUNDS } from "./constants.js";
+import { MAX_TOOL_ROUNDS } from "../constants.js";
 
 /** A tool call surfaced to the host by {@link AgUiClient}. */
 export interface AgUiToolCall {

package/src/{define_ag_ui_chat.ts → core/define_ag_ui_chat.ts}

@@ -1,5 +1,5 @@
+import { ELEMENT_TAG } from "../constants.js";
 import { AgUiChat } from "./ag_ui_chat.js";
-import { ELEMENT_TAG } from "./constants.js";
 
 /**
  * Register the `<ag-ui-chat>` Custom Element.

package/src/dom/animations.ts

@@ -0,0 +1,201 @@
+/**
+ * Visible-action animation primitives.
+ *
+ * These run against the **host page** DOM (not the element's shadow root) so a
+ * user watches the agent type, highlight, and click at human-readable speed.
+ * Each is configurable; pass small/zero durations in tests (or use fake timers).
+ */
+
+import { setNativeChecked, setNativeValue } from "./native_setter.js";
+
+const ACCENT = "#4f46e5";
+
+function delay(ms: number): Promise<void> {
+  return new Promise<void>((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+/** An element whose `value` can be typed into. */
+export type TextLikeElement = HTMLInputElement | HTMLTextAreaElement;
+
+export interface TypeOptions {
+  /** Milliseconds between characters. Default 35. */
+  charDelayMs?: number;
+}
+
+/**
+ * Clear ``el`` and type ``value`` one character at a time, firing ``input``
+ * events as a real user would, then a final ``change`` event.
+ */
+export async function typeInto(
+  el: TextLikeElement,
+  value: string,
+  options: TypeOptions = {},
+): Promise<void> {
+  const charDelayMs = options.charDelayMs ?? 35;
+  setNativeValue(el, "");
+  el.dispatchEvent(new Event("input", { bubbles: true }));
+  for (const char of value) {
+    setNativeValue(el, el.value + char);
+    el.dispatchEvent(new Event("input", { bubbles: true }));
+    if (charDelayMs > 0) {
+      await delay(charDelayMs);
+    }
+  }
+  el.dispatchEvent(new Event("change", { bubbles: true }));
+}
+
+export interface HighlightClickOptions {
+  /** Milliseconds to hold the highlight before clicking. Default 280. */
+  highlightMs?: number;
+}
+
+/** Outline ``el``, pause so the user sees it, then click and restore. */
+export async function highlightThenClick(
+  el: HTMLElement,
+  options: HighlightClickOptions = {},
+): Promise<void> {
+  const highlightMs = options.highlightMs ?? 280;
+  const previousOutline = el.style.outline;
+  const previousOffset = el.style.outlineOffset;
+  el.style.outline = `2px solid ${ACCENT}`;
+  el.style.outlineOffset = "2px";
+  await delay(highlightMs);
+  el.style.outline = previousOutline;
+  el.style.outlineOffset = previousOffset;
+  el.click();
+}
+
+/** Scroll ``el`` to the vertical centre of the viewport. */
+export function scrollIntoCenterView(el: HTMLElement): void {
+  el.scrollIntoView({ block: "center", inline: "nearest", behavior: "smooth" });
+}
+
+export interface FlashOptions {
+  /** Milliseconds to hold the focus flash. Default 200. */
+  flashMs?: number;
+}
+
+/** Focus ``el`` and briefly flash a ring around it. */
+export async function focusWithFlash(el: HTMLElement, options: FlashOptions = {}): Promise<void> {
+  const flashMs = options.flashMs ?? 200;
+  el.focus();
+  const previousShadow = el.style.boxShadow;
+  el.style.boxShadow = `0 0 0 3px rgba(79, 70, 229, 0.4)`;
+  await delay(flashMs);
+  el.style.boxShadow = previousShadow;
+}
+
+const RING = "0 0 0 3px rgba(79, 70, 229, 0.4)";
+
+/**
+ * Whether the user has asked the OS/browser to minimise motion.
+ *
+ * The richer action animations below check this and skip their hold delays so
+ * the agent's edits still happen (events fire, values set) but without the
+ * visible pause. The character-typing / highlight primitives above predate this
+ * and keep their explicit-duration contract.
+ */
+export function prefersReducedMotion(): boolean {
+  return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+
+/** Like {@link delay}, but resolves immediately under reduced motion. */
+function motionDelay(ms: number): Promise<void> {
+  if (ms <= 0 || prefersReducedMotion()) {
+    return Promise.resolve();
+  }
+  return delay(ms);
+}
+
+export interface PressOptions {
+  /** Milliseconds to hold the pressed state before clicking. Default 140. */
+  pressMs?: number;
+}
+
+/**
+ * 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}).
+ */
+export async function pressThenClick(el: HTMLElement, options: PressOptions = {}): Promise<void> {
+  const pressMs = options.pressMs ?? 140;
+  const previousTransform = el.style.transform;
+  const previousTransition = el.style.transition;
+  const previousShadow = el.style.boxShadow;
+  el.style.transition = "transform 80ms ease";
+  el.style.transform = "scale(0.96)";
+  el.style.boxShadow = RING;
+  await motionDelay(pressMs);
+  el.style.transform = previousTransform;
+  el.style.transition = previousTransition;
+  el.style.boxShadow = previousShadow;
+  el.click();
+}
+
+export interface SelectOptions {
+  /** Milliseconds to hold the highlight before committing. Default 220. */
+  highlightMs?: number;
+}
+
+/** 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) {
+      return option;
+    }
+  }
+  return null;
+}
+
+/**
+ * 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` +
+ * `change`. Throws when no option matches.
+ */
+export async function selectOption(
+  el: HTMLSelectElement,
+  value: string,
+  options: SelectOptions = {},
+): Promise<void> {
+  const option = findOption(el, value);
+  if (option === null) {
+    throw new Error(`no <option> matching "${value}"`);
+  }
+  const highlightMs = options.highlightMs ?? 220;
+  const previousOutline = el.style.outline;
+  const previousOffset = el.style.outlineOffset;
+  el.style.outline = `2px solid ${ACCENT}`;
+  el.style.outlineOffset = "2px";
+  await motionDelay(highlightMs);
+  setNativeValue(el, option.value);
+  el.dispatchEvent(new Event("input", { bubbles: true }));
+  el.dispatchEvent(new Event("change", { bubbles: true }));
+  el.style.outline = previousOutline;
+  el.style.outlineOffset = previousOffset;
+}
+
+export interface ToggleOptions {
+  /** Milliseconds to hold the flash. Default 200. */
+  flashMs?: number;
+}
+
+/**
+ * Flash a ring around a checkbox/radio, set its ``checked`` state, and fire
+ * `input` + `change` so frameworks observe the flip.
+ */
+export async function toggleControl(
+  el: HTMLInputElement,
+  checked: boolean,
+  options: ToggleOptions = {},
+): Promise<void> {
+  const flashMs = options.flashMs ?? 200;
+  const previousShadow = el.style.boxShadow;
+  el.style.boxShadow = RING;
+  await motionDelay(flashMs);
+  setNativeChecked(el, checked);
+  el.dispatchEvent(new Event("input", { bubbles: true }));
+  el.dispatchEvent(new Event("change", { bubbles: true }));
+  el.style.boxShadow = previousShadow;
+}

package/src/{dom_driver.ts → dom/dom_driver.ts}

@@ -2,11 +2,18 @@ import {
   focusWithFlash,
   type HighlightClickOptions,
   highlightThenClick,
+  type PressOptions,
+  pressThenClick,
+  type SelectOptions,
   scrollIntoCenterView,
+  selectOption,
   type TextLikeElement,
+  type ToggleOptions,
   type TypeOptions,
+  toggleControl,
   typeInto,
 } from "./animations.js";
+import { setNativeChecked, setNativeValue } from "./native_setter.js";
 
 /**
  * Generic, framework-free DOM-driving primitives.
@@ -42,6 +49,32 @@ export async function clickElement(
   await highlightThenClick(el, options);
 }
 
+/** Scroll to a button/control and click it with a visible "press" animation. */
+export async function pressButton(el: HTMLElement, options: PressOptions = {}): Promise<void> {
+  scrollIntoCenterView(el);
+  await pressThenClick(el, options);
+}
+
+/** Scroll to a `<select>`, highlight it, and pick the matching option (animated). */
+export async function selectControl(
+  el: HTMLSelectElement,
+  value: string,
+  options: SelectOptions = {},
+): Promise<void> {
+  scrollIntoCenterView(el);
+  await selectOption(el, value, options);
+}
+
+/** Scroll to a checkbox/radio, flash it, and set its checked state (animated). */
+export async function toggleCheckbox(
+  el: HTMLInputElement,
+  checked: boolean,
+  options: ToggleOptions = {},
+): Promise<void> {
+  scrollIntoCenterView(el);
+  await toggleControl(el, checked, options);
+}
+
 /**
  * Set a `<select>` or checkbox value without typing animation, dispatching the
  * ``input`` and ``change`` events frameworks listen for.
@@ -51,9 +84,9 @@ export function setControlValue(
   value: string | boolean,
 ): void {
   if (el instanceof HTMLInputElement && el.type === "checkbox") {
-    el.checked = Boolean(value);
+    setNativeChecked(el, Boolean(value));
   } else {
-    el.value = String(value);
+    setNativeValue(el, String(value));
   }
   el.dispatchEvent(new Event("input", { bubbles: true }));
   el.dispatchEvent(new Event("change", { bubbles: true }));

package/src/dom/native_setter.ts

@@ -0,0 +1,42 @@
+// 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.
+
+type ValueSetter = (this: HTMLElement, value: string) => void;
+type CheckedSetter = (this: HTMLElement, checked: boolean) => void;
+
+/** 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.
+  const setter = (Object.getOwnPropertyDescriptor(proto, prop) as PropertyDescriptor).set;
+  return setter as unknown as (this: HTMLElement, value: never) => void;
+}
+
+const setInputValue = prototypeSetter(HTMLInputElement.prototype, "value") as ValueSetter;
+const setTextareaValue = prototypeSetter(HTMLTextAreaElement.prototype, "value") as ValueSetter;
+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. */
+export function setNativeValue(
+  el: HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement,
+  value: string,
+): void {
+  if (el instanceof HTMLTextAreaElement) {
+    setTextareaValue.call(el, value);
+  } else if (el instanceof HTMLSelectElement) {
+    setSelectValue.call(el, value);
+  } else {
+    setInputValue.call(el, value);
+  }
+}
+
+/** Set ``el.checked`` via the native prototype setter. */
+export function setNativeChecked(el: HTMLInputElement, checked: boolean): void {
+  setInputChecked.call(el, checked);
+}

package/src/index.ts

@@ -1,60 +1,89 @@
 // Public surface re-exports. Per CLAUDE.md, this is the only re-export point.
-export { AgUiChat, type MessageRole, type SubmitDetail } from "./ag_ui_chat.js";
-export {
-  AgUiClient,
-  type AgUiClientConfig,
-  type AgUiClientHandlers,
-  type AgUiRunInputs,
-  type AgUiToolCall,
-  type ExecuteTool,
-  type ToolExecution,
-} from "./agui_client.js";
-export {
-  type FlashOptions,
-  focusWithFlash,
-  type HighlightClickOptions,
-  highlightThenClick,
-  scrollIntoCenterView,
-  type TextLikeElement,
-  type TypeOptions,
-  typeInto,
-} from "./animations.js";
-export { type ClientTool, ClientToolRegistry } from "./client_tool_registry.js";
-export { type ConfirmationRequest, requestConfirmation } from "./confirmation_modal.js";
+
 export {
   ELEMENT_TAG,
   MAX_TOOL_ROUNDS,
   MESSAGE_ROLE,
   SUBMIT_EVENT,
+  TOGGLE_EVENT,
   TOOL_CALL_STATUS,
+  TOOL_DISPLAY,
+  X_CONFIRM_KEY,
   X_DESTRUCTIVE_KEY,
   X_NAVIGATES_KEY,
+  X_SUMMARY_KEY,
 } from "./constants.js";
+export {
+  AgUiChat,
+  type MessageRole,
+  type SubmitDetail,
+  type ToggleDetail,
+} from "./core/ag_ui_chat.js";
+export {
+  AgUiClient,
+  type AgUiClientConfig,
+  type AgUiClientHandlers,
+  type AgUiRunInputs,
+  type AgUiToolCall,
+  type ExecuteTool,
+  type ToolExecution,
+} from "./core/agui_client.js";
 export {
   type ClientConversationStore,
   type NavigationCheckpoint,
   SessionStorageStore,
-} from "./conversation_store.js";
+} from "./core/conversation_store.js";
 export {
   type AgentFactory,
   createHttpAgent,
   type HttpAgentOptions,
-} from "./create_http_agent.js";
-export { defineAgUiChat } from "./define_ag_ui_chat.js";
+} from "./core/create_http_agent.js";
+export { defineAgUiChat } from "./core/define_ag_ui_chat.js";
+export {
+  type FlashOptions,
+  focusWithFlash,
+  type HighlightClickOptions,
+  highlightThenClick,
+  type PressOptions,
+  prefersReducedMotion,
+  pressThenClick,
+  type SelectOptions,
+  scrollIntoCenterView,
+  selectOption,
+  type TextLikeElement,
+  type ToggleOptions,
+  type TypeOptions,
+  toggleControl,
+  typeInto,
+} from "./dom/animations.js";
 export {
   clickElement,
   type FillFieldOptions,
   fillField,
+  pressButton,
+  selectControl,
   setControlValue,
-} from "./dom_driver.js";
-export { isDestructive } from "./is_destructive.js";
-export { isNavigates } from "./is_navigates.js";
-export { createPageMapContext, type PageMap } from "./page_map.js";
-export { createRouteTools, type Route, type RouteMap } from "./route_map.js";
-export { createStateHookTools, type StateHook } from "./state_hook.js";
+  toggleCheckbox,
+} from "./dom/dom_driver.js";
+export { setNativeChecked, setNativeValue } from "./dom/native_setter.js";
+export type { Skill } from "./skills/skill.js";
+export { type ClientTool, ClientToolRegistry } from "./tools/client_tool_registry.js";
+export { isDestructive } from "./tools/is_destructive.js";
+export { isNavigates } from "./tools/is_navigates.js";
+export { createPageMapContext, type PageMap } from "./tools/page_map.js";
+export {
+  createRouteTools,
+  type Route,
+  type RouteMap,
+  type RouteWithParams,
+} from "./tools/route_map.js";
+export { createStateHookTools, type StateHook } from "./tools/state_hook.js";
+export { type ConfirmationRequest, requestConfirmation } from "./ui/confirmation_card.js";
+export { renderMarkdown } from "./ui/render_markdown.js";
 export {
   type SettledStatus,
   ToolCallCard,
   type ToolCallStatus,
-} from "./tool_call_card.js";
+  type ToolDisplayMode,
+} from "./ui/tool_call_card.js";
 export { VERSION } from "./version.js";

package/src/skills/fill_template.ts

@@ -0,0 +1,32 @@
+/** Result of {@link fillTemplate}: the filled text plus any unresolved keys. */
+export interface TemplateResult {
+  /** The prompt with resolved `{placeholder}`s substituted. */
+  readonly text: string;
+  /** Placeholder names with no value available (deduped, in first-seen order). */
+  readonly missing: readonly string[];
+}
+
+const PLACEHOLDER_RE = /\{([a-zA-Z_][a-zA-Z0-9_]*)\}/g;
+
+/**
+ * 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.
+ */
+export function fillTemplate(template: string, values: Record<string, unknown>): TemplateResult {
+  const missing: string[] = [];
+  const text = template.replace(PLACEHOLDER_RE, (token, key: string) => {
+    const value = values[key];
+    if (value === undefined || value === null || value === "") {
+      if (!missing.includes(key)) {
+        missing.push(key);
+      }
+      return token;
+    }
+    return String(value);
+  });
+  return { text, missing };
+}

package/src/skills/parse_skills.ts

@@ -0,0 +1,26 @@
+import type { Skill } from "./skill.js";
+
+/** Whether ``value`` has the required string fields of a {@link Skill}. */
+function isSkill(value: unknown): value is Skill {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const record = value as Record<string, unknown>;
+  return (
+    typeof record["name"] === "string" &&
+    typeof record["title"] === "string" &&
+    typeof record["prompt"] === "string"
+  );
+}
+
+/**
+ * Parse an untrusted value (parsed JSON from `data-skills` or a skills
+ * endpoint) into a list of {@link Skill}s, dropping anything malformed. Never
+ * throws — a bad payload yields an empty list.
+ */
+export function parseSkills(value: unknown): Skill[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.filter(isSkill);
+}

package/src/skills/skill.ts

@@ -0,0 +1,23 @@
+/**
+ * A pre-defined prompt the user can launch from the chat — surfaced as a chip
+ * and/or in the `/`-command palette. One catalog feeds both surfaces; the host
+ * provides skills via the `skills` property / `data-skills` attribute / a
+ * fetched endpoint (see {@link AgUiChat}).
+ */
+export interface Skill {
+  /** Stable id; the `/token` (kebab-case) in the palette. */
+  readonly name: string;
+  /** Label shown in chips and the palette. */
+  readonly title: string;
+  /** Secondary line shown in the palette. */
+  readonly description?: string;
+  /**
+   * The prompt inserted (or sent). May contain `{placeholder}`s filled from the
+   * host's skill context before send; an unfilled placeholder blocks send.
+   */
+  readonly prompt: string;
+  /** Send immediately on pick instead of pre-filling the input (default false). */
+  readonly sendImmediately?: boolean;
+  /** Also surface this skill as a chip (default false; the palette shows all). */
+  readonly chip?: boolean;
+}

package/src/{client_tool_registry.ts → tools/client_tool_registry.ts}

@@ -24,11 +24,13 @@ export interface ClientTool {
 export class ClientToolRegistry {
   readonly #tools = new Map<string, ClientTool>();
 
-  /** Register a tool. Throws if the name is already taken. */
+  /**
+   * 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.
+   */
   register(tool: ClientTool): void {
-    if (this.#tools.has(tool.name)) {
-      throw new Error(`tool "${tool.name}" already registered`);
-    }
     this.#tools.set(tool.name, tool);
   }
 

package/src/{is_destructive.ts → tools/is_destructive.ts}

@@ -1,4 +1,4 @@
-import { X_DESTRUCTIVE_KEY } from "./constants.js";
+import { X_DESTRUCTIVE_KEY } from "../constants.js";
 
 /**
  * Whether a tool's JSON-Schema `parameters` marks it destructive.

package/src/{is_navigates.ts → tools/is_navigates.ts}

@@ -1,4 +1,4 @@
-import { X_NAVIGATES_KEY } from "./constants.js";
+import { X_NAVIGATES_KEY } from "../constants.js";
 
 /**
  * Whether a tool's JSON-Schema `parameters` marks it as navigating.