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

package/dist/spec/catalog.js

@@ -0,0 +1,104 @@
+import { describeSchema, toJsonSchema, validateSchema } from "../json-schema.js";
+import { isExpression } from "./expressions.js";
+import { buildSpecPrompt } from "./prompt.js";
+// src/spec/catalog.ts
+/** The built-in action every catalog accepts. */
+const SET_STATE_ACTION = {
+	description: "Writes `value` at the JSON Pointer `path` in state.",
+	params: {
+		type: "object",
+		properties: {
+			path: {
+				type: "string",
+				description: "JSON Pointer into state"
+			},
+			value: { description: "The value to write" }
+		},
+		required: ["path"]
+	}
+};
+/** Built-in actions every catalog accepts; a host handles `sendMessage`, `updateModelContext`, and `copyText` the way it handles its own actions. */
+const BUILT_IN_ACTIONS = {
+	setState: SET_STATE_ACTION,
+	sendMessage: {
+		description: "Sends `text` as the user's next message.",
+		params: {
+			type: "object",
+			properties: { text: {
+				type: "string",
+				description: "The message"
+			} },
+			required: ["text"]
+		}
+	},
+	updateModelContext: {
+		description: "Replaces what this UI tells the model about the user's choices with `text` and `data`.",
+		params: {
+			type: "object",
+			properties: {
+				text: {
+					type: "string",
+					description: "The choices in words"
+				},
+				data: { description: "The choices as data" }
+			}
+		}
+	},
+	copyText: {
+		description: "Copies `text` to the user's clipboard.",
+		params: {
+			type: "object",
+			properties: { text: {
+				type: "string",
+				description: "The text to copy"
+			} },
+			required: ["text"]
+		}
+	}
+};
+const skipExpressions = { skip: isExpression };
+/**
+* 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.
+*/
+function defineCatalog(definition) {
+	const components = definition.components;
+	const actions = definition.actions ?? {};
+	const schemaCache = /* @__PURE__ */ new Map();
+	const component = (type) => Object.hasOwn(components, type) ? components[type] : void 0;
+	for (const name of Object.keys(BUILT_IN_ACTIONS)) if (Object.hasOwn(actions, name)) throw new Error(`The action name "${name}" is reserved for the built-in action.`);
+	const action = (name) => Object.hasOwn(BUILT_IN_ACTIONS, name) ? BUILT_IN_ACTIONS[name] : Object.hasOwn(actions, name) ? actions[name] : void 0;
+	const catalog = {
+		components,
+		actions,
+		component,
+		action,
+		propsSchema(type) {
+			if (!schemaCache.has(type)) schemaCache.set(type, toJsonSchema(component(type)?.props));
+			return schemaCache.get(type);
+		},
+		paramsSchema(name) {
+			const key = `action:${name}`;
+			if (!schemaCache.has(key)) schemaCache.set(key, toJsonSchema(action(name)?.params));
+			return schemaCache.get(key);
+		},
+		validateProps(type, props) {
+			const schema = component(type)?.props;
+			if (!schema) return [];
+			return validateSchema(schema, props ?? {}, skipExpressions);
+		},
+		validateParams(name, params) {
+			const schema = action(name)?.params;
+			if (!schema) return [];
+			return validateSchema(schema, params ?? {}, skipExpressions);
+		},
+		prompt: (options) => buildSpecPrompt(catalog, options)
+	};
+	return catalog;
+}
+/** One line describing a component's props for prompts and errors. */
+const describeProps = (catalog, type) => describeSchema(catalog.propsSchema(type));
+export { SET_STATE_ACTION, defineCatalog, describeProps };
+
+//# sourceMappingURL=catalog.js.map

