@haikit/client 0.22.1 → 0.24.0

package/README.md

@@ -13,7 +13,7 @@ API — it is built from `createChat` + `renderTranscript`, and dropping to thos
 when the default shell stops fitting is the expected path.
 
 `hai.css` styles **only what the framework renders** — transcript blocks, tool
-rows, the surface container, shell, composer, debug drawer. It deliberately does
+rows, the surface container, shell, composer, debug drawer, dock. It deliberately does
 not style the inside of your surfaces; your components emit their own class
 names and your stylesheet owns them. Every colour is a `--hai-*` custom
 property, so override what you like.
@@ -44,6 +44,14 @@ is parked on its surface, `resolved` once that surface has been answered or
 typed over, or how long it took. Expand it to see the input and the
 `tool_result`, which is everything the model received.
 
+Every surface has a **Dock** button on its bar. Docked, it waits on a shelf
+above the message box and opens from there as a window, one at a time; **Put
+back** or **Remove from dock** returns it to its place. It's moved, not
+mounted again, so your component keeps its state. A docked question stays
+amber on the shelf, when the shelf is full the oldest go into a pile, and
+**Remove all** at the shelf's end puts every docked surface back at once.
+`dock: false` leaves it out.
+
 It is light or dark with the system. To pin it, put `data-hai-theme="dark"` (or
 `"light"`) on the `<html>` element, or pass `theme: "dark"` to `mountChat`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haikit/client",
