@agentable-ui/genui 0.1.0 → 0.2.0

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;
@@ -61,7 +62,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 +119,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 +138,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 +153,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 +213,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 +259,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 +272,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, 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. */
@@ -192,9 +193,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 +369,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 +384,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 +476,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) => {
+		setActionError(message);
+		onActionErrorRef.current?.(message, node);
+	}, []);
+	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 +773,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 +824,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 +838,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 +903,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 +928,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 +967,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 {
@@ -840,6 +1052,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 +1161,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.2.0",
+  "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/core": "^0.1.1",
+    "@agentable-ui/react": "^0.1.0",
+    "@agentable-ui/lang": "^0.1.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.1.1"
   },
   "scripts": {
     "build": "tsdown",