@haikit/client 0.16.0 → 0.18.0

package/README.md

@@ -76,10 +76,22 @@ colour at all.
 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.
+`mount` may return `{ freeze, expire, unmount, update }`. `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.
+
+**A tool can revise a surface in place** (`ctx.update`). The revision arrives
+as a `ui_open` naming the handle it `replaces`. The client moves the surface's
+record and transcript block to the new handle, keeping the same element, and
+hands the new props to `update(props)`. Implement it to keep what the
+component holds, such as its scroll, sort or a row the user picked. Without
+it, the component is mounted again in place. Either way, `ctx.send` names the
+surface's current handle, so a click after a revision reaches the new one.
+Each surface keeps its own deadline, and a replaced surface's stops counting.
+A revision app code makes from outside a turn (`hai.update`) arrives the same
+way, on the events stream, and its deadline counts from when the server
+stored it.
 
 `chat.close()` is for good: anything open is aborted, every surface is
 unmounted, and subscribers hear `{ type: "closed" }`. `mountChat` then removes

package/package.json

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

package/src/index.d.ts

@@ -63,7 +63,8 @@ export type WireEvent = { type: string } & Record<string, any>;
  * tool name, never a handler.
  */
 export interface MountCtx {
-  handle: string;
+  /** The surface's handle as it is now: a revision in place (`update`) moves it on. */
+  readonly handle: string;
   mode: SurfaceMode;
   state: SurfaceState;
   /** What the user picked, when the surface is mounted already frozen. */
@@ -89,6 +90,13 @@ export interface SurfaceInstance {
   freeze?(selection?: unknown): void;
   expire?(): void;
   unmount?(): void;
+  /**
+   * The surface was revised in place (a tool's `ctx.update`): these are its
+   * new props. Implement it to keep what the component holds, such as its
+   * scroll, sort or expanded rows. Without it, the runtime mounts the
+   * component again in the same element, losing that.
+   */
+  update?(props: any): void;
 }
 
 /** Your component. `props` is whatever the surface's `props` schema produces. */
@@ -135,6 +143,9 @@ export interface SurfaceRecord {
   instance: SurfaceInstance | null;
   /** The element it was last mounted into. */
   element: HTMLElement | null;
+  /** When it goes out of date, in this browser's clock, or null if never. Its window, in ms. */
+  deadline?: number | null;
+  window?: number;
 }
 
 export interface ChatState {

package/src/index.js

@@ -36,6 +36,11 @@ export function createChat({ endpoint = "/hai", registry, notices = {} }) {
   };
 
   const notify = (event) => listeners.forEach((fn) => fn(state, event));
+  /**
+   * handle -> the handle that replaced it, for every revision this browser has
+   * heard of, including ones it only heard named; followed by `current`.
+   */
+  const replacedBy = new Map();
 
   /**
    * Requests open or waiting to go out — which is not the same as
@@ -95,6 +100,12 @@ export function createChat({ endpoint = "/hai", registry, notices = {} }) {
    * a buffering proxy holds the stream back.
    */
   let sentAt = 0;
+  /**
+   * The last notice the events stream finished sending, by its id: where a
+   * reconnect resumes. Update notices arrive as surface frames, not notices,
+   * so `state.notices` alone would miss them.
+   */
+  let resumeAfter = 0;
 
   // ── transport: SSE over POST (EventSource cannot POST) ──────────────
   function enqueue(path, body) {
@@ -211,7 +222,11 @@ export function createChat({ endpoint = "/hai", registry, notices = {} }) {
     }
   }
 
-  function apply(event) {
+  /**
+   * `from`: when a surface in this event was rendered, at the latest, by this
+   * browser's clock, for one that no request of its own asked for.
+   */
+  function apply(event, from = sentAt) {
     switch (event.type) {
       case "hello":
         state.conversationId = event.conversationId;
@@ -227,14 +242,12 @@ export function createChat({ endpoint = "/hai", registry, notices = {} }) {
         const { type, ...notice } = event;
         state.notices.push(notice);
         const block = { kind: "notice", id: `n:${event.seq}`, ...notice };
-        // beside its surface — after any notices already there — or at the end
-        const at = event.handle === undefined ? -1 : state.blocks.findIndex((b) => b.id === `ui:${event.handle}`);
+        // beside its surface — after any notices already there — or at the end;
+        // one naming an earlier handle of the surface goes beside it as it is now
+        const handle = event.handle === undefined ? undefined : current(event.handle);
+        const at = handle === undefined ? -1 : state.blocks.findIndex((b) => b.kind === "ui" && b.handle === handle);
         if (at < 0) state.blocks.push(block);
-        else {
-          let i = at + 1;
-          while (state.blocks[i]?.kind === "notice" && state.blocks[i].handle === event.handle) i++;
-          state.blocks.splice(i, 0, block);
-        }
+        else state.blocks.splice(afterNotices(at), 0, block);
         break;
       }
 
@@ -271,44 +284,94 @@ export function createChat({ endpoint = "/hai", registry, notices = {} }) {
         break;
       }
 
-      case "ui_open":
+      case "ui_open": {
         if (state.surfaces.has(event.handle)) break; // shown already: a rejoin's catch-up
-        state.surfaces.set(event.handle, {
-          handle: event.handle,
-          component: event.component,
-          version: event.version,
-          mode: event.mode,
-          state: "live",
-          props: null,
-          instance: null,
-          element: null,
-        });
-        state.blocks.push({ kind: "ui", id: `ui:${event.handle}`, handle: event.handle, toolId: event.toolId });
-        // Notices come on a stream of their own, so one can arrive before the
-        // surface it names: it went to the end then, and moves under it now.
-        // Moved within the same array, which the transcript would otherwise
-        // take for a new conversation's.
-        for (const early of state.blocks.filter((b) => b.kind === "notice" && b.handle === event.handle)) {
-          state.blocks.splice(state.blocks.indexOf(early), 1);
-          state.blocks.push(early);
+        // Replaced already: a revision on the events stream overtook the
+        // request that showed the original, held back on its way here. The
+        // surface it became stands, and takes the original's tool row; the
+        // original isn't shown beside it, and its props go nowhere.
+        if (replacedBy.has(event.handle)) {
+          const now = state.blocks.find((b) => b.kind === "ui" && b.handle === current(event.handle));
+          if (now && !now.toolId) now.toolId = event.toolId;
+          break;
         }
+        // A revision of a surface on screen takes over its record in place:
+        // its component, element and state stay, its handle moves on, and its
+        // props stay until the new ones arrive, so the transcript keeps the
+        // same element rather than mounting afresh.
+        // `replaces`, or, for a revision replayed after several, an earlier
+        // handle of the same surface: whichever this browser last saw
+        const old = [event.replaces, ...(event.alsoReplaces ?? [])]
+          .filter((h) => h !== undefined)
+          .map((h) => state.surfaces.get(h))
+          .find(Boolean);
+        // every earlier handle now leads here, seen or not, so a notice naming
+        // one finds this surface
+        for (const h of [event.replaces, ...(event.alsoReplaces ?? [])]) {
+          if (h !== undefined && h !== event.handle) replacedBy.set(h, event.handle);
+        }
+        let surface;
+        if (old) {
+          const was = old.handle;
+          state.surfaces.delete(was);
+          Object.assign(old, { handle: event.handle, component: event.component, version: event.version, revising: true });
+          state.surfaces.set(event.handle, (surface = old));
+          const block = state.blocks.find((b) => b.kind === "ui" && b.handle === was);
+          if (block) block.handle = event.handle;
+        } else {
+          surface = {
+            handle: event.handle,
+            component: event.component,
+            version: event.version,
+            mode: event.mode,
+            state: "live",
+            props: null,
+            instance: null,
+            element: null,
+          };
+          state.surfaces.set(event.handle, surface);
+          state.blocks.push({ kind: "ui", id: `ui:${event.handle}`, handle: event.handle, toolId: event.toolId });
+        }
+        // Notices come on a stream of their own, so one can arrive before the
+        // surface it names, or name a handle of it this browser hadn't heard
+        // of: it went to the end then, and moves under it now, among those
+        // already beside it in the order they were sent. Moved within the
+        // same array, which the transcript would otherwise take for a new
+        // conversation's.
+        const early = state.blocks
+          .filter((b) => b.kind === "notice" && b.handle !== undefined && current(b.handle) === event.handle)
+          .sort((x, y) => x.seq - y.seq);
+        for (const notice of early) state.blocks.splice(state.blocks.indexOf(notice), 1);
+        const at = state.blocks.findIndex((b) => b.kind === "ui" && b.handle === event.handle);
+        if (at >= 0) state.blocks.splice(afterNotices(at), 0, ...early);
+        else state.blocks.push(...early);
+        // Each surface keeps its own deadline: from when the request that
+        // rendered it was sent or, by its age, from when it was stored,
+        // whichever is earlier. A revision brings its own, and the one it
+        // replaced stops counting.
         if (typeof event.staleAfterMs === "number") {
-          // From when the request that rendered it was sent, or, for a surface
-          // replayed to a stream that joined a wake turn part way, from when
-          // it was stored, by its age: whichever is earlier.
-          const from = typeof event.ageMs === "number" ? Math.min(sentAt, Date.now() - event.ageMs) : sentAt;
-          const at = from + event.staleAfterMs;
-          if (state.expiresAt === null || at < state.expiresAt) {
-            state.expiresAt = at;
-            closingWindow = event.staleAfterMs;
-            schedule();
-          }
+          const stored = typeof event.ageMs === "number" ? Math.min(from, Date.now() - event.ageMs) : from;
+          surface.deadline = stored + event.staleAfterMs;
+          surface.window = event.staleAfterMs;
+        } else {
+          surface.deadline = null;
         }
+        refreshDeadline();
         break;
+      }
 
       case "ui_props": {
         const surface = state.surfaces.get(event.handle);
-        if (surface) surface.props = event.props;
+        if (!surface) break;
+        surface.props = event.props;
+        if (surface.revising) {
+          // A revision's props reach the component already mounted: through
+          // its `update`, keeping its own state, or by mounting it again.
+          surface.revising = false;
+          const { instance, element } = surface;
+          if (instance && typeof instance.update === "function") attempt(() => instance.update(event.props));
+          else if (instance && element) mount(surface.handle, element);
+        }
         break;
       }
 
@@ -372,7 +435,7 @@ export function createChat({ endpoint = "/hai", registry, notices = {} }) {
       const opened = Date.now();
       let delivered = false;
       try {
-        const last = state.notices.at(-1)?.seq ?? 0;
+        const last = Math.max(resumeAfter, state.notices.at(-1)?.seq ?? 0);
         const res = await fetch(`${endpoint}/events?conversationId=${encodeURIComponent(conversationId)}`, {
           headers: last ? { "last-event-id": String(last) } : {},
           signal,
@@ -391,13 +454,21 @@ export function createChat({ endpoint = "/hai", registry, notices = {} }) {
               if (gen !== generation) return;
               const frame = buffer.slice(0, i);
               buffer = buffer.slice(i + 2);
-              const line = frame.split("\n").find((l) => l.startsWith("data: "));
+              const lines = frame.split("\n");
+              const line = lines.find((l) => l.startsWith("data: "));
               if (line) {
                 const event = JSON.parse(line.slice(6));
                 followTurn(event);
-                apply(event);
+                // A revision `hai.update` made comes outside any turn, even
+                // while one is running, so no request of this browser's
+                // dates it: only its age does. No tool call made it.
+                const outside = event.type === "ui_open" && event.toolId === "";
+                apply(event, remote && !outside ? sentAt : Date.now());
                 delivered = true;
               }
+              // the notice this frame finished, revisions' included
+              const id = Number(lines.find((l) => l.startsWith("id: "))?.slice(4));
+              if (Number.isSafeInteger(id) && id > resumeAfter) resumeAfter = id;
             }
           }
         }
@@ -500,6 +571,35 @@ export function createChat({ endpoint = "/hai", registry, notices = {} }) {
         `${duration(closingWindow)}. Start a new conversation for current results.`,
     });
 
+  /**
+   * Where a notice for the surface at `at` goes: after the notices already
+   * beside it, which may name an earlier revision of it, so they keep the
+   * order they arrived in. A notice that names no surface sits at the end,
+   * not beside one, and isn't counted among them.
+   */
+  function afterNotices(at) {
+    let i = at + 1;
+    while (state.blocks[i]?.kind === "notice" && state.blocks[i].handle !== undefined) i++;
+    return i;
+  }
+
+  /** The handle a surface has now, following every revision heard of since `handle`. */
+  function current(handle) {
+    while (replacedBy.has(handle)) handle = replacedBy.get(handle);
+    return handle;
+  }
+
+  /** The earliest deadline among the surfaces showing, and which window set it. */
+  function refreshDeadline() {
+    let soonest = null;
+    for (const surface of state.surfaces.values()) {
+      if (surface.deadline != null && (soonest === null || surface.deadline < soonest.deadline)) soonest = surface;
+    }
+    state.expiresAt = soonest?.deadline ?? null;
+    if (soonest) closingWindow = soonest.window;
+    schedule();
+  }
+
   // One timer, for the earliest deadline. setTimeout fires at once for delays
   // past about 24.8 days, so a long wait is taken in steps.
   function schedule() {
@@ -546,13 +646,17 @@ export function createChat({ endpoint = "/hai", registry, notices = {} }) {
     element.replaceChildren();
     surface.element = element;
     surface.instance = definition.mount(element, surface.props, {
-      handle,
+      // the surface as it is now, as `send` below: a revision moves it on
+      get handle() {
+        return surface.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),
+      // and names the surface as it is now: a revision moves it on.
+      send: (action, value) => interact(surface.handle, action, value),
     });
     if (state.expired) seal(surface);
     return surface.instance;
@@ -627,6 +731,7 @@ export function createChat({ endpoint = "/hai", registry, notices = {} }) {
     aborter = new AbortController();
     stopListening();
     cutOff = false;
+    resumeAfter = 0;
     clearTimeout(timer);
     for (const surface of state.surfaces.values()) unmount(surface);
     for (const seq of [...noticeMounts.keys()]) unmountNotice(seq);
@@ -640,6 +745,7 @@ export function createChat({ endpoint = "/hai", registry, notices = {} }) {
       notices: [],
     });
     state.surfaces.clear();
+    replacedBy.clear();
     notify({ type: "reset" });
   }
 

package/src/transcript.js

@@ -46,6 +46,9 @@ export function renderTranscript(root, chat) {
       el = renderBlock(block, chat);
       // 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
+      el.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.
@@ -99,19 +102,20 @@ function toolStatus(block, chat) {
   if (block.status !== "awaiting") return block.status;
   const { blocks, surfaces, expired } = chat.state;
   // Found once per row and kept: every answered question keeps its row
-  // `awaiting`, and this runs for each of them on every streamed event.
-  let handle = questions.get(block);
-  if (handle === undefined) {
-    handle = blocks.find(
+  // `awaiting`, and this runs for each of them on every streamed event. The
+  // surface's block is kept, not its handle, which a revision moves on.
+  let question = questions.get(block);
+  if (question === undefined) {
+    question = blocks.find(
       (b) => b.kind === "ui" && b.toolId === block.id && surfaces.get(b.handle)?.mode === "elicit",
-    )?.handle;
-    if (handle !== undefined) questions.set(block, handle);
+    );
+    if (question !== undefined) questions.set(block, question);
   }
-  if (surfaces.get(handle)?.state === "frozen") return "resolved";
+  if (surfaces.get(question?.handle)?.state === "frozen") return "resolved";
   return expired ? "expired" : "awaiting";
 }
 
-/** A tool row's block → the handle of the question it asked, once seen. */
+/** A tool row's block → the block of the question it asked, once seen. */
 const questions = new WeakMap();
 
 const STATUS_TEXT = {