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

package/src/ui/composer/skill_styles.ts

@@ -0,0 +1,120 @@
+// Skills and suggestions over the composer: the chip rows and the / palette.
+export const SKILL_STYLES: string = `
+/* Skills — chips row + the /-command palette, above the input. */
+.skill-chips {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  padding: 10px 12px;
+}
+
+/* The row is hidden whenever the host offers no skills, which is most elements
+   most of the time, and an author display beats the user-agent rule for the
+   hidden attribute. Without this it kept its padding: 20px of panel between
+   the transcript and the composer, under every placement, reading as the gap
+   under whatever the transcript ends with. */
+.skill-chips[hidden] {
+  display: none;
+}
+
+.skill-chip {
+  border: 1px solid var(--_border);
+  border-radius: 999px;
+  padding: 4px 12px;
+  font: inherit;
+  font-size: 0.9em;
+  cursor: pointer;
+  background: var(--_assistant-bg);
+  color: var(--_fg);
+}
+
+.skill-chip:hover {
+  border-color: var(--_accent);
+}
+
+/* Follow-up suggestion chips. Deliberately the skill chips' shape rather than a
+   second chip vocabulary -- both are "a question you could ask", and the only
+   difference is who chose it. Inside the transcript, so they scroll with the
+   answer they follow instead of hovering above the composer. */
+.suggestions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  align-self: stretch;
+}
+
+.suggestion-chip {
+  border: 1px solid var(--_border);
+  border-radius: 999px;
+  padding: 4px 12px;
+  font: inherit;
+  font-size: 0.9em;
+  text-align: left;
+  cursor: pointer;
+  background: var(--_assistant-bg);
+  color: var(--_fg);
+}
+
+.suggestion-chip:hover,
+.suggestion-chip:focus-visible {
+  border-color: var(--_accent);
+}
+
+.skill-palette {
+  margin: 8px 12px 0;
+  display: flex;
+  flex-direction: column;
+  max-height: 220px;
+  overflow: auto;
+  /* Scrolling past the end of this must not scroll the page behind it. */
+  overscroll-behavior: contain;
+  background: var(--_bg);
+  border: 1px solid var(--_border);
+  border-radius: 8px;
+  box-shadow: 0 8px 24px rgba(20, 20, 50, 0.16);
+}
+
+/* Closed nearly all of the time and mounted on every element. The display
+   above beats the user-agent rule for the hidden attribute, so without this a
+   closed palette still painted its margin, border and shadow as a line over
+   the composer. */
+.skill-palette[hidden] {
+  display: none;
+}
+
+.skill-item {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  align-items: flex-start;
+  padding: 8px 12px;
+  border: none;
+  background: none;
+  font: inherit;
+  text-align: left;
+  cursor: pointer;
+  color: var(--_fg);
+}
+
+.skill-item[aria-selected="true"] {
+  background: var(--_assistant-bg);
+}
+
+.skill-item-title {
+  font-weight: 600;
+}
+
+.skill-item-desc {
+  font-size: 0.85em;
+  color: var(--_muted);
+}
+
+/* The hint sits directly above the composer's top border, so a zero bottom
+   margin left the text touching the divider. */
+.skill-hint {
+  margin: 8px 12px;
+  font-size: 0.85em;
+  line-height: 1.4;
+  color: var(--_danger);
+}
+`;

package/src/ui/composer/skills_menu.ts

