@ulearning/ai-generative-frame 0.0.0-stage → 1.0.0-next.0

package/dist/spec/calc.js

@@ -0,0 +1,498 @@
+import { getAtPointer, parsePointer } from "./pointer.js";
+// src/spec/calc.ts
+const isNumber = (value) => typeof value === "number" && Number.isFinite(value);
+const normalize = (value) => value === void 0 || typeof value === "number" && !Number.isFinite(value) ? null : value;
+const pointerTokens = (path) => {
+	try {
+		return parsePointer(path && !path.startsWith("/") ? `/${path}` : path);
+	} catch {
+		return [];
+	}
+};
+const readPath = (base, path) => getAtPointer(base, pointerTokens(path));
+const readReference = (path, ctx) => {
+	if (path === "$index") return ctx.index;
+	if (path === "$item") return ctx.item;
+	if (path.startsWith("$item/")) return readPath(ctx.item, path.slice(5));
+	if (path === "$event") return ctx.event;
+	if (path.startsWith("$event/")) return readPath(ctx.event, path.slice(6));
+	return readPath(ctx.state, path);
+};
+const eachChild = (value, visit) => {
+	if (Array.isArray(value)) {
+		for (let index = 0; index < value.length; index++) if (Object.hasOwn(value, index) && !visit(value[index], String(index))) return false;
+		return true;
+	}
+	for (const key in value) if (Object.hasOwn(value, key) && !visit(value[key], key)) return false;
+	return true;
+};
+const visitAll = (value, step) => {
+	step();
+	if (typeof value === "object" && value !== null) eachChild(value, (child) => {
+		visitAll(child, step);
+		return true;
+	});
+};
+const formatText = (value, step) => {
+	if (value === null || value === void 0) return "";
+	if (typeof value !== "object") return String(value);
+	visitAll(value, step);
+	return JSON.stringify(value);
+};
+const fractionDigits = (value) => Math.max(0, Math.min(20, Math.trunc(value)));
+const numeric = (fn) => (args) => args.every(isNumber) ? fn(...args) : null;
+const aggregate = (operation, args, step) => {
+	const [list, field] = args;
+	if (!Array.isArray(list) || args.length > 2) return null;
+	if (args.length === 2 && typeof field !== "string") return null;
+	if (typeof field === "string" && field.length > 500) return null;
+	const tokens = typeof field === "string" ? pointerTokens(field) : void 0;
+	if (tokens && tokens.length > 32) return null;
+	let total = 0;
+	let count = 0;
+	let extreme = null;
+	for (const item of list) {
+		step();
+		const value = tokens ? getAtPointer(item, tokens) : item;
+		if (!isNumber(value)) continue;
+		total += value;
+		count++;
+		if (extreme === null) extreme = value;
+		else if (operation === "min") extreme = Math.min(extreme, value);
+		else if (operation === "max") extreme = Math.max(extreme, value);
+	}
+	if (operation === "sum") return total;
+	if (operation === "avg") return count ? total / count : null;
+	return extreme;
+};
+const formatters = /* @__PURE__ */ new Map();
+const formatNumber = (value, options) => {
+	if (!isNumber(value)) return null;
+	const key = JSON.stringify(options);
+	let formatter = formatters.get(key);
+	if (!formatter) {
+		try {
+			formatter = new Intl.NumberFormat("en-US", options);
+		} catch {
+			return null;
+		}
+		if (formatters.size >= 64) formatters.clear();
+		formatters.set(key, formatter);
+	}
+	return formatter.format(value);
+};
+const decimalFormat = (args, style) => {
+	const [value, digits] = args;
+	if (args.length === 1) return formatNumber(value, { style });
+	if (!isNumber(digits)) return null;
+	const precision = fractionDigits(digits);
+	return formatNumber(value, {
+		style,
+		minimumFractionDigits: precision,
+		maximumFractionDigits: precision
+	});
+};
+const functions = new Map([
+	["round", {
+		min: 1,
+		max: 2,
+		run: numeric((x, digits = 0) => {
+			const scale = 10 ** fractionDigits(digits);
+			return Math.round(x * scale) / scale;
+		})
+	}],
+	["floor", {
+		min: 1,
+		max: 1,
+		run: numeric(Math.floor)
+	}],
+	["ceil", {
+		min: 1,
+		max: 1,
+		run: numeric(Math.ceil)
+	}],
+	["abs", {
+		min: 1,
+		max: 1,
+		run: numeric(Math.abs)
+	}],
+	["clamp", {
+		min: 3,
+		max: 3,
+		run: numeric((x, low, high) => Math.min(Math.max(x, low), high))
+	}],
+	...["min", "max"].map((name) => [name, {
+		min: 1,
+		max: Infinity,
+		run: (args, step) => Array.isArray(args[0]) ? aggregate(name, args, step) : numeric(name === "min" ? Math.min : Math.max)(args, step)
+	}]),
+	["count", {
+		min: 1,
+		max: 1,
+		run: ([list]) => Array.isArray(list) ? list.length : null
+	}],
+	...["sum", "avg"].map((name) => [name, {
+		min: 1,
+		max: 2,
+		run: (args, step) => aggregate(name, args, step)
+	}]),
+	["number", {
+		min: 1,
+		max: 2,
+		run: (args) => decimalFormat(args, "decimal")
+	}],
+	["currency", {
+		min: 2,
+		max: 2,
+		run: ([value, code]) => typeof code === "string" ? formatNumber(value, {
+			style: "currency",
+			currency: code
+		}) : null
+	}],
+	["percent", {
+		min: 1,
+		max: 2,
+		run: (args) => decimalFormat(args, "percent")
+	}],
+	["time", {
+		min: 1,
+		max: 1,
+		run: ([value]) => {
+			if (!isNumber(value)) return null;
+			const minutes = (Math.round(value) % 1440 + 1440) % 1440;
+			const hour = Math.floor(minutes / 60);
+			return `${hour % 12 || 12}:${String(minutes % 60).padStart(2, "0")} ${hour < 12 ? "AM" : "PM"}`;
+		}
+	}],
+	["plural", {
+		min: 3,
+		max: 3,
+		run: ([n, one, other]) => n === 1 ? one : other
+	}]
+]);
+const tokenize = (formula) => {
+	const tokens = [];
+	let offset = 0;
+	while (offset < formula.length) {
+		const char = formula[offset];
+		if (/\s/.test(char)) offset++;
+		else if (char === "'" || char === "\"") {
+			offset++;
+			let value = "";
+			while (offset < formula.length && formula[offset] !== char) {
+				let next = formula[offset++];
+				if (next === "\\") {
+					next = formula[offset++] ?? "";
+					if (next !== "\\" && next !== "'" && next !== "\"") throw new Error("Invalid string escape");
+				}
+				value += next;
+			}
+			if (offset >= formula.length) throw new Error("Unterminated string");
+			offset++;
+			tokens.push({
+				kind: "literal",
+				value
+			});
+		} else if (char === "$" && formula[offset + 1] === "{") {
+			const end = formula.indexOf("}", offset + 2);
+			if (end === -1) throw new Error("Unterminated reference");
+			tokens.push({
+				kind: "reference",
+				text: formula.slice(offset + 2, end).trim()
+			});
+			offset = end + 1;
+		} else if (/[0-9]/.test(char)) {
+			const start = offset++;
+			while (/[0-9]/.test(formula[offset] ?? "")) offset++;
+			if (formula[offset] === "." && /[0-9]/.test(formula[offset + 1] ?? "")) {
+				offset++;
+				while (/[0-9]/.test(formula[offset] ?? "")) offset++;
+			}
+			tokens.push({
+				kind: "literal",
+				value: Number(formula.slice(start, offset))
+			});
+		} else if (/[a-zA-Z_]/.test(char)) {
+			const start = offset++;
+			while (/[a-zA-Z0-9_]/.test(formula[offset] ?? "")) offset++;
+			const name = formula.slice(start, offset);
+			if (name === "true" || name === "false" || name === "null") tokens.push({
+				kind: "literal",
+				value: name === "null" ? null : name === "true"
+			});
+			else tokens.push({
+				kind: "name",
+				text: name
+			});
+		} else {
+			const pair = formula.slice(offset, offset + 2);
+			if ([
+				"||",
+				"&&",
+				"==",
+				"!=",
+				"<=",
+				">="
+			].includes(pair)) {
+				tokens.push({
+					kind: "symbol",
+					text: pair
+				});
+				offset += 2;
+			} else if ("?:<>+-*/%!(),".includes(char)) {
+				tokens.push({
+					kind: "symbol",
+					text: char
+				});
+				offset++;
+			} else throw new Error(`Unexpected token "${char}"`);
+		}
+	}
+	tokens.push({ kind: "end" });
+	return tokens;
+};
+const precedence = [
+	["||"],
+	["&&"],
+	["==", "!="],
+	[
+		"<",
+		"<=",
+		">",
+		">="
+	],
+	["+", "-"],
+	[
+		"*",
+		"/",
+		"%"
+	]
+];
+const parse = (formula) => {
+	const tokens = tokenize(formula);
+	let position = 0;
+	const current = () => tokens[position];
+	const match = (symbol) => {
+		const token = current();
+		if (token.kind !== "symbol" || token.text !== symbol) return false;
+		position++;
+		return true;
+	};
+	const expect = (symbol) => {
+		if (!match(symbol)) throw new Error(`Expected "${symbol}"`);
+	};
+	const checkDepth = (depth) => {
+		if (depth > 32) throw new Error("Formula exceeds 32 levels of nesting");
+	};
+	const primary = (depth) => {
+		checkDepth(depth);
+		const token = current();
+		position++;
+		if (token.kind === "literal") return token;
+		if (token.kind === "reference") return {
+			kind: "reference",
+			path: token.text
+		};
+		if (token.kind === "symbol" && token.text === "(") {
+			const node = conditional(depth + 1);
+			expect(")");
+			return node;
+		}
+		if (token.kind === "name") {
+			const fn = functions.get(token.text);
+			if (!fn) throw new Error(`Unknown function "${token.text}"; known: ${[...functions.keys()].join(", ")}`);
+			checkDepth(depth + 1);
+			expect("(");
+			const args = [];
+			if (!match(")")) {
+				do
+					args.push(conditional(depth + 1));
+				while (match(","));
+				expect(")");
+			}
+			if (args.length < fn.min || args.length > fn.max) throw new Error(`Wrong argument count for "${token.text}"`);
+			return {
+				kind: "call",
+				name: token.text,
+				args
+			};
+		}
+		throw new Error("Expected a value");
+	};
+	const unary = (depth) => {
+		checkDepth(depth);
+		const token = current();
+		if (token.kind === "symbol" && (token.text === "-" || token.text === "!")) {
+			position++;
+			return {
+				kind: "unary",
+				operator: token.text,
+				operand: unary(depth + 1)
+			};
+		}
+		return primary(depth);
+	};
+	const binary = (level, depth) => {
+		const operators = precedence[level];
+		if (!operators) return unary(depth);
+		let left = binary(level + 1, depth);
+		for (;;) {
+			const token = current();
+			if (token.kind !== "symbol" || !operators.includes(token.text)) return left;
+			position++;
+			left = {
+				kind: "binary",
+				operator: token.text,
+				left,
+				right: binary(level + 1, depth)
+			};
+		}
+	};
+	const conditional = (depth) => {
+		const condition = binary(0, depth);
+		if (!match("?")) return condition;
+		const then = conditional(depth + 1);
+		expect(":");
+		return {
+			kind: "conditional",
+			condition,
+			then,
+			otherwise: conditional(depth + 1)
+		};
+	};
+	const node = conditional(0);
+	if (current().kind !== "end") throw new Error("Unexpected trailing token");
+	return node;
+};
+const parsedFormulas = /* @__PURE__ */ new Map();
+const parsedFormula = (formula) => {
+	if (formula.length > 500) return "Formula exceeds 500 characters";
+	const cached = parsedFormulas.get(formula);
+	if (cached !== void 0) return cached;
+	let result;
+	try {
+		result = parse(formula);
+	} catch (error) {
+		result = error instanceof Error ? error.message : "Invalid formula";
+	}
+	if (parsedFormulas.size >= 500) parsedFormulas.clear();
+	parsedFormulas.set(formula, result);
+	return result;
+};
+const childCount = (value, step) => {
+	let count = 0;
+	eachChild(value, () => {
+		step();
+		count++;
+		return true;
+	});
+	return count;
+};
+const equal = (a, b, step) => {
+	step();
+	if (a === b) return true;
+	if (typeof a !== "object" || typeof b !== "object" || !a || !b) return false;
+	if (Array.isArray(a) !== Array.isArray(b)) return false;
+	if (childCount(a, step) !== childCount(b, step)) return false;
+	return eachChild(a, (child, key) => equal(child, b[key], step));
+};
+const calculate = (operator, left, right, step) => {
+	if (operator === "==") return equal(left, right, step);
+	if (operator === "!=") return !equal(left, right, step);
+	if (operator === "+" && (typeof left === "string" || typeof right === "string")) return formatText(left, step) + formatText(right, step);
+	if ([
+		"<",
+		"<=",
+		">",
+		">="
+	].includes(operator)) {
+		if (!(typeof left === "number" && typeof right === "number") && !(typeof left === "string" && typeof right === "string")) return false;
+		if (operator === "<") return left < right;
+		if (operator === "<=") return left <= right;
+		if (operator === ">") return left > right;
+		return left >= right;
+	}
+	if (!isNumber(left) || !isNumber(right)) return null;
+	switch (operator) {
+		case "+": return left + right;
+		case "-": return left - right;
+		case "*": return left * right;
+		case "/": return right === 0 ? null : left / right;
+		case "%": return right === 0 ? null : left % right;
+		default: return null;
+	}
+};
+const evaluate = (node, ctx, step) => {
+	step();
+	const visit = (child) => normalize(evaluate(child, ctx, step));
+	switch (node.kind) {
+		case "literal": return node.value;
+		case "reference": return readReference(node.path, ctx);
+		case "unary": {
+			const value = visit(node.operand);
+			return node.operator === "!" ? !value : isNumber(value) ? -value : null;
+		}
+		case "conditional": return visit(node.condition) ? visit(node.then) : visit(node.otherwise);
+		case "call": return functions.get(node.name).run(node.args.map(visit), step);
+		case "binary": {
+			const left = visit(node.left);
+			if (node.operator === "&&") return Boolean(left) && Boolean(visit(node.right));
+			if (node.operator === "||") return Boolean(left) || Boolean(visit(node.right));
+			return calculate(node.operator, left, visit(node.right), step);
+		}
+	}
+};
+/** Evaluates a bounded formula, returning null when it cannot run. */
+function evaluateFormula(formula, ctx) {
+	try {
+		const node = parsedFormula(formula);
+		if (typeof node === "string") return null;
+		let steps = 0;
+		return normalize(evaluate(node, ctx, () => {
+			if (++steps > 1e4) throw new Error("Formula exceeds 10000 evaluation steps");
+		}));
+	} catch {
+		return null;
+	}
+}
+/** The state paths a formula shows as values, leaving out reads under a condition and reads in the `?` branch of a condition on that same path, which only runs while it has a value. */
+function formulaValueReads(formula) {
+	const node = parsedFormula(formula);
+	if (typeof node === "string") return [];
+	const reads = /* @__PURE__ */ new Set();
+	const visit = (current, condition, guarded) => {
+		switch (current.kind) {
+			case "literal": return;
+			case "reference":
+				if (!condition && !current.path.startsWith("$") && !guarded.has(current.path)) reads.add(current.path);
+				return;
+			case "unary":
+				visit(current.operand, condition || current.operator === "!", guarded);
+				return;
+			case "binary": {
+				const logical = current.operator === "&&" || current.operator === "||";
+				visit(current.left, condition || logical, guarded);
+				visit(current.right, condition || logical, guarded);
+				return;
+			}
+			case "conditional":
+				visit(current.condition, true, guarded);
+				visit(current.then, condition, current.condition.kind === "reference" ? /* @__PURE__ */ new Set([...guarded, current.condition.path]) : guarded);
+				visit(current.otherwise, condition, guarded);
+				return;
+			case "call":
+				for (const arg of current.args) visit(arg, condition, guarded);
+				return;
+		}
+	};
+	visit(node, false, /* @__PURE__ */ new Set());
+	return [...reads];
+}
+/** Why a formula cannot run, or undefined when it parses within the bounds. */
+function formulaIssue(formula) {
+	const result = parsedFormula(formula);
+	return typeof result === "string" ? result : void 0;
+}
+export { evaluateFormula, formulaIssue, formulaValueReads };
+
+//# sourceMappingURL=calc.js.map

