@assistant-ui/react-generative-ui 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 AgentbaseAI Inc.
+
+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,140 @@
+# @assistant-ui/react-generative-ui
+
+Generative UI tools for assistant-ui.
+
+## Installation
+
+```bash
+npm install @assistant-ui/react-generative-ui
+```
+
+## Usage
+
+Declare the components the model is allowed to render in a library, then expose
+them through the `present` tool. The model emits a `{ $type, ...props }` tree
+(`$type` names the component, so a real `type` prop never collides); the tool
+renders it against the library.
+
+```tsx
+import { JSONGenerativeUI } from "@assistant-ui/react-generative-ui";
+import { Thread, Tools } from "@assistant-ui/react";
+import { z } from "zod";
+
+const generativeUI = new JSONGenerativeUI({
+  library: {
+    Card: {
+      description: "A card container with a title.",
+      properties: z.object({ title: z.string() }),
+      render: ({ title, children }) => (
+        <section className="card">
+          <h3>{title}</h3>
+          {children}
+        </section>
+      ),
+    },
+    Text: {
+      description: "A run of text.",
+      properties: z.object({ tone: z.enum(["muted", "normal"]).optional() }),
+      render: ({ tone, children }) => <p data-tone={tone}>{children}</p>,
+    },
+  },
+});
+
+const toolkit = {
+  present: generativeUI.present(),
+};
+
+function App() {
+  return (
+    <Thread>
+      <Tools toolkit={toolkit} />
+      {/* MessageList, Composer, ... */}
+    </Thread>
+  );
+}
+```
+
+A node's `children` prop is rendered recursively, so components can be nested:
+
+```json
+{
+  "$type": "Card",
+  "title": "Hello",
+  "children": [{ "$type": "Text", "tone": "muted", "children": "Nested text" }]
+}
+```
+
+## Streaming props
+
+By default a component renders only once its props have fully arrived, so
+`render` always sees complete props. Opt into rendering from partial props with
+`streamProperties`. When you do, `render` receives an injected `$status` prop
+that discriminates the props: while `"streaming"` they are `Partial`, and once
+`"done"` they are complete.
+
+```tsx
+const generativeUI = new JSONGenerativeUI({
+  library: {
+    Weather: {
+      description: "A live weather card.",
+      properties: z.object({ city: z.string(), temp: z.number() }),
+      streamProperties: true,
+      render: (props) => {
+        if (props.$status === "done") {
+          return <Card>{`${props.city}: ${props.temp}°`}</Card>; // complete props
+        }
+        return <Card>{props.city ?? "Loading…"}</Card>; // partial props
+      },
+    },
+  },
+});
+```
+
+`render` is a function of `props`, not a React component — but it runs on its
+own fiber, so you can call hooks inside it as usual.
+
+## `"use generative"` authoring
+
+The examples above wire the library up by hand on the client. With the
+`"use generative"` compiler (`@assistant-ui/next` or `@assistant-ui/vite`) you
+can instead colocate a component's `properties` schema with its `render` and
+expose the library as tools, and the build splits each half to the right target:
+the schema goes to the server (so the model sees the tool), the `render` stays on
+the client.
+
+```tsx
+"use generative";
+
+import { z } from "zod";
+import { Weather } from "@/components/weather";
+import { defineToolkit } from "@assistant-ui/react";
+import {
+  JSONGenerativeUI,
+  defineGenerativeComponents,
+} from "@assistant-ui/react-generative-ui";
+
+const generative = new JSONGenerativeUI({
+  library: defineGenerativeComponents({
+    Weather: {
+      description: "Show a weather card.",
+      properties: z.object({ city: z.string() }),
+      render: (props) => <Weather {...props} />,
+    },
+  }),
+});
+
+export default defineToolkit({
+  // `present` displays a component; `prompt_user` is a human-in-the-loop prompt.
+  present: generative.present(),
+  prompt_user: generative.promptUser(),
+});
+```
+
+The model calls `present` with a node like `{ "$type": "Weather", "city": "SF" }`.
+Pass `present({ display: "standalone" })` to render the component on its own
+surface instead of inline. See the
+[`"use generative"` docs](https://www.assistant-ui.com/docs) for the build setup.
+
+## License
+
+MIT

package/dist/JSONGenerativeUI.client.d.ts

@@ -0,0 +1,23 @@
+import { JSONGenerativeUIOptions, PresentTool, PresentToolOptions, PromptUserTool } from "./JSONGenerativeUI.shared.js";
+
+//#region src/JSONGenerativeUI.client.d.ts
+/**
+ * Client build of {@link JSONGenerativeUI}, resolved through the package's
+ * `default` export condition (browser and SSR).
+ *
+ * `present` is a frontend tool that renders the model's `{ $type, ...props }`
+ * tree against the library and resolves immediately. `prompt_user` is a
+ * human-in-the-loop tool: the model pauses and the rendered UI supplies the
+ * result. Both draw the tree the same way, so they share one `render`.
+ */
+declare class JSONGenerativeUI {
+  private readonly library;
+  private readonly parameters;
+  constructor(options: JSONGenerativeUIOptions);
+  private readonly render;
+  present(options?: PresentToolOptions): PresentTool;
+  promptUser(): PromptUserTool;
+}
+//#endregion
+export { JSONGenerativeUI };
+//# sourceMappingURL=JSONGenerativeUI.client.d.ts.map

package/dist/JSONGenerativeUI.client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"JSONGenerativeUI.client.d.ts","names":[],"sources":["../src/JSONGenerativeUI.client.tsx"],"mappings":";;;;;AA+BA;;;;;;;cAAa,gBAAA;EAAA,iBACM,OAAA;EAAA,iBACA,UAAA;cAEL,OAAA,EAAS,uBAAA;EAAA,iBAKJ,MAAA;EASjB,OAAA,CAAQ,OAAA,GAAU,kBAAA,GAAqB,WAAA;EASvC,UAAA,IAAc,cAAA;AAAA"}

