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

package/src/ui/composer/composer_attachments.ts

@@ -0,0 +1,324 @@
+import {
+  ATTACHMENT_EVENT,
+  DEFAULT_ATTACHMENT_MAX_BYTES,
+  PASTE_ATTACH_CHARS,
+} from "../../constants.js";
+import type { AttachmentsDetail } from "../../core/events/attachments_detail.js";
+import { type UploadHandler, uploadAttachment } from "../../core/upload_attachment.js";
+import type { UiStrings } from "../ui_strings.js";
+import { AttachmentTray } from "./attachment_tray.js";
+
+/** What the composer's attachments need from the element that owns them. */
+export interface ComposerAttachmentsHost {
+  /** The custom element: its upload attributes, and where the event is dispatched. */
+  readonly element: HTMLElement;
+  /** The chat shell, which a file can be dropped or pasted anywhere on. */
+  readonly chat: HTMLElement;
+  /** Where the tray mounts, above the composer. */
+  readonly slot: HTMLElement;
+  /** The hidden multi-file input the paperclip opens. */
+  readonly fileInput: HTMLInputElement;
+  /** The paperclip, revealed once uploads are possible. */
+  readonly button: HTMLButtonElement;
+  /** The resolved string table. */
+  readonly strings: () => UiStrings;
+  /** The host's `uploadHandler`, read when the tray is wired. */
+  readonly uploadHandler: () => UploadHandler | null;
+  /** The headers a request to `url` carries. */
+  readonly headersFor: (url: string) => Record<string, string>;
+  /** The cookie policy every request carries, when one is configured. */
+  readonly credentialsOption: () => { credentials?: RequestCredentials };
+}
+
+/**
+ * Files handed to the composer: the tray they upload through, and the four
+ * ways into it -- the picker, a drop, a paste, and a host's `attachFile`.
+ *
+ * Owned one-to-one by an `<ag-ui-chat>`, and holding no state outside the
+ * instance.
+ */
+export class ComposerAttachments {
+  readonly #host: ComposerAttachmentsHost;
+  /** Upload tray; created on connect only when `data-attachments-url` is set. */
+  #tray: AttachmentTray | null = null;
+
+  constructor(host: ComposerAttachmentsHost) {
+    this.#host = host;
+  }
+
+  /** The tray, once uploads are wired; `null` while the chat is text-only. */
+  get tray(): AttachmentTray | null {
+    return this.#tray;
+  }
+
+  /**
+   * Enable the composer's file-upload tray when uploads are possible — either a
+   * custom `uploadHandler` is set or `data-attachments-url` provides the
+   * built-in multipart endpoint: reveal the 📎 button, wire the hidden file
+   * input + drag-and-drop, and mount the tray. With neither, the affordance
+   * stays hidden and the chat degrades to text-only.
+   *
+   * Called on every connect, so it starts by taking down the tray the last
+   * connection mounted: that one was disposed when the element left, and the
+   * attributes that decide whether there is a tray at all may have changed
+   * since. The shell outlives a connection, so its listeners go under `signal`.
+   */
+  wire(signal: AbortSignal): void {
+    this.#tray?.element.remove();
+    this.#tray = null;
+    const url = this.#host.element.getAttribute("data-attachments-url");
+    const upload = this.#host.uploadHandler() ?? this.#defaultUploadHandler(url);
+    if (upload === null) {
+      return;
+    }
+    const accept = this.#host.element.getAttribute("data-attachment-accept") ?? "";
+    // Bound to the local rather than the field: the hook can only fire from a
+    // tray that exists, so passing it removes a null check no caller can reach.
+    const tray: AttachmentTray = new AttachmentTray({
+      upload,
+      maxBytes: this.#maxBytes(),
+      accept,
+      strings: this.#host.strings(),
+      // The tray's change hook, surfaced to the host as an event. A host
+      // driving its own composer could otherwise not tell a settled upload from
+      // one still in flight, which is the state sendMessage() has to be called
+      // with knowledge of.
+      onChange: () => this.#dispatch(tray),
+    });
+    this.#tray = tray;
+    this.#host.slot.appendChild(this.#tray.element);
+    this.#host.fileInput.accept = accept;
+    this.#host.button.hidden = false;
+    this.#enableDragAndDrop(signal);
+    this.#enablePaste(tray, signal);
+  }
+
+  /** The queueing behind `AgUiChat.attachFile`, whose doc is the contract. */
+  attach(file: File): boolean {
+    if (this.#tray === null) {
+      return false;
+    }
+    this.#tray.add(file);
+    return true;
+  }
+
+  /** Queue every file from the picker into the tray, then reset the input. */
+  onFilesPicked(): void {
+    const input = this.#host.fileInput;
+    const files = input.files;
+    if (files !== null) {
+      for (const file of Array.from(files)) {
+        this.#tray?.add(file);
+      }
+    }
+    // Reset so re-picking the same file fires `change` again.
+    input.value = "";
+  }
+
+  /** The built-in multipart upload handler for `data-attachments-url`, or `null`. */
+  #defaultUploadHandler(url: string | null): UploadHandler | null {
+    if (url === null) {
+      return null;
+    }
+    // Forward the tray's abort signal so removing a chip (or tearing the
+    // element down) cancels the XHR.
+    return (file, onProgress, signal) =>
+      uploadAttachment(file, {
+        url,
+        headers: this.#host.headersFor(url),
+        ...this.#host.credentialsOption(),
+        onProgress,
+        signal,
+      });
+  }
+
+  /** The client-side upload size cap from `data-attachment-max-bytes`. */
+  #maxBytes(): number {
+    const attr = this.#host.element.getAttribute("data-attachment-max-bytes");
+    if (attr === null) {
+      return DEFAULT_ATTACHMENT_MAX_BYTES;
+    }
+    const parsed = Number.parseInt(attr, 10);
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : DEFAULT_ATTACHMENT_MAX_BYTES;
+  }
+
+  /** Accept files dropped anywhere on the chat shell into the tray. */
+  #enableDragAndDrop(signal: AbortSignal): void {
+    const chat = this.#host.chat;
+    chat.addEventListener(
+      "dragover",
+      (event) => {
+        event.preventDefault();
+        chat.classList.add("chat--dragover");
+      },
+      { signal },
+    );
+    chat.addEventListener(
+      "dragleave",
+      () => {
+        chat.classList.remove("chat--dragover");
+      },
+      { signal },
+    );
+    chat.addEventListener(
+      "drop",
+      (event) => {
+        event.preventDefault();
+        chat.classList.remove("chat--dragover");
+        const files = event.dataTransfer?.files;
+        if (files !== undefined) {
+          for (const file of Array.from(files)) {
+            this.#tray?.add(file);
+          }
+        }
+      },
+      { signal },
+    );
+  }
+
+  /**
+   * Turn a very long text paste into an attachment instead of a wall of text.
+   *
+   * A composer capped at `40vh` is not where forty thousand characters go: the
+   * user cannot read what they pasted, cannot edit around it, and sends one
+   * enormous turn. As a file it stays whole, the model still receives it, and
+   * the box is left for the question about it.
+   *
+   * Only where the host has configured uploads -- and structurally so, rather
+   * than by a check here: the paste listener is wired inside the attachment
+   * setup, so with no tray there is no listener at all and an ordinary paste is
+   * untouched. Quietly dropping a paste for being long would be far worse than
+   * an awkward composer. The tray is passed rather than read off the field for
+   * the same reason its `onChange` hook is: it can only be called from one that
+   * exists, so taking it as an argument removes a null check no caller can
+   * reach.
+   *
+   * Nothing is lost by removing the chip: the text is still on the clipboard,
+   * so pasting again brings it back. That is why this needs no undo of its own.
+   */
+  #pasteLongTextAsFile(event: ClipboardEvent, clipboard: DataTransfer, tray: AttachmentTray): void {
+    const threshold = this.#pasteAttachThreshold();
+    const text = clipboard.getData("text/plain");
+    if (threshold === null || text.length < threshold) {
+      return;
+    }
+    event.preventDefault();
+    tray.add(new File([text], `pasted-${pasteStamp()}.txt`, { type: "text/plain" }));
+  }
+
+  /**
+   * How long a pasted string has to be before it becomes a file, or `null` to
+   * leave every paste in the composer.
+   *
+   * One attribute with three answers rather than three attributes: absent is
+   * the default, `off` refuses, and a number states the threshold. A value that
+   * is neither says so, because a typo silently meaning "off" is the failure
+   * this whole release keeps finding.
+   */
+  #pasteAttachThreshold(): number | null {
+    const raw = this.#host.element.getAttribute("data-paste-attach");
+    if (raw === null) {
+      return PASTE_ATTACH_CHARS;
+    }
+    if (raw === "off") {
+      return null;
+    }
+    const stated = Number.parseInt(raw, 10);
+    if (Number.isNaN(stated) || stated <= 0) {
+      console.warn(
+        `<ag-ui-chat>: data-paste-attach="${raw}" is neither "off" nor a positive ` +
+          `number of characters, so the default of ${PASTE_ATTACH_CHARS} is used.`,
+      );
+      return PASTE_ATTACH_CHARS;
+    }
+    return stated;
+  }
+
+  /**
+   * Accept files pasted into the composer.
+   *
+   * The whole tray already exists behind this: a paste is one more way to hand
+   * it a `File`, alongside the picker and a drop.
+   *
+   * Two rules keep it from stealing a paste that was never about files.
+   * `clipboardData.files` is empty for text, so ordinary pasting is untouched.
+   * And the default is only prevented when the clipboard carries **no text**:
+   * copying a rich selection that happens to contain an image puts both on the
+   * clipboard, and swallowing the words someone meant to paste in order to
+   * attach a picture they did not is the worse of the two failures.
+   */
+  #enablePaste(tray: AttachmentTray, signal: AbortSignal): void {
+    this.#host.chat.addEventListener(
+      "paste",
+      (event: ClipboardEvent) => {
+        // Nullish rather than a null check: the property is typed as nullable,
+        // and an engine that fires a plain Event for a paste leaves it absent
+        // instead, which is not the same value and is the same situation.
+        const clipboard = event.clipboardData ?? null;
+        if (clipboard === null) {
+          return;
+        }
+        const files = Array.from(clipboard.files);
+        if (files.length === 0) {
+          this.#pasteLongTextAsFile(event, clipboard, tray);
+          return;
+        }
+        if (clipboard.getData("text/plain") === "") {
+          event.preventDefault();
+        }
+        for (const file of files) {
+          this.#tray?.add(named(file));
+        }
+      },
+      { signal },
+    );
+  }
+
+  /** Tell the host what the tray now holds — see {@link ATTACHMENT_EVENT}. */
+  #dispatch(tray: AttachmentTray): void {
+    this.#host.element.dispatchEvent(
+      new CustomEvent<AttachmentsDetail>(ATTACHMENT_EVENT, {
+        detail: { attachments: tray.readyRefs(), pending: tray.pendingCount() },
+        bubbles: true,
+        composed: true,
+      }),
+    );
+  }
+}
+
+/**
+ * The moment of a paste, as a string a filename can carry.
+ *
+ * ISO 8601 with its colons and the decimal point replaced, because both are
+ * reserved in a filename on at least one platform a download lands on. Shared
+ * by the two paste paths, so a pasted image and a long text pasted as a file
+ * are named the same way.
+ */
+function pasteStamp(): string {
+  return new Date().toISOString().replace(/[:.]/g, "-");
+}
+
+/**
+ * A pasted file, guaranteed to have a name.
+ *
+ * A file dropped or picked always carries one; a pasted one need not. Some
+ * engines hand over a blob with an empty name, which travels all the way to
+ * the upload as an empty `filename` and lands on the server as a file nobody
+ * can identify -- while the chip in the tray shows an empty label. A file that
+ * already has a name keeps it, including the generic one Chrome gives a pasted
+ * screenshot: it is at least what the file is, and the chip shows the size
+ * beside it.
+ */
+function named(file: File): File {
+  if (file.name !== "") {
+    return file;
+  }
+  // The subtype is the extension for every clipboard image type worth naming.
+  // A type with no slash in it falls back to the whole string, and an absent
+  // one leaves a bare stamp rather than a name ending in a dot.
+  const subtype = file.type.split("/")[1] ?? file.type;
+  const stamp = pasteStamp();
+  return new File([file], subtype === "" ? `pasted-${stamp}` : `pasted-${stamp}.${subtype}`, {
+    type: file.type,
+  });
+}