-  "version": "0.22.1",
+  "version": "0.24.0",
   "description": "The haikit browser runtime: streams tool payloads into interactive UI surfaces. Plain ESM, no build step, no dependencies.",
   "keywords": [
     "haikit",

package/src/app.d.ts

@@ -27,6 +27,14 @@ export interface MountChatOptions {
    * dark setting, or a `data-hai-theme` already in the page's markup.
    */
   theme?: "light" | "dark";
+  /**
+   * Let the reader dock surfaces. Default true. Each surface gets a bar with
+   * its name and a Dock button, which moves it out of the transcript onto a
+   * shelf above the message box; from there it opens as a window, one at a
+   * time, and Put back or Remove from dock returns it to its place. `false`
+   * shows surfaces as `renderTranscript` does without `onDock`.
+   */
+  dock?: boolean;
   /** Passed to `createChat`: how long the events stream may be silent before the chat polls. Default 8000 ms. */
   eventsFallbackMs?: number;
   /** Passed to `createChat`: how long each poll asks the server to hold. Default 15000 ms. */

package/src/app.js

@@ -95,6 +95,7 @@ function dropFavicon() {
  *   placeholder?: string,
  *   emptyText?: string,
  *   theme?: "light" | "dark",
+ *   dock?: boolean,
  *   eventsFallbackMs?: number,
  *   pollHoldMs?: number,
  * }} options
@@ -112,6 +113,7 @@ export function mountChat({
   placeholder = "message…",
   emptyText = "",
   theme,
+  dock = true,
   eventsFallbackMs,
   pollHoldMs,
 }) {
@@ -165,6 +167,17 @@ export function mountChat({
   const main = h("div", `hai-main${inspector ? " has-inspector" : ""}`);
   main.append(chatPane);
 
+  const wideQuery = typeof matchMedia === "function" ? matchMedia(WIDE) : null;
+  const wide = () => !wideQuery || wideQuery.matches;
+
+  // Before the drawer, so the dock hears Escape first: it closes what the
+  // reader is in, and the drawer what's left.
+  const docked = dock
+    ? createDock({ chat, id, shell, chatPane, transcript, composer, statusEl, wide, wideQuery,
+        drawerOpen: () => main.classList.contains("inspector-open"),
+        onChange: () => showWaiting() })
+    : null;
+
   let inspectorBody = null;
   let ctxCount = null;
   let releaseDrawer = () => {};
@@ -195,8 +208,6 @@ export function mountChat({
     toggle.setAttribute("aria-controls", aside.id);
     actions.append(toggle);
 
-    const wideQuery = typeof matchMedia === "function" ? matchMedia(WIDE) : null;
-    const wide = () => !wideQuery || wideQuery.matches;
     const isOpen = () => main.classList.contains("inspector-open");
     // Over the chat, on a narrow screen, the drawer is all there is to reach:
     // the chat behind it is inert until it closes or the screen widens.
@@ -322,17 +333,20 @@ export function mountChat({
   // init tool's row, a welcome surface) doesn't replace them.
   const engaged = () => chat.state.blocks.some((b) => b.kind === "user" || b.kind === "interaction");
   const render = () => {
-    renderTranscript(transcript, chat);
+    renderTranscript(transcript, chat, docked ? { onDock: docked.onDock } : {});
     if (!engaged()) transcript.append(emptyState());
+    docked?.sync();
   };
 
   // ── status ─────────────────────────────────────────────────────────
-  // A live region: it changes only when the status does, so a screen reader
-  // hears "Thinking" once a turn, not once per streamed word.
+  // A live region: it changes only when the status does, or where the
+  // question it waits on is, so a screen reader hears "Thinking" once a turn,
+  // not once per streamed word.
   let shownStatus = null;
   function showStatus(status) {
-    if (status === shownStatus) return;
-    shownStatus = status;
+    const where = status === "awaiting" && docked?.waiting() ? "in the dock" : "above";
+    if (`${status} ${where}` === shownStatus) return;
+    shownStatus = `${status} ${where}`;
     statusEl.dataset.status = status;
     statusEl.replaceChildren();
     if (status === "streaming") {
@@ -341,15 +355,27 @@ export function mountChat({
       dots.append(h("i"), h("i"), h("i"));
       statusEl.append(dots, "Thinking");
     } else if (status === "awaiting") {
-      statusEl.append(h("span", "hai-pulse"), "Waiting on your selection above");
+      statusEl.append(h("span", "hai-pulse"), `Waiting on your selection ${where}`);
     }
   }
 
+  // The status line and the message box say where the question waiting on the
+  // reader is: above, or in the dock.
+  function showWaiting() {
+    const { state } = chat;
+    showStatus(state.expired ? "idle" : state.status);
+    input.placeholder =
+      state.expired ? "start a new conversation to continue"
+      : state.status === "awaiting" ? `pick an option ${docked?.waiting() ? "in the dock" : "above"} — or type to override`
+      : placeholder;
+  }
+
   // ── wiring ─────────────────────────────────────────────────────────
   chat.subscribe((state, event) => {
     // chat.close(): the surfaces are unmounted and the chat lets go of this
     // listener; the shell goes too, and nothing of it stays observed.
     if (event.type === "closed") {
+      docked?.release();
       closeTranscript(transcript);
       shell.remove();
       releaseDrawer();
@@ -359,8 +385,12 @@ export function mountChat({
     }
 
     // A new conversation starts at once, so the server's init tool — if it
-    // has one — runs before anything is typed.
-    if (event.type === "reset") start();
+    // has one — runs before anything is typed. The last one's surfaces are
+    // gone, docked ones too.
+    if (event.type === "reset") {
+      docked?.clear();
+      start();
+    }
 
     render();
 
@@ -371,11 +401,7 @@ export function mountChat({
     newBtn.disabled = !engaged() && !state.expired && !state.conversationId;
     input.disabled = state.expired !== null;
     sendBtn.disabled = state.status === "streaming" || state.expired !== null;
-    showStatus(state.expired ? "idle" : state.status);
-    input.placeholder =
-      state.expired ? "start a new conversation to continue"
-      : state.status === "awaiting" ? "pick an option above — or type to override"
-      : placeholder;
+    showWaiting();
 
     if (inspectorBody) {
       renderInspector(inspectorBody, state.context);
@@ -400,6 +426,434 @@ export function mountChat({
   return chat;
 }
 
+/**
+ * The dock: a shelf on top of the composer that a surface goes to when its
+ * Dock button is pressed, and a window above it where one docked surface at a
+ * time opens. Docking moves the surface's element, never mounts it again, so
+ * its component keeps its state; an iframe or video inside starts over, as
+ * it would anywhere a page moves one. The surface's card stays in the
+ * transcript, where Put back returns it.
+ *
+ * When the shelf's row is full, the oldest go into a pile at its end, which
+ * lists them. A surface waiting on the reader, or open, stays in the row.
+ * Remove all, at the shelf's end, puts every docked surface back at once.
+ */
+function createDock({ chat, id, shell, chatPane, transcript, composer, statusEl, wide, wideQuery, drawerOpen, onChange }) {
+  /** Docked surfaces, oldest first. */
+  const entries = [];
+  /** The one open in the window. */
+  let open = null;
+
+  // ── the shelf ────────────────────────────────────────────────────────
+  const shelf = h("div", "hai-dock");
+  shelf.hidden = true;
+  shelf.setAttribute("role", "toolbar");
+  shelf.setAttribute("aria-label", "Docked surfaces");
+  const count = h("span", "hai-dock-count");
+  count.setAttribute("aria-hidden", "true");
+  const row = h("div", "hai-dock-row");
+  const pile = h("span", "hai-dock-pile");
+  pile.hidden = true;
+  const pileBtn = h("button", "hai-dock-item");
+  pileBtn.type = "button";
+  pileBtn.setAttribute("aria-expanded", "false");
+  pileBtn.setAttribute("aria-controls", `${id}-pile`);
+  const pileText = h("span");
+  const pileMark = changedMark();
+  pileBtn.append(icon("stack"), pileText, pileMark);
+  const list = h("div", "hai-pile-list");
+  list.id = `${id}-pile`;
+  list.hidden = true;
+  pile.append(pileBtn, list);
+  // Remove all, at the shelf's end: every docked surface back in the chat
+  const clear = h("button", "hai-dock-clear");
+  clear.type = "button";
+  clear.title = "Remove all from dock";
+  clear.setAttribute("aria-label", "Remove all from the dock");
+  clear.append(icon("undockAll"));
+  shelf.append(count, row, pile, clear);
+  composer.prepend(shelf);
+
+  // ── the window ───────────────────────────────────────────────────────
+  const win = h("section", "hai-window");
+  win.id = `${id}-window`;
+  win.hidden = true;
+  win.tabIndex = -1;
+  win.setAttribute("role", "dialog");
+  win.setAttribute("aria-labelledby", `${id}-window-name`);
+  const winName = h("span", "hai-window-name");
+  winName.id = `${id}-window-name`;
+  const winTool = h("span", "hai-window-tool");
+  const winBadge = h("span", "hai-tstatus hai-window-badge");
+  const remove = h("button", "hai-bar-btn hai-bar-icon");
+  remove.type = "button";
+  remove.title = "Remove from dock";
+  remove.append(icon("undock"));
+  const minimise = h("button", "hai-bar-btn hai-bar-icon");
+  minimise.type = "button";
+  minimise.title = "Dock";
+  minimise.append(icon("dock"));
+  const winBar = h("div", "hai-window-bar");
+  winBar.append(icon("window"), winName, winTool, winBadge, remove, minimise);
+  const winBody = h("div", "hai-window-body");
+  win.append(winBar, winBody);
+
+  // what docking did, for a screen reader: the button pressed has gone
+  const live = h("div", "hai-dock-live");
+  live.setAttribute("role", "status");
+  chatPane.append(win, live);
+
+  // ── each surface, as it is now ───────────────────────────────────────
+  const surfaceOf = (entry) => chat.state.surfaces.get(entry.block.handle);
+  const nameOf = (entry) => surfaceOf(entry)?.component ?? "surface";
+  const toolOf = (entry) => chat.state.blocks.find((b) => b.kind === "tool" && b.id === entry.block.toolId)?.name;
+  // a question still open waits on the reader, as its tool row says
+  const statusOf = (entry) => {
+    if (chat.state.expired) return "expired";
+    const surface = surfaceOf(entry);
+    return surface?.mode === "elicit" && surface.state !== "frozen" ? "awaiting" : "live";
+  };
+
+  function onDock({ handle, card, element }) {
+    if (entries.some((e) => e.card === card)) return;
+    const block = chat.state.blocks.find((b) => b.kind === "ui" && b.handle === handle);
+    if (!block) return;
+    const entry = { block, card, element, bar: card.firstElementChild, props: surfaceOf({ block })?.props, changed: false, stacked: false };
+
+    // what stays in the transcript, in the surface's place
+    entry.stubText = h("span", "hai-docked-text");
+    entry.back = h("button", "hai-bar-btn hai-bar-icon");
+    entry.back.type = "button";
+    entry.back.title = "Put back";
+    entry.back.append(icon("undock"));
+    entry.back.onclick = () => undock(entry, true);
+    const stub = h("div", "hai-docked");
+    stub.append(entry.stubText, entry.back);
+
+    // and its button on the shelf
+    entry.item = h("button", "hai-dock-item");
+    entry.item.type = "button";
+    entry.item.setAttribute("aria-controls", win.id);
+    entry.itemName = h("span");
+    entry.dot = h("span", "hai-dock-dot");
+    entry.dot.setAttribute("aria-hidden", "true");
+    entry.mark = changedMark();
+    entry.item.append(icon("window"), entry.itemName, entry.dot, entry.mark);
+    entry.item.onclick = () => (open === entry ? close(true) : show(entry));
+    row.append(entry.item);
+
+    element.hidden = true;
+    winBody.append(element);
+    card.replaceChildren(stub);
+    card.dataset.docked = "";
+    entries.push(entry);
+    sync();
+    // the reader stays where they were, on the button that undoes it
+    entry.back.focus();
+    live.textContent = `${nameOf(entry)} docked`;
+  }
+
+  function undock(entry, focus) {
+    if (open === entry) close(false);
+    entries.splice(entries.indexOf(entry), 1);
+    entry.item.remove();
+    entry.element.hidden = false;
+    entry.card.replaceChildren(entry.bar, entry.element);
+    delete entry.card.dataset.docked;
+    sync();
+    if (focus) {
+      entry.bar.querySelector("button")?.focus();
+      entry.card.scrollIntoView?.({ block: "nearest" });
+    }
+    live.textContent = `${nameOf(entry)} is back in the chat`;
+  }
+
+  function show(entry) {
+    if (open && open !== entry) open.element.hidden = true;
+    // one opened from the pile comes into the row, as the newest
+    if (entry.stacked) {
+      entries.push(...entries.splice(entries.indexOf(entry), 1));
+      row.append(entry.item);
+    }
+    open = entry;
+    entry.changed = false;
+    entry.element.hidden = false;
+    measure();
+    win.hidden = false;
+    closePile(false);
+    sync();
+    win.focus();
+  }
+
+  function close(focus) {
+    if (!open) return;
+    const entry = open;
+    open = null;
+    entry.element.hidden = true;
+    win.hidden = true;
+    sync();
+    if (focus) (entry.stacked ? pileBtn : entry.item).focus();
+  }
+
+  remove.onclick = () => open && undock(open, true);
+  minimise.onclick = () => close(true);
+
+  // Every docked surface back in its card, oldest first. The shelf goes with
+  // them, so the reader goes to the message box under it, or, once the
+  // conversation has expired and the box is disabled, to the button that
+  // starts a new one.
+  clear.onclick = () => {
+    const n = entries.length;
+    for (const entry of [...entries]) undock(entry, false);
+    const input = composer.querySelector(".hai-input");
+    if (input && !input.disabled) input.focus();
+    else transcript.querySelector(".hai-expired .hai-new")?.focus();
+    live.textContent = n === 1 ? "1 surface is back in the chat" : `${n} surfaces are back in the chat`;
+  };
+
+  // ── keeping up ───────────────────────────────────────────────────────
+  // After every event the chat renders, and after every change here.
+  function sync() {
+    for (const entry of entries) {
+      // new props while docked and closed: the reader hasn't seen them
+      const props = surfaceOf(entry)?.props;
+      if (props !== entry.props) {
+        entry.changed ||= entry !== open;
+        entry.props = props;
+      }
+      const name = nameOf(entry);
+      const status = statusOf(entry);
+      const isOpen = open === entry;
+      setText(entry.itemName, name);
+      setAttr(entry.item, "data-status", status);
+      setAttr(entry.item, "aria-expanded", String(isOpen));
+      setAttr(
+        entry.item,
+        "aria-label",
+        [name, status === "awaiting" && "awaiting you", status === "expired" && "out of date", entry.changed && "changed"]
+          .filter(Boolean)
+          .join(", "),
+      );
+      setHidden(entry.dot, status !== "awaiting");
+      setHidden(entry.mark, !entry.changed);
+      const text = `${name} ${isOpen ? "is open in a window" : "is in the dock"}`;
+      if (entry.stubText.textContent !== text) entry.stubText.replaceChildren(icon("dock"), text);
+      setAttr(entry.back, "aria-label", `Put ${name} back`);
+    }
+    setHidden(shelf, entries.length === 0);
+    setText(count, `docked · ${entries.length}`);
+
+    if (open) {
+      const name = nameOf(open);
+      const tool = toolOf(open);
+      const status = statusOf(open);
+      setAttr(win, "data-status", status);
+      setText(winName, name);
+      setText(winTool, tool ? `· ${tool}` : "");
+      setHidden(winBadge, status === "live");
+      setText(winBadge, status === "awaiting" ? "awaiting you" : "out of date");
+      setAttr(remove, "aria-label", `Remove ${name} from the dock`);
+      setAttr(minimise, "aria-label", `Dock ${name}`);
+    }
+    chatPane.classList.toggle("window-open", open !== null);
+    // over the chat, on a narrow screen, the window is all there is to reach
+    const inert = open !== null && !wide();
+    if (transcript.inert !== inert) transcript.inert = inert;
+    stack();
+    onChange();
+  }
+
+  // Every streamed word reaches sync, so it writes only what has changed: a
+  // dock that stays the same costs no style or layout work.
+  function setText(el, text) {
+    if (el.textContent !== text) el.textContent = text;
+  }
+  function setAttr(el, name, value) {
+    if (el.getAttribute(name) !== value) el.setAttribute(name, value);
+  }
+  function setHidden(el, hidden) {
+    if (el.hidden !== hidden) el.hidden = hidden;
+  }
+
+  // The window sits above the status line and the composer, or on a narrow
+  // screen over everything down to the composer: their heights, as they are.
+  function measure() {
+    chatPane.style.setProperty("--hai-composer-height", `${composer.offsetHeight}px`);
+    chatPane.style.setProperty("--hai-foot", `${composer.offsetHeight + statusEl.offsetHeight}px`);
+  }
+
+  // Into the pile, oldest first, until the row fits. Measured, so it does
+  // nothing where nothing is laid out.
+  let listed = "";
+  /** Each piled surface's row in the list, as last built. */
+  const rows = new Map();
+  // Measured again only when what decides it changes: which surfaces are
+  // docked, in what order, their names, their dots, which is open; or the
+  // room, when the observer below says so.
+  let measured = null;
+  function stack(force = false) {
+    const focused = document.activeElement;
+    const inputs = entries.map((e) => `${e.block.id}:${nameOf(e)}:${statusOf(e) === "awaiting"}:${e === open}`).join(" ");
+    if (force || inputs !== measured) {
+      measured = inputs;
+      for (const entry of entries) entry.item.hidden = false;
+      pile.hidden = true;
+      const stackable = entries.filter((e) => e !== open && statusOf(e) !== "awaiting");
+      let piled = 0;
+      while (row.scrollWidth > row.clientWidth && piled < stackable.length) {
+        stackable[piled++].item.hidden = true;
+        pile.hidden = false;
+        pileText.textContent = `${piled} more`;
+      }
+      for (const entry of entries) entry.stacked = stackable.indexOf(entry) > -1 && stackable.indexOf(entry) < piled;
+      // an item stacked under the reader's focus hands it to the pile, and a
+      // pile that goes hands it to the item now at the row's end, where it was
+      if (entries.some((e) => e.stacked && e.item === focused)) pileBtn.focus();
+      else if (focused === pileBtn && pile.hidden) entries.filter((e) => !e.item.hidden).at(-1)?.item.focus();
+    }
+    const stacked = entries.filter((e) => e.stacked);
+    const changed = stacked.filter((e) => e.changed).length;
+    setHidden(pileMark, changed === 0);
+    setAttr(pileBtn, "aria-label", `${stacked.length} more docked surfaces${changed ? `, ${changed} changed` : ""}`);
+    if (!stacked.length) closePile(false);
+
+    // The list, rebuilt only when what it shows changes: which surfaces, not
+    // just their names, since two can share a component. A reader may be in
+    // it, and keeps their place on the same surface's row.
+    const key = stacked.map((e) => `${e.block.id}:${nameOf(e)}:${e.changed}`).join(" ");
+    if (key === listed) return;
+    listed = key;
+    const focusedEntry = [...rows].find(([, row]) => row === focused)?.[0];
+    rows.clear();
+    list.replaceChildren(h("div", "hai-pile-head", `stacked · ${stacked.length} · oldest first`));
+    for (const entry of stacked) {
+      const b = h("button", "hai-pile-row");
+      b.type = "button";
+      b.append(icon("window"), h("span", "hai-pile-name", nameOf(entry)));
+      if (entry.changed) {
+        const mark = changedMark();
+        mark.hidden = false;
+        b.append(mark);
+      }
+      b.setAttribute("aria-label", `${nameOf(entry)}${entry.changed ? ", changed" : ""}`);
+      b.onclick = () => show(entry);
+      rows.set(entry, b);
+      list.append(b);
+    }
+    // the reader stays on the same surface: its new row, or its item on the
+    // shelf if it has left the pile
+    if (focusedEntry) (rows.get(focusedEntry) ?? (focusedEntry.stacked ? null : focusedEntry.item))?.focus();
+  }
+
+  function openPile() {
+    // no taller than the room above the shelf, in the chat: it scrolls
+    const room = pile.getBoundingClientRect().top - chatPane.getBoundingClientRect().top - 30;
+    list.style.maxHeight = room > 0 ? `${room}px` : "";
+    list.hidden = false;
+    pileBtn.setAttribute("aria-expanded", "true");
+    list.querySelector("button")?.focus();
+  }
+
+  function closePile(focus) {
+    if (list.hidden) return;
+    list.hidden = true;
+    pileBtn.setAttribute("aria-expanded", "false");
+    if (focus) pileBtn.focus();
+  }
+
+  pileBtn.onclick = () => (list.hidden ? openPile() : closePile(true));
+
+  // ── keys and clicks ──────────────────────────────────────────────────
+  // Arrows move along the shelf, and up and down the pile's list.
+  shelf.addEventListener("keydown", (e) => {
+    const inList = list.contains(e.target);
+    const keys = inList ? ["ArrowUp", "ArrowDown", "Home", "End"] : ["ArrowLeft", "ArrowRight", "Home", "End"];
+    if (!keys.includes(e.key)) return;
+    const buttons = inList
+      ? [...list.querySelectorAll("button")]
+      : [...shelf.querySelectorAll(".hai-dock-item, .hai-dock-clear")].filter((b) => !b.hidden && !b.closest("[hidden]"));
+    const at = buttons.indexOf(e.target);
+    if (at < 0) return;
+    e.preventDefault();
+    const step = e.key === "ArrowRight" || e.key === "ArrowDown" ? 1 : -1;
+    const next = e.key === "Home" ? 0 : e.key === "End" ? buttons.length - 1 : (at + step + buttons.length) % buttons.length;
+    buttons[next].focus();
+  });
+
+  // Escape closes the pile's list, then the window: from inside the dock, or
+  // from anywhere while the drawer is closed. With the drawer open, Escape
+  // from outside the dock is the drawer's, even with the list open behind it.
+  // Unless something there used the key first, such as a surface closing a
+  // menu of its own.
+  const onKey = (e) => {
+    if (e.key !== "Escape" || e.defaultPrevented) return;
+    const inside = win.contains(document.activeElement) || shelf.contains(document.activeElement);
+    if (!inside && drawerOpen()) return;
+    if (!list.hidden) {
+      e.preventDefault();
+      closePile(inside);
+      return;
+    }
+    if (!open) return;
+    e.preventDefault();
+    close(inside);
+  };
+  shell.addEventListener("keydown", onKey);
+
+  // a click away from the pile's list closes it, and on a narrow screen a tap
+  // on the chat the window covers docks it again, as a tap outside a sheet does
+  shell.addEventListener("pointerdown", (e) => {
+    if (!list.hidden && !pile.contains(e.target)) closePile(false);
+  });
+  chatPane.addEventListener("click", (e) => {
+    if (e.target === chatPane && transcript.inert) close(true);
+  });
+
+  // Across the breakpoint the shelf's count comes or goes, so the row's room
+  // changes though the composer's width may not, and no resize says so.
+  const onResize = () => {
+    measured = null;
+    sync();
+  };
+  wideQuery?.addEventListener("change", onResize);
+  // the room changed: the window's place, and what fits on the shelf
+  const resized = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(() => (measure(), stack(true)));
+  resized?.observe(composer);
+  resized?.observe(statusEl);
+
+  return {
+    onDock,
+    sync,
+    /** Whether a surface waiting on the reader is in the dock. */
+    waiting: () => entries.some((e) => statusOf(e) === "awaiting"),
+    /** A new conversation: the last one's surfaces are gone, docked ones too. */
+    clear() {
+      closePile(false);
+      open = null;
+      win.hidden = true;
+      for (const entry of entries) {
+        entry.item.remove();
+        entry.element.remove();
+      }
+      entries.length = 0;
+      sync();
+    },
+    release() {
+      shell.removeEventListener("keydown", onKey);
+      wideQuery?.removeEventListener("change", onResize);
+      resized?.disconnect();
+    },
+  };
+}
+
+/** The accent square a docked surface wears while it has changed unseen. */
+function changedMark() {
+  const mark = h("span", "hai-dock-changed");
+  mark.setAttribute("aria-hidden", "true");
+  mark.hidden = true;
+  return mark;
+}
+
 /** A header button: an icon, and a label that narrow screens keep for screen
  *  readers only. */
 function button(className, iconName, label) {

package/src/hai.css

@@ -205,6 +205,7 @@
 /* the conversation is a centred column; the scrollbar stays at the edge */
 .hai-chat {
   --hai-gutter: max(16px, calc((100% - var(--hai-column)) / 2));
+  position: relative;
   display: flex;
   flex-direction: column;
   min-width: 0;
@@ -312,9 +313,11 @@
   background: var(--hai-panel-2);
   overflow: hidden;
 }
-.hai-tool:has(+ .hai-surface) { margin-bottom: 0; border-bottom-left-radius: 0; border-bottom-right-radius: 0; }
+.hai-tool:has(+ .hai-surface),
+.hai-tool:has(+ .hai-dockable) { margin-bottom: 0; border-bottom-left-radius: 0; border-bottom-right-radius: 0; }
 /* a row and its live surface are one card, under one shadow */
-.hai-tool:has(+ .hai-surface:not([data-expired])) { box-shadow: var(--hai-shadow); }
+.hai-tool:has(+ .hai-surface:not([data-expired])),
+.hai-tool:has(+ .hai-dockable:not([data-expired]):not([data-docked])) { box-shadow: var(--hai-shadow); }
 .hai-tool summary {
   display: flex;
   align-items: center;
@@ -486,6 +489,81 @@
 
 /* out of date — the runtime has made the surface inert; this only shows it */
 .hai-surface[data-expired] { opacity: .45; filter: grayscale(.7); box-shadow: none; }
+
+/* ── the dock: a surface's card, its bar, and what stays when it docks ─ */
+/* With the dock on, a surface mounts inside a card of its own: a bar with its
+   name and Dock, then the surface. The card is what the transcript keeps; the
+   surface itself moves to the dock and back. */
+.hai-dockable {
+  margin-bottom: 18px;
+  overflow: hidden;
+  border: 3px solid var(--hai-line);
+  border-radius: var(--hai-radius);
+  background: var(--hai-panel);
+  box-shadow: var(--hai-shadow);
+}
+.hai-tool + .hai-dockable { border-top: none; border-top-left-radius: 0; border-top-right-radius: 0; }
+.hai-dockable > .hai-surface,
+.hai-dockable > .hai-surface-error,
+.hai-window-body > .hai-surface,
+.hai-window-body > .hai-surface-error { margin: 0; border: none; border-radius: 0; box-shadow: none; }
+.hai-dockable[data-expired] { box-shadow: none; }
+/* docked: a flat stub in the surface's place */
+.hai-dockable[data-docked] { background: var(--hai-panel-2); box-shadow: none; }
+
+.hai-surface-bar {
+  display: flex;
+  align-items: stretch;
+  min-height: 34px;
+  border-bottom: 2px solid var(--hai-line);
+  background: var(--hai-panel-2);
+  color: var(--hai-fg);
+}
+.hai-surface-name {
+  flex: 1;
+  min-width: 0;
+  align-self: center;
+  padding: 0 14px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font: 700 11.5px var(--hai-mono);
+  color: var(--hai-dim);
+}
+/* a button that is a bar's cell, an icon named for screen readers and in a
+   tooltip: Dock, Put back, and the window's Remove from dock and Dock */
+.hai-bar-btn {
+  flex: none;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 6px;
+  padding: 0 12px;
+  border: none;
+  border-left: 2px solid;
+  border-radius: 0;
+  background: none;
+  color: inherit;
+  font: 700 12px var(--hai-mono);
+  cursor: pointer;
+}
+.hai-bar-btn .hai-icon { width: 14px; height: 14px; stroke-width: 2.5; }
+.hai-bar-btn:hover { background: var(--hai-hover); }
+.hai-bar-icon { width: 40px; padding: 0; }
+.hai-bar-icon .hai-icon { width: 16px; height: 16px; }
+
+.hai-docked { display: flex; align-items: stretch; min-height: 40px; color: var(--hai-fg); }
+.hai-docked-text {
+  flex: 1;
+  min-width: 0;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 0 14px;
+  font: 12px var(--hai-mono);
+  color: var(--hai-dim);
+}
+.hai-docked-text .hai-icon { width: 14px; height: 14px; stroke-width: 2.5; }
 .hai-expired {
   flex-wrap: wrap;
   align-items: center;
@@ -577,6 +655,269 @@
 .hai-send .hai-icon { width: 18px; height: 18px; stroke-width: 2.5; }
 .hai-send:disabled { opacity: .35; cursor: default; }
 
+/* ── the dock's shelf, on top of the composer ───────────────────────── */
+/* The composer card's top row while anything is docked: one card, one
+   shadow. Not positioned, so the box below covers the shelf's own shadow. */
+.hai-dock {
+  /* Remove all's size: the pile's list lines up past it, with the shelf's end */
+  --hai-dock-clear: 36px;
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 0 14px 0 12px;
+  border: 3px solid var(--hai-line);
+  border-radius: var(--hai-radius) var(--hai-radius) 0 0;
+  background: var(--hai-panel-2);
+  box-shadow: var(--hai-shadow);
+  transition: box-shadow .15s;
+}
+.hai-dock[hidden] { display: none; }
+.hai-dock:not([hidden]) + .hai-composer-box { border-top: none; border-top-left-radius: 0; border-top-right-radius: 0; }
+.hai-composer:has(.hai-composer-box:focus-within) > .hai-dock { box-shadow: 4px 4px 0 var(--hai-accent); }
+.hai-dock-count { flex: none; font: 700 11px var(--hai-mono); color: var(--hai-dim); }
+/* room above and to the right for an item's corner mark, below for its shadow */
+.hai-dock-row {
+  flex: 1;
+  min-width: 0;
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 8px 8px 8px 0;
+  overflow-x: auto;
+  scrollbar-width: none;
+}
+
+/* a docked surface: open is pressed and inked; amber waits on you */
+.hai-dock-item {
+  position: relative;
+  flex: none;
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  height: 36px;
+  padding: 0 12px;
+  box-sizing: border-box;
+  border: 2px solid var(--hai-line);
+  border-radius: var(--hai-radius);
+  background: var(--hai-panel);
+  box-shadow: 3px 3px 0 var(--hai-line);
+  color: var(--hai-fg);
+  font: 700 12px var(--hai-mono);
+  white-space: nowrap;
+  cursor: pointer;
+}
+.hai-dock-item[hidden] { display: none; }
+.hai-dock-item .hai-icon { width: 14px; height: 14px; stroke-width: 2.5; }
+.hai-dock-item:hover { background-image: linear-gradient(var(--hai-hover) 0 0); }
+.hai-dock-item[data-status="awaiting"] { background-color: var(--hai-warn); color: var(--hai-on-accent); }
+.hai-dock-item[aria-expanded="true"] {
+  background: var(--hai-fg);
+  color: var(--hai-panel);
+  box-shadow: none;
+  transform: translate(3px, 3px);
+}
+.hai-dock-item[data-status="expired"] {
+  border-style: dashed;
+  border-color: var(--hai-dim);
+  background: transparent;
+  box-shadow: none;
+  color: var(--hai-dim);
+}
+.hai-dock-dot {
+  width: 10px;
+  height: 10px;
+  box-sizing: border-box;
+  border: 2px solid;
+  border-radius: 50%;
+  background: var(--hai-accent);
+}
+.hai-dock-dot[hidden] { display: none; }
+.hai-dock-item[aria-expanded="true"] .hai-dock-dot { background: var(--hai-warn); }
+.hai-dock-changed {
+  position: absolute;
+  top: -7px;
+  right: -7px;
+  width: 12px;
+  height: 12px;
+  box-sizing: border-box;
+  border: 2px solid var(--hai-line);
+  background: var(--hai-accent);
+}
+.hai-dock-changed[hidden] { display: none; }
+
+/* the pile the oldest go into when the row is full: two edges behind it */
+.hai-dock-pile {
+  position: relative;
+  /* above an open window, which its list may overlap */
+  z-index: 6;
+  isolation: isolate;
+  flex: none;
+  display: inline-flex;
+  margin: 8px 8px 8px 0;
+}
+.hai-dock-pile[hidden] { display: none; }
+.hai-dock-pile::before,
+.hai-dock-pile::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  z-index: -1;
+  box-sizing: border-box;
+  border: 2px solid var(--hai-line);
+  background: var(--hai-panel);
+  transform: translate(8px, -8px);
+}
+.hai-dock-pile::after { transform: translate(4px, -4px); }
+/* Remove all, at the shelf's end: a quiet icon until the pointer's on it */
+.hai-dock-clear {
+  flex: none;
+  display: grid;
+  place-items: center;
+  width: var(--hai-dock-clear);
+  height: var(--hai-dock-clear);
+  padding: 0;
+  border: 2px solid transparent;
+  border-radius: var(--hai-radius);
+  background: none;
+  color: var(--hai-dim);
+  cursor: pointer;
+}
+.hai-dock-clear .hai-icon { width: 16px; height: 16px; stroke-width: 2.5; }
+.hai-dock-clear:hover { border-color: var(--hai-line); background: var(--hai-hover); color: var(--hai-fg); }
+/* what's in it, oldest first, above the shelf */
+/* Its right edge lines up with the shelf's: past the pile's margin, the gap,
+   Remove all, the shelf's padding and its border. So it opens leftward from
+   the shelf's end, and fits whatever the screen fits. */
+.hai-pile-list {
+  position: absolute;
+  right: calc(-1 * (8px + 10px + var(--hai-dock-clear, 36px) + 14px + 3px));
+  bottom: calc(100% + 18px);
+  z-index: 6;
+  width: 280px;
+  max-width: calc(100vw - 32px);
+  /* the room above the shelf, measured as it opens; this until then */
+  max-height: 60vh;
+  overflow-y: auto;
+  scrollbar-width: thin;
+  scrollbar-color: var(--hai-line) transparent;
+  border: 3px solid var(--hai-line);
+  border-radius: var(--hai-radius);
+  background: var(--hai-panel);
+  box-shadow: var(--hai-shadow);
+}
+.hai-pile-list[hidden] { display: none; }
+.hai-pile-head {
+  position: sticky;
+  top: 0;
+  padding: 6px 12px;
+  border-bottom: 2px solid var(--hai-line);
+  background: var(--hai-panel-2);
+  font: 700 11px var(--hai-mono);
+  color: var(--hai-dim);
+}
+.hai-pile-row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  width: 100%;
+  min-height: 44px;
+  padding: 0 12px;
+  border: none;
+  border-bottom: 2px solid var(--hai-line-soft);
+  background: none;
+  color: var(--hai-fg);
+  font: 700 12px var(--hai-mono);
+  text-align: left;
+  cursor: pointer;
+}
+.hai-pile-row:last-child { border-bottom: none; }
+.hai-pile-row:hover { background: var(--hai-hover); }
+.hai-pile-row .hai-icon { width: 14px; height: 14px; stroke-width: 2.5; }
+.hai-pile-name { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; }
+.hai-pile-row .hai-dock-changed { position: static; flex: none; }
+
+/* ── a docked surface, open as a window ─────────────────────────────── */
+/* Above the status line and the composer, in the column; raised higher than a
+   card. Its title bar is inked like its pressed item, amber while it waits. */
+.hai-window {
+  position: absolute;
+  z-index: 5;
+  left: var(--hai-gutter);
+  bottom: calc(var(--hai-foot, 140px) + 8px);
+  display: flex;
+  flex-direction: column;
+  width: min(560px, 100% - 2 * var(--hai-gutter));
+  max-height: calc(100% - var(--hai-foot, 140px) - 32px);
+  box-sizing: border-box;
+  border: 3px solid var(--hai-line);
+  border-radius: var(--hai-radius);
+  background: var(--hai-panel);
+  box-shadow: 8px 8px 0 var(--hai-line);
+  color: var(--hai-fg);
+}
+.hai-window[hidden] { display: none; }
+.hai-window:focus { outline: none; }
+.hai-window:focus-visible { outline: 3px solid var(--hai-fg); outline-offset: 2px; }
+.hai-window-bar {
+  flex: none;
+  display: flex;
+  align-items: stretch;
+  gap: 10px;
+  min-height: 40px;
+  padding-left: 12px;
+  border-bottom: 3px solid var(--hai-line);
+  background: var(--hai-fg);
+  color: var(--hai-panel);
+}
+.hai-window-bar > .hai-icon { align-self: center; width: 14px; height: 14px; stroke-width: 2.5; }
+/* a long name gives way, after the tool's, so the bar's buttons stay in reach */
+.hai-window-name {
+  flex: 0 1 auto;
+  min-width: 0;
+  align-self: center;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font: 700 12.5px var(--hai-mono);
+}
+.hai-window-tool {
+  flex: 1;
+  min-width: 0;
+  align-self: center;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font: 12px var(--hai-mono);
+}
+.hai-window-badge { flex: none; align-self: center; }
+.hai-window-badge[hidden] { display: none; }
+.hai-window-bar > .hai-bar-btn + .hai-bar-btn { margin-left: -10px; }
+.hai-window[data-status="awaiting"] .hai-window-bar { background: var(--hai-warn); color: var(--hai-on-accent); }
+.hai-window[data-status="expired"] { border-style: dashed; border-color: var(--hai-dim); box-shadow: none; }
+.hai-window[data-status="expired"] .hai-window-bar {
+  border-bottom-style: dashed;
+  border-color: var(--hai-dim);
+  background: color-mix(in srgb, var(--hai-dim) 10%, var(--hai-panel-2));
+  color: var(--hai-fg);
+}
+.hai-window[data-status="expired"] .hai-window-badge { background: none; }
+.hai-window-body {
+  min-height: 0;
+  overflow-y: auto;
+  scrollbar-width: thin;
+  scrollbar-color: var(--hai-line) transparent;
+}
+
+/* for a screen reader only: what docking just did */
+.hai-dock-live {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+}
+
 /* ── model context debug drawer ─────────────────────────────────────── */
 /* Closed, it waits off the right edge, out of the tab order and the
    accessibility tree; open, it slides in, over the chat on a narrow screen. */
@@ -652,6 +993,32 @@
     clip-path: inset(50%);
     white-space: nowrap;
   }
+  /* the window is a sheet over the chat, down to the composer; the chat
+     behind it dims, out of reach until it docks again */
+  .hai-window {
+    left: 0;
+    right: 0;
+    top: 12%;
+    bottom: var(--hai-composer-height, 120px);
+    width: auto;
+    max-height: none;
+    border-left: none;
+    border-right: none;
+    border-radius: 0;
+    box-shadow: none;
+  }
+  .hai-chat.window-open > .hai-transcript,
+  .hai-chat.window-open > .hai-status { opacity: .4; }
+  .hai-dock-count { display: none; }
+}
+/* a finger's worth, wherever the pointer is coarse */
+@media (pointer: coarse) {
+  .hai-dock-item { height: 44px; }
+  .hai-dock { --hai-dock-clear: 44px; }
+  .hai-surface-bar { min-height: 44px; }
+  .hai-docked { min-height: 44px; }
+  .hai-window-bar { min-height: 44px; }
+  .hai-bar-icon { width: 44px; }
 }
 @media (max-width: 599.98px) {
   .hai-model { display: none; }
@@ -667,6 +1034,12 @@
 .hai-new:focus-visible { outline: 3px solid var(--hai-fg); outline-offset: 2px; }
 /* inside the row's border, clear of it, in the row's text colour: ink on amber too */
 .hai-tool summary:focus-visible { outline: 2px solid currentColor; outline-offset: -5px; }
+/* the dock's items and its pile take the buttons' ring; a bar's cells and the
+   pile's rows, where a card would clip it, a ring inside */
+.hai-dock-item:focus-visible,
+.hai-dock-clear:focus-visible { outline: 3px solid var(--hai-fg); outline-offset: 2px; }
+.hai-bar-btn:focus-visible,
+.hai-pile-row:focus-visible { outline: 2px solid currentColor; outline-offset: -6px; }
 
 @keyframes hai-pulse {
   0% { box-shadow: 0 0 0 0 color-mix(in srgb, var(--hai-warn) 55%, transparent); }
@@ -682,6 +1055,7 @@
   .hai-shimmer { animation: none; }
   .hai-chevron,
   .hai-composer-box,
+  .hai-dock,
   .hai-chat,
   .hai-inspector,
   .hai-main.inspector-open > .hai-inspector { transition: none; }

package/src/icons.js

@@ -16,6 +16,13 @@ const PATHS = {
   alert: "M4 4h16v16H4zM12 8v5M12 16.5v.01",
   clock: "M12 3a9 9 0 1 0 0 18 9 9 0 0 0 0-18zM12 7v5l3.5 2",
   reply: "M5 4v7a4 4 0 0 0 4 4h10M15 11l4 4-4 4",
+  // the dock: a surface as a window, down onto the shelf, up back into the
+  // chat, and the pile the oldest go into when the shelf is full
+  window: "M4 5h16v14H4zM4 9h16",
+  dock: "M12 4v10M7.5 9.5 12 14l4.5-4.5M4 20h16",
+  undock: "M12 16V4M7.5 8.5 12 4l4.5 4.5M4 20h16",
+  undockAll: "M12 13V3M7.5 7.5 12 3l4.5 4.5M4 17h16M4 21h16",
+  stack: "M3 8h13v13H3zM8 8V3h13v13h-5",
 };
 
 const SVG = "http://www.w3.org/2000/svg";

package/src/transcript.d.ts

@@ -11,6 +11,26 @@ export function h<K extends keyof HTMLElementTagNameMap>(
   text?: string | null,
 ): HTMLElementTagNameMap[K];
 
+/** A surface whose Dock button was pressed, as `renderTranscript` hands it to `onDock`. */
+export interface DockRequest {
+  /** The surface's handle, as it is now. */
+  handle: string;
+  /** Its card, `div.hai-dockable`: stays in the transcript, in the surface's place. */
+  card: HTMLElement;
+  /** The element the surface is mounted in, `div.hai-surface`, inside the card. */
+  element: HTMLElement;
+}
+
+export interface TranscriptOptions {
+  /**
+   * Makes surfaces dockable. Each one is drawn in a card, `div.hai-dockable`:
+   * a bar with its component's name and, once mounted, a Dock button that
+   * calls this. Moving `element` elsewhere keeps its component mounted; the
+   * transcript leaves the card's contents to you. `mountChat` passes its dock.
+   */
+  onDock?: (request: DockRequest) => void;
+}
+
 /**
  * The default transcript renderer. Call it on every event: a block keeps its
  * element while what it shows is unchanged, so each surface mounts once and
@@ -19,7 +39,7 @@ export function h<K extends keyof HTMLElementTagNameMap>(
  * Once the reader scrolls up, it keeps their place until they scroll back
  * down. Deliberately plain — this is the part you are expected to replace.
  */
-export function renderTranscript(root: HTMLElement, chat: Chat): void;
+export function renderTranscript(root: HTMLElement, chat: Chat, options?: TranscriptOptions): void;
 
 /**
  * Stop following a transcript that is going away, so its resize observer and

package/src/transcript.js

@@ -15,7 +15,7 @@ export const h = (tag, className, text) => {
   return node;
 };
 
-export function renderTranscript(root, chat) {
+export function renderTranscript(root, chat, { onDock } = {}) {
   const { state } = chat;
   const follow = follower(root);
 
@@ -43,18 +43,24 @@ export function renderTranscript(root, chat) {
     const before = follow.shown.get(block.id);
     let el = before?.el;
     if (before?.look !== look) {
-      el = renderBlock(block, chat);
+      el = renderBlock(block, chat, onDock);
       // an expanded tool row stays expanded when its status changes
       if (before?.el.open) el.open = true;
     } else if (block.kind === "ui" && el.dataset.handle !== block.handle) {
-      // a revision moved this surface to a new handle; its element stays
+      // a revision moved this surface to a new handle; its element stays,
+      // and so does its card's surface, wherever the dock has put it
       el.dataset.handle = block.handle;
+      const surface = cards.get(el);
+      if (surface) surface.dataset.handle = block.handle;
     } else if (block.progress !== before.progress) {
       // Progress changes the row in place. Rebuilt for every frame, a row a
       // keyboard user is on would take their focus up to ten times a second.
       const parts = rowParts.get(el);
       if (parts) showStatus(parts, block, toolStatus(block, chat));
     }
+    // a card is out of date when its surface is, docked or not
+    const surface = cards.get(el);
+    if (surface) el.toggleAttribute("data-expired", surface.hasAttribute("data-expired"));
     shown.set(block.id, { el, look, progress: block.progress });
     return el;
   });
@@ -286,7 +292,36 @@ function follower(root) {
   return follow;
 }
 
-function renderBlock(block, chat) {
+/** A dockable card's element → the element its surface mounts into, wherever that is now. */
+const cards = new WeakMap();
+
+/**
+ * A surface in a card of its own: a bar with its component's name and, once it
+ * has mounted, a Dock button that hands it to `onDock`. The card stays in the
+ * transcript, in the surface's place; what happens to the surface is the
+ * dock's to decide.
+ */
+function dockable(block, el, surface, onDock) {
+  const card = h("div", "hai-dockable");
+  card.dataset.handle = block.handle;
+  const name = surface?.component ?? "surface";
+  const bar = h("div", "hai-surface-bar");
+  bar.append(h("span", "hai-surface-name", name));
+  if (surface?.props) {
+    const dock = h("button", "hai-bar-btn hai-bar-icon");
+    dock.type = "button";
+    dock.title = "Dock";
+    dock.setAttribute("aria-label", `Dock ${name}`);
+    dock.append(icon("dock"));
+    dock.onclick = () => onDock({ handle: card.dataset.handle, card, element: el });
+    bar.append(dock);
+  }
+  card.append(bar, el);
+  cards.set(card, el);
+  return card;
+}
+
+function renderBlock(block, chat, onDock) {
   switch (block.kind) {
     case "user": {
       const el = h("div", "hai-block hai-user");
@@ -377,7 +412,7 @@ function renderBlock(block, chat) {
         for (let i = 0; i < 3; i++) skeleton.append(h("div", "hai-shimmer"));
         el.append(skeleton);
       }
-      return el;
+      return onDock ? dockable(block, el, surface, onDock) : el;
     }
 
     // Something the server told this conversation outside of any request. The