package/dist/spec/calc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"calc.js","names":[],"sources":["../../src/spec/calc.ts"],"sourcesContent":["import type { ExpressionContext } from \"./expressions\";\nimport { getAtPointer, parsePointer } from \"./pointer\";\n\ntype Node =\n  | { kind: \"literal\"; value: unknown }\n  | { kind: \"reference\"; path: string }\n  | { kind: \"unary\"; operator: string; operand: Node }\n  | { kind: \"binary\"; operator: string; left: Node; right: Node }\n  | { kind: \"conditional\"; condition: Node; then: Node; otherwise: Node }\n  | { kind: \"call\"; name: string; args: Node[] };\n\ntype Token =\n  | { kind: \"literal\"; value: unknown }\n  | { kind: \"reference\" | \"name\" | \"symbol\"; text: string }\n  | { kind: \"end\" };\n\ntype FormulaFunction = {\n  min: number;\n  max: number;\n  run: (args: unknown[], step: () => void) => unknown;\n};\n\nconst isNumber = (value: unknown): value is number =>\n  typeof value === \"number\" && Number.isFinite(value);\n\nconst normalize = (value: unknown): unknown =>\n  value === undefined || (typeof value === \"number\" && !Number.isFinite(value))\n    ? null\n    : value;\n\nconst pointerTokens = (path: string) => {\n  try {\n    return parsePointer(path && !path.startsWith(\"/\") ? `/${path}` : path);\n  } catch {\n    return [];\n  }\n};\n\nconst readPath = (base: unknown, path: string) =>\n  getAtPointer(base, pointerTokens(path));\n\nconst readReference = (path: string, ctx: ExpressionContext) => {\n  if (path === \"$index\") return ctx.index;\n  if (path === \"$item\") return ctx.item;\n  if (path.startsWith(\"$item/\")) return readPath(ctx.item, path.slice(5));\n  if (path === \"$event\") return ctx.event;\n  if (path.startsWith(\"$event/\")) return readPath(ctx.event, path.slice(6));\n  return readPath(ctx.state, path);\n};\n\nconst eachChild = (\n  value: object,\n  visit: (child: unknown, key: string) => boolean,\n) => {\n  if (Array.isArray(value)) {\n    for (let index = 0; index < value.length; index++) {\n      if (Object.hasOwn(value, index) && !visit(value[index], String(index))) {\n        return false;\n      }\n    }\n    return true;\n  }\n  for (const key in value) {\n    if (\n      Object.hasOwn(value, key) &&\n      !visit((value as Record<string, unknown>)[key], key)\n    ) {\n      return false;\n    }\n  }\n  return true;\n};\n\nconst visitAll = (value: unknown, step: () => void): void => {\n  step();\n  if (typeof value === \"object\" && value !== null) {\n    eachChild(value, (child) => {\n      visitAll(child, step);\n      return true;\n    });\n  }\n};\n\nconst formatText = (value: unknown, step: () => void) => {\n  if (value === null || value === undefined) return \"\";\n  if (typeof value !== \"object\") return String(value);\n  visitAll(value, step);\n  return JSON.stringify(value);\n};\n\nconst fractionDigits = (value: number) =>\n  Math.max(0, Math.min(20, Math.trunc(value)));\n\nconst numeric =\n  (fn: (...args: number[]) => number): FormulaFunction[\"run\"] =>\n  (args) =>\n    args.every(isNumber) ? fn(...args) : null;\n\nconst aggregate = (\n  operation: \"sum\" | \"avg\" | \"min\" | \"max\",\n  args: unknown[],\n  step: () => void,\n) => {\n  const [list, field] = args;\n  if (!Array.isArray(list) || args.length > 2) return null;\n  if (args.length === 2 && typeof field !== \"string\") return null;\n  if (typeof field === \"string\" && field.length > 500) return null;\n  const tokens = typeof field === \"string\" ? pointerTokens(field) : undefined;\n  if (tokens && tokens.length > 32) return null;\n  let total = 0;\n  let count = 0;\n  let extreme: number | null = null;\n  for (const item of list) {\n    step();\n    const value = tokens ? getAtPointer(item, tokens) : item;\n    if (!isNumber(value)) continue;\n    total += value;\n    count++;\n    if (extreme === null) extreme = value;\n    else if (operation === \"min\") extreme = Math.min(extreme, value);\n    else if (operation === \"max\") extreme = Math.max(extreme, value);\n  }\n  if (operation === \"sum\") return total;\n  if (operation === \"avg\") return count ? total / count : null;\n  return extreme;\n};\n\nconst formatters = new Map<string, Intl.NumberFormat>();\n\nconst formatNumber = (value: unknown, options: Intl.NumberFormatOptions) => {\n  if (!isNumber(value)) return null;\n  const key = JSON.stringify(options);\n  let formatter = formatters.get(key);\n  if (!formatter) {\n    try {\n      formatter = new Intl.NumberFormat(\"en-US\", options);\n    } catch {\n      return null;\n    }\n    if (formatters.size >= 64) formatters.clear();\n    formatters.set(key, formatter);\n  }\n  return formatter.format(value);\n};\n\nconst decimalFormat = (args: unknown[], style: \"decimal\" | \"percent\") => {\n  const [value, digits] = args;\n  if (args.length === 1) return formatNumber(value, { style });\n  if (!isNumber(digits)) return null;\n  const precision = fractionDigits(digits);\n  return formatNumber(value, {\n    style,\n    minimumFractionDigits: precision,\n    maximumFractionDigits: precision,\n  });\n};\n\nconst functions = new Map<string, FormulaFunction>([\n  [\n    \"round\",\n    {\n      min: 1,\n      max: 2,\n      run: numeric((x, digits = 0) => {\n        const scale = 10 ** fractionDigits(digits);\n        return Math.round(x * scale) / scale;\n      }),\n    },\n  ],\n  [\"floor\", { min: 1, max: 1, run: numeric(Math.floor) }],\n  [\"ceil\", { min: 1, max: 1, run: numeric(Math.ceil) }],\n  [\"abs\", { min: 1, max: 1, run: numeric(Math.abs) }],\n  [\n    \"clamp\",\n    {\n      min: 3,\n      max: 3,\n      run: numeric((x, low, high) => Math.min(Math.max(x, low), high)),\n    },\n  ],\n  ...([\"min\", \"max\"] as const).map((name): [string, FormulaFunction] => [\n    name,\n    {\n      min: 1,\n      max: Infinity,\n      run: (args, step) =>\n        Array.isArray(args[0])\n          ? aggregate(name, args, step)\n          : numeric(name === \"min\" ? Math.min : Math.max)(args, step),\n    },\n  ]),\n  [\n    \"count\",\n    {\n      min: 1,\n      max: 1,\n      run: ([list]) => (Array.isArray(list) ? list.length : null),\n    },\n  ],\n  ...([\"sum\", \"avg\"] as const).map((name): [string, FormulaFunction] => [\n    name,\n    {\n      min: 1,\n      max: 2,\n      run: (args, step) => aggregate(name, args, step),\n    },\n  ]),\n  [\"number\", { min: 1, max: 2, run: (args) => decimalFormat(args, \"decimal\") }],\n  [\n    \"currency\",\n    {\n      min: 2,\n      max: 2,\n      run: ([value, code]) =>\n        typeof code === \"string\"\n          ? formatNumber(value, { style: \"currency\", currency: code })\n          : null,\n    },\n  ],\n  [\n    \"percent\",\n    { min: 1, max: 2, run: (args) => decimalFormat(args, \"percent\") },\n  ],\n  [\n    \"time\",\n    {\n      min: 1,\n      max: 1,\n      run: ([value]) => {\n        if (!isNumber(value)) return null;\n        const minutes = ((Math.round(value) % 1440) + 1440) % 1440;\n        const hour = Math.floor(minutes / 60);\n        return `${hour % 12 || 12}:${String(minutes % 60).padStart(2, \"0\")} ${hour < 12 ? \"AM\" : \"PM\"}`;\n      },\n    },\n  ],\n  [\n    \"plural\",\n    { min: 3, max: 3, run: ([n, one, other]) => (n === 1 ? one : other) },\n  ],\n]);\n\nconst tokenize = (formula: string): Token[] => {\n  const tokens: Token[] = [];\n  let offset = 0;\n  while (offset < formula.length) {\n    const char = formula[offset]!;\n    if (/\\s/.test(char)) {\n      offset++;\n    } else if (char === \"'\" || char === '\"') {\n      offset++;\n      let value = \"\";\n      while (offset < formula.length && formula[offset] !== char) {\n        let next = formula[offset++]!;\n        if (next === \"\\\\\") {\n          next = formula[offset++] ?? \"\";\n          if (next !== \"\\\\\" && next !== \"'\" && next !== '\"') {\n            throw new Error(\"Invalid string escape\");\n          }\n        }\n        value += next;\n      }\n      if (offset >= formula.length) throw new Error(\"Unterminated string\");\n      offset++;\n      tokens.push({ kind: \"literal\", value });\n    } else if (char === \"$\" && formula[offset + 1] === \"{\") {\n      const end = formula.indexOf(\"}\", offset + 2);\n      if (end === -1) throw new Error(\"Unterminated reference\");\n      tokens.push({\n        kind: \"reference\",\n        text: formula.slice(offset + 2, end).trim(),\n      });\n      offset = end + 1;\n    } else if (/[0-9]/.test(char)) {\n      const start = offset++;\n      while (/[0-9]/.test(formula[offset] ?? \"\")) offset++;\n      if (formula[offset] === \".\" && /[0-9]/.test(formula[offset + 1] ?? \"\")) {\n        offset++;\n        while (/[0-9]/.test(formula[offset] ?? \"\")) offset++;\n      }\n      tokens.push({\n        kind: \"literal\",\n        value: Number(formula.slice(start, offset)),\n      });\n    } else if (/[a-zA-Z_]/.test(char)) {\n      const start = offset++;\n      while (/[a-zA-Z0-9_]/.test(formula[offset] ?? \"\")) offset++;\n      const name = formula.slice(start, offset);\n      if (name === \"true\" || name === \"false\" || name === \"null\") {\n        tokens.push({\n          kind: \"literal\",\n          value: name === \"null\" ? null : name === \"true\",\n        });\n      } else tokens.push({ kind: \"name\", text: name });\n    } else {\n      const pair = formula.slice(offset, offset + 2);\n      if ([\"||\", \"&&\", \"==\", \"!=\", \"<=\", \">=\"].includes(pair)) {\n        tokens.push({ kind: \"symbol\", text: pair });\n        offset += 2;\n      } else if (\"?:<>+-*/%!(),\".includes(char)) {\n        tokens.push({ kind: \"symbol\", text: char });\n        offset++;\n      } else throw new Error(`Unexpected token \"${char}\"`);\n    }\n  }\n  tokens.push({ kind: \"end\" });\n  return tokens;\n};\n\nconst precedence = [\n  [\"||\"],\n  [\"&&\"],\n  [\"==\", \"!=\"],\n  [\"<\", \"<=\", \">\", \">=\"],\n  [\"+\", \"-\"],\n  [\"*\", \"/\", \"%\"],\n];\n\nconst parse = (formula: string): Node => {\n  const tokens = tokenize(formula);\n  let position = 0;\n  const current = () => tokens[position]!;\n  const match = (symbol: string) => {\n    const token = current();\n    if (token.kind !== \"symbol\" || token.text !== symbol) return false;\n    position++;\n    return true;\n  };\n  const expect = (symbol: string) => {\n    if (!match(symbol)) throw new Error(`Expected \"${symbol}\"`);\n  };\n  const checkDepth = (depth: number) => {\n    if (depth > 32) throw new Error(\"Formula exceeds 32 levels of nesting\");\n  };\n  const primary = (depth: number): Node => {\n    checkDepth(depth);\n    const token = current();\n    position++;\n    if (token.kind === \"literal\") return token;\n    if (token.kind === \"reference\")\n      return { kind: \"reference\", path: token.text };\n    if (token.kind === \"symbol\" && token.text === \"(\") {\n      const node = conditional(depth + 1);\n      expect(\")\");\n      return node;\n    }\n    if (token.kind === \"name\") {\n      const fn = functions.get(token.text);\n      if (!fn) {\n        throw new Error(\n          `Unknown function \"${token.text}\"; known: ${[...functions.keys()].join(\", \")}`,\n        );\n      }\n      checkDepth(depth + 1);\n      expect(\"(\");\n      const args: Node[] = [];\n      if (!match(\")\")) {\n        do {\n          args.push(conditional(depth + 1));\n        } while (match(\",\"));\n        expect(\")\");\n      }\n      if (args.length < fn.min || args.length > fn.max) {\n        throw new Error(`Wrong argument count for \"${token.text}\"`);\n      }\n      return { kind: \"call\", name: token.text, args };\n    }\n    throw new Error(\"Expected a value\");\n  };\n  const unary = (depth: number): Node => {\n    checkDepth(depth);\n    const token = current();\n    if (token.kind === \"symbol\" && (token.text === \"-\" || token.text === \"!\")) {\n      position++;\n      return { kind: \"unary\", operator: token.text, operand: unary(depth + 1) };\n    }\n    return primary(depth);\n  };\n  const binary = (level: number, depth: number): Node => {\n    const operators = precedence[level];\n    if (!operators) return unary(depth);\n    let left = binary(level + 1, depth);\n    for (;;) {\n      const token = current();\n      if (token.kind !== \"symbol\" || !operators.includes(token.text))\n        return left;\n      position++;\n      left = {\n        kind: \"binary\",\n        operator: token.text,\n        left,\n        right: binary(level + 1, depth),\n      };\n    }\n  };\n  const conditional = (depth: number): Node => {\n    const condition = binary(0, depth);\n    if (!match(\"?\")) return condition;\n    const then = conditional(depth + 1);\n    expect(\":\");\n    return {\n      kind: \"conditional\",\n      condition,\n      then,\n      otherwise: conditional(depth + 1),\n    };\n  };\n  const node = conditional(0);\n  if (current().kind !== \"end\") throw new Error(\"Unexpected trailing token\");\n  return node;\n};\n\nconst parsedFormulas = new Map<string, Node | string>();\n\nconst parsedFormula = (formula: string): Node | string => {\n  if (formula.length > 500) return \"Formula exceeds 500 characters\";\n  const cached = parsedFormulas.get(formula);\n  if (cached !== undefined) return cached;\n  let result: Node | string;\n  try {\n    result = parse(formula);\n  } catch (error) {\n    result = error instanceof Error ? error.message : \"Invalid formula\";\n  }\n  if (parsedFormulas.size >= 500) parsedFormulas.clear();\n  parsedFormulas.set(formula, result);\n  return result;\n};\n\nconst childCount = (value: object, step: () => void) => {\n  let count = 0;\n  eachChild(value, () => {\n    step();\n    count++;\n    return true;\n  });\n  return count;\n};\n\nconst equal = (a: unknown, b: unknown, step: () => void): boolean => {\n  step();\n  if (a === b) return true;\n  if (typeof a !== \"object\" || typeof b !== \"object\" || !a || !b) return false;\n  if (Array.isArray(a) !== Array.isArray(b)) return false;\n  if (childCount(a, step) !== childCount(b, step)) return false;\n  return eachChild(a, (child, key) =>\n    equal(child, (b as Record<string, unknown>)[key], step),\n  );\n};\n\nconst calculate = (\n  operator: string,\n  left: unknown,\n  right: unknown,\n  step: () => void,\n): unknown => {\n  if (operator === \"==\") return equal(left, right, step);\n  if (operator === \"!=\") return !equal(left, right, step);\n  if (\n    operator === \"+\" &&\n    (typeof left === \"string\" || typeof right === \"string\")\n  ) {\n    return formatText(left, step) + formatText(right, step);\n  }\n  if ([\"<\", \"<=\", \">\", \">=\"].includes(operator)) {\n    if (\n      !(typeof left === \"number\" && typeof right === \"number\") &&\n      !(typeof left === \"string\" && typeof right === \"string\")\n    )\n      return false;\n    if (operator === \"<\") return left < right;\n    if (operator === \"<=\") return left <= right;\n    if (operator === \">\") return left > right;\n    return left >= right;\n  }\n  if (!isNumber(left) || !isNumber(right)) return null;\n  switch (operator) {\n    case \"+\":\n      return left + right;\n    case \"-\":\n      return left - right;\n    case \"*\":\n      return left * right;\n    case \"/\":\n      return right === 0 ? null : left / right;\n    case \"%\":\n      return right === 0 ? null : left % right;\n    default:\n      return null;\n  }\n};\n\nconst evaluate = (\n  node: Node,\n  ctx: ExpressionContext,\n  step: () => void,\n): unknown => {\n  step();\n  const visit = (child: Node) => normalize(evaluate(child, ctx, step));\n  switch (node.kind) {\n    case \"literal\":\n      return node.value;\n    case \"reference\":\n      return readReference(node.path, ctx);\n    case \"unary\": {\n      const value = visit(node.operand);\n      return node.operator === \"!\" ? !value : isNumber(value) ? -value : null;\n    }\n    case \"conditional\":\n      return visit(node.condition) ? visit(node.then) : visit(node.otherwise);\n    case \"call\":\n      return functions.get(node.name)!.run(node.args.map(visit), step);\n    case \"binary\": {\n      const left = visit(node.left);\n      if (node.operator === \"&&\")\n        return Boolean(left) && Boolean(visit(node.right));\n      if (node.operator === \"||\")\n        return Boolean(left) || Boolean(visit(node.right));\n      return calculate(node.operator, left, visit(node.right), step);\n    }\n  }\n};\n\n/** Evaluates a bounded formula, returning null when it cannot run. */\nexport function evaluateFormula(\n  formula: string,\n  ctx: ExpressionContext,\n): unknown {\n  try {\n    const node = parsedFormula(formula);\n    if (typeof node === \"string\") return null;\n    let steps = 0;\n    return normalize(\n      evaluate(node, ctx, () => {\n        if (++steps > 10_000)\n          throw new Error(\"Formula exceeds 10000 evaluation steps\");\n      }),\n    );\n  } catch {\n    return null;\n  }\n}\n\n/** The state paths a formula shows as values, leaving out reads under a condition and reads in the `?` branch of a condition on that same path, which only runs while it has a value. */\nexport function formulaValueReads(formula: string): string[] {\n  const node = parsedFormula(formula);\n  if (typeof node === \"string\") return [];\n  const reads = new Set<string>();\n  const visit = (\n    current: Node,\n    condition: boolean,\n    guarded: ReadonlySet<string>,\n  ): void => {\n    switch (current.kind) {\n      case \"literal\":\n        return;\n      case \"reference\":\n        if (\n          !condition &&\n          !current.path.startsWith(\"$\") &&\n          !guarded.has(current.path)\n        )\n          reads.add(current.path);\n        return;\n      case \"unary\":\n        visit(current.operand, condition || current.operator === \"!\", guarded);\n        return;\n      case \"binary\": {\n        const logical = current.operator === \"&&\" || current.operator === \"||\";\n        visit(current.left, condition || logical, guarded);\n        visit(current.right, condition || logical, guarded);\n        return;\n      }\n      case \"conditional\":\n        visit(current.condition, true, guarded);\n        visit(\n          current.then,\n          condition,\n          current.condition.kind === \"reference\"\n            ? new Set([...guarded, current.condition.path])\n            : guarded,\n        );\n        visit(current.otherwise, condition, guarded);\n        return;\n      case \"call\":\n        for (const arg of current.args) visit(arg, condition, guarded);\n        return;\n    }\n  };\n  visit(node, false, new Set());\n  return [...reads];\n}\n\n/** Why a formula cannot run, or undefined when it parses within the bounds. */\nexport function formulaIssue(formula: string): string | undefined {\n  const result = parsedFormula(formula);\n  return typeof result === \"string\" ? result : undefined;\n}\n"],"mappings":"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"}