package/dist/JSONGenerativeUI.client.js

@@ -0,0 +1,48 @@
+import { buildPresentParameters } from "./buildPresentParameters.js";
+import { presentToolBase, promptUserToolBase } from "./JSONGenerativeUI.shared.js";
+import { renderGenerativeUI } from "./renderGenerativeUI.js";
+//#region src/JSONGenerativeUI.client.tsx
+/** Maps a tool-call part status to the generative-UI streaming status. Only a
+* `complete` call has fully-arrived args; `running` and `incomplete`
+* (aborted/errored, so args may be partial) both render as `"streaming"` so a
+* non-streaming component is never handed partial props. */
+function uiStatus(status) {
+	return status.type === "complete" ? "done" : "streaming";
+}
+/**
+* Client build of {@link JSONGenerativeUI}, resolved through the package's
+* `default` export condition (browser and SSR).
+*
+* `present` is a frontend tool that renders the model's `{ $type, ...props }`
+* tree against the library and resolves immediately. `prompt_user` is a
+* human-in-the-loop tool: the model pauses and the rendered UI supplies the
+* result. Both draw the tree the same way, so they share one `render`.
+*/
+var JSONGenerativeUI = class {
+	library;
+	parameters;
+	constructor(options) {
+		this.library = options.library;
+		this.parameters = buildPresentParameters(options.library);
+	}
+	render = ({ args, status }) => renderGenerativeUI(args, this.library, { status: uiStatus(status) });
+	present(options) {
+		return {
+			...presentToolBase(this.parameters, options),
+			unstable_backendDefault: { parameters: true },
+			execute: async () => ({}),
+			render: this.render
+		};
+	}
+	promptUser() {
+		return {
+			...promptUserToolBase(this.parameters),
+			unstable_backendDefault: { parameters: true },
+			render: this.render
+		};
+	}
+};
+//#endregion
+export { JSONGenerativeUI };
+
+//# sourceMappingURL=JSONGenerativeUI.client.js.map

