@agentable-ui/lang 0.0.0-stage → 0.2.1

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

@@ -1,3 +1,73 @@
-# Temporary Holding Version
+# @agentable-ui/lang
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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])
+rev = Stat("Revenue", "$48.2k", "+6.1%", "up")
+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";
+
+const library = createLibrary(uiCatalog);
+const system = library.prompt({ tools: [{ name: "refund_order", description: "Refund a paid order." }] });
+
+// 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
+```
+
+## 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 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.
+- `library.parse(text)` — `{ root, nodes, unresolved, errors, chars, tokens }`.
+- `library.stream()` — `set(text, done?)` / `push(chunk, done?)`; the last unterminated line is held back until `done`.
+- `serialize(tree, library)` — a node tree as a program, root line first.
+- `parseProgram`, `evaluate`, `signatureLine`, `typeName` for lower-level use.
+
+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.
+
+## 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.d.ts

@@ -0,0 +1,230 @@
+import { JSONSchema, SchemaInput } from "@agentable-ui/core";
+//#region src/ast.d.ts
+/** The syntax tree of an Agentable Lang program: one statement per line, `name = Expression`. */
+type Expr = {
+  kind: "string";
+  value: string;
+} | {
+  kind: "number";
+  value: number;
+} | {
+  kind: "boolean";
+  value: boolean;
+} | {
+  kind: "null";
+} | {
+  kind: "array";
+  items: Expr[];
+} | {
+  kind: "object";
+  entries: Array<[string, Expr]>;
+} |
+/** Another statement's name: a node used as a child. */
+{
+  kind: "ref";
+  name: string;
+} |
+/** `$ui.selected.id`, `$data.rows`, `$event`; `!$ui.x` only in `when:`. */
+{
+  kind: "path";
+  path: string;
+  negated: boolean;
+} |
+/** `Component(args)` */
+{
+  kind: "call";
+  name: string;
+  args: Arg[];
+} |
+/** `@Action(args)` */
+{
+  kind: "action";
+  name: string;
+  args: Arg[];
+};
+interface Arg {
+  /** Named argument (`label: "x"`); positional when absent. */
+  name?: string;
+  expr: Expr;
+}
+interface Statement {
+  name: string;
+  expr: Expr;
+  /** 1-based line number in the program. */
+  line: number;
+}
+type ErrorCode = "parse-failed" | "unknown-component" | "unknown-action" | "unknown-arg" | "excess-args" | "missing-required" | "bad-arg" | "unresolved-ref" | "reused-node" | "cycle" | "no-root" | "not-a-component";
+interface LangError {
+  code: ErrorCode;
+  message: string;
+  /** 1-based line; 0 when the error is about the whole program. */
+  line: number;
+  /** "error" drops the statement or argument; "warning" keeps rendering. */
+  severity: "error" | "warning";
+}
+//#endregion
+//#region src/parser.d.ts
+interface Program {
+  statements: Statement[];
+  errors: LangError[];
+}
+/**
+ * Parse a whole program: one statement per line, `#` or `//` comments,
+ * blank lines ignored. A bad line is reported and skipped; the rest still
+ * parses. Later statements with the same name replace earlier ones.
+ */
+export declare function parseProgram(text: string): Program;
+/**
+ * Split streamed text into the part that is safe to parse and the trailing
+ * partial line. A program is complete only when `done` is true; until then
+ * the last unterminated line is held back.
+ */
+export declare function stableText(text: string, done: boolean): string;
+//#endregion
+//#region src/prompt.d.ts
+interface PromptOptions {
+  /** Opening paragraph; replaces the default. */
+  preamble?: string;
+  /** Extra rules appended to the language rules. */
+  rules?: string[];
+  /** Example programs; replace the default one. Each is `{ ask, program }`. */
+  examples?: Array<{
+    ask: string;
+    program: string;
+  }>;
+  /** Tools that @Tool may call: name and a one-line description. */
+  tools?: Array<{
+    name: string;
+    description?: string;
+  }>;
+  /** A compact description of $data.* the program may bind to (e.g. from genui's shapeOf). */
+  data?: unknown;
+  /** Set false to leave out the state and action rules for display-only use. */
+  interactive?: boolean;
+}
+/** Build the system prompt that teaches a model the language and this library. */
+export declare function buildPrompt(lib: Library, opts?: PromptOptions): string;
+//#endregion
+//#region src/library.d.ts
+/** What the language needs to know about a component. The same shape as a genui catalog entry; extra keys are ignored. */
+interface LibraryEntry {
+  description: string;
+  props: SchemaInput;
+  childrenProp?: string;
+  /** Event name -> callback prop. Only the keys matter here. */
+  events?: Record<string, string>;
+}
+type LibraryInput = Record<string, LibraryEntry>;
+/** The resolved, ordered contract of one component. */
+interface Signature {
+  name: string;
+  description: string;
+  /** Prop names in positional order. */
+  props: string[];
+  required: Set<string>;
+  /** Rendered `name?: type` per prop. */
+  types: Record<string, string>;
+  childrenProp?: string;
+  events: string[];
+  schema: JSONSchema;
+}
+interface ParseResult extends EvalResult {
+  /** True once the whole program is in; partial input renders what has arrived. */
+  complete: boolean;
+  /** Characters and estimated tokens of the program text parsed. */
+  chars: number;
+  tokens: number;
+}
+interface Library {
+  signatures: Record<string, Signature>;
+  root: string | undefined;
+  /** Parse and evaluate a complete program. */
+  parse(text: string): ParseResult;
+  /** A parser that accepts the text received so far; `set(text, done)` re-evaluates. */
+  stream(): StreamingParser;
+  /** The system prompt that teaches a model this library. */
+  prompt(options?: PromptOptions): string;
+  /** One line per component, as the prompt shows them. */
+  signatureLines(): string[];
+}
+interface StreamingParser {
+  /** Re-parse with the full text so far. The last unterminated line is held back until `done`. */
+  set(text: string, done?: boolean): ParseResult;
+  /** Append a chunk. */
+  push(chunk: string, done?: boolean): ParseResult;
+  result(): ParseResult;
+}
+export declare function createLibrary(components: LibraryInput, options?: {
+  root?: string;
+}): Library;
+/** A compact type for a prompt: string, number, "a"|"b", T[], {k: T}. */
+export declare function typeName(s: JSONSchema, depth: number): string;
+export declare function signatureLine(sig: Signature): string;
+//#endregion
+//#region src/evaluate.d.ts
+/** The node tree the renderer draws: structurally the same as @agentable-ui/genui's UISpec. */
+interface UINode {
+  component: string;
+  id?: string;
+  props?: Record<string, unknown>;
+  bind?: Record<string, string>;
+  on?: Record<string, UIAction[]>;
+  when?: string;
+  children?: UINode[];
+}
+type UIAction = {
+  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;
+} | {
+  type: "tool";
+  name: string;
+  args?: Record<string, unknown>;
+  into?: string;
+} | {
+  type: "message";
+  text: string;
+};
+interface EvalResult {
+  root: UINode | null;
+  /** Node count in `root`. */
+  nodes: number;
+  /** Names used as children that no statement defines yet. Expected while streaming. */
+  unresolved: string[];
+  errors: LangError[];
+}
+export declare const ACTION_NAMES: string[];
+/**
+ * Turn parsed statements into a node tree using the library's signatures.
+ * Positional arguments map to props in signature order, then to children.
+ * Named arguments may be props, `children`, `when`, or an event name.
+ */
+export declare function evaluate(statements: Statement[], signatures: Record<string, Signature>): EvalResult;
+//#endregion
+//#region src/serialize.d.ts
+/**
+ * Write a node tree as a program. Positional arguments are used while the
+ * props line up with the signature; named arguments after the first gap.
+ * Useful for showing a JSON spec as the language, and for measuring both.
+ */
+export declare function serialize(root: UINode, lib: Library): string;
+//#endregion
+export type { Arg, ErrorCode, EvalResult, Expr, LangError, Library, LibraryEntry, LibraryInput, ParseResult, Program, PromptOptions, Signature, Statement, StreamingParser, UIAction, UINode };

