@haikit/client 0.6.2 → 0.8.0

package/README.md

@@ -18,6 +18,21 @@ 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.
 
+## Surface lifecycle
+
+The default transcript keeps each block's element for as long as what it
+shows is unchanged, so a surface mounts **once** and keeps its own state — a
+filter, an expanded row, a React tree — while the conversation streams on.
+`mount` may return `{ freeze, expire, unmount }`. `unmount` is called when the
+surface goes away: `chat.reset()` starts a new conversation, `chat.close()`
+ends the chat, or the surface is mounted again. Release there whatever `mount`
+set up.
+
+`chat.close()` is for good: anything open is aborted, every surface is
+unmounted, and subscribers hear `{ type: "closed" }`. `mountChat` then removes
+its shell. A page using `renderTranscript` directly calls `closeTranscript(root)`
+when it removes a transcript, so its resize observer and scroll listener let go.
+
 ## Out-of-date conversations
 
 The server closes a conversation once any surface passes its freshness window.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haikit/client",
-  "version": "0.6.2",
+  "version": "0.8.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

@@ -21,6 +21,9 @@ export interface MountChatOptions {
  * soon as it opens, and again after `reset()`, so a server with an init tool
  * runs it before the user types.
  *
+ * Returns the chat. `chat.close()` ends it for good and removes the shell, so a
+ * page that takes the chat away again leaves nothing of it behind.
+ *
  * It is a convenience, not the API — everything it does is built on `createChat`
  * and `renderTranscript`. Dropping to those when this shell stops fitting is the
  * expected path, not a failure mode.

package/src/app.js

@@ -15,7 +15,7 @@
  */
 
 import { createChat } from "./index.js";
-import { renderTranscript, h } from "./transcript.js";
+import { renderTranscript, closeTranscript, h } from "./transcript.js";
 
 /**
  * @param {{
@@ -111,24 +111,33 @@ export function mountChat({
     return empty;
   }
 
-  const renderEmpty = () => transcript.replaceChildren(emptyState());
+  // Every render goes through the transcript, an empty one included, so the
+  // elements a reset leaves behind are taken out and stop being observed.
+  // The suggestions follow it until the user engages — a first message, or an
+  // answer to something init showed. What the conversation opened with (an
+  // init tool's row, a welcome surface) doesn't replace them.
+  const render = () => {
+    renderTranscript(transcript, chat);
+    if (!chat.state.blocks.some((b) => b.kind === "user" || b.kind === "interaction")) {
+      transcript.append(emptyState());
+    }
+  };
 
   // ── 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") {
+      closeTranscript(transcript);
+      shell.remove();
+      return;
+    }
+
     // 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") chat.start();
 
-    if (state.blocks.length === 0) renderEmpty();
-    else {
-      renderTranscript(transcript, chat);
-      // what the conversation opened with (an init tool's row, a welcome
-      // surface) doesn't replace the suggestions; the user engaging does —
-      // a first message, or an answer to something init showed
-      if (!state.blocks.some((b) => b.kind === "user" || b.kind === "interaction")) {
-        transcript.append(emptyState());
-      }
-    }
+    render();
 
     modelEl.textContent = state.model;
     input.disabled = state.expired !== null;
@@ -154,7 +163,7 @@ export function mountChat({
     }
   };
 
-  renderEmpty();
+  render();
   chat.start();
   return chat;
 }

package/src/index.d.ts

@@ -37,6 +37,8 @@ export interface MountCtx {
   handle: string;
   mode: SurfaceMode;
   state: SurfaceState;
+  /** What the user picked, when the surface is mounted already frozen. */
+  selection?: unknown;
   send(action: string, value: unknown): Promise<void>;
 }
 