package/dist/spec/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","names":[],"sources":["../../src/spec/catalog.ts"],"sourcesContent":["import {\n  describeSchema,\n  toJsonSchema,\n  validateSchema,\n  type JsonSchema,\n  type SchemaIssue,\n  type StandardSchemaLike,\n} from \"../json-schema\";\nimport { isExpression } from \"./expressions\";\nimport { buildSpecPrompt, type SpecPromptOptions } from \"./prompt\";\n\nexport type PropsSchema = JsonSchema | StandardSchemaLike;\n\n/** A component the model may use. Implementations are supplied per framework. */\nexport type ComponentDefinition = {\n  description: string;\n  /** JSON Schema for the props, or a Standard Schema (e.g. Zod 4) that can export one. */\n  props?: PropsSchema;\n  /**\n   * Child slots. `\"default\"` maps to `children`; other names map to\n   * `slots.<name>`. Components without slots take no children.\n   */\n  slots?: readonly string[];\n  /** Events the component emits, which elements bind with `on`. */\n  events?: readonly string[];\n};\n\nexport type ActionDefinition = {\n  description: string;\n  params?: PropsSchema;\n};\n\nexport type CatalogDefinition<\n  TComponents extends Record<string, ComponentDefinition> = Record<\n    string,\n    ComponentDefinition\n  >,\n  TActions extends Record<string, ActionDefinition> = Record<\n    string,\n    ActionDefinition\n  >,\n> = {\n  components: TComponents;\n  actions?: TActions;\n};\n\nexport type Catalog<\n  TComponents extends Record<string, ComponentDefinition> = Record<\n    string,\n    ComponentDefinition\n  >,\n  TActions extends Record<string, ActionDefinition> = Record<\n    string,\n    ActionDefinition\n  >,\n> = {\n  readonly components: TComponents;\n  readonly actions: TActions;\n  /** Component definition by name, or undefined. */\n  component(type: string): ComponentDefinition | undefined;\n  /** Action definition by name, including the built-in `setState`. */\n  action(name: string): ActionDefinition | undefined;\n  /** JSON Schema of a component's props, if it has one. */\n  propsSchema(type: string): JsonSchema | undefined;\n  /** Validates props, treating expression values as valid placeholders. */\n  /** JSON Schema of an action's params, if it has one. */\n  paramsSchema(action: string): JsonSchema | undefined;\n  validateProps(type: string, props: unknown): SchemaIssue[];\n  validateParams(action: string, params: unknown): SchemaIssue[];\n  /** Model guidance for this catalog: components, actions, protocol, expressions, rules. */\n  prompt(options?: SpecPromptOptions): string;\n};\n\n/** The built-in action every catalog accepts. */\nexport const SET_STATE_ACTION: ActionDefinition = {\n  description: \"Writes `value` at the JSON Pointer `path` in state.\",\n  params: {\n    type: \"object\",\n    properties: {\n      path: { type: \"string\", description: \"JSON Pointer into state\" },\n      value: { description: \"The value to write\" },\n    },\n    required: [\"path\"],\n  },\n};\n\nconst SEND_MESSAGE_ACTION: ActionDefinition = {\n  description: \"Sends `text` as the user's next message.\",\n  params: {\n    type: \"object\",\n    properties: { text: { type: \"string\", description: \"The message\" } },\n    required: [\"text\"],\n  },\n};\n\nconst UPDATE_MODEL_CONTEXT_ACTION: ActionDefinition = {\n  description:\n    \"Replaces what this UI tells the model about the user's choices with `text` and `data`.\",\n  params: {\n    type: \"object\",\n    properties: {\n      text: { type: \"string\", description: \"The choices in words\" },\n      data: { description: \"The choices as data\" },\n    },\n  },\n};\n\nconst COPY_TEXT_ACTION: ActionDefinition = {\n  description: \"Copies `text` to the user's clipboard.\",\n  params: {\n    type: \"object\",\n    properties: { text: { type: \"string\", description: \"The text to copy\" } },\n    required: [\"text\"],\n  },\n};\n\n/** Built-in actions every catalog accepts; a host handles `sendMessage`, `updateModelContext`, and `copyText` the way it handles its own actions. */\nconst BUILT_IN_ACTIONS: Readonly<Record<string, ActionDefinition>> = {\n  setState: SET_STATE_ACTION,\n  sendMessage: SEND_MESSAGE_ACTION,\n  updateModelContext: UPDATE_MODEL_CONTEXT_ACTION,\n  copyText: COPY_TEXT_ACTION,\n};\n\nconst skipExpressions = { skip: isExpression };\n\n/**\n * Declares the components and actions a model may use in a spec. Props are\n * JSON Schema (or a Standard Schema exposing JSON Schema), so the catalog\n * stays dependency-free and works as model guidance and runtime validation.\n */\nexport function defineCatalog<\n  const TComponents extends Record<string, ComponentDefinition>,\n  const TActions extends Record<string, ActionDefinition> = Record<\n    never,\n    ActionDefinition\n  >,\n>(\n  definition: CatalogDefinition<TComponents, TActions>,\n): Catalog<TComponents, TActions> {\n  const components = definition.components;\n  const actions = (definition.actions ?? {}) as TActions;\n  const schemaCache = new Map<string, JsonSchema | undefined>();\n\n  const component = (type: string) =>\n    Object.hasOwn(components, type) ? components[type] : undefined;\n  for (const name of Object.keys(BUILT_IN_ACTIONS)) {\n    if (Object.hasOwn(actions, name)) {\n      throw new Error(\n        `The action name \"${name}\" is reserved for the built-in action.`,\n      );\n    }\n  }\n  const action = (name: string) =>\n    Object.hasOwn(BUILT_IN_ACTIONS, name)\n      ? BUILT_IN_ACTIONS[name]\n      : Object.hasOwn(actions, name)\n        ? actions[name]\n        : undefined;\n\n  const catalog: Catalog<TComponents, TActions> = {\n    components,\n    actions,\n    component,\n    action,\n    propsSchema(type) {\n      if (!schemaCache.has(type)) {\n        schemaCache.set(type, toJsonSchema(component(type)?.props));\n      }\n      return schemaCache.get(type);\n    },\n    paramsSchema(name) {\n      const key = `action:${name}`;\n      if (!schemaCache.has(key)) {\n        schemaCache.set(key, toJsonSchema(action(name)?.params));\n      }\n      return schemaCache.get(key);\n    },\n    validateProps(type, props) {\n      const schema = component(type)?.props;\n      if (!schema) return [];\n      return validateSchema(schema, props ?? {}, skipExpressions);\n    },\n    validateParams(name, params) {\n      const schema = action(name)?.params;\n      if (!schema) return [];\n      return validateSchema(schema, params ?? {}, skipExpressions);\n    },\n    prompt: (options) => buildSpecPrompt(catalog, options),\n  };\n  return catalog;\n}\n\n/** One line describing a component's props for prompts and errors. */\nexport const describeProps = (catalog: Catalog, type: string) =>\n  describeSchema(catalog.propsSchema(type));\n"],"mappings":";;;;;AA0EA,MAAa,mBAAqC;CAChD,aAAa;CACb,QAAQ;EACN,MAAM;EACN,YAAY;GACV,MAAM;IAAE,MAAM;IAAU,aAAa;GAA0B;GAC/D,OAAO,EAAE,aAAa,qBAAqB;EAC7C;EACA,UAAU,CAAC,MAAM;CACnB;AACF;;AAiCA,MAAM,mBAA+D;CACnE,UAAU;CACV,aAAa;EAhCb,aAAa;EACb,QAAQ;GACN,MAAM;GACN,YAAY,EAAE,MAAM;IAAE,MAAM;IAAU,aAAa;GAAc,EAAE;GACnE,UAAU,CAAC,MAAM;EACnB;CA2B+B;CAC/B,oBAAoB;EAxBpB,aACE;EACF,QAAQ;GACN,MAAM;GACN,YAAY;IACV,MAAM;KAAE,MAAM;KAAU,aAAa;IAAuB;IAC5D,MAAM,EAAE,aAAa,sBAAsB;GAC7C;EACF;CAgB8C;CAC9C,UAAU;EAbV,aAAa;EACb,QAAQ;GACN,MAAM;GACN,YAAY,EAAE,MAAM;IAAE,MAAM;IAAU,aAAa;GAAmB,EAAE;GACxE,UAAU,CAAC,MAAM;EACnB;CAQyB;AAC3B;AAEA,MAAM,kBAAkB,EAAE,MAAM,aAAa;;;;;;AAO7C,SAAgB,cAOd,YACgC;CAChC,MAAM,aAAa,WAAW;CAC9B,MAAM,UAAW,WAAW,WAAW,CAAC;CACxC,MAAM,8BAAc,IAAI,IAAoC;CAE5D,MAAM,aAAa,SACjB,OAAO,OAAO,YAAY,IAAI,IAAI,WAAW,QAAQ,KAAA;CACvD,KAAK,MAAM,QAAQ,OAAO,KAAK,gBAAgB,GAC7C,IAAI,OAAO,OAAO,SAAS,IAAI,GAC7B,MAAM,IAAI,MACR,oBAAoB,KAAK,uCAC3B;CAGJ,MAAM,UAAU,SACd,OAAO,OAAO,kBAAkB,IAAI,IAChC,iBAAiB,QACjB,OAAO,OAAO,SAAS,IAAI,IACzB,QAAQ,QACR,KAAA;CAER,MAAM,UAA0C;EAC9C;EACA;EACA;EACA;EACA,YAAY,MAAM;GAChB,IAAI,CAAC,YAAY,IAAI,IAAI,GACvB,YAAY,IAAI,MAAM,aAAa,UAAU,IAAI,CAAC,EAAE,KAAK,CAAC;GAE5D,OAAO,YAAY,IAAI,IAAI;EAC7B;EACA,aAAa,MAAM;GACjB,MAAM,MAAM,UAAU;GACtB,IAAI,CAAC,YAAY,IAAI,GAAG,GACtB,YAAY,IAAI,KAAK,aAAa,OAAO,IAAI,CAAC,EAAE,MAAM,CAAC;GAEzD,OAAO,YAAY,IAAI,GAAG;EAC5B;EACA,cAAc,MAAM,OAAO;GACzB,MAAM,SAAS,UAAU,IAAI,CAAC,EAAE;GAChC,IAAI,CAAC,QAAQ,OAAO,CAAC;GACrB,OAAO,eAAe,QAAQ,SAAS,CAAC,GAAG,eAAe;EAC5D;EACA,eAAe,MAAM,QAAQ;GAC3B,MAAM,SAAS,OAAO,IAAI,CAAC,EAAE;GAC7B,IAAI,CAAC,QAAQ,OAAO,CAAC;GACrB,OAAO,eAAe,QAAQ,UAAU,CAAC,GAAG,eAAe;EAC7D;EACA,SAAS,YAAY,gBAAgB,SAAS,OAAO;CACvD;CACA,OAAO;AACT;;AAGA,MAAa,iBAAiB,SAAkB,SAC9C,eAAe,QAAQ,YAAY,IAAI,CAAC"}

package/dist/spec/expressions.d.ts

@@ -0,0 +1,45 @@
+import type { Condition } from "./types.js";
+/** What expressions can read while an element renders or an action runs. */
+export type ExpressionContext = {
+    state: unknown;
+    /** The current item and index inside a `repeat`. */
+    item?: unknown;
+    index?: number;
+    /** The state path of the current item, so `$bindItem` can write back. */
+    itemPath?: string;
+    /** The payload an event was emitted with, for action params. */
+    event?: unknown;
+};
+/** True for `{ $state }`, `{ $bindState }`, `{ $item }`, `{ $bindItem }`, `{ $index }`, `{ $event }`, `{ $cond }`, `{ $calc }`, and `{ $template }`. */
+export declare const isExpression: (value: unknown) => value is Record<string, unknown>;
+/** True for a string that is only an expression key, such as `"$calc"`. */
+export declare const isExpressionKey: (value: string) => boolean;
+/**
+ * Fills `${/path}` (state), `${$item/path}`, `${$item}`, and `${$index}`
+ * placeholders in a `$template` string.
+ */
+export declare function renderTemplate(template: string, ctx: ExpressionContext): string;
+/** The state paths a `$template` string's placeholders read. */
+export declare const templateStatePaths: (template: string) => string[];
+/** Resolves expressions anywhere inside a value; plain values pass through. */
+export declare function resolveValue(value: unknown, ctx: ExpressionContext): unknown;
+/** The state paths a condition only holds true while they have a value: a `$state` it tests for truthiness or with any comparator but `neq` alone, in every part of `$and` or a list. */
+export declare function conditionGuards(condition: unknown): string[];
+/**
+ * Evaluates a visibility condition. Unknown shapes are false, so a
+ * half-streamed condition hides its element rather than throwing.
+ */
+export declare function evaluateCondition(condition: Condition | undefined, ctx: ExpressionContext): boolean;
+/** Resolved props plus the state path behind each two-way bound prop. */
+export type ResolvedProps = {
+    props: Record<string, unknown>;
+    bindings: Record<string, string>;
+};
+/**
+ * Resolves an element's props. Top-level `$bindState` and `$bindItem` props
+ * are also reported in `bindings`, so the component can write the value back.
+ */
+export declare function resolveProps(props: Record<string, unknown> | undefined, ctx: ExpressionContext): ResolvedProps;
+/** The state path of item `index` in the array at `path`. */
+export declare const itemPointer: (path: string, index: number) => string;
+//# sourceMappingURL=expressions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"expressions.d.ts","mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAS;AAExC;AACA,MAAM,MAAM,iBAAiB,GAAG;IAC9B,KAAK,EAAE,OAAO;IACd;IACA,IAAI,CAAC,EAAE,OAAO;IACd,KAAK,CAAC,EAAE,MAAM;IACd;IACA,QAAQ,CAAC,EAAE,MAAM;IACjB;IACA,KAAK,CAAC,EAAE,OAAO;CAChB;AAqBD;AACA,eAAO,MAAM,YAAY,GACvB,OAAO,OAAO,KACb,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAC6C;AAE/E;AACA,eAAO,MAAM,eAAe,GAAI,OAAO,MAAM,YACV;AAqCnC;;;;AAIA,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,iBAAiB,GACrB,MAAM;AA8BT;AACA,eAAO,MAAM,kBAAkB,GAAI,UAAU,MAAM,KAAG,MAAM,EAGlB;AAE1C;AACA,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,iBAAiB,GAAG,OAAO;AAmD7E;AACA,wBAAgB,eAAe,CAAC,SAAS,EAAE,OAAO,GAAG,MAAM,EAAE;AAc7D;;;;AAIA,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,SAAS,GAAG,SAAS,EAChC,GAAG,EAAE,iBAAiB,GACrB,OAAO;AA+DV;AACA,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;CACjC;AAKD;;;;AAIA,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC1C,GAAG,EAAE,iBAAiB,GACrB,aAAa;AAqBhB;AACA,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,EAAE,OAAO,MAAM,WACa","names":[],"ignoreList":[],"sources":["../../src/spec/expressions.ts"],"sourcesContent":[null]}

