@assistant-ui/react-generative-ui 0.0.6 → 0.0.8

package/src/ir.ts

@@ -0,0 +1,279 @@
+/**
+ * The generative-ui intermediate representation: a model-emitted, cross-platform
+ * UI tree. React-free, so converters and non-web runtimes consume it without
+ * pulling React. The flat `$type` shape is the canonical form; the legacy
+ * `component` shape is accepted as a backward-compatible alias.
+ *
+ * Reserved keys are partitioned off from component props so the component prop
+ * namespace stays fully free:
+ *
+ * - `$`-prefixed keys are framework-reserved (`$type`, `$key`, `$action`,
+ *   `$status`). Components never declare `$`-prefixed props, so a component
+ *   can use `type`, `status`, `variant`, etc. as ordinary props without
+ *   colliding with the framework.
+ * - `children` is additionally reserved (the JSX convention).
+ * - every other key is an inline prop passed straight to the component.
+ */
+
+import { TYPE_KEY } from "./constants";
+
+export const TEXT_SIZES = ["sm", "md", "lg", "xl", "2xl", "3xl"] as const;
+export type TextSize = (typeof TEXT_SIZES)[number];
+
+export const IMAGE_SIZE_TOKENS = ["sm", "md", "lg"] as const;
+export type ImageSize = (typeof IMAGE_SIZE_TOKENS)[number] | number;
+
+export const WEIGHTS = ["normal", "medium", "semibold", "bold"] as const;
+export type Weight = (typeof WEIGHTS)[number];
+
+export const COLORS = [
+  "emphasis",
+  "secondary",
+  "alpha-70",
+  "white",
+  "white-70",
+  "white-50",
+] as const;
+export type Color = (typeof COLORS)[number];
+
+export const ALIGNS = ["start", "center", "end"] as const;
+export type Align = (typeof ALIGNS)[number];
+
+export const JUSTIFIES = ["start", "center", "end", "between"] as const;
+export type Justify = (typeof JUSTIFIES)[number];
+
+export const BUTTON_STYLES = [
+  "primary",
+  "secondary",
+  "outline",
+  "ghost",
+  "danger",
+] as const;
+export type ButtonStyle = (typeof BUTTON_STYLES)[number];
+
+export const ALERT_TONES = ["info", "success", "warning", "danger"] as const;
+/** A severity level, from informational to destructive. */
+export type AlertTone = (typeof ALERT_TONES)[number];
+
+export const ICON_NAMES = [
+  "sun",
+  "moon",
+  "cloud",
+  "rain",
+  "snow",
+  "wind",
+  "play",
+  "pause",
+  "check",
+  "x",
+  "star",
+  "heart",
+  "arrow-right",
+  "arrow-up-right",
+  "chevron-right",
+  "calendar",
+  "clock",
+  "map-pin",
+  "plane",
+  "truck",
+  "credit-card",
+  "user",
+  "search",
+  "bell",
+] as const;
+/** A name from the built-in icon set; the closed enum lets the model see exactly which icons exist. */
+export type IconName = (typeof ICON_NAMES)[number];
+
+/**
+ * Behavior payload carried by an interactive node. `type` is resolved by the host's action registry, not the renderer; keeping behavior as data keeps the tree serializable, so the same node renders on web while converters may bind the type to a native action id on other platforms.
+ */
+export interface Action {
+  readonly type: string;
+  readonly [payload: string]: unknown;
+}
+
+/**
+ * Anything renderable as generative UI, as the model emits it. The renderer
+ * also accepts `number`, `boolean`, `null`, `undefined`, and arrays at the
+ * input boundary (numbers render as text, falsy/boolean as nothing, arrays as
+ * lists); {@link normalizeUINode} accepts that full range.
+ */
+export type UINode = string | number | UIElement | LegacyComponentNode;
+
+export type UIChildren = UINode | readonly UINode[];
+
+/** The flat node shape: inline props keep the tree compact and natural for a
+ * model to emit, instead of a nested `{ type, props }` bag. Reserved keys are
+ * stripped before props reach the component (see the module header). */
+export interface UIElement {
+  readonly $type: string;
+  readonly $key?: string | number;
+  readonly children?: UIChildren;
+  readonly $action?: Action;
+  readonly [prop: string]: unknown;
+}
+
+/**
+ * The legacy node shape: a `component` name plus a nested `props` bag. Kept
+ * for backward compatibility. New code authors the flat {@link UIElement}
+ * shape instead.
+ */
+export interface LegacyComponentNode {
+  readonly component: string;
+  readonly props?: Record<string, unknown>;
+  readonly children?: UIChildren;
+  readonly key?: string;
+}
+
+export type UISpec = UINode | readonly UINode[];
+
+/**
+ * A node normalized to a single canonical shape: a `type` string, an inline
+ * `props` bag, recursive `children`, an optional `key`, and an optional
+ * `action`. Renderers and platform converters consume this form, so they never
+ * branch on whether the model emitted the flat `$type` shape or the legacy
+ * `component` shape, and they never see the reserved `$`-prefixed keys leak
+ * into component props.
+ */
+export interface NormalizedUIElement {
+  readonly type: string;
+  readonly props: Readonly<Record<string, unknown>>;
+  readonly children?: NormalizedUINode | undefined;
+  readonly key?: string | number | undefined;
+  readonly action?: Action | undefined;
+}
+
+export type NormalizedUINode =
+  | string
+  | number
+  | readonly NormalizedUINode[]
+  | NormalizedUIElement
+  | null;
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+type LegacyNodeRecord = { component: string } & Record<string, unknown>;
+
+const isLegacyNode = (
+  node: Record<string, unknown>,
+): node is LegacyNodeRecord => typeof node["component"] === "string";
+
+const isTypeNode = (node: Record<string, unknown>): node is UIElement =>
+  typeof node[TYPE_KEY] === "string";
+
+/** Bounds recursion so a runaway or adversarial model response cannot overflow
+ * the stack; past this depth (far beyond any real UI) we stop. */
+const MAX_DEPTH = 64;
+
+/**
+ * Steps a streaming partial path down into `key`. `partialPath` is the remaining
+ * segment of the parse meta's partial path relative to `node` (`undefined` once
+ * the walk leaves the partial frontier, i.e. everything below is complete).
+ */
+function descend(
+  partialPath: readonly string[] | undefined,
+  key: string,
+): readonly string[] | undefined {
+  return partialPath?.[0] === key ? partialPath.slice(1) : undefined;
+}
+
+/**
+ * Normalizes a generative-ui input to {@link NormalizedUINode}. The flat
+ * `$type` shape and the legacy `component` shape both map to the same canonical
+ * element, with reserved keys (`$type`, `$key`, `$action`, `children`) stripped
+ * from the prop bag. A node that carries neither a `$type` nor a `component`
+ * string is not renderable and resolves to `null` rather than throwing, so a
+ * partially-streamed or malformed node degrades to "render nothing".
+ *
+ * `partialPath` carries streaming state from the tool-args parse meta: a node
+ * whose `$type` is still mid-arrival is held back (resolves to `null`) until it
+ * completes, and the path is threaded into `children` so a nested streaming
+ * node is held back while completed siblings render. Omit it for a
+ * non-streaming (converter) normalize.
+ */
+export function normalizeUINode(
+  node: unknown,
+  partialPath?: readonly string[] | undefined,
+  depth = 0,
+): NormalizedUINode {
+  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, index) =>
+      normalizeUINode(child, descend(partialPath, String(index)), depth + 1),
+    );
+  if (!isRecord(node)) return null;
+
+  // The flat `$type` shape is the canonical form; detect it first so a flat
+  // node that happens to use `component` as an ordinary prop is not swallowed
+  // by the legacy `component`-shape branch.
+  if (isTypeNode(node)) {
+    if (partialPath?.length === 1 && partialPath[0] === TYPE_KEY) return null;
+    const { [TYPE_KEY]: type, $key, $action, children, ...rest } = node;
+    // The `$`-prefixed namespace is framework-reserved (see the module header),
+    // so any model-supplied `$`-prefixed key is stripped from the prop bag the
+    // component sees. `$type`/`$key`/`$action` are pulled above; sweep the rest
+    // (e.g. a stray `$status`) so it never leaks to converters or components.
+    const props = stripReservedProps(rest);
+    return {
+      type,
+      props,
+      children: normalizeChildren(children, partialPath, depth),
+      key: $key,
+      action: $action,
+    };
+  }
+
+  if (isLegacyNode(node)) {
+    const props = stripReservedProps(
+      (node.props ?? {}) as Record<string, unknown>,
+    );
+    return {
+      type: node.component,
+      props,
+      children: normalizeChildren(node.children, partialPath, depth),
+      key: node.key as string | undefined,
+    };
+  }
+
+  return null;
+}
+
+function stripReservedProps(
+  props: Record<string, unknown>,
+): Record<string, unknown> {
+  let out: Record<string, unknown> | undefined;
+  for (const key of Object.keys(props)) {
+    if (key.startsWith("$")) {
+      out ??= { ...props };
+      delete out[key];
+    }
+  }
+  return out ?? props;
+}
+
+function normalizeChildren(
+  children: unknown,
+  partialPath: readonly string[] | undefined,
+  depth: number,
+): NormalizedUINode | undefined {
+  if (children === undefined) return undefined;
+  return normalizeUINode(children, descend(partialPath, "children"), depth + 1);
+}
+
+/**
+ * Normalizes the root of a {@link UISpec}, preserving whether the root was a
+ * single node or a list.
+ */
+export function normalizeSpec(spec: UISpec): {
+  readonly root: NormalizedUINode | readonly NormalizedUINode[];
+} {
+  if (Array.isArray(spec)) {
+    return {
+      root: (spec as readonly UINode[]).map((node) => normalizeUINode(node)),
+    };
+  }
+  return { root: normalizeUINode(spec) };
+}