package/dist/spec/catalog.d.ts

@@ -0,0 +1,52 @@
+import { type JsonSchema, type SchemaIssue, type StandardSchemaLike } from "../json-schema.js";
+import { type SpecPromptOptions } from "./prompt.js";
+export type PropsSchema = JsonSchema | StandardSchemaLike;
+/** A component the model may use. Implementations are supplied per framework. */
+export type ComponentDefinition = {
+    description: string;
+    /** JSON Schema for the props, or a Standard Schema (e.g. Zod 4) that can export one. */
+    props?: PropsSchema;
+    /**
+     * Child slots. `"default"` maps to `children`; other names map to
+     * `slots.<name>`. Components without slots take no children.
+     */
+    slots?: readonly string[];
+    /** Events the component emits, which elements bind with `on`. */
+    events?: readonly string[];
+};
+export type ActionDefinition = {
+    description: string;
+    params?: PropsSchema;
+};
+export type CatalogDefinition<TComponents extends Record<string, ComponentDefinition> = Record<string, ComponentDefinition>, TActions extends Record<string, ActionDefinition> = Record<string, ActionDefinition>> = {
+    components: TComponents;
+    actions?: TActions;
+};
+export type Catalog<TComponents extends Record<string, ComponentDefinition> = Record<string, ComponentDefinition>, TActions extends Record<string, ActionDefinition> = Record<string, ActionDefinition>> = {
+    readonly components: TComponents;
+    readonly actions: TActions;
+    /** Component definition by name, or undefined. */
+    component(type: string): ComponentDefinition | undefined;
+    /** Action definition by name, including the built-in `setState`. */
+    action(name: string): ActionDefinition | undefined;
+    /** JSON Schema of a component's props, if it has one. */
+    propsSchema(type: string): JsonSchema | undefined;
+    /** Validates props, treating expression values as valid placeholders. */
+    /** JSON Schema of an action's params, if it has one. */
+    paramsSchema(action: string): JsonSchema | undefined;
+    validateProps(type: string, props: unknown): SchemaIssue[];
+    validateParams(action: string, params: unknown): SchemaIssue[];
+    /** Model guidance for this catalog: components, actions, protocol, expressions, rules. */
+    prompt(options?: SpecPromptOptions): string;
+};
+/** The built-in action every catalog accepts. */
+export declare const SET_STATE_ACTION: ActionDefinition;
+/**
+ * Declares the components and actions a model may use in a spec. Props are
+ * JSON Schema (or a Standard Schema exposing JSON Schema), so the catalog
+ * stays dependency-free and works as model guidance and runtime validation.
+ */
+export declare function defineCatalog<const TComponents extends Record<string, ComponentDefinition>, const TActions extends Record<string, ActionDefinition> = Record<never, ActionDefinition>>(definition: CatalogDefinition<TComponents, TActions>): Catalog<TComponents, TActions>;
+/** One line describing a component's props for prompts and errors. */
+export declare const describeProps: (catalog: Catalog, type: string) => string;
+//# sourceMappingURL=catalog.d.ts.map