package/dist/JSONGenerativeUI.client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"JSONGenerativeUI.client.js","names":[],"sources":["../src/JSONGenerativeUI.client.tsx"],"sourcesContent":["import type { ReactNode } from \"react\";\nimport { buildPresentParameters } from \"./buildPresentParameters\";\nimport {\n  presentToolBase,\n  promptUserToolBase,\n  type JSONGenerativeUIOptions,\n  type PresentParameters,\n  type PresentTool,\n  type PresentToolOptions,\n  type PromptUserTool,\n} from \"./JSONGenerativeUI.shared\";\nimport { renderGenerativeUI } from \"./renderGenerativeUI\";\nimport type { GenerativeUILibrary, GenerativeUIStatus } from \"./types\";\n\n/** Maps a tool-call part status to the generative-UI streaming status. Only a\n * `complete` call has fully-arrived args; `running` and `incomplete`\n * (aborted/errored, so args may be partial) both render as `\"streaming\"` so a\n * non-streaming component is never handed partial props. */\nfunction uiStatus(status: { type: string }): GenerativeUIStatus {\n  return status.type === \"complete\" ? \"done\" : \"streaming\";\n}\n\n/**\n * Client build of {@link JSONGenerativeUI}, resolved through the package's\n * `default` export condition (browser and SSR).\n *\n * `present` is a frontend tool that renders the model's `{ $type, ...props }`\n * tree against the library and resolves immediately. `prompt_user` is a\n * human-in-the-loop tool: the model pauses and the rendered UI supplies the\n * result. Both draw the tree the same way, so they share one `render`.\n */\nexport class JSONGenerativeUI {\n  private readonly library: GenerativeUILibrary;\n  private readonly parameters: PresentParameters;\n\n  constructor(options: JSONGenerativeUIOptions) {\n    this.library = options.library;\n    this.parameters = buildPresentParameters(options.library);\n  }\n\n  private readonly render = ({\n    args,\n    status,\n  }: {\n    args: unknown;\n    status: { type: string };\n  }): ReactNode =>\n    renderGenerativeUI(args, this.library, { status: uiStatus(status) });\n\n  present(options?: PresentToolOptions): PresentTool {\n    return {\n      ...presentToolBase(this.parameters, options),\n      unstable_backendDefault: { parameters: true },\n      execute: async () => ({}),\n      render: this.render,\n    };\n  }\n\n  promptUser(): PromptUserTool {\n    return {\n      ...promptUserToolBase(this.parameters),\n      unstable_backendDefault: { parameters: true },\n      render: this.render,\n    };\n  }\n}\n"],"mappings":";;;;;;;;AAkBA,SAAS,SAAS,QAA8C;CAC9D,OAAO,OAAO,SAAS,aAAa,SAAS;AAC/C;;;;;;;;;;AAWA,IAAa,mBAAb,MAA8B;CAC5B;CACA;CAEA,YAAY,SAAkC;EAC5C,KAAK,UAAU,QAAQ;EACvB,KAAK,aAAa,uBAAuB,QAAQ,OAAO;CAC1D;CAEA,UAA2B,EACzB,MACA,aAKA,mBAAmB,MAAM,KAAK,SAAS,EAAE,QAAQ,SAAS,MAAM,EAAE,CAAC;CAErE,QAAQ,SAA2C;EACjD,OAAO;GACL,GAAG,gBAAgB,KAAK,YAAY,OAAO;GAC3C,yBAAyB,EAAE,YAAY,KAAK;GAC5C,SAAS,aAAa,CAAC;GACvB,QAAQ,KAAK;EACf;CACF;CAEA,aAA6B;EAC3B,OAAO;GACL,GAAG,mBAAmB,KAAK,UAAU;GACrC,yBAAyB,EAAE,YAAY,KAAK;GAC5C,QAAQ,KAAK;EACf;CACF;AACF"}

package/dist/JSONGenerativeUI.server.d.ts

@@ -0,0 +1,25 @@
+import { JSONGenerativeUIOptions, PresentTool, PresentToolOptions, PromptUserTool } from "./JSONGenerativeUI.shared.js";
+
+//#region src/JSONGenerativeUI.server.d.ts
+/**
+ * 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.
+ */
+declare class JSONGenerativeUI {
+  private readonly parameters;
+  constructor(options: JSONGenerativeUIOptions);
+  present(options?: PresentToolOptions): PresentTool;
+  promptUser(): PromptUserTool;
+}
+//#endregion
+export { JSONGenerativeUI };
+//# sourceMappingURL=JSONGenerativeUI.server.d.ts.map

