@agentable-ui/lang 0.1.0 → 0.2.1

package/README.md

@@ -1,11 +1,13 @@
 # @agentable-ui/lang
 
-Agentable Lang: a compact, streaming-first language for model-generated UI. One node per line, rendered as it arrives, about half the tokens of the same tree as JSON. Framework-free; no model calls, no network.
+Parse, stream, and generate prompts for model-written UI programs. Each line names a component and its arguments. The package is framework-free and makes no model or network calls. Use [genui](../genui) to render the result.
 
 ```bash
 npm install @agentable-ui/lang @agentable-ui/core
 ```
 
+## Read a program
+
 ```txt
 root = Stack([stats, note])
 stats = StatGroup([rev, orders])
@@ -14,6 +16,10 @@ orders = Stat("Orders", 140, "+12", "up")
 note = Callout("On track", "Ahead of target by 4%.", "success")
 ```
 
+## Parse or stream a response
+
+The built-in catalog comes from `@agentable-ui/ui`; install it separately if you use this example. `createLibrary` also accepts your own catalog, without React.
+
 ```ts
 import { createLibrary } from "@agentable-ui/lang";
 import { uiCatalog } from "@agentable-ui/ui";
@@ -21,30 +27,33 @@ import { uiCatalog } from "@agentable-ui/ui";
 const library = createLibrary(uiCatalog);
 const system = library.prompt({ tools: [{ name: "refund_order", description: "Refund a paid order." }] });
 
-// Server: send `system` with the user's message to any model and stream the text back.
-// Client: <Renderer components={uiCatalog} response={text} isStreaming /> from @agentable-ui/genui,
-// or parse it yourself:
-const sp = library.stream();
-for await (const chunk of modelStream) {
-  const { root, errors } = sp.push(chunk);
-}
-sp.push("", true); // done
+// Your application sends system with the user's message to a model.
+// Parse a finished response:
+const result = library.parse('root = Text("Hello")');
+console.log(result.root, result.errors);
+
+// Or feed successive chunks to the streaming parser:
+const parser = library.stream();
+parser.push('root = Text("Hel');
+parser.push('lo")\n');
+const finished = parser.push("", true); // flush the final partial line
 ```
 
-## The language
+## Syntax at a glance
 
 - One statement per line: `name = Component(args)`. The entry is `root`. Forward references are fine; the last definition of a name wins.
 - Arguments are positional in the component's declared prop order, or named: `Callout("On track", text: "Ahead by 4%.")`. `null` skips an optional positional argument.
 - Children are a list of statement names, wherever they sit: `Stack([a, b])`, `Card("Title", [a, b])`, or `children: [a, b]`. A name may be used once.
 - Strings in double quotes, lists in `[]`, objects in `{key: value}`, numbers, `true`, `false`, `null`. `#` starts a comment.
 - State: `$data.x` reads app data (read-only); `$ui.x` is state the interface owns. A path given as an argument binds that prop: `rows: $data.paid`.
+- Read paths can filter and count lists: `$data.items[done=true]`, `$data.items[status!="archived"]`, `$data.items[done=true].length`. A missing boolean field counts as `false`. Filters are read-only; actions can't write through them.
 - `when: $ui.selected` shows a node while the path is truthy, `when: !$ui.done` while falsy.
 - Events are named arguments holding actions: `press: @Set($ui.selected, $event)` or a list `[@Set(...), @Tool(...)]`. `$event` is the event's value, `$event.id` a field of it.
 - Actions: `@Set(path, value)`, `@Merge(path, object)`, `@Push(path, value)`, `@Remove(path)`, `@Increment(path, by?)`, `@Toggle(path)`, `@Tool(name, args?, into?)`, `@Say(text)`. Written paths must be `$ui.*`.
 
 A bad line is dropped with a structured error and the rest still renders. Unknown components, unknown arguments, excess arguments and bad action arguments are reported with codes (`unknown-component`, `unknown-arg`, `excess-args`, `bad-arg`, `missing-required`, `parse-failed`, `cycle`, `reused-node`, `no-root`) a host can feed back to the model.
 
-## API
+## API reference
 
 - `createLibrary(catalog, { root? })` — a catalog is `{ Name: { description, props, childrenProp?, events? } }`; `props` is JSON Schema or any Standard Schema (zod 4, valibot 1). The `uiCatalog` from `@agentable-ui/ui` works as is.
 - `library.prompt({ preamble?, rules?, examples?, tools?, data?, interactive? })` — the system prompt: rules, one signature line per component, tools, an example.
