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

package/src/ui/styles.ts

@@ -571,6 +571,7 @@ export const STYLES = `
   opacity: 0;
 }
 
+:host([collapsed]:is([placement="embedded"], [placement="page"])) .messages-wrap,
 :host([collapsed]:is([placement="embedded"], [placement="page"])) .messages,
 :host([collapsed]:is([placement="embedded"], [placement="page"])) .input-row,
 :host([collapsed]:is([placement="embedded"], [placement="page"])) .skill-chips,
@@ -579,9 +580,113 @@ export const STYLES = `
   display: none;
 }
 
+/* Jump-to-latest: shown only once the reader has scrolled away *and* missed
+   something. Anchored to the panel rather than the list so it does not scroll
+   with the content it is offering to scroll to. */
+/* The transcript's own box, and the only one whose foot is the transcript's
+   foot. The panel's foot is below the composer, the chips and the footer. */
+.messages-wrap {
+  position: relative;
+  flex: 1;
+  min-height: 0;
+  display: flex;
+  flex-direction: column;
+}
+
+.jump-latest {
+  position: absolute;
+  left: 50%;
+  transform: translateX(-50%);
+  bottom: var(--_pad);
+  z-index: 2;
+  display: none;
+  align-items: center;
+  gap: 0.35em;
+  padding: 0.4em 0.9em;
+  border: 1px solid var(--_border);
+  border-radius: 999px;
+  /* A raised surface, not the panel's own background. Reusing --_bg made the
+     pill the same colour as everything behind it, leaving a 1px border and a
+     shadow to carry the whole affordance -- and a dark-on-dark shadow carries
+     nothing. --_hover is the token that already means "lifted off the panel",
+     and it separates in both themes without competing with the accent the send
+     button owns. */
+  background: var(--_hover);
+  color: var(--_text);
+  font: inherit;
+  font-size: 0.85em;
+  cursor: pointer;
+  box-shadow: 0 2px 10px rgb(0 0 0 / 0.18);
+}
+
+.jump-latest[data-missed="true"] {
+  display: flex;
+}
+
+.jump-latest:hover {
+  border-color: var(--_accent);
+}
+
+/* The offer to quote a selection. Positioned in script against the transcript
+   box, which is the only ancestor whose top and foot are the transcript's --
+   the same reason .jump-latest lives here. The translate is the half the
+   script does not do: script sets the point the offer hangs from, CSS decides
+   which corner of the offer that point is. */
+.quote-selection {
+  position: absolute;
+  z-index: 2;
+  transform: translate(-50%, -100%);
+  padding: 0.25em 0.7em;
+  border: 1px solid var(--_border);
+  border-radius: 999px;
+  background: var(--_hover);
+  color: var(--_text);
+  font: inherit;
+  font-size: 0.8em;
+  line-height: 1.6;
+  white-space: nowrap;
+  cursor: pointer;
+  box-shadow: 0 2px 10px rgb(0 0 0 / 0.18);
+}
+
+/* Flipped under the selection when there was no room above it. Only the
+   vertical half of the translate changes: it still hangs from its own centre
+   horizontally. */
+.quote-selection[data-below="true"] {
+  transform: translate(-50%, 0);
+}
+
+.quote-selection:hover {
+  border-color: var(--_accent);
+}
+
+/* Screen-reader-only status region. Off-screen rather than display:none or
+   visibility:hidden, both of which take the element out of the accessibility
+   tree entirely -- a hidden live region announces nothing at all, which is the
+   classic way this pattern is written wrong.
+
+   The 1px box with clip-path, rather than width/height 0, is the shape that
+   survives: a zero-sized element is dropped from the tree by some engines. */
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  border: 0;
+  overflow: hidden;
+  white-space: nowrap;
+  clip-path: inset(50%);
+}
+
 .messages {
   flex: 1;
   overflow-y: auto;
+  /* The browser's own scroll anchoring competes with the scroller for the same
+     job and wins unpredictably -- it can hold the view still exactly when we
+     want to follow. Turned off so following is decided in one place. Safari
+     does not implement it, which is itself a reason not to depend on it. */
+  overflow-anchor: none;
   padding: var(--_pad);
   display: flex;
   flex-direction: column;
@@ -1090,6 +1195,21 @@ export const STYLES = `
   color: var(--_fg);
 }
 
+/* A region a host formatter took over, marked by the card. Preformatted
+   whitespace is what makes the built-in block read as written, and it is the one
+   thing a host cannot want: a table inherits it as mangled cell spacing, and a
+   sentence as line breaks nobody typed.
+
+   Whitespace only. The card's own face, frame, padding and scroll cap stay,
+   because the card is one visual object -- the head row and the status pill are
+   monospaced too -- and a region that dropped the family would be the only part
+   of it wearing a different one. A host that wants that restyles the
+   tool-card-result part, which does not need the formatter at all. */
+.tool-call-args[data-formatted],
+.tool-call-result[data-formatted] {
+  white-space: normal;
+}
+
 /* Display modes are pure visibility over one DOM shape, selected from the host
    attribute rather than a value stamped on the card at build time, so flipping
    data-tool-display re-styles cards already on screen. See ToolCallCard.
@@ -1154,6 +1274,174 @@ export const STYLES = `
   display: flex;
 }
 