package/dist/index.js

@@ -0,0 +1,951 @@
+import { estimateTokens, toJsonSchema } from "@agentable-ui/core";
+//#region src/lexer.ts
+/**
+* A recursive-descent parser for one statement line. Kept deliberately
+* small: strings, numbers, booleans, null, arrays, objects, refs, $paths,
+* Component(args) and @Action(args).
+*/
+var LineParser = class {
+	src;
+	i = 0;
+	constructor(src) {
+		this.src = src;
+	}
+	/** Parse `name = expr`; throws a plain Error with a message on bad syntax. */
+	statement() {
+		this.ws();
+		const name = this.ident();
+		if (!name) throw new Error("A statement starts with a name, e.g. `root = Stack([...])`.");
+		this.ws();
+		if (!this.eat("=")) throw new Error(`Expected "=" after "${name}".`);
+		this.ws();
+		const expr = this.expr();
+		this.ws();
+		if (this.i < this.src.length) throw new Error(`Unexpected "${this.src[this.i]}" after the expression.`);
+		return {
+			name,
+			expr
+		};
+	}
+	ws() {
+		while (this.i < this.src.length && /\s/.test(this.src[this.i])) this.i++;
+	}
+	eat(s) {
+		if (this.src.startsWith(s, this.i)) {
+			this.i += s.length;
+			return true;
+		}
+		return false;
+	}
+	ident() {
+		const m = /^[A-Za-z_][A-Za-z0-9_-]*/.exec(this.src.slice(this.i));
+		if (!m) return null;
+		this.i += m[0].length;
+		return m[0];
+	}
+	expr() {
+		const c = this.src[this.i];
+		if (c === void 0) throw new Error("Expected a value.");
+		if (c === "\"" || c === "'") return {
+			kind: "string",
+			value: this.string()
+		};
+		if (c === "[") return this.array();
+		if (c === "{") return this.object();
+		if (c === "$") return this.path(false);
+		if (c === "!") {
+			this.i++;
+			this.ws();
+			if (this.src[this.i] !== "$") throw new Error("\"!\" may only negate a $path.");
+			return this.path(true);
+		}
+		if (c === "@") {
+			this.i++;
+			const name = this.ident();
+			if (!name) throw new Error("Expected an action name after \"@\".");
+			this.ws();
+			if (!this.eat("(")) throw new Error(`Expected "(" after @${name}.`);
+			return {
+				kind: "action",
+				name,
+				args: this.args()
+			};
+		}
+		if (c === "-" || /[0-9]/.test(c)) return this.number();
+		const name = this.ident();
+		if (!name) throw new Error(`Unexpected "${c}".`);
+		if (name === "true" || name === "false") return {
+			kind: "boolean",
+			value: name === "true"
+		};
+		if (name === "null") return { kind: "null" };
+		this.ws();
+		if (this.eat("(")) return {
+			kind: "call",
+			name,
+			args: this.args()
+		};
+		return {
+			kind: "ref",
+			name
+		};
+	}
+	/** After "(": comma-separated args, positional or `name: expr`, up to ")". */
+	args() {
+		const out = [];
+		this.ws();
+		if (this.eat(")")) return out;
+		for (;;) {
+			this.ws();
+			let name;
+			const save = this.i;
+			const id = this.ident();
+			this.ws();
+			if (id && this.eat(":")) {
+				name = id;
+				this.ws();
+			} else this.i = save;
+			const expr = this.expr();
+			out.push(name ? {
+				name,
+				expr
+			} : { expr });
+			this.ws();
+			if (this.eat(")")) return out;
+			if (!this.eat(",")) throw new Error("Expected \",\" or \")\" in the argument list.");
+		}
+	}
+	array() {
+		this.i++;
+		const items = [];
+		this.ws();
+		if (this.eat("]")) return {
+			kind: "array",
+			items
+		};
+		for (;;) {
+			this.ws();
+			items.push(this.expr());
+			this.ws();
+			if (this.eat("]")) return {
+				kind: "array",
+				items
+			};
+			if (!this.eat(",")) throw new Error("Expected \",\" or \"]\" in the list.");
+		}
+	}
+	object() {
+		this.i++;
+		const entries = [];
+		this.ws();
+		if (this.eat("}")) return {
+			kind: "object",
+			entries
+		};
+		for (;;) {
+			this.ws();
+			const c = this.src[this.i];
+			const key = c === "\"" || c === "'" ? this.string() : this.ident();
+			if (!key) throw new Error("Expected a key in the object.");
+			this.ws();
+			if (!this.eat(":")) throw new Error(`Expected ":" after key "${key}".`);
+			this.ws();
+			entries.push([key, this.expr()]);
+			this.ws();
+			if (this.eat("}")) return {
+				kind: "object",
+				entries
+			};
+			if (!this.eat(",")) throw new Error("Expected \",\" or \"}\" in the object.");
+		}
+	}
+	string() {
+		const quote = this.src[this.i];
+		this.i++;
+		let out = "";
+		for (;;) {
+			const c = this.src[this.i];
+			if (c === void 0) throw new Error("Unterminated string.");
+			this.i++;
+			if (c === quote) return out;
+			if (c === "\\") {
+				const n = this.src[this.i];
+				this.i++;
+				if (n === "n") out += "\n";
+				else if (n === "t") out += "	";
+				else if (n === "u") {
+					const hex = this.src.slice(this.i, this.i + 4);
+					if (!/^[0-9a-fA-F]{4}$/.test(hex)) throw new Error("Bad \\u escape.");
+					out += String.fromCharCode(parseInt(hex, 16));
+					this.i += 4;
+				} else if (n !== void 0) out += n;
+				continue;
+			}
+			out += c;
+		}
+	}
+	number() {
+		const m = /^-?\d+(\.\d+)?([eE][+-]?\d+)?/.exec(this.src.slice(this.i));
+		if (!m) throw new Error("Bad number.");
+		this.i += m[0].length;
+		return {
+			kind: "number",
+			value: Number(m[0])
+		};
+	}
+	path(negated) {
+		this.i++;
+		const head = this.ident();
+		if (!head) throw new Error("Expected a name after \"$\", e.g. $ui.selected.");
+		let path = head;
+		for (;;) {
+			if (this.src[this.i] === ".") {
+				this.i++;
+				const seg = this.ident();
+				if (!seg) throw new Error(`Expected a segment after "." in $${path}.`);
+				path += `.${seg}`;
+				continue;
+			}
+			if (this.src[this.i] === "[") {
+				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 {
+				kind: "path",
+				path,
+				negated
+			};
+		}
+	}
+};
+//#endregion
+//#region src/parser.ts
+/**
+* Parse a whole program: one statement per line, `#` or `//` comments,
+* blank lines ignored. A bad line is reported and skipped; the rest still
+* parses. Later statements with the same name replace earlier ones.
+*/
+function parseProgram(text) {
+	const statements = [];
+	const errors = [];
+	const byName = /* @__PURE__ */ new Map();
+	text.split(/\r?\n/).forEach((raw, idx) => {
+		const line = idx + 1;
+		const src = stripComment(raw);
+		if (!src.trim()) return;
+		try {
+			const { name, expr } = new LineParser(src).statement();
+			const st = {
+				name,
+				expr,
+				line
+			};
+			const prev = byName.get(name);
+			if (prev !== void 0) statements[prev] = st;
+			else {
+				byName.set(name, statements.length);
+				statements.push(st);
+			}
+		} catch (e) {
+			errors.push({
+				code: "parse-failed",
+				message: `Line ${line}: ${e instanceof Error ? e.message : String(e)}`,
+				line,
+				severity: "error"
+			});
+		}
+	});
+	return {
+		statements,
+		errors
+	};
+}
+/** Drop a trailing `# comment` or `// comment` outside of strings. */
+function stripComment(line) {
+	let quote = null;
+	for (let i = 0; i < line.length; i++) {
+		const c = line[i];
+		if (quote) {
+			if (c === "\\") i++;
+			else if (c === quote) quote = null;
+			continue;
+		}
+		if (c === "\"" || c === "'") quote = c;
+		else if (c === "#" || c === "/" && line[i + 1] === "/") return line.slice(0, i);
+	}
+	return line;
+}
+/**
+* Split streamed text into the part that is safe to parse and the trailing
+* partial line. A program is complete only when `done` is true; until then
+* the last unterminated line is held back.
+*/
+function stableText(text, done) {
+	if (done) return text;
+	const nl = text.lastIndexOf("\n");
+	return nl < 0 ? "" : text.slice(0, nl + 1);
+}
+//#endregion
+//#region src/evaluate.ts
+const isRefList = (x) => x.kind === "ref" || x.kind === "array" && x.items.every((i) => i.kind === "ref");
+/** Built-in actions: name -> positional parameters. `path` params must be $ui.* paths. */
+const ACTIONS = {
+	Set: {
+		type: "set",
+		params: [{
+			name: "path",
+			kind: "path",
+			required: true
+		}, {
+			name: "value",
+			kind: "value",
+			required: true
+		}]
+	},
+	Merge: {
+		type: "merge",
+		params: [{
+			name: "path",
+			kind: "path",
+			required: true
+		}, {
+			name: "value",
+			kind: "object",
+			required: true
+		}]
+	},
+	Push: {
+		type: "push",
+		params: [{
+			name: "path",
+			kind: "path",
+			required: true
+		}, {
+			name: "value",
+			kind: "value",
+			required: true
+		}]
+	},
+	Remove: {
+		type: "remove",
+		params: [{
+			name: "path",
+			kind: "path",
+			required: true
+		}]
+	},
+	Increment: {
+		type: "increment",
+		params: [{
+			name: "path",
+			kind: "path",
+			required: true
+		}, {
+			name: "by",
+			kind: "number"
+		}]
+	},
+	Toggle: {
+		type: "toggle",
+		params: [{
+			name: "path",
+			kind: "path",
+			required: true
+		}]
+	},
+	Tool: {
+		type: "tool",
+		params: [
+			{
+				name: "name",
+				kind: "string",
+				required: true
+			},
+			{
+				name: "args",
+				kind: "object"
+			},
+			{
+				name: "into",
+				kind: "path"
+			}
+		]
+	},
+	Say: {
+		type: "message",
+		params: [{
+			name: "text",
+			kind: "string",
+			required: true
+		}]
+	}
+};
+const ACTION_NAMES = Object.keys(ACTIONS);
+/**
+* Turn parsed statements into a node tree using the library's signatures.
+* Positional arguments map to props in signature order, then to children.
+* Named arguments may be props, `children`, `when`, or an event name.
+*/
+function evaluate(statements, signatures) {
+	const errors = [];
+	const unresolved = /* @__PURE__ */ new Set();
+	const byName = new Map(statements.map((s) => [s.name, s]));
+	const used = /* @__PURE__ */ new Set();
+	let nodes = 0;
+	const rootStatement = byName.get("root") ?? statements[0];
+	if (!rootStatement) return {
+		root: null,
+		nodes: 0,
+		unresolved: [],
+		errors
+	};
+	if (rootStatement.name !== "root") errors.push({
+		code: "no-root",
+		message: `No "root" statement; using "${rootStatement.name}".`,
+		line: rootStatement.line,
+		severity: "warning"
+	});
+	function node(st, stack) {
+		if (stack.includes(st.name)) {
+			errors.push({
+				code: "cycle",
+				message: `"${st.name}" contains itself.`,
+				line: st.line,
+				severity: "error"
+			});
+			return null;
+		}
+		if (used.has(st.name)) {
+			errors.push({
+				code: "reused-node",
+				message: `"${st.name}" is used in more than one place; define a second statement.`,
+				line: st.line,
+				severity: "error"
+			});
+			return null;
+		}
+		const e = st.expr;
+		if (e.kind !== "call") {
+			errors.push({
+				code: "not-a-component",
+				message: `"${st.name}" must be a component call like Card(...).`,
+				line: st.line,
+				severity: "error"
+			});
+			return null;
+		}
+		const sig = signatures[e.name];
+		if (!sig) {
+			errors.push({
+				code: "unknown-component",
+				message: `Unknown component "${e.name}". Components: ${Object.keys(signatures).join(", ")}.`,
+				line: st.line,
+				severity: "error"
+			});
+			return null;
+		}
+		used.add(st.name);
+		nodes++;
+		const out = {
+			component: e.name,
+			id: st.name
+		};
+		const props = {};
+		const bind = {};
+		const on = {};
+		let childExprs;
+		const slots = [...sig.props, ...sig.childrenProp ? ["children"] : []];
+		let pos = 0;
+		for (const arg of e.args) {
+			let key = arg.name;
+			if (!key) {
+				if (sig.childrenProp && isRefList(arg.expr)) key = "children";
+				else if (pos >= sig.props.length) {
+					errors.push({
+						code: "excess-args",
+						message: `${e.name} takes ${slots.length} arguments; extra ones dropped.`,
+						line: st.line,
+						severity: "warning"
+					});
+					break;
+				} else key = slots[pos++];
+			}
+			if (key === "children") {
+				if (!sig.childrenProp) errors.push({
+					code: "unknown-arg",
+					message: `${e.name} does not take children.`,
+					line: st.line,
+					severity: "warning"
+				});
+				else childExprs = arg.expr;
+				continue;
+			}
+			if (key === "when") {
+				if (arg.expr.kind !== "path" || !/^(ui|data)\./.test(arg.expr.path)) errors.push({
+					code: "bad-arg",
+					message: `when: must be a $ui.* or $data.* path.`,
+					line: st.line,
+					severity: "warning"
+				});
+				else out.when = `${arg.expr.negated ? "!" : ""}${arg.expr.path}`;
+				continue;
+			}
+			if (sig.events.includes(key)) {
+				const list = actionList(arg.expr, st, e.name, key);
+				if (list) on[key] = list;
+				continue;
+			}
+			if (!sig.props.includes(key)) {
+				errors.push({
+					code: "unknown-arg",
+					message: `${e.name} has no argument "${key}". Arguments: ${slots.join(", ")}${sig.events.length ? `; events: ${sig.events.join(", ")}` : ""}.`,
+					line: st.line,
+					severity: "warning"
+				});
+				continue;
+			}
+			if (arg.expr.kind === "null") continue;
+			if (arg.expr.kind === "path") {
+				if (arg.expr.negated || !/^(ui|data)\./.test(arg.expr.path)) errors.push({
+					code: "bad-arg",
+					message: `${key}: bind to a $ui.* or $data.* path.`,
+					line: st.line,
+					severity: "warning"
+				});
+				else bind[key] = arg.expr.path;
+				continue;
+			}
+			const v = literal(arg.expr, st, `${e.name}(${key})`);
+			if (v !== void 0) props[key] = v;
+		}
+		if (Object.keys(props).length) out.props = props;
+		if (Object.keys(bind).length) out.bind = bind;
+		if (Object.keys(on).length) out.on = on;
+		if (childExprs) {
+			const items = childExprs.kind === "array" ? childExprs.items : [childExprs];
+			const kids = [];
+			for (const item of items) {
+				if (item.kind !== "ref") {
+					errors.push({
+						code: "bad-arg",
+						message: `${e.name} children must be names of other statements.`,
+						line: st.line,
+						severity: "warning"
+					});
+					continue;
+				}
+				const target = byName.get(item.name);
+				if (!target) {
+					unresolved.add(item.name);
+					continue;
+				}
+				const kid = node(target, [...stack, st.name]);
+				if (kid) kids.push(kid);
+			}
+			out.children = kids;
+		}
+		return out;
+	}
+	/** Literal JSON for a prop: no refs, paths or actions inside. */
+	function literal(x, st, where) {
+		switch (x.kind) {
+			case "string":
+			case "number":
+			case "boolean": return x.value;
+			case "null": return null;
+			case "array": return x.items.map((i) => literal(i, st, where)).filter((v) => v !== void 0);
+			case "object": return Object.fromEntries(x.entries.map(([k, v]) => [k, literal(v, st, where)]).filter(([, v]) => v !== void 0));
+			default:
+				errors.push({
+					code: "bad-arg",
+					message: `${where}: ${x.kind === "ref" ? "a node reference" : x.kind === "path" ? "a $path" : "a call"} is not allowed inside a value. Bind a whole prop with $ui.x or $data.x instead.`,
+					line: st.line,
+					severity: "warning"
+				});
+				return;
+		}
+	}
+	/** Action argument: paths become {{templates}} resolved when the event fires. */
+	function template(x, st, where) {
+		switch (x.kind) {
+			case "path":
+				if (x.negated) {
+					errors.push({
+						code: "bad-arg",
+						message: `${where}: "!" is only allowed in when:.`,
+						line: st.line,
+						severity: "warning"
+					});
+					return;
+				}
+				return `{{${x.path === "event" ? "value" : x.path.startsWith("event.") ? `value.${x.path.slice(6)}` : x.path}}}`;
+			case "array": return x.items.map((i) => template(i, st, where)).filter((v) => v !== void 0);
+			case "object": return Object.fromEntries(x.entries.map(([k, v]) => [k, template(v, st, where)]).filter(([, v]) => v !== void 0));
+			default: return literal(x, st, where);
+		}
+	}
+	function actionList(x, st, comp, event) {
+		const items = x.kind === "array" ? x.items : [x];
+		const out = [];
+		for (const item of items) {
+			if (item.kind !== "action") {
+				errors.push({
+					code: "bad-arg",
+					message: `${comp} ${event}: expected an @Action, e.g. @Set($ui.x, $event).`,
+					line: st.line,
+					severity: "warning"
+				});
+				continue;
+			}
+			const a = action(item.name, item.args, st, `${comp} ${event}`);
+			if (a) out.push(a);
+		}
+		return out.length ? out : null;
+	}
+	function action(name, args, st, where) {
+		const def = ACTIONS[name];
+		if (!def) {
+			errors.push({
+				code: "unknown-action",
+				message: `${where}: unknown action @${name}. Actions: ${ACTION_NAMES.map((n) => `@${n}`).join(", ")}.`,
+				line: st.line,
+				severity: "warning"
+			});
+			return null;
+		}
+		const out = { type: def.type };
+		let pos = 0;
+		for (const arg of args) {
+			const p = arg.name ? def.params.find((q) => q.name === arg.name) : def.params[pos++];
+			if (!p) {
+				errors.push({
+					code: "excess-args",
+					message: `${where}: @${name} takes ${def.params.map((q) => q.name).join(", ")}.`,
+					line: st.line,
+					severity: "warning"
+				});
+				continue;
+			}
+			const x = arg.expr;
+			if (p.kind === "path") {
+				if (x.kind !== "path" || x.negated || !x.path.startsWith("ui.")) {
+					errors.push({
+						code: "bad-arg",
+						message: `${where}: @${name} ${p.name} must be a $ui.* path.`,
+						line: st.line,
+						severity: "warning"
+					});
+					return null;
+				}
+				out[p.name] = x.path;
+				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") {
+				errors.push({
+					code: "bad-arg",
+					message: `${where}: @${name} ${p.name} must be a string.`,
+					line: st.line,
+					severity: "warning"
+				});
+				return null;
+			}
+			if (p.kind === "number" && typeof v !== "number") {
+				errors.push({
+					code: "bad-arg",
+					message: `${where}: @${name} ${p.name} must be a number.`,
+					line: st.line,
+					severity: "warning"
+				});
+				return null;
+			}
+			if (p.kind === "object" && (typeof v !== "object" || v === null || Array.isArray(v))) {
+				errors.push({
+					code: "bad-arg",
+					message: `${where}: @${name} ${p.name} must be an object.`,
+					line: st.line,
+					severity: "warning"
+				});
+				return null;
+			}
+			out[p.name] = v;
+		}
+		for (const p of def.params) if (p.required && out[p.name] === void 0) {
+			errors.push({
+				code: "missing-required",
+				message: `${where}: @${name} needs ${p.name}.`,
+				line: st.line,
+				severity: "warning"
+			});
+			return null;
+		}
+		return out;
+	}
+	return {
+		root: node(rootStatement, []),
+		nodes,
+		unresolved: [...unresolved],
+		errors
+	};
+}
+//#endregion
+//#region src/prompt.ts
+const DEFAULT_EXAMPLE = {
+	ask: "Show August revenue, orders and refunds, and a note that we are on track.",
+	program: `root = Stack([stats, note])
+stats = StatGroup([rev, orders, refunds])
+rev = Stat("Revenue", "$48.2k", "+6.1%", "up")
+orders = Stat("Orders", "140", "+12", "up")
+refunds = Stat("Refunds", "9", "-2", "down")
+note = Callout("On track", "Revenue is ahead of target by 4%.", "success")`
+};
+/** Build the system prompt that teaches a model the language and this library. */
+function buildPrompt(lib, opts = {}) {
+	const interactive = opts.interactive ?? true;
+	const out = [];
+	out.push(opts.preamble ?? "You answer by writing a user interface in Agentable Lang, a small line-based language. Each line defines one node: `name = Component(args)`. The host renders the lines as they stream, so write the root first and keep programs short.");
+	out.push("");
+	out.push("Rules:");
+	const rules = [
+		"One statement per line, `name = Component(...)`. Names are [a-zA-Z0-9_-]. The entry is the statement named `root`.",
+		"Arguments are positional in the order shown below, or named (`kind: \"success\"`). Use `null` to skip an optional positional argument.",
+		"Children are a list of statement names, `Stack([a, b])` or `Card(\"Title\", [a, b])`; a bare list anywhere in the arguments is the children. A name may be used once. Forward references are fine.",
+		"Strings use double quotes. Lists use [], objects use {key: value}. Numbers, true, false and null are literal.",
+		"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`.", "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("");
+	out.push("Components:");
+	for (const line of lib.signatureLines()) out.push(`- ${line}`);
+	if (interactive && opts.tools?.length) {
+		out.push("");
+		out.push("Tools @Tool may call (the host confirms consequential ones with the user):");
+		for (const t of opts.tools) out.push(`- ${t.name}${t.description ? `: ${t.description}` : ""}`);
+	}
+	if (interactive && opts.data !== void 0) {
+		out.push("");
+		out.push(`Shape of $data: ${JSON.stringify(opts.data)}`);
+	}
+	const examples = opts.examples ?? [DEFAULT_EXAMPLE];
+	if (examples.length) {
+		out.push("");
+		out.push(examples.length > 1 ? "Examples:" : "Example:");
+		for (const ex of examples) {
+			out.push(`Ask: ${ex.ask}`);
+			out.push("Program:");
+			out.push(ex.program.trim());
+			out.push("");
+		}
+		out.pop();
+	}
+	return out.join("\n");
+}
+//#endregion
+//#region src/library.ts
+function createLibrary(components, options = {}) {
+	const signatures = {};
+	for (const [name, entry] of Object.entries(components)) signatures[name] = signature(name, entry);
+	if (options.root && !signatures[options.root]) throw new Error(`root "${options.root}" is not in the library.`);
+	const parseText = (text, complete) => {
+		const program = parseProgram(text);
+		const evaluated = evaluate(program.statements, signatures);
+		let errors = [...program.errors, ...evaluated.errors];
+		if (!complete) errors = errors.filter((e) => e.code !== "no-root");
+		return {
+			...evaluated,
+			errors,
+			complete,
+			chars: text.length,
+			tokens: estimateTokens(text.length)
+		};
+	};
+	const lib = {
+		signatures,
+		root: options.root,
+		parse: (text) => parseText(text, true),
+		stream() {
+			let buffer = "";
+			let last = parseText("", false);
+			const set = (text, done = false) => {
+				buffer = text;
+				last = parseText(stableText(text, done), done);
+				return last;
+			};
+			return {
+				set,
+				push: (chunk, done) => set(buffer + chunk, done),
+				result: () => last
+			};
+		},
+		prompt: (opts) => buildPrompt(lib, opts),
+		signatureLines: () => Object.values(signatures).map(signatureLine)
+	};
+	return lib;
+}
+function signature(name, entry) {
+	let schema;
+	try {
+		schema = toJsonSchema(entry.props);
+	} catch {
+		schema = {
+			type: "object",
+			properties: {}
+		};
+	}
+	const properties = schema.properties ?? {};
+	const required = new Set((schema.required ?? []).filter((k) => k in properties));
+	const props = Object.keys(properties);
+	const types = {};
+	for (const p of props) types[p] = typeName(properties[p], 0);
+	return {
+		name,
+		description: entry.description,
+		props,
+		required,
+		types,
+		childrenProp: entry.childrenProp,
+		events: Object.keys(entry.events ?? {}),
+		schema
+	};
+}
+/** A compact type for a prompt: string, number, "a"|"b", T[], {k: T}. */
+function typeName(s, depth) {
+	if (Array.isArray(s.enum)) return s.enum.map((v) => JSON.stringify(v)).join("|");
+	if (Array.isArray(s.anyOf)) return s.anyOf.map((x) => typeName(x, depth)).join("|");
+	if (Array.isArray(s.oneOf)) return s.oneOf.map((x) => typeName(x, depth)).join("|");
+	const t = Array.isArray(s.type) ? s.type : s.type ? [String(s.type)] : [];
+	if (t.length > 1) return t.map((x) => typeName({
+		...s,
+		type: x
+	}, depth)).join("|");
+	const type = t[0] ?? "any";
+	if (type === "array") return `${typeName(s.items ?? {}, depth + 1)}[]`;
+	if (type === "object") {
+		const props = s.properties ?? {};
+		const keys = Object.keys(props);
+		if (!keys.length || depth >= 2) return "object";
+		const req = new Set(s.required ?? []);
+		return `{${keys.map((k) => `${k}${req.has(k) ? "" : "?"}: ${typeName(props[k], depth + 1)}`).join(", ")}}`;
+	}
+	if (type === "integer") return "number";
+	return type;
+}
+function signatureLine(sig) {
+	const args = sig.props.map((p) => `${p}${sig.required.has(p) ? "" : "?"}: ${sig.types[p]}`);
+	if (sig.childrenProp) args.push("children?: [nodes]");
+	const events = sig.events.length ? ` · events: ${sig.events.join(", ")}` : "";
+	return `${sig.name}(${args.join(", ")})${events} — ${sig.description}`;
+}
+//#endregion
+//#region src/serialize.ts
+/**
+* Write a node tree as a program. Positional arguments are used while the
+* props line up with the signature; named arguments after the first gap.
+* Useful for showing a JSON spec as the language, and for measuring both.
+*/
+function serialize(root, lib) {
+	const lines = [];
+	const taken = /* @__PURE__ */ new Set();
+	const nameFor = (n, i) => {
+		let base = n.id ?? `${n.component.toLowerCase()}${i}`;
+		if (!/^[A-Za-z_][A-Za-z0-9_-]*$/.test(base)) base = `n${i}`;
+		let name = base;
+		let k = 2;
+		while (taken.has(name)) name = `${base}${k++}`;
+		taken.add(name);
+		return name;
+	};
+	let counter = 0;
+	const walk = (n, forced) => {
+		const name = forced ?? nameFor(n, counter++);
+		const at = lines.length;
+		lines.push("");
+		const kids = (n.children ?? []).map((c) => walk(c));
+		lines[at] = `${name} = ${call(n, kids, lib)}`;
+		return name;
+	};
+	taken.add("root");
+	walk(root, "root");
+	return lines.join("\n");
+}
+function call(n, kids, lib) {
+	const sig = lib.signatures[n.component];
+	const props = n.props ?? {};
+	const bind = n.bind ?? {};
+	const args = [];
+	let positional = true;
+	const order = sig?.props ?? Object.keys(props);
+	for (const p of order) {
+		if (!(p in props || p in bind)) {
+			positional = false;
+			continue;
+		}
+		const v = p in bind ? `$${bind[p]}` : value(props[p]);
+		args.push(positional ? v : `${p}: ${v}`);
+	}
+	for (const p of Object.keys(props)) if (!order.includes(p)) args.push(`${p}: ${value(props[p])}`);
+	if (kids.length) args.push(positional && sig?.childrenProp ? `[${kids.join(", ")}]` : `children: [${kids.join(", ")}]`);
+	if (n.when) args.push(`when: ${n.when.startsWith("!") ? `!$${n.when.slice(1)}` : `$${n.when}`}`);
+	for (const [ev, actions] of Object.entries(n.on ?? {})) {
+		const list = actions.map(action);
+		args.push(`${ev}: ${list.length === 1 ? list[0] : `[${list.join(", ")}]`}`);
+	}
+	return `${n.component}(${args.join(", ")})`;
+}
+function action(a) {
+	switch (a.type) {
+		case "set": return `@Set($${a.path}, ${template(a.value)})`;
+		case "merge": return `@Merge($${a.path}, ${template(a.value)})`;
+		case "push": return `@Push($${a.path}, ${template(a.value)})`;
+		case "remove": return `@Remove($${a.path})`;
+		case "increment": return a.by === void 0 ? `@Increment($${a.path})` : `@Increment($${a.path}, ${a.by})`;
+		case "toggle": return `@Toggle($${a.path})`;
+		case "tool": {
+			const parts = [JSON.stringify(a.name)];
+			if (a.args) parts.push(template(a.args));
+			if (a.into) parts.push(`$${a.into}`);
+			return `@Tool(${parts.join(", ")})`;
+		}
+		case "message": return `@Say(${JSON.stringify(a.text)})`;
+	}
+}
+/** {{value}} -> $event, {{ui.x}} -> $ui.x; anything else is a literal. */
+function template(v) {
+	if (typeof v === "string") {
+		const m = /^\{\{\s*([^}]+?)\s*\}\}$/.exec(v);
+		if (m) {
+			const p = m[1];
+			return p === "value" ? "$event" : p.startsWith("value.") ? `$event.${p.slice(6)}` : `$${p}`;
+		}
+		return JSON.stringify(v);
+	}
+	if (Array.isArray(v)) return `[${v.map(template).join(", ")}]`;
+	if (v && typeof v === "object") return `{${Object.entries(v).map(([k, x]) => `${key(k)}: ${template(x)}`).join(", ")}}`;
+	return JSON.stringify(v) ?? "null";
+}
+function value(v) {
+	if (Array.isArray(v)) return `[${v.map(value).join(", ")}]`;
+	if (v && typeof v === "object") return `{${Object.entries(v).map(([k, x]) => `${key(k)}: ${value(x)}`).join(", ")}}`;
+	return JSON.stringify(v) ?? "null";
+}
+const key = (k) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(k) ? k : JSON.stringify(k);
+//#endregion
+export { ACTION_NAMES, buildPrompt, createLibrary, evaluate, parseProgram, serialize, signatureLine, stableText, typeName };

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@agentable-ui/lang",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "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",
+  "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/lang"
+  },
+  "keywords": [
+    "generative-ui",
+    "genui",
+    "webmcp",
+    "agent",
+    "mcp",
+    "components",
+    "react",
+    "streaming"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@agentable-ui/core": "^0.2.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
 }