@assistant-ui/react-generative-ui 0.0.5 → 0.0.7

package/dist/ir.js

@@ -0,0 +1,149 @@
+import { TYPE_KEY } from "./constants.js";
+//#region src/ir.ts
+/**
+* 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.
+*/
+const TEXT_SIZES = [
+	"sm",
+	"md",
+	"lg",
+	"xl",
+	"2xl",
+	"3xl"
+];
+const IMAGE_SIZE_TOKENS = [
+	"sm",
+	"md",
+	"lg"
+];
+const WEIGHTS = [
+	"normal",
+	"medium",
+	"semibold",
+	"bold"
+];
+const COLORS = [
+	"emphasis",
+	"secondary",
+	"alpha-70",
+	"white",
+	"white-70",
+	"white-50"
+];
+const ALIGNS = [
+	"start",
+	"center",
+	"end"
+];
+const JUSTIFIES = [
+	"start",
+	"center",
+	"end",
+	"between"
+];
+const BUTTON_STYLES = [
+	"primary",
+	"secondary",
+	"outline",
+	"ghost",
+	"danger"
+];
+const ALERT_TONES = [
+	"info",
+	"success",
+	"warning",
+	"danger"
+];
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isLegacyNode = (node) => typeof node["component"] === "string";
+const isTypeNode = (node) => 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, key) {
+	return partialPath?.[0] === key ? partialPath.slice(1) : void 0;
+}
+/**
+* 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.
+*/
+function normalizeUINode(node, partialPath, depth = 0) {
+	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;
+	if (isTypeNode(node)) {
+		if (partialPath?.length === 1 && partialPath[0] === "$type") return null;
+		const { [TYPE_KEY]: type, $key, $action, children, ...rest } = node;
+		return {
+			type,
+			props: stripReservedProps(rest),
+			children: normalizeChildren(children, partialPath, depth),
+			key: $key,
+			action: $action
+		};
+	}
+	if (isLegacyNode(node)) {
+		const props = stripReservedProps(node.props ?? {});
+		return {
+			type: node.component,
+			props,
+			children: normalizeChildren(node.children, partialPath, depth),
+			key: node.key
+		};
+	}
+	return null;
+}
+function stripReservedProps(props) {
+	let out;
+	for (const key of Object.keys(props)) if (key.startsWith("$")) {
+		out ??= { ...props };
+		delete out[key];
+	}
+	return out ?? props;
+}
+function normalizeChildren(children, partialPath, depth) {
+	if (children === void 0) return void 0;
+	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.
+*/
+function normalizeSpec(spec) {
+	if (Array.isArray(spec)) return { root: spec.map((node) => normalizeUINode(node)) };
+	return { root: normalizeUINode(spec) };
+}
+//#endregion
+export { ALERT_TONES, ALIGNS, BUTTON_STYLES, COLORS, IMAGE_SIZE_TOKENS, JUSTIFIES, TEXT_SIZES, WEIGHTS, normalizeSpec, normalizeUINode };
+
+//# sourceMappingURL=ir.js.map

package/dist/ir.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ir.js","names":[],"sources":["../src/ir.ts"],"sourcesContent":["/**\n * The generative-ui intermediate representation: a model-emitted, cross-platform\n * UI tree. React-free, so converters and non-web runtimes consume it without\n * pulling React. The flat `$type` shape is the canonical form; the legacy\n * `component` shape is accepted as a backward-compatible alias.\n *\n * Reserved keys are partitioned off from component props so the component prop\n * namespace stays fully free:\n *\n * - `$`-prefixed keys are framework-reserved (`$type`, `$key`, `$action`,\n *   `$status`). Components never declare `$`-prefixed props, so a component\n *   can use `type`, `status`, `variant`, etc. as ordinary props without\n *   colliding with the framework.\n * - `children` is additionally reserved (the JSX convention).\n * - every other key is an inline prop passed straight to the component.\n */\n\nimport { TYPE_KEY } from \"./constants\";\n\nexport const TEXT_SIZES = [\"sm\", \"md\", \"lg\", \"xl\", \"2xl\", \"3xl\"] as const;\nexport type TextSize = (typeof TEXT_SIZES)[number];\n\nexport const IMAGE_SIZE_TOKENS = [\"sm\", \"md\", \"lg\"] as const;\nexport type ImageSize = (typeof IMAGE_SIZE_TOKENS)[number] | number;\n\nexport const WEIGHTS = [\"normal\", \"medium\", \"semibold\", \"bold\"] as const;\nexport type Weight = (typeof WEIGHTS)[number];\n\nexport const COLORS = [\n  \"emphasis\",\n  \"secondary\",\n  \"alpha-70\",\n  \"white\",\n  \"white-70\",\n  \"white-50\",\n] as const;\nexport type Color = (typeof COLORS)[number];\n\nexport const ALIGNS = [\"start\", \"center\", \"end\"] as const;\nexport type Align = (typeof ALIGNS)[number];\n\nexport const JUSTIFIES = [\"start\", \"center\", \"end\", \"between\"] as const;\nexport type Justify = (typeof JUSTIFIES)[number];\n\nexport const BUTTON_STYLES = [\n  \"primary\",\n  \"secondary\",\n  \"outline\",\n  \"ghost\",\n  \"danger\",\n] as const;\nexport type ButtonStyle = (typeof BUTTON_STYLES)[number];\n\nexport const ALERT_TONES = [\"info\", \"success\", \"warning\", \"danger\"] as const;\n/** Maps to ChatKit `alert` severity levels. */\nexport type AlertTone = (typeof ALERT_TONES)[number];\n\n/**\n * Behavior payload carried by an interactive node. `type` is resolved by the\n * host's action registry, not the renderer; keeping behavior as data keeps the\n * tree serializable so the same node renders on web and converts to a native\n * action id on Slack.\n */\nexport interface Action {\n  readonly type: string;\n  readonly [payload: string]: unknown;\n}\n\n/**\n * Anything renderable as generative UI, as the model emits it. The renderer\n * also accepts `number`, `boolean`, `null`, `undefined`, and arrays at the\n * input boundary (numbers render as text, falsy/boolean as nothing, arrays as\n * lists); {@link normalizeUINode} accepts that full range.\n */\nexport type UINode = string | number | UIElement | LegacyComponentNode;\n\nexport type UIChildren = UINode | readonly UINode[];\n\n/** The flat node shape: inline props keep the tree compact and natural for a\n * model to emit, instead of a nested `{ type, props }` bag. Reserved keys are\n * stripped before props reach the component (see the module header). */\nexport interface UIElement {\n  readonly $type: string;\n  readonly $key?: string | number;\n  readonly children?: UIChildren;\n  readonly $action?: Action;\n  readonly [prop: string]: unknown;\n}\n\n/**\n * The legacy node shape: a `component` name plus a nested `props` bag. Kept\n * for backward compatibility. New code authors the flat {@link UIElement}\n * shape instead.\n */\nexport interface LegacyComponentNode {\n  readonly component: string;\n  readonly props?: Record<string, unknown>;\n  readonly children?: UIChildren;\n  readonly key?: string;\n}\n\nexport type UISpec = UINode | readonly UINode[];\n\n/**\n * A node normalized to a single canonical shape: a `type` string, an inline\n * `props` bag, recursive `children`, an optional `key`, and an optional\n * `action`. Renderers and platform converters consume this form, so they never\n * branch on whether the model emitted the flat `$type` shape or the legacy\n * `component` shape, and they never see the reserved `$`-prefixed keys leak\n * into component props.\n */\nexport interface NormalizedUIElement {\n  readonly type: string;\n  readonly props: Readonly<Record<string, unknown>>;\n  readonly children?: NormalizedUINode | undefined;\n  readonly key?: string | number | undefined;\n  readonly action?: Action | undefined;\n}\n\nexport type NormalizedUINode =\n  | string\n  | number\n  | readonly NormalizedUINode[]\n  | NormalizedUIElement\n  | null;\n\nconst isRecord = (value: unknown): value is Record<string, unknown> =>\n  typeof value === \"object\" && value !== null && !Array.isArray(value);\n\ntype LegacyNodeRecord = { component: string } & Record<string, unknown>;\n\nconst isLegacyNode = (\n  node: Record<string, unknown>,\n): node is LegacyNodeRecord => typeof node[\"component\"] === \"string\";\n\nconst isTypeNode = (node: Record<string, unknown>): node is UIElement =>\n  typeof node[TYPE_KEY] === \"string\";\n\n/** Bounds recursion so a runaway or adversarial model response cannot overflow\n * the stack; past this depth (far beyond any real UI) we stop. */\nconst MAX_DEPTH = 64;\n\n/**\n * Steps a streaming partial path down into `key`. `partialPath` is the remaining\n * segment of the parse meta's partial path relative to `node` (`undefined` once\n * the walk leaves the partial frontier, i.e. everything below is complete).\n */\nfunction descend(\n  partialPath: readonly string[] | undefined,\n  key: string,\n): readonly string[] | undefined {\n  return partialPath?.[0] === key ? partialPath.slice(1) : undefined;\n}\n\n/**\n * Normalizes a generative-ui input to {@link NormalizedUINode}. The flat\n * `$type` shape and the legacy `component` shape both map to the same canonical\n * element, with reserved keys (`$type`, `$key`, `$action`, `children`) stripped\n * from the prop bag. A node that carries neither a `$type` nor a `component`\n * string is not renderable and resolves to `null` rather than throwing, so a\n * partially-streamed or malformed node degrades to \"render nothing\".\n *\n * `partialPath` carries streaming state from the tool-args parse meta: a node\n * whose `$type` is still mid-arrival is held back (resolves to `null`) until it\n * completes, and the path is threaded into `children` so a nested streaming\n * node is held back while completed siblings render. Omit it for a\n * non-streaming (converter) normalize.\n */\nexport function normalizeUINode(\n  node: unknown,\n  partialPath?: readonly string[] | undefined,\n  depth = 0,\n): NormalizedUINode {\n  if (depth > MAX_DEPTH) return null;\n  if (node == null || typeof node === \"boolean\") return null;\n  if (typeof node === \"string\" || typeof node === \"number\") return node;\n  if (Array.isArray(node))\n    return node.map((child, index) =>\n      normalizeUINode(child, descend(partialPath, String(index)), depth + 1),\n    );\n  if (!isRecord(node)) return null;\n\n  // The flat `$type` shape is the canonical form; detect it first so a flat\n  // node that happens to use `component` as an ordinary prop is not swallowed\n  // by the legacy `component`-shape branch.\n  if (isTypeNode(node)) {\n    if (partialPath?.length === 1 && partialPath[0] === TYPE_KEY) return null;\n    const { [TYPE_KEY]: type, $key, $action, children, ...rest } = node;\n    // The `$`-prefixed namespace is framework-reserved (see the module header),\n    // so any model-supplied `$`-prefixed key is stripped from the prop bag the\n    // component sees. `$type`/`$key`/`$action` are pulled above; sweep the rest\n    // (e.g. a stray `$status`) so it never leaks to converters or components.\n    const props = stripReservedProps(rest);\n    return {\n      type,\n      props,\n      children: normalizeChildren(children, partialPath, depth),\n      key: $key,\n      action: $action,\n    };\n  }\n\n  if (isLegacyNode(node)) {\n    const props = stripReservedProps(\n      (node.props ?? {}) as Record<string, unknown>,\n    );\n    return {\n      type: node.component,\n      props,\n      children: normalizeChildren(node.children, partialPath, depth),\n      key: node.key as string | undefined,\n    };\n  }\n\n  return null;\n}\n\nfunction stripReservedProps(\n  props: Record<string, unknown>,\n): Record<string, unknown> {\n  let out: Record<string, unknown> | undefined;\n  for (const key of Object.keys(props)) {\n    if (key.startsWith(\"$\")) {\n      out ??= { ...props };\n      delete out[key];\n    }\n  }\n  return out ?? props;\n}\n\nfunction normalizeChildren(\n  children: unknown,\n  partialPath: readonly string[] | undefined,\n  depth: number,\n): NormalizedUINode | undefined {\n  if (children === undefined) return undefined;\n  return normalizeUINode(children, descend(partialPath, \"children\"), depth + 1);\n}\n\n/**\n * Normalizes the root of a {@link UISpec}, preserving whether the root was a\n * single node or a list.\n */\nexport function normalizeSpec(spec: UISpec): {\n  readonly root: NormalizedUINode | readonly NormalizedUINode[];\n} {\n  if (Array.isArray(spec)) {\n    return {\n      root: (spec as readonly UINode[]).map((node) => normalizeUINode(node)),\n    };\n  }\n  return { root: normalizeUINode(spec) };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAmBA,MAAa,aAAa;CAAC;CAAM;CAAM;CAAM;CAAM;CAAO;AAAK;AAG/D,MAAa,oBAAoB;CAAC;CAAM;CAAM;AAAI;AAGlD,MAAa,UAAU;CAAC;CAAU;CAAU;CAAY;AAAM;AAG9D,MAAa,SAAS;CACpB;CACA;CACA;CACA;CACA;CACA;AACF;AAGA,MAAa,SAAS;CAAC;CAAS;CAAU;AAAK;AAG/C,MAAa,YAAY;CAAC;CAAS;CAAU;CAAO;AAAS;AAG7D,MAAa,gBAAgB;CAC3B;CACA;CACA;CACA;CACA;AACF;AAGA,MAAa,cAAc;CAAC;CAAQ;CAAW;CAAW;AAAQ;AAyElE,MAAM,YAAY,UAChB,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAIrE,MAAM,gBACJ,SAC6B,OAAO,KAAK,iBAAiB;AAE5D,MAAM,cAAc,SAClB,OAAO,KAAK,cAAc;;;AAI5B,MAAM,YAAY;;;;;;AAOlB,SAAS,QACP,aACA,KAC+B;CAC/B,OAAO,cAAc,OAAO,MAAM,YAAY,MAAM,CAAC,IAAI,KAAA;AAC3D;;;;;;;;;;;;;;;AAgBA,SAAgB,gBACd,MACA,aACA,QAAQ,GACU;CAClB,IAAI,QAAQ,WAAW,OAAO;CAC9B,IAAI,QAAQ,QAAQ,OAAO,SAAS,WAAW,OAAO;CACtD,IAAI,OAAO,SAAS,YAAY,OAAO,SAAS,UAAU,OAAO;CACjE,IAAI,MAAM,QAAQ,IAAI,GACpB,OAAO,KAAK,KAAK,OAAO,UACtB,gBAAgB,OAAO,QAAQ,aAAa,OAAO,KAAK,CAAC,GAAG,QAAQ,CAAC,CACvE;CACF,IAAI,CAAC,SAAS,IAAI,GAAG,OAAO;CAK5B,IAAI,WAAW,IAAI,GAAG;EACpB,IAAI,aAAa,WAAW,KAAK,YAAY,OAAA,SAAiB,OAAO;EACrE,MAAM,GAAG,WAAW,MAAM,MAAM,SAAS,UAAU,GAAG,SAAS;EAM/D,OAAO;GACL;GACA,OAHY,mBAAmB,IAG3B;GACJ,UAAU,kBAAkB,UAAU,aAAa,KAAK;GACxD,KAAK;GACL,QAAQ;EACV;CACF;CAEA,IAAI,aAAa,IAAI,GAAG;EACtB,MAAM,QAAQ,mBACX,KAAK,SAAS,CAAC,CAClB;EACA,OAAO;GACL,MAAM,KAAK;GACX;GACA,UAAU,kBAAkB,KAAK,UAAU,aAAa,KAAK;GAC7D,KAAK,KAAK;EACZ;CACF;CAEA,OAAO;AACT;AAEA,SAAS,mBACP,OACyB;CACzB,IAAI;CACJ,KAAK,MAAM,OAAO,OAAO,KAAK,KAAK,GACjC,IAAI,IAAI,WAAW,GAAG,GAAG;EACvB,QAAQ,EAAE,GAAG,MAAM;EACnB,OAAO,IAAI;CACb;CAEF,OAAO,OAAO;AAChB;AAEA,SAAS,kBACP,UACA,aACA,OAC8B;CAC9B,IAAI,aAAa,KAAA,GAAW,OAAO,KAAA;CACnC,OAAO,gBAAgB,UAAU,QAAQ,aAAa,UAAU,GAAG,QAAQ,CAAC;AAC9E;;;;;AAMA,SAAgB,cAAc,MAE5B;CACA,IAAI,MAAM,QAAQ,IAAI,GACpB,OAAO,EACL,MAAO,KAA2B,KAAK,SAAS,gBAAgB,IAAI,CAAC,EACvE;CAEF,OAAO,EAAE,MAAM,gBAAgB,IAAI,EAAE;AACvC"}