package/src/renderGenerativeUI.test.tsx

@@ -1,5 +1,6 @@
 import { describe, it, expect, vi } from "vitest";
 import { renderToStaticMarkup } from "react-dom/server";
+import { isValidElement, type ReactElement } from "react";
 import { parsePartialJsonObject } from "assistant-stream/utils";
 import { z } from "zod";
 import { renderGenerativeUI } from "./renderGenerativeUI";
@@ -65,6 +66,28 @@ describe("renderGenerativeUI", () => {
     );
   });
 
+  it("uses stable $key for array items and keeps the positional fallback", () => {
+    const out = renderGenerativeUI(
+      [
+        { $type: "Text", $key: "1:Text", children: "first" },
+        { $type: "Text", children: "second" },
+        "plain",
+        { $type: "Text", $key: { id: "bad" }, children: "bad key" },
+      ],
+      library,
+    );
+
+    expect(Array.isArray(out)).toBe(true);
+    const elements = out as ReactElement[];
+    expect(elements.every(isValidElement)).toBe(true);
+    expect(elements.map((element) => element.key)).toEqual([
+      "model:1:Text",
+      "1:Text",
+      "2:#text",
+      "3:Text",
+    ]);
+  });
+
   it("passes a component's own `type` prop through without collision", () => {
     const html = renderToStaticMarkup(
       <>
@@ -189,6 +212,11 @@ describe("buildPresentParameters", () => {
     ]);
     // each component's description rides along on the $type enum.
     expect(schema.properties.$type.description).toContain("Card");
+    expect(schema.properties.$key).toEqual({
+      description:
+        "Stable identity for this UI node. Use it for list items that may reorder.",
+      anyOf: [{ type: "string" }, { type: "number" }],
+    });
     expect(schema.properties.children.$ref).toBe("#/$defs/children");
 
     // every component's props are merged into the one flat property bag.
@@ -205,12 +233,14 @@ describe("buildPresentParameters", () => {
     expect(schema.$defs.node.oneOf).toBeUndefined();
   });
 
-  it("drops author-declared `$type`/`children` and keeps the discriminator", () => {
+  it("drops author-declared `$`-prefixed and `children` props, keeping framework fields", () => {
     const schema = buildPresentParameters({
       Reserved: {
         description: "Declares reserved keys that must not leak through.",
         properties: z.object({
           $type: z.number(),
+          $key: z.boolean(),
+          $action: z.string(),
           children: z.number(),
           label: z.string(),
         }),
@@ -219,13 +249,50 @@ describe("buildPresentParameters", () => {
     }) 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).
+    // author's `$`-prefixed props and `children` are dropped in favor of the
+    // framework fields.
     expect(schema.properties.$type.enum).toEqual(["Reserved"]);
+    expect(schema.properties.$key).toEqual({
+      description:
+        "Stable identity for this UI node. Use it for list items that may reorder.",
+      anyOf: [{ type: "string" }, { type: "number" }],
+    });
+    expect(schema.properties.$action).toBeUndefined();
     expect(schema.properties.children.$ref).toBe("#/$defs/children");
     expect(schema.properties.label).toBeDefined();
     expect(schema.required).toEqual(["$type"]);
   });
 
+  it("names every component that declares the same prop in the dev warning", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      buildPresentParameters({
+        Select: {
+          description: "Selects an option.",
+          properties: z.object({ value: z.string() }),
+          render: () => null,
+        },
+        DatePicker: {
+          description: "Picks a date.",
+          properties: z.object({ value: z.string() }),
+          render: () => null,
+        },
+        Combobox: {
+          description: "Chooses from filtered options.",
+          properties: z.object({ value: z.string() }),
+          render: () => null,
+        },
+      });
+
+      expect(warn).toHaveBeenCalledTimes(1);
+      expect(warn).toHaveBeenCalledWith(
+        '[@assistant-ui/react-generative-ui] Prop "value" is declared by "Select", "DatePicker", and "Combobox"; keeping "Select"\'s schema. Rename or align the prop type to avoid an ambiguous schema.',
+      );
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
   it("throws when a component's properties is not an object schema", () => {
     expect(() =>
       buildPresentParameters({

package/src/renderGenerativeUI.tsx

@@ -1,23 +1,26 @@
 import { getPartialJsonObjectMeta } from "assistant-stream/utils";
 import { Fragment, type ReactNode } from "react";
-import { TYPE_KEY } from "./constants";
-import type {
-  GenerativeUIElement,
-  GenerativeUILibrary,
-  GenerativeUINode,
-  GenerativeUIRenderContext,
-} from "./types";
+import {
+  normalizeUINode,
+  type NormalizedUIElement,
+  type NormalizedUINode,
+} from "./ir";
+import type { GenerativeUILibrary, GenerativeUIRenderContext } from "./types";
 
 const DEFAULT_CONTEXT: GenerativeUIRenderContext = { status: "done" };
 
+const isElement = (node: NormalizedUINode): node is NormalizedUIElement =>
+  typeof node === "object" && node !== null && !Array.isArray(node);
+
 /**
  * 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.
+ * normalize that wire form into the canonical {@link NormalizedUINode} (with
+ * `children` lifted to a reserved top-level key), 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,
@@ -29,87 +32,32 @@ export function renderGenerativeUI(
   // string has not finished streaming.
   const meta = getPartialJsonObjectMeta(node as Record<symbol, unknown>);
   const partialPath = meta?.state === "partial" ? meta.partialPath : undefined;
-  return renderNode(normalizeNode(node, partialPath), 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}.
- *
- * `partialPath` is the remaining segment of the parse meta's partial path
- * relative to `node` (`undefined` once the walk leaves the partial frontier,
- * i.e. everything below is complete).
- */
-function normalizeNode(
-  node: unknown,
-  partialPath: readonly string[] | undefined,
-  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, index) =>
-      normalizeNode(child, descend(partialPath, String(index)), 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
-  // (or whose `$type` string is still mid-arrival) is not an error, it just
-  // isn't renderable.
-  if (typeof type !== "string") return null;
-  if (partialPath?.length === 1 && partialPath[0] === TYPE_KEY) return null;
-
-  if ("children" in props) {
-    props["children"] = normalizeNode(
-      props["children"],
-      descend(partialPath, "children"),
-      depth + 1,
-    );
-  }
-  return { type, props } as GenerativeUIElement;
-}
-
-/** Steps the partial path down into `key`; siblings of the path are complete. */
-function descend(
-  partialPath: readonly string[] | undefined,
-  key: string,
-): readonly string[] | undefined {
-  return partialPath?.[0] === key ? partialPath.slice(1) : undefined;
+  return renderNode(normalizeUINode(node, partialPath), library, context);
 }
 
 function renderNode(
-  node: GenerativeUINode,
+  node: NormalizedUINode,
   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.
+    // Use a model-provided stable key when present. Otherwise, keep the
+    // positional fallback: pairing the index with the node's kind means that
+    // when the kind at an index changes, 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)}`}>
+      <Fragment key={nodeKey(child, index)}>
         {renderNode(child, library, context)}
       </Fragment>
     ));
   }
-  return renderElement(node, library, context);
+  return isElement(node) ? renderElement(node, library, context) : null;
 }
 
 function renderElement(
-  element: GenerativeUIElement,
+  element: NormalizedUIElement,
   library: GenerativeUILibrary,
   context: GenerativeUIRenderContext,
 ): ReactNode {
@@ -123,11 +71,23 @@ function renderElement(
   // 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);
+  // `children` is a reserved top-level key on the normalized element, not a
+  // prop, so it is not in `props`. Inject the framework props last so the model
+  // can never override them. `$action` is likewise reserved and stripped from
+  // the prop bag during normalization, so it is re-injected here for components
+  // that carry behavior (e.g. `Button`).
+  const props: Record<string, unknown> = {
+    ...element.props,
+    $status: context.status,
+  };
+  if (context.dispatch !== undefined) {
+    props["$dispatch"] = context.dispatch;
+  }
+  if (element.action !== undefined) {
+    props["$action"] = element.action;
+  }
+  if (element.children !== undefined) {
+    props["children"] = renderNode(element.children, library, context);
   }
 
   return <GenerativeUIComponentRenderer render={entry.render} props={props} />;
@@ -149,11 +109,18 @@ function GenerativeUIComponentRenderer({
 
 /** 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 {
+function nodeKind(node: NormalizedUINode): 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;
+  return isElement(node) ? node.type : "";
+}
+
+function nodeKey(node: NormalizedUINode, index: number): string {
+  return isElement(node) &&
+    (typeof node.key === "string" || typeof node.key === "number")
+    ? `model:${node.key}`
+    : `${index}:${nodeKind(node)}`;
 }
 
 function reportUnknownComponent(type: string, available: string[]): void {