+/* A delegated sub-agent's progress, inside the card that delegated. Empty on
+   every card that delegated nothing, so it collapses rather than adding a gap
+   to each one -- the same shape the approval slot uses. */
+.tool-call-subagent:empty {
+  display: none;
+}
+
+.tool-call-subagent {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.subagent {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  min-width: 0;
+}
+
+/* The collapsed row is the status and the expander at once, which is what keeps
+   a ten-step child one row until somebody opens it. Full width and left-aligned,
+   because it is a line of the card rather than a button on it. */
+.subagent-row {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  width: 100%;
+  box-sizing: border-box;
+  padding: 2px 0;
+  border: none;
+  background: none;
+  font: inherit;
+  text-align: left;
+  color: var(--_muted);
+  cursor: pointer;
+}
+
+/* Nothing behind the row yet -- a delegation that failed before calling
+   anything. Drop the affordances rather than offer a control that expands onto
+   an empty region, which is the refusal the card's own toggle already makes. */
+.subagent-row:disabled {
+  cursor: default;
+}
+
+.subagent-row::after {
+  content: "▸";
+  flex: none;
+  margin-left: auto;
+  color: var(--_accent);
+}
+
+.subagent-row[aria-expanded="true"]::after {
+  content: "▾";
+}
+
+.subagent-row:disabled::after {
+  display: none;
+}
+
+/* Empty in the DOM; the glyph is drawn here from the panel's data-phase, so a
+   host re-themes it through the same tool-icon custom properties the card uses. */
+.subagent-icon {
+  flex: none;
+  box-sizing: border-box;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 10px;
+  height: 10px;
+  font-size: 10px;
+  line-height: 1;
+}
+
+/* Anything that is not a terminal phase is the child still working. Selected by
+   what it is not, so a phase this client has not heard of still spins rather
+   than rendering as a blank. */
+.subagent[data-phase]:not([data-phase="finished"]):not([data-phase="failed"]) .subagent-icon {
+  border: 2px solid var(--_muted);
+  border-top-color: transparent;
+  border-radius: 50%;
+  animation: ag-ui-tool-spin var(--_tool-spin-duration) linear infinite;
+}
+
+.subagent[data-phase="finished"] .subagent-icon::before {
+  content: var(--_tool-icon-done);
+  color: var(--_success);
+}
+
+.subagent[data-phase="failed"] .subagent-icon::before {
+  content: var(--_tool-icon-error);
+  color: var(--_danger);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .subagent .subagent-icon {
+    animation: none;
+  }
+}
+
+/* The server's own pre-rendered line. Shrinks and wraps rather than pushing the
+   chevron out of the card, which is what a fixed-width sibling in a flex row
+   does to a panel at sidebar width. */
+.subagent-status {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow-wrap: anywhere;
+}
+
+/* The child's own calls. Indented and ruled, so the nesting is visible without
+   a second card frame around it. */
+.subagent-steps {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  margin-left: 4px;
+  padding-left: 10px;
+  border-left: 1px solid var(--_border);
+}
+
+.subagent-steps[hidden] {
+  display: none;
+}
+
+.subagent-step {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  min-width: 0;
+  color: var(--_muted);
+}
+
+.subagent-step-icon {
+  flex: none;
+  box-sizing: border-box;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 8px;
+  height: 8px;
+  font-size: 9px;
+  line-height: 1;
+}
+
+/* No outcome yet: the wire says null while the call is in flight, and the
+   absence of the attribute is how that arrives here. A hollow ring, not a
+   spinner -- several can be on screen at once and the row above already spins. */
+.subagent-step:not([data-ok]) .subagent-step-icon {
+  border: 1px solid var(--_muted);
+  border-radius: 50%;
+}
+
+.subagent-step[data-ok="true"] .subagent-step-icon::before {
+  content: var(--_tool-icon-done);
+  color: var(--_success);
+}
+
+.subagent-step[data-ok="false"] .subagent-step-icon::before {
+  content: var(--_tool-icon-error);
+  color: var(--_danger);
+}
+
+.subagent-step-name {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow-wrap: anywhere;
+}
+
 .tool-call-toggle {
   align-self: flex-start;
   border: none;
@@ -1747,6 +2035,7 @@ export const STYLES = `
 
 .confirm-actions {
   display: flex;
+  flex-wrap: wrap;
   gap: 8px;
   justify-content: flex-end;
 }
@@ -1773,6 +2062,99 @@ export const STYLES = `
   color: #ffffff;
 }
 
+/* The session waiver. Deliberately the quietest of the three: it is the widest
+   decision on the card, so it should be reachable without being the one the eye
+   lands on when the user means to say yes once. */
+.confirm-btn--always {
+  font-weight: 500;
+  opacity: 0.85;
+}
+
+.confirm-btn--always:hover,
+.confirm-btn--always:focus-visible {
+  opacity: 1;
+}
+
+/* Editable arguments on an approval card. A plain field rather than a code
+   editor: it holds the JSON a card already displays, and the only interaction
+   is correcting a value before letting the call run. */
+.approval-edit {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+
+.approval-args {
+  box-sizing: border-box;
+  width: 100%;
+  resize: vertical;
+  border: 1px solid var(--_border);
+  border-radius: 8px;
+  padding: 8px;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 0.85em;
+  background: var(--_bg);
+  color: var(--_fg);
+}
+
+.approval-args:focus-visible {
+  border-color: var(--_accent);
+  outline: none;
+}
+
+.approval-error {
+  font-size: 0.85em;
+  color: var(--_danger);
+}
+
+/* Message action row. Sits under a finished assistant bubble.
+
+   The wrap is insurance rather than a fix: these buttons are glyph-only, so at
+   every width tested they fit on one line and removing the wrap changes
+   nothing. It is here because the confirmation row one release earlier did
+   overflow when it gained a third button, off the left edge and outside its own
+   card, and the difference between the two rows is only that this one's labels
+   are icons today. */
+.message-actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 4px;
+  /* Negative, and that is the point. The answer group is a flex column with its
+     own gap, so a positive margin here pushes the row further from the message
+     it acts on than the next card is below it -- the buttons then read as
+     belonging to whatever follows. Pulling back inside the gap is what makes
+     them the message's own. */
+  margin-top: -6px;
+}
+
+.message-action {
+  border: none;
+  border-radius: 6px;
+  padding: 2px 6px;
+  font: inherit;
+  line-height: 1.2;
+  cursor: pointer;
+  background: transparent;
+  color: var(--_muted);
+  opacity: 0.75;
+}
+
+.message-action:hover,
+.message-action:focus-visible {
+  opacity: 1;
+  background: var(--_border);
+}
+
+.message-action[aria-pressed="true"] {
+  opacity: 1;
+  color: var(--_accent);
+}
+
+.message-action--confirmed {
+  opacity: 1;
+  color: var(--_accent);
+}
+
 /* Approval card — the server-side-tool gate (approve/deny an interrupt). */
 .approval {
   align-self: stretch;
@@ -1917,6 +2299,34 @@ export const STYLES = `
   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;

package/src/ui/subagent_panel.ts

@@ -0,0 +1,213 @@
+import type { SUBAGENT_PHASE } from "../constants.js";
+import { DEFAULT_UI_STRINGS, type UiStrings } from "./ui_strings.js";
+
+/** One phase of a delegation's life, as the server spells it. */
+export type SubAgentPhase = (typeof SUBAGENT_PHASE)[keyof typeof SUBAGENT_PHASE];
+
+/**
+ * One tool call the child made, as the two tool phases report it.
+ *
+ * `ok` is a tri-state and stays one here rather than collapsing to a boolean:
+ * `null` is the call in flight, `true` a result the child accepted, `false` a
+ * result that came back to it. Flattening `null` into `false` would draw a
+ * running call as a failed one for as long as it runs.
+ */
+export interface SubAgentTool {
+  readonly toolCallId: string;
+  readonly name: string;
+  readonly ok: boolean | null;
+}
+
+/**
+ * One narrowed progress announcement about a delegation.
+ *
+ * Every field but `phase` and `delegationId` is nullable because the wire's
+ * `value` is `unknown` and a malformed announcement must not take the run down
+ * with it. `null` means "said nothing about this", never "said nothing was
+ * there" — the panel leaves what it already shows alone.
+ */
+export interface SubAgentUpdate {
+  /** The **parent's** `delegate_task` tool-call id, not the child's run id. */
+  readonly delegationId: string;
+  /** The child agent's name, for a host that wants to style or select by it. */
+  readonly agent: string | null;
+  readonly phase: SubAgentPhase;
+  /** The server's pre-rendered line. The collapsed row needs nothing else. */
+  readonly status: string | null;
+  /** Present on the two tool phases only. */
+  readonly tool: SubAgentTool | null;
+}
+
+/**
+ * The nested surface for one delegation: a collapsed status row that expands
+ * onto the child agent's own tool calls.
+ *
+ * ## Where it goes and why
+ *
+ * Into {@link ToolCallCard.subagentSlot} — the card the parent's own
+ * `delegate_task` call already drew. The wire keys progress on the *parent's*
+ * tool-call id, so the thing being narrated is already on screen; a floating
+ * element would have duplicated its identity and then had to explain the
+ * relationship. Attaching instead means the delegation reuses how tool cards
+ * already behave, and there is no second visual language to learn.
+ *
+ * ## The shape
+ *
+ * One row per delegation, live, carrying nothing but the server's own `status`
+ * line — which is what makes a ten-step child cost one row until somebody opens
+ * it. Two alternatives were rejected on the way here and both are worth naming:
+ * a bare status line is cheaper and gives up the detail entirely, and inline
+ * child cards in the transcript interleave parent and child with nothing marking
+ * whose is whose, in an order the persisted transcript will not reproduce.
+ *
+ * A child's steps are keyed by the child's own `toolCallId`, so the `tool_call`
+ * that opens one and the `tool_result` that settles it are the same row updated
+ * in place rather than two rows stacked.
+ *
+ * ## What it never does
+ *
+ * It never renders failure text. A `failed` phase carries none, on purpose; the
+ * detail arrives on the ordinary `TOOL_CALL_RESULT` and lands in the same card's
+ * result region, a few pixels below. Anything invented here would be this
+ * component guessing at words the server declined to send.
+ *
+ * Nothing here is persisted: the events ride the imperative carrier, so a thread
+ * restore rebuilds the tool card and not the delegation under it.
+ *
+ * Pure DOM, like the other widgets: the host appends {@link element}, and all
+ * chrome text comes from {@link UiStrings}. The status line is server text and
+ * is set with `textContent`, never parsed as markup.
+ */
+export class SubAgentPanel {
+  /** The panel's root; append this into the delegating card's slot. */
+  readonly element: HTMLDivElement;
+
+  /**
+   * The collapsed row, which is the expander as well as the status.
+   *
+   * Disabled while the child has called nothing, so a delegation that failed
+   * before it started offers no control that expands onto an empty region —
+   * the same refusal the card's own Details toggle already makes.
+   */
+  readonly #row: HTMLButtonElement;
+  readonly #status: HTMLSpanElement;
+  readonly #steps: HTMLDivElement;
+  /** The child's tool calls, keyed by the child's own call id. */
+  readonly #stepRows = new Map<string, HTMLDivElement>();
+
+  constructor(strings: UiStrings = DEFAULT_UI_STRINGS) {
+    this.element = document.createElement("div");
+    this.element.className = "subagent";
+    this.element.setAttribute("part", "subagent");
+
+    this.#row = document.createElement("button");
+    this.#row.type = "button";
+    this.#row.className = "subagent-row";
+    this.#row.setAttribute("part", "subagent-row");
+    this.#row.setAttribute("aria-expanded", "false");
+    this.#row.disabled = true;
+
+    // Left empty in the DOM, like the tool card's: the shadow CSS draws a
+    // spinner or a settled mark from the panel's data-phase, so a host themes
+    // the glyph without either side reaching into the other's stylesheet.
+    const icon = document.createElement("span");
+    icon.className = "subagent-icon";
+    icon.setAttribute("part", "subagent-icon");
+    icon.setAttribute("aria-hidden", "true");
+
+    this.#status = document.createElement("span");
+    this.#status.className = "subagent-status";
+    this.#status.setAttribute("part", "subagent-status");
+    // Seeded rather than left blank: an announcement whose status field is
+    // unusable must still leave a readable row, since the row is the control.
+    this.#status.textContent = strings.subAgentWorking;
+
+    this.#row.append(icon, this.#status);
+
+    this.#steps = document.createElement("div");
+    this.#steps.className = "subagent-steps";
+    this.#steps.setAttribute("part", "subagent-steps");
+    this.#steps.setAttribute("role", "list");
+    this.#steps.setAttribute("aria-label", strings.subAgentSteps);
+    this.#steps.hidden = true;
+
+    // The attribute is the state, as it is on the tool card: one place holds
+    // whether the region is open, and it is the one a screen reader reads.
+    this.#row.addEventListener("click", () => {
+      this.#setExpanded(this.#row.getAttribute("aria-expanded") !== "true");
+    });
+
+    this.element.append(this.#row, this.#steps);
+  }
+
+  /**
+   * Fold one announcement in.
+   *
+   * Every field is applied only when the update actually carried it, so a phase
+   * that says nothing about the agent or the status leaves both as they stand.
+   * That is what lets `finished` be two keys wide on the wire without blanking
+   * the row it closes.
+   */
+  report(update: SubAgentUpdate): void {
+    this.element.setAttribute("data-phase", update.phase);
+    if (update.agent !== null) {
+      this.element.setAttribute("data-agent", update.agent);
+    }
+    if (update.status !== null) {
+      this.#status.textContent = update.status;
+    }
+    if (update.tool !== null) {
+      this.#recordStep(update.tool);
+    }
+  }
+
+  /**
+   * Open or settle one of the child's calls, keyed by its own id.
+   *
+   * The absence of `data-ok` is what "still running" looks like, mirroring the
+   * wire's `null` rather than inventing a third value for it — so the attribute
+   * is removed on the way in and written on the way out.
+   */
+  #recordStep(tool: SubAgentTool): void {
+    const row = this.#stepRows.get(tool.toolCallId) ?? this.#createStep(tool);
+    if (tool.ok === null) {
+      row.removeAttribute("data-ok");
+      return;
+    }
+    row.setAttribute("data-ok", String(tool.ok));
+  }
+
+  #createStep(tool: SubAgentTool): HTMLDivElement {
+    const row = document.createElement("div");
+    row.className = "subagent-step";
+    row.setAttribute("part", "subagent-step");
+    row.setAttribute("role", "listitem");
+    row.setAttribute("data-tool-call-id", tool.toolCallId);
+
+    const icon = document.createElement("span");
+    icon.className = "subagent-step-icon";
+    icon.setAttribute("part", "subagent-step-icon");
+    icon.setAttribute("aria-hidden", "true");
+
+    const name = document.createElement("span");
+    name.className = "subagent-step-name";
+    name.setAttribute("part", "subagent-step-name");
+    // The child's raw tool name. Not prettified and not looked up in the tool
+    // catalog: a sub-agent's tools are its own and never reached the browser's
+    // schema, and the status line above quotes the same raw name, so relabelling
+    // here would make the two lines disagree about one call.
+    name.textContent = tool.name;
+
+    row.append(icon, name);
+    this.#steps.appendChild(row);
+    this.#stepRows.set(tool.toolCallId, row);
+    // There is something behind the row now, so it becomes a control.
+    this.#row.disabled = false;
+    return row;
+  }
+
+  #setExpanded(expanded: boolean): void {
+    this.#steps.hidden = !expanded;
+    this.#row.setAttribute("aria-expanded", String(expanded));
+  }
+}