package/dist/renderGenerativeUI.d.ts

@@ -6,10 +6,11 @@ import { ReactNode } from "react";
  * 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.
  */
 declare function renderGenerativeUI(node: unknown, library: GenerativeUILibrary, context?: GenerativeUIRenderContext): ReactNode;
 //#endregion

package/dist/renderGenerativeUI.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"renderGenerativeUI.d.ts","names":[],"sources":["../src/renderGenerativeUI.tsx"],"mappings":";;;;;;AAqBA;;;;;;;iBAAgB,kBAAA,CACd,IAAA,WACA,OAAA,EAAS,mBAAA,EACT,OAAA,GAAS,yBAAA,GACR,SAAA"}
+{"version":3,"file":"renderGenerativeUI.d.ts","names":[],"sources":["../src/renderGenerativeUI.tsx"],"mappings":";;;;;;AAwBA;;;;;;;;iBAAgB,kBAAA,CACd,IAAA,WACA,OAAA,EAAS,mBAAA,EACT,OAAA,GAAS,yBAAA,GACR,SAAA"}

package/dist/renderGenerativeUI.js

@@ -1,60 +1,29 @@
-import { TYPE_KEY } from "./constants.js";
+import { normalizeUINode } from "./ir.js";
 import { getPartialJsonObjectMeta } from "assistant-stream/utils";
 import { Fragment } from "react";
 import { jsx } from "react/jsx-runtime";
 //#region src/renderGenerativeUI.tsx
 const DEFAULT_CONTEXT = { status: "done" };
