@artooi/ag-ui-web-component 0.28.0 → 0.30.0

package/src/core/agui_client.ts

@@ -109,6 +109,24 @@ export interface AgUiClientHandlers {
   /** Fired when the reasoning block ends (before the answer text streams). */
   onReasoningEnd(): void;
   onRunEnd(): void;
+  /**
+   * The server replaced the whole conversation with `MESSAGES_SNAPSHOT`.
+   *
+   * `@ag-ui/client` applies the event before any subscriber sees it, so by the
+   * time this fires `agent.messages` **is** the server's list -- and the run
+   * loop persists `agent.messages`. The replacement therefore reaches the
+   * conversation store whatever the host does; this hook exists so the host can
+   * stop that being invisible.
+   */
+  onMessagesSnapshot(messages: readonly Message[]): void;
+  /**
+   * The agent sent a `CUSTOM` event.
+   *
+   * Forwarded whole and uninterpreted: `name` is an open string the protocol
+   * does not enumerate, so a client that decided which names were legal would
+   * be the thing the open field exists to avoid.
+   */
+  onCustomEvent(name: string, value: unknown): void;
   onError(message: string): void;
   /**
    * Fired when the user cancelled the run ({@link AgUiClient.cancel}) — the
@@ -164,6 +182,22 @@ export interface AgUiClientConfig extends AgUiRunInputs {
    * passes its localized string.
    */
   connectionLostMessage?: string;
+  /**
+   * Upper bound on frontend tool-call to re-run rounds within one
+   * {@link AgUiClient.send}. Defaults to {@link MAX_TOOL_ROUNDS}.
+   *
+   * The default suits a chat whose tools answer questions. A page-driving
+   * deployment reaches it legitimately -- filling a form field by field is one
+   * round each -- and the symptom is not an error but an answer that stops
+   * mid-task, which reads as the model giving up. Raise it where a turn is
+   * expected to take many small steps.
+   *
+   * Read once, when the client is built. The bound is a property of the
+   * deployment rather than of a run, so re-reading it per round would only make
+   * a mid-run change possible, and a mid-run change to how long the run may
+   * last is not a thing a host has any way to reason about.
+   */
+  maxToolRounds?: number;
 }
 
 /**
@@ -201,6 +235,7 @@ export class AgUiClient {
    */
   readonly #closedMessageIds = new Set<string>();
   readonly #connectionLostMessage: string;
+  readonly #maxToolRounds: number;
   // Set by cancel(); reset at the top of each #run(). Checked by the loop so
   // a cancel between frontend-tool rounds doesn't start another round.
   #cancelled = false;
