@haikit/react 0.8.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,76 @@
+# @haikit/react
+
+Write haikit surface components in React.
+
+```bash
+npm install @haikit/react react react-dom
+```
+
+```tsx
+import { useState } from "react";
+import { reactSurface, type SurfaceProps } from "@haikit/react";
+import type { greetingPicker } from "../shared/surfaces.ts";
+
+function GreetingPicker({ props, send, mode, state, selection }: SurfaceProps<typeof greetingPicker>) {
+  const [script, setScript] = useState<string | null>(null); // local state: never reaches the server
+  const live = state === "live" && mode === "elicit";
+  return (
+    <div className="rows">
+      {props.greetings
+        .filter((g) => !script || g.script === script)
+        .map((g) =>
+          live ? (
+            <button key={g.code} type="button" onClick={() => send("choose", g.code)}>
+              {g.text}
+            </button>
+          ) : (
+            <div key={g.code} className={g.code === selection ? "picked" : undefined}>
+              {g.text}
+            </div>
+          ),
+        )}
+    </div>
+  );
+}
+
+export const registry = { greeting_picker: reactSurface(GreetingPicker) };
+```
+
+Pass `registry` to `mountChat` or `createChat` as usual. The client's contract
+doesn't change: a registry entry is anything with `mount(element, props, ctx)`,
+and `reactSurface` builds one around a React component.
+
+## What the component gets
+
+`SurfaceProps<typeof yourSurface>` is typed from the same `defineSurface`
+contract the server implements:
+
+| prop | |
+|---|---|
+| `props` | the surface's props, as its `props` schema produced them |
+| `send(action, value)` | the only channel to the server: an action the contract declares, with a value of its input type. Anything else is a compile error |
+| `mode` | how the surface was opened: `elicit` as a question the turn waits on, `display` as something shown. It stays `elicit` once answered |
+| `state` | `live`, or `frozen` once answered: a resolved question can't be answered again |
+| `selection` | what the user picked, once frozen |
+| `expired` | the conversation is out of date; nothing here can reach the server again |
+
+Import the contract with `import type`. Only the types are needed, so the
+schemas and their library stay out of the browser bundle.
+
+## Lifecycle
+
+The default transcript mounts a surface **once**, so `useState` survives the
+conversation streaming on around it. The root re-renders when the surface
+freezes or the conversation goes out of date. It is unmounted when the surface
+goes away, on `chat.reset()` or `chat.close()`, so effects clean up after
+themselves. The first render is synchronous, so the surface already has its
+height when the transcript scrolls to it.
+
+React escapes text by default. Keep it that way: tool payloads are untrusted
+input, so never pass them to `dangerouslySetInnerHTML`.
+
+## Building
+
+React needs a bundler. `examples/hello-react` in the haikit repo runs Vite
+inside its own node server while developing, so the app and `/hai` share one
+port with no proxy, and serves `vite build`'s output in production.

package/dist/index.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @haikit/react — write surface components in React.
+ *
+ *   function GreetingPicker({ props, send, state }: SurfaceProps<typeof greetingPicker>) { … }
+ *   export const registry = { greeting_picker: reactSurface(GreetingPicker) };
+ *
+ * The client's contract is unchanged: a registry entry is something with a
+ * `mount(element, props, ctx)`. This builds one around a React component, and
+ * types it from the same `defineSurface` contract the server implements, so a
+ * prop or an action that changes there stops this side compiling.
+ */
+import { type ComponentType } from "react";
+import type { ComponentDef, SurfaceMode, SurfaceState } from "@haikit/client";
+import type { ActionMap, Infer, QueryMap, Surface } from "@haikit/core";
+type AnySurface = Surface<any, ActionMap, QueryMap>;
+type PropsOf<S> = S extends Surface<infer P, any, any> ? P : never;
+type ActionsOf<S> = S extends Surface<any, infer A, any> ? A : never;
+/** What a React surface component receives, typed from its surface contract. */
+export interface SurfaceProps<S extends AnySurface> {
+    /** The surface's props, as its `props` schema produced them. */
+    props: PropsOf<S>;
+    /**
+     * How the surface was opened: `elicit` as a question the turn waits on,
+     * `display` as something shown. It doesn't change once the question is
+     * answered; `state` does.
+     */
+    mode: SurfaceMode;
+    /** `frozen` once answered: a resolved question cannot be answered again. */
+    state: SurfaceState;
+    /** What the user picked, once the surface is frozen. */
+    selection?: unknown;
+    /** The conversation is out of date: nothing here can reach the server again. */
+    expired: boolean;
+    /**
+     * The only channel to the server: an action the contract declares, with a
+     * value of its input type. Never a tool, never a handler.
+     */
+    send<K extends keyof ActionsOf<S> & string>(action: K, value: Infer<ActionsOf<S>[K]["input"]>): Promise<void>;
+}
+/**
+ * A registry entry that renders `Component` into the surface's element.
+ *
+ * The first render is synchronous, so the surface has its height when the
+ * transcript scrolls to it; later ones are React's. It re-renders when the
+ * surface freezes or the conversation goes out of date, and its root is
+ * unmounted when the surface goes away, so effects clean up after themselves.
+ */
+export declare function reactSurface<S extends AnySurface>(Component: ComponentType<SurfaceProps<S>>): ComponentDef<PropsOf<S>>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,OAAO,CAAC;AAG1D,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9E,OAAO,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAExE,KAAK,UAAU,GAAG,OAAO,CAAC,GAAG,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;AACpD,KAAK,OAAO,CAAC,CAAC,IAAI,CAAC,SAAS,OAAO,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AACnE,KAAK,SAAS,CAAC,CAAC,IAAI,CAAC,SAAS,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAErE,gFAAgF;AAChF,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,UAAU;IAChD,gEAAgE;IAChE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAClB;;;;OAIG;IACH,IAAI,EAAE,WAAW,CAAC;IAClB,4EAA4E;IAC5E,KAAK,EAAE,YAAY,CAAC;IACpB,wDAAwD;IACxD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,gFAAgF;IAChF,OAAO,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,IAAI,CAAC,CAAC,SAAS,MAAM,SAAS,CAAC,CAAC,CAAC,GAAG,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/G;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,UAAU,EAAE,SAAS,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CA4CtH"}