package/dist/spec/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","mappings":"AAAA,OAAO,EAIL,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACxB,MAAM,mBAAgB;AAEvB,OAAO,EAAmB,KAAK,iBAAiB,EAAE,MAAM,aAAU;AAElE,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,kBAAkB;AAEzD;AACA,MAAM,MAAM,mBAAmB,GAAG;IAChC,WAAW,EAAE,MAAM;IACnB;IACA,KAAK,CAAC,EAAE,WAAW;IACnB;;;;IAIA,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE;IACzB;IACA,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE;CAC3B;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,WAAW,EAAE,MAAM;IACnB,MAAM,CAAC,EAAE,WAAW;CACrB;AAED,MAAM,MAAM,iBAAiB,CAC3B,WAAW,SAAS,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,GAAG,MAAM,CAC9D,MAAM,EACN,mBAAmB,CACpB,EACD,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAAG,MAAM,CACxD,MAAM,EACN,gBAAgB,CACjB,IACC;IACF,UAAU,EAAE,WAAW;IACvB,OAAO,CAAC,EAAE,QAAQ;CACnB;AAED,MAAM,MAAM,OAAO,CACjB,WAAW,SAAS,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,GAAG,MAAM,CAC9D,MAAM,EACN,mBAAmB,CACpB,EACD,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAAG,MAAM,CACxD,MAAM,EACN,gBAAgB,CACjB,IACC;IACF,QAAQ,CAAC,UAAU,EAAE,WAAW;IAChC,QAAQ,CAAC,OAAO,EAAE,QAAQ;IAC1B;IACA,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS;IACxD;IACA,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAClD;IACA,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IACjD;IACA;IACA,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IACpD,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,WAAW,EAAE;IAC1D,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,WAAW,EAAE;IAC9D;IACA,MAAM,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,MAAM;CAC5C;AAED;AACA,eAAO,MAAM,gBAAgB,EAAE,gBAU9B;AA0CD;;;;;AAKA,wBAAgB,aAAa,CAC3B,KAAK,CAAC,WAAW,SAAS,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,EAC7D,KAAK,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAAG,MAAM,CAC9D,KAAK,EACL,gBAAgB,CACjB,EAED,UAAU,EAAE,iBAAiB,CAAC,WAAW,EAAE,QAAQ,CAAC,GACnD,OAAO,CAAC,WAAW,EAAE,QAAQ,CAAC;AAsDjC;AACA,eAAO,MAAM,aAAa,GAAI,SAAS,OAAO,EAAE,MAAM,MAAM,WACjB","names":[],"ignoreList":[],"sources":["../../src/spec/catalog.ts"],"sourcesContent":[null]}