@agentable-ui/genui 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agentable contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# @agentable-ui/genui
+
+Generative UI for Agentable: the agent describes what to render, you keep control of what can be rendered.
+
+```bash
+npm install @agentable-ui/genui @agentable-ui/ui @agentable-ui/react @agentable-ui/core
+```
+
+```tsx
+import { AgentSurface } from "@agentable-ui/genui";
+import { uiCatalog } from "@agentable-ui/ui";
+
+<AgentSurface components={uiCatalog} name="present" maxNodes={60} />;
+```
+
+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.
+
+## Why one tool
+
+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.
+
+## Validation
+
+`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.
+
+- `catalogSchema(catalog, allowed)` — the generated JSON Schema for the `present` tool.
+- `renderSpec(spec, catalog)` — render a validated spec yourself.
+
+## Interactive surfaces
+
+Nodes can do more than display props:
+
+```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.*` 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}}`.
+
+## Catalog entries
+
+```ts
+const catalog = {
+  Stat: {
+    component: Stat,
+    props: z.object({ label: z.string(), value: z.string(), delta: z.string().optional() }),
+    description: "A single headline number.",
+  },
+};
+```
+
+`props` accepts a JSON Schema object or any Standard Schema validator. `uiCatalog` from [`@agentable-ui/ui`](../ui) is a ready-made set.
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,221 @@
+import { ComponentType, ReactNode } from "react";
+import { JSONSchema, SchemaInput, Tier } from "@agentable-ui/core";
+//#region src/state.d.ts
+/**
+ * Surface state. Two roots: `data` is the app's, read-only to generated UI;
+ * `ui` belongs to the surface and is the only thing actions may write.
+ */
+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. */
+export declare function getPath(obj: unknown, path: string): unknown;
+type StateAction = {
+  type: "set";
+  path: string;
+  value: unknown;
+} | {
+  type: "merge";
+  path: string;
+  value: Record<string, unknown>;
+} | {
+  type: "push";
+  path: string;
+  value: unknown;
+} | {
+  type: "remove";
+  path: string;
+} | {
+  type: "increment";
+  path: string;
+  by?: number;
+} | {
+  type: "toggle";
+  path: string;
+};
+interface UiStore {
+  get(): Record<string, unknown>;
+  /** Apply actions all-or-nothing. Throws, leaving state untouched, if any fails. */
+  dispatch(actions: StateAction | StateAction[]): void;
+  replace(next: Record<string, unknown>): void;
+  subscribe(fn: () => void): () => void;
+}
+export declare function createUiStore(initial?: Record<string, unknown>): UiStore;
+/**
+ * Substitute `{{…}}` placeholders in action values.
+ *   {{value}} / {{value.id}}   the event's value, or a field of it
+ *   {{ui.x}} / {{data.x}}      surface state at the time of the event
+ * A string that is exactly one placeholder keeps the resolved type; embedded
+ * placeholders (e.g. "ui.rows[{{value}}].done") are stringified.
+ */
+export declare function interpolate<T>(input: T, payload: Record<string, unknown>, state: SurfaceState): T;
+//#endregion
+//#region src/spec.d.ts
+/** Call a tool through the registry. The result lands in `into` (a ui.* path) when given. */
+interface ToolAction {
+  type: "tool";
+  name: string;
+  args?: Record<string, unknown>;
+  into?: string;
+}
+type UIAction = StateAction | ToolAction;
+interface UISpec {
+  component: string;
+  /** Stable id, needed to target the node with patch ops. */
+  id?: string;
+  props?: Record<string, unknown>;
+  /** propName -> state path ("data.orders.open", "ui.selected.name"). Resolved on every render. */
+  bind?: Record<string, string>;
+  /** eventName -> actions, run in order when the component fires the event. */
+  on?: Record<string, UIAction[]>;
+  /** Render only while this state path is truthy ("!path" for falsy). */
+  when?: string;
+  children?: UISpec[];
+}
+/** Incremental edits to the presented tree. */
+type SurfaceOp = {
+  op: "add";
+  parent: string;
+  node: UISpec;
+  index?: number;
+} |
+/** Replace the node with the same id. Its children are kept unless `node.children` is given. */
+{
+  op: "update";
+  node: UISpec;
+} | {
+  op: "remove";
+  id: string;
+} |
+/** Write surface state; `path` must be under ui. */
+{
+  op: "set";
+  path: string;
+  value: unknown;
+};
+/** The slice of a catalog entry validation needs. */
+interface ValidatableEntry {
+  props: SchemaInput;
+  childrenProp?: string;
+  events?: Record<string, string>;
+}
+interface SpecIssue {
+  path: string;
+  message: string;
+}
+interface ValidateOptions {
+  maxDepth?: number;
+  maxNodes?: number;
+  /** State that bindings and `when` resolve against. Bound data.* paths must exist. */
+  state?: SurfaceState;
+  /** Tool names that `tool` actions may call. None when absent. */
+  tools?: ReadonlySet<string>;
+}
+export declare function isVisible(node: Pick<UISpec, "when">, state: SurfaceState): boolean;
+/** Static props overlaid with bound values that currently resolve. */
+export declare function resolveProps(node: UISpec, state: SurfaceState): Record<string, unknown>;
+/**
+ * Validate a spec against the catalog. Unknown props are dropped; unknown
+ * components, bad props, dangling data bindings and writes outside ui.* fail.
+ * Nodes hidden by `when` skip the checks that depend on bound values: their
+ * data (a selection, say) legitimately does not exist until they show.
+ */
+export declare function validateSpec(spec: UISpec, catalog: Record<string, ValidatableEntry>, allowed: Set<string>, opts?: ValidateOptions): Promise<{
+  ok: true;
+  spec: UISpec;
+  nodes: number;
+} | {
+  ok: false;
+  issues: SpecIssue[];
+}>;
+/**
+ * Apply patch ops to a tree. Returns the new tree plus the state writes to
+ * dispatch; throws with a message naming the op that failed. The caller
+ * validates the result before committing, so a bad batch changes nothing.
+ */
+export declare function applyOps(root: UISpec, ops: SurfaceOp[]): {
+  root: UISpec;
+  state: StateAction[];
+};
+//#endregion
+//#region src/index.d.ts
+export interface CatalogComponent<P = Record<string, unknown>> {
+  component: ComponentType<P>;
+  description: string;
+  props: SchemaInput;
+  childrenProp?: string;
+  /**
+   * Events the component can fire: event name -> callback prop. The callback's
+   * first argument becomes `{{value}}` in the node's actions, e.g.
+   * `{ change: "onChange" }` for an input that calls `onChange(nextValue)`.
+   */
+  events?: Record<string, string>;
+  /** Tier-gate the catalog entry. Tier 1 entries appear in `present` only after their group is opened. */
+  tier?: Tier;
+  group?: string;
+}
+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;
+  /** Patch the current tree (applied after `root` when both are given). */
+  ops?: SurfaceOp[];
+  /** ui.* state to start from when sending `root`. */
+  ui?: Record<string, unknown>;
+  /** Optional title shown above the rendered tree. */
+  title?: string;
+}
+/** Build the `present` input schema for the currently allowed components. */
+export declare function catalogSchema(catalog: Catalog, allowed: Iterable<string>): JSONSchema;
+/** How a rendered node reaches live state and fires its events. Omit for a static render. */
+export interface RenderContext {
+  state: SurfaceState;
+  emit: (node: UISpec, event: string, value: unknown) => void;
+}
+export declare function renderSpec(spec: UISpec, catalog: Catalog, key?: string, ctx?: RenderContext): ReactNode;
+export interface AgentSurfaceProps {
+  components: Catalog;
+  /** Tool name. Default "present". */
+  name?: string;
+  id?: string;
+  group?: string;
+  tier?: Tier;
+  priority?: number;
+  maxDepth?: number;
+  maxNodes?: number;
+  placeholder?: ReactNode;
+  onPresent?: (spec: UISpec | null, title?: string) => void;
+  className?: string;
+  /** Show a "clear" affordance. Default true. */
+  clearable?: boolean;
+  /** App data the agent may bind to as data.*. Read-only to generated UI; re-renders when it changes. */
+  data?: Record<string, unknown>;
+  /**
+   * Tools that `tool` actions may call. Default: every tool an agent can reach
+   * on this page (tier 0 and 1). `false` disables tool actions.
+   */
+  tools?: string[] | false;
+  /**
+   * Name of the read-only tool that returns surface state and the shape of
+   * `data`. Defaults to `<name>_state` when `data` is given; `false` omits it.
+   */
+  stateTool?: string | false;
+  /** Called when an action in the generated UI fails or is declined. */
+  onActionError?: (message: string, node: UISpec) => void;
+}
+/**
+ * Renders whatever the agent last called `present` with. Every catalog
+ * component is declared as a capability with a `render` descriptor, so the
+ * catalog is a projection of the same registry that holds the tools.
+ *
+ * Nodes can bind props to app data (data.*) or surface state (ui.*), and wire
+ * events to actions that write ui.* or call registered tools. A button in the
+ * 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;
+//#endregion
+export type { SpecIssue, StateAction, SurfaceOp, SurfaceState, ToolAction, UIAction, UISpec, UiStore, ValidateOptions };

package/dist/index.js

@@ -0,0 +1,947 @@
+import { Component, createElement, useCallback, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { toJsonSchema, validateInput } from "@agentable-ui/core";
+import { useAgentable, useAgentableSnapshot, useCapability } from "@agentable-ui/react";
+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. */
+const UNSAFE_KEYS = /* @__PURE__ */ new Set([
+	"__proto__",
+	"prototype",
+	"constructor"
+]);
+/** "a.b[0].c" -> ["a", "b", 0, "c"]. Throws on __proto__, prototype and constructor segments. */
+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}".`);
+	return keys;
+}
+/** Read a path, following own properties only. Undefined for missing or unsafe paths. */
+function getPath(obj, path) {
+	let keys;
+	try {
+		keys = parsePath(path);
+	} catch {
+		return;
+	}
+	let cur = obj;
+	for (const key of keys) {
+		if (cur == null || typeof cur !== "object" || !Object.hasOwn(cur, key)) return void 0;
+		cur = cur[key];
+	}
+	return cur;
+}
+/** True for "data.x" / "ui.x" (and "!ui.x" when `negatable`). */
+function isStatePath(path, roots = ["data", "ui"], negatable = false) {
+	if (typeof path !== "string") return false;
+	const p = negatable && path.startsWith("!") ? path.slice(1) : path;
+	let keys;
+	try {
+		keys = parsePath(p);
+	} catch {
+		return false;
+	}
+	const head = keys[0];
+	return typeof head === "string" && roots.includes(head) && keys.length > 1;
+}
+function setPath(obj, keys, value) {
+	if (!keys.length) throw new Error("Cannot replace the whole ui state.");
+	let cur = obj;
+	for (let i = 0; i < keys.length - 1; i++) {
+		const k = keys[i];
+		const next = keys[i + 1];
+		if (!Object.hasOwn(cur, k) || cur[k] == null || typeof cur[k] !== "object") cur[k] = typeof next === "number" ? [] : {};
+		cur = cur[k];
+	}
+	const last = keys[keys.length - 1];
+	if (value === void 0) {
+		if (Array.isArray(cur) && typeof last === "number") cur.splice(last, 1);
+		else delete cur[last];
+	} else cur[last] = value;
+}
+/** Keys under `ui` for a "ui.x.y" path. Throws for anything outside ui. */
+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}").`);
+	return keys.slice(1);
+}
+function reduce(ui, a) {
+	const keys = uiKeys(a.path);
+	const cur = getPath({ ui }, a.path);
+	switch (a.type) {
+		case "set": return setPath(ui, keys, a.value);
+		case "merge":
+			if (cur !== void 0 && (typeof cur !== "object" || cur === null || Array.isArray(cur))) throw new Error(`merge target "${a.path}" is not an object`);
+			return setPath(ui, keys, {
+				...cur,
+				...a.value
+			});
+		case "push":
+			if (cur !== void 0 && !Array.isArray(cur)) throw new Error(`push target "${a.path}" is not an array`);
+			return setPath(ui, keys, [...cur ?? [], a.value]);
+		case "remove": return setPath(ui, keys, void 0);
+		case "increment":
+			if (cur !== void 0 && typeof cur !== "number") throw new Error(`increment target "${a.path}" is not a number`);
+			return setPath(ui, keys, (cur ?? 0) + (a.by ?? 1));
+		case "toggle": return setPath(ui, keys, !cur);
+	}
+}
+function createUiStore(initial = {}) {
+	let ui = structuredClone(initial);
+	const listeners = /* @__PURE__ */ new Set();
+	const emit = () => listeners.forEach((l) => l());
+	return {
+		get: () => ui,
+		dispatch(actions) {
+			const list = Array.isArray(actions) ? actions : [actions];
+			const draft = structuredClone(ui);
+			for (const a of list) reduce(draft, a);
+			ui = draft;
+			emit();
+		},
+		replace(next) {
+			ui = structuredClone(next);
+			emit();
+		},
+		subscribe(fn) {
+			listeners.add(fn);
+			return () => {
+				listeners.delete(fn);
+			};
+		}
+	};
+}
+const PLACEHOLDER = /\{\{\s*([^}]+?)\s*\}\}/g;
+const WHOLE = /^\{\{\s*([^}]+?)\s*\}\}$/;
+function resolveExpr(expr, payload, state) {
+	if (isStatePath(expr)) return getPath(state, expr);
+	return getPath(payload, expr);
+}
+/**
+* Substitute `{{…}}` placeholders in action values.
+*   {{value}} / {{value.id}}   the event's value, or a field of it
+*   {{ui.x}} / {{data.x}}      surface state at the time of the event
+* A string that is exactly one placeholder keeps the resolved type; embedded
+* placeholders (e.g. "ui.rows[{{value}}].done") are stringified.
+*/
+function interpolate(input, payload, state) {
+	const sub = (v) => {
+		if (typeof v === "string") {
+			const whole = v.match(WHOLE);
+			if (whole) return resolveExpr(whole[1], payload, state) ?? null;
+			if (!v.includes("{{")) return v;
+			return v.replace(PLACEHOLDER, (_, expr) => {
+				const r = resolveExpr(expr, payload, state);
+				return r == null ? "" : typeof r === "object" ? JSON.stringify(r) : String(r);
+			});
+		}
+		if (Array.isArray(v)) return v.map(sub);
+		if (v && typeof v === "object") return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, sub(x)]));
+		return v;
+	};
+	return sub(input);
+}
+//#endregion
+//#region src/spec.ts
+const ID_PATTERN = /^[a-zA-Z0-9_-]+$/;
+const STATE_ACTIONS = /* @__PURE__ */ new Set([
+	"set",
+	"merge",
+	"push",
+	"remove",
+	"increment",
+	"toggle"
+]);
+function isVisible(node, state) {
+	if (!node.when) return true;
+	const neg = node.when.startsWith("!");
+	const v = getPath(state, neg ? node.when.slice(1) : node.when);
+	return neg ? !v : !!v;
+}
+/** Static props overlaid with bound values that currently resolve. */
+function resolveProps(node, state) {
+	const out = { ...node.props ?? {} };
+	for (const [prop, path] of Object.entries(node.bind ?? {})) {
+		const v = getPath(state, path);
+		if (v !== void 0) out[prop] = v;
+	}
+	return out;
+}
+const isObject = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+function actionIssues(a, path, tools) {
+	if (!isObject(a) || typeof a.type !== "string") return [{
+		path,
+		message: "Each action needs a type."
+	}];
+	if (a.type === "tool") {
+		const out = [];
+		if (typeof a.name !== "string" || !tools?.has(a.name)) {
+			const allowed = tools?.size ? [...tools].join(", ") : "(none)";
+			out.push({
+				path: `${path}.name`,
+				message: `Unknown tool "${String(a.name)}". Callable: ${allowed}.`
+			});
+		}
+		if (a.args !== void 0 && !isObject(a.args)) out.push({
+			path: `${path}.args`,
+			message: "args must be an object."
+		});
+		if (a.into !== void 0 && !isStatePath(a.into, ["ui"])) out.push({
+			path: `${path}.into`,
+			message: "into must be a ui.* path."
+		});
+		return out;
+	}
+	if (!STATE_ACTIONS.has(a.type)) return [{
+		path: `${path}.type`,
+		message: `Unknown action "${a.type}". Use set, merge, push, remove, increment, toggle or tool.`
+	}];
+	if (!isStatePath(a.path, ["ui"])) return [{
+		path: `${path}.path`,
+		message: "Actions may only write ui.* paths; data.* is read-only."
+	}];
+	if ((a.type === "set" || a.type === "push") && !("value" in a)) return [{
+		path,
+		message: `${a.type} needs a value.`
+	}];
+	if (a.type === "merge" && !isObject(a.value)) return [{
+		path: `${path}.value`,
+		message: "merge needs an object value."
+	}];
+	if (a.type === "increment" && a.by !== void 0 && typeof a.by !== "number") return [{
+		path: `${path}.by`,
+		message: "by must be a number."
+	}];
+	return [];
+}
+/**
+* Validate a spec against the catalog. Unknown props are dropped; unknown
+* components, bad props, dangling data bindings and writes outside ui.* fail.
+* Nodes hidden by `when` skip the checks that depend on bound values: their
+* data (a selection, say) legitimately does not exist until they show.
+*/
+async function validateSpec(spec, catalog, allowed, opts = {}) {
+	const maxDepth = opts.maxDepth ?? 6;
+	const maxNodes = opts.maxNodes ?? 60;
+	const state = opts.state ?? {
+		data: {},
+		ui: {}
+	};
+	const issues = [];
+	const ids = /* @__PURE__ */ new Set();
+	let nodes = 0;
+	async function walk(node, path, depth, parentHidden) {
+		nodes++;
+		if (nodes > maxNodes) {
+			issues.push({
+				path,
+				message: `More than ${maxNodes} nodes.`
+			});
+			return null;
+		}
+		if (depth > maxDepth) {
+			issues.push({
+				path,
+				message: `Deeper than ${maxDepth} levels.`
+			});
+			return null;
+		}
+		if (!node || typeof node !== "object" || typeof node.component !== "string") {
+			issues.push({
+				path,
+				message: "Each node needs a component name."
+			});
+			return null;
+		}
+		const entry = catalog[node.component];
+		if (!entry || !allowed.has(node.component)) {
+			issues.push({
+				path,
+				message: `Unknown component "${node.component}". Allowed: ${[...allowed].join(", ")}.`
+			});
+			return null;
+		}
+		const out = { component: node.component };
+		const before = issues.length;
+		if (node.id !== void 0) {
+			if (typeof node.id !== "string" || !ID_PATTERN.test(node.id)) issues.push({
+				path: `${path}.id`,
+				message: "id must match [a-zA-Z0-9_-]+."
+			});
+			else if (ids.has(node.id)) issues.push({
+				path: `${path}.id`,
+				message: `Duplicate id "${node.id}".`
+			});
+			else {
+				ids.add(node.id);
+				out.id = node.id;
+			}
+		}
+		if (node.when !== void 0) {
+			if (!isStatePath(node.when, ["data", "ui"], true)) issues.push({
+				path: `${path}.when`,
+				message: "when must be a state path like \"ui.selected\" or \"!data.done\"."
+			});
+			else out.when = node.when;
+		}
+		const hidden = parentHidden || out.when !== void 0 && !isVisible(out, state);
+		const schema = toJsonSchema(entry.props);
+		const known = new Set(Object.keys(schema.properties ?? {}));
+		const bind = {};
+		let unresolved = false;
+		if (node.bind !== void 0) {
+			if (!isObject(node.bind)) issues.push({
+				path: `${path}.bind`,
+				message: "bind must map prop names to state paths."
+			});
+			else for (const [prop, sp] of Object.entries(node.bind)) {
+				const at = `${path}.bind.${prop}`;
+				if (!known.has(prop)) issues.push({
+					path: at,
+					message: `"${node.component}" has no prop "${prop}".`
+				});
+				else if (!isStatePath(sp)) issues.push({
+					path: at,
+					message: "Bind to a state path under data.* or ui.*, e.g. \"data.orders.open\"."
+				});
+				else {
+					bind[prop] = sp;
+					if (getPath(state, sp) === void 0) {
+						unresolved = true;
+						if (!hidden && sp.startsWith("data.")) issues.push({
+							path: at,
+							message: `State path "${sp}" does not exist.`
+						});
+					}
+				}
+			}
+			if (Object.keys(bind).length) out.bind = bind;
+		}
+		const raw = isObject(node.props) ? node.props : {};
+		const cleaned = {};
+		for (const [k, v] of Object.entries(raw)) if (known.has(k)) cleaned[k] = v;
+		if (hidden || unresolved) out.props = cleaned;
+		else {
+			const result = await validateInput(entry.props, resolveProps({
+				...out,
+				props: cleaned
+			}, state));
+			if (!result.ok) for (const i of result.issues) issues.push({
+				path: `${path}.props${i.path ? "." + i.path : ""}`,
+				message: i.message
+			});
+			else {
+				const value = { ...result.value };
+				for (const prop of Object.keys(bind)) delete value[prop];
+				out.props = value;
+			}
+		}
+		if (node.on !== void 0) {
+			const events = entry.events ?? {};
+			if (!isObject(node.on)) issues.push({
+				path: `${path}.on`,
+				message: "on must map event names to action lists."
+			});
+			else {
+				const on = {};
+				for (const [ev, actions] of Object.entries(node.on)) {
+					const at = `${path}.on.${ev}`;
+					if (!(ev in events)) {
+						const names = Object.keys(events);
+						issues.push({
+							path: at,
+							message: `"${node.component}" has no event "${ev}".${names.length ? ` Events: ${names.join(", ")}.` : ""}`
+						});
+					} else if (!Array.isArray(actions)) issues.push({
+						path: at,
+						message: "Handlers are lists of actions."
+					});
+					else {
+						actions.forEach((a, i) => issues.push(...actionIssues(a, `${at}[${i}]`, opts.tools)));
+						on[ev] = actions;
+					}
+				}
+				if (Object.keys(on).length) out.on = on;
+			}
+		}
+		if (Array.isArray(node.children) && node.children.length) {
+			if (!entry.childrenProp) issues.push({
+				path: `${path}.children`,
+				message: `"${node.component}" does not accept children.`
+			});
+			else {
+				const kids = [];
+				for (let i = 0; i < node.children.length; i++) {
+					const kid = await walk(node.children[i], `${path}.children[${i}]`, depth + 1, hidden);
+					if (kid) kids.push(kid);
+				}
+				out.children = kids;
+			}
+		}
+		return issues.length > before ? null : out;
+	}
+	const cleaned = await walk(spec, "root", 1, false);
+	if (issues.length || !cleaned) return {
+		ok: false,
+		issues
+	};
+	return {
+		ok: true,
+		spec: cleaned,
+		nodes
+	};
+}
+/**
+* Apply patch ops to a tree. Returns the new tree plus the state writes to
+* dispatch; throws with a message naming the op that failed. The caller
+* validates the result before committing, so a bad batch changes nothing.
+*/
+function applyOps(root, ops) {
+	let tree = structuredClone(root);
+	const state = [];
+	const matches = (n, id) => n.id === id || id === "root" && n === tree;
+	ops.forEach((op, i) => {
+		const at = `ops[${i}]`;
+		if (!isObject(op)) throw new Error(`${at}: each op must be an object.`);
+		if (op.op === "set") {
+			state.push({
+				type: "set",
+				path: op.path,
+				value: op.value
+			});
+			return;
+		}
+		if (op.op === "add") {
+			const parent = find(tree, (n) => matches(n, op.parent));
+			if (!parent) throw new Error(`${at}: no node with id "${op.parent}".`);
+			const kids = parent.children ??= [];
+			const idx = typeof op.index === "number" ? Math.max(0, Math.min(op.index, kids.length)) : kids.length;
+			kids.splice(idx, 0, op.node);
+			return;
+		}
+		if (op.op === "update") {
+			const id = op.node?.id;
+			if (!id) throw new Error(`${at}: update needs node.id.`);
+			const target = find(tree, (n) => n.id === id);
+			if (!target) throw new Error(`${at}: no node with id "${id}".`);
+			const next = {
+				...op.node,
+				children: op.node.children ?? target.children
+			};
+			if (target === tree) tree = next;
+			else replaceIn(tree, target, next);
+			return;
+		}
+		if (op.op === "remove") {
+			const target = find(tree, (n) => n.id === op.id);
+			if (!target) throw new Error(`${at}: no node with id "${op.id}".`);
+			if (target === tree) throw new Error(`${at}: cannot remove the root; present null to clear.`);
+			replaceIn(tree, target, null);
+			return;
+		}
+		throw new Error(`${at}: unknown op "${String(op.op)}". Use add, update, remove or set.`);
+	});
+	return {
+		root: tree,
+		state
+	};
+}
+function find(node, pred) {
+	if (pred(node)) return node;
+	for (const c of node.children ?? []) {
+		const hit = find(c, pred);
+		if (hit) return hit;
+	}
+}
+function replaceIn(node, target, next) {
+	const kids = node.children;
+	if (!kids) return false;
+	const i = kids.indexOf(target);
+	if (i >= 0) {
+		if (next) kids[i] = next;
+		else kids.splice(i, 1);
+		return true;
+	}
+	return kids.some((c) => replaceIn(c, target, next));
+}
+//#endregion
+//#region src/index.tsx
+const ACTION_TYPES = [
+	"set",
+	"merge",
+	"push",
+	"remove",
+	"increment",
+	"toggle",
+	"tool"
+];
+/** Build the `present` input schema for the currently allowed components. */
+function catalogSchema(catalog, allowed) {
+	return {
+		type: "object",
+		$defs: {
+			node: {
+				type: "object",
+				properties: {
+					component: {
+						type: "string",
+						enum: [...allowed]
+					},
+					id: {
+						type: "string",
+						description: "Stable id; needed to patch this node with ops."
+					},
+					props: {
+						type: "object",
+						description: "Props for the component; see the tool description."
+					},
+					bind: {
+						type: "object",
+						additionalProperties: { type: "string" },
+						description: "Prop -> state path, e.g. {\"value\":\"data.revenue\"}. data.* is app data, ui.* is surface state."
+					},
+					on: {
+						type: "object",
+						additionalProperties: {
+							type: "array",
+							items: { $ref: "#/$defs/action" }
+						},
+						description: "Event -> actions, run in order."
+					},
+					when: {
+						type: "string",
+						description: "Render only while this path is truthy (\"!ui.x\" for falsy)."
+					},
+					children: {
+						type: "array",
+						items: { $ref: "#/$defs/node" }
+					}
+				},
+				required: ["component"]
+			},
+			action: {
+				type: "object",
+				properties: {
+					type: {
+						type: "string",
+						enum: ACTION_TYPES
+					},
+					path: {
+						type: "string",
+						description: "ui.* path to write."
+					},
+					value: {},
+					by: { type: "number" },
+					name: {
+						type: "string",
+						description: "tool: the tool to call."
+					},
+					args: {
+						type: "object",
+						description: "tool: arguments. {{value}} is the event value; {{ui.x}} and {{data.x}} read state."
+					},
+					into: {
+						type: "string",
+						description: "tool: ui.* path that receives the result."
+					}
+				},
+				required: ["type"]
+			},
+			op: {
+				type: "object",
+				properties: {
+					op: {
+						type: "string",
+						enum: [
+							"add",
+							"update",
+							"remove",
+							"set"
+						]
+					},
+					parent: {
+						type: "string",
+						description: "add: parent node id (\"root\" for the root)."
+					},
+					index: { type: "number" },
+					node: { $ref: "#/$defs/node" },
+					id: {
+						type: "string",
+						description: "remove: node id."
+					},
+					path: {
+						type: "string",
+						description: "set: ui.* path."
+					},
+					value: {}
+				},
+				required: ["op"]
+			}
+		},
+		properties: {
+			root: {
+				anyOf: [{ $ref: "#/$defs/node" }, { type: "null" }],
+				description: "Tree to render; replaces the current one. null clears."
+			},
+			ops: {
+				type: "array",
+				items: { $ref: "#/$defs/op" },
+				description: "Edit the current tree in place instead of resending it."
+			},
+			ui: {
+				type: "object",
+				description: "Initial ui.* state for a new root."
+			},
+			title: { type: "string" }
+		}
+	};
+}
+function propSummary(schema) {
+	const props = schema.properties ?? {};
+	const required = new Set(schema.required ?? []);
+	return Object.entries(props).map(([k, v]) => {
+		let t = Array.isArray(v.type) ? v.type.join("|") : String(v.type ?? "any");
+		if (Array.isArray(v.enum)) t = v.enum.map(String).join("|");
+		if (t === "array") t = `${v.items?.type ?? "any"}[]`;
+		return `${k}${required.has(k) ? "" : "?"}:${t}`;
+	}).join(",");
+}
+function renderSpec(spec, catalog, key = "0", ctx) {
+	const entry = catalog[spec.component];
+	if (!entry) return null;
+	if (ctx && !isVisible(spec, ctx.state)) return null;
+	const props = {
+		...ctx ? resolveProps(spec, ctx.state) : spec.props ?? {},
+		key
+	};
+	if (ctx && spec.on) {
+		for (const [event, prop] of Object.entries(entry.events ?? {})) if (spec.on[event]) props[prop] = (value) => ctx.emit(spec, event, value);
+	}
+	if (entry.childrenProp && spec.children?.length) props[entry.childrenProp] = spec.children.map((c, i) => renderSpec(c, catalog, `${key}.${c.id ?? i}`, ctx));
+	return createElement(entry.component, props);
+}
+/**
+* Renders whatever the agent last called `present` with. Every catalog
+* component is declared as a capability with a `render` descriptor, so the
+* catalog is a projection of the same registry that holds the tools.
+*
+* Nodes can bind props to app data (data.*) or surface state (ui.*), and wire
+* events to actions that write ui.* or call registered tools. A button in the
+* 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 }) {
+	const [state, setState] = useState({
+		spec: null,
+		at: 0
+	});
+	const [error, setError] = useState(null);
+	const [store] = useState(() => createUiStore());
+	const ui = useSyncExternalStore(store.subscribe, store.get, store.get);
+	const agentable = useAgentable();
+	const snapshot = useAgentableSnapshot();
+	const onPresentRef = useRef(onPresent);
+	onPresentRef.current = onPresent;
+	const onActionErrorRef = useRef(onActionError);
+	onActionErrorRef.current = onActionError;
+	const catalogRef = useRef(components);
+	catalogRef.current = components;
+	const specRef = useRef(state.spec);
+	specRef.current = state.spec;
+	const dataRef = useRef(data ?? {});
+	dataRef.current = data ?? {};
+	const baseId = id ?? `genui.${name}`;
+	const readName = stateTool === void 0 ? data ? `${name}_state` : false : stateTool;
+	const openGroups = useMemo(() => new Set(snapshot.groups.filter((g) => g.open).map((g) => g.name)), [snapshot.groups]);
+	const allowed = useMemo(() => {
+		const out = /* @__PURE__ */ new Set();
+		for (const [n, e] of Object.entries(components)) if ((e.tier ?? 0) === 0 || e.group && openGroups.has(e.group)) out.add(n);
+		return out;
+	}, [components, openGroups]);
+	const allowedKey = [...allowed].join(",");
+	const allowedRef = useRef(allowed);
+	allowedRef.current = allowed;
+	const callable = useMemo(() => {
+		const out = /* @__PURE__ */ new Map();
+		if (tools === false) return out;
+		const only = tools ? new Set(tools) : null;
+		for (const c of snapshot.capabilities) {
+			if (!c.toolName || c.declaredTier > 1 || c.id.startsWith(`${baseId}.`) || c.id === baseId) continue;
+			if (only && !only.has(c.toolName)) continue;
+			if (!out.has(c.toolName)) out.set(c.toolName, c.id);
+		}
+		return out;
+	}, [
+		snapshot.capabilities,
+		tools,
+		baseId
+	]);
+	const callableRef = useRef(callable);
+	callableRef.current = callable;
+	const entryCaps = useMemo(() => Object.entries(components).map(([n, e]) => ({
+		id: `${baseId}.catalog.${n}`,
+		group: e.group ?? group,
+		tier: e.tier ?? 0,
+		render: {
+			component: n,
+			props: e.props,
+			description: e.description
+		}
+	})), [
+		components,
+		baseId,
+		group
+	]);
+	const description = useMemo(() => {
+		const lines = [...allowed].map((n) => {
+			const e = components[n];
+			let schema;
+			try {
+				schema = toJsonSchema(e.props);
+			} catch {
+				schema = {};
+			}
+			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.";
+		if (readName) text += ` Call ${readName} for bindable data.`;
+		text += ` Components: ${lines.join(" ")}`;
+		if (text.length > 500) text = text.slice(0, 497) + "...";
+		return text;
+	}, [
+		allowedKey,
+		components,
+		readName
+	]);
+	const inputSchema = useMemo(() => catalogSchema(components, allowed), [components, allowed]);
+	const clear = useCallback(() => {
+		store.replace({});
+		setError(null);
+		setState({
+			spec: null,
+			at: Date.now()
+		});
+	}, [store]);
+	const execute = useCallback(async (args) => {
+		if (args.root === null) {
+			clear();
+			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;
+		if (!tree) return { error: "Nothing is presented yet; send root first." };
+		const draft = createUiStore(args.root ? args.ui ?? {} : store.get());
+		try {
+			if (args.ops?.length) {
+				const patched = applyOps(tree, args.ops);
+				tree = patched.root;
+				if (patched.state.length) draft.dispatch(patched.state);
+			}
+		} catch (e) {
+			return { error: e instanceof Error ? e.message : String(e) };
+		}
+		const result = await validateSpec(tree, catalogRef.current, allowedRef.current, {
+			maxDepth,
+			maxNodes,
+			state: {
+				data: dataRef.current,
+				ui: draft.get()
+			},
+			tools: new Set(callableRef.current.keys())
+		});
+		if (!result.ok) return {
+			error: "Invalid UI spec.",
+			issues: result.issues
+		};
+		const title = args.title ?? (args.root ? void 0 : state.title);
+		store.replace(draft.get());
+		setError(null);
+		setState({
+			spec: result.spec,
+			title,
+			at: args.root ? Date.now() : state.at
+		});
+		onPresentRef.current?.(result.spec, title);
+		return {
+			rendered: true,
+			nodes: result.nodes
+		};
+	}, [
+		maxDepth,
+		maxNodes,
+		store,
+		clear,
+		state.title,
+		state.at
+	]);
+	useCapability({
+		id: baseId,
+		group,
+		tier,
+		priority,
+		tool: {
+			name,
+			title: "Present UI",
+			description,
+			inputSchema,
+			annotations: {
+				readOnlyHint: false,
+				consequentialHint: false
+			},
+			confirm: false,
+			execute
+		}
+	});
+	useCapability(readName ? {
+		id: `${baseId}.state`,
+		group,
+		tier,
+		priority,
+		tool: {
+			name: readName,
+			title: "Read surface state",
+			description: `Read what ${name} can bind to. Without a path: the shape of data.*, current ui.* state and the presented tree. With a path (e.g. "data.orders"): that value.`,
+			inputSchema: {
+				type: "object",
+				properties: { path: {
+					type: "string",
+					description: "data.* or ui.* path."
+				} }
+			},
+			annotations: { readOnlyHint: true },
+			cache: false,
+			execute: ({ path }) => {
+				const s = {
+					data: dataRef.current,
+					ui: store.get()
+				};
+				if (path) return getPath(s, path) ?? null;
+				return {
+					data: shapeOf(s.data),
+					ui: s.ui,
+					tree: specRef.current
+				};
+			}
+		}
+	} : null);
+	const fail = useCallback((message, node) => {
+		setError(message);
+		onActionErrorRef.current?.(message, node);
+	}, []);
+	const emit = useCallback((node, event, value) => {
+		const actions = node.on?.[event];
+		if (!actions?.length) return;
+		(async () => {
+			setError(null);
+			for (const raw of actions) {
+				const action = interpolate(raw, { value }, {
+					data: dataRef.current,
+					ui: store.get()
+				});
+				if (action.type !== "tool") {
+					try {
+						store.dispatch(action);
+					} catch (e) {
+						return fail(e instanceof Error ? e.message : String(e), node);
+					}
+					continue;
+				}
+				const capId = callableRef.current.get(action.name);
+				if (!agentable || !capId) return fail(`Tool "${action.name}" is not available.`, node);
+				const result = parseResult(await agentable.invokeCapability(capId, action.args ?? {}));
+				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-empty": state.spec ? void 0 : "",
+		children: [entryCaps.map((c) => /* @__PURE__ */ jsx(DeclareRender, { cap: c }, c.id)), state.spec ? /* @__PURE__ */ jsxs(Fragment, { children: [
+			state.title || clearable ? /* @__PURE__ */ jsxs("div", {
+				"data-agentable-surface-header": "",
+				children: [state.title ? /* @__PURE__ */ jsx("h3", { children: state.title }) : /* @__PURE__ */ jsx("span", {}), clearable ? /* @__PURE__ */ jsx("button", {
+					type: "button",
+					onClick: clear,
+					"data-agentable-button": "",
+					"aria-label": "Clear agent output",
+					children: "Clear"
+				}) : null]
+			}) : null,
+			error ? /* @__PURE__ */ jsx("p", {
+				role: "alert",
+				"data-agentable-surface-error": "",
+				children: error
+			}) : null,
+			/* @__PURE__ */ jsx(SurfaceBoundary, { children: /* @__PURE__ */ jsx("div", {
+				"data-agentable-surface-body": "",
+				children: renderSpec(state.spec, components, "0", ctx)
+			}) }, state.at)
+		] }) : placeholder ?? null]
+	});
+}
+function DeclareRender({ cap }) {
+	useCapability(cap);
+	return null;
+}
+/** Bound values change after validation; a component that throws on them must not take the page down. */
+var SurfaceBoundary = class extends Component {
+	state = { failed: null };
+	static getDerivedStateFromError(e) {
+		return { failed: e instanceof Error ? e.message : String(e) };
+	}
+	render() {
+		if (this.state.failed) return /* @__PURE__ */ jsxs("p", {
+			role: "alert",
+			"data-agentable-surface-error": "",
+			children: ["This view failed to render: ", this.state.failed]
+		});
+		return this.props.children;
+	}
+};
+function parseResult(text) {
+	try {
+		return JSON.parse(text);
+	} catch {
+		return text;
+	}
+}
+/** A compact description of data for the agent: keys, array lengths, a sample item's fields. */
+function shapeOf(value, depth = 0) {
+	if (Array.isArray(value)) {
+		const first = value[0];
+		return first && typeof first === "object" && !Array.isArray(first) ? {
+			array: value.length,
+			item: Object.keys(first)
+		} : { array: value.length };
+	}
+	if (value && typeof value === "object") {
+		if (depth >= 2) return Object.keys(value);
+		return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, shapeOf(v, depth + 1)]));
+	}
+	return typeof value;
+}
+//#endregion
+export { AgentSurface, applyOps, catalogSchema, createUiStore, getPath, interpolate, isVisible, parsePath, renderSpec, resolveProps, validateSpec };

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@agentable-ui/genui",
+  "version": "0.1.0",
+  "description": "Generative UI for Agentable: AgentSurface, catalog schema generation, validated rendering via a single present tool.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/harsh071/agentable-ui",
+    "directory": "packages/genui"
+  },
+  "keywords": [
+    "webmcp",
+    "agent",
+    "mcp",
+    "components",
+    "react",
+    "modelContext"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@agentable-ui/core": "^0.1.0",
+    "@agentable-ui/react": "^0.1.0"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.7",
+    "@testing-library/react": "^16.3.3",
+    "@agentable-ui/ui": "^0.1.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}