@@ -0,0 +1,188 @@
+import type { Skill } from "../../skills/skill.js";
+
+/**
+ * The two skill surfaces over a single catalog: a chips row (the `chip: true`
+ * subset) and a slash-command palette (all skills, filtered). Both opt-in.
+ * Pure DOM; the host appends {@link chips} and {@link palette}, feeds input via
+ * {@link onInput} / {@link onKeydown}, and acts on {@link onPick}.
+ */
+export class SkillsMenu {
+  /** Chips row — append above the input. Hidden unless chips are enabled and present. */
+  readonly chips: HTMLDivElement;
+  /** The `/`-command dropdown — append in the input area. Hidden until opened. */
+  readonly palette: HTMLDivElement;
+
+  readonly #onPick: (skill: Skill) => void;
+  #skills: readonly Skill[] = [];
+  #chipsEnabled = false;
+  #slashEnabled = false;
+  #filtered: Skill[] = [];
+  #activeIndex = 0;
+
+  constructor(onPick: (skill: Skill) => void) {
+    this.#onPick = onPick;
+    this.chips = document.createElement("div");
+    this.chips.className = "skill-chips";
+    this.chips.setAttribute("part", "skill-chips");
+    this.chips.hidden = true;
+    this.palette = document.createElement("div");
+    this.palette.className = "skill-palette";
+    this.palette.setAttribute("part", "skill-palette");
+    this.palette.setAttribute("role", "listbox");
+    this.palette.hidden = true;
+  }
+
+  /** Replace the catalog (both surfaces re-derive from it). */
+  setSkills(skills: readonly Skill[]): void {
+    this.#skills = skills;
+    this.#renderChips();
+  }
+
+  enableChips(enabled: boolean): void {
+    this.#chipsEnabled = enabled;
+    this.#renderChips();
+  }
+
+  enableSlash(enabled: boolean): void {
+    this.#slashEnabled = enabled;
+  }
+
+  /** Whether the palette is currently open. */
+  isOpen(): boolean {
+    return !this.palette.hidden;
+  }
+
+  /**
+   * React to an input value change: open + filter the palette when slash mode
+   * is on and the value starts with `/`, otherwise close it.
+   */
+  onInput(value: string): void {
+    if (this.#slashEnabled && value.startsWith("/")) {
+      this.#open(value.slice(1));
+    } else {
+      this.close();
+    }
+  }
+
+  /**
+   * Handle a keydown while the palette is open. Returns ``true`` when consumed
+   * (the host should `preventDefault` and skip its own handling).
+   */
+  onKeydown(event: KeyboardEvent): boolean {
+    if (!this.isOpen()) {
+      return false;
+    }
+    if (event.key === "ArrowDown") {
+      this.#move(1);
+      return true;
+    }
+    if (event.key === "ArrowUp") {
+      this.#move(-1);
+      return true;
+    }
+    if (event.key === "Escape") {
+      this.close();
+      return true;
+    }
+    if (event.key === "Enter") {
+      // `slice(i, i+1)` yields a 0-or-1 element array; forEach gives a
+      // definite Skill (no indexed-access `| undefined`).
+      this.#filtered.slice(this.#activeIndex, this.#activeIndex + 1).forEach((skill) => {
+        this.#pick(skill);
+      });
+      return true;
+    }
+    return false;
+  }
+
+  /** Close the palette. */
+  close(): void {
+    this.palette.hidden = true;
+    this.palette.replaceChildren();
+  }
+
+  #open(query: string): void {
+    const needle = query.trim().toLowerCase();
+    const matches = this.#skills.filter(
+      (skill) =>
+        skill.name.toLowerCase().includes(needle) || skill.title.toLowerCase().includes(needle),
+    );
+    if (matches.length === 0) {
+      this.close();
+      return;
+    }
+    this.#filtered = matches;
+    this.#activeIndex = 0;
+    this.#renderPalette();
+    this.palette.hidden = false;
+  }
+
+  #move(delta: number): void {
+    const count = this.#filtered.length;
+    this.#activeIndex = (this.#activeIndex + delta + count) % count;
+    this.#renderPalette();
+  }
+
+  #pick(skill: Skill): void {
+    this.close();
+    this.#onPick(skill);
+  }
+
+  #renderChips(): void {
+    this.chips.replaceChildren();
+    const chipSkills = this.#chipsEnabled
+      ? this.#skills.filter((skill) => skill.chip === true)
+      : [];
+    this.chips.hidden = chipSkills.length === 0;
+    for (const skill of chipSkills) {
+      const button = document.createElement("button");
+      button.type = "button";
+      button.className = "skill-chip";
+      button.setAttribute("part", "skill-chip");
+      button.textContent = skill.title;
+      // The chip stays a label — it is a one-click affordance, not something to
+      // memorise — but naming the command it stands for makes the two
+      // discoverable as the same thing.
+      button.title = `/${skill.name}`;
+      button.addEventListener("click", () => this.#pick(skill));
+      this.chips.appendChild(button);
+    }
+  }
+
+  #renderPalette(): void {
+    this.palette.replaceChildren();
+    this.#filtered.forEach((skill, index) => {
+      const item = document.createElement("button");
+      item.type = "button";
+      item.className = "skill-item";
+      item.setAttribute("part", "skill-item");
+      item.setAttribute("role", "option");
+      item.setAttribute("aria-selected", index === this.#activeIndex ? "true" : "false");
+
+      const title = document.createElement("span");
+      title.className = "skill-item-title";
+      title.setAttribute("part", "skill-item-title");
+
+      // The token leads, because it is the thing the user has to type. A row
+      // showing only the label taught the label and not the command, so the
+      // palette could not be used to learn its own vocabulary.
+      const token = document.createElement("code");
+      token.className = "skill-item-token";
+      token.setAttribute("part", "skill-item-token");
+      token.textContent = `/${skill.name}`;
+      title.append(token, document.createTextNode(` ${skill.title}`));
+      item.appendChild(title);
+
+      if (skill.description !== undefined) {
+        const desc = document.createElement("span");
+        desc.className = "skill-item-desc";
+        desc.setAttribute("part", "skill-item-desc");
+        desc.textContent = skill.description;
+        item.appendChild(desc);
+      }
+
+      item.addEventListener("click", () => this.#pick(skill));
+      this.palette.appendChild(item);
+    });
+  }
+}

