@assistant-ui/react-generative-ui 0.0.2

package/src/renderGenerativeUI.test.tsx

@@ -0,0 +1,204 @@
+import { describe, it, expect } from "vitest";
+import { renderToStaticMarkup } from "react-dom/server";
+import { z } from "zod";
+import { renderGenerativeUI } from "./renderGenerativeUI";
+import { buildPresentParameters } from "./buildPresentParameters";
+import type { GenerativeUILibrary } from "./types";
+
+const library: GenerativeUILibrary = {
+  Card: {
+    description: "A card container.",
+    properties: z.object({ title: z.string() }),
+    render: ({ title, children }: any) => (
+      <section data-title={title}>{children}</section>
+    ),
+  },
+  Text: {
+    description: "A run of text.",
+    properties: z.object({ tone: z.enum(["muted", "normal"]).optional() }),
+    render: ({ tone, children }: any) => <p data-tone={tone}>{children}</p>,
+  },
+  Button: {
+    description: "A button with its own `type` prop.",
+    properties: z.object({ type: z.enum(["button", "submit"]) }),
+    render: ({ type, children }: any) => (
+      <button type={type}>{children}</button>
+    ),
+  },
+  Live: {
+    description: "Renders from partial props while streaming.",
+    properties: z.object({ label: z.string() }),
+    streamProperties: true,
+    render: (props) => (
+      <span data-status={props.$status}>{props.label ?? "…"}</span>
+    ),
+  },
+};
+
+describe("renderGenerativeUI", () => {
+  it("renders a component and passes its props", () => {
+    const html = renderToStaticMarkup(
+      <>{renderGenerativeUI({ $type: "Text", tone: "muted" }, library)}</>,
+    );
+    expect(html).toBe('<p data-tone="muted"></p>');
+  });
+
+  it("renders children recursively", () => {
+    const html = renderToStaticMarkup(
+      <>
+        {renderGenerativeUI(
+          {
+            $type: "Card",
+            title: "Hello",
+            children: [
+              { $type: "Text", children: "first" },
+              { $type: "Text", tone: "muted", children: "second" },
+            ],
+          },
+          library,
+        )}
+      </>,
+    );
+    expect(html).toBe(
+      '<section data-title="Hello"><p>first</p><p data-tone="muted">second</p></section>',
+    );
+  });
+
+  it("passes a component's own `type` prop through without collision", () => {
+    const html = renderToStaticMarkup(
+      <>
+        {renderGenerativeUI(
+          { $type: "Button", type: "submit", children: "Go" },
+          library,
+        )}
+      </>,
+    );
+    expect(html).toBe('<button type="submit">Go</button>');
+  });
+
+  it("renders a string child directly", () => {
+    const html = renderToStaticMarkup(
+      <>{renderGenerativeUI({ $type: "Card", children: "plain" }, library)}</>,
+    );
+    expect(html).toBe("<section><p></p></section>".replace("<p></p>", "plain"));
+  });
+
+  it("renders nothing for an unknown component", () => {
+    const html = renderToStaticMarkup(
+      <>{renderGenerativeUI({ $type: "Missing" }, library)}</>,
+    );
+    expect(html).toBe("");
+  });
+
+  it("renders nothing for a node without a resolved type", () => {
+    const html = renderToStaticMarkup(<>{renderGenerativeUI({}, library)}</>);
+    expect(html).toBe("");
+  });
+
+  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(() =>
+      renderToStaticMarkup(<>{renderGenerativeUI(node, library)}</>),
+    ).not.toThrow();
+  });
+
+  it("passes the status to render and tolerates partial props while streaming", () => {
+    const html = renderToStaticMarkup(
+      <>
+        {renderGenerativeUI({ $type: "Live" }, library, {
+          status: "streaming",
+        })}
+      </>,
+    );
+    expect(html).toBe('<span data-status="streaming">…</span>');
+  });
+
+  it("gates opt-out components until their props are complete", () => {
+    const streaming = renderToStaticMarkup(
+      <>
+        {renderGenerativeUI({ $type: "Card", title: "x" }, library, {
+          status: "streaming",
+        })}
+      </>,
+    );
+    expect(streaming).toBe("");
+
+    const done = renderToStaticMarkup(
+      <>
+        {renderGenerativeUI({ $type: "Card", title: "x" }, library, {
+          status: "done",
+        })}
+      </>,
+    );
+    expect(done).toBe('<section data-title="x"></section>');
+  });
+});
+
+describe("buildPresentParameters", () => {
+  it("produces a flat object schema with no top-level oneOf/anyOf", () => {
+    const schema = buildPresentParameters(library) as any;
+
+    expect(schema.type).toBe("object");
+    expect(schema.required).toEqual(["$type"]);
+    // Tool/function-call schemas reject these at the top level.
+    expect(schema.oneOf).toBeUndefined();
+    expect(schema.anyOf).toBeUndefined();
+
+    expect(schema.properties.$type.enum).toEqual([
+      "Card",
+      "Text",
+      "Button",
+      "Live",
+    ]);
+    // each component's description rides along on the $type enum.
+    expect(schema.properties.$type.description).toContain("Card");
+    expect(schema.properties.children.$ref).toBe("#/$defs/children");
+
+    // every component's props are merged into the one flat property bag.
+    expect(schema.properties.title).toBeDefined(); // Card
+    expect(schema.properties.tone).toBeDefined(); // Text
+    expect(schema.properties.type).toBeDefined(); // Button's own `type` prop
+    expect(schema.properties.label).toBeDefined(); // Live
+
+    // children recurses back into a node.
+    expect(schema.$defs.children.anyOf).toContainEqual({
+      $ref: "#/$defs/node",
+    });
+    expect(schema.$defs.node.type).toBe("object");
+    expect(schema.$defs.node.oneOf).toBeUndefined();
+  });
+
+  it("drops author-declared `$type`/`children` and keeps the discriminator", () => {
+    const schema = buildPresentParameters({
+      Reserved: {
+        description: "Declares reserved keys that must not leak through.",
+        properties: z.object({
+          $type: z.number(),
+          children: z.number(),
+          label: z.string(),
+        }),
+        render: () => null,
+      },
+    }) as any;
+
+    // The discriminator is the framework enum, not the author's `$type`; the
+    // author's `children` is dropped (the root `children` $ref owns that slot).
+    expect(schema.properties.$type.enum).toEqual(["Reserved"]);
+    expect(schema.properties.children.$ref).toBe("#/$defs/children");
+    expect(schema.properties.label).toBeDefined();
+    expect(schema.required).toEqual(["$type"]);
+  });
+
+  it("throws when a component's properties is not an object schema", () => {
+    expect(() =>
+      buildPresentParameters({
+        Bad: {
+          description: "Non-object props.",
+          properties: z.string() as never,
+          render: () => null,
+        },
+      }),
+    ).toThrow(/must be an object schema/);
+  });
+});

