@assistant-ui/react-generative-ui 0.0.2

package/src/JSONGenerativeUI.server.tsx

@@ -0,0 +1,39 @@
+import { buildPresentParameters } from "./buildPresentParameters";
+import {
+  presentToolBase,
+  promptUserToolBase,
+  type JSONGenerativeUIOptions,
+  type PresentParameters,
+  type PresentTool,
+  type PresentToolOptions,
+  type PromptUserTool,
+} from "./JSONGenerativeUI.shared";
+
+/**
+ * Server build of {@link JSONGenerativeUI}, resolved through the package's
+ * `react-server` export condition.
+ *
+ * The model only needs each tool's `type`, `description`, and `parameters` on
+ * the server, so `present`/`prompt_user` return exactly that — no `execute` and
+ * no `render`, keeping the renderer (and React) out of the server graph. The
+ * client build adds those back. The two builds share one set of public types, so
+ * consumers see a single {@link JSONGenerativeUI} either way.
+ *
+ * `as` casts here because the tool types require a `render` for frontend/human
+ * tools; on the server it is structurally absent and never read.
+ */
+export class JSONGenerativeUI {
+  private readonly parameters: PresentParameters;
+
+  constructor(options: JSONGenerativeUIOptions) {
+    this.parameters = buildPresentParameters(options.library);
+  }
+
+  present(options?: PresentToolOptions): PresentTool {
+    return presentToolBase(this.parameters, options) as PresentTool;
+  }
+
+  promptUser(): PromptUserTool {
+    return promptUserToolBase(this.parameters) as PromptUserTool;
+  }
+}

package/src/JSONGenerativeUI.shared.ts

@@ -0,0 +1,74 @@
+import type { ToolDefinition } from "@assistant-ui/react";
+import type { JSONSchema7 } from "json-schema";
+import type { GenerativeUILibrary } from "./types";
+
+/** Options for {@link JSONGenerativeUI}. */
+export type JSONGenerativeUIOptions = {
+  /**
+   * The components the model is allowed to render, keyed by the `$type` it
+   * selects them with. Author it with `defineGenerativeComponents({ ... })` so a
+   * `"use generative"` build can split each `render` from its `properties`.
+   */
+  library: GenerativeUILibrary;
+};
+
+/** Options for {@link JSONGenerativeUI.present}. */
+export type PresentToolOptions = {
+  /**
+   * Set `"standalone"` to render the component on its own surface (outside the
+   * chain-of-thought trace), e.g. a full-bleed artifact like a card. Omit it for
+   * the default inline rendering — there is no `"inline"` value because that is
+   * already the default.
+   */
+  display?: "standalone";
+};
+
+/** The `present` tool, as the model sees it (no client `render`/`execute`). */
+export type PresentTool = ToolDefinition<
+  Record<string, unknown>,
+  Record<string, never>
+>;
+
+/** The `prompt_user` tool, as the model sees it (no client `render`). */
+export type PromptUserTool = ToolDefinition<Record<string, unknown>, unknown>;
+
+const PRESENT_DESCRIPTION =
+  "Present a UI component to the user. Select a component with `$type` and " +
+  "provide its props inline; nest components with `children`.";
+
+const PROMPT_USER_DESCRIPTION =
+  "Present a UI component to the user and wait for their response. Select a " +
+  "component with `$type` and provide its props inline; nest components with " +
+  "`children`. The user interacts with it and the result is returned to you.";
+
+/** The tool `parameters` schema, built once per instance (see `buildPresentParameters`). */
+export type PresentParameters = JSONSchema7;
+
+/**
+ * The schema-only half of the `present` tool, shared by both builds. The server
+ * build returns exactly this; the client build adds `execute` and `render`.
+ * Takes the already-built `parameters` so it isn't recomputed per tool.
+ */
+export function presentToolBase(
+  parameters: PresentParameters,
+  options?: PresentToolOptions,
+) {
+  return {
+    type: "frontend" as const,
+    description: PRESENT_DESCRIPTION,
+    parameters,
+    ...(options?.display !== undefined ? { display: options.display } : {}),
+  };
+}
+
+/**
+ * The schema-only half of the `prompt_user` tool, shared by both builds. The
+ * server build returns exactly this; the client build adds `render`.
+ */
+export function promptUserToolBase(parameters: PresentParameters) {
+  return {
+    type: "human" as const,
+    description: PROMPT_USER_DESCRIPTION,
+    parameters,
+  };
+}

