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

package/src/ui/transcript/message_styles.ts

@@ -0,0 +1,262 @@
+// Messages: the answer well, incoming-text animations, rendered markdown,
+// code blocks and their copy button, tables, and the pending dots.
+export const MESSAGE_STYLES: string = `
+/* ── Answer group / well ─────────────────────────────────────────
+   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 turn renders as a flat stack. */
+.answer {
+  display: flex;
+  flex-direction: column;
+  gap: var(--_space);
+  align-self: stretch;
+  min-width: 0;
+}
+
+:host([data-answer-well]) .answer {
+  padding: var(--_pad);
+  background: var(--_well-bg);
+  border: 1px solid var(--_well-border);
+  border-radius: var(--_well-radius);
+}
+
+.message {
+  max-width: 80%;
+  padding: var(--_msg-pad);
+  border-radius: var(--_msg-radius);
+  line-height: 1.4;
+  white-space: pre-wrap;
+  /* overflow-wrap, not word-break, and the difference is the whole reason a
+     markdown table used to be unreadable.
+
+     Both stop one long unbroken token blowing out the bubble, which is all this
+     is for. But word-break: break-word is the legacy spelling of "break
+     anywhere", and breaking anywhere drops the *min-content* width of every
+     descendant to one character. A table's column algorithm takes min-content
+     as an input, so the table always fitted max-width: 100%, the overflow-x:
+     auto below it never had anything to scroll, and the columns absorbed the
+     pressure by rendering one letter per line instead. A seven-column header
+     came out 162px tall.
+
+     overflow-wrap: break-word breaks a word only when it would otherwise
+     overflow its line, and leaves min-content alone -- so the bubble is still
+     protected and the table is free to be wider than the panel and scroll. */
+  overflow-wrap: break-word;
+}
+
+/* ── Incoming-text animations (data-text-animation) ─────────────────────── */
+/* .message--restored (rehydrated history) is excluded: entrance animations are
+   for freshly-arriving messages, not the whole transcript replaying on reload.
+   Word mode is excluded implicitly — restored bubbles aren't wrapped. */
+:host([data-text-animation="fade"]) .message--assistant:not(.message--restored) {
+  animation: ag-ui-msg-fade 0.25s ease both;
+}
+
+@keyframes ag-ui-msg-fade {
+  from { opacity: 0; transform: translateY(4px); }
+  to { opacity: 1; transform: none; }
+}
+
+.message--assistant .word {
+  animation: ag-ui-word-in 0.3s ease both;
+  animation-delay: calc(var(--ag-ui-word-index, 0) * 35ms);
+}
+
+@keyframes ag-ui-word-in {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :host([data-text-animation="fade"]) .message--assistant,
+  .message--assistant .word {
+    animation: none;
+  }
+}
+
+.message--user {
+  align-self: flex-end;
+  background: var(--_user-bg);
+  color: var(--_user-fg);
+  border-bottom-right-radius: 4px;
+}
+
+.message--assistant {
+  align-self: flex-start;
+  background: var(--_assistant-bg);
+  border-bottom-left-radius: 4px;
+  /* Assistant bubbles hold rendered markdown/HTML, so collapse the source
+     whitespace the renderer leaves between block tags. */
+  white-space: normal;
+}
+
+/* Rendered-markdown elements inside an assistant bubble. */
+.message--assistant > :first-child {
+  margin-top: 0;
+}
+
+.message--assistant > :last-child {
+  margin-bottom: 0;
+}
+
+.message--assistant p,
+.message--assistant ul,
+.message--assistant ol,
+.message--assistant blockquote,
+.message--assistant pre {
+  margin: 0.5em 0;
+}
+
+.message--assistant ul,
+.message--assistant ol {
+  padding-left: 1.3em;
+}
+
+.message--assistant a {
+  color: var(--_accent);
+  text-decoration: underline;
+}
+
+.message--assistant code {
+  font-family: ui-monospace, "SF Mono", Menlo, monospace;
+  font-size: 0.92em;
+  background: rgba(127, 127, 127, 0.16);
+  padding: 1px 4px;
+  border-radius: 4px;
+}
+
+.message--assistant pre {
+  padding: 8px 10px;
+  overflow: auto;
+  background: var(--_bg);
+  border: 1px solid var(--_border);
+  border-radius: 6px;
+}
+
+.message--assistant pre code {
+  background: none;
+  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;
+}
+
+/* The only reader of --ag-ui-surface and --ag-ui-text. Their defaults are
+   transparent and the body foreground, which is what this button rendered as
+   before either token existed; changing them repaints only this control. */
+.code-copy {
+  position: absolute;
+  top: 4px;
+  right: 4px;
+  padding: 2px 8px;
+  font: inherit;
+  font-size: 0.75em;
+  line-height: 1.6;
+  color: var(--_muted);
+  background: var(--_surface);
+  border: 1px solid var(--_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(--_text);
+  background: var(--_hover);
+}
+
+.code-copy[data-state="copied"] {
+  opacity: 1;
+  color: var(--_text);
+}
+
+.code-copy[data-state="failed"] {
+  opacity: 1;
+  color: var(--_danger, var(--_text));
+}
+
+.message--assistant blockquote {
+  padding-left: 10px;
+  border-left: 3px solid var(--_border);
+  color: var(--_muted);
+}
+
+/* Markdown tables. table/thead/tbody/tr/th/td are all in the sanitizer's
+   ALLOWED_TAGS, so an agent can emit one. A wide table must scroll inside its
+   own box rather than stretch 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(--_border);
+  text-align: left;
+  vertical-align: top;
+}
+
+.message--assistant th {
+  background: var(--_hover);
+  font-weight: 600;
+}
+
+.pending {
+  align-self: flex-start;
+  display: inline-flex;
+  gap: 4px;
+  align-items: center;
+  padding: 12px 14px;
+  background: var(--_assistant-bg);
+  border-radius: 14px;
+  border-bottom-left-radius: 4px;
+}
+
+.pending-dot {
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background: var(--_muted);
+  animation: ag-ui-pending 1.2s infinite ease-in-out both;
+}
+
+.pending-dot:nth-child(2) {
+  animation-delay: 0.16s;
+}
+
+.pending-dot:nth-child(3) {
+  animation-delay: 0.32s;
+}
+
+@keyframes ag-ui-pending {
+  0%, 80%, 100% { opacity: 0.3; transform: translateY(0); }
+  40% { opacity: 1; transform: translateY(-3px); }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .pending-dot {
+    animation: none;
+    opacity: 0.6;
+  }
+}
+`;

