@agentable-ui/genui 0.1.0 → 0.3.1

package/README.md

@@ -1,66 +1,110 @@
 # @agentable-ui/genui
 
-Generative UI for Agentable: the agent describes what to render, you keep control of what can be rendered.
+Render model-generated interfaces using components you allow. Use `Renderer` for text streamed by your application, or `AgentSurface` for an in-page agent that calls a `present` tool.
+
+## Install
 
 ```bash
 npm install @agentable-ui/genui @agentable-ui/ui @agentable-ui/react @agentable-ui/core
 ```
 
+## Render a program
+
+This complete example renders a static program. Replace `program` with the accumulated text from your model stream and set `isStreaming` while chunks arrive.
+
 ```tsx
-import { AgentSurface } from "@agentable-ui/genui";
+import { Renderer } from "@agentable-ui/genui";
 import { uiCatalog } from "@agentable-ui/ui";
+import "@agentable-ui/ui/styles.css";
+
+const program = `root = Card("Order summary", [total])
+total = Stat("Revenue", "$48.2k")`;
 
-<AgentSurface components={uiCatalog} name="present" maxNodes={60} />;
+export default function Summary() {
+  return <Renderer components={uiCatalog} response={program} isStreaming={false} />;
+}
 ```
 
-That declares a `present` tool whose input schema is generated from the catalog. The agent sends a UI spec; the component tree it can produce is exactly the catalog you passed and nothing else.
+`response` is the **full text received so far**, not just the newest chunk. Complete lines render as they arrive; interactions stay disabled until streaming finishes. `onError` receives structured parsing and validation issues. Your app owns model requests, credentials, and streaming transport.
 
-## Why one tool
+## Give a browser agent a surface
 
-Exposing a tool per component burns the budget and lets the agent invent markup. A single `present` tool with a generated schema keeps the cost flat and the output constrained.
+```tsx
+import { AgentableProvider } from "@agentable-ui/react";
+import { AgentSurface } from "@agentable-ui/genui";
+import { uiCatalog } from "@agentable-ui/ui";
+import "@agentable-ui/ui/styles.css";
+
+export default function App() {
+  return (
+    <AgentableProvider>
+      <AgentSurface components={uiCatalog} name="present" maxNodes={60} />
+    </AgentableProvider>
+  );
+}
+```
 
-## Validation
+The surface declares one `present` tool with a schema derived from its currently allowed catalog. An agent can supply either a program or a JSON tree:
 
-`validateSpec(spec, catalog, allowed, opts)` runs before anything renders and rejects unknown components, bad prop shapes, specs deeper than `maxDepth` (default 6) and specs larger than `maxNodes` (default 60). Failures come back to the agent as structured issues it can correct, not as a thrown error.
+```json
+{"program":"root = Card(\"Hello\")"}
+```
 
-- `catalogSchema(catalog, allowed)` — the generated JSON Schema for the `present` tool.
-- `renderSpec(spec, catalog)` — render a validated spec yourself.
+```json
+{"root":{"component":"Card","props":{"title":"Hello"}}}
+```
 
-## Interactive surfaces
+A single tool avoids one tool per visual component; its schema size still depends on the catalog. Use a focused catalog and inspect the result in devtools.
 
-Nodes can do more than display props:
+## Bind data and handle events
 