+const isElement = (node) => 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.
 */
 function renderGenerativeUI(node, library, context = DEFAULT_CONTEXT) {
 	const meta = getPartialJsonObjectMeta(node);
-	return renderNode(normalizeNode(node, meta?.state === "partial" ? meta.partialPath : void 0), 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, partialPath, depth = 0) {
-	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;
-	if (typeof type !== "string") return null;
-	if (partialPath?.length === 1 && partialPath[0] === "$type") return null;
-	if ("children" in props) props["children"] = normalizeNode(props["children"], descend(partialPath, "children"), depth + 1);
-	return {
-		type,
-		props
-	};
-}
-/** Steps the partial path down into `key`; siblings of the path are complete. */
-function descend(partialPath, key) {
-	return partialPath?.[0] === key ? partialPath.slice(1) : void 0;
+	return renderNode(normalizeUINode(node, meta?.state === "partial" ? meta.partialPath : void 0), library, context);
 }
 function renderNode(node, library, context) {
 	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) => /* @__PURE__ */ jsx(Fragment, { children: renderNode(child, library, context) }, `${index}:${nodeKind(child)}`));
-	return renderElement(node, library, context);
+	if (Array.isArray(node)) return node.map((child, index) => /* @__PURE__ */ jsx(Fragment, { children: renderNode(child, library, context) }, nodeKey(child, index)));
+	return isElement(node) ? renderElement(node, library, context) : null;
 }
 function renderElement(element, library, context) {
 	const entry = library[element.type];
@@ -63,12 +32,13 @@ function renderElement(element, library, context) {
 		return null;
 	}
 	if (!entry.streamProperties && context.status === "streaming") return null;
-	const { children, ...rest } = element.props;
 	const props = {
-		...rest,
+		...element.props,
 		$status: context.status
 	};
-	if (children !== void 0) props["children"] = renderNode(children, library, context);
+	if (context.dispatch !== void 0) props["$dispatch"] = context.dispatch;
+	if (element.action !== void 0) props["$action"] = element.action;
+	if (element.children !== void 0) props["children"] = renderNode(element.children, library, context);
 	return /* @__PURE__ */ jsx(GenerativeUIComponentRenderer, {
 		render: entry.render,
 		props
@@ -87,7 +57,10 @@ function nodeKind(node) {
 	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, index) {
+	return isElement(node) && (typeof node.key === "string" || typeof node.key === "number") ? `model:${node.key}` : `${index}:${nodeKind(node)}`;
 }
 function reportUnknownComponent(type, available) {
 	if (process.env["NODE_ENV"] !== "production") console.error(`[@assistant-ui/react-generative-ui] Unknown component "${type}". Available components: ${available.join(", ") || "(none)"}.`);

package/dist/renderGenerativeUI.js.map

@@ -1 +1 @@
-{"version":3,"file":"renderGenerativeUI.js","names":[],"sources":["../src/renderGenerativeUI.tsx"],"sourcesContent":["import { getPartialJsonObjectMeta } from \"assistant-stream/utils\";\nimport { Fragment, type ReactNode } from \"react\";\nimport { TYPE_KEY } from \"./constants\";\nimport type {\n  GenerativeUIElement,\n  GenerativeUILibrary,\n  GenerativeUINode,\n  GenerativeUIRenderContext,\n} from \"./types\";\n\nconst DEFAULT_CONTEXT: GenerativeUIRenderContext = { status: \"done\" };\n\n/**\n * Renders a generative-ui tree against a {@link GenerativeUILibrary}.\n *\n * The model emits each node as a flat object `{ $type, ...props }`. We first\n * normalize that wire form into React-shaped elements (`{ type, props }`), then\n * render: each `type` is looked up in the library and its `props` are passed\n * to the component's `render(props, context)`, with `children` rendered\n * recursively so components can nest.\n */\nexport function renderGenerativeUI(\n  node: unknown,\n  library: GenerativeUILibrary,\n  context: GenerativeUIRenderContext = DEFAULT_CONTEXT,\n): ReactNode {\n  // Tool args are parsed incrementally, and the parse meta records which path\n  // is still mid-arrival, so normalization can hold back a node whose `$type`\n  // string has not finished streaming.\n  const meta = getPartialJsonObjectMeta(node as Record<symbol, unknown>);\n  const partialPath = meta?.state === \"partial\" ? meta.partialPath : undefined;\n  return renderNode(normalizeNode(node, partialPath), library, context);\n}\n\n/**\n * The deepest tree we normalize. The input comes from the model, so a runaway\n * or adversarial response could nest arbitrarily deep and overflow the stack;\n * past this depth we stop (far beyond any real UI). Bounding normalization\n * bounds rendering too, since it only walks the normalized tree.\n */\nconst MAX_DEPTH = 64;\n\n/**\n * Converts the flat wire form into a normalized {@link GenerativeUINode}.\n *\n * `partialPath` is the remaining segment of the parse meta's partial path\n * relative to `node` (`undefined` once the walk leaves the partial frontier,\n * i.e. everything below is complete).\n */\nfunction normalizeNode(\n  node: unknown,\n  partialPath: readonly string[] | undefined,\n  depth = 0,\n): GenerativeUINode {\n  if (depth > MAX_DEPTH) return null;\n  if (node == null || typeof node === \"boolean\") return null;\n  if (typeof node === \"string\" || typeof node === \"number\") return node;\n  if (Array.isArray(node))\n    return node.map((child, index) =>\n      normalizeNode(child, descend(partialPath, String(index)), depth + 1),\n    );\n  if (typeof node !== \"object\") return null;\n\n  const { [TYPE_KEY]: type, ...props } = node as Record<string, unknown>;\n  // Args stream in incrementally; a node whose `$type` has not arrived yet\n  // (or whose `$type` string is still mid-arrival) is not an error, it just\n  // isn't renderable.\n  if (typeof type !== \"string\") return null;\n  if (partialPath?.length === 1 && partialPath[0] === TYPE_KEY) return null;\n\n  if (\"children\" in props) {\n    props[\"children\"] = normalizeNode(\n      props[\"children\"],\n      descend(partialPath, \"children\"),\n      depth + 1,\n    );\n  }\n  return { type, props } as GenerativeUIElement;\n}\n\n/** Steps the partial path down into `key`; siblings of the path are complete. */\nfunction descend(\n  partialPath: readonly string[] | undefined,\n  key: string,\n): readonly string[] | undefined {\n  return partialPath?.[0] === key ? partialPath.slice(1) : undefined;\n}\n\nfunction renderNode(\n  node: GenerativeUINode,\n  library: GenerativeUILibrary,\n  context: GenerativeUIRenderContext,\n): ReactNode {\n  if (node == null || typeof node === \"boolean\") return null;\n  if (typeof node === \"string\" || typeof node === \"number\") return node;\n  if (Array.isArray(node)) {\n    // The wire format has no per-node id, so the key is positional. Pairing the\n    // index with the node's kind means that when the model splices or reorders\n    // `children` and the kind at an index changes, the key changes and React\n    // remounts instead of handing a streaming node's hook state to a different\n    // component.\n    return node.map((child, index) => (\n      <Fragment key={`${index}:${nodeKind(child)}`}>\n        {renderNode(child, library, context)}\n      </Fragment>\n    ));\n  }\n  return renderElement(node, library, context);\n}\n\nfunction renderElement(\n  element: GenerativeUIElement,\n  library: GenerativeUILibrary,\n  context: GenerativeUIRenderContext,\n): ReactNode {\n  const entry = library[element.type];\n  if (!entry) {\n    reportUnknownComponent(element.type, Object.keys(library));\n    return null;\n  }\n\n  // Components that opt out of prop streaming wait until their props are\n  // complete rather than rendering from a partial parse.\n  if (!entry.streamProperties && context.status === \"streaming\") return null;\n\n  // Inject the framework props last so the model can never override them.\n  const { children, ...rest } = element.props;\n  const props: Record<string, unknown> = { ...rest, $status: context.status };\n  if (children !== undefined) {\n    props[\"children\"] = renderNode(children, library, context);\n  }\n\n  return <GenerativeUIComponentRenderer render={entry.render} props={props} />;\n}\n\n/**\n * Mounts a single node's `render` on its own fiber so the function may use\n * hooks and hold state independently of its siblings and parent.\n */\nfunction GenerativeUIComponentRenderer({\n  render,\n  props,\n}: {\n  render: (props: any) => ReactNode;\n  props: Record<string, unknown>;\n}): ReactNode {\n  return render(props);\n}\n\n/** A coarse kind tag for a child, used in its list key so a node changing kind\n * at a given index forces a remount rather than a wrong-fiber reuse. */\nfunction nodeKind(node: GenerativeUINode): string {\n  if (node == null || typeof node === \"boolean\") return \"\";\n  if (typeof node === \"string\" || typeof node === \"number\") return \"#text\";\n  if (Array.isArray(node)) return \"#array\";\n  return node.type;\n}\n\nfunction reportUnknownComponent(type: string, available: string[]): void {\n  if (process.env[\"NODE_ENV\"] !== \"production\") {\n    // eslint-disable-next-line no-console\n    console.error(\n      `[@assistant-ui/react-generative-ui] Unknown component \"${type}\". ` +\n        `Available components: ${available.join(\", \") || \"(none)\"}.`,\n    );\n  }\n}\n"],"mappings":";;;;;AAUA,MAAM,kBAA6C,EAAE,QAAQ,OAAO;;;;;;;;;;AAWpE,SAAgB,mBACd,MACA,SACA,UAAqC,iBAC1B;CAIX,MAAM,OAAO,yBAAyB,IAA+B;CAErE,OAAO,WAAW,cAAc,MADZ,MAAM,UAAU,YAAY,KAAK,cAAc,KAAA,CAClB,GAAG,SAAS,OAAO;AACtE;;;;;;;AAQA,MAAM,YAAY;;;;;;;;AASlB,SAAS,cACP,MACA,aACA,QAAQ,GACU;CAClB,IAAI,QAAQ,WAAW,OAAO;CAC9B,IAAI,QAAQ,QAAQ,OAAO,SAAS,WAAW,OAAO;CACtD,IAAI,OAAO,SAAS,YAAY,OAAO,SAAS,UAAU,OAAO;CACjE,IAAI,MAAM,QAAQ,IAAI,GACpB,OAAO,KAAK,KAAK,OAAO,UACtB,cAAc,OAAO,QAAQ,aAAa,OAAO,KAAK,CAAC,GAAG,QAAQ,CAAC,CACrE;CACF,IAAI,OAAO,SAAS,UAAU,OAAO;CAErC,MAAM,GAAG,WAAW,MAAM,GAAG,UAAU;CAIvC,IAAI,OAAO,SAAS,UAAU,OAAO;CACrC,IAAI,aAAa,WAAW,KAAK,YAAY,OAAA,SAAiB,OAAO;CAErE,IAAI,cAAc,OAChB,MAAM,cAAc,cAClB,MAAM,aACN,QAAQ,aAAa,UAAU,GAC/B,QAAQ,CACV;CAEF,OAAO;EAAE;EAAM;CAAM;AACvB;;AAGA,SAAS,QACP,aACA,KAC+B;CAC/B,OAAO,cAAc,OAAO,MAAM,YAAY,MAAM,CAAC,IAAI,KAAA;AAC3D;AAEA,SAAS,WACP,MACA,SACA,SACW;CACX,IAAI,QAAQ,QAAQ,OAAO,SAAS,WAAW,OAAO;CACtD,IAAI,OAAO,SAAS,YAAY,OAAO,SAAS,UAAU,OAAO;CACjE,IAAI,MAAM,QAAQ,IAAI,GAMpB,OAAO,KAAK,KAAK,OAAO,UACtB,oBAAC,UAAD,EAAA,UACG,WAAW,OAAO,SAAS,OAAO,EAC3B,GAFK,GAAG,MAAM,GAAG,SAAS,KAAK,GAE/B,CACX;CAEH,OAAO,cAAc,MAAM,SAAS,OAAO;AAC7C;AAEA,SAAS,cACP,SACA,SACA,SACW;CACX,MAAM,QAAQ,QAAQ,QAAQ;CAC9B,IAAI,CAAC,OAAO;EACV,uBAAuB,QAAQ,MAAM,OAAO,KAAK,OAAO,CAAC;EACzD,OAAO;CACT;CAIA,IAAI,CAAC,MAAM,oBAAoB,QAAQ,WAAW,aAAa,OAAO;CAGtE,MAAM,EAAE,UAAU,GAAG,SAAS,QAAQ;CACtC,MAAM,QAAiC;EAAE,GAAG;EAAM,SAAS,QAAQ;CAAO;CAC1E,IAAI,aAAa,KAAA,GACf,MAAM,cAAc,WAAW,UAAU,SAAS,OAAO;CAG3D,OAAO,oBAAC,+BAAD;EAA+B,QAAQ,MAAM;EAAe;CAAQ,CAAA;AAC7E;;;;;AAMA,SAAS,8BAA8B,EACrC,QACA,SAIY;CACZ,OAAO,OAAO,KAAK;AACrB;;;AAIA,SAAS,SAAS,MAAgC;CAChD,IAAI,QAAQ,QAAQ,OAAO,SAAS,WAAW,OAAO;CACtD,IAAI,OAAO,SAAS,YAAY,OAAO,SAAS,UAAU,OAAO;CACjE,IAAI,MAAM,QAAQ,IAAI,GAAG,OAAO;CAChC,OAAO,KAAK;AACd;AAEA,SAAS,uBAAuB,MAAc,WAA2B;CACvE,IAAI,QAAQ,IAAI,gBAAgB,cAE9B,QAAQ,MACN,0DAA0D,KAAK,2BACpC,UAAU,KAAK,IAAI,KAAK,SAAS,EAC9D;AAEJ"}
+{"version":3,"file":"renderGenerativeUI.js","names":[],"sources":["../src/renderGenerativeUI.tsx"],"sourcesContent":["import { getPartialJsonObjectMeta } from \"assistant-stream/utils\";\nimport { Fragment, type ReactNode } from \"react\";\nimport {\n  normalizeUINode,\n  type NormalizedUIElement,\n  type NormalizedUINode,\n} from \"./ir\";\nimport type { GenerativeUILibrary, GenerativeUIRenderContext } from \"./types\";\n\nconst DEFAULT_CONTEXT: GenerativeUIRenderContext = { status: \"done\" };\n\nconst isElement = (node: NormalizedUINode): node is NormalizedUIElement =>\n  typeof node === \"object\" && node !== null && !Array.isArray(node);\n\n/**\n * Renders a generative-ui tree against a {@link GenerativeUILibrary}.\n *\n * The model emits each node as a flat object `{ $type, ...props }`. We first\n * normalize that wire form into the canonical {@link NormalizedUINode} (with\n * `children` lifted to a reserved top-level key), then render: each `type` is\n * looked up in the library and its `props` are passed to the component's\n * `render(props, context)`, with `children` rendered recursively so components\n * can nest.\n */\nexport function renderGenerativeUI(\n  node: unknown,\n  library: GenerativeUILibrary,\n  context: GenerativeUIRenderContext = DEFAULT_CONTEXT,\n): ReactNode {\n  // Tool args are parsed incrementally, and the parse meta records which path\n  // is still mid-arrival, so normalization can hold back a node whose `$type`\n  // string has not finished streaming.\n  const meta = getPartialJsonObjectMeta(node as Record<symbol, unknown>);\n  const partialPath = meta?.state === \"partial\" ? meta.partialPath : undefined;\n  return renderNode(normalizeUINode(node, partialPath), library, context);\n}\n\nfunction renderNode(\n  node: NormalizedUINode,\n  library: GenerativeUILibrary,\n  context: GenerativeUIRenderContext,\n): ReactNode {\n  if (node == null || typeof node === \"boolean\") return null;\n  if (typeof node === \"string\" || typeof node === \"number\") return node;\n  if (Array.isArray(node)) {\n    // Use a model-provided stable key when present. Otherwise, keep the\n    // positional fallback: pairing the index with the node's kind means that\n    // when the kind at an index changes, React remounts instead of handing a\n    // streaming node's hook state to a different component.\n    return node.map((child, index) => (\n      <Fragment key={nodeKey(child, index)}>\n        {renderNode(child, library, context)}\n      </Fragment>\n    ));\n  }\n  return isElement(node) ? renderElement(node, library, context) : null;\n}\n\nfunction renderElement(\n  element: NormalizedUIElement,\n  library: GenerativeUILibrary,\n  context: GenerativeUIRenderContext,\n): ReactNode {\n  const entry = library[element.type];\n  if (!entry) {\n    reportUnknownComponent(element.type, Object.keys(library));\n    return null;\n  }\n\n  // Components that opt out of prop streaming wait until their props are\n  // complete rather than rendering from a partial parse.\n  if (!entry.streamProperties && context.status === \"streaming\") return null;\n\n  // `children` is a reserved top-level key on the normalized element, not a\n  // prop, so it is not in `props`. Inject the framework props last so the model\n  // can never override them. `$action` is likewise reserved and stripped from\n  // the prop bag during normalization, so it is re-injected here for components\n  // that carry behavior (e.g. `Button`).\n  const props: Record<string, unknown> = {\n    ...element.props,\n    $status: context.status,\n  };\n  if (context.dispatch !== undefined) {\n    props[\"$dispatch\"] = context.dispatch;\n  }\n  if (element.action !== undefined) {\n    props[\"$action\"] = element.action;\n  }\n  if (element.children !== undefined) {\n    props[\"children\"] = renderNode(element.children, library, context);\n  }\n\n  return <GenerativeUIComponentRenderer render={entry.render} props={props} />;\n}\n\n/**\n * Mounts a single node's `render` on its own fiber so the function may use\n * hooks and hold state independently of its siblings and parent.\n */\nfunction GenerativeUIComponentRenderer({\n  render,\n  props,\n}: {\n  render: (props: any) => ReactNode;\n  props: Record<string, unknown>;\n}): ReactNode {\n  return render(props);\n}\n\n/** A coarse kind tag for a child, used in its list key so a node changing kind\n * at a given index forces a remount rather than a wrong-fiber reuse. */\nfunction nodeKind(node: NormalizedUINode): string {\n  if (node == null || typeof node === \"boolean\") return \"\";\n  if (typeof node === \"string\" || typeof node === \"number\") return \"#text\";\n  if (Array.isArray(node)) return \"#array\";\n  return isElement(node) ? node.type : \"\";\n}\n\nfunction nodeKey(node: NormalizedUINode, index: number): string {\n  return isElement(node) &&\n    (typeof node.key === \"string\" || typeof node.key === \"number\")\n    ? `model:${node.key}`\n    : `${index}:${nodeKind(node)}`;\n}\n\nfunction reportUnknownComponent(type: string, available: string[]): void {\n  if (process.env[\"NODE_ENV\"] !== \"production\") {\n    // eslint-disable-next-line no-console\n    console.error(\n      `[@assistant-ui/react-generative-ui] Unknown component \"${type}\". ` +\n        `Available components: ${available.join(\", \") || \"(none)\"}.`,\n    );\n  }\n}\n"],"mappings":";;;;;AASA,MAAM,kBAA6C,EAAE,QAAQ,OAAO;AAEpE,MAAM,aAAa,SACjB,OAAO,SAAS,YAAY,SAAS,QAAQ,CAAC,MAAM,QAAQ,IAAI;;;;;;;;;;;AAYlE,SAAgB,mBACd,MACA,SACA,UAAqC,iBAC1B;CAIX,MAAM,OAAO,yBAAyB,IAA+B;CAErE,OAAO,WAAW,gBAAgB,MADd,MAAM,UAAU,YAAY,KAAK,cAAc,KAAA,CAChB,GAAG,SAAS,OAAO;AACxE;AAEA,SAAS,WACP,MACA,SACA,SACW;CACX,IAAI,QAAQ,QAAQ,OAAO,SAAS,WAAW,OAAO;CACtD,IAAI,OAAO,SAAS,YAAY,OAAO,SAAS,UAAU,OAAO;CACjE,IAAI,MAAM,QAAQ,IAAI,GAKpB,OAAO,KAAK,KAAK,OAAO,UACtB,oBAAC,UAAD,EAAA,UACG,WAAW,OAAO,SAAS,OAAO,EAC3B,GAFK,QAAQ,OAAO,KAAK,CAEzB,CACX;CAEH,OAAO,UAAU,IAAI,IAAI,cAAc,MAAM,SAAS,OAAO,IAAI;AACnE;AAEA,SAAS,cACP,SACA,SACA,SACW;CACX,MAAM,QAAQ,QAAQ,QAAQ;CAC9B,IAAI,CAAC,OAAO;EACV,uBAAuB,QAAQ,MAAM,OAAO,KAAK,OAAO,CAAC;EACzD,OAAO;CACT;CAIA,IAAI,CAAC,MAAM,oBAAoB,QAAQ,WAAW,aAAa,OAAO;CAOtE,MAAM,QAAiC;EACrC,GAAG,QAAQ;EACX,SAAS,QAAQ;CACnB;CACA,IAAI,QAAQ,aAAa,KAAA,GACvB,MAAM,eAAe,QAAQ;CAE/B,IAAI,QAAQ,WAAW,KAAA,GACrB,MAAM,aAAa,QAAQ;CAE7B,IAAI,QAAQ,aAAa,KAAA,GACvB,MAAM,cAAc,WAAW,QAAQ,UAAU,SAAS,OAAO;CAGnE,OAAO,oBAAC,+BAAD;EAA+B,QAAQ,MAAM;EAAe;CAAQ,CAAA;AAC7E;;;;;AAMA,SAAS,8BAA8B,EACrC,QACA,SAIY;CACZ,OAAO,OAAO,KAAK;AACrB;;;AAIA,SAAS,SAAS,MAAgC;CAChD,IAAI,QAAQ,QAAQ,OAAO,SAAS,WAAW,OAAO;CACtD,IAAI,OAAO,SAAS,YAAY,OAAO,SAAS,UAAU,OAAO;CACjE,IAAI,MAAM,QAAQ,IAAI,GAAG,OAAO;CAChC,OAAO,UAAU,IAAI,IAAI,KAAK,OAAO;AACvC;AAEA,SAAS,QAAQ,MAAwB,OAAuB;CAC9D,OAAO,UAAU,IAAI,MAClB,OAAO,KAAK,QAAQ,YAAY,OAAO,KAAK,QAAQ,YACnD,SAAS,KAAK,QACd,GAAG,MAAM,GAAG,SAAS,IAAI;AAC/B;AAEA,SAAS,uBAAuB,MAAc,WAA2B;CACvE,IAAI,QAAQ,IAAI,gBAAgB,cAE9B,QAAQ,MACN,0DAA0D,KAAK,2BACpC,UAAU,KAAK,IAAI,KAAK,SAAS,EAC9D;AAEJ"}

package/dist/types.d.ts

@@ -1,31 +1,60 @@
+import { Action, NormalizedUIElement } from "./ir.js";
 import { ReactNode } from "react";
 import { ZodType } from "zod";
 
 //#region src/types.d.ts
+/**
+ * The canonical generative-ui element, normalized from the flat `$type` shape
+ * or the legacy `component` shape (see {@link normalizeUINode}). `children` is
+ * a reserved top-level key, not a prop, so it lives here rather than inside
+ * `props`. Alias of {@link NormalizedUIElement}; kept under its old name so the
+ * package's public surface stays append-only.
+ */
+type GenerativeUIElement = NormalizedUIElement;
+type GenerativeUIProps = NormalizedUIElement["props"];
+/**
+ * Anything renderable as generative UI — mirrors React's `ReactNode`: an
+ * element, primitive text, a list of nodes, or nothing. Widened beyond the
+ * model payload (a {@link GenerativeUIElement}) with the renderer's
+ * null/boolean/undefined inputs.
+ */
+type GenerativeUINode = GenerativeUIElement | string | number | boolean | null | undefined | GenerativeUINode[];
+type GenerativeUIAction = Action;
 /** Whether a node's props are still streaming in or have fully arrived. */
 type GenerativeUIStatus = "streaming" | "done";
+/** The dispatcher an interactive component calls to fire its `$action`. */
+type GenerativeUIDispatch = (action: Action) => unknown;
 /** The render context threaded through {@link renderGenerativeUI}. */
 type GenerativeUIRenderContext = {
   /** Whether the tool call's arguments are still streaming or are complete. */status: GenerativeUIStatus;
+  dispatch?: GenerativeUIDispatch;
 };
 /**
  * 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`.
+ * and the injected framework keys. `$status` is the discriminant — when it is
+ * `"done"`, `P` is complete; while `"streaming"`, `P` is partial. `$action` is
+ * the node's behavior payload, present only on interactive nodes. `$dispatch`
+ * fires that payload through the host's {@link ActionRegistry}; it is present
+ * only when a registry was wired. All three are `$`-prefixed so they never
+ * collide with a real `status`/`action`/`dispatch` prop.
  */
 type StreamingRenderProps<P> = (Partial<P> & {
   children?: ReactNode;
   $status: "streaming";
+  $action?: Action;
+  $dispatch?: GenerativeUIDispatch;
 }) | (P & {
   children?: ReactNode;
   $status: "done";
+  $action?: Action;
+  $dispatch?: GenerativeUIDispatch;
 });
 /** Props for a component that only renders once complete — `$status` is always `"done"`. */
 type StaticRenderProps<P> = P & {
   children?: ReactNode;
   $status: "done";
+  $action?: Action;
+  $dispatch?: GenerativeUIDispatch;
 };
 /**
  * A component the model is allowed to render, with the schema for its props.
@@ -64,31 +93,6 @@ type GenerativeUIComponent<P = any> = {
  * This registry is the security boundary — any `type` not present is rejected.
  */
 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.
- */
-type GenerativeUIElement = {
-  type: string;
-  props: GenerativeUIProps;
-};
-/** Props passed to a component — mirrors a React component's props. */
-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.
- */
-type GenerativeUINode = GenerativeUIElement | string | number | boolean | null | undefined | GenerativeUINode[];
 //#endregion
-export { GenerativeUIComponent, GenerativeUIElement, GenerativeUILibrary, GenerativeUINode, GenerativeUIProps, GenerativeUIRenderContext, GenerativeUIStatus };
+export { GenerativeUIAction, GenerativeUIComponent, GenerativeUIDispatch, GenerativeUIElement, GenerativeUILibrary, GenerativeUINode, GenerativeUIProps, GenerativeUIRenderContext, GenerativeUIStatus };
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","names":[],"sources":["../src/types.ts"],"mappings":";;;;;KAIY,kBAAA;AAAZ;AAAA,KAGY,yBAAA;+EAEV,MAAA,EAAQ,kBAAkB;AAAA;AAF5B;;;;AAE4B;AAC1B;;AAHF,KAYK,oBAAA,OACA,OAAA,CAAQ,CAAA;EAAO,QAAA,GAAW,SAAA;EAAW,OAAA;AAAA,MACrC,CAAA;EAAM,QAAA,GAAW,SAAA;EAAW,OAAA;AAAA;;KAG5B,iBAAA,MAAuB,CAAA;EAAM,QAAA,GAAW,SAAS;EAAE,OAAA;AAAA;;;;;;;;AAHhB;AAAA;;;;KAiB5B,qBAAA;EAdgB,oFAiBtB,WAAA,UAjBuC;EAmBvC,UAAA,EAAY,OAAA,CAAQ,CAAA;EAnBqC;AAAA;AAc/D;;;;EAYM,gBAAA;EACA,MAAA,GAAS,KAAA,EAAO,oBAAA,CAAqB,CAAA,MAAO,SAAA;AAAA;EAG5C,WAAA;EACA,UAAA,EAAY,OAAA,CAAQ,CAAA,GAAR;EAEZ,gBAAA;EACA,MAAA,GAAS,KAAA,EAAO,iBAAA,CAAkB,CAAA,MAAO,SAAA;AAAA;;;;;;;;KAUnC,mBAAA,GAAsB,MAAM,SAAS,qBAAA;;;;;;;;;;;;;KAcrC,mBAAA;EACV,IAAA;EACA,KAAA,EAAO,iBAAiB;AAAA;AA1B8B;AAAA,KA8B5C,iBAAA;EACV,QAAA,GAAW,gBAAA;AAAA,IACT,MAAM;;AAtB4D;AActE;;KAcY,gBAAA,GACR,mBAAA,kDAMA,gBAAgB"}
+{"version":3,"file":"types.d.ts","names":[],"sources":["../src/types.ts"],"mappings":";;;;;;;AAWA;;;;AAAqD;KAAzC,mBAAA,GAAsB,mBAAmB;AAAA,KAEzC,iBAAA,GAAoB,mBAAmB;;;AAAA;AAQnD;;;KAAY,gBAAA,GACR,mBAAA,kDAMA,gBAAgB;AAAA,KAER,kBAAA,GAAqB,MAAM;AAAvC;AAAA,KAGY,kBAAA;;KAGA,oBAAA,IAAwB,MAAc,EAAN,MAAM;AANX;AAAA,KAS3B,yBAAA;EANkB,6EAQ5B,MAAA,EAAQ,kBAAA;EACR,QAAA,GAAW,oBAAoB;AAAA;AANjC;;;;AAAkD;AAGlD;;;;AAHA,KAkBK,oBAAA,OACA,OAAA,CAAQ,CAAA;EACP,QAAA,GAAW,SAAA;EACX,OAAA;EACA,OAAA,GAAU,MAAA;EACV,SAAA,GAAY,oBAAA;AAAA,MAEb,CAAA;EACC,QAAA,GAAW,SAAA;EACX,OAAA;EACA,OAAA,GAAU,MAAA;EACV,SAAA,GAAY,oBAAA;AAAA;;KAIb,iBAAA,MAAuB,CAAA;EAC1B,QAAA,GAAW,SAAA;EACX,OAAA;EACA,OAAA,GAAU,MAAA;EACV,SAAA,GAAY,oBAAA;AAAA;;;;;;;;;;;;;KAeF,qBAAA;EA1BN,oFA6BA,WAAA,UA5BA;EA8BA,UAAA,EAAY,OAAA,CAAQ,CAAA;EA7BV;;;;AACsB;AAAA;EAmChC,gBAAA;EACA,MAAA,GAAS,KAAA,EAAO,oBAAA,CAAqB,CAAA,MAAO,SAAA;AAAA;EAG5C,WAAA;EACA,UAAA,EAAY,OAAA,CAAQ,CAAA,GAhCZ;EAkCR,gBAAA;EACA,MAAA,GAAS,KAAA,EAAO,iBAAA,CAAkB,CAAA,MAAO,SAAA;AAAA;;;;;;;;KAUnC,mBAAA,GAAsB,MAAM,SAAS,qBAAA"}

package/dist/vocabulary/alert.d.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+
+//#region src/vocabulary/alert.d.ts
+declare const alertVocabulary: {
+  Alert: {
+    description: string;
+    properties: z.ZodObject<{
+      title: z.ZodOptional<z.ZodString>;
+      description: z.ZodOptional<z.ZodString>;
+      tone: z.ZodOptional<z.ZodEnum<{
+        success: "success";
+        info: "info";
+        warning: "warning";
+        danger: "danger";
+      }>>;
+    }, z.core.$strip>;
+    render: ({
+      title,
+      description,
+      tone,
+      children
+    }: any) => import("react").JSX.Element;
+  };
+  Carousel: {
+    description: string;
+    properties: z.ZodObject<{}, z.core.$strip>;
+    render: ({
+      children
+    }: any) => import("react").JSX.Element;
+  };
+};
+//#endregion
+export { alertVocabulary };
+//# sourceMappingURL=alert.d.ts.map

package/dist/vocabulary/alert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alert.d.ts","names":[],"sources":["../../src/vocabulary/alert.tsx"],"mappings":";;;cAOa,eAAA"}

package/dist/vocabulary/alert.js

@@ -0,0 +1,49 @@
+import { ALERT_TONES } from "../ir.js";
+import { Children } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { z } from "zod";
+//#region src/vocabulary/alert.tsx
+const MAX_CARDS = 10;
+const alertVocabulary = {
+	Alert: {
+		description: "A highlighted message conveying urgency. `tone` drives the severity.",
+		properties: z.object({
+			title: z.string().optional().describe("Alert title."),
+			description: z.string().optional().describe("Supporting description text."),
+			tone: z.enum(ALERT_TONES).optional().describe("Severity tone; defaults to `info`.")
+		}),
+		render: ({ title, description, tone, children }) => /* @__PURE__ */ jsxs("div", {
+			"data-aui": "alert",
+			"data-aui-tone": tone ?? "info",
+			role: "alert",
+			children: [
+				title ? /* @__PURE__ */ jsx("header", {
+					"data-aui": "alert-title",
+					children: title
+				}) : null,
+				description ? /* @__PURE__ */ jsx("p", {
+					"data-aui": "alert-desc",
+					children: description
+				}) : null,
+				children
+			]
+		})
+	},
+	Carousel: {
+		description: "A horizontally scrollable group of `Card` children (max 10).",
+		properties: z.object({}),
+		render: ({ children }) => {
+			return /* @__PURE__ */ jsx("div", {
+				"data-aui": "carousel",
+				children: Children.toArray(children).slice(0, MAX_CARDS).map((card, i) => /* @__PURE__ */ jsx("div", {
+					"data-aui": "carousel-slide",
+					children: card
+				}, i))
+			});
+		}
+	}
+};
+//#endregion
+export { alertVocabulary };
+
+//# sourceMappingURL=alert.js.map

package/dist/vocabulary/alert.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alert.js","names":[],"sources":["../../src/vocabulary/alert.tsx"],"sourcesContent":["import { Children } from \"react\";\nimport { z } from \"zod\";\nimport type { GenerativeUILibrary } from \"../types\";\nimport { ALERT_TONES } from \"../ir\";\n\nconst MAX_CARDS = 10;\n\nexport const alertVocabulary = {\n  Alert: {\n    description:\n      \"A highlighted message conveying urgency. `tone` drives the severity.\",\n    properties: z.object({\n      title: z.string().optional().describe(\"Alert title.\"),\n      description: z\n        .string()\n        .optional()\n        .describe(\"Supporting description text.\"),\n      tone: z\n        .enum(ALERT_TONES)\n        .optional()\n        .describe(\"Severity tone; defaults to `info`.\"),\n    }),\n    render: ({ title, description, tone, children }) => (\n      <div data-aui=\"alert\" data-aui-tone={tone ?? \"info\"} role=\"alert\">\n        {title ? <header data-aui=\"alert-title\">{title}</header> : null}\n        {description ? <p data-aui=\"alert-desc\">{description}</p> : null}\n        {children}\n      </div>\n    ),\n  },\n  Carousel: {\n    description: \"A horizontally scrollable group of `Card` children (max 10).\",\n    properties: z.object({}),\n    render: ({ children }) => {\n      const cards = Children.toArray(children).slice(0, MAX_CARDS);\n      return (\n        <div data-aui=\"carousel\">\n          {cards.map((card, i) => (\n            <div key={i} data-aui=\"carousel-slide\">\n              {card}\n            </div>\n          ))}\n        </div>\n      );\n    },\n  },\n} satisfies GenerativeUILibrary;\n"],"mappings":";;;;;AAKA,MAAM,YAAY;AAElB,MAAa,kBAAkB;CAC7B,OAAO;EACL,aACE;EACF,YAAY,EAAE,OAAO;GACnB,OAAO,EAAE,OAAO,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,cAAc;GACpD,aAAa,EACV,OAAO,CAAC,CACR,SAAS,CAAC,CACV,SAAS,8BAA8B;GAC1C,MAAM,EACH,KAAK,WAAW,CAAC,CACjB,SAAS,CAAC,CACV,SAAS,oCAAoC;EAClD,CAAC;EACD,SAAS,EAAE,OAAO,aAAa,MAAM,eACnC,qBAAC,OAAD;GAAK,YAAS;GAAQ,iBAAe,QAAQ;GAAQ,MAAK;aAA1D;IACG,QAAQ,oBAAC,UAAD;KAAQ,YAAS;eAAe;IAAc,CAAA,IAAI;IAC1D,cAAc,oBAAC,KAAD;KAAG,YAAS;eAAc;IAAe,CAAA,IAAI;IAC3D;GACE;;CAET;CACA,UAAU;EACR,aAAa;EACb,YAAY,EAAE,OAAO,CAAC,CAAC;EACvB,SAAS,EAAE,eAAe;GAExB,OACE,oBAAC,OAAD;IAAK,YAAS;cAFF,SAAS,QAAQ,QAAQ,CAAC,CAAC,MAAM,GAAG,SAGzC,CAAC,CAAC,KAAK,MAAM,MAChB,oBAAC,OAAD;KAAa,YAAS;eACnB;IACE,GAFK,CAEL,CACN;GACE,CAAA;EAET;CACF;AACF"}

package/dist/vocabulary/data.d.ts

@@ -0,0 +1,53 @@
+import { z } from "zod";
+
+//#region src/vocabulary/data.d.ts
+declare const dataVocabulary: {
+  Table: {
+    description: string;
+    properties: z.ZodObject<{
+      columns: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+      }, z.core.$strip>>>;
+      rows: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>>;
+    }, z.core.$strip>;
+    render: ({
+      columns,
+      rows,
+      children
+    }: any) => import("react").JSX.Element;
+  };
+  Markdown: {
+    description: string;
+    properties: z.ZodObject<{
+      value: z.ZodString;
+    }, z.core.$strip>;
+    streamProperties: true;
+    render: ({
+      value,
+      children
+    }: any) => import("react").JSX.Element;
+  };
+  Chart: {
+    description: string;
+    properties: z.ZodObject<{
+      variant: z.ZodEnum<{
+        bar: "bar";
+        line: "line";
+        sparkline: "sparkline";
+      }>;
+      data: z.ZodArray<z.ZodObject<{
+        label: z.ZodOptional<z.ZodString>;
+        value: z.ZodNumber;
+      }, z.core.$strip>>;
+      color: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    render: ({
+      variant,
+      data,
+      color
+    }: any) => import("react").JSX.Element;
+  };
+};
+//#endregion
+export { dataVocabulary };
+//# sourceMappingURL=data.d.ts.map

package/dist/vocabulary/data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data.d.ts","names":[],"sources":["../../src/vocabulary/data.tsx"],"mappings":";;;cAWa,cAAA"}