@haikit/client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hai contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,25 @@
+# @haikit/client
+
+Browser runtime. Plain ESM, no build step.
+
+```js
+import { mountChat } from "@haikit/client/app.js";
+mountChat({ root, registry, suggestions: ["…"] });
+```
+
+`mountChat` is the ten-line path: it builds the shell, wires the composer,
+renders the transcript and mounts your surfaces. It is a convenience, not the
+API — it is built from `createChat` + `renderTranscript`, and dropping to those
+when the default shell stops fitting is the expected path.
+
+`hai.css` styles **only what the framework renders** — transcript blocks, tool
+rows, the surface container, shell, composer, inspector. It deliberately does
+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.
+
+## Serving it
+
+This package ships source, not a bundle. With a bundler, import normally. With
+no bundler, serve `node_modules/@haikit/client/src/` under a URL prefix — the
+examples mount it at `/hai-client/`.

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@haikit/client",
+  "version": "0.1.0",
+  "description": "The haikit browser runtime: streams tool payloads into interactive UI surfaces. Plain ESM, no build step, no dependencies.",
+  "keywords": [
+    "haikit",
+    "llm",
+    "agent",
+    "agentic-ui",
+    "generative-ui",
+    "tool-use",
+    "chat-ui",
+    "sse",
+    "ai"
+  ],
+  "type": "module",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./app.js": {
+      "types": "./src/app.d.ts",
+      "default": "./src/app.js"
+    },
+    "./transcript.js": {
+      "types": "./src/transcript.d.ts",
+      "default": "./src/transcript.js"
+    },
+    "./hai.css": "./src/hai.css",
+    "./package.json": "./package.json",
+    "./*": "./src/*"
+  },
+  "files": [
+    "src"
+  ],
+  "sideEffects": [
+    "*.css"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/wfoxd/haikit/tree/main/packages/client#readme",
+  "bugs": {
+    "url": "https://github.com/wfoxd/haikit/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wfoxd/haikit.git",
+    "directory": "packages/client"
+  }
+}

package/src/app.d.ts

@@ -0,0 +1,32 @@
+import type { Chat, Registry } from "./index.js";
+
+export interface MountChatOptions {
+  root: HTMLElement;
+  registry: Registry;
+  /** Base path the server's two routes are mounted at. Default `/hai`. */
+  endpoint?: string;
+  title?: string;
+  subtitle?: string;
+  /** Clickable starter prompts shown on the empty transcript. */
+  suggestions?: string[];
+  /** Show the context inspector. Default true — keep it on while developing. */
+  inspector?: boolean;
+  placeholder?: string;
+  emptyText?: string;
+}
+
+/**
+ * Builds the shell, wires the composer, renders the transcript and mounts your
+ * surfaces. The ten-line path to a running app.
+ *
+ * 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.
+ */
+export function mountChat(options: MountChatOptions): Chat;
+
+/** The context inspector: makes the dual channel visible. */
+export function renderInspector(
+  el: HTMLElement,
+  context?: { messages?: any[]; modelTokens?: number; uiTokens?: number },
+): void;

package/src/app.js

