@json-render/core 0.4.3 → 0.5.0

package/dist/index.mjs

@@ -19,26 +19,36 @@ var DynamicBooleanSchema = z.union([
   z.boolean(),
   z.object({ path: z.string() })
 ]);
-function resolveDynamicValue(value, dataModel) {
+function resolveDynamicValue(value, stateModel) {
   if (value === null || value === void 0) {
     return void 0;
   }
   if (typeof value === "object" && "path" in value) {
-    return getByPath(dataModel, value.path);
+    return getByPath(stateModel, value.path);
   }
   return value;
 }
+function unescapeJsonPointer(token) {
+  return token.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+function parseJsonPointer(path) {
+  const raw = path.startsWith("/") ? path.slice(1).split("/") : path.split("/");
+  return raw.map(unescapeJsonPointer);
+}
 function getByPath(obj, path) {
   if (!path || path === "/") {
     return obj;
   }
-  const segments = path.startsWith("/") ? path.slice(1).split("/") : path.split("/");
+  const segments = parseJsonPointer(path);
   let current = obj;
   for (const segment of segments) {
     if (current === null || current === void 0) {
       return void 0;
     }
-    if (typeof current === "object") {
+    if (Array.isArray(current)) {
+      const index = parseInt(segment, 10);
+      current = current[index];
+    } else if (typeof current === "object") {
       current = current[segment];
     } else {
       return void 0;
@@ -50,13 +60,13 @@ function isNumericIndex(str) {
   return /^\d+$/.test(str);
 }
 function setByPath(obj, path, value) {
-  const segments = path.startsWith("/") ? path.slice(1).split("/") : path.split("/");
+  const segments = parseJsonPointer(path);
   if (segments.length === 0) return;
   let current = obj;
   for (let i = 0; i < segments.length - 1; i++) {
     const segment = segments[i];
     const nextSegment = segments[i + 1];
-    const nextIsNumeric = nextSegment !== void 0 && isNumericIndex(nextSegment);
+    const nextIsNumeric = nextSegment !== void 0 && (isNumericIndex(nextSegment) || nextSegment === "-");
     if (Array.isArray(current)) {
       const index = parseInt(segment, 10);
       if (current[index] === void 0 || typeof current[index] !== "object") {
@@ -72,12 +82,95 @@ function setByPath(obj, path, value) {
   }
   const lastSegment = segments[segments.length - 1];
   if (Array.isArray(current)) {
-    const index = parseInt(lastSegment, 10);
-    current[index] = value;
+    if (lastSegment === "-") {
+      current.push(value);
+    } else {
+      const index = parseInt(lastSegment, 10);
+      current[index] = value;
+    }
   } else {
     current[lastSegment] = value;
   }
 }
+function addByPath(obj, path, value) {
+  const segments = parseJsonPointer(path);
+  if (segments.length === 0) return;
+  let current = obj;
+  for (let i = 0; i < segments.length - 1; i++) {
+    const segment = segments[i];
+    const nextSegment = segments[i + 1];
+    const nextIsNumeric = nextSegment !== void 0 && (isNumericIndex(nextSegment) || nextSegment === "-");
+    if (Array.isArray(current)) {
+      const index = parseInt(segment, 10);
+      if (current[index] === void 0 || typeof current[index] !== "object") {
+        current[index] = nextIsNumeric ? [] : {};
+      }
+      current = current[index];
+    } else {
+      if (!(segment in current) || typeof current[segment] !== "object") {
+        current[segment] = nextIsNumeric ? [] : {};
+      }
+      current = current[segment];
+    }
+  }
+  const lastSegment = segments[segments.length - 1];
+  if (Array.isArray(current)) {
+    if (lastSegment === "-") {
+      current.push(value);
+    } else {
+      const index = parseInt(lastSegment, 10);
+      current.splice(index, 0, value);
+    }
+  } else {
+    current[lastSegment] = value;
+  }
+}
+function removeByPath(obj, path) {
+  const segments = parseJsonPointer(path);
+  if (segments.length === 0) return;
+  let current = obj;
+  for (let i = 0; i < segments.length - 1; i++) {
+    const segment = segments[i];
+    if (Array.isArray(current)) {
+      const index = parseInt(segment, 10);
+      if (current[index] === void 0 || typeof current[index] !== "object") {
+        return;
+      }
+      current = current[index];
+    } else {
+      if (!(segment in current) || typeof current[segment] !== "object") {
+        return;
+      }
+      current = current[segment];
+    }
+  }
+  const lastSegment = segments[segments.length - 1];
+  if (Array.isArray(current)) {
+    const index = parseInt(lastSegment, 10);
+    if (index >= 0 && index < current.length) {
+      current.splice(index, 1);
+    }
+  } else {
+    delete current[lastSegment];
+  }
+}
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (a === null || b === null) return false;
+  if (typeof a !== typeof b) return false;
+  if (typeof a !== "object") return false;
+  if (Array.isArray(a)) {
+    if (!Array.isArray(b)) return false;
+    if (a.length !== b.length) return false;
+    return a.every((item, i) => deepEqual(item, b[i]));
+  }
+  const aObj = a;
+  const bObj = b;
+  const aKeys = Object.keys(aObj);
+  const bKeys = Object.keys(bObj);
+  if (aKeys.length !== bKeys.length) return false;
+  return aKeys.every((key) => deepEqual(aObj[key], bObj[key]));
+}
 function findFormValue(fieldName, params, data) {
   if (params?.[fieldName] !== void 0) {
     const val = params[fieldName];
@@ -126,10 +219,38 @@ function parseSpecStreamLine(line) {
   }
 }
 function applySpecStreamPatch(obj, patch) {
-  if (patch.op === "set" || patch.op === "add" || patch.op === "replace") {
-    setByPath(obj, patch.path, patch.value);
-  } else if (patch.op === "remove") {
-    setByPath(obj, patch.path, void 0);
+  switch (patch.op) {
+    case "add":
+      addByPath(obj, patch.path, patch.value);
+      break;
+    case "replace":
+      setByPath(obj, patch.path, patch.value);
+      break;
+    case "remove":
+      removeByPath(obj, patch.path);
+      break;
+    case "move": {
+      if (!patch.from) break;
+      const moveValue = getByPath(obj, patch.from);
+      removeByPath(obj, patch.from);
+      addByPath(obj, patch.path, moveValue);
+      break;
+    }
+    case "copy": {
+      if (!patch.from) break;
+      const copyValue = getByPath(obj, patch.from);
+      addByPath(obj, patch.path, copyValue);
+      break;
+    }
+    case "test": {
+      const actual = getByPath(obj, patch.path);
+      if (!deepEqual(actual, patch.value)) {
+        throw new Error(
+          `Test operation failed: value at "${patch.path}" does not match`
+        );
+      }
+      break;
+    }
   }
   return obj;
 }
@@ -231,7 +352,7 @@ var VisibilityConditionSchema = z2.union([
   LogicExpressionSchema
 ]);
 function evaluateLogicExpression(expr, ctx) {
-  const { dataModel } = ctx;
+  const { stateModel } = ctx;
   if ("and" in expr) {
     return expr.and.every((subExpr) => evaluateLogicExpression(subExpr, ctx));
   }
@@ -242,30 +363,30 @@ function evaluateLogicExpression(expr, ctx) {
     return !evaluateLogicExpression(expr.not, ctx);
   }
   if ("path" in expr) {
-    const value = resolveDynamicValue({ path: expr.path }, dataModel);
+    const value = resolveDynamicValue({ path: expr.path }, stateModel);
     return Boolean(value);
   }
   if ("eq" in expr) {
     const [left, right] = expr.eq;
-    const leftValue = resolveDynamicValue(left, dataModel);
-    const rightValue = resolveDynamicValue(right, dataModel);
+    const leftValue = resolveDynamicValue(left, stateModel);
+    const rightValue = resolveDynamicValue(right, stateModel);
     return leftValue === rightValue;
   }
   if ("neq" in expr) {
     const [left, right] = expr.neq;
-    const leftValue = resolveDynamicValue(left, dataModel);
-    const rightValue = resolveDynamicValue(right, dataModel);
+    const leftValue = resolveDynamicValue(left, stateModel);
+    const rightValue = resolveDynamicValue(right, stateModel);
     return leftValue !== rightValue;
   }
   if ("gt" in expr) {
     const [left, right] = expr.gt;
     const leftValue = resolveDynamicValue(
       left,
-      dataModel
+      stateModel
     );
     const rightValue = resolveDynamicValue(
       right,
-      dataModel
+      stateModel
     );
     if (typeof leftValue === "number" && typeof rightValue === "number") {
       return leftValue > rightValue;
@@ -276,11 +397,11 @@ function evaluateLogicExpression(expr, ctx) {
     const [left, right] = expr.gte;
     const leftValue = resolveDynamicValue(
       left,
-      dataModel
+      stateModel
     );
     const rightValue = resolveDynamicValue(
       right,
-      dataModel
+      stateModel
     );
     if (typeof leftValue === "number" && typeof rightValue === "number") {
       return leftValue >= rightValue;
@@ -291,11 +412,11 @@ function evaluateLogicExpression(expr, ctx) {
     const [left, right] = expr.lt;
     const leftValue = resolveDynamicValue(
       left,
-      dataModel
+      stateModel
     );
     const rightValue = resolveDynamicValue(
       right,
-      dataModel
+      stateModel
     );
     if (typeof leftValue === "number" && typeof rightValue === "number") {
       return leftValue < rightValue;
@@ -306,11 +427,11 @@ function evaluateLogicExpression(expr, ctx) {
     const [left, right] = expr.lte;
     const leftValue = resolveDynamicValue(
       left,
-      dataModel
+      stateModel
     );
     const rightValue = resolveDynamicValue(
       right,
-      dataModel
+      stateModel
     );
     if (typeof leftValue === "number" && typeof rightValue === "number") {
       return leftValue <= rightValue;
@@ -327,7 +448,7 @@ function evaluateVisibility(condition, ctx) {
     return condition;
   }
   if ("path" in condition && !("and" in condition) && !("or" in condition)) {
-    const value = resolveDynamicValue({ path: condition.path }, ctx.dataModel);
+    const value = resolveDynamicValue({ path: condition.path }, ctx.stateModel);
     return Boolean(value);
   }
   if ("auth" in condition) {
@@ -381,6 +502,44 @@ var visibility = {
   lte: (left, right) => ({ lte: [left, right] })
 };
 
+// src/props.ts
+function isPathExpression(value) {
+  return typeof value === "object" && value !== null && "$path" in value && typeof value.$path === "string";
+}
+function isCondExpression(value) {
+  return typeof value === "object" && value !== null && "$cond" in value && "$then" in value && "$else" in value;
+}
+function resolvePropValue(value, ctx) {
+  if (value === null || value === void 0) {
+    return value;
+  }
+  if (isPathExpression(value)) {
+    return getByPath(ctx.stateModel, value.$path);
+  }
+  if (isCondExpression(value)) {
+    const result = evaluateVisibility(value.$cond, ctx);
+    return resolvePropValue(result ? value.$then : value.$else, ctx);
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => resolvePropValue(item, ctx));
+  }
+  if (typeof value === "object") {
+    const resolved = {};
+    for (const [key, val] of Object.entries(value)) {
+      resolved[key] = resolvePropValue(val, ctx);
+    }
+    return resolved;
+  }
+  return value;
+}
+function resolveElementProps(props, ctx) {
+  const resolved = {};
+  for (const [key, value] of Object.entries(props)) {
+    resolved[key] = resolvePropValue(value, ctx);
+  }
+  return resolved;
+}
+
 // src/actions.ts
 import { z as z3 } from "zod";
 var ActionConfirmSchema = z3.object({
@@ -399,44 +558,45 @@ var ActionOnErrorSchema = z3.union([
   z3.object({ set: z3.record(z3.string(), z3.unknown()) }),
   z3.object({ action: z3.string() })
 ]);
-var ActionSchema = z3.object({
-  name: z3.string(),
+var ActionBindingSchema = z3.object({
+  action: z3.string(),
   params: z3.record(z3.string(), DynamicValueSchema).optional(),
   confirm: ActionConfirmSchema.optional(),
   onSuccess: ActionOnSuccessSchema.optional(),
   onError: ActionOnErrorSchema.optional()
 });
-function resolveAction(action2, dataModel) {
+var ActionSchema = ActionBindingSchema;
+function resolveAction(binding, stateModel) {
   const resolvedParams = {};
-  if (action2.params) {
-    for (const [key, value] of Object.entries(action2.params)) {
-      resolvedParams[key] = resolveDynamicValue(value, dataModel);
+  if (binding.params) {
+    for (const [key, value] of Object.entries(binding.params)) {
+      resolvedParams[key] = resolveDynamicValue(value, stateModel);
     }
   }
-  let confirm = action2.confirm;
+  let confirm = binding.confirm;
   if (confirm) {
     confirm = {
       ...confirm,
-      message: interpolateString(confirm.message, dataModel),
-      title: interpolateString(confirm.title, dataModel)
+      message: interpolateString(confirm.message, stateModel),
+      title: interpolateString(confirm.title, stateModel)
     };
   }
   return {
-    name: action2.name,
+    action: binding.action,
     params: resolvedParams,
     confirm,
-    onSuccess: action2.onSuccess,
-    onError: action2.onError
+    onSuccess: binding.onSuccess,
+    onError: binding.onError
   };
 }
-function interpolateString(template, dataModel) {
+function interpolateString(template, stateModel) {
   return template.replace(/\$\{([^}]+)\}/g, (_, path) => {
-    const value = resolveDynamicValue({ path }, dataModel);
+    const value = resolveDynamicValue({ path }, stateModel);
     return String(value ?? "");
   });
 }
 async function executeAction(ctx) {
-  const { action: action2, handler, setData, navigate, executeAction: executeAction2 } = ctx;
+  const { action: action2, handler, setState, navigate, executeAction: executeAction2 } = ctx;
   try {
     await handler(action2.params);
     if (action2.onSuccess) {
@@ -444,7 +604,7 @@ async function executeAction(ctx) {
         navigate(action2.onSuccess.navigate);
       } else if ("set" in action2.onSuccess) {
         for (const [path, value] of Object.entries(action2.onSuccess.set)) {
-          setData(path, value);
+          setState(path, value);
         }
       } else if ("action" in action2.onSuccess && executeAction2) {
         await executeAction2(action2.onSuccess.action);
@@ -455,7 +615,7 @@ async function executeAction(ctx) {
       if ("set" in action2.onError) {
         for (const [path, value] of Object.entries(action2.onError.set)) {
           const resolvedValue = typeof value === "string" && value === "$error.message" ? error.message : value;
-          setData(path, resolvedValue);
+          setState(path, resolvedValue);
         }
       } else if ("action" in action2.onError && executeAction2) {
         await executeAction2(action2.onError.action);
@@ -465,25 +625,26 @@ async function executeAction(ctx) {
     }
   }
 }
-var action = {
-  /** Create a simple action */
-  simple: (name, params) => ({
-    name,
+var actionBinding = {
+  /** Create a simple action binding */
+  simple: (actionName, params) => ({
+    action: actionName,
     params
   }),
-  /** Create an action with confirmation */
-  withConfirm: (name, confirm, params) => ({
-    name,
+  /** Create an action binding with confirmation */
+  withConfirm: (actionName, confirm, params) => ({
+    action: actionName,
     params,
     confirm
   }),
-  /** Create an action with success handler */
-  withSuccess: (name, onSuccess, params) => ({
-    name,
+  /** Create an action binding with success handler */
+  withSuccess: (actionName, onSuccess, params) => ({
+    action: actionName,
     params,
     onSuccess
   })
 };
+var action = actionBinding;
 
 // src/validation.ts
 import { z as z4 } from "zod";
@@ -592,11 +753,11 @@ var builtInValidationFunctions = {
   }
 };
 function runValidationCheck(check2, ctx) {
-  const { value, dataModel, customFunctions } = ctx;
+  const { value, stateModel, customFunctions } = ctx;
   const resolvedArgs = {};
   if (check2.args) {
     for (const [key, argValue] of Object.entries(check2.args)) {
-      resolvedArgs[key] = resolveDynamicValue(argValue, dataModel);
+      resolvedArgs[key] = resolveDynamicValue(argValue, stateModel);
     }
   }
   const fn = builtInValidationFunctions[check2.fn] ?? customFunctions?.[check2.fn];
@@ -621,7 +782,7 @@ function runValidation(config, ctx) {
   const errors = [];
   if (config.enabled) {
     const enabled = evaluateLogicExpression(config.enabled, {
-      dataModel: ctx.dataModel,
+      stateModel: ctx.stateModel,
       authState: ctx.authState
     });
     if (!enabled) {
@@ -688,6 +849,155 @@ var check = {
   })
 };
 
+// src/spec-validator.ts
+function validateSpec(spec, options = {}) {
+  const { checkOrphans = false } = options;
+  const issues = [];
+  if (!spec.root) {
+    issues.push({
+      severity: "error",
+      message: "Spec has no root element defined.",
+      code: "missing_root"
+    });
+    return { valid: false, issues };
+  }
+  if (!spec.elements[spec.root]) {
+    issues.push({
+      severity: "error",
+      message: `Root element "${spec.root}" not found in elements map.`,
+      code: "root_not_found"
+    });
+  }
+  if (Object.keys(spec.elements).length === 0) {
+    issues.push({
+      severity: "error",
+      message: "Spec has no elements.",
+      code: "empty_spec"
+    });
+    return { valid: false, issues };
+  }
+  for (const [key, element] of Object.entries(spec.elements)) {
+    if (element.children) {
+      for (const childKey of element.children) {
+        if (!spec.elements[childKey]) {
+          issues.push({
+            severity: "error",
+            message: `Element "${key}" references child "${childKey}" which does not exist in the elements map.`,
+            elementKey: key,
+            code: "missing_child"
+          });
+        }
+      }
+    }
+    const props = element.props;
+    if (props && "visible" in props && props.visible !== void 0) {
+      issues.push({
+        severity: "error",
+        message: `Element "${key}" has "visible" inside "props". It should be a top-level field on the element (sibling of type/props/children).`,
+        elementKey: key,
+        code: "visible_in_props"
+      });
+    }
+    if (props && "on" in props && props.on !== void 0) {
+      issues.push({
+        severity: "error",
+        message: `Element "${key}" has "on" inside "props". It should be a top-level field on the element (sibling of type/props/children).`,
+        elementKey: key,
+        code: "on_in_props"
+      });
+    }
+    if (props && "repeat" in props && props.repeat !== void 0) {
+      issues.push({
+        severity: "error",
+        message: `Element "${key}" has "repeat" inside "props". It should be a top-level field on the element (sibling of type/props/children).`,
+        elementKey: key,
+        code: "repeat_in_props"
+      });
+    }
+  }
+  if (checkOrphans) {
+    const reachable = /* @__PURE__ */ new Set();
+    const walk = (key) => {
+      if (reachable.has(key)) return;
+      reachable.add(key);
+      const el = spec.elements[key];
+      if (el?.children) {
+        for (const childKey of el.children) {
+          if (spec.elements[childKey]) {
+            walk(childKey);
+          }
+        }
+      }
+    };
+    if (spec.elements[spec.root]) {
+      walk(spec.root);
+    }
+    for (const key of Object.keys(spec.elements)) {
+      if (!reachable.has(key)) {
+        issues.push({
+          severity: "warning",
+          message: `Element "${key}" is not reachable from root "${spec.root}".`,
+          elementKey: key,
+          code: "orphaned_element"
+        });
+      }
+    }
+  }
+  const hasErrors = issues.some((i) => i.severity === "error");
+  return { valid: !hasErrors, issues };
+}
+function autoFixSpec(spec) {
+  const fixes = [];
+  const fixedElements = {};
+  for (const [key, element] of Object.entries(spec.elements)) {
+    const props = element.props;
+    let fixed = element;
+    if (props && "visible" in props && props.visible !== void 0) {
+      const { visible, ...restProps } = fixed.props;
+      fixed = {
+        ...fixed,
+        props: restProps,
+        visible
+      };
+      fixes.push(`Moved "visible" from props to element level on "${key}".`);
+    }
+    let currentProps = fixed.props;
+    if (currentProps && "on" in currentProps && currentProps.on !== void 0) {
+      const { on, ...restProps } = currentProps;
+      fixed = {
+        ...fixed,
+        props: restProps,
+        on
+      };
+      fixes.push(`Moved "on" from props to element level on "${key}".`);
+    }
+    currentProps = fixed.props;
+    if (currentProps && "repeat" in currentProps && currentProps.repeat !== void 0) {
+      const { repeat, ...restProps } = currentProps;
+      fixed = {
+        ...fixed,
+        props: restProps,
+        repeat
+      };
+      fixes.push(`Moved "repeat" from props to element level on "${key}".`);
+    }
+    fixedElements[key] = fixed;
+  }
+  return {
+    spec: { root: spec.root, elements: fixedElements },
+    fixes
+  };
+}
+function formatSpecIssues(issues) {
+  const errors = issues.filter((i) => i.severity === "error");
+  if (errors.length === 0) return "";
+  const lines = ["The generated UI spec has the following errors:"];
+  for (const issue of errors) {
+    lines.push(`- ${issue.message}`);
+  }
+  return lines.join("\n");
+}
+
 // src/schema.ts
 import { z as z5 } from "zod";
 function createBuilder() {
@@ -712,6 +1022,7 @@ function defineSchema(builder, options) {
   return {
     definition,
     promptTemplate: options?.promptTemplate,
+    defaultRules: options?.defaultRules,
     createCatalog(catalog) {
       return createCatalogFromSchema(this, catalog);
     }
@@ -867,15 +1178,95 @@ function generatePrompt(catalog, options) {
     "Output JSONL (one JSON object per line) with patches to build a UI tree."
   );
   lines.push(
-    "Each line is a JSON patch operation. Start with the root, then add each element."
+    "Each line is a JSON patch operation. Start with /root, then stream /elements and /state patches interleaved so the UI fills in progressively as it streams."
   );
   lines.push("");
   lines.push("Example output (each line is a separate JSON object):");
   lines.push("");
-  lines.push(`{"op":"set","path":"/root","value":"card-1"}
-{"op":"set","path":"/elements/card-1","value":{"key":"card-1","type":"Card","props":{"title":"Dashboard"},"children":["metric-1","chart-1"],"parentKey":""}}
-{"op":"set","path":"/elements/metric-1","value":{"key":"metric-1","type":"Metric","props":{"label":"Revenue","valuePath":"analytics.revenue","format":"currency"},"children":[],"parentKey":"card-1"}}
-{"op":"set","path":"/elements/chart-1","value":{"key":"chart-1","type":"Chart","props":{"type":"bar","dataPath":"analytics.salesByRegion"},"children":[],"parentKey":"card-1"}}`);
+  lines.push(`{"op":"add","path":"/root","value":"blog"}
+{"op":"add","path":"/elements/blog","value":{"type":"Stack","props":{"direction":"vertical","gap":"md"},"children":["heading","posts-grid"]}}
+{"op":"add","path":"/elements/heading","value":{"type":"Heading","props":{"text":"Blog","level":"h1"},"children":[]}}
+{"op":"add","path":"/elements/posts-grid","value":{"type":"Grid","props":{"columns":2,"gap":"md"},"repeat":{"path":"/posts","key":"id"},"children":["post-card"]}}
+{"op":"add","path":"/elements/post-card","value":{"type":"Card","props":{"title":{"$path":"$item/title"}},"children":["post-meta"]}}
+{"op":"add","path":"/elements/post-meta","value":{"type":"Text","props":{"text":{"$path":"$item/author"},"variant":"muted"},"children":[]}}
+{"op":"add","path":"/state/posts","value":[]}
+{"op":"add","path":"/state/posts/0","value":{"id":"1","title":"Getting Started","author":"Jane","date":"Jan 15"}}
+{"op":"add","path":"/state/posts/1","value":{"id":"2","title":"Advanced Tips","author":"Bob","date":"Feb 3"}}
+
+Note: state patches appear right after the elements that use them, so the UI fills in as it streams.`);
+  lines.push("");
+  lines.push("INITIAL STATE:");
+  lines.push(
+    "Specs include a /state field to seed the state model. Components with statePath read from and write to this state, and $path expressions read from it."
+  );
+  lines.push(
+    "CRITICAL: You MUST include state patches whenever your UI displays data via $path expressions, uses repeat to iterate over arrays, or uses statePath bindings. Without state, $path references resolve to nothing and repeat lists render zero items."
+  );
+  lines.push(
+    "Output state patches right after the elements that reference them, so the UI fills in progressively as it streams."
+  );
+  lines.push(
+    "Stream state progressively - output one patch per array item instead of one giant blob:"
+  );
+  lines.push(
+    '  For arrays: {"op":"add","path":"/state/posts/0","value":{"id":"1","title":"First Post",...}} then /state/posts/1, /state/posts/2, etc.'
+  );
+  lines.push(
+    '  For scalars: {"op":"add","path":"/state/newTodoText","value":""}'
+  );
+  lines.push(
+    '  Initialize the array first if needed: {"op":"add","path":"/state/posts","value":[]}'
+  );
+  lines.push(
+    'When content comes from the state model, use { "$path": "/some/path" } dynamic props to display it instead of hardcoding the same value in both state and props. The state model is the single source of truth.'
+  );
+  lines.push(
+    "Include realistic sample data in state. For blogs: 3-4 posts with titles, excerpts, authors, dates. For product lists: 3-5 items with names, prices, descriptions. Never leave arrays empty."
+  );
+  lines.push("");
+  lines.push("DYNAMIC LISTS (repeat field):");
+  lines.push(
+    'Any element can have a top-level "repeat" field to render its children once per item in a state array: { "repeat": { "path": "/arrayPath", "key": "id" } }.'
+  );
+  lines.push(
+    'The element itself renders once (as the container), and its children are expanded once per array item. "path" is the state array path. "key" is an optional field name on each item for stable React keys.'
+  );
+  lines.push(
+    'Example: { "type": "Column", "props": { "gap": 8 }, "repeat": { "path": "/todos", "key": "id" }, "children": ["todo-item"] }'
+  );
+  lines.push(
+    'Inside children of a repeated element, use "$item/field" for per-item paths: statePath:"$item/completed", { "$path": "$item/title" }. Use "$index" for the current array index.'
+  );
+  lines.push(
+    "ALWAYS use the repeat field for lists backed by state arrays. NEVER hardcode individual elements for each array item."
+  );
+  lines.push(
+    'IMPORTANT: "repeat" is a top-level field on the element (sibling of type/props/children), NOT inside props.'
+  );
+  lines.push("");
+  lines.push("ARRAY STATE ACTIONS:");
+  lines.push(
+    'Use action "pushState" to append items to arrays. Params: { path: "/arrayPath", value: { ...item }, clearPath: "/inputPath" }.'
+  );
+  lines.push(
+    'Values inside pushState can contain { "path": "/statePath" } references to read current state (e.g. the text from an input field).'
+  );
+  lines.push(
+    'Use "$id" inside a pushState value to auto-generate a unique ID.'
+  );
+  lines.push(
+    'Example: on: { "press": { "action": "pushState", "params": { "path": "/todos", "value": { "id": "$id", "title": { "path": "/newTodoText" }, "completed": false }, "clearPath": "/newTodoText" } } }'
+  );
+  lines.push(
+    `Use action "removeState" to remove items from arrays by index. Params: { path: "/arrayPath", index: N }. Inside a repeated element's children, use "$index" for the current item index.`
+  );
+  lines.push(
+    "For lists where users can add/remove items (todos, carts, etc.), use pushState and removeState instead of hardcoding with setState."
+  );
+  lines.push("");
+  lines.push(
+    'IMPORTANT: State paths use RFC 6901 JSON Pointer syntax (e.g. "/todos/0/title"). Do NOT use JavaScript-style dot notation (e.g. "/todos.length" is WRONG). To generate unique IDs for new items, use "$id" instead of trying to read array length.'
+  );
   lines.push("");
   const components = catalog.data.components;
   if (components) {
@@ -885,8 +1276,9 @@ function generatePrompt(catalog, options) {
       const propsStr = def.props ? formatZodType(def.props) : "{}";
       const hasChildren = def.slots && def.slots.length > 0;
       const childrenStr = hasChildren ? " [accepts children]" : "";
+      const eventsStr = def.events && def.events.length > 0 ? ` [events: ${def.events.join(", ")}]` : "";
       const descStr = def.description ? ` - ${def.description}` : "";
-      lines.push(`- ${name}: ${propsStr}${descStr}${childrenStr}`);
+      lines.push(`- ${name}: ${propsStr}${descStr}${childrenStr}${eventsStr}`);
     }
     lines.push("");
   }
@@ -899,17 +1291,90 @@ function generatePrompt(catalog, options) {
     }
     lines.push("");
   }
+  lines.push("EVENTS (the `on` field):");
+  lines.push(
+    "Elements can have an optional `on` field to bind events to actions. The `on` field is a top-level field on the element (sibling of type/props/children), NOT inside props."
+  );
+  lines.push(
+    'Each key in `on` is an event name (from the component\'s supported events), and the value is an action binding: `{ "action": "<actionName>", "params": { ... } }`.'
+  );
+  lines.push("");
+  lines.push("Example:");
+  lines.push(
+    '  {"type":"Button","props":{"label":"Save"},"on":{"press":{"action":"setState","params":{"path":"/saved","value":true}}},"children":[]}'
+  );
+  lines.push("");
+  lines.push(
+    'Action params can use dynamic path references to read from state: { "path": "/statePath" }.'
+  );
+  lines.push(
+    "IMPORTANT: Do NOT put action/actionParams inside props. Always use the `on` field for event bindings."
+  );
+  lines.push("");
+  lines.push("VISIBILITY CONDITIONS:");
+  lines.push(
+    "Elements can have an optional `visible` field to conditionally show/hide based on data state. IMPORTANT: `visible` is a top-level field on the element object (sibling of type/props/children), NOT inside props."
+  );
+  lines.push(
+    'Correct: {"type":"Column","props":{"gap":8},"visible":{"eq":[{"path":"/tab"},"home"]},"children":[...]}'
+  );
+  lines.push(
+    '- `{ "eq": [{ "path": "/statePath" }, "value"] }` - visible when state at path equals value'
+  );
+  lines.push(
+    '- `{ "neq": [{ "path": "/statePath" }, "value"] }` - visible when state at path does not equal value'
+  );
+  lines.push('- `{ "path": "/statePath" }` - visible when path is truthy');
+  lines.push(
+    '- `{ "and": [...] }`, `{ "or": [...] }`, `{ "not": {...} }` - combine conditions'
+  );
+  lines.push("- `true` / `false` - always visible/hidden");
+  lines.push("");
+  lines.push(
+    "Use the Pressable component with on.press bound to setState to update state and drive visibility."
+  );
+  lines.push(
+    'Example: A Pressable with on: { "press": { "action": "setState", "params": { "path": "/activeTab", "value": "home" } } } sets state, then a container with visible: { "eq": [{ "path": "/activeTab" }, "home"] } shows only when that tab is active.'
+  );
+  lines.push("");
+  lines.push("DYNAMIC PROPS:");
+  lines.push(
+    "Any prop value can be a dynamic expression that resolves based on state. Two forms are supported:"
+  );
+  lines.push("");
+  lines.push(
+    '1. State binding: `{ "$path": "/statePath" }` - resolves to the value at that state path.'
+  );
+  lines.push(
+    '   Example: `"color": { "$path": "/theme/primary" }` reads the color from state.'
+  );
+  lines.push("");
+  lines.push(
+    '2. Conditional: `{ "$cond": <condition>, "$then": <value>, "$else": <value> }` - evaluates the condition (same syntax as visibility conditions) and picks the matching value.'
+  );
+  lines.push(
+    '   Example: `"color": { "$cond": { "eq": [{ "path": "/activeTab" }, "home"] }, "$then": "#007AFF", "$else": "#8E8E93" }`'
+  );
+  lines.push(
+    '   Example: `"name": { "$cond": { "eq": [{ "path": "/activeTab" }, "home"] }, "$then": "home", "$else": "home-outline" }`'
+  );
+  lines.push("");
+  lines.push(
+    "Use dynamic props instead of duplicating elements with opposing visible conditions when only prop values differ."
+  );
+  lines.push("");
   lines.push("RULES:");
   const baseRules = [
     "Output ONLY JSONL patches - one JSON object per line, no markdown, no code fences",
-    'First line sets root: {"op":"set","path":"/root","value":"<root-key>"}',
-    'Then add each element: {"op":"set","path":"/elements/<key>","value":{...}}',
+    'First set root: {"op":"add","path":"/root","value":"<root-key>"}',
+    'Then add each element: {"op":"add","path":"/elements/<key>","value":{...}}',
+    "Output /state patches right after the elements that use them, one per array item for progressive loading. REQUIRED whenever using $path, repeat, or statePath.",
     "ONLY use components listed above",
-    "Each element value needs: key, type, props, children (array of child keys), parentKey",
-    "Use unique keys (e.g., 'header', 'metric-1', 'chart-revenue')",
-    "Root element's parentKey is empty string, children reference their parent's key"
+    "Each element value needs: type, props, children (array of child keys)",
+    "Use unique keys for the element map entries (e.g., 'header', 'metric-1', 'chart-revenue')"
   ];
-  const allRules = [...baseRules, ...customRules];
+  const schemaRules = catalog.schema.defaultRules ?? [];
+  const allRules = [...baseRules, ...schemaRules, ...customRules];
   allRules.forEach((rule, i) => {
     lines.push(`${i + 1}. ${rule}`);
   });
@@ -1047,6 +1512,56 @@ function defineCatalog(schema, catalog) {
   return schema.createCatalog(catalog);
 }
 
+// src/prompt.ts
+function isNonEmptySpec(spec) {
+  if (!spec || typeof spec !== "object") return false;
+  const s = spec;
+  return typeof s.root === "string" && typeof s.elements === "object" && s.elements !== null && Object.keys(s.elements).length > 0;
+}
+var PATCH_INSTRUCTIONS = `IMPORTANT: The current UI is already loaded. Output ONLY the patches needed to make the requested change:
+- To add a new element: {"op":"add","path":"/elements/new-key","value":{...}}
+- To modify an existing element: {"op":"replace","path":"/elements/existing-key","value":{...}}
+- To remove an element: {"op":"remove","path":"/elements/old-key"}
+- To update the root: {"op":"replace","path":"/root","value":"new-root-key"}
+- To add children: update the parent element with new children array
+
+DO NOT output patches for elements that don't need to change. Only output what's necessary for the requested modification.`;
+function buildUserPrompt(options) {
+  const { prompt, currentSpec, state, maxPromptLength } = options;
+  let userText = String(prompt || "");
+  if (maxPromptLength !== void 0 && maxPromptLength > 0) {
+    userText = userText.slice(0, maxPromptLength);
+  }
+  if (isNonEmptySpec(currentSpec)) {
+    const parts2 = [];
+    parts2.push(
+      `CURRENT UI STATE (already loaded, DO NOT recreate existing elements):`
+    );
+    parts2.push(JSON.stringify(currentSpec, null, 2));
+    parts2.push("");
+    parts2.push(`USER REQUEST: ${userText}`);
+    if (state && Object.keys(state).length > 0) {
+      parts2.push("");
+      parts2.push(`AVAILABLE STATE:
+${JSON.stringify(state, null, 2)}`);
+    }
+    parts2.push("");
+    parts2.push(PATCH_INSTRUCTIONS);
+    return parts2.join("\n");
+  }
+  const parts = [userText];
+  if (state && Object.keys(state).length > 0) {
+    parts.push(`
+AVAILABLE STATE:
+${JSON.stringify(state, null, 2)}`);
+  }
+  parts.push(
+    `
+Remember: Output /root first, then interleave /elements and /state patches so the UI fills in progressively as it streams. Output each state patch right after the elements that use it, one per array item.`
+  );
+  return parts.join("\n");
+}
+
 // src/catalog.ts
 import { z as z6 } from "zod";
 function createCatalog(config) {
@@ -1063,22 +1578,18 @@ function createCatalog(config) {
   const componentSchemas = componentNames.map((componentName) => {
     const def = components[componentName];
     return z6.object({
-      key: z6.string(),
       type: z6.literal(componentName),
       props: def.props,
       children: z6.array(z6.string()).optional(),
-      parentKey: z6.string().nullable().optional(),
       visible: VisibilityConditionSchema.optional()
     });
   });
   let elementSchema;
   if (componentSchemas.length === 0) {
     elementSchema = z6.object({
-      key: z6.string(),
       type: z6.string(),
       props: z6.record(z6.string(), z6.unknown()),
       children: z6.array(z6.string()).optional(),
-      parentKey: z6.string().nullable().optional(),
       visible: VisibilityConditionSchema.optional()
     });
   } else if (componentSchemas.length === 1) {
@@ -1160,7 +1671,7 @@ function generateCatalogPrompt(catalog) {
   lines.push("");
   lines.push("Components can have a `visible` property:");
   lines.push("- `true` / `false` - Always visible/hidden");
-  lines.push('- `{ "path": "/data/path" }` - Visible when path is truthy');
+  lines.push('- `{ "path": "/state/path" }` - Visible when path is truthy');
   lines.push('- `{ "auth": "signedIn" }` - Visible when user is signed in');
   lines.push('- `{ "and": [...] }` - All conditions must be true');
   lines.push('- `{ "or": [...] }` - Any condition must be true');
@@ -1299,21 +1810,21 @@ function generateSystemPrompt(catalog, options = {}) {
     }
     lines.push("");
   }
-  lines.push("OUTPUT FORMAT (JSONL):");
-  lines.push('{"op":"set","path":"/root","value":"element-key"}');
+  lines.push("OUTPUT FORMAT (JSONL, RFC 6902 JSON Patch):");
+  lines.push('{"op":"add","path":"/root","value":"element-key"}');
   lines.push(
-    '{"op":"add","path":"/elements/key","value":{"key":"...","type":"...","props":{...},"children":[...]}}'
+    '{"op":"add","path":"/elements/key","value":{"type":"...","props":{...},"children":[...]}}'
   );
   lines.push('{"op":"remove","path":"/elements/key"}');
   lines.push("");
   lines.push("RULES:");
   const baseRules = [
-    "First line sets /root to root element key",
-    "Add elements with /elements/{key}",
+    'First line sets /root to root element key: {"op":"add","path":"/root","value":"<key>"}',
+    'Add elements with /elements/{key}: {"op":"add","path":"/elements/<key>","value":{...}}',
     "Remove elements with op:remove - also update the parent's children array to exclude the removed key",
     "Children array contains string keys, not objects",
     "Parent first, then children",
-    "Each element needs: key, type, props",
+    "Each element needs: type, props",
     "ONLY use props listed above - never invent new props"
   ];
   const allRules = [...baseRules, ...customRules];
@@ -1330,6 +1841,7 @@ function generateSystemPrompt(catalog, options = {}) {
   return lines.join("\n");
 }
 export {
+  ActionBindingSchema,
   ActionConfirmSchema,
   ActionOnErrorSchema,
   ActionOnSuccessSchema,
@@ -1343,7 +1855,11 @@ export {
   ValidationConfigSchema,
   VisibilityConditionSchema,
   action,
+  actionBinding,
+  addByPath,
   applySpecStreamPatch,
+  autoFixSpec,
+  buildUserPrompt,
   builtInValidationFunctions,
   check,
   compileSpecStream,
@@ -1355,16 +1871,21 @@ export {
   evaluateVisibility,
   executeAction,
   findFormValue,
+  formatSpecIssues,
   generateCatalogPrompt,
   generateSystemPrompt,
   getByPath,
   interpolateString,
   parseSpecStreamLine,
+  removeByPath,
   resolveAction,
   resolveDynamicValue,
+  resolveElementProps,
+  resolvePropValue,
   runValidation,
   runValidationCheck,
   setByPath,
+  validateSpec,
   visibility
 };
 //# sourceMappingURL=index.mjs.map