package/src/JSONGenerativeUI.test.tsx

@@ -0,0 +1,89 @@
+import { describe, it, expect } from "vitest";
+import { renderToStaticMarkup } from "react-dom/server";
+import { z } from "zod";
+import { JSONGenerativeUI as ClientGenUI } from "./JSONGenerativeUI.client";
+import { JSONGenerativeUI as ServerGenUI } from "./JSONGenerativeUI.server";
+import { defineGenerativeComponents } from "./defineGenerativeComponents";
+import type { GenerativeUILibrary } from "./types";
+
+const library: GenerativeUILibrary = {
+  Card: {
+    description: "A card.",
+    properties: z.object({ title: z.string() }),
+    render: ({ title, children }: any) => (
+      <section data-title={title}>{children}</section>
+    ),
+  },
+  Button: {
+    description: "A button.",
+    properties: z.object({ label: z.string() }),
+    render: ({ label }: any) => <button>{label}</button>,
+  },
+};
+
+const renderTool = (tool: any, args: unknown) =>
+  renderToStaticMarkup(
+    <>{tool.render({ args, status: { type: "complete" } })}</>,
+  );
+
+describe("JSONGenerativeUI — client build", () => {
+  const ui = new ClientGenUI({ library });
+
+  it("present is a frontend tool with matching parameters, render, and execute", () => {
+    const tool = ui.present();
+    expect(tool.type).toBe("frontend");
+    expect(typeof tool.execute).toBe("function");
+    expect(typeof tool.render).toBe("function");
+    expect(tool.unstable_backendDefault).toEqual({ parameters: true });
+    expect((tool.parameters as any).properties.$type.enum).toEqual([
+      "Card",
+      "Button",
+    ]);
+  });
+
+  it("present renders the model's tree against the library", () => {
+    const html = renderTool(ui.present(), { $type: "Card", title: "Hi" });
+    expect(html).toBe('<section data-title="Hi"></section>');
+  });
+
+  it("prompt_user is a human tool that renders the tree (no execute)", () => {
+    const tool = ui.promptUser();
+    expect(tool.type).toBe("human");
+    expect(tool.unstable_backendDefault).toEqual({ parameters: true });
+    expect((tool as any).execute).toBeUndefined();
+    const html = renderTool(tool, { $type: "Button", label: "ok" });
+    expect(html).toBe("<button>ok</button>");
+  });
+});
+
+describe("JSONGenerativeUI — server build", () => {
+  const ui = new ServerGenUI({ library });
+
+  it("present carries only schema (no render/execute) and matches the client schema", () => {
+    const tool = ui.present() as any;
+    expect(tool.type).toBe("frontend");
+    expect(tool.render).toBeUndefined();
+    expect(tool.execute).toBeUndefined();
+    expect(tool.unstable_backendDefault).toBeUndefined();
+    expect(tool.parameters.properties.$type.enum).toEqual(["Card", "Button"]);
+    expect(tool.parameters).toEqual(
+      new ClientGenUI({ library }).present().parameters,
+    );
+  });
+
+  it("prompt_user carries only schema (no render)", () => {
+    const tool = ui.promptUser() as any;
+    expect(tool.type).toBe("human");
+    expect(tool.render).toBeUndefined();
+    expect(tool.unstable_backendDefault).toBeUndefined();
+    expect(tool.parameters.properties.$type.enum).toEqual(["Card", "Button"]);
+  });
+});
+
+describe("defineGenerativeComponents", () => {
+  it("throws at runtime — it must be stripped by the compiler, never called", () => {
+    expect(() => defineGenerativeComponents({})).toThrow(
+      /no runtime implementation/,
+    );
+  });
+});

package/src/buildPresentParameters.ts

