@haikit/client 0.15.0 → 0.17.0

package/README.md

@@ -76,10 +76,19 @@ 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.
 
 `chat.close()` is for good: anything open is aborted, every surface is
 unmounted, and subscribers hear `{ type: "closed" }`. `mountChat` then removes
@@ -129,7 +138,15 @@ The server closes a conversation once any surface passes its freshness window.
 The client knows each window too, so a tab left open closes on time instead of
 looking live until a click is refused: `state.expired` holds the notice,
 `send` and `interact` stop sending, and each surface's element is made `inert`
-with `data-expired` set. `chat.reset()` starts a new conversation; the default
+with `data-expired` set.
+
+The browser counts each window from when it sent the request that rendered
+the surface, which is never later than the server's own stamp, so its
+deadline is never later than the server's. Each surface also comes with
+`ageMs`, how long ago the server stored it: the time its digest took, plus,
+for one replayed to a stream that joined a wake turn part way, how long it
+waited. The window is counted from whichever is earlier. That's a duration,
+not a time, so the two clocks are never compared. `chat.reset()` starts a new conversation; the default
 transcript renders the notice with a button that calls it.
 
 ## Serving it

package/package.json

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

@@ -228,13 +228,9 @@ export function createChat({ endpoint = "/hai", registry, notices = {} }) {
         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}`);
+        const at = event.handle === undefined ? -1 : state.blocks.findIndex((b) => b.kind === "ui" && b.handle === event.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,40 +267,70 @@ 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 });
+        // 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.
+        const old = event.replaces === undefined ? undefined : state.surfaces.get(event.replaces);
+        let surface;
+        if (old) {
+          state.surfaces.delete(old.handle);
+          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 === event.replaces);
+          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: 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);
-        }
+        const early = state.blocks.filter((b) => b.kind === "notice" && b.handle === event.handle);
+        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") {
-          const at = sentAt + event.staleAfterMs;
-          if (state.expiresAt === null || at < state.expiresAt) {
-            state.expiresAt = at;
-            closingWindow = event.staleAfterMs;
-            schedule();
-          }
+          const from = typeof event.ageMs === "number" ? Math.min(sentAt, Date.now() - event.ageMs) : sentAt;
+          surface.deadline = from + 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;
       }
 
@@ -496,6 +522,29 @@ 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 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() {
@@ -542,13 +591,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;

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.