@haikit/client 0.17.0 → 0.19.0

package/README.md

@@ -89,6 +89,9 @@ 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
@@ -132,6 +135,29 @@ name the registry doesn't list renders an error card. Like a surface, `mount`
 may return `{ unmount }`. With `createChat`, mount one yourself with
 `chat.mountNotice(seq, element)`.
 
+## Signals
+
+A signal (`hai.signal`) is a broadcast to every open browser, such as how many
+people are online. It comes down the same events stream, and goes to a
+handler, never to the transcript:
+
+```js
+mountChat({
+  root, registry,
+  signals: {
+    online(payload, { version }) {
+      badge.textContent = `${payload.count} reading now`;
+    },
+  },
+});
+```
+
+Each signal's latest payload is also in `state.signals`, by name, and
+subscribers hear a `signal` event. A stream that opens is sent each signal's
+latest value first, so the handler runs as soon as the events stream is up.
+Signals carry no id: a reconnect is sent the latest values again rather than
+the ones it missed.
+
 ## 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.17.0",
+  "version": "0.19.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

@@ -1,10 +1,12 @@
-import type { Chat, NoticeRegistry, Registry } from "./index.js";
+import type { Chat, NoticeRegistry, Registry, SignalRegistry } from "./index.js";
 
 export interface MountChatOptions {
   root: HTMLElement;
   registry: Registry;
   /** Components for the notices the server sends, by notice name. */
   notices?: NoticeRegistry;
+  /** Handlers for the signals the server sends, by signal name. */
+  signals?: SignalRegistry;
   /** Base path the server's two routes are mounted at. Default `/hai`. */
   endpoint?: string;
   title?: string;

package/src/app.js

@@ -101,6 +101,7 @@ export function mountChat({
   root,
   registry,
   notices,
+  signals,
   endpoint = "/hai",
   title = "HaiKIT",
   subtitle = "",
@@ -110,7 +111,7 @@ export function mountChat({
   emptyText = "",
   theme,
 }) {
-  const chat = createChat({ endpoint, registry, notices });
+  const chat = createChat({ endpoint, registry, notices, signals });
   const id = `hai-${++shells}`;
 
   // Unset, the page follows the system. A pin goes on the root, where hai.css

package/src/index.d.ts

@@ -128,6 +128,15 @@ export interface NoticeDef<P = any> {
   mount(element: HTMLElement, payload: P, ctx: NoticeMountCtx): NoticeInstance | null | void;
 }
 
+/**
+ * What the browser does with a signal: a handler, called with its payload each
+ * time one arrives. Signals are never drawn in the transcript.
+ */
+export type SignalHandler<P = any> = (payload: P, ctx: { version: number }) => void;
+
+/** Handlers for the signals the server sends, by signal name. */
+export type SignalRegistry = Record<string, SignalHandler<any>>;
+
 /** The notices allowlist, by notice name. Separate from `Registry`, so names never clash. */
 export type NoticeRegistry = Record<string, NoticeDef<any>>;
 
@@ -171,6 +180,8 @@ export interface ChatState {
   expired: string | null;
   /** Notices the server has sent this conversation, in order. */
   notices: NoticeRecord[];
+  /** Each signal's latest payload, by name, since the events stream opened. */
+  signals: Record<string, unknown>;
 }
 
 export interface Chat {
@@ -229,4 +240,9 @@ export interface Chat {
  * `GET {endpoint}/events` open for the conversation, resuming after the last
  * notice it saw if the connection drops, until `reset()` or `close()`.
  */
-export function createChat(options: { endpoint?: string; registry: Registry; notices?: NoticeRegistry }): Chat;
+export function createChat(options: {
+  endpoint?: string;
+  registry: Registry;
+  notices?: NoticeRegistry;
+  signals?: SignalRegistry;
+}): Chat;

package/src/index.js

@@ -12,7 +12,7 @@
 /**
  * @param {{endpoint?: string, registry: Record<string, {mount: Function}>, notices?: Record<string, {mount: Function}>}} options
  */
-export function createChat({ endpoint = "/hai", registry, notices = {} }) {
+export function createChat({ endpoint = "/hai", registry, notices = {}, signals = {} }) {
   const listeners = new Set();
   const state = {
     conversationId: null,
@@ -33,9 +33,19 @@ export function createChat({ endpoint = "/hai", registry, notices = {} }) {
     expired: null,
     /** Notices the server has sent this conversation, in the order they were sent. */
     notices: [],
+    /**
+     * Each signal's latest payload, by name, since the events stream opened.
+     * No prototype, so a signal can be named anything, `__proto__` included.
+     */
+    signals: Object.create(null),
   };
 
   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 +105,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 +227,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,13 +247,25 @@ 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.kind === "ui" && b.handle === 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 state.blocks.splice(afterNotices(at), 0, block);
         break;
       }
 
+      // A broadcast to every open browser. Never stored, so there is nothing
+      // to resume: its latest value is kept, and its handler hears it.
+      case "signal": {
+        state.signals[event.name] = event.payload;
+        // the app's own handlers only, never one an object inherits, such as `toString`
+        const handler = Object.hasOwn(signals, event.name) ? signals[event.name] : undefined;
+        if (typeof handler === "function") attempt(() => handler(event.payload, { version: event.version }));
+        break;
+      }
+
       // A stream that rejoins a wake turn is sent what the turn has shown so
       // far: a block this client already has is brought up to date, not added
       // again.
@@ -269,17 +301,37 @@ export function createChat({ endpoint = "/hai", registry, notices = {} }) {
 
       case "ui_open": {
         if (state.surfaces.has(event.handle)) break; // shown already: a rejoin's catch-up
+        // 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.
-        const old = event.replaces === undefined ? undefined : state.surfaces.get(event.replaces);
+        // `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) {
-          state.surfaces.delete(old.handle);
+          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 === event.replaces);
+          const block = state.blocks.find((b) => b.kind === "ui" && b.handle === was);
           if (block) block.handle = event.handle;
         } else {
           surface = {
@@ -296,10 +348,14 @@ export function createChat({ endpoint = "/hai", registry, notices = {} }) {
           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.
-        const early = state.blocks.filter((b) => b.kind === "notice" && b.handle === event.handle);
+        // 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);
@@ -309,8 +365,8 @@ export function createChat({ endpoint = "/hai", registry, notices = {} }) {
         // whichever is earlier. A revision brings its own, and the one it
         // replaced stops counting.
         if (typeof event.staleAfterMs === "number") {
-          const from = typeof event.ageMs === "number" ? Math.min(sentAt, Date.now() - event.ageMs) : sentAt;
-          surface.deadline = from + event.staleAfterMs;
+          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;
@@ -394,7 +450,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,
@@ -413,13 +469,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;
             }
           }
         }
@@ -534,6 +598,12 @@ export function createChat({ endpoint = "/hai", registry, notices = {} }) {
     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;
@@ -676,6 +746,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);
@@ -687,8 +758,10 @@ export function createChat({ endpoint = "/hai", registry, notices = {} }) {
       expiresAt: null,
       expired: null,
       notices: [],
+      signals: Object.create(null),
     });
     state.surfaces.clear();
+    replacedBy.clear();
     notify({ type: "reset" });
   }
 

package/src/transcript.js

@@ -102,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 = {