@artooi/ag-ui-web-component 0.18.0 → 0.20.0

package/src/core/ag_ui_chat.ts

@@ -42,6 +42,12 @@ import {
   requestQuestion,
 } from "../ui/question_card.js";
 import { renderMarkdown } from "../ui/render_markdown.js";
+import {
+  createResizeHandle,
+  type ResizeAnchor,
+  type ResizeAxis,
+  type ResizeSize,
+} from "../ui/resize_handle.js";
 import { wrapWords } from "../ui/reveal_words.js";
 import { renderRunNotice } from "../ui/run_notice.js";
 import { SkillsMenu } from "../ui/skills_menu.js";
@@ -130,6 +136,9 @@ const CONNECT_TIME_ATTRIBUTES = [
 /** Per-tab persistence key for the collapsed state (survives MPA reloads). */
 const COLLAPSED_KEY = "ag-ui-chat:collapsed";
 
+/** Per-tab persistence key for a dragged panel size. */
+const SIZE_KEY = "ag-ui-chat:size";
+
 /** Per-tab persistence key for the built-in theme toggle. */
 const THEME_KEY = "ag-ui-chat:theme";
 
@@ -524,10 +533,16 @@ export class AgUiChat extends HTMLElement {
 
   /** Attributes the element reacts to after it has been connected. */
   static get observedAttributes(): string[] {
-    return ["title-text", ...CONNECT_TIME_ATTRIBUTES];
+    return ["title-text", "placement", ...CONNECT_TIME_ATTRIBUTES];
   }
 
   attributeChangedCallback(name: string, previous: string | null, value: string | null): void {
+    if (name === "placement") {
+      // Placement moves the panel, so the edges its layout holds still change
+      // with it. Deferred a frame so the new rules have applied.
+      requestAnimationFrame(() => this.#syncResizeAnchor());
+      return;
+    }
     if (name === "title-text") {
       // `#strings` is the resolved table once connected, the English defaults
       // before then.
@@ -760,7 +775,11 @@ export class AgUiChat extends HTMLElement {
 
   /**
    * How much detail tool-call cards show, from the `data-tool-display`
-   * attribute (`minimal` / `compact` / `full`). Defaults to `full`.
+   * attribute (`minimal` / `inline` / `compact` / `full`). Defaults to `full`.
+   *
+   * Applied by the shadow CSS from the attribute itself, so changing it
+   * restyles every card already in the transcript rather than only the ones
+   * built afterwards.
    */
   get toolDisplay(): ToolDisplayMode {
     const attr = this.getAttribute("data-tool-display");
@@ -783,6 +802,14 @@ export class AgUiChat extends HTMLElement {
     // key read/write, so this instance doesn't share collapsed/theme/thread
     // state with another on the same origin.
     this.#storageNs = this.id !== "" ? this.id : this.endpoint;
+    // Restore a dragged size before the panel paints, so it does not snap from
+    // the placement default to the user's width on the first frame.
+    this.#applySize(this.#readSize());
+    // Position the grip at the corner this layout grows toward. Deferred to a
+    // frame so the host's own stylesheet has applied; re-measured on every drag
+    // anyway, so a wrong first guess costs a grip in the wrong corner and never
+    // a wrong resize.
+    requestAnimationFrame(() => this.#syncResizeAnchor());
     // Resolve the string table before rendering any chrome (defaults are the
     // floor; `data-strings` then the `strings` property layer over them).
     this.#strings = mergeUiStrings({ ...this.#readStringOverrides(), ...this.strings });
@@ -1094,23 +1121,69 @@ export class AgUiChat extends HTMLElement {
     this.#skillsMenu.setSkills([...merged.values()]);
   }
 
-  /** Pre-fill (or send) a picked skill's prompt, filling its placeholders. */
+  /**
+   * Act on a picked skill.
+   *
+   * A skill that ships no `prompt` is **server-resolved**: the catalog carries
+   * only its name and label, and picking it sends the bare `/name` token for
+   * the agent to expand — from the harness `Skills` capability, or from the
+   * server's own instructions. That is the shape to prefer, because the prompt
+   * then never reaches the browser at all: a skill is often where a project's
+   * internal workflow is written down most plainly, and a catalog endpoint is a
+   * plain GET.
+   *
+   * A skill that does carry a `prompt` keeps the older behaviour — the client
+   * fills its `{placeholder}`s from the page and sends (or pre-fills) the text.
+   * Right for a user-facing convenience, and for placeholders only the page can
+   * supply.
+   *
+   * Either way a pick now **sends**, rather than parking text in the composer
+   * for a second click; `sendImmediately: false` opts back into pre-filling.
+   */
   #applySkill(skill: Skill): void {
+    if (skill.prompt === undefined) {
+      this.#skillHint.hidden = true;
+      void this.sendMessage(`/${skill.name}`);
+      return;
+    }
     const { text, missing } = fillTemplate(skill.prompt, this.skillContext());
     if (missing.length > 0) {
+      // Hand the user something to work with rather than only a refusal. The
+      // partially-filled template goes into the composer with its unresolved
+      // `{placeholder}`s intact and the first one selected, so the next
+      // keystroke replaces it. Blocking with a hint alone left whatever the
+      // user had typed to open the palette — a lone "/" — sitting there, which
+      // says nothing about what the skill wanted or how to give it.
       this.#skillHint.textContent = this.#strings.skillNeeds
         .replace("{title}", skill.title)
         .replace("{fields}", missing.join(", "));
       this.#skillHint.hidden = false;
+      this.#input.value = text;
+      this.#input.focus();
+      this.#selectFirstPlaceholder(text);
       return;
     }
     this.#skillHint.hidden = true;
     this.#input.value = text;
-    if (skill.sendImmediately === true) {
-      void this.#submit();
-    } else {
+    if (skill.sendImmediately === false) {
       this.#input.focus();
+      return;
     }
+    void this.#submit();
+  }
+
+  /**
+   * Put the caret on the first unresolved placeholder, selected.
+   *
+   * Typing then replaces it, which is the shortest path from "this skill needs
+   * a topic" to a sendable prompt.
+   */
+  #selectFirstPlaceholder(text: string): void {
+    // The first surviving brace *is* the first unresolved placeholder — a
+    // resolved one was substituted away — so this needs no search through the
+    // missing keys and no not-found branch to defend.
+    const start = text.indexOf("{");
+    this.#input.setSelectionRange(start, text.indexOf("}", start) + 1);
   }
 
   /** Whether the widget is collapsed (reflected as the `collapsed` attribute). */
@@ -1164,6 +1237,113 @@ export class AgUiChat extends HTMLElement {
     this.#syncThemeGlyph();
   }
 
+  /**
+   * Which axes the current placement allows.
+   *
+   * A full-bleed layout is `100vw`/`100vh` by definition and cannot be resized
+   * at all; a docked panel owns its height, leaving only its inner edge. Read
+   * per interaction, because `placement` is a live attribute.
+   */
+  #resizeAxis(): ResizeAxis {
+    switch (this.getAttribute("placement")) {
+      case "full":
+      case "page":
+        return "none";
+      case "sidebar":
+      case "side":
+        return "width";
+      default:
+        return "both";
+    }
+  }
+
+  /**
+   * Which edges the layout is holding still, by measuring rather than guessing.
+   *
+   * A resize has to be computed from the edge that does not move, and which
+   * edge that is belongs to the **host's layout**, not to `placement`: a
+   * floating panel is pinned bottom-right, while an embedded one goes wherever
+   * the page's own CSS puts it — flex-start, flex-end, a grid cell. Mapping
+   * placement to a corner got this wrong for any host that right-aligns the
+   * element, and the symptom is bad enough to read as a broken control: the
+   * panel shrinks when dragged outward, travelling by its opposite corner.
+   *
+   * So: nudge the size by a pixel, see which edges stayed put, and undo. One
+   * forced reflow per drag, which is cheap next to being wrong.
+   */
+  #measureAnchor(): ResizeAnchor {
+    const before = this.getBoundingClientRect();
+    const width = this.style.getPropertyValue("--ag-ui-width");
+    const height = this.style.getPropertyValue("--ag-ui-height");
+    this.#applySize({ width: before.width + 1, height: before.height + 1 });
+    const after = this.getBoundingClientRect();
+    // Restore exactly what was there, including "nothing" — leaving a probe
+    // value behind would pin a panel that had been sizing itself.
+    this.#restoreProperty("--ag-ui-width", width);
+    this.#restoreProperty("--ag-ui-height", height);
+    return {
+      x: Math.abs(after.left - before.left) < 0.5 ? "left" : "right",
+      y: Math.abs(after.top - before.top) < 0.5 ? "top" : "bottom",
+    };
+  }
+
+  /** Stamp the measured anchor so the shadow CSS can place the grip. */
+  #syncResizeAnchor(): void {
+    if (!this.#connected) {
+      return;
+    }
+    const anchor = this.#measureAnchor();
+    this.setAttribute("data-resize-anchor", `${anchor.y}-${anchor.x}`);
+  }
+
+  /** Put a custom property back to a previous value, or remove it if there was none. */
+  #restoreProperty(name: string, value: string): void {
+    if (value === "") {
+      this.style.removeProperty(name);
+      return;
+    }
+    this.style.setProperty(name, value);
+  }
+
+  /**
+   * Write a dragged size onto the host as custom properties.
+   *
+   * Properties rather than inline `width` / `height`: the placement rules set
+   * those same properties, so an inline dimension would outrank them and a
+   * panel dragged while floating would keep that width after switching to
+   * fullscreen.
+   */
+  #applySize(size: ResizeSize): void {
+    if (size.width !== undefined) {
+      this.style.setProperty("--ag-ui-width", `${size.width}px`);
+    }
+    if (size.height !== undefined) {
+      this.style.setProperty("--ag-ui-height", `${size.height}px`);
+    }
+  }
+
+  /** Persist a dragged size per tab, alongside the collapsed/theme preferences. */
+  #persistSize(size: ResizeSize): void {
+    const stored = { ...this.#readSize(), ...size };
+    sessionStorage.setItem(this.#storageKey(SIZE_KEY), JSON.stringify(stored));
+  }
+
+  /** The persisted size for this instance, or an empty record. */
+  #readSize(): ResizeSize {
+    const raw = this.#readScopedItem(SIZE_KEY);
+    if (raw === null) {
+      return {};
+    }
+    try {
+      const parsed: unknown = JSON.parse(raw);
+      return typeof parsed === "object" && parsed !== null ? (parsed as ResizeSize) : {};
+    } catch {
+      // A corrupt entry is not worth failing a mount over; fall back to the
+      // placement's own size.
+      return {};
+    }
+  }
+
   /** This instance's namespaced form of an origin-scoped storage key. */
   #storageKey(base: string): string {
     return this.#storageNs === "" ? base : `${base}:${this.#storageNs}`;
@@ -1648,10 +1828,36 @@ export class AgUiChat extends HTMLElement {
     this.#rail.append(this.#iconElement("launcher", "launcher-icon", "💬"));
     this.#rail.addEventListener("click", () => this.setCollapsed(false));
 
+    this.#chat.append(
+      createResizeHandle({
+        axis: () => this.#resizeAxis(),
+        anchor: () => this.#measureAnchor(),
+        rect: () => this.getBoundingClientRect(),
+        apply: (size) => this.#applySize(size),
+        commit: (size) => {
+          this.#persistSize(size);
+          // Re-stamp after the drag: a host whose layout changed underneath us
+          // would otherwise keep the grip in the old corner, which reads as the
+          // control being in the wrong place even though the drag was right.
+          this.#syncResizeAnchor();
+        },
+        label: this.#strings.resizePanel,
+      }),
+    );
     this.#root.append(style, this.#chat, this.#rail);
   }
 
-  /** Build a header control button (icon glyph + localized title/aria). */
+  /**
+   * Build a header control button: a named slot a host can project markup into,
+   * with the built-in glyph as the slot's fallback.
+   *
+   * The glyph used to be the button's own `textContent`, which left a host able
+   * to restyle the control through its `part` but unable to replace it — a CSS
+   * `content` override could swap one character for another, and nothing could
+   * supply a brand `<img>` or `<svg>`. This is the same slot-with-fallback
+   * idiom the header icon already uses, so existing embeds render exactly as
+   * before.
+   */
   #headerButton(modifier: string, label: string, glyph: string): HTMLButtonElement {
     const button = document.createElement("button");
     button.type = "button";
@@ -1659,7 +1865,10 @@ export class AgUiChat extends HTMLElement {
     button.setAttribute("part", `header-button ${modifier}-button`);
     button.title = label;
     button.setAttribute("aria-label", label);
-    button.textContent = glyph;
+    const slot = document.createElement("slot");
+    slot.name = `icon-${modifier}`;
+    slot.append(document.createTextNode(glyph));
+    button.append(slot);
     return button;
   }
 
@@ -1962,7 +2171,11 @@ export class AgUiChat extends HTMLElement {
       // The run loop is suspended on this card; a Stop while it's open aborts
       // the controller, resolving the decision as declined.
       this.#confirmAbort = new AbortController();
-      const decision = requestConfirmation(this.#messages, request, {
+      // Into the turn's answer group, like every other inline card. Appending
+      // to the message list made it a sibling *after* the group, so anything
+      // that streamed afterwards rendered above it and the prompt drifted to
+      // the foot of the turn no matter when it was asked.
+      const decision = requestConfirmation(this.#ensureGroup(), request, {
         signal: this.#confirmAbort.signal,
         strings: this.#strings,
       });
@@ -1970,6 +2183,7 @@ export class AgUiChat extends HTMLElement {
       this.#messages.scrollTop = this.#messages.scrollHeight;
       const accepted = await decision;
       this.#confirmAbort = null;
+      card.recordDecision(accepted ? "approved" : "declined");
       if (!accepted) {
         const message = this.#strings.declinedAction;
         card.settle(TOOL_CALL_STATUS.DECLINED, message);
@@ -2046,6 +2260,12 @@ export class AgUiChat extends HTMLElement {
           : await requestApproval(this.#ensureGroup(), request, { signal, strings: this.#strings });
       this.#updateEmptyState();
       this.#messages.scrollTop = this.#messages.scrollHeight;
+      // Same annotation as the client-side confirmation gate. Without it the
+      // two gates read differently for the same act: a locally-confirmed call
+      // said who let it through and a server-gated one said nothing, which is
+      // backwards, since the server-side gate is the one guarding the tools
+      // that actually run on the backend.
+      card?.recordDecision(approved ? "approved" : "declined");
       if (approved) {
         responses[interrupt.id] = { status: "resolved", payload: { approved: true } };
       } else {
@@ -2300,7 +2520,7 @@ export class AgUiChat extends HTMLElement {
         : (this.toolSummaries[call.name] ??
           this.#toolCatalog[call.name] ??
           prettifyToolName(call.name));
-    const card = new ToolCallCard(call.name, call.args, this.toolDisplay, summary, this.#strings);
+    const card = new ToolCallCard(call.name, call.args, summary, this.#strings);
     this.#toolCards.set(call.id, card);
     this.#ensureGroup().appendChild(card.element);
     this.#updateEmptyState();

package/src/core/agui_client.ts

@@ -181,6 +181,13 @@ export class AgUiClient {
   readonly #executeTool: ExecuteTool | null;
   readonly #resolveInterrupts: ResolveInterrupts | null;
   readonly #onPersist: (messages: readonly Message[]) => void;
+  /**
+   * Message ids the server has already closed, so a reuse can be reported.
+   *
+   * Per client rather than per run: the merge happens across runs, which is the
+   * case a per-run set would miss entirely.
+   */
+  readonly #closedMessageIds = new Set<string>();
   readonly #connectionLostMessage: string;
   // Set by cancel(); reset at the top of each #run(). Checked by the loop so
   // a cancel between frontend-tool rounds doesn't start another round.
@@ -397,14 +404,33 @@ export class AgUiClient {
 
   #buildSubscriber(pending: AgUiToolCall[], runState: RunState): AgentSubscriber {
     const h = this.#handlers;
+    const closed = this.#closedMessageIds;
     return {
       onRunInitialized() {
         h.onRunStart();
       },
+      onTextMessageStartEvent({ event }) {
+        // A server that reuses a message id gets its two answers merged into
+        // one transcript entry, silently, and that merged entry is what gets
+        // persisted. The protocol has no rule to enforce here and refusing the
+        // event would be worse than the merge, so this warns and continues —
+        // but it should not be silent, because the corruption outlives the
+        // session and reads as a client bug. Found by a demo harness doing
+        // exactly this.
+        if (closed.has(event.messageId)) {
+          console.warn(
+            `<ag-ui-chat>: the server reused message id "${event.messageId}", which was ` +
+              "already closed. Its content will be appended to that earlier message rather " +
+              "than starting a new one, and the merged result is what gets persisted. " +
+              "Issue a fresh id per message.",
+          );
+        }
+      },
       onTextMessageContentEvent({ textMessageBuffer }) {
         h.onTextDelta(textMessageBuffer);
       },
-      onTextMessageEndEvent({ textMessageBuffer }) {
+      onTextMessageEndEvent({ event, textMessageBuffer }) {
+        closed.add(event.messageId);
         h.onTextEnd(textMessageBuffer);
       },
       onToolCallEndEvent({ event, toolCallName, toolCallArgs }) {

package/src/skills/parse_skills.ts

@@ -1,6 +1,12 @@
 import type { Skill } from "./skill.js";
 
-/** Whether ``value`` has the required string fields of a {@link Skill}. */
+/**
+ * Whether ``value`` has the required string fields of a {@link Skill}.
+ *
+ * `prompt` is optional and must stay so: a server-resolved skill deliberately
+ * omits it, and requiring it here would silently drop exactly the skills whose
+ * wording was kept off the client.
+ */
 function isSkill(value: unknown): value is Skill {
   if (typeof value !== "object" || value === null) {
     return false;
@@ -9,7 +15,7 @@ function isSkill(value: unknown): value is Skill {
   return (
     typeof record["name"] === "string" &&
     typeof record["title"] === "string" &&
-    typeof record["prompt"] === "string"
+    (record["prompt"] === undefined || typeof record["prompt"] === "string")
   );
 }
 

package/src/skills/skill.ts

@@ -12,11 +12,21 @@ export interface Skill {
   /** Secondary line shown in the palette. */
   readonly description?: string;
   /**
-   * The prompt inserted (or sent). May contain `{placeholder}`s filled from the
-   * host's skill context before send; an unfilled placeholder blocks send.
+   * The prompt to send. May contain `{placeholder}`s filled from the host's
+   * skill context before send; an unfilled placeholder blocks send.
+   *
+   * **Omit it to keep the prompt on the server.** The skill then sends the bare
+   * `/name` token and the agent resolves what it means, so the wording never
+   * reaches the browser — worth preferring for anything internal, since a
+   * fetched catalog is a plain GET and an embedded one sits in the page source.
+   */
+  readonly prompt?: string;
+  /**
+   * Set `false` to pre-fill the composer instead of sending on pick. Only
+   * meaningful for a skill that carries its own `prompt`; a server-resolved one
+   * always sends. Defaults to sending — a chip that needs a second click to do
+   * anything is a two-step shortcut.
    */
-  readonly prompt: string;
-  /** Send immediately on pick instead of pre-filling the input (default false). */
   readonly sendImmediately?: boolean;
   /** Also surface this skill as a chip (default false; the palette shows all). */
   readonly chip?: boolean;

package/src/ui/confirmation_card.ts

@@ -40,8 +40,14 @@ export interface ConfirmationOptions {
  * Unlike a modal overlay, the card lives in the transcript right where the
  * action is — it reads naturally after the assistant's explanation and never
  * steals focus from the page. Resolves ``true`` on confirm, ``false`` on
- * cancel. The card stays in the transcript as a resolved record (buttons
- * disabled, `data-resolved` set) rather than vanishing.
+ * cancel.
+ *
+ * **Answering it removes it.** A prompt and a record are two different objects:
+ * the prompt owns the user's attention until it is answered, and the record of
+ * what was decided belongs in the transcript, in order, scrolling with
+ * everything else. The tool card this gates is that record — it settles to
+ * `done` or `declined` and carries the decision. Leaving the spent form in
+ * place made an answered question read as outstanding.
  */
 export function requestConfirmation(
   host: Node & ParentNode,
@@ -66,6 +72,8 @@ export function requestConfirmation(
     args.className = "confirm-args";
     args.setAttribute("part", "confirm-args");
     args.textContent = JSON.stringify(request.args, null, 2);
+    // A call with no arguments rendered the string "{}" in a box of its own.
+    args.hidden = Object.keys(request.args).length === 0;
 
     const actions = document.createElement("div");
     actions.className = "confirm-actions";
@@ -80,9 +88,11 @@ export function requestConfirmation(
         return;
       }
       settled = true;
-      cancel.disabled = true;
-      confirm.disabled = true;
-      card.setAttribute("data-resolved", accepted ? "confirmed" : "declined");
+      // The prompt leaves once it has been answered. What stays is the tool
+      // card next to it, which settles to the outcome and scrolls with the rest
+      // of the transcript -- a record of the action rather than a spent form
+      // sitting there as a standing reminder of one.
+      card.remove();
       resolve(accepted);
     };
 

package/src/ui/resize_handle.ts

@@ -0,0 +1,176 @@
+/** Which edges the layout holds still while the panel changes size. */
+export interface ResizeAnchor {
+  /** The horizontal edge that does not move. */
+  readonly x: "left" | "right";
+  /** The vertical edge that does not move. */
+  readonly y: "top" | "bottom";
+}
+
+/**
+ * What the current placement allows: both axes, width only, or nothing.
+ *
+ * Which *corner* the grip sits on is not part of this — that follows the host's
+ * layout, which the component measures rather than assumes.
+ */
+export type ResizeAxis = "none" | "width" | "both";
+
+/** Persisted size, in CSS pixels. Either axis may be absent. */
+export interface ResizeSize {
+  readonly width?: number;
+  readonly height?: number;
+}
+
+/** The panel's position on screen at the moment a drag starts. */
+export interface PanelRect {
+  readonly left: number;
+  readonly top: number;
+  readonly right: number;
+  readonly bottom: number;
+}
+
+/** What the handle needs from its host to do its job. */
+export interface ResizeOptions {
+  /**
+   * Which axes the current placement allows, read **per interaction**.
+   *
+   * A getter rather than a value because `placement` is a live attribute: read
+   * once at construction, a handle built while floating kept its axes after the
+   * host switched to a docked or full-bleed layout.
+   */
+  readonly axis: () => ResizeAxis;
+  /**
+   * Which edges the layout is holding still, measured at the moment of the
+   * drag.
+   *
+   * **Measured, not derived from `placement`.** A floating panel is pinned
+   * bottom-right and an embedded one goes wherever the host's own CSS puts it —
+   * the demo playground drops it in a right-aligned flex slot, so "embedded"
+   * alone says nothing. Guessing produced a panel that shrank when dragged
+   * outward and travelled by its opposite corner.
+   */
+  readonly anchor: () => ResizeAnchor;
+  /** The panel's current bounding box. */
+  readonly rect: () => PanelRect;
+  /** Apply a size (the host writes the custom properties). */
+  readonly apply: (size: ResizeSize) => void;
+  /** Called once per completed drag, for persistence. */
+  readonly commit: (size: ResizeSize) => void;
+  /** Accessible label. */
+  readonly label: string;
+}
+
+/** Smallest usable panel; below this the composer and header collide. */
+const MIN_WIDTH = 280;
+const MIN_HEIGHT = 240;
+
+/**
+ * A drag handle that resizes the chat panel.
+ *
+ * The size was previously fixed by whatever the host set `--ag-ui-width` /
+ * `--ag-ui-height` to: themeable by the page, immovable by the person reading a
+ * long answer in a 380px column.
+ *
+ * **The new size is measured from the edge that is not moving, never from a
+ * delta**, and which edge that is is **measured rather than assumed**. A
+ * floating panel is pinned bottom-right; an embedded one goes wherever the
+ * host's CSS puts it, so `placement` does not answer the question. Getting it
+ * wrong is very visible: the panel shrinks when dragged outward and travels by
+ * its opposite corner.
+ *
+ * **It writes the custom properties rather than inline `width` / `height`.**
+ * The placement rules set those same properties, so an inline dimension would
+ * fight them — a sidebar would keep a dragged width after switching to
+ * fullscreen. Writing the property means placement still has the final say.
+ *
+ * The axes are read per interaction, so switching `placement` at runtime takes
+ * effect immediately rather than leaving whichever ones the element happened to
+ * mount with.
+ */
+export function createResizeHandle(options: ResizeOptions): HTMLDivElement {
+  const handle = document.createElement("div");
+  handle.className = "resize-handle";
+  handle.setAttribute("part", "resize-handle");
+  handle.setAttribute("role", "separator");
+  handle.setAttribute("aria-label", options.label);
+  handle.tabIndex = 0;
+
+  /** The size implied by a pointer at (x, y), given which edges are pinned. */
+  const sizeAt = (
+    axis: ResizeAxis,
+    anchor: ResizeAnchor,
+    rect: PanelRect,
+    x: number,
+    y: number,
+  ): ResizeSize => {
+    const width = anchor.x === "right" ? rect.right - x : x - rect.left;
+    const clamped: ResizeSize = { width: Math.max(MIN_WIDTH, width) };
+    if (axis !== "both") {
+      return clamped;
+    }
+    const height = anchor.y === "bottom" ? rect.bottom - y : y - rect.top;
+    return { ...clamped, height: Math.max(MIN_HEIGHT, height) };
+  };
+
+  handle.addEventListener("pointerdown", (event: PointerEvent) => {
+    const axis = options.axis();
+    if (axis === "none") {
+      return;
+    }
+    // Captured once: the fixed edges cannot move during the drag, and reading
+    // them live would chase the panel as it resizes.
+    const anchor = options.anchor();
+    const rect = options.rect();
+
+    const onMove = (move: PointerEvent): void => {
+      options.apply(sizeAt(axis, anchor, rect, move.clientX, move.clientY));
+    };
+
+    const onUp = (up: PointerEvent): void => {
+      window.removeEventListener("pointermove", onMove);
+      window.removeEventListener("pointerup", onUp);
+      handle.removeAttribute("data-dragging");
+      options.commit(sizeAt(axis, anchor, rect, up.clientX, up.clientY));
+    };
+
+    handle.setAttribute("data-dragging", "true");
+    // Listeners on `window`, not the handle: a fast drag outruns the pointer
+    // and would otherwise strand the panel mid-resize with no pointerup.
+    window.addEventListener("pointermove", onMove);
+    window.addEventListener("pointerup", onUp);
+    event.preventDefault();
+  });
+
+  // Keyboard parity. A pointer-only resize is unreachable without a mouse, and
+  // this control has no equivalent elsewhere in the UI.
+  handle.addEventListener("keydown", (event: KeyboardEvent) => {
+    const axis = options.axis();
+    if (axis === "none") {
+      return;
+    }
+    const anchor = options.anchor();
+    const rect = options.rect();
+    const step = event.shiftKey ? 64 : 16;
+    // An arrow moves the grip, and whether that grows or shrinks depends on
+    // which side the grip is on — the same asymmetry the pointer path handles.
+    const outward = anchor.x === "right" ? -1 : 1;
+    const width = rect.right - rect.left;
+    const height = rect.bottom - rect.top;
+    let next: ResizeSize | null = null;
+    if (event.key === "ArrowLeft") {
+      next = { width: Math.max(MIN_WIDTH, width - step * outward) };
+    } else if (event.key === "ArrowRight") {
+      next = { width: Math.max(MIN_WIDTH, width + step * outward) };
+    } else if (axis === "both" && (event.key === "ArrowUp" || event.key === "ArrowDown")) {
+      const grow = event.key === (anchor.y === "bottom" ? "ArrowUp" : "ArrowDown");
+      next = { height: Math.max(MIN_HEIGHT, height + (grow ? step : -step)) };
+    }
+    if (next === null) {
+      return;
+    }
+    event.preventDefault();
+    options.apply(next);
+    options.commit(next);
+  });
+
+  return handle;
+}