package/dist/spec/expressions.js

@@ -0,0 +1,199 @@
+import { deepEqual } from "../json-schema.js";
+import { getAtPointer, joinPointer, parsePointer } from "./pointer.js";
+import { evaluateFormula } from "./calc.js";
+// src/spec/expressions.ts
+const SOURCE_KEYS = [
+	"$state",
+	"$bindState",
+	"$item",
+	"$bindItem",
+	"$index",
+	"$event"
+];
+const EXPRESSION_KEYS = /* @__PURE__ */ new Set([
+	...SOURCE_KEYS,
+	"$cond",
+	"$calc",
+	"$template"
+]);
+const COMPARATORS = [
+	"eq",
+	"neq",
+	"gt",
+	"gte",
+	"lt",
+	"lte"
+];
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** True for `{ $state }`, `{ $bindState }`, `{ $item }`, `{ $bindItem }`, `{ $index }`, `{ $event }`, `{ $cond }`, `{ $calc }`, and `{ $template }`. */
+const isExpression = (value) => isRecord(value) && Object.keys(value).some((key) => EXPRESSION_KEYS.has(key));
+/** True for a string that is only an expression key, such as `"$calc"`. */
+const isExpressionKey = (value) => EXPRESSION_KEYS.has(value.trim());
+const readPath = (base, path) => typeof path === "string" && path !== "" ? getAtPointer(base, safeTokens(path)) : base;
+const safeTokens = (path) => {
+	try {
+		return parsePointer(path.startsWith("/") ? path : `/${path}`);
+	} catch {
+		return [];
+	}
+};
+const readSource = (expression, ctx) => {
+	if ("$state" in expression) return readPath(ctx.state, expression["$state"]);
+	if ("$bindState" in expression) return readPath(ctx.state, expression["$bindState"]);
+	if ("$item" in expression) return readPath(ctx.item, expression["$item"]);
+	if ("$bindItem" in expression) return readPath(ctx.item, expression["$bindItem"]);
+	if ("$index" in expression) return ctx.index;
+	if ("$event" in expression) return readPath(ctx.event, expression["$event"]);
+};
+const formatTemplateValue = (value) => value === void 0 || value === null ? "" : typeof value === "object" ? JSON.stringify(value) : String(value);
+/**
+* Fills `${/path}` (state), `${$item/path}`, `${$item}`, and `${$index}`
+* placeholders in a `$template` string.
+*/
+function renderTemplate(template, ctx) {
+	const fill = (ref) => {
+		if (ref === "$index") return formatTemplateValue(ctx.index);
+		if (ref === "$item") return formatTemplateValue(ctx.item);
+		if (ref.startsWith("$item/")) return formatTemplateValue(readPath(ctx.item, ref.slice(5)));
+		return formatTemplateValue(readPath(ctx.state, ref));
+	};
+	let out = "";
+	let from = 0;
+	for (const { start, end, ref } of placeholders(template)) {
+		out += template.slice(from, start) + fill(ref);
+		from = end + 1;
+	}
+	return out + template.slice(from);
+}
+function* placeholders(template) {
+	let from = 0;
+	for (;;) {
+		const start = template.indexOf("${", from);
+		if (start === -1) return;
+		const end = template.indexOf("}", start + 2);
+		if (end === -1) return;
+		yield {
+			start,
+			end,
+			ref: template.slice(start + 2, end).trim()
+		};
+		from = end + 1;
+	}
+}
+/** The state paths a `$template` string's placeholders read. */
+const templateStatePaths = (template) => [...placeholders(template)].map(({ ref }) => ref).filter((ref) => !ref.startsWith("$"));
+/** Resolves expressions anywhere inside a value; plain values pass through. */
+function resolveValue(value, ctx) {
+	if (Array.isArray(value)) return value.map((item) => resolveValue(item, ctx));
+	if (!isRecord(value)) return value;
+	if ("$cond" in value) return evaluateCondition(value["$cond"], ctx) ? resolveValue(value["$then"], ctx) : resolveValue(value["$else"], ctx);
+	if ("$calc" in value) return typeof value["$calc"] === "string" ? evaluateFormula(value["$calc"], ctx) : null;
+	if ("$template" in value) return typeof value["$template"] === "string" ? renderTemplate(value["$template"], ctx) : "";
+	if (SOURCE_KEYS.some((key) => key in value)) return readSource(value, ctx);
+	const result = {};
+	for (const [key, child] of Object.entries(value)) result[key] = resolveValue(child, ctx);
+	return result;
+}
+const compare = (left, operator, right) => {
+	switch (operator) {
+		case "eq": return deepEqual(left, right);
+		case "neq": return !deepEqual(left, right);
+		default:
+			if (!(typeof left === "number" && typeof right === "number") && !(typeof left === "string" && typeof right === "string")) return false;
+			if (operator === "gt") return left > right;
+			if (operator === "gte") return left >= right;
+			if (operator === "lt") return left < right;
+			return left <= right;
+	}
+};
+/** The state paths a condition only holds true while they have a value: a `$state` it tests for truthiness or with any comparator but `neq` alone, in every part of `$and` or a list. */
+function conditionGuards(condition) {
+	if (Array.isArray(condition)) return condition.flatMap(conditionGuards);
+	if (!isRecord(condition)) return [];
+	if (Array.isArray(condition["$and"])) return conditionGuards(condition["$and"]);
+	if (typeof condition["$state"] !== "string" || condition["not"] === true) return [];
+	const comparators = COMPARATORS.filter((operator) => operator in condition);
+	return comparators.length === 0 || comparators.some((operator) => operator !== "neq") ? [condition["$state"]] : [];
+}
+/**
+* Evaluates a visibility condition. Unknown shapes are false, so a
+* half-streamed condition hides its element rather than throwing.
+*/
+function evaluateCondition(condition, ctx) {
+	return evaluateConditionValue(condition, ctx) ?? false;
+}
+function evaluateConditionValue(condition, ctx) {
+	if (condition === void 0) return true;
+	if (typeof condition === "boolean") return condition;
+	if (Array.isArray(condition)) {
+		let result = true;
+		for (const part of condition) {
+			const value = evaluateConditionValue(part, ctx);
+			if (value === false) return false;
+			if (value === void 0) result = void 0;
+		}
+		return result;
+	}
+	if (!isRecord(condition)) return Boolean(condition);
+	if (Array.isArray(condition["$and"])) return evaluateConditionValue(condition["$and"], ctx);
+	if (Array.isArray(condition["$or"])) {
+		let result = false;
+		for (const part of condition["$or"]) {
+			const value = evaluateConditionValue(part, ctx);
+			if (value === true) return true;
+			if (value === void 0) result = void 0;
+		}
+		return result;
+	}
+	const hasSource = SOURCE_KEYS.some((key) => key in condition);
+	if (!hasSource && "not" in condition) {
+		const value = evaluateConditionValue(condition["not"], ctx);
+		return value === void 0 ? void 0 : !value;
+	}
+	if (!hasSource) {
+		if (!isExpression(condition)) return void 0;
+		let expression = condition;
+		while (isRecord(expression) && "$cond" in expression) {
+			const matches = evaluateConditionValue(expression["$cond"], ctx);
+			if (matches === void 0) return void 0;
+			expression = expression[matches ? "$then" : "$else"];
+		}
+		return Boolean(resolveValue(expression, ctx));
+	}
+	const value = readSource(condition, ctx);
+	let result = true;
+	let compared = false;
+	for (const operator of COMPARATORS) {
+		if (!(operator in condition)) continue;
+		compared = true;
+		result &&= compare(value, operator, resolveValue(condition[operator], ctx));
+	}
+	if (!compared) result = Boolean(value);
+	return condition["not"] === true ? !result : result;
+}
+const normalizePath = (path) => path === "" || path.startsWith("/") ? path : `/${path}`;
+/**
+* Resolves an element's props. Top-level `$bindState` and `$bindItem` props
+* are also reported in `bindings`, so the component can write the value back.
+*/
+function resolveProps(props, ctx) {
+	const resolved = {};
+	const bindings = {};
+	for (const [key, value] of Object.entries(props ?? {})) {
+		if (isRecord(value) && typeof value["$bindState"] === "string") bindings[key] = normalizePath(value["$bindState"]);
+		else if (isRecord(value) && typeof value["$bindItem"] === "string" && ctx.itemPath !== void 0) {
+			const field = value["$bindItem"];
+			bindings[key] = field ? `${ctx.itemPath}${normalizePath(field)}` : ctx.itemPath;
+		}
+		resolved[key] = resolveValue(value, ctx);
+	}
+	return {
+		props: resolved,
+		bindings
+	};
+}
+/** The state path of item `index` in the array at `path`. */
+const itemPointer = (path, index) => `${path === "" ? "" : normalizePath(path)}${joinPointer([index])}`;
+export { conditionGuards, evaluateCondition, isExpression, isExpressionKey, itemPointer, renderTemplate, resolveProps, resolveValue, templateStatePaths };
+
+//# sourceMappingURL=expressions.js.map