package/dist/JSONGenerativeUI.server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"JSONGenerativeUI.server.d.ts","names":[],"sources":["../src/JSONGenerativeUI.server.tsx"],"mappings":";;;;;AAwBA;;;;;;;;;;;cAAa,gBAAA;EAAA,iBACM,UAAA;cAEL,OAAA,EAAS,uBAAA;EAIrB,OAAA,CAAQ,OAAA,GAAU,kBAAA,GAAqB,WAAA;EAIvC,UAAA,IAAc,cAAA;AAAA"}

package/dist/JSONGenerativeUI.server.js

@@ -0,0 +1,32 @@
+import { buildPresentParameters } from "./buildPresentParameters.js";
+import { presentToolBase, promptUserToolBase } from "./JSONGenerativeUI.shared.js";
+//#region src/JSONGenerativeUI.server.tsx
+/**
+* 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.
+*/
+var JSONGenerativeUI = class {
+	parameters;
+	constructor(options) {
+		this.parameters = buildPresentParameters(options.library);
+	}
+	present(options) {
+		return presentToolBase(this.parameters, options);
+	}
+	promptUser() {
+		return promptUserToolBase(this.parameters);
+	}
+};
+//#endregion
+export { JSONGenerativeUI };
+
+//# sourceMappingURL=JSONGenerativeUI.server.js.map

package/dist/JSONGenerativeUI.server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"JSONGenerativeUI.server.js","names":[],"sources":["../src/JSONGenerativeUI.server.tsx"],"sourcesContent":["import { buildPresentParameters } from \"./buildPresentParameters\";\nimport {\n  presentToolBase,\n  promptUserToolBase,\n  type JSONGenerativeUIOptions,\n  type PresentParameters,\n  type PresentTool,\n  type PresentToolOptions,\n  type PromptUserTool,\n} from \"./JSONGenerativeUI.shared\";\n\n/**\n * Server build of {@link JSONGenerativeUI}, resolved through the package's\n * `react-server` export condition.\n *\n * The model only needs each tool's `type`, `description`, and `parameters` on\n * the server, so `present`/`prompt_user` return exactly that — no `execute` and\n * no `render`, keeping the renderer (and React) out of the server graph. The\n * client build adds those back. The two builds share one set of public types, so\n * consumers see a single {@link JSONGenerativeUI} either way.\n *\n * `as` casts here because the tool types require a `render` for frontend/human\n * tools; on the server it is structurally absent and never read.\n */\nexport class JSONGenerativeUI {\n  private readonly parameters: PresentParameters;\n\n  constructor(options: JSONGenerativeUIOptions) {\n    this.parameters = buildPresentParameters(options.library);\n  }\n\n  present(options?: PresentToolOptions): PresentTool {\n    return presentToolBase(this.parameters, options) as PresentTool;\n  }\n\n  promptUser(): PromptUserTool {\n    return promptUserToolBase(this.parameters) as PromptUserTool;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAwBA,IAAa,mBAAb,MAA8B;CAC5B;CAEA,YAAY,SAAkC;EAC5C,KAAK,aAAa,uBAAuB,QAAQ,OAAO;CAC1D;CAEA,QAAQ,SAA2C;EACjD,OAAO,gBAAgB,KAAK,YAAY,OAAO;CACjD;CAEA,aAA6B;EAC3B,OAAO,mBAAmB,KAAK,UAAU;CAC3C;AACF"}

package/dist/JSONGenerativeUI.shared.d.ts