package/src/ui/composer/composer_voice.ts

@@ -0,0 +1,93 @@
+import { type TranscribeHandler, transcribeAudio } from "../../core/transcribe_audio.js";
+import type { UiStrings } from "../ui_strings.js";
+import { VoiceInput } from "./voice_input.js";
+
+/** What the composer's mic needs from the element that owns it. */
+export interface ComposerVoiceHost {
+  /** The custom element, whose `data-transcribe-url` names the built-in endpoint. */
+  readonly element: HTMLElement;
+  /** Where the mic button mounts, in the composer's tool row. */
+  readonly slot: HTMLElement;
+  /** The composer a transcript is written into. */
+  readonly input: HTMLTextAreaElement;
+  /** The resolved string table. */
+  readonly strings: () => UiStrings;
+  /** The host's `transcribeHandler`, read when the mic is wired. */
+  readonly transcribeHandler: () => TranscribeHandler | null;
+  /** The headers a request to `url` carries. */
+  readonly headersFor: (url: string) => Record<string, string>;
+  /** The cookie policy every request carries, when one is configured. */
+  readonly credentialsOption: () => { credentials?: RequestCredentials };
+  /** React to the composer's value changing, as typing does. */
+  readonly onInput: () => void;
+}
+
+/**
+ * The composer's mic: mounted when transcription is possible, and what a
+ * transcript does to the composer.
+ *
+ * Owned one-to-one by an `<ag-ui-chat>`, and holding no state outside the
+ * instance.
+ */
+export class ComposerVoice {
+  readonly #host: ComposerVoiceHost;
+  /** Voice-input control; created on connect when transcription is available. */
+  #voice: VoiceInput | null = null;
+
+  constructor(host: ComposerVoiceHost) {
+    this.#host = host;
+  }
+
+  /**
+   * Reveal the composer's 🎤 mic button when transcription is possible — either
+   * a custom `transcribeHandler` is set or `data-transcribe-url` provides the
+   * built-in POST endpoint. The control records via `MediaRecorder` and drops
+   * the transcript into the composer; with neither configured the mic stays
+   * hidden and the chat is text-only.
+   *
+   * Called on every connect, so it starts by taking down the mic the last
+   * connection mounted, which was released when the element left.
+   */
+  wire(): void {
+    this.#voice?.element.remove();
+    this.#voice = null;
+    const url = this.#host.element.getAttribute("data-transcribe-url");
+    const transcribe = this.#host.transcribeHandler() ?? this.#defaultTranscribeHandler(url);
+    if (transcribe === null) {
+      return;
+    }
+    this.#voice = new VoiceInput({
+      transcribe,
+      onText: (text) => this.#insertText(text),
+      strings: this.#host.strings(),
+    });
+    this.#host.slot.appendChild(this.#voice.element);
+  }
+
+  /** Release the mic, so the browser's recording indicator clears. */
+  dispose(): void {
+    this.#voice?.dispose();
+  }
+
+  /** The built-in transcription handler for `data-transcribe-url`, or `null`. */
+  #defaultTranscribeHandler(url: string | null): TranscribeHandler | null {
+    if (url === null) {
+      return null;
+    }
+    return (audio) =>
+      transcribeAudio(audio, {
+        url,
+        headers: this.#host.headersFor(url),
+        ...this.#host.credentialsOption(),
+      });
+  }
+
+  /** Drop a voice transcript into the composer (appended to any typed text). */
+  #insertText(text: string): void {
+    const input = this.#host.input;
+    const current = input.value.trim();
+    input.value = current === "" ? text : `${current} ${text}`;
+    this.#host.onInput();
+    input.focus();
+  }
+}