package/dist/spec/expressions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expressions.js","names":[],"sources":["../../src/spec/expressions.ts"],"sourcesContent":["import { deepEqual } from \"../json-schema\";\nimport { evaluateFormula } from \"./calc\";\nimport { getAtPointer, joinPointer, parsePointer } from \"./pointer\";\nimport type { Condition } from \"./types\";\n\n/** What expressions can read while an element renders or an action runs. */\nexport type ExpressionContext = {\n  state: unknown;\n  /** The current item and index inside a `repeat`. */\n  item?: unknown;\n  index?: number;\n  /** The state path of the current item, so `$bindItem` can write back. */\n  itemPath?: string;\n  /** The payload an event was emitted with, for action params. */\n  event?: unknown;\n};\n\nconst SOURCE_KEYS = [\n  \"$state\",\n  \"$bindState\",\n  \"$item\",\n  \"$bindItem\",\n  \"$index\",\n  \"$event\",\n] as const;\nconst EXPRESSION_KEYS = new Set<string>([\n  ...SOURCE_KEYS,\n  \"$cond\",\n  \"$calc\",\n  \"$template\",\n]);\nconst COMPARATORS = [\"eq\", \"neq\", \"gt\", \"gte\", \"lt\", \"lte\"] as const;\n\nconst isRecord = (value: unknown): value is Record<string, unknown> =>\n  typeof value === \"object\" && value !== null && !Array.isArray(value);\n\n/** True for `{ $state }`, `{ $bindState }`, `{ $item }`, `{ $bindItem }`, `{ $index }`, `{ $event }`, `{ $cond }`, `{ $calc }`, and `{ $template }`. */\nexport const isExpression = (\n  value: unknown,\n): value is Record<string, unknown> =>\n  isRecord(value) && Object.keys(value).some((key) => EXPRESSION_KEYS.has(key));\n\n/** True for a string that is only an expression key, such as `\"$calc\"`. */\nexport const isExpressionKey = (value: string) =>\n  EXPRESSION_KEYS.has(value.trim());\n\nconst readPath = (base: unknown, path: unknown) =>\n  typeof path === \"string\" && path !== \"\"\n    ? getAtPointer(base, safeTokens(path))\n    : base;\n\nconst safeTokens = (path: string) => {\n  try {\n    return parsePointer(path.startsWith(\"/\") ? path : `/${path}`);\n  } catch {\n    return [];\n  }\n};\n\nconst readSource = (\n  expression: Record<string, unknown>,\n  ctx: ExpressionContext,\n) => {\n  if (\"$state\" in expression) return readPath(ctx.state, expression[\"$state\"]);\n  if (\"$bindState\" in expression)\n    return readPath(ctx.state, expression[\"$bindState\"]);\n  if (\"$item\" in expression) return readPath(ctx.item, expression[\"$item\"]);\n  if (\"$bindItem\" in expression)\n    return readPath(ctx.item, expression[\"$bindItem\"]);\n  if (\"$index\" in expression) return ctx.index;\n  if (\"$event\" in expression) return readPath(ctx.event, expression[\"$event\"]);\n  return undefined;\n};\n\nconst formatTemplateValue = (value: unknown) =>\n  value === undefined || value === null\n    ? \"\"\n    : typeof value === \"object\"\n      ? JSON.stringify(value)\n      : String(value);\n\n/**\n * Fills `${/path}` (state), `${$item/path}`, `${$item}`, and `${$index}`\n * placeholders in a `$template` string.\n */\nexport function renderTemplate(\n  template: string,\n  ctx: ExpressionContext,\n): string {\n  const fill = (ref: string) => {\n    if (ref === \"$index\") return formatTemplateValue(ctx.index);\n    if (ref === \"$item\") return formatTemplateValue(ctx.item);\n    if (ref.startsWith(\"$item/\")) {\n      return formatTemplateValue(readPath(ctx.item, ref.slice(5)));\n    }\n    return formatTemplateValue(readPath(ctx.state, ref));\n  };\n  let out = \"\";\n  let from = 0;\n  for (const { start, end, ref } of placeholders(template)) {\n    out += template.slice(from, start) + fill(ref);\n    from = end + 1;\n  }\n  return out + template.slice(from);\n}\n\nfunction* placeholders(template: string) {\n  let from = 0;\n  for (;;) {\n    const start = template.indexOf(\"${\", from);\n    if (start === -1) return;\n    const end = template.indexOf(\"}\", start + 2);\n    if (end === -1) return;\n    yield { start, end, ref: template.slice(start + 2, end).trim() };\n    from = end + 1;\n  }\n}\n\n/** The state paths a `$template` string's placeholders read. */\nexport const templateStatePaths = (template: string): string[] =>\n  [...placeholders(template)]\n    .map(({ ref }) => ref)\n    .filter((ref) => !ref.startsWith(\"$\"));\n\n/** Resolves expressions anywhere inside a value; plain values pass through. */\nexport function resolveValue(value: unknown, ctx: ExpressionContext): unknown {\n  if (Array.isArray(value)) return value.map((item) => resolveValue(item, ctx));\n  if (!isRecord(value)) return value;\n  if (\"$cond\" in value) {\n    return evaluateCondition(value[\"$cond\"] as Condition, ctx)\n      ? resolveValue(value[\"$then\"], ctx)\n      : resolveValue(value[\"$else\"], ctx);\n  }\n  if (\"$calc\" in value) {\n    return typeof value[\"$calc\"] === \"string\"\n      ? evaluateFormula(value[\"$calc\"], ctx)\n      : null;\n  }\n  if (\"$template\" in value) {\n    return typeof value[\"$template\"] === \"string\"\n      ? renderTemplate(value[\"$template\"], ctx)\n      : \"\";\n  }\n  if (SOURCE_KEYS.some((key) => key in value)) return readSource(value, ctx);\n  const result: Record<string, unknown> = {};\n  for (const [key, child] of Object.entries(value)) {\n    result[key] = resolveValue(child, ctx);\n  }\n  return result;\n}\n\nconst compare = (\n  left: unknown,\n  operator: (typeof COMPARATORS)[number],\n  right: unknown,\n) => {\n  switch (operator) {\n    case \"eq\":\n      return deepEqual(left, right);\n    case \"neq\":\n      return !deepEqual(left, right);\n    default: {\n      if (\n        !(typeof left === \"number\" && typeof right === \"number\") &&\n        !(typeof left === \"string\" && typeof right === \"string\")\n      ) {\n        return false;\n      }\n      if (operator === \"gt\") return left > right;\n      if (operator === \"gte\") return left >= right;\n      if (operator === \"lt\") return left < right;\n      return left <= right;\n    }\n  }\n};\n\n/** The state paths a condition only holds true while they have a value: a `$state` it tests for truthiness or with any comparator but `neq` alone, in every part of `$and` or a list. */\nexport function conditionGuards(condition: unknown): string[] {\n  if (Array.isArray(condition)) return condition.flatMap(conditionGuards);\n  if (!isRecord(condition)) return [];\n  if (Array.isArray(condition[\"$and\"]))\n    return conditionGuards(condition[\"$and\"]);\n  if (typeof condition[\"$state\"] !== \"string\" || condition[\"not\"] === true)\n    return [];\n  const comparators = COMPARATORS.filter((operator) => operator in condition);\n  return comparators.length === 0 ||\n    comparators.some((operator) => operator !== \"neq\")\n    ? [condition[\"$state\"]]\n    : [];\n}\n\n/**\n * Evaluates a visibility condition. Unknown shapes are false, so a\n * half-streamed condition hides its element rather than throwing.\n */\nexport function evaluateCondition(\n  condition: Condition | undefined,\n  ctx: ExpressionContext,\n): boolean {\n  return evaluateConditionValue(condition, ctx) ?? false;\n}\n\nfunction evaluateConditionValue(\n  condition: Condition | undefined,\n  ctx: ExpressionContext,\n): boolean | undefined {\n  if (condition === undefined) return true;\n  if (typeof condition === \"boolean\") return condition;\n  if (Array.isArray(condition)) {\n    let result: boolean | undefined = true;\n    for (const part of condition) {\n      const value = evaluateConditionValue(part as Condition, ctx);\n      if (value === false) return false;\n      if (value === undefined) result = undefined;\n    }\n    return result;\n  }\n  if (!isRecord(condition)) return Boolean(condition);\n  if (Array.isArray(condition[\"$and\"])) {\n    return evaluateConditionValue(condition[\"$and\"] as Condition[], ctx);\n  }\n  if (Array.isArray(condition[\"$or\"])) {\n    let result: boolean | undefined = false;\n    for (const part of condition[\"$or\"] as Condition[]) {\n      const value = evaluateConditionValue(part, ctx);\n      if (value === true) return true;\n      if (value === undefined) result = undefined;\n    }\n    return result;\n  }\n  const hasSource = SOURCE_KEYS.some((key) => key in condition);\n  if (!hasSource && \"not\" in condition) {\n    const value = evaluateConditionValue(condition[\"not\"] as Condition, ctx);\n    return value === undefined ? undefined : !value;\n  }\n  if (!hasSource) {\n    if (!isExpression(condition)) return undefined;\n    let expression: unknown = condition;\n    while (isRecord(expression) && \"$cond\" in expression) {\n      const matches = evaluateConditionValue(\n        expression[\"$cond\"] as Condition,\n        ctx,\n      );\n      if (matches === undefined) return undefined;\n      expression = expression[matches ? \"$then\" : \"$else\"];\n    }\n    return Boolean(resolveValue(expression, ctx));\n  }\n\n  const value = readSource(condition, ctx);\n  let result = true;\n  let compared = false;\n  for (const operator of COMPARATORS) {\n    if (!(operator in condition)) continue;\n    compared = true;\n    result &&= compare(value, operator, resolveValue(condition[operator], ctx));\n  }\n  if (!compared) result = Boolean(value);\n  return condition[\"not\"] === true ? !result : result;\n}\n\n/** Resolved props plus the state path behind each two-way bound prop. */\nexport type ResolvedProps = {\n  props: Record<string, unknown>;\n  bindings: Record<string, string>;\n};\n\nconst normalizePath = (path: string) =>\n  path === \"\" || path.startsWith(\"/\") ? path : `/${path}`;\n\n/**\n * Resolves an element's props. Top-level `$bindState` and `$bindItem` props\n * are also reported in `bindings`, so the component can write the value back.\n */\nexport function resolveProps(\n  props: Record<string, unknown> | undefined,\n  ctx: ExpressionContext,\n): ResolvedProps {\n  const resolved: Record<string, unknown> = {};\n  const bindings: Record<string, string> = {};\n  for (const [key, value] of Object.entries(props ?? {})) {\n    if (isRecord(value) && typeof value[\"$bindState\"] === \"string\") {\n      bindings[key] = normalizePath(value[\"$bindState\"]);\n    } else if (\n      isRecord(value) &&\n      typeof value[\"$bindItem\"] === \"string\" &&\n      ctx.itemPath !== undefined\n    ) {\n      const field = value[\"$bindItem\"];\n      bindings[key] = field\n        ? `${ctx.itemPath}${normalizePath(field)}`\n        : ctx.itemPath;\n    }\n    resolved[key] = resolveValue(value, ctx);\n  }\n  return { props: resolved, bindings };\n}\n\n/** The state path of item `index` in the array at `path`. */\nexport const itemPointer = (path: string, index: number) =>\n  `${path === \"\" ? \"\" : normalizePath(path)}${joinPointer([index])}`;\n"],"mappings":";;;;AAiBA,MAAM,cAAc;CAClB;CACA;CACA;CACA;CACA;CACA;AACF;AACA,MAAM,kCAAkB,IAAI,IAAY;CACtC,GAAG;CACH;CACA;CACA;AACF,CAAC;AACD,MAAM,cAAc;CAAC;CAAM;CAAO;CAAM;CAAO;CAAM;AAAK;AAE1D,MAAM,YAAY,UAChB,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;;AAGrE,MAAa,gBACX,UAEA,SAAS,KAAK,KAAK,OAAO,KAAK,KAAK,CAAC,CAAC,MAAM,QAAQ,gBAAgB,IAAI,GAAG,CAAC;;AAG9E,MAAa,mBAAmB,UAC9B,gBAAgB,IAAI,MAAM,KAAK,CAAC;AAElC,MAAM,YAAY,MAAe,SAC/B,OAAO,SAAS,YAAY,SAAS,KACjC,aAAa,MAAM,WAAW,IAAI,CAAC,IACnC;AAEN,MAAM,cAAc,SAAiB;CACnC,IAAI;EACF,OAAO,aAAa,KAAK,WAAW,GAAG,IAAI,OAAO,IAAI,MAAM;CAC9D,QAAQ;EACN,OAAO,CAAC;CACV;AACF;AAEA,MAAM,cACJ,YACA,QACG;CACH,IAAI,YAAY,YAAY,OAAO,SAAS,IAAI,OAAO,WAAW,SAAS;CAC3E,IAAI,gBAAgB,YAClB,OAAO,SAAS,IAAI,OAAO,WAAW,aAAa;CACrD,IAAI,WAAW,YAAY,OAAO,SAAS,IAAI,MAAM,WAAW,QAAQ;CACxE,IAAI,eAAe,YACjB,OAAO,SAAS,IAAI,MAAM,WAAW,YAAY;CACnD,IAAI,YAAY,YAAY,OAAO,IAAI;CACvC,IAAI,YAAY,YAAY,OAAO,SAAS,IAAI,OAAO,WAAW,SAAS;AAE7E;AAEA,MAAM,uBAAuB,UAC3B,UAAU,KAAA,KAAa,UAAU,OAC7B,KACA,OAAO,UAAU,WACf,KAAK,UAAU,KAAK,IACpB,OAAO,KAAK;;;;;AAMpB,SAAgB,eACd,UACA,KACQ;CACR,MAAM,QAAQ,QAAgB;EAC5B,IAAI,QAAQ,UAAU,OAAO,oBAAoB,IAAI,KAAK;EAC1D,IAAI,QAAQ,SAAS,OAAO,oBAAoB,IAAI,IAAI;EACxD,IAAI,IAAI,WAAW,QAAQ,GACzB,OAAO,oBAAoB,SAAS,IAAI,MAAM,IAAI,MAAM,CAAC,CAAC,CAAC;EAE7D,OAAO,oBAAoB,SAAS,IAAI,OAAO,GAAG,CAAC;CACrD;CACA,IAAI,MAAM;CACV,IAAI,OAAO;CACX,KAAK,MAAM,EAAE,OAAO,KAAK,SAAS,aAAa,QAAQ,GAAG;EACxD,OAAO,SAAS,MAAM,MAAM,KAAK,IAAI,KAAK,GAAG;EAC7C,OAAO,MAAM;CACf;CACA,OAAO,MAAM,SAAS,MAAM,IAAI;AAClC;AAEA,UAAU,aAAa,UAAkB;CACvC,IAAI,OAAO;CACX,SAAS;EACP,MAAM,QAAQ,SAAS,QAAQ,MAAM,IAAI;EACzC,IAAI,UAAU,IAAI;EAClB,MAAM,MAAM,SAAS,QAAQ,KAAK,QAAQ,CAAC;EAC3C,IAAI,QAAQ,IAAI;EAChB,MAAM;GAAE;GAAO;GAAK,KAAK,SAAS,MAAM,QAAQ,GAAG,GAAG,CAAC,CAAC,KAAK;EAAE;EAC/D,OAAO,MAAM;CACf;AACF;;AAGA,MAAa,sBAAsB,aACjC,CAAC,GAAG,aAAa,QAAQ,CAAC,CAAC,CACxB,KAAK,EAAE,UAAU,GAAG,CAAC,CACrB,QAAQ,QAAQ,CAAC,IAAI,WAAW,GAAG,CAAC;;AAGzC,SAAgB,aAAa,OAAgB,KAAiC;CAC5E,IAAI,MAAM,QAAQ,KAAK,GAAG,OAAO,MAAM,KAAK,SAAS,aAAa,MAAM,GAAG,CAAC;CAC5E,IAAI,CAAC,SAAS,KAAK,GAAG,OAAO;CAC7B,IAAI,WAAW,OACb,OAAO,kBAAkB,MAAM,UAAuB,GAAG,IACrD,aAAa,MAAM,UAAU,GAAG,IAChC,aAAa,MAAM,UAAU,GAAG;CAEtC,IAAI,WAAW,OACb,OAAO,OAAO,MAAM,aAAa,WAC7B,gBAAgB,MAAM,UAAU,GAAG,IACnC;CAEN,IAAI,eAAe,OACjB,OAAO,OAAO,MAAM,iBAAiB,WACjC,eAAe,MAAM,cAAc,GAAG,IACtC;CAEN,IAAI,YAAY,MAAM,QAAQ,OAAO,KAAK,GAAG,OAAO,WAAW,OAAO,GAAG;CACzE,MAAM,SAAkC,CAAC;CACzC,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,KAAK,GAC7C,OAAO,OAAO,aAAa,OAAO,GAAG;CAEvC,OAAO;AACT;AAEA,MAAM,WACJ,MACA,UACA,UACG;CACH,QAAQ,UAAR;EACE,KAAK,MACH,OAAO,UAAU,MAAM,KAAK;EAC9B,KAAK,OACH,OAAO,CAAC,UAAU,MAAM,KAAK;EAC/B;GACE,IACE,EAAE,OAAO,SAAS,YAAY,OAAO,UAAU,aAC/C,EAAE,OAAO,SAAS,YAAY,OAAO,UAAU,WAE/C,OAAO;GAET,IAAI,aAAa,MAAM,OAAO,OAAO;GACrC,IAAI,aAAa,OAAO,OAAO,QAAQ;GACvC,IAAI,aAAa,MAAM,OAAO,OAAO;GACrC,OAAO,QAAQ;CAEnB;AACF;;AAGA,SAAgB,gBAAgB,WAA8B;CAC5D,IAAI,MAAM,QAAQ,SAAS,GAAG,OAAO,UAAU,QAAQ,eAAe;CACtE,IAAI,CAAC,SAAS,SAAS,GAAG,OAAO,CAAC;CAClC,IAAI,MAAM,QAAQ,UAAU,OAAO,GACjC,OAAO,gBAAgB,UAAU,OAAO;CAC1C,IAAI,OAAO,UAAU,cAAc,YAAY,UAAU,WAAW,MAClE,OAAO,CAAC;CACV,MAAM,cAAc,YAAY,QAAQ,aAAa,YAAY,SAAS;CAC1E,OAAO,YAAY,WAAW,KAC5B,YAAY,MAAM,aAAa,aAAa,KAAK,IAC/C,CAAC,UAAU,SAAS,IACpB,CAAC;AACP;;;;;AAMA,SAAgB,kBACd,WACA,KACS;CACT,OAAO,uBAAuB,WAAW,GAAG,KAAK;AACnD;AAEA,SAAS,uBACP,WACA,KACqB;CACrB,IAAI,cAAc,KAAA,GAAW,OAAO;CACpC,IAAI,OAAO,cAAc,WAAW,OAAO;CAC3C,IAAI,MAAM,QAAQ,SAAS,GAAG;EAC5B,IAAI,SAA8B;EAClC,KAAK,MAAM,QAAQ,WAAW;GAC5B,MAAM,QAAQ,uBAAuB,MAAmB,GAAG;GAC3D,IAAI,UAAU,OAAO,OAAO;GAC5B,IAAI,UAAU,KAAA,GAAW,SAAS,KAAA;EACpC;EACA,OAAO;CACT;CACA,IAAI,CAAC,SAAS,SAAS,GAAG,OAAO,QAAQ,SAAS;CAClD,IAAI,MAAM,QAAQ,UAAU,OAAO,GACjC,OAAO,uBAAuB,UAAU,SAAwB,GAAG;CAErE,IAAI,MAAM,QAAQ,UAAU,MAAM,GAAG;EACnC,IAAI,SAA8B;EAClC,KAAK,MAAM,QAAQ,UAAU,QAAuB;GAClD,MAAM,QAAQ,uBAAuB,MAAM,GAAG;GAC9C,IAAI,UAAU,MAAM,OAAO;GAC3B,IAAI,UAAU,KAAA,GAAW,SAAS,KAAA;EACpC;EACA,OAAO;CACT;CACA,MAAM,YAAY,YAAY,MAAM,QAAQ,OAAO,SAAS;CAC5D,IAAI,CAAC,aAAa,SAAS,WAAW;EACpC,MAAM,QAAQ,uBAAuB,UAAU,QAAqB,GAAG;EACvE,OAAO,UAAU,KAAA,IAAY,KAAA,IAAY,CAAC;CAC5C;CACA,IAAI,CAAC,WAAW;EACd,IAAI,CAAC,aAAa,SAAS,GAAG,OAAO,KAAA;EACrC,IAAI,aAAsB;EAC1B,OAAO,SAAS,UAAU,KAAK,WAAW,YAAY;GACpD,MAAM,UAAU,uBACd,WAAW,UACX,GACF;GACA,IAAI,YAAY,KAAA,GAAW,OAAO,KAAA;GAClC,aAAa,WAAW,UAAU,UAAU;EAC9C;EACA,OAAO,QAAQ,aAAa,YAAY,GAAG,CAAC;CAC9C;CAEA,MAAM,QAAQ,WAAW,WAAW,GAAG;CACvC,IAAI,SAAS;CACb,IAAI,WAAW;CACf,KAAK,MAAM,YAAY,aAAa;EAClC,IAAI,EAAE,YAAY,YAAY;EAC9B,WAAW;EACX,WAAW,QAAQ,OAAO,UAAU,aAAa,UAAU,WAAW,GAAG,CAAC;CAC5E;CACA,IAAI,CAAC,UAAU,SAAS,QAAQ,KAAK;CACrC,OAAO,UAAU,WAAW,OAAO,CAAC,SAAS;AAC/C;AAQA,MAAM,iBAAiB,SACrB,SAAS,MAAM,KAAK,WAAW,GAAG,IAAI,OAAO,IAAI;;;;;AAMnD,SAAgB,aACd,OACA,KACe;CACf,MAAM,WAAoC,CAAC;CAC3C,MAAM,WAAmC,CAAC;CAC1C,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,SAAS,CAAC,CAAC,GAAG;EACtD,IAAI,SAAS,KAAK,KAAK,OAAO,MAAM,kBAAkB,UACpD,SAAS,OAAO,cAAc,MAAM,aAAa;OAC5C,IACL,SAAS,KAAK,KACd,OAAO,MAAM,iBAAiB,YAC9B,IAAI,aAAa,KAAA,GACjB;GACA,MAAM,QAAQ,MAAM;GACpB,SAAS,OAAO,QACZ,GAAG,IAAI,WAAW,cAAc,KAAK,MACrC,IAAI;EACV;EACA,SAAS,OAAO,aAAa,OAAO,GAAG;CACzC;CACA,OAAO;EAAE,OAAO;EAAU;CAAS;AACrC;;AAGA,MAAa,eAAe,MAAc,UACxC,GAAG,SAAS,KAAK,KAAK,cAAc,IAAI,IAAI,YAAY,CAAC,KAAK,CAAC"}