@@ -0,0 +1,53 @@
+import { JSONSchema7 } from "./node_modules/.pnpm/@types_json-schema@7.0.15/node_modules/@types/json-schema/index.js";
+import { GenerativeUILibrary } from "./types.js";
+import { ToolDefinition } from "@assistant-ui/react";
+
+//#region src/JSONGenerativeUI.shared.d.ts
+/** Options for {@link JSONGenerativeUI}. */
+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}. */
+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`). */
+type PresentTool = ToolDefinition<Record<string, unknown>, Record<string, never>>;
+/** The `prompt_user` tool, as the model sees it (no client `render`). */
+type PromptUserTool = ToolDefinition<Record<string, unknown>, unknown>;
+/** The tool `parameters` schema, built once per instance (see `buildPresentParameters`). */
+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.
+ */
+declare function presentToolBase(parameters: PresentParameters, options?: PresentToolOptions): {
+  display?: "standalone";
+  type: "frontend";
+  description: string;
+  parameters: JSONSchema7;
+};
+/**
+ * The schema-only half of the `prompt_user` tool, shared by both builds. The
+ * server build returns exactly this; the client build adds `render`.
+ */
+declare function promptUserToolBase(parameters: PresentParameters): {
+  type: "human";
+  description: string;
+  parameters: JSONSchema7;
+};
+//#endregion
+export { JSONGenerativeUIOptions, PresentParameters, PresentTool, PresentToolOptions, PromptUserTool, presentToolBase, promptUserToolBase };
+//# sourceMappingURL=JSONGenerativeUI.shared.d.ts.map

package/dist/JSONGenerativeUI.shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"JSONGenerativeUI.shared.d.ts","names":[],"sources":["../src/JSONGenerativeUI.shared.ts"],"mappings":";;;;;;KAKY,uBAAA;EAAA;;;;AAMkB;EAA5B,OAAA,EAAS,mBAAmB;AAAA;;KAIlB,kBAAA;EAOH;AAIT;;;;;EAJE,OAAO;AAAA;;KAIG,WAAA,GAAc,cAAA,CACxB,MAAA,mBACA,MAAA;;KAIU,cAAA,GAAiB,cAAc,CAAC,MAAA;;KAYhC,iBAAA,GAAoB,WAAW;AAZ3C;;;;AAAkD;AAAlD,iBAmBgB,eAAA,CACd,UAAA,EAAY,iBAAA,EACZ,OAAA,GAAU,kBAAA;;;;;;;;;;iBAcI,kBAAA,CAAmB,UAAA,EAAY,iBAAA;;;cAAA,WAAA;AAAA"}

package/dist/JSONGenerativeUI.shared.js

@@ -0,0 +1,31 @@
+//#region src/JSONGenerativeUI.shared.ts
+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 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.
+*/
+function presentToolBase(parameters, options) {
+	return {
+		type: "frontend",
+		description: PRESENT_DESCRIPTION,
+		parameters,
+		...options?.display !== void 0 ? { 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`.
+*/
+function promptUserToolBase(parameters) {
+	return {
+		type: "human",
+		description: PROMPT_USER_DESCRIPTION,
+		parameters
+	};
+}
+//#endregion
+export { presentToolBase, promptUserToolBase };
+
+//# sourceMappingURL=JSONGenerativeUI.shared.js.map

