@artooi/ag-ui-web-component 0.38.0 → 0.40.0

package/src/ui/transcript/answer_actions.ts

@@ -0,0 +1,139 @@
+import { FEEDBACK_EVENT, ICON_RETRY, MESSAGE_ACTIONS } from "../../constants.js";
+import type { FeedbackDetail } from "../../core/events/feedback_detail.js";
+import { commaTokens } from "../../core/utils.js";
+import { copyPayload } from "../excerpts/copy_payload.js";
+import type { UiStrings } from "../ui_strings.js";
+import { attachMessageActions, messageActionBar, messageActionButton } from "./message_actions.js";
+
+/** What the answer actions need from the element that owns them. */
+export interface AnswerActionsHost {
+  /** The custom element: its `data-message-actions`, and where feedback is dispatched. */
+  readonly element: HTMLElement;
+  /** The resolved string table. */
+  readonly strings: () => UiStrings;
+  /** Retry the last turn, as the element's public `retryLastTurn` does. */
+  readonly retry: () => void;
+}
+
+/**
+ * The action row under a finished answer -- copy, retry, feedback -- and the
+ * one row currently holding Retry.
+ *
+ * Owned one-to-one by an `<ag-ui-chat>`, and holding no state outside the
+ * instance.
+ */
+export class AnswerActions {
+  readonly #host: AnswerActionsHost;
+  /**
+   * The one action row currently carrying Retry, if any.
+   *
+   * Retry belongs to the **last** turn only: re-running an older one is
+   * branching, and for a page-driving agent editing a past turn is not neutral
+   * -- those turns clicked buttons, and re-running turn 3 does not un-save what
+   * turn 5 saved. Holding a single owner is what keeps exactly one offer on
+   * screen without per-bubble bookkeeping.
+   */
+  #retryOwner: HTMLElement | null = null;
+
+  constructor(host: AnswerActionsHost) {
+    this.#host = host;
+  }
+
+  /** Forget the row holding Retry, with the transcript it was in. */
+  forget(): void {
+    this.#retryOwner = null;
+  }
+
+  /**
+   * Give a finished assistant bubble its action row, and hand it Retry.
+   *
+   * Every finished bubble gets copy and feedback -- both are safe on a message
+   * of any age. Retry moves to the newest, because it is the only one where
+   * re-running answers the same question rather than rewriting history.
+   *
+   * `data-message-actions` subtracts from that. The row is built only when
+   * something survives to go in it: an empty row still takes its margin, still
+   * answers to the `message-actions` part, and still reads to a screen reader
+   * as a group of actions with none in it.
+   */
+  attach(bubble: HTMLDivElement, options: { rateable?: boolean } = {}): void {
+    const enabled = this.#enabled();
+    const copyable = enabled.has(MESSAGE_ACTIONS.COPY);
+    // A failed run is copyable -- error text is what people paste into a bug
+    // report -- but not rateable: a rating is a statement about an *answer*,
+    // and mixing "the connection dropped" into that signal makes the host's
+    // feedback data say less than it did before.
+    const rateable = options.rateable !== false && enabled.has(MESSAGE_ACTIONS.FEEDBACK);
+    if (copyable || rateable) {
+      attachMessageActions(bubble, {
+        strings: this.#host.strings(),
+        // Read at click time, not captured: a bubble rendered from markdown
+        // holds its text in the DOM, and that is what the user sees and means
+        // to copy. Serialised rather than read off `textContent`, which welds
+        // a table into one run of digits and picks up the code blocks' own
+        // copy buttons on the way past.
+        ...(copyable
+          ? {
+              text: () => copyPayload(bubble).text,
+              html: () => copyPayload(bubble).html,
+            }
+          : {}),
+        ...(rateable
+          ? {
+              onFeedback: (rating: "up" | "down") => {
+                this.#host.element.dispatchEvent(
+                  new CustomEvent<FeedbackDetail>(FEEDBACK_EVENT, {
+                    detail: { content: copyPayload(bubble).text, rating },
+                    bubbles: true,
+                    composed: true,
+                  }),
+                );
+              },
+            }
+          : {}),
+      });
+    }
+    if (enabled.has(MESSAGE_ACTIONS.RETRY)) {
+      this.#moveRetryTo(messageActionBar(bubble, this.#host.strings()));
+    }
+  }
+
+  /** Move the Retry button onto `bar`, taking it off whoever held it. */
+  #moveRetryTo(bar: HTMLElement): void {
+    this.#retryOwner?.querySelector(".message-action--retry")?.remove();
+    const retry = messageActionButton("retry", this.#host.strings().retryMessage, ICON_RETRY);
+    retry.addEventListener("click", () => {
+      this.#host.retry();
+    });
+    // First in the row: it is the action a reader reaches for when the answer
+    // was wrong, which is when they are least inclined to hunt for a control.
+    bar.prepend(retry);
+    this.#retryOwner = bar;
+  }
+
+  /**
+   * Which message actions a finished bubble offers, from
+   * `data-message-actions`.
+   *
+   * **Absent means copy and retry, not all three.** Those two work with nothing
+   * wired: copy reads the DOM, retry drives this element. The rating pair does
+   * not -- it fires `ag-ui-feedback` and stores nothing by design, because a
+   * rating belongs to whatever the host already uses for product signal. With no
+   * listener the buttons still latch `aria-pressed`, so a reader is told their
+   * rating was taken and a screen reader announces it, while nothing recorded
+   * anything. This README has always said two buttons that lead nowhere are
+   * worse than none; shipping them by default was that sentence being false.
+   *
+   * A host with a listener asks for them: `data-message-actions="copy,retry,feedback"`.
+   * A value names the survivors, which makes `data-message-actions="false"` --
+   * the spelling its sibling `data-quote-selection` uses -- an empty set by
+   * falling out of the same rule rather than by a case of its own.
+   */
+  #enabled(): ReadonlySet<string> {
+    const attr = this.#host.element.getAttribute("data-message-actions");
+    if (attr === null) {
+      return new Set([MESSAGE_ACTIONS.COPY, MESSAGE_ACTIONS.RETRY]);
+    }
+    return new Set(commaTokens(attr));
+  }
+}