-```jsonc
-{
-  "component": "RecordTable", "id": "orders",
-  "bind": { "rows": "data.paid" },                       // read app data
-  "on": { "select": [{ "type": "set", "path": "ui.selected", "value": "{{value}}" }] }
-}
-{
-  "component": "Button", "when": "ui.selected", "props": { "label": "Refund this order" },
-  "on": { "press": [{ "type": "tool", "name": "refund_order", "args": { "id": "{{ui.selected.id}}" }, "into": "ui.last" }] }
-}
+- `$data.*` in Lang (or `data.*` in JSON bindings) reads application data passed through `data`. Generated UI cannot write to it. Read paths can filter and count arrays: `$data.items[done=true].length`.
+- `$ui.*` is local interface state. Actions can set, merge, push, remove, increment, or toggle it.
+- A catalog entry maps event names to callback props, for example `events: { press: "onPress" }`.
+- `when` conditionally shows a node. `@Say` forwards a message to `onMessage`.
+
+For example:
+
+```text
+root = Stack([input, greeting])
+input = TextInput("Name", value: $ui.name, change: @Set($ui.name, $event))
+greeting = Text("Thanks for sharing your name.", when: $ui.name)
 ```
 
-- `data.*` is what you pass as `<AgentSurface data={...}>`. It is read-only to generated UI and re-renders when it changes.
-- `ui.*` belongs to the surface. Actions (`set`, `merge`, `push`, `remove`, `increment`, `toggle`) may only write here.
-- `tool` actions call registered tools through `agentable.invokeCapability`, so confirmation, caching and invalidation work exactly as for an agent. Only tools an agent could reach (tier 0 or 1) are callable; narrow them with `tools={[...]}` or turn them off with `tools={false}`.
-- `present({ ops })` patches the current tree by node id (`add`, `update`, `remove`, `set`) instead of resending it.
-- With `data` set, a read-only `<name>_state` tool returns the shape of `data`, the current `ui` state and the tree.
-- Catalog entries declare events as `events: { press: "onPress" }`: event name to callback prop, whose first argument becomes `{{value}}`.
+Tool routing differs by host:
+
+| Host | Tool configuration |
+|---|---|
+| `Renderer` | `tools={{ tool_name: callback }}` supplies callbacks. Missing names can fall back to a mounted Agentable registry. Direct callbacks follow your application's policies. |
+| `AgentSurface` | `tools={["tool_name"]}` narrows callable registry tools; `tools={false}` disables tool actions. Registry calls retain confirmation, caching, and invalidation. |
 
-## Catalog entries
+`AgentSurface` can also patch the current tree with `present({ ops })`, using node ids and `add`, `update`, `remove`, or `set` operations. When `data` is supplied, a read-only `<name>_state` tool reports the data shape, UI state, and current tree; set `stateTool={false}` to omit it.
+
+## Validation and custom catalogs
+
+```tsx
+import { Stat } from "@agentable-ui/ui";
 
-```ts
 const catalog = {
   Stat: {
     component: Stat,
-    props: z.object({ label: z.string(), value: z.string(), delta: z.string().optional() }),
-    description: "A single headline number.",
+    description: "A headline number.",
+    props: {
+      type: "object",
+      properties: {
+        label: { type: "string" },
+        value: { type: "string" },
+      },
+      required: ["label", "value"],
+    },
   },
 };
 ```
 
-`props` accepts a JSON Schema object or any Standard Schema validator. `uiCatalog` from [`@agentable-ui/ui`](../ui) is a ready-made set.
+Catalog schemas accept JSON Schema or supported Standard Schema validators. Unknown components, invalid props, and excessive depth/node counts produce structured issues. `AgentSurface` defaults to depth 6 and 60 nodes. Renderer prunes invalid nodes so valid parts can remain visible; validation options depend on the host.
+
+Lower-level exports include `validateSpec`, `catalogSchema`, and `renderSpec`. Validate before calling `renderSpec` directly.
+
+See [lang](../lang) for syntax, prompts, and parsing; [ui](../ui) for the built-in catalog.
 
-MIT
+MIT licensed.

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { ComponentType, ReactNode } from "react";
 import { JSONSchema, SchemaInput, Tier } from "@agentable-ui/core";