package/dist/JSONGenerativeUI.shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"JSONGenerativeUI.shared.js","names":[],"sources":["../src/JSONGenerativeUI.shared.ts"],"sourcesContent":["import type { ToolDefinition } from \"@assistant-ui/react\";\nimport type { JSONSchema7 } from \"json-schema\";\nimport type { GenerativeUILibrary } from \"./types\";\n\n/** Options for {@link JSONGenerativeUI}. */\nexport type JSONGenerativeUIOptions = {\n  /**\n   * The components the model is allowed to render, keyed by the `$type` it\n   * selects them with. Author it with `defineGenerativeComponents({ ... })` so a\n   * `\"use generative\"` build can split each `render` from its `properties`.\n   */\n  library: GenerativeUILibrary;\n};\n\n/** Options for {@link JSONGenerativeUI.present}. */\nexport type PresentToolOptions = {\n  /**\n   * Set `\"standalone\"` to render the component on its own surface (outside the\n   * chain-of-thought trace), e.g. a full-bleed artifact like a card. Omit it for\n   * the default inline rendering — there is no `\"inline\"` value because that is\n   * already the default.\n   */\n  display?: \"standalone\";\n};\n\n/** The `present` tool, as the model sees it (no client `render`/`execute`). */\nexport type PresentTool = ToolDefinition<\n  Record<string, unknown>,\n  Record<string, never>\n>;\n\n/** The `prompt_user` tool, as the model sees it (no client `render`). */\nexport type PromptUserTool = ToolDefinition<Record<string, unknown>, unknown>;\n\nconst PRESENT_DESCRIPTION =\n  \"Present a UI component to the user. Select a component with `$type` and \" +\n  \"provide its props inline; nest components with `children`.\";\n\nconst PROMPT_USER_DESCRIPTION =\n  \"Present a UI component to the user and wait for their response. Select a \" +\n  \"component with `$type` and provide its props inline; nest components with \" +\n  \"`children`. The user interacts with it and the result is returned to you.\";\n\n/** The tool `parameters` schema, built once per instance (see `buildPresentParameters`). */\nexport type PresentParameters = JSONSchema7;\n\n/**\n * The schema-only half of the `present` tool, shared by both builds. The server\n * build returns exactly this; the client build adds `execute` and `render`.\n * Takes the already-built `parameters` so it isn't recomputed per tool.\n */\nexport function presentToolBase(\n  parameters: PresentParameters,\n  options?: PresentToolOptions,\n) {\n  return {\n    type: \"frontend\" as const,\n    description: PRESENT_DESCRIPTION,\n    parameters,\n    ...(options?.display !== undefined ? { display: options.display } : {}),\n  };\n}\n\n/**\n * The schema-only half of the `prompt_user` tool, shared by both builds. The\n * server build returns exactly this; the client build adds `render`.\n */\nexport function promptUserToolBase(parameters: PresentParameters) {\n  return {\n    type: \"human\" as const,\n    description: PROMPT_USER_DESCRIPTION,\n    parameters,\n  };\n}\n"],"mappings":";AAkCA,MAAM,sBACJ;AAGF,MAAM,0BACJ;;;;;;AAYF,SAAgB,gBACd,YACA,SACA;CACA,OAAO;EACL,MAAM;EACN,aAAa;EACb;EACA,GAAI,SAAS,YAAY,KAAA,IAAY,EAAE,SAAS,QAAQ,QAAQ,IAAI,CAAC;CACvE;AACF;;;;;AAMA,SAAgB,mBAAmB,YAA+B;CAChE,OAAO;EACL,MAAM;EACN,aAAa;EACb;CACF;AACF"}

package/dist/buildPresentParameters.d.ts

@@ -0,0 +1,24 @@
+import { JSONSchema7 } from "./node_modules/.pnpm/@types_json-schema@7.0.15/node_modules/@types/json-schema/index.js";
+import { GenerativeUILibrary } from "./types.js";
+
+//#region src/buildPresentParameters.d.ts
+/**
+ * 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.
+ */
+declare function buildPresentParameters(library: GenerativeUILibrary): JSONSchema7;
+//#endregion
+export { buildPresentParameters };
+//# sourceMappingURL=buildPresentParameters.d.ts.map

package/dist/buildPresentParameters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildPresentParameters.d.ts","names":[],"sources":["../src/buildPresentParameters.ts"],"mappings":";;;;;;AAqBA;;;;;;;;AAEc;;;;;;iBAFE,sBAAA,CACd,OAAA,EAAS,mBAAA,GACR,WAAW"}

package/dist/buildPresentParameters.js