package/src/renderGenerativeUI.tsx

@@ -0,0 +1,135 @@
+import { Fragment, type ReactNode } from "react";
+import { TYPE_KEY } from "./constants";
+import type {
+  GenerativeUIElement,
+  GenerativeUILibrary,
+  GenerativeUINode,
+  GenerativeUIRenderContext,
+} from "./types";
+
+const DEFAULT_CONTEXT: GenerativeUIRenderContext = { status: "done" };
+
+/**
+ * Renders a generative-ui tree against a {@link GenerativeUILibrary}.
+ *
+ * The model emits each node as a flat object `{ $type, ...props }`. We first
+ * normalize that wire form into React-shaped elements (`{ type, props }`), then
+ * render: each `type` is looked up in the library and its `props` are passed
+ * to the component's `render(props, context)`, with `children` rendered
+ * recursively so components can nest.
+ */
+export function renderGenerativeUI(
+  node: unknown,
+  library: GenerativeUILibrary,
+  context: GenerativeUIRenderContext = DEFAULT_CONTEXT,
+): ReactNode {
+  return renderNode(normalizeNode(node), library, context);
+}
+
+/**
+ * The deepest tree we normalize. The input comes from the model, so a runaway
+ * or adversarial response could nest arbitrarily deep and overflow the stack;
+ * past this depth we stop (far beyond any real UI). Bounding normalization
+ * bounds rendering too, since it only walks the normalized tree.
+ */
+const MAX_DEPTH = 64;
+
+/** Converts the flat wire form into a normalized {@link GenerativeUINode}. */
+function normalizeNode(node: unknown, depth = 0): GenerativeUINode {
+  if (depth > MAX_DEPTH) return null;
+  if (node == null || typeof node === "boolean") return null;
+  if (typeof node === "string" || typeof node === "number") return node;
+  if (Array.isArray(node))
+    return node.map((child) => normalizeNode(child, depth + 1));
+  if (typeof node !== "object") return null;
+
+  const { [TYPE_KEY]: type, ...props } = node as Record<string, unknown>;
+  // Args stream in incrementally; a node whose `$type` has not arrived yet is
+  // not an error, it just isn't renderable.
+  if (typeof type !== "string") return null;
+
+  if ("children" in props) {
+    props["children"] = normalizeNode(props["children"], depth + 1);
+  }
+  return { type, props } as GenerativeUIElement;
+}
+
+function renderNode(
+  node: GenerativeUINode,
+  library: GenerativeUILibrary,
+  context: GenerativeUIRenderContext,
+): ReactNode {
+  if (node == null || typeof node === "boolean") return null;
+  if (typeof node === "string" || typeof node === "number") return node;
+  if (Array.isArray(node)) {
+    // The wire format has no per-node id, so the key is positional. Pairing the
+    // index with the node's kind means that when the model splices or reorders
+    // `children` and the kind at an index changes, the key changes and React
+    // remounts instead of handing a streaming node's hook state to a different
+    // component.
+    return node.map((child, index) => (
+      <Fragment key={`${index}:${nodeKind(child)}`}>
+        {renderNode(child, library, context)}
+      </Fragment>
+    ));
+  }
+  return renderElement(node, library, context);
+}
+
+function renderElement(
+  element: GenerativeUIElement,
+  library: GenerativeUILibrary,
+  context: GenerativeUIRenderContext,
+): ReactNode {
+  const entry = library[element.type];
+  if (!entry) {
+    reportUnknownComponent(element.type, Object.keys(library));
+    return null;
+  }
+
+  // Components that opt out of prop streaming wait until their props are
+  // complete rather than rendering from a partial parse.
+  if (!entry.streamProperties && context.status === "streaming") return null;
+
+  // Inject the framework props last so the model can never override them.
+  const { children, ...rest } = element.props;
+  const props: Record<string, unknown> = { ...rest, $status: context.status };
+  if (children !== undefined) {
+    props["children"] = renderNode(children, library, context);
+  }
+
+  return <GenerativeUIComponentRenderer render={entry.render} props={props} />;
+}
+
+/**
+ * Mounts a single node's `render` on its own fiber so the function may use
+ * hooks and hold state independently of its siblings and parent.
+ */
+function GenerativeUIComponentRenderer({
+  render,
+  props,
+}: {
+  render: (props: any) => ReactNode;
+  props: Record<string, unknown>;
+}): ReactNode {
+  return render(props);
+}
+
+/** A coarse kind tag for a child, used in its list key so a node changing kind
+ * at a given index forces a remount rather than a wrong-fiber reuse. */
+function nodeKind(node: GenerativeUINode): string {
+  if (node == null || typeof node === "boolean") return "";
+  if (typeof node === "string" || typeof node === "number") return "#text";
+  if (Array.isArray(node)) return "#array";
+  return node.type;
+}
+
+function reportUnknownComponent(type: string, available: string[]): void {
+  if (process.env["NODE_ENV"] !== "production") {
+    // eslint-disable-next-line no-console
+    console.error(
+      `[@assistant-ui/react-generative-ui] Unknown component "${type}". ` +
+        `Available components: ${available.join(", ") || "(none)"}.`,
+    );
+  }
+}