@@ -0,0 +1,90 @@
+import { toJSONSchema } from "assistant-stream";
+import type { JSONSchema7, JSONSchema7Definition } from "json-schema";
+import { TYPE_KEY } from "./constants";
+import type { GenerativeUILibrary } from "./types";
+
+/**
+ * Builds the JSON schema for the `present` tool from a {@link GenerativeUILibrary}.
+ *
+ * The model produces a node `{ $type, ...props }` where `$type` selects a
+ * component and the rest are its props. The schema is a flat object: `$type` is
+ * an enum of the component names, every component's props are merged into one
+ * optional bag, and `children` recurses via `$defs` so the tree can nest.
+ *
+ * It is intentionally flat rather than a per-`$type` discriminated union. Tool /
+ * function-call schemas (OpenAI and others) require the top-level parameters to
+ * be a plain object and reject a top-level `oneOf`/`anyOf`/`enum`. So props can't
+ * be refined per `$type` at the root; the model is guided instead by `$type`'s
+ * description (which lists each component) and each prop's own description. The
+ * renderer validates nothing here — an unknown `$type` or stray prop is handled
+ * at render time — so a looser schema only costs the model a hint, not safety.
+ */
+export function buildPresentParameters(
+  library: GenerativeUILibrary,
+): JSONSchema7 {
+  const names = Object.keys(library);
+
+  // Merge every component's props into one optional bag. `$type`/`children` are
+  // framework-reserved, so drop any author-declared copies. On a name clash the
+  // first component's schema wins — props are an advisory hint here, not a
+  // strict per-component contract.
+  const props: Record<string, JSONSchema7Definition> = {};
+  for (const name of names) {
+    const propsSchema = toJSONSchema(library[name]!.properties);
+    if (propsSchema.type !== "object") {
+      throw new Error(
+        `[@assistant-ui/react-generative-ui] Component "${name}": ` +
+          "`properties` must be an object schema (e.g. `z.object({ ... })`).",
+      );
+    }
+    for (const [key, schema] of Object.entries(propsSchema.properties ?? {})) {
+      if (key === TYPE_KEY || key === "children") continue;
+      if (!(key in props)) {
+        props[key] = schema;
+      } else if (process.env["NODE_ENV"] !== "production") {
+        // eslint-disable-next-line no-console
+        console.warn(
+          `[@assistant-ui/react-generative-ui] Prop "${key}" is declared by more ` +
+            "than one component; the first component's schema is kept and the rest " +
+            "are ignored. Rename or align the type to avoid an ambiguous schema.",
+        );
+      }
+    }
+  }
+
+  // Carry each component's description on the `$type` enum, since there are no
+  // per-branch schemas to hang them on anymore.
+  const typeDescription =
+    names.length > 0
+      ? `The component to render. ${names
+          .map((name) => `"${name}": ${library[name]!.description}`)
+          .join("; ")}`
+      : "The component to render.";
+
+  const node: JSONSchema7 = {
+    type: "object",
+    properties: {
+      [TYPE_KEY]: { type: "string", enum: names, description: typeDescription },
+      ...props,
+      children: { $ref: "#/$defs/children" },
+    },
+    required: [TYPE_KEY],
+  };
+
+  const children: JSONSchema7 = {
+    description: "Nested generative UI rendered inside this component.",
+    anyOf: [
+      { type: "string" },
+      { $ref: "#/$defs/node" },
+      {
+        type: "array",
+        items: { anyOf: [{ type: "string" }, { $ref: "#/$defs/node" }] },
+      },
+    ],
+  };
+
+  return {
+    ...node,
+    $defs: { node, children },
+  };
+}

package/src/constants.ts

@@ -0,0 +1,10 @@
+/**
+ * The wire key naming the component to render.
+ *
+ * The model emits nodes as flat objects `{ [TYPE_KEY]: name, ...props }`. We
+ * use `$type` rather than `type` so a component's own `type` prop (e.g. a
+ * button's `type="submit"`) flows through as an ordinary prop without
+ * colliding with the discriminator. It mirrors the `$type` discriminator
+ * convention used by JSON polymorphism elsewhere.
+ */
+export const TYPE_KEY = "$type";