@@ -0,0 +1,68 @@
+import { TYPE_KEY } from "./constants.js";
+import { toJSONSchema } from "assistant-stream";
+//#region src/buildPresentParameters.ts
+/**
+* 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.
+*/
+function buildPresentParameters(library) {
+	const names = Object.keys(library);
+	const props = {};
+	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 === "children") continue;
+			if (!(key in props)) props[key] = schema;
+			else if (process.env["NODE_ENV"] !== "production") 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.`);
+		}
+	}
+	const typeDescription = names.length > 0 ? `The component to render. ${names.map((name) => `"${name}": ${library[name].description}`).join("; ")}` : "The component to render.";
+	const node = {
+		type: "object",
+		properties: {
+			[TYPE_KEY]: {
+				type: "string",
+				enum: names,
+				description: typeDescription
+			},
+			...props,
+			children: { $ref: "#/$defs/children" }
+		},
+		required: [TYPE_KEY]
+	};
+	const children = {
+		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
+		}
+	};
+}
+//#endregion
+export { buildPresentParameters };
+
+//# sourceMappingURL=buildPresentParameters.js.map

package/dist/buildPresentParameters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildPresentParameters.js","names":[],"sources":["../src/buildPresentParameters.ts"],"sourcesContent":["import { toJSONSchema } from \"assistant-stream\";\nimport type { JSONSchema7, JSONSchema7Definition } from \"json-schema\";\nimport { TYPE_KEY } from \"./constants\";\nimport type { GenerativeUILibrary } from \"./types\";\n\n/**\n * Builds the JSON schema for the `present` tool from a {@link GenerativeUILibrary}.\n *\n * The model produces a node `{ $type, ...props }` where `$type` selects a\n * component and the rest are its props. The schema is a flat object: `$type` is\n * an enum of the component names, every component's props are merged into one\n * optional bag, and `children` recurses via `$defs` so the tree can nest.\n *\n * It is intentionally flat rather than a per-`$type` discriminated union. Tool /\n * function-call schemas (OpenAI and others) require the top-level parameters to\n * be a plain object and reject a top-level `oneOf`/`anyOf`/`enum`. So props can't\n * be refined per `$type` at the root; the model is guided instead by `$type`'s\n * description (which lists each component) and each prop's own description. The\n * renderer validates nothing here — an unknown `$type` or stray prop is handled\n * at render time — so a looser schema only costs the model a hint, not safety.\n */\nexport function buildPresentParameters(\n  library: GenerativeUILibrary,\n): JSONSchema7 {\n  const names = Object.keys(library);\n\n  // Merge every component's props into one optional bag. `$type`/`children` are\n  // framework-reserved, so drop any author-declared copies. On a name clash the\n  // first component's schema wins — props are an advisory hint here, not a\n  // strict per-component contract.\n  const props: Record<string, JSONSchema7Definition> = {};\n  for (const name of names) {\n    const propsSchema = toJSONSchema(library[name]!.properties);\n    if (propsSchema.type !== \"object\") {\n      throw new Error(\n        `[@assistant-ui/react-generative-ui] Component \"${name}\": ` +\n          \"`properties` must be an object schema (e.g. `z.object({ ... })`).\",\n      );\n    }\n    for (const [key, schema] of Object.entries(propsSchema.properties ?? {})) {\n      if (key === TYPE_KEY || key === \"children\") continue;\n      if (!(key in props)) {\n        props[key] = schema;\n      } else if (process.env[\"NODE_ENV\"] !== \"production\") {\n        // eslint-disable-next-line no-console\n        console.warn(\n          `[@assistant-ui/react-generative-ui] Prop \"${key}\" is declared by more ` +\n            \"than one component; the first component's schema is kept and the rest \" +\n            \"are ignored. Rename or align the type to avoid an ambiguous schema.\",\n        );\n      }\n    }\n  }\n\n  // Carry each component's description on the `$type` enum, since there are no\n  // per-branch schemas to hang them on anymore.\n  const typeDescription =\n    names.length > 0\n      ? `The component to render. ${names\n          .map((name) => `\"${name}\": ${library[name]!.description}`)\n          .join(\"; \")}`\n      : \"The component to render.\";\n\n  const node: JSONSchema7 = {\n    type: \"object\",\n    properties: {\n      [TYPE_KEY]: { type: \"string\", enum: names, description: typeDescription },\n      ...props,\n      children: { $ref: \"#/$defs/children\" },\n    },\n    required: [TYPE_KEY],\n  };\n\n  const children: JSONSchema7 = {\n    description: \"Nested generative UI rendered inside this component.\",\n    anyOf: [\n      { type: \"string\" },\n      { $ref: \"#/$defs/node\" },\n      {\n        type: \"array\",\n        items: { anyOf: [{ type: \"string\" }, { $ref: \"#/$defs/node\" }] },\n      },\n    ],\n  };\n\n  return {\n    ...node,\n    $defs: { node, children },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,uBACd,SACa;CACb,MAAM,QAAQ,OAAO,KAAK,OAAO;CAMjC,MAAM,QAA+C,CAAC;CACtD,KAAK,MAAM,QAAQ,OAAO;EACxB,MAAM,cAAc,aAAa,QAAQ,MAAO,UAAU;EAC1D,IAAI,YAAY,SAAS,UACvB,MAAM,IAAI,MACR,kDAAkD,KAAK,yEAEzD;EAEF,KAAK,MAAM,CAAC,KAAK,WAAW,OAAO,QAAQ,YAAY,cAAc,CAAC,CAAC,GAAG;GACxE,IAAI,QAAA,WAAoB,QAAQ,YAAY;GAC5C,IAAI,EAAE,OAAO,QACX,MAAM,OAAO;QACR,IAAI,QAAQ,IAAI,gBAAgB,cAErC,QAAQ,KACN,6CAA6C,IAAI,gKAGnD;EAEJ;CACF;CAIA,MAAM,kBACJ,MAAM,SAAS,IACX,4BAA4B,MACzB,KAAK,SAAS,IAAI,KAAK,KAAK,QAAQ,MAAO,aAAa,EACxD,KAAK,IAAI,MACZ;CAEN,MAAM,OAAoB;EACxB,MAAM;EACN,YAAY;IACT,WAAW;IAAE,MAAM;IAAU,MAAM;IAAO,aAAa;GAAgB;GACxE,GAAG;GACH,UAAU,EAAE,MAAM,mBAAmB;EACvC;EACA,UAAU,CAAC,QAAQ;CACrB;CAEA,MAAM,WAAwB;EAC5B,aAAa;EACb,OAAO;GACL,EAAE,MAAM,SAAS;GACjB,EAAE,MAAM,eAAe;GACvB;IACE,MAAM;IACN,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,SAAS,GAAG,EAAE,MAAM,eAAe,CAAC,EAAE;GACjE;EACF;CACF;CAEA,OAAO;EACL,GAAG;EACH,OAAO;GAAE;GAAM;EAAS;CAC1B;AACF"}