@@ -214,6 +249,12 @@ export class AgUiClient {
     this.#resolveInterrupts = config.resolveInterrupts ?? null;
     this.#onPersist = config.onPersist ?? (() => {});
     this.#connectionLostMessage = config.connectionLostMessage ?? "Connection lost";
+    // Validated here rather than at each caller, so the element's attribute and
+    // a direct consumer get the same answer. A bound below one -- or a NaN from
+    // an unparseable attribute -- is not a smaller budget but a send that runs
+    // the agent zero times, which would look exactly like a broken endpoint.
+    const rounds = config.maxToolRounds ?? MAX_TOOL_ROUNDS;
+    this.#maxToolRounds = rounds >= 1 ? Math.floor(rounds) : MAX_TOOL_ROUNDS;
     const onStateChanged = config.onStateChanged;
     if (onStateChanged !== undefined) {
       // The agent applies STATE_SNAPSHOT / STATE_DELTA itself; subscribing is
@@ -252,7 +293,8 @@ export class AgUiClient {
    *
    * When the agent calls frontend tools, this executes them and re-runs the
    * agent with the results, looping until the agent stops calling frontend
-   * tools (bounded by {@link MAX_TOOL_ROUNDS}).
+   * tools (bounded by {@link AgUiClientConfig.maxToolRounds}, which defaults to
+   * {@link MAX_TOOL_ROUNDS}).
    *
    * `attachments` ride on the user message as a non-standard field so the
    * default store round-trips them for history replay; see
@@ -271,6 +313,45 @@ export class AgUiClient {
     await this.#run();
   }
 
+  /**
+   * Drop everything after the most recent user message, so the same question
+   * can be asked again.
+   *
+   * Returns the retained history, or `null` when there is nothing to retry (no
+   * user message has been sent yet). **Truncates only** -- the caller re-renders
+   * from the returned list and then calls {@link resume}, because the transcript
+   * belongs to the element and a client that reached into it would own two
+   * things. Running here instead would stream the new answer in underneath the
+   * old one.
+   *
+   * Re-running answers the question the agent was last asked, rather than
+   * telling it its answer was wrong, which is what makes the result a
+   * *different* answer instead of a conversation about the previous one.
+   *
+   * **A retried turn re-runs its tools.** For a page-driving agent that is not
+   * neutral: the previous attempt already clicked what it clicked, and this
+   * does not undo it.
+   */
+  truncateToLastUser(): readonly Message[] | null {
+    const messages = [...this.#agent.messages];
+    // Forward, keeping the last match, rather than a reverse scan with an
+    // index lookup: `noUncheckedIndexedAccess` makes the latter reach for an
+    // optional chain whose null arm cannot happen and cannot be covered.
+    let lastUser = -1;
+    for (const [index, message] of messages.entries()) {
+      if (message.role === "user") {
+        lastUser = index;
+      }
+    }
+    if (lastUser === -1) {
+      return null;
+    }
+    const kept = messages.slice(0, lastUser + 1);
+    this.#agent.setMessages(kept);
+    this.#onPersist(this.#agent.messages);
+    return kept;
+  }
+
   /**
    * Resume the run loop after a navigating tool's result was supplied
    * post-reload (via {@link addToolResult}). Unlike {@link send}, adds no user
@@ -332,7 +413,7 @@ export class AgUiClient {
     // continues an unfinished frontend-tool round after a page load; this stays
     // inside one #run().
     let resume: ResumeEntry[] | undefined;
-    for (let round = 0; round < MAX_TOOL_ROUNDS; round += 1) {
+    for (let round = 0; round < this.#maxToolRounds; round += 1) {
       // A cancel during the previous round's tool execution lands here: the
       // running handler completed, but no further round starts.
       if (this.#cancelled) {
@@ -483,6 +564,12 @@ export class AgUiClient {
       // Emitted after the client has written the patched messages, which is the
       // first moment the result exists. Only the ids marked above are looked at,
       // so an ordinary text delta does not walk the transcript.
+      onCustomEvent({ event }) {
+        h.onCustomEvent(event.name, event.value);
+      },
+      onMessagesSnapshotEvent({ event }) {
+        h.onMessagesSnapshot(event.messages as readonly Message[]);
+      },
       onMessagesChanged({ messages }) {
         if (pendingDeltas.size === 0) {
           return;

package/src/index.ts

@@ -4,13 +4,19 @@ export {
   ATTACHMENT_EVENT,
   CHART_ACTIVITY_TYPE,
   COMPACTION_ACTIVITY_TYPE,
+  CUSTOM_AGENT_EVENT,
   ELEMENT_TAG,
+  FEEDBACK_EVENT,
+  INVALIDATE_CUSTOM_NAME,
+  INVALIDATE_EVENT,
   LOAD_CAPABILITY_TOOL,
   MAX_TOOL_ROUNDS,
+  MESSAGE_ACTIONS,
   MESSAGE_ROLE,
   RUN_FINISHED_EVENT,
   STATE_EVENT,
   SUBMIT_EVENT,
+  SUGGESTIONS_ACTIVITY_TYPE,
   TOGGLE_EVENT,
   TOOL_CALL_STATUS,
   TOOL_DISPLAY,
@@ -21,8 +27,13 @@ export {
   X_SUMMARY_KEY,
 } from "./constants.js";
 export {
+  type ActivityRegistration,
+  type ActivityRenderer,
   AgUiChat,
   type AttachmentsDetail,
+  type CustomAgentDetail,
+  type FeedbackDetail,
+  type InvalidateDetail,
   type MessageRole,
   type RunFinishedDetail,
   type StateDetail,
@@ -143,6 +154,16 @@ export {
   type ConfirmationRequest,
   requestConfirmation,
 } from "./ui/confirmation_card.js";
+export {
+  attachMessageActions,
+  type MessageActionsOptions,
+  messageActionBar,
+} from "./ui/message_actions.js";
+export {
+  attachQuoteOffer,
+  type PageQuoteOffer,
+  type PageQuoteOfferOptions,
+} from "./ui/page_quote_offer.js";
 export { prettifyToolName } from "./ui/prettify_tool_name.js";
 export {
   type QuestionOptions,
@@ -150,12 +171,34 @@ export {
   type QuestionRequest,
   requestQuestion,
 } from "./ui/question_card.js";
+// Quoting. The transcript wires these itself; they are exported for the half
+// the component cannot reach -- a selection made in the **host page**, which
+// a host reads its own way and hands to `AgUiChat.quote()`.
+export {
+  asQuote,
+  MAX_QUOTE_CHARS,
+  type QuotableSelection,
+  quotableSelection,
+} from "./ui/quote_selection.js";
+export {
+  type RelativeTimeFormatter,
+  relativeTime,
+} from "./ui/relative_time.js";
 export { type RenderMarkdownOptions, renderMarkdown } from "./ui/render_markdown.js";
+export {
+  MAX_SUGGESTION_CHARS,
+  MAX_SUGGESTIONS,
+  renderSuggestionChips,
+  suggestionPrompts,
+} from "./ui/suggestion_chips.js";
 export {
   type SettledStatus,
   ToolCallCard,
+  type ToolCallCardOptions,
   type ToolCallStatus,
   type ToolDisplayMode,
+  type ToolPayload,
+  type ToolPayloadFormatter,
 } 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/ui/approval_card.ts

@@ -10,6 +10,11 @@ export interface ApprovalRequest {
   message?: string;
   /** Tool name, surfaced as a `data-tool-name` attribute for styling/tests. */
   toolName?: string;
+  /**
+   * The call's arguments, shown for editing when {@link ApprovalOptions.onEdit}
+   * is set. Omitted when the interrupt names no call whose arguments are known.
+   */
+  args?: Record<string, unknown>;
 }
 
 /** Build a labelled action button. */
@@ -31,6 +36,19 @@ export interface ApprovalOptions {
   signal?: AbortSignal;
   /** Localized strings; defaults to the English {@link DEFAULT_UI_STRINGS}. */
   strings?: UiStrings;
+  /**
+   * Offer the call's arguments for editing, and receive what the user approved.
+   *
+   * Called **only** on approval, and only when the text parses and differs from
+   * what was proposed -- an untouched call resolves as a plain approval, so a
+   * server sees `editedArgs` exactly when something was actually edited.
+   *
+   * Absent means no editor, which is deliberate: AG-UI gates this on the
+   * agent's own `approveWithEdits` capability, and a card that let a user
+   * rewrite arguments a server will discard is worse than one that does not
+   * offer to.
+   */
+  onEdit?: (args: Record<string, unknown>) => void;
 }
 
 /**
@@ -78,6 +96,8 @@ export function requestApproval(
     body.setAttribute("part", "approval-body");
     body.textContent = request.message ?? strings.approvalPrompt;
 
+    const editor = buildEditor(request, options, strings);
+
     const actions = document.createElement("div");
     actions.className = "approval-actions";
     actions.setAttribute("part", "approval-actions");
@@ -98,11 +118,19 @@ export function requestApproval(
     };
 
     deny.addEventListener("click", () => close(false));
-    approve.addEventListener("click", () => close(true));
+    approve.addEventListener("click", () => {
+      if (editor !== null && !editor.commit()) {
+        // Unparseable JSON: say so on the card and stay open. Approving what
+        // the user did not write -- the original arguments -- would be the one
+        // outcome they cannot see coming.
+        return;
+      }
+      close(true);
+    });
     options.signal?.addEventListener("abort", () => close(false), { once: true });
 
     actions.append(deny, approve);
-    card.append(body, actions);
+    card.append(body, ...(editor === null ? [] : [editor.root]), actions);
     host.appendChild(card);
     if (options.signal?.aborted === true) {
       // The run was cancelled before the card could ask; record the denial.
@@ -112,3 +140,63 @@ export function requestApproval(
     approve.focus();
   });
 }
+
+/** The editable-arguments region, or `null` when this card does not offer one. */
+function buildEditor(
+  request: ApprovalRequest,
+  options: ApprovalOptions,
+  strings: UiStrings,
+): { root: HTMLElement; commit: () => boolean } | null {
+  const { onEdit } = options;
+  if (onEdit === undefined || request.args === undefined) {
+    return null;
+  }
+  const original = JSON.stringify(request.args, null, 2);
+  const root = document.createElement("div");
+  root.className = "approval-edit";
+  root.setAttribute("part", "approval-edit");
+
+  const field = document.createElement("textarea");
+  field.className = "approval-args";
+  field.setAttribute("part", "approval-args");
+  field.setAttribute("aria-label", strings.approvalEditArgs);
+  field.rows = Math.min(10, original.split("\n").length);
+  field.value = original;
+
+  const error = document.createElement("div");
+  error.className = "approval-error";
+  error.setAttribute("part", "approval-error");
+  // A live region: it appears in response to pressing Approve, and a message
+  // that only exists visually leaves a screen-reader user with a button that
+  // silently did nothing.
+  error.setAttribute("role", "alert");
+  error.hidden = true;
+
+  root.append(field, error);
+  return {
+    root,
+    commit: () => {
+      if (field.value === original) {
+        return true;
+      }
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(field.value);
+      } catch {
+        error.textContent = strings.approvalArgsInvalid;
+        error.hidden = false;
+        field.focus();
+        return false;
+      }
+      if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        error.textContent = strings.approvalArgsNotAnObject;
+        error.hidden = false;
+        field.focus();
+        return false;
+      }
+      error.hidden = true;
+      onEdit(parsed as Record<string, unknown>);
+      return true;
+    },
+  };
+}

package/src/ui/checkpoint_menu.ts

@@ -1,5 +1,5 @@
 import type { RunRow } from "../core/run_index.js";
-import { relativeTime } from "./relative_time.js";
+import { type RelativeTimeFormatter, relativeTime } from "./relative_time.js";
 import { DEFAULT_UI_STRINGS, type UiStrings } from "./ui_strings.js";
 
 /** How the host continues a picked run. */
@@ -46,6 +46,7 @@ export class CheckpointMenu {
   readonly #heading: HTMLSpanElement;
   /** What had focus before the panel opened, restored on close. */
   #lastFocused: HTMLElement | null = null;
+  #formatRelativeTime: RelativeTimeFormatter | null = null;
   #strings: UiStrings;
   #runs: readonly RunRow[] = [];
 
@@ -91,6 +92,25 @@ export class CheckpointMenu {
   }
 
   /** Re-localize a panel built before the host's strings resolved. */
+  /**
+   * Replace the timestamp formatter, or restore the built-in with `null`.
+   *
+   * The built-in is deliberately locale-neutral -- there is no `Intl` anywhere
+   * in this component, so it never disagrees with a host's own formatting by
+   * guessing a locale. That is a defensible default and a poor requirement, so
+   * this is the way out.
+   */
+  setRelativeTimeFormatter(format: RelativeTimeFormatter | null): void {
+    this.#formatRelativeTime = format;
+  }
+
+  /** This row's timestamp, through the host's formatter when it set one. */
+  #formatTime(timestamp: number): string {
+    return this.#formatRelativeTime !== null
+      ? this.#formatRelativeTime(timestamp)
+      : relativeTime(timestamp, Date.now(), this.#strings);
+  }
+
   setStrings(strings: UiStrings): void {
     this.#strings = strings;
     this.element.setAttribute("aria-label", strings.checkpoints);
@@ -207,10 +227,7 @@ export class CheckpointMenu {
     row.setAttribute("part", "checkpoint-row");
 
     const preview = previewOf(run);
-    const time =
-      run.started_at === null
-        ? null
-        : relativeTime(Date.parse(run.started_at), Date.now(), this.#strings);
+    const time = run.started_at === null ? null : this.#formatTime(Date.parse(run.started_at));
 
     const label = document.createElement("span");
     label.className = "checkpoint-label";

package/src/ui/confirmation_card.ts

@@ -31,6 +31,16 @@ export interface ConfirmationOptions {
   signal?: AbortSignal;
   /** Localized strings; defaults to the English {@link DEFAULT_UI_STRINGS}. */
   strings?: UiStrings;
+  /**
+   * Offer a third button — "always allow, this session" — and call this when
+   * the user picks it. The card still resolves `true`: the extra decision is
+   * *in addition to* approving this call, not instead of it.
+   *
+   * Absent means no button, which is deliberate: presence of the handler is
+   * what enables it, so the affordance can never be rendered with nothing
+   * listening. A caller that cannot honour the waiver simply does not pass one.
+   */
+  onAlwaysAllow?: () => void;
 }
 
 /**
@@ -43,6 +53,12 @@ export interface ConfirmationOptions {
  * Answering it removes it: the record of the decision belongs to the tool card
  * this gates, which settles to `done` or `declined` and carries it. A spent
  * form left in place reads as still outstanding.
+ *
+ * With `onAlwaysAllow` set the card offers a third button. A prompt that is
+ * approved nearly every time is not a decision, it is a speed bump — and the
+ * reflex it trains is what makes the rare refusal easy to miss. Letting the
+ * user say "not this one again, this session" is the affordance that keeps the
+ * remaining prompts meaningful.
  */
 export function requestConfirmation(
   host: Node & ParentNode,
@@ -75,6 +91,10 @@ export function requestConfirmation(
     actions.setAttribute("part", "confirm-actions");
 
     const cancel = actionButton("cancel", strings.cancel);
+    const always =
+      options.onAlwaysAllow === undefined
+        ? null
+        : actionButton("always", strings.confirmAlways.replace("{tool}", request.toolName));
     const confirm = actionButton("confirm", strings.confirm);
 
     let settled = false;
@@ -93,9 +113,17 @@ export function requestConfirmation(
 
     cancel.addEventListener("click", () => close(false));
     confirm.addEventListener("click", () => close(true));
+    always?.addEventListener("click", () => {
+      // Recorded before resolving, so a caller that reads its own allowlist
+      // synchronously on the next call already sees this one.
+      options.onAlwaysAllow?.();
+      close(true);
+    });
     options.signal?.addEventListener("abort", () => close(false), { once: true });
 
-    actions.append(cancel, confirm);
+    // Confirm stays last, and rightmost: the waiver is the wider decision, and
+    // putting it where the eye lands for "yes" is how it gets taken by accident.
+    actions.append(cancel, ...(always === null ? [] : [always]), confirm);
     card.append(body, args, actions);
     host.appendChild(card);
     if (options.signal?.aborted === true) {

package/src/ui/message_actions.ts

@@ -0,0 +1,170 @@
+import type { UiStrings } from "./ui_strings.js";
+
+/** How long a button shows its confirmation before reverting. */
+const CONFIRM_MS = 1500;
+
+/** What an action bar can do, beyond copying. */
+export interface MessageActionsOptions {
+  /** Localized strings. */
+  strings: UiStrings;
+  /**
+   * The text Copy puts on the clipboard. Absent means no copy button.
+   *
+   * A function rather than a string because a bubble's content is rewritten
+   * while it streams, and the bar is attached to the element rather than to a
+   * snapshot of it. Optional for the same reason `onFeedback` is: what a button
+   * needs to do its job is also the statement that the button belongs here, so
+   * there is no second flag saying the same thing and no way for the two to
+   * disagree.
+   */
+  text?: () => string;
+  /**
+   * Report a rating for this message. Absent means no feedback buttons.
+   *
+   * The component stores nothing: a rating is the host's to keep, and a
+   * write-only table nobody reads is not worth a schema.
+   */
+  onFeedback?: (rating: "up" | "down") => void;
+}
+
+/**
+ * Give one finished message bubble its row of actions.
+ *
+ * **Finished** is load-bearing. A streaming bubble reassigns its `innerHTML` on
+ * every delta, so anything attached mid-stream is discarded and rebuilt for
+ * each one -- the same constraint `attachCopyButtons` records, one level up.
+ *
+ * Retry is deliberately **not** here: it belongs to the last turn only, so the
+ * element owns it and moves it as the transcript grows. Everything on this bar
+ * is safe to offer on any message, however old.
+ *
+ * Idempotent -- a bubble already given a bar is skipped, so a re-render or a
+ * second call cannot stack rows.
+ *
+ * Each button is present because the option it needs was passed: `text` for
+ * Copy, `onFeedback` for the rating pair. Passing neither builds an empty row,
+ * which is a caller's mistake rather than a state to guard against -- the
+ * element skips the call entirely when a host has turned both off.
+ */
+export function attachMessageActions(bubble: HTMLElement, options: MessageActionsOptions): void {
+  if (existingBar(bubble) !== null) {
+    return;
+  }
+  const bar = messageActionBar(bubble, options.strings);
+  const text = options.text;
+  if (text !== undefined) {
+    bar.appendChild(copyButton(options.strings, text));
+  }
+  if (options.onFeedback !== undefined) {
+    bar.append(
+      feedbackButton("up", options.strings.feedbackUp, options.onFeedback),
+      feedbackButton("down", options.strings.feedbackDown, options.onFeedback),
+    );
+  }
+}
+
+/**
+ * The empty action row on `bubble`, created if it has none yet.
+ *
+ * Shared so a bubble that wants *only* Retry -- a failed run, which has nothing
+ * worth copying and nothing to rate -- gets the same row, the same part name
+ * and the same accessible grouping as every other message, rather than a
+ * second thing that looks like one.
+ */
+export function messageActionBar(bubble: HTMLElement, strings: UiStrings): HTMLElement {
+  const existing = existingBar(bubble);
+  if (existing !== null) {
+    return existing;
+  }
+  const bar = document.createElement("div");
+  bar.className = "message-actions";
+  bar.setAttribute("part", "message-actions");
+  // A group rather than a toolbar: these are independent actions on the message
+  // above, not a set the user arrows between.
+  bar.setAttribute("role", "group");
+  bar.setAttribute("aria-label", strings.messageActions);
+  // A **sibling**, never a child. Inside the bubble the buttons join its
+  // `textContent`, which is what Copy reads, what history persists and what
+  // every existing assertion about a message's text compares against -- so an
+  // answer would be copied back with the glyphs of the buttons that copied it.
+  // The bubble must therefore already be in the tree when this is called.
+  bubble.after(bar);
+  return bar;
+}
+
+/** The action row belonging to `bubble`, if it has one. */
+function existingBar(bubble: HTMLElement): HTMLElement | null {
+  const next = bubble.nextElementSibling;
+  return next?.classList.contains("message-actions") === true ? (next as HTMLElement) : null;
+}
+
+/** Build one action button, labelled for screen readers rather than by glyph. */
+export function messageActionButton(
+  modifier: string,
+  label: string,
+  glyph: string,
+): HTMLButtonElement {
+  const button = document.createElement("button");
+  button.type = "button";
+  button.className = `message-action message-action--${modifier}`;
+  button.setAttribute("part", `message-action message-action-${modifier}`);
+  button.title = label;
+  button.setAttribute("aria-label", label);
+  const icon = document.createElement("span");
+  icon.setAttribute("aria-hidden", "true");
+  icon.textContent = glyph;
+  button.appendChild(icon);
+  return button;
+}
+
+function copyButton(strings: UiStrings, text: () => string): HTMLButtonElement {
+  const button = messageActionButton("copy", strings.copyMessage, "⎘");
+  button.addEventListener("click", () => {
+    void navigator.clipboard.writeText(text()).then(
+      () => flash(button, strings.copied, strings.copyMessage),
+      // A denied clipboard permission is the common case, not an exception:
+      // say so on the button rather than throwing into an unhandled rejection.
+      () => flash(button, strings.copyFailed, strings.copyMessage),
+    );
+  });
+  return button;
+}
+
+function feedbackButton(
+  rating: "up" | "down",
+  label: string,
+  report: (rating: "up" | "down") => void,
+): HTMLButtonElement {
+  const button = messageActionButton(
+    rating === "up" ? "up" : "down",
+    label,
+    rating === "up" ? "\u{1F44D}" : "\u{1F44E}",
+  );
+  button.addEventListener("click", () => {
+    // Pressed rather than removed: the rating is a standing statement about the
+    // message, and a button that vanishes leaves no record of what was said.
+    const pressed = button.getAttribute("aria-pressed") === "true";
+    button.setAttribute("aria-pressed", pressed ? "false" : "true");
+    report(rating);
+  });
+  button.setAttribute("aria-pressed", "false");
+  return button;
+}
+
+/**
+ * Flash `message` on the button, then restore `label`.
+ *
+ * The label to restore is passed rather than read back off the element: the
+ * caller is the one that set it, and reading it would introduce a null arm that
+ * cannot happen and cannot be covered.
+ */
+function flash(button: HTMLButtonElement, message: string, label: string): void {
+  button.title = message;
+  button.setAttribute("aria-label", message);
+  button.classList.add("message-action--confirmed");
+  setTimeout(() => {
+    button.title = label;
+    button.setAttribute("aria-label", label);
+    button.classList.remove("message-action--confirmed");
+  }, CONFIRM_MS);
+}