@agentable-ui/genui 0.2.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

@@ -10,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";
@@ -274,4 +284,4 @@ export interface AgentSurfaceProps {
  */
 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 { MessageAction, RendererError, RendererProps, 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

@@ -10,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 {
@@ -27,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];
 	}
@@ -64,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) {
@@ -554,8 +608,8 @@ function Renderer({ components, library, response, isStreaming = false, data, to
 		isStreaming
 	]);
 	const fail = useCallback((message, node) => {
-		setActionError(message);
-		onActionErrorRef.current?.(message, node);
+		if (onActionErrorRef.current) onActionErrorRef.current(message, node);
+		else setActionError(message);
 	}, []);
 	const emit = useCallback((node, event, value) => {
 		const actions = node.on?.[event];
@@ -1039,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];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentable-ui/genui",
-  "version": "0.2.0",
+  "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",
@@ -34,9 +34,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@agentable-ui/core": "^0.1.1",
-    "@agentable-ui/react": "^0.1.0",
-    "@agentable-ui/lang": "^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"
@@ -47,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.1"
+    "@agentable-ui/ui": "^0.2.1"
   },
   "scripts": {
     "build": "tsdown",