package/src/ui/transcript/render_markdown.ts

@@ -0,0 +1,181 @@
+// Sanitisation is verified only in the `chromium` project: DOMPurify silently
+// sanitises nothing under happy-dom, so CLAUDE.md has the root cause.
+import DOMPurify, { type Config, type DOMPurify as Purifier } from "dompurify";
+import { Marked } from "marked";
+
+// A local instance, so configuration never leaks into a host's deduped `marked`.
+// Never mutated; per-call construction would re-pay setup on every streaming render.
+const parser = new Marked({ gfm: true, breaks: true });
+
+// Conservative allowlist for assistant chat content. Rendering untrusted
+// model/tool output as HTML is an XSS surface and this sanitiser is the only
+// thing standing in front of it, so `iframe`, `style` and all scripting stay
+// out.
+//
+// `img` is excluded by default: a model-controlled image URL is fetched with no
+// user interaction, turning prompt-injected page data into a zero-click
+// exfiltration channel. Hosts that trust their content opt in via `allowImages`.
+const ALLOWED_TAGS = [
+  "a",
+  "p",
+  "br",
+  "strong",
+  "em",
+  "b",
+  "i",
+  "u",
+  "s",
+  "del",
+  "code",
+  "pre",
+  "ul",
+  "ol",
+  "li",
+  "blockquote",
+  "h1",
+  "h2",
+  "h3",
+  "h4",
+  "h5",
+  "h6",
+  "hr",
+  "span",
+  "table",
+  "thead",
+  "tbody",
+  "tr",
+  "th",
+  "td",
+];
+
+// `target` and `rel` are on the list because {@link harden} writes them onto
+// every link. An attribute the returned markup carries but the config does not
+// name would be markup the sanitiser never approved — which is the whole defect
+// the hook exists to avoid.
+//
+// `class` is here only for marked's `language-*` code-fence hint, and `harden`
+// narrows it to exactly that. Left wide, it is a chrome-forgery channel: the
+// shadow stylesheet's component classes are unscoped selectors, so a `<span
+// class="approval-btn approval-btn--approve">` in model output resolves to the
+// same pixels as the real human-in-the-loop approval button, inside the surface
+// where the user decides whether to approve.
+const ALLOWED_ATTR = ["href", "title", "class", "target", "rel"];
+
+/**
+ * The sanitiser's declared allowlist — and, because {@link harden} runs inside
+ * the sanitiser rather than after it, its *effective* one too.
+ *
+ * `ALLOW_DATA_ATTR` and `ALLOW_ARIA_ATTR` default to `true`, which would admit
+ * every `data-*` and `aria-*` attribute on top of the five named above. Both
+ * matter here: the cards drive their resolved / expanded / status appearance off
+ * `[data-resolved]`, `[data-status]` and `[data-expanded]`, and an `aria-label`
+ * on model output makes a screen reader announce something other than what is on
+ * screen. Turning them off is what makes the declared list the real one.
+ *
+ * Exported so a test can assert the returned markup is a fixed point of it.
+ */
+export const SANITIZE_CONFIG: Config = {
+  ALLOWED_TAGS,
+  ALLOWED_ATTR,
+  ALLOW_DATA_ATTR: false,
+  ALLOW_ARIA_ATTR: false,
+};
+
+/** {@link SANITIZE_CONFIG} plus the images a host opts into. */
+export const SANITIZE_CONFIG_WITH_IMAGES: Config = {
+  ...SANITIZE_CONFIG,
+  ALLOWED_TAGS: [...ALLOWED_TAGS, "img"],
+  ALLOWED_ATTR: [...ALLOWED_ATTR, "src", "alt", "width", "height"],
+};
+
+/** The one class value markdown is allowed to carry, and where it may sit. */
+const LANGUAGE_CLASS = /^language-[A-Za-z0-9_+#.-]+$/;
+const LANGUAGE_HOSTS = new Set(["CODE", "PRE"]);
+
+/**
+ * Per-element hardening, run *inside* the sanitiser.
+ *
+ * It belongs here rather than in a pass over the finished string because
+ * DOMPurify must be the last thing to touch the markup: anything edited in
+ * afterwards is inserted into the document without the sanitiser ever having
+ * seen it, and re-parsing sanitiser output is the shape every mXSS bypass takes.
+ * Running as a hook means DOMPurify serialises the result of these edits, so
+ * what the caller inserts is exactly what it approved.
+ *
+ * Two jobs:
+ *
+ * - links open in a new tab and never hand over their opener. `target`/`rel` are
+ *   this module's to write, so they are stripped from everything else rather
+ *   than inherited from the model's own markup;
+ * - `class` is narrowed to the code-fence language hint on `code`/`pre`, the
+ *   only thing it is allowed for, and dropped everywhere else so model output
+ *   cannot adopt the component's own chrome.
+ */
+function harden(node: Element): void {
+  if (node.nodeName === "A" && node.hasAttribute("href")) {
+    node.setAttribute("target", "_blank");
+    node.setAttribute("rel", "noopener noreferrer");
+  } else {
+    node.removeAttribute("target");
+    node.removeAttribute("rel");
+  }
+  const classes = node.getAttribute("class");
+  if (classes === null) {
+    return;
+  }
+  const kept = LANGUAGE_HOSTS.has(node.nodeName)
+    ? classes.split(/\s+/).filter((token) => LANGUAGE_CLASS.test(token))
+    : [];
+  if (kept.length === 0) {
+    node.removeAttribute("class");
+    return;
+  }
+  node.setAttribute("class", kept.join(" "));
+}
+
+// A memo, not state: DOMPurify's default export is a singleton that `addHook`
+// mutates for every caller sharing the copy, host app included, so this module
+// builds its own instance. The hook is added before the instance is published
+// and nothing touches it afterwards, so every element reads the same value.
+// Built on first render, because an instance made without a DOM has no
+// `addHook` and an eager one would make a server-side `import` throw.
+let memo: Purifier | undefined;
+
+function sanitizer(): Purifier {
+  if (memo === undefined) {
+    const built = DOMPurify();
+    built.addHook("afterSanitizeAttributes", harden);
+    memo = built;
+  }
+  return memo;
+}
+
+/** Options for {@link renderMarkdown}. */
+export interface RenderMarkdownOptions {
+  /**
+   * Permit `<img>` tags (and their `src`/`alt`/`width`/`height` attributes) in
+   * the sanitised output. Off by default; see the exfiltration note on the
+   * allowlist above. Only enable for trusted content sources.
+   */
+  readonly allowImages?: boolean;
+}
+
+/**
+ * Render markdown (and any embedded raw HTML) to a sanitised HTML string.
+ *
+ * Markdown syntax and literal HTML share one path: `marked` emits HTML, then
+ * DOMPurify strips everything outside {@link SANITIZE_CONFIG} — scripts, event
+ * handlers, `javascript:` URLs, `data-*`/`aria-*`, and every class but a code
+ * fence's `language-*` hint. Links come out with `target="_blank"` and
+ * `rel="noopener noreferrer"`.
+ *
+ * The returned string is the sanitiser's own output, trimmed. Nothing edits it
+ * afterwards, so what a caller inserts is what DOMPurify approved.
+ */
+export function renderMarkdown(text: string, options?: RenderMarkdownOptions): string {
+  const allowImages = options?.allowImages === true;
+  const rendered = parser.parse(text, { async: false });
+  return sanitizer()
+    .sanitize(rendered, allowImages ? SANITIZE_CONFIG_WITH_IMAGES : SANITIZE_CONFIG)
+    .trim();
+}

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/reveal_words.ts

@@ -0,0 +1,41 @@
+/** Collect the text nodes under ``root`` with their parents (depth-first). */
+function collectTextNodes(root: Node, out: { node: Text; parent: Node }[]): void {
+  for (const child of Array.from(root.childNodes)) {
+    if (child.nodeType === Node.TEXT_NODE) {
+      out.push({ node: child as Text, parent: root });
+    } else {
+      collectTextNodes(child, out);
+    }
+  }
+}
+
+/**
+ * Wrap each word under ``root`` in `<span class="word" style="--ag-ui-word-index: N">`
+ * so CSS can reveal them one-by-one (staggered by the index). Whitespace is
+ * preserved as plain text. Used for the `word` text-animation mode on a
+ * completed assistant message; pure DOM, idempotent enough to re-run.
+ */
+export function wrapWords(root: HTMLElement): void {
+  const texts: { node: Text; parent: Node }[] = [];
+  collectTextNodes(root, texts);
+  let index = 0;
+  for (const { node, parent } of texts) {
+    const fragment = document.createDocumentFragment();
+    for (const part of node.data.split(/(\s+)/)) {
+      if (part === "") {
+        continue;
+      }
+      if (/\s/.test(part)) {
+        fragment.appendChild(document.createTextNode(part));
+        continue;
+      }
+      const span = document.createElement("span");
+      span.className = "word";
+      span.style.setProperty("--ag-ui-word-index", String(index));
+      span.textContent = part;
+      fragment.appendChild(span);
+      index += 1;
+    }
+    parent.replaceChild(fragment, node);
+  }
+}

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);
+}

