@haikit/client 0.8.0 → 0.9.1

package/README.md

@@ -13,11 +13,64 @@ API — it is built from `createChat` + `renderTranscript`, and dropping to thos
 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
+rows, the surface container, shell, composer, debug drawer. 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.
 
+## The default UI
+
+The [default UI guide](https://github.com/wfoxd/haikit/blob/main/docs/default-ui.md)
+covers it in full: every option, what each part of the screen does, theming,
+styling your surfaces, and building your own layout. In short:
+
+`mountChat` gives you a header with **New chat** and a **Context** button that
+shows how many tokens the model holds, a centred conversation, and a composer
+that grows as you type.
+
+**Context** opens the *model context debug drawer*: every message, tool call
+and digest the model receives, and how much of the payload stayed out of
+context. It starts closed and slides in from the right. On a wide screen the
+chat makes room for it, and on a narrow one it opens over the chat. Escape or
+its close button shuts it. It opens again after a reload if it was open
+before. `inspector: false` leaves it out.
+
+Each tool row says where its call stands: running, `awaiting you` while the turn
+is parked on its surface, `resolved` once that surface has been answered or
+typed over, or how long it took. Expand it to see the input and the
+`tool_result`, which is everything the model received.
+
+It is light or dark with the system. To pin it, put `data-hai-theme="dark"` (or
+`"light"`) on the `<html>` element, or pass `theme: "dark"` to `mountChat`.
+
+### Tokens
+
+Every token is set at zero specificity, so a plain `:root` rule in your own
+sheet wins. Give a colour one value per scheme with `light-dark()`:
+
+```css
+:root { --hai-accent: #b07cff; }
+@supports (color: light-dark(#000, #fff)) {
+  :root { --hai-accent: light-dark(#6d28d9, #b07cff); }
+}
+```
+
+Keep the plain value first. A browser without `light-dark()` gets hai.css's
+dark scheme, and an override it can't read would leave that token with no
+colour at all.
+
+| | |
+|---|---|
+| `--hai-bg` `--hai-panel` `--hai-panel-2` | page, cards, secondary panels |
+| `--hai-fg` `--hai-dim` | text, secondary text |
+| `--hai-line` `--hai-line-soft` | borders, row dividers |
+| `--hai-accent` `--hai-on-accent` | the accent, and text drawn on it |
+| `--hai-good` `--hai-warn` `--hai-bad` | status colours; each, and the accent, has a `-soft` tint for backgrounds |
+| `--hai-hover` `--hai-selected` | row hover and picked-row backgrounds, for your surfaces |
+| `--hai-user-bg` `--hai-code-bg` `--hai-shadow` | user bubble, digest blocks, card shadow |
+| `--hai-radius` `--hai-sans` `--hai-mono` | shape and type |
+| `--hai-column` `--hai-inspector-width` | conversation width, debug drawer width |
+
 ## Surface lifecycle
 
 The default transcript keeps each block's element for as long as what it

package/package.json

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

@@ -9,10 +9,20 @@ export interface MountChatOptions {
   subtitle?: string;
   /** Clickable starter prompts shown on the empty transcript. */
   suggestions?: string[];
-  /** Show the context inspector. Default true — keep it on while developing. */
+  /**
+   * Include the model context debug drawer, opened from the header. Default
+   * true — keep it while developing. It starts closed, and opens again after a
+   * reload if it was open before.
+   */
   inspector?: boolean;
   placeholder?: string;
   emptyText?: string;
+  /**
+   * Pin the page to a colour scheme, by setting `data-hai-theme` on the root
+   * element until the chat closes. Unset, it follows the system's light or
+   * dark setting, or a `data-hai-theme` already in the page's markup.
+   */
+  theme?: "light" | "dark";
 }
 
 /**
@@ -30,7 +40,7 @@ export interface MountChatOptions {
  */
 export function mountChat(options: MountChatOptions): Chat;
 
-/** The context inspector: makes the dual channel visible. */
+/** What the model context debug drawer shows: makes the dual channel visible. */
 export function renderInspector(
   el: HTMLElement,
   context?: { messages?: any[]; modelTokens?: number; uiTokens?: number },

package/src/app.js

@@ -2,7 +2,8 @@
  * 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.
+ * (optionally) the model context debug drawer. It is the ten-line path to a
+ * running app.
  *
  *   import { mountChat } from "/hai-client/app.js";
  *   import { registry } from "./components.js";
@@ -16,6 +17,70 @@
 
 import { createChat } from "./index.js";
 import { renderTranscript, closeTranscript, h } from "./transcript.js";
+import { icon, mark, FAVICON } from "./icons.js";
+
+/** Below this width the drawer opens over the chat rather than beside it. */
+const WIDE = "(min-width: 900px)";
+
+/** The drawer's name, as its heading shows it and assistive technology says it. */
+const DRAWER = "Model context debug drawer";
+
+/** Where the drawer remembers being open, so a reload while developing keeps it. */
+const REMEMBER = "hai:debug-drawer";
+
+/** Numbers the inspector's ids, so two shells on a page never share one. */
+let shells = 0;
+
+/**
+ * The page's scheme pin is one attribute shared by every chat on it. It
+ * follows the newest themed chat still open; when the last one closes, the
+ * page gets back the pin it had before the first. A pin the page set itself
+ * in the meantime is the page's, and closing a chat leaves it alone.
+ */
+const pinning = { chats: [], pageOwn: undefined, ours: undefined };
+
+function pin(chat) {
+  if (!pinning.chats.length) pinning.pageOwn = document.documentElement.dataset.haiTheme;
+  pinning.chats.push(chat);
+  setPin(chat.theme);
+}
+
+function unpin(chat) {
+  const i = pinning.chats.indexOf(chat);
+  if (i < 0) return;
+  pinning.chats.splice(i, 1);
+  if (document.documentElement.dataset.haiTheme !== pinning.ours) return;
+  setPin(pinning.chats.at(-1)?.theme ?? pinning.pageOwn);
+}
+
+function setPin(theme) {
+  const page = document.documentElement;
+  if (theme === undefined) delete page.dataset.haiTheme;
+  else page.dataset.haiTheme = theme;
+  pinning.ours = theme;
+}
+
+/**
+ * A page without an icon of its own gets the haikit favicon while a chat is
+ * open on it. Every chat shares the one link; the last to close takes it away.
+ */
+const favicon = { chats: 0, link: null };
+
+function addFavicon() {
+  if (favicon.chats++ || document.querySelector('link[rel~="icon"]')) return;
+  const link = document.createElement("link");
+  link.rel = "icon";
+  link.type = "image/svg+xml";
+  link.href = FAVICON;
+  document.head.append(link);
+  favicon.link = link;
+}
+
+function dropFavicon() {
+  if (--favicon.chats) return;
+  favicon.link?.remove();
+  favicon.link = null;
+}
 
 /**
  * @param {{
@@ -28,37 +93,63 @@ import { renderTranscript, closeTranscript, h } from "./transcript.js";
  *   inspector?: boolean,
  *   placeholder?: string,
  *   emptyText?: string,
+ *   theme?: "light" | "dark",
  * }} options
  */
 export function mountChat({
   root,
   registry,
   endpoint = "/hai",
-  title = "hai",
+  title = "HaiKIT",
   subtitle = "",
   suggestions = [],
   inspector = true,
   placeholder = "message…",
   emptyText = "",
+  theme,
 }) {
   const chat = createChat({ endpoint, registry });
+  const id = `hai-${++shells}`;
+
+  // Unset, the page follows the system. A pin goes on the root, where hai.css
+  // sets the tokens: a minifier that lowers light-dark() resolves them there,
+  // so a pin on the shell alone would not reach them.
+  const pinned = theme === "light" || theme === "dark" ? { theme } : null;
+  if (pinned) pin(pinned);
+  addFavicon();
 
   // ── 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 brand = h("div", "hai-brand");
+  brand.append(mark("small", "hai-logo hai-mark"), h("span", "hai-title", title));
+  if (subtitle) brand.append(h("span", "hai-subtitle", subtitle));
+
+  const modelEl = h("span", "hai-model");
+  modelEl.hidden = true;
+  const newBtn = button("hai-btn", "plus", "New chat");
+  newBtn.onclick = () => chat.reset();
+  const actions = h("div", "hai-actions");
+  actions.append(modelEl, newBtn);
+  top.append(brand, actions);
 
   const transcript = h("div", "hai-transcript");
   const statusEl = h("div", "hai-status");
+  statusEl.setAttribute("role", "status");
   const input = h("textarea", "hai-input");
   input.rows = 1;
   input.placeholder = placeholder;
-  const sendBtn = h("button", "hai-send", "Send");
+  input.setAttribute("aria-label", "Message");
+  const sendBtn = h("button", "hai-send");
+  sendBtn.type = "button";
+  sendBtn.setAttribute("aria-label", "Send");
+  sendBtn.append(icon("send"));
 
+  const box = h("div", "hai-composer-box");
+  box.append(input, sendBtn);
   const composer = h("div", "hai-composer");
-  composer.append(input, sendBtn);
+  composer.append(box);
 
   const chatPane = h("section", "hai-chat");
   chatPane.append(transcript, statusEl, composer);
@@ -67,19 +158,103 @@ export function mountChat({
   main.append(chatPane);
 
   let inspectorBody = null;
+  let ctxCount = null;
+  let releaseDrawer = () => {};
   if (inspector) {
+    // The model context debug drawer: closed until asked for, it slides in
+    // from the right, beside the chat on a wide screen and over it on a
+    // narrow one. The header button that opens it says how much the model
+    // holds, open or not.
     const aside = h("aside", "hai-inspector");
-    const heading = h("div", "hai-inspector-title", "Model context ");
-    heading.append(h("span", null, "— everything the model sees"));
+    aside.id = `${id}-inspector`;
+    aside.setAttribute("aria-label", DRAWER);
+    const head = h("div", "hai-inspector-head");
+    const heading = h("div", "hai-inspector-title", DRAWER);
+    heading.append(h("span", null, "everything the model sees"));
+    const hide = h("button", "hai-icon-btn");
+    hide.type = "button";
+    hide.setAttribute("aria-label", `Close ${DRAWER.toLowerCase()}`);
+    hide.append(icon("close"));
+    head.append(heading, hide);
     inspectorBody = h("div", "hai-inspector-body");
-    aside.append(heading, inspectorBody);
+    aside.append(head, inspectorBody);
     main.append(aside);
+
+    const toggle = button("hai-btn hai-ctx-toggle", "panel", "Context");
+    ctxCount = h("span", "hai-ctx-count");
+    toggle.append(ctxCount);
+    toggle.title = DRAWER;
+    toggle.setAttribute("aria-controls", aside.id);
+    actions.append(toggle);
+
+    const wideQuery = typeof matchMedia === "function" ? matchMedia(WIDE) : null;
+    const wide = () => !wideQuery || wideQuery.matches;
+    const isOpen = () => main.classList.contains("inspector-open");
+    // Over the chat, on a narrow screen, the drawer is all there is to reach:
+    // the chat behind it is inert until it closes or the screen widens.
+    const sync = () => {
+      chatPane.inert = isOpen() && !wide();
+    };
+    const set = (open) => {
+      main.classList.toggle("inspector-open", open);
+      toggle.setAttribute("aria-expanded", String(open));
+      // out of reach as soon as it starts to close, not once it has slid away
+      aside.inert = !open;
+      sync();
+    };
+    const show = (open) => {
+      set(open);
+      try {
+        localStorage.setItem(REMEMBER, open ? "open" : "closed");
+      } catch {}
+    };
+    toggle.onclick = () => {
+      const open = !isOpen();
+      show(open);
+      if (open) hide.focus();
+    };
+    hide.onclick = () => {
+      show(false);
+      toggle.focus();
+    };
+    // a tap on the chat it covers closes it, as a tap outside a dialog does,
+    // and focus goes back to Context, as it does from the close button
+    main.addEventListener("click", (e) => {
+      if (e.target === main && chatPane.inert) hide.onclick();
+    });
+    // Escape closes it from anywhere in the shell, unless something there
+    // used the key first, such as a surface closing a menu of its own. Focus
+    // goes back to Context from inside the drawer; a reader typing in the
+    // composer keeps their place.
+    shell.addEventListener("keydown", (e) => {
+      if (e.key !== "Escape" || e.defaultPrevented || !isOpen()) return;
+      const inside = aside.contains(document.activeElement);
+      show(false);
+      if (inside) toggle.focus();
+    });
+    wideQuery?.addEventListener("change", sync);
+    releaseDrawer = () => wideQuery?.removeEventListener("change", sync);
+
+    // Open again after a reload if it was open before, but only beside the
+    // chat: over it, on a narrow screen, it would hide the page it debugs.
+    let remembered = null;
+    try {
+      remembered = localStorage.getItem(REMEMBER);
+    } catch {}
+    set(remembered === "open" && wide());
   }
 
   shell.append(top, main);
   root.replaceChildren(shell);
 
-  // ── empty state ────────────────────────────────────────────────────
+  // ── composer ───────────────────────────────────────────────────────
+  // The input grows with what is typed, up to the height hai.css allows.
+  const fit = () => {
+    input.style.height = "auto";
+    input.style.height = `${input.scrollHeight}px`;
+  };
+  input.addEventListener("input", fit);
+
   const send = () => {
     const text = input.value.trim();
     if (!text) return;
@@ -88,21 +263,29 @@ export function mountChat({
     // this already knows: keep the text for the new conversation instead
     if (chat.state.expired) return;
     input.value = "";
+    fit();
     // A message queued behind a long turn can still be turned away later, if
     // the conversation goes out of date before its turn comes. Give the text
     // back then, unless something new has been typed since.
     sending.then((sent) => {
-      if (!sent && !input.value) input.value = text;
+      if (!sent && !input.value) {
+        input.value = text;
+        fit();
+      }
     });
   };
 
+  // ── empty state ────────────────────────────────────────────────────
   function emptyState() {
     const empty = h("div", "hai-empty");
+    if (!emptyText && !suggestions.length) return empty;
+    empty.append(mark("full", "hai-logo hai-empty-mark"));
     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.type = "button";
         b.onclick = () => { input.value = s; send(); };
         row.append(b);
       }
@@ -116,13 +299,31 @@ export function mountChat({
   // The suggestions follow it until the user engages — a first message, or an
   // answer to something init showed. What the conversation opened with (an
   // init tool's row, a welcome surface) doesn't replace them.
+  const engaged = () => chat.state.blocks.some((b) => b.kind === "user" || b.kind === "interaction");
   const render = () => {
     renderTranscript(transcript, chat);
-    if (!chat.state.blocks.some((b) => b.kind === "user" || b.kind === "interaction")) {
-      transcript.append(emptyState());
-    }
+    if (!engaged()) transcript.append(emptyState());
   };
 
+  // ── status ─────────────────────────────────────────────────────────
+  // A live region: it changes only when the status does, so a screen reader
+  // hears "Thinking" once a turn, not once per streamed word.
+  let shownStatus = null;
+  function showStatus(status) {
+    if (status === shownStatus) return;
+    shownStatus = status;
+    statusEl.dataset.status = status;
+    statusEl.replaceChildren();
+    if (status === "streaming") {
+      const dots = h("span", "hai-dots");
+      dots.setAttribute("aria-hidden", "true");
+      dots.append(h("i"), h("i"), h("i"));
+      statusEl.append(dots, "Thinking");
+    } else if (status === "awaiting") {
+      statusEl.append(h("span", "hai-pulse"), "Waiting on your selection above");
+    }
+  }
+
   // ── wiring ─────────────────────────────────────────────────────────
   chat.subscribe((state, event) => {
     // chat.close(): the surfaces are unmounted and the chat lets go of this
@@ -130,6 +331,9 @@ export function mountChat({
     if (event.type === "closed") {
       closeTranscript(transcript);
       shell.remove();
+      releaseDrawer();
+      if (pinned) unpin(pinned);
+      dropFavicon();
       return;
     }
 
@@ -140,52 +344,88 @@ export function mountChat({
     render();
 
     modelEl.textContent = state.model;
+    modelEl.hidden = !state.model;
+    // There is something to start over from once the user has engaged, or
+    // once the server has a conversation: init may already be asking.
+    newBtn.disabled = !engaged() && !state.expired && !state.conversationId;
     input.disabled = state.expired !== null;
     sendBtn.disabled = state.status === "streaming" || state.expired !== null;
-    statusEl.dataset.status = state.status;
-    statusEl.textContent =
-      state.status === "streaming" ? "thinking…"
-      : state.status === "awaiting" ? "awaiting your selection in the component above"
-      : "";
+    showStatus(state.expired ? "idle" : state.status);
     input.placeholder =
       state.expired ? "start a new conversation to continue"
       : state.status === "awaiting" ? "pick an option above — or type to override"
       : placeholder;
 
-    if (inspectorBody) renderInspector(inspectorBody, state.context);
+    if (inspectorBody) {
+      renderInspector(inspectorBody, state.context);
+      const tokens = state.context.modelTokens;
+      ctxCount.textContent = tokens ? `~${tokens.toLocaleString()} tok` : "";
+    }
   });
 
   sendBtn.onclick = send;
   input.onkeydown = (e) => {
-    if (e.key === "Enter" && !e.shiftKey) {
+    if (e.key === "Enter" && !e.shiftKey && !e.isComposing) {
       e.preventDefault();
       send();
     }
   };
 
+  newBtn.disabled = true;
   render();
+  // a server without an init tool sends nothing until the first message
+  if (inspectorBody) renderInspector(inspectorBody, chat.state.context);
   chat.start();
   return chat;
 }
 
+/** A header button: an icon, and a label that narrow screens keep for screen
+ *  readers only. */
+function button(className, iconName, label) {
+  const b = h("button", className);
+  b.type = "button";
+  b.append(icon(iconName), h("span", "hai-btn-label", label));
+  return b;
+}
+
 /**
- * The context inspector. Makes the dual channel visible, which is the whole
- * argument — keep it on while developing.
+ * What the model context debug drawer shows. Makes the dual channel visible,
+ * which is the whole argument — keep it on while developing.
  */
 export function renderInspector(el, { messages = [], modelTokens = 0, uiTokens = 0 } = {}) {
+  // following the newest context, as the transcript does, unless scrolled up
+  const following = el.scrollHeight - el.scrollTop - el.clientHeight < 40;
   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` : ""),
+  if (!messages.length && !modelTokens && !uiTokens) {
+    el.append(
+      h("p", "hai-inspector-empty", "Nothing yet. Every message, tool call and digest the model receives shows up here."),
+    );
+    return;
+  }
+
+  const total = modelTokens + uiTokens;
+  const pct = uiTokens ? Math.round((1 - modelTokens / total) * 100) : 0;
+  const stats = h("div", "hai-ctx");
+  if (uiTokens) {
+    const headline = h("div", "hai-ctx-headline");
+    headline.append(h("span", "hai-ctx-pct", `${pct}%`), h("span", null, "kept out of context"));
+    stats.append(headline);
+  }
+  const meter = h("div", "hai-meter");
+  meter.setAttribute("aria-hidden", "true");
+  const share = h("span", "hai-meter-model");
+  share.style.width = `${total ? (modelTokens / total) * 100 : 100}%`;
+  meter.append(share);
+  stats.append(
+    meter,
+    stat("hai-key-model", "model context", modelTokens),
+    stat("hai-key-ui", "browser payload", uiTokens),
   );
-  el.append(bar);
+  el.append(stats);
 
   for (const m of messages) {
-    const box = h("div", "hai-msg");
+    const box = h("div", `hai-msg hai-msg-${m.role}`);
     box.append(h("div", "hai-role", m.role));
     const body = h("div", "hai-mbody");
     if (typeof m.content === "string") {
@@ -193,12 +433,36 @@ export function renderInspector(el, { messages = [], modelTokens = 0, uiTokens =
     } 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));
+        if (b.type === "tool_use") {
+          const call = h("div", "hai-tu");
+          call.append(h("span", "hai-kind", `tool_use · ${b.name}`), h("div", null, JSON.stringify(b.input)));
+          body.append(call);
+        }
+        if (b.type === "tool_result") {
+          const result = h("div", "hai-tr");
+          result.append(h("span", "hai-kind", "tool_result"), h("div", null, plain(b.content)));
+          body.append(result);
+        }
       }
     }
     box.append(body);
     el.append(box);
   }
+
+  if (following) el.scrollTop = el.scrollHeight;
+}
+
+function stat(key, label, tokens) {
+  const row = h("div", "hai-ctx-stat");
+  const name = h("span", "hai-ctx-label");
+  name.append(h("i", `hai-key ${key}`), label);
+  row.append(name, h("span", "hai-ctx-tok", `~${tokens.toLocaleString()} tok`));
+  return row;
+}
+
+/** A tool_result's content as text: a string, or an array of content blocks. */
+function plain(content) {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) return content.map((c) => c?.text ?? JSON.stringify(c)).join("\n");
+  return JSON.stringify(content);
 }