package/dist/constants.d.ts

@@ -0,0 +1,14 @@
+//#region src/constants.d.ts
+/**
+ * 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.
+ */
+declare const TYPE_KEY = "$type";
+//#endregion
+export { TYPE_KEY };
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","names":[],"sources":["../src/constants.ts"],"mappings":";;AASA;;;;AAAqB;;;;cAAR,QAAA"}

package/dist/constants.js

@@ -0,0 +1,15 @@
+//#region src/constants.ts
+/**
+* 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.
+*/
+const TYPE_KEY = "$type";
+//#endregion
+export { TYPE_KEY };
+
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","names":[],"sources":["../src/constants.ts"],"sourcesContent":["/**\n * The wire key naming the component to render.\n *\n * The model emits nodes as flat objects `{ [TYPE_KEY]: name, ...props }`. We\n * use `$type` rather than `type` so a component's own `type` prop (e.g. a\n * button's `type=\"submit\"`) flows through as an ordinary prop without\n * colliding with the discriminator. It mirrors the `$type` discriminator\n * convention used by JSON polymorphism elsewhere.\n */\nexport const TYPE_KEY = \"$type\";\n"],"mappings":";;;;;;;;;;AASA,MAAa,WAAW"}

package/dist/defineGenerativeComponents.d.ts

@@ -0,0 +1,33 @@
+import { GenerativeUILibrary } from "./types.js";
+
+//#region src/defineGenerativeComponents.d.ts
+/**
+ * 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.
+ */
+declare function defineGenerativeComponents(_library: GenerativeUILibrary): GenerativeUILibrary;
+//#endregion
+export { defineGenerativeComponents };
+//# sourceMappingURL=defineGenerativeComponents.d.ts.map

package/dist/defineGenerativeComponents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineGenerativeComponents.d.ts","names":[],"sources":["../src/defineGenerativeComponents.ts"],"mappings":";;;;;AA4BA;;;;;;;;AAEsB;;;;;;;;;;;;;;;;iBAFN,0BAAA,CACd,QAAA,EAAU,mBAAA,GACT,mBAAmB"}

package/dist/defineGenerativeComponents.js

@@ -0,0 +1,34 @@
+//#region src/defineGenerativeComponents.ts
+/**
+* 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.
+*/
+function defineGenerativeComponents(_library) {
+	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.");
+}
+//#endregion
+export { defineGenerativeComponents };
+
+//# sourceMappingURL=defineGenerativeComponents.js.map

package/dist/defineGenerativeComponents.js.map

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