package/dist/spec/patch.d.ts

@@ -0,0 +1,20 @@
+import { type WriteOptions } from "./pointer.js";
+import type { PatchOperation } from "./types.js";
+/** Narrows an unknown value to a patch operation, or explains why it is not one. */
+export declare function checkPatchOperation(value: unknown): {
+    ok: true;
+    op: PatchOperation;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Applies one RFC 6902 operation and returns the new document; the input is
+ * not mutated and unchanged branches are shared. Throws when the operation
+ * cannot apply. With `createMissing`, `add` and `replace` create missing
+ * parent objects, which streaming relies on for paths like `/state/a/b`.
+ */
+export declare function applyPatchOperation<T>(doc: T, operation: PatchOperation, options?: WriteOptions): T;
+/** Applies operations in order; throws on the first one that fails. */
+export declare function applyPatch<T>(doc: T, operations: readonly PatchOperation[], options?: WriteOptions): T;
+//# sourceMappingURL=patch.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"patch.d.ts","mappings":"AACA,OAAO,EAIL,KAAK,YAAY,EAClB,MAAM,cAAW;AAClB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAS;AAI7C;AACA,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,GACb;IAAE,EAAE,EAAE,IAAI;IAAE,EAAE,EAAE,cAAc;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK;IAAE,KAAK,EAAE,MAAM;CAAE;AAgClE;;;;;;AAMA,wBAAgB,mBAAmB,CAAC,CAAC,EACnC,GAAG,EAAE,CAAC,EACN,SAAS,EAAE,cAAc,EACzB,OAAO,GAAE,YAAiB,GACzB,CAAC;AA6CJ;AACA,wBAAgB,UAAU,CAAC,CAAC,EAC1B,GAAG,EAAE,CAAC,EACN,UAAU,EAAE,SAAS,cAAc,EAAE,EACrC,OAAO,GAAE,YAAiB,GACzB,CAAC","names":[],"ignoreList":[],"sources":["../../src/spec/patch.ts"],"sourcesContent":[null]}

package/dist/spec/patch.js

@@ -0,0 +1,77 @@
+import { deepEqual } from "../json-schema.js";
+import { getAtPointer, parsePointer, writeAtPointer } from "./pointer.js";
+// src/spec/patch.ts
+const OPS = /* @__PURE__ */ new Set([
+	"add",
+	"replace",
+	"remove",
+	"move",
+	"copy",
+	"test"
+]);
+/** Narrows an unknown value to a patch operation, or explains why it is not one. */
+function checkPatchOperation(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return {
+		ok: false,
+		error: "a patch operation must be a JSON object"
+	};
+	const op = value;
+	if (typeof op["op"] !== "string" || !OPS.has(op["op"])) return {
+		ok: false,
+		error: `"op" must be one of ${[...OPS].join(", ")}`
+	};
+	if (typeof op["path"] !== "string") return {
+		ok: false,
+		error: "\"path\" must be a string"
+	};
+	if ((op["op"] === "move" || op["op"] === "copy") && typeof op["from"] !== "string") return {
+		ok: false,
+		error: `"${op["op"]}" needs a string "from"`
+	};
+	if ((op["op"] === "add" || op["op"] === "replace" || op["op"] === "test") && !("value" in op)) return {
+		ok: false,
+		error: `"${op["op"]}" needs a "value"`
+	};
+	return {
+		ok: true,
+		op
+	};
+}
+const clone = (value) => value === void 0 ? value : JSON.parse(JSON.stringify(value));
+/**
+* Applies one RFC 6902 operation and returns the new document; the input is
+* not mutated and unchanged branches are shared. Throws when the operation
+* cannot apply. With `createMissing`, `add` and `replace` create missing
+* parent objects, which streaming relies on for paths like `/state/a/b`.
+*/
+function applyPatchOperation(doc, operation, options = {}) {
+	const path = parsePointer(operation.path);
+	switch (operation.op) {
+		case "add": return writeAtPointer(doc, path, "add", operation.value, options);
+		case "replace": return writeAtPointer(doc, path, "replace", operation.value, options);
+		case "remove": return writeAtPointer(doc, path, "remove");
+		case "move": {
+			const from = parsePointer(operation.from);
+			if (from.length < path.length && from.every((token, index) => path[index] === token)) throw new Error("Cannot move a value into one of its own children");
+			const value = getAtPointer(doc, from);
+			if (value === void 0) throw new Error(`Nothing to move at "${operation.from}"`);
+			const removed = writeAtPointer(doc, from, "remove");
+			return writeAtPointer(removed, path, "add", value, options);
+		}
+		case "copy": {
+			const value = getAtPointer(doc, operation.from);
+			if (value === void 0) throw new Error(`Nothing to copy at "${operation.from}"`);
+			return writeAtPointer(doc, path, "add", clone(value), options);
+		}
+		case "test":
+			if (!deepEqual(getAtPointer(doc, path), operation.value)) throw new Error(`Test failed at "${operation.path}"`);
+			return doc;
+	}
+}
+/** Applies operations in order; throws on the first one that fails. */
+function applyPatch(doc, operations, options = {}) {
+	return operations.reduce((current, operation) => applyPatchOperation(current, operation, options), doc);
+}
+export { applyPatch, applyPatchOperation, checkPatchOperation };
+
+//# sourceMappingURL=patch.js.map

package/dist/spec/patch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"patch.js","names":[],"sources":["../../src/spec/patch.ts"],"sourcesContent":["import { deepEqual } from \"../json-schema\";\nimport {\n  getAtPointer,\n  parsePointer,\n  writeAtPointer,\n  type WriteOptions,\n} from \"./pointer\";\nimport type { PatchOperation } from \"./types\";\n\nconst OPS = new Set([\"add\", \"replace\", \"remove\", \"move\", \"copy\", \"test\"]);\n\n/** Narrows an unknown value to a patch operation, or explains why it is not one. */\nexport function checkPatchOperation(\n  value: unknown,\n): { ok: true; op: PatchOperation } | { ok: false; error: string } {\n  if (typeof value !== \"object\" || value === null || Array.isArray(value)) {\n    return { ok: false, error: \"a patch operation must be a JSON object\" };\n  }\n  const op = value as Record<string, unknown>;\n  if (typeof op[\"op\"] !== \"string\" || !OPS.has(op[\"op\"])) {\n    return {\n      ok: false,\n      error: `\"op\" must be one of ${[...OPS].join(\", \")}`,\n    };\n  }\n  if (typeof op[\"path\"] !== \"string\") {\n    return { ok: false, error: '\"path\" must be a string' };\n  }\n  if (\n    (op[\"op\"] === \"move\" || op[\"op\"] === \"copy\") &&\n    typeof op[\"from\"] !== \"string\"\n  ) {\n    return { ok: false, error: `\"${op[\"op\"]}\" needs a string \"from\"` };\n  }\n  if (\n    (op[\"op\"] === \"add\" || op[\"op\"] === \"replace\" || op[\"op\"] === \"test\") &&\n    !(\"value\" in op)\n  ) {\n    return { ok: false, error: `\"${op[\"op\"]}\" needs a \"value\"` };\n  }\n  return { ok: true, op: op as PatchOperation };\n}\n\nconst clone = <T>(value: T): T =>\n  value === undefined ? value : (JSON.parse(JSON.stringify(value)) as T);\n\n/**\n * Applies one RFC 6902 operation and returns the new document; the input is\n * not mutated and unchanged branches are shared. Throws when the operation\n * cannot apply. With `createMissing`, `add` and `replace` create missing\n * parent objects, which streaming relies on for paths like `/state/a/b`.\n */\nexport function applyPatchOperation<T>(\n  doc: T,\n  operation: PatchOperation,\n  options: WriteOptions = {},\n): T {\n  const path = parsePointer(operation.path);\n  switch (operation.op) {\n    case \"add\":\n      return writeAtPointer(doc, path, \"add\", operation.value, options) as T;\n    case \"replace\":\n      return writeAtPointer(\n        doc,\n        path,\n        \"replace\",\n        operation.value,\n        options,\n      ) as T;\n    case \"remove\":\n      return writeAtPointer(doc, path, \"remove\") as T;\n    case \"move\": {\n      const from = parsePointer(operation.from);\n      if (\n        from.length < path.length &&\n        from.every((token, index) => path[index] === token)\n      ) {\n        throw new Error(\"Cannot move a value into one of its own children\");\n      }\n      const value = getAtPointer(doc, from);\n      if (value === undefined) {\n        throw new Error(`Nothing to move at \"${operation.from}\"`);\n      }\n      const removed = writeAtPointer(doc, from, \"remove\");\n      return writeAtPointer(removed, path, \"add\", value, options) as T;\n    }\n    case \"copy\": {\n      const value = getAtPointer(doc, operation.from);\n      if (value === undefined) {\n        throw new Error(`Nothing to copy at \"${operation.from}\"`);\n      }\n      return writeAtPointer(doc, path, \"add\", clone(value), options) as T;\n    }\n    case \"test\":\n      if (!deepEqual(getAtPointer(doc, path), operation.value)) {\n        throw new Error(`Test failed at \"${operation.path}\"`);\n      }\n      return doc;\n  }\n}\n\n/** Applies operations in order; throws on the first one that fails. */\nexport function applyPatch<T>(\n  doc: T,\n  operations: readonly PatchOperation[],\n  options: WriteOptions = {},\n): T {\n  return operations.reduce(\n    (current, operation) => applyPatchOperation(current, operation, options),\n    doc,\n  );\n}\n"],"mappings":";;;AASA,MAAM,sBAAM,IAAI,IAAI;CAAC;CAAO;CAAW;CAAU;CAAQ;CAAQ;AAAM,CAAC;;AAGxE,SAAgB,oBACd,OACiE;CACjE,IAAI,OAAO,UAAU,YAAY,UAAU,QAAQ,MAAM,QAAQ,KAAK,GACpE,OAAO;EAAE,IAAI;EAAO,OAAO;CAA0C;CAEvE,MAAM,KAAK;CACX,IAAI,OAAO,GAAG,UAAU,YAAY,CAAC,IAAI,IAAI,GAAG,KAAK,GACnD,OAAO;EACL,IAAI;EACJ,OAAO,uBAAuB,CAAC,GAAG,GAAG,CAAC,CAAC,KAAK,IAAI;CAClD;CAEF,IAAI,OAAO,GAAG,YAAY,UACxB,OAAO;EAAE,IAAI;EAAO,OAAO;CAA0B;CAEvD,KACG,GAAG,UAAU,UAAU,GAAG,UAAU,WACrC,OAAO,GAAG,YAAY,UAEtB,OAAO;EAAE,IAAI;EAAO,OAAO,IAAI,GAAG,MAAM;CAAyB;CAEnE,KACG,GAAG,UAAU,SAAS,GAAG,UAAU,aAAa,GAAG,UAAU,WAC9D,EAAE,WAAW,KAEb,OAAO;EAAE,IAAI;EAAO,OAAO,IAAI,GAAG,MAAM;CAAmB;CAE7D,OAAO;EAAE,IAAI;EAAU;CAAqB;AAC9C;AAEA,MAAM,SAAY,UAChB,UAAU,KAAA,IAAY,QAAS,KAAK,MAAM,KAAK,UAAU,KAAK,CAAC;;;;;;;AAQjE,SAAgB,oBACd,KACA,WACA,UAAwB,CAAC,GACtB;CACH,MAAM,OAAO,aAAa,UAAU,IAAI;CACxC,QAAQ,UAAU,IAAlB;EACE,KAAK,OACH,OAAO,eAAe,KAAK,MAAM,OAAO,UAAU,OAAO,OAAO;EAClE,KAAK,WACH,OAAO,eACL,KACA,MACA,WACA,UAAU,OACV,OACF;EACF,KAAK,UACH,OAAO,eAAe,KAAK,MAAM,QAAQ;EAC3C,KAAK,QAAQ;GACX,MAAM,OAAO,aAAa,UAAU,IAAI;GACxC,IACE,KAAK,SAAS,KAAK,UACnB,KAAK,OAAO,OAAO,UAAU,KAAK,WAAW,KAAK,GAElD,MAAM,IAAI,MAAM,kDAAkD;GAEpE,MAAM,QAAQ,aAAa,KAAK,IAAI;GACpC,IAAI,UAAU,KAAA,GACZ,MAAM,IAAI,MAAM,uBAAuB,UAAU,KAAK,EAAE;GAE1D,MAAM,UAAU,eAAe,KAAK,MAAM,QAAQ;GAClD,OAAO,eAAe,SAAS,MAAM,OAAO,OAAO,OAAO;EAC5D;EACA,KAAK,QAAQ;GACX,MAAM,QAAQ,aAAa,KAAK,UAAU,IAAI;GAC9C,IAAI,UAAU,KAAA,GACZ,MAAM,IAAI,MAAM,uBAAuB,UAAU,KAAK,EAAE;GAE1D,OAAO,eAAe,KAAK,MAAM,OAAO,MAAM,KAAK,GAAG,OAAO;EAC/D;EACA,KAAK;GACH,IAAI,CAAC,UAAU,aAAa,KAAK,IAAI,GAAG,UAAU,KAAK,GACrD,MAAM,IAAI,MAAM,mBAAmB,UAAU,KAAK,EAAE;GAEtD,OAAO;CACX;AACF;;AAGA,SAAgB,WACd,KACA,YACA,UAAwB,CAAC,GACtB;CACH,OAAO,WAAW,QACf,SAAS,cAAc,oBAAoB,SAAS,WAAW,OAAO,GACvE,GACF;AACF"}