package/src/ui/composer/voice_input.ts

@@ -1,5 +1,6 @@
 import { ICON_VOICE } from "../../constants.js";
 import type { TranscribeHandler } from "../../core/transcribe_audio.js";
+import { fillUiString } from "../fill_ui_string.js";
 import { DEFAULT_UI_STRINGS, type UiStrings } from "../ui_strings.js";
 
 /** Lifecycle of the mic button, reflected on its `data-state` for CSS. */
@@ -164,10 +165,9 @@ export class VoiceInput {
         // #setState has just reset the tooltip to the idle label, so this goes
         // after it. It says why the mic went quiet on its own — the transcript
         // below is the proof nothing was thrown away.
-        this.element.title = this.#strings.recordingLimit.replace(
-          "{n}",
-          String(MAX_RECORDING_MS / 60_000),
-        );
+        this.element.title = fillUiString(this.#strings.recordingLimit, {
+          n: MAX_RECORDING_MS / 60_000,
+        });
       }
       if (text !== "") {
         this.#onText(text);

package/src/ui/excerpts/transcript_quote_offer.ts

@@ -0,0 +1,198 @@
+import type { UiStrings } from "../ui_strings.js";
+import { attachQuoteOffer, type PageQuoteOffer } from "./page_quote_offer.js";
+import { asQuote, quotableSelection } from "./quote_selection.js";
+
+/** Pixels between a selection and the offer to quote it. */
+const QUOTE_GAP = 6;
+
+/** What the quote offer needs from the element that owns it. */
+export interface TranscriptQuoteHost {
+  /** The custom element: its opt-out attribute, and what a page offer excludes. */
+  readonly element: HTMLElement;
+  /** The shadow root a transcript selection is read through. */
+  readonly root: ShadowRoot;
+  /** The transcript, whose selections are offered. */
+  readonly messages: HTMLElement;
+  /** The transcript's positioning box, which the offer floats inside. */
+  readonly messagesWrap: HTMLElement;
+  /** The composer a quotation is written into. */
+  readonly input: HTMLTextAreaElement;
+  /** The resolved string table. */
+  readonly strings: () => UiStrings;
+  /** Resize the composer to what it now holds. */
+  readonly autoGrow: () => void;
+  /** The element's public `quote`, so a host that replaced it is the one called. */
+  readonly quote: (text: string) => void;
+}
+
+/**
+ * Quoting a selection into the composer: the offer floated beside a selection
+ * in the transcript, the same offer over the host page, and the quotation
+ * itself.
+ *
+ * Owned one-to-one by an `<ag-ui-chat>`, and holding no state outside the
+ * instance.
+ */
+export class TranscriptQuoteOffer {
+  /**
+   * Offer to quote the current selection, floated beside it.
+   *
+   * Shares the transcript's positioning box with the jump button for the same
+   * reason: it is positioned against the transcript, and must not scroll away
+   * with the words it is pointing at.
+   */
+  readonly button: HTMLButtonElement = document.createElement("button");
+
+  readonly #host: TranscriptQuoteHost;
+  /** What {@link button} would quote, while it is showing. */
+  #quoting = "";
+  /** The host-page offer, while one is attached; see {@link offerInPage}. */
+  #pageQuote: PageQuoteOffer | null = null;
+
+  constructor(host: TranscriptQuoteHost) {
+    this.#host = host;
+  }
+
+  /** The quotation behind `AgUiChat.quote`, whose doc is the contract. */
+  insert(text: string): void {
+    const quoted = asQuote(text);
+    if (quoted === "") {
+      return;
+    }
+    const input = this.#host.input;
+    // Appended after whatever is already typed, on a fresh paragraph: a second
+    // quotation is a second thing being asked about, not a replacement for the
+    // first. Trailing blank lines are dropped so repeated quoting does not
+    // accumulate gaps.
+    const current = input.value.replace(/\s+$/, "");
+    input.value = current === "" ? quoted : `${current}\n\n${quoted}`;
+    this.#host.autoGrow();
+    input.focus();
+    const end = input.value.length;
+    input.setSelectionRange(end, end);
+  }
+
+  /** The offer behind `AgUiChat.offerQuoteInPage`, whose doc is the contract. */
+  offerInPage(within: HTMLElement): () => void {
+    this.#pageQuote?.detach();
+    const offer = attachQuoteOffer({
+      within,
+      label: this.#host.strings().quoteSelection,
+      exclude: this.#host.element,
+      onQuote: (text) => this.#host.quote(text),
+    });
+    this.#pageQuote = offer;
+    return () => {
+      offer.detach();
+      if (this.#pageQuote === offer) {
+        this.#pageQuote = null;
+      }
+    };
+  }
+
+  /**
+   * Take the host-page offer down. It listens on the host's document, not on
+   * anything of ours, so nothing else would ever take it down.
+   */
+  detachPageOffer(): void {
+    this.#pageQuote?.detach();
+    this.#pageQuote = null;
+  }
+
+  /**
+   * Build the offer and listen for settled selections in the transcript.
+   *
+   * The button and the transcript outlive a connection, so the listeners go
+   * under `signal`, which the element aborts when it leaves the document.
+   */
+  mount(signal: AbortSignal): void {
+    const button = this.button;
+    button.className = "quote-selection";
+    button.type = "button";
+    button.setAttribute("part", "quote-selection");
+    button.textContent = this.#host.strings().quoteSelection;
+    button.hidden = true;
+    // `mousedown` rather than `click`: pressing anywhere else collapses the
+    // selection first, and by the time a click lands there is nothing left to
+    // quote. Preventing the default keeps the selection alive long enough to
+    // read it.
+    button.addEventListener(
+      "mousedown",
+      (event) => {
+        event.preventDefault();
+      },
+      { signal },
+    );
+    button.addEventListener(
+      "click",
+      () => {
+        this.#host.quote(this.#quoting);
+        window.getSelection()?.removeAllRanges();
+        this.#hide();
+      },
+      { signal },
+    );
+
+    // A settled selection, by either input. `mouseup` rather than
+    // `selectionchange` so the offer does not chase the pointer mid-drag; the
+    // second half of the same gesture, `mousedown`, retires the previous offer
+    // before the new selection exists.
+    const messages = this.#host.messages;
+    messages.addEventListener("mouseup", (event) => this.#onSelectionSettled(event), { signal });
+    messages.addEventListener("keyup", () => this.#onSelectionSettled(), { signal });
+    messages.addEventListener("mousedown", () => this.#hide(), { signal });
+  }
+
+  /** Whether the transcript offers to quote what the user selects. */
+  #enabled(): boolean {
+    return this.#host.element.getAttribute("data-quote-selection") !== "false";
+  }
+
+  /**
+   * Offer to quote the settled selection, or retire the offer.
+   *
+   * `event` is passed for its coordinates and only those: they say which line
+   * of a selection spanning several messages the offer should hang from. A
+   * keyboard selection has none, and the first line is used instead.
+   */
+  #onSelectionSettled(event?: MouseEvent): void {
+    if (!this.#enabled()) {
+      return;
+    }
+    const near = event === undefined ? undefined : { x: event.clientX, y: event.clientY };
+    const selected = quotableSelection(this.#host.messages, [this.#host.root], near);
+    if (selected === null) {
+      this.#hide();
+      return;
+    }
+    this.#quoting = selected.text;
+    this.#place(selected.rect);
+  }
+
+  /** Float the offer beside `rect`, kept inside the transcript's own box. */
+  #place(rect: DOMRect): void {
+    const button = this.button;
+    // Unhidden first: a hidden element measures zero, and its own size is what
+    // decides whether it fits above the selection and how far to pull it left.
+    button.hidden = false;
+    const wrap = this.#host.messagesWrap.getBoundingClientRect();
+    const top = rect.top - wrap.top;
+    // Above the selection by default, below it when there is no room --
+    // selecting the first line of the transcript is the ordinary case, not an
+    // edge one, and an offer clipped by the header is an offer nobody takes.
+    const below = top < QUOTE_GAP + button.offsetHeight;
+    button.dataset["below"] = String(below);
+    button.style.top = `${below ? rect.bottom - wrap.top + QUOTE_GAP : top - QUOTE_GAP}px`;
+    // Centred on the selection, then pulled back by its own half-width so a
+    // selection at either margin does not push the offer out of the panel.
+    const half = button.offsetWidth / 2;
+    const centre = rect.left + rect.width / 2 - wrap.left;
+    button.style.left = `${Math.min(Math.max(centre, half), wrap.width - half)}px`;
+  }
+
+  /** Retire the offer, and forget what it was pointing at. */
+  #hide(): void {
+    this.button.hidden = true;
+    this.#quoting = "";
+  }
+}

package/src/ui/fill_ui_string.ts

@@ -0,0 +1,41 @@
+/** A `{token}` placeholder, named the way every key in the string table names one. */
+const TOKEN_RE = /\{([a-zA-Z_][a-zA-Z0-9_]*)\}/g;
+
+/**
+ * Fill the `{token}` placeholders of a string-table template.
+ *
+ * Every string-table template goes through here rather than through
+ * `template.replace("{token}", value)`, which was wrong in two ways at once:
+ *
+ * - **A string replacement interprets dollar patterns in the value.** `$&`
+ *   inserts the matched token, and `` $` `` and `$'` the text either side of it,
+ *   so a queued message reading `costs $& more` was labelled
+ *   `Do not send "costs {text} more"`. Several of these values are text a user
+ *   or a server wrote -- a queued message, a tool name, a skill title, an
+ *   agent name -- so the value has to land verbatim. A replacer function's
+ *   return value is never interpreted, which is the whole fix.
+ * - **A string pattern replaces only the first occurrence**, so a translation
+ *   that uses a token twice was left half filled.
+ *
+ * One pass over the template, so a value that itself contains a `{token}` is
+ * inserted as written rather than filled in turn: a skill titled
+ * `Fill {fields}` stays that, where chained replacements filled it twice.
+ *
+ * A token with no entry in `values` is left as written. Every call site passes
+ * the tokens its key documents, so that is a translation carrying a token the
+ * call site does not know, and printing it is more honest than dropping it.
+ * `skills/fill_template.ts` is the prompt-side counterpart, and its contract is
+ * different on purpose: a prompt reports what it could not fill so a send can
+ * be refused.
+ *
+ * @param template - A string-table value, e.g. `strings.removeQueued`.
+ * @param values - The value for each token the template's key documents.
+ */
+export function fillUiString(
+  template: string,
+  values: Readonly<Record<string, string | number>>,
+): string {
+  return template.replace(TOKEN_RE, (token, key: string) =>
+    Object.hasOwn(values, key) ? String(values[key]) : token,
+  );
+}