@@ -0,0 +1,168 @@
+/**
+ * hai-client — the default UI.
+ *
+ * `mountChat()` builds the shell, wires the composer, renders the transcript and
+ * (optionally) the context inspector. It is the ten-line path to a running app.
+ *
+ *   import { mountChat } from "/hai-client/app.js";
+ *   import { registry } from "./components.js";
+ *   mountChat({ root: document.querySelector("#app"), registry });
+ *
+ * It is a convenience, not the API. Everything it does is built on the headless
+ * pieces — `createChat` and `renderTranscript` — and when this shell stops
+ * fitting, drop to those and write your own. That is the expected path, not a
+ * failure mode.
+ */
+
+import { createChat } from "./index.js";
+import { renderTranscript, h } from "./transcript.js";
+
+/**
+ * @param {{
+ *   root: HTMLElement,
+ *   registry: Record<string, { mount: Function }>,
+ *   endpoint?: string,
+ *   title?: string,
+ *   subtitle?: string,
+ *   suggestions?: string[],
+ *   inspector?: boolean,
+ *   placeholder?: string,
+ *   emptyText?: string,
+ * }} options
+ */
+export function mountChat({
+  root,
+  registry,
+  endpoint = "/hai",
+  title = "hai",
+  subtitle = "",
+  suggestions = [],
+  inspector = true,
+  placeholder = "message…",
+  emptyText = "",
+}) {
+  const chat = createChat({ endpoint, registry });
+
+  // ── shell ──────────────────────────────────────────────────────────
+  const shell = h("div", "hai-shell");
+
+  const top = h("header", "hai-top");
+  const modelEl = h("span", "hai-model", "…");
+  top.append(h("span", "hai-title", title), h("span", "hai-subtitle", subtitle), modelEl);
+
+  const transcript = h("div", "hai-transcript");
+  const statusEl = h("div", "hai-status");
+  const input = h("textarea", "hai-input");
+  input.rows = 1;
+  input.placeholder = placeholder;
+  const sendBtn = h("button", "hai-send", "Send");
+
+  const composer = h("div", "hai-composer");
+  composer.append(input, sendBtn);
+
+  const chatPane = h("section", "hai-chat");
+  chatPane.append(transcript, statusEl, composer);
+
+  const main = h("div", `hai-main${inspector ? " has-inspector" : ""}`);
+  main.append(chatPane);
+
+  let inspectorBody = null;
+  if (inspector) {
+    const aside = h("aside", "hai-inspector");
+    const heading = h("div", "hai-inspector-title", "Model context ");
+    heading.append(h("span", null, "— everything the model sees"));
+    inspectorBody = h("div", "hai-inspector-body");
+    aside.append(heading, inspectorBody);
+    main.append(aside);
+  }
+
+  shell.append(top, main);
+  root.replaceChildren(shell);
+
+  // ── empty state ────────────────────────────────────────────────────
+  const send = () => {
+    const text = input.value.trim();
+    if (!text) return;
+    input.value = "";
+    chat.send(text);
+  };
+
+  function renderEmpty() {
+    const empty = h("div", "hai-empty");
+    if (emptyText) empty.append(h("p", null, emptyText));
+    if (suggestions.length) {
+      const row = h("div", "hai-suggestions");
+      for (const s of suggestions) {
+        const b = h("button", "hai-suggestion", s);
+        b.onclick = () => { input.value = s; send(); };
+        row.append(b);
+      }
+      empty.append(row);
+    }
+    transcript.replaceChildren(empty);
+  }
+
+  // ── wiring ─────────────────────────────────────────────────────────
+  chat.subscribe((state) => {
+    if (state.blocks.length === 0) renderEmpty();
+    else renderTranscript(transcript, chat);
+
+    modelEl.textContent = state.model;
+    sendBtn.disabled = state.status === "streaming";
+    statusEl.dataset.status = state.status;
+    statusEl.textContent =
+      state.status === "streaming" ? "thinking…"
+      : state.status === "awaiting" ? "awaiting your selection in the component above"
+      : "";
+    input.placeholder =
+      state.status === "awaiting" ? "pick an option above — or type to override" : placeholder;
+
+    if (inspectorBody) renderInspector(inspectorBody, state.context);
+  });
+
+  sendBtn.onclick = send;
+  input.onkeydown = (e) => {
+    if (e.key === "Enter" && !e.shiftKey) {
+      e.preventDefault();
+      send();
+    }
+  };
+
+  renderEmpty();
+  return chat;
+}
+
+/**
+ * The context inspector. Makes the dual channel visible, which is the whole
+ * argument — keep it on while developing.
+ */
+export function renderInspector(el, { messages = [], modelTokens = 0, uiTokens = 0 } = {}) {
+  el.replaceChildren();
+
+  const pct = uiTokens ? Math.round((1 - modelTokens / (modelTokens + uiTokens)) * 100) : 0;
+  const bar = h("div", "hai-ctx-bar");
+  bar.append(
+    h("div", null, `model context  ~${modelTokens} tok`),
+    h("div", "hai-stat-dim", `browser payload  ~${uiTokens} tok`),
+    h("div", "hai-stat-good", uiTokens ? `${pct}% kept out of context` : ""),
+  );
+  el.append(bar);
+
+  for (const m of messages) {
+    const box = h("div", "hai-msg");
+    box.append(h("div", "hai-role", m.role));
+    const body = h("div", "hai-mbody");
+    if (typeof m.content === "string") {
+      body.append(h("div", null, m.content));
+    } else {
+      for (const b of m.content ?? []) {
+        if (b.type === "text" && b.text) body.append(h("div", null, b.text));
+        if (b.type === "tool_use")
+          body.append(h("div", "hai-tu", `tool_use ${b.name} ${JSON.stringify(b.input)}`));
+        if (b.type === "tool_result") body.append(h("div", "hai-tr", b.content));
+      }
+    }
+    box.append(body);
+    el.append(box);
+  }
+}