package/dist/spec/pending.d.ts

@@ -0,0 +1,15 @@
+export declare const PENDING_STYLE: {
+    readonly display: "inline-flex";
+    readonly gap: "4px";
+    readonly padding: "6px 2px";
+};
+export declare const PENDING_DOT_STYLE: {
+    readonly width: "5px";
+    readonly height: "5px";
+    readonly borderRadius: "50%";
+    readonly background: "currentColor";
+    readonly opacity: 0.2;
+};
+/** Pulses the pending indicator's dots in turn, and leaves them still under reduced motion; returns the cleanup. */
+export declare function animatePendingDots(host: Element): () => void;
+//# sourceMappingURL=pending.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pending.d.ts","mappings":"AAEA,eAAO,MAAM,aAAa;;;;CAIhB;AAEV,eAAO,MAAM,iBAAiB;;;;;;CAMpB;AAEV;AACA,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,IAAI","names":[],"ignoreList":[],"sources":["../../src/spec/pending.ts"],"sourcesContent":[null]}

package/dist/spec/pending.js

@@ -0,0 +1,33 @@
+// src/spec/pending.ts
+const DOT_FRAMES = [
+	{ opacity: .2 },
+	{ opacity: .8 },
+	{ opacity: .2 }
+];
+const PENDING_STYLE = {
+	display: "inline-flex",
+	gap: "4px",
+	padding: "6px 2px"
+};
+const PENDING_DOT_STYLE = {
+	width: "5px",
+	height: "5px",
+	borderRadius: "50%",
+	background: "currentColor",
+	opacity: .2
+};
+/** Pulses the pending indicator's dots in turn, and leaves them still under reduced motion; returns the cleanup. */
+function animatePendingDots(host) {
+	if (globalThis.matchMedia?.("(prefers-reduced-motion: reduce)")?.matches) return () => {};
+	const animations = Array.from(host.children).flatMap((dot, index) => typeof dot.animate === "function" ? [dot.animate(DOT_FRAMES, {
+		duration: 1200,
+		delay: index * 150,
+		iterations: Infinity
+	})] : []);
+	return () => {
+		for (const animation of animations) animation.cancel();
+	};
+}
+export { PENDING_DOT_STYLE, PENDING_STYLE, animatePendingDots };
+
+//# sourceMappingURL=pending.js.map

