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

package/src/ui/history/thread_drawer.ts

@@ -0,0 +1,471 @@
+import type { ThreadMeta } from "../../core/conversation_store.js";
+import { DEFAULT_UI_STRINGS, type UiStrings } from "../ui_strings.js";
+import { type RelativeTimeFormatter, relativeTime } from "./relative_time.js";
+import { openerElement } from "./utils.js";
+
+/**
+ * How many conversations there have to be before the filter appears.
+ *
+ * A search box above a list you can already read in one glance is a control
+ * asking to be used on nothing.
+ */
+export const FILTER_FROM = 8;
+
+/**
+ * When the search box shows: from {@link FILTER_FROM} conversations (`auto`),
+ * over any list (`always`), or not at all (`never`).
+ */
+export type ThreadsSearch = "auto" | "always" | "never";
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/** Actions the host ({@link AgUiChat}) wires to the drawer's rows. */
+export interface ThreadDrawerCallbacks {
+  /** A row was picked — load that thread and make it active. */
+  readonly onSelect: (threadId: string) => void;
+  /** The "New chat" action — start a fresh thread. */
+  readonly onNew: () => void;
+  /** A row was renamed to `title`. */
+  readonly onRename: (threadId: string, title: string) => void;
+  /** A row was deleted (after the inline confirm). */
+  readonly onDelete: (threadId: string) => void;
+}
+
+/**
+ * The chat-history drawer: a slide-over listing the user's threads (title,
+ * relative time, preview), with select / new / rename / delete actions and an
+ * empty state. Pure DOM, like {@link SkillsMenu}: the host appends
+ * {@link element}, toggles it, feeds rows via {@link setThreads}, and acts on
+ * the callbacks.
+ *
+ * A view only — it never mutates the store. After a callback the host updates
+ * the store and calls {@link setThreads} to refresh. All visible text comes
+ * from {@link UiStrings}; {@link setStrings} re-localizes a drawer built before
+ * its strings resolved.
+ */
+export class ThreadDrawer {
+  /** The drawer root (backdrop + panel). Append to the chat shell; hidden until opened. */
+  readonly element: HTMLDivElement;
+
+  readonly #callbacks: ThreadDrawerCallbacks;
+  readonly #panel: HTMLDivElement;
+  readonly #heading: HTMLSpanElement;
+  readonly #newButton: HTMLButtonElement;
+  readonly #list: HTMLDivElement;
+  #formatRelativeTime: RelativeTimeFormatter | null = null;
+  #strings: UiStrings;
+  #threads: readonly ThreadMeta[] = [];
+  #activeId = "";
+  /** Dismisses the list without starting a new conversation. */
+  #closeButton: HTMLButtonElement;
+  /** Narrows the list. Only rendered once there is enough of a list to narrow. */
+  #filter: HTMLInputElement;
+  /** The current filter text, lowercased once rather than per row. */
+  #query = "";
+  #search: ThreadsSearch = "auto";
+
+  /** The element focused before the drawer opened, restored on close. */
+  #lastFocused: HTMLElement | null = null;
+
+  constructor(callbacks: ThreadDrawerCallbacks, strings: UiStrings = DEFAULT_UI_STRINGS) {
+    this.#callbacks = callbacks;
+    this.#strings = strings;
+
+    this.element = document.createElement("div");
+    this.element.className = "drawer";
+    this.element.setAttribute("part", "drawer");
+    this.element.hidden = true;
+
+    const backdrop = document.createElement("div");
+    backdrop.className = "drawer-backdrop";
+    backdrop.setAttribute("part", "drawer-backdrop");
+    backdrop.addEventListener("click", () => this.close());
+
+    this.#panel = document.createElement("div");
+    this.#panel.className = "drawer-panel";
+    this.#panel.setAttribute("part", "drawer-panel");
+    this.#panel.setAttribute("role", "dialog");
+    this.#panel.setAttribute("aria-modal", "true");
+    this.#panel.setAttribute("aria-label", strings.chatHistory);
+    // Escape closes the drawer; Tab is trapped within the panel while it's open.
+    this.#panel.addEventListener("keydown", (event) => this.#onPanelKeydown(event));
+
+    const header = document.createElement("div");
+    header.className = "drawer-header";
+    header.setAttribute("part", "drawer-header");
+    this.#heading = document.createElement("span");
+    this.#heading.className = "drawer-title";
+    this.#heading.setAttribute("part", "drawer-title");
+    this.#heading.textContent = strings.chats;
+    this.#newButton = document.createElement("button");
+    this.#newButton.type = "button";
+    this.#newButton.className = "drawer-new";
+    this.#newButton.setAttribute("part", "drawer-new");
+    this.#newButton.textContent = strings.newChat;
+    this.#newButton.addEventListener("click", () => {
+      this.close();
+      this.#callbacks.onNew();
+    });
+    // An explicit way back. The backdrop closes on click, which is enough
+    // wherever a strip of it is showing -- but the embedded placement widens
+    // the panel to the full width of the host's box, so there is no backdrop
+    // left to hit and the only exits were Escape, picking a row, or starting a
+    // new conversation. The first is invisible and the last is destructive of
+    // the thing you were looking at.
+    this.#closeButton = document.createElement("button");
+    this.#closeButton.type = "button";
+    this.#closeButton.className = "drawer-close";
+    this.#closeButton.setAttribute("part", "drawer-close");
+    this.#closeButton.title = strings.closeHistory;
+    this.#closeButton.setAttribute("aria-label", strings.closeHistory);
+    this.#closeButton.append(document.createTextNode("\u00d7"));
+    this.#closeButton.addEventListener("click", () => this.close());
+    header.append(this.#heading, this.#newButton, this.#closeButton);
+
+    // Hidden until the list is long enough to be worth narrowing. A search box
+    // above four conversations is a control asking to be used on something
+    // already entirely visible.
+    this.#filter = document.createElement("input");
+    this.#filter.type = "search";
+    this.#filter.className = "drawer-filter";
+    this.#filter.setAttribute("part", "drawer-filter");
+    this.#filter.placeholder = strings.searchConversations;
+    this.#filter.setAttribute("aria-label", strings.searchConversations);
+    this.#filter.addEventListener("input", () => {
+      this.#query = this.#filter.value.trim().toLowerCase();
+      this.#renderList();
+    });
+
+    this.#list = document.createElement("div");
+    this.#list.className = "drawer-list";
+    this.#list.setAttribute("part", "drawer-list");
+
+    this.#panel.append(header, this.#filter, this.#list);
+    this.element.append(backdrop, this.#panel);
+  }
+
+  /** Re-localize the drawer's chrome and rows (the host calls this on connect). */
+  /**
+   * 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, undefined, this.#strings);
+  }
+
+  setStrings(strings: UiStrings): void {
+    this.#strings = strings;
+    this.#panel.setAttribute("aria-label", strings.chatHistory);
+    this.#heading.textContent = strings.chats;
+    this.#newButton.textContent = strings.newChat;
+    this.#closeButton.title = strings.closeHistory;
+    this.#closeButton.setAttribute("aria-label", strings.closeHistory);
+    this.#filter.placeholder = strings.searchConversations;
+    this.#filter.setAttribute("aria-label", strings.searchConversations);
+    this.#renderList();
+  }
+
+  isOpen(): boolean {
+    return !this.element.hidden;
+  }
+
+  open(): void {
+    if (this.isOpen()) {
+      return;
+    }
+    // Remember what had focus so it's restored on close, then move focus into
+    // the panel (its first control) so keyboard users land inside the dialog.
+    this.#lastFocused = openerElement(
+      this.element.getRootNode() as Document | ShadowRoot,
+    ) as HTMLElement | null;
+    this.element.hidden = false;
+    this.#newButton.focus();
+  }
+
+  close(): void {
+    if (!this.isOpen()) {
+      return;
+    }
+    this.element.hidden = true;
+    this.#lastFocused?.focus();
+    this.#lastFocused = null;
+  }
+
+  toggle(): void {
+    if (this.isOpen()) {
+      this.close();
+    } else {
+      this.open();
+    }
+  }
+
+  /** The currently-focused element within the drawer's root (shadow-aware). */
+  #activeElement(): Element | null {
+    return (this.element.getRootNode() as Document | ShadowRoot).activeElement;
+  }
+
+  /** Escape-to-close and a Tab focus trap while the dialog is open. */
+  #onPanelKeydown(event: KeyboardEvent): void {
+    if (event.key === "Escape") {
+      event.preventDefault();
+      this.close();
+      return;
+    }
+    if (event.key !== "Tab") {
+      return;
+    }
+    const focusables = Array.from(
+      this.#panel.querySelectorAll<HTMLElement>("button, input, [tabindex]"),
+    ).filter((el) => !el.hidden);
+    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();
+    }
+  }
+
+  /** Choose when the search box shows; the host's `data-threads-search`. */
+  setSearchMode(mode: ThreadsSearch): void {
+    this.#search = mode;
+    this.#renderList();
+  }
+
+  /** Render the rows (or the empty state), highlighting the active thread. */
+  setThreads(threads: readonly ThreadMeta[], activeId: string): void {
+    this.#threads = threads;
+    this.#activeId = activeId;
+    this.#renderList();
+  }
+
+  #renderList(): void {
+    this.#list.replaceChildren();
+    const hideFilter =
+      this.#search === "auto" ? this.#threads.length < FILTER_FROM : this.#search === "never";
+    this.#filter.hidden = hideFilter;
+    // Cleared as it goes, or the query outlives the control that set it: a
+    // list that drops below the threshold while a query matches nothing shows
+    // "no conversations match that" over conversations that are right there,
+    // with nothing left on screen to clear. Reopening does not help either --
+    // only a new drawer would.
+    if (hideFilter && this.#query !== "") {
+      this.#filter.value = "";
+      this.#query = "";
+    }
+    const shown = this.#matching();
+    if (shown.length === 0) {
+      const empty = document.createElement("div");
+      empty.className = "drawer-empty";
+      empty.setAttribute("part", "drawer-empty");
+      // Two different situations wearing one sentence would be a small lie:
+      // "no conversations yet" reads as data loss when what happened is that a
+      // filter matched nothing.
+      empty.textContent =
+        this.#threads.length === 0 ? this.#strings.noConversations : this.#strings.noMatches;
+      this.#list.appendChild(empty);
+      return;
+    }
+    const groups = this.#groups(shown);
+    for (const [label, metas] of groups) {
+      // One group would label the whole list, which says nothing the rows do not.
+      if (groups.length > 1) {
+        const heading = document.createElement("div");
+        heading.className = "drawer-group-label";
+        heading.setAttribute("part", "drawer-group-label");
+        heading.setAttribute("role", "heading");
+        heading.setAttribute("aria-level", "3");
+        heading.textContent = label;
+        this.#list.appendChild(heading);
+      }
+      for (const meta of metas) {
+        this.#list.appendChild(this.#renderRow(meta));
+      }
+    }
+  }
+
+  /**
+   * The rows by age from local midnight, in list order within each group, empty
+   * groups dropped. A date that does not parse is never today, so it lands in Older.
+   */
+  #groups(shown: readonly ThreadMeta[]): [string, ThreadMeta[]][] {
+    const now = new Date();
+    const today = new Date(now.getFullYear(), now.getMonth(), now.getDate()).getTime();
+    const recent: ThreadMeta[] = [];
+    const week: ThreadMeta[] = [];
+    const older: ThreadMeta[] = [];
+    for (const meta of shown) {
+      const at = meta.updatedAt;
+      (at >= today ? recent : at >= today - 7 * DAY_MS ? week : older).push(meta);
+    }
+    const groups: [string, ThreadMeta[]][] = [
+      [this.#strings.threadsToday, recent],
+      [this.#strings.threadsPreviousWeek, week],
+      [this.#strings.threadsOlder, older],
+    ];
+    return groups.filter(([, metas]) => metas.length > 0);
+  }
+
+  /**
+   * The rows the filter leaves.
+   *
+   * Title and preview both, because the title is often the model's summary of
+   * a conversation and the thing being looked for is as likely to be a phrase
+   * from inside it. Client-side over what the drawer already holds: the server
+   * index is fetched whole, so a query would be a round trip to filter a list
+   * already in memory.
+   */
+  #matching(): readonly ThreadMeta[] {
+    if (this.#query === "") {
+      return this.#threads;
+    }
+    return this.#threads.filter(
+      (meta) =>
+        meta.title.toLowerCase().includes(this.#query) ||
+        meta.preview.toLowerCase().includes(this.#query),
+    );
+  }
+
+  #renderRow(meta: ThreadMeta): HTMLDivElement {
+    const row = document.createElement("div");
+    row.className = "drawer-row";
+    row.setAttribute("part", "drawer-row");
+    if (meta.threadId === this.#activeId) {
+      row.classList.add("drawer-row--active");
+    }
+
+    const select = document.createElement("button");
+    select.type = "button";
+    select.className = "drawer-row-select";
+    select.setAttribute("part", "drawer-row-select");
+    const title = document.createElement("span");
+    title.className = "drawer-row-title";
+    title.setAttribute("part", "drawer-row-title");
+    title.textContent = meta.title;
+    const time = document.createElement("span");
+    time.className = "drawer-row-time";
+    time.setAttribute("part", "drawer-row-time");
+    time.textContent = this.#formatTime(meta.updatedAt);
+    const preview = document.createElement("span");
+    preview.className = "drawer-row-preview";
+    preview.setAttribute("part", "drawer-row-preview");
+    preview.textContent = meta.preview;
+    select.append(title, time, preview);
+    select.addEventListener("click", () => {
+      this.close();
+      this.#callbacks.onSelect(meta.threadId);
+    });
+
+    const rename = document.createElement("button");
+    rename.type = "button";
+    rename.className = "drawer-row-rename";
+    rename.setAttribute("part", "drawer-row-rename");
+    rename.title = this.#strings.rename;
+    rename.setAttribute("aria-label", this.#strings.renameConversation);
+    rename.textContent = "✎";
+    rename.addEventListener("click", () => this.#startRename(row, meta));
+
+    const remove = document.createElement("button");
+    remove.type = "button";
+    remove.className = "drawer-row-delete";
+    remove.setAttribute("part", "drawer-row-delete");
+    remove.title = this.#strings.delete;
+    remove.setAttribute("aria-label", this.#strings.deleteConversation);
+    remove.textContent = "🗑";
+    remove.addEventListener("click", () => this.#confirmDelete(row, meta));
+
+    const actions = document.createElement("div");
+    actions.className = "drawer-row-actions";
+    actions.setAttribute("part", "drawer-row-actions");
+    actions.append(rename, remove);
+
+    row.append(select, actions);
+    return row;
+  }
+
+  /** Swap a row for an inline rename input; Enter/blur commits, Escape cancels. */
+  #startRename(row: HTMLDivElement, meta: ThreadMeta): void {
+    const input = document.createElement("input");
+    input.type = "text";
+    input.className = "drawer-rename-input";
+    input.setAttribute("part", "drawer-rename-input");
+    input.value = meta.title;
+    // One-shot: Enter, Escape, and blur can all fire for a single edit (Enter
+    // commits and re-renders, which blurs the detached input); the flag makes
+    // the later events no-ops so a rename isn't submitted twice.
+    let done = false;
+    const commit = (): void => {
+      if (done) {
+        return;
+      }
+      done = true;
+      const value = input.value.trim();
+      if (value === "" || value === meta.title) {
+        this.#renderList();
+      } else {
+        this.#callbacks.onRename(meta.threadId, value);
+      }
+    };
+    const cancel = (): void => {
+      if (done) {
+        return;
+      }
+      done = true;
+      this.#renderList();
+    };
+    input.addEventListener("keydown", (event) => {
+      if (event.key === "Enter") {
+        event.preventDefault();
+        commit();
+      } else if (event.key === "Escape") {
+        // Stop the panel's Escape handler from also closing the drawer.
+        event.preventDefault();
+        event.stopPropagation();
+        cancel();
+      }
+    });
+    input.addEventListener("blur", () => commit());
+    row.replaceChildren(input);
+    input.focus();
+    input.select();
+  }
+
+  /** Swap a row for an inline "Delete? [Delete] [Cancel]" confirm. */
+  #confirmDelete(row: HTMLDivElement, meta: ThreadMeta): void {
+    const confirm = document.createElement("div");
+    confirm.className = "drawer-confirm";
+    confirm.setAttribute("part", "drawer-confirm");
+    const label = document.createElement("span");
+    label.className = "drawer-confirm-label";
+    label.setAttribute("part", "drawer-confirm-label");
+    label.textContent = this.#strings.deletePrompt;
+    const yes = document.createElement("button");
+    yes.type = "button";
+    yes.className = "drawer-confirm-yes";
+    yes.setAttribute("part", "drawer-confirm-yes");
+    yes.textContent = this.#strings.delete;
+    yes.addEventListener("click", () => this.#callbacks.onDelete(meta.threadId));
+    const no = document.createElement("button");
+    no.type = "button";
+    no.className = "drawer-confirm-no";
+    no.setAttribute("part", "drawer-confirm-no");
+    no.textContent = this.#strings.cancel;
+    no.addEventListener("click", () => this.#renderList());
+    confirm.append(label, yes, no);
+    row.replaceChildren(confirm);
+  }
+}

package/src/ui/history/utils.ts

@@ -0,0 +1,11 @@
+export function openerElement(root: Document | ShadowRoot): Element | null {
+  const inside = root.activeElement;
+  if (inside !== null) {
+    return inside;
+  }
+  let active: Element | null = document.activeElement;
+  while (active?.shadowRoot?.activeElement) {
+    active = active.shadowRoot.activeElement;
+  }
+  return active === document.body ? null : active;
+}

package/src/ui/interrupts/approval_card.ts

@@ -0,0 +1,202 @@
+import { DEFAULT_UI_STRINGS, type UiStrings } from "../ui_strings.js";
+
+/** What the inline approval card displays for one server-side-tool interrupt. */
+export interface ApprovalRequest {
+  /**
+   * Human-readable prompt from the AG-UI interrupt (e.g.
+   * `Approve delete_thing({…})?`). Falls back to the generic
+   * {@link UiStrings.approvalPrompt} when the interrupt carries no message.
+   */
+  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. */
+function actionButton(modifier: string, label: string): HTMLButtonElement {
+  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;
+}
+
+/** Options for {@link requestApproval}. */
+export interface ApprovalOptions {
+  /**
+   * Aborting this signal resolves the card as denied, with buttons disabled and
+   * `data-resolved="denied"` — how a Stop control dismisses a pending approval.
+   */
+  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;
+}
+
+/**
+ * A fully custom renderer for a server-side-tool approval, set via
+ * `AgUiChat.approvalRenderer`. Receives the {@link ApprovalRequest} and an
+ * `AbortSignal` that fires when the run is stopped, and resolves `true` to
+ * approve or `false` to deny. Replaces the built-in {@link requestApproval}
+ * card entirely, the host owning the DOM; to restyle the built-in card instead,
+ * use the `strings` and `::part()` seams.
+ */
+export type ApprovalRenderer = (
+  request: ApprovalRequest,
+  options: { signal: AbortSignal },
+) => Promise<boolean>;
+
+/**
+ * Append an inline approval card to `host` and resolve `true` to run a gated
+ * server-side tool or `false` to deny it.
+ *
+ * Distinct from the client-tool confirmation card
+ * ({@link requestConfirmation}): a gated server tool defers instead of
+ * executing, so the run finishes on an AG-UI interrupt the client answers with
+ * `resume[]`, and this is the browser half of that loop. Unlike the
+ * confirmation card, this one stays in the transcript as a resolved record,
+ * buttons disabled and `data-resolved` set.
+ */
+export function requestApproval(
+  host: Node & ParentNode,
+  request: ApprovalRequest,
+  options: ApprovalOptions = {},
+): Promise<boolean> {
+  const strings = options.strings ?? DEFAULT_UI_STRINGS;
+  return new Promise<boolean>((resolve) => {
+    const card = document.createElement("div");
+    card.className = "approval";
+    card.setAttribute("part", "approval");
+    if (request.toolName !== undefined) {
+      card.setAttribute("data-tool-name", request.toolName);
+    }
+    card.setAttribute("role", "group");
+    card.setAttribute("aria-label", strings.approveAction);
+
+    const body = document.createElement("div");
+    body.className = "approval-body";
+    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");
+
+    const deny = actionButton("deny", strings.deny);
+    const approve = actionButton("approve", strings.approve);
+
+    let settled = false;
+    const close = (approved: boolean): void => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      deny.disabled = true;
+      approve.disabled = true;
+      card.setAttribute("data-resolved", approved ? "approved" : "denied");
+      resolve(approved);
+    };
+
+    deny.addEventListener("click", () => close(false));
+    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, ...(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.
+      close(false);
+      return;
+    }
+    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;
+    },
+  };
+}