package/src/types.ts

@@ -0,0 +1,104 @@
+import type { ReactNode } from "react";
+import type { ZodType } from "zod";
+
+/** Whether a node's props are still streaming in or have fully arrived. */
+export type GenerativeUIStatus = "streaming" | "done";
+
+/** The render context threaded through {@link renderGenerativeUI}. */
+export type GenerativeUIRenderContext = {
+  /** Whether the tool call's arguments are still streaming or are complete. */
+  status: GenerativeUIStatus;
+};
+
+/**
+ * Props a component's `render` receives: its model props, rendered `children`,
+ * and the injected `$status`. `$status` is the discriminant — when it is
+ * `"done"`, `P` is complete; while `"streaming"`, `P` is partial. It is named
+ * `$status` (not `status`) so it never collides with a real `status` prop, the
+ * same reservation as `$type`.
+ */
+type StreamingRenderProps<P> =
+  | (Partial<P> & { children?: ReactNode; $status: "streaming" })
+  | (P & { children?: ReactNode; $status: "done" });
+
+/** Props for a component that only renders once complete — `$status` is always `"done"`. */
+type StaticRenderProps<P> = P & { children?: ReactNode; $status: "done" };
+
+/**
+ * A component the model is allowed to render, with the schema for its props.
+ *
+ * Components opt into prop streaming with `streamProperties`: they render as
+ * props arrive, so `render` sees `Partial<P>` while `$status` is `"streaming"`
+ * and the full `P` once it is `"done"`. By default a component opts out and is
+ * only rendered once its props are complete.
+ *
+ * `render` is a function of `props`, not a React component. Direct hook use is
+ * fine (each node is mounted on its own fiber), but a given node must keep its
+ * `type` across renders for hook identity to be stable.
+ */
+export type GenerativeUIComponent<P = any> =
+  | {
+      /** Natural-language description shown to the model when selecting the component. */
+      description: string;
+      /** Schema for the props the model must provide. Drives the tool parameters. */
+      properties: ZodType<P>;
+      /**
+       * Render from partially-streamed props. Widened to `boolean | undefined`
+       * so a non-literal value (e.g. a variable) still resolves to this branch
+       * cleanly rather than matching neither; the strict `false | undefined`
+       * branch below is the only one that promises complete props.
+       */
+      streamProperties: boolean | undefined;
+      render: (props: StreamingRenderProps<P>) => ReactNode;
+    }
+  | {
+      description: string;
+      properties: ZodType<P>;
+      /** Render only once props are complete (the default). */
+      streamProperties?: false | undefined;
+      render: (props: StaticRenderProps<P>) => ReactNode;
+    };
+
+/**
+ * The consumer-provided allowlist of components the model is permitted to
+ * render. Keys are the `type` values referenced in the generative-ui tree
+ * (e.g. `"Card"`, `"Button"`); values describe each component.
+ *
+ * This registry is the security boundary — any `type` not present is rejected.
+ */
+export type GenerativeUILibrary = Record<string, GenerativeUIComponent>;
+
+/**
+ * A component invocation — mirrors React's `ReactElement`.
+ *
+ * `type` selects a component from the {@link GenerativeUILibrary}; `props` are
+ * passed to it. The `children` prop is special: it is itself a renderable
+ * {@link GenerativeUINode}, drawn as generative UI rather than passed as data.
+ *
+ * On the wire the model emits the flattened form `{ $type, ...props }`, where
+ * `$type` names the component so a real `type` prop never collides. This is the
+ * normalized shape the renderer works with, the same way React normalizes
+ * `createElement` arguments into an element.
+ */
+export type GenerativeUIElement = {
+  type: string;
+  props: GenerativeUIProps;
+};
+
+/** Props passed to a component — mirrors a React component's props. */
+export type GenerativeUIProps = {
+  children?: GenerativeUINode;
+} & Record<string, unknown>;
+
+/**
+ * Anything renderable as generative UI — mirrors React's `ReactNode`: an
+ * element, primitive text, or a list of nodes.
+ */
+export type GenerativeUINode =
+  | GenerativeUIElement
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | GenerativeUINode[];