@artooi/agents-web-components 0.0.0-stage → 0.1.1

package/src/ui/themes/theme_hosts.ts

@@ -0,0 +1,14 @@
+/**
+ * The host selectors theme rules hang off, as one record so every theme
+ * module spells them the same way.
+ *
+ * Classic and code keep today's structure, so the structural rules the newer
+ * themes share apply to every element that wears neither. Quiet is the
+ * default, so its own structure applies to every element that wears no other
+ * built-in theme -- including one whose theme is a word the library does not
+ * know, which is how a host's own named theme starts from Quiet.
+ */
+export const THEME_HOST = {
+  modern: ':host(:not([theme~="classic"], [theme~="code"]))',
+  quiet: ':host(:not([theme~="classic"], [theme~="code"], [theme~="soft"], [theme~="ledger"]))',
+} as const;

package/src/ui/transcript/answer_actions.ts

@@ -0,0 +1,165 @@
+import { FEEDBACK_EVENT, ICON_RETRY, MESSAGE_ACTIONS } from "../../constants.js";
+import type { AgUiMessageIds } from "../../core/agui_client.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 element's current conversation thread. */
+  readonly threadId: () => string;
+  /** Follow the transcript's foot, as every site that adds to it does. */
+  readonly follow: () => void;
+}
+
+/** A finished bubble that is not an answer, and so carries no rating. */
+interface Unrateable {
+  readonly rateable: false;
+}
+
+/**
+ * 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 a page-driving agent's past turns clicked buttons that a
+   * re-run does not undo. One owner keeps exactly one offer on screen.
+   */
+  #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.
+   *
+   * `message` names the answer, which is what a rating is filed under; a bubble
+   * that is not an answer says so instead, and has no id to give.
+   */
+  attach(bubble: HTMLDivElement, message: AgUiMessageIds | Unrateable): 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 answer = "messageId" in message ? message : null;
+    const rateable = answer !== null && enabled.has(MESSAGE_ACTIONS.FEEDBACK);
+    // Read now, not at click time: the thread the message was drawn in is the
+    // one it is stored under, even if a later path kept bubbles across threads.
+    const threadId = this.#host.threadId();
+    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,
+                      messageId: answer.messageId,
+                      threadId,
+                      // Omitted rather than undefined: a restored message has
+                      // no run, and a key holding nothing reads as one that
+                      // was looked up and came back empty.
+                      ...(answer.runId === undefined ? {} : { runId: answer.runId }),
+                    },
+                    bubbles: true,
+                    composed: true,
+                  }),
+                );
+              },
+            }
+          : {}),
+      });
+    }
+    if (enabled.has(MESSAGE_ACTIONS.RETRY)) {
+      this.#moveRetryTo(messageActionBar(bubble, this.#host.strings()));
+    }
+    // The row is insertion too: without this a pinned transcript rests one row short of its foot.
+    this.#host.follow();
+  }
+
+  /** 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/attachment_chip_styles.ts

@@ -0,0 +1,116 @@
+// An attachment chip, in the tray and in a sent message alike, the drop
+// outline, and the note a cancelled run leaves, which sits here only
+// because no rule moved in the split.
+export const ATTACHMENT_CHIP_STYLES: string = `
+/* A chip carries its own text colour because it carries its own background.
+   The same chip renders in two places with opposite inherited colours: the
+   composer tray gives it the panel's, a sent user bubble gives it the user
+   foreground, which is white on the stock light theme and near-invisible
+   against the chip. Pairing the colour with the background it belongs to makes
+   both placements read alike. Overridden below for an errored chip, which
+   keeps its red. */
+.attachment-chip {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  /* Without this the 100% below caps the content box, so the chip still
+     overflows its container by its own padding and border. Invisible while a
+     character cap kept names short; routine once the container is what bounds
+     the name. */
+  box-sizing: border-box;
+  max-width: 100%;
+  padding: 4px 8px;
+  border: 1px solid var(--_border);
+  border-radius: 999px;
+  background: var(--_assistant-bg);
+  color: var(--_text);
+  font-size: 0.85em;
+  position: relative;
+}
+
+.attachment-chip--error {
+  border-color: var(--_danger);
+  color: var(--_danger);
+}
+
+/* The type mark. Painted from currentColor, so it carries the chip's state
+   with it and turns red along with an errored one; muted by opacity rather
+   than a colour, which is what keeps that true. Sized from the chip's own text
+   rather than --ag-ui-glyph-size, the way an icon holder's glyph takes the
+   holder's size: the composer's 18px buttons would make a chip button-height. */
+.attachment-chip-icon {
+  display: inline-flex;
+  flex: none;
+  opacity: 0.75;
+}
+
+.attachment-chip-icon .glyph {
+  width: 1.25em;
+  height: 1.25em;
+}
+
+/* No character cap: the chip is already max-width 100%, so its container is
+   what bounds the name, and a fixed cap only truncated names the chip had room
+   for. min-width: 0 is what lets the flex item shrink past its content, so the
+   ellipsis appears at the container edge instead of the chip overflowing. */
+.attachment-chip-name {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  min-width: 0;
+}
+
+.attachment-chip-size {
+  color: var(--_muted);
+  white-space: nowrap;
+}
+
+.attachment-chip--error .attachment-chip-size {
+  color: var(--_danger);
+}
+
+/* The progress bar fills as the file uploads. */
+.attachment-chip-bar {
+  flex-basis: 100%;
+  height: 3px;
+  border-radius: 2px;
+  background: var(--_border);
+  overflow: hidden;
+}
+
+.attachment-chip-bar-fill {
+  height: 100%;
+  background: var(--_accent);
+  transition: width 0.15s ease;
+}
+
+.attachment-chip-remove,
+.attachment-chip-retry {
+  border: none;
+  background: none;
+  color: inherit;
+  cursor: pointer;
+  padding: 0;
+  line-height: 1;
+  opacity: 0.7;
+}
+
+.attachment-chip-remove:hover,
+.attachment-chip-retry:hover {
+  opacity: 1;
+}
+
+/* A subtle outline while a file is dragged over the shell. */
+.chat--dragover {
+  outline: 2px dashed var(--_accent);
+  outline-offset: -4px;
+}
+
+/* Muted "⏹ Stopped" line after a cancelled run — a note, not an error bubble. */
+.stopped-note {
+  align-self: flex-start;
+  color: var(--_muted);
+  font-size: 12px;
+  padding: 2px 4px;
+}
+`;

package/src/ui/transcript/attachment_chips.ts

@@ -0,0 +1,82 @@
+import { ICON_FILE, ICON_FILE_IMAGE, ICON_FILE_PDF, ICON_FILE_TEXT } from "../../constants.js";
+import type { AttachmentRef } from "../../core/attachment.js";
+
+/**
+ * Render the read-only attachment chips on a sent user message bubble and on
+ * restored history — one chip per ref with a type icon, filename, and human
+ * size. Static: no progress and no remove, both of which live in the composer
+ * tray.
+ */
+export function renderAttachmentChips(refs: readonly AttachmentRef[]): HTMLDivElement {
+  const list = document.createElement("div");
+  list.className = "attachment-chips";
+  list.setAttribute("part", "attachment-chips");
+  for (const ref of refs) {
+    list.appendChild(renderChip(ref));
+  }
+  return list;
+}
+
+function renderChip(ref: AttachmentRef): HTMLDivElement {
+  const chip = document.createElement("div");
+  chip.className = "attachment-chip attachment-chip--ready";
+  chip.setAttribute("part", "attachment-chip");
+
+  const icon = document.createElement("span");
+  icon.className = "attachment-chip-icon";
+  icon.setAttribute("part", "attachment-chip-icon");
+  icon.innerHTML = iconFor(ref.mime);
+  icon.setAttribute("aria-hidden", "true");
+
+  const name = document.createElement("span");
+  name.className = "attachment-chip-name";
+  name.setAttribute("part", "attachment-chip-name");
+  name.textContent = ref.name;
+  name.title = ref.name;
+
+  const size = document.createElement("span");
+  size.className = "attachment-chip-size";
+  size.setAttribute("part", "attachment-chip-size");
+  size.textContent = formatBytes(ref.size);
+
+  chip.append(icon, name, size);
+  return chip;
+}
+
+/**
+ * A coarse type mark for a chip — image, PDF, text document, or generic file —
+ * as inline SVG markup rather than a character, so it matches the composer's
+ * SVG buttons in weight and takes the glyph size and `currentColor`, which
+ * emoji do not.
+ *
+ * The MIME string only selects among author-written constants and is never
+ * interpolated into one, so the result is safe to assign as markup.
+ */
+export function iconFor(mime: string): string {
+  if (mime.startsWith("image/")) {
+    return ICON_FILE_IMAGE;
+  }
+  if (mime === "application/pdf") {
+    return ICON_FILE_PDF;
+  }
+  if (mime.startsWith("text/")) {
+    return ICON_FILE_TEXT;
+  }
+  return ICON_FILE;
+}
+
+/** A compact human-readable byte size (e.g. `1.2 MB`). */
+export function formatBytes(bytes: number): string {
+  if (bytes < 1024) {
+    return `${bytes} B`;
+  }
+  const units = ["KB", "MB", "GB"];
+  let value = bytes / 1024;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit += 1;
+  }
+  const rounded = value < 10 ? Math.round(value * 10) / 10 : Math.round(value);
+  return `${rounded} ${units[unit]}`;
+}

package/src/ui/transcript/build_transcript.ts

@@ -0,0 +1,67 @@
+import type { UiStrings } from "../ui_strings.js";
+
+/** The transcript's parts, owned by the element, and what fills them. */
+export interface TranscriptOptions {
+  readonly messages: HTMLElement;
+  readonly jumpButton: HTMLButtonElement;
+  readonly emptyWrap: HTMLElement;
+  /** The greeting's text node, kept by the element so a new user name updates it. */
+  readonly greetingText: HTMLElement;
+  /** The starter chips, or `null` when the host configured none. */
+  readonly starters: HTMLElement | null;
+  readonly strings: UiStrings;
+}
+
+/**
+ * Ready the message list, its jump-to-latest control and the empty state.
+ *
+ * The empty state is built but not put into the list: the element mounts the
+ * scroller, the quote offer and the announcer first and appends it after, so
+ * the scroller's observers see the list fill exactly as they always have.
+ */
+export function buildTranscript(options: TranscriptOptions): void {
+  const { messages, jumpButton, emptyWrap, strings } = options;
+  messages.className = "messages";
+  messages.setAttribute("part", "messages");
+  messages.setAttribute("role", "log");
+  // NOT a live region. The streaming bubble's innerHTML is replaced inside
+  // this element on every animation frame, and `role="log"` already implies
+  // polite announcement whose default `aria-relevant` includes text
+  // additions -- so a screen reader was asked to re-announce the whole answer
+  // tens of times as it streamed. `aria-live="off"` is an explicit override
+  // of the role's implicit value, which is why the role can stay: the log
+  // semantics are what let the transcript be navigated as one, and only the
+  // announcing is the defect. Status goes to the announcer instead.
+  messages.setAttribute("aria-live", "off");
+  messages.setAttribute("aria-label", strings.conversation);
+
+  jumpButton.className = "jump-latest";
+  jumpButton.type = "button";
+  jumpButton.setAttribute("part", "jump-latest");
+  jumpButton.textContent = strings.jumpToLatest;
+
+  // Empty-state region: a host slot at the top of the list, hidden as soon as
+  // anything renders.
+  emptyWrap.className = "empty";
+  emptyWrap.setAttribute("part", "empty");
+  // The greeting heads the empty state, in a slot of its own: a host that
+  // replaces the starters keeps the greeting, and a host that replaces the
+  // greeting keeps the starters. A div rather than a heading, because this
+  // sits inside somebody else's page, which owns the document outline.
+  const greeting = document.createElement("div");
+  greeting.className = "greeting";
+  greeting.setAttribute("part", "greeting");
+  const greetingSlot = document.createElement("slot");
+  greetingSlot.name = "greeting";
+  greetingSlot.append(options.greetingText);
+  greeting.append(greetingSlot);
+  const emptySlot = document.createElement("slot");
+  emptySlot.name = "empty";
+  // Fallback content, so a host that slots its own gets exactly that and
+  // nothing of ours: the starters live *inside* the slot rather than beside
+  // it, which is the difference between an offer and an imposition.
+  if (options.starters !== null) {
+    emptySlot.append(options.starters);
+  }
+  emptyWrap.replaceChildren(greeting, emptySlot);
+}