package/src/hai.css

@@ -0,0 +1,206 @@
+/**
+ * hai-client — default UI.
+ *
+ * Styles ONLY what the framework renders: transcript blocks, the tool
+ * provenance row, the surface container, and the shell that mountChat() builds.
+ *
+ * It deliberately does not style the inside of your surfaces. Your components
+ * emit their own class names and your own stylesheet owns them — otherwise the
+ * framework starts dictating what your UI looks like.
+ *
+ * Everything is driven by custom properties. Override them in your own sheet:
+ *
+ *   :root { --hai-accent: #b07cff; --hai-bg: #101014; }
+ */
+
+:root {
+  --hai-bg: #0d1013;
+  --hai-panel: #14181d;
+  --hai-panel-2: #11161c;
+  --hai-line: #242c34;
+  --hai-fg: #dde3ea;
+  --hai-dim: #7c8894;
+  --hai-accent: #6ea8fe;
+  --hai-good: #63c49a;
+  --hai-warn: #e0b055;
+  --hai-bad: #e07070;
+  --hai-radius: 10px;
+  --hai-mono: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
+  --hai-sans: ui-sans-serif, system-ui, -apple-system, sans-serif;
+  --hai-inspector-width: 400px;
+}
+
+/* ── shell ──────────────────────────────────────────────────────────── */
+.hai-shell {
+  height: 100vh;
+  display: flex;
+  flex-direction: column;
+  background: var(--hai-bg);
+  color: var(--hai-fg);
+  font: 14px/1.55 var(--hai-sans);
+}
+.hai-top {
+  display: flex;
+  align-items: baseline;
+  gap: 12px;
+  padding: 10px 16px;
+  border-bottom: 1px solid var(--hai-line);
+  background: var(--hai-panel);
+}
+.hai-title { font-weight: 700; letter-spacing: .04em; }
+.hai-subtitle { color: var(--hai-dim); font-size: 12px; }
+.hai-model { margin-left: auto; font: 11px var(--hai-mono); color: var(--hai-warn); }
+
+.hai-main { flex: 1; display: grid; grid-template-columns: minmax(0, 1fr); min-height: 0; }
+.hai-main.has-inspector { grid-template-columns: minmax(0, 1fr) var(--hai-inspector-width); }
+.hai-chat { display: flex; flex-direction: column; min-height: 0; }
+
+.hai-transcript { flex: 1; overflow-y: auto; padding: 18px 20px 8px; }
+.hai-empty { color: var(--hai-dim); max-width: 60ch; }
+.hai-suggestions { display: flex; flex-wrap: wrap; gap: 8px; margin-top: 14px; }
+.hai-suggestion {
+  background: var(--hai-panel-2);
+  color: var(--hai-fg);
+  border: 1px solid var(--hai-line);
+  border-radius: 999px;
+  padding: 5px 12px;
+  cursor: pointer;
+  font: inherit;
+  font-size: 13px;
+}
+.hai-suggestion:hover { border-color: var(--hai-accent); }
+
+/* ── transcript blocks ──────────────────────────────────────────────── */
+.hai-block { margin: 0 0 12px; max-width: 70ch; }
+.hai-user .hai-body {
+  background: #1d2733;
+  border: 1px solid #27333f;
+  border-radius: var(--hai-radius);
+  padding: 8px 12px;
+  display: inline-block;
+}
+.hai-assistant .hai-body { white-space: pre-wrap; }
+.hai-interaction {
+  color: var(--hai-good);
+  font-size: 13px;
+  display: flex;
+  gap: 8px;
+  border-left: 2px solid var(--hai-good);
+  padding-left: 10px;
+}
+.hai-error { color: var(--hai-bad); font: 12px var(--hai-mono); }
+
+/* tool provenance row — chrome for the surface directly beneath it */
+.hai-tool {
+  border: 1px solid var(--hai-line);
+  border-radius: var(--hai-radius) var(--hai-radius) 0 0;
+  background: var(--hai-panel);
+  max-width: none;
+  margin-bottom: 0;
+}
+.hai-tool summary {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 7px 12px;
+  cursor: pointer;
+  font: 12px var(--hai-mono);
+  list-style: none;
+}
+.hai-tool summary::-webkit-details-marker { display: none; }
+.hai-gear { color: var(--hai-dim); }
+.hai-tname { color: var(--hai-accent); }
+.hai-targs { color: var(--hai-dim); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; flex: 1; }
+.hai-tstatus { color: var(--hai-dim); }
+.hai-status-awaiting .hai-tstatus { color: var(--hai-warn); }
+.hai-status-running .hai-tstatus { color: var(--hai-accent); }
+.hai-tool-detail { padding: 0 12px 10px; border-top: 1px solid var(--hai-line); }
+.hai-label { font: 11px var(--hai-mono); color: var(--hai-dim); margin: 8px 0 4px; }
+.hai-digest {
+  margin: 0;
+  padding: 8px 10px;
+  background: #0b0e11;
+  border: 1px solid var(--hai-line);
+  border-radius: 6px;
+  font: 11.5px/1.5 var(--hai-mono);
+  color: var(--hai-good);
+  white-space: pre-wrap;
+  max-height: 180px;
+  overflow: auto;
+}
+
+/* surface container — your component mounts inside this */
+.hai-surface {
+  border: 1px solid var(--hai-line);
+  border-top: none;
+  border-radius: 0 0 var(--hai-radius) var(--hai-radius);
+  background: var(--hai-panel-2);
+  margin-bottom: 14px;
+  overflow: hidden;
+}
+.hai-skeleton, .hai-surface-error { padding: 14px; font: 12px var(--hai-mono); color: var(--hai-dim); }
+.hai-surface-error { color: var(--hai-bad); }
+
+/* ── status + composer ──────────────────────────────────────────────── */
+.hai-status { padding: 0 20px 4px; font-size: 12px; min-height: 18px; color: var(--hai-dim); }
+.hai-status[data-status="awaiting"] { color: var(--hai-warn); }
+.hai-composer { display: flex; gap: 8px; padding: 10px 20px 16px; border-top: 1px solid var(--hai-line); }
+.hai-input {
+  flex: 1;
+  resize: none;
+  background: var(--hai-panel);
+  color: var(--hai-fg);
+  border: 1px solid var(--hai-line);
+  border-radius: 8px;
+  padding: 9px 12px;
+  font: inherit;
+  min-height: 38px;
+  max-height: 180px;
+}
+.hai-input:focus { outline: none; border-color: var(--hai-accent); }
+.hai-send {
+  background: var(--hai-accent);
+  color: var(--hai-bg);
+  border: none;
+  border-radius: 8px;
+  padding: 0 18px;
+  font: inherit;
+  font-weight: 600;
+  cursor: pointer;
+}
+.hai-send:disabled { opacity: .4; cursor: default; }
+
+/* ── context inspector ──────────────────────────────────────────────── */
+.hai-inspector {
+  border-left: 1px solid var(--hai-line);
+  background: var(--hai-panel-2);
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+}
+.hai-inspector-title { padding: 10px 14px; border-bottom: 1px solid var(--hai-line); font-size: 12px; font-weight: 600; }
+.hai-inspector-title span { color: var(--hai-dim); font-weight: 400; }
+.hai-inspector-body { flex: 1; overflow-y: auto; padding: 12px 14px; }
+.hai-ctx-bar {
+  display: flex;
+  flex-direction: column;
+  gap: 3px;
+  margin-bottom: 14px;
+  padding: 10px;
+  border: 1px solid var(--hai-line);
+  border-radius: 8px;
+  background: var(--hai-bg);
+  font: 11.5px var(--hai-mono);
+}
+.hai-stat-dim { color: var(--hai-dim); }
+.hai-stat-good { color: var(--hai-good); }
+.hai-msg { margin-bottom: 10px; border-left: 2px solid var(--hai-line); padding-left: 9px; }
+.hai-role { font: 10px var(--hai-mono); text-transform: uppercase; color: var(--hai-dim); letter-spacing: .07em; }
+.hai-mbody { font: 11.5px/1.5 var(--hai-mono); white-space: pre-wrap; word-break: break-word; }
+.hai-tu { color: var(--hai-accent); }
+.hai-tr { color: var(--hai-good); }
+
+@media (max-width: 900px) {
+  .hai-main.has-inspector { grid-template-columns: minmax(0, 1fr); }
+  .hai-inspector { display: none; }
+}