package/src/ui/transcript/stick_to_bottom.ts

@@ -0,0 +1,126 @@
+/** A transcript that follows new content, unless the reader has other ideas. */
+export interface StickToBottom {
+  /**
+   * New content arrived. Scrolls to the bottom only while following, so
+   * reading older messages during a run is no longer undone on the next token.
+   */
+  readonly follow: () => void;
+  /** Go to the bottom and resume following, whatever the reader was doing. */
+  readonly jump: () => void;
+  /** Whether the transcript is currently following new content. */
+  readonly following: () => boolean;
+  readonly dispose: () => void;
+}
+
+export interface StickToBottomOptions {
+  /** The scrolling element -- the message list. */
+  readonly viewport: HTMLElement;
+  /**
+   * Called whenever the answer to "should a jump-to-latest affordance show?"
+   * changes. True means the reader has scrolled away *and* has since missed
+   * something; scrolling up through a settled transcript is not a reason to
+   * nag.
+   */
+  readonly onMissedContent: (missed: boolean) => void;
+}
+
+/**
+ * How close to the bottom still counts as the bottom, in CSS pixels.
+ *
+ * Not zero: `scrollHeight - scrollTop - clientHeight` lands on fractional
+ * values under a zoom level or a fractional device pixel ratio, so an exact
+ * comparison reports "scrolled away" for a transcript that is visibly pinned.
+ */
+const BOTTOM_SLACK_PX = 4;
+
+/**
+ * Follow the foot of a scrolling transcript, and stop when the reader scrolls
+ * away.
+ *
+ * Before this, eleven separate sites assigned `scrollTop = scrollHeight`
+ * unconditionally and nothing anywhere listened for a `scroll` event -- so
+ * nothing knew the reader had scrolled up, and scrolling back through a run was
+ * undone by the next token. Stick-to-bottom with a jump-to-latest affordance is
+ * a named primitive elsewhere for exactly this reason: shadcn ships it as
+ * `MessageScroller`, AI Elements as `ConversationScrollButton`.
+ *
+ * **Telling a reader's scroll from our own is the whole problem**, and the
+ * answer here is that it does not have to be told. A programmatic scroll only
+ * ever happens while already following, and it lands at the bottom, so the
+ * `scroll` event it provokes recomputes "at the bottom" as true and changes
+ * nothing. A reader's scroll is the only kind that can move the answer.
+ *
+ * A `ResizeObserver` covers the case scroll events cannot see: the *viewport*
+ * changing size. Resizing the panel, or the keyboard opening on a phone, moves
+ * the foot without anything scrolling and without any content arriving, so a
+ * pinned transcript would silently come unpinned.
+ *
+ * ⚠ It does **not** cover content that grows after insertion -- an image
+ * decoding, a chart laying out. A `ResizeObserver` on a scroll container does
+ * not fire when its `scrollHeight` changes, so catching that means observing
+ * every child, and the payoff is one late nudge in a case the reader can fix by
+ * scrolling. Insertion itself is covered: every site that adds to the
+ * transcript calls {@link StickToBottom.follow}.
+ */
+export function createStickToBottom({
+  viewport,
+  onMissedContent,
+}: StickToBottomOptions): StickToBottom {
+  let isFollowing = true;
+  let missed = false;
+
+  const atBottom = (): boolean =>
+    viewport.scrollHeight - viewport.scrollTop - viewport.clientHeight <= BOTTOM_SLACK_PX;
+
+  const setMissed = (next: boolean): void => {
+    if (next === missed) {
+      return;
+    }
+    missed = next;
+    onMissedContent(missed);
+  };
+
+  const toBottom = (): void => {
+    viewport.scrollTop = viewport.scrollHeight;
+  };
+
+  const onScroll = (): void => {
+    isFollowing = atBottom();
+    if (isFollowing) {
+      setMissed(false);
+    }
+  };
+
+  const follow = (): void => {
+    if (isFollowing) {
+      toBottom();
+      return;
+    }
+    setMissed(true);
+  };
+
+  // Passive: this listener never calls preventDefault, and saying so keeps it
+  // off the critical path of a scroll it has no intention of blocking.
+  viewport.addEventListener("scroll", onScroll, { passive: true });
+
+  const observer = new ResizeObserver(() => {
+    if (isFollowing) {
+      toBottom();
+    }
+  });
+  observer.observe(viewport);
+
+  return {
+    follow,
+    jump: (): void => {
+      isFollowing = true;
+      setMissed(false);
+      toBottom();
+    },
+    following: (): boolean => isFollowing,
+    dispose: (): void => {
+      viewport.removeEventListener("scroll", onScroll);
+      observer.disconnect();
+    },
+  };
+}