@@ -55,4 +64,10 @@ A bad line is dropped with a structured error and the rest still renders. Unknow
 
 The node tree it produces is the same `{ component, props, bind, on, when, children }` shape `@agentable-ui/genui` validates and renders, so a program and a JSON tree are interchangeable everywhere, including the `present` tool.
 
-MIT
+## Rendering and error handling
+
+Parsing returns a tree and structured errors; it does not execute application tools. Pass the accumulated program to `Renderer` from `@agentable-ui/genui` to display it. In Lang, `$event` is the event payload; the JSON tree representation uses `{{value}}`.
+
+Handle `errors` and `unresolved` separately. Forward references can remain unresolved while streaming. Pass `done: true` on the final push so the parser processes the final line even without a newline. Token figures are estimates, not a guaranteed reduction compared with JSON.
+
+MIT licensed.

package/dist/index.js

@@ -207,10 +207,17 @@ var LineParser = class {
 				continue;
 			}
 			if (this.src[this.i] === "[") {
-				const m = /^\[(\d+)\]/.exec(this.src.slice(this.i));
-				if (!m) throw new Error(`Only numeric indexes are allowed in $${path}[...].`);
-				this.i += m[0].length;
-				path += `[${m[1]}]`;
+				const rest = this.src.slice(this.i);
+				const m = /^\[(\d+)\]/.exec(rest);
+				if (m) {
+					this.i += m[0].length;
+					path += `[${m[1]}]`;
+					continue;
+				}
+				const f = /^\[\s*([A-Za-z_][A-Za-z0-9_]*)\s*(!?=)\s*("[^"\]]*"|[A-Za-z0-9_.-]+)\s*\]/.exec(rest);
+				if (!f) throw new Error(`Use [0] or [field=value] in $${path}[...].`);
+				this.i += f[0].length;
+				path += `[${f[1]}${f[2]}${f[3]}]`;
 				continue;
 			}
 			return {
@@ -643,7 +650,10 @@ function evaluate(statements, signatures) {
 				out[p.name] = x.path;
 				continue;
 			}
-			if (x.kind === "null") continue;
+			if (x.kind === "null") {
+				if (p.kind === "value") out[p.name] = null;
+				continue;
+			}
 			const v = template(x, st, `${where} @${name}`);
 			if (v === void 0) continue;
 			if (p.kind === "string" && typeof v !== "string") {
@@ -719,7 +729,7 @@ function buildPrompt(lib, opts = {}) {
 		"Only the components listed below exist. Do not invent components, arguments or events.",
 		"Lines starting with # are comments. Do not wrap the program in code fences or add prose before or after it."
 	];
-	if (interactive) rules.push("State: `$data.x` reads app data (read-only); `$ui.x` is interface state you own. Pass a path as an argument to bind that prop, e.g. `rows: $data.paid`.", "`when: $ui.selected` shows a node only while that path is truthy; `when: !$ui.done` while it is falsy.", "Events take actions: `press: @Set($ui.selected, $event)` or a list `[@Set(...), @Tool(...)]`. `$event` is the value the event fired with; `$event.id` a field of it.", "Actions: @Set(path, value) @Merge(path, object) @Push(path, value) @Remove(path) @Increment(path, by?) @Toggle(path) @Tool(name, args?, into?) @Say(text). Paths written by actions must be $ui.*.");
+	if (interactive) rules.push("State: `$data.x` reads app data (read-only); `$ui.x` is interface state you own. Pass a path as an argument to bind that prop, e.g. `rows: $data.paid`.", "Read paths can filter lists and count them: `$data.items[done=true]`, `$data.items[status!=\"archived\"]`, `$data.items[done=true].length`. Filters are read-only; actions cannot write through them.", "`when: $ui.selected` shows a node only while that path is truthy; `when: !$ui.done` while it is falsy.", "Events take actions: `press: @Set($ui.selected, $event)` or a list `[@Set(...), @Tool(...)]`. `$event` is the value the event fired with; `$event.id` a field of it.", "Actions: @Set(path, value) @Merge(path, object) @Push(path, value) @Remove(path) @Increment(path, by?) @Toggle(path) @Tool(name, args?, into?) @Say(text). Paths written by actions must be $ui.*.");
 	rules.push(...opts.rules ?? []);
 	for (const r of rules) out.push(`- ${r}`);
 	out.push("");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentable-ui/lang",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Agentable Lang: a compact, streaming-first language for model-generated UI. Parser, streaming parser, prompt generation and serializer, framework-free.",
   "license": "MIT",
   "type": "module",
@@ -36,7 +36,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@agentable-ui/core": "^0.1.1"
+    "@agentable-ui/core": "^0.2.0"
   },
   "scripts": {
     "build": "tsdown",