package/src/index.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Types for the headless browser runtime.
+ *
+ * Hand-written rather than generated, and deliberately self-contained: this
+ * package has no runtime dependencies and gains none by being typed. The wire
+ * shapes below mirror `@haikit/core`'s `Block` / `WireEvent`, which is the one
+ * thing crossing the server/browser line — on this side it crosses as types
+ * only, so duplicating them here costs nothing at runtime.
+ */
+
+export type ConversationStatus = "idle" | "streaming" | "awaiting";
+export type SurfaceMode = "display" | "elicit";
+export type SurfaceState = "live" | "frozen";
+
+/** Blocks the server emits, plus the two the client synthesises locally. */
+export type Block =
+  | { kind: "user"; id: string; text: string }
+  | { kind: "assistant"; id: string; text: string }
+  | { kind: "tool"; id: string; name: string; input: unknown; status: string; ms?: number; result?: string }
+  | { kind: "interaction"; id: string; handle: string; label: string }
+  /** synthesised from `ui_open` — the slot a surface mounts into */
+  | { kind: "ui"; id: string; handle: string; toolId: string }
+  /** synthesised from `error` */
+  | { kind: "error"; id: string; message: string };
+
+/** The SSE frame shape. Narrow on `type` to get the specific payload. */
+export type WireEvent = { type: string } & Record<string, any>;
+
+/**
+ * What `mount()` hands your component. `send` is the ONLY channel back to the
+ * server: it carries an action name declared in the surface contract — never a
+ * tool name, never a handler.
+ */
+export interface MountCtx {
+  handle: string;
+  mode: SurfaceMode;
+  state: SurfaceState;
+  send(action: string, value: unknown): Promise<void>;
+}
+
+/**
+ * Returned by `mount`. `freeze` is called when the server marks the surface
+ * frozen — a resolved elicit turn cannot be replayed, and the component should
+ * reflect that.
+ */
+export interface SurfaceInstance {
+  freeze?(selection?: unknown): void;
+}
+
+/** Your component. `props` is whatever the surface's `props` schema produces. */
+export interface ComponentDef<P = any> {
+  mount(element: HTMLElement, props: P, ctx: MountCtx): SurfaceInstance | null | void;
+}
+
+/**
+ * The allowlist. A component the registry does not name cannot be mounted —
+ * an unknown name renders an error card, never improvised UI.
+ */
+export type Registry = Record<string, ComponentDef<any>>;
+
+export interface SurfaceRecord {
+  handle: string;
+  component: string;
+  version: number;
+  mode: SurfaceMode;
+  state: SurfaceState;
+  props: unknown | null;
+  instance: SurfaceInstance | null;
+}
+
+export interface ChatState {
+  conversationId: string | null;
+  model: string;
+  status: ConversationStatus;
+  blocks: Block[];
+  /** handle → surface record */
+  surfaces: Map<string, SurfaceRecord>;
+  context: { messages: any[]; modelTokens: number; uiTokens: number };
+}
+
+export interface Chat {
+  /** Mutable — read it in a subscriber, do not hold references across events. */
+  state: ChatState;
+  send(text: string): Promise<void>;
+  interact(handle: string, action: string, value: unknown): Promise<void>;
+  /** Mounts the surface for `handle` into `element`. Null if props have not arrived. */
+  mount(handle: string, element: HTMLElement): SurfaceInstance | null;
+  /** Returns an unsubscribe function. */
+  subscribe(fn: (state: ChatState, event: WireEvent) => void): () => void;
+}
+
+export function createChat(options: { endpoint?: string; registry: Registry }): Chat;