package/src/ui/transcript/answer_stream.ts

@@ -0,0 +1,123 @@
+import { renderMarkdown } from "./render_markdown.js";
+
+/** What the streamed answer needs from the element that owns it. */
+export interface AnswerStreamHost {
+  /** Append an empty assistant bubble to the transcript, and return it. */
+  readonly openBubble: () => HTMLDivElement;
+  /** The element's `allowImages`, read per render. */
+  readonly allowImages: () => boolean;
+  /** Keep the transcript at its foot, if the reader is there. */
+  readonly follow: () => void;
+}
+
+/**
+ * The assistant answer currently streaming: the bubble it streams into, the
+ * text the next frame will draw, and how many deltas it arrived in.
+ *
+ * Owned one-to-one by an `<ag-ui-chat>`, and holding no state outside the
+ * instance.
+ */
+export class AnswerStream {
+  readonly #host: AnswerStreamHost;
+  #streamingBubble: HTMLDivElement | null = null;
+  // Text deltas applied to the current streaming bubble. >1 ⇒ the message
+  // revealed progressively as it streamed, so the word reveal must not re-animate
+  // it; ≤1 ⇒ it arrived at once and the word reveal is appropriate.
+  #streamDeltas = 0;
+  // The accumulated answer the next render will draw. Deltas overwrite it
+  // (each one carries the whole answer), so a frame always draws the latest.
+  #streamBuffer = "";
+  // The frame that render is queued on, or `null` when nothing is queued —
+  // also the flag saying a delta is still undrawn.
+  #streamFrame: number | null = null;
+
+  constructor(host: AnswerStreamHost) {
+    this.#host = host;
+  }
+
+  /** Text deltas the current answer has arrived in so far. */
+  get deltas(): number {
+    return this.#streamDeltas;
+  }
+
+  /**
+   * Count one delta received. Counted per delta received, not per render: the
+   * word reveal asks whether the answer *arrived* progressively, which
+   * coalescing renders must not change the answer to.
+   */
+  countDelta(): void {
+    this.#streamDeltas += 1;
+  }
+
+  /**
+   * Queue a render of the answer so far, at most one per frame.
+   *
+   * Each `TEXT_MESSAGE_CONTENT` event carries the *whole* accumulated answer,
+   * and drawing it means marked + DOMPurify over the entire document and a
+   * wholesale replacement of the bubble's subtree. Once per token that is
+   * quadratic in the answer's length — a long answer is agent-controlled, so
+   * an ordinary run becomes a progressively stalling tab — and every rebuild
+   * takes any selection or focus inside the bubble with it.
+   *
+   * A frame is the right grain: it is the fastest anything on screen can
+   * change anyway, so a burst of tokens costs one parse and the text still
+   * appears to flow rather than in visible chunks.
+   */
+  queue(buffer: string): void {
+    this.#streamBuffer = buffer;
+    this.#open();
+    if (this.#streamFrame !== null) {
+      return;
+    }
+    this.#streamFrame = requestAnimationFrame(() => {
+      this.#streamFrame = null;
+      this.into(this.#streamBuffer);
+    });
+  }
+
+  /** Render `buffer` into the streaming bubble now, dropping any queued frame. */
+  into(buffer: string): HTMLDivElement {
+    // A frame still queued would otherwise fire after this and repaint the
+    // bubble with whatever the last delta held — behind the buffer just drawn.
+    if (this.#streamFrame !== null) {
+      cancelAnimationFrame(this.#streamFrame);
+      this.#streamFrame = null;
+    }
+    this.#streamBuffer = buffer;
+    const bubble = this.#open();
+    bubble.innerHTML = renderMarkdown(buffer, { allowImages: this.#host.allowImages() });
+    this.#host.follow();
+    return bubble;
+  }
+
+  /**
+   * Close the current answer's streaming bubble.
+   *
+   * Draws a queued render first. A run that ends without a text end — a
+   * cancel, an error, a round boundary — leaves the last delta sitting in the
+   * queue, and simply dropping the bubble here would strand it: the partial
+   * answer the user stopped mid-sentence would lose its final tokens, or be an
+   * empty bubble above the stopped note.
+   */
+  end(): void {
+    if (this.#streamFrame !== null) {
+      this.into(this.#streamBuffer);
+    }
+    this.#streamingBubble = null;
+  }
+
+  /**
+   * The bubble the current answer streams into, opening it on first sight.
+   *
+   * Opened the moment a token arrives rather than on the frame that draws it,
+   * so the answer's container replaces the pending dots straight away and the
+   * turn never shows a gap while the first render waits for a frame.
+   */
+  #open(): HTMLDivElement {
+    if (this.#streamingBubble === null) {
+      this.#streamingBubble = this.#host.openBubble();
+      this.#streamDeltas = 0;
+    }
+    return this.#streamingBubble;
+  }
+}

package/src/ui/transcript/render_or_warn.ts

@@ -0,0 +1,22 @@
+/**
+ * Call a consumer's renderer, turning a throw into "nothing drawn".
+ *
+ * `render` is consumer code -- a host's activity renderer, a tool's `render` --
+ * and both call sites run inside the history replay, where a throw abandons the
+ * loop and takes every later turn of the transcript with it -- silently, and
+ * again on every reload. One thing that fails to draw is worth losing; the rest
+ * of the conversation is not. Reported so the failure is findable rather than
+ * merely survived.
+ *
+ * @param render - The consumer's renderer, already bound to its input.
+ * @param subject - What was being drawn, for the warning: `tool <name>` or
+ *   `activity <type>`.
+ */
+export function renderOrWarn(render: () => Node | null, subject: string): Node | null {
+  try {
+    return render();
+  } catch (error) {
+    console.warn(`ag-ui-chat: render failed for ${subject}`, error);
+    return null;
+  }
+}

package/src/ui/transcript/starter_chips.ts

@@ -0,0 +1,42 @@
+import type { UiStrings } from "../ui_strings.js";
+import { renderSuggestionChips } from "./suggestion_chips.js";
+
+/**
+ * The prompts offered on an empty transcript, from `element`'s `data-starters`.
+ *
+ * Different from the suggestion chips a run pushes, which are follow-ups to
+ * something already said. These answer the blank-page question instead, and
+ * they are the host's rather than the model's -- only the host knows what its
+ * page is for. Shares the renderer, the count and the length limit, because
+ * two rows of prompt chips that behaved differently would be the harder
+ * thing to explain.
+ *
+ * Read once at connect: it is content for a state the widget is in before
+ * anything happens, and a host that wants it to change has `slot="empty"`.
+ *
+ * Parses the attribute itself rather than through the element's JSON attribute
+ * reader, because the warning is its own: it says no starters are shown and
+ * gives an example of the shape, where the shared one says a built-in default
+ * is in use, which for this attribute there is not.
+ */
+export function renderStarterChips(
+  element: Element,
+  strings: UiStrings,
+  onPick: (prompt: string) => void,
+): HTMLElement | null {
+  const raw = element.getAttribute("data-starters");
+  if (raw === null) {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    console.warn(
+      "<ag-ui-chat>: data-starters is not valid JSON, so no starters are shown. " +
+        "It takes an array of strings, e.g. data-starters='[\"Summarise this page\"]'.",
+    );
+    return null;
+  }
+  return renderSuggestionChips({ prompts: parsed }, strings, onPick);
+}