@@ -48,10 +50,16 @@ export interface MountCtx {
  * `expire` is called when the conversation goes out of date. By then the
  * runtime has already made the element `inert` and set `data-expired` on it,
  * so nothing inside can reach the server; this hook is only for looks.
+ *
+ * `unmount` is called when the surface goes away: `reset()` starts a new
+ * conversation, `close()` ends the chat, or the surface is mounted again.
+ * Release whatever `mount` set up there — timers, subscriptions, a React root.
+ * The default transcript mounts each surface once, not on every event.
  */
 export interface SurfaceInstance {
   freeze?(selection?: unknown): void;
   expire?(): void;
+  unmount?(): void;
 }
 
 /** Your component. `props` is whatever the surface's `props` schema produces. */
@@ -72,6 +80,8 @@ export interface SurfaceRecord {
   mode: SurfaceMode;
   state: SurfaceState;
   props: unknown | null;
+  /** What the user picked, once frozen. */
+  selection?: unknown;
   instance: SurfaceInstance | null;
   /** The element it was last mounted into. */
   element: HTMLElement | null;
@@ -120,14 +130,27 @@ export interface Chat {
    */
   start(): Promise<boolean>;
   interact(handle: string, action: string, value: unknown): Promise<void>;
-  /** Mounts the surface for `handle` into `element`. Null if props have not arrived. */
+  /**
+   * Mounts the surface for `handle` into `element`. Null if props have not
+   * arrived, or the chat is closed. Mounting a surface again unmounts the
+   * instance it had before.
+   */
   mount(handle: string, element: HTMLElement): SurfaceInstance | null;
   /**
    * Start a new conversation on the next send. Anything queued for the old one
-   * is never sent, and a request still open is aborted — the new conversation
-   * never waits behind it. Subscribers are notified with `{ type: "reset" }`.
+   * is never sent, a request still open is aborted — the new conversation
+   * never waits behind it — and every surface is unmounted. Subscribers are
+   * notified with `{ type: "reset" }`.
    */
   reset(): void;
+  /**
+   * Done with this chat for good, as when the page showing it goes away.
+   * Anything queued is never sent, a request still open is aborted, and every
+   * surface is unmounted. Subscribers are notified with `{ type: "closed" }`
+   * and then dropped. From then on `send` and `start` resolve `false`, and
+   * `interact`, `mount` and `reset` do nothing. `mountChat` removes its shell.
+   */
+  close(): void;
   /** Returns an unsubscribe function. */
   subscribe(fn: (state: ChatState, event: WireEvent) => void): () => void;
 }

package/src/index.js

@@ -64,6 +64,9 @@ export function createChat({ endpoint = "/hai", registry }) {
   let generation = 0;
   let aborter = new AbortController();
 
+  /** Set by close(): this chat is done for good, and does nothing more. */
+  let shutDown = false;
+
   /**
    * When the request now streaming was sent. The server stamps every surface
    * it renders after that request arrived, so a freshness deadline counted from
@@ -101,9 +104,11 @@ export function createChat({ endpoint = "/hai", registry }) {
     });
 
   async function pump(path, body, gen, signal, outcome) {
-    // Checked again here, not only when queued: a long turn ahead of this
-    // request can run past the deadline while it waits.
-    if (closed()) return;
+    // A request left over from before reset() or close() does nothing at all:
+    // not even closing an out-of-date conversation that is no longer this one.
+    // The deadline is checked again here, not only when queued: a long turn
+    // ahead of this request can run past it while it waits.
+    if (gen !== generation || closed()) return;
     sentAt = Date.now();
     let res = await post(path, body, signal);
 
@@ -113,8 +118,8 @@ export function createChat({ endpoint = "/hai", registry }) {
     // retry covers the first and gives up honestly on the second.
     if (res.status === 409) {
       await new Promise((r) => setTimeout(r, 150));
-      // the deadline can pass during the wait, like any other queued request
-      if (closed()) return;
+      // the deadline can pass during the wait, and reset() or close() come
+      if (gen !== generation || closed()) return;
       res = await post(path, body, signal); // rejects at once if reset() aborted it meanwhile
     }
     // Anything but a second 409 means the server took the request up itself —
@@ -217,6 +222,8 @@ export function createChat({ endpoint = "/hai", registry }) {
         const surface = state.surfaces.get(event.handle);
         if (surface) {
           surface.state = event.state;
+          // kept, so a surface mounted again once frozen still knows the answer
+          surface.selection = event.selection;
           surface.instance?.freeze?.(event.selection);
         }
         break;
@@ -293,10 +300,14 @@ export function createChat({ endpoint = "/hai", registry }) {
   /**
    * Mount a surface into an element. Strict allowlist: an unregistered
    * component renders an error card, never an improvised UI.
+   *
+   * One instance per surface. Mounting it again, into this element or another,
+   * unmounts the one before, so nothing that instance set up outlives it.
    */
   function mount(handle, element) {
     const surface = state.surfaces.get(handle);
-    if (!surface || !surface.props) return null;
+    if (shutDown || !surface || !surface.props) return null;
+    unmount(surface);
 
     const definition = registry[surface.component];
     if (!definition) {
@@ -311,6 +322,7 @@ export function createChat({ endpoint = "/hai", registry }) {
       handle,
       mode: surface.mode,
       state: surface.state,
+      selection: surface.selection,
       // The ONLY channel a component has to the server. It passes an action
       // name declared in the contract — never a tool, never a handler.
       send: (action, value) => interact(handle, action, value),
@@ -319,6 +331,18 @@ export function createChat({ endpoint = "/hai", registry }) {
     return surface.instance;
   }
 
+  /**
+   * Let a surface's instance go. A component that throws on its way out still
+   * goes: the error is reported, not allowed to stop a reset or a close part
+   * way through.
+   */
+  function unmount(surface) {
+    const { instance } = surface;
+    surface.instance = null;
+    surface.element = null;
+    attempt(() => instance?.unmount?.());
+  }
+
   // A message is queued, never refused for being busy. It resolves to whether
   // the server took it: false if the conversation went out of date first —
   // at the call, or while it waited behind a long turn — if reset() started
@@ -328,7 +352,7 @@ export function createChat({ endpoint = "/hai", registry }) {
   // caller can also check `state.expired` straight after calling and never
   // clear the input at all.
   async function send(text) {
-    if (!text.trim() || closed()) return false;
+    if (shutDown || !text.trim() || closed()) return false;
     return enqueue("/chat", { message: text });
   }
 
@@ -350,7 +374,7 @@ export function createChat({ endpoint = "/hai", registry }) {
    * like send().
    */
   async function start() {
-    if (begun() || closed()) return false;
+    if (shutDown || begun() || closed()) return false;
     return enqueue("/start", {});
   }
 
@@ -360,19 +384,22 @@ export function createChat({ endpoint = "/hai", registry }) {
   // checked first, so a click that cannot be sent still closes a conversation
   // whose timer slept through its deadline.
   async function interact(handle, action, value) {
-    if (closed() || busy) return;
+    if (shutDown || closed() || busy) return;
     await enqueue("/interact", { handle, action, value });
   }
 
   /**
    * Start over. The next send begins a new conversation. Anything queued for
-   * the old one is never sent, and anything still open is aborted.
+   * the old one is never sent, anything still open is aborted, and every
+   * surface it showed is unmounted.
    */
   function reset() {
+    if (shutDown) return;
     generation++;
     aborter.abort();
     aborter = new AbortController();
     clearTimeout(timer);
+    for (const surface of state.surfaces.values()) unmount(surface);
     Object.assign(state, {
       conversationId: null,
       status: "idle",
@@ -385,6 +412,26 @@ export function createChat({ endpoint = "/hai", registry }) {
     notify({ type: "reset" });
   }
 
+  /**
+   * Done with this chat for good, as when the page that showed it goes away.
+   * Anything queued is never sent, anything open is aborted, every surface is
+   * unmounted, and subscribers hear `{ type: "closed" }` so they can let go of
+   * what they hold. From then on the chat does nothing.
+   */
+  function close() {
+    if (shutDown) return;
+    shutDown = true;
+    generation++;
+    aborter.abort();
+    clearTimeout(timer);
+    for (const surface of state.surfaces.values()) unmount(surface);
+    // Every subscriber hears it, even after one that throws, and none is held
+    // on to: they are let go of before they are told.
+    const subscribers = [...listeners];
+    listeners.clear();
+    for (const fn of subscribers) attempt(() => fn(state, { type: "closed" }));
+  }
+
   return {
     state,
     start,
@@ -392,13 +439,30 @@ export function createChat({ endpoint = "/hai", registry }) {
     interact,
     mount,
     reset,
+    close,
     subscribe(fn) {
+      // a closed chat tells no one anything again, so it keeps no one either
+      if (shutDown) return () => {};
       listeners.add(fn);
       return () => listeners.delete(fn);
     },
   };
 }
 
+/**
+ * Run `fn`, reporting what it throws without letting it stop the caller: the
+ * error surfaces as an uncaught one would, after the caller has finished.
+ */
+function attempt(fn) {
+  try {
+    fn();
+  } catch (err) {
+    queueMicrotask(() => {
+      throw err;
+    });
+  }
+}
+
 /** "2 hours", "15 minutes" — for a sentence a person reads. */
 function duration(ms) {
   const units = [

package/src/transcript.d.ts

@@ -12,10 +12,17 @@ export function h<K extends keyof HTMLElementTagNameMap>(
 ): HTMLElementTagNameMap[K];
 
 /**
- * The default transcript renderer. Replaces `root`'s children on every call.
- * While the reader is at the bottom, it keeps the newest content in view,
- * surfaces included once they have mounted and as they grow. 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.
+ * 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
+ * keeps its own state. While the reader is at the bottom, it keeps the newest
+ * content in view, surfaces included once they have mounted and as they grow.
+ * 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;
+
+/**
+ * Stop following a transcript that is going away, so its resize observer and
+ * scroll listener let go of it. `mountChat` does this when its chat closes.
+ */
+export function closeTranscript(root: HTMLElement): void;

package/src/transcript.js

@@ -19,15 +19,37 @@ export function renderTranscript(root, chat) {
 
   // reset() gives a new conversation a new blocks array, and a new
   // conversation starts at the bottom, wherever the reader was in the last.
-  if (state.blocks !== follow.blocks) Object.assign(follow, { blocks: state.blocks, stick: true, top: 0 });
+  // Its elements are all new too: the old surfaces are already unmounted.
+  if (state.blocks !== follow.blocks) {
+    // the last conversation's elements may already be gone from the page; they
+    // stop being observed either way
+    for (const { el } of follow.shown.values()) follow.observer?.unobserve(el);
+    Object.assign(follow, { blocks: state.blocks, shown: new Map(), stick: true, top: 0 });
+  }
   // A scroll the reader made since the last render, whose event hasn't arrived
   // yet: taken now, or the pin below would overwrite it. Not while an earlier
   // render in this task is still mounting: the reader can't scroll within a
   // task, and the position read then is one clamped to a shorter transcript.
   else if (!follow.mounting) follow.noticeScroll();
 
-  root.replaceChildren();
-  for (const block of state.blocks) root.append(renderBlock(block, chat));
+  // A block keeps its element for as long as what it shows is unchanged, so a
+  // surface mounts once rather than on every event, and whatever its component
+  // holds — a filter, an expanded row, a React tree — lives as long as it does.
+  const shown = new Map();
+  const elements = state.blocks.map((block) => {
+    const look = appearance(block, chat);
+    const before = follow.shown.get(block.id);
+    let el = before?.el;
+    if (before?.look !== look) {
+      el = renderBlock(block, chat);
+      // an expanded tool row stays expanded when its status changes
+      if (before?.el.open) el.open = true;
+    }
+    shown.set(block.id, { el, look });
+    return el;
+  });
+  follow.shown = shown;
+  place(root, elements, follow.observer);
 
   // Surfaces mount in microtasks queued by renderBlock, in block order. This
   // one is queued after them, so it runs once they have content and height:
@@ -37,18 +59,57 @@ export function renderTranscript(root, chat) {
     follow.mounting = false;
     follow.stick ? follow.pin() : follow.hold();
   });
+}
+
+/**
+ * Stop following a transcript that is going away: its resize observer and
+ * scroll listener let go of it. `mountChat` does this when its chat closes; a
+ * page rendering a transcript itself does it when it removes one.
+ */
+export function closeTranscript(root) {
+  followers.get(root)?.close();
+  followers.delete(root);
+}
 
-  // Surfaces can grow after they mount, as a table expands or an image loads.
-  // While following, the observer keeps the newest content in view as they do.
-  // Otherwise it returns the reader to their place, which a rebuild may have
-  // had to clamp while the surfaces above it were still short. The browser
-  // reports scrolls before resizes in a frame, so a scroll the reader has just
-  // made is already their place by then.
-  if (follow.observer) {
-    follow.observer.disconnect();
-    follow.observer.observe(root);
-    for (const child of root.children) follow.observer.observe(child);
+/** What a block's element shows. While this is unchanged, the element is kept. */
+function appearance(block, chat) {
+  // a surface shows a skeleton until its props arrive, and then itself for good
+  if (block.kind === "ui") return chat.state.surfaces.get(block.handle)?.props ? "mounted" : "loading";
+  return JSON.stringify(block);
+}
+
+/**
+ * Put `elements` in order under `root`, moving none that is already there:
+ * one taken out and put back loses its scroll position and focus, and any
+ * iframe or video in it starts over. Whatever else is there goes — a block's
+ * old element, or something the page added after the last render.
+ */
+function place(root, elements, observer) {
+  const wanted = new Set(elements);
+  const drop = (node) => {
+    const next = node.nextSibling;
+    node.remove();
+    // text and comments are dropped too, but only elements were ever observed
+    if (node.nodeType === 1) observer?.unobserve(node);
+    return next;
+  };
+  let at = root.firstChild;
+  for (const el of elements) {
+    while (at && !wanted.has(at)) at = drop(at);
+    if (at === el) {
+      at = at.nextSibling;
+      continue;
+    }
+    root.insertBefore(el, at);
+    // Surfaces can grow after they mount, as a table expands or an image
+    // loads. While following, the observer keeps the newest content in view
+    // as they do. Otherwise it returns the reader to their place, should a
+    // surface above it have been short for a moment. The browser reports
+    // scrolls before resizes in a frame, so a scroll the reader has just made
+    // is already their place by then.
+    observer?.observe(el);
   }
+  while (at) at = drop(at);
 }
 
 /** Within this many pixels of the bottom, the reader is following new content. */
@@ -83,6 +144,8 @@ function follower(root) {
     top: 0,
     // the blocks array of the conversation shown
     blocks: null,
+    // block id → { el, look }: the element showing each block, and what it shows
+    shown: new Map(),
     // a render's surfaces are still to mount
     mounting: false,
     // the reader has scrolled, unless this is where the transcript's own
@@ -112,9 +175,16 @@ function follower(root) {
       typeof ResizeObserver === "undefined"
         ? null
         : new ResizeObserver(() => (follow.stick ? follow.pin() : follow.hold())),
+    close() {
+      follow.observer?.disconnect();
+      root.removeEventListener("scroll", onScroll);
+    },
   };
 
-  root.addEventListener("scroll", () => follow.noticeScroll(), { passive: true });
+  const onScroll = () => follow.noticeScroll();
+  root.addEventListener("scroll", onScroll, { passive: true });
+  // the viewport itself: a window resized while following stays at the bottom
+  follow.observer?.observe(root);
 
   followers.set(root, follow);
   return follow;