@artooi/ag-ui-web-component 0.16.0 → 0.18.0

package/dist/index.js

@@ -3,6 +3,7 @@ var ELEMENT_TAG = "ag-ui-chat";
 var SUBMIT_EVENT = "ag-ui-submit";
 var TOGGLE_EVENT = "ag-ui-toggle";
 var STATE_EVENT = "ag-ui-state";
+var ATTACHMENT_EVENT = "ag-ui-attachments";
 var MESSAGE_ROLE = {
   USER: "user",
   ASSISTANT: "assistant"
@@ -449,6 +450,9 @@ var DEFAULT_UI_STRINGS = {
   collapse: "Collapse",
   expand: "Expand",
   toggleTheme: "Toggle theme",
+  copyCode: "Copy",
+  copied: "Copied",
+  copyFailed: "Copy failed",
   checkpoints: "Continue a run",
   noCheckpoints: "Nothing to continue yet.",
   resumeRun: "Resume",
@@ -466,6 +470,7 @@ var DEFAULT_UI_STRINGS = {
   usingSkill: "Using skill {name}",
   runInterrupted: "The previous response didn\u2019t finish \u2014 the page changed before it arrived.",
   pageMoved: "The page changed since you last looked at it. Call read_page to see the current page, then retry.",
+  attachmentsStillUploading: "{n} file still uploading \u2014 it was not sent with this message and is still attached.",
   skillNeeds: "\u201C{title}\u201D needs: {fields}",
   message: "Message",
   inputPlaceholder: "Ask anything\u2026",
@@ -529,12 +534,12 @@ function mergeUiStrings(overrides) {
 
 // src/ui/approval_card.ts
 function actionButton(modifier, label) {
-  const button = document.createElement("button");
-  button.type = "button";
-  button.className = `approval-btn approval-btn--${modifier}`;
-  button.setAttribute("part", `approval-button approval-${modifier}`);
-  button.textContent = label;
-  return button;
+  const button2 = document.createElement("button");
+  button2.type = "button";
+  button2.className = `approval-btn approval-btn--${modifier}`;
+  button2.setAttribute("part", `approval-button approval-${modifier}`);
+  button2.textContent = label;
+  return button2;
 }
 function requestApproval(host, request, options = {}) {
   const strings = options.strings ?? DEFAULT_UI_STRINGS;
@@ -581,6 +586,55 @@ function requestApproval(host, request, options = {}) {
   });
 }
 
+// src/ui/attach_copy_buttons.ts
+var CONFIRM_MS = 1500;
+function attachCopyButtons(root, strings) {
+  for (const pre of Array.from(root.querySelectorAll("pre"))) {
+    const code = pre.querySelector("code");
+    if (code === null || pre.querySelector(".code-copy") !== null) {
+      continue;
+    }
+    pre.classList.add("has-copy");
+    pre.append(button(code, strings));
+  }
+}
+function button(code, strings) {
+  const text2 = code.textContent;
+  const copy = document.createElement("button");
+  copy.type = "button";
+  copy.className = "code-copy";
+  copy.setAttribute("part", "code-copy");
+  copy.textContent = strings.copyCode;
+  copy.title = strings.copyCode;
+  copy.setAttribute("aria-label", strings.copyCode);
+  copy.addEventListener("click", () => {
+    void writeText(text2).then((ok) => {
+      confirm(copy, ok ? strings.copied : strings.copyFailed, strings);
+    });
+  });
+  return copy;
+}
+async function writeText(text2) {
+  const clipboard = navigator.clipboard;
+  if (clipboard === void 0) {
+    return false;
+  }
+  try {
+    await clipboard.writeText(text2);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function confirm(copy, message, strings) {
+  copy.textContent = message;
+  copy.dataset["state"] = message === strings.copied ? "copied" : "failed";
+  setTimeout(() => {
+    copy.textContent = strings.copyCode;
+    delete copy.dataset["state"];
+  }, CONFIRM_MS);
+}
+
 // src/ui/attachment_chips.ts
 function renderAttachmentChips(refs) {
   const list = document.createElement("div");
@@ -693,6 +747,10 @@ var AttachmentTray = class {
   hasPending() {
     return this.#items.some((item) => item.status === ATTACHMENT_STATUS.UPLOADING);
   }
+  /** How many chips are still uploading — the count a send-time notice names. */
+  pendingCount() {
+    return this.#items.filter((item) => item.status === ATTACHMENT_STATUS.UPLOADING).length;
+  }
   /** Whether the tray holds no chips. */
   isEmpty() {
     return this.#items.length === 0;
@@ -879,6 +937,8 @@ var CheckpointMenu = class {
   #onPick;
   #list;
   #heading;
+  /** What had focus before the panel opened, restored on close. */
+  #lastFocused = null;
   #strings;
   #runs = [];
   constructor(onPick, strings = DEFAULT_UI_STRINGS) {
@@ -889,24 +949,21 @@ var CheckpointMenu = class {
     this.element.setAttribute("part", "checkpoints");
     this.element.setAttribute("role", "dialog");
     this.element.setAttribute("aria-label", strings.checkpoints);
+    this.element.tabIndex = -1;
     this.element.hidden = true;
     const header = document.createElement("div");
     header.className = "checkpoints-header";
     header.setAttribute("part", "checkpoints-header");
     this.#heading = document.createElement("span");
     this.#heading.className = "checkpoints-title";
+    this.#heading.setAttribute("part", "checkpoints-title");
     this.#heading.textContent = strings.checkpoints;
     header.append(this.#heading);
     this.#list = document.createElement("div");
     this.#list.className = "checkpoints-list";
     this.#list.setAttribute("part", "checkpoints-list");
     this.element.append(header, this.#list);
-    this.element.addEventListener("keydown", (event) => {
-      if (event.key === "Escape") {
-        event.stopPropagation();
-        this.close();
-      }
-    });
+    this.element.addEventListener("keydown", (event) => this.#onKeydown(event));
   }
   /** Replace the rows. The host passes only `continuable` runs. */
   setRuns(runs) {
@@ -921,10 +978,52 @@ var CheckpointMenu = class {
     this.#render();
   }
   open() {
+    if (this.open_) {
+      return;
+    }
+    this.#lastFocused = this.#activeElement();
     this.element.hidden = false;
+    (this.#focusables()[0] ?? this.element).focus();
   }
   close() {
+    if (!this.open_) {
+      return;
+    }
     this.element.hidden = true;
+    this.#lastFocused?.focus();
+    this.#lastFocused = null;
+  }
+  /** The focused element within this panel's root (shadow-aware). */
+  #activeElement() {
+    return this.element.getRootNode().activeElement;
+  }
+  /** The panel's tabbable controls, in document order. */
+  #focusables() {
+    return Array.from(this.element.querySelectorAll("button, [tabindex]")).filter(
+      (el) => !el.hidden
+    );
+  }
+  /** Escape closes; Tab is trapped so focus cannot wander behind the dialog. */
+  #onKeydown(event) {
+    if (event.key === "Escape") {
+      event.stopPropagation();
+      this.close();
+      return;
+    }
+    if (event.key !== "Tab") {
+      return;
+    }
+    const focusables = this.#focusables();
+    const first = focusables[0];
+    const last = focusables[focusables.length - 1];
+    const active = this.#activeElement();
+    if (event.shiftKey && active === first) {
+      event.preventDefault();
+      last?.focus();
+    } else if (!event.shiftKey && active === last) {
+      event.preventDefault();
+      first?.focus();
+    }
   }
   get open_() {
     return !this.element.hidden;
@@ -949,6 +1048,7 @@ var CheckpointMenu = class {
     row.setAttribute("part", "checkpoint-row");
     const label = document.createElement("span");
     label.className = "checkpoint-label";
+    label.setAttribute("part", "checkpoint-label");
     label.textContent = run.started_at === null ? run.run_id : relativeTime(Date.parse(run.started_at), Date.now(), this.#strings);
     label.title = run.run_id;
     row.append(label);
@@ -967,27 +1067,27 @@ var CheckpointMenu = class {
     return row;
   }
   #action(runId, verb, label) {
-    const button = document.createElement("button");
-    button.type = "button";
-    button.className = `checkpoint-action checkpoint-${verb}`;
-    button.setAttribute("part", `checkpoint-action checkpoint-${verb}`);
-    button.textContent = label;
-    button.addEventListener("click", () => {
+    const button2 = document.createElement("button");
+    button2.type = "button";
+    button2.className = `checkpoint-action checkpoint-${verb}`;
+    button2.setAttribute("part", `checkpoint-action checkpoint-${verb}`);
+    button2.textContent = label;
+    button2.addEventListener("click", () => {
       this.close();
       this.#onPick(runId, verb);
     });
-    return button;
+    return button2;
   }
 };
 
 // src/ui/confirmation_card.ts
 function actionButton2(modifier, label) {
-  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;
+  const button2 = document.createElement("button");
+  button2.type = "button";
+  button2.className = `confirm-btn confirm-btn--${modifier}`;
+  button2.setAttribute("part", `confirm-button confirm-${modifier}`);
+  button2.textContent = label;
+  return button2;
 }
 function requestConfirmation(host, request, options = {}) {
   const strings = options.strings ?? DEFAULT_UI_STRINGS;
@@ -1010,7 +1110,7 @@ function requestConfirmation(host, request, options = {}) {
     actions.className = "confirm-actions";
     actions.setAttribute("part", "confirm-actions");
     const cancel = actionButton2("cancel", strings.cancel);
-    const confirm = actionButton2("confirm", strings.confirm);
+    const confirm2 = actionButton2("confirm", strings.confirm);
     let settled = false;
     const close = (accepted) => {
       if (settled) {
@@ -1018,21 +1118,21 @@ function requestConfirmation(host, request, options = {}) {
       }
       settled = true;
       cancel.disabled = true;
-      confirm.disabled = true;
+      confirm2.disabled = true;
       card.setAttribute("data-resolved", accepted ? "confirmed" : "declined");
       resolve(accepted);
     };
     cancel.addEventListener("click", () => close(false));
-    confirm.addEventListener("click", () => close(true));
+    confirm2.addEventListener("click", () => close(true));
     options.signal?.addEventListener("abort", () => close(false), { once: true });
-    actions.append(cancel, confirm);
+    actions.append(cancel, confirm2);
     card.append(body, args, actions);
     host.appendChild(card);
     if (options.signal?.aborted === true) {
       close(false);
       return;
     }
-    confirm.focus();
+    confirm2.focus();
   });
 }
 
@@ -4185,13 +4285,13 @@ var SkillsMenu = class {
     const chipSkills = this.#chipsEnabled ? this.#skills.filter((skill) => skill.chip === true) : [];
     this.chips.hidden = chipSkills.length === 0;
     for (const skill of chipSkills) {
-      const button = document.createElement("button");
-      button.type = "button";
-      button.className = "skill-chip";
-      button.setAttribute("part", "skill-chip");
-      button.textContent = skill.title;
-      button.addEventListener("click", () => this.#pick(skill));
-      this.chips.appendChild(button);
+      const button2 = document.createElement("button");
+      button2.type = "button";
+      button2.className = "skill-chip";
+      button2.setAttribute("part", "skill-chip");
+      button2.textContent = skill.title;
+      button2.addEventListener("click", () => this.#pick(skill));
+      this.chips.appendChild(button2);
     }
   }
   #renderPalette() {
@@ -4231,6 +4331,7 @@ var STYLES = `
   --ag-ui-user-bg: #4f46e5;
   --ag-ui-user-fg: #ffffff;
   --ag-ui-assistant-bg: #f1f1f6;
+  --ag-ui-hover: #e7e7ee;
   --ag-ui-input-bg: var(--ag-ui-bg);
   --ag-ui-tool-bg: var(--ag-ui-assistant-bg);
   --ag-ui-tool-fg: var(--ag-ui-accent);
@@ -4300,6 +4401,7 @@ var STYLES = `
   --ag-ui-bg: #15151f;
   --ag-ui-fg: #e8e8f2;
   --ag-ui-assistant-bg: #25253a;
+  --ag-ui-hover: #303049;
   --ag-ui-header-bg: #1f1f30;
   --ag-ui-header-fg: #e8e8f2;
   --ag-ui-border: #33334a;
@@ -4312,6 +4414,7 @@ var STYLES = `
     --ag-ui-bg: #15151f;
     --ag-ui-fg: #e8e8f2;
     --ag-ui-assistant-bg: #25253a;
+    --ag-ui-hover: #303049;
     --ag-ui-header-bg: #1f1f30;
     --ag-ui-header-fg: #e8e8f2;
     --ag-ui-border: #33334a;
@@ -4327,6 +4430,7 @@ var STYLES = `
   --ag-ui-accent: #3fb950;
   --ag-ui-user-bg: #238636;
   --ag-ui-assistant-bg: #161b22;
+  --ag-ui-hover: #21262d;
   --ag-ui-header-bg: #010409;
   --ag-ui-header-fg: #c9d1d9;
   --ag-ui-border: #30363d;
@@ -4728,12 +4832,86 @@ var STYLES = `
   padding: 0;
 }
 
+/* The copy button sits inside the block, so it scrolls with wide code rather
+   than floating over the bubble. Positioning is on the pre; the button only
+   appears once one has been attached. */
+.message--assistant pre.has-copy {
+  position: relative;
+}
+
+.code-copy {
+  position: absolute;
+  top: 4px;
+  right: 4px;
+  padding: 2px 8px;
+  font: inherit;
+  font-size: 0.75em;
+  line-height: 1.6;
+  color: var(--ag-ui-muted);
+  background: var(--ag-ui-surface);
+  border: 1px solid var(--ag-ui-border);
+  border-radius: 4px;
+  cursor: pointer;
+  opacity: 0;
+  transition: opacity 0.12s ease;
+}
+
+/* Revealed on hover or keyboard focus. Focus matters as much as hover here:
+   hidden-until-hover is invisible to a keyboard user otherwise. */
+.message--assistant pre.has-copy:hover .code-copy,
+.code-copy:focus-visible {
+  opacity: 1;
+}
+
+.code-copy:hover {
+  color: var(--ag-ui-text);
+  background: var(--ag-ui-hover);
+}
+
+.code-copy[data-state="copied"] {
+  opacity: 1;
+  color: var(--ag-ui-text);
+}
+
+.code-copy[data-state="failed"] {
+  opacity: 1;
+  color: var(--ag-ui-danger, var(--ag-ui-text));
+}
+
 .message--assistant blockquote {
   padding-left: 10px;
   border-left: 3px solid var(--ag-ui-border);
   color: var(--ag-ui-muted);
 }
 
+/* Markdown tables. table/thead/tbody/tr/th/td are all in
+   the sanitizer's ALLOWED_TAGS, so an agent emitting one renders it \u2014 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. */
+.message--assistant table {
+  display: block;
+  width: fit-content;
+  max-width: 100%;
+  overflow-x: auto;
+  border-collapse: collapse;
+  font-size: 0.95em;
+}
+
+.message--assistant th,
+.message--assistant td {
+  padding: 6px 10px;
+  border: 1px solid var(--ag-ui-border);
+  text-align: left;
+  vertical-align: top;
+}
+
+.message--assistant th {
+  background: var(--ag-ui-hover);
+  font-weight: 600;
+}
+
 .pending {
   align-self: flex-start;
   display: inline-flex;
@@ -5484,9 +5662,9 @@ var STYLES = `
   flex-direction: column;
   gap: 0.25rem;
   padding: 0.5rem;
-  border: 1px solid var(--agui-border, #d7d7dc);
+  border: 1px solid var(--ag-ui-border);
   border-radius: 0.5rem;
-  background: var(--agui-surface, #fff);
+  background: var(--ag-ui-assistant-bg);
   box-shadow: 0 6px 24px rgb(0 0 0 / 12%);
   max-height: 60%;
   overflow-y: auto;
@@ -5517,7 +5695,7 @@ var STYLES = `
 }
 
 .checkpoint-row:hover {
-  background: var(--agui-hover, #f3f3f5);
+  background: var(--ag-ui-hover);
 }
 
 .checkpoint-label {
@@ -5532,7 +5710,7 @@ var STYLES = `
   font-size: 0.6875rem;
   padding: 0 0.375rem;
   border-radius: 999px;
-  background: var(--agui-hover, #f3f3f5);
+  background: var(--ag-ui-hover);
   opacity: 0.8;
 }
 
@@ -5541,14 +5719,14 @@ var STYLES = `
   font-size: 0.75rem;
   cursor: pointer;
   padding: 0.125rem 0.5rem;
-  border: 1px solid var(--agui-border, #d7d7dc);
+  border: 1px solid var(--ag-ui-border);
   border-radius: 0.375rem;
   background: transparent;
   color: inherit;
 }
 
 .checkpoint-action:hover {
-  background: var(--agui-hover, #f3f3f5);
+  background: var(--ag-ui-hover);
 }
 
 .drawer-backdrop {
@@ -6013,9 +6191,9 @@ var ThreadDrawer = class {
   }
   /** Swap a row for an inline "Delete? [Delete] [Cancel]" confirm. */
   #confirmDelete(row, meta) {
-    const confirm = document.createElement("div");
-    confirm.className = "drawer-confirm";
-    confirm.setAttribute("part", "drawer-confirm");
+    const confirm2 = document.createElement("div");
+    confirm2.className = "drawer-confirm";
+    confirm2.setAttribute("part", "drawer-confirm");
     const label = document.createElement("span");
     label.className = "drawer-confirm-label";
     label.setAttribute("part", "drawer-confirm-label");
@@ -6032,8 +6210,8 @@ var ThreadDrawer = class {
     no.setAttribute("part", "drawer-confirm-no");
     no.textContent = this.#strings.cancel;
     no.addEventListener("click", () => this.#renderList());
-    confirm.append(label, yes, no);
-    row.replaceChildren(confirm);
+    confirm2.append(label, yes, no);
+    row.replaceChildren(confirm2);
   }
 };
 
@@ -6999,6 +7177,21 @@ function errorMessage2(xhr) {
 }
 
 // src/core/ag_ui_chat.ts
+var CONNECT_TIME_ATTRIBUTES = [
+  "data-attachments-url",
+  "data-attachment-accept",
+  "data-attachment-max-bytes",
+  "data-transcribe-url",
+  "data-threads-url",
+  "data-tools-url",
+  "data-skills-url",
+  "data-skills",
+  "data-prompt-chips",
+  "data-slash-commands",
+  "data-theme-toggle",
+  "data-strings",
+  "data-icon-url"
+];
 var COLLAPSED_KEY = "ag-ui-chat:collapsed";
 var THEME_KEY = "ag-ui-chat:theme";
 var AgUiChat = class extends HTMLElement {
@@ -7198,6 +7391,8 @@ var AgUiChat = class extends HTMLElement {
   #voiceSlot;
   /** Voice-input control; created on connect when transcription is available. */
   #voice = null;
+  /** Whether the element is currently in the DOM; gates the connect-time warning. */
+  #connected = false;
   /** Refs attached to the message currently being sent (the context manifest). */
   #runAttachments = [];
   #client = null;
@@ -7344,12 +7539,21 @@ var AgUiChat = class extends HTMLElement {
     const index = this.#runs();
     this.#checkpoints.setRuns(index === null ? [] : await index.continuable());
   }
-  /** Attributes whose late changes must reflect in already-rendered chrome. */
+  /** Attributes the element reacts to after it has been connected. */
   static get observedAttributes() {
-    return ["title-text"];
+    return ["title-text", ...CONNECT_TIME_ATTRIBUTES];
   }
-  attributeChangedCallback(_name, _previous, value) {
-    this.#title.textContent = value ?? this.#strings.title;
+  attributeChangedCallback(name, previous, value) {
+    if (name === "title-text") {
+      this.#title.textContent = value ?? this.#strings.title;
+      return;
+    }
+    if (previous === value || !this.#connected) {
+      return;
+    }
+    console.warn(
+      `<ag-ui-chat>: "${name}" was changed after the element connected, and is read only while connecting \u2014 this assignment has no effect. Set it before the element enters the DOM (in the markup, or on the element before appending it); frameworks that patch attributes after mount should bind it at creation. To apply a new value now, remove and re-insert the element.`
+    );
   }
   /** Declare a frontend tool the agent may call. */
   registerTool(tool) {
@@ -7565,6 +7769,7 @@ var AgUiChat = class extends HTMLElement {
     this.#wireVoice();
     this.#threadId = this.conversationStore.threadId();
     void this.#rehydrate();
+    this.#connected = true;
   }
   /**
    * Tear down live resources when the element leaves the DOM (a removed node, a
@@ -7575,10 +7780,27 @@ var AgUiChat = class extends HTMLElement {
    * `MediaRecorder`.
    */
   disconnectedCallback() {
+    this.#connected = false;
     this.#cancelRun();
     this.#attachTray?.dispose();
     this.#voice?.dispose();
   }
+  /**
+   * Read an opt-in flag attribute the way HTML reads a boolean attribute.
+   *
+   * Present means on — bare (`data-prompt-chips`), empty
+   * (`data-prompt-chips=""`) or any value except the literal `"false"`. These
+   * were compared against the string `"true"`, so writing the attribute bare —
+   * the spelling every native boolean attribute uses, and the one a reader
+   * reaches for first — silently *disabled* the feature it names, with nothing
+   * to indicate why the chips never appeared.
+   *
+   * `="false"` still turns it off, so an explicit opt-out keeps working.
+   */
+  #flag(name) {
+    const value = this.getAttribute(name);
+    return value !== null && value !== "false";
+  }
   /** Parse the inline `data-strings` JSON overrides (empty when absent/malformed). */
   #readStringOverrides() {
     const raw = this.getAttribute("data-strings");
@@ -7608,12 +7830,18 @@ var AgUiChat = class extends HTMLElement {
       return;
     }
     const accept = this.getAttribute("data-attachment-accept") ?? "";
-    this.#attachTray = new AttachmentTray({
+    const tray = new AttachmentTray({
       upload,
       maxBytes: this.#attachmentMaxBytes(),
       accept,
-      strings: this.#strings
+      strings: this.#strings,
+      // The tray's change hook, surfaced to the host as an event. A host
+      // driving its own composer could otherwise not tell a settled upload from
+      // one still in flight, which is the state sendMessage() has to be called
+      // with knowledge of.
+      onChange: () => this.#dispatchAttachments(tray)
     });
+    this.#attachTray = tray;
     this.#attachSlot.appendChild(this.#attachTray.element);
     this.#fileInput.accept = accept;
     this.#attachButton.hidden = false;
@@ -7753,8 +7981,8 @@ Use the read_attachment tool with an id to read a file's contents.`
   }
   /** Wire the skill surfaces: opt-in flags, embedded catalog, optional fetch. */
   #initSkills() {
-    this.#skillsMenu.enableChips(this.getAttribute("data-prompt-chips") === "true");
-    this.#skillsMenu.enableSlash(this.getAttribute("data-slash-commands") === "true");
+    this.#skillsMenu.enableChips(this.#flag("data-prompt-chips"));
+    this.#skillsMenu.enableSlash(this.#flag("data-slash-commands"));
     this.#embedSkills = this.#readEmbeddedSkills();
     this.#recomputeSkills();
     void this.#fetchSkills();
@@ -8095,6 +8323,7 @@ Use the read_attachment tool with an id to read a file's contents.`
     bubble.setAttribute("part", `message message-${role}`);
     if (role === MESSAGE_ROLE.ASSISTANT) {
       bubble.innerHTML = renderMarkdown(content, { allowImages: this.allowImages });
+      attachCopyButtons(bubble, this.#strings);
       this.#ensureGroup().appendChild(bubble);
     } else {
       this.#currentGroup = null;
@@ -8251,14 +8480,14 @@ Use the read_attachment tool with an id to read a file's contents.`
   }
   /** Build a header control button (icon glyph + localized title/aria). */
   #headerButton(modifier, label, glyph) {
-    const button = document.createElement("button");
-    button.type = "button";
-    button.className = `header-btn header-btn--${modifier}`;
-    button.setAttribute("part", `header-button ${modifier}-button`);
-    button.title = label;
-    button.setAttribute("aria-label", label);
-    button.textContent = glyph;
-    return button;
+    const button2 = document.createElement("button");
+    button2.type = "button";
+    button2.className = `header-btn header-btn--${modifier}`;
+    button2.setAttribute("part", `header-button ${modifier}-button`);
+    button2.title = label;
+    button2.setAttribute("aria-label", label);
+    button2.textContent = glyph;
+    return button2;
   }
   /**
    * An icon holder wrapping a `<slot>` so a host can project custom markup; with
@@ -8338,12 +8567,46 @@ Use the read_attachment tool with an id to read a file's contents.`
     if (content === "" && attachments.length === 0) {
       return;
     }
+    this.#input.value = "";
+    if (this.#attachTray?.hasPending() === true) {
+      this.#appendNotice(
+        "\u{1F4CE}",
+        this.#strings.attachmentsStillUploading.replace(
+          "{n}",
+          String(this.#attachTray.pendingCount())
+        ),
+        "attachment-pending"
+      );
+    }
+    this.#attachTray?.clearReady();
+    await this.sendMessage(content, attachments);
+  }
+  /**
+   * Send a message as if the user had typed it — renders the user bubble,
+   * dispatches {@link SUBMIT_EVENT}, and starts the run.
+   *
+   * The programmatic half of the composer, for a host driving its own input
+   * (a "Ask about this order" button, a command palette, a custom composer
+   * replacing the built-in one). Everything the built-in Send does happens
+   * here; Send itself now reads the composer, clears it, and calls this.
+   *
+   * `attachments` are durable {@link AttachmentRef}s — the shape
+   * {@link attachFile}'s upload resolves to, and the shape
+   * {@link ATTACHMENT_EVENT} reports. Pass them to attach files to the message.
+   *
+   * No-ops while a run is in flight (a second concurrent run would orphan the
+   * first) and for an entirely empty message. Unlike the built-in Send, this
+   * does **not** consult the tray: what you pass is what is sent, so a host
+   * composer stays in charge of its own state.
+   */
+  async sendMessage(content, attachments = []) {
+    if (this.#running || content === "" && attachments.length === 0) {
+      return;
+    }
     const bubble = this.appendMessage(MESSAGE_ROLE.USER, content);
     if (attachments.length > 0) {
       bubble.appendChild(renderAttachmentChips(attachments));
     }
-    this.#input.value = "";
-    this.#attachTray?.clearReady();
     this.#runAttachments = attachments;
     this.dispatchEvent(
       new CustomEvent(SUBMIT_EVENT, {
@@ -8354,6 +8617,35 @@ Use the read_attachment tool with an id to read a file's contents.`
     );
     await this.#client_send(content, attachments);
   }
+  /**
+   * Queue a file for upload into the attachment tray, exactly as the file
+   * picker and drag-and-drop do — validation, progress chip, and all.
+   *
+   * Returns `false` when uploads are not configured (no `data-attachments-url`
+   * and no {@link uploadHandler}), which is the only way for a host to tell;
+   * the tray does not exist to report anything in that case.
+   *
+   * Uploading is asynchronous: watch {@link ATTACHMENT_EVENT} for the resulting
+   * {@link AttachmentRef}, and pass it to {@link sendMessage} once `pending`
+   * reaches zero.
+   */
+  attachFile(file) {
+    if (this.#attachTray === null) {
+      return false;
+    }
+    this.#attachTray.add(file);
+    return true;
+  }
+  /** Tell the host what the tray now holds — see {@link ATTACHMENT_EVENT}. */
+  #dispatchAttachments(tray) {
+    this.dispatchEvent(
+      new CustomEvent(ATTACHMENT_EVENT, {
+        detail: { attachments: tray.readyRefs(), pending: tray.pendingCount() },
+        bubbles: true,
+        composed: true
+      })
+    );
+  }
   async #client_send(content, attachments) {
     if (this.endpoint === "") {
       return;
@@ -8539,6 +8831,7 @@ Use the read_attachment tool with an id to read a file's contents.`
         if (this.#streamDeltas <= 1) {
           this.#revealWords(bubble);
         }
+        attachCopyButtons(bubble, this.#strings);
         this.#streamingBubble = null;
       },
       onToolCall: (call) => {
@@ -8766,8 +9059,9 @@ function setControlValue(el, value) {
 }
 
 // src/version.ts
-var VERSION = "0.16.0";
+var VERSION = "0.18.0";
 export {
+  ATTACHMENT_EVENT,
   AgUiChat,
   AgUiClient,
   COMPACTION_ACTIVITY_TYPE,