package/src/index.js

@@ -0,0 +1,166 @@
+/**
+ * hai-client — the browser runtime.
+ *
+ * Headless: it owns the transport, the block store, and surface mounting.
+ * It does NOT own how your transcript looks — see transcript.js for a default
+ * renderer you are expected to replace.
+ *
+ * Note this package has no dependency on hai-server. The only thing crossing
+ * that line is your surface contract, and on this side it crosses as types.
+ */
+
+/**
+ * @param {{endpoint?: string, registry: Record<string, {mount: Function}>}} options
+ */
+export function createChat({ endpoint = "/hai", registry }) {
+  const listeners = new Set();
+  const state = {
+    conversationId: null,
+    model: "",
+    status: "idle",
+    blocks: [],
+    /** handle -> { component, version, mode, props, state, instance } */
+    surfaces: new Map(),
+    context: { messages: [], modelTokens: 0, uiTokens: 0 },
+  };
+
+  const notify = (event) => listeners.forEach((fn) => fn(state, event));
+
+  // ── transport: SSE over POST (EventSource cannot POST) ──────────────
+  async function stream(path, body) {
+    const res = await fetch(endpoint + path, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ conversationId: state.conversationId, ...body }),
+    });
+    const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
+    let buffer = "";
+    for (;;) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      buffer += value;
+      let i;
+      while ((i = buffer.indexOf("\n\n")) >= 0) {
+        const frame = buffer.slice(0, i);
+        buffer = buffer.slice(i + 2);
+        const line = frame.split("\n").find((l) => l.startsWith("data: "));
+        if (line) apply(JSON.parse(line.slice(6)));
+      }
+    }
+  }
+
+  function apply(event) {
+    switch (event.type) {
+      case "hello":
+        state.conversationId = event.conversationId;
+        state.model = event.model;
+        break;
+
+      case "block_start":
+        state.blocks.push({ ...event.block });
+        break;
+
+      case "text_delta": {
+        const block = state.blocks.find((b) => b.id === event.id);
+        if (block) block.text += event.text;
+        break;
+      }
+
+      case "block_update": {
+        const block = state.blocks.find((b) => b.id === event.id);
+        if (block) Object.assign(block, event);
+        break;
+      }
+
+      case "ui_open":
+        state.surfaces.set(event.handle, {
+          handle: event.handle,
+          component: event.component,
+          version: event.version,
+          mode: event.mode,
+          state: "live",
+          props: null,
+          instance: null,
+        });
+        state.blocks.push({ kind: "ui", id: `ui:${event.handle}`, handle: event.handle, toolId: event.toolId });
+        break;
+
+      case "ui_props": {
+        const surface = state.surfaces.get(event.handle);
+        if (surface) surface.props = event.props;
+        break;
+      }
+
+      case "ui_state": {
+        const surface = state.surfaces.get(event.handle);
+        if (surface) {
+          surface.state = event.state;
+          surface.instance?.freeze?.(event.selection);
+        }
+        break;
+      }
+
+      case "status":
+        state.status = event.status;
+        break;
+
+      case "context":
+        state.context = event;
+        break;
+
+      case "error":
+        state.blocks.push({ kind: "error", id: `e${state.blocks.length}`, message: event.message });
+        state.status = "idle";
+        break;
+    }
+    notify(event);
+  }
+
+  /**
+   * Mount a surface into an element. Strict allowlist: an unregistered
+   * component renders an error card, never an improvised UI.
+   */
+  function mount(handle, element) {
+    const surface = state.surfaces.get(handle);
+    if (!surface || !surface.props) return null;
+
+    const definition = registry[surface.component];
+    if (!definition) {
+      element.textContent = `unknown component: ${surface.component}`;
+      element.className = "hai-surface-error";
+      return null;
+    }
+
+    element.replaceChildren();
+    surface.instance = definition.mount(element, surface.props, {
+      handle,
+      mode: surface.mode,
+      state: surface.state,
+      // 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),
+    });
+    return surface.instance;
+  }
+
+  async function send(text) {
+    if (!text.trim() || state.status === "streaming") return;
+    await stream("/chat", { message: text });
+  }
+
+  async function interact(handle, action, value) {
+    if (state.status === "streaming") return;
+    await stream("/interact", { handle, action, value });
+  }
+
+  return {
+    state,
+    send,
+    interact,
+    mount,
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+  };
+}