package/src/defineGenerativeComponents.ts

@@ -0,0 +1,38 @@
+import type { GenerativeUILibrary } from "./types";
+
+/**
+ * Authoring helper for a `"use generative"` generative-UI library — the set of
+ * components the model may render. Each component colocates its `properties`
+ * schema (kept on every build, drives the tool parameters) with its `render`
+ * (kept only on the client). Pass the result to {@link JSONGenerativeUI}:
+ *
+ * ```tsx
+ * "use generative";
+ * const generative = new JSONGenerativeUI({
+ *   library: defineGenerativeComponents({
+ *     Card: {
+ *       description: "A card.",
+ *       properties: z.object({ title: z.string() }),
+ *       render: (props) => <Card {...props} />,
+ *     },
+ *   }),
+ * });
+ * ```
+ *
+ * Unlike {@link defineToolkit}, it has **no runtime implementation**. A
+ * `"use generative"` compiler unwraps the `defineGenerativeComponents(...)` call
+ * per build, dropping each `render` (and its client-only imports) from the server
+ * build. Reaching it at runtime means the module wasn't compiled (the directive
+ * is missing, or it was used outside a `"use generative"` file), so it throws
+ * rather than shipping client `render` code to the server.
+ */
+export function defineGenerativeComponents(
+  _library: GenerativeUILibrary,
+): GenerativeUILibrary {
+  throw new Error(
+    "[assistant-ui] defineGenerativeComponents() has no runtime implementation " +
+      "— it is stripped at build time by the use-generative compiler. Reaching " +
+      "it means this module was not compiled (e.g. used outside a " +
+      '"use generative" file). Add the directive, or do not use it here.',
+  );
+}

package/src/generativeUIToJSX.test.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect } from "vitest";
+import { generativeUIToJSX } from "./generativeUIToJSX";
+
+describe("generativeUIToJSX", () => {
+  it("renders a leaf element as a self-closing tag", () => {
+    expect(generativeUIToJSX({ $type: "Weather", id: "5d99d2e9" })).toBe(
+      '<Weather id="5d99d2e9" />',
+    );
+  });
+
+  it("renders an element with no props", () => {
+    expect(generativeUIToJSX({ $type: "Divider" })).toBe("<Divider />");
+  });
+
+  it("formats prop types as JSX attributes", () => {
+    expect(
+      generativeUIToJSX({
+        $type: "Box",
+        label: "hi",
+        count: 3,
+        open: true,
+        hidden: false,
+        data: { a: 1 },
+      }),
+    ).toBe('<Box label="hi" count={3} open hidden={false} data={{"a":1}} />');
+  });
+
+  it("uses the expression form for strings with quotes", () => {
+    expect(generativeUIToJSX({ $type: "Note", text: 'say "hi"' })).toBe(
+      '<Note text={"say \\"hi\\""} />',
+    );
+  });
+
+  it("renders string children between tags", () => {
+    expect(
+      generativeUIToJSX({ $type: "Text", tone: "muted", children: "hello" }),
+    ).toBe('<Text tone="muted">hello</Text>');
+  });
+
+  it("renders nested and arrayed children recursively", () => {
+    expect(
+      generativeUIToJSX({
+        $type: "Card",
+        title: "Hi",
+        children: [
+          { $type: "Text", children: "a" },
+          { $type: "Text", tone: "muted", children: "b" },
+        ],
+      }),
+    ).toBe('<Card title="Hi"><Text>a</Text><Text tone="muted">b</Text></Card>');
+  });
+
+  it("bounds deeply nested trees instead of overflowing the stack", () => {
+    let node: any = { $type: "Text", children: "deep" };
+    for (let i = 0; i < 5000; i++) node = { $type: "Card", children: node };
+    expect(() => generativeUIToJSX(node)).not.toThrow();
+  });
+
+  it("returns empty string for non-renderable nodes", () => {
+    expect(generativeUIToJSX(null)).toBe("");
+    expect(generativeUIToJSX(true)).toBe("");
+    expect(generativeUIToJSX({})).toBe(""); // no $type yet (still streaming)
+  });
+});