package/src/ui/composer/voice_input.ts

@@ -0,0 +1,282 @@
+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. */
+type VoiceState = "idle" | "recording" | "transcribing";
+
+/**
+ * How long one recording may run before it stops itself.
+ *
+ * Two minutes is a ceiling, not a target: dictating into a chat composer is a
+ * sentence or two, and two minutes of speech is roughly 350 words — longer than
+ * any message this control is for. What it bounds is the case that has no end
+ * at all, a mic left live in a forgotten tab: about a megabyte of accumulated
+ * Opus, a recording indicator the user is no longer watching, and eventually a
+ * multipart upload no client-side check sizes.
+ *
+ * Hitting it stops and transcribes; the audio is never discarded, because a cap
+ * the user was not told about must not cost them the words they already spoke.
+ */
+const MAX_RECORDING_MS = 120_000;
+
+/** Construction options for {@link VoiceInput}. */
+export interface VoiceInputOptions {
+  /** Turns a recorded clip into text (the built-in or a custom transport). */
+  readonly transcribe: TranscribeHandler;
+  /** Called with the transcript when a recording transcribes successfully. */
+  readonly onText: (text: string) => void;
+  /** UI string table (labels/tooltips). */
+  readonly strings?: UiStrings;
+}
+
+/**
+ * The composer's voice-input control: a mic button that records via
+ * `MediaRecorder`, then POSTs the clip through a {@link TranscribeHandler} and
+ * hands the transcript back via `onText`.
+ *
+ * Click to start recording, which prompts for mic permission, and again to stop
+ * and transcribe. The button reflects its `idle` / `recording` / `transcribing`
+ * state on `data-state` for theming and is exposed as `part="voice-button"`; a
+ * capture or transcription failure returns it to idle and surfaces the message
+ * on its tooltip.
+ *
+ * Pure DOM. The host mounts {@link element} in the input row.
+ */
+export class VoiceInput {
+  /** The mic button; mount this in the composer. */
+  readonly element: HTMLButtonElement;
+
+  readonly #transcribe: TranscribeHandler;
+  readonly #onText: (text: string) => void;
+  readonly #strings: UiStrings;
+  #state: VoiceState = "idle";
+  #recorder: MediaRecorder | null = null;
+  #stream: MediaStream | null = null;
+  #chunks: Blob[] = [];
+  #capTimer: ReturnType<typeof setTimeout> | null = null;
+  #hitCap = false;
+  #disposed = false;
+  /** Identifies the newest start; an older one that settles is stale. */
+  #startToken: object = {};
+
+  constructor(options: VoiceInputOptions) {
+    this.#transcribe = options.transcribe;
+    this.#onText = options.onText;
+    this.#strings = options.strings ?? DEFAULT_UI_STRINGS;
+
+    this.element = document.createElement("button");
+    this.element.type = "button";
+    this.element.className = "voice-btn";
+    this.element.setAttribute("part", "voice-button");
+    // The mic glyph, in a slot so a host can project its own mark. Author-written
+    // constant markup, never user or server data.
+    const glyph = document.createElement("slot");
+    glyph.name = "icon-voice";
+    glyph.innerHTML = ICON_VOICE;
+    this.element.append(glyph);
+    this.#setState("idle");
+    this.element.addEventListener("click", () => {
+      void this.toggle();
+    });
+  }
+
+  /** Start recording when idle, stop (and transcribe) when recording. */
+  async toggle(): Promise<void> {
+    if (this.#state === "recording") {
+      this.#stop();
+      return;
+    }
+    if (this.#state === "transcribing") {
+      return;
+    }
+    await this.#start();
+  }
+
+  async #start(): Promise<void> {
+    // The button reads idle for the whole of the permission prompt, so a second
+    // click during it is a second start. The latest click wins: this token is
+    // replaced by every start, and whichever one settles while it is not the
+    // newest is stale. It is a token and not an in-flight flag on purpose:
+    // getUserMedia may never settle (a dismissed prompt), and a flag waiting
+    // for it would leave the button dead until reload.
+    const token = {};
+    this.#startToken = token;
+    let stream: MediaStream | null;
+    try {
+      stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+    } catch {
+      stream = null;
+    }
+    if (token !== this.#startToken || this.#disposed) {
+      // Superseded by a later click, or the prompt outlived the control: the
+      // element left, or user-key changed, while it was open. Whatever this
+      // call was granted is released and nothing shared is touched: #stream,
+      // #recorder and the cap timer belong to the newer start, and recording
+      // now on a disposed control would light the browser's indicator for a
+      // button nobody can see or stop (dispose has already run, so nothing
+      // else would ever release these tracks). A refusal is dropped the same
+      // way, so a click nobody is waiting on draws no error over the newer one.
+      for (const track of stream?.getTracks() ?? []) {
+        track.stop();
+      }
+      return;
+    }
+    if (stream === null) {
+      this.#fail(this.#strings.transcriptionFailed);
+      return;
+    }
+    this.#stream = stream;
+    this.#chunks = [];
+    this.#hitCap = false;
+    let recorder: MediaRecorder;
+    try {
+      recorder = new MediaRecorder(stream);
+      recorder.addEventListener("dataavailable", (event) => {
+        this.#chunks.push(event.data);
+      });
+      recorder.addEventListener("stop", () => {
+        void this.#finish(recorder.mimeType);
+      });
+      this.#recorder = recorder;
+      recorder.start();
+    } catch {
+      // A granted stream the browser will not record: one whose tracks have
+      // already ended (Chromium throws NotSupportedError from start), a device
+      // that went away between the grant and the start, or no MediaRecorder at
+      // all. It is a refused mic by another route, so it ends the same way: the
+      // tracks are released (the stream is already stored, and nothing else
+      // would stop it), the button shows the failure, and nothing reaches the
+      // click handler, which discards the promise. A recorder whose start threw
+      // can still report "recording" and still holds its listeners, but #fail
+      // clears #recorder, so neither #stop nor dispose can reach it and its stop
+      // listener never runs #finish.
+      this.#fail(this.#strings.transcriptionFailed);
+      return;
+    }
+    // Nothing else ends a recording: `MediaRecorder` runs until it is told to
+    // stop, so without this the only exits are a second click and `dispose()`.
+    this.#capTimer = setTimeout(() => {
+      this.#hitCap = true;
+      this.#stop();
+    }, MAX_RECORDING_MS);
+    this.#setState("recording");
+  }
+
+  #stop(): void {
+    this.#clearCap();
+    // ``stop`` flushes a final ``dataavailable`` then fires ``stop`` → #finish.
+    this.#recorder?.stop();
+  }
+
+  /** Drop the cap timer; recording is over, by whichever route. */
+  #clearCap(): void {
+    if (this.#capTimer !== null) {
+      clearTimeout(this.#capTimer);
+      this.#capTimer = null;
+    }
+  }
+
+  /**
+   * Tear the control down, for a host element removed mid-recording or handed
+   * to the next principal. Stops any live `MediaRecorder`, releases the mic
+   * tracks so the browser's recording indicator clears, and suppresses the
+   * pending transcription — a disconnected control must not fire `onText` into
+   * a detached element.
+   *
+   * Disposal is final: nothing un-disposes an instance, and the host's next
+   * wiring builds a new one. So the disposed flag alone tells a continuation
+   * that outlived the control from a live one, and a clip already posted when this runs is
+   * dropped whenever its answer arrives.
+   */
+  dispose(): void {
+    this.#disposed = true;
+    this.#clearCap();
+    if (this.#recorder !== null && this.#recorder.state !== "inactive") {
+      this.#recorder.stop();
+    }
+    this.#recorder = null;
+    this.#releaseStream();
+  }
+
+  async #finish(mimeType: string): Promise<void> {
+    if (this.#disposed) {
+      return;
+    }
+    this.#releaseStream();
+    this.#setState("transcribing");
+    const audio = new Blob(this.#chunks, { type: mimeType || "audio/webm" });
+    try {
+      const text = await this.#transcribe(audio);
+      if (this.#disposed) {
+        // Disposed while the clip was in flight. The check above ran before the
+        // await and cannot see this: on a change of user-key the host disposes
+        // and wires a fresh mic over the same composer, so delivering now
+        // would put the previous principal's words in the next one's box.
+        // The button is left as it was, too: it is no longer this control's
+        // to change.
+        return;
+      }
+      this.#setState("idle");
+      if (this.#hitCap) {
+        // #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 = fillUiString(this.#strings.recordingLimit, {
+          n: MAX_RECORDING_MS / 60_000,
+        });
+      }
+      if (text !== "") {
+        this.#onText(text);
+      }
+    } catch (error) {
+      this.#fail(error instanceof Error ? error.message : this.#strings.transcriptionFailed);
+    } finally {
+      this.#recorder = null;
+    }
+  }
+
+  /** Stop the mic tracks so the browser's recording indicator clears. */
+  #releaseStream(): void {
+    for (const track of this.#stream?.getTracks() ?? []) {
+      track.stop();
+    }
+    this.#stream = null;
+  }
+
+  #fail(message: string): void {
+    // A transcription that fails can settle after dispose. (A refused prompt
+    // cannot reach here that way: #start drops a stale or disposed refusal
+    // before it calls this.) A disposed control has nothing to release and no
+    // tooltip to draw.
+    if (this.#disposed) {
+      return;
+    }
+    this.#releaseStream();
+    this.#recorder = null;
+    this.#setState("idle");
+    this.element.title = message;
+  }
+
+  #setState(state: VoiceState): void {
+    this.#state = state;
+    this.element.dataset["state"] = state;
+    const label = this.#labelFor(state);
+    this.element.title = label;
+    this.element.setAttribute("aria-label", label);
+    this.element.setAttribute("aria-pressed", String(state === "recording"));
+    // The control is inert while a clip transcribes (no second recording yet).
+    this.element.disabled = state === "transcribing";
+  }
+
+  #labelFor(state: VoiceState): string {
+    if (state === "recording") {
+      return this.#strings.stopRecording;
+    }
+    if (state === "transcribing") {
+      return this.#strings.transcribing;
+    }
+    return this.#strings.recordVoice;
+  }
+}

