@haikit/client 0.18.0 → 0.19.0

package/README.md

@@ -135,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.18.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,6 +33,11 @@ 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));
@@ -251,6 +256,16 @@ export function createChat({ endpoint = "/hai", registry, notices = {} }) {
         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.
@@ -743,6 +758,7 @@ export function createChat({ endpoint = "/hai", registry, notices = {} }) {
       expiresAt: null,
       expired: null,
       notices: [],
+      signals: Object.create(null),
     });
     state.surfaces.clear();
     replacedBy.clear();