+import { Library } from "@agentable-ui/lang";
 //#region src/state.d.ts
 /**
  * Surface state. Two roots: `data` is the app's, read-only to generated UI;
@@ -9,9 +10,19 @@ interface SurfaceState {
   data: Record<string, unknown>;
   ui: Record<string, unknown>;
 }
-/** "a.b[0].c" -> ["a", "b", 0, "c"]. Throws on __proto__, prototype and constructor segments. */
-export declare function parsePath(path: string): Array<string | number>;
-/** Read a path, following own properties only. Undefined for missing or unsafe paths. */
+/** A read-only list filter in a path: `items[done=true]`, `items[status!="archived"]`. */
+interface PathFilter {
+  field: string;
+  op: "=" | "!=";
+  value: string | number | boolean;
+}
+type PathKey = string | number | PathFilter;
+/**
+ * "a.b[0].c" -> ["a", "b", 0, "c"]; "items[done=true]" -> ["items", {field: "done", op: "=", value: true}].
+ * Throws on __proto__, prototype and constructor segments, and on malformed selectors.
+ */
+export declare function parsePath(path: string): PathKey[];
+/** Read a path, following own properties only. Filters narrow arrays. Undefined for missing or unsafe paths. */
 export declare function getPath(obj: unknown, path: string): unknown;
 type StateAction = {
   type: "set";
@@ -61,7 +72,12 @@ interface ToolAction {
   args?: Record<string, unknown>;
   into?: string;
 }
-type UIAction = StateAction | ToolAction;
+/** Send text to the assistant (the surface's `onMessage`). */
+interface MessageAction {
+  type: "message";
+  text: string;
+}
+type UIAction = StateAction | ToolAction | MessageAction;
 interface UISpec {
   component: string;
   /** Stable id, needed to target the node with patch ops. */
@@ -113,6 +129,11 @@ interface ValidateOptions {
   state?: SurfaceState;
   /** Tool names that `tool` actions may call. None when absent. */
   tools?: ReadonlySet<string>;
+  /**
+   * Drop nodes with issues instead of failing the whole spec. Used while a
+   * program streams in, where a half-formed node must not blank the rest.
+   */
+  prune?: boolean;
 }
 export declare function isVisible(node: Pick<UISpec, "when">, state: SurfaceState): boolean;
 /** Static props overlaid with bound values that currently resolve. */
@@ -127,6 +148,7 @@ export declare function validateSpec(spec: UISpec, catalog: Record<string, Valid
   ok: true;
   spec: UISpec;
   nodes: number;
+  issues: SpecIssue[];
 } | {
   ok: false;
   issues: SpecIssue[];
@@ -141,6 +163,46 @@ export declare function applyOps(root: UISpec, ops: SurfaceOp[]): {
   state: StateAction[];
 };
 //#endregion
+//#region src/renderer.d.ts
+interface RendererError {
+  code: string;
+  message: string;
+  line?: number;
+  path?: string;
+}
+interface RendererProps {
+  /** Components the program may use. The library (signatures, prompt) is derived from it. */
+  components: Catalog;
+  /** Pass a prebuilt library to share it with prompt generation. */
+  library?: Library;
+  /** The program text received so far. */
+  response: string;
+  /** True while tokens are still arriving: partial lines are held back and the UI is inert. */
+  isStreaming?: boolean;
+  /** App data the program may bind to as $data.*. */
+  data?: Record<string, unknown>;
+  /** Functions @Tool may call by name. Names not here fall back to the Agentable registry when a provider is mounted. */
+  tools?: Record<string, (args: Record<string, unknown>) => unknown | Promise<unknown>>;
+  /** Text sent by @Say. */
+  onMessage?: (text: string, node: UISpec) => void;
+  /** Structured parse and validation errors; `[]` once clean. Warnings are left out. */
+  onError?: (errors: RendererError[]) => void;
+  /** An action failed or was declined. */
+  onActionError?: (message: string, node: UISpec) => void;
+  /** $ui.* state to start from. */
+  initialUi?: Record<string, unknown>;
+  onUiChange?: (ui: Record<string, unknown>) => void;
+  placeholder?: ReactNode;
+  className?: string;
+}
+/**
+ * Renders an Agentable Lang program as it streams. Each complete line is
+ * parsed, the tree is validated against the catalog with bad nodes pruned,
+ * and the rest draws immediately. Bindings, `when` and actions work exactly
+ * as in <AgentSurface>; tool actions go to `tools` or the registry.
+ */
+export declare function Renderer({ components, library, response, isStreaming, data, tools, onMessage, onError, onActionError, initialUi, onUiChange, placeholder, className }: RendererProps): import("react").JSX.Element;
+//#endregion
 //#region src/index.d.ts
 export interface CatalogComponent<P = Record<string, unknown>> {
   component: ComponentType<P>;
@@ -161,6 +223,8 @@ export type Catalog = Record<string, CatalogComponent<never>>;
 export interface PresentArgs {
   /** The tree to render. Replaces the current one and resets ui state. null clears the surface. */
   root?: UISpec | null;
+  /** The tree as an Agentable Lang program (about half the tokens of `root`). */
+  program?: string;
   /** Patch the current tree (applied after `root` when both are given). */
   ops?: SurfaceOp[];
   /** ui.* state to start from when sending `root`. */
@@ -205,6 +269,8 @@ export interface AgentSurfaceProps {
   stateTool?: string | false;
   /** Called when an action in the generated UI fails or is declined. */
   onActionError?: (message: string, node: UISpec) => void;
+  /** Receives text a `@Say` / message action sends to the assistant. Without it the action fails. */
+  onMessage?: (text: string, node: UISpec) => void;
 }
 /**
  * Renders whatever the agent last called `present` with. Every catalog
@@ -216,6 +282,6 @@ export interface AgentSurfaceProps {
  * generated UI and an agent reach a tool through the same registry path, so
  * confirmation, caching and invalidation apply to both.
  */
-export declare function AgentSurface({ components, name, id, group, tier, priority, maxDepth, maxNodes, placeholder, onPresent, className, clearable, data, tools, stateTool, onActionError }: AgentSurfaceProps): import("react").JSX.Element;
+export declare function AgentSurface({ components, name, id, group, tier, priority, maxDepth, maxNodes, placeholder, onPresent, className, clearable, data, tools, stateTool, onActionError, onMessage }: AgentSurfaceProps): import("react").JSX.Element;
 //#endregion
-export type { SpecIssue, StateAction, SurfaceOp, SurfaceState, ToolAction, UIAction, UISpec, UiStore, ValidateOptions };
+export type { MessageAction, PathFilter, PathKey, RendererError, RendererProps, SpecIssue, StateAction, SurfaceOp, SurfaceState, ToolAction, UIAction, UISpec, UiStore, ValidateOptions };

package/dist/index.js

@@ -1,6 +1,7 @@
-import { Component, createElement, useCallback, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { Component, createElement, useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { toJsonSchema, validateInput } from "@agentable-ui/core";
 import { useAgentable, useAgentableSnapshot, useCapability } from "@agentable-ui/react";
+import { createLibrary } from "@agentable-ui/lang";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 //#region src/state.ts
 /** Keys that reach an object's prototype. Paths come from agents and user input, so they are never followed. */
@@ -9,14 +10,62 @@ const UNSAFE_KEYS = /* @__PURE__ */ new Set([
 	"prototype",
 	"constructor"
 ]);
-/** "a.b[0].c" -> ["a", "b", 0, "c"]. Throws on __proto__, prototype and constructor segments. */
+const isFilter = (k) => typeof k === "object";
+function literal(raw) {
+	if (raw.startsWith("\"")) return raw.slice(1, -1);
+	if (raw === "true") return true;
+	if (raw === "false") return false;
+	if (/^-?\d+(\.\d+)?$/.test(raw)) return Number(raw);
+	return raw;
+}
+/**
+* "a.b[0].c" -> ["a", "b", 0, "c"]; "items[done=true]" -> ["items", {field: "done", op: "=", value: true}].
+* Throws on __proto__, prototype and constructor segments, and on malformed selectors.
+*/
 function parsePath(path) {
 	if (!path) return [];
-	const keys = path.replace(/\[(\d+)\]/g, ".$1").split(".").filter(Boolean).map((p) => /^\d+$/.test(p) ? Number(p) : p);
-	for (const k of keys) if (typeof k === "string" && UNSAFE_KEYS.has(k)) throw new Error(`Path "${path}" uses the reserved key "${k}".`);
+	const keys = [];
+	let i = 0;
+	while (i < path.length) {
+		const c = path[i];
+		if (c === ".") {
+			i++;
+			continue;
+		}
+		const rest = path.slice(i);
+		if (c === "[") {
+			const index = /^\[(\d+)\]/.exec(rest);
+			if (index) {
+				keys.push(Number(index[1]));
+				i += index[0].length;
+				continue;
+			}
+			const filter = /^\[([A-Za-z_][A-Za-z0-9_]*)(!?=)("[^"\]]*"|[A-Za-z0-9_.-]+)\]/.exec(rest);
+			if (!filter) throw new Error(`Path "${path}" has a bad selector; use [0] or [field=value].`);
+			keys.push({
+				field: filter[1],
+				op: filter[2],
+				value: literal(filter[3])
+			});
+			i += filter[0].length;
+			continue;
+		}
+		const seg = /^[^.[\]]+/.exec(rest)[0];
+		keys.push(/^\d+$/.test(seg) ? Number(seg) : seg);
+		i += seg.length;
+	}
+	for (const k of keys) {
+		const name = isFilter(k) ? k.field : k;
+		if (typeof name === "string" && UNSAFE_KEYS.has(name)) throw new Error(`Path "${path}" uses the reserved key "${name}".`);
+	}
 	return keys;
 }
-/** Read a path, following own properties only. Undefined for missing or unsafe paths. */
+function matches(item, f) {
+	const v = item !== null && typeof item === "object" && Object.hasOwn(item, f.field) ? item[f.field] : void 0;
+	const eq = typeof f.value === "boolean" ? Boolean(v) === f.value : v !== void 0 && v !== null && String(v) === String(f.value);
+	return f.op === "=" ? eq : !eq;
+}
+/** Read a path, following own properties only. Filters narrow arrays. Undefined for missing or unsafe paths. */
 function getPath(obj, path) {
 	let keys;
 	try {
@@ -26,6 +75,11 @@ function getPath(obj, path) {
 	}
 	let cur = obj;
 	for (const key of keys) {
+		if (isFilter(key)) {
+			if (!Array.isArray(cur)) return void 0;
+			cur = cur.filter((item) => matches(item, key));
+			continue;
+		}
 		if (cur == null || typeof cur !== "object" || !Object.hasOwn(cur, key)) return void 0;
 		cur = cur[key];
 	}
@@ -63,6 +117,7 @@ function setPath(obj, keys, value) {
 function uiKeys(path) {
 	const keys = parsePath(path);
 	if (keys[0] !== "ui" || keys.length < 2) throw new Error(`Actions may only write ui.* paths (got "${path}").`);
+	if (keys.some(isFilter)) throw new Error(`Filters like [field=value] are read-only (got "${path}").`);
 	return keys.slice(1);
 }
 function reduce(ui, a) {
@@ -192,9 +247,13 @@ function actionIssues(a, path, tools) {
 		});
 		return out;
 	}
+	if (a.type === "message") return typeof a.text === "string" ? [] : [{
+		path: `${path}.text`,
+		message: "message needs a text string."
+	}];
 	if (!STATE_ACTIONS.has(a.type)) return [{
 		path: `${path}.type`,
-		message: `Unknown action "${a.type}". Use set, merge, push, remove, increment, toggle or tool.`
+		message: `Unknown action "${a.type}". Use set, merge, push, remove, increment, toggle, tool or message.`
 	}];
 	if (!isStatePath(a.path, ["ui"])) return [{
 		path: `${path}.path`,
@@ -364,6 +423,7 @@ async function validateSpec(spec, catalog, allowed, opts = {}) {
 				if (Object.keys(on).length) out.on = on;
 			}
 		}
+		const ownBad = issues.length > before;
 		if (Array.isArray(node.children) && node.children.length) {
 			if (!entry.childrenProp) issues.push({
 				path: `${path}.children`,
@@ -378,17 +438,22 @@ async function validateSpec(spec, catalog, allowed, opts = {}) {
 				out.children = kids;
 			}
 		}
-		return issues.length > before ? null : out;
+		if (ownBad) {
+			nodes--;
+			return null;
+		}
+		return out;
 	}
 	const cleaned = await walk(spec, "root", 1, false);
-	if (issues.length || !cleaned) return {
+	if (!cleaned || issues.length && !opts.prune) return {
 		ok: false,
 		issues
 	};
 	return {
 		ok: true,
 		spec: cleaned,
-		nodes
+		nodes,
+		issues
 	};
 }
 /**
@@ -465,6 +530,185 @@ function replaceIn(node, target, next) {
 	return kids.some((c) => replaceIn(c, target, next));
 }
 //#endregion
+//#region src/renderer.tsx
+/**
+* Renders an Agentable Lang program as it streams. Each complete line is
+* parsed, the tree is validated against the catalog with bad nodes pruned,
+* and the rest draws immediately. Bindings, `when` and actions work exactly
+* as in <AgentSurface>; tool actions go to `tools` or the registry.
+*/
+function Renderer({ components, library, response, isStreaming = false, data, tools, onMessage, onError, onActionError, initialUi, onUiChange, placeholder, className }) {
+	const lib = useMemo(() => library ?? createLibrary(components), [library, components]);
+	const [store] = useState(() => createUiStore(initialUi ?? {}));
+	const ui = useSyncExternalStore(store.subscribe, store.get, store.get);
+	const agentable = useAgentable();
+	const snapshot = useAgentableSnapshot();
+	const [spec, setSpec] = useState(null);
+	const [actionError, setActionError] = useState(null);
+	const dataRef = useRef(data ?? {});
+	dataRef.current = data ?? {};
+	const toolsRef = useRef(tools);
+	toolsRef.current = tools;
+	const onMessageRef = useRef(onMessage);
+	onMessageRef.current = onMessage;
+	const onErrorRef = useRef(onError);
+	onErrorRef.current = onError;
+	const onActionErrorRef = useRef(onActionError);
+	onActionErrorRef.current = onActionError;
+	const onUiChangeRef = useRef(onUiChange);
+	onUiChangeRef.current = onUiChange;
+	useEffect(() => store.subscribe(() => onUiChangeRef.current?.(store.get())), [store]);
+	const registryTools = useMemo(() => {
+		const out = /* @__PURE__ */ new Map();
+		for (const c of snapshot.capabilities) if (c.toolName && c.declaredTier <= 1 && !out.has(c.toolName)) out.set(c.toolName, c.id);
+		return out;
+	}, [snapshot.capabilities]);
+	const registryRef = useRef(registryTools);
+	registryRef.current = registryTools;
+	const callable = useMemo(() => /* @__PURE__ */ new Set([...Object.keys(tools ?? {}), ...registryTools.keys()]), [tools, registryTools]);
+	const parsed = useMemo(() => lib.parse(isStreaming ? heldBack(response) : response), [
+		lib,
+		response,
+		isStreaming
+	]);
+	useEffect(() => {
+		let live = true;
+		const allowed = new Set(Object.keys(components));
+		const errors = parsed.errors.filter((e) => e.severity === "error" && (e.code !== "no-root" || !isStreaming)).map(fromLang);
+		if (!parsed.root) {
+			setSpec(null);
+			onErrorRef.current?.(errors);
+			return;
+		}
+		validateSpec(parsed.root, components, allowed, {
+			state: {
+				data: dataRef.current,
+				ui: store.get()
+			},
+			tools: callable,
+			prune: true,
+			maxNodes: 200
+		}).then((r) => {
+			if (!live) return;
+			if (r.ok) {
+				setSpec(r.spec);
+				onErrorRef.current?.([...errors, ...r.issues.map(fromIssue)]);
+			} else {
+				setSpec(null);
+				onErrorRef.current?.([...errors, ...r.issues.map(fromIssue)]);
+			}
+		});
+		return () => {
+			live = false;
+		};
+	}, [
+		parsed,
+		components,
+		callable,
+		isStreaming
+	]);
+	const fail = useCallback((message, node) => {
+		if (onActionErrorRef.current) onActionErrorRef.current(message, node);
+		else setActionError(message);
+	}, []);
+	const emit = useCallback((node, event, value) => {
+		const actions = node.on?.[event];
+		if (!actions?.length) return;
+		(async () => {
+			setActionError(null);
+			for (const raw of actions) {
+				const action = interpolate(raw, { value }, {
+					data: dataRef.current,
+					ui: store.get()
+				});
+				if (action.type === "message") {
+					if (!onMessageRef.current) return fail("Nothing is listening for messages here.", node);
+					onMessageRef.current(action.text, node);
+					continue;
+				}
+				if (action.type !== "tool") {
+					try {
+						store.dispatch(action);
+					} catch (e) {
+						return fail(e instanceof Error ? e.message : String(e), node);
+					}
+					continue;
+				}
+				let result;
+				const fn = toolsRef.current?.[action.name];
+				try {
+					if (fn) result = await fn(action.args ?? {});
+					else {
+						const capId = registryRef.current.get(action.name);
+						if (!agentable || !capId) return fail(`Tool "${action.name}" is not available.`, node);
+						result = parseResult$1(await agentable.invokeCapability(capId, action.args ?? {}));
+					}
+				} catch (e) {
+					return fail(e instanceof Error ? e.message : String(e), node);
+				}
+				if (result && typeof result === "object" && "error" in result) return fail(String(result.error), node);
+				if (action.into) store.dispatch({
+					type: "set",
+					path: action.into,
+					value: result
+				});
+			}
+		})();
+	}, [
+		agentable,
+		store,
+		fail
+	]);
+	const ctx = useMemo(() => ({
+		state: {
+			data: data ?? {},
+			ui
+		},
+		emit
+	}), [
+		data,
+		ui,
+		emit
+	]);
+	return /* @__PURE__ */ jsxs("div", {
+		className,
+		"data-agentable-surface": "",
+		"data-streaming": isStreaming ? "" : void 0,
+		"data-empty": spec ? void 0 : "",
+		children: [actionError ? /* @__PURE__ */ jsx("p", {
+			role: "alert",
+			"data-agentable-surface-error": "",
+			children: actionError
+		}) : null, spec ? /* @__PURE__ */ jsx("div", {
+			"data-agentable-surface-body": "",
+			inert: isStreaming || void 0,
+			children: renderSpec(spec, components, "0", ctx)
+		}) : placeholder ?? null]
+	});
+}
+/** While streaming, the last unterminated line is not parsed. */
+function heldBack(text) {
+	const nl = text.lastIndexOf("\n");
+	return nl < 0 ? "" : text.slice(0, nl + 1);
+}
+const fromLang = (e) => ({
+	code: e.code,
+	message: e.message,
+	line: e.line
+});
+const fromIssue = (i) => ({
+	code: "invalid-node",
+	message: i.message,
+	path: i.path
+});
+function parseResult$1(text) {
+	try {
+		return JSON.parse(text);
+	} catch {
+		return text;
+	}
+}
+//#endregion
 //#region src/index.tsx
 const ACTION_TYPES = [
 	"set",
@@ -583,6 +827,10 @@ function catalogSchema(catalog, allowed) {
 				anyOf: [{ $ref: "#/$defs/node" }, { type: "null" }],
 				description: "Tree to render; replaces the current one. null clears."
 			},
+			program: {
+				type: "string",
+				description: "The tree as a program, one node per line: `root = Stack([a, b])`, `a = Stat(\"Revenue\", \"$48k\")`. Same components; fewer tokens than root."
+			},
 			ops: {
 				type: "array",
 				items: { $ref: "#/$defs/op" },
@@ -630,7 +878,7 @@ function renderSpec(spec, catalog, key = "0", ctx) {
 * generated UI and an agent reach a tool through the same registry path, so
 * confirmation, caching and invalidation apply to both.
 */
-function AgentSurface({ components, name = "present", id, group, tier, priority, maxDepth = 6, maxNodes = 60, placeholder, onPresent, className, clearable = true, data, tools, stateTool, onActionError }) {
+function AgentSurface({ components, name = "present", id, group, tier, priority, maxDepth = 6, maxNodes = 60, placeholder, onPresent, className, clearable = true, data, tools, stateTool, onActionError, onMessage }) {
 	const [state, setState] = useState({
 		spec: null,
 		at: 0
@@ -644,8 +892,13 @@ function AgentSurface({ components, name = "present", id, group, tier, priority,
 	onPresentRef.current = onPresent;
 	const onActionErrorRef = useRef(onActionError);
 	onActionErrorRef.current = onActionError;
+	const onMessageRef = useRef(onMessage);
+	onMessageRef.current = onMessage;
 	const catalogRef = useRef(components);
 	catalogRef.current = components;
+	const library = useMemo(() => createLibrary(components), [components]);
+	const libraryRef = useRef(library);
+	libraryRef.current = library;
 	const specRef = useRef(state.spec);
 	specRef.current = state.spec;
 	const dataRef = useRef(data ?? {});
@@ -704,7 +957,7 @@ function AgentSurface({ components, name = "present", id, group, tier, priority,
 			const events = Object.keys(e.events ?? {});
 			return `${n}{${propSummary(schema)}}${e.childrenProp ? "+children" : ""}${events.length ? ` on:${events.join("|")}` : ""}`;
 		});
-		let text = "Render UI with this app's components: a tree of {component, props, children}. Nodes can bind props to state, run actions on events, and be patched by id via ops.";
+		let text = "Render UI with this app's components: a program (one `name = Component(args)` line per node) or a {component, props, children} tree. Nodes bind props to state, run actions on events, and can be patched by id via ops.";
 		if (readName) text += ` Call ${readName} for bindable data.`;
 		text += ` Components: ${lines.join(" ")}`;
 		if (text.length > 500) text = text.slice(0, 497) + "...";
@@ -729,10 +982,23 @@ function AgentSurface({ components, name = "present", id, group, tier, priority,
 			onPresentRef.current?.(null);
 			return { cleared: true };
 		}
-		if (args.root === void 0 && !args.ops?.length) return { error: "Send root to render a tree, ops to patch it, or root: null to clear." };
-		let tree = args.root ?? specRef.current;
+		let root = args.root;
+		if (typeof args.program === "string" && root === void 0) {
+			const parsed = libraryRef.current.parse(args.program);
+			const errors = parsed.errors.filter((e) => e.severity === "error");
+			if (!parsed.root || errors.length) return {
+				error: "Invalid program.",
+				issues: parsed.errors.map((e) => ({
+					path: `line ${e.line}`,
+					message: e.message
+				}))
+			};
+			root = parsed.root;
+		}
+		if (root === void 0 && !args.ops?.length) return { error: "Send program or root to render, ops to patch, or root: null to clear." };
+		let tree = root ?? specRef.current;
 		if (!tree) return { error: "Nothing is presented yet; send root first." };
-		const draft = createUiStore(args.root ? args.ui ?? {} : store.get());
+		const draft = createUiStore(root ? args.ui ?? {} : store.get());
 		try {
 			if (args.ops?.length) {
 				const patched = applyOps(tree, args.ops);
@@ -755,13 +1021,13 @@ function AgentSurface({ components, name = "present", id, group, tier, priority,
 			error: "Invalid UI spec.",
 			issues: result.issues
 		};
-		const title = args.title ?? (args.root ? void 0 : state.title);
+		const title = args.title ?? (root ? void 0 : state.title);
 		store.replace(draft.get());
 		setError(null);
 		setState({
 			spec: result.spec,
 			title,
-			at: args.root ? Date.now() : state.at
+			at: root ? Date.now() : state.at
 		});
 		onPresentRef.current?.(result.spec, title);
 		return {
@@ -827,8 +1093,8 @@ function AgentSurface({ components, name = "present", id, group, tier, priority,
 		}
 	} : null);
 	const fail = useCallback((message, node) => {
-		setError(message);
-		onActionErrorRef.current?.(message, node);
+		if (onActionErrorRef.current) onActionErrorRef.current(message, node);
+		else setError(message);
 	}, []);
 	const emit = useCallback((node, event, value) => {
 		const actions = node.on?.[event];
@@ -840,6 +1106,11 @@ function AgentSurface({ components, name = "present", id, group, tier, priority,
 					data: dataRef.current,
 					ui: store.get()
 				});
+				if (action.type === "message") {
+					if (!onMessageRef.current) return fail("Nothing is listening for messages here.", node);
+					onMessageRef.current(action.text, node);
+					continue;
+				}
 				if (action.type !== "tool") {
 					try {
 						store.dispatch(action);
@@ -944,4 +1215,4 @@ function shapeOf(value, depth = 0) {
 	return typeof value;
 }
 //#endregion
-export { AgentSurface, applyOps, catalogSchema, createUiStore, getPath, interpolate, isVisible, parsePath, renderSpec, resolveProps, validateSpec };
+export { AgentSurface, Renderer, applyOps, catalogSchema, createUiStore, getPath, interpolate, isVisible, parsePath, renderSpec, resolveProps, validateSpec };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agentable-ui/genui",
-  "version": "0.1.0",
-  "description": "Generative UI for Agentable: AgentSurface, catalog schema generation, validated rendering via a single present tool.",
+  "version": "0.3.1",
+  "description": "Generative UI for Agentable: a streaming Renderer for Agentable Lang programs, AgentSurface with a single validated present tool, catalog schema generation.",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,
@@ -34,8 +34,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@agentable-ui/core": "^0.1.0",
-    "@agentable-ui/react": "^0.1.0"
+    "@agentable-ui/react": "^0.1.1",
+    "@agentable-ui/lang": "^0.2.1",
+    "@agentable-ui/core": "^0.2.0"
   },
   "peerDependencies": {
     "react": "^18.2.0 || ^19.0.0"
@@ -46,7 +47,7 @@
     "@types/react": "^19.2.18",
     "@types/react-dom": "^19.2.7",
     "@testing-library/react": "^16.3.3",
-    "@agentable-ui/ui": "^0.1.0"
+    "@agentable-ui/ui": "^0.2.1"
   },
   "scripts": {
     "build": "tsdown",