package/src/transcript.d.ts

@@ -0,0 +1,19 @@
+import type { Chat } from "./index.js";
+
+/**
+ * Element helper. Generic over the tag so `h("textarea", …).rows` and
+ * `h("button", …).disabled` typecheck — a plain `HTMLElement` return would
+ * force a cast at every call site.
+ */
+export function h<K extends keyof HTMLElementTagNameMap>(
+  tag: K,
+  className?: string | null,
+  text?: string | null,
+): HTMLElementTagNameMap[K];
+
+/**
+ * The default transcript renderer. Replaces `root`'s children on every call and
+ * preserves scroll-to-bottom. Deliberately plain — this is the part you are
+ * expected to replace.
+ */
+export function renderTranscript(root: HTMLElement, chat: Chat): void;

package/src/transcript.js

@@ -0,0 +1,87 @@
+/**
+ * A default transcript renderer. Deliberately plain — data-dense agentic UIs
+ * are bespoke, and this is the part you are expected to replace. It exists so
+ * an app can be running in ten lines.
+ *
+ * Everything uses textContent. Tool payloads are untrusted input.
+ */
+
+export const h = (tag, className, text) => {
+  const node = document.createElement(tag);
+  if (className) node.className = className;
+  if (text != null) node.textContent = text;
+  return node;
+};
+
+export function renderTranscript(root, chat) {
+  const { state } = chat;
+  const atBottom = root.scrollHeight - root.scrollTop - root.clientHeight < 160;
+
+  root.replaceChildren();
+  for (const block of state.blocks) root.append(renderBlock(block, chat));
+
+  if (atBottom) root.scrollTop = root.scrollHeight;
+}
+
+function renderBlock(block, chat) {
+  switch (block.kind) {
+    case "user": {
+      const el = h("div", "hai-block hai-user");
+      el.append(h("div", "hai-body", block.text));
+      return el;
+    }
+
+    case "assistant": {
+      const el = h("div", "hai-block hai-assistant");
+      el.append(h("div", "hai-body", block.text ?? ""));
+      return el;
+    }
+
+    case "interaction": {
+      const el = h("div", "hai-block hai-interaction");
+      el.append(h("span", "hai-arrow", "↳"), h("span", null, block.label));
+      return el;
+    }
+
+    case "error":
+      return h("div", "hai-block hai-error", `error: ${block.message}`);
+
+    // Provenance chrome. The tool row and its surface are one visual unit:
+    // what produced this, with what arguments, and what the model got back.
+    case "tool": {
+      const el = h("details", `hai-block hai-tool hai-status-${block.status}`);
+      const summary = h("summary");
+      summary.append(
+        h("span", "hai-gear", "⚙"),
+        h("span", "hai-tname", block.name),
+        h("span", "hai-targs", JSON.stringify(block.input)),
+        h(
+          "span",
+          "hai-tstatus",
+          block.status === "running" ? "…" : block.status === "awaiting" ? "awaiting user" : `${block.ms}ms`,
+        ),
+      );
+      el.append(summary);
+      const detail = h("div", "hai-tool-detail");
+      detail.append(h("div", "hai-label", "→ tool_result — all the model receives"));
+      detail.append(h("pre", "hai-digest", block.result ?? "…"));
+      el.append(detail);
+      return el;
+    }
+
+    case "ui": {
+      const el = h("div", "hai-surface");
+      el.dataset.handle = block.handle;
+      const surface = chat.state.surfaces.get(block.handle);
+      if (surface?.props) {
+        queueMicrotask(() => chat.mount(block.handle, el));
+      } else {
+        el.append(h("div", "hai-skeleton", `${surface?.component ?? "surface"} · loading…`));
+      }
+      return el;
+    }
+
+    default:
+      return h("div", "hai-block", JSON.stringify(block));
+  }
+}