package/src/ui/excerpts/attach_copy_buttons.ts

@@ -0,0 +1,73 @@
+import type { UiStrings } from "../ui_strings.js";
+
+/** How long the button shows its "copied" confirmation before reverting. */
+const CONFIRM_MS = 1500;
+
+/**
+ * Give every fenced code block in `root` a copy button.
+ *
+ * Call only on finished bubbles: the streaming bubble reassigns its `innerHTML`
+ * on every delta, so a button attached mid-stream is discarded and rebuilt for
+ * each one.
+ *
+ * Idempotent — a bubble already processed is skipped, so a re-render or a second
+ * call cannot stack buttons.
+ */
+export function attachCopyButtons(root: ParentNode, strings: UiStrings): void {
+  for (const pre of Array.from(root.querySelectorAll("pre"))) {
+    const code = pre.querySelector("code");
+    if (code === null || pre.querySelector(".code-copy") !== null) {
+      continue;
+    }
+    pre.classList.add("has-copy");
+    pre.append(button(code, strings));
+  }
+}
+
+function button(code: Element, strings: UiStrings): HTMLButtonElement {
+  // Never null: `textContent` is nullable only on documents and doctypes,
+  // and this is always the `code` element `querySelector` just returned.
+  const text = code.textContent as string;
+  const copy = document.createElement("button");
+  copy.type = "button";
+  copy.className = "code-copy";
+  copy.setAttribute("part", "code-copy");
+  copy.textContent = strings.copyCode;
+  copy.title = strings.copyCode;
+  copy.setAttribute("aria-label", strings.copyCode);
+  copy.addEventListener("click", () => {
+    void writeText(text).then((ok) => {
+      // Report the real outcome: a button that always claims success leaves the
+      // reader pasting stale clipboard content.
+      confirm(copy, ok ? strings.copied : strings.copyFailed, strings);
+    });
+  });
+  return copy;
+}
+
+/**
+ * Copy `text`, reporting whether it landed. The Clipboard API needs a secure
+ * context and a user gesture and is absent in some embeddings, so failure is an
+ * ordinary outcome rather than an error to throw at the host page.
+ */
+async function writeText(text: string): Promise<boolean> {
+  const clipboard = navigator.clipboard;
+  if (clipboard === undefined) {
+    return false;
+  }
+  try {
+    await clipboard.writeText(text);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function confirm(copy: HTMLButtonElement, message: string, strings: UiStrings): void {
+  copy.textContent = message;
+  copy.dataset["state"] = message === strings.copied ? "copied" : "failed";
+  setTimeout(() => {
+    copy.textContent = strings.copyCode;
+    delete copy.dataset["state"];
+  }, CONFIRM_MS);
+}