package/dist/spec/pending.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pending.js","names":[],"sources":["../../src/spec/pending.ts"],"sourcesContent":["const DOT_FRAMES = [{ opacity: 0.2 }, { opacity: 0.8 }, { opacity: 0.2 }];\n\nexport const PENDING_STYLE = {\n  display: \"inline-flex\",\n  gap: \"4px\",\n  padding: \"6px 2px\",\n} as const;\n\nexport const PENDING_DOT_STYLE = {\n  width: \"5px\",\n  height: \"5px\",\n  borderRadius: \"50%\",\n  background: \"currentColor\",\n  opacity: 0.2,\n} as const;\n\n/** Pulses the pending indicator's dots in turn, and leaves them still under reduced motion; returns the cleanup. */\nexport function animatePendingDots(host: Element): () => void {\n  if (globalThis.matchMedia?.(\"(prefers-reduced-motion: reduce)\")?.matches) {\n    return () => {};\n  }\n  const animations = Array.from(host.children).flatMap((dot, index) =>\n    typeof dot.animate === \"function\"\n      ? [\n          dot.animate(DOT_FRAMES, {\n            duration: 1200,\n            delay: index * 150,\n            iterations: Infinity,\n          }),\n        ]\n      : [],\n  );\n  return () => {\n    for (const animation of animations) animation.cancel();\n  };\n}\n"],"mappings":";AAAA,MAAM,aAAa;CAAC,EAAE,SAAS,GAAI;CAAG,EAAE,SAAS,GAAI;CAAG,EAAE,SAAS,GAAI;AAAC;AAExE,MAAa,gBAAgB;CAC3B,SAAS;CACT,KAAK;CACL,SAAS;AACX;AAEA,MAAa,oBAAoB;CAC/B,OAAO;CACP,QAAQ;CACR,cAAc;CACd,YAAY;CACZ,SAAS;AACX;;AAGA,SAAgB,mBAAmB,MAA2B;CAC5D,IAAI,WAAW,aAAa,kCAAkC,CAAC,EAAE,SAC/D,aAAa,CAAC;CAEhB,MAAM,aAAa,MAAM,KAAK,KAAK,QAAQ,CAAC,CAAC,SAAS,KAAK,UACzD,OAAO,IAAI,YAAY,aACnB,CACE,IAAI,QAAQ,YAAY;EACtB,UAAU;EACV,OAAO,QAAQ;EACf,YAAY;CACd,CAAC,CACH,IACA,CAAC,CACP;CACA,aAAa;EACX,KAAK,MAAM,aAAa,YAAY,UAAU,OAAO;CACvD;AACF"}

