@artooi/ag-ui-web-component 0.6.0 → 0.8.0

package/src/index.ts

@@ -25,6 +25,7 @@ export {
   type AgUiClientHandlers,
   type AgUiRunInputs,
   type AgUiToolCall,
+  ConnectionLostError,
   type ExecuteTool,
   type ToolExecution,
 } from "./core/agui_client.js";
@@ -78,6 +79,11 @@ 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 {
+  createPageActionTools,
+  PAGE_ACTIONS,
+  type ResolvePageTarget,
+} from "./tools/page_action_tools.js";
 export { createPageMapContext, type PageMap } from "./tools/page_map.js";
 export { parseToolCatalog, type ToolCatalogEntry } from "./tools/parse_tool_catalog.js";
 export {
@@ -100,4 +106,5 @@ export {
   type ToolCallStatus,
   type ToolDisplayMode,
 } from "./ui/tool_call_card.js";
+export { DEFAULT_UI_STRINGS, mergeUiStrings, type UiStrings } from "./ui/ui_strings.js";
 export { VERSION } from "./version.js";

package/src/tools/page_action_tools.ts

@@ -0,0 +1,130 @@
+import { X_SUMMARY_KEY } from "../constants.js";
+import { scrollIntoCenterView } from "../dom/animations.js";
+import type { ClientTool } from "./client_tool_registry.js";
+
+/**
+ * Resolve a page-action target string to a host-page element, or `null` when it
+ * matches nothing. The default (`document.querySelector`) treats the string as a
+ * CSS selector; a host with a page map overrides it to map its own element ids,
+ * the same way host packages wrap the DOM-driver primitives with environment-
+ * aware lookups.
+ */
+export type ResolvePageTarget = (target: string) => HTMLElement | null;
+
+/** The built-in page-action tool tokens, opted in via `data-page-actions`. */
+export const PAGE_ACTIONS = {
+  SCROLL: "scroll",
+  DRAG: "drag",
+} as const;
+
+/**
+ * The opt-in page-action tools selected by `enabled` (a set of
+ * {@link PAGE_ACTIONS} tokens), bound to a {@link ResolvePageTarget}.
+ *
+ * - `scroll_to` — scroll a target (`top` / `bottom` / a resolver target) into
+ *   view. Benign; no confirmation.
+ * - `drag_and_drop` — drag one element onto another, firing the standard HTML5
+ *   drag sequence so the host page's own drop handler reacts. Not stamped
+ *   destructive: a drag rearranges transient state and the durable change
+ *   happens at the page's explicit commit. A host whose page persists *on drop*
+ *   gates it with the element's `confirmPredicate`.
+ *
+ * Both report a clean, model-readable error when a target resolves to nothing,
+ * rather than throwing an opaque crash.
+ */
+export function createPageActionTools(
+  enabled: ReadonlySet<string>,
+  resolveTarget: ResolvePageTarget,
+): ClientTool[] {
+  const tools: ClientTool[] = [];
+  if (enabled.has(PAGE_ACTIONS.SCROLL)) {
+    tools.push(scrollTool(resolveTarget));
+  }
+  if (enabled.has(PAGE_ACTIONS.DRAG)) {
+    tools.push(dragTool(resolveTarget));
+  }
+  return tools;
+}
+
+function scrollTool(resolveTarget: ResolvePageTarget): ClientTool {
+  return {
+    name: "scroll_to",
+    description:
+      "Scroll a target into view. `target` is `top`, `bottom`, or a CSS " +
+      "selector / page-map element id. Read-only: it changes nothing on the page.",
+    parameters: {
+      type: "object",
+      properties: { target: { type: "string" } },
+      required: ["target"],
+      [X_SUMMARY_KEY]: "Scroll into view",
+    },
+    handler: (args) => {
+      const target = String(args["target"] ?? "");
+      if (target === "top" || target === "bottom") {
+        const top = target === "top" ? 0 : document.body.scrollHeight;
+        window.scrollTo({ top, behavior: "smooth" });
+        return { scrolled: true, target };
+      }
+      const element = resolveTarget(target);
+      if (element === null) {
+        throw new Error(`no element matching "${target}"`);
+      }
+      scrollIntoCenterView(element);
+      return { scrolled: true, target };
+    },
+  };
+}
+
+function dragTool(resolveTarget: ResolvePageTarget): ClientTool {
+  return {
+    name: "drag_and_drop",
+    description:
+      "Drag the `from` element onto the `to` element (CSS selectors or page-map " +
+      "element ids), firing the page's native drag-and-drop. Use for reordering " +
+      "sortable lists. The page decides what the drop commits.",
+    parameters: {
+      type: "object",
+      properties: { from: { type: "string" }, to: { type: "string" } },
+      required: ["from", "to"],
+      [X_SUMMARY_KEY]: "Drag and drop",
+    },
+    handler: (args) => {
+      const fromTarget = String(args["from"] ?? "");
+      const toTarget = String(args["to"] ?? "");
+      const from = resolveTarget(fromTarget);
+      if (from === null) {
+        throw new Error(`no element matching "${fromTarget}"`);
+      }
+      const to = resolveTarget(toTarget);
+      if (to === null) {
+        throw new Error(`no element matching "${toTarget}"`);
+      }
+      dispatchDragSequence(from, to);
+      return { dragged: true, from: fromTarget, to: toTarget };
+    },
+  };
+}
+
+/**
+ * Fire the standard HTML5 drag sequence — `dragstart` on the source, then
+ * `dragenter` / `dragover` / `drop` on the target, then `dragend` on the source —
+ * sharing one {@link DataTransfer}. Dispatched as typed, bubbling events (the
+ * `dataTransfer` is attached explicitly so a drop handler reads it in every
+ * environment).
+ */
+function dispatchDragSequence(from: HTMLElement, to: HTMLElement): void {
+  const dataTransfer = new DataTransfer();
+  fire(from, "dragstart", dataTransfer);
+  fire(to, "dragenter", dataTransfer);
+  fire(to, "dragover", dataTransfer);
+  fire(to, "drop", dataTransfer);
+  fire(from, "dragend", dataTransfer);
+}
+
+function fire(target: HTMLElement, type: string, dataTransfer: DataTransfer): void {
+  const event = new Event(type, { bubbles: true, cancelable: true }) as Event & {
+    dataTransfer: DataTransfer;
+  };
+  event.dataTransfer = dataTransfer;
+  target.dispatchEvent(event);
+}

package/src/ui/attachment_tray.ts

@@ -3,6 +3,7 @@ import { ATTACHMENT_STATUS } from "../constants.js";
 import type { AttachmentRef } from "../core/attachment.js";
 import type { UploadHandler } from "../core/upload_attachment.js";
 import { formatBytes, iconFor } from "./attachment_chips.js";
+import { DEFAULT_UI_STRINGS, type UiStrings } from "./ui_strings.js";
 
 /** Status of a pending tray chip. */
 type AttachmentStatus = (typeof ATTACHMENT_STATUS)[keyof typeof ATTACHMENT_STATUS];
@@ -17,6 +18,8 @@ export interface AttachmentTrayConfig {
   readonly accept: string;
   /** Fired when the set of attachments changes (add / settle / remove). */
   readonly onChange?: () => void;
+  /** Localized strings; defaults to the English {@link DEFAULT_UI_STRINGS}. */
+  readonly strings?: UiStrings;
 }
 
 /** One pending file in the tray, from pick to ready/error. */
@@ -44,12 +47,15 @@ export class AttachmentTray {
   readonly element: HTMLDivElement;
 
   readonly #config: AttachmentTrayConfig;
+  readonly #strings: UiStrings;
   #items: TrayItem[] = [];
 
   constructor(config: AttachmentTrayConfig) {
     this.#config = config;
+    this.#strings = config.strings ?? DEFAULT_UI_STRINGS;
     this.element = document.createElement("div");
     this.element.className = "attachment-tray";
+    this.element.setAttribute("part", "attachment-tray");
     this.element.hidden = true;
   }
 
@@ -113,10 +119,10 @@ export class AttachmentTray {
   /** The size/type rejection reason for a file, or `null` when accepted. */
   #reject(file: File): string | null {
     if (this.#config.maxBytes > 0 && file.size > this.#config.maxBytes) {
-      return `Too large (max ${formatBytes(this.#config.maxBytes)})`;
+      return this.#strings.tooLarge.replace("{size}", formatBytes(this.#config.maxBytes));
     }
     if (!accepts(this.#config.accept, file)) {
-      return "File type not allowed";
+      return this.#strings.fileTypeNotAllowed;
     }
     return null;
   }
@@ -137,7 +143,7 @@ export class AttachmentTray {
       })
       .catch((error: unknown) => {
         item.status = ATTACHMENT_STATUS.ERROR;
-        item.error = error instanceof Error ? error.message : "upload failed";
+        item.error = error instanceof Error ? error.message : this.#strings.uploadFailed;
       })
       .finally(() => {
         this.#render();
@@ -194,8 +200,8 @@ export class AttachmentTray {
       const retry = document.createElement("button");
       retry.type = "button";
       retry.className = "attachment-chip-retry";
-      retry.title = "Retry";
-      retry.setAttribute("aria-label", "Retry upload");
+      retry.title = this.#strings.retry;
+      retry.setAttribute("aria-label", this.#strings.retryUpload);
       retry.textContent = "↻";
       retry.addEventListener("click", () => this.#upload(item));
       chip.appendChild(retry);
@@ -204,8 +210,8 @@ export class AttachmentTray {
     const remove = document.createElement("button");
     remove.type = "button";
     remove.className = "attachment-chip-remove";
-    remove.title = "Remove";
-    remove.setAttribute("aria-label", "Remove attachment");
+    remove.title = this.#strings.remove;
+    remove.setAttribute("aria-label", this.#strings.removeAttachment);
     remove.textContent = "✕";
     remove.addEventListener("click", () => this.#remove(item));
     chip.appendChild(remove);

package/src/ui/confirmation_card.ts

@@ -1,10 +1,12 @@
+import { DEFAULT_UI_STRINGS, type UiStrings } from "./ui_strings.js";
+
 /** What the inline confirmation card displays. */
 export interface ConfirmationRequest {
   toolName: string;
   args: Record<string, unknown>;
   /**
    * Human-readable prompt (from the tool's `x-confirm` metadata), e.g.
-   * "Activate this project?". Falls back to a generic `Run "<tool>"?`.
+   * "Activate this project?". Falls back to the generic `confirmRun` template.
    */
   message?: string;
 }
@@ -14,6 +16,7 @@ function actionButton(modifier: string, label: string): HTMLButtonElement {
   const button = document.createElement("button");
   button.type = "button";
   button.className = `confirm-btn confirm-btn--${modifier}`;
+  button.setAttribute("part", `confirm-button confirm-${modifier}`);
   button.textContent = label;
   return button;
 }
@@ -26,6 +29,8 @@ export interface ConfirmationOptions {
    * pending confirmation when the user cancels the whole run.
    */
   signal?: AbortSignal;
+  /** Localized strings; defaults to the English {@link DEFAULT_UI_STRINGS}. */
+  strings?: UiStrings;
 }
 
 /**
@@ -43,26 +48,31 @@ export function requestConfirmation(
   request: ConfirmationRequest,
   options: ConfirmationOptions = {},
 ): Promise<boolean> {
+  const strings = options.strings ?? DEFAULT_UI_STRINGS;
   return new Promise<boolean>((resolve) => {
     const card = document.createElement("div");
     card.className = "confirm";
+    card.setAttribute("part", "confirm");
     card.setAttribute("data-tool-name", request.toolName);
     card.setAttribute("role", "group");
-    card.setAttribute("aria-label", "Confirm action");
+    card.setAttribute("aria-label", strings.confirmAction);
 
     const body = document.createElement("div");
     body.className = "confirm-body";
-    body.textContent = request.message ?? `Run “${request.toolName}”?`;
+    body.setAttribute("part", "confirm-body");
+    body.textContent = request.message ?? strings.confirmRun.replace("{tool}", request.toolName);
 
     const args = document.createElement("pre");
     args.className = "confirm-args";
+    args.setAttribute("part", "confirm-args");
     args.textContent = JSON.stringify(request.args, null, 2);
 
     const actions = document.createElement("div");
     actions.className = "confirm-actions";
+    actions.setAttribute("part", "confirm-actions");
 
-    const cancel = actionButton("cancel", "Cancel");
-    const confirm = actionButton("confirm", "Confirm");
+    const cancel = actionButton("cancel", strings.cancel);
+    const confirm = actionButton("confirm", strings.confirm);
 
     let settled = false;
     const close = (accepted: boolean): void => {

package/src/ui/relative_time.ts

@@ -1,28 +1,35 @@
+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"`. Kept locale-independent on purpose so the rendered label is
- * stable across environments.
+ * `"just now"`. 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.
  */
-export function relativeTime(timestamp: number, now: number = Date.now()): string {
+export function relativeTime(
+  timestamp: number,
+  now: number = Date.now(),
+  strings: UiStrings = DEFAULT_UI_STRINGS,
+): string {
   const seconds = Math.round((now - timestamp) / 1000);
   if (seconds < 60) {
-    return "just now";
+    return strings.justNow;
   }
   const minutes = Math.round(seconds / 60);
   if (minutes < 60) {
-    return `${minutes}m ago`;
+    return strings.minutesAgo.replace("{n}", String(minutes));
   }
   const hours = Math.round(minutes / 60);
   if (hours < 24) {
-    return `${hours}h ago`;
+    return strings.hoursAgo.replace("{n}", String(hours));
   }
   const days = Math.round(hours / 24);
   if (days < 7) {
-    return `${days}d ago`;
+    return strings.daysAgo.replace("{n}", String(days));
   }
-  return `${Math.round(days / 7)}w ago`;
+  return strings.weeksAgo.replace("{n}", String(Math.round(days / 7)));
 }

package/src/ui/styles.ts

@@ -24,6 +24,17 @@ export const STYLES = `
   --ag-ui-danger: #b91c1c;
   --ag-ui-muted: #6b7280;
 
+  /* Tool-call status icon glyphs (override to re-theme) + spinner speed.
+     The pending state is the animated ring; the settled states use these. */
+  --ag-ui-tool-icon-done: "✓";
+  --ag-ui-tool-icon-error: "✕";
+  --ag-ui-tool-icon-declined: "⊘";
+  --ag-ui-tool-spin-duration: 0.7s;
+
+  /* Answer well (opt-in via data-answer-well) — boxes a whole assistant turn. */
+  --ag-ui-well-bg: transparent;
+  --ag-ui-well-border: var(--ag-ui-border);
+
   /* Surface — set --ag-ui-shadow: none for a flush, embedded panel. */
   --ag-ui-shadow: 0 12px 32px rgba(20, 20, 50, 0.18);
   --ag-ui-font: inherit;
@@ -46,6 +57,8 @@ export const STYLES = `
   --ag-ui-inset: auto 24px 24px auto;
   --ag-ui-max-width: calc(100vw - 48px);
   --ag-ui-max-height: calc(100vh - 48px);
+  /* Reading-column width for placement="page" (full-bleed, centred content). */
+  --ag-ui-content-max-width: 820px;
 
   position: var(--ag-ui-position);
   inset: var(--ag-ui-inset);
@@ -133,6 +146,99 @@ export const STYLES = `
   --ag-ui-radius: 0;
 }
 
+/* Page (PAGE-1): 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. */
+:host([placement="page"]) {
+  --ag-ui-inset: 0;
+  --ag-ui-width: 100vw;
+  --ag-ui-height: 100vh;
+  --ag-ui-max-width: 100vw;
+  --ag-ui-max-height: 100vh;
+  --ag-ui-radius: 0;
+}
+
+:host([placement="page"]) .messages {
+  padding-inline: max(var(--ag-ui-pad), calc((100% - var(--ag-ui-content-max-width)) / 2));
+}
+
+:host([placement="page"]) .input-row {
+  padding-inline: max(12px, calc((100% - var(--ag-ui-content-max-width)) / 2));
+}
+
+/* In the reading column the assistant well uses the full width; the user
+   message stays a right-aligned pill (its default align-self + max-width). */
+:host([placement="page"]) .message--assistant {
+  max-width: 100%;
+}
+
+/* Sidebar (CUST-3): a full-height docked panel that slides open/closed and
+   collapses to a slim icon rail (not the floating launcher). Docked right by
+   default; data-side="left" docks it left. Overlay by default — set
+   --ag-ui-position: static (and place this element in your own layout) for a
+   host-managed push instead. */
+:host([placement="sidebar"]) {
+  --ag-ui-inset: 0 0 0 auto;
+  --ag-ui-width: 420px;
+  --ag-ui-height: 100vh;
+  --ag-ui-max-height: 100vh;
+  --ag-ui-radius: 0;
+  --ag-ui-rail-width: 52px;
+  transition: width 0.28s ease;
+}
+
+:host([placement="sidebar"][data-side="left"]) {
+  --ag-ui-inset: 0 auto 0 0;
+}
+
+:host([placement="sidebar"]) .chat {
+  transition: transform 0.28s ease;
+}
+
+/* Collapsed sidebar: shrink the host to the rail width, hide the panel, and
+   reveal the rail. Higher specificity than the generic collapse rules, so it
+   wins regardless of source order. */
+:host([placement="sidebar"][collapsed]) {
+  width: var(--ag-ui-rail-width);
+  height: 100vh;
+  max-height: 100vh;
+  bottom: 0;
+}
+
+:host([placement="sidebar"][collapsed]) .chat {
+  display: none;
+}
+
+/* The rail is a sibling of the panel (so it survives the panel being hidden);
+   shown only for a collapsed sidebar. */
+.rail {
+  display: none;
+  border: none;
+  font: inherit;
+}
+
+:host([placement="sidebar"][collapsed]) .rail {
+  display: flex;
+  position: absolute;
+  inset: 0;
+  align-items: flex-start;
+  justify-content: center;
+  padding-top: 16px;
+  border: 1px solid var(--ag-ui-border);
+  background: var(--ag-ui-header-bg);
+  color: var(--ag-ui-header-fg);
+  cursor: pointer;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :host([placement="sidebar"]),
+  :host([placement="sidebar"]) .chat {
+    transition: none;
+  }
+}
+
 /* Embedded: drop the floating chrome and the high z-index stacking context so
    the widget lives in the host's own layout (fixes overlay/z-index clashes). */
 :host([placement="embedded"]) {
@@ -170,12 +276,33 @@ export const STYLES = `
 }
 
 .header-title {
+  flex: 1;
+  min-width: 0;
   font-weight: 600;
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
 }
 
+/* Header / launcher icon holder (CUST-2): a slot, with a data-icon-url <img>
+   fallback, sized via --ag-ui-icon-size. */
+.icon-holder {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: none;
+  width: var(--ag-ui-icon-size, 22px);
+  height: var(--ag-ui-icon-size, 22px);
+  line-height: 1;
+}
+
+.icon-img {
+  width: 100%;
+  height: 100%;
+  object-fit: contain;
+  border-radius: var(--ag-ui-icon-radius, 4px);
+}
+
 .header-controls {
   display: flex;
   gap: 2px;
@@ -231,6 +358,39 @@ export const STYLES = `
   gap: var(--ag-ui-space);
 }
 
+/* Empty-state region (CUST-1 slot): centred while it's the only thing in the
+   list, hidden as soon as a message, card, or pending indicator renders. */
+.empty {
+  margin: auto;
+  text-align: center;
+  color: var(--ag-ui-muted);
+}
+
+.empty[hidden] {
+  display: none;
+}
+
+/* ── Answer group / well (WELL-1) ─────────────────────────────────────────
+   One .answer per assistant turn wraps the streamed text, its tool cards,
+   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. */
+.answer {
+  display: flex;
+  flex-direction: column;
+  gap: var(--ag-ui-space);
+  align-self: stretch;
+  min-width: 0;
+}
+
+:host([data-answer-well]) .answer {
+  padding: var(--ag-ui-pad);
+  background: var(--ag-ui-well-bg);
+  border: 1px solid var(--ag-ui-well-border);
+  border-radius: var(--ag-ui-radius);
+}
+
 .message {
   max-width: 80%;
   padding: var(--ag-ui-msg-pad);
@@ -403,10 +563,71 @@ export const STYLES = `
 }
 
 .tool-call-name {
+  flex: 1;
+  min-width: 0;
   font-weight: 600;
   word-break: break-word;
 }
 
+/* Leading status icon (CARD-1). Empty in the DOM — the glyph/spinner is drawn
+   here from the card's data-status, so it stays themeable. */
+.tool-call-icon {
+  flex: none;
+  box-sizing: border-box;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 14px;
+  height: 14px;
+  font-size: 12px;
+  line-height: 1;
+}
+
+/* Pending: a real spinning ring. Speed is tunable; reduced motion stops it. */
+.tool-call[data-status="pending"] .tool-call-icon {
+  border: 2px solid var(--ag-ui-muted);
+  border-top-color: transparent;
+  border-radius: 50%;
+  animation: ag-ui-tool-spin var(--ag-ui-tool-spin-duration) linear infinite;
+}
+
+@keyframes ag-ui-tool-spin {
+  to { transform: rotate(360deg); }
+}
+
+/* Settled: a themeable glyph coloured by outcome. */
+.tool-call[data-status="done"] .tool-call-icon::before {
+  content: var(--ag-ui-tool-icon-done);
+  color: var(--ag-ui-success);
+}
+
+.tool-call[data-status="error"] .tool-call-icon::before {
+  content: var(--ag-ui-tool-icon-error);
+  color: var(--ag-ui-danger);
+}
+
+.tool-call[data-status="declined"] .tool-call-icon::before {
+  content: var(--ag-ui-tool-icon-declined);
+  color: var(--ag-ui-muted);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .tool-call[data-status="pending"] .tool-call-icon {
+    animation: none;
+  }
+}
+
+/* Inline display mode (CARD-1): the lightest card — drop the box chrome so the
+   status row reads as one line of the answer; the result toggle still expands
+   below it. */
+.tool-call[data-display="inline"] {
+  max-width: 100%;
+  background: transparent;
+  border: none;
+  padding: 2px 0;
+  gap: 2px;
+}
+
 .tool-call-status {
   flex: none;
   padding: 1px 8px;