package/dist/index.js

@@ -0,0 +1,66 @@
+/**
+ * @haikit/react — write surface components in React.
+ *
+ *   function GreetingPicker({ props, send, state }: SurfaceProps<typeof greetingPicker>) { … }
+ *   export const registry = { greeting_picker: reactSurface(GreetingPicker) };
+ *
+ * The client's contract is unchanged: a registry entry is something with a
+ * `mount(element, props, ctx)`. This builds one around a React component, and
+ * types it from the same `defineSurface` contract the server implements, so a
+ * prop or an action that changes there stops this side compiling.
+ */
+import { createElement } from "react";
+import { createRoot } from "react-dom/client";
+import { flushSync } from "react-dom";
+/**
+ * A registry entry that renders `Component` into the surface's element.
+ *
+ * The first render is synchronous, so the surface has its height when the
+ * transcript scrolls to it; later ones are React's. It re-renders when the
+ * surface freezes or the conversation goes out of date, and its root is
+ * unmounted when the surface goes away, so effects clean up after themselves.
+ */
+export function reactSurface(Component) {
+    return {
+        mount(element, props, ctx) {
+            const root = createRoot(element);
+            let state = ctx.state;
+            // set when it is mounted already frozen
+            let selection = ctx.selection;
+            let expired = false;
+            const draw = () => root.render(createElement(Component, {
+                props,
+                mode: ctx.mode,
+                state,
+                selection,
+                expired,
+                send: ctx.send,
+            }));
+            // A component that throws on its first render leaves no instance behind
+            // to unmount later, so its root is let go of here, before the error goes
+            // on; otherwise a remount would stack a second root on this element.
+            try {
+                flushSync(draw);
+            }
+            catch (err) {
+                root.unmount();
+                throw err;
+            }
+            return {
+                freeze(picked) {
+                    state = "frozen";
+                    selection = picked;
+                    draw();
+                },
+                expire() {
+                    expired = true;
+                    draw();
+                },
+                unmount() {
+                    root.unmount();
+                },
+            };
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,aAAa,EAAsB,MAAM,OAAO,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AA+BtC;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAuB,SAAyC;IAC1F,OAAO;QACL,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,GAAG;YACvB,MAAM,IAAI,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;YACjC,IAAI,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC;YACtB,wCAAwC;YACxC,IAAI,SAAS,GAAG,GAAG,CAAC,SAAS,CAAC;YAC9B,IAAI,OAAO,GAAG,KAAK,CAAC;YACpB,MAAM,IAAI,GAAG,GAAG,EAAE,CAChB,IAAI,CAAC,MAAM,CACT,aAAa,CAAC,SAAS,EAAE;gBACvB,KAAK;gBACL,IAAI,EAAE,GAAG,CAAC,IAAI;gBACd,KAAK;gBACL,SAAS;gBACT,OAAO;gBACP,IAAI,EAAE,GAAG,CAAC,IAA+B;aAC1C,CAAC,CACH,CAAC;YACJ,wEAAwE;YACxE,yEAAyE;YACzE,qEAAqE;YACrE,IAAI,CAAC;gBACH,SAAS,CAAC,IAAI,CAAC,CAAC;YAClB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,OAAO,EAAE,CAAC;gBACf,MAAM,GAAG,CAAC;YACZ,CAAC;YACD,OAAO;gBACL,MAAM,CAAC,MAAM;oBACX,KAAK,GAAG,QAAQ,CAAC;oBACjB,SAAS,GAAG,MAAM,CAAC;oBACnB,IAAI,EAAE,CAAC;gBACT,CAAC;gBACD,MAAM;oBACJ,OAAO,GAAG,IAAI,CAAC;oBACf,IAAI,EAAE,CAAC;gBACT,CAAC;gBACD,OAAO;oBACL,IAAI,CAAC,OAAO,EAAE,CAAC;gBACjB,CAAC;aACF,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@haikit/react",
+  "version": "0.8.0",
+  "description": "Write haikit surface components in React: typed props and actions from the shared surface contract.",
+  "keywords": [
+    "haikit",
+    "react",
+    "llm",
+    "agent",
+    "agentic-ui",
+    "generative-ui",
+    "tool-use",
+    "ai"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "prepack": "npm --prefix ../.. run build"
+  },
+  "dependencies": {
+    "@haikit/client": "0.8.0",
+    "@haikit/core": "0.8.0"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/wfoxd/haikit/tree/main/packages/react#readme",
+  "bugs": {
+    "url": "https://github.com/wfoxd/haikit/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wfoxd/haikit.git",
+    "directory": "packages/react"
+  }
+}

package/src/index.ts

@@ -0,0 +1,98 @@
+/**
+ * @haikit/react — write surface components in React.
+ *
+ *   function GreetingPicker({ props, send, state }: SurfaceProps<typeof greetingPicker>) { … }
+ *   export const registry = { greeting_picker: reactSurface(GreetingPicker) };
+ *
+ * The client's contract is unchanged: a registry entry is something with a
+ * `mount(element, props, ctx)`. This builds one around a React component, and
+ * types it from the same `defineSurface` contract the server implements, so a
+ * prop or an action that changes there stops this side compiling.
+ */
+
+import { createElement, type ComponentType } from "react";
+import { createRoot } from "react-dom/client";
+import { flushSync } from "react-dom";
+import type { ComponentDef, SurfaceMode, SurfaceState } from "@haikit/client";
+import type { ActionMap, Infer, QueryMap, Surface } from "@haikit/core";
+
+type AnySurface = Surface<any, ActionMap, QueryMap>;
+type PropsOf<S> = S extends Surface<infer P, any, any> ? P : never;
+type ActionsOf<S> = S extends Surface<any, infer A, any> ? A : never;
+
+/** What a React surface component receives, typed from its surface contract. */
+export interface SurfaceProps<S extends AnySurface> {
+  /** The surface's props, as its `props` schema produced them. */
+  props: PropsOf<S>;
+  /**
+   * How the surface was opened: `elicit` as a question the turn waits on,
+   * `display` as something shown. It doesn't change once the question is
+   * answered; `state` does.
+   */
+  mode: SurfaceMode;
+  /** `frozen` once answered: a resolved question cannot be answered again. */
+  state: SurfaceState;
+  /** What the user picked, once the surface is frozen. */
+  selection?: unknown;
+  /** The conversation is out of date: nothing here can reach the server again. */
+  expired: boolean;
+  /**
+   * The only channel to the server: an action the contract declares, with a
+   * value of its input type. Never a tool, never a handler.
+   */
+  send<K extends keyof ActionsOf<S> & string>(action: K, value: Infer<ActionsOf<S>[K]["input"]>): Promise<void>;
+}
+
+/**
+ * A registry entry that renders `Component` into the surface's element.
+ *
+ * The first render is synchronous, so the surface has its height when the
+ * transcript scrolls to it; later ones are React's. It re-renders when the
+ * surface freezes or the conversation goes out of date, and its root is
+ * unmounted when the surface goes away, so effects clean up after themselves.
+ */
+export function reactSurface<S extends AnySurface>(Component: ComponentType<SurfaceProps<S>>): ComponentDef<PropsOf<S>> {
+  return {
+    mount(element, props, ctx) {
+      const root = createRoot(element);
+      let state = ctx.state;
+      // set when it is mounted already frozen
+      let selection = ctx.selection;
+      let expired = false;
+      const draw = () =>
+        root.render(
+          createElement(Component, {
+            props,
+            mode: ctx.mode,
+            state,
+            selection,
+            expired,
+            send: ctx.send as SurfaceProps<S>["send"],
+          }),
+        );
+      // A component that throws on its first render leaves no instance behind
+      // to unmount later, so its root is let go of here, before the error goes
+      // on; otherwise a remount would stack a second root on this element.
+      try {
+        flushSync(draw);
+      } catch (err) {
+        root.unmount();
+        throw err;
+      }
+      return {
+        freeze(picked) {
+          state = "frozen";
+          selection = picked;
+          draw();
+        },
+        expire() {
+          expired = true;
+          draw();
+        },
+        unmount() {
+          root.unmount();
+        },
+      };
+    },
+  };
+}