package/dist/spec/pointer.d.ts

@@ -0,0 +1,17 @@
+/** Splits a JSON Pointer (RFC 6901) into unescaped tokens. `""` is the whole document. */
+export declare function parsePointer(pointer: string): string[];
+export declare const escapePointerToken: (token: string | number) => string;
+export declare const joinPointer: (tokens: readonly (string | number)[]) => string;
+/** Reads the value at a pointer, or `undefined` when any step is missing. */
+export declare function getAtPointer(doc: unknown, pointer: string | string[]): unknown;
+export type WriteMode = "add" | "replace" | "remove";
+export type WriteOptions = {
+    /** Create missing intermediate objects instead of failing. */
+    createMissing?: boolean;
+};
+/**
+ * Returns a copy of `doc` with the value at `tokens` added, replaced, or
+ * removed. Containers along the path are copied; everything else is shared.
+ */
+export declare function writeAtPointer(doc: unknown, tokens: readonly string[], mode: WriteMode, value?: unknown, options?: WriteOptions, arrayParents?: readonly string[]): unknown;
+//# sourceMappingURL=pointer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pointer.d.ts","mappings":"AAAA;AACA,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE;AAWvD,eAAO,MAAM,kBAAkB,GAAI,OAAO,MAAM,GAAG,MAAM,KAAG,MACJ;AAExD,eAAO,MAAM,WAAW,GAAI,QAAQ,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,KAAG,MACF;AAOjE;AACA,wBAAgB,YAAY,CAC1B,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,GACzB,OAAO;AAmBV,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,SAAS,GAAG,QAAQ;AAEpD,MAAM,MAAM,YAAY,GAAG;IACzB;IACA,aAAa,CAAC,EAAE,OAAO;CACxB;AAID;;;;AAIA,wBAAgB,cAAc,CAC5B,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,IAAI,EAAE,SAAS,EACf,KAAK,CAAC,EAAE,OAAO,EACf,OAAO,GAAE,YAAiB,EAC1B,YAAY,GAAE,SAAS,MAAM,EAAO,GACnC,OAAO","names":[],"ignoreList":[],"sources":["../../src/spec/pointer.ts"],"sourcesContent":[null]}