package/src/generativeUIToJSX.ts

@@ -0,0 +1,63 @@
+import { TYPE_KEY } from "./constants";
+
+/**
+ * Serializes a generative-UI node to a JSX-like string for display — the
+ * "view source" of a model-produced tree. The wire form
+ * `{ $type: "Weather", id: "x" }` becomes `<Weather id="x" />`, and nested
+ * `children` render between tags: `<Card title="Hi"><Text>hello</Text></Card>`.
+ *
+ * It is a faithful textual rendering, not a parser: text children are emitted
+ * verbatim (not HTML/JSX-escaped), so the result is meant to be shown, not
+ * re-parsed. Returns `""` for nodes that aren't renderable (no `$type` yet,
+ * `null`, booleans).
+ */
+export function generativeUIToJSX(node: unknown): string {
+  return toJSX(node, 0);
+}
+
+/**
+ * The deepest tree we serialize. Input is model-produced, so a runaway/
+ * adversarial response could nest arbitrarily deep and overflow the stack — past
+ * this depth (far beyond any real UI) we stop. Mirrors the renderer's bound.
+ */
+const MAX_DEPTH = 64;
+
+function toJSX(node: unknown, depth: number): string {
+  if (depth > MAX_DEPTH) return "";
+  if (node == null || typeof node === "boolean") return "";
+  if (typeof node === "string") return node;
+  if (typeof node === "number") return String(node);
+  if (Array.isArray(node))
+    return node.map((child) => toJSX(child, depth + 1)).join("");
+  if (typeof node !== "object") return "";
+
+  const {
+    [TYPE_KEY]: type,
+    children,
+    ...props
+  } = node as Record<string, unknown>;
+  if (typeof type !== "string") return "";
+
+  const attrs = Object.entries(props)
+    .map(([key, value]) => formatAttr(key, value))
+    .join("");
+  const inner = children === undefined ? "" : toJSX(children, depth + 1);
+
+  return inner === ""
+    ? `<${type}${attrs} />`
+    : `<${type}${attrs}>${inner}</${type}>`;
+}
+
+/** Formats one prop as a JSX attribute (`id="x"`, `count={3}`, `open`, …). */
+function formatAttr(key: string, value: unknown): string {
+  if (value === undefined) return "";
+  if (value === true) return ` ${key}`;
+  if (typeof value === "string") {
+    // Plain double-quoted form when safe; expression form when a quote or
+    // newline would break the attribute.
+    return /["\n]/.test(value)
+      ? ` ${key}={${JSON.stringify(value)}}`
+      : ` ${key}="${value}"`;
+  }
+  return ` ${key}={${JSON.stringify(value)}}`;
+}

package/src/index.ts

@@ -0,0 +1,26 @@
+// `JSONGenerativeUI` is the one export that differs per build: it comes from the
+// `./internal-json` subpath, which resolves to the server variant (schema only)
+// under the `react-server` condition and the client variant (adds render/execute)
+// otherwise. Everything else here is isomorphic, so this single entry serves
+// both conditions — no per-build index barrel needed.
+export { JSONGenerativeUI } from "@assistant-ui/react-generative-ui/internal-json";
+export { renderGenerativeUI } from "./renderGenerativeUI";
+export { generativeUIToJSX } from "./generativeUIToJSX";
+export { buildPresentParameters } from "./buildPresentParameters";
+export { defineGenerativeComponents } from "./defineGenerativeComponents";
+export { TYPE_KEY } from "./constants";
+export type {
+  JSONGenerativeUIOptions,
+  PresentTool,
+  PresentToolOptions,
+  PromptUserTool,
+} from "./JSONGenerativeUI.shared";
+export type {
+  GenerativeUILibrary,
+  GenerativeUIComponent,
+  GenerativeUIElement,
+  GenerativeUIProps,
+  GenerativeUINode,
+  GenerativeUIStatus,
